/*
 * dbox.h
 *  further dialogue box routines for Straylight apps
 *
 * 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.
 */

/*
 *
 * Conventions from the old C library supported by this one
 *
 *  1. Use of field 0 as default action button
 *
 * New conventions
 *
 *  1. Field 1 is Cancel action button (it is activated when Esc is pressed)
 *
 */

#ifndef __dbox_h
#define __dbox_h

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

#ifndef __event_h
#include "event.h"
#endif

typedef wimp_i dbox_field;
typedef struct dbox__dboxstr *dbox;
typedef void (*dbox_eventhandler)(dbox d,dbox_field clicked,void *handle);
typedef BOOL (*dbox_raweventhandler)(dbox d,wimp_eventstr *e,void *handle);

typedef enum
{
  dbox_RESETSTATE,
  dbox_SETSTATE,
  dbox_READSTATE,
  dbox_TOGGLESTATE
}
dbox_action;

typedef enum
{
  dbox_MENU_OVERPTR,              /* Menu dbox, opened over pointer        */
  dbox_STATIC_LASTPOS,            /* Static dbox, opened in last position  */
  dbox_MENU_LASTPOS,              /* Menu dbox, opened in last stored pos  */
  dbox_STATIC_OVERPTR,            /* Static dbox, opened over pointer      */
  dbox_MENU_CENTRE,               /* Menu dbox, centred on screen          */
  dbox_STATIC_CENTRE              /* Static dbox, centred on screen        */
}
dbox_openType;

#define dbox_CLOSE (dbox_field)-1
#define dbox_HELP (dbox_field)-2
#define dbox_ENDFILLIN (dbox_field)-3

/*----- Private external interfaces ---------------------------------------*
 *
 * Some parts of dbox are better left alone...
 */

#ifdef dbox__INTERNALS

typedef void (*dbox__mf)(int *x,int *y);
typedef BOOL (*dbox__esm)(void);
typedef void (*dbox__ddb)(wimp_openstr *o);
void dbox__rms(dbox__mf mf,dbox__esm esm,dbox__ddb ddb);

wimp_w dbox__menuDboxWindow(void);

#endif

/*-------------------------------------------------------------------------*/

/*
 * BOOL dbox_wasSubmenu(void)
 *
 * Use
 *  Returns whether the current menu hit was due to a submenu request or an
 *  actual Menu_Selection event.
 *
 * Returns
 *  TRUE if event was submenu warning
 *  FALSE otherwise
 *  Exits with error if neither (i.e. it was not called from a menu handler)
 */

#define dbox_wasSubmenu(x) (event_whyMenuEvent()==event_MENUSUBMENU)

/*
 * BOOL wasAdjustClick(void)
 *
 * Use
 *  Returns whether the last event was caused by a mouse click with the
 *  adjust mouse button.  Useful for deciding whether you want to bump a
 *  value up or down, or for keeping a dbox on-screen.
 *
 * Returns
 *  TRUE if the last event WAS caused by an adjust click.
 */

BOOL dbox_wasAdjustClick(void);

/*
 * dbox dbox_create(char *template)
 *
 * Use
 *  Creates a dbox from a template and returns a handle to it.  It calls
 *  werr() sensibly with nice messages if it failed.
 *
 * Parameters
 *  char *name == name of template to use
 *
 * Returns
 *  Abstract handle to dbox or NULL if the dbox could not be
 *  created
 */

dbox dbox_create(char *name);

/*
 * void dbox_display(dbox d,dbox_openType how)
 *
 * Use
 *  Displays a dbox on the screen.  The new dbox_openType is compatible with
 *  the old TRUE/FALSE system.  Note that is the event was a submenu, then
 *  the dbox will be opened as a submenu regardless of how you want it done.
 *
 *  If the dbox conatins a writable icon, then the caret is placed within
 *  the first one.  This is handled automatically by the WIMP for submenu
 *  dboxes, but not (unfortunately) for static ones.
 *
 * Parameters
 *  dbox d == dbox handle
 *  dbox_openType how == how you want the dbox opened
 */

void dbox_display(dbox d,dbox_openType how);

/*
 * void dbox_openDisplaced(dbox d)
 *
 * Use
 *  Displaces the dbox from its original height by the statutory 48 OS
 *  units.  If it would overlap the icon bar, it gets moved up to a sensible
 *  height.  The dbox must be opened by this call once only.  It must be
 *  closed using dbox_deleteNoUpdate().  The dbox is opened as a static
 *  dbox, of course.
 *
 * Parameters
 *  dbox d == the dbox
 */

void dbox_openDisplaced(dbox d);

/*
 * void dbox_hide(dbox d)
 *
 * Use
 *  Closes the dbox specified in whatever manner necessary to stop it being
 *  seen.  The window can still be created real easy.
 *
 * Parameters
 *  dbox d == dialogue box handle
 */

void dbox_hide(dbox d);

/*
 * void dbox_deleteNoUpdate(dbox d)
 *
 * Use
 *  Zaps a dbox without storing the thing's position away, so it reappears
 *  where you want it.
 *
 * Parameters
 *  dbox d == the handle
 */

void dbox_deleteNoUpdate(dbox d);

/*
 * void dbox_updatePosition(dbox d)
 *
 * Use
 *  Stores the position of the dialogue box away, so that next time a dbox
 *  using the same template is opened, it goes to that place.
 *
 * Parameters
 *  dbox d == the dbox handle
 */

void dbox_updatePosition(dbox d);

/*
 * void dbox_delete(dbox d)
 *
 * Use
 *  Utterly zaps the dialogue box specified.  Updates the template, so it's
 *  right next time around, though.  The window is deleted, and the dbox's
 *  space is freed.
 *
 * Parameters
 *  dbox d == dialogue box handle
 */

void dbox_delete(dbox d);

/*
 * void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle)
 *
 * Use
 *  This routine attaches an event handler to a dbox.  Pass 0 as the pointer
 *  to the procedure if you want to remove the handler. Event handers are an
 *  alternative to using dbox_fillin().
 *
 * Parameters
 *  dbox d == the dbox you want to attach a handler to.
 *  dbox_eventhandler proc == the hander procedure.
 *  void *handle == up to you.  It gets passed to the procedure, though.
 */

void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle);

/*
 * void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle)
 *
 * Use
 *  This routine attaches a raw event handler to a dbox.  Pass 0 as the
 *  pointer to the procedure if you want to remove the handler.  A raw event
 *  handler gets passed all the WIMP events received by the dbox.  It should
 *  return FALSE if it could not process the event itself, or TRUE if it
 *  did.
 *
 * Parameters
 *  dbox d == the dbox you want to attach a handler to.
 *  dbox_eventhandler proc == the hander procedure.
 *  void *handle == up to you.  It gets passed to the procedure, though.
 */

void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle);

/*
 * dbox_field dbox_fillin(dbox d)
 *
 * Use
 *  This is a nice simple way of handling a dbox.  It means you can handle
 *  everything from an in-line point of view. Functions can easily return
 *  the results they need (like dbox_query()).  Unfortunately, it will only
 *  work with menu dboxes, and will complain bitterly at you if you try and
 *  do anything different.
 *
 * Parameters
 *  dbox d == the dbox handle
 *
 * Returns
 *  The field number that was clicked.
 */

dbox_field dbox_fillin(dbox d);

/*
 * void dbox__eventProcess(void)
 *
 * Use
 *  Part of a private interface.  Do not use this function.
 */

void dbox__eventProcess(void);

/*
 * void dbox_eventProcess(void)
 *
 * Use
 *  Compatibility with old programs.
 */

#define dbox_eventProcess(x) event_process()

/*
 * void dbox_setfield(dbox d,dbox_field f,char *string,...)
 *
 * Use
 *  This routine will write the string into the field specified, if and only
 *  if the field's data is indirected.  No checking is performed whatsoever,
 *  though, so watch out!
 *
 * Parameters
 *  dbox d == the dbox
 *  dbox_field f == the field
 *  char *string == a printf-style format string
 */

void dbox_setfield(dbox d,dbox_field f,char *string,...);

/*
 * void dbox_clickicon(dbox d,dbox_field f)
 *
 * Use
 *  This routine neatly calls Interface, telling it to handle a click on the
 *  field specified.  The clicks are handled in a stack-like manner.
 *
 * Parameters
 *  dbox d == the dbox
 *  dbox_field f == the field
 */

void dbox_clickicon(dbox d,dbox_field f);

/*
 * void dbox_unclick(void)
 *
 * Use
 *  This routine declicks the last icon to be 'dbox_clickicon'ed.  If you
 *  intend to delete the dbox after the click, you should use code like
 *  this:
 *
 *    dbox_hide(d);
 *    dbox_unclick();
 *    dbox_delete(d);
 */

void dbox_unclick(void);

/*
 * void dbox_unclickAll(void)
 *
 * Use
 *  This call dbox_unclick()s all the 'dbox_clickicon'ed icons in the dbox.
 *  You shouldn't really need to use it.  It's mainly there for consistency
 *  with Straylight's WimpLib v. 3.00.
 */

void dbox_unclickAll(void);

/*
 * void dbox_getfield(dbox d,dbox_field f,char *buffer,int size)
 *
 * Use
 *  This is the same routine as in RISC_OSlib.  It returns the contents of
 *  the icon text in the buffer.
 */

void dbox_getfield(dbox d, dbox_field f, char *buffer, int size);

/*
 * void dbox_scanfield(dbox d,dbox_field f,char *format,...)
 *
 * Use
 *  Reads in scanf()-style the contents of a field.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field number
 *  char *format == a scanf() style format string
 */

void dbox_scanfield(dbox d,dbox_field f,char *format,...);

/*
 * BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a)
 *
 * Use
 *  This call will read the icon's state of selection and return it, and
 *  optionally alter it as specified in the dbox_action parameter.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field you're interested in
 *  dbox_action a == what you want to do with it
 */

BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a);

/*
 * BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a)
 *
 * Use
 *  This call will read the icon's state of shading and return it, and
 *  optionally alter it as specified in the dbox_action parameter.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field you're interested in
 *  dbox_action a == what you want to do with it
 */

BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a);

/*
 * wimp_w dbox_syshandle(dbox d)
 *
 * Use
 *  Returns the window handle used by the dbox specified, because your poor
 *  underprivileged code can't access my nice data structure.  This is for
 *  setting up things like calls to event_attachmenu and suchlike, which
 *  don't know about cunning things like dboxes.
 *
 * Parameters
 *  dbox d == the dbox you're interested in
 *
 * Returns
 *  The window handle, which is a wimp_w
 */

wimp_w dbox_syshandle(dbox d);

/*
 * int dbox_getNumeric(dbox d,dbox_field f)
 *
 * Use
 *  Reads an integer from a field.  If there is no semblance to a valid
 *  integer, 0 is returned.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field to read from
 */

int dbox_getNumeric(dbox d,dbox_field f);

/*
 * void dbox_setNumeric(dbox d,dbox_field f,int val)
 *
 * Use
 *  Writes the integer value specified into the field.
 *
 * Parameters
 *  dbox d == the dbox handle
 *  dbox_field f == the field to set
 *  int val == the integer value to write
 */

void dbox_setNumeric(dbox d,dbox_field f,int val);

/*
 * dbox_field dbox_helpField(void)
 *
 * Use
 *  Returns field number that Help is interested in.
 *
 * Returns
 *  Field number.
 */

dbox_field dbox_helpField(void);

/*
 * void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag)
 *
 * Use
 *  Gives the specified dialogue box an inbuilt title (in a group box, round
 *  the outside, as seen in Elite).  This is drawn automatically normally,
 *  but raw event handlers might want to do extra drawing, so the entry
 *  point to the redraw code is also supplied.
 *
 * Parameters
 *  dbox d == the dialogue box to do this to
 *  dbox_field icon == the icon around which the title is to be drawn
 *  BOOL moveDrag == allow a click on any of the dialogue box to move it
 */

void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag);

/*
 * void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle)
 *
 * Use
 *  Redraws an embedded title (as seen in Elite).  This is for the use of
 *  raw event handlers, which might want to do this sort of thing, because
 *  the redraw is normally handled automatically.
 *
 * Parameters
 *  wimp_redrawstr *r == the redraw information I need
 *  void *handle == a dbox, really.  This is for passing to wimpt_redraw.
 */

void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle);

/*
 * BOOL dbox_hasTitle(dbox d)
 *
 * Use
 *  Returns TRUE if the given dialogue box has a window title bar.
 *
 * Parameters
 *  dbox d == the dialogue box to check
 *
 * Returns
 *  TRUE if the dialogue box has a title bar
 */

BOOL dbox_hasTitle(dbox d);

#endif