textscreen/txt_table.h

   1 // Emacs style mode select   -*- C++ -*-
   2 //-----------------------------------------------------------------------------
   3 //
   4 // Copyright(C) 2006 Simon Howard
   5 //
   6 // This program is free software; you can redistribute it and/or
   7 // modify it under the terms of the GNU General Public License
   8 // as published by the Free Software Foundation; either version 2
   9 // of the License, or (at your option) any later version.
  10 //
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  19 // 02111-1307, USA.
  20 //
  21
  22 #ifndef TXT_TABLE_H
  23 #define TXT_TABLE_H
  24
  25 /**
  26  * @file txt_table.h
  27  *
  28  * Table widget.
  29  */
  30
  31 /**
  32  * Table widget.
  33  *
  34  * A table is a widget that contains other widgets.  It may have
  35  * multiple columns, in which case the child widgets are laid out
  36  * in a grid.  Columns automatically grow as necessary, although
  37  * minimum column widths can be set using @ref TXT_SetColumnWidths.
  38  *
  39  * To create a new table, use @ref TXT_NewTable.  It is also
  40  * possible to use @ref TXT_NewHorizBox to create a table, specifying
  41  * widgets to place inside a horizontal list.  A vertical list is
  42  * possible simply by creating a table containing a single column.
  43  */
  44
  45 typedef struct txt_table_s txt_table_t;
  46
  47 #include "txt_widget.h"
  48
  49 struct txt_table_s
  50 {
  51     txt_widget_t widget;
  52
  53     // Widgets in this table
  54     // The widget at (x,y) in the table is widgets[columns * y + x]
  55
  56     txt_widget_t **widgets;
  57     int num_widgets;
  58
  59     // Number of columns
  60
  61     int columns;
  62
  63     // Currently selected
  64
  65     int selected_x;
  66     int selected_y;
  67 };
  68
  69 extern txt_widget_class_t txt_table_class;
  70
  71 void TXT_InitTable(txt_table_t *table, int columns);
  72
  73 /**
  74  * Create a new table.
  75  *
  76  * @param columns       The number of columns in the new table.
  77  * @return              Pointer to the new table structure.
  78  */
  79
  80 txt_table_t *TXT_NewTable(int columns);
  81
  82 /**
  83  * Create a table containing the specified widgets packed horizontally,
  84  * from left to right.
  85  *
  86  * The arguments to this function are variable.  Each argument must
  87  * be a pointer to a widget, and the list is terminated with a
  88  * NULL.
  89  *
  90  * @return             Pointer to the new table structure.
  91  */
  92
  93 txt_table_t *TXT_NewHorizBox(TXT_UNCAST_ARG(first_widget), ...);
  94
  95 /**
  96  * Get the currently selected widget within a table.
  97  *
  98  * This function will recurse through subtables if necessary.
  99  *
 100  * @param table        The table.
 101  * @return             Pointer to the widget that is currently selected.
 102  */
 103
 104 txt_widget_t *TXT_GetSelectedWidget(TXT_UNCAST_ARG(table));
 105
 106 /**
 107  * Add a widget to a table.
 108  *
 109  * Widgets are added to tables horizontally, from left to right.
 110  * For example, for a table with three columns, the first call
 111  * to this function will add a widget to the first column, the second
 112  * call to the second column, the third call to the third column,
 113  * and the fourth will return to the first column, starting a new
 114  * row.
 115  *
 116  * For adding many widgets, it may be easier to use
 117  * @ref TXT_AddWidgets.
 118  *
 119  * @param table        The table.
 120  * @param widget       The widget to add.
 121  */
 122
 123 void TXT_AddWidget(TXT_UNCAST_ARG(table), TXT_UNCAST_ARG(widget));
 124
 125 /**
 126  * Add multiple widgets to a table.
 127  *
 128  * Widgets are added as described in the documentation for the
 129  * @ref TXT_AddWidget function.  This function adds multiple
 130  * widgets.  The number of arguments is variable, and the argument
 131  * list must be terminated by a NULL pointer.
 132  *
 133  * @param table        The table.
 134  */
 135
 136 void TXT_AddWidgets(TXT_UNCAST_ARG(table), ...);
 137
 138 /**
 139  * Select the given widget that is contained within the specified
 140  * table.
 141  *
 142  * This function will recursively search through subtables if
 143  * necessary.
 144  *
 145  * @param table       The table.
 146  * @param widget      The widget to select.
 147  * @return            Non-zero (true) if it has been selected,
 148  *                    or zero (false) if it was not found within
 149  *                    this table.
 150  */
 151
 152 int TXT_SelectWidget(TXT_UNCAST_ARG(table), TXT_UNCAST_ARG(widget));
 153
 154 /**
 155  * Set the widths of the columns of the table.
 156  *
 157  * The arguments to this function are variable, and correspond
 158  * to the number of columns in the table.  For example, if a table
 159  * has five columns, the width of each of the five columns must be
 160  * specified.
 161  *
 162  * The width values are in number of characters.
 163  *
 164  * Note that this function only sets the minimum widths for columns;
 165  * if the columns contain widgets that are wider than the widths
 166  * specified, they will be larger.
 167  *
 168  * @param table     The table.
 169  */
 170
 171 void TXT_SetColumnWidths(TXT_UNCAST_ARG(table), ...);
 172
 173 /**
 174  * Remove all widgets from a table.
 175  *
 176  * @param table    The table.
 177  */
 178
 179 void TXT_ClearTable(TXT_UNCAST_ARG(table));
 180
 181 #endif /* #ifndef TXT_TABLE_T */
 182
 183