3 * further dialogue box routines for Straylight apps
5 * v. 1.00 (23 July 1991)
7 * © 1991-1998 Straylight
10 /*----- Licensing note ----------------------------------------------------*
12 * This file is part of Straylight's Steel library.
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)
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.
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.
31 * Conventions from the old C library supported by this one
33 * 1. Use of field 0 as default action button
37 * 1. Field 1 is Cancel action button (it is activated when Esc is pressed)
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);
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 */
77 #define dbox_CLOSE (dbox_field)-1
78 #define dbox_HELP (dbox_field)-2
79 #define dbox_ENDFILLIN (dbox_field)-3
81 /*----- Private external interfaces ---------------------------------------*
83 * Some parts of dbox are better left alone...
86 #ifdef dbox__INTERNALS
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);
93 wimp_w dbox__menuDboxWindow(void);
97 /*-------------------------------------------------------------------------*/
100 * BOOL dbox_wasSubmenu(void)
103 * Returns whether the current menu hit was due to a submenu request or an
104 * actual Menu_Selection event.
107 * TRUE if event was submenu warning
109 * Exits with error if neither (i.e. it was not called from a menu handler)
112 #define dbox_wasSubmenu(x) (event_whyMenuEvent()==event_MENUSUBMENU)
115 * BOOL wasAdjustClick(void)
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.
123 * TRUE if the last event WAS caused by an adjust click.
126 BOOL dbox_wasAdjustClick(void);
129 * dbox dbox_create(char *template)
132 * Creates a dbox from a template and returns a handle to it. It calls
133 * werr() sensibly with nice messages if it failed.
136 * char *name == name of template to use
139 * Abstract handle to dbox or NULL if the dbox could not be
143 dbox dbox_create(char *name);
146 * void dbox_display(dbox d,dbox_openType how)
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.
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.
158 * dbox d == dbox handle
159 * dbox_openType how == how you want the dbox opened
162 void dbox_display(dbox d,dbox_openType how);
165 * void dbox_openDisplaced(dbox d)
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
178 void dbox_openDisplaced(dbox d);
181 * void dbox_hide(dbox d)
184 * Closes the dbox specified in whatever manner necessary to stop it being
185 * seen. The window can still be created real easy.
188 * dbox d == dialogue box handle
191 void dbox_hide(dbox d);
194 * void dbox_deleteNoUpdate(dbox d)
197 * Zaps a dbox without storing the thing's position away, so it reappears
201 * dbox d == the handle
204 void dbox_deleteNoUpdate(dbox d);
207 * void dbox_updatePosition(dbox d)
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.
214 * dbox d == the dbox handle
217 void dbox_updatePosition(dbox d);
220 * void dbox_delete(dbox d)
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
228 * dbox d == dialogue box handle
231 void dbox_delete(dbox d);
234 * void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle)
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().
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.
247 void dbox_eventHandler(dbox d,dbox_eventhandler proc,void *handle);
250 * void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle)
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
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.
265 void dbox_rawEventHandler(dbox d,dbox_raweventhandler proc,void *handle);
268 * dbox_field dbox_fillin(dbox d)
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.
278 * dbox d == the dbox handle
281 * The field number that was clicked.
284 dbox_field dbox_fillin(dbox d);
287 * void dbox__eventProcess(void)
290 * Part of a private interface. Do not use this function.
293 void dbox__eventProcess(void);
296 * void dbox_eventProcess(void)
299 * Compatibility with old programs.
302 #define dbox_eventProcess(x) event_process()
305 * void dbox_setfield(dbox d,dbox_field f,char *string,...)
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!
314 * dbox_field f == the field
315 * char *string == a printf-style format string
318 void dbox_setfield(dbox d,dbox_field f,char *string,...);
321 * void dbox_clickicon(dbox d,dbox_field f)
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.
329 * dbox_field f == the field
332 void dbox_clickicon(dbox d,dbox_field f);
335 * void dbox_unclick(void)
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
347 void dbox_unclick(void);
350 * void dbox_unclickAll(void)
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.
358 void dbox_unclickAll(void);
361 * void dbox_getfield(dbox d,dbox_field f,char *buffer,int size)
364 * This is the same routine as in RISC_OSlib. It returns the contents of
365 * the icon text in the buffer.
368 void dbox_getfield(dbox d, dbox_field f, char *buffer, int size);
371 * void dbox_scanfield(dbox d,dbox_field f,char *format,...)
374 * Reads in scanf()-style the contents of a field.
377 * dbox d == the dbox handle
378 * dbox_field f == the field number
379 * char *format == a scanf() style format string
382 void dbox_scanfield(dbox d,dbox_field f,char *format,...);
385 * BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a)
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.
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
397 BOOL dbox_selecticon(dbox d,dbox_field f,dbox_action a);
400 * BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a)
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.
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
412 BOOL dbox_shadeicon(dbox d,dbox_field f,dbox_action a);
415 * wimp_w dbox_syshandle(dbox d)
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.
424 * dbox d == the dbox you're interested in
427 * The window handle, which is a wimp_w
430 wimp_w dbox_syshandle(dbox d);
433 * int dbox_getNumeric(dbox d,dbox_field f)
436 * Reads an integer from a field. If there is no semblance to a valid
437 * integer, 0 is returned.
440 * dbox d == the dbox handle
441 * dbox_field f == the field to read from
444 int dbox_getNumeric(dbox d,dbox_field f);
447 * void dbox_setNumeric(dbox d,dbox_field f,int val)
450 * Writes the integer value specified into the field.
453 * dbox d == the dbox handle
454 * dbox_field f == the field to set
455 * int val == the integer value to write
458 void dbox_setNumeric(dbox d,dbox_field f,int val);
461 * dbox_field dbox_helpField(void)
464 * Returns field number that Help is interested in.
470 dbox_field dbox_helpField(void);
473 * void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag)
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.
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
487 void dbox_setEmbeddedTitle(dbox d,dbox_field icon,BOOL moveDrag);
490 * void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle)
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.
498 * wimp_redrawstr *r == the redraw information I need
499 * void *handle == a dbox, really. This is for passing to wimpt_redraw.
502 void dbox_drawEmbeddedTitle(wimp_redrawstr *r,void *handle);
505 * BOOL dbox_hasTitle(dbox d)
508 * Returns TRUE if the given dialogue box has a window title bar.
511 * dbox d == the dialogue box to check
514 * TRUE if the dialogue box has a title bar
517 BOOL dbox_hasTitle(dbox d);