ref: e447c9fb929e61a40203b0193ee8d4cab8d72f7e
dir: /DoConfig/fltk/FL/Fl_Browser_.H/
//
// "$Id$"
//
// Common browser header file for the Fast Light Tool Kit (FLTK).
//
// Copyright 1998-2016 by Bill Spitzak and others.
//
// 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
Fl_Browser_ widget . */
// Yes, I know this should be a template...
#ifndef Fl_Browser__H
#define Fl_Browser__H
#ifndef Fl_Group_H
#include "Fl_Group.H"
#endif
#include "Fl_Scrollbar.H"
#include <FL/Fl.H> // Fl::scrollbar_size()
#define FL_NORMAL_BROWSER 0 /**< type() of Fl_Browser */
#define FL_SELECT_BROWSER 1 /**< type() of FL_Select_Browser */
#define FL_HOLD_BROWSER 2 /**< type() of Fl_Hold_Browser */
#define FL_MULTI_BROWSER 3 /**< type() of Fl_Multi_Browser */
#define FL_SORT_ASCENDING 0 /**< sort browser items in ascending alphabetic order. */
#define FL_SORT_DESCENDING 1 /**< sort in descending order */
/**
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.
Keyboard navigation of browser items
------------------------------------
The keyboard navigation of browser items is only possible if
visible_focus() is enabled. If disabled, the widget rejects keyboard focus;
Tab and Shift-Tab focus navigation will skip the widget.
In 'Select' and 'Normal' mode, the widget rejects keyboard focus;
no navigation keys are supported (other than scrollbar positioning).
In 'Hold' mode, the widget accepts keyboard focus, and Up/Down arrow
keys can navigate the selected item.
In 'Multi' mode, the widget accepts keyboard focus, and Up/Down arrow
keys navigate the focus box; Space toggles the current item's selection,
Enter selects only the current item (deselects all others). If Shift
(or Ctrl) is combined with Up/Down arrow keys, the current item's
selection state is extended to the next item. In this way one can
extend a selection or de-selection.
*/
class FL_EXPORT Fl_Browser_ : public Fl_Group {
int position_; // where user wants it scrolled to
int real_position_; // the current vertical scrolling position
int hposition_; // where user wants it panned to
int real_hposition_; // the current horizontal scrolling position
int offset_; // how far down top_ item the real_position is
int max_width; // widest object seen so far
uchar has_scrollbar_; // which scrollbars are enabled
Fl_Font textfont_;
Fl_Fontsize textsize_;
Fl_Color textcolor_;
void* top_; // which item scrolling position is in
void* selection_; // which is selected (except for FL_MULTI_BROWSER)
void *redraw1,*redraw2; // minimal update pointers
void* max_width_item; // which item has max_width_
int scrollbar_size_; // size of scrollbar trough
void update_top();
protected:
// All of the following must be supplied by the subclass:
/**
This method must be provided by the subclass
to return the first item in the list.
\see item_first(), item_next(), item_last(), item_prev()
*/
virtual void *item_first() const = 0;
/**
This method must be provided by the subclass
to return the item in the list after \p item.
\see item_first(), item_next(), item_last(), item_prev()
*/
virtual void *item_next(void *item) const = 0;
/**
This method must be provided by the subclass
to return the item in the list before \p item.
\see item_first(), item_next(), item_last(), item_prev()
*/
virtual void *item_prev(void *item) const = 0;
/**
This method must be provided by the subclass
to return the last item in the list.
\see item_first(), item_next(), item_last(), item_prev()
*/
virtual void *item_last() const { return 0L; }
/**
This method must be provided by the subclass to return
the height of \p item in pixels.
Allow for two additional pixels for the list selection box.
\param[in] item The item whose height is returned.
\returns The height of the specified \p item in pixels.
\see item_height(), item_width(), item_quick_height()
*/
virtual int item_height(void *item) const = 0;
/**
This method must be provided by the subclass to return the width of the
\p item in pixels. Allow for two additional pixels for the list
selection box.
\param[in] item The item whose width is returned.
\returns The width of the item in pixels.
*/
virtual int item_width(void *item) const = 0;
virtual int item_quick_height(void *item) const ;
/**
This method must be provided by the subclass to draw the \p item
in the area indicated by \p X, \p Y, \p W, \p H.
*/
virtual void item_draw(void *item,int X,int Y,int W,int H) const = 0;
/**
This optional method returns a string (label) that may be used for sorting.
\param[in] item The item whose label text is returned.
\returns The item's text label. (Can be NULL if blank)
*/
virtual const char *item_text(void *item) const { (void)item; return 0L; }
/**
This optional method should be provided by the subclass
to efficiently swap browser items \p a and \p b, such as for sorting.
\param[in] a,b The two items to be swapped.
*/
virtual void item_swap(void *a,void *b) { (void)a; (void)b; }
/**
This method must be provided by the subclass
to return the item for the specified \p index.
\param[in] index The \p index of the item to be returned
\returns The item at the specified \p index.
*/
virtual void *item_at(int index) const { (void)index; return 0L; }
// you don't have to provide these but it may help speed it up:
virtual int full_width() const ; // current width of all items
virtual int full_height() const ; // current height of all items
virtual int incr_height() const ; // average height of an item
// These only need to be done by subclass if you want a multi-browser:
virtual void item_select(void *item,int val=1);
virtual int item_selected(void *item) const ;
// things the subclass may want to call:
/**
Returns the item that appears at the top of the list.
*/
void *top() const { return top_; }
/**
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.
*/
void *selection() const { return selection_; }
void new_list(); // completely clobber all data, as though list replaced
void deleting(void *item); // get rid of any pointers to item
void replacing(void *a,void *b); // change a pointers to b
void swapping(void *a,void *b); // exchange pointers a and b
void inserting(void *a,void *b); // insert b near a
int displayed(void *item) const ; // true if this item is visible
void redraw_line(void *item); // minimal update, no change in size
/**
This method will cause the entire list to be redrawn.
\see redraw_lines(), redraw_line()
*/
void redraw_lines() { damage(FL_DAMAGE_SCROLL); } // redraw all of them
void bbox(int &X,int &Y,int &W,int &H) const;
int leftedge() const; // x position after scrollbar & border
void *find_item(int ypos); // item under mouse
void draw();
Fl_Browser_(int X,int Y,int W,int H,const char *L=0);
public:
/**
Vertical scrollbar. Public, so that it can be accessed directly.
*/
Fl_Scrollbar scrollbar;
/**
Horizontal scrollbar. Public, so that it can be accessed directly.
*/
Fl_Scrollbar hscrollbar;
int handle(int event);
void resize(int X,int Y,int W,int H);
int select(void *item,int val=1,int docallbacks=0);
int select_only(void *item,int docallbacks=0);
int deselect(int docallbacks=0);
/**
Gets the vertical scroll position of the list as a pixel position \p pos.
The position returned is how many pixels of the list are scrolled off the top edge
of the screen. Example: A position of '3' indicates the top 3 pixels of
the list are scrolled off the top edge of the screen.
\see position(), hposition()
*/
int position() const { return position_; }
void position(int pos); // scroll to here
/**
Gets the horizontal scroll position of the list as a pixel position \p pos.
The position returned is how many pixels of the list are scrolled off the left edge
of the screen. Example: A position of '18' indicates the left 18 pixels of
the list are scrolled off the left edge of the screen.
\see position(), hposition()
*/
int hposition() const { return hposition_; }
void hposition(int); // pan to here
void display(void *item); // scroll so this item is shown
/**
Values for has_scrollbar().
*/
/** Anonymous enum bit flags for has_scrollbar().
- bit 0: horizontal
- bit 1: vertical
- bit 2: 'always' (to be combined with bits 0 and 1)
- bit 3-31: reserved for future use
*/
enum { // values for has_scrollbar()
HORIZONTAL = 1, ///< Only show horizontal scrollbar.
VERTICAL = 2, ///< Only show vertical scrollbar.
BOTH = 3, ///< Show both scrollbars. (default)
ALWAYS_ON = 4, ///< Specified scrollbar(s) should 'always' be shown (to be used with HORIZONTAL/VERTICAL)
HORIZONTAL_ALWAYS = 5, ///< Horizontal scrollbar always on.
VERTICAL_ALWAYS = 6, ///< Vertical scrollbar always on.
BOTH_ALWAYS = 7 ///< Both scrollbars always on.
};
/**
Returns the current scrollbar mode, see Fl_Browser_::has_scrollbar(uchar)
*/
uchar has_scrollbar() const { return has_scrollbar_; }
/**
Sets whether the widget should have scrollbars or not (default Fl_Browser_::BOTH).
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 \p mode:
- 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.
*/
void has_scrollbar(uchar mode) { has_scrollbar_ = mode; }
/**
Gets the default text font for the lines in the browser.
\see textfont(), textsize(), textcolor()
*/
Fl_Font textfont() const { return textfont_; }
/**
Sets the default text font for the lines in the browser to \p font.
*/
void textfont(Fl_Font font) { textfont_ = font; }
/**
Gets the default text size (in pixels) for the lines in the browser.
*/
Fl_Fontsize textsize() const { return textsize_; }
/**
Sets the default text size (in pixels) for the lines in the browser to \p size.
*/
void textsize(Fl_Fontsize newSize) { textsize_ = newSize; }
/**
Gets the default text color for the lines in the browser.
*/
Fl_Color textcolor() const { return textcolor_; }
/**
Sets the default text color for the lines in the browser to color \p col.
*/
void textcolor(Fl_Color col) { textcolor_ = col; }
/**
Gets the current size of the scrollbars' troughs, in pixels.
If this value is zero (default), this widget will use the
Fl::scrollbar_size() value as the scrollbar's width.
\returns Scrollbar size in pixels, or 0 if the global Fl::scrollbar_size() is being used.
\see Fl::scrollbar_size(int)
*/
int scrollbar_size() const {
return(scrollbar_size_);
}
/**
Sets the pixel size of the scrollbars' troughs to \p newSize, in pixels.
Normally you should not need this method, and should use
Fl::scrollbar_size(int) instead to manage the size of ALL
your widgets' scrollbars. This ensures your application
has a consistent UI, is the default behavior, and is normally
what you want.
Only use THIS method if you really need to override the global
scrollbar size. The need for this should be rare.
Setting \p newSize to the special value of 0 causes the widget to
track the global Fl::scrollbar_size(), which is the default.
\param[in] newSize Sets the scrollbar size in pixels.\n
If 0 (default), scrollbar size tracks the global Fl::scrollbar_size()
\see Fl::scrollbar_size()
*/
void scrollbar_size(int newSize) {
scrollbar_size_ = newSize;
}
/**
This method has been deprecated, existing for backwards compatibility only.
Use scrollbar_size() instead.
This method always returns the global value Fl::scrollbar_size().
\returns Always returns the global value Fl::scrollbar_size().
\todo This method should eventually be removed in 1.4+
*/
int scrollbar_width() const {
return(Fl::scrollbar_size());
}
/**
This method has been deprecated, existing for backwards compatibility only.
Use scrollbar_size(int) instead.
This method sets the global Fl::scrollbar_size(), and forces this
instance of the widget to use it.
\todo This method should eventually be removed in 1.4+
*/
void scrollbar_width(int width) {
Fl::scrollbar_size(width);
scrollbar_size_ = 0;
}
/**
Moves the vertical scrollbar to the righthand side of the list.
For back compatibility.
*/
void scrollbar_right() { scrollbar.align(FL_ALIGN_RIGHT); }
/**
Moves the vertical scrollbar to the lefthand side of the list.
For back compatibility.
*/
void scrollbar_left() { scrollbar.align(FL_ALIGN_LEFT); }
void sort(int flags=0);
};
#endif
//
// End of "$Id$".
//