From 723fe666cfc32043b73ffe7f625cde343a59c378 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Sat, 19 Feb 2011 22:40:31 +0000 Subject: Document NULL item behavior, small code mods for same. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8449 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Tree.H | 39 ++++++++++------------------ src/Fl_Tree.cxx | 73 +++++++++++++++++++++++++++++++--------------------- src/Fl_Tree_Item.cxx | 2 +- 3 files changed, 59 insertions(+), 55 deletions(-) diff --git a/FL/Fl_Tree.H b/FL/Fl_Tree.H index 792ae4adf..7bbc38a3c 100644 --- a/FL/Fl_Tree.H +++ b/FL/Fl_Tree.H @@ -231,11 +231,11 @@ public: 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 @@ public: 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 @@ public: /// 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 @@ public: /// - 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 @@ public: /// 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 @@ public: /// 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 @@ public: /// - 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 @@ public: /// 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 @@ public: /// 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 @@ public: } /// 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 @@ public: /// 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 @@ public: /// 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 @@ public: /// - 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 @@ public: /// 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 @@ public: /// 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 @@ public: /// - 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 @@ public: /// 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 @@ public: /// 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 diff --git a/src/Fl_Tree.cxx b/src/Fl_Tree.cxx index 03d3ccdff..a96ed2d6f 100644 --- a/src/Fl_Tree.cxx +++ b/src/Fl_Tree.cxx @@ -126,6 +126,8 @@ Fl_Tree_Item* Fl_Tree::add(const char *path) { } /// 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 @@ Fl_Tree_Item* Fl_Tree::insert_above(Fl_Tree_Item *above, const char *name) { /// 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. +/// 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. +/// Fl_Tree_Item* Fl_Tree::add(Fl_Tree_Item *item, const char *name) { return(item->add(_prefs, name)); } @@ -160,12 +162,12 @@ Fl_Tree_Item* Fl_Tree::add(Fl_Tree_Item *item, const char *name) { /// 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 @@ Fl_Tree_Item *Fl_Tree::find_item(const char *path) { /// 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 @@ void Fl_Tree::draw() { /// /// \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 @@ void Fl_Tree::set_item_focus(Fl_Tree_Item *item) { /// \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 @@ Fl_Tree_Item* Fl_Tree::first() { /// } /// \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 @@ Fl_Tree_Item *Fl_Tree::next(Fl_Tree_Item *item) { /// } /// \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 @@ Fl_Tree_Item *Fl_Tree::first_selected_item() { /// \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 @@ int Fl_Tree::handle(int e) { /// 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 @@ int Fl_Tree::deselect_all(Fl_Tree_Item *item, int docallback) { /// 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 @@ int Fl_Tree::select_all(Fl_Tree_Item *item, int docallback) { /// - 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 @@ int Fl_Tree::select_only(Fl_Tree_Item *selitem, int docallback) { /// 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 @@ void Fl_Tree::show_item(Fl_Tree_Item *item, int yoff) { /// 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 @@ void Fl_Tree::vposition(int pos) { } /// 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); } /** diff --git a/src/Fl_Tree_Item.cxx b/src/Fl_Tree_Item.cxx index 053f0adb7..eca41a5a8 100644 --- a/src/Fl_Tree_Item.cxx +++ b/src/Fl_Tree_Item.cxx @@ -299,7 +299,7 @@ Fl_Tree_Item *Fl_Tree_Item::add(const Fl_Tree_Prefs &prefs, const char *new_labe /// 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 { -- cgit v1.2.3