Author: greg.ercolano
Date: 2011-02-19 14:40:31 -0800 (Sat, 19 Feb 2011)
New Revision: 8449
Log:
Document NULL item behavior, small code mods for same.
Modified:
branches/branch-1.3/FL/Fl_Tree.H
branches/branch-1.3/src/Fl_Tree.cxx
branches/branch-1.3/src/Fl_Tree_Item.cxx
Modified: branches/branch-1.3/FL/Fl_Tree.H
===================================================================
--- branches/branch-1.3/FL/Fl_Tree.H 2011-02-19 22:39:00 UTC (rev 8448)
+++ branches/branch-1.3/FL/Fl_Tree.H 2011-02-19 22:40:31 UTC (rev 8449)
@@ -231,11 +231,11 @@
Fl_Tree_Item* insert(Fl_Tree_Item *item, const char *name, int pos);
/// Remove the specified \p item from the tree.
+ /// \p item may not be NULL.
/// If it has children, all those are removed too.
/// \returns 0 if done, -1 if 'item' not found.
///
int remove(Fl_Tree_Item *item) {
- if ( !item ) return(0);
if ( item == _root ) {
clear();
} else {
@@ -254,6 +254,8 @@
delete _root; _root = 0;
}
/// Clear all the children of a particular node in the tree specified by \p
item.
+ /// Item may not be NULL.
+ ///
void clear_children(Fl_Tree_Item *item) {
if ( item->has_children() ) {
item->clear_children();
@@ -301,12 +303,11 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be opened
+ /// \param[in] item -- the item to be opened. Must not be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - callback() is not invoked
/// - 1 - callback() is invoked if item changed,
/// callback_reason() will be FL_TREE_REASON_OPENED
- ///
/// \returns
/// - 1 -- item was opened
/// - 0 -- item was already open, no change
@@ -335,7 +336,6 @@
/// - 0 - callback() is not invoked
/// - 1 - callback() is invoked if item changed,
/// callback_reason() will be FL_TREE_REASON_OPENED
- ///
/// \returns
/// - 1 -- OK: item opened
/// - 0 -- OK: item was already open, no change
@@ -355,7 +355,7 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be opened
+ /// \param[in] item -- the item whose open state is to be toggled. Must not
be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - callback() is not invoked
/// - 1 - callback() is invoked, callback_reason() will be either
@@ -377,12 +377,11 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be closed
+ /// \param[in] item -- the item to be closed. Must not be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - callback() is not invoked
/// - 1 - callback() is invoked if item changed,
/// callback_reason() will be FL_TREE_REASON_CLOSED
- ///
/// \returns
/// - 1 -- item was closed
/// - 0 -- item was already closed, no change
@@ -410,7 +409,6 @@
/// - 0 - callback() is not invoked
/// - 1 - callback() is invoked if item changed,
/// callback_reason() will be FL_TREE_REASON_CLOSED
- ///
/// \returns
/// - 1 -- OK: item closed
/// - 0 -- OK: item was already closed, no change
@@ -428,8 +426,7 @@
/// Items that are 'open' are themselves not necessarily visible;
/// one of the item's parents might be closed.
///
- /// \param[in] item -- the item to be tested
- ///
+ /// \param[in] item -- the item to be tested. Must not be NULL.
/// \returns
/// - 1 : item is open
/// - 0 : item is closed
@@ -443,7 +440,6 @@
/// one of the item's parents might be closed.
///
/// \param[in] path -- the tree item's pathname (eg. "Flintstones/Fred")
- ///
/// \returns
/// - 1 - OK: item is open
/// - 0 - OK: item is closed
@@ -456,8 +452,7 @@
}
/// See if the specified \p item is closed.
///
- /// \param[in] item -- the item to be tested
- ///
+ /// \param[in] item -- the item to be tested. Must not be NULL.
/// \returns
/// - 1 : item is open
/// - 0 : item is closed
@@ -468,7 +463,6 @@
/// See if item specified by \p path (eg: "Parent/child/item") is closed.
///
/// \param[in] path -- the tree item's pathname (eg. "Flintstones/Fred")
- ///
/// \returns
/// - 1 - OK: item is closed
/// - 0 - OK: item is open
@@ -487,12 +481,11 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be selected
+ /// \param[in] item -- the item to be selected. Must not be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked if item changed state,
/// callback_reason() will be FL_TREE_REASON_SELECTED
- ///
/// \returns
/// - 1 - item's state was changed
/// - 0 - item was already selected, no change was made
@@ -521,7 +514,6 @@
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked if item changed state,
/// callback_reason() will be FL_TREE_REASON_SELECTED
- ///
/// \returns
/// - 1 : OK: item's state was changed
/// - 0 : OK: item was already selected, no change was made
@@ -539,7 +531,7 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be selected
+ /// \param[in] item -- the item to be selected. Must not be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked, callback_reason() will be
@@ -561,15 +553,14 @@
/// The callback can use callback_item() and callback_reason() respectively
to determine
/// the item changed and the reason the callback was called.
///
- /// \param[in] item -- the item to be selected
+ /// \param[in] item -- the item to be selected. Must not be NULL.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked if item changed state,
/// callback_reason() will be FL_TREE_REASON_DESELECTED
- ///
/// \returns
- /// - 0 - item was already deselected, no change was made
- /// - 1 - item's state was changed
+ /// - 0 - item was already deselected, no change was made
+ /// - 1 - item's state was changed
///
int deselect(Fl_Tree_Item *item, int docallback=1) {
if ( item->is_selected() ) {
@@ -595,7 +586,6 @@
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked if item changed state,
/// callback_reason() will be FL_TREE_REASON_DESELECTED
- ///
/// \returns
/// - 1 - OK: item's state was changed
/// - 0 - OK: item was already deselected, no change was made
@@ -614,7 +604,7 @@
/// See if the specified \p item is selected.
///
- /// \param[in] item -- the item to be tested
+ /// \param[in] item -- the item to be tested. Must not be NULL.
///
/// \return
/// - 1 : item selected
@@ -626,7 +616,6 @@
/// See if item specified by \p path (eg: "Parent/child/item") is selected.
///
/// \param[in] path -- the tree item's pathname (eg. "Flintstones/Fred")
- ///
/// \returns
/// - 1 : item selected
/// - 0 : item deselected
Modified: branches/branch-1.3/src/Fl_Tree.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Tree.cxx 2011-02-19 22:39:00 UTC (rev 8448)
+++ branches/branch-1.3/src/Fl_Tree.cxx 2011-02-19 22:40:31 UTC (rev 8449)
@@ -126,6 +126,8 @@
}
/// Inserts a new item above the specified Fl_Tree_Item, with the label set to
'name'.
+/// \param[in] above -- the item above which to insert the new item. Must not
be NULL.
+/// \param[in] name -- the name of the new item
/// \returns the item that was added, or 0 if 'above' could not be found.
///
Fl_Tree_Item* Fl_Tree::insert_above(Fl_Tree_Item *above, const char *name) {
@@ -134,21 +136,21 @@
/// Insert a new item into a tree-item's children at a specified position.
///
-/// \param[in] item The existing item to insert new child into
+/// \param[in] item The existing item to insert new child into. Must not be
NULL.
/// \param[in] name The label for the new item
/// \param[in] pos The position of the new item in the child list
+/// \returns the item that was added.
///
-/// \returns the item that was added.
Fl_Tree_Item* Fl_Tree::insert(Fl_Tree_Item *item, const char *name, int pos) {
return(item->insert(_prefs, name, pos));
}
/// Add a new child to a tree-item.
///
-/// \param[in] item The existing item to add new child to
+/// \param[in] item The existing item to add new child to. Must not be NULL.
/// \param[in] name The label for the new item
+/// \returns the item that was added.
///
-/// \returns the item that was added.
Fl_Tree_Item* Fl_Tree::add(Fl_Tree_Item *item, const char *name) {
return(item->add(_prefs, name));
}
@@ -160,12 +162,12 @@
/// to do lookups without causing compiler errors.
///
/// \param[in] path -- the tree item's pathname to be found (eg.
"Flintstones/Fred")
+/// \returns the item, or NULL if not found.
///
-/// \returns the item, or 0 if not found.
/// \see item_pathname()
///
Fl_Tree_Item *Fl_Tree::find_item(const char *path) {
- if ( ! _root ) return(0);
+ if ( ! _root ) return(NULL);
char **arr = parse_path(path);
Fl_Tree_Item *item = _root->find_item(arr);
free_path(arr);
@@ -174,7 +176,7 @@
/// A const version of Fl_Tree::find_item(const char *path)
const Fl_Tree_Item *Fl_Tree::find_item(const char *path) const {
- if ( ! _root ) return(0);
+ if ( ! _root ) return(NULL);
char **arr = parse_path(path);
const Fl_Tree_Item *item = _root->find_item(arr);
free_path(arr);
@@ -288,7 +290,6 @@
///
/// \param[in] item The item above/below which we'll find the next visible item
/// \param[in] dir The direction to search. Can be FL_Up or FL_Down.
-///
/// \returns The item found, or 0 if there's no visible items above/below the
specified \p item.
///
Fl_Tree_Item *Fl_Tree::next_visible_item(Fl_Tree_Item *item, int dir) {
@@ -329,7 +330,7 @@
/// \returns the item clicked, or 0 if no item was under the current event.
///
const Fl_Tree_Item* Fl_Tree::find_clicked() const {
- if ( ! _root ) return(0);
+ if ( ! _root ) return(NULL);
return(_root->find_clicked(_prefs));
}
@@ -368,8 +369,7 @@
/// }
/// \endcode
///
-/// \param[in] item The item to use to find the next item. If NULL, returns
NULL
-///
+/// \param[in] item The item to use to find the next item. If NULL, returns 0.
/// \returns Next item in tree, or 0 if at last item.
///
/// \see first(),next(),last(),prev()
@@ -389,8 +389,7 @@
/// }
/// \endcode
///
-/// \param[in] item The item to use to find the previous item. If NULL,
returns NULL
-///
+/// \param[in] item The item to use to find the previous item. If NULL,
returns 0.
/// \returns Previous item in tree, or 0 if at first item.
///
/// \see first(),next(),last(),prev()
@@ -450,7 +449,6 @@
/// \endcode
///
/// \param[in] item The item to use to find the next selected item. If NULL,
first() is used.
-///
/// \returns The next selected item, or 0 if there are no more selected items.
///
Fl_Tree_Item *Fl_Tree::next_selected_item(Fl_Tree_Item *item) {
@@ -685,7 +683,8 @@
/// The callback can use callback_item() and callback_reason() respectively to
determine
/// the item changed and the reason the callback was called.
///
-/// \param[in] item The item that will be deselected (along with all its
children)
+/// \param[in] item The item that will be deselected (along with all its
children).
+/// If NULL, first() is used.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked for each item that changed state,
@@ -717,12 +716,11 @@
/// the item changed and the reason the callback was called.
///
/// \param[in] item The item that will be selected (along with all its
children).
-/// If NULL, first() is assumed.
+/// If NULL, first() is used.
/// \param[in] docallback -- A flag that determines if the callback() is
invoked or not:
/// - 0 - the callback() is not invoked
/// - 1 - the callback() is invoked for each item that changed state,
/// callback_reason() will be FL_TREE_REASON_SELECTED
-///
/// \returns count of how many items were actually changed to the selected
state.
///
int Fl_Tree::select_all(Fl_Tree_Item *item, int docallback) {
@@ -754,7 +752,6 @@
/// - 1 - the callback() is invoked for each item that changed state,
/// callback_reason() will be either FL_TREE_REASON_SELECTED or
/// FL_TREE_REASON_DESELECTED
-///
/// \returns the number of items whose selection states were changed, if any.
///
int Fl_Tree::select_only(Fl_Tree_Item *selitem, int docallback) {
@@ -785,6 +782,9 @@
/// the value will be clipped. So if yoff=100, but scrollbar's max
/// is 50, then 50 will be used.
///
+/// \param[in] item The item to be shown. Should not be NULL.
+/// \param[in] yoff The pixel offset from the top for the displayed position.
+///
/// \see show_item_top(), show_item_middle(), show_item_bottom()
///
void Fl_Tree::show_item(Fl_Tree_Item *item, int yoff) {
@@ -800,42 +800,57 @@
/// This can be used to detect if the item is scrolled off-screen.
/// 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 item.
+/// or open()/close() status of the item.
///
+/// \param[in] item The item to be checked. If NULL, first() is used.
+/// \returns 1 if displayed, 0 if scrolled off screen or no items are in tree.
+///
int Fl_Tree::displayed(Fl_Tree_Item *item) {
- return( (item->y() >= y() && item->y() <= (y()+h()-item->h())) ? 1 : 0);
+ item = item ? item : first();
+ if (!item) return(0);
+ return( (item->y() >= y()) && (item->y() <= (y()+h()-item->h())) ? 1 : 0);
}
/// Adjust the vertical scroll bar to show \p item at the top
/// of the display IF it is currently off-screen (eg. show_item_top()).
/// If it is already on-screen, no change is made.
///
+/// \param[in] item The item to be shown. If NULL, first() is used.
+///
/// \see show_item_top(), show_item_middle(), show_item_bottom()
///
void Fl_Tree::show_item(Fl_Tree_Item *item) {
+ item = item ? item : first();
+ if (!item) return;
if ( displayed(item) ) return;
show_item_top(item);
}
/// Adjust the vertical scrollbar so that \p item is at the top of the display.
+///
+/// \param[in] item The item to be shown. If NULL, first() is used.
+///
void Fl_Tree::show_item_top(Fl_Tree_Item *item) {
item = item ? item : first();
- if ( ! item ) return;
- show_item(item, 0);
+ if (item) show_item(item, 0);
}
/// Adjust the vertical scrollbar so that \p item is in the middle of the
display.
+///
+/// \param[in] item The item to be shown. If NULL, first() is used.
+///
void Fl_Tree::show_item_middle(Fl_Tree_Item *item) {
item = item ? item : first();
- if ( ! item ) return;
- show_item(item, h()/2 - item->h()/2);
+ if (item) show_item(item, (h()/2)-(item->h()/2));
}
/// Adjust the vertical scrollbar so that \p item is at the bottom of the
display.
+///
+/// \param[in] item The item to be shown. If NULL, first() is used.
+///
void Fl_Tree::show_item_bottom(Fl_Tree_Item *item) {
item = item ? item : first();
- if ( ! item ) return;
- show_item(item, h() - item->h());
+ if (item) show_item(item, h()-item->h());
}
/// Returns the vertical scroll position as a pixel offset.
@@ -863,11 +878,11 @@
}
/// Displays \p item, scrolling the tree as necessary.
-/// \param[in] item The item to be displayed.
+/// \param[in] item The item to be displayed. If NULL, first() is used.
///
void Fl_Tree::display(Fl_Tree_Item *item) {
- if ( ! item ) return;
- show_item_middle(item);
+ item = item ? item : first();
+ if (item) show_item_middle(item);
}
/**
Modified: branches/branch-1.3/src/Fl_Tree_Item.cxx
===================================================================
--- branches/branch-1.3/src/Fl_Tree_Item.cxx 2011-02-19 22:39:00 UTC (rev
8448)
+++ branches/branch-1.3/src/Fl_Tree_Item.cxx 2011-02-19 22:40:31 UTC (rev
8449)
@@ -299,7 +299,7 @@
///
Fl_Tree_Item *Fl_Tree_Item::add(const Fl_Tree_Prefs &prefs, char **arr) {
int t = find_child(*arr);
- Fl_Tree_Item *item;
+ Fl_Tree_Item *item = 0;
if ( t == -1 ) {
item = (Fl_Tree_Item*)add(prefs, *arr);
} else {
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
