home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / Libraries / LinkList / h / Icon
Encoding:
Text File  |  1992-04-06  |  9.8 KB  |  256 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.00 (22 Mar 1992)
  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. extern void Icon_Select(window_handle window, icon_handle icon);
  44. /* If the given icon is currently deselected, it is selected */
  45.  
  46. extern void Icon_Deselect(window_handle window, icon_handle icon);
  47. /* If the given icon is currently selected, it is deselected */
  48.  
  49. void Icon_Select3d(window_handle window, icon_handle icon);
  50. /* Just the same as Icon_Select, but forces redraw of the area around the
  51.  * icon so that the 3-d border is redrawn indented/unindented as appropriate
  52.  */
  53.  
  54. extern void Icon_Deselect3d(window_handle window, icon_handle icon);
  55. /* Just the same as Icon_Deselect, but forces redraw of the area around the
  56.  * icon so that the 3-d border is redrawn indented/unindented as appropriate
  57.  */
  58.  
  59.  
  60.  
  61. extern void Icon_Shade(window_handle window, icon_handle icon);
  62. /*
  63.  * if the icon is currently unshaded (active) it is shaded (made inactive)
  64.  * This includes removing the caret from the icon.
  65.  */
  66.  
  67. extern void Icon_Unshade(window_handle window, icon_handle icon);
  68. /* if the icon is currently shaded (inactive) it is unshaded (made active) */
  69.  
  70.  
  71.  
  72. extern void Icon_ForceWindowRedraw(window_handle window, icon_handle icon);
  73. /*  Force Redraws the area of WINDOW surrounding the icon, *including*
  74.  *  the 3-d border (validation string "b<bordertype>")
  75.  */
  76.  
  77. #define Icon_ForceRedraw(wind, icon) Wimp_SetIconState(wind, icon, 0, 0);
  78.         /* Forces the WIMP to redraw (just) the icon */
  79.  
  80.  
  81.  
  82. extern void Icon_SetCaret(window_handle window, icon_handle icon);
  83. /*
  84.  * This routine sets the caret within the requested icon. It places the
  85.  * caret at the (righthand) end of the text in the icon. If the icon is not
  86.  * a text icon, then the function returns quietly
  87.  */
  88.  
  89. extern void Icon_LoseCaret(window_handle window, icon_handle icon);
  90. /* Icon_LoseCaret
  91.  * This routine ensures that the caret is *not* contained within the
  92.  * designated icon. Only sets a new position if the icon currently contains
  93.  *  the caret.
  94.  */
  95.  
  96.  
  97.  
  98. extern void Icon_SetInteger(window_handle w, icon_handle i, int value);
  99. /*
  100.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  101.  * If the number is too long (too many digits) it will be truncated to fit.
  102.  * If unable to set the text (incorrect icon type), it returns quietly
  103.  */
  104.  
  105. extern void Icon_SetDouble(window_handle w, icon_handle i,
  106.                            double value, int decimalplaces);
  107. /*
  108.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  109.  * Only the first "decimalplaces" digits after the decimal point are
  110.  * printed. If the number is too long (too many digits) it will be truncated
  111.  * to fit. This may affect the accuracy or actual value of the number.
  112.  * If unable to set the text (incorrect icon type), it returns quietly
  113.  */
  114.  
  115. extern void Icon_SetText(window_handle w, icon_handle i, char *text);
  116. /*
  117.  * Copies the text string into the icon's indirected string buffer (and redraws)
  118.  * If unable to set the text (incorrect icon type), it returns quietly
  119.  * If text passed in is a NULL pointer, sets icon text to " "
  120.  */
  121.  
  122. extern void Icon_printf(window_handle window, icon_handle icon,
  123.                         char *format, ...);
  124. /* 
  125.  * Exactly the same as sprintf, but instead of passing in a string into which
  126.  * the result is written, you pass in the window+icon identifier of an
  127.  * indirected icon. (Anything other than an indirected icon will return
  128.  * quietly with NO effect)
  129.  * e.g Icon_printf(window, 5, "%d bytes copied", current);
  130.  */
  131.  
  132.  
  133.  
  134. extern double Icon_GetDouble(window_handle w, icon_handle i);
  135. /*
  136.  * Gets the given icon's text and returns it in the form of a "double"
  137.  * floating-point value. 0 will be returned from any error/invalid text
  138.  */
  139.  
  140. extern int Icon_GetInteger(window_handle w, icon_handle i);
  141. /*
  142.  * Gets the given icon's text and returns it in the form of an integer
  143.  * numeric value. 0 will be returned from any error/invalid text
  144.  */
  145.  
  146. extern void Icon_GetText(window_handle w, icon_handle i, char *text);
  147. /*
  148.  * Copies the text string from the icon (sprite name, text, or indirected)
  149.  * into the array pointed to by "text"
  150.  */
  151.  
  152.  
  153.  
  154. extern void Icon_SetRadios(window_handle window,
  155.                            icon_handle first, icon_handle last,
  156.                            icon_handle onradio);
  157. /*
  158.  * Pass in a group of icons (specified by lowest-numbered icon and
  159.  * highest-numbered icon), and the icon from this group that you want
  160.  * selected. All icons except the one you want selected will be deselected.
  161.  */
  162.  
  163. extern int Icon_WhichRadio(window_handle window,
  164.                            icon_handle first, icon_handle last);
  165. /*
  166.  * This function accepts parameters for the first (lowest numbered) and
  167.  * last (highest numnbered) in a group of icons (generally a group of radio
  168.  * buttons). It returns the icon number of the first icon it finds within
  169.  * this range which is selected (or "last" if none are selected).
  170.  * Use it to find which of a group of radios is selected.
  171.  */
  172.  
  173.  
  174.  
  175. /*
  176.  * Waits for the given number of centiseconds.
  177.  * This is a MULTITASKING wait - although your program will do nothing,
  178.  * the rest of the desktop will continue to run.
  179.  * The wait is aborted after the given time, or as soon as an event is
  180.  * received. If an attempt is made to re-enter ClickWait(), it will return
  181.  * immediately (i.e. if a click event causes ClickWait to ba called, then
  182.  * a second click while "waiting" from the first click will have no effect.
  183.  */
  184. extern void Icon_ClickWait(int waittime);
  185.  
  186.  
  187.  
  188. /*
  189.  * Starts a drag operation based on the given icon.
  190.  * This is mainly used in "save as" windows to start drags of the file icon
  191.  * when it is clicked on, but may be useful elsewhere.
  192.  *
  193.  * Currently NOT DragASprite compatible... Anyone want to remedy this?
  194.  */
  195. extern void Icon_StartDrag(window_handle window, icon_handle icon);
  196.  
  197.  
  198.  
  199. /* =========================================================================
  200.  * Special high-level icon functions:
  201.  *   Slider icons: See "DeskLib.Libraries.Icon.c.Slider" for details
  202.  */
  203.  
  204. extern int Icon_SetSlider(window_handle window,
  205.                           icon_handle baseicon, icon_handle slidericon,
  206.                           int sliderpos);
  207. /* Sets a slider icon-pair to the specified position (specify as a
  208.  * percentage). Values < 0 and > 1000 are clipped, and the value to which the
  209.  * slider has been set is returned.
  210.  */
  211.  
  212. extern int Icon_UpdateSlider(window_handle window,
  213.                              icon_handle baseicon, icon_handle slidericon,
  214.                              int lastpos);
  215. /* (call on null events while slider being dragged)
  216.  * Calculates a new slider percentage from the mouse pointer position.
  217.  * If this differs from lastpos, the slider is updated (by recreating the
  218.  * slidericon to the new length.
  219.  * returns the new slider position percentage value.
  220.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  221.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  222.  */
  223.  
  224. extern int Icon_UpdateSlider(window_handle window,
  225.                              icon_handle baseicon, icon_handle slidericon,
  226.                              int lastpos);
  227. /* (call on null events while slider being dragged)
  228.  * Calculates a new slider percentage from the mouse pointer position.
  229.  * If this differs from lastpos, the slider is updated (by recreating the
  230.  * slidericon to the new length.
  231.  * returns the new slider position percentage value.
  232.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  233.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  234.  */
  235.  
  236. extern int Icon_DragSlider(window_handle window,
  237.                            icon_handle baseicon, icon_handle slidericon);
  238. /* Initiates the drag operation on a slider. Call this when you get a click
  239.  * in either baseicon or slidericon.
  240.  * Returns the new percentage represented by the slider (remember this so
  241.  * you can pass it in to Icon_UpdateSlider to save unnecessary (flickery)
  242.  * update.)
  243.  * NOTE: It is up to you to turn on NULL events and remember that
  244.  * Icon_UpdateSlider must be called on each poll...
  245.  * An alternative is to make the 2 slider icons use button type ALWAYS, and
  246.  * check the mouse button state yourself to see whether a drag needs to be
  247.  * started/continued...
  248.  */
  249.  
  250. extern int Icon_ReadSlider(window_handle window,
  251.                            icon_handle baseicon, icon_handle slidericon);
  252. /* Given a slider icon-pair, returns a percentage representing the state */
  253.  
  254.  
  255. #endif
  256.