Inherits fltk::Menu.
Inherited by fltk::ComboBrowser, fltk::FileBrowser, and fltk::MultiBrowser.
Classes | |
class | Mark |
Public Types | |
enum | { IS_MULTI = 1, NORMAL = GROUP_TYPE, MULTI = GROUP_TYPE+1 } |
enum | { NO_COLUMN_SELECTED = -1 } |
enum | linepos { NOSCROLL, TOP, MIDDLE, BOTTOM } |
Public Member Functions | |
bool | at_mark (const Mark &mark) const |
void | bottomline (int line) |
int | box_height () const |
int | box_width () const |
Browser (int X, int Y, int W, int H, const char *l=0) | |
const char ** | column_labels () const |
void | column_labels (const char **pLabels) |
void | column_widths (const int *pWidths) |
const int * | column_widths () const |
int | compare_to_mark (const Mark &mark) const |
const int * | current_index () const |
int | current_level () const |
int | current_position () const |
void | damage_item (const Mark &) |
void | damage_item () |
bool | deselect (int do_callback=0) |
bool | display (int line, bool value=true) |
bool | display_lines () const |
void | display_lines (bool display) |
bool | displayed (int line) |
void | draw () |
const int * | focus_index () const |
int | focus_level () const |
int | focus_position () const |
Widget * | goto_focus () |
Widget * | goto_index (const int *indexes, unsigned level) |
Widget * | goto_index (int) |
Widget * | goto_index (int, int, int=-1, int=-1, int=-1) |
Widget * | goto_mark (const Mark &) |
Widget * | goto_position (int y) |
Widget * | goto_top () |
const Symbol * | group_symbol () const |
void | group_symbol (const Symbol *s) |
int | handle (int) |
Widget * | header (int col) |
int | height () const |
bool | indented () const |
void | indented (bool v) |
int | item_h () const |
bool | item_is_open () const |
bool | item_is_parent () const |
bool | item_is_visible () const |
void | layout () |
const Symbol * | leaf_symbol () const |
void | leaf_symbol (const Symbol *s) |
int | load (const char *filename) |
bool | make_item_visible (linepos=NOSCROLL) |
void | middleline (int line) |
int | multi () const |
Widget * | next () |
Widget * | next_visible () |
int | nheader () const |
Widget * | previous_visible () |
bool | select (int line, bool value=true) |
bool | select (Widget *e, int val, int do_callback=0) |
bool | select_only_this (int do_callback=0) |
bool | selected (int line) |
int | selected_column () |
int | set_column_start (int column, int x) |
bool | set_focus () |
bool | set_item_opened (bool) |
bool | set_item_selected (bool value=true, int do_callback=0) |
bool | set_item_visible (bool) |
void | set_mark (Mark &dest) const |
void | set_mark_to_focus (Mark &dest) const |
int | topline () const |
void | topline (int line) |
int | value () const |
void | value (int v) |
int | width () const |
int | xposition () const |
void | xposition (int) |
int | yposition () const |
void | yposition (int) |
~Browser () | |
Public Attributes | |
Scrollbar | hscrollbar |
The horizontal scrollbar. | |
Scrollbar | scrollbar |
The vertical scrollbar. | |
Static Public Attributes | |
static NamedStyle * | default_style = &::style |
Protected Member Functions | |
void | handle_callback (int doit) |
Private Types | |
enum | { NUM_REDRAW = 2 } |
Private Member Functions | |
void | clear_belowmouse () |
void | draw_clip (const Rectangle &) |
void | draw_item (int) |
Widget * | goto_visible_focus () |
void | set_belowmouse () |
void | set_level (unsigned) |
Static Private Member Functions | |
static void | column_click_cb_ (Widget *, void *) |
static void | draw_clip_cb (void *, const Rectangle &) |
static void | hscrollbar_cb (Widget *, void *) |
static void | scrollbar_cb (Widget *, void *) |
Private Attributes | |
Mark | BELOWMOUSE |
The Mark that's below the mouse. | |
const char ** | column_labels_ |
The labels to be used across the top of the Browser. | |
const int * | column_widths_ |
Original column widths. | |
int * | column_widths_i |
Original column widths after user interaction. | |
int * | column_widths_p |
Actual column widths. | |
bool | displaylines_ |
Flag to determine whether or not to draw lines. | |
Mark | FIRST_VISIBLE |
The first visible item. | |
Mark | FOCUS |
The item that has focus. | |
const Symbol * | group_symbol_ |
The symbol used to draw parent items. | |
Widget ** | header_ |
The set of widgets heading each column. | |
int | height_ |
The height of all the visible items. | |
Mark | HERE |
The current item. | |
bool | indented_ |
Flag to determine whether or not to draw + symbols. | |
Rectangle | interior |
A Rectangle representing the area inside box edges and scrollbars. | |
const Symbol * | leaf_symbol_ |
The symbol used to draw child items. | |
int | nColumn |
The amount of columns. | |
int | nHeader |
The amount of widgets heading each column. | |
Mark | OPEN |
The item that has been opened. | |
Mark | REDRAW [NUM_REDRAW] |
An array of Marks that need to be redrawn on the next call to redraw() | |
int | scrolldx |
The amount the user has scrolled horizontally since the last redraw. | |
int | scrolldy |
The amount the user has scrolled vertically since the last redraw. | |
int | selected_column_ |
The index of the currently selected column. | |
int | siblings |
Number of children of the parent of the HERE item. | |
int | width_ |
The width of the longest item in the browser. | |
int | xposition_ |
The horizontal scrolling position. | |
int | yposition_ |
The vertical scrolling position. |
Displays a scrolling vertical list of text widgets, possibly with a hierarchical arrangement, and lets the user select one of them.
The items may be created as child widgets (usually the same widgets as are used to create menus: fltk::Item widgets, or fltk::ItemGroup widgets to make a hierarchy).
All the functions used to add, remove, or modify items in the list are defined by the base class fltk::Menu. See that for much more information. For a simple constant list you can populate the list by calling browser->add("text of item") once for each item.
You can also us an fltk::List which allows you to control the storage by dynamically creating a temporary "fake" widget for the browser to use each time it wants to look at or draw an item. This is useful for creating browsers with hundreds of thousands of items, or when the set of items changes rapidly.
If you give the browser a callback you can find out what item was selected with value(), the first item is zero (this is different from older versions of fltk that started at 1!), and will be negative if no item is selected. You can change the selected item with value(new_value).
The subclass fltk::MultiBrowser lets the user select more than one item at the same time.
The callback() is done when the user changes the selected items or when they open/close parents. In addition, if the user double-clicks a non-parent item, then it is "executed" which usually means that the callback() on the item itself is run. However, if no callback has been set on the item, the callback() of this widget is called with the user_data() of the item.
You can control when callbacks are done with the when() method. The following values are useful, the default value is fltk::WHEN_CHANGED.
anonymous enum |
anonymous enum |
anonymous enum [private] |
Argument to make_item_visible()
Browser::Browser | ( | int | X, |
int | Y, | ||
int | W, | ||
int | H, | ||
const char * | L = 0 |
||
) |
The constructor makes an empty browser.
Browser::~Browser | ( | ) |
The destructor deletes all the list items (because they are child fltk::Widgets of an fltk::Group) and destroys the browser.
bool fltk::Browser::at_mark | ( | const Mark & | mark | ) | const [inline] |
void Browser::bottomline | ( | int | line | ) | [inline] |
Convenience function for non-hierarchial browsers.
line | Make the indexed item visible and scroll to put it at the bottom of the browser. |
int Browser::box_height | ( | ) | const [inline] |
If this is changed (by resizing the widget, adding or deleting items or opening or closing a parent item such that the scrollbar visibility changes) then layout() must be called before this is correct.
int Browser::box_width | ( | ) | const [inline] |
If this is changed (by resizing the widget, adding or deleting items or opening or closing a parent item such that the scrollbar visibility changes) then layout() must be called before this is correct.
void Browser::clear_belowmouse | ( | ) | [private] |
Indicates that nothing should be highlighted
void Browser::column_click_cb_ | ( | Widget * | ww, |
void * | d | ||
) | [static, private] |
The callback that is triggered when the user clicks on a column header
ww | The widget that was clicked on |
d | An integer representing the index of the column that was clicked, used to trigger the column's callback |
const char** fltk::Browser::column_labels | ( | ) | const [inline] |
void Browser::column_labels | ( | const char ** | t | ) |
Set an array of labels to put at the top of the browser. The initial sizes of them are set with column_widths(). Items in the browser can print into the correct columns by putting '\t' characters into their text. Or they can look at fltk::column_widths() to find the settings from their draw() methods.
t | A const char* array of labels |
void Browser::column_widths | ( | const int * | t | ) |
Sets the horizontal locations that each '\t' character in an item should start printing text at. These are measured from the left edge of the browser, including any area for the open/close + glyphs.
t | A constant integer array, with the 'i'th position representing the width of column i
// Example 1: make three columns, total width of columns is 300 pixels. // Columns are resizable, but total width is kept always. const int widths[] = { 100, 100, 100, 0 }; // Example 2: make three columns, total width of columns is always width of the browser. // Columns are resizable, third column is flexible and will take remaining space left. const int widths[] = { 100, 100, -1, 0 }; |
const int* fltk::Browser::column_widths | ( | ) | const [inline] |
int fltk::Browser::compare_to_mark | ( | const Mark & | mark | ) | const [inline] |
const int * Browser::current_index | ( | ) | const [inline] |
int Browser::current_level | ( | ) | const [inline] |
int Browser::current_position | ( | ) | const [inline] |
You may also want the height, which is in item_h().
void Browser::damage_item | ( | const Mark & | mark | ) |
Set item referenced by this mark as being damaged.
mark | The damaged item being referenced through its Mark |
void Browser::damage_item | ( | ) | [inline] |
Tell the browser to redraw the current item. Do this if you know it has changed appearance. This is better than redrawing the entire browser because it will blink a lot less.
bool Browser::deselect | ( | int | do_callback = 0 | ) |
Turn off current selection of all items in the browser. For the regular Browser, this puts it in a special state where nothing is highlighted and index(0) returns -1. The user cannot get it into this state with the GUI.
For a MultiBrowser the user can get this state by ctrl+clicking the selected items off.
do_callback | If do_callback has some bits that are also in when() then the callback is done for each item that changes selected state. |
bool Browser::display | ( | int | line, |
bool | value = true |
||
) |
Convenience function for non-hierarchial browsers. Make the indexed item be visible() and scroll the browser so it can be seen by the user.
bool Browser::display_lines | ( | ) | const |
Accessor method
void Browser::display_lines | ( | bool | display | ) |
Accessor (set) method which is used to set the value of the "displaylines_" member.
display | If you set display to false it will mean that you do not want lines of the tree to be displayed. |
bool Browser::displayed | ( | int | line | ) |
Convenience function for non-hierarchial browsers.
line | The line this item is on |
void Browser::draw | ( | void | ) | [virtual] |
The standard draw function. See Widget::draw
Reimplemented from fltk::Group.
void Browser::draw_clip | ( | const Rectangle & | r | ) | [private] |
Draws the Browser's clip region
r | The Rectangle representing the clip region |
void Browser::draw_clip_cb | ( | void * | v, |
const Rectangle & | r | ||
) | [static, private] |
void Browser::draw_item | ( | int | damage | ) | [private] |
Draws the current item
damage | If damage is non-zero it draws the left-hand glyphs and OR's that damage into the item. |
const int * Browser::focus_index | ( | ) | const [inline] |
Reimplemented from fltk::Group.
int Browser::focus_level | ( | ) | const [inline] |
int Browser::focus_position | ( | ) | const [inline] |
You may also want the height, which is in
goto_focus(); item_h()
.
Widget * Browser::goto_focus | ( | ) | [inline] |
Sets the item() to the "focus" (the item with the dotted square in an fltk::MultiBrowser, and the selected item in a normal fltk::Browser.
Widget * Browser::goto_index | ( | int | a, |
int | b, | ||
int | c = -1 , |
||
int | d = -1 , |
||
int | e = -1 |
||
) |
Go to an item at any level up to 5. Negative numbers indicate that no more levels should be looked at.
a | The top level index |
b | The child of the top level's index |
c | The child of b's index |
d | The child of c's index |
e | The child of d's index |
Widget * Browser::goto_index | ( | const int * | indexes, |
unsigned | level | ||
) |
Go to a nested item. This sets the current item() to the given item.
and also returns it. If the values are out of range then null is returned.
indexes | An integer array. indexes[0] must contain the index of the top-level item, indexes[1] must contain the index of the child of this top level item relative to the parent, and so on. |
level | The depth of the node to go to (and the length of indexes, + 1) |
A negative number in indexes[0] will make it go into a special no-item state where select_only_this() will do deselect().
Widget * Browser::goto_index | ( | int | i | ) |
Widget * Browser::goto_position | ( | int | Y | ) |
Widget * Browser::goto_top | ( | ) |
Because of the hierarchial structure it is difficult to identify an item in the browser. Instead of passing an identifier to all the calls that can modify an item, the browser provides several calls to set item() based on various rules, and then calls to modify the current item().
This call sets item() to the very first visible widget in the browser. It returns the widget for that item, or null if the browser is empty.
If you have invisible items in the browser you should use goto_index(0) if you want to go to the first item even if it is invisible.
Widget * Browser::goto_visible_focus | ( | ) | [private] |
Sets HERE to the currently focused widget, if it's visible
Go to the focus if it is visible and return it. If it is not visible, go to the top of the visible region and return zero. This is used by keystrokes so the browser does not scroll unexpectedly.
const Symbol* fltk::Browser::group_symbol | ( | ) | const [inline] |
Browser::group_symbol | ( | const Symbol * | s | ) | [inline] |
Sets a default value for image() on each item that is a hierarchy parent. If the parent item has no image() then this one is used for it.
s | The symbol to use for the image |
int Browser::handle | ( | int | event | ) | [virtual] |
The Browser's custom handle function
See Widget::handle
event | The event to be handled |
Reimplemented from fltk::Group.
void fltk::Browser::handle_callback | ( | int | doit | ) | [protected] |
Defines how callbacks are handled in the browser
doit | no idea. This function looks NYI |
Widget * Browser::header | ( | int | col | ) | [inline] |
col | The index of the required column |
int Browser::height | ( | ) | const [inline] |
If this is changed (by adding or deleting items or opening or closing a parent item) then layout() must be called before this is correct.
void Browser::hscrollbar_cb | ( | Widget * | o, |
void * | |||
) | [static, private] |
The callback to move horizontal scrollbar
o | The horizontal Scrollbar |
bool fltk::Browser::indented | ( | ) | const [inline] |
void Browser::indented | ( | bool | v | ) | [inline] |
v | Turn this on to for space to be reserved for open/close boxes drawn to the left of top-level items. You usually want this for a hierarchial browser. This should be off for a flat browser, or to emulate Windows Explorer where "My Computer" does not have an open/close to the left of it. The default value is false. |
int Browser::item_h | ( | ) | const |
Gets the current item's height and calls layout if needed
bool Browser::item_is_open | ( | ) | const |
bool Browser::item_is_parent | ( | ) | const |
bool Browser::item_is_visible | ( | ) | const |
void Browser::layout | ( | ) | [virtual] |
The Browser's custom layout function
see Widget::layout
Reimplemented from fltk::Menu.
const Symbol* fltk::Browser::leaf_symbol | ( | ) | const [inline] |
Browser::leaf_symbol | ( | const Symbol * | s | ) | [inline] |
Sets a default value for image() on each item that is not a parent of other items. If the item has no image() then this one is used for it.
s | The symbol to use for the image |
int Browser::load | ( | const char * | filename | ) |
Adds the contents of a file to a browser, splitting at newlines. This is useful if the browser was storing items that should be saved on program exit and reloaded next time the program is started
filename | The name of the file to load |
bool Browser::make_item_visible | ( | linepos | where = NOSCROLL | ) |
This makes the current item visible to the user.
First it turns off the fltk::INVISIBLE flag on the current item, and turns off the fltk::INVISIBLE flag and opens (turning on the fltk::STATE flag) all parent items. These flag changes cause flags_changed() to be called on any fltk::List that you have assigned to the browser.
The browser is then scrolled by calling yposition() so the item is visible.
where | The optional argument tells how to scroll. If not specified (or the default value of fltk::Browser::NOSCROLL is given) then the browser is scrolled as little as possible to show the item. If it is fltk::Browser::TOP then the item is put at the top of the browser. If it is fltk::Browser::MIDDLE then the item is centered vertically in the browser. If it is fltk::Browser::BOTTOM then the item is put at the bottom of the browser. |
This does nothing if the current item is null.
void Browser::middleline | ( | int | line | ) | [inline] |
Convenience function for non-hierarchial browsers.
line | Make the indexed item visible and scroll to put it in the middle of the browser if it is not already visible (passes NO_SCROLL to make_item_visible(). |
int fltk::Browser::multi | ( | ) | const [inline] |
Widget * Browser::next | ( | ) |
Move the current item to the next item. If if is a parent it moves to the first child. If not a parent, it moves to the next child of it's parent. If it is the last child it moves to the parent's brother. Repeatedly calling this will visit every child of the browser.
The current_position() is NOT set by this! It cannot be calculated efficiently and would slow down the use of this function for visiting all items.
Widget * Browser::next_visible | ( | ) |
int Browser::nheader | ( | ) | const [inline] |
Widget * Browser::previous_visible | ( | ) |
void Browser::scrollbar_cb | ( | Widget * | o, |
void * | |||
) | [static, private] |
bool Browser::select | ( | Widget * | e, |
int | v, | ||
int | do_callback = 0 |
||
) |
This is for use by the MultiBrowser subclass.
This method changes item position in the tree.
e | Used to select or deselect an Widget, |
v | true selects, false deselects |
do_callback | optionally execute a callback (calls set_item_selected() - see this for further documentation). |
bool Browser::select | ( | int | line, |
bool | value = true |
||
) |
Same as goto_index(line),set_item_selected(value), to change the selected state of an item in a non-hierarchial MultiBrowser.
line | The line of the widget to look at |
value | Flag representing whether or not to select this item |
bool Browser::select_only_this | ( | int | do_callback = 0 | ) |
Make an item be the only one selected. For the MultiBrowser subclass this will turn off selection of all other items and turn it on for this one and also set the focus here. If the selection changes and when() & do_callback is non-zero, the callback is done.
For the MultiBrowser, the callback is done for each item that changes, whether it turns on or off.
do_callback | Logical OR of WHEN_* conditions to trigger the callback |
bool Browser::selected | ( | int | line | ) |
Does goto_index(line),item_selected() to return the selection state of an item in a non-hierarchial MultiBrowser.
line | The line to look at |
int Browser::selected_column | ( | ) | [inline] |
It will call the callback() if the user clicks on a column title. Check this to see which one they clicked. This will return a negative number if the callback is being done for some other reason, such as the user clicking on an item.
void Browser::set_belowmouse | ( | ) | [private] |
Checks if the current item is not the highlighted one and needs highligting, and trigger the old and new highlighted ones to redraw if so
int Browser::set_column_start | ( | int | col, |
int | x | ||
) |
Sets the start position of a column to a certain position
col | The index of the column to move |
x | The x position, in pixels, that this column is to be moved to |
bool Browser::set_focus | ( | ) |
Change the focus (the selected item, or in an fltk::MultiBrowser the item that has a dotted box around it, to the current item. This calls make_item_visible().
bool Browser::set_item_opened | ( | bool | open | ) |
Opens the current item (which must be a parent)
open | If the current item is a parent, set the open state (the fltk::STATE flags) to the given value and redraw the browser correctly. |
bool Browser::set_item_selected | ( | bool | value = true , |
int | do_callback = 0 |
||
) |
This is for use by the MultiBrowser subclass. Turn the fltk::SELECTED flag on or off in the current item (use goto_index() to set the current item before calling this).
value | This is the toggle switch; if true this item is SELECTED otherwise it's deselected |
do_callback | A logical OR of when this callback should be executed, which is internally logical AND'd with when(). If when() & do_callback returns 0 but do_callback is positive, this does set_changed() |
If this is not a MultiBrowser, this does select_only_this() if value is true, and deselect() if value is false.
bool Browser::set_item_visible | ( | bool | value | ) |
Turns off or on the fltk::INVISIBLE flag on the given item and redraw the browser if necessary.
value | The new value of the flag on the given item |
void Browser::set_level | ( | unsigned | n | ) | [private] |
This function increases the number of levels we can store in each mark, and sets the level of the current mark to n.
n | The requested level of the current mark |
void fltk::Browser::set_mark | ( | Mark & | dest | ) | const [inline] |
void fltk::Browser::set_mark_to_focus | ( | Mark & | dest | ) | const [inline] |
void Browser::topline | ( | int | line | ) | [inline] |
Convenience function for non-hierarchial browsers.
line | Make the indexed item visible and scroll to put it at the top of the browser. |
int Browser::topline | ( | ) | const [inline] |
Convenience function for non-hierarchial browsers.
int Browser::value | ( | ) | const [inline] |
Reimplemented from fltk::Menu.
void Browser::value | ( | int | v | ) | [inline] |
Same as
goto_index(v);set_focus();
, to change the current item in a non-hierarchial browser.
v | The item to change to |
Reimplemented from fltk::Menu.
int Browser::width | ( | ) | const [inline] |
If this is changed (by adding or deleting items or opening or closing a parent item) then layout() must be called before this is correct.
int fltk::Browser::xposition | ( | ) | const [inline] |
void Browser::xposition | ( | int | X | ) |
Set the horizontal scrolling position, measured in pixels. Zero is the normal position where the left edge of the child widgets is visible.
X | The new scrolling position |
void Browser::yposition | ( | int | Y | ) |
Set the vertical scrolling position, measured in pixels. Zero means the top of the first item is visible. Positive numbers scroll the display up.
Y | The new vertical Scrollbar position |
int fltk::Browser::yposition | ( | ) | const [inline] |
NamedStyle * Browser::default_style = &::style [static] |
This style mostly serves to set the parenting back to Widget::default_style to avoid the gray color and larger leading set by Menu::default_style. However it also sets it's own glyph() function to one that draws the [+] and [-] indicators.
Reimplemented from fltk::Menu.