src/ml_tabbed_layout.h

   1 /* Monolith tabbed 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_tabbed_layout.h,v 1.1 2002/11/13 20:46:38 rich Exp $
  19  */
  20
  21 #ifndef ML_TABBED_LAYOUT_H
  22 #define ML_TABBED_LAYOUT_H
  23
  24 #include <ml_widget.h>
  25
  26 struct ml_tabbed_layout;
  27 typedef struct ml_tabbed_layout *ml_tabbed_layout;
  28
  29 /* Function: new_ml_tabbed_layout - monolith tabbed layout ("dialog") widget
  30  * Function: ml_tabbed_layout_push_back
  31  * Function: ml_tabbed_layout_pop_back
  32  * Function: ml_tabbed_layout_push_front
  33  * Function: ml_tabbed_layout_pop_front
  34  * Function: ml_tabbed_layout_get
  35  * Function: ml_tabbed_layout_insert
  36  * Function: ml_tabbed_layout_replace
  37  * Function: ml_tabbed_layout_erase
  38  * Function: ml_tabbed_layout_clear
  39  * Function: ml_tabbed_layout_size
  40  * Function: ml_tabbed_layout_pack
  41  * Function: ml_tabbed_layout_bring_to_front
  42  * Function: ml_tabbed_layout_send_to_back
  43  * Function: ml_tabbed_layout_get_front_tab
  44  *
  45  * This is the tabbed layout widget (often called a "tabbed dialog"). It
  46  * displays a row of tabs along the top, allowing the user to select one
  47  * of several widgets in the main area. The tabs have a three-dimensional
  48  * appearance, giving the effect of multiple layers of widgets, similar
  49  * to a card index.
  50  *
  51  * The monolith tabbed layout widget has some intentional limitations.
  52  * First, and foremost, it only supports a small number of tabs. This
  53  * is for good usability reasons (see, for instance, this page:
  54  * @code{http://www.iarchitect.com/tabs.htm} ). If you want to have
  55  * a widget with a large number of tabs, then a better approach is
  56  * to use a tree which selects a widget (refer to the classic
  57  * Netscape Navigator preferences window for an example).
  58  * Secondly, the tabs may only appear at the top of the page.
  59  *
  60  * @code{new_ml_tabbed_layout} creates a new, empty tabbed layout widget.
  61  *
  62  * Underlying the tabbed layout is a simple c2lib vector, and the
  63  * main access functions uses a similar notation to the equivalent
  64  * c2lib @code{vector_*} functions. The exception is that each tab
  65  * also has a @code{name} field, which is what is displayed on the
  66  * tab itself. Go to the SEE ALSO section below
  67  * to see how to manipulate widgets within the tabbed layout.
  68  *
  69  * @code{ml_tabbed_layout_pack} is equivalent to
  70  * @code{ml_tabbed_layout_push_back}: it appends the widget to the end
  71  * of the current vector of widgets.
  72  *
  73  * Any tab added is always added at the bottom of the pile.
  74  *
  75  * In left-to-right locales, the tabs appear in the same order that
  76  * they are pushed into the vector.
  77  *
  78  * There are two further operations which can be carried out on
  79  * tabs. The @code{ml_tabbed_layout_bring_to_front} function
  80  * takes a tab index (ie. leftmost tab is 0, etc.) and brings that
  81  * tab to the front or top of the pile. The
  82  * @code{ml_tabbed_layout_send_to_back} function takes a tab
  83  * index and sends that tab to the back or bottom of the pile.
  84  * The user may also bring tabs to the front by clicking on them.
  85  * @code{ml_tabbed_layout_get_front_tab} returns the index of
  86  * the tab which is currently on top (hence of the widget which
  87  * is currently displayed, since all other widgets will be hidden).
  88  *
  89  * See also: @ref{vector_push_back(3)}, @ref{vector_pop_back(3)},
  90  * @ref{vector_push_front(3)}, @ref{vector_pop_front(3)},
  91  * @ref{vector_get(3)}, @ref{vector_insert(3)}, @ref{vector_replace(3)},
  92  * @ref{vector_erase(3)}, @ref{vector_clear(3)}, @ref{vector_size(3)}.
  93  */
  94 extern ml_tabbed_layout new_ml_tabbed_layout (pool pool);
  95 extern void ml_tabbed_layout_push_back (ml_tabbed_layout, const char *name, ml_widget);
  96 extern ml_widget ml_tabbed_layout_pop_back (ml_tabbed_layout);
  97 extern void ml_tabbed_layout_push_front (ml_tabbed_layout, const char *name, ml_widget);
  98 extern ml_widget ml_tabbed_layout_pop_front (ml_tabbed_layout);
  99 extern ml_widget ml_tabbed_layout_get (ml_tabbed_layout, int i);
 100 extern void ml_tabbed_layout_insert (ml_tabbed_layout, int i, const char *name, ml_widget);
 101 extern void ml_tabbed_layout_replace (ml_tabbed_layout, int i, const char *name, ml_widget);
 102 extern void ml_tabbed_layout_erase (ml_tabbed_layout, int i);
 103 extern void ml_tabbed_layout_clear (ml_tabbed_layout);
 104 extern int ml_tabbed_layout_size (ml_tabbed_layout);
 105 extern void ml_tabbed_layout_pack (ml_tabbed_layout, const char *name, ml_widget);
 106 extern void ml_tabbed_layout_bring_to_front (ml_tabbed_layout, int i);
 107 extern void ml_tabbed_layout_send_to_back (ml_tabbed_layout, int i);
 108 extern int ml_tabbed_layout_get_front_tab (ml_tabbed_layout);
 109
 110 #endif /* ML_TABBED_LAYOUT_H */