mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
cf5f3fbca2
fltk/FL/Fl_Tree.H
Greg Ercolano 205570d134 Fl_Tree documentation fixes for html/pdf, doxygen 1.8.5 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@13008 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
2018-08-06 18:04:46 +00:00

493 lines
19 KiB
C++
Raw Blame History

//
// "$Id$"
//
#ifndef FL_TREE_H
#define FL_TREE_H
#include <FL/Fl.H>
#include <FL/Fl_Group.H>
#include <FL/Fl_Scrollbar.H>
#include <FL/fl_draw.H>
#include <FL/Fl_Tree_Item.H>
#include <FL/Fl_Tree_Prefs.H>
//////////////////////
// FL/Fl_Tree.H
//////////////////////
//
// Fl_Tree -- This file is part of the Fl_Tree widget for FLTK
// Copyright (C) 2009-2010 by Greg Ercolano.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file. If this
// file is missing or damaged, see the license at:
//
// http://www.fltk.org/COPYING.php
//
// Please report all bugs and problems on the following page:
//
// http://www.fltk.org/str.php
//
///
/// \file
/// \brief This file contains the definitions of the Fl_Tree class
///
/** \class Fl_Tree
\brief Tree widget.
\image html tree-simple.png "Fl_Tree example program"
\image latex tree-simple.png "Fl_Tree example program" width=4cm
\code
Fl_Tree // Top level widget
|--- Fl_Tree_Item // Items in the tree
|--- Fl_Tree_Prefs // Preferences for the tree
|--- Fl_Tree_Connector (enum) // Connection modes
|--- Fl_Tree_Select (enum) // Selection modes
|--- Fl_Tree_Sort (enum) // Sort behavior
\endcode
Similar to Fl_Browser, Fl_Tree is a browser of Fl_Tree_Item's arranged
in a parented hierarchy, or 'tree'. Subtrees can be expanded or closed.
Items can be added, deleted, inserted, sorted and re-ordered.
The tree items may also contain other FLTK widgets, like buttons, input fields,
or even "custom" widgets.
The callback() is invoked depending on the value of when():
- FL_WHEN_RELEASE -- callback invoked when left mouse button is released on an item
- FL_WHEN_CHANGED -- callback invoked when left mouse changes selection state
The simple way to define a tree:
\par
\code
#include <FL/Fl_Tree.H>
[..]
Fl_Tree tree(X,Y,W,H);
tree.begin();
tree.add("Flintstones/Fred");
tree.add("Flintstones/Wilma");
tree.add("Flintstones/Pebbles");
tree.add("Simpsons/Homer");
tree.add("Simpsons/Marge");
tree.add("Simpsons/Bart");
tree.add("Simpsons/Lisa");
tree.end();
\endcode
\par FEATURES
Items can be added with add(),<BR>
removed with remove(),<BR>
completely cleared with clear(),<BR>
inserted with insert() and insert_above(),<BR>
selected/deselected with select() and deselect(),<BR>
open/closed with open() and close(),<BR>
positioned on the screen with show_item_top(), show_item_middle() and
show_item_bottom(),<BR>
item children can be swapped around with Fl_Tree_Item::swap_children(),<BR>
items can be moved around with Fl_Tree_Item::move(),<BR>
an item's children can be walked with Fl_Tree_Item::first() and Fl_Tree_Item::next(),
an item's children can be indexed directly with Fl_Tree_Item::child()
and Fl_Tree_Item::children(),<BR>
items can be moved from one subtree to another with Fl_Tree_Item::deparent()
and Fl_Tree_Item::reparent(),<BR>
sorting can be controlled when items are add()ed via sortorder().<BR>
You can walk the entire tree with first() and next().<BR>
You can walk visible items with first_visible_item()
and next_visible_item().<BR>
You can walk selected items with first_selected_item() and
next_selected_item().<BR>
Items can be found by their pathname using find_item(const char*),
and an item's pathname can be found with item_pathname().<BR>
The selected items' colors are controlled by selection_color()
(inherited from Fl_Widget).<BR>
A hook is provided to allow you to redefine how item's labels are drawn
via Fl_Tree::item_draw_callback().<BR>
\par SELECTION OF ITEMS
The tree can have different selection behaviors controlled by selectmode().
The background color used for selected items is the Fl_Tree::selection_color().
The foreground color for selected items is controlled internally with fl_contrast().
\par CHILD WIDGETS
FLTK widgets (including custom widgets) can be assigned to tree items via
Fl_Tree_Item::widget().
\par
When an Fl_Tree_Item::widget() is defined, the default behavior is for the
widget() to be shown in place of the item's label (if it has one).
Only the widget()'s width will be used; the widget()'s x() and y() position
will be managed by the tree, and the h() will track the item's height.
This default behavior can be altered (ABI 1.3.1):
Setting Fl_Tree::item_draw_mode()'s FL_TREE_ITEM_DRAW_LABEL_AND_WIDGET flag
causes the label + widget to be displayed together in that order, and
adding the FL_TREE_ITEM_HEIGHT_FROM_WIDGET flag causes widget's height
to define the widget()'s height.
\par ICONS
The tree's open/close icons can be redefined with
Fl_Tree::openicon(), Fl_Tree::closeicon(). User icons
can either be changed globally with Fl_Tree::usericon(),
or on a per-item basis with Fl_Tree_Item::usericon().
\par
Various default preferences can be globally manipulated via Fl_Tree_Prefs,
including colors, margins, icons, connection lines, etc.
\par FONTS AND COLORS
When adding new items to the tree, the new items get the
defaults for fonts and colors from:
\par
- Fl_Tree::item_labelfont() -- The default item label font (default: FL_HELVETICA)
- Fl_Tree::item_labelsize() -- The default item label size (default: FL_NORMAL_SIZE)
- Fl_Tree::item_labelfgcolor() -- The default item label foreground color (default: FL_FOREGROUND_COLOR)
- Fl_Tree::item_labelbgcolor() -- The default item label background color (default: 0xffffffff, which tree uses as 'transparent')
\par
Each item (Fl_Tree_Item) inherits a copy of these font/color attributes when created,
and each item has its own methods to let the app change these values on a per-item basis
using methods of the same name:
\par
- Fl_Tree_Item::labelfont() -- The item's label font (default: FL_HELVETICA)
- Fl_Tree_Item::labelsize() -- The item's label size (default: FL_NORMAL_SIZE)
- Fl_Tree_Item::labelfgcolor() -- The item's label foreground color (default: FL_FOREGROUND_COLOR)
- Fl_Tree_Item::labelbgcolor() -- The item's label background color (default: 0xffffffff, which uses the tree's own bg color)
\par CALLBACKS
The tree's callback() will be invoked when items change state or are open/closed.
when() controls when mouse/keyboard events invoke the callback.
callback_item() and callback_reason() can be used to determine the cause of the callback. e.g.
\par
\code
void MyTreeCallback(Fl_Widget *w, void *data) {
Fl_Tree *tree = (Fl_Tree*)w;
Fl_Tree_Item *item = (Fl_Tree_Item*)tree->callback_item(); // get selected item
switch ( tree->callback_reason() ) {
case FL_TREE_REASON_SELECTED: [..]
case FL_TREE_REASON_DESELECTED: [..]
case FL_TREE_REASON_RESELECTED: [..]
case FL_TREE_REASON_OPENED: [..]
case FL_TREE_REASON_CLOSED: [..]
}
:
}
\endcode
\par SIMPLE EXAMPLES
To find all the selected items:
\par
\code
for ( Fl_Tree_Item *i=first_selected_item(); i; i=next_selected_item(i) )
printf("Item %s is selected\n", i->label());
\endcode
\par
To get an item's full menu pathname, use Fl_Tree::item_pathname(), e.g.
\par
\code
[..]
char pathname[256] = "???";
tree->item_pathname(pathname, sizeof(pathname), item); // eg. "Parent/Child/Item"
[..]
\endcode
\par
To walk all the items of the tree from top to bottom:
\par
\code
// Walk all the items in the tree, and print their labels
for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
printf("Item: %s\n", item->label());
}
\endcode
\par
To recursively walk all the children of a particular item,
define a function that uses recursion:
\par
\code
// Find all of the item's children and print an indented report of their labels
void my_print_all_children(Fl_Tree_Item *item, int indent=0) {
for ( int t=0; t<item->children(); t++ ) {
printf("%*s Item: %s\n", indent, "", item->child(t)->label());
my_print_all_children(item->child(t), indent+4); // recurse
}
}
\endcode
\par
To change the default label font and color when creating new items:
\par
\code
tree = new Fl_Tree(..);
tree->item_labelfont(FL_COURIER); // Use Courier font for all new items
tree->item_labelfgcolor(FL_RED); // Use red color for labels of all new items
[..]
// Now create the items in the tree using the above defaults.
tree->add("Aaa");
tree->add("Bbb");
\endcode
\par
To change the font and color of all existing items in the tree:
\par
\code
// Change the font and color of all items currently in the tree
for ( Fl_Tree_Item *item = tree->first(); item; item = tree->next(item) ) {
item->labelfont(FL_COURIER);
item->labelcolor(FL_RED);
}
\endcode
\par DISPLAY DESCRIPTION
The following image shows the tree's various visual elements
and the methods that control them:
\par
\image html tree-elements.png
\image latex tree-elements.png "Fl_Tree elements" width=6cm
\par
The following shows the protected dimension variables 'tree inner' (tix..)
and 'tree outer' (tox..):
\image html tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
\image latex tree-dimensions.png "Fl_Tree inner/outer dimensions" width=6cm
\par KEYBOARD BINDINGS
The following table lists keyboard bindings for navigating the tree:
\par
Keyboard | FL_TREE_SELECT_MULTI | FL_TREE_SELECT_SINGLE | FL_TREE_SELECT_NONE |
------------------------|-----------------------------|-----------------------------|-----------------------------|
Ctrl-A (Linux/Windows) | Select all items | N/A | N/A |
Command-A (Mac) | Select all items | N/A | N/A |
Space | Selects item | Selects item | N/A |
Ctrl-Space | Toggle item | Toggle item | N/A |
Shift-Space | Extends selection | Selects item | N/A |
Enter | Toggles open/close | Toggles open/close | Toggles open/close |
Ctrl-Enter | Toggles open/close | Toggles open/close | Toggles open/close |
Shift-Enter | Toggles open/close | Toggles open/close | Toggles open/close |
Right / Left | Open/Close item | Open/Close item | Open/Close item |
Up / Down | Move focus box up/down | Move focus box up/down | N/A |
Shift-Up / Shift-Down | Extend selection up/down | Move focus up/down | N/A |
Home / End | Move to top/bottom of tree | Move to top/bottom of tree | Move to top/bottom of tree |
PageUp / PageDown | Page up/down | Page up/down | Page up/down |
*/
/// \enum Fl_Tree_Reason
/// The reason the callback was invoked.
///
enum Fl_Tree_Reason {
FL_TREE_REASON_NONE=0, ///< unknown reason
FL_TREE_REASON_SELECTED, ///< an item was selected
FL_TREE_REASON_DESELECTED, ///< an item was de-selected
FL_TREE_REASON_RESELECTED, ///< an item was re-selected (e.g. double-clicked)
FL_TREE_REASON_OPENED, ///< an item was opened
FL_TREE_REASON_CLOSED, ///< an item was closed
FL_TREE_REASON_DRAGGED ///< an item was dragged into a new place
};
class FL_EXPORT Fl_Tree : public Fl_Group {
friend class Fl_Tree_Item;
Fl_Tree_Item *_root; // can be null!
Fl_Tree_Item *_item_focus; // item that has focus box
Fl_Tree_Item *_callback_item; // item invoked during callback (can be NULL)
Fl_Tree_Reason _callback_reason; // reason for the callback
Fl_Tree_Prefs _prefs; // all the tree's settings
int _scrollbar_size; // size of scrollbar trough
Fl_Tree_Item *_lastselect;
void fix_scrollbar_order();
protected:
Fl_Scrollbar *_vscroll; ///< Vertical scrollbar
Fl_Scrollbar *_hscroll; ///< Horizontal scrollbar
int _tox,_toy,_tow,_toh; ///< Tree widget outer xywh dimension: outside scrollbars, inside widget border
int _tix,_tiy,_tiw,_tih; ///< Tree widget inner xywh dimension: inside borders + scrollbars
/// the calculated width of the entire tree hierarchy. See calc_tree()
int _tree_w;
/// the calculated height of the entire tree hierarchy. See calc_tree()
int _tree_h;
void item_clicked(Fl_Tree_Item* val);
void do_callback_for_item(Fl_Tree_Item* item, Fl_Tree_Reason reason);
// next_visible_item() and extend_selection() moved to 'public' in ABI 1.3.3
// undocmented draw_tree() dropped -- draw() does all the work now
public:
Fl_Tree(int X, int Y, int W, int H, const char *L=0);
~Fl_Tree();
int handle(int e);
void draw();
void show_self();
void resize(int,int,int,int);
///////////////////////
// root methods
///////////////////////
void root_label(const char *new_label);
Fl_Tree_Item* root();
void root(Fl_Tree_Item *newitem);
const Fl_Tree_Prefs& prefs() const { return _prefs; }
////////////////////////////////
// Item creation/removal methods
////////////////////////////////
Fl_Tree_Item *add(const char *path, Fl_Tree_Item *newitem=0);
Fl_Tree_Item* add(Fl_Tree_Item *parent_item, const char *name);
Fl_Tree_Item *insert_above(Fl_Tree_Item *above, const char *name);
Fl_Tree_Item* insert(Fl_Tree_Item *item, const char *name, int pos);
int remove(Fl_Tree_Item *item);
void clear();
void clear_children(Fl_Tree_Item *item);
////////////////////////
// Item lookup methods
////////////////////////
Fl_Tree_Item *find_item(const char *path);
const Fl_Tree_Item *find_item(const char *path) const;
int item_pathname(char *pathname, int pathnamelen, const Fl_Tree_Item *item) const;
const Fl_Tree_Item* find_clicked(int yonly=0) const;
Fl_Tree_Item* find_clicked(int yonly=0);
Fl_Tree_Item *item_clicked();
Fl_Tree_Item *first();
Fl_Tree_Item *first_visible(); // deprecated in ABI 10303
Fl_Tree_Item *first_visible_item();
Fl_Tree_Item *next(Fl_Tree_Item *item=0);
Fl_Tree_Item *prev(Fl_Tree_Item *item=0);
Fl_Tree_Item *last();
Fl_Tree_Item *last_visible(); // deprecated in ABI 10303
Fl_Tree_Item *last_visible_item();
Fl_Tree_Item *next_visible_item(Fl_Tree_Item *start, int dir); // made public in 1.3.3 ABI
Fl_Tree_Item *first_selected_item();
Fl_Tree_Item *last_selected_item();
Fl_Tree_Item *next_item(Fl_Tree_Item *item, int dir=FL_Down, bool visible=false);
Fl_Tree_Item *next_selected_item(Fl_Tree_Item *item=0, int dir=FL_Down);
int get_selected_items(Fl_Tree_Item_Array &items);
//////////////////////////
// Item open/close methods
//////////////////////////
int open(Fl_Tree_Item *item, int docallback=1);
int open(const char *path, int docallback=1);
void open_toggle(Fl_Tree_Item *item, int docallback=1);
int close(Fl_Tree_Item *item, int docallback=1);
int close(const char *path, int docallback=1);
int is_open(Fl_Tree_Item *item) const;
int is_open(const char *path) const;
int is_close(Fl_Tree_Item *item) const;
int is_close(const char *path) const;
/////////////////////////
// Item selection methods
/////////////////////////
int select(Fl_Tree_Item *item, int docallback=1);
int select(const char *path, int docallback=1);
void select_toggle(Fl_Tree_Item *item, int docallback=1);
int deselect(Fl_Tree_Item *item, int docallback=1);
int deselect(const char *path, int docallback=1);
int deselect_all(Fl_Tree_Item *item=0, int docallback=1);
int select_only(Fl_Tree_Item *selitem, int docallback=1);
int select_all(Fl_Tree_Item *item=0, int docallback=1);
int extend_selection_dir(Fl_Tree_Item *from,
Fl_Tree_Item *to,
int dir,
int val,
bool visible);
int extend_selection(Fl_Tree_Item *from,
Fl_Tree_Item *to,
int val=1,
bool visible=false);
void set_item_focus(Fl_Tree_Item *item);
Fl_Tree_Item *get_item_focus() const;
int is_selected(Fl_Tree_Item *item) const;
int is_selected(const char *path);
/////////////////////////////////
// Item attribute related methods
/////////////////////////////////
Fl_Font item_labelfont() const;
void item_labelfont(Fl_Font val);
Fl_Fontsize item_labelsize() const;
void item_labelsize(Fl_Fontsize val);
Fl_Color item_labelfgcolor(void) const;
void item_labelfgcolor(Fl_Color val);
Fl_Color item_labelbgcolor(void) const;
void item_labelbgcolor(Fl_Color val);
Fl_Color connectorcolor() const;
void connectorcolor(Fl_Color val);
int marginleft() const;
void marginleft(int val);
int margintop() const;
void margintop(int val);
int marginbottom() const;
void marginbottom(int val);
int linespacing() const;
void linespacing(int val);
int openchild_marginbottom() const;
void openchild_marginbottom(int val);
int usericonmarginleft() const;
void usericonmarginleft(int val);
int labelmarginleft() const;
void labelmarginleft(int val);
int widgetmarginleft() const;
void widgetmarginleft(int val);
int connectorwidth() const;
void connectorwidth(int val);
Fl_Image* usericon() const;
void usericon(Fl_Image *val);
Fl_Image* openicon() const;
void openicon(Fl_Image *val);
Fl_Image* closeicon() const;
void closeicon(Fl_Image *val);
int showcollapse() const;
void showcollapse(int val);
int showroot() const;
void showroot(int val);
Fl_Tree_Connector connectorstyle() const;
void connectorstyle(Fl_Tree_Connector val);
Fl_Tree_Sort sortorder() const;
void sortorder(Fl_Tree_Sort val);
Fl_Boxtype selectbox() const;
void selectbox(Fl_Boxtype val);
Fl_Tree_Select selectmode() const;
void selectmode(Fl_Tree_Select val);
Fl_Tree_Item_Reselect_Mode item_reselect_mode() const;
void item_reselect_mode(Fl_Tree_Item_Reselect_Mode mode);
Fl_Tree_Item_Draw_Mode item_draw_mode() const;
void item_draw_mode(Fl_Tree_Item_Draw_Mode mode);
void item_draw_mode(int mode);
void calc_dimensions();
void calc_tree();
void recalc_tree();
int displayed(Fl_Tree_Item *item);
void show_item(Fl_Tree_Item *item, int yoff);
void show_item(Fl_Tree_Item *item);
void show_item_top(Fl_Tree_Item *item);
void show_item_middle(Fl_Tree_Item *item);
void show_item_bottom(Fl_Tree_Item *item);
void display(Fl_Tree_Item *item);
int vposition() const;
void vposition(int pos);
int hposition() const;
void hposition(int pos);
int is_scrollbar(Fl_Widget *w);
int scrollbar_size() const;
void scrollbar_size(int size);
int is_vscroll_visible() const;
int is_hscroll_visible() const;
///////////////////////
// callback related
///////////////////////
void callback_item(Fl_Tree_Item* item);
Fl_Tree_Item* callback_item();
void callback_reason(Fl_Tree_Reason reason);
Fl_Tree_Reason callback_reason() const;
/// Load FLTK preferences
void load(class Fl_Preferences&);
};
#endif /*FL_TREE_H*/
//
// End of "$Id$".
//
Reference in New Issue View Git Blame Copy Permalink