+++ /dev/null
-/*\r
- * Exports and types from dialog.c.\r
- */\r
-\r
-/*\r
- * This will come in handy for generic control handlers. Anyone\r
- * knows how to make this more portable, let me know :-)\r
- */\r
-#define ATOFFSET(data, offset) ( (void *) ( (char *)(data) + (offset) ) )\r
-\r
-/*\r
- * This is the big union which defines a single control, of any\r
- * type.\r
- * \r
- * General principles:\r
- * - _All_ pointers in this structure are expected to point to\r
- * dynamically allocated things, unless otherwise indicated.\r
- * - `char' fields giving keyboard shortcuts are expected to be\r
- * NO_SHORTCUT if no shortcut is desired for a particular control.\r
- * - The `label' field can often be NULL, which will cause the\r
- * control to not have a label at all. This doesn't apply to\r
- * checkboxes and push buttons, in which the label is not\r
- * separate from the control.\r
- */\r
-\r
-#define NO_SHORTCUT '\0'\r
-\r
-enum {\r
- CTRL_TEXT, /* just a static line of text */\r
- CTRL_EDITBOX, /* label plus edit box */\r
- CTRL_RADIO, /* label plus radio buttons */\r
- CTRL_CHECKBOX, /* checkbox (contains own label) */\r
- CTRL_BUTTON, /* simple push button (no label) */\r
- CTRL_LISTBOX, /* label plus list box */\r
- CTRL_COLUMNS, /* divide window into columns */\r
- CTRL_FILESELECT, /* label plus filename selector */\r
- CTRL_FONTSELECT, /* label plus font selector */\r
- CTRL_TABDELAY /* see `tabdelay' below */\r
-};\r
-\r
-/*\r
- * Many controls have `intorptr' unions for storing user data,\r
- * since the user might reasonably want to store either an integer\r
- * or a void * pointer. Here I define a union, and two convenience\r
- * functions to create that union from actual integers or pointers.\r
- * \r
- * The convenience functions are declared as inline if possible.\r
- * Otherwise, they're declared here and defined when this header is\r
- * included with DEFINE_INTORPTR_FNS defined. This is a total pain,\r
- * but such is life.\r
- */\r
-typedef union { void *p; int i; } intorptr;\r
-\r
-#ifndef INLINE\r
-intorptr I(int i);\r
-intorptr P(void *p);\r
-#endif\r
-\r
-#if defined DEFINE_INTORPTR_FNS || defined INLINE\r
-#ifdef INLINE\r
-#define PREFIX INLINE\r
-#else\r
-#define PREFIX\r
-#endif\r
-PREFIX intorptr I(int i) { intorptr ret; ret.i = i; return ret; }\r
-PREFIX intorptr P(void *p) { intorptr ret; ret.p = p; return ret; }\r
-#undef PREFIX\r
-#endif\r
-\r
-/*\r
- * Each control has an `int' field specifying which columns it\r
- * occupies in a multi-column part of the dialog box. These macros\r
- * pack and unpack that field.\r
- * \r
- * If a control belongs in exactly one column, just specifying the\r
- * column number is perfectly adequate.\r
- */\r
-#define COLUMN_FIELD(start, span) ( (((span)-1) << 16) + (start) )\r
-#define COLUMN_START(field) ( (field) & 0xFFFF )\r
-#define COLUMN_SPAN(field) ( (((field) >> 16) & 0xFFFF) + 1 )\r
-\r
-union control;\r
-\r
-/*\r
- * The number of event types is being deliberately kept small, on\r
- * the grounds that not all platforms might be able to report a\r
- * large number of subtle events. We have:\r
- * - the special REFRESH event, called when a control's value\r
- * needs setting\r
- * - the ACTION event, called when the user does something that\r
- * positively requests action (double-clicking a list box item,\r
- * or pushing a push-button)\r
- * - the VALCHANGE event, called when the user alters the setting\r
- * of the control in a way that is usually considered to alter\r
- * the underlying data (toggling a checkbox or radio button,\r
- * moving the items around in a drag-list, editing an edit\r
- * control)\r
- * - the SELCHANGE event, called when the user alters the setting\r
- * of the control in a more minor way (changing the selected\r
- * item in a list box).\r
- * - the CALLBACK event, which happens after the handler routine\r
- * has requested a subdialog (file selector, font selector,\r
- * colour selector) and it has come back with information.\r
- */\r
-enum {\r
- EVENT_REFRESH,\r
- EVENT_ACTION,\r
- EVENT_VALCHANGE,\r
- EVENT_SELCHANGE,\r
- EVENT_CALLBACK\r
-};\r
-typedef void (*handler_fn)(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-\r
-#define STANDARD_PREFIX \\r
- int type; \\r
- char *label; \\r
- int tabdelay; \\r
- int column; \\r
- handler_fn handler; \\r
- intorptr context; \\r
- intorptr helpctx\r
-\r
-union control {\r
- /*\r
- * The first possibility in this union is the generic header\r
- * shared by all the structures, which we are therefore allowed\r
- * to access through any one of them.\r
- */\r
- struct {\r
- int type;\r
- /*\r
- * Every control except CTRL_COLUMNS has _some_ sort of\r
- * label. By putting it in the `generic' union as well as\r
- * everywhere else, we avoid having to have an irritating\r
- * switch statement when we go through and deallocate all\r
- * the memory in a config-box structure.\r
- * \r
- * Yes, this does mean that any non-NULL value in this\r
- * field is expected to be dynamically allocated and\r
- * freeable.\r
- * \r
- * For CTRL_COLUMNS, this field MUST be NULL.\r
- */\r
- char *label;\r
- /*\r
- * If `tabdelay' is non-zero, it indicates that this\r
- * particular control should not yet appear in the tab\r
- * order. A subsequent CTRL_TABDELAY entry will place it.\r
- */\r
- int tabdelay;\r
- /*\r
- * Indicate which column(s) this control occupies. This can\r
- * be unpacked into starting column and column span by the\r
- * COLUMN macros above.\r
- */\r
- int column;\r
- /*\r
- * Most controls need to provide a function which gets\r
- * called when that control's setting is changed, or when\r
- * the control's setting needs initialising.\r
- * \r
- * The `data' parameter points to the writable data being\r
- * modified as a result of the configuration activity; for\r
- * example, the PuTTY `Config' structure, although not\r
- * necessarily.\r
- * \r
- * The `dlg' parameter is passed back to the platform-\r
- * specific routines to read and write the actual control\r
- * state.\r
- */\r
- handler_fn handler;\r
- /*\r
- * Almost all of the above functions will find it useful to\r
- * be able to store a piece of `void *' or `int' data.\r
- */\r
- intorptr context;\r
- /*\r
- * For any control, we also allow the storage of a piece of\r
- * data for use by context-sensitive help. For example, on\r
- * Windows you can click the magic question mark and then\r
- * click a control, and help for that control should spring\r
- * up. Hence, here is a slot in which to store per-control\r
- * data that a particular platform-specific driver can use\r
- * to ensure it brings up the right piece of help text.\r
- */\r
- intorptr helpctx;\r
- } generic;\r
- struct {\r
- STANDARD_PREFIX;\r
- union control *ctrl;\r
- } tabdelay;\r
- struct {\r
- STANDARD_PREFIX;\r
- } text;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut; /* keyboard shortcut */\r
- /*\r
- * Percentage of the dialog-box width used by the edit box.\r
- * If this is set to 100, the label is on its own line;\r
- * otherwise the label is on the same line as the box\r
- * itself.\r
- */\r
- int percentwidth;\r
- int password; /* details of input are hidden */\r
- /*\r
- * A special case of the edit box is the combo box, which\r
- * has a drop-down list built in. (Note that a _non_-\r
- * editable drop-down list is done as a special case of a\r
- * list box.)\r
- * \r
- * Don't try setting has_list and password on the same\r
- * control; front ends are not required to support that\r
- * combination.\r
- */\r
- int has_list;\r
- /*\r
- * Edit boxes tend to need two items of context, so here's\r
- * a spare.\r
- */\r
- intorptr context2;\r
- } editbox;\r
- struct {\r
- STANDARD_PREFIX;\r
- /*\r
- * `shortcut' here is a single keyboard shortcut which is\r
- * expected to select the whole group of radio buttons. It\r
- * can be NO_SHORTCUT if required, and there is also a way\r
- * to place individual shortcuts on each button; see below.\r
- */\r
- char shortcut;\r
- /*\r
- * There are separate fields for `ncolumns' and `nbuttons'\r
- * for several reasons.\r
- * \r
- * Firstly, we sometimes want the last of a set of buttons\r
- * to have a longer label than the rest; we achieve this by\r
- * setting `ncolumns' higher than `nbuttons', and the\r
- * layout code is expected to understand that the final\r
- * button should be given all the remaining space on the\r
- * line. This sounds like a ludicrously specific special\r
- * case (if we're doing this sort of thing, why not have\r
- * the general ability to have a particular button span\r
- * more than one column whether it's the last one or not?)\r
- * but actually it's reasonably common for the sort of\r
- * three-way control you get a lot of in PuTTY: `yes'\r
- * versus `no' versus `some more complex way to decide'.\r
- * \r
- * Secondly, setting `nbuttons' higher than `ncolumns' lets\r
- * us have more than one line of radio buttons for a single\r
- * setting. A very important special case of this is\r
- * setting `ncolumns' to 1, so that each button is on its\r
- * own line.\r
- */\r
- int ncolumns;\r
- int nbuttons;\r
- /*\r
- * This points to a dynamically allocated array of `char *'\r
- * pointers, each of which points to a dynamically\r
- * allocated string.\r
- */\r
- char **buttons; /* `nbuttons' button labels */\r
- /*\r
- * This points to a dynamically allocated array of `char'\r
- * giving the individual keyboard shortcuts for each radio\r
- * button. The array may be NULL if none are required.\r
- */\r
- char *shortcuts; /* `nbuttons' shortcuts; may be NULL */\r
- /*\r
- * This points to a dynamically allocated array of\r
- * intorptr, giving helpful data for each button.\r
- */\r
- intorptr *buttondata; /* `nbuttons' entries; may be NULL */\r
- } radio;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut;\r
- } checkbox;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut;\r
- /*\r
- * At least Windows has the concept of a `default push\r
- * button', which gets implicitly pressed when you hit\r
- * Return even if it doesn't have the input focus.\r
- */\r
- int isdefault;\r
- /*\r
- * Also, the reverse of this: a default cancel-type button,\r
- * which is implicitly pressed when you hit Escape.\r
- */\r
- int iscancel;\r
- } button;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut; /* keyboard shortcut */\r
- /*\r
- * Height of the list box, in approximate number of lines.\r
- * If this is zero, the list is a drop-down list.\r
- */\r
- int height; /* height in lines */\r
- /*\r
- * If this is set, the list elements can be reordered by\r
- * the user (by drag-and-drop or by Up and Down buttons,\r
- * whatever the per-platform implementation feels\r
- * comfortable with). This is not guaranteed to work on a\r
- * drop-down list, so don't try it!\r
- */\r
- int draglist;\r
- /*\r
- * If this is non-zero, the list can have more than one\r
- * element selected at a time. This is not guaranteed to\r
- * work on a drop-down list, so don't try it!\r
- * \r
- * Different non-zero values request slightly different\r
- * types of multi-selection (this may well be meaningful\r
- * only in GTK, so everyone else can ignore it if they\r
- * want). 1 means the list box expects to have individual\r
- * items selected, whereas 2 means it expects the user to\r
- * want to select a large contiguous range at a time.\r
- */\r
- int multisel;\r
- /*\r
- * Percentage of the dialog-box width used by the list box.\r
- * If this is set to 100, the label is on its own line;\r
- * otherwise the label is on the same line as the box\r
- * itself. Setting this to anything other than 100 is not\r
- * guaranteed to work on a _non_-drop-down list, so don't\r
- * try it!\r
- */\r
- int percentwidth;\r
- /*\r
- * Some list boxes contain strings that contain tab\r
- * characters. If `ncols' is greater than 0, then\r
- * `percentages' is expected to be non-zero and to contain\r
- * the respective widths of `ncols' columns, which together\r
- * will exactly fit the width of the list box. Otherwise\r
- * `percentages' must be NULL.\r
- * \r
- * There should never be more than one column in a\r
- * drop-down list (one with height==0), because front ends\r
- * may have to implement it as a special case of an\r
- * editable combo box.\r
- */\r
- int ncols; /* number of columns */\r
- int *percentages; /* % width of each column */\r
- } listbox;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut;\r
- /*\r
- * `filter' dictates what type of files will be selected by\r
- * default; for example, when selecting private key files\r
- * the file selector would do well to only show .PPK files\r
- * (on those systems where this is the chosen extension).\r
- * \r
- * The precise contents of `filter' are platform-defined,\r
- * unfortunately. The special value NULL means `all files'\r
- * and is always a valid fallback.\r
- * \r
- * Unlike almost all strings in this structure, this value\r
- * is NOT expected to require freeing (although of course\r
- * you can always use ctrl_alloc if you do need to create\r
- * one on the fly). This is because the likely mode of use\r
- * is to define string constants in a platform-specific\r
- * header file, and directly reference those. Or worse, a\r
- * particular platform might choose to cast integers into\r
- * this pointer type...\r
- */\r
- char const *filter;\r
- /*\r
- * Some systems like to know whether a file selector is\r
- * choosing a file to read or one to write (and possibly\r
- * create).\r
- */\r
- int for_writing;\r
- /*\r
- * On at least some platforms, the file selector is a\r
- * separate dialog box, and contains a user-settable title.\r
- * \r
- * This value _is_ expected to require freeing.\r
- */\r
- char *title;\r
- } fileselect;\r
- struct {\r
- /* In this variant, `label' MUST be NULL. */\r
- STANDARD_PREFIX;\r
- int ncols; /* number of columns */\r
- int *percentages; /* % width of each column */\r
- /*\r
- * Every time this control type appears, exactly one of\r
- * `ncols' and the previous number of columns MUST be one.\r
- * Attempting to allow a seamless transition from a four-\r
- * to a five-column layout, for example, would be way more\r
- * trouble than it was worth. If you must lay things out\r
- * like that, define eight unevenly sized columns and use\r
- * column-spanning a lot. But better still, just don't.\r
- * \r
- * `percentages' may be NULL if ncols==1, to save space.\r
- */\r
- } columns;\r
- struct {\r
- STANDARD_PREFIX;\r
- char shortcut;\r
- } fontselect;\r
-};\r
-\r
-#undef STANDARD_PREFIX\r
-\r
-/*\r
- * `controlset' is a container holding an array of `union control'\r
- * structures, together with a panel name and a title for the whole\r
- * set. In Windows and any similar-looking GUI, each `controlset'\r
- * in the config will be a container box within a panel.\r
- * \r
- * Special case: if `boxname' is NULL, the control set gives an\r
- * overall title for an entire panel of controls.\r
- */\r
-struct controlset {\r
- char *pathname; /* panel path, e.g. "SSH/Tunnels" */\r
- char *boxname; /* internal short name of controlset */\r
- char *boxtitle; /* title of container box */\r
- int ncolumns; /* current no. of columns at bottom */\r
- int ncontrols; /* number of `union control' in array */\r
- int ctrlsize; /* allocated size of array */\r
- union control **ctrls; /* actual array */\r
-};\r
-\r
-/*\r
- * This is the container structure which holds a complete set of\r
- * controls.\r
- */\r
-struct controlbox {\r
- int nctrlsets; /* number of ctrlsets */\r
- int ctrlsetsize; /* ctrlset size */\r
- struct controlset **ctrlsets; /* actual array of ctrlsets */\r
- int nfrees;\r
- int freesize;\r
- void **frees; /* array of aux data areas to free */\r
-};\r
-\r
-struct controlbox *ctrl_new_box(void);\r
-void ctrl_free_box(struct controlbox *);\r
-\r
-/*\r
- * Standard functions used for populating a controlbox structure.\r
- */\r
-\r
-/* Set up a panel title. */\r
-struct controlset *ctrl_settitle(struct controlbox *,\r
- char *path, char *title);\r
-/* Retrieve a pointer to a controlset, creating it if absent. */\r
-struct controlset *ctrl_getset(struct controlbox *,\r
- char *path, char *name, char *boxtitle);\r
-void ctrl_free_set(struct controlset *);\r
-\r
-void ctrl_free(union control *);\r
-\r
-/*\r
- * This function works like `malloc', but the memory it returns\r
- * will be automatically freed when the controlbox is freed. Note\r
- * that a controlbox is a dialog-box _template_, not an instance,\r
- * and so data allocated through this function is better not used\r
- * to hold modifiable per-instance things. It's mostly here for\r
- * allocating structures to be passed as control handler params.\r
- */\r
-void *ctrl_alloc(struct controlbox *b, size_t size);\r
-\r
-/*\r
- * Individual routines to create `union control' structures in a controlset.\r
- * \r
- * Most of these routines allow the most common fields to be set\r
- * directly, and put default values in the rest. Each one returns a\r
- * pointer to the `union control' it created, so that final tweaks\r
- * can be made.\r
- */\r
-\r
-/* `ncolumns' is followed by that many percentages, as integers. */\r
-union control *ctrl_columns(struct controlset *, int ncolumns, ...);\r
-union control *ctrl_editbox(struct controlset *, char *label, char shortcut,\r
- int percentage, intorptr helpctx,\r
- handler_fn handler,\r
- intorptr context, intorptr context2);\r
-union control *ctrl_combobox(struct controlset *, char *label, char shortcut,\r
- int percentage, intorptr helpctx,\r
- handler_fn handler,\r
- intorptr context, intorptr context2);\r
-/*\r
- * `ncolumns' is followed by (alternately) radio button titles and\r
- * intorptrs, until a NULL in place of a title string is seen. Each\r
- * title is expected to be followed by a shortcut _iff_ `shortcut'\r
- * is NO_SHORTCUT.\r
- */\r
-union control *ctrl_radiobuttons(struct controlset *, char *label,\r
- char shortcut, int ncolumns,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context, ...);\r
-union control *ctrl_pushbutton(struct controlset *,char *label,char shortcut,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_listbox(struct controlset *,char *label,char shortcut,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_droplist(struct controlset *, char *label, char shortcut,\r
- int percentage, intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_draglist(struct controlset *,char *label,char shortcut,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_filesel(struct controlset *,char *label,char shortcut,\r
- char const *filter, int write, char *title,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_fontsel(struct controlset *,char *label,char shortcut,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_text(struct controlset *, char *text, intorptr helpctx);\r
-union control *ctrl_checkbox(struct controlset *, char *label, char shortcut,\r
- intorptr helpctx,\r
- handler_fn handler, intorptr context);\r
-union control *ctrl_tabdelay(struct controlset *, union control *);\r
-\r
-/*\r
- * Standard handler routines to cover most of the common cases in\r
- * the config box.\r
- */\r
-/*\r
- * The standard radio-button handler expects the main `context'\r
- * field to contain the `offsetof' of an int field in the structure\r
- * pointed to by `data', and expects each of the individual button\r
- * data to give a value for that int field.\r
- */\r
-void dlg_stdradiobutton_handler(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-/*\r
- * The standard checkbox handler expects the main `context' field\r
- * to contain the `offsetof' an int field in the structure pointed\r
- * to by `data', optionally ORed with CHECKBOX_INVERT to indicate\r
- * that the sense of the datum is opposite to the sense of the\r
- * checkbox.\r
- */\r
-#define CHECKBOX_INVERT (1<<30)\r
-void dlg_stdcheckbox_handler(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-/*\r
- * The standard edit-box handler expects the main `context' field\r
- * to contain the `offsetof' a field in the structure pointed to by\r
- * `data'. The secondary `context2' field indicates the type of\r
- * this field:\r
- * \r
- * - if context2 > 0, the field is a char array and context2 gives\r
- * its size.\r
- * - if context2 == -1, the field is an int and the edit box is\r
- * numeric.\r
- * - if context2 < -1, the field is an int and the edit box is\r
- * _floating_, and (-context2) gives the scale. (E.g. if\r
- * context2 == -1000, then typing 1.2 into the box will set the\r
- * field to 1200.)\r
- */\r
-void dlg_stdeditbox_handler(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-/*\r
- * The standard file-selector handler expects the main `context'\r
- * field to contain the `offsetof' a Filename field in the\r
- * structure pointed to by `data'.\r
- */\r
-void dlg_stdfilesel_handler(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-/*\r
- * The standard font-selector handler expects the main `context'\r
- * field to contain the `offsetof' a Font field in the structure\r
- * pointed to by `data'.\r
- */\r
-void dlg_stdfontsel_handler(union control *ctrl, void *dlg,\r
- void *data, int event);\r
-\r
-/*\r
- * Routines the platform-independent dialog code can call to read\r
- * and write the values of controls.\r
- */\r
-void dlg_radiobutton_set(union control *ctrl, void *dlg, int whichbutton);\r
-int dlg_radiobutton_get(union control *ctrl, void *dlg);\r
-void dlg_checkbox_set(union control *ctrl, void *dlg, int checked);\r
-int dlg_checkbox_get(union control *ctrl, void *dlg);\r
-void dlg_editbox_set(union control *ctrl, void *dlg, char const *text);\r
-void dlg_editbox_get(union control *ctrl, void *dlg, char *buffer, int length);\r
-/* The `listbox' functions can also apply to combo boxes. */\r
-void dlg_listbox_clear(union control *ctrl, void *dlg);\r
-void dlg_listbox_del(union control *ctrl, void *dlg, int index);\r
-void dlg_listbox_add(union control *ctrl, void *dlg, char const *text);\r
-/*\r
- * Each listbox entry may have a numeric id associated with it.\r
- * Note that some front ends only permit a string to be stored at\r
- * each position, which means that _if_ you put two identical\r
- * strings in any listbox then you MUST not assign them different\r
- * IDs and expect to get meaningful results back.\r
- */\r
-void dlg_listbox_addwithid(union control *ctrl, void *dlg,\r
- char const *text, int id);\r
-int dlg_listbox_getid(union control *ctrl, void *dlg, int index);\r
-/* dlg_listbox_index returns <0 if no single element is selected. */\r
-int dlg_listbox_index(union control *ctrl, void *dlg);\r
-int dlg_listbox_issel(union control *ctrl, void *dlg, int index);\r
-void dlg_listbox_select(union control *ctrl, void *dlg, int index);\r
-void dlg_text_set(union control *ctrl, void *dlg, char const *text);\r
-void dlg_filesel_set(union control *ctrl, void *dlg, Filename fn);\r
-void dlg_filesel_get(union control *ctrl, void *dlg, Filename *fn);\r
-void dlg_fontsel_set(union control *ctrl, void *dlg, FontSpec fn);\r
-void dlg_fontsel_get(union control *ctrl, void *dlg, FontSpec *fn);\r
-/*\r
- * Bracketing a large set of updates in these two functions will\r
- * cause the front end (if possible) to delay updating the screen\r
- * until it's all complete, thus avoiding flicker.\r
- */\r
-void dlg_update_start(union control *ctrl, void *dlg);\r
-void dlg_update_done(union control *ctrl, void *dlg);\r
-/*\r
- * Set input focus into a particular control.\r
- */\r
-void dlg_set_focus(union control *ctrl, void *dlg);\r
-/*\r
- * Change the label text on a control.\r
- */\r
-void dlg_label_change(union control *ctrl, void *dlg, char const *text);\r
-/*\r
- * Return the `ctrl' structure for the most recent control that had\r
- * the input focus apart from the one mentioned. This is NOT\r
- * GUARANTEED to work on all platforms, so don't base any critical\r
- * functionality on it!\r
- */\r
-union control *dlg_last_focused(union control *ctrl, void *dlg);\r
-/*\r
- * During event processing, you might well want to give an error\r
- * indication to the user. dlg_beep() is a quick and easy generic\r
- * error; dlg_error() puts up a message-box or equivalent.\r
- */\r
-void dlg_beep(void *dlg);\r
-void dlg_error_msg(void *dlg, char *msg);\r
-/*\r
- * This function signals to the front end that the dialog's\r
- * processing is completed, and passes an integer value (typically\r
- * a success status).\r
- */\r
-void dlg_end(void *dlg, int value);\r
-\r
-/*\r
- * Routines to manage a (per-platform) colour selector.\r
- * dlg_coloursel_start() is called in an event handler, and\r
- * schedules the running of a colour selector after the event\r
- * handler returns. The colour selector will send EVENT_CALLBACK to\r
- * the control that spawned it, when it's finished;\r
- * dlg_coloursel_results() fetches the results, as integers from 0\r
- * to 255; it returns nonzero on success, or zero if the colour\r
- * selector was dismissed by hitting Cancel or similar.\r
- * \r
- * dlg_coloursel_start() accepts an RGB triple which is used to\r
- * initialise the colour selector to its starting value.\r
- */\r
-void dlg_coloursel_start(union control *ctrl, void *dlg,\r
- int r, int g, int b);\r
-int dlg_coloursel_results(union control *ctrl, void *dlg,\r
- int *r, int *g, int *b);\r
-\r
-/*\r
- * This routine is used by the platform-independent code to\r
- * indicate that the value of a particular control is likely to\r
- * have changed. It triggers a call of the handler for that control\r
- * with `event' set to EVENT_REFRESH.\r
- * \r
- * If `ctrl' is NULL, _all_ controls in the dialog get refreshed\r
- * (for loading or saving entire sets of settings).\r
- */\r
-void dlg_refresh(union control *ctrl, void *dlg);\r
-\r
-/*\r
- * It's perfectly possible that individual controls might need to\r
- * allocate or store per-dialog-instance data, so here's a\r
- * mechanism.\r
- * \r
- * `dlg_get_privdata' and `dlg_set_privdata' allow the user to get\r
- * and set a void * pointer associated with the control in\r
- * question. `dlg_alloc_privdata' will allocate memory, store a\r
- * pointer to that memory in the private data field, and arrange\r
- * for it to be automatically deallocated on dialog cleanup.\r
- */\r
-void *dlg_get_privdata(union control *ctrl, void *dlg);\r
-void dlg_set_privdata(union control *ctrl, void *dlg, void *ptr);\r
-void *dlg_alloc_privdata(union control *ctrl, void *dlg, size_t size);\r
-\r
-/*\r
- * Standard helper functions for reading a controlbox structure.\r
- */\r
-\r
-/*\r
- * Find the index of next controlset in a controlbox for a given\r
- * path, or -1 if no such controlset exists. If -1 is passed as\r
- * input, finds the first. Intended usage is something like\r
- * \r
- * for (index=-1; (index=ctrl_find_path(ctrlbox, index, path)) >= 0 ;) {\r
- * ... process this controlset ...\r
- * }\r
- */\r
-int ctrl_find_path(struct controlbox *b, char *path, int index);\r
-int ctrl_path_elements(char *path);\r
-/* Return the number of matching path elements at the starts of p1 and p2,\r
- * or INT_MAX if the paths are identical. */\r
-int ctrl_path_compare(char *p1, char *p2);\r