Crawly Crypt Collection 2

home *** CD-ROM | disk | FTP | other *** search

/ Crawly Crypt Collection 2 / crawlyvol2.bin / program / c / fldlib93 / fldlib.doc next >

Wrap

Text File | 1994-05-21 | 16.1 KB | 494 lines

FLDLIB Floating dialogue library for Lattice C v0.93 beta (18/5/94) (C) 1994 M.J.Maisey Introduction ------------ FLDLIB was designed to be a very easy to use windowed dialog library which would integrate into existing programs with the minimum of hassle, and which would make writing simple applications which only use dialogs very quick. It will manage as many floating (windowed) dialogs as the AES or memory allows, and take care of all event handling for these wind- ows. The library has been written for use with Lattice C 5. Any port to another implementation of C will involve the writing of replacement wind_redraw and wind_title functions. Anyone wishing to distribute such a port should contact me first. General ------- Unless you are using the fld_do() call, you will be dealing with the floating dialogs via a unique handle which each will have. You will also have to change the structure of your program a little to re- flect the non-modality of the dialog system. All structures, function prototypes and defines are in fldlib.h. fldlib.o (the actual library) must be linked in to any programs us- ing it. In Lattice C 5.5 and above this is done by adding it to the 'input files' list in the project manager. I apologise for the use of the American 'dialog' throughout these docs and this library, but all GEM documentation I have seen uses this spelling! FLDLIB calls ------------ short fld_do(form, title) OBJECT *form; char *title; Manages a single form in a window. No other floating dialogs may be open. Returns: Index of clicked object OR FLDC_NONE if other dialogs already open or the close box on the dialog was clicked. 'tree' is a pointer to the resource tree to be managed. 'title' is the title of the window to be opened. Notes: This function is ideal for use by those who wish to manage a single floating dialog at a time, in a modal manner, as your application cannot respond to other GEM events while the dialog is open. No setup is required for the call (e.g. form_dial, form_center) as all setup is done for you, with the dialog being centred on the screen. The dialog is automatically closed before the call returns (e.g. when an object with EXIT or TOUCHEXIT flags set has been selected, or the close box has been clicked). To initialise close boxes, an fld_ability(FLDA_CLOSE) should be iss- ued before the fld_do(). ---------------------------------------------- short fld_open(form, centred, title, type) OBJECT *form; short centred, type; char *title; Opens a floating dialog. Returns: Handle of floating dialog OR -1 if problem 'form' is a pointer to the object tree to be managed. 'centred' indicates the of centreing to be done before opening FLDC_NONE Do not centre FLDC_SCREEN Centre on screen FLDC_MOUSE Centre on mouse pointer 'title' is the title of the window to be opened 'type' can be any short int. It is not used internally by FLDLIB, and is purely for the programmer's benefit. It will be ret- urned by the floating dialog management routines which may deal with more than one dialog. If assigned a unique value (typically the index of the resource tree), it can provide a clearer method than the handle for differentiating between different floating dialogs (see the examples for a demonst- ration of its use). Notes: This call opens a floating dialog for use with fld_domulti() or the fld_key()/fld_mouse()/fld_event combination. form_dial() et al are not required beforehand. If fld_open is called with a form parameter which points to the same OBJECT as an already open flying dialog, the existing dialog will be topped and its handle returned. ---------------------------------------------- void fld_close(fldhandle) short fldhandle; Close a floating dialog. 'fldhandle' is the handle of the floating dialog to be closed. Notes: This call closes a floating dialog. It is used with fld_domulti() or the fld_key/fld_mouse()/fld event combination. Note that dialogs do not have to be explicitly closed before program exit if fld_exit() is used. ---------------------------------------------- void fld_exit(void) Clean up before program exit. Notes: This call should be used directly before appl_exit(). It closes all open floating dialogs and frees the memory malloc'd by the library. ---------------------------------------------- short fld_domulti(type, fldhandle) short *type, *fldhandle; Manage multiple floating dialogs. Returns: Index of selected object OR The negative fldhandle of a closed fldhandle 'type' is filled in with the type of the floating dialog with the selected object 'fldhandle' is filled in with the handle of the floating dialog. Notes: This call manages multiple floating dialogs, which must be previous- ly opened with fld_open(). It is suitable for use in programs which only use floating dialog windows and do not do their own window management routines. Floating dialogs are *not* closed when an exit object is clicked on, although when fld_ability(FLDA_CLOSE) has been called to enable clo- ser gadgets, they may be closed by the library when a closer has been clicked on. In this case, a negative return code will be rec- ieved by the application. This code will be the negative of the fldhandle of the closed dialogue. ---------------------------------------------- short fld_key(kc, type, fldhandle) short kc, *type, *fldhandle; Respond to keypress from evnt_multi(). Returns: Index of selected object OR -1 if none selected. 'kc' is the keypress returned by evnt_multi() 'type' is filled in with the type of the floating dialog with the selected object 'fldhandle' is filled in with the handle of the floating dialog. Notes: This call is for use in programs which wish to utilise non-dialog windows as well as using floating dialogs. It should be used every time a MU_KEYBD event is received, and will check if any floating dialogs are topped and process the keypress. It will return -1 and fill in 'type' and 'fldhandle' if an object has been selected. Curr- ently, the only way this will arise is if a default exit button ex- ists on the dialog and <return> has been pressed. ---------------------------------------------- short fld_mouse(x, y, numclicks, type, fldhandle) short x, y, numclicks, *type, *fldhandle; Respond to button click event from evnt_multi(). Returns: Index of selected object OR -1 if none selected. 'x', 'y' and 'numclicks' are returned by evnt_multi() 'type' is filled in with the type of the floating dialog with the selected object 'fldhandle' is filled in with the handle of the floating dialog. Notes: This call is for use in programs which wish to utilise non-dialog windows as well as using floating dialogs. It should be used every time a MU_BUTTON event is received, and will check if any floating dialogs are topped and process the click. It will return -1 and fill in 'type' and 'fldhandle' if an object has been selected. ---------------------------------------------- short fld_mesag(msgbuf) short *msgbuf; Respond to message from evnt_multi(). Returns: FLDR_NONE or fldhandle of closed dialog 'msgbuf' is the message buffer filled in by evnt_multi(). Notes: This call is for use in programs which wish to utilise non-dialog windows as well as using floating dialogs. It should be used every time a MU_MESAG event is received. Applications which have called fld_ability(FLDA_CLOSE) should monit- or the return value to check whether dialog closer boxes have been clicked, as applications are responsible for taking their own action with closed dialogue boxes (typically this will just be to call fld_close()). It is recommended that closer clicks should be treated as a 'Cancel' rather than an 'OK'. ---------------------------------------------- void fld_draw(fldhandle, startobj, depth) short fldhandle; int startobj, int depth; Redraw floating dialog. 'fldhandle' is the handle of the dialog 'startobj' is the object to start drawing from 'depth' is the depth to draw to Notes: This call should be used as a replacement for an objc_draw after an object's attributes have been changed by the program. Object redraw- ing is handled by the library at all other times. objc_draw() should *never* be used to redraw floating dialogs. ---------------------------------------------- int fld_getwin(fldhandle) short fldhandle; Find window handle for a given floating dialog. Returns: AES window handle OR NULL if invalid handle 'fldhandle' is the handle for the dialog. Notes: This call provides an easier way to find the windowhandle of a dia- log than poking around in the FLD structures used internally by FLDLIB. ---------------------------------------------- OBJECT *fld_getform(fldhandle) short fldhandle; Find object tree for a given floating dialog. Returns: Pointer to object tree OR NULL if invalid handle 'fldhandle' is the handle for the dialog. Notes: This call provides an easier way to find the tree used by a float- ing dialog than poking around in the FLD structures used internally by FLDLIB. ---------------------------------------------- FLD *fld_getfld(fldhandle) short fldhandle; Find FLD structure for given handle Returns: Pointer to FLD structure OR NULL if invalid handle 'fldhandle' is the handle for the dialog. Notes: This call might be used to implement functions not included as part of the library - for example, changing the object tree for a given dialog, and is also used for patching in an addition redraw routine (see below). Changes to the contents of the FLD structure (particularly the next and fldhandle members) should be made with EXTREME CAUTION, as it is possible to crash the library by doing this. The FLD structure is defined in FLDLIB.H. ---------------------------------------------- FLD *fld_findtype(type) short type; Find FLD structure for given floating dialog type. Returns: Pointer to FLD structure OR NULL if type not found 'type' is the type of the dialog. Notes: This call will help you is you wish to check whether a dialog is op- en or not without tracking via fldhandles thoughout your program. If there are two or more open dialogs with the same type, the FLD structure for the first opened will be returned. ---------------------------------------------- FLD *fld_findform(form) short form; Find FLD structure for given object tree. Returns: Pointer to FLD structure OR NULL if object tree not found 'form' is the pointer to the object tree. Notes: This call will help you is you wish to check whether a dialog is op- en or not without tracking via fldhandles thoughout your program. ---------------------------------------------- void fld_ability(progability) int progability; Set ability of application to handle more advanced FLDLIB features. 'progability' a bitmask of the ability of the application. Currently the only defined values are FLDA_CLOSE indicating that closer boxes should be ena- bled. FLDA_ICON indicating that iconify boxes should be en- abled. and FLDA_NONE indicating no extra abilities. This value is a placeholder value. It is not currently necessary to explicitly call fld_ability as it is the default. Notes: FLDA_CLOSE alters the behaviour of the functions fld_open(), fld_do, fld_domulti() and fld_event(). The documentation for these functions should be consulted, as close box handling may need to be added to your source. FLDA_ICON does not require any additional handling in your source. Iconification is completely handled by the library This function is likely to be used in the future to enable other ad- ditions to FLDLIB. ---------------------------------------------- Adding a customised dialog redraw routine ----------------------------------------- (Advanced users) A technique that has been fairly widely used with modal dialog boxes is to just draw graphics other than those available as GEM objects straight over the dialog. This will not work with windowed dialogs, which may be pushed to the back and later require redrawing. It should be noted that to be totally solid, programs should imple- ment this type of graphic via G_USERDEF objects. However, the G_USERDEF system can be quite difficult to use, and hence FLDLIB provides an alternative method. Each object has an FLD structure associated, which may be obtained with fld_getfld(). The 'xredraw' member is a pointer to an addition- al redraw routine for the windowed dialog. Normally this is NULL (= no additional redraw), but can be set to a function to be called every time a redraw is required. This is done in the following man- ner. fld_getfld(fldhandle)->xredraw = custom_redraw; Where custom_redraw is a function of type: int custom_redraw(int windowhandle, GRECT *rect) { /* redraw code goes here */ return 1; } 'windowhandle' will be irrelevent to custom redraw routines 'rect' is the clipping rectangle for the redraw The redraw routine should always return 1, unless it wishes to abort the redraw. It will be called once for every rectangle that needs redrawing. Three external variables are set during redraws, and are: OBJECT *fld_tempform; /* Pointer to the object tree being drawn over */ int fld_tempstart; /* Start object for the redraw */ int fld_tempdepth; /* Depth of the redraw */ These are defined in fldlib.h. ------------------------------------------------------ I can be contacted by email at Martin_Maisey@standard.embassy.com (Internet) Martin Maisey @ 2:2501/101 (Fidonet) Martin Maisey @ 90:104/0.0 (NeST) Martin Maisey @ 100:107/6.0 (TurboNet) Martin Maisey @ 51:504/0.0 (AtariNet) Or by snail-mail at 384 Unthank Rd. Norwich Norfolk NR4 7QE ENGLAND Updates to the library will be made available via the normal file echos. Please report any bugs or suggestions to me ASAP. ---------------------------------------------- FLDLIB is freeware. It may be distributed under the following condi- tions: 1) No profit may be made from the distribution of FLDLIB. Any charge made must be no more than the cost of distribution. 2) The files FLDLIB.C, FLDLIB.O, FLDLIB.H and FLDLIB.DOC must all be present in the distribution. 3) The software is copyright, and modified versions may not be dis- tributed without the prior permission of the author. 4) The author may not be held responsible for any damage resulting directly or indirectly from the use of this software. 5) The freeware status of FLDLIB does not mean that any programs using FLDLIB (which distributed without FLDLIB documentation and with FLDLIB in binary form only) need necessarily be freeware. However, if such programs are to be distributed, FLDLIB must be credited either in the documentation or in the main program. If such programs are to be distributed to the profit of the author or any other party, a copy of the program must be sent to the author.