diff --git a/include/nana/gui/widgets/button.hpp b/include/nana/gui/widgets/button.hpp index 5305e4f6..e57f3b12 100644 --- a/include/nana/gui/widgets/button.hpp +++ b/include/nana/gui/widgets/button.hpp @@ -1,13 +1,13 @@ -/* +/** * A Button Implementation * Nana C++ Library(http://www.nanapro.org) - * Copyright(C) 2003-2014 Jinhao(cnjinhao@hotmail.com) + * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) * * Distributed under the Boost Software License, Version 1.0. * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/button.hpp + * @file: nana/gui/widgets/button.hpp */ #ifndef NANA_GUI_WIDGET_BUTTON_HPP diff --git a/include/nana/gui/widgets/categorize.hpp b/include/nana/gui/widgets/categorize.hpp index 72df23d6..7f6b2521 100644 --- a/include/nana/gui/widgets/categorize.hpp +++ b/include/nana/gui/widgets/categorize.hpp @@ -1,4 +1,4 @@ -/* +/** * A Categorize Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -7,7 +7,7 @@ * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/categorize.hpp + * @file: nana/gui/widgets/categorize.hpp */ #ifndef NANA_GUI_WIDGET_CATEGORIZE_HPP diff --git a/include/nana/gui/widgets/checkbox.hpp b/include/nana/gui/widgets/checkbox.hpp index 0795fa1a..22f87fff 100644 --- a/include/nana/gui/widgets/checkbox.hpp +++ b/include/nana/gui/widgets/checkbox.hpp @@ -1,13 +1,13 @@ -/* +/** * A CheckBox Implementation * Nana C++ Library(http://www.nanapro.org) - * Copyright(C) 2003-2014 Jinhao(cnjinhao@hotmail.com) + * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) * * Distributed under the Boost Software License, Version 1.0. * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/checkbox.hpp + * @file: nana/gui/widgets/checkbox.hpp */ #ifndef NANA_GUI_WIDGET_CHECKBOX_HPP diff --git a/include/nana/gui/widgets/combox.hpp b/include/nana/gui/widgets/combox.hpp index 5a1f7e84..16b22faf 100644 --- a/include/nana/gui/widgets/combox.hpp +++ b/include/nana/gui/widgets/combox.hpp @@ -1,4 +1,4 @@ -/* +/** * A Combox Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -7,7 +7,7 @@ * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/combox.hpp + * @file: nana/gui/widgets/combox.hpp */ #ifndef NANA_GUI_WIDGETS_COMBOX_HPP diff --git a/include/nana/gui/widgets/date_chooser.hpp b/include/nana/gui/widgets/date_chooser.hpp index b4bf2126..9fc0ca8d 100644 --- a/include/nana/gui/widgets/date_chooser.hpp +++ b/include/nana/gui/widgets/date_chooser.hpp @@ -1,4 +1,4 @@ -/* +/** * A date chooser Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/float_listbox.hpp b/include/nana/gui/widgets/float_listbox.hpp index 67e48591..f28840ea 100644 --- a/include/nana/gui/widgets/float_listbox.hpp +++ b/include/nana/gui/widgets/float_listbox.hpp @@ -1,7 +1,7 @@ -/* +/** * A float_listbox Implementation * Nana C++ Library(http://www.nanapro.org) - * Copyright(C) 2003-2014 Jinhao(cnjinhao@hotmail.com) + * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) * * Distributed under the Boost Software License, Version 1.0. * (See accompanying file LICENSE_1_0.txt or copy at diff --git a/include/nana/gui/widgets/form.hpp b/include/nana/gui/widgets/form.hpp index 79ec3f6b..66047576 100644 --- a/include/nana/gui/widgets/form.hpp +++ b/include/nana/gui/widgets/form.hpp @@ -1,4 +1,4 @@ -/* +/** * A Form Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/frame.hpp b/include/nana/gui/widgets/frame.hpp index 0b04b4b6..6cc91dce 100644 --- a/include/nana/gui/widgets/frame.hpp +++ b/include/nana/gui/widgets/frame.hpp @@ -1,7 +1,7 @@ -/* +/** * A Frame Implementation * Nana C++ Library(http://www.nanapro.org) - * Copyright(C) 2003-2014 Jinhao(cnjinhao@hotmail.com) + * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) * * Distributed under the Boost Software License, Version 1.0. * (See accompanying file LICENSE_1_0.txt or copy at @@ -9,7 +9,7 @@ * * @file: nana/gui/widgets/frame.hpp * - * A frame provides a way to contain the platform window in a stdex GUI Window + * @brief A frame provides a way to contain the platform window in a stdex GUI Window */ #ifndef NANA_GUI_WIDGET_FRAME_HPP diff --git a/include/nana/gui/widgets/label.hpp b/include/nana/gui/widgets/label.hpp index c6488e5b..ba6a5cf0 100644 --- a/include/nana/gui/widgets/label.hpp +++ b/include/nana/gui/widgets/label.hpp @@ -1,7 +1,7 @@ -/* +/** * A Label Control Implementation * Nana C++ Library(http://www.nanapro.org) - * Copyright(C) 2003-2014 Jinhao(cnjinhao@hotmail.com) + * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) * * Distributed under the Boost Software License, Version 1.0. * (See accompanying file LICENSE_1_0.txt or copy at diff --git a/include/nana/gui/widgets/listbox.hpp b/include/nana/gui/widgets/listbox.hpp index 1bc087be..056349cd 100644 --- a/include/nana/gui/widgets/listbox.hpp +++ b/include/nana/gui/widgets/listbox.hpp @@ -1,4 +1,4 @@ -/* +/** * A List Box Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/menu.hpp b/include/nana/gui/widgets/menu.hpp index 36f99a28..03e61c9d 100644 --- a/include/nana/gui/widgets/menu.hpp +++ b/include/nana/gui/widgets/menu.hpp @@ -1,4 +1,4 @@ -/* +/** * A Menu implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2009-2014 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/panel.hpp b/include/nana/gui/widgets/panel.hpp index e1d98d00..248a36eb 100644 --- a/include/nana/gui/widgets/panel.hpp +++ b/include/nana/gui/widgets/panel.hpp @@ -1,4 +1,4 @@ -/* +/** * A Panel Implementation * Nana C++ Library(http://www.nanaro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -9,7 +9,7 @@ * * @file: nana/gui/widgets/panel.hpp * - * @brief: panel is a widget used for placing some widgets. + * @brief panel is a widget used for placing some widgets. */ #ifndef NANA_GUI_WIDGETS_PANEL_HPP diff --git a/include/nana/gui/widgets/picture.hpp b/include/nana/gui/widgets/picture.hpp index f4ba4f22..bd40f0e0 100644 --- a/include/nana/gui/widgets/picture.hpp +++ b/include/nana/gui/widgets/picture.hpp @@ -1,4 +1,4 @@ -/* +/** * A Picture Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -9,7 +9,7 @@ * * @file: nana/gui/widgets/picture.hpp * - * Used for showing a picture + * @brief Used for showing a picture */ #ifndef NANA_GUI_WIDGET_PICTURE_HPP #define NANA_GUI_WIDGET_PICTURE_HPP diff --git a/include/nana/gui/widgets/progress.hpp b/include/nana/gui/widgets/progress.hpp index 5464571b..91e58ab7 100644 --- a/include/nana/gui/widgets/progress.hpp +++ b/include/nana/gui/widgets/progress.hpp @@ -1,4 +1,4 @@ -/* +/** * A Progress Indicator Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/scroll.hpp b/include/nana/gui/widgets/scroll.hpp index 4b165313..f5598efd 100644 --- a/include/nana/gui/widgets/scroll.hpp +++ b/include/nana/gui/widgets/scroll.hpp @@ -1,4 +1,4 @@ -/* +/** * A Scroll Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/slider.hpp b/include/nana/gui/widgets/slider.hpp index ca1ab75a..0e32237d 100644 --- a/include/nana/gui/widgets/slider.hpp +++ b/include/nana/gui/widgets/slider.hpp @@ -1,4 +1,4 @@ -/* +/** * A Slider Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/spinbox.hpp b/include/nana/gui/widgets/spinbox.hpp index a1a85021..df962c39 100644 --- a/include/nana/gui/widgets/spinbox.hpp +++ b/include/nana/gui/widgets/spinbox.hpp @@ -1,4 +1,4 @@ -/* +/** * A Spin box widget * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/tabbar.hpp b/include/nana/gui/widgets/tabbar.hpp index 4d641461..94cf2407 100644 --- a/include/nana/gui/widgets/tabbar.hpp +++ b/include/nana/gui/widgets/tabbar.hpp @@ -1,4 +1,4 @@ -/* +/** * A Tabbar implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -7,8 +7,8 @@ * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/tabbar.hpp - * @brief: A tabbar contains tab items and toolbox for scrolling, closing, selecting items. + * @file: nana/gui/widgets/tabbar.hpp + * @brief A tabbar contains tab items and toolbox for scrolling, closing, selecting items. * */ #ifndef NANA_GUI_WIDGET_TABBAR_HPP diff --git a/include/nana/gui/widgets/textbox.hpp b/include/nana/gui/widgets/textbox.hpp index 045a05fc..a678d31c 100644 --- a/include/nana/gui/widgets/textbox.hpp +++ b/include/nana/gui/widgets/textbox.hpp @@ -1,4 +1,4 @@ -/* +/** * A Textbox Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/toolbar.hpp b/include/nana/gui/widgets/toolbar.hpp index 35f539ac..efb8af74 100644 --- a/include/nana/gui/widgets/toolbar.hpp +++ b/include/nana/gui/widgets/toolbar.hpp @@ -1,4 +1,4 @@ -/* +/** * A Toolbar Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) diff --git a/include/nana/gui/widgets/treebox.hpp b/include/nana/gui/widgets/treebox.hpp index 4d8748eb..db15a6cd 100644 --- a/include/nana/gui/widgets/treebox.hpp +++ b/include/nana/gui/widgets/treebox.hpp @@ -1,4 +1,4 @@ -/* +/** * A Tree Box Implementation * Nana C++ Library(http://www.nanapro.org) * Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com) @@ -7,12 +7,12 @@ * (See accompanying file LICENSE_1_0.txt or copy at * http://www.boost.org/LICENSE_1_0.txt) * - * @file: nana/gui/widgets/treebox.hpp - * @brief: + * @file: nana/gui/widgets/treebox.hpp + * @brief * The treebox organizes the nodes by a key string. - * The treebox would have a vertical scrollbar if the node - * is too many to display. And it does not have a horizontal scrollbar, - * the widget will adjust the node's displaying position for fitting. + * The treebox would have a vertical scrollbar if there are too many nodes + * to display. It does not have an horizontal scrollbar: + * the widget will adjust the node's displaying position for fitting. */ #ifndef NANA_GUI_WIDGETS_TREEBOX_HPP @@ -332,12 +332,13 @@ namespace nana }//end namespace treebox }//end namespace drawerbase - struct arg_treebox + /// a type of treebox event parameter + struct arg_treebox : public event_arg { - treebox& widget; - drawerbase::treebox::item_proxy & item; - bool operated; + treebox& widget; ///< where the event occurs + drawerbase::treebox::item_proxy & item; ///< the operated node + bool operated; ///< operation state of the event arg_treebox(treebox&, drawerbase::treebox::item_proxy&, bool operated); }; @@ -349,28 +350,30 @@ namespace nana struct treebox_events : public general_events { - basic_event expanded; - basic_event checked; - basic_event selected; - basic_event hovered; + basic_event expanded; ///< a user expands or shrinks a node + basic_event checked; ///< a user checks or unchecks a node + basic_event selected; ///< a user selects or unselects a node + basic_event hovered; ///< a user moves the cursor over a node }; }//end namespace treebox }//end namespace drawerbase - /// Displays a hierarchical list of items, such as the files and directories on a disk. - class treebox + /// \brief Displays a hierarchical list of items, such as the files and directories on a disk. + /// See also in [documentation](http://nanapro.org/en-us/help/widgets/treebox.htm) + class treebox :public widget_object < category::widget_tag, drawerbase::treebox::trigger, drawerbase::treebox::treebox_events> { public: - /// A type refers to the item and also used to iterate through the node. + /// A type refers to the item and is also used to iterate through the nodes. typedef drawerbase::treebox::item_proxy item_proxy; + /// state images for the node typedef drawerbase::treebox::node_image_tag node_image_type; - /// The interface of treebox item renderer + /// The interface of treebox user-defined item renderer typedef drawerbase::treebox::renderer_interface renderer_interface; - /// The interface of treebox compset_placer + /// The interface of treebox compset_placer to define the position of node components typedef drawerbase::treebox::compset_placer_interface compset_placer_interface; /// The default constructor without creating the widget. @@ -378,7 +381,7 @@ namespace nana /// \brief The construct that creates a widget. /// @param wd A handle to the parent window of the widget being created. - /// @param visible specifying the visible after creating. + /// @param visible specifying the visibility after creating. treebox(window wd, bool visible); /// \brief The construct that creates a widget. @@ -388,16 +391,16 @@ namespace nana treebox(window, const nana::rectangle& = rectangle(), bool visible = true); template - treebox & renderer(const ItemRenderer & rd) + treebox & renderer(const ItemRenderer & rd) ///< set user-defined node renderer { get_drawer_trigger().renderer(::nana::pat::cloneable(rd)); return *this; } - const nana::pat::cloneable & renderer() const; + const nana::pat::cloneable & renderer() const; ///< get user-defined node renderer template - treebox & placer(const Placer & r) + treebox & placer(const Placer & r) ///< location of a node components { get_drawer_trigger().placer(::nana::pat::cloneable(r)); return *this; @@ -406,38 +409,51 @@ namespace nana const nana::pat::cloneable & placer() const; /// \brief Eanble the widget to be draws automatically when it is operated. + /// + /// The treebox automatically redraws after certain operations, but, + /// under some circumstances, it is good to disable the automatic drawing mode, + /// for example, before adding nodes in a loop, disable the mode to avoiding + /// frequent and useless refresh for better performance, and then, after + /// the operations, enable the automatic redraw mode again. /// @param bool whether to enable. void auto_draw(bool); - /// \brief Enable the checkbox for each item of the widget. - /// @param bool wheter to enable. + /// \brief Enable the checkboxs for each item of the widget. + /// @param bool indicates whether to show or hide the checkboxs. treebox & checkable(bool enable); - /// Determinte whether the checkbox is enabled. - bool checkable() const; + + bool checkable() const; ///< Determinte whether the checkboxs are enabled. - node_image_type& icon(const nana::string& id) const; + /// \brief Creates an icon scheme with the specified name. + /// + /// The icon scheme includes 3 images for node states. + /// These states are 'normal', 'hovered' and 'expanded'. + /// If 'hovered' or 'expanded' are not set, it uses 'normal' state image for these 2 states. + /// See also in [documentation](http://nanapro.org/en-us/help/widgets/treebox.htm) + node_image_type& icon(const nana::string& id ///< the name of an icon scheme. If the name is not existing, it creates a new scheme for the name. + ) const; void icon_erase(const nana::string& id); item_proxy find(const nana::string& keypath); ///< Find an item though a specified keypath. /// Inserts a new node to treebox, but if the keypath exists returns the existing node. - item_proxy insert(const nana::string& path_key, ///< specifies the node hierarchical + item_proxy insert(const nana::string& path_key, ///< specifies the node hierarchy nana::string title ///< used for displaying ); /// Inserts a new node to treebox, but if the keypath exists returns the existing node. item_proxy insert( item_proxy pos, ///< the parent item node const nana::string& key, ///< specifies the new node - nana::string title ///< used for displaying. + nana::string title ///< title used for displaying in the new node. ); - item_proxy erase(item_proxy i); + item_proxy erase(item_proxy i); ///< Removes the node at pos and return the Item proxy following the removed node - void erase(const nana::string& keypath); + void erase(const nana::string& keypath); ///< Removes the node by the key path. nana::string make_key_path(item_proxy i, const nana::string& splitter) const;///root_division && impl_->window_handle) { impl_->root_division->field_area = API::window_size(impl_->window_handle); + if (impl_->root_division->field_area.empty()) return; + impl_->root_division->collocate(impl_->window_handle); for (auto & field : impl_->fields)