dialog.h

大名鼎鼎的远程登录软件putty的Symbian版源码

	 * The precise contents of `filter' are platform-defined,
	 * unfortunately. The special value NULL means `all files'
	 * and is always a valid fallback.
	 * 
	 * Unlike almost all strings in this structure, this value
	 * is NOT expected to require freeing (although of course
	 * you can always use ctrl_alloc if you do need to create
	 * one on the fly). This is because the likely mode of use
	 * is to define string constants in a platform-specific
	 * header file, and directly reference those. Or worse, a
	 * particular platform might choose to cast integers into
	 * this pointer type...
	 */
	char const *filter;
	/*
	 * Some systems like to know whether a file selector is
	 * choosing a file to read or one to write (and possibly
	 * create).
	 */
	int for_writing;
	/*
	 * On at least some platforms, the file selector is a
	 * separate dialog box, and contains a user-settable title.
	 * 
	 * This value _is_ expected to require freeing.
	 */
	char *title;
    } fileselect;
    struct {
	/* In this variant, `label' MUST be NULL. */
	STANDARD_PREFIX;
	int ncols;		       /* number of columns */
	int *percentages;	       /* % width of each column */
	/*
	 * Every time this control type appears, exactly one of
	 * `ncols' and the previous number of columns MUST be one.
	 * Attempting to allow a seamless transition from a four-
	 * to a five-column layout, for example, would be way more
	 * trouble than it was worth. If you must lay things out
	 * like that, define eight unevenly sized columns and use
	 * column-spanning a lot. But better still, just don't.
	 * 
	 * `percentages' may be NULL if ncols==1, to save space.
	 */
    } columns;
    struct {
	STANDARD_PREFIX;
	char shortcut;
    } fontselect;
};

#undef STANDARD_PREFIX

/*
 * `controlset' is a container holding an array of `union control'
 * structures, together with a panel name and a title for the whole
 * set. In Windows and any similar-looking GUI, each `controlset'
 * in the config will be a container box within a panel.
 * 
 * Special case: if `boxname' is NULL, the control set gives an
 * overall title for an entire panel of controls.
 */
struct controlset {
    char *pathname;		       /* panel path, e.g. "SSH/Tunnels" */
    char *boxname;		       /* internal short name of controlset */
    char *boxtitle;		       /* title of container box */
    int ncolumns;		       /* current no. of columns at bottom */
    int ncontrols;		       /* number of `union control' in array */
    int ctrlsize;		       /* allocated size of array */
    union control **ctrls;	       /* actual array */
};

/*
 * This is the container structure which holds a complete set of
 * controls.
 */
struct controlbox {
    int nctrlsets;		       /* number of ctrlsets */
    int ctrlsetsize;		       /* ctrlset size */
    struct controlset **ctrlsets;      /* actual array of ctrlsets */
    int nfrees;
    int freesize;
    void **frees;		       /* array of aux data areas to free */
};

struct controlbox *ctrl_new_box(void);
void ctrl_free_box(struct controlbox *);

/*
 * Standard functions used for populating a controlbox structure.
 */

/* Set up a panel title. */
struct controlset *ctrl_settitle(struct controlbox *,
				 char *path, char *title);
/* Retrieve a pointer to a controlset, creating it if absent. */
struct controlset *ctrl_getset(struct controlbox *,
			       char *path, char *name, char *boxtitle);
void ctrl_free_set(struct controlset *);

void ctrl_free(union control *);

/*
 * This function works like `malloc', but the memory it returns
 * will be automatically freed when the controlbox is freed. Note
 * that a controlbox is a dialog-box _template_, not an instance,
 * and so data allocated through this function is better not used
 * to hold modifiable per-instance things. It's mostly here for
 * allocating structures to be passed as control handler params.
 */
void *ctrl_alloc(struct controlbox *b, size_t size);

/*
 * Individual routines to create `union control' structures in a controlset.
 * 
 * Most of these routines allow the most common fields to be set
 * directly, and put default values in the rest. Each one returns a
 * pointer to the `union control' it created, so that final tweaks
 * can be made.
 */

/* `ncolumns' is followed by that many percentages, as integers. */
union control *ctrl_columns(struct controlset *, int ncolumns, ...);
union control *ctrl_editbox(struct controlset *, char *label, char shortcut,
			    int percentage, intorptr helpctx,
			    handler_fn handler,
			    intorptr context, intorptr context2);
union control *ctrl_combobox(struct controlset *, char *label, char shortcut,
			     int percentage, intorptr helpctx,
			     handler_fn handler,
			     intorptr context, intorptr context2);
/*
 * `ncolumns' is followed by (alternately) radio button titles and
 * intorptrs, until a NULL in place of a title string is seen. Each
 * title is expected to be followed by a shortcut _iff_ `shortcut'
 * is NO_SHORTCUT.
 */
union control *ctrl_radiobuttons(struct controlset *, char *label,
				 char shortcut, int ncolumns,
				 intorptr helpctx,
				 handler_fn handler, intorptr context, ...);
union control *ctrl_pushbutton(struct controlset *,char *label,char shortcut,
			       intorptr helpctx,
			       handler_fn handler, intorptr context);
union control *ctrl_listbox(struct controlset *,char *label,char shortcut,
			    intorptr helpctx,
			    handler_fn handler, intorptr context);
union control *ctrl_droplist(struct controlset *, char *label, char shortcut,
			     int percentage, intorptr helpctx,
			     handler_fn handler, intorptr context);
union control *ctrl_draglist(struct controlset *,char *label,char shortcut,
			     intorptr helpctx,
			     handler_fn handler, intorptr context);
union control *ctrl_filesel(struct controlset *,char *label,char shortcut,
			    char const *filter, int write, char *title,
			    intorptr helpctx,
			    handler_fn handler, intorptr context);
union control *ctrl_fontsel(struct controlset *,char *label,char shortcut,
			    intorptr helpctx,
			    handler_fn handler, intorptr context);
union control *ctrl_text(struct controlset *, char *text, intorptr helpctx);
union control *ctrl_checkbox(struct controlset *, char *label, char shortcut,
			     intorptr helpctx,
			     handler_fn handler, intorptr context);
union control *ctrl_tabdelay(struct controlset *, union control *);

/*
 * Standard handler routines to cover most of the common cases in
 * the config box.
 */
/*
 * The standard radio-button handler expects the main `context'
 * field to contain the `offsetof' of an int field in the structure
 * pointed to by `data', and expects each of the individual button
 * data to give a value for that int field.
 */
void dlg_stdradiobutton_handler(union control *ctrl, void *dlg,
				void *data, int event);
/*
 * The standard checkbox handler expects the main `context' field
 * to contain the `offsetof' an int field in the structure pointed
 * to by `data', optionally ORed with CHECKBOX_INVERT to indicate
 * that the sense of the datum is opposite to the sense of the
 * checkbox.
 */
#define CHECKBOX_INVERT (1<<30)
void dlg_stdcheckbox_handler(union control *ctrl, void *dlg,
			     void *data, int event);
/*
 * The standard edit-box handler expects the main `context' field
 * to contain the `offsetof' a field in the structure pointed to by
 * `data'. The secondary `context2' field indicates the type of
 * this field:
 * 
 *  - if context2 > 0, the field is a char array and context2 gives
 *    its size.
 *  - if context2 == -1, the field is an int and the edit box is
 *    numeric.
 *  - if context2 < -1, the field is an int and the edit box is
 *    _floating_, and (-context2) gives the scale. (E.g. if
 *    context2 == -1000, then typing 1.2 into the box will set the
 *    field to 1200.)
 */
void dlg_stdeditbox_handler(union control *ctrl, void *dlg,
			    void *data, int event);
/*
 * The standard file-selector handler expects the main `context'
 * field to contain the `offsetof' a Filename field in the
 * structure pointed to by `data'.
 */
void dlg_stdfilesel_handler(union control *ctrl, void *dlg,
			    void *data, int event);
/*
 * The standard font-selector handler expects the main `context'
 * field to contain the `offsetof' a Font field in the structure
 * pointed to by `data'.
 */
void dlg_stdfontsel_handler(union control *ctrl, void *dlg,
			    void *data, int event);

/*
 * Routines the platform-independent dialog code can call to read
 * and write the values of controls.
 */
void dlg_radiobutton_set(union control *ctrl, void *dlg, int whichbutton);
int dlg_radiobutton_get(union control *ctrl, void *dlg);
void dlg_checkbox_set(union control *ctrl, void *dlg, int checked);
int dlg_checkbox_get(union control *ctrl, void *dlg);
void dlg_editbox_set(union control *ctrl, void *dlg, char const *text);
void dlg_editbox_get(union control *ctrl, void *dlg, char *buffer, int length);
/* The `listbox' functions can also apply to combo boxes. */
void dlg_listbox_clear(union control *ctrl, void *dlg);
void dlg_listbox_del(union control *ctrl, void *dlg, int index);
void dlg_listbox_add(union control *ctrl, void *dlg, char const *text);
/*
 * Each listbox entry may have a numeric id associated with it.
 * Note that some front ends only permit a string to be stored at
 * each position, which means that _if_ you put two identical
 * strings in any listbox then you MUST not assign them different
 * IDs and expect to get meaningful results back.
 */
void dlg_listbox_addwithid(union control *ctrl, void *dlg,
			   char const *text, int id);
int dlg_listbox_getid(union control *ctrl, void *dlg, int index);
/* dlg_listbox_index returns <0 if no single element is selected. */
int dlg_listbox_index(union control *ctrl, void *dlg);
int dlg_listbox_issel(union control *ctrl, void *dlg, int index);
void dlg_listbox_select(union control *ctrl, void *dlg, int index);
void dlg_text_set(union control *ctrl, void *dlg, char const *text);
void dlg_filesel_set(union control *ctrl, void *dlg, Filename fn);
void dlg_filesel_get(union control *ctrl, void *dlg, Filename *fn);
void dlg_fontsel_set(union control *ctrl, void *dlg, FontSpec fn);
void dlg_fontsel_get(union control *ctrl, void *dlg, FontSpec *fn);
/*
 * Bracketing a large set of updates in these two functions will
 * cause the front end (if possible) to delay updating the screen
 * until it's all complete, thus avoiding flicker.
 */
void dlg_update_start(union control *ctrl, void *dlg);
void dlg_update_done(union control *ctrl, void *dlg);
/*
 * Set input focus into a particular control.
 */
void dlg_set_focus(union control *ctrl, void *dlg);
/*
 * Return the `ctrl' structure for the most recent control that had
 * the input focus apart from the one mentioned. This is NOT
 * GUARANTEED to work on all platforms, so don't base any critical
 * functionality on it!
 */
union control *dlg_last_focused(union control *ctrl, void *dlg);
/*
 * During event processing, you might well want to give an error
 * indication to the user. dlg_beep() is a quick and easy generic
 * error; dlg_error() puts up a message-box or equivalent.
 */
void dlg_beep(void *dlg);
void dlg_error_msg(void *dlg, char *msg);
/*
 * This function signals to the front end that the dialog's
 * processing is completed, and passes an integer value (typically
 * a success status).
 */
void dlg_end(void *dlg, int value);

/*
 * Routines to manage a (per-platform) colour selector.
 * dlg_coloursel_start() is called in an event handler, and
 * schedules the running of a colour selector after the event
 * handler returns. The colour selector will send EVENT_CALLBACK to
 * the control that spawned it, when it's finished;
 * dlg_coloursel_results() fetches the results, as integers from 0
 * to 255; it returns nonzero on success, or zero if the colour
 * selector was dismissed by hitting Cancel or similar.
 * 
 * dlg_coloursel_start() accepts an RGB triple which is used to
 * initialise the colour selector to its starting value.
 */
void dlg_coloursel_start(union control *ctrl, void *dlg,
			 int r, int g, int b);
int dlg_coloursel_results(union control *ctrl, void *dlg,
			  int *r, int *g, int *b);

/*
 * This routine is used by the platform-independent code to
 * indicate that the value of a particular control is likely to
 * have changed. It triggers a call of the handler for that control
 * with `event' set to EVENT_REFRESH.
 * 
 * If `ctrl' is NULL, _all_ controls in the dialog get refreshed
 * (for loading or saving entire sets of settings).
 */
void dlg_refresh(union control *ctrl, void *dlg);

/*
 * It's perfectly possible that individual controls might need to
 * allocate or store per-dialog-instance data, so here's a
 * mechanism.
 * 
 * `dlg_get_privdata' and `dlg_set_privdata' allow the user to get
 * and set a void * pointer associated with the control in
 * question. `dlg_alloc_privdata' will allocate memory, store a
 * pointer to that memory in the private data field, and arrange
 * for it to be automatically deallocated on dialog cleanup.
 */
void *dlg_get_privdata(union control *ctrl, void *dlg);
void dlg_set_privdata(union control *ctrl, void *dlg, void *ptr);
void *dlg_alloc_privdata(union control *ctrl, void *dlg, size_t size);

/*
 * Standard helper functions for reading a controlbox structure.
 */

/*
 * Find the index of next controlset in a controlbox for a given
 * path, or -1 if no such controlset exists. If -1 is passed as
 * input, finds the first. Intended usage is something like
 * 
 * 	for (index=-1; (index=ctrl_find_path(ctrlbox, index, path)) >= 0 ;) {
 *          ... process this controlset ...
 *      }
 */
int ctrl_find_path(struct controlbox *b, char *path, int index);
int ctrl_path_elements(char *path);
/* Return the number of matching path elements at the starts of p1 and p2,
 * or INT_MAX if the paths are identical. */
int ctrl_path_compare(char *p1, char *p2);