From a973a183a73730c10d01efd7536cd5d425eaaad0 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Sun, 23 Mar 2014 17:36:59 +0000 Subject: Added docs to Fl_Tabs as per STR#1174, and some doc improvements. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@10120 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Tabs.H | 126 +++++++++++++++++++++++++++++------ documentation/src/tabs_default.png | Bin 0 -> 1054 bytes documentation/src/tabs_selection.png | Bin 0 -> 1127 bytes documentation/src/tabs_uniform.png | Bin 0 -> 1199 bytes 4 files changed, 106 insertions(+), 20 deletions(-) create mode 100644 documentation/src/tabs_default.png create mode 100644 documentation/src/tabs_selection.png create mode 100644 documentation/src/tabs_uniform.png diff --git a/FL/Fl_Tabs.H b/FL/Fl_Tabs.H index 7099d5281..b6693210d 100644 --- a/FL/Fl_Tabs.H +++ b/FL/Fl_Tabs.H @@ -49,47 +49,133 @@ gap is larger. It is easiest to lay this out in fluid, using the fluid browser to select each child group and resize them until the tabs look the way you want them to. - + The background area behind and to the right of the tabs is "transparent", exposing the background detail of the parent. The value of Fl_Tabs::box() does not affect this area. So if Fl_Tabs is resized by itself without the parent, force the appropriate parent (visible behind the tabs) to redraw() to prevent artifacts. - Resizing note: when Fl_Tabs is resized vertically, the default - behavior scales the tab's height as well as its children. - To keep the tab height constant during resizing, set the - tab widget's resizable() to one of the tab's children, i.e. - - \code - tabs = new Fl_Tabs(..); - child_a = new Fl_Group(..); - child_b = new Fl_Group(..); - tabs->end(); - tabs->resizable(child_a); // keeps tab height constant - \endcode + See "Resizing Caveats" below on how to keep tab heights constant. + See "Callback's Use Of when()" on how to control the details + of how clicks invoke the callback(). A typical use of the Fl_Tabs widget: + + \par \code + // Typical use of Fl_Tabs Fl_Tabs *tabs = new Fl_Tabs(10,10,300,200); { - Fl_Group *tab1 = new Fl_Group(20,30,280,170,"Tab1"); + Fl_Group *grp1 = new Fl_Group(20,30,280,170,"Tab1"); { ..widgets that go in tab#1.. } - tab1->end(); - Fl_Group *tab2 = new Fl_Group(20,30,280,170,"Tab2"); + grp1->end(); + Fl_Group *grp2 = new Fl_Group(20,30,280,170,"Tab2"); { ..widgets that go in tab#2.. } - tab2->end(); + grp2->end(); } tabs->end(); \endcode - In the above, tab1's tab can be made red by using tab1->selection_color(FL_RED); - and tab1's text can be made bold by tab1->labelfont(FL_HELVETICA_BOLD), - and can be made 'engraved' by tab1->labeltype(FL_ENGRAVED_LABEL); + \b Default \b Appearance + + The appearance of each "tab" is taken from the label() and color() of the + child group corresponding to that "tab" and panel. Where the "tabs" appear + depends on the position and size of the child groups that make up the + panels within the Fl_Tab, i.e. whether there is more space above or + below them. The height of the "tabs" depends on how much free space + is available. + + \image html tabs_default.png "Fl_Tabs Default Appearance" + \image latex tabs_default.png "Fl_Tabs Default Appearance" width=8cm + + \b Highlighting \b The \b Selected \b Tab + + The selected "tab" can be highlighted further by setting the + selection_color() of the Fl_Tab itself, e.g. + + \par + \code + .. + tabs = new Fl_Tabs(..); + tabs->selection_color(FL_DARK3); + .. + \endcode + + The result of the above looks like: + \image html tabs_selection.png "Highlighting the selected tab" + \image latex tabs_selection.png "Highlighting the selected tab" width=8cm + + \b Uniform \b Tab \b and \b Panel \b Appearance + + In order to have uniform tab and panel appearance, not only must the color() + and selection_color() for each child group be set, but also the + selection_color() of the Fl_Tab itself any time a new "tab" is selected. + This can be achieved within the Fl_Tab callback, e.g. + + \par + \code + void MyTabCallback(Fl_Widget *w, void*) { + Fl_Tabs *tabs = (Fl_Tabs*)w; + // When tab changed, make sure it has same color as its group + tabs->selection_color( (tab->value())->color() ); + } + .. + int main(..) { + // Define tabs widget + tabs = new Fl_Tabs(..); + tabs->callback(MyTabCallback); + + // Create three tabs each colored differently + grp1 = new Fl_Group(.. "One"); + grp1->color(9); + grp1->selection_color(9); + grp1->end(); + + grp2 = new Fl_Group(.. "Two"); + grp2->color(10); + grp2->selection_color(10); + grp2->end(); + + grp3 = new Fl_Group(.. "Three"); + grp3->color(14); + grp3->selection_color(14); + grp3->end(); + .. + // Make sure default tab has same color as its group + tabs->selection_color( (tab->value())->color() ); + .. + return Fl::run(); + } + \endcode + + The result of the above looks like: + \image html tabs_uniform.png "Fl_Tabs with uniform colors" + \image latex tabs_uniform.png "Fl_Tabs with uniform colors" width=8cm + + \b Resizing \b Caveats + + When Fl_Tabs is resized vertically, the default behavior scales the + tab's height as well as its children. To keep the tab height constant + during resizing, set the tab widget's resizable() to one of the tab's + child groups, i.e. + + \par + \code + tabs = new Fl_Tabs(..); + grp1 = new Fl_Group(..); + .. + grp2 = new Fl_Group(..); + .. + tabs->end(); + tabs->resizable(grp1); // keeps tab height constant + \endcode + + \par Callback's Use Of when() As of FLTK 1.3.3, Fl_Tabs() supports the following flags for when(): diff --git a/documentation/src/tabs_default.png b/documentation/src/tabs_default.png new file mode 100644 index 000000000..6ba92308d Binary files /dev/null and b/documentation/src/tabs_default.png differ diff --git a/documentation/src/tabs_selection.png b/documentation/src/tabs_selection.png new file mode 100644 index 000000000..80b74e5f2 Binary files /dev/null and b/documentation/src/tabs_selection.png differ diff --git a/documentation/src/tabs_uniform.png b/documentation/src/tabs_uniform.png new file mode 100644 index 000000000..1c37af58d Binary files /dev/null and b/documentation/src/tabs_uniform.png differ -- cgit v1.2.3