menu: add some comments

6 files changed, 61 insertions, 6 deletions

diff --git a/src/menu/application.cpp b/src/menu/application.cpp
index b8392802..6bad5324 100644
--- a/src/menu/application.cpp
+++ b/src/menu/application.cpp
@@ -166,14 +166,17 @@ namespace usdx
 			// called from the thread owning the OpenGL contect
 			gl_thread = boost::this_thread::get_id();
 
+			// set-up the opengl projection matrix
 			glMatrixMode(GL_PROJECTION);
 			glLoadIdentity();
-
 			glOrtho(0.0f, get_width(), get_height(), 0.0f, -1.0f, 1.0f);
 
+			// reset the modelview matrix
 			glMatrixMode(GL_MODELVIEW);
 			glLoadIdentity();
 
+			// the depth layer is not used, so disable the depth test for
+			// higher performance
 			glDisable(GL_DEPTH_TEST);
 		}
 
diff --git a/src/menu/background.hpp b/src/menu/background.hpp
index b57959b7..660605dd 100644
--- a/src/menu/background.hpp
+++ b/src/menu/background.hpp
@@ -48,6 +48,11 @@ namespace usdx
 	public:
 		virtual ~Background();
 
+		/**
+		 * Returns the parent DrawableControl, this background is attached
+		 * to. Could be used for example to determine the size of the parent
+		 * control and adjust the background.
+		 */
 		const DrawableControl& get_parent(void) const;
 	};
 };
diff --git a/src/menu/background_image.hpp b/src/menu/background_image.hpp
index 67d117b9..1112aa54 100644
--- a/src/menu/background_image.hpp
+++ b/src/menu/background_image.hpp
@@ -34,6 +34,10 @@
 
 namespace usdx
 {
+	/**
+	 * This class draws an image as background for the drawable control an
+	 * instance of this class is attached to.
+	 */
 	class BackgroundImage : public Background
 	{
 	private:
diff --git a/src/menu/clipping_helper.hpp b/src/menu/clipping_helper.hpp
index 13e021f4..cbcf7320 100644
--- a/src/menu/clipping_helper.hpp
+++ b/src/menu/clipping_helper.hpp
@@ -33,12 +33,31 @@
 
 namespace usdx
 {
+	/**
+	 * ClippingHelper is a class for handling multiple nested clipping areas. It
+	 * handles the set up (during construction) and the tear down (during
+	 * deconstruction) of the new clipping. It also preserves the clipping
+	 * settings before using this class.
+	 *
+	 * This class is perfeclty suited for using it in a single scope to cleanup
+	 * the new clipping at the end of the current scope.
+	 */
 	class ClippingHelper
 	{
 	private:
 		static log4cpp::Category& log;
 
+		/**
+		 * Whether clipping was enabled before it is setup by this helper. If it
+		 * was enabled, it should not be disabled afterwards and the resulting
+		 * clipping rectangle should be the intersection between the old and the
+		 * new clipping area.
+		 */
 		GLboolean was_enabled;
+
+		/**
+		 * Buffer to cache the old clipping area and resore if afterwards.
+		 */
 		GLint scissor_box[4];
 
 		/**
@@ -47,6 +66,7 @@ namespace usdx
 		 * used for converting the OpenGL array to the common internal format.
 		 */
 		static Rectangle<int> makeRect(GLint box[4]);
+
 	public:
 		ClippingHelper(const Container*, const Rectangle<int>&);
 		virtual ~ClippingHelper();
diff --git a/src/menu/control.hpp b/src/menu/control.hpp
index cb18c330..b821e79b 100644
--- a/src/menu/control.hpp
+++ b/src/menu/control.hpp
@@ -29,9 +29,17 @@
 
 namespace usdx
 {
+	/**
+	 * Base class for all controls, either the drawable ones as well as the
+	 * hidden ones. This class handles a owner slave relation ship and handles
+	 * automatic destruction on destruction of the owner,
+	 */
 	class Control
 	{
 	private:
+		/**
+		 * Owner of this control. The owner is responsible for destruction.
+		 */
 		Control* owner;
 
 	protected:
@@ -44,6 +52,11 @@ namespace usdx
 		Control(Control*);
 		virtual ~Control();
 
+		/**
+		 * Change the current owner of this component. This requires to
+		 * unregister this control at the old owner and register it again
+		 * withthe new owner.
+		 */
 		void set_owner(Control*);
 		Control* get_owner(void) const;
 	};
diff --git a/src/menu/drawable.hpp b/src/menu/drawable.hpp
index 74ecef94..08471471 100644
--- a/src/menu/drawable.hpp
+++ b/src/menu/drawable.hpp
@@ -33,11 +33,21 @@ namespace usdx
 	class Drawable
 	{
 	private:
+		/**
+		 * Whether the drawable should be visible at the moment or not.
+		 */
 		bool visible;
 
 	protected:
 		/**
-		 * Pure virtual method, that descendant classes have to implement.
+		 * Pure virtual method, that descendant classes have to
+		 * implement. It should contain all actions that are required for
+		 * displaying this drawable. This methoed gets allways called from the
+		 * same thread, from that the video output is initialized at programm
+		 * start.
+		 *
+		 * WARNING: This method should not be called manually. If you want to
+		 * request, that a drawable is redrawn, use repaint() instead.
 		 */
 		virtual void draw(void) = 0;
 
@@ -46,17 +56,17 @@ namespace usdx
 		virtual ~Drawable(void) {};
 
 		/**
-		 * Method for redraw this Object. If visible issues draw.
+		 * Method for redraw this object. If visible executes the draw method.
 		 */
-		void repaint(void);
+		virtual void repaint(void);
 
 		/**
-		 * Setter for visible.
+		 * Set if the drawable should be visible.
 		 */
 		virtual void set_visible(bool value);
 
 		/**
-		 * Getter for visible.
+		 * Returns whether the drawable should be visible.
 		 */
 		virtual const bool is_visible(void) const;
 	};