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