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