Add documentation for high-level textscreen functions.

Subversion-branch: /trunk/chocolate-doom
Subversion-revision: 1449

1 files changed, 116 insertions, 2 deletions

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 */