home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / !DeskLib / h / Icon < prev    next >
Encoding:
Text File  |  1993-07-14  |  10.7 KB  |  281 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 Jason Williams
  13.     Version: 1.08 (14 Jul 1993)
  14.     Purpose: High-level icon handling routines
  15. */
  16.  
  17.  
  18. #ifndef __dl_icon_h
  19. #define __dl_icon_h
  20.  
  21. #ifndef __dl_wimp_h
  22. #include "Wimp.h"
  23. #endif
  24.  
  25.  
  26.   /* Icon_BarIcon ---------------------------------------------------------
  27.    * This function places an icon on the iconbar. It makes a "normal"
  28.    * sprite-only icon, with the "normal" default flags. If you want an
  29.    * icon that is not this default, then create it yourself (it isn't hard!)
  30.    *
  31.    * If you wish to attach handlers/menus to the baricon, then remember
  32.    * it's handle, and pass this to Event_Claim...
  33.    * (Or wait for release 2 of DeskLib, which should have an Event_BarIcon)
  34.    *
  35.    * Pass in "spritename" -  the name of a sprite in the Wimp Sprite pool
  36.    * and "pos", which should be iconbar_LEFT or iconbar_RIGHT
  37.    * The correct size of the icon will be determined and used
  38.    * Returns: The icon handle of the created icon
  39.    */
  40. extern icon_handle Icon_BarIcon(char *spritename, window_handle pos);
  41.  
  42.  
  43.   /* Icon_GetSelect -------------------------------------------------------
  44.    *  Returns TRUE if the given icon is selected
  45.    */
  46. extern BOOL Icon_GetSelect(window_handle window, icon_handle icon);
  47.  
  48.  
  49.   /* Icon_GetShade --------------------------------------------------------
  50.    *  Returns TRUE if the given icon is shaded
  51.    */
  52. extern BOOL Icon_GetShade(window_handle window, icon_handle icon);
  53.  
  54.  
  55. extern void Icon_SetSelect(window_handle window, icon_handle icon, int flag);
  56. /* Equivalent in action to Icon_Select + Icon_Deselect: Pass in a flag to
  57.  * set the new selected status of the icon (0 = deselect, 1 = select)
  58.  */
  59.  
  60. extern void Icon_Select(window_handle window, icon_handle icon);
  61. /* If the given icon is currently deselected, it is selected */
  62.  
  63. extern void Icon_Deselect(window_handle window, icon_handle icon);
  64. /* If the given icon is currently selected, it is deselected */
  65.  
  66.  
  67. extern void Icon_SetShade(window_handle window, icon_handle icon, int flag);
  68. /* Equivalent in action to Icon_Shade + Icon_Unshade: Pass in a flag to
  69.  * set the new shaded status of the icon (0 = unshaded, 1 = shaded)
  70.  */
  71.  
  72. extern void Icon_Shade(window_handle window, icon_handle icon);
  73. /*
  74.  * if the icon is currently unshaded (active) it is shaded (made inactive)
  75.  * This includes removing the caret from the icon.
  76.  */
  77.  
  78. extern void Icon_Unshade(window_handle window, icon_handle icon);
  79. /* if the icon is currently shaded (inactive) it is unshaded (made active) */
  80.  
  81.  
  82.  
  83. extern void Icon_ForceWindowRedraw(window_handle window, icon_handle icon);
  84. /*  Force Redraws the area of WINDOW surrounding the icon, *including*
  85.  *  the 3-d border (validation string "b<bordertype>")
  86.  */
  87.  
  88. #define Icon_ForceRedraw(wind, icon) Wimp_SetIconState(wind, icon, 0, 0);
  89.         /* Forces the WIMP to redraw (just) the icon */
  90.  
  91.  
  92.  
  93. extern void Icon_SetCaret(window_handle window, icon_handle icon);
  94. /*
  95.  * This routine sets the caret within the requested icon. It places the
  96.  * caret at the (righthand) end of the text in the icon. If the icon is not
  97.  * a text icon, then the function returns quietly
  98.  */
  99.  
  100. extern void Icon_LoseCaret(window_handle window, icon_handle icon);
  101. /* Icon_LoseCaret
  102.  * This routine ensures that the caret is *not* contained within the
  103.  * designated icon. Only sets a new position if the icon currently contains
  104.  *  the caret.
  105.  */
  106.  
  107.  
  108.  
  109. extern void Icon_SetInteger(window_handle w, icon_handle i, int value);
  110. /*
  111.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  112.  * If the number is too long (too many digits) it will be truncated to fit.
  113.  * If unable to set the text (incorrect icon type), it returns quietly
  114.  */
  115.  
  116. extern void Icon_SetDouble(window_handle w, icon_handle i,
  117.                            double value, int decimalplaces);
  118. /*
  119.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  120.  * Only the first "decimalplaces" digits after the decimal point are
  121.  * printed. If the number is too long (too many digits) it will be truncated
  122.  * to fit. This may affect the accuracy or actual value of the number.
  123.  * If unable to set the text (incorrect icon type), it returns quietly
  124.  */
  125.  
  126. extern void Icon_SetText(window_handle w, icon_handle i, char *text);
  127. /*
  128.  * Copies the text string into the icon's indirected string buffer (and redraws)
  129.  * If unable to set the text (incorrect icon type), it returns quietly
  130.  * If text passed in is a NULL pointer, sets icon text to " "
  131.  */
  132.  
  133. extern void Icon_printf(window_handle window, icon_handle icon,
  134.                         char *format, ...);
  135. /* 
  136.  * Exactly the same as sprintf, but instead of passing in a string into which
  137.  * the result is written, you pass in the window+icon identifier of an
  138.  * indirected icon. (Anything other than an indirected icon will return
  139.  * quietly with NO effect)
  140.  * e.g Icon_printf(window, 5, "%d bytes copied", current);
  141.  */
  142.  
  143.  
  144.  
  145. extern double Icon_GetDouble(window_handle w, icon_handle i);
  146. /*
  147.  * Gets the given icon's text and returns it in the form of a "double"
  148.  * floating-point value. 0 will be returned from any error/invalid text
  149.  */
  150.  
  151. extern int Icon_GetInteger(window_handle w, icon_handle i);
  152. /*
  153.  * Gets the given icon's text and returns it in the form of an integer
  154.  * numeric value. 0 will be returned from any error/invalid text
  155.  */
  156.  
  157. extern void Icon_GetText(window_handle w, icon_handle i, char *text);
  158. /*
  159.  * Copies the text string from the icon (sprite name, text, or indirected)
  160.  * into the array pointed to by "text"
  161.  */
  162.  
  163.  
  164.  
  165. extern void Icon_SetRadios(window_handle window,
  166.                            icon_handle first, icon_handle last,
  167.                            icon_handle onradio);
  168. /*
  169.  * Pass in a group of icons (specified by lowest-numbered icon and
  170.  * highest-numbered icon), and the icon from this group that you want
  171.  * selected. All icons except the one you want selected will be deselected.
  172.  */
  173.  
  174. extern int Icon_WhichRadio(window_handle window,
  175.                            icon_handle first, icon_handle last);
  176. /*
  177.  * This function accepts parameters for the first (lowest numbered) and
  178.  * last (highest numnbered) in a group of icons (generally a group of radio
  179.  * buttons). It returns the icon number of the first icon it finds within
  180.  * this range which is selected (or "last" if none are selected).
  181.  * Use it to find which of a group of radios is selected.
  182.  */
  183.  
  184.  
  185.  
  186. /*
  187.  * Waits for the given number of centiseconds.
  188.  * This is a MULTITASKING wait - although your program will do nothing,
  189.  * the rest of the desktop will continue to run.
  190.  * The wait is aborted after the given time, or as soon as an event is
  191.  * received. If an attempt is made to re-enter ClickWait(), it will return
  192.  * immediately (i.e. if a click event causes ClickWait to ba called, then
  193.  * a second click while "waiting" from the first click will have no effect.
  194.  */
  195. extern void Icon_ClickWait(int waittime);
  196.  
  197.  
  198.  
  199. /*
  200.  * Starts a drag operation based on the given icon.
  201.  * This is mainly used in "save as" windows to start drags of the file icon
  202.  * when it is clicked on, but may be useful elsewhere.
  203.  *
  204.  * This call DOES NOT use DragASprite
  205.  */
  206. extern void Icon_StartDrag(window_handle window, icon_handle icon);
  207.  
  208. /*
  209.  * Starts a drag operation based on the given icon, using DragASpr if available
  210.  *   extern void Icon_StartSolidDrag(window_handle window, icon_handle icon);
  211.  */
  212. #define Icon_StartSolidDrag DragASprite_DragIcon
  213.  
  214.  
  215. /*
  216.  * This will free any indirected data for this icon. It uses free(), so
  217.  * obviously expects that malloc() was used to get the memory in the first
  218.  * place, so make sure this is the case if you use this function.
  219.  */
  220. extern void Icon_DisposeIndData(icon_data *data, icon_flags flags);
  221.  
  222.  
  223.  
  224. /* =========================================================================
  225.  * Special high-level icon functions:
  226.  *   Slider icons: See "DeskLib.Libraries.Icon.c.Slider" for details
  227.  */
  228.  
  229. extern int Icon_SetSlider(window_handle window,
  230.                           icon_handle baseicon, icon_handle slidericon,
  231.                           int sliderpos);
  232. /* Sets a slider icon-pair to the specified position (specify as a
  233.  * percentage). Values < 0 and > 1000 are clipped, and the value to which the
  234.  * slider has been set is returned.
  235.  */
  236.  
  237. extern int Icon_UpdateSlider(window_handle window,
  238.                              icon_handle baseicon, icon_handle slidericon,
  239.                              int lastpos);
  240. /* (call on null events while slider being dragged)
  241.  * Calculates a new slider percentage from the mouse pointer position.
  242.  * If this differs from lastpos, the slider is updated (by recreating the
  243.  * slidericon to the new length.
  244.  * returns the new slider position percentage value.
  245.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  246.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  247.  */
  248.  
  249. extern int Icon_UpdateSlider(window_handle window,
  250.                              icon_handle baseicon, icon_handle slidericon,
  251.                              int lastpos);
  252. /* (call on null events while slider being dragged)
  253.  * Calculates a new slider percentage from the mouse pointer position.
  254.  * If this differs from lastpos, the slider is updated (by recreating the
  255.  * slidericon to the new length.
  256.  * returns the new slider position percentage value.
  257.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  258.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  259.  */
  260.  
  261. extern int Icon_DragSlider(window_handle window,
  262.                            icon_handle baseicon, icon_handle slidericon);
  263. /* Initiates the drag operation on a slider. Call this when you get a click
  264.  * in either baseicon or slidericon.
  265.  * Returns the new percentage represented by the slider (remember this so
  266.  * you can pass it in to Icon_UpdateSlider to save unnecessary (flickery)
  267.  * update.)
  268.  * NOTE: It is up to you to turn on NULL events and remember that
  269.  * Icon_UpdateSlider must be called on each poll...
  270.  * An alternative is to make the 2 slider icons use button type ALWAYS, and
  271.  * check the mouse button state yourself to see whether a drag needs to be
  272.  * started/continued...
  273.  */
  274.  
  275. extern int Icon_ReadSlider(window_handle window,
  276.                            icon_handle baseicon, icon_handle slidericon);
  277. /* Given a slider icon-pair, returns a percentage representing the state */
  278.  
  279.  
  280. #endif
  281.