Merge branch 'hotfixes-1.0.1' into develop

Conflicts:
	.gitignore
	include/nana/deploy.hpp
	source/deploy.cpp
	source/gui/widgets/listbox.cpp

include/nana/basic_types.hpp

@@ -18,7 +18,7 @@
 
 namespace nana
 {
-	//A constant value for the invalid position.
+	/// A constant value for the invalid position.
 	const std::size_t npos = static_cast<std::size_t>(-1);
 
 
@@ -127,8 +127,7 @@ namespace nana
 
 	using pixel_color_t = pixel_argb_t;
 
-	//http://www.w3.org/TR/2011/REC-css3-color-20110607/
-	//4.3. Extended color keywords
+	/// See extended CSS color keywords (4.3) in http://www.w3.org/TR/2011/REC-css3-color-20110607/
 	enum class colors
 	{
 		alice_blue = 0xf0f8ff,
@@ -283,7 +282,7 @@ namespace nana
 		//temporary defintions, these will be replaced by color schema
 		button_face_shadow_start = 0xF5F4F2,
 		button_face_shadow_end = 0xD5D2CA,
-		button_face = 0xD4D0C8,
+		button_face = 0xD4D0C8 , //,light_cyan
 		dark_border = 0x404040,
 		gray_border = 0x808080,
 		highlight = 0x1CC4F7
@@ -320,10 +319,10 @@ namespace nana
 
 		color blend(const color& bgcolor, bool ignore_bgcolor_alpha) const;
 
-		///< Blends two colors with the specified alpha, and the alpha values that come with these two colors are both ignored. 
+		/// Blends two colors with the specified alpha, and the alpha values that come with these two colors are both ignored. 
 		color blend(const color& bgcolor, double alpha) const;
 
-		///< Determines whether the color is completely transparent.
+		/// Determines whether the color is completely transparent.
 		bool invisible() const;
 		pixel_color_t px_color() const;
 		pixel_argb_t argb() const;
@@ -435,10 +434,10 @@ namespace nana
 		unsigned height;
 	};
 
-	class area_rotator
+	class rectangle_rotator
 	{
 	public:
-		area_rotator(bool rotated, const ::nana::rectangle& area);
+		rectangle_rotator(bool rotated, const ::nana::rectangle& area);
 
 		int x() const;
 		int & x_ref();
@@ -455,7 +454,7 @@ namespace nana
 	private:
 		bool rotated_;
 		::nana::rectangle area_;
-	};//end class area_rotator
+	};//end class rectangle_rotator
 
 	enum class arrange
 	{

include/nana/config.hpp

@@ -1,7 +1,7 @@
 /*
  *	Nana Configuration
  *	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
@@ -20,10 +20,13 @@
 	#define PLATFORM_SPEC_HPP <nana/detail/win32/platform_spec.hpp>
 
 	//Test if it is MINGW
-	#if defined(__MINGW32__)
+	#if defined(__MINGW32__) || defined(__MINGW64__)
 		#define NANA_MINGW
 		#define STD_CODECVT_NOT_SUPPORTED
-		//#define STD_THREAD_NOT_SUPPORTED	//Use this flag if MinGW version is older than 4.8.1
+		#if (__GNUC__ == 4) && ((__GNUC_MINOR__ < 8) || (__GNUC_MINOR__ == 8 && __GNUC_PATCHLEVEL__ < 1))
+			//Use this flag if MinGW version is older than 4.8.1
+			#define STD_THREAD_NOT_SUPPORTED
+		#endif
 	#endif
 #elif (defined(linux) || defined(__linux) || defined(__linux__) || defined(__GNU__) || defined(__GLIBC__)) && !defined(_CRAYC)
 //Linux:
@@ -35,6 +38,13 @@
 #	static_assert(false, "Only Windows and Unix are support now");
 #endif
 
+#if defined(NANA_MINGW) || defined(NANA_LINUX)
+	#if (__GNUC__ == 4) && (__GNUC_MINOR__ == 8) && (__GNUC_PATCHLEVEL__ <= 1)
+		//Some functions which are specified in 21.5 Numeric conversions in Strings library have not yet implemented
+		#define STD_NUMERIC_CONVERSIONS_NOT_SUPPORTED
+	#endif
+#endif
+
 //Here defines some flags that tell Nana what features will be supported.
 #define NANA_UNICODE
 

include/nana/deploy.hpp

@@ -23,8 +23,8 @@
 #undef NANA_WINDOWS
 #endif
 
-//Implement workarounds for MinGW
-#if defined(NANA_MINGW) && (__GNUC__ == 4) && (__GNUC_MINOR__ < 8)
+//Implement workarounds for GCC/MinGW which version is below 4.8.2
+#if defined(STD_NUMERIC_CONVERSIONS_NOT_SUPPORTED)
 namespace std
 {
 	//Workaround for no implemenation of std::stoi in MinGW.

include/nana/detail/linux_X11/msg_dispatcher.hpp

@@ -172,7 +172,7 @@ namespace detail
 			{
 				int pending;
 				{
-					nana::detail::platform_scope_guard psg;
+					nana::detail::platform_scope_guard lock;
 					pending = ::XPending(display_);
 					if(pending)
 					{

include/nana/gui/basis.hpp

@@ -96,7 +96,8 @@ namespace nana
 			//System Code for OS
 			os_pageup = 0x21, os_pagedown,
 			os_arrow_left = 0x25, os_arrow_up, os_arrow_right, os_arrow_down,
-			os_insert = 0x2D, os_del
+			os_insert = 0x2D, os_del ,
+            os_end = 0x23   , os_home //Pos 1
 		};
 	};
 

include/nana/gui/detail/basic_window.hpp

@@ -166,7 +166,8 @@ namespace detail
 			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
-			unsigned Reserved	:21;
+			bool ignore_menubar_focus : 1;	//A flag indicates whether the menubar sets the focus.
+			unsigned Reserved	:20;
 			unsigned char tab;		//indicate a window that can receive the keyboard TAB
 			mouse_action	action;
 		}flags;
@@ -175,7 +176,6 @@ namespace detail
 		{
 			caret_descriptor* caret;
 			std::shared_ptr<general_events> events_ptr;
-			general_events* attached_events;
 		}together;
 		
 		widget_colors* scheme{ nullptr };

include/nana/gui/detail/bedrock.hpp

@@ -54,13 +54,14 @@ namespace detail
 		native_window_type root(core_window_t*);
 
 		void set_menubar_taken(core_window_t*);
-		core_window_t* get_menubar_taken();
+
+		//Delay Restores focus when a menu which attached to menubar is closed
+		void delay_restore(int);
 		bool close_menu_if_focus_other_window(native_window_type focus);
 		void set_menu(native_window_type menu_window, bool is_keyboard_condition);
 		native_window_type get_menu(native_window_type owner, bool is_keyboard_condition);
 		native_window_type get_menu();
-		void remove_menu();
-		void empty_menu();
+		void erase_menu(bool try_destroy);
 
 		void get_key_state(arg_keyboard&);
 		bool set_keyboard_shortkey(bool yes);

include/nana/gui/detail/events_operation.hpp

@@ -23,7 +23,6 @@ namespace nana
 			void register_evt(event_handle);
 			void cancel(event_handle);
 			void erase(event_handle);
-			std::size_t size() const;
 		private:
 			mutable std::recursive_mutex mutex_;
 			std::unordered_set<event_handle>	register_;

include/nana/gui/detail/general_events.hpp

@@ -1,4 +1,4 @@
-/*
+/**
 *	Definition of General Events
 *	Nana C++ Library(http://www.nanapro.org)
 *	Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com)
@@ -19,7 +19,6 @@
 #include <functional>
 #include <memory>
 #include <vector>
-#include <algorithm>
 
 namespace nana
 {
@@ -43,11 +42,13 @@ namespace nana
 		void events_operation_cancel(event_handle);
 	}//end namespace detail
 
+    /// base clase for all event argument types
 	class event_arg
 	{
 	public:
 		virtual ~event_arg();
 
+        /// ignorable handlers behind the current one in a chain of event handlers will not get called.
 		void stop_propagation() const;
 		bool propagation_stopped() const;
 	private:
@@ -56,18 +57,19 @@ namespace nana
 
 	struct general_events;
 
+    /// the type of the members of general_events 
 	template<typename Arg>
 	class basic_event : public detail::event_interface
 	{
 	public:
-		typedef const typename std::remove_reference<Arg>::type & arg_reference;
+		using arg_reference = const typename std::remove_reference<Arg>::type &;
 	private:
 		struct docker
 			: public detail::docker_interface
 		{
 			basic_event * const event_ptr;
 			std::function<void(arg_reference)> invoke;
-			bool flag_entered{ false };
+
 			bool flag_deleted{ false };
 			bool unignorable{false};
 
@@ -89,7 +91,38 @@ namespace nana
 				return event_ptr;
 			}
 		};
+
+		//class emit_counter is a RAII helper for emitting count
+		//It is used for avoiding a try{}catch block which is required for some finial works when
+		//event handlers throw exceptions.
+		class emit_counter
+		{
+		public:
+			emit_counter(basic_event* evt)
+				: evt_{evt}
+			{
+				++evt->emitting_count_;
+			}
+
+			~emit_counter()
+			{
+				if ((0 == --evt_->emitting_count_) && evt_->deleted_flags_)
+				{
+					evt_->deleted_flags_ = false;
+					for (auto i = evt_->dockers_->begin(); i != evt_->dockers_->end();)
+					{
+						if (i->get()->flag_deleted)
+							i = evt_->dockers_->erase(i);
+						else
+							++i;
+					}
+				}
+			}
+		private:
+			basic_event * const evt_;
+		};
 	public:
+        /// It will get called firstly, because it is set at the beginning of the chain.
 		template<typename Function>
 		event_handle connect_front(Function && fn)
 		{
@@ -112,6 +145,7 @@ namespace nana
 			});
 		}
 
+		/// It will not get called if stop_propagation() was called.
 		template<typename Function>
 		event_handle connect(Function && fn)
 		{
@@ -127,13 +161,15 @@ namespace nana
 			return evt;
 		}
 
-		template<typename Function>
+		/// It will not get called if stop_propagation() was called.
+        template<typename Function>
 		event_handle operator()(Function&& fn)
 		{
 			return connect(std::forward<Function>(fn));
 		}
 
-		template<typename Function>
+		/// It will get called because it is unignorable.
+        template<typename Function>
 		event_handle connect_unignorable(Function && fn, bool in_front = false)
 		{
 			internal_scope_guard lock;
@@ -157,54 +193,37 @@ namespace nana
 			return (nullptr == dockers_ ? 0 : dockers_->size());
 		}
 
-		void emit(arg_reference& arg) const
+		void emit(arg_reference& arg)
 		{
 			internal_scope_guard lock;
 			if (nullptr == dockers_)
 				return;
 
-			//Make a copy to allow create/destroy a new event handler when the call of emit in an event.
-			const std::size_t fixed_size = 10;
-			docker* fixed_buffer[fixed_size];
-			docker** transitory = fixed_buffer;
+			emit_counter ec(this);
 
-			std::unique_ptr<docker*[]> variable_buffer;
 			auto& dockers = *dockers_;
-			if (dockers.size() > fixed_size)
-			{
-				variable_buffer.reset(new docker*[dockers.size()]);
-				transitory = variable_buffer.get();
-			}
+			const auto dockers_len = dockers.size();
 
-			auto output = transitory;
-			for (auto & dck : dockers)
+			//The dockers may resize when a new event handler is created by a calling handler.
+			//Traverses with position can avaid crash error which caused by a iterator which becomes invalid.
+			for (std::size_t pos = 0; pos < dockers_len; ++pos)
 			{
-				(*output++) = dck.get();
-			}
-
-			bool stop_propagation = false;
-			for (; transitory != output; ++transitory)
-			{
-				auto docker_ptr = *transitory;
-				if (stop_propagation && !docker_ptr->unignorable)
+				auto docker_ptr = dockers[pos].get();
+				if (docker_ptr->flag_deleted)
 					continue;
 
-				auto i = std::find_if(dockers.begin(), dockers.end(), [docker_ptr](std::unique_ptr<docker>& p){
-					return (docker_ptr == p.get());
-				});
-
-				if (i != dockers.end())
+				docker_ptr->invoke(arg);
+				if (arg.propagation_stopped())
 				{
-					docker_ptr->flag_entered = true;
-					docker_ptr->invoke(arg);
+					for (++pos; pos < dockers_len; ++pos)
+					{
+						auto docker_ptr = dockers[pos].get();
+						if (!docker_ptr->unignorable || docker_ptr->flag_deleted)
+							continue;
 
-					if (arg.propagation_stopped())
-						stop_propagation = true;
-					
-					docker_ptr->flag_entered = false;
-
-					if (docker_ptr->flag_deleted)
-						dockers.erase(i);
+						docker_ptr->invoke(arg);
+					}
+					break;
 				}
 			}
 		}
@@ -221,17 +240,20 @@ namespace nana
 			internal_scope_guard lock;
 			if (dockers_)
 			{
-				auto i = std::find_if(dockers_->begin(), dockers_->end(), [evt](const std::unique_ptr<docker>& sp)
+				for (auto i = dockers_->begin(), end = dockers_->end(); i != end; ++i)
 				{
-					return (reinterpret_cast<detail::docker_interface*>(evt) == sp.get());
-				});
-
-				if (i != dockers_->end())
-				{
-					if (i->get()->flag_entered)
-						i->get()->flag_deleted = true;
-					else
-						dockers_->erase(i);
+					if (reinterpret_cast<detail::docker_interface*>(evt) == i->get())
+					{
+						//Checks whether this event is working now.
+						if (emitting_count_ > 1)
+						{
+							i->get()->flag_deleted = true;
+							deleted_flags_ = true;
+						}
+						else
+							dockers_->erase(i);
+						break;
+					}
 				}
 			}
 		}
@@ -392,22 +414,27 @@ namespace nana
 			}
 		};
 	private:
+		unsigned emitting_count_{ 0 };
+		bool deleted_flags_{ false };
 		std::unique_ptr<std::vector<std::unique_ptr<docker>>> dockers_;
 	};
 
 	struct arg_mouse
 		: public event_arg
 	{
-		event_code evt_code;
-		::nana::window window_handle;
-		::nana::point pos;
-		bool left_button;
-		bool mid_button;
-		bool right_button;
-		bool shift;
-		bool ctrl;
+		event_code evt_code; ///< 
+		::nana::window window_handle;  ///< A handle to the event window
+		::nana::point pos;   ///< cursor position in the event window
+		bool left_button;    ///< mouse left button is pressed?
+		bool mid_button;     ///< mouse middle button is pressed?
+		bool right_button;   ///< mouse right button is pressed?
+		bool shift;          ///< keyboard Shift is pressed?
+		bool ctrl;           ///< keyboard Ctrl is pressed?
 	};
 
+    /// in arg_wheel event_code is event_code::mouse_wheel 
+    /// The type arg_wheel is derived from arg_mouse, a handler 
+    /// with prototype void(const arg_mouse&) can be set for mouse_wheel.
 	struct arg_wheel : public arg_mouse
 	{
 		enum class wheel{
@@ -415,98 +442,99 @@ namespace nana
 			horizontal
 		};
 
-		wheel	which;		///<which wheel is rotated
-		bool	upwards;	///< true if the wheel is rotated to the top/left, depends on which. false otherwise.
-		unsigned distance;	//expressed in multiples or divisions of 120
+		wheel	which;		///< which wheel is rotated
+		bool	upwards;	///< true if the wheel is rotated to the top/left, depends on which and false otherwise
+		unsigned distance;	///< expressed in multiples or divisions of 120
 	};
 
-	struct arg_dropfiles : public event_arg
+	struct arg_dropfiles : public event_arg  
 	{
-		::nana::window	window_handle;
-		::nana::point	pos;
-		std::vector<nana::string>	files;
+		::nana::window	window_handle;	    ///<  A handle to the event window
+		::nana::point	pos;	            ///<  cursor position in the event window
+		std::vector<nana::string>	files;	///<  external filenames
 	};
 
 	struct arg_expose : public event_arg
 	{
-		::nana::window window_handle;
-		bool exposed;
+		::nana::window window_handle;	///< A handle to the event window
+		bool exposed;	                ///< the window is visible?
 	};
 
 	struct arg_focus : public event_arg
 	{
-		::nana::window window_handle;
-		::nana::native_window_type receiver;
-		bool getting;
+		::nana::window window_handle;	      ///< A handle to the event window
+		::nana::native_window_type receiver;  ///< it is a native window handle, and specified which window receives focus
+		bool getting;	                      ///< the window received focus?
 	};
 
 	struct arg_keyboard : public event_arg
 	{
-		event_code evt_code;
-		::nana::window window_handle;
-		mutable nana::char_t key;
-		mutable bool ignore;
-		bool ctrl;
-		bool shift;
+		event_code evt_code;	    ///< it is event_code::key_press in current event
+		::nana::window window_handle;	///< A handle to the event window
+		mutable nana::char_t key;	///< the key corresponding to the key pressed
+		mutable bool ignore;	    ///< this member is not used
+		bool ctrl;	                ///< keyboard Ctrl is pressed?
+		bool shift;	                ///< keyboard Shift is pressed
 	};
 
 	struct arg_move : public event_arg
 	{
-		::nana::window window_handle;
-		int x;
-		int y;
+		::nana::window window_handle;	///< A handle to the event window
+		int x;	                        ///< 
+		int y;	                        ///< 
 	};
 
 	struct arg_resized : public event_arg
 	{
-		::nana::window window_handle;
-		unsigned width;
-		unsigned height;
+		::nana::window window_handle;	///< A handle to the event window
+		unsigned width;	                ///< new width in pixels.
+		unsigned height;	            ///< new height in pixels.
 	};
 
 	struct arg_resizing : public event_arg
 	{
-		::nana::window window_handle;
-		window_border border;
-		mutable unsigned width;
-		mutable unsigned height;
+		::nana::window window_handle;	///< A handle to the event window
+		window_border border;	        ///< the window is being resized by moving border
+		mutable unsigned width;	        ///< new width in pixels. If it is modified, the window's width will be the modified value
+		mutable unsigned height;	    ///< new height in pixels. If it is modified, the window's height will be the modified value
 	};
 
 	struct arg_unload : public event_arg
 	{
-		::nana::window window_handle;
-		mutable bool cancel;
+		::nana::window window_handle;	///< A handle to the event window
+		mutable bool cancel;	        ///< 
 	};
 
 	struct arg_destroy : public event_arg
 	{
-		::nana::window window_handle;
+		::nana::window window_handle;	///< A handle to the event window
 	};
 
+    /// provides some fundamental events that every widget owns.
 	struct general_events
 	{
 		virtual ~general_events(){}
-		basic_event<arg_mouse> mouse_enter;
-		basic_event<arg_mouse> mouse_move;
-		basic_event<arg_mouse> mouse_leave;
-		basic_event<arg_mouse> mouse_down;
-		basic_event<arg_mouse> mouse_up;
-		basic_event<arg_mouse> click;
-		basic_event<arg_mouse> dbl_click;
-		basic_event<arg_wheel> mouse_wheel;
-		basic_event<arg_dropfiles>	mouse_dropfiles;
-		basic_event<arg_expose>	expose;
-		basic_event<arg_focus>	focus;
-		basic_event<arg_keyboard>	key_press;
-		basic_event<arg_keyboard>	key_release;
-		basic_event<arg_keyboard>	key_char;
-		basic_event<arg_keyboard>	shortkey;
+		basic_event<arg_mouse> mouse_enter; ///< the cursor enters the window
+		basic_event<arg_mouse> mouse_move;  ///< the cursor moves on the window
+		basic_event<arg_mouse> mouse_leave; ///< the cursor leaves the window
+		basic_event<arg_mouse> mouse_down;  ///< the user presses the mouse button
+		basic_event<arg_mouse> mouse_up;    ///< the user presses the mouse button
+		basic_event<arg_mouse> click;       ///< the window is clicked, but occurs after mouse_down and before mouse_up
+		basic_event<arg_mouse> dbl_click;   ///< the window is double clicked
+		basic_event<arg_wheel> mouse_wheel; ///< the mouse wheel rotates while the window has focus
+		basic_event<arg_dropfiles>	mouse_dropfiles; ///< the mouse drops some external data while the window enable accepting files
+		basic_event<arg_expose>	expose;     ///< the visibility changes
+		basic_event<arg_focus>	focus;      ///< the window receives or loses keyboard focus
+		basic_event<arg_keyboard>	key_press;   ///< a key is pressed while the window has focus. event code is event_code::key_press
+		basic_event<arg_keyboard>	key_release; ///< a key is released while the window has focus. event code is event_code::key_release
+		basic_event<arg_keyboard>	key_char;    ///< a character, whitespace or backspace is pressed. event code is event_code::key_char
+		basic_event<arg_keyboard>	shortkey;    ///< a defined short key is pressed. event code is event_code::shortkey
 
-		basic_event<arg_move>		move;
-		basic_event<arg_resizing>	resizing;
-		basic_event<arg_resized>	resized;
+		basic_event<arg_move>		move;     ///< the window changes position
+		basic_event<arg_resizing>	resizing; ///< the window is changing its size
+		basic_event<arg_resized>	resized;  ///< the window is changing its size
 
-		basic_event<arg_destroy>	destroy;
+		basic_event<arg_destroy>	destroy;  ///< the window is destroyed, but occurs when all children have been destroyed
 	};
 
 	namespace detail

include/nana/gui/detail/handle_manager.hpp

@@ -25,7 +25,6 @@
 
 #include <map>
 #include <iterator>
-#include <algorithm>
 
 namespace nana
 {
@@ -260,9 +259,14 @@ namespace nana
 				{
 					if(cond_type::is_queue(handle))
 					{
-						auto i = std::find(queue.begin(), queue.end(), handle);
-						if(i != queue.end())
-							queue.erase(i);
+						for (auto i = queue.begin(); i != queue.end(); ++i)
+						{
+							if (handle == *i)
+							{
+								queue.erase(i);
+								break;
+							}
+						}
 					}
 				}
 			};

include/nana/gui/detail/inner_fwd_implement.hpp

@@ -1,7 +1,7 @@
 /*
  *	Implementations of Inner Forward Declaration
  *	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
@@ -19,7 +19,6 @@
 #include "../../paint/graphics.hpp"
 
 #include <map>
-#include <algorithm>
 
 namespace nana{
 	namespace detail
@@ -62,12 +61,15 @@ namespace nana{
 			void umake(window wd)
 			{
 				if (wd == nullptr) return;
-				auto i = std::find_if(keybase_.begin(), keybase_.end(), [wd](const item_type& m){
-					return (m.handle == wd);
-				});
 
-				if (i != keybase_.end())
-					keybase_.erase(i);
+				for (auto i = keybase_.begin(), end = keybase_.end(); i != end; ++i)
+				{
+					if (i->handle == wd)
+					{
+						keybase_.erase(i);
+						break;
+					}
+				}
 			}
 
 			std::vector<unsigned long> keys(window wd) const

include/nana/gui/place.hpp

@@ -10,7 +10,7 @@
  *	@file: nana/gui/place.cpp
  *
  *	@contributions:
- *	min/max and splitter bar initial weight by qPCR4vir.
+ *	min/max and splitter bar initial weight by Ariel Vina-Rodriguez.
  */
 
 #ifndef NANA_GUI_PLACE_HPP

include/nana/gui/programming_interface.hpp

@@ -77,6 +77,8 @@ namespace API
 		window create_frame(window, const rectangle&, widget* attached);
 
 		paint::graphics* window_graphics(window);
+
+		void delay_restore(bool);
 	}//end namespace dev
 
 
@@ -193,7 +195,7 @@ namespace API
 		return *comp_wdg_colors;
 	}
 
-	nana::point window_position(window);
+	point window_position(window);
 	void move_window(window, int x, int y);
 	void move_window(window wd, const rectangle&);
 
@@ -203,9 +205,11 @@ namespace API
 	void draw_through(window, std::function<void()>);
 	void map_through_widgets(window, native_drawable_type);
 
-	nana::size window_size(window);
+	size window_size(window);
 	void window_size(window, const size&);
-	bool window_rectangle(window, rectangle&);
+	size window_outline_size(window);
+	void window_outline_size(window, const size&);
+	bool get_window_rectangle(window, rectangle&);
 	bool track_window_size(window, const size&, bool true_for_max);   ///< Sets the minimum or maximum tracking size of a window.
 	void window_enabled(window, bool);
 	bool window_enabled(window);
@@ -235,7 +239,7 @@ namespace API
 	cursor window_cursor(window);
 
 	void activate_window(window);
-	bool is_focus_window(window);
+	bool is_focus_ready(window);
 	window focus_window();
 	void focus_window(window);
 
@@ -288,7 +292,6 @@ namespace API
 	void register_menu_window(window, bool has_keyboard);
 	bool attach_menubar(window menubar);
 	void detach_menubar(window menubar);
-	void restore_menubar_taken_window();
 
 	bool is_window_zoomed(window, bool ask_for_max);  ///<Tests a window whether it is maximized or minimized.
 

include/nana/gui/screen.hpp

@@ -27,25 +27,37 @@ namespace nana
 		/// The index of monitor.
 		virtual std::size_t get_index() const = 0;
 
+		virtual bool is_primary_monitor() const = 0;
+
 		/// Returns the positional coordinates and size of the display device in reference to the desktop area
 		virtual const ::nana::rectangle& area() const = 0;
+		virtual const ::nana::rectangle& workarea() const = 0;
 	};
 
 	class screen
 	{
+		struct implement;
 	public:
 		static ::nana::size desktop_size();
 		static ::nana::size primary_monitor_size();
-		static std::shared_ptr<display>	from_point(const point&);
-		static std::shared_ptr<display> from_window(window);
+
+		screen();
+
+		/// Reload has no preconditions, it's safe to call on moved-from
+		void reload();
 
 		/// Returns the number of display monitors
 		std::size_t count() const;
 
-		std::shared_ptr<display> get_display(std::size_t index) const;
-		std::shared_ptr<display> get_primary() const;
+		display& from_point(const point&);
+		display& from_window(window);
+
+		display& get_display(std::size_t index) const;
+		display& get_primary() const;
 
 		void for_each(std::function<void(display&)>) const;
+	private:
+		std::shared_ptr<implement> impl_;
 	};
 }//end namespace nana
 

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

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

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

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

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)

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 

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)

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

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 

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)
@@ -8,6 +8,7 @@
  *	http://www.boost.org/LICENSE_1_0.txt)
  *
  *	@file: nana/gui/widgets/listbox.hpp
+ *	@contributors: Ariel Vina-Rodriguez
  *
  */
 
@@ -16,6 +17,7 @@
 #include "widget.hpp"
 #include <nana/concepts.hpp>
 #include <nana/key_type.hpp>
+//#include <nana/paint/graphics.hpp>
 #include <functional>
 #include <initializer_list>
 
@@ -27,7 +29,7 @@ namespace nana
 	{
 		namespace listbox
 		{
-			typedef std::size_t size_type;
+			using size_type = std::size_t ;
 
 			struct cell
 			{
@@ -35,7 +37,7 @@ namespace nana
 				{
 					::nana::color bgcolor;
 					::nana::color fgcolor;
-
+                    /// ::nana::paint::font font;  \todo 
 					format() = default;
 					format(const ::nana::color& bgcolor, const ::nana::color& fgcolor);
 				};
@@ -112,7 +114,8 @@ namespace nana
 				std::size_t pos_{0};
 			};
 
-			struct index_pair
+            /// usefull for both absolute and display (sorted) positions
+            struct index_pair
 			{
 				size_type cat;	//The pos of category
 				size_type item;	//the pos of item in a category.
@@ -169,7 +172,8 @@ namespace nana
 			class drawer_header_impl;
 			class drawer_lister_impl;
 
-			class trigger: public drawer_trigger
+			/// mostly works on display positions
+            class trigger: public drawer_trigger
 			{
 			public:
 				trigger();
@@ -192,19 +196,29 @@ namespace nana
 				void dbl_click(graph_reference, const arg_mouse&)	override;
 				void resized(graph_reference, const arg_resized&)		override;
 				void key_press(graph_reference, const arg_keyboard&)	override;
+				void key_char(graph_reference, const arg_keyboard&)	override;
 			private:
 				essence_t * essence_;
 				drawer_header_impl *drawer_header_;
 				drawer_lister_impl *drawer_lister_;
 			};//end class trigger
 
-			class item_proxy
+            /// operate with absolute positions and contain only the position but montain pointers to parts of the real items 
+			/// item_proxy self, it references and iterators are not invalidated by sort()
+            class item_proxy
 				: public std::iterator<std::input_iterator_tag, item_proxy>
 			{
 			public:
 				item_proxy(essence_t*);
 				item_proxy(essence_t*, const index_pair&);
 
+                /// the main porpose of this it to make obvious that item_proxy operate with absolute positions, and dont get moved during sort()
+                static item_proxy from_display(essence_t *ess, const index_pair &relative) ;
+                item_proxy from_display(const index_pair &relative) const;
+
+                /// posible use: last_selected_display = last_selected.to_display().item; use with caution, it get invalidated after a sort()
+                index_pair to_display() const;
+
 				bool empty() const;
 
 				item_proxy & check(bool ck);
@@ -237,7 +251,7 @@ namespace nana
 					auto && cells = ores.move_cells();
 					auto cols = columns();
 					cells.resize(cols);
-					for (auto pos = 0; pos < cols; ++pos)
+					for (auto pos = 0u; pos < cols; ++pos)
 					{
 						auto & el = cells[pos];
 						if (el.text.size() == 1 && el.text[0] == nana::char_t(0))
@@ -318,8 +332,8 @@ namespace nana
 				essence_t * _m_ess() const;
 			private:
 				std::vector<cell> & _m_cells() const;
-				nana::any * _m_value(bool alloc_if_empty);
-				const nana::any * _m_value() const;
+				nana::any         * _m_value(bool alloc_if_empty);
+				const nana::any   * _m_value() const;
 			private:
 				essence_t * ess_;
 				category_t*	cat_{nullptr};
@@ -334,7 +348,7 @@ namespace nana
 				cat_proxy(essence_t*, size_type pos);
 				cat_proxy(essence_t*, category_t*);
 
-				/// Append an item at end of the category, set_value determines whether assign T object to the value of item.
+				/// Append an item at abs end of the category, set_value determines whether assign T object to the value of item.
 				template<typename T>
 				item_proxy append(T&& t, bool set_value = false)
 				{
@@ -367,13 +381,18 @@ namespace nana
 				item_proxy cbegin() const;
 				item_proxy cend() const;
 
-				item_proxy at(size_type pos) const;
+				item_proxy at(size_type pos_abs) const;
 				item_proxy back() const;
 
-				/// Returns the index of a item by its display pos, the index of the item isn't changed after sorting.
+				/// Returns the absolute index of a item by its display pos, the index of the item isn't changed after sorting.
+				/// convert from display order to absolute (find the real item in that display pos) but without check from current active sorting, in fact using just the last sorting !!!
 				size_type index_by_display_order(size_type disp_order) const;
-				size_type display_order(size_type pos) const;
-				size_type position() const;
+				
+          		/// find display order for the real item but without check from current active sorting, in fact using just the last sorting !!!
+                size_type display_order(size_type pos) const;
+				
+                /// this cat position
+                size_type position() const;
 
 				/// Returns the number of items
 				size_type size() const;
@@ -410,9 +429,21 @@ namespace nana
 			private:
 				essence_t*	ess_{nullptr};
 				category_t*	cat_{nullptr};
-				size_type	pos_{0};
+				size_type	pos_{0};  ///< Absolute position, not relative to display, and dont change during sort()
 			};
-		}
+		
+            struct export_options
+            {
+               nana::string sep = nana::string {STR("\t" )}, 
+                            endl= nana::string {STR("\n")} ; 
+               bool only_selected_items{true}, 
+                    only_checked_items {false},
+                    only_visible_columns{true};
+
+               using columns_indexs = std::vector<size_type>;
+               columns_indexs columns_order;
+            };
+        }
 	}//end namespace drawerbase
 
 	struct arg_listbox
@@ -446,12 +477,12 @@ namespace nana
 		}
 	}//end namespace drawerbase
 
-/*! \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 items. 
+/*! \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. 
 A category is a text with can be \a selected, \a checked and \a expanded to show the items.
 An item is formed by \a column-fields, each corresponding to one of the \a headers. 
 An item can be \a selected and \a checked.
 The user can \a drag the header to \a reisize it or to \a reorganize it. 
-By \a clicking on a header the list get \a reordered, first up, and then down alternatively,
+By \a clicking on a header the list get \a reordered, first up, and then down alternatively.
 */
 	class listbox
 		:	public widget_object<category::widget_tag, drawerbase::listbox::trigger, drawerbase::listbox::listbox_events, drawerbase::listbox::scheme>,
@@ -465,7 +496,9 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 		using selection = drawerbase::listbox::selection;    ///<A container type for items.
 		using iresolver = drawerbase::listbox::iresolver;
 		using oresolver = drawerbase::listbox::oresolver;
-		using cell = drawerbase::listbox::cell;
+		using cell      = drawerbase::listbox::cell;
+		using export_options= drawerbase::listbox::export_options;
+		using columns_indexs= drawerbase::listbox::size_type;
 	public:
 		listbox() = default;
 		listbox(window, bool visible);
@@ -481,8 +514,11 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 		void append(std::initializer_list<nana::string>); ///<Appends categories at the end
 		cat_proxy insert(cat_proxy, nana::string);
 		cat_proxy at(size_type pos) const;
+
+        /// add categories in order when use a key?
 		listbox& ordered_categories(bool);
 
+        /// return a proxy to tha cat with the key or create a new one in the right order
 		template<typename Key>
 		cat_proxy operator[](const Key & ck)
 		{
@@ -507,7 +543,7 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 			return cat_proxy(&_m_ess(), _m_at_key(p));
 		}
 
-		item_proxy at(const index_pair&) const;
+		item_proxy at(const index_pair &abs_pos) const;
 
 		void insert(const index_pair&, nana::string);         ///<Insert a new item with a text in the first column.
 
@@ -536,20 +572,26 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 			_m_ease_key(&key);
 		}
 
-		            ///Sets a strick weak ordering comparer for a column
+		bool sortable() const;
+		void sortable(bool enable);
+		
+		///Sets a strict weak ordering comparer for a column
 		void set_sort_compare(size_type col, std::function<bool(const nana::string&, nana::any*,
 				                                        const nana::string&, nana::any*, bool reverse)> strick_ordering);
 
-		void sort_col(size_type col, bool reverse = false);
+		/// sort() and ivalidate any existing reference from display position to absolute item, that is: after sort() display offset point to different items
+        void sort_col(size_type col, bool reverse = false);
 		size_type sort_col() const;
-		void unsort();
+
+        /// potencially ivalidate any existing reference from display position to absolute item, that is: after sort() display offset point to different items
+        void unsort();
 		bool freeze_sort(bool freeze);
 
-		selection selected() const;                         ///<Get the indexs of all the selected items
-
+		selection selected() const;                         ///<Get the absolute indexs of all the selected items
+                                    
 		void show_header(bool);
 		bool visible_header() const;
-		void move_select(bool upwards);                     ///<Selects an item besides the current selected item.
+		void move_select(bool upwards);  ///<Selects an item besides the current selected item in the display.
 
 		size_type size_categ() const;                   ///<Get the number of categories
 		size_type size_item() const;                    ///<The number of items in the default category
@@ -557,6 +599,7 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 
 		void enable_single(bool for_selection, bool category_limited);
 		void disable_single(bool for_selection);
+        export_options& def_export_options();
 	private:
 		drawerbase::listbox::essence_t & _m_ess() const;
 		nana::any* _m_anyobj(size_type cat, size_type index, bool allocate_if_empty) const;

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)
@@ -139,16 +139,16 @@ namespace nana
 		void clear();								///< Erases all of the items.
 		/// Closes the menu. It does not destroy the menu; just close the window for the menu.
 		void close();
-		void image(std::size_t index, const paint::image& icon);
-		void check_style(std::size_t index, checks);
-		void checked(std::size_t index, bool);
-		bool checked(std::size_t index) const;
-		void enabled(std::size_t index, bool);///< Enables or disables the mouse or keyboard input for the item.
-		bool enabled(std::size_t index) const;
-		void erase(std::size_t index);			 	 ///< Removes the item
-		bool link(std::size_t index, menu& menu_obj);///< Link a menu to the item as a sub menu.
-		menu * link(std::size_t index);		 	     ///< Retrieves a linked sub menu of the item.
-		menu *create_sub_menu(std::size_t index);
+		void image(std::size_t pos, const paint::image& icon);
+		void check_style(std::size_t pos, checks);
+		void checked(std::size_t pos, bool);
+		bool checked(std::size_t pos) const;
+		void enabled(std::size_t pos, bool);///< Enables or disables the mouse or keyboard input for the item.
+		bool enabled(std::size_t pos) const;
+		void erase(std::size_t pos);			 	 ///< Removes the item
+		bool link(std::size_t pos, menu& menu_obj);///< Link a menu to the item as a sub menu.
+		menu * link(std::size_t pos);		 	     ///< Retrieves a linked sub menu of the item.
+		menu *create_sub_menu(std::size_t pos);
 		void popup(window owner, int x, int y);     ///< Popup the menu at the owner window. 
 		void popup_await(window owner, int x, int y);
 		void answerer(std::size_t index, const event_fn_t&);  ///< Modify answerer of the specified item.
@@ -171,7 +171,6 @@ namespace nana
 		const pat::cloneable<renderer_interface>& renderer() const;
 
 	private:
-		void _m_destroy_menu_window();
 		void _m_popup(window, int x, int y, bool called_by_menubar);
 	private:
 		implement * impl_;

include/nana/gui/widgets/menubar.hpp

@@ -24,12 +24,16 @@ namespace nana
 			class item_renderer
 			{
 			public:
-				enum state_t{state_normal, state_highlight, state_selected};
-				typedef nana::paint::graphics& graph_reference;
+				enum class state
+				{
+					normal, highlighted, selected
+				};
+
+				using graph_reference = paint::graphics&;
 
 				item_renderer(window, graph_reference);
-				virtual void background(const nana::point& pos, const nana::size& size, state_t);
-				virtual void caption(int x, int y, const nana::string& text);
+				virtual void background(const point&, const ::nana::size&, state);
+				virtual void caption(const point&, const ::nana::string&);
 			private:
 				window	handle_;
 				graph_reference graph_;
@@ -61,7 +65,6 @@ namespace nana
 				bool _m_popup_menu();
 				void _m_total_close();
 				bool _m_close_menu();
-				void _m_unload_menu_window();
 				std::size_t _m_item_by_pos(const ::nana::point&);
 				bool _m_track_mouse(const ::nana::point&);
 				void _m_draw();

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)
@@ -8,8 +8,10 @@
  *	http://www.boost.org/LICENSE_1_0.txt)
  *
  *	@file: nana/gui/widgets/panel.hpp
+ *	@author: Jinhao
+ *	@contributors: Ariel Vina-Rodriguez
  *
- *	@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
@@ -44,11 +46,13 @@ namespace nana
 		panel(window wd, bool visible)
 		{
 			this->create(wd, rectangle(), visible);
+			this->bgcolor(API::bgcolor(wd));
 		}
 
 		panel(window wd, const nana::rectangle& r = rectangle(), bool visible = true)
 		{
 			this->create(wd, r, visible);
+			this->bgcolor(API::bgcolor(wd));
 		}
 
 		bool transparent() const

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
@@ -34,7 +34,7 @@ namespace nana
 				void attached(widget_reference, graph_reference)	override;
 			private:
 				void refresh(graph_reference)	override;
-				void _m_draw_background();
+				void _m_draw_background(unsigned,unsigned);
 			private:
 				implement * const impl_;
 			};

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)

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)
@@ -8,6 +8,7 @@
  *	http://www.boost.org/LICENSE_1_0.txt)
  *
  *	@file: nana/gui/widgets/scroll.hpp
+ *	@contributors: Ariel Vina-Rodriguez
  */
 #ifndef NANA_GUI_WIDGET_SCROLL_HPP
 #define NANA_GUI_WIDGET_SCROLL_HPP
@@ -49,17 +50,17 @@ namespace nana
 
 			struct metrics_type
 			{
-				typedef std::size_t size_type;
+				using size_type = std::size_t;
 
-				size_type peak;
-				size_type range;
-				size_type step;
-				size_type value;
+				size_type peak;   ///< the whole total
+				size_type range;  ///< how many is shonw on a page, that is, How many to scroll after click on first or second
+				size_type step;   ///< how many to scroll by click in forward  or backward
+				size_type value;  ///< current offset calculated from the very beginnig
 
 				buttons what;
 				bool pressed;
-				size_type	scroll_length;
-				int			scroll_pos;
+				size_type	scroll_length;       ///< the lenght in pixels of the central button show how many of the total (peak) is shonw (range)
+				int			scroll_pos;          ///< in pixels, and correspond to the offsset from the very beginning (value)
 				int			scroll_mouse_offset;
 
 				metrics_type();
@@ -70,11 +71,11 @@ namespace nana
 			public:
 				struct states
 				{
-					enum{none, highlight, actived, selected};
+					enum{ none, highlight, actived, selected };
 				};
 
-				typedef nana::paint::graphics& graph_reference;
-				const static unsigned fixedsize = 16;
+				using graph_reference = paint::graphics&;
+				const static unsigned fixedsize = 16; // make it part of a new "metric" in the widget_scheme
 
 				drawer(metrics_type& m);
 				void set_vertical(bool);
@@ -114,7 +115,7 @@ namespace nana
 
 				void peak(size_type s)
 				{
-					if(graph_ && (metrics_.peak != s))
+					if (graph_ && (metrics_.peak != s))
 					{
 						metrics_.peak = s;
 						API::refresh_window(widget_->handle());
@@ -123,10 +124,10 @@ namespace nana
 
 				void value(size_type s)
 				{
-					if(s + metrics_.range > metrics_.peak)
+					if (s + metrics_.range > metrics_.peak)
 						s = metrics_.peak - metrics_.range;
 
-					if(graph_ && (metrics_.value != s))
+					if (graph_ && (metrics_.value != s))
 					{
 						metrics_.value = s;
 						_m_emit_value_changed();
@@ -137,7 +138,7 @@ namespace nana
 
 				void range(size_type s)
 				{
-					if(graph_ && (metrics_.range != s))
+					if (graph_ && (metrics_.range != s))
 					{
 						metrics_.range = s;
 						API::refresh_window(widget_->handle());
@@ -151,31 +152,31 @@ namespace nana
 
 				bool make_step(bool forward, unsigned multiple)
 				{
-					if(graph_)
+					if (graph_)
 					{
 						size_type step = (multiple > 1 ? metrics_.step * multiple : metrics_.step);
 						size_type value = metrics_.value;
-						if(forward)
+						if (forward)
 						{
 							size_type maxv = metrics_.peak - metrics_.range;
-							if(metrics_.peak > metrics_.range && value < maxv)
+							if (metrics_.peak > metrics_.range && value < maxv)
 							{
-								if(maxv - value >= step)
+								if (maxv - value >= step)
 									value += step;
 								else
 									value = maxv;
 							}
 						}
-						else if(value)
+						else if (value)
 						{
-							if(value > step)
+							if (value > step)
 								value -= step;
 							else
 								value = 0;
 						}
 						size_type cmpvalue = metrics_.value;
 						metrics_.value = value;
-						if(value != cmpvalue)
+						if (value != cmpvalue)
 						{
 							_m_emit_value_changed();
 							return true;
@@ -221,24 +222,24 @@ namespace nana
 				void mouse_move(graph_reference graph, const ::nana::arg_mouse& arg) override
 				{
 					bool redraw = false;
-					if(metrics_.pressed && (metrics_.what == buttons::scroll))
+					if (metrics_.pressed && (metrics_.what == buttons::scroll))
 					{
 						size_type cmpvalue = metrics_.value;
 						drawer_.scroll_delta_pos(graph, (Vertical ? arg.pos.y : arg.pos.x));
-						if(cmpvalue != metrics_.value)
+						if (cmpvalue != metrics_.value)
 							_m_emit_value_changed();
 						redraw = true;
 					}
 					else
 					{
 						buttons what = drawer_.what(graph, arg.pos);
-						if(metrics_.what != what)
+						if (metrics_.what != what)
 						{
 							redraw = true;
 							metrics_.what = what;
 						}
 					}
-					if(redraw)
+					if (redraw)
 					{
 						drawer_.draw(graph, metrics_.what);
 						API::lazy_refresh();
@@ -247,11 +248,11 @@ namespace nana
 
 				void mouse_down(graph_reference graph, const arg_mouse& arg) override
 				{
-					if(arg.left_button)
+					if (arg.left_button)
 					{
 						metrics_.pressed = true;
 						metrics_.what = drawer_.what(graph, arg.pos);
-						switch(metrics_.what)
+						switch (metrics_.what)
 						{
 						case buttons::first:
 						case buttons::second:
@@ -265,13 +266,13 @@ namespace nana
 							break;
 						case buttons::forward:
 						case buttons::backward:
-							{
-								size_type cmpvalue = metrics_.value;
-								drawer_.auto_scroll();
-								if(cmpvalue != metrics_.value)
-									_m_emit_value_changed();
-							}
-							break;
+						{
+							size_type cmpvalue = metrics_.value;
+							drawer_.auto_scroll();
+							if (cmpvalue != metrics_.value)
+								_m_emit_value_changed();
+						}
+						break;
 						default:	//Ignore buttons::none
 							break;
 						}
@@ -294,7 +295,7 @@ namespace nana
 
 				void mouse_leave(graph_reference graph, const arg_mouse&) override
 				{
-					if(metrics_.pressed) return;
+					if (metrics_.pressed) return;
 
 					metrics_.what = buttons::none;
 					drawer_.draw(graph, buttons::none);
@@ -303,7 +304,7 @@ namespace nana
 
 				void mouse_wheel(graph_reference graph, const arg_wheel& arg) override
 				{
-					if(make_step(arg.upwards == false, 3))
+					if (make_step(arg.upwards == false, 3))
 					{
 						drawer_.draw(graph, metrics_.what);
 						API::lazy_refresh();
@@ -333,7 +334,7 @@ namespace nana
 
 	/// Provides a way to display an object which is larger than the window's client area.
 	template<bool Vertical>
-	class scroll
+	class scroll    // add a widget scheme?
 		: public widget_object<category::widget_tag, drawerbase::scroll::trigger<Vertical>, drawerbase::scroll::scroll_events<Vertical>>
 	{
 		typedef widget_object<category::widget_tag, drawerbase::scroll::trigger<Vertical> > base_type;
@@ -345,29 +346,29 @@ 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  specify the visibility after creation.
 		scroll(window wd, bool visible)
 		{
-			this->create(wd, rectangle(), visible);
+			this->create(wd, rectangle(), visible);   // add a widget scheme? and take some colors from these wd?
 		}
 
 		///  \brief The construct that creates a widget.
 		/// @param wd  A handle to the parent window of the widget being created.
 		/// @param r  the size and position of the widget in its parent window coordinate.
-		/// @param visible  specifying the visible after creating.
+		/// @param visible  specify the visibility after creation.
 		scroll(window wd, const rectangle& r, bool visible = true)
 		{
 			this->create(wd, r, visible);
 		}
 
 		///  \brief Determines whether it is scrollable.
-		/// @param for_less  whether it can be scrolled for a less value.
+		/// @param for_less  whether it can be scrolled for a less value (backward or "up" if true, forward or "down" if false).
 		bool scrollable(bool for_less) const
 		{
 			auto & m = this->get_drawer_trigger().metrics();
 			return (for_less ? (0 != m.value) : (m.value < m.peak - m.range));
 		}
-
+		///  the whole total (peak)
 		size_type amount() const
 		{
 			return this->get_drawer_trigger().metrics().peak;
@@ -378,7 +379,7 @@ namespace nana
 			return this->get_drawer_trigger().peak(Max);
 		}
 
-		/// Get the range of the widget.
+		/// Get the range of the widget (how many is shonw on a page, that is, How many to scroll after click on first or second)
 		size_type range() const
 		{
 			return this->get_drawer_trigger().metrics().range;
@@ -390,7 +391,7 @@ namespace nana
 			return this->get_drawer_trigger().range(r);
 		}
 
-		///  \brief Get the value.
+		///  \brief Get the value (current offset calculated from the very beginnig)
 		/// @return the value.
 		size_type value() const
 		{
@@ -419,12 +420,12 @@ namespace nana
 			return this->get_drawer_trigger().step(s);
 		}
 
-		///  \brief Increase/decrease values by a step.
+		///  \brief Increase/decrease values by a step (alternativelly by some number of steps).
 		/// @param forward  it determines whether increase or decrease.
 		/// @return true if the value is changed.
-		bool make_step(bool forward)
+		bool make_step(bool forward, unsigned steps = 1)
 		{
-			if(this->get_drawer_trigger().make_step(forward, 1))
+			if (this->get_drawer_trigger().make_step(forward, steps))
 			{
 				API::refresh_window(this->handle());
 				return true;
@@ -437,13 +438,17 @@ namespace nana
 		/// @return true if the vlaue is changed.
 		bool make_scroll(bool forward)
 		{
-			if(this->get_drawer_trigger().make_step(forward, 3))
-			{
-				API::refresh_window(this->handle());
-				return true;
-			}
-			return false;
+			return this->make_step(forward, 3);	// set this 3 in the metrics of the widget scheme ?
 		}
+
+		///  \brief Increase/decrease values by a page as if it is scrolled page up.
+		/// @param forward  it determines whether increase or decrease.
+		/// @return true if the vlaue is changed.
+		bool make_page_scroll(bool forward)
+		{
+			return this->make_step(forward, range() - 1);
+		}
+
 	};//end class scroll
 }//end namespace nana
 #endif

include/nana/gui/widgets/skeletons/text_editor.hpp

@@ -157,7 +157,8 @@ namespace nana{	namespace widgets
 
 			void set_accept(std::function<bool(char_type)>);
 			void set_accept(accepts);
-			bool respone_keyboard(char_type);
+			bool respond_char(char_type);
+			bool respond_key(char_type);
 
 			void typeface_changed();
 
@@ -227,7 +228,6 @@ namespace nana{	namespace widgets
 			void del();
 			void backspace(bool record_undo = true);
 			void undo(bool reverse);
-			bool move(nana::char_t);
 			void move_ns(bool to_north);	//Moves up and down
 			void move_left();
 			void move_right();

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)

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)

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

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)

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)

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<arg_treebox> expanded;
-				basic_event<arg_treebox> checked;
-				basic_event<arg_treebox> selected;
-				basic_event<arg_treebox> hovered;
+				basic_event<arg_treebox> expanded; ///< a user expands or shrinks a node
+				basic_event<arg_treebox> checked;  ///< a user checks or unchecks a node
+				basic_event<arg_treebox> selected; ///< a user selects or unselects a node
+				basic_event<arg_treebox> 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<typename ItemRenderer>
-		treebox & renderer(const ItemRenderer & rd)
+		treebox & renderer(const ItemRenderer & rd) ///< set user-defined node renderer
 		{
 			get_drawer_trigger().renderer(::nana::pat::cloneable<renderer_interface>(rd));
 			return *this;
 		}
 
-		const nana::pat::cloneable<renderer_interface> & renderer() const;
+		const nana::pat::cloneable<renderer_interface> & renderer() const;  ///< get user-defined node renderer
 
 		template<typename Placer>
-		treebox & placer(const Placer & r)
+		treebox & placer(const Placer & r) ///< location of a node components
 		{
 			get_drawer_trigger().placer(::nana::pat::cloneable<compset_placer_interface>(r));
 			return *this;
@@ -406,38 +409,51 @@ namespace nana
 		const nana::pat::cloneable<compset_placer_interface> & 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;///<returns the key path
-		item_proxy selected() const;
+		item_proxy selected() const; ///< returns the selected node
 	};//end class treebox
 }//end namespace nana
 #endif

include/nana/gui/widgets/widget.hpp

@@ -1,4 +1,4 @@
-/*
+/**
  *	The fundamental widget class implementation
  *	Nana C++ Library(http://www.nanapro.org)
  *	Copyright(C) 2003-2015 Jinhao(cnjinhao@hotmail.com)
@@ -409,6 +409,16 @@ namespace nana
 		{
 			API::map_through_widgets(handle(), drawable);
 		}
+
+		void outline_size(const ::nana::size& sz)
+		{
+			API::window_outline_size(handle(), sz);
+		}
+
+		::nana::size outline_size() const
+		{
+			return API::window_outline_size(handle());
+		}
 	protected:
 		DrawerTrigger& get_drawer_trigger()
 		{

include/nana/key_type.hpp

@@ -22,10 +22,10 @@ namespace nana
 			virtual ~key_interface(){}
 
 			virtual bool same_type(const key_interface*) const = 0;
-			virtual bool compare(const key_interface*) const = 0;
+			virtual bool compare(const key_interface*) const = 0; ///< is this key less than right key? [call it less(rk), less_than(rk) or compare_less(rk)?: if (lk.less_than(rk )) ]
 		};	//end class key_interface
 
-		//Use less compare for equal compare
+		//Use less compare for equal compare [call it equal_by_less()?]
 		inline bool pred_equal_by_less(const key_interface * left, const key_interface* right)
 		{
 			return (left->compare(right) == false) && (right->compare(left) == false);

include/nana/paint/detail/image_bmp.hpp

@@ -1,3 +1,15 @@
+/*
+ *	Bitmap Format Graphics Implementation
+ *	Nana C++ Library(http://www.nanapro.org)
+ *	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/paint/detail/image_bmp.hpp
+ *	@contributors: Ryan Gonzalez
+ */
 #ifndef NANA_PAINT_DETAIL_IMAGE_BMP_HPP
 #define NANA_PAINT_DETAIL_IMAGE_BMP_HPP
 

include/nana/paint/image.hpp

@@ -1,6 +1,7 @@
 /*
  *	Paint Image Implementation
- *	Copyright(C) 2003-2013 Jinhao(cnjinhao@hotmail.com)
+ *	Nana C++ Library(http://www.nanapro.org)
+ *	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 
@@ -39,6 +40,8 @@ namespace paint
 		bool empty() const;
 		operator unspecified_bool_t() const;
 		void close();
+
+		bool alpha() const;
 		nana::size size() const;
 		void paste(graphics& dst, int x, int y) const;
 		void paste(const nana::rectangle& r_src, graphics& dst, const point& p_dst) const;///< Paste the area of picture specified by r_src into the destination graphics specified by dst at position p_dst.

include/nana/system/dataexch.hpp

@@ -14,7 +14,13 @@
 #define NANA_SYSTEM_DATAEXCH_HPP
 #include <nana/basic_types.hpp>
 
-namespace nana{ namespace system{
+namespace nana{
+
+namespace paint{
+	class graphics;
+}
+
+namespace system{
             /// a data exchange mechanism through Windows Clipboard, X11 Selection.
 	class dataexch
 	{
@@ -26,6 +32,7 @@ namespace nana{ namespace system{
 
 		void set(const nana::char_t* text);
 		void set(const nana::string& text);
+		bool set(const nana::paint::graphics& g);
 		void get(nana::string& str);
 	private:
 		bool _m_set(unsigned type, const void* buf, std::size_t size);