Class Hierarchy
Fl_Group
|
+----Fl_Browser_
|
+----Fl_Browser, Fl_Check_Browser
Include Files
#include <FL/Fl_Browser_.H>
Description
This is the base class for browsers. To be useful it must be
subclassed and several virtual functions defined. The Forms-compatible
browser and the file chooser's browser are subclassed off of this.
This has been designed so that the subclass has complete control
over the storage of the data, although because next() and
prev() functions are used to index, it works best as a linked list
or as a large block of characters in which the line breaks must be
searched for.
A great deal of work has been done so that the "height" of a data
object does not need to be determined until it is drawn. This is
useful if actually figuring out the size of an object requires
accessing image data or doing stat() on a file or doing some
other slow operation.
Methods
The constructor makes an empty browser.
The destructor deletes all list items and destroys the browser.
[protected] This method returns the bounding box for the interior of the list, inside
the scrollbars.
[protected] This method should be used when an item is deleted from the list.
It allows the Fl_Browser_ to discard any cached data it has
on the item.
Deselects all items in the list and returns 1 if the state changed
or 0 if it did not.
If docb is non-zero, deselect tries to call the
callback function for the widget.
Displays item p, scrolling the list as necessary.
[protected] This method returns non-zero if item p is currently visible in
the list.
[protected] The first form draws the list within the normal widget bounding box.
[protected] The second form draws the contents of the browser within the
specified bounding box.
This method returns the item under mouse at my. If no item is
displayed at that position then NULL is returned.
[protected] This method may be provided by the subclass to indicate the full height
of the item list in pixels. The default implementation computes the full
height from the item heights.
[protected] This method may be provided by the subclass to indicate the full width
of the item list in pixels. The default implementation computes the full
width from the item widths.
The first form handles an event within the normal widget bounding box.
[protected] The second form handles an event within the specified bounding box.
By default you can scroll in both directions, and the scrollbars
disappear if the data will fit in the widget. has_scrollbar() changes
this based on the value of h:
0 - No scrollbars.
Fl_Browser_::HORIZONTAL - Only a horizontal
scrollbar.
Fl_Browser_::VERTICAL - Only a vertical
scrollbar.
Fl_Browser_::BOTH - The default is both
scrollbars.
Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal
scrollbar always on, vertical always off.
Fl_Browser_::VERTICAL_ALWAYS - Vertical
scrollbar always on, horizontal always off.
Fl_Browser_::BOTH_ALWAYS - Both always on.
Gets or sets the horizontal scrolling position of the list,
which is the pixel offset of the list items within the list
area.
[protected] This method may be provided to return the average height of all items, to
be used for scrolling. The default implementation uses the height of the first
item.
[protected] This method should be used when an item is added to the list.
It allows the Fl_Browser_ to update its cache data as needed.
[protected] This method must be provided by the subclass to draw the item
p in the area indicated by x, y, w,
and h.
[protected] This method must be provided by the subclass to return the first item in
the list.
[protected] This method must be provided by the subclass to return the height of the
item p in pixels. Allow for two additional pixels for the list
selection box.
[protected] This method must be provided by the subclass to return the item in
the list after p.
[protected] This method must be provided by the subclass to return the item in
the list before p.
[protected] This method may be provided by the subclass to return the height of the
item p in pixels. Allow for two additional pixels for the list
selection box. This method differs from
item_height in that it is only
called for selection and scrolling operations. The default implementation
calls item_height.
[protected] This method must be implemented by the subclass if it supports
multiple selections in the browser. The s argument specifies the
selection state for item p: 0 = off, 1 = on.
[protected] This method must be implemented by the subclass if it supports
multiple selections in the browser. The method should return 1 if p
is selected and 0 otherwise.
[protected] This method must be provided by the subclass to return the width of the
item p in pixels. Allow for two additional pixels for the list
selection box.
[protected] This method returns the X position of the left edge of the list area
after adjusting for the scrollbar and border, if any.
[protected] This method should be called when the list data is completely replaced
or cleared. It informs the Fl_Browser_ widget that any cached
information it has concerning the items is invalid.
Gets or sets the vertical scrolling position of the list,
which is the pixel offset of the list items within the list
area.
[protected] This method should be called when the contents of an item have changed
but not changed the height of the item.
[protected] This method will cause the entire list to be redrawn.
[protected] This method should be used when an item is replaced in the list.
It allows the Fl_Browser_ to update its cache data as needed.
Repositions and/or resizes the browser.
This method moves the vertical scrollbar to the lefthand side of the list.
This method moves the vertical scrollbar to the righthand side of the list.
Sets or gets the width of any scrollbars that are used.
Sets the selection state of item p to s and
returns 1 if the state changed or 0 if it did not.
If docb is non-zero, select tries to call the callback
function for the widget.
Selects item p and returns 1 if the state changed or 0 if it did
not. Any other items in the list are deselected.
If docb is non-zero, select_only tries to call the
callback function for the widget.
[protected] Returns the item currently selected, or NULL if there is no selection.
For multiple selection browsers this call returns the currently focused item,
even if it is not selected. To find all selected items, call
Fl_Multi_Browser::selected() for every item in question.
The first form gets the default text color for the lines in the
browser.
The second form sets the default text color to color
The first form gets the default text font for the lines in the
browser.
The second form sets the default text font to font
The first form gets the default text size for the lines in the
browser.
The second form sets the default text size to size
[protected] Returns the item the appears at the top of the list.
From gregd, 17:47 Mar 12, 2006 (score=3)
A lot of the descriptions here are completely worlthless. For example:
Fl_Browser_::replacing(void *a, void *b)
What is a, what is b?
Which is part of a larger problem with this documentation, which is it's almost completely lacking in "how do I program using this thing" kind of information. You know, like "what are the various callbacks for, and when are they called." Is it really the case that the only time that a Window callback is called is when it's being closed?
I really doubt that I'm the only programmer who would like to USE FLTK, but who doesn't want to waste a large amount of time learning the wheres and whyfors of it. There is almost no "this is who you sue this" information here.
[ Reply ]
From greg.ercolano, 07:58 Aug 16, 2006 (score=3)
I'd agree about the docs for replacing().. what is a and b indeed ;)
I have a feeling they rushed through the docs for funcs like these, because these functions were mostly for internal use or for indepth widget programming, where use of the function involves RTSL. A second pass should probably be taken at the docs to elaborate on methods like these.
Regarding the question of docs for "this is how you use this" (as opposed to "who you sue" ;), this is really a reference manual, not a tutorial, so don't expect that info to be here. Other toolkit docs are similar. It would be nice if there were simple copy/pasteable examples in the reference docs, similar to these:http://seriss.com/people/erco/fltk/
Regarding callbacks, the callback behavior is different for each widget, so eg. the Fl_Window's callback is only called when a window is closed, an Fl_Button's callback is called when the button is pressed. Such behavior is documented in the higher level widgets, eg. Fl_Button, Fl_Select_Browser, etc. In this case your comment went towards Fl_Browser_, which is a base class.. the higher level docs is probably what you want (Fl_Select_Browser, Fl_Multi_Browser, etc)
[ Reply ]
|