chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/buttons

   1 /*
   2  * Buttons
   3  *  provides handling for clever buttons and things.
   4  *
   5  * v. 1.00 (23 July 1991)
   6  *
   7  * © 1991-1998 Straylight
   8  */
   9
  10 /*----- Licensing note ----------------------------------------------------*
  11  *
  12  * This file is part of Straylight's Steel library.
  13  *
  14  * Steel is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2, or (at your option)
  17  * any later version.
  18  *
  19  * Steel is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with Steel.  If not, write to the Free Software Foundation,
  26  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 #ifndef __buttons_h
  30 #define __buttons_h
  31
  32 #ifndef __wimp_h
  33 #include "wimp.h"
  34 #endif
  35
  36 #ifndef __dbox_h
  37 #include "dbox.h"
  38 #endif
  39
  40 typedef void (*buttons_arrowProc)(dbox d,dbox_field f,int diff,void *handle);
  41
  42 typedef struct
  43 {
  44   int min,max;
  45   BOOL wrap;
  46 }
  47 buttons_simpleArrow;
  48
  49 /*
  50  * A function to handle the update of a slider.
  51  */
  52 typedef void (*buttons_sliderHandler)(dbox d,wimp_i i,int val,void *handle);
  53
  54 /*
  55  * void buttons_arrowClick
  56  * (
  57  *   dbox d,
  58  *   dbox_field f,
  59  *   int min,
  60  *   int max,
  61  *   int increment,
  62  *   BOOL wrap
  63  * )
  64  *
  65  * Use
  66  *  Increases (or decreases) the value in a writable box.  If the last event
  67  *  was a click with the adjust button, the increment is made negative (i.e.
  68  *  1 becomes -1, and -1 becomes 1), following the standard convention.  The
  69  *  value will not be allowed to exceed the limits passed.  If you don't
  70  *  want limits, make max and min the same.  Optionally, you can make the
  71  *  field's value 'wrap around' if it goes out of range.
  72  *
  73  * Parameters
  74  *  dbox d == the dbox handle
  75  *  dbox_field f == the field number
  76  *  int min == the lowest allowable value for the field
  77  *  int max == the highest allowable value for the field
  78  *  int increment == what to add to the value.  This may be negative.
  79  *  BOOL wrap == wrap around or not
  80  */
  81
  82 void buttons_arrowClick
  83 (
  84   dbox d,
  85   dbox_field f,
  86   int min,
  87   int max,
  88   int increment,
  89   BOOL wrap
  90 );
  91
  92 /*
  93  * void buttons_arrow(dbox d,
  94  *                    dbox_field f,
  95  *                    dbox wd,
  96  *                    dbox_field wf,
  97  *                    buttons_arrowProc p,
  98  *                    int diff,
  99  *                    void *handle)
 100  *
 101  * Use
 102  *  Handles a click on an arrow button.  It constrains the mouse pointer
 103  *  so it doesn't drift away annoyingly, and presses the icon in (by
 104  *  selecting it, so set up the sprites properly) while it's being clicked,
 105  *  with nary a flicker in sight.  It simulates auto-repeat on the button,
 106  *  so don't use real auto-repeat buttons.
 107  *
 108  * Parameters
 109  *  dbox d,dbox_field f == the icon that was clicked
 110  *  dbox wd,dbox_field wf == the (writable) icon that is passed to p
 111  *  buttons_arrowProc p == a procedure to call for each `click' on the
 112  *   button.  It may call buttons_arrowClick to bump the field.  If you pass
 113  *   0, a default function is called which just bumps the icon.  handle must
 114  *   point to a buttons_simpleArrow structure filled in correctly.
 115  *  int diff == the difference to add to the icon (passed to p).  The sign
 116  *   is toggled if the click was with the adjust button.
 117  *  void *handle == a handle to pass to p
 118  */
 119
 120 void buttons_arrow(dbox d,
 121                    dbox_field f,
 122                    dbox wd,
 123                    dbox_field wf,
 124                    buttons_arrowProc p,
 125                    int diff,
 126                    void *handle);
 127
 128 /*
 129  * BOOL buttons_insertChar(dbox d,int chcode,char min,char max)
 130  *
 131  * Use
 132  *  This function inserts the character specified into the writable field
 133  *  containing the caret.  Useful if you want to handle input yourself so
 134  *  you can update things (such as sliders) in deending on the input.  It
 135  *  will insure that the character is within the limits given (invalid
 136  *  limits will cause a default of 32-255 to be used).
 137  *
 138  * Parameters
 139  *  dbox d == dbox handle
 140  *  int chcode == the character, as returned from dbox_eventProcess().
 141  *  char min == minimum character allowable.
 142  *  char max == maximum character allowable.
 143  *
 144  * Returns
 145  *  Whether it inserted the character or not.
 146  */
 147
 148 BOOL buttons_insertChar(dbox d,int chcode,char min,char max);
 149
 150 /*
 151  * void buttons_redrawSlider
 152  * (
 153  *   dbox d,
 154  *   wimp_i i,
 155  *   int max,
 156  *   int val,
 157  *   int colour,
 158  *   BOOL isVertical
 159  * )
 160  *
 161  * Use
 162  *  Draws a slider in the specified icon
 163  *
 164  * Parameters
 165  *  dbox d == dbox handle
 166  *  wimp_i icon == the icon we're dealing with
 167  *  int max == the maximum value you want
 168  *  int val == the current value of the slider
 169  *  int colour == the WIMP colour for the slider
 170  *  BOOL isVertical == TRUE if the slider is vertical
 171  */
 172
 173 void buttons_redrawSlider
 174 (
 175   dbox d,
 176   wimp_i i,
 177   int max,
 178   int val,
 179   int colour,
 180   BOOL isVertical
 181 );
 182
 183 /*
 184  * void buttons_updateSlider
 185  * (
 186  *   dbox d,
 187  *   wimp_i i,
 188  *   int max,
 189  *   int val,
 190  *   int colour,
 191  *   BOOL isVertical
 192  * )
 193  *
 194  * Use
 195  *  Redraws a slider in the specified icon
 196  *
 197  * Parameters
 198  *  dbox d == dbox handle
 199  *  wimp_i icon == the icon we're dealing with
 200  *  int max == the maximum value you want
 201  *  int val == the current value of the slider
 202  *  int colour == the WIMP colour for the slider
 203  *  BOOL isVertical == TRUE if the slider is vertical
 204  */
 205
 206 void buttons_updateSlider
 207 (
 208   dbox d,
 209   wimp_i i,
 210   int max,
 211   int val,
 212   int colour,
 213   BOOL isVertical
 214 );
 215
 216 /*
 217  * void buttons_slideSlider
 218  * (
 219  *   dbox d,
 220  *   wimp_i i,
 221  *   int max,
 222  *   int *val,
 223  *   int colour,
 224  *   BOOL isVertical,
 225  *   buttons_sliderHandler proc,
 226  *   void *handle
 227  * )
 228  *
 229  * Use
 230  *  This routine just neatly handles the slider totally.  Just pass it the
 231  *  parameters it needs, and let it get on with it.
 232  *
 233  * Parameters
 234  *  dbox d == the dbox
 235  *  wimp_i i == the icon number
 236  *  int max == the maximum slider value
 237  *  int *val == a pointer to the slider value (updated as we go along)
 238  *  int colour == the colour for the slider
 239  *  BOOL isVertical == whether the slider is vertical
 240  *  buttons_sliderHandler proc == a slider handler, which can update, say a
 241  *   a writable field as the drag takes place
 242  *  void *handle == a handle to pass the routine
 243  */
 244
 245 void buttons_slideSlider
 246 (
 247   dbox d,
 248   wimp_i i,
 249   int max,
 250   int *val,
 251   int colour,
 252   BOOL isVertical,
 253   buttons_sliderHandler proc,
 254   void *handle
 255 );
 256
 257 /*
 258  * void buttons_redrawColourButton(dbox d,wimp_i i,buttons_colourstr *c)
 259  *
 260  * Use
 261  *  Redraws a true-colour button.
 262  *
 263  * Parameters
 264  *  dbox d == the dbox
 265  *  wimp_i i == icon number
 266  *  buttons_colourstr == the colour we're intersted in
 267  */
 268
 269 void buttons_redrawColourButton(dbox d,wimp_i i,wimp_paletteword c);
 270
 271 /*
 272  * buttons_updateColourButton(dbox d,wimp_i i,wimp_paletteword c)
 273  *
 274  * Use
 275  *  This routine redraws a colour button.
 276  *
 277  * Parameters
 278  *  dbox d ==  the dbox
 279  *  wimp_i == the icon number
 280  *  wimp_paletteword c == the colour number
 281  */
 282
 283 void buttons_updateColourButton(dbox d,wimp_i i,wimp_paletteword c);
 284
 285 #endif