From 2b5dae761ba1727cb483f4bae334a1b25f222e18 Mon Sep 17 00:00:00 2001 From: Simon Howard Date: Sat, 7 Mar 2009 00:24:45 +0000 Subject: Add documentation for high-level textscreen functions. Subversion-branch: /trunk/chocolate-doom Subversion-revision: 1449 --- textscreen/txt_button.h | 35 +++++++++++- textscreen/txt_checkbox.h | 35 ++++++++++++ textscreen/txt_dropdown.h | 24 +++++++++ textscreen/txt_inputbox.h | 32 +++++++++++ textscreen/txt_label.h | 37 +++++++++++++ textscreen/txt_radiobutton.h | 37 +++++++++++++ textscreen/txt_scrollpane.h | 18 +++++++ textscreen/txt_separator.h | 17 ++++++ textscreen/txt_spinctrl.h | 30 +++++++++++ textscreen/txt_strut.h | 20 +++++-- textscreen/txt_table.h | 118 ++++++++++++++++++++++++++++++++++++++++- textscreen/txt_widget.h | 39 ++++++++++++-- textscreen/txt_window.h | 95 +++++++++++++++++++++++++++++++-- textscreen/txt_window_action.h | 44 +++++++++++++-- 14 files changed, 562 insertions(+), 19 deletions(-) (limited to 'textscreen') diff --git a/textscreen/txt_button.h b/textscreen/txt_button.h index 11040f2f..ea7fd6e5 100644 --- a/textscreen/txt_button.h +++ b/textscreen/txt_button.h @@ -22,6 +22,13 @@ #ifndef TXT_BUTTON_H #define TXT_BUTTON_H +/** + * Button widget. + * + * A button is a widget that can be selected to perform some action. + * When a button is pressed, it emits the "pressed" signal. + */ + typedef struct txt_button_s txt_button_t; #include "txt_widget.h" @@ -32,9 +39,35 @@ struct txt_button_s char *label; }; +/** + * Create a new button widget. + * + * @param label The label to use on the new button. + * @return Pointer to the new button widget. + */ + txt_button_t *TXT_NewButton(char *label); -txt_button_t *TXT_NewButton2(char *label, TxtWidgetSignalFunc func, + +/** + * Create a new button widget, binding the "pressed" signal to a + * specified callback function. + * + * @param label The label to use on the new button. + * @param func The callback function to invoke. + * @param user_data User-specified pointer to pass to the callback. + * @return Pointer to the new button widget. + */ + +txt_button_t *TXT_NewButton2(char *label, TxtWidgetSignalFunc func, void *user_data); + +/** + * Change the label used on a button. + * + * @param button The button. + * @param label The new label. + */ + void TXT_SetButtonLabel(txt_button_t *button, char *label); #endif /* #ifndef TXT_BUTTON_H */ diff --git a/textscreen/txt_checkbox.h b/textscreen/txt_checkbox.h index 1b34c3a0..b786ad61 100644 --- a/textscreen/txt_checkbox.h +++ b/textscreen/txt_checkbox.h @@ -22,6 +22,19 @@ #ifndef TXT_CHECKBOX_H #define TXT_CHECKBOX_H +/** + * Checkbox widget. + * + * A checkbox is used to control boolean values that may be either on + * or off. The widget has a label that is displayed to the right of + * the checkbox indicator. The widget tracks an integer variable; + * if the variable is non-zero, the checkbox is checked, while if it + * is zero, the checkbox is unchecked. It is also possible to + * create "inverted" checkboxes where this logic is reversed. + * + * When a checkbox is changed, it emits the "changed" signal. + */ + typedef struct txt_checkbox_s txt_checkbox_t; #include "txt_widget.h" @@ -34,7 +47,29 @@ struct txt_checkbox_s int inverted; }; +/** + * Create a new checkbox. + * + * @param label The label for the new checkbox. + * @param variable Pointer to the variable containing this checkbox's + * value. + * @return Pointer to the new checkbox. + */ + txt_checkbox_t *TXT_NewCheckBox(char *label, int *variable); + +/** + * Create a new inverted checkbox. + * + * An inverted checkbox displays the opposite of a normal checkbox; + * where it would be checked, it appears unchecked, and vice-versa. + * + * @param label The label for the new checkbox. + * @param variable Pointer to the variable containing this checkbox's + * value. + * @return Pointer to the new checkbox. + */ + txt_checkbox_t *TXT_NewInvertedCheckBox(char *label, int *variable); #endif /* #ifndef TXT_CHECKBOX_H */ diff --git a/textscreen/txt_dropdown.h b/textscreen/txt_dropdown.h index 1a142b73..6eb8a726 100644 --- a/textscreen/txt_dropdown.h +++ b/textscreen/txt_dropdown.h @@ -22,6 +22,16 @@ #ifndef TXT_DROPDOWN_H #define TXT_DROPDOWN_H +/** + * Dropdown list widget. + * + * A dropdown list allows the user to select from a list of values, + * which appears when the list is selected. + * + * When the value of a dropdown list is changed, the "changed" signal + * is emitted. + */ + typedef struct txt_dropdown_list_s txt_dropdown_list_t; #include "txt_widget.h" @@ -38,6 +48,20 @@ struct txt_dropdown_list_s int num_values; }; +/** + * Create a new dropdown list widget. + * + * The parameters specify a list of string labels, and a pointer to an + * integer variable. The variable contains the current "value" of the + * list, as an index within the list of labels. + * + * @param variable Pointer to the variable containing the + * list's value. + * @param values Pointer to an array of strings containing + * the labels to use for the list. + * @param num_values The number of variables in the list. + */ + txt_dropdown_list_t *TXT_NewDropdownList(int *variable, char **values, int num_values); diff --git a/textscreen/txt_inputbox.h b/textscreen/txt_inputbox.h index fa610485..729dbbc6 100644 --- a/textscreen/txt_inputbox.h +++ b/textscreen/txt_inputbox.h @@ -22,6 +22,15 @@ #ifndef TXT_INPUTBOX_H #define TXT_INPUTBOX_H +/** + * Input box widget. + * + * An input box is a widget that displays a value, which can be + * selected to enter a new value. + * + * Input box widgets can be of an integer or string type. + */ + typedef struct txt_inputbox_s txt_inputbox_t; #include "txt_widget.h" @@ -35,7 +44,30 @@ struct txt_inputbox_s void *value; }; +/** + * Create a new input box widget for controlling a string value. + * + * @param value Pointer to a string variable that contains + * a pointer to the current value of the + * input box. The value should be allocated + * dynamically; when the string is changed it + * will be freed and the variable set to point + * to the new string value. + * @param size Width of the input box, in characters. + * @return Pointer to the new input box widget. + */ + txt_inputbox_t *TXT_NewInputBox(char **value, int size); + +/** + * Create a new input box widget for controlling an integer value. + * + * @param value Pointer to an integer variable containing + * the value of the input box. + * @param size Width of the input box, in characters. + * @return Pointer to the new input box widget. + */ + txt_inputbox_t *TXT_NewIntInputBox(int *value, int size); #endif /* #ifndef TXT_INPUTBOX_H */ diff --git a/textscreen/txt_label.h b/textscreen/txt_label.h index c8e002e0..ba1b0c3e 100644 --- a/textscreen/txt_label.h +++ b/textscreen/txt_label.h @@ -22,6 +22,12 @@ #ifndef TXT_LABEL_H #define TXT_LABEL_H +/** + * Label widget. + * + * A label widget does nothing except show a text label. + */ + typedef struct txt_label_s txt_label_t; #include "txt_main.h" @@ -37,9 +43,40 @@ struct txt_label_s txt_color_t bgcolor; }; +/** + * Create a new label widget. + * + * @param label String to display in the widget. + * @return Pointer to the new label widget. + */ + txt_label_t *TXT_NewLabel(char *label); + +/** + * Set the string displayed in a label widget. + * + * @param label The widget. + * @param value The string to display. + */ + void TXT_SetLabel(txt_label_t *label, char *value); + +/** + * Set the background color of a label widget. + * + * @param label The widget. + * @param color The background color to use. + */ + void TXT_SetBGColor(txt_label_t *label, txt_color_t color); + +/** + * Set the foreground color of a label widget. + * + * @param label The widget. + * @param color The foreground color to use. + */ + void TXT_SetFGColor(txt_label_t *label, txt_color_t color); #endif /* #ifndef TXT_LABEL_H */ diff --git a/textscreen/txt_radiobutton.h b/textscreen/txt_radiobutton.h index d668254c..b1d6487c 100644 --- a/textscreen/txt_radiobutton.h +++ b/textscreen/txt_radiobutton.h @@ -22,6 +22,24 @@ #ifndef TXT_RADIOBUTTON_H #define TXT_RADIOBUTTON_H +/** + * A radio button widget. + * + * Radio buttons are typically used in groups, to allow a value to be + * selected from a range of options. Each radio button corresponds + * to a particular option that may be selected. A radio button + * has an indicator to indicate whether it is the currently-selected + * value, and a text label. + * + * Internally, a radio button tracks an integer variable that may take + * a range of different values. Each radio button has a particular + * value associated with it; if the variable is equal to that value, + * the radio button appears selected. If a radio button is pressed + * by the user through the GUI, the variable is set to its value. + * + * When a radio button is selected, the "selected" signal is emitted. + */ + typedef struct txt_radiobutton_s txt_radiobutton_t; #include "txt_widget.h" @@ -34,7 +52,26 @@ struct txt_radiobutton_s int value; }; +/** + * Create a new radio button widget. + * + * @param label The label to display next to the radio button. + * @param variable Pointer to the variable tracking whether this + * radio button is selected. + * @param value If the variable is equal to this value, the + * radio button appears selected. + * @return Pointer to the new radio button widget. + */ + txt_radiobutton_t *TXT_NewRadioButton(char *label, int *variable, int value); + +/** + * Set the label on a radio button. + * + * @param radiobutton The radio button. + * @param value The new label. + */ + void TXT_SetRadioButtonLabel(txt_radiobutton_t *radiobutton, char *value); #endif /* #ifndef TXT_RADIOBUTTON_H */ diff --git a/textscreen/txt_scrollpane.h b/textscreen/txt_scrollpane.h index 661542a3..7242e61e 100644 --- a/textscreen/txt_scrollpane.h +++ b/textscreen/txt_scrollpane.h @@ -22,6 +22,14 @@ #ifndef TXT_SCROLLPANE_H #define TXT_SCROLLPANE_H +/** + * Scrollable pane widget. + * + * A scrollable pane widget is a widget that contains another widget + * that is larger than it. Scroll bars appear on the side to allow + * different areas of the contained widget to be seen. + */ + typedef struct txt_scrollpane_s txt_scrollpane_t; #include "txt_widget.h" @@ -35,6 +43,16 @@ struct txt_scrollpane_s txt_widget_t *child; }; +/** + * Create a new scroll pane widget. + * + * @param w Width of the scroll pane, in characters. + * @param h Height of the scroll pane, in lines. + * @param target The target widget that the scroll pane will + * contain. + * @return Pointer to the new scroll pane widget. + */ + txt_scrollpane_t *TXT_NewScrollPane(int w, int h, TXT_UNCAST_ARG(target)); #endif /* #ifndef TXT_SCROLLPANE_H */ diff --git a/textscreen/txt_separator.h b/textscreen/txt_separator.h index c8691171..518a56c9 100644 --- a/textscreen/txt_separator.h +++ b/textscreen/txt_separator.h @@ -22,6 +22,15 @@ #ifndef TXT_SEPARATOR_H #define TXT_SEPARATOR_H +/** + * Horizontal separator. + * + * A horizontal separator appears as a horizontal line divider across + * the length of the window in which it is added. An optional label + * allows the separator to be used as a section divider for grouping + * related controls. + */ + typedef struct txt_separator_s txt_separator_t; #include "txt_widget.h" @@ -34,6 +43,14 @@ struct txt_separator_s extern txt_widget_class_t txt_separator_class; +/** + * Create a new horizontal separator widget. + * + * @param label Label to display on the separator. If this is + * set to NULL, no label is displayed. + * @return The new separator widget. + */ + txt_separator_t *TXT_NewSeparator(char *label); #endif /* #ifndef TXT_SEPARATOR_H */ diff --git a/textscreen/txt_spinctrl.h b/textscreen/txt_spinctrl.h index 2fdd2a62..02d5a211 100644 --- a/textscreen/txt_spinctrl.h +++ b/textscreen/txt_spinctrl.h @@ -22,7 +22,16 @@ #ifndef TXT_SPINCONTROL_H #define TXT_SPINCONTROL_H +/** + * Spin control widget. + * + * A spin control widget works as an input box that can be used to + * set numeric values, but also has buttons that allow its value + * to be increased or decreased. + */ + typedef struct txt_spincontrol_s txt_spincontrol_t; + typedef enum { TXT_SPINCONTROL_INT, @@ -40,7 +49,28 @@ struct txt_spincontrol_s char *buffer; }; +/** + * Create a new spin control widget tracking an integer value. + * + * @param value Pointer to the variable containing the value + * displayed in the widget. + * @param min Minimum value that may be set. + * @param max Maximum value that may be set. + * @return Pointer to the new spin control widget. + */ + txt_spincontrol_t *TXT_NewSpinControl(int *value, int min, int max); + +/** + * Create a new spin control widget tracking a float value. + * + * @param value Pointer to the variable containing the value + * displayed in the widget. + * @param min Minimum value that may be set. + * @param max Maximum value that may be set. + * @return Pointer to the new spin control widget. + */ + txt_spincontrol_t *TXT_NewFloatSpinControl(float *value, float min, float max); #endif /* #ifndef TXT_SPINCONTROL_H */ diff --git a/textscreen/txt_strut.h b/textscreen/txt_strut.h index 7d9e7650..8436aa9c 100644 --- a/textscreen/txt_strut.h +++ b/textscreen/txt_strut.h @@ -22,15 +22,18 @@ #ifndef TXT_STRUT_H #define TXT_STRUT_H +/** + * Strut widget. + * + * A strut is a widget that takes up a fixed amount of space. It can + * be visualised as a transparent box. Struts are used to provide + * spacing between widgets. + */ + typedef struct txt_strut_s txt_strut_t; #include "txt_widget.h" -// -// A strut is used to force a table to a minimum width/height. It is not -// visible but it takes up space. -// - struct txt_strut_s { txt_widget_t widget; @@ -38,6 +41,13 @@ struct txt_strut_s int height; }; +/** + * Create a new strut. + * + * @param width Width of the strut, in characters. + * @param height Height of the strut, in characters. + */ + txt_strut_t *TXT_NewStrut(int width, int height); #endif /* #ifndef TXT_STRUT_H */ diff --git a/textscreen/txt_table.h b/textscreen/txt_table.h index dee6f4bb..2bbb8ffc 100644 --- a/textscreen/txt_table.h +++ b/textscreen/txt_table.h @@ -22,9 +22,23 @@ #ifndef TXT_TABLE_H #define TXT_TABLE_H +/** + * Table widget. + * + * A table is a widget that contains other widgets. It may have + * multiple columns, in which case the child widgets are laid out + * in a grid. Columns automatically grow as necessary, although + * minimum column widths can be set using @ref TXT_SetColumnWidths. + * + * To create a new table, use @ref TXT_NewTable. It is also + * possible to use @ref TXT_NewHorizBox to create a table, specifying + * widgets to place inside a horizontal list. A vertical list is + * possible simply by creating a table containing a single column. + */ + typedef struct txt_table_s txt_table_t; -#include "txt_widget.h" +#include "txt_widget.h" struct txt_table_s { @@ -48,14 +62,114 @@ struct txt_table_s extern txt_widget_class_t txt_table_class; +void TXT_InitTable(txt_table_t *table, int columns); + +/** + * Create a new table. + * + * @param columns The number of columns in the new table. + * @return Pointer to the new table structure. + */ + txt_table_t *TXT_NewTable(int columns); + +/** + * Create a table containing the specified widgets packed horizontally, + * from left to right. + * + * The arguments to this function are variable. Each argument must + * be a pointer to a widget, and the list is terminated with a + * NULL. + * + * @return Pointer to the new table structure. + */ + txt_table_t *TXT_NewHorizBox(TXT_UNCAST_ARG(first_widget), ...); -void TXT_InitTable(txt_table_t *table, int columns); + +/** + * Get the currently selected widget within a table. + * + * This function will recurse through subtables if necessary. + * + * @param table The table. + * @return Pointer to the widget that is currently selected. + */ + txt_widget_t *TXT_GetSelectedWidget(TXT_UNCAST_ARG(table)); + +/** + * Add a widget to a table. + * + * Widgets are added to tables horizontally, from left to right. + * For example, for a table with three columns, the first call + * to this function will add a widget to the first column, the second + * call to the second column, the third call to the third column, + * and the fourth will return to the first column, starting a new + * row. + * + * For adding many widgets, it may be easier to use + * @ref TXT_AddWidgets. + * + * @param table The table. + * @param widget The widget to add. + */ + void TXT_AddWidget(TXT_UNCAST_ARG(table), TXT_UNCAST_ARG(widget)); + +/** + * Add multiple widgets to a table. + * + * Widgets are added as described in the documentation for the + * @ref TXT_AddWidget function. This function adds multiple + * widgets. The number of arguments is variable, and the argument + * list must be terminated by a NULL pointer. + * + * @param table The table. + */ + void TXT_AddWidgets(TXT_UNCAST_ARG(table), ...); + +/** + * Select the given widget that is contained within the specified + * table. + * + * This function will recursively search through subtables if + * necessary. + * + * @param table The table. + * @param widget The widget to select. + * @return Non-zero (true) if it has been selected, + * or zero (false) if it was not found within + * this table. + */ + int TXT_SelectWidget(TXT_UNCAST_ARG(table), TXT_UNCAST_ARG(widget)); + +/** + * Set the widths of the columns of the table. + * + * The arguments to this function are variable, and correspond + * to the number of columns in the table. For example, if a table + * has five columns, the width of each of the five columns must be + * specified. + * + * The width values are in number of characters. + * + * Note that this function only sets the minimum widths for columns; + * if the columns contain widgets that are wider than the widths + * specified, they will be larger. + * + * @param table The table. + */ + void TXT_SetColumnWidths(TXT_UNCAST_ARG(table), ...); + +/** + * Remove all widgets from a table. + * + * @param table The table. + */ + void TXT_ClearTable(TXT_UNCAST_ARG(table)); #endif /* #ifndef TXT_TABLE_T */ diff --git a/textscreen/txt_widget.h b/textscreen/txt_widget.h index 0e80f3c1..b1afea50 100644 --- a/textscreen/txt_widget.h +++ b/textscreen/txt_widget.h @@ -42,8 +42,20 @@ typedef enum TXT_HORIZ_RIGHT, } txt_horiz_align_t; -typedef struct txt_widget_class_s txt_widget_class_t; +/** + * A GUI widget. + * + * A widget is an individual component of a GUI. Various different widget + * types exist. + * + * Widgets may emit signals. The types of signal emitted by a widget + * depend on the type of the widget. It is possible to be notified + * when a signal occurs using the @ref TXT_SignalConnect function. + */ + typedef struct txt_widget_s txt_widget_t; + +typedef struct txt_widget_class_s txt_widget_class_t; typedef struct txt_callback_table_s txt_callback_table_t; typedef void (*TxtWidgetSizeCalc)(TXT_UNCAST_ARG(widget)); @@ -82,15 +94,34 @@ struct txt_widget_s void TXT_InitWidget(TXT_UNCAST_ARG(widget), txt_widget_class_t *widget_class); void TXT_CalcWidgetSize(TXT_UNCAST_ARG(widget)); void TXT_DrawWidget(TXT_UNCAST_ARG(widget), int selected); -void TXT_SignalConnect(TXT_UNCAST_ARG(widget), char *signal_name, - TxtWidgetSignalFunc func, void *user_data); void TXT_EmitSignal(TXT_UNCAST_ARG(widget), char *signal_name); int TXT_WidgetKeyPress(TXT_UNCAST_ARG(widget), int key); void TXT_WidgetMousePress(TXT_UNCAST_ARG(widget), int x, int y, int b); void TXT_DestroyWidget(TXT_UNCAST_ARG(widget)); -void TXT_SetWidgetAlign(TXT_UNCAST_ARG(widget), txt_horiz_align_t horiz_align); void TXT_LayoutWidget(TXT_UNCAST_ARG(widget)); +/** + * Set a callback function to be invoked when a signal occurs. + * + * @param widget The widget to watch. + * @param signal_name The signal to watch. + * @param func The callback function to invoke. + * @param user_data User-specified pointer to pass to the callback function. + */ + +void TXT_SignalConnect(TXT_UNCAST_ARG(widget), char *signal_name, + TxtWidgetSignalFunc func, void *user_data); + +/** + * Set the policy for how a widget should be aligned within a table. + * By default, widgets are aligned to the left of the column. + * + * @param widget The widget. + * @param horiz_align The alignment to use. + */ + +void TXT_SetWidgetAlign(TXT_UNCAST_ARG(widget), txt_horiz_align_t horiz_align); + #endif /* #ifndef TXT_WIDGET_H */ diff --git a/textscreen/txt_window.h b/textscreen/txt_window.h index 3659ed29..38c7a128 100644 --- a/textscreen/txt_window.h +++ b/textscreen/txt_window.h @@ -22,6 +22,25 @@ #ifndef TXT_WINDOW_H #define TXT_WINDOW_H +/** + * A window. + * + * A window contains widgets, and may also be treated as a table + * containing a single column. + * + * Windows can be created using @ref TXT_NewWindow and closed using + * @ref TXT_CloseWindow. When a window is closed, it emits the + * "closed" signal. + * + * In addition to the widgets within a window, windows also have + * a "tray" area at their bottom containing window action widgets. + * These widgets allow keyboard shortcuts to trigger common actions. + * Each window has three slots for keyboard shortcuts. By default, + * the left slot contains an action to close the window when the + * escape button is pressed, while the right slot contains an + * action to activate the currently-selected widget. + */ + typedef struct txt_window_s txt_window_t; #include "txt_widget.h" @@ -68,18 +87,86 @@ struct txt_window_s unsigned int window_w, window_h; }; +/** + * Open a new window. + * + * @param title Title to display in the titlebar of the new window. + * @return Pointer to a new @ref txt_window_t structure + * representing the new window. + */ + txt_window_t *TXT_NewWindow(char *title); + +/** + * Close a window. + * + * @param window Tine window to close. + */ + void TXT_CloseWindow(txt_window_t *window); -void TXT_SetWindowPosition(txt_window_t *window, + +/** + * Set the position of a window on the screen. + * + * The window is specified as coordinates relative to a predefined + * position on the screen (eg. center of the screen, top left of the + * screen, etc). + * + * @param window The window. + * @param horiz_align Horizontal position on the screen to which the + * coordinates are relative (left side, right side + * or center). + * @param vert_align Vertical position on the screen to which the + * coordinates are relative (top, bottom or center). + * @param x X coordinate (horizonal axis) for window position. + * @param y Y coordinate (vertical axis) for window position. + */ + +void TXT_SetWindowPosition(txt_window_t *window, txt_horiz_align_t horiz_align, txt_vert_align_t vert_align, int x, int y); + +/** + * Set a window action for a given window. + * + * Each window can have up to three window actions, which provide + * keyboard shortcuts that can be used within a given window. + * + * @param window The window. + * @param position The window action slot to set (left, center or right). + * @param action The window action widget. If this is NULL, any + * current window action in the given slot is removed. + */ + void TXT_SetWindowAction(txt_window_t *window, txt_horiz_align_t position, txt_window_action_t *action); -void TXT_SetKeyListener(txt_window_t *window, - TxtWindowKeyPress key_listener, + +/** + * Set a callback function to be invoked whenever a key is pressed within + * a window. + * + * @param window The window. + * @param key_listener Callback function. + * @param user_data User-specified pointer to pass to the callback + * function. + */ + +void TXT_SetKeyListener(txt_window_t *window, + TxtWindowKeyPress key_listener, void *user_data); -void TXT_SetMouseListener(txt_window_t *window, + +/** + * Set a callback function to be invoked whenever a mouse button is pressed + * within a window. + * + * @param window The window. + * @param mouse_listener Callback function. + * @param user_data User-specified pointer to pass to the callback + * function. + */ + +void TXT_SetMouseListener(txt_window_t *window, TxtWindowMousePress mouse_listener, void *user_data); diff --git a/textscreen/txt_window_action.h b/textscreen/txt_window_action.h index 56f5a1b6..3f016bdb 100644 --- a/textscreen/txt_window_action.h +++ b/textscreen/txt_window_action.h @@ -22,6 +22,16 @@ #ifndef TXT_WINDOW_ACTION_H #define TXT_WINDOW_ACTION_H +/** + * Window action widget. + * + * A window action is attached to a window and corresponds to a + * keyboard shortcut that is active within that window. When the + * key is pressed, the action is triggered. + * + * When a window action is triggered, the "pressed" signal is emitted. + */ + typedef struct txt_window_action_s txt_window_action_t; #include "txt_widget.h" @@ -34,17 +44,45 @@ struct txt_window_action_s int key; }; +/** + * Create a new window action. + * + * @param key The keyboard key that triggers this action. + * @param label Label to display for this action in the tray + * at the bottom of the window. + * @return Pointer to the new window action widget. + */ + txt_window_action_t *TXT_NewWindowAction(int key, char *label); -// Creates an "escape" button that closes the window +/** + * Create a new window action that closes the window when the + * escape key is pressed. The label "Close" is used. + * + * @param window The window to close. + * @return Pointer to the new window action widget. + */ txt_window_action_t *TXT_NewWindowEscapeAction(txt_window_t *window); -// Same as above, but the button is named "abort" +/** + * Create a new window action that closes the window when the + * escape key is pressed. The label "Abort" is used. + * + * @param window The window to close. + * @return Pointer to the new window action widget. + */ txt_window_action_t *TXT_NewWindowAbortAction(txt_window_t *window); -// Accept button that does nothing +/** + * Create a new "select" window action. This does not really do + * anything, but reminds the user that "enter" can be pressed to + * activate the currently-selected widget. + * + * @param window The window. + * @return Pointer to the new window action widget. + */ txt_window_action_t *TXT_NewWindowSelectAction(txt_window_t *window); -- cgit v1.2.3