Initial revision

[ssr] / StraySrc / Libraries / Steel / h / buttons

/*
 * Buttons
 *  provides handling for clever buttons and things.
 *
 * v. 1.00 (23 July 1991)
 *
 * © 1991-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __buttons_h
#define __buttons_h

#ifndef __wimp_h
#include "wimp.h"
#endif

#ifndef __dbox_h
#include "dbox.h"
#endif

typedef void (*buttons_arrowProc)(dbox d,dbox_field f,int diff,void *handle);

typedef struct
{
  int min,max;
  BOOL wrap;
}
buttons_simpleArrow;

/*
 * A function to handle the update of a slider.
 */
typedef void (*buttons_sliderHandler)(dbox d,wimp_i i,int val,void *handle);

/*
 * void buttons_arrowClick
 * (
 *   dbox d,
 *   dbox_field f,
 *   int min,
 *   int max,
 *   int increment,
 *   BOOL wrap
 * )
 *
 * Use
 *  Increases (or decreases) the value in a writable box.  If the last event
 *  was a click with the adjust button, the increment is made negative (i.e.
 *  1 becomes -1, and -1 becomes 1), following the standard convention.  The
 *  value will not be allowed to exceed the limits passed.  If you don't
 *  want limits, make max and min the same.  Optionally, you can make the
 *  field's value 'wrap around' if it goes out of range.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field number
 *  int min == the lowest allowable value for the field
 *  int max == the highest allowable value for the field
 *  int increment == what to add to the value.  This may be negative.
 *  BOOL wrap == wrap around or not
 */

void buttons_arrowClick
(
  dbox d,
  dbox_field f,
  int min,
  int max,
  int increment,
  BOOL wrap
);

/*
 * void buttons_arrow(dbox d,
 *                    dbox_field f,
 *                    dbox wd,
 *                    dbox_field wf,
 *                    buttons_arrowProc p,
 *                    int diff,
 *                    void *handle)
 *
 * Use
 *  Handles a click on an arrow button.  It constrains the mouse pointer
 *  so it doesn't drift away annoyingly, and presses the icon in (by
 *  selecting it, so set up the sprites properly) while it's being clicked,
 *  with nary a flicker in sight.  It simulates auto-repeat on the button,
 *  so don't use real auto-repeat buttons.
 *
 * Parameters
 *  dbox d,dbox_field f == the icon that was clicked
 *  dbox wd,dbox_field wf == the (writable) icon that is passed to p
 *  buttons_arrowProc p == a procedure to call for each `click' on the
 *   button.  It may call buttons_arrowClick to bump the field.  If you pass
 *   0, a default function is called which just bumps the icon.  handle must
 *   point to a buttons_simpleArrow structure filled in correctly.
 *  int diff == the difference to add to the icon (passed to p).  The sign
 *   is toggled if the click was with the adjust button.
 *  void *handle == a handle to pass to p
 */

void buttons_arrow(dbox d,
                   dbox_field f,
                   dbox wd,
                   dbox_field wf,
                   buttons_arrowProc p,
                   int diff,
                   void *handle);

/*
 * BOOL buttons_insertChar(dbox d,int chcode,char min,char max)
 *
 * Use
 *  This function inserts the character specified into the writable field
 *  containing the caret.  Useful if you want to handle input yourself so
 *  you can update things (such as sliders) in deending on the input.  It
 *  will insure that the character is within the limits given (invalid
 *  limits will cause a default of 32-255 to be used).
 *
 * Parameters
 *  dbox d == dbox handle
 *  int chcode == the character, as returned from dbox_eventProcess().
 *  char min == minimum character allowable.
 *  char max == maximum character allowable.
 *
 * Returns
 *  Whether it inserted the character or not.
 */

BOOL buttons_insertChar(dbox d,int chcode,char min,char max);

/*
 * void buttons_redrawSlider
 * (
 *   dbox d,
 *   wimp_i i,
 *   int max,
 *   int val,
 *   int colour,
 *   BOOL isVertical
 * )
 *
 * Use
 *  Draws a slider in the specified icon
 *
 * Parameters
 *  dbox d == dbox handle
 *  wimp_i icon == the icon we're dealing with
 *  int max == the maximum value you want
 *  int val == the current value of the slider
 *  int colour == the WIMP colour for the slider
 *  BOOL isVertical == TRUE if the slider is vertical
 */

void buttons_redrawSlider
(
  dbox d,
  wimp_i i,
  int max,
  int val,
  int colour,
  BOOL isVertical
);

/*
 * void buttons_updateSlider
 * (
 *   dbox d,
 *   wimp_i i,
 *   int max,
 *   int val,
 *   int colour,
 *   BOOL isVertical
 * )
 *
 * Use
 *  Redraws a slider in the specified icon
 *
 * Parameters
 *  dbox d == dbox handle
 *  wimp_i icon == the icon we're dealing with
 *  int max == the maximum value you want
 *  int val == the current value of the slider
 *  int colour == the WIMP colour for the slider
 *  BOOL isVertical == TRUE if the slider is vertical
 */

void buttons_updateSlider
(
  dbox d,
  wimp_i i,
  int max,
  int val,
  int colour,
  BOOL isVertical
);

/*
 * void buttons_slideSlider
 * (
 *   dbox d,
 *   wimp_i i,
 *   int max,
 *   int *val,
 *   int colour,
 *   BOOL isVertical,
 *   buttons_sliderHandler proc,
 *   void *handle
 * )
 *
 * Use
 *  This routine just neatly handles the slider totally.  Just pass it the
 *  parameters it needs, and let it get on with it.
 *
 * Parameters
 *  dbox d == the dbox
 *  wimp_i i == the icon number
 *  int max == the maximum slider value
 *  int *val == a pointer to the slider value (updated as we go along)
 *  int colour == the colour for the slider
 *  BOOL isVertical == whether the slider is vertical
 *  buttons_sliderHandler proc == a slider handler, which can update, say a
 *   a writable field as the drag takes place
 *  void *handle == a handle to pass the routine
 */

void buttons_slideSlider
(
  dbox d,
  wimp_i i,
  int max,
  int *val,
  int colour,
  BOOL isVertical,
  buttons_sliderHandler proc,
  void *handle
);

/*
 * void buttons_redrawColourButton(dbox d,wimp_i i,buttons_colourstr *c)
 *
 * Use
 *  Redraws a true-colour button.
 *
 * Parameters
 *  dbox d == the dbox
 *  wimp_i i == icon number
 *  buttons_colourstr == the colour we're intersted in
 */

void buttons_redrawColourButton(dbox d,wimp_i i,wimp_paletteword c);

/*
 * buttons_updateColourButton(dbox d,wimp_i i,wimp_paletteword c)
 *
 * Use
 *  This routine redraws a colour button.
 *
 * Parameters
 *  dbox d ==  the dbox
 *  wimp_i == the icon number
 *  wimp_paletteword c == the colour number
 */

void buttons_updateColourButton(dbox d,wimp_i i,wimp_paletteword c);

#endif