home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / Icon < prev    next >
Encoding:
Text File  |  1994-05-29  |  19.3 KB  |  506 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
  13.     Version: 1.10 (22 Mar 1994)
  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. #ifndef __dl_dragaspr_h
  26. #include "DragASpr.h"
  27. #endif
  28.  
  29.  
  30.   /* Icon_BarIcon ---------------------------------------------------------
  31.    * This function places an icon on the iconbar. It makes a "normal"
  32.    * sprite-only icon, with the "normal" default flags. If you want an
  33.    * icon that is not this default, then create it yourself (it isn't hard!)
  34.    *
  35.    * If you wish to attach handlers/menus to the baricon, then remember
  36.    * it's handle, and pass this to Event_Claim...
  37.    * (Or wait for release 2 of DeskLib, which should have an Event_BarIcon)
  38.    *
  39.    * Pass in "spritename" -  the name of a sprite in the Wimp Sprite pool
  40.    * and "pos", which should be iconbar_LEFT or iconbar_RIGHT
  41.    * The correct size of the icon will be determined and used
  42.    * Returns: The icon handle of the created icon
  43.    */
  44. extern icon_handle Icon_BarIcon(char *spritename, window_handle pos);
  45.  
  46.  
  47.   /* Icon_BarIconUser -----------------------------------------------------
  48.    * Plonk a sprite from a USER sprite area on the icon bar
  49.    * Returns icon handle.
  50.    */
  51. extern icon_handle Icon_BarIconUser(char *spritename, window_handle pos,
  52.                                     unsigned int *area);
  53.  
  54.  
  55.   /* Icon_GetSelect -------------------------------------------------------
  56.    *  Returns TRUE if the given icon is selected
  57.    */
  58. extern BOOL Icon_GetSelect(window_handle window, icon_handle icon);
  59.  
  60.  
  61.   /* Icon_GetShade --------------------------------------------------------
  62.    *  Returns TRUE if the given icon is shaded
  63.    */
  64. extern BOOL Icon_GetShade(window_handle window, icon_handle icon);
  65.  
  66.  
  67. extern void Icon_SetSelect(window_handle window, icon_handle icon, int flag);
  68. /* Equivalent in action to Icon_Select + Icon_Deselect: Pass in a flag to
  69.  * set the new selected status of the icon (0 = deselect, 1 = select)
  70.  */
  71.  
  72. extern void Icon_Select(window_handle window, icon_handle icon);
  73. /* If the given icon is currently deselected, it is selected */
  74.  
  75. extern void Icon_Deselect(window_handle window, icon_handle icon);
  76. /* If the given icon is currently selected, it is deselected */
  77.  
  78.  
  79. extern void Icon_SetShade(window_handle window, icon_handle icon, int flag);
  80. /* Equivalent in action to Icon_Shade + Icon_Unshade: Pass in a flag to
  81.  * set the new shaded status of the icon (0 = unshaded, 1 = shaded)
  82.  */
  83.  
  84. extern void Icon_Shade(window_handle window, icon_handle icon);
  85. /*
  86.  * if the icon is currently unshaded (active) it is shaded (made inactive)
  87.  * This includes removing the caret from the icon.
  88.  */
  89.  
  90. extern void Icon_Unshade(window_handle window, icon_handle icon);
  91. /* if the icon is currently shaded (inactive) it is unshaded (made active) */
  92.  
  93.  
  94. extern void Icon_SetForeColour(window_handle window, icon_handle icon,
  95.                                int wimpcolour);
  96. /*  Sets an icon's foreground colour to the given WIMP colour (in range 0..15).
  97.  *  NOTE that this is a simple function which does not currently support
  98.  *  outline font icons (in fact, it'll corrupt their font handle and cause
  99.  *  untold grief)
  100.  */
  101.  
  102. extern void Icon_SetBackColour(window_handle window, icon_handle icon,
  103.                                int wimpcolour);
  104. /*  Sets an icon's background colour to the given WIMP colour (in range 0..15).
  105.  *  NOTE that this is a simple function which does not currently support
  106.  *  outline font icons (in fact, it'll corrupt their font handle and cause
  107.  *  untold grief)
  108.  */
  109.  
  110.  
  111. extern void Icon_ForceWindowRedraw(window_handle window, icon_handle icon);
  112. /*  Force Redraws the area of WINDOW surrounding the icon, *including*
  113.  *  the 3-d border (validation string "b<bordertype>")
  114.  */
  115.  
  116. #define Icon_ForceRedraw(wind, icon) Wimp_SetIconState(wind, icon, 0, 0);
  117.         /* Forces the WIMP to redraw (just) the icon */
  118.  
  119.  
  120.  
  121. extern void Icon_SetCaret(window_handle window, icon_handle icon);
  122. /*
  123.  * This routine sets the caret within the requested icon. It places the
  124.  * caret at the (righthand) end of the text in the icon. If the icon is not
  125.  * a text icon, then the function returns quietly
  126.  */
  127.  
  128. extern void Icon_LoseCaret(window_handle window, icon_handle icon);
  129. /* Icon_LoseCaret
  130.  * This routine ensures that the caret is *not* contained within the
  131.  * designated icon. Only sets a new position if the icon currently contains
  132.  *  the caret.
  133.  */
  134.  
  135.  
  136.  
  137. extern void Icon_SetInteger(window_handle w, icon_handle i, int value);
  138. /*
  139.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  140.  * If the number is too long (too many digits) it will be truncated to fit.
  141.  * If unable to set the text (incorrect icon type), it returns quietly
  142.  */
  143.  
  144. extern void Icon_SetDouble(window_handle w, icon_handle i,
  145.                            double value, int decimalplaces);
  146. /*
  147.  * Sets the given icon's text to hold the number in "value". (and redraws icon)
  148.  * Only the first "decimalplaces" digits after the decimal point are
  149.  * printed. If the number is too long (too many digits) it will be truncated
  150.  * to fit. This may affect the accuracy or actual value of the number.
  151.  * If unable to set the text (incorrect icon type), it returns quietly
  152.  */
  153.  
  154. extern void Icon_SetText(window_handle w, icon_handle i, char *text);
  155. /*
  156.  * Copies the text string into the icon's indirected string buffer (and redraws)
  157.  * If unable to set the text (incorrect icon type), it returns quietly
  158.  * If text passed in is a NULL pointer, sets icon text to " "
  159.  */
  160.  
  161. extern void Icon_SetTextRJ(window_handle w, icon_handle i, char *text);
  162. /*
  163.  * Copies the text string into the icon's indirected string buffer (and redraws)
  164.  * This text is "right justified", meaning that if the text doesn't fit
  165.  * into the available buffer space, it is truncated at the *LEFT*-hand side,
  166.  * and preceded by a '...' (ellipsis) character.
  167.  * If unable to set the text (incorrect icon type), it returns quietly
  168.  * If text passed in is a NULL pointer, sets icon text to '\0'
  169.  */
  170.  
  171.  
  172. extern void Icon_printf(window_handle window, icon_handle icon,
  173.                         char *format, ...);
  174. /* 
  175.  * Exactly the same as sprintf, but instead of passing in a string into which
  176.  * the result is written, you pass in the window+icon identifier of an
  177.  * indirected icon. (Anything other than an indirected icon will return
  178.  * quietly with NO effect)
  179.  * e.g Icon_printf(window, 5, "%d bytes copied", current);
  180.  */
  181.  
  182.  
  183.  
  184. extern double Icon_GetDouble(window_handle w, icon_handle i);
  185. /*
  186.  * Gets the given icon's text and returns it in the form of a "double"
  187.  * floating-point value. 0 will be returned from any error/invalid text
  188.  */
  189.  
  190. extern int Icon_GetInteger(window_handle w, icon_handle i);
  191. /*
  192.  * Gets the given icon's text and returns it in the form of an integer
  193.  * numeric value. 0 will be returned from any error/invalid text
  194.  */
  195.  
  196. extern void Icon_GetText(window_handle w, icon_handle i, char *text);
  197. /*
  198.  * Copies the text string from the icon (sprite name, text, or indirected)
  199.  * into the array pointed to by "text"
  200.  * Note that the array pointed to by "text" must be big enough to hold the
  201.  * resulting string, so the minimum sizes are:
  202.  *  If non-indirected (or a sprite), 12 characters
  203.  *  If indirected text, the indirected size of the icon.
  204.  */
  205.  
  206.  
  207.  
  208. /****************************************************************************
  209.  
  210.     char *Icon_GetTextPtr(window_handle window, icon_handle icon);
  211.     
  212.     Inputs:   window, icon - handle pair of the icon to examine.
  213.     Returns:  Pointer to the *actual* indirected text buffer used for the
  214.               given icon.  If the icon is not indirected text, then you will
  215.               get garbage back.
  216.     Purpose:  Get a pointer to the indirected text buffer for this icon, so
  217.               you can read/change it.
  218.  
  219. ****************************************************************************/
  220.  
  221. extern char *Icon_GetTextPtr(window_handle, icon_handle);
  222.  
  223.  
  224. /****************************************************************************
  225.  
  226. > os_error *Icon_SetFlags(window_handle window, 
  227.                           icon_handle icon, 
  228.                           int flags, 
  229.                           BOOL set);
  230.     
  231.   Inputs:   window, icon - window and icon handle pair of icon to change.
  232.             flags - bitfield specifying the bits to change.
  233.             set - if TRUE, all the flags defined by 'flags' will be set to
  234.                   1, otherwise they will all be set to 0.
  235.   Returns:  Usual RISC OS error block.
  236.   Purpose:  Neat interface to the Wimp_SetIconState SWI.
  237.   Errors:   As for Wimp_SetIconState()
  238.  
  239. ****************************************************************************/
  240.  
  241. #define Icon_SetFlags(window, icon, flags, set) \
  242.   Wimp_SetIconState((window), (icon), ((set) ? (flags) : 0), (flags))
  243.  
  244.  
  245. /****************************************************************************
  246.  
  247. > os_error *Icon_SetFgCol(window, icon, col) 
  248.     
  249.   Inputs:   window, icon - handle pair to identify the icon to change.
  250.             col - the new foreground colour to apply to the icon.
  251.   Returns:  Standard RISC OS error block.
  252.   Purpose:  Macro to allow simple call to change the foreground colour
  253.             of an icon (via the Wimp_SetIconState SWI).
  254.   SeeAlso:  Icon_SetBgCol()
  255.  
  256. ****************************************************************************/
  257.  
  258. #define Icon_SetFgCol(w, i, col) \
  259. Wimp_SetIconState((w), (i), (col) * icon_FORECOLOUR, 0xF * icon_FORECOLOUR)
  260.  
  261.  
  262. /****************************************************************************
  263.  
  264. > os_error *Icon_SetBgCol(window, icon, col) 
  265.     
  266.   Inputs:   window, icon - handle pair to identify the icon to change.
  267.             col - the new background colour to apply to the icon.
  268.   Returns:  Standard RISC OS error block.
  269.   Purpose:  Macro to allow simple call to change the background colour
  270.             of an icon (via the Wimp_SetIconState SWI).
  271.   SeeAlso:  Icon_SetFgCol()
  272.  
  273. ****************************************************************************/
  274.  
  275. #define Icon_SetBgCol(w, i, col) \
  276. Wimp_SetIconState((w), (i), \
  277.                 (unsigned) (col) * (unsigned) icon_BACKCOLOUR, \
  278.                 (unsigned) 0xF * (unsigned) icon_BACKCOLOUR)
  279.                 
  280.  
  281. /****************************************************************************
  282.  
  283.     void Icon_ShadeGroup(window_handle window, 
  284.                         icon_handle icons[], 
  285.                          BOOL shade);
  286.     
  287.     Inputs:   window - the window that contains the icons to be changed.
  288.               icons - array of icon handles that specify the icons to change.
  289.                       The array should be terminated with -1.
  290.               shade - TRUE to shade the icons, FALSE to unshade them.
  291.     Purpose:  Shade a group of icons as defined by an -1 terminated array of
  292.               icon handles.
  293.     SeeAlso:  Icon_SelectGroup()
  294.  
  295. ****************************************************************************/
  296.  
  297. extern void Icon_ShadeGroup(window_handle window, 
  298.                          icon_handle icons[], 
  299.                             BOOL shade);
  300.  
  301.  
  302. /****************************************************************************
  303.  
  304.     void Icon_SelectGroup(window_handle window, 
  305.                          icon_handle icons[], 
  306.                           BOOL select);
  307.     
  308.     Inputs:   window - the window that contains the icons to be changed.
  309.               icons - array of icon handles that specify the icons to change.
  310.                       The array should be terminated with -1.
  311.               select - TRUE to select the icons, FALSE to unselect them.
  312.     Purpose:  Select or unselect a group of icons, as defined by an -1 
  313.               terminated array of icon handles.
  314.     SeeAlso:  Icon_ShadeGroup()
  315.  
  316. ****************************************************************************/
  317.  
  318. extern void Icon_SelectGroup(window_handle window, 
  319.                           icon_handle icons[], 
  320.                           BOOL select);
  321.  
  322.  
  323.  
  324.  
  325. /****************************************************************************
  326.  
  327.     int Icon_GetFgCol(icon_block *icon);
  328.     
  329.     Inputs:   icon - pointer to the icon info block that the colour should
  330.                      be extracted.  This copes with anti-aliased icons.
  331.     Returns:  The foreground colour of the described icon.
  332.     Purpose:  Extract the foreground colour of an icon, coping with all the
  333.               special cases.
  334.  
  335. ****************************************************************************/
  336.  
  337. extern int Icon_GetFgCol(icon_block *icon);
  338.  
  339.  
  340. /****************************************************************************
  341.  
  342.     int Icon_GetBgCol(icon_block *icon);
  343.     
  344.     Inputs:   icon - pointer to the icon info block that the colour should
  345.                      be extracted.  This copes with anti-aliased icons.
  346.     Returns:  The background colour of the described icon.
  347.     Purpose:  Extract the background colour of an icon, coping with all the
  348.               special cases.
  349.  
  350. ****************************************************************************/
  351.  
  352. extern int Icon_GetBgCol(icon_block *icon);
  353.  
  354.  
  355.  
  356.  
  357. extern void Icon_SetRadios(window_handle window,
  358.                            icon_handle first, icon_handle last,
  359.                            icon_handle onradio);
  360. /*
  361.  * Pass in a group of icons (specified by lowest-numbered icon and
  362.  * highest-numbered icon), and the icon from this group that you want
  363.  * selected. All icons except the one you want selected will be deselected.
  364.  */
  365.  
  366. extern int Icon_WhichRadio(window_handle window,
  367.                            icon_handle first, icon_handle last);
  368. /*
  369.  * This function accepts parameters for the first (lowest numbered) and
  370.  * last (highest numnbered) in a group of icons (generally a group of radio
  371.  * buttons). It returns the icon number of the first icon it finds within
  372.  * this range which is selected (or "last" if none are selected).
  373.  * Use it to find which of a group of radios is selected.
  374.  */
  375.  
  376.  
  377.  
  378. /*
  379.  * Waits for the given number of centiseconds.
  380.  * This is a MULTITASKING wait - although your program will do nothing,
  381.  * the rest of the desktop will continue to run.
  382.  * The wait is aborted after the given time, or as soon as an event is
  383.  * received. If an attempt is made to re-enter ClickWait(), it will return
  384.  * immediately (i.e. if a click event causes ClickWait to ba called, then
  385.  * a second click while "waiting" from the first click will have no effect.
  386.  */
  387. extern void Icon_ClickWait(int waittime);
  388.  
  389.  
  390.  
  391. /*
  392.  * Starts a drag operation based on the given icon.
  393.  * This is mainly used in "save as" windows to start drags of the file icon
  394.  * when it is clicked on, but may be useful elsewhere.
  395.  *
  396.  * This call DOES NOT use DragASprite
  397.  */
  398. extern void Icon_StartDrag(window_handle window, icon_handle icon);
  399.  
  400. /*
  401.  * Starts a drag operation based on the given icon, using DragASpr if available
  402.  *   extern void Icon_StartSolidDrag(window_handle window, icon_handle icon);
  403.  */
  404. #define Icon_StartSolidDrag DragASprite_DragIcon
  405.  
  406.  
  407. /*
  408.  * This will free any indirected data for this icon. It uses free(), so
  409.  * obviously expects that malloc() was used to get the memory in the first
  410.  * place, so make sure this is the case if you use this function.
  411.  */
  412. extern void Icon_DisposeIndData(icon_data *data, icon_flags flags);
  413.  
  414.  
  415.  
  416. /****************************************************************************
  417.  
  418.     void Icon_FileIcon(window_handle window, icon_handle icon, int filetype);
  419.     
  420.     Inputs:   window   - the window containing the icon to change.
  421.               icon     - handle of the icon to change.
  422.               filetype - desired filetype sprite to display.
  423.     Purpose:  Changes an icon in a window to display the correct filetype
  424.               sprite for the given filetype number.
  425.               Requires that the specified icon is an indirected text-only
  426.               icon with enough room in the text buffer to hold the sprite
  427.               name.
  428.               This function converts it to an indirected sprite-only icon,
  429.               and fills in the sprite name and area.
  430.              
  431.               It does not check to make sure that the sprite corresponding
  432.               to this filetype exists in the Wimp sprite pool - the caller
  433.               should ensure that this is the case.
  434.  
  435. ****************************************************************************/
  436.  
  437. extern void Icon_FileIcon(window_handle window, icon_handle icon, int filetype);
  438.  
  439.  
  440. /****************************************************************************
  441.  
  442.     void Icon_ScreenPos(window_handle window, icon_handle icon,
  443.                         wimp_rect *rect)
  444.     
  445.     Inputs:   window   - the window containing the icon to examine.
  446.               icon     - handle of the icon to examine.
  447.     Outputs:  rect     - the screen coordinates of the icon.
  448.     Purpose:  Gets the coordinate of an icon, and converts them into
  449.               screen coordinates.
  450.  
  451. ****************************************************************************/
  452.  
  453. extern void Icon_ScreenPos(window_handle window,
  454.                            icon_handle icon,
  455.                            wimp_rect *rect);
  456.  
  457.  
  458.  
  459. /* =========================================================================
  460.  * Special high-level icon functions:
  461.  *   Slider icons: See "DeskLib.Libraries.Icon.c.Slider" for details
  462.  */
  463.  
  464. extern int Icon_SetSlider(window_handle window,
  465.                           icon_handle baseicon, icon_handle slidericon,
  466.                           int sliderpos);
  467. /* Sets a slider icon-pair to the specified position (specify as a
  468.  * percentage). Values < 0 and > 1000 are clipped, and the value to which the
  469.  * slider has been set is returned.
  470.  */
  471.  
  472. extern int Icon_UpdateSlider(window_handle window,
  473.                              icon_handle baseicon, icon_handle slidericon,
  474.                              int lastpos);
  475. /* (call on null events while slider being dragged)
  476.  * Calculates a new slider percentage from the mouse pointer position.
  477.  * If this differs from lastpos, the slider is updated (by recreating the
  478.  * slidericon to the new length.
  479.  * returns the new slider position percentage value.
  480.  * NOTE: Slider update is achieved by DELETING and re-creating the slider
  481.  * icon. This relies upon no icons of a lower icon handle having been deleted!
  482.  */
  483.  
  484.  
  485. extern int Icon_DragSlider(window_handle window,
  486.                            icon_handle baseicon, icon_handle slidericon);
  487. /* Initiates the drag operation on a slider. Call this when you get a click
  488.  * in either baseicon or slidericon.
  489.  * Returns the new percentage represented by the slider (remember this so
  490.  * you can pass it in to Icon_UpdateSlider to save unnecessary (flickery)
  491.  * update.)
  492.  * NOTE: It is up to you to turn on NULL events and remember that
  493.  * Icon_UpdateSlider must be called on each poll...
  494.  * An alternative is to make the 2 slider icons use button type ALWAYS, and
  495.  * check the mouse button state yourself to see whether a drag needs to be
  496.  * started/continued...
  497.  */
  498.  
  499. extern int Icon_ReadSlider(window_handle window,
  500.                            icon_handle baseicon, icon_handle slidericon);
  501. /* Given a slider icon-pair, returns a percentage representing the state */
  502.  
  503.  
  504.  
  505. #endif
  506.