Author: matt
Date: 2012-08-03 04:29:01 -0700 (Fri, 03 Aug 2012)
New Revision: 9651
Log:
Updated documentation in Browser_.
Modified:
branches/branch-3.0/fluid/WidgetBrowser.h
branches/branch-3.0/include/fltk3/Browser_.h
branches/branch-3.0/include/fltk3/ask.h
branches/branch-3.0/src/fltk3/Bitmap.cxx
branches/branch-3.0/src/fltk3/Browser_.cxx
Modified: branches/branch-3.0/fluid/WidgetBrowser.h
===================================================================
--- branches/branch-3.0/fluid/WidgetBrowser.h 2012-08-02 19:47:06 UTC (rev
9650)
+++ branches/branch-3.0/fluid/WidgetBrowser.h 2012-08-03 11:29:01 UTC (rev
9651)
@@ -44,7 +44,7 @@
class WidgetBrowser : public fltk3::Browser_
{
- friend class Fl_Type;
+ friend class ::Fl_Type;
static void handle_second_single_click_i(void*);
Modified: branches/branch-3.0/include/fltk3/Browser_.h
===================================================================
--- branches/branch-3.0/include/fltk3/Browser_.h 2012-08-02 19:47:06 UTC
(rev 9650)
+++ branches/branch-3.0/include/fltk3/Browser_.h 2012-08-03 11:29:01 UTC
(rev 9651)
@@ -47,10 +47,12 @@
const uchar 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.
+ \brief 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
@@ -65,128 +67,325 @@
*/
class FLTK3_EXPORT Browser_ : public fltk3::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
- void* top_; // which item scrolling position is in
- void* selection_; // which is selected (except for fltk3::MULTI_BROWSER)
- void *redraw1,*redraw2; // minimal update pointers
- void* max_width_item; // which item has max_width_
- int scrollbar_size_; // size of scrollbar trough
+ 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
+ void* top_; // which item scrolling position is in
+ void* selection_; // which is selected (except for
fltk3::MULTI_BROWSER)
+ void *redraw1,*redraw2; // minimal update pointers
+ void* max_width_item; // which item has max_width_
+ int scrollbar_size_; // size of scrollbar trough
+ // Figure out top() based on position():
void update_top();
protected:
- // All of the following must be supplied by the subclass:
/**
+ \brief Return the first item in the list.
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()
+ \note This method must be implemented by any derived browser class.
*/
virtual void *item_first() const;
+
/**
+ \brief Return the next item in the list.
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()
+ \note This method must be implemented by any derived browser class.
*/
virtual void *item_next(void *item) const;
+
/**
+ \brief Return the previous item in the list.
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()
+ \note This method must be implemented by any derived browser class.
*/
virtual void *item_prev(void *item) const;
+
/**
+ \brief Return the last item in the list.
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()
+ \note This method must be implemented by any derived browser class.
*/
virtual void *item_last() const;
+
/**
+ \brief Return the height of an item.
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()
+ \note This method must be implemented by any derived browser class.
*/
virtual int item_height(void *item) const;
+
/**
+ \brief Return the width of an item.
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.
+ \note This method must be implemented by any derived browser class.
*/
virtual int item_width(void *item) const;
+
+ /**
+ \brief Quickly return some estimated height of the item.
+ This method may be provided by the subclass to return the height of the
+ \p item, 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.
+ \param[in] item The item whose height to return.
+ \returns The height, in pixels.
+ \note This method must be implemented by any derived browser class.
+ */
virtual int item_quick_height(void *item) const ;
+
/**
+ \brief Draw an item.
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.
+ \note This method must be implemented by any derived browser class.
*/
virtual void item_draw(void *item,int X,int Y,int W,int H) const;
+
/**
+ \brief Return a label text for sorting.
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)
+ \note Implementation of this method is optional.
*/
virtual const char *item_text(void *item) const;
+
/**
+ \brief Swap to items.
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.
+ \note Implementation of this method is optional.
*/
virtual void item_swap(void *a,void *b);
+
/**
+ \brief Return an item at an index.
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.
+ \note This method must be implemented by any derived browser class.
*/
virtual void *item_at(int index) const;
- // 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:
+
+ /**
+ \brief Current width of all items.
+ 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.
+ \returns The maximum width of all the items, in pixels.
+ \note Implementation of this method is optional, but may speed up
calculations.
+ */
+ virtual int full_width() const ;
+
+ /**
+ \brief Current height of all items.
+ 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.
+ Includes the items that are scrolled off screen.
+ \returns The height of the entire list, in pixels.
+ \note Implementation of this method is optional, but may speed up
calculations.
+ */
+ virtual int full_height() const ;
+
+ /**
+ \brief average height of an item.
+ 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.
+ \returns The average height of items, in pixels.
+ \note Implementation of this method is optional, but may speed up
calculations.
+ */
+ virtual int incr_height() const ;
+
+ /**
+ \brief Mark an item selected.
+ This method must be implemented by the subclass if it supports
+ multiple selections; sets the selection state to \p val for the \p item.
+ Sets the selection state for \p item, where optional \p val is 1 (select,
the default)
+ or 0 (de-select).
+ \param[in] item The item to be selected
+ \param[in] val The optional selection state; 1=select, 0=de-select.\n
+ The default is to select the item (1).
+ \note These only need to be implemented by subclass if you want a
multi-browser.
+ */
virtual void item_select(void *item,int val=1);
+
+ /**
+ \brief Return if an item is selected.
+ This method must be implemented by the subclass if it supports
+ multiple selections; returns the selection state for \p item.
+ The method should return 1 if \p item is selected, or 0 otherwise.
+ \param[in] item The item to test.
+ \note These only need to be implemented by subclass if you want a
multi-browser.
+ */
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.
+ \brief 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.
+ \brief 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
fltk3::MultiBrowser::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
+
/**
+ \brief Quick way to delete and reset everything.
+ This method should be called when the list data is completely replaced
+ or cleared. It informs the fltk3::Browser_ widget that any cached
+ information it has concerning the items is invalid.
+ This method does not clear the list, it just handles the follow up
+ bookkeeping after the list has been cleared.
+ */
+ void new_list();
+
+ /**
+ \brief Call this before deleting an item.
+ Tell it that this item is going away, and that this must remove
+ all pointers to it.
+
+ This method should be used when \p item is being deleted from the list.
+ It allows the fltk3::Browser_ to discard any cached data it has on the
item.
+ This method does not actually delete the item, but handles the follow up
+ bookkeeping after the item has just been deleted.
+ \param[in] item The item being deleted.
+ */
+ void deleting(void *item);
+
+ /**
+ \brief Call this before replacing one item with another.
+ This method should be used when item \p a is being replaced by item \p b.
+ It allows the fltk3::Browser_ to update its cache data as needed,
+ schedules a redraw for the item being changed, and tries to maintain the
selection.
+ This method does not actually replace the item, but handles the follow up
+ bookkeeping after the item has just been replaced.
+ \param[in] a Item being replaced
+ \param[in] b Item to replace 'a'
+ */
+ void replacing(void *a,void *b);
+
+ /**
+ \brief Call this before swapping two items.
+ This method should be used when two items \p a and \p b are being swapped.
+ It allows the fltk3::Browser_ to update its cache data as needed,
+ schedules a redraw for the two items, and tries to maintain the current
selection.
+ This method does not actually swap items, but handles the follow up
+ bookkeeping after items have been swapped.
+ \param[in] a,b Items being swapped.
+ */
+ void swapping(void *a,void *b);
+
+ /**
+ \brief Call this before inserting an item.
+ This method should be used when an item is in the process of
+ being inserted into the list.
+ It allows the fltk3::Browser_ to update its cache data as needed,
+ scheduling a redraw for the affected lines.
+ This method does not actually insert items, but handles the
+ follow up bookkeeping after items have been inserted.
+ \param[in] a The starting item position
+ \param[in] b The new item being inserted
+ */
+ void inserting(void *a,void *b);
+
+ /**
+ \brief Tell whether item is currently displayed.
+ Returns non-zero if \p item has been scrolled to a position where it is
being displayed.
+ Checks to see if the item's vertical position is within the top and bottom
+ edges of the display window. This does NOT take into account the
hide()/show()
+ status of the widget or item.
+ \param[in] item The item to check
+ \returns 1 if visible, 0 if not visible.
+ \see display(), displayed()
+ */
+ int displayed(void *item) const ;
+
+ /**
+ \brief Cause minimal update to redraw the given item.
+ This method should be called when the contents of \p item has changed,
+ but not its height.
+ \param[in] item The item that needs to be redrawn.
+ \see redraw_lines(), redraw_line()
+ */
+ void redraw_line(void *item);
+
+ /**
This method will cause the entire list to be redrawn.
\see redraw_lines(), redraw_line()
*/
- void redraw_lines() { damage(fltk3::DAMAGE_SCROLL); } // redraw all of them
+ void redraw_lines() { damage(fltk3::DAMAGE_SCROLL); }
+
+ /**
+ \brief Returns the drawing area of the widget.
+ Returns the bounding box for the interior of the list's display window,
+ inside the scrollbars.
+ \param[out] X,Y,W,H The returned bounding box.
+ (The original contents of these parameters are overwritten)
+ */
void bbox(int &X,int &Y,int &W,int &H) const;
- int leftedge() const; // x position after scrollbar & border
+
+ /**
+ \brief Returns the left edge of the item list.
+ This method returns the X position of the left edge of the list area
+ after adjusting for the scrollbar and border, if any.
+ \returns The X position of the left edge of the list, in pixels.
+ \see fltk3::Browser_::bbox()
+ */
+ int leftedge() const;
+
+ /**
+ \brief This method returns the item under mouse y position \p ypos.
+ NULL is returned if no item is displayed at that position.
+ \param[in] ypos The y position (eg. fltk3::event_y()) to find an item
under.
+ \returns The item, or NULL if not found
+ */
void *find_item(int ypos); // item under mouse
+ /** \internal
+ \brief Draws the list within the normal widget bounding box.
+ Draw() and hence redraw() has side effect of updating top and setting
+ scrollbar positions!
+ */
void draw();
+
+ /** \internal
+ The constructor makes an empty browser.
+ \param[in] X,Y,W,H position and size.
+ \param[in] L The label string, may be NULL.
+ */
Browser_(int X,int Y,int W,int H,const char *L=0);
public:
@@ -200,12 +399,61 @@
*/
fltk3::Scrollbar hscrollbar;
+ /**
+ Handles the \p event within the normal widget bounding box.
+ \param[in] event The event to process.
+ \returns 1 if event was processed, 0 if not.
+ */
int handle(int event);
+
+ /**
+ \brief Repositions and/or resizes the browser.
+ The scrollbars may be moved again by draw(), since each one's size
+ depends on whether the other is visible or not. This skips over
+ fltk3::Group::resize since it moves the scrollbars uselessly.
+ \param[in] X,Y,W,H The new position and size for the browser, in pixels.
+ */
void resize(int X,int Y,int W,int H);
+ /**
+ \brief Select or deselect an item.
+ Sets the selection state of \p item to \p val,
+ and returns 1 if the state changed or 0 if it did not.
+
+ If \p docallbacks is non-zero, select tries to call
+ the callback function for the widget.
+
+ \param[in] item The item whose selection state is to be changed
+ \param[in] val The new selection state (1=select, 0=de-select)
+ \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+ If 0, doesn't do callback (default).
+ \returns 1 if state was changed, 0 if not.
+ */
int select(void *item,int val=1,int docallbacks=0);
+
+ /**
+ \brief Select a single item.
+ Selects \p item and returns 1 if the state changed or 0 if it did not.
+ Any other items in the list are deselected.
+ \param[in] item The \p item to select.
+ \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+ If 0, doesn't do callback (default).
+ */
int select_only(void *item,int docallbacks=0);
+
+ /**
+ \brief Deselect all items.
+ Deselects all items in the list and returns 1 if the state changed
+ or 0 if it did not.
+
+ If the optional \p docallbacks parameter is non-zero, deselect tries
+ to call the callback function for the widget.
+
+ \param[in] docallbacks If 1, invokes widget callback if item changed.\n
+ If 0, doesn't do callback (default).
+ */
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
@@ -214,7 +462,22 @@
\see position(), hposition()
*/
int position() const { return position_; }
+
+ /**
+ \brief Sets the vertical scroll position.
+ Sets the vertical scroll position of the list to pixel position \p pos.
+ The position is how many pixels of the list are scrolled off the top edge
+ of the screen. Example: A position of '3' scrolls the top three pixels of
+ the list off the top edge of the screen.
+
+ Change position(), top() will update when update_top() is called
+ (probably by draw() or handle()):
+
+ \param[in] pos The vertical position (in pixels) to scroll the browser to.
+ \see position(), hposition()
+ */
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
@@ -223,13 +486,28 @@
\see position(), hposition()
*/
int hposition() const { return hposition_; }
- void hposition(int); // pan to here
- void display(void *item); // scroll so this item is shown
+
+ /**
+ Sets the horizontal scroll position of the list to pixel position \p pos.
+ The position is how many pixels of the list are scrolled off the left edge
+ of the screen. Example: A position of '18' scrolls the left 18 pixels of
the list
+ off the left edge of the screen.
+ \param[in] pos The horizontal position (in pixels) to scroll the browser
to.
+ \see position(), hposition()
+ */
+ void hposition(int pos); // pan to here
/**
- Values for has_scrollbar().
+ \brief Ensure this item is displayed.
+ Displays the \p item, scrolling the list as necessary.
+ \param[in] item The item to be displayed.
+ \see display(), displayed()
*/
- /** Anonymous enum bit flags for has_scrollbar().
+ void display(void *item);
+
+ /**
+ \brief 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)
@@ -244,10 +522,12 @@
VERTICAL_ALWAYS = 6, ///< Vertical scrollbar always on.
BOTH_ALWAYS = 7 ///< Both scrollbars always on.
};
+
/**
Returns the current scrollbar mode, see
fltk3::Browser_::has_scrollbar(uchar)
*/
uchar has_scrollbar() const { return has_scrollbar_; }
+
/**
Sets whether the widget should have scrollbars or not (default
fltk3::Browser_::BOTH).
By default you can scroll in both directions, and the scrollbars
@@ -284,6 +564,7 @@
int scrollbar_size() const {
return(scrollbar_size_);
}
+
/**
Sets the pixel size of the scrollbars' troughs to the \p size, in pixels.
@@ -305,7 +586,8 @@
*/
void scrollbar_size(int size) {
scrollbar_size_ = size;
- }
+ }
+
/**
This method has been deprecated, existing for backwards compatibility
only.
Use scrollbar_size() instead.
@@ -316,6 +598,7 @@
int scrollbar_width() const {
return(fltk3::scrollbar_size());
}
+
/**
This method has been deprecated, existing for backwards compatibility
only.
Use scrollbar_size(int) instead.
@@ -327,16 +610,28 @@
fltk3::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(fltk3::ALIGN_RIGHT); }
+
/**
Moves the vertical scrollbar to the lefthand side of the list.
For back compatibility.
*/
void scrollbar_left() { scrollbar.align(fltk3::ALIGN_LEFT); }
+
+ /**
+ Sort the items in the browser based on \p flags.
+ item_swap(void*, void*) and item_text(void*) must be implemented for this
call.
+ \param[in] flags fltk3::SORT_ASCENDING -- sort in ascending order\n
+ fltk3::SORT_DESCENDING -- sort in descending order\n
+ Values other than the above will cause undefined behavior\n
+ Other flags may appear in the future.
+ \todo Add a flag to ignore case
+ */
void sort(int flags=0);
};
Modified: branches/branch-3.0/include/fltk3/ask.h
===================================================================
--- branches/branch-3.0/include/fltk3/ask.h 2012-08-02 19:47:06 UTC (rev
9650)
+++ branches/branch-3.0/include/fltk3/ask.h 2012-08-03 11:29:01 UTC (rev
9651)
@@ -59,9 +59,6 @@
FLTK3_EXPORT void vmessage(const char *, va_list);
FLTK3_EXPORT void alert(const char *,...) __fl_attr((__format__ (__printf__,
1, 2)));
FLTK3_EXPORT void valert(const char *, va_list);
- // fltk3::ask() is deprecated since it uses "Yes" and "No" for the buttons,
- // which does not conform to the current FLTK Human Interface Guidelines.
- // Use fltk3::choice() instead with the appropriate verbs instead.
FLTK3_EXPORT int ask(const char *,...) __fl_attr((__format__ (__printf__, 1,
2), __deprecated__));
FLTK3_EXPORT int vask(const char *, va_list);
FLTK3_EXPORT int choice(const char *q,const char *b0,const char *b1,const
char *b2,...) __fl_attr((__format__ (__printf__, 1, 5)));
Modified: branches/branch-3.0/src/fltk3/Bitmap.cxx
===================================================================
--- branches/branch-3.0/src/fltk3/Bitmap.cxx 2012-08-02 19:47:06 UTC (rev
9650)
+++ branches/branch-3.0/src/fltk3/Bitmap.cxx 2012-08-03 11:29:01 UTC (rev
9651)
@@ -25,12 +25,7 @@
// http://www.fltk.org/str.php
//
-/** \fn fltk3::Bitmap::Bitmap(const char *array, int W, int H)
- The constructors create a new bitmap from the specified bitmap data.*/
-/** \fn fltk3::Bitmap::Bitmap(const unsigned char *array, int W, int H)
- The constructors create a new bitmap from the specified bitmap data.*/
-
#include <fltk3/run.h>
#include <fltk3/x.h>
#include <fltk3/draw.h>
Modified: branches/branch-3.0/src/fltk3/Browser_.cxx
===================================================================
--- branches/branch-3.0/src/fltk3/Browser_.cxx 2012-08-02 19:47:06 UTC (rev
9650)
+++ branches/branch-3.0/src/fltk3/Browser_.cxx 2012-08-03 11:29:01 UTC (rev
9651)
@@ -35,31 +35,13 @@
#include <fltk3/Wrapper.h>
-// 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.
-
-// Yes, I know this should be a template...
-
-// 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 was
-// done for the file chooser, because the height requires doing stat()
-// to see if the file is a directory, which can be annoyingly slow
-// over the network.
-
/* redraw bits:
1 = redraw children (the scrollbar)
2 = redraw one or two items
4 = redraw all items
*/
+
static void scrollbar_callback(fltk3::Widget* s, void*) {
((fltk3::Browser_*)(s->parent()))->position(int(((fltk3::Scrollbar*)s)->value()));
}
@@ -68,13 +50,8 @@
((fltk3::Browser_*)(s->parent()))->hposition(int(((fltk3::Scrollbar*)s)->value()));
}
-// return where to draw the actual box:
-/**
- Returns the bounding box for the interior of the list's display window, inside
- the scrollbars.
- \param[out] X,Y,W,H The returned bounding box.\n
- (The original contents of these parameters are overwritten)
- */
+
+// Documented in the header file
void fltk3::Browser_::bbox(int& X, int& Y, int& W, int& H) const {
int scrollsize = scrollbar_size_ ? scrollbar_size_ : fltk3::scrollbar_size();
fltk3::Box* b = box() ? box() : fltk3::DOWN_BOX;
@@ -94,24 +71,15 @@
if (H < 0) H = 0;
}
-/**
- This method returns the X position of the left edge of the list area
- after adjusting for the scrollbar and border, if any.
- \returns The X position of the left edge of the list, in pixels.
- \see fltk3::Browser_::bbox()
- */
+
+// Documented in the header file
int fltk3::Browser_::leftedge() const {
int X, Y, W, H; bbox(X, Y, W, H);
return X;
}
-// The scrollbars may be moved again by draw(), since each one's size
-// depends on whether the other is visible or not. This skips over
-// fltk3::Group::resize since it moves the scrollbars uselessly.
-/**
- Repositions and/or resizes the browser.
- \param[in] X,Y,W,H The new position and size for the browser, in pixels.
- */
+
+// Documented in the header file
void fltk3::Browser_::resize(int X, int Y, int W, int H) {
int scrollsize = scrollbar_size_ ? scrollbar_size_ : fltk3::scrollbar_size();
Widget::resize(X, Y, W, H);
@@ -125,20 +93,16 @@
W, scrollsize);
}
-// Cause minimal update to redraw the given item:
-/**
- This method should be called when the contents of \p item has changed,
- but not its height.
- \param[in] item The item that needs to be redrawn.
- \see redraw_lines(), redraw_line()
- */
+
+// Documented in the header file
void fltk3::Browser_::redraw_line(void* item) {
if (!redraw1 || redraw1 == item) {redraw1 = item;
damage(fltk3::DAMAGE_EXPOSE);}
else if (!redraw2 || redraw2 == item) {redraw2 = item;
damage(fltk3::DAMAGE_EXPOSE);}
else damage(fltk3::DAMAGE_SCROLL);
}
-// Figure out top() based on position():
+
+// Documented in the header file
void fltk3::Browser_::update_top() {
if (!top_) top_ = item_first();
if (position_ != real_position_) {
@@ -192,16 +156,8 @@
}
}
-// Change position(), top() will update when update_top() is called
-// (probably by draw() or handle()):
-/**
- Sets the vertical scroll position of the list to pixel position \p pos.
- The position is how many pixels of the list are scrolled off the top edge
- of the screen. Example: A position of '3' scrolls the top three pixels of
- the list off the top edge of the screen.
- \param[in] pos The vertical position (in pixels) to scroll the browser to.
- \see position(), hposition()
- */
+
+// Documented in the header file
void fltk3::Browser_::position(int pos) {
if (pos < 0) pos = 0;
if (pos == position_) return;
@@ -209,14 +165,8 @@
if (pos != real_position_) redraw_lines();
}
-/**
- Sets the horizontal scroll position of the list to pixel position \p pos.
- The position is how many pixels of the list are scrolled off the left edge
- of the screen. Example: A position of '18' scrolls the left 18 pixels of the
list
- off the left edge of the screen.
- \param[in] pos The horizontal position (in pixels) to scroll the browser to.
- \see position(), hposition()
- */
+
+// Documented in the header file
void fltk3::Browser_::hposition(int pos) {
if (pos < 0) pos = 0;
if (pos == hposition_) return;
@@ -224,16 +174,8 @@
if (pos != real_hposition_) redraw_lines();
}
-// Tell whether item is currently displayed:
-/**
- Returns non-zero if \p item has been scrolled to a position where it is being
displayed.
- Checks to see if the item's vertical position is within the top and bottom
- edges of the display window. This does NOT take into account the hide()/show()
- status of the widget or item.
- \param[in] item The item to check
- \returns 1 if visible, 0 if not visible.
- \see display(), displayed()
- */
+
+// Documented in the header file
int fltk3::Browser_::displayed(void* item) const {
int X, Y, W, H; bbox(X, Y, W, H);
int yy = H+offset_;
@@ -244,13 +186,9 @@
return 0;
}
-// Ensure this item is displayed:
+
+// Documented in the header file
// Messy because we have no idea if it is before top or after bottom:
-/**
- Displays the \p item, scrolling the list as necessary.
- \param[in] item The item to be displayed.
- \see display(), displayed()
- */
void fltk3::Browser_::display(void* item) {
// First special case - want to display first item in the list?
@@ -331,10 +269,8 @@
#endif
}
-// redraw, has side effect of updating top and setting scrollbar:
-/**
- Draws the list within the normal widget bounding box.
- */
+
+// Documented in the header file
void fltk3::Browser_::draw() {
int drawsquare = 0;
update_top();
@@ -487,14 +423,8 @@
real_hposition_ = hposition_;
}
-// Quick way to delete and reset everything:
-/**
- This method should be called when the list data is completely replaced
- or cleared. It informs the fltk3::Browser_ widget that any cached
- information it has concerning the items is invalid.
- This method does not clear the list, it just handles the follow up
- bookkeeping after the list has been cleared.
- */
+
+// Documented in the header file
void fltk3::Browser_::new_list() {
top_ = 0;
position_ = real_position_ = 0;
@@ -506,15 +436,7 @@
redraw_lines();
}
-// Tell it that this item is going away, and that this must remove
-// all pointers to it:
-/**
- This method should be used when \p item is being deleted from the list.
- It allows the fltk3::Browser_ to discard any cached data it has on the item.
- This method does not actually delete the item, but handles the follow up
- bookkeeping after the item has just been deleted.
- \param[in] item The item being deleted.
- */
+// Documented in the header file
void fltk3::Browser_::deleting(void* item) {
if (displayed(item)) {
redraw_lines();
@@ -534,15 +456,8 @@
if (item == max_width_item) {max_width_item = 0; max_width = 0;}
}
-/**
- This method should be used when item \p a is being replaced by item \p b.
- It allows the fltk3::Browser_ to update its cache data as needed,
- schedules a redraw for the item being changed, and tries to maintain the
selection.
- This method does not actually replace the item, but handles the follow up
- bookkeeping after the item has just been replaced.
- \param[in] a Item being replaced
- \param[in] b Item to replace 'a'
- */
+
+// Documented in the header file
void fltk3::Browser_::replacing(void* a, void* b) {
redraw_line(a);
if (a == selection_) selection_ = b;
@@ -550,14 +465,8 @@
if (a == max_width_item) {max_width_item = 0; max_width = 0;}
}
-/**
- This method should be used when two items \p a and \p b are being swapped.
- It allows the fltk3::Browser_ to update its cache data as needed,
- schedules a redraw for the two items, and tries to maintain the current
selection.
- This method does not actually swap items, but handles the follow up
- bookkeeping after items have been swapped.
- \param[in] a,b Items being swapped.
- */
+
+// Documented in the header file
void fltk3::Browser_::swapping(void* a, void* b) {
redraw_line(a);
redraw_line(b);
@@ -567,27 +476,15 @@
else if (b == top_) top_ = a;
}
-/**
- This method should be used when an item is in the process of
- being inserted into the list.
- It allows the fltk3::Browser_ to update its cache data as needed,
- scheduling a redraw for the affected lines.
- This method does not actually insert items, but handles the
- follow up bookkeeping after items have been inserted.
- \param[in] a The starting item position
- \param[in] b The new item being inserted
- */
+
+// Documented in the header file
void fltk3::Browser_::inserting(void* a, void* b) {
if (displayed(a)) redraw_lines();
if (a == top_) top_ = b;
}
-/**
- This method returns the item under mouse y position \p ypos.
- NULL is returned if no item is displayed at that position.
- \param[in] ypos The y position (eg. fltk3::event_y()) to find an item under.
- \returns The item, or NULL if not found
- */
+
+// Documented in the header file
void* fltk3::Browser_::find_item(int ypos) {
update_top();
int X, Y, W, H; bbox(X, Y, W, H);
@@ -600,19 +497,8 @@
return 0;
}
-/**
- Sets the selection state of \p item to \p val,
- and returns 1 if the state changed or 0 if it did not.
-
- If \p docallbacks is non-zero, select tries to call
- the callback function for the widget.
-
- \param[in] item The item whose selection state is to be changed
- \param[in] val The new selection state (1=select, 0=de-select)
- \param[in] docallbacks If 1, invokes widget callback if item changed.\n
- If 0, doesn't do callback (default).
- \returns 1 if state was changed, 0 if not.
- */
+
+// Documented in the header file
int fltk3::Browser_::select(void* item, int val, int docallbacks) {
if (type() == fltk3::MULTI_BROWSER) {
if (selection_ != item) {
@@ -645,16 +531,8 @@
return 1;
}
-/**
- Deselects all items in the list and returns 1 if the state changed
- or 0 if it did not.
-
- If the optional \p docallbacks parameter is non-zero, deselect tries
- to call the callback function for the widget.
-
- \param[in] docallbacks If 1, invokes widget callback if item changed.\n
- If 0, doesn't do callback (default).
- */
+
+// Documented in the header file
int fltk3::Browser_::deselect(int docallbacks) {
if (type() == fltk3::MULTI_BROWSER) {
int change = 0;
@@ -670,13 +548,8 @@
}
}
-/**
- Selects \p item and returns 1 if the state changed or 0 if it did not.
- Any other items in the list are deselected.
- \param[in] item The \p item to select.
- \param[in] docallbacks If 1, invokes widget callback if item changed.\n
- If 0, doesn't do callback (default).
- */
+
+// Documented in the header file
int fltk3::Browser_::select_only(void* item, int docallbacks) {
if (!item) return deselect(docallbacks);
int change = 0;
@@ -693,11 +566,8 @@
return change;
}
-/**
- Handles the \p event within the normal widget bounding box.
- \param[in] event The event to process.
- \returns 1 if event was processed, 0 if not.
- */
+
+// Documented in the header file
int fltk3::Browser_::handle(int event) {
// NOTE:
// We use fltk3::WidgetTracker to test if the user has deleted
@@ -953,11 +823,8 @@
return 0;
}
-/**
- The constructor makes an empty browser.
- \param[in] X,Y,W,H position and size.
- \param[in] L The label string, may be NULL.
- */
+
+// Documented in the header file
fltk3::Browser_::Browser_(int X, int Y, int W, int H, const char* L)
: fltk3::Group(X, Y, W, H, L),
scrollbar(0, 0, 0, 0, 0), // they will be resized by draw()
@@ -987,15 +854,8 @@
end();
}
-/**
- Sort the items in the browser based on \p flags.
- item_swap(void*, void*) and item_text(void*) must be implemented for this
call.
- \param[in] flags fltk3::SORT_ASCENDING -- sort in ascending order\n
- fltk3::SORT_DESCENDING -- sort in descending order\n
- Values other than the above will cause undefined behavior\n
- Other flags may appear in the future.
- \todo Add a flag to ignore case
- */
+
+// Documented in the header file
void fltk3::Browser_::sort(int flags) {
//
// Simple bubble sort - pure lazyness on my side.
@@ -1034,41 +894,25 @@
}
}
+
// Default versions of some of the virtual functions:
-/**
- This method may be provided by the subclass to return the height of the
- \p item, 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.
- \param[in] item The item whose height to return.
- \returns The height, in pixels.
- */
+
+// Documented in the header file
int fltk3::Browser_::item_quick_height(void* item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, item_quick_height(item),
BrowserItemQuickHeight)
return item_height(item);
}
-/**
- 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.
- \returns The average height of items, in pixels.
- */
+
+// Documented in the header file
int fltk3::Browser_::incr_height() const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, incr_height(), BrowserIncrHeight)
return item_quick_height(item_first());
}
-/**
- 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.
- Includes the items that are scrolled off screen.
- \returns The height of the entire list, in pixels.
- */
+
+// Documented in the header file
int fltk3::Browser_::full_height() const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, full_height(), BrowserFullHeight)
int t = 0;
@@ -1077,89 +921,95 @@
return t;
}
-/**
- 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.
- \returns The maximum width of all the items, in pixels.
- */
+
+// Documented in the header file
int fltk3::Browser_::full_width() const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, full_width(), BrowserFullWidth)
return max_width;
}
-/**
- This method must be implemented by the subclass if it supports
- multiple selections; sets the selection state to \p val for the \p item.
- Sets the selection state for \p item, where optional \p val is 1 (select, the
default)
- or 0 (de-select).
- \param[in] item The item to be selected
- \param[in] val The optional selection state; 1=select, 0=de-select.\n
- The default is to select the item (1).
- */
+
+// Documented in the header file
void fltk3::Browser_::item_select(void *item, int val) {
FLTK3_WIDGET_VCALLS_WRAPPER(item_select(item, val), BrowserItemSelect)
}
-/**
- This method must be implemented by the subclass if it supports
- multiple selections; returns the selection state for \p item.
- The method should return 1 if \p item is selected, or 0 otherwise.
- \param[in] item The item to test.
- */
-int fltk3::Browser_::item_selected(void* item) const {
+
+// Documented in the header file
+int fltk3::Browser_::item_selected(void* item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, item_selected(item),
BrowserItemSelected)
return item==selection_ ? 1 : 0;
}
+
+// Documented in the header file
void *fltk3::Browser_::item_first() const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(void*, item_first(), BrowserItemFirst)
return 0;
}
+
+// Documented in the header file
void *fltk3::Browser_::item_next(void *item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(void*, item_next(item), BrowserItemNext)
return 0;
}
+
+// Documented in the header file
void *fltk3::Browser_::item_prev(void *item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(void*, item_prev(item), BrowserItemPrev)
return 0;
}
+
+// Documented in the header file
void *fltk3::Browser_::item_last() const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(void*, item_last(), BrowserItemLast)
return 0;
}
+
+// Documented in the header file
int fltk3::Browser_::item_height(void *item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, item_height(item), BrowserItemHeight)
return 0;
}
-int fltk3::Browser_::item_width(void *item) const {
+
+// Documented in the header file
+int fltk3::Browser_::item_width(void *item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(int, item_width(item), BrowserItemWidth)
return 0;
}
+
+// Documented in the header file
void fltk3::Browser_::item_draw(void *item,int X,int Y,int W,int H) const {
FLTK3_WIDGET_VCALLS_WRAPPER(item_draw(item, X, Y, W, H), BrowserItemDraw)
}
+
+// Documented in the header file
const char *fltk3::Browser_::item_text(void *item) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(const char *, item_text(item),
BrowserItemText)
return 0L;
}
-void fltk3::Browser_::item_swap(void *a,void *b) {
+
+// Documented in the header file
+void fltk3::Browser_::item_swap(void *a,void *b) {
FLTK3_WIDGET_VCALLS_WRAPPER(item_swap(a, b), BrowserItemSwap)
}
-void *fltk3::Browser_::item_at(int index) const {
+
+// Documented in the header file
+void *fltk3::Browser_::item_at(int index) const {
FLTK3_WIDGET_VCALLS_WRAPPER_RET(void *, item_at(index), BrowserItemAt)
return 0L;
}
+
//
// End of "$Id$".
//
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
