home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Icon < prev    next >
Encoding:
Text File  |  1996-05-21  |  23.2 KB  |  602 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Icon.h
  12.     Author:  Copyright © 1992, 1993, 1994 Jason Williams, Simon Truss
  13.     Version: 1.15 (10 Nov 1995)
  14.     Purpose: High-level icon handling routines
  15.     History: 1.14 (?? Dec 1994)    - JW
  16.              1.15 (10 Nov 1995) - ST - Added Desk_Icon_InsertText.
  17. */
  18.  
  19.  
  20. #ifndef __Desk_Icon_h
  21. #define __Desk_Icon_h
  22.  
  23. #ifdef __cplusplus
  24.     extern "C" {
  25. #endif
  26.  
  27.  
  28. #ifndef __Desk_Wimp_h
  29. #include "Desk.Wimp.h"
  30. #endif
  31.  
  32. #ifndef __Desk_DragASpr_h
  33. #include "Desk.DragASpr.h"
  34. #endif
  35.  
  36.  
  37. extern Desk_icon_handle Desk_Icon_BarIcon(const char *spritename, Desk_window_handle pos);
  38.   /* 
  39.    * sprite-only icon, with the "normal" default flags. If you want an
  40.    * icon that is not this default, then create it yourself (it isn't hard!)
  41.    *
  42.    * If you wish to attach handlers/menus to the baricon, then remember
  43.    * it's handle, and pass this to Desk_Event_Claim...
  44.    * (Or wait for release 2 of DeskLib, which should have an Desk_Event_BarIcon)
  45.    *
  46.    * Pass in "spritename" -  the name of a sprite in the Wimp Sprite pool
  47.    * and "pos", which should be Desk_iconbar_LEFT or Desk_iconbar_RIGHT
  48.    * The correct size of the icon will be determined and used
  49.    * Returns: The icon handle of the created icon
  50.    */
  51.  
  52.  
  53. extern Desk_icon_handle Desk_Icon_BarIconUser( const char *spritename, Desk_window_handle pos, 
  54.                                      unsigned int *area);
  55.   /*
  56.    * Plonk a sprite from a USER sprite area on the icon bar
  57.    * Returns icon handle.
  58.    */
  59.                                     
  60.  
  61.  
  62. extern Desk_bool Desk_Icon_GetSelect(Desk_window_handle window, Desk_icon_handle icon);
  63.   /*
  64.    *  Returns Desk_bool_TRUE if the given icon is selected
  65.    */
  66.  
  67.  
  68. extern Desk_bool Desk_Icon_GetShade(Desk_window_handle window, Desk_icon_handle icon);
  69.   /*
  70.    *  Returns Desk_bool_TRUE if the given icon is shaded
  71.    */
  72.  
  73.  
  74. extern void Desk_Icon_SetSelect(Desk_window_handle window, Desk_icon_handle icon, int flag);
  75. /* Equivalent in action to Desk_Icon_Select + Desk_Icon_Deselect: Pass in a flag to
  76.  * set the new selected status of the icon (0 = deselect, 1 = select)
  77.  */
  78.  
  79. extern void Desk_Icon_Select(Desk_window_handle window, Desk_icon_handle icon);
  80. /* If the given icon is currently deselected, it is selected */
  81.  
  82. extern void Desk_Icon_Deselect(Desk_window_handle window, Desk_icon_handle icon);
  83. /* If the given icon is currently selected, it is deselected */
  84.  
  85.  
  86. extern void Desk_Icon_SetShade(Desk_window_handle window, Desk_icon_handle icon, int flag);
  87. /* Equivalent in action to Desk_Icon_Shade + Desk_Icon_Unshade: Pass in a flag to
  88.  * set the new shaded status of the icon (0 = unshaded, 1 = shaded)
  89.  */
  90.  
  91. extern void Desk_Icon_Shade(Desk_window_handle window, Desk_icon_handle icon);
  92. /*
  93.  * if the icon is currently unshaded (active) it is shaded (made inactive)
  94.  * This includes removing the caret from the icon.
  95.  */
  96.  
  97. extern void Desk_Icon_Unshade(Desk_window_handle window, Desk_icon_handle icon);
  98. /* if the icon is currently shaded (inactive) it is unshaded (made active) */
  99.  
  100.  
  101. extern void Desk_Icon_SetForeColour(Desk_window_handle window, Desk_icon_handle icon,
  102.                                int wimpcolour);
  103. /*  Sets an icon's foreground colour to the given WIMP colour (in range 0..15).
  104.  *  NOTE that this is a simple function which does not currently support
  105.  *  outline font icons (in fact, it'll corrupt their font handle and cause
  106.  *  untold grief)
  107.  */
  108.  
  109. extern void Desk_Icon_SetBackColour(Desk_window_handle window, Desk_icon_handle icon,
  110.                                int wimpcolour);
  111. /*  Sets an icon's background colour to the given WIMP colour (in range 0..15).
  112.  *  NOTE that this is a simple function which does not currently support
  113.  *  outline font icons (in fact, it'll corrupt their font handle and cause
  114.  *  untold grief)
  115.  */
  116.  
  117.  
  118. extern void Desk_Icon_ForceWindowRedraw(Desk_window_handle window, Desk_icon_handle icon);
  119. /*  Force Redraws the area of WINDOW surrounding the icon, *including*
  120.  *  the 3-d border (validation string "b<bordertype>")
  121.  */
  122.  
  123. #define Desk_Icon_ForceRedraw(wind, icon) Desk_Wimp_SetIconState(wind, icon, 0, 0);
  124.         /* Forces the WIMP to redraw (just) the icon */
  125.  
  126.  
  127.  
  128. extern void Desk_Icon_SetCaret(Desk_window_handle window, Desk_icon_handle icon);
  129. /*
  130.  * This routine sets the caret within the requested icon. It places the
  131.  * caret at the (righthand) end of the text in the icon. If the icon is not
  132.  * a text icon, then the function returns quietly
  133.  */
  134.  
  135. extern void Desk_Icon_LoseCaret(Desk_window_handle window, Desk_icon_handle icon);
  136. /* Desk_Icon_LoseCaret
  137.  * This routine ensures that the caret is *not* contained within the
  138.  * designated icon. Only sets a new position if the icon currently contains
  139.  *  the caret.
  140.  */
  141.  
  142.  
  143.  
  144. extern void Desk_Icon_SetInteger(Desk_window_handle w, Desk_icon_handle i, int value);
  145. /*
  146.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  147.  * If the number is too long (too many digits) it will be truncated to fit.
  148.  * If unable to set the text (incorrect icon type), it returns quietly
  149.  */
  150.  
  151. extern void Desk_Icon_SetDouble(Desk_window_handle w, Desk_icon_handle i,
  152.                            double value, int decimalplaces);
  153. /*
  154.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  155.  * Only the first "decimalplaces" digits after the decimal point are
  156.  * printed. If the number is too long (too many digits) it will be truncated
  157.  * to fit. This may affect the accuracy or actual value of the number.
  158.  * If unable to set the text (incorrect icon type), it returns quietly
  159.  */
  160.  
  161. extern void Desk_Icon_SetText(Desk_window_handle w, Desk_icon_handle i, char *text);
  162. /*
  163.  * Copies the text string into the icon's indirected string buffer (and redraws)
  164.  * If unable to set the text (incorrect icon type), it returns quietly
  165.  * If text passed in is a NULL pointer, sets icon text to " "
  166.  */
  167.  
  168. extern void Desk_Icon_SetTextRJ(Desk_window_handle w, Desk_icon_handle i, char *text);
  169. /*
  170.  * Copies the text string into the icon's indirected string buffer (and redraws)
  171.  * This text is "right justified", meaning that if the text doesn't fit
  172.  * into the available buffer space, it is truncated at the *LEFT*-hand side,
  173.  * and preceded by a '...' (ellipsis) character.
  174.  * If unable to set the text (incorrect icon type), it returns quietly
  175.  * If text passed in is a NULL pointer, sets icon text to '\0'
  176.  */
  177.  
  178.  
  179. extern void Desk_Icon_printf(Desk_window_handle window, Desk_icon_handle icon,
  180.                         const char *format, ...);
  181. /* 
  182.  * Exactly the same as sprintf, but instead of passing in a string into which
  183.  * the result is written, you pass in the window+icon identifier of an
  184.  * indirected icon. (Anything other than an indirected icon will return
  185.  * quietly with NO effect)
  186.  * e.g Desk_Icon_printf(window, 5, "%d bytes copied", current);
  187.  */
  188.  
  189.  
  190.  
  191. extern double Desk_Icon_GetDouble(Desk_window_handle w, Desk_icon_handle i);
  192. /*
  193.  * Gets the given icon's text and returns it in the form of a "double"
  194.  * floating-point value. 0 will be returned from any error/invalid text
  195.  */
  196.  
  197. extern int Desk_Icon_GetInteger(Desk_window_handle w, Desk_icon_handle i);
  198. /*
  199.  * Gets the given icon's text and returns it in the form of an integer
  200.  * numeric value. 0 will be returned from any error/invalid text
  201.  */
  202.  
  203. extern void Desk_Icon_GetText(Desk_window_handle w, Desk_icon_handle i, char *text);
  204. /*
  205.  * Copies the text string from the icon (sprite name, text, or indirected)
  206.  * into the array pointed to by "text"
  207.  * Note that the array pointed to by "text" must be big enough to hold the
  208.  * resulting string, so the minimum sizes are:
  209.  *  If non-indirected (or a sprite), 12 characters
  210.  *  If indirected text, the indirected size of the icon.
  211.  */
  212.  
  213.  
  214.  
  215. extern char *Desk_Icon_GetTextPtr(Desk_window_handle, Desk_icon_handle);
  216. /*    
  217.     Inputs:   window, icon - handle pair of the icon to examine.
  218.     Returns:  Pointer to the *actual* indirected text buffer used for the
  219.               given icon.  If the icon is not indirected text, then you will
  220.               get garbage back.
  221.     Purpose:  Get a pointer to the indirected text buffer for this icon, so
  222.               you can read/change it.
  223. */
  224.  
  225.  
  226.  
  227.  
  228. #define Desk_Icon_SetFlags(window, icon, flags, set) \
  229.   Desk_Wimp_SetIconState((window), (icon), ((set) ? (flags) : 0), (flags))
  230. /*
  231. Use like:
  232.   Desk_os_error *Desk_Icon_SetFlags(Desk_window_handle window, 
  233.                           Desk_icon_handle icon, 
  234.                           int flags, 
  235.                           Desk_bool set);
  236.     
  237.   Inputs:   window, icon - window and icon handle pair of icon to change.
  238.             flags - bitfield specifying the bits to change.
  239.             set - if Desk_bool_TRUE, all the flags defined by 'flags' will be set to
  240.                   1, otherwise they will all be set to 0.
  241.   Returns:  Usual RISC OS error block.
  242.   Purpose:  Neat interface to the Desk_Wimp_SetIconState SWI.
  243.   Errors:   As for Desk_Wimp_SetIconState()
  244. */
  245.  
  246.  
  247. #define Desk_Icon_SetFgCol(w, i, col) \
  248. Desk_Wimp_SetIconState((w), (i), (col) * Desk_icon_FORECOLOUR, 0xF * Desk_icon_FORECOLOUR)
  249. /*
  250. Use like:
  251.   Desk_os_error *Desk_Icon_SetFgCol(Desk_window_handle window, Desk_icon_handle icon, int col) 
  252.     
  253.   Inputs:   window, icon - handle pair to identify the icon to change.
  254.             col - the new foreground colour to apply to the icon.
  255.   Returns:  Standard RISC OS error block.
  256.   Purpose:  Macro to allow simple call to change the foreground colour
  257.             of an icon (via the Desk_Wimp_SetIconState SWI).
  258.   SeeAlso:  Desk_Icon_SetBgCol()
  259. */
  260.  
  261.  
  262.  
  263. #define Desk_Icon_SetBgCol(w, i, col) \
  264. Desk_Wimp_SetIconState((w), (i), \
  265.                 (unsigned) (col) * (unsigned) Desk_icon_BACKCOLOUR, \
  266.                 (unsigned) 0xF * (unsigned) Desk_icon_BACKCOLOUR)
  267. /*
  268. Use like:
  269.   Desk_os_error *Desk_Icon_SetBgCol( Desk_window_handle window, Desk_icon_handle icon, int col) 
  270.     
  271.   Inputs:   window, icon - handle pair to identify the icon to change.
  272.             col - the new background colour to apply to the icon.
  273.   Returns:  Standard RISC OS error block.
  274.   Purpose:  Macro to allow simple call to change the background colour
  275.             of an icon (via the Desk_Wimp_SetIconState SWI).
  276.   SeeAlso:  Desk_Icon_SetFgCol()
  277. */
  278.                 
  279.  
  280. extern void Desk_Icon_ShadeGroup(Desk_window_handle window, 
  281.                             Desk_icon_handle icons[], 
  282.                             Desk_bool shade);
  283. /*    
  284.     Inputs:   window - the window that contains the icons to be changed.
  285.               icons - array of icon handles that specify the icons to change.
  286.                       The array should be terminated with -1.
  287.               shade - Desk_bool_TRUE to shade the icons, Desk_bool_FALSE to unshade them.
  288.     Purpose:  Shade a group of icons as defined by an -1 terminated array of
  289.               icon handles.
  290.     SeeAlso:  Desk_Icon_SelectGroup()
  291. */
  292.  
  293.  
  294.  
  295. extern void Desk_Icon_SelectGroup(Desk_window_handle window, 
  296.                              Desk_icon_handle icons[], 
  297.                              Desk_bool select);
  298. /*    
  299.     Inputs:   window - the window that contains the icons to be changed.
  300.               icons - array of icon handles that specify the icons to change.
  301.                       The array should be terminated with -1.
  302.               select - Desk_bool_TRUE to select the icons, Desk_bool_FALSE to unselect them.
  303.     Purpose:  Select or unselect a group of icons, as defined by an -1 
  304.               terminated array of icon handles.
  305.     SeeAlso:  Desk_Icon_ShadeGroup()
  306. */
  307.  
  308.  
  309.  
  310.  
  311. extern int Desk_Icon_GetFgCol(const Desk_icon_block *icon);
  312. /*
  313.     int Desk_Icon_GetFgCol(Desk_icon_block *icon);
  314.     
  315.     Inputs:   icon - pointer to the icon info block that the colour should
  316.                      be extracted.  This copes with anti-aliased icons.
  317.     Returns:  The foreground colour of the described icon.
  318.     Purpose:  Extract the foreground colour of an icon, coping with all the
  319.               special cases.
  320. */
  321.  
  322.  
  323. extern int Desk_Icon_GetBgCol(const Desk_icon_block *icon);
  324. /*
  325.     int Desk_Icon_GetBgCol(Desk_icon_block *icon);
  326.     
  327.     Inputs:   icon - pointer to the icon info block that the colour should
  328.                      be extracted.  This copes with anti-aliased icons.
  329.     Returns:  The background colour of the described icon.
  330.     Purpose:  Extract the background colour of an icon, coping with all the
  331.               special cases.
  332. */
  333.  
  334.  
  335.  
  336.  
  337. extern void Desk_Icon_SetRadios(Desk_window_handle window,
  338.                            Desk_icon_handle first, Desk_icon_handle last,
  339.                            Desk_icon_handle onradio);
  340. /*
  341.  * Pass in a group of icons (specified by lowest-numbered icon and
  342.  * highest-numbered icon), and the icon from this group that you want
  343.  * selected. All icons except the one you want selected will be deselected.
  344.  */
  345.  
  346. extern int Desk_Icon_WhichRadio(Desk_window_handle window,
  347.                            Desk_icon_handle first, Desk_icon_handle last);
  348. /*
  349.  * This function accepts parameters for the first (lowest numbered) and
  350.  * last (highest numnbered) in a group of icons (generally a group of radio
  351.  * buttons). It returns the icon number of the first icon it finds within
  352.  * this range which is selected (or "last" if none are selected).
  353.  * Use it to find which of a group of radios is selected.
  354.  */
  355.  
  356. extern int Desk_Icon_WhichRadioInEsg(Desk_window_handle wh, int esg);
  357. /*
  358.  * Basically the same as Desk_Icon_WhichRadio, but specifies the radio-group
  359.  * by matching all icons with the given ESG, rather than having to have
  360.  * a sequential block of icon numbers.
  361.  */
  362.  
  363.  
  364. extern void Desk_Icon_ClickWait(int waittime);
  365. /*
  366.  * Waits for the given number of centiseconds.
  367.  * This is a MULTITASKING wait - although your program will do nothing,
  368.  * the rest of the desktop will continue to run.
  369.  * The wait is aborted after the given time, or as soon as an event is
  370.  * received. If an attempt is made to re-enter ClickWait(), it will return
  371.  * immediately (i.e. if a click event causes ClickWait to ba called, then
  372.  * a second click while "waiting" from the first click will have no effect.
  373.  */
  374.  
  375.  
  376.  
  377. extern void Desk_Icon_StartDrag(Desk_window_handle window, Desk_icon_handle icon);
  378. /*
  379.  * Starts a drag operation based on the given icon.
  380.  * This is mainly used in "save as" windows to start drags of the file icon
  381.  * when it is clicked on, but may be useful elsewhere.
  382.  *
  383.  * This call DOES NOT use DragASprite
  384.  */
  385.  
  386.  
  387. #define Desk_Icon_StartSolidDrag Desk_DragASprite_DragIcon
  388. /*
  389.  * Starts a drag operation based on the given icon, using DragASpr if available
  390.  *   extern void Desk_Icon_StartSolidDrag(Desk_window_handle window, Desk_icon_handle icon);
  391.  */
  392.  
  393.  
  394. extern void Desk_Icon_DisposeIndData(Desk_icon_data *data, Desk_icon_flags flags);
  395. /*
  396.  * This will free any indirected data for this icon. It uses free(), so
  397.  * obviously expects that malloc() was used to get the memory in the first
  398.  * place, so make sure this is the case if you use this function.
  399.  */
  400.  
  401.  
  402.  
  403. extern void Desk_Icon_FileIcon(Desk_window_handle window, Desk_icon_handle icon, int filetype);
  404. /*
  405.     Inputs:   window   - the window containing the icon to change.
  406.               icon     - handle of the icon to change.
  407.               filetype - desired filetype sprite to display.
  408.     Purpose:  Changes an icon in a window to display the correct filetype
  409.               sprite for the given filetype number.
  410.               Requires that the specified icon is an indirected text-only
  411.               icon with enough room in the text buffer to hold the sprite
  412.               name.
  413.               This function converts it to an indirected sprite-only icon,
  414.               and fills in the sprite name and area.
  415.              
  416.               It does not check to make sure that the sprite corresponding
  417.               to this filetype exists in the Wimp sprite pool - the caller
  418.               should ensure that this is the case.
  419. */
  420.  
  421.  
  422. extern void Desk_Icon_ScreenPos(Desk_window_handle window,
  423.                            Desk_icon_handle icon,
  424.                            Desk_wimp_rect *rect);
  425. /*
  426.     Inputs:   window   - the window containing the icon to examine.
  427.               icon     - handle of the icon to examine.
  428.     Outputs:  rect     - the screen coordinates of the icon.
  429.     Purpose:  Gets the coordinate of an icon, and converts them into
  430.               screen coordinates.
  431. */
  432.  
  433.  
  434.  
  435. /* =========================================================================
  436.  * Special high-level icon functions:
  437.  *   Slider icons: See "DeskLib.Libraries.Icon.c.Slider" for details
  438.  */
  439.  
  440. extern int Desk_Icon_SetSlider(Desk_window_handle window,
  441.                           Desk_icon_handle baseicon, Desk_icon_handle slidericon,
  442.                           int sliderpos);
  443. /* Sets a slider icon-pair to the specified position (specify as a
  444.  * percentage). Values < 0 and > 1000 are clipped, and the value to which the
  445.  * slider has been set is returned.
  446.  */
  447.  
  448. extern int Desk_Icon_UpdateSlider(Desk_window_handle window,
  449.                              Desk_icon_handle baseicon, Desk_icon_handle slidericon,
  450.                              int lastpos);
  451. /* (call on null events while slider being dragged)
  452.  * Calculates a new slider percentage from the mouse pointer position.
  453.  * If this differs from lastpos, the slider is updated (by recreating the
  454.  * slidericon to the new length.
  455.  * returns the new slider position percentage value.
  456.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  457.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  458.  */
  459.  
  460.  
  461. extern int Desk_Icon_DragSlider(Desk_window_handle window,
  462.                            Desk_icon_handle baseicon, Desk_icon_handle slidericon);
  463. /* Initiates the drag operation on a slider. Call this when you get a click
  464.  * in either baseicon or slidericon.
  465.  * Returns the new percentage represented by the slider (remember this so
  466.  * you can pass it in to Desk_Icon_UpdateSlider to save unnecessary (flickery)
  467.  * update.)
  468.  * NOTE: It is up to you to turn on NULL events and remember that
  469.  * Desk_Icon_UpdateSlider must be called on each poll...
  470.  * An alternative is to make the 2 slider icons use button type ALWAYS, and
  471.  * check the mouse button state yourself to see whether a drag needs to be
  472.  * started/continued...
  473.  */
  474.  
  475. extern int Desk_Icon_ReadSlider(Desk_window_handle window,
  476.                            Desk_icon_handle baseicon, Desk_icon_handle slidericon);
  477. /* Given a slider icon-pair, returns a percentage representing the state */
  478.  
  479.  
  480.  
  481.  
  482.  
  483. typedef struct {
  484.                 Desk_window_handle window;
  485.                 Desk_icon_handle   texticon;
  486.                 Desk_icon_handle   incrementicon;
  487.                 Desk_icon_handle   decrementicon;
  488.                 Desk_bool          loop;
  489.                 unsigned int  step;
  490.                 int           min;
  491.                 int           max;
  492.                } Desk_icon_incdecblock;
  493. /*
  494.  
  495.   Purpose:  hold data for IncDec handlers
  496.   Fields:   window         - handle of window holding icons
  497.             texticon       - handle of text icon holding integer
  498.             incrementicon  - handle of increment icon
  499.             decrementicon  - handle of decrement icon
  500.             loop           - Desk_bool_TRUE=loop beyond min & max limits
  501.             step           - increment/decrement steps
  502.             min            - lower limit
  503.             max            - upper limit
  504.   SeeAlso:  Desk_InitIcon_IncDecHandler
  505. */
  506.  
  507.  
  508. extern Desk_icon_incdecblock *Desk_Icon_InitIncDecHandler(
  509.                                            const Desk_window_handle window,
  510.                                            const Desk_icon_handle   texticon,
  511.                                            const Desk_icon_handle   incrementicon,
  512.                                            const Desk_icon_handle   decrementicon,
  513.                                            const Desk_bool          loop,
  514.                                            const unsigned int  step,
  515.                                            const int           min,
  516.                                            const int           max,
  517.                                            const int           start);
  518. /*
  519.  
  520.   Purpose:  Claims handlers for clicks on Increment and Decrement Icons
  521.             which increment decrement integer number in a text icon
  522.   Inputs:   window         - handle of window
  523.             texticon       - handle of text icon holding the integer number
  524.                              which is to be incremented/decremented
  525.             incrementicon  - handle of increment icon
  526.                              click with select increments
  527.                              click with adjust decrements
  528.             decrementicon  - handle of decrement icon
  529.                              click with select decrements
  530.                              click with adjust increments
  531.             loop           - Desk_bool_TRUE=integer loops past min & max limits
  532.             step           - by how much integer is inc/decremented
  533.             min            - minimum limit
  534.             max            - maximum limit
  535.             start          - starting integer
  536.   Returns:  result of the claims to the click events on the icons
  537.   SeeAlso:  Desk_Icon_ReleaseIncDecHandler
  538. */
  539.  
  540.  
  541.  
  542.  
  543. extern Desk_bool Desk_Icon_ReleaseIncDecHandler(Desk_icon_incdecblock *incdecblock);
  544. /*
  545.   Purpose:  Release handlers for clicks on increment and decrement icons, &
  546.               frees memory occupied by the data block pointed to by the d
  547.   Inputs:   incdecblock - pointer to data block
  548.   Returns:  result of releasing handlers
  549.   SeeAlso:  Desk_Icon_InitIncDecHandler
  550. */
  551.  
  552.  
  553.  
  554. extern void Desk_Icon_AlterValidation(Desk_window_handle window, Desk_icon_handle icon,
  555.                                  const char *newvalidation);
  556. /*
  557.   Purpose:  Alter the validation string of an icon. This causes a redraw of
  558.             the icon after setting - useful for setting border types, etc
  559.   Inputs:   window        - the window
  560.             icon          - the icon
  561.             newvalidation - the new validation string
  562.   Returns:  -
  563.   Notes:    If the validation string is already set to the given value,
  564.             this function does nothing.
  565.             WARNING - it is assumed that the new validation string will
  566.             fit into the space used by the existing string - if this is
  567.             not the case, you will overwrite and corrupt memory.
  568. */
  569.  
  570.  
  571.  
  572. extern Desk_bool Desk_Icon_ButtonIsHeld(void);
  573. /*
  574.  *  Returns Desk_bool_TRUE if a mouse button is held down.
  575.  *
  576.  *  Usage : With inc/dec type icons where auto-repeat is required for an
  577.  *          icon using a 3D effect, with a button type 'Click'.
  578.  *          It prevents the annoying repeated indent-outdent effect
  579.  *          produced when using a button type 'Auto-Repeat' with a 3D
  580.  *          icon.
  581.  *  It currently returns Desk_bool_TRUE, even if the pointer is no longer over the
  582.  *  icon, provided the button is still held down.
  583.  */
  584.  
  585.  
  586. extern void Desk_Icon_InsertText(Desk_window_handle w, Desk_icon_handle i, const char *text);
  587. /*
  588.  * Copies the text string into the icon's indirected string buffer (and redraws)
  589.  * If unable to set the text (incorrect icon type),
  590.  * it returns quietly. Text is inserted at caret if icon has the input focus
  591.  * or to end of icon if it has no focus.
  592.  * Uses full Error2 error-handling for wimp veneers and malloc.
  593.  */
  594.  
  595.  
  596. #ifdef __cplusplus
  597. }
  598. #endif
  599.  
  600.  
  601. #endif
  602.