Documentation

  
  FLTK Apps      FLTK Library      Forums      Links     Login 
 Home  |  Articles & FAQs  |  Bugs & Features  |  Documentation  |  Download  ]
 

class Fl_Browser_


Class Hierarchy

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

Fl_Browser::Fl_Browser(int, int, int, int, const char * = 0)

The constructor makes an empty browser.

Fl_Browser::~Fl_Browser(void)

The destructor deletes all list items and destroys the browser.

Fl_Browser_::bbox(int &x, int &y, int &w, int &h) const

[protected] This method returns the bounding box for the interior of the list, inside the scrollbars.

Fl_Browser_::deleting(void *a)

[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.

int Fl_Browser_::deselect(int docb=0)

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.

Fl_Browser_::display(void *p)

Displays item p, scrolling the list as necessary.

int Fl_Browser_::displayed(void *p) const

[protected] This method returns non-zero if item p is currently visible in the list.

Fl_Browser_::draw()
Fl_Browser_::draw(int x, int y, int w, int h)

[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.

void *Fl_Browser_::find_item(int my)

This method returns the item under mouse at my. If no item is displayed at that position then NULL is returned.

virtual int Fl_Browser_::full_height() const

[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.

Fl_Browser_::full_width() const

[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.

Fl_Browser_::handle(int event)
Fl_Browser_::handle(int event, int x, int y, int w, int h)

The first form handles an event within the normal widget bounding box.

[protected] The second form handles an event within the specified bounding box.

void Fl_Browser_::has_scrollbar(int h)

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.

int Fl_Browser_::hposition() const
Fl_Browser_::hposition(int h)

Gets or sets the horizontal scrolling position of the list, which is the pixel offset of the list items within the list area.

virtual int Fl_Browser_::incr_height() const

[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.

Fl_Browser_::inserting(void *a, void *b)

[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.

virtual void Fl_Browser_::item_draw(void *p, int x, int y, int w, int h)

[protected] This method must be provided by the subclass to draw the item p in the area indicated by x, y, w, and h.

virtual void *Fl_Browser_::item_first() const

[protected] This method must be provided by the subclass to return the first item in the list.

virtual int Fl_Browser_::item_height(void *p) const

[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.

virtual void *Fl_Browser_::item_next(void *p) const

[protected] This method must be provided by the subclass to return the item in the list after p.

virtual void *Fl_Browser_::item_prev(void *p) const

[protected] This method must be provided by the subclass to return the item in the list before p.

virtual int Fl_Browser_::item_quick_height(void *p) const

[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.

virtual void Fl_Browser_::item_select(void *p, int s=1)

[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.

virtual int Fl_Browser_::item_selected(void *p) const

[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.

virtual int Fl_Browser_::item_width(void *p) const

[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.

int Fl_Browser_::leftedge() const

[protected] This method returns the X position of the left edge of the list area after adjusting for the scrollbar and border, if any.

Fl_Browser_::new_list()

[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.

int Fl_Browser_::position() const
Fl_Browser_::position(int v) const

Gets or sets the vertical scrolling position of the list, which is the pixel offset of the list items within the list area.

Fl_Browser_::redraw_line(void *p)

[protected] This method should be called when the contents of an item have changed but not changed the height of the item.

Fl_Browser_::redraw_lines()

[protected] This method will cause the entire list to be redrawn.

Fl_Browser_::replacing(void *a, void *b)

[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.

Fl_Browser_::resize(int x, int y, int w, int h)

Repositions and/or resizes the browser.

Fl_Browser_::scrollbar_left()

This method moves the vertical scrollbar to the lefthand side of the list.

Fl_Browser_::scrollbar_right()

This method moves the vertical scrollbar to the righthand side of the list.

static void Fl_Browser_::scrollbar_width(int sw);
static int Fl_Browser_::scrollbar_width() const;

Sets or gets the width of any scrollbars that are used.

int Fl_Browser_::select(void *p, int s=1, int docb=0)

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.

Fl_Browser_::select_only(void *p, int docb=0)

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.

void *Fl_Browser_::selection() const

[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.

Fl_Color Fl_Browser_::textcolor() const
void Fl_Browser_::textcolor(Fl_Color color)

The first form gets the default text color for the lines in the browser.

The second form sets the default text color to color

Fl_Font Fl_Browser_::textfont() const
void Fl_Browser_::textfont(Fl_Font font)

The first form gets the default text font for the lines in the browser.

The second form sets the default text font to font

uchar Fl_Browser_::textsize() const
void Fl_Browser_::textsize(uchar size)

The first form gets the default text size for the lines in the browser.

The second form sets the default text size to size

void *Fl_Browser_::top() const

[protected] Returns the item the appears at the top of the list.


User Comments [ Add Comment ]

From gregd, 20: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, 10: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 ]

 
 

Comments are owned by the poster. All other content is copyright 1998-2015 by Bill Spitzak and others. This project is hosted by Seriss Corporation. Please report site problems to 'erco@seriss.com'.