1 /* Monolith tabbed layout class.
2 * - by Richard W.M. Jones <rich@annexia.org>
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.
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.
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.
18 * $Id: ml_tabbed_layout.h,v 1.1 2002/11/13 20:46:38 rich Exp $
21 #ifndef ML_TABBED_LAYOUT_H
22 #define ML_TABBED_LAYOUT_H
24 #include <ml_widget.h>
26 struct ml_tabbed_layout;
27 typedef struct ml_tabbed_layout *ml_tabbed_layout;
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
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
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.
60 * @code{new_ml_tabbed_layout} creates a new, empty tabbed layout widget.
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.
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.
73 * Any tab added is always added at the bottom of the pile.
75 * In left-to-right locales, the tabs appear in the same order that
76 * they are pushed into the vector.
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).
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)}.
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);
110 #endif /* ML_TABBED_LAYOUT_H */