src/ml_table_layout.h

   1 /* Monolith table layout class.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: ml_table_layout.h,v 1.3 2002/11/13 20:46:38 rich Exp $
  19  */
  20
  21 #ifndef ML_TABLE_LAYOUT_H
  22 #define ML_TABLE_LAYOUT_H
  23
  24 #include <ml_widget.h>
  25
  26 struct ml_table_layout;
  27 typedef struct ml_table_layout *ml_table_layout;
  28
  29 /* Function: new_ml_table_layout - monolith table layout widget
  30  * Function: ml_table_layout_pack
  31  * Function: ml_table_layout_add_row
  32  * Function: ml_table_layout_set_colspan
  33  * Function: ml_table_layout_set_rowspan
  34  * Function: ml_table_layout_set_align
  35  * Function: ml_table_layout_set_valign
  36  * Function: ml_table_layout_set_class
  37  * Function: ml_table_layout_set_header
  38  *
  39  * The monolith table layout widget is a very powerful
  40  * layout tool. It is modelled on, and indeed implemented using,
  41  * HTML <table>s. Table layouts are grids of widgets with
  42  * a fixed number of rows and columns. Each widget normally
  43  * occupies a single cell of the table, but widgets may occupy
  44  * a rectangle of several adjacent cells. All cells in the table
  45  * are referenced using the row and column number, with row
  46  * and column numbers starting from zero.
  47  *
  48  * Note that when creating forms, it is often better to use
  49  * the simpler @code{ml_multicol_layout} widget (see
  50  * @ref{new_ml_multicol_layout(3)}).
  51  *
  52  * For single row or single column tables, it is usually better
  53  * to use @code{ml_horizontal_layout} or @code{ml_vertical_layout}
  54  * respectively (see @ref{new_ml_horizontal_layout(3)},
  55  * @ref{new_ml_vertical_layout(3)}).
  56  *
  57  * @code{new_ml_table_layout} creates a new table layout widget
  58  * with @code{rows} cells across and @code{cols} cells down. The
  59  * cells are numbered @code{0 .. rows-1} across and code{0 .. cols-1}
  60  * down.
  61  *
  62  * The following properties can be changed on tables (see
  63  * @ref{ml_widget_set_property(3)}):
  64  *
  65  * @code{class}: The stylesheet class.
  66  *
  67  * @code{ml_table_layout_pack} packs a widget at position
  68  * @code{(row,col)} within the table. To remove a widget and
  69  * leave a cell empty, pack a @code{NULL} widget.
  70  *
  71  * @code{ml_table_layout_add_row} adds a single row at the end
  72  * of the table.
  73  *
  74  * @code{ml_table_layout_set_colspan} and
  75  * @code{ml_table_layout_set_rowspan} set the column span
  76  * and row span for a particular table cell respectively.
  77  * The col/row-span allow a cell to occupy one or more
  78  * adjacent cells in the table (any widgets packed in those
  79  * adjacent cells are silently ignored). The default
  80  * column and row span for every cell is 1.
  81  *
  82  * @code{ml_table_layout_set_align} sets the horizontal
  83  * alignment for the content of a cell. The possibilities
  84  * are @code{"left"}, @code{"center"}
  85  * or @code{"right"}, with the default being left-aligned.
  86  *
  87  * @code{ml_table_layout_set_valign} sets the vertical
  88  * alignment for the content of a cell. The possibilities
  89  * are @code{"top"}, @code{"middle"}
  90  * or @code{"bottom"}, with the default being middle.
  91  *
  92  * @code{ml_table_layout_set_class} sets the stylesheet class for a
  93  * cell (the default being no class).
  94  *
  95  * @code{ml_table_layout_set_header} sets a boolean flag on a cell. When
  96  * try, this is a header cell. Otherwise, this is a normal table body cell.
  97  * This can be used in conjunction with stylesheets on the table.
  98  *
  99  * See also: @ref{new_ml_multicol_layout(3)},
 100  * @ref{new_ml_horizontal_layout(3)},
 101  * @ref{new_ml_vertical_layout(3)},
 102  * @ref{new_ml_widget(3)}.
 103  */
 104 extern ml_table_layout new_ml_table_layout (pool, int rows, int cols);
 105 extern void ml_table_layout_pack (ml_table_layout, ml_widget, int row, int col);
 106 extern void ml_table_layout_add_row (ml_table_layout);
 107 extern void ml_table_layout_set_colspan (ml_table_layout, int row, int col, int colspan);
 108 extern void ml_table_layout_set_rowspan (ml_table_layout, int row, int col, int rowspan);
 109 extern void ml_table_layout_set_align (ml_table_layout, int row, int col, const char *align);
 110 extern void ml_table_layout_set_valign (ml_table_layout, int row, int col, const char *valign);
 111 extern void ml_table_layout_set_class (ml_table_layout, int row, int col, const char *clazz);
 112 extern void ml_table_layout_set_header (ml_table_layout, int row, int col, int is_header);
 113
 114 #endif /* ML_TABLE_LAYOUT_H */