home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / gcc / !GCC / patches / DeskLib / h / Slider < prev    next >
Encoding:
Text File  |  1994-10-03  |  12.2 KB  |  317 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:    Slider.h
  12.     Author:  Copyright © 1994 Peter Gaunt
  13.     Version: 1.00 (12 Mar 1994)
  14.     Purpose: Provide a clean way of using 'slider' icons.  These routines
  15.                are more general-purpose, friendly and efficient that those
  16.                found in the Icon library.  (The Icon slider functions are left
  17.                in for backwards compatibility at the moment - you should
  18.                use these functions in preference).
  19. */
  20.  
  21. #ifndef __dl_slider_h
  22. #define __dl_slider_h
  23.  
  24. #ifndef __dl_core_h
  25. #include "Core.h"
  26. #endif
  27.  
  28. #ifndef __dl_WimpSWIs_h
  29. #include "WimpSWIs.h"
  30. #endif
  31.  
  32. #ifndef __dl_Sprite_h
  33. #include "Sprite.h"
  34. #endif
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40. #define SLIDER_MAX 100000
  41.  
  42. /*
  43. To work, sliders need a base icon. This should be a non-text, non-sprite icon
  44. with an unfilled background. The window should have its auto-redraw flag clear.
  45. They need a minimal amount of co-operation from the rest of the program in
  46. order to be redrawn after redraw events (this basically just involves calling
  47. Slider_Redraw inside a redraw loop). The boundary for the slider icon should
  48. not overlap any part of the window which also needs help to be redrawn.
  49.  
  50. Although sliders maintain their current value internally on a scale of
  51. 0 - SLIDER_MAX, the values returned when Slider functions are called are always
  52. in "user units" which are set within whatever limits suit your program best
  53. (within reason of course).
  54.  
  55. Slider functions need screen_delta info to be kept up to date
  56. Make sure the mode change event is enabled and Handler_ModeChange is called
  57.  
  58. */
  59.  
  60.  
  61. /****************************************************************************
  62.  
  63. >   typedef struct slider_info
  64.  
  65.     The slider functions use this structure extensively.
  66.  
  67.     The elements are as follows :
  68.  
  69.     window: handle of window containing the slider
  70.     icon  : handle of base icon within the window. Should have unfilled
  71.             background.
  72.             If you want to be able to drag the slider you should normally
  73.             set the icon's button type to click (type 3). You then call
  74.             Slider_Drag when the icon is clicked.
  75.  
  76.     value: slider functions use values between 0 & SLIDER_MAX which are
  77.            converted to user units between limits.min and limits.max when
  78.            returned to calling functions. Set this status.value to
  79.            SLIDER_MAX +1 when initialising the slider.
  80.  
  81.     limits.min
  82.     limits.max: Values returned when the slider is at its minimum or maximum
  83.                 extent. Other slider positions return intermediate values.
  84.                 The slider is clamped to these values.
  85.  
  86.     colour.foreground
  87.     colour.background: Foreground and background colours of the slider.
  88.                        Set colours to -1 if not wanting a visible slider.
  89.                        See also flags.rgb below
  90.     border.x
  91.     border.y: size of blank border which will be left between the slider and
  92.               the base icon boundary. OS units.
  93.               Note that if the base icon has a border then setting the slider
  94.               borders to 0 causes the icon's border to flicker when the
  95.               slider is updated. Setting a slider border avoids this. The
  96.               slider border needed to prevent flicker depends on the type of
  97.               border which the icon has. A value of 4 suffices for most of
  98.               the standard icon borders. A value of 12 produces sliders
  99.               similar to those in the RISC OS 3 Style Guide if the icon has
  100.               an r2 type border. Setting borders greater than half the size
  101.               of the icon produces odd effects...
  102.  
  103.     knob: Not used at present but may be used in future versions to specify
  104.           a sprite to be used as a knob. For now set knob.spritearea to NULL
  105.           to indicate no knob.
  106.  
  107.     flags.vertical: If set then slider is vertical. If clear then it is
  108.                     horizontal.
  109.     flags.rgb:      If clear then colour.foreground & colour.background refer
  110.                     to Wimp colours 0-15. If set then they refer to an RGB
  111.                     palette suitable for passing to ColourTrans (0xBBGGRR00).
  112.     flags.dragging: This is set by Slider_Drag while it is dragging a slider.
  113.                     Set this to zero when initialising slider.
  114.     flags.clickstop:If clear then slider is dragged as smoothly as possible.
  115.                     If set then slider jumps between exact user values as it
  116.                     is dragged, i.e. slider will only be redrawn when user
  117.                     value changes.
  118.     flags.reserved: For future expansion. Set this to zero.
  119.  
  120.     update: If this is not set to NULL then it is a pointer to a function
  121.             which will be called if the slider value (in user units not
  122.             internal units) changes during a call to Slider_SetValue
  123.             or Slider_Drag.
  124.  
  125.             Providing an update function is useful since it allows you
  126.             to centralise other operations, such as updating a text icon
  127.             showing the slider's value, regardless of whether the slider
  128.             moves because of a drag or a call to Slider_SetValue. It is
  129.             also useful for continually monitoring the current value during
  130.             a drag operation which otherwise you wouldn't know until the
  131.             drag finished.
  132.  
  133.             The function should take two arguments. The first is a
  134.             pointer to a slider_info structure. When the function is
  135.             called this argument is a pointer to the slider currently
  136.             being dealt with.
  137.  
  138.             The second argument is a pointer to any data you wish.
  139.             You pass a pointer (which can be NULL) to the data to
  140.             Slider_SetValue or Slider_Drag when you call them and it
  141.             gets passed on to the update function when/if it is called.
  142.             This argument can be useful, for example, for passing
  143.             information to your update function to indicate just what
  144.             operation is currently being performed (e.g. to let it
  145.             distinguish between a call to Slider_SetValue and a call to
  146.             Slider_Drag).
  147.  
  148.             The function should return non-NULL if it wants the drag
  149.             function to stop dragging. This allows you to, for example,
  150.             stop the slider going above or below a maximum or minimum
  151.             value, independently of limits.min and limits.max.
  152.  
  153.     reference: You may use this for any purpose you like. If you set up more
  154.                than one slider, it is useful to give each a separate
  155.                reference so that your update function (if any) can
  156.                distinguish between them without having to check the window &
  157.                icon handles.
  158.  
  159. ****************************************************************************/
  160.  
  161. typedef struct
  162. {
  163.   window_handle window;
  164.   icon_handle   icon;
  165.  
  166.   int value;
  167.  
  168.   struct
  169.   { int         min;
  170.     int         max;
  171.   } limits;
  172.  
  173.   struct
  174.   { int foreground;
  175.     int background;
  176.   } colour;
  177.  
  178.   struct
  179.   { int x;
  180.     int y;
  181.   } border;
  182.  
  183.   struct
  184.   { sprite_areainfo *spritearea;
  185.     sprite_header   *sprite;
  186.   } knob;
  187.  
  188.   struct
  189.   { int  vertical  :1;
  190.     int  rgb       :1;
  191.     int  dragging  :1;
  192.     int  clickstop :1;
  193.     int  reserved  :28;
  194.   } flags;
  195.  
  196.   int ( *update )( void *, void * );
  197.   int reference;
  198. } slider_info;
  199.  
  200.  
  201.  
  202. /****************************************************************************
  203.  
  204. > os_error *Slider_Redraw(slider_info *slider, wimp_rect *clipwindow);
  205.  
  206.  
  207.   Inputs:   slider - the slider info for this slider.
  208.               clipwindow - the area of the window being redrawn (in screen
  209.               coordinates).
  210.   Returns:  An error pointer, or NULL if no errors occured.
  211.   Purpose:  Redraws a slider icon - call this function from within your
  212.               redraw loops.
  213.             If clipwindow != NULL then does nothing if slider is outside
  214.             clip window.
  215.   Errors:   Unable to use the colour indicated in 'slider'.
  216.   SeeAlso:  Slider_ReadValue; Slider_SetValue; Slider_Drag
  217.  
  218. ****************************************************************************/
  219.  
  220. extern os_error *Slider_Redraw(slider_info *slider, wimp_rect *clipwindow);
  221.  
  222.  
  223. /****************************************************************************
  224.  
  225.   int Slider_ReadValue(slider_info *slider);
  226.  
  227.   Inputs:   slider - the slider info for this slider.
  228.   Returns:  The current slider value, in user units.
  229.   Purpose:  Returns current slider setting in user units.
  230.             (i.e. between slider->limits.min and slider->limits.max)
  231.   SeeAlso:  Slider_SetValue; Slider_Drag; Slider_Redraw
  232.  
  233. ****************************************************************************/
  234.  
  235. extern int Slider_ReadValue( slider_info *slider );
  236.  
  237.  
  238.  
  239. /****************************************************************************
  240.  
  241.   os_error *Slider_SetValue(slider_info *slider,
  242.                             int value,
  243.                             int *valueset,
  244.                             void *ref );
  245.  
  246.   Inputs:   slider - the slider info for this slider.
  247.               value  - the value (in user units) that the slider should be
  248.                          set to.
  249.               ref    - a reference to pass to the update callback funtion.
  250.   Outputs:  valueset - if not NULL, this is updated to hold the value
  251.                        actually the slider is actually set to (this can be
  252.                        different to 'value', e.g. if value is outside the
  253.                        slider limits).
  254.   Returns:  Standard error block or NULL if no error occurs.
  255.   Purpose:  Sets slider to value in value (user units).
  256.               If the slider is being dragged (i.e. if slider->status.dragging
  257.               is set) then the function does nothing.
  258.  
  259.             The value is clamped to numbers between slider->limits.min and
  260.             slider->limits.max.
  261.  
  262.             The slider->update function (if any) will be called if the value
  263.             has changed.
  264.  
  265.             Can also be used to alter other settings (e.g. colour) by
  266.             directly changing the slider structure before calling.
  267.   Errors:   An error is returned if there is a problem accessing or
  268.               redrawing the icon.
  269.   SeeAlso:  Slider_ReadValue; Slider_Drag; Slider_Redraw
  270.  
  271. ****************************************************************************/
  272.  
  273. extern os_error *Slider_SetValue(slider_info *slider,
  274.                                  int value,
  275.                                  int *valueset,
  276.                                  void *ref );
  277.  
  278.  
  279.  
  280. /****************************************************************************
  281.  
  282.   os_error *Slider_Drag(slider_info *slider,
  283.                         BOOL *closed,
  284.                         int *value,
  285.                         void *ref )
  286.  
  287.   Inputs:   slider - the slider info for this slider.
  288.               ref    - a reference to pass to the update callback funtion.
  289.   Outputs:  closed - if not NULL, and the window is closed during the drag,
  290.                          then closed is set to TRUE.
  291.               value  - if not NULL, then it is set to the slider value (in
  292.                          user units) on exit.
  293.   Returns:  Standard error block, or none if no errors encountered.
  294.   Purpose:  Drag a slider. Call when slider's base icon is clicked on.
  295.               Polls the Wimp, grabbing NULL events but passing the rest on to
  296.               Event_Process.
  297.               Exits when dragging stops or the slider->update function (if any)
  298.               returns a non-NULL value.
  299.               Also exits if window is closed while dragging (see Outputs).
  300.   Errors:   An error is returned if there is a problem accessing or
  301.               redrawing the icon.
  302.   SeeAlso:  Slider_SetValue; Slider_ReadValue; Slider_Redraw
  303.  
  304. ****************************************************************************/
  305.  
  306. extern os_error *Slider_Drag(slider_info *slider,
  307.                              int *closed,
  308.                              int *value,
  309.                              void *ref);
  310.  
  311.  
  312. #ifdef __cplusplus
  313.            }
  314. #endif
  315.  
  316. #endif
  317.