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

   1 /*
   2  * dbox.h
   3  *  further dialogue box routines for Straylight apps
   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 /*
  30  *
  31  * Conventions from the old C library supported by this one
  32  *
  33  *  1. Use of field 0 as default action button
  34  *
  35  * New conventions
  36  *
  37  *  1. Field 1 is Cancel action button (it is activated when Esc is pressed)
  38  *
  39  */
  40
  41 #ifndef __dbox_h
  42 #define __dbox_h
  43
  44 #ifndef __wimp_h
  45 #include "wimp.h"
  46 #endif
  47
  48 #ifndef __event_h
  49 #include "event.h"
  50 #endif
  51
  52 typedef wimp_i dbox_field;
  53 typedef struct dbox__dboxstr *dbox;
  54 typedef void (*dbox_eventhandler)(dbox d,dbox_field clicked,void *handle);
  55 typedef BOOL (*dbox_raweventhandler)(dbox d,wimp_eventstr *e,void *handle);
  56
  57 typedef enum
  58 {
  59   dbox_RESETSTATE,
  60   dbox_SETSTATE,
  61   dbox_READSTATE,
  62   dbox_TOGGLESTATE
  63 }
  64 dbox_action;
  65
  66 typedef enum
  67 {
  68   dbox_MENU_OVERPTR,              /* Menu dbox, opened over pointer        */
  69   dbox_STATIC_LASTPOS,            /* Static dbox, opened in last position  */
  70   dbox_MENU_LASTPOS,              /* Menu dbox, opened in last stored pos  */
  71   dbox_STATIC_OVERPTR,            /* Static dbox, opened over pointer      */
  72   dbox_MENU_CENTRE,               /* Menu dbox, centred on screen          */
  73   dbox_STATIC_CENTRE              /* Static dbox, centred on screen        */
  74 }
  75 dbox_openType;
  76
  77 #define dbox_CLOSE (dbox_field)-1
  78 #define dbox_HELP (dbox_field)-2
  79 #define dbox_ENDFILLIN (dbox_field)-3
  80
  81 /*----- Private external interfaces ---------------------------------------*
  82  *
  83  * Some parts of dbox are better left alone...
  84  */
  85
  86 #ifdef dbox__INTERNALS
  87
  88 typedef void (*dbox__mf)(int *x,int *y);
  89 typedef BOOL (*dbox__esm)(void);
  90 typedef void (*dbox__ddb)(wimp_openstr *o);
  91 void dbox__rms(dbox__mf mf,dbox__esm esm,dbox__ddb ddb);
  92
  93 wimp_w dbox__menuDboxWindow(void);
  94
  95 #endif
  96
  97 /*-------------------------------------------------------------------------*/
  98
  99 /*
 100  * BOOL dbox_wasSubmenu(void)
 101  *
 102  * Use
 103  *  Returns whether the current menu hit was due to a submenu request or an
 104  *  actual Menu_Selection event.
 105  *
 106  * Returns
 107  *  TRUE if event was submenu warning
 108  *  FALSE otherwise
 109  *  Exits with error if neither (i.e. it was not called from a menu handler)
 110  */
 111
 112 #define dbox_wasSubmenu(x) (event_whyMenuEvent()==event_MENUSUBMENU)
 113
 114 /*
 115  * BOOL wasAdjustClick(void)
 116  *
 117  * Use
 118  *  Returns whether the last event was caused by a mouse click with the
 119  *  adjust mouse button.  Useful for deciding whether you want to bump a
 120  *  value up or down, or for keeping a dbox on-screen.
 121  *
 122  * Returns
 123  *  TRUE if the last event WAS caused by an adjust click.
 124  */
 125
 126 BOOL dbox_wasAdjustClick(void);
 127
 128 /*
 129  * dbox dbox_create(char *template)
 130  *
 131  * Use
 132  *  Creates a dbox from a template and returns a handle to it.  It calls
 133  *  werr() sensibly with nice messages if it failed.
 134  *
 135  * Parameters
 136  *  char *name == name of template to use
 137  *
 138  * Returns
 139  *  Abstract handle to dbox or NULL if the dbox could not be
 140  *  created
 141  */
 142
 143 dbox dbox_create(char *name);
 144
 145 /*
 146  * void dbox_display(dbox d,dbox_openType how)
 147  *
 148  * Use
 149  *  Displays a dbox on the screen.  The new dbox_openType is compatible with
 150  *  the old TRUE/FALSE system.  Note that is the event was a submenu, then
 151  *  the dbox will be opened as a submenu regardless of how you want it done.
 152  *
 153  *  If the dbox conatins a writable icon, then the caret is placed within
 154  *  the first one.  This is handled automatically by the WIMP for submenu
 155  *  dboxes, but not (unfortunately) for static ones.
 156  *
 157  * Parameters
 158  *  dbox d == dbox handle
 159  *  dbox_openType how == how you want the dbox opened
 160  */
 161
 162 void dbox_display(dbox d,dbox_openType how);
 163
 164 /*
 165  * void dbox_openDisplaced(dbox d)
 166  *
 167  * Use
 168  *  Displaces the dbox from its original height by the statutory 48 OS
 169  *  units.  If it would overlap the icon bar, it gets moved up to a sensible
 170  *  height.  The dbox must be opened by this call once only.  It must be
 171  *  closed using dbox_deleteNoUpdate().  The dbox is opened as a static
 172  *  dbox, of course.
 173  *
 174  * Parameters
 175  *  dbox d == the dbox
 176  */
 177
 178 void dbox_openDisplaced(dbox d);
 179
 180 /*
 181  * void dbox_hide(dbox d)
 182  *
 183  * Use
 184  *  Closes the dbox specified in whatever manner necessary to stop it being
 185  *  seen.  The window can still be created real easy.
 186  *
 187  * Parameters
 188  *  dbox d == dialogue box handle
 189  */
 190
 191 void dbox_hide(dbox d);
 192
 193 /*
 194  * void dbox_deleteNoUpdate(dbox d)
 195  *
 196  * Use
 197  *  Zaps a dbox without storing the thing's position away, so it reappears
 198  *  where you want it.
 199  *
 200  * Parameters
 201  *  dbox d == the handle
 202  */
 203
 204 void dbox_deleteNoUpdate(dbox d);
 205
 206 /*
 207  * void dbox_updatePosition(dbox d)
 208  *
 209  * Use
 210  *  Stores the position of the dialogue box away, so that next time a dbox
 211  *  using the same template is opened, it goes to that place.
 212  *
 213  * Parameters
 214  *  dbox d == the dbox handle
 215  */
 216
 217 void dbox_updatePosition(dbox d);
 218
 219 /*
 220  * void dbox_delete(dbox d)
 221  *
 222  * Use
 223  *  Utterly zaps the dialogue box specified.  Updates the template, so it's
 224  *  right next time around, though.  The window is deleted, and the dbox's
 225  *  space is freed.
 226  *
 227  * Parameters
 228  *  dbox d == dialogue box handle
 229  */
 230
 231 void dbox_delete(dbox d);
 232
 233 /*
 234  * void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle)
 235  *
 236  * Use
 237  *  This routine attaches an event handler to a dbox.  Pass 0 as the pointer
 238  *  to the procedure if you want to remove the handler. Event handers are an
 239  *  alternative to using dbox_fillin().
 240  *
 241  * Parameters
 242  *  dbox d == the dbox you want to attach a handler to.
 243  *  dbox_eventhandler proc == the hander procedure.
 244  *  void *handle == up to you.  It gets passed to the procedure, though.
 245  */
 246
 247 void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle);
 248
 249 /*
 250  * void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle)
 251  *
 252  * Use
 253  *  This routine attaches a raw event handler to a dbox.  Pass 0 as the
 254  *  pointer to the procedure if you want to remove the handler.  A raw event
 255  *  handler gets passed all the WIMP events received by the dbox.  It should
 256  *  return FALSE if it could not process the event itself, or TRUE if it
 257  *  did.
 258  *
 259  * Parameters
 260  *  dbox d == the dbox you want to attach a handler to.
 261  *  dbox_eventhandler proc == the hander procedure.
 262  *  void *handle == up to you.  It gets passed to the procedure, though.
 263  */
 264
 265 void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle);
 266
 267 /*
 268  * dbox_field dbox_fillin(dbox d)
 269  *
 270  * Use
 271  *  This is a nice simple way of handling a dbox.  It means you can handle
 272  *  everything from an in-line point of view. Functions can easily return
 273  *  the results they need (like dbox_query()).  Unfortunately, it will only
 274  *  work with menu dboxes, and will complain bitterly at you if you try and
 275  *  do anything different.
 276  *
 277  * Parameters
 278  *  dbox d == the dbox handle
 279  *
 280  * Returns
 281  *  The field number that was clicked.
 282  */
 283
 284 dbox_field dbox_fillin(dbox d);
 285
 286 /*
 287  * void dbox__eventProcess(void)
 288  *
 289  * Use
 290  *  Part of a private interface.  Do not use this function.
 291  */
 292
 293 void dbox__eventProcess(void);
 294
 295 /*
 296  * void dbox_eventProcess(void)
 297  *
 298  * Use
 299  *  Compatibility with old programs.
 300  */
 301
 302 #define dbox_eventProcess(x) event_process()
 303
 304 /*
 305  * void dbox_setfield(dbox d,dbox_field f,char *string,...)
 306  *
 307  * Use
 308  *  This routine will write the string into the field specified, if and only
 309  *  if the field's data is indirected.  No checking is performed whatsoever,
 310  *  though, so watch out!
 311  *
 312  * Parameters
 313  *  dbox d == the dbox
 314  *  dbox_field f == the field
 315  *  char *string == a printf-style format string
 316  */
 317
 318 void dbox_setfield(dbox d,dbox_field f,char *string,...);
 319
 320 /*
 321  * void dbox_clickicon(dbox d,dbox_field f)
 322  *
 323  * Use
 324  *  This routine neatly calls Interface, telling it to handle a click on the
 325  *  field specified.  The clicks are handled in a stack-like manner.
 326  *
 327  * Parameters
 328  *  dbox d == the dbox
 329  *  dbox_field f == the field
 330  */
 331
 332 void dbox_clickicon(dbox d,dbox_field f);
 333
 334 /*
 335  * void dbox_unclick(void)
 336  *
 337  * Use
 338  *  This routine declicks the last icon to be 'dbox_clickicon'ed.  If you
 339  *  intend to delete the dbox after the click, you should use code like
 340  *  this:
 341  *
 342  *    dbox_hide(d);
 343  *    dbox_unclick();
 344  *    dbox_delete(d);
 345  */
 346
 347 void dbox_unclick(void);
 348
 349 /*
 350  * void dbox_unclickAll(void)
 351  *
 352  * Use
 353  *  This call dbox_unclick()s all the 'dbox_clickicon'ed icons in the dbox.
 354  *  You shouldn't really need to use it.  It's mainly there for consistency
 355  *  with Straylight's WimpLib v. 3.00.
 356  */
 357
 358 void dbox_unclickAll(void);
 359
 360 /*
 361  * void dbox_getfield(dbox d,dbox_field f,char *buffer,int size)
 362  *
 363  * Use
 364  *  This is the same routine as in RISC_OSlib.  It returns the contents of
 365  *  the icon text in the buffer.
 366  */
 367
 368 void dbox_getfield(dbox d, dbox_field f, char *buffer, int size);
 369
 370 /*
 371  * void dbox_scanfield(dbox d,dbox_field f,char *format,...)
 372  *
 373  * Use
 374  *  Reads in scanf()-style the contents of a field.
 375  *
 376  * Parameters
 377  *  dbox d == the dbox handle
 378  *  dbox_field f == the field number
 379  *  char *format == a scanf() style format string
 380  */
 381
 382 void dbox_scanfield(dbox d,dbox_field f,char *format,...);
 383
 384 /*
 385  * BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a)
 386  *
 387  * Use
 388  *  This call will read the icon's state of selection and return it, and
 389  *  optionally alter it as specified in the dbox_action parameter.
 390  *
 391  * Parameters
 392  *  dbox d == the dbox handle
 393  *  dbox_field f == the field you're interested in
 394  *  dbox_action a == what you want to do with it
 395  */
 396
 397 BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a);
 398
 399 /*
 400  * BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a)
 401  *
 402  * Use
 403  *  This call will read the icon's state of shading and return it, and
 404  *  optionally alter it as specified in the dbox_action parameter.
 405  *
 406  * Parameters
 407  *  dbox d == the dbox handle
 408  *  dbox_field f == the field you're interested in
 409  *  dbox_action a == what you want to do with it
 410  */
 411
 412 BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a);
 413
 414 /*
 415  * wimp_w dbox_syshandle(dbox d)
 416  *
 417  * Use
 418  *  Returns the window handle used by the dbox specified, because your poor
 419  *  underprivileged code can't access my nice data structure.  This is for
 420  *  setting up things like calls to event_attachmenu and suchlike, which
 421  *  don't know about cunning things like dboxes.
 422  *
 423  * Parameters
 424  *  dbox d == the dbox you're interested in
 425  *
 426  * Returns
 427  *  The window handle, which is a wimp_w
 428  */
 429
 430 wimp_w dbox_syshandle(dbox d);
 431
 432 /*
 433  * int dbox_getNumeric(dbox d,dbox_field f)
 434  *
 435  * Use
 436  *  Reads an integer from a field.  If there is no semblance to a valid
 437  *  integer, 0 is returned.
 438  *
 439  * Parameters
 440  *  dbox d == the dbox handle
 441  *  dbox_field f == the field to read from
 442  */
 443
 444 int dbox_getNumeric(dbox d,dbox_field f);
 445
 446 /*
 447  * void dbox_setNumeric(dbox d,dbox_field f,int val)
 448  *
 449  * Use
 450  *  Writes the integer value specified into the field.
 451  *
 452  * Parameters
 453  *  dbox d == the dbox handle
 454  *  dbox_field f == the field to set
 455  *  int val == the integer value to write
 456  */
 457
 458 void dbox_setNumeric(dbox d,dbox_field f,int val);
 459
 460 /*
 461  * dbox_field dbox_helpField(void)
 462  *
 463  * Use
 464  *  Returns field number that Help is interested in.
 465  *
 466  * Returns
 467  *  Field number.
 468  */
 469
 470 dbox_field dbox_helpField(void);
 471
 472 /*
 473  * void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag)
 474  *
 475  * Use
 476  *  Gives the specified dialogue box an inbuilt title (in a group box, round
 477  *  the outside, as seen in Elite).  This is drawn automatically normally,
 478  *  but raw event handlers might want to do extra drawing, so the entry
 479  *  point to the redraw code is also supplied.
 480  *
 481  * Parameters
 482  *  dbox d == the dialogue box to do this to
 483  *  dbox_field icon == the icon around which the title is to be drawn
 484  *  BOOL moveDrag == allow a click on any of the dialogue box to move it
 485  */
 486
 487 void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag);
 488
 489 /*
 490  * void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle)
 491  *
 492  * Use
 493  *  Redraws an embedded title (as seen in Elite).  This is for the use of
 494  *  raw event handlers, which might want to do this sort of thing, because
 495  *  the redraw is normally handled automatically.
 496  *
 497  * Parameters
 498  *  wimp_redrawstr *r == the redraw information I need
 499  *  void *handle == a dbox, really.  This is for passing to wimpt_redraw.
 500  */
 501
 502 void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle);
 503
 504 /*
 505  * BOOL dbox_hasTitle(dbox d)
 506  *
 507  * Use
 508  *  Returns TRUE if the given dialogue box has a window title bar.
 509  *
 510  * Parameters
 511  *  dbox d == the dialogue box to check
 512  *
 513  * Returns
 514  *  TRUE if the dialogue box has a title bar
 515  */
 516
 517 BOOL dbox_hasTitle(dbox d);
 518
 519 #endif