doxy docs

include/nana/gui/detail/basic_window.hpp

@@ -1,4 +1,4 @@
-/*
+/**
  *	A Basic Window Widget Definition
  *	Nana C++ Library(http://www.nanapro.org)
  *	Copyright(C) 2003-2016 Jinhao(cnjinhao@hotmail.com)
@@ -7,7 +7,8 @@
  *	(See accompanying file LICENSE_1_0.txt or copy at 
  *	http://www.boost.org/LICENSE_1_0.txt)
  *
- *	@file: nana/gui/detail/basic_window.hpp
+ *	@file nana/gui/detail/basic_window.hpp
+ *  @brief A Basic Window Widget Definition
  */
 
 #ifndef NANA_GUI_DETAIL_BASIC_WINDOW_HPP
@@ -58,20 +59,18 @@ namespace detail
 		::nana::rectangle effective_range_;
 	};//end class caret_descriptor
 
-	//tab_type
+	/// Define some constant about tab category, these flags can be combine with operator |
-	//@brief: Define some constant about tab category, these flags can be combine with operator |
 	struct tab_type
 	{
 		enum t
 		{
-			none,		//process by nana
+			none,		///< process by nana
-			tabstop,	//move to the next tabstop window
+			tabstop,	///< move to the next tabstop window
-			eating,		//process by current window
+			eating,		///< process by current window
 		};
 	};
 
-	//struct basic_window
+	/// a window data structure descriptor 
-	//@brief: a window data structure descriptor 
 	struct basic_window
 		: public events_holder
 	{
@@ -88,8 +87,7 @@ namespace detail
 			bool rendered;
 		};
 
-		//basic_window
+		/// constructor for the root window
-		//@brief: constructor for the root window
 		basic_window(basic_window* owner, std::unique_ptr<widget_notifier_interface>&&, category::root_tag**);
 
 		template<typename Category>
@@ -106,8 +104,7 @@ namespace detail
 
 		~basic_window();
 
-		//bind_native_window
+		/// bind a native window and baisc_window
-		//@brief: bind a native window and baisc_window
 		void bind_native_window(native_window_type, unsigned width, unsigned height, unsigned extra_width, unsigned extra_height, paint::graphics&);
 
 		void frame_window(native_window_type);
@@ -116,13 +113,13 @@ namespace detail
 		bool visible_parents() const;
 		bool displayed() const;
 		bool belong_to_lazy() const;
-		const basic_window * child_caret() const; //Returns a child which owns a caret
+		const basic_window * child_caret() const; ///< Returns the child which owns the caret
 
 		bool is_draw_through() const;	///< Determines whether it is a draw-through window.
 
 		basic_window * seek_non_lite_widget_ancestor() const;
 	public:
-		//Override event_holder
+		/// Override event_holder
 		bool set_events(const std::shared_ptr<general_events>&) override;
 		general_events * get_events() const override;
 	private:
@@ -132,7 +129,7 @@ namespace detail
 #if defined(NANA_LINUX) || defined(NANA_MACOS)
 		point	pos_native;
 #endif
-		point	pos_root;	//coordinate for root window
+		point	pos_root;	///< coordinates of the root window
 		point	pos_owner;
 		size	dimension;
 		::nana::size	min_track_size;
@@ -147,9 +144,9 @@ namespace detail
 		basic_window	*owner;
 
 		native_string_type		title;
-		::nana::detail::drawer	drawer;	//Self Drawer with owen graphics
+		::nana::detail::drawer	drawer;	    ///< Self Drawer with owen graphics
-		basic_window*		root_widget;	//A pointer refers to the root basic window, if the window is a root, the pointer refers to itself.
+		basic_window*		root_widget;	///< A pointer refers to the root basic window, if the window is a root, the pointer refers to itself.
-		paint::graphics*	root_graph;		//Refer to the root buffer graphics
+		paint::graphics*	root_graph;		///< Refer to the root buffer graphics
 		cursor	predef_cursor;
 		std::unique_ptr<widget_notifier_interface> widget_notifier;
 
@@ -157,20 +154,20 @@ namespace detail
 		{
 			bool enabled	:1;
 			bool dbl_click	:1;
-			bool captured	:1;	//if mouse button is down, it always receive mouse move even the mouse is out of its rectangle
+			bool captured	:1;	///< if mouse button is down, it always receive mouse move even the mouse is out of its rectangle
 			bool modal		:1;
-			bool take_active:1;	//If take_active is false, other.active_window still keeps the focus.
+			bool take_active:1;	///< If take_active is false, other.active_window still keeps the focus.
 			bool refreshing	:1;
 			bool destroying	:1;
-			bool dropable	:1; //Whether the window has make mouse_drop event.
+			bool dropable	:1; ///< Whether the window has make mouse_drop event.
-			bool fullscreen	:1;	//When the window is maximizing whether it fit for fullscreen.
+			bool fullscreen	:1;	///< When the window is maximizing whether it fit for fullscreen.
 			bool borderless :1;
-			bool make_bground_declared	: 1;	//explicitly make bground for bground effects
+			bool make_bground_declared	: 1;	///< explicitly make bground for bground effects
-			bool ignore_menubar_focus	: 1;	//A flag indicates whether the menubar sets the focus.
+			bool ignore_menubar_focus	: 1;	///< A flag indicates whether the menubar sets the focus.
-			bool ignore_mouse_focus		: 1;	//A flag indicates whether the widget accepts focus when clicking on it
+			bool ignore_mouse_focus		: 1;	///< A flag indicates whether the widget accepts focus when clicking on it
-			bool space_click_enabled : 1;		//A flag indicates whether enable mouse_down/click/mouse_up when pressing and releasing whitespace key.
+			bool space_click_enabled : 1;		///< A flag indicates whether enable mouse_down/click/mouse_up when pressing and releasing whitespace key.
 			unsigned Reserved	:18;
-			unsigned char tab;		//indicate a window that can receive the keyboard TAB
+			unsigned char tab;		///< indicate a window that can receive the keyboard TAB
 			mouse_action	action;
 		}flags;
 
@@ -199,7 +196,7 @@ namespace detail
 
 			struct	attr_root_tag
 			{
-				container	frames;	//initialization is null, it will be created while creating a frame widget. Refer to WindowManager::create_frame
+				container	frames;	///< initialization is null, it will be created while creating a frame widget. Refer to WindowManager::create_frame
 				container	tabstop;
 				std::vector<edge_nimbus_action> effects_edge_nimbus;
 				basic_window*	focus{nullptr};
@@ -211,13 +208,13 @@ namespace detail
 				cursor			state_cursor{nana::cursor::arrow};
 				basic_window*	state_cursor_window{ nullptr };
 
-				std::function<void()> draw_through;	// A draw through renderer for root widgets.
+				std::function<void()> draw_through;	///< A draw through renderer for root widgets.
 			};
 
 			const category::flags category;
-			basic_window *active_window;	//if flags.take_active is false, the active_window still keeps the focus,
+			basic_window *active_window;	///< if flags.take_active is false, the active_window still keeps the focus,
-											//if the active_window is null, the parent of this window keeps focus.
+											///< if the active_window is null, the parent of this window keeps focus.
-			paint::graphics glass_buffer;	//if effect.bground is avaiable. Refer to window_layout::make_bground.
+			paint::graphics glass_buffer;	///< if effect.bground is avaiable. Refer to window_layout::make_bground.
 			update_state	upd_state;
 
 			union
@@ -230,8 +227,8 @@ namespace detail
 			~other_tag();
 		}other;
 
-		native_window_type	root;		//root Window handle
+		native_window_type	root;		    ///< root Window handle
-		unsigned			thread_id;		//the identifier of the thread that created the window.
+		unsigned			thread_id;		///< the identifier of the thread that created the window.
 		unsigned			index;
 		container			children;
 	};

include/nana/gui/widgets/listbox.hpp

@@ -517,7 +517,7 @@ namespace nana
 				basic_event<arg_listbox> checked;
 				basic_event<arg_listbox> selected;
 
-				/// An event occurs when a listbox category is double clicking.
+				/// An event that occurs when a listbox category is double clicking.
                 basic_event<arg_category> category_dbl_click;
 			};
 
@@ -536,19 +536,23 @@ namespace nana
 	}//end namespace drawerbase
 
 /*! \class listbox
-\brief A rectangle containing a list of strings from which the user can select. This widget contain a list of \a categories, with in turn contain a list of \a items. 
+\brief A rectangle containing a list of strings from which the user can select. 
-A category is a text with can be \a selected, \a checked and \a expanded to show the items.
+This widget contain a list of \a categories, with in turn contain a list of \a items. 
-An item is formed by \a column-fields, each corresponding to one of the \a headers. 
+A \a category is a text with can be \a selected, \a checked and \a expanded to show the \a items.
-An item can be \a selected and \a checked.
+An \a item is formed by \a column-fields, each corresponding to one of the \a headers. 
+An \a item can be \a selected and \a checked.
 The user can \a drag the header to \a resize it or to \a reorganize it. 
 By \a clicking on one header the list get \a reordered, first up, and then down alternatively.
 
-1. The resolver is used to resolute an object of the specified type for a listbox item.
+1. The resolver is used to resolute an object of the specified type into (or back from) a listbox item.
-3. nana::listbox creates the category 0 by default. The member functions without the categ parameter operate the items that belong to category 0.
+3. nana::listbox creates the category 0 by default. 
+   This is an special category, becouse it is invisible, while the associated items are visible. 
+   The optional, user-created categories begin at index 1 and are visibles.
+   The member functions without the categ parameter operate the items that belong to category 0.
 4. A sort compare is used for sorting the items. It is a strict weak ordering comparer that must meet the requirement:
 		Irreflexivity (comp(x, x) returns false) 
 	and 
-		antisymmetry(comp(a, b) != comp(b, a) returns true)
+		Antisymmetry(comp(a, b) != comp(b, a) returns true)
 	A simple example.
 		bool sort_compare( const std::string& s1, nana::any*, 
 						   const std::string& s2, nana::any*, bool reverse)
@@ -563,10 +567,10 @@ By \a clicking on one header the list get \a reordered, first up, and then down
 		{
 			if(o1 && o2) 	//some items may not attach a customer object.
 			{
-				int * i1 = o1->get<int>();
+				int * i1 = any_cast<int>(*o1);
-				int * i2 = o2->get<int>();
+				int * i2 = any_cast<int>(*o2);
 				return (i1 && i2 && (reverse ? *i1 > *i2 : *i1 < *i2));
- 							;//some types may not be int.
+ 					  // ^ some types may not be int.
 			}
 			return false;
 		}
@@ -710,7 +714,7 @@ By \a clicking on one header the list get \a reordered, first up, and then down
 
 		size_type size_categ() const;                   ///<Get the number of categories
 		size_type size_item() const;                    ///<The number of items in the default category
-		size_type size_item(size_type cat) const;          ///<The number of items in category "cat"
+		size_type size_item(size_type cat) const;       ///<The number of items in category "cat"
 
 		void enable_single(bool for_selection, bool category_limited);
 		void disable_single(bool for_selection);

include/nana/gui/widgets/slider.hpp

@@ -114,7 +114,7 @@ namespace nana
 			};
 		}//end namespace slider
 	}//end namespace drawerbase
-    /// A slider widget wich the user can drag for tracking
+    /// A slider widget wich the user can drag for tracking \todo add scheme ?
 	class slider
 		: public widget_object<category::widget_tag, drawerbase::slider::trigger, drawerbase::slider::slider_events>
 	{

source/gui/detail/window_layout.cpp

@@ -95,9 +95,9 @@ namespace nana
 			}
 
 			//read_visual_rectangle
-			//@brief:	Reads the visual rectangle of a window, the visual rectangle's reference frame is to root widget,
+			///@brief 	Reads the visual rectangle of a window, the visual rectangle's reference frame is to root widget,
-			//			the visual rectangle is a rectangular block that a window should be displayed on screen.
+			///			the visual rectangle is a rectangular block that a window should be displayed on screen.
-			//			The result is a rectangle that is a visible area for its ancesters.
+			///			The result is a rectangle that is a visible area for its ancesters.
 			bool window_layout::read_visual_rectangle(core_window_t* wd, nana::rectangle& visual)
 			{
 				if (! wd->displayed())	return false;

source/gui/widgets/listbox.cpp

@@ -338,6 +338,7 @@ namespace nana
 					column_t(native_string_type&& txt, unsigned px, size_type pos)
 						: text(std::move(txt)), pixels(px), index(pos)
 					{}
+					/// \todo introduce default cell format
 				};
 
 				using container = std::vector<column_t> ;
@@ -1828,9 +1829,7 @@ namespace nana
 			};//end class es_lister
 
 
-			//struct essence_t
+			/// created and live by the trigger, holds data for listbox: the state of the struct does not effect on member funcions, therefore all data members are public.
-			//@brief:	this struct gives many data for listbox,
-			//			the state of the struct does not effect on member funcions, therefore all data members are public.
 			struct essence_t
 			{
 				enum class item_state{normal, highlighted, pressed, grabbed, floated};
@@ -2644,6 +2643,7 @@ namespace nana
 					item_spliter_ = npos;
 				}
 
+				/// return true an set member item_spliter_ if x is in the spliter area after that header item (column)
 				bool mouse_spliter(const nana::rectangle& r, int x)
 				{
 					if(essence_->ptr_state == item_state::highlighted)
@@ -3003,9 +3003,19 @@ namespace nana
 					}
 				}
 
-				//Draws an item
+				/// Draws an item
-				//@param content_r the rectangle of list content
+				void _m_draw_item(const category_t& cat, 
-				void _m_draw_item(const category_t& cat, const index_pair& item_pos, const int x, const int y, const int txtoff, unsigned width, const nana::rectangle& content_r, const std::vector<size_type>& seqs, nana::color bgcolor, nana::color fgcolor, item_state state) const
+					              const index_pair& item_pos, 
+					              const int x, 
+					              const int y, 
+					              const int txtoff, 
+					              unsigned width, 
+					              const nana::rectangle& content_r,      ///< the rectangle where the full list content have to be drawn
+					              const std::vector<size_type>& seqs, 
+					              nana::color bgcolor, 
+					              nana::color fgcolor, 
+					              item_state state
+					) const
 				{
 					auto & item = cat.items[item_pos.item];
 
@@ -3022,7 +3032,7 @@ namespace nana
 						if (item.flags.selected)
 							bgcolor = bgcolor.blend(colors::black, 0.98);           // or "selected"
 						else
-							bgcolor = bgcolor.blend(essence_->scheme_ptr->item_selected, 0.7);
+							bgcolor = bgcolor.blend(essence_->scheme_ptr->item_selected, 0.7);   /// \todo create a parametre for amount of blend
 					}
 
 					unsigned show_w = width - essence_->scroll.offset_x;