Merge pull request #35 from Jarod42/renaming_and_doc_improvements

Renaming and doc improvements

ChangeLog

@@ -1,3 +1,10 @@
+Version 1.1.0
+=============
+* Rectangle::intersect has been renamed to Rectangle::isIntersecting.
+* Widget::hasModalFocus has been renamed to Widget::isModalFocused.
+* Widget::hasModalMouseInputFocus has been renamed to Widget::isModalMouseInputFocused.
+* Widget::generateAction has been renamed to Widget::distributeActionEvent.
+
 Version 1.0.0
 =============
 * Large number of fixes to widgets/drawing/sdl2 support

TODO

@@ -1,4 +1,4 @@
-* Continue rebasing from 00d4287a5411f0f99c60b87e62fef26437e21ac6
+* Continue rebasing from 4c1d9a0bb1393dafb8efe28849c09914261a8ad8
 * Add a focus listener interface.
 * Make focus apply synchronously.
 * Graphics and input objects for DirectX.

include/guisan/actionevent.hpp

@@ -67,8 +67,24 @@ namespace gcn
     class Widget;
 
     /**
-     * Represents an action event.
+     * Represents an action event. An action event is an event
+     * that can be fired by a widget whenever an action has occured.
+     * What exactly an action is is up to the widget that fires
+     * the action event. An example is a Button which fires an action
+     * event as soon as the Button is clicked, another example is
+     * TextField which fires an action event as soon as the enter
+     * key is pressed.
      *
+     * Any object can listen for actions from widgets by implementing
+     * the ActionListener interface.
+     *
+     * If you have implement a widget of your own it's a good idea to 
+     * let the widget fire action events whenever you feel an action
+     * has occured so action listeners of the widget can be informed
+     * of the state of the widget.
+     *
+     * @see Widget::addActionListener, Widget::removeActionListener,
+     *      Widget::distributeActionEvent
      * @author Olof Naessén
      * @since 0.6.0
      */
@@ -79,8 +95,8 @@ namespace gcn
         /**
          * Constructor.
          *
-         * @param source the source widget of the event.
-         * @param id the identifier of the event.
+         * @param source The source widget of the event.
+         * @param id An identifier of the event.
          */
         ActionEvent(Widget* source, const std::string& id);
 
@@ -90,13 +106,19 @@ namespace gcn
         virtual ~ActionEvent();
 
         /**
-         * Gets the id of the event.
+         * Gets the identifier of the event. An identifier can
+         * be used to distinguish from two actions from the same
+         * widget or to let many widgets fire the same widgets
+         * that should be treated equally.
          *
-         * @return the id of the event.
+         * @return The identifier of the event.
          */
         const std::string& getId() const;
 
     protected:
+        /**
+         * Holds the identifier of the event.
+         */
         std::string mId;
     };
 }

include/guisan/actionlistener.hpp

@@ -65,11 +65,10 @@
 namespace gcn
 {
     /**
-     * Listener of action events from Widgets. To be able to
-     * listen for actions you must make a class which inherits
-     * from this class and implements the action function.
+     * Interface for listening for action events from widgets.
      *
-     * @see Widget::addActionListener
+     * @see Widget::addActionListener, Widget::removeActionListener,
+     *      ActionEvent
      * @author Olof Naessén
      * @author Per Larsson
      */
@@ -83,15 +82,23 @@ namespace gcn
         virtual ~ActionListener() { }
 
         /**
-         * Called when an action is recieved from a Widget. It is used
+         * Called when an action is recieved from a widget. It is used
          * to be able to recieve a notification that an action has
          * occured.
          *
-         * @param actionEvent the event of the action.
+         * @param actionEvent The event of the action.
          * @since 0.6.0
          */
         virtual void action(const ActionEvent& actionEvent) = 0;
 
+    protected:
+        /**
+         * Constructor.
+         *
+         * You should not be able to make an instance of ActionListener,
+         * therefore its constructor is protected.
+         */
+        ActionListener() {}
     };
 }
 

include/guisan/basiccontainer.hpp

@@ -66,10 +66,12 @@
 namespace gcn
 {
     /**
-     * Implements basic container behaviour. Most container will suffice by
-     * inheriting from this class.
+     * A base class for containers. The class implements the most
+     * common things for a container. If you are implementing a 
+     * container, consider inheriting from this class.
      *
      * @see Container
+     * @since 0.6.0
      */
     class GCN_CORE_DECLSPEC BasicContainer : public Widget, public DeathListener
     {
@@ -111,39 +113,46 @@ namespace gcn
         /**
          * Adds a widget to the basic container.
          *
-         * @param widget the widget to add.
+         * @param widget The widget to add.
+         * @see remove, clear
          */
         void add(Widget* widget);
 
         /**
          * Removes a widget from the basic container.
          *
-         * @param widget the widget to remove.
+         * @param widget The widget to remove.
+         * @see add, clear
          */
         virtual void remove(Widget* widget);
 
         /**
          * Clears the basic container from all widgets.
+         *
+         * @see remove, clear
          */
         virtual void clear();
 
         /**
-         * Draws children widgets.
+         * Draws the children widgets of the basic container.
          *
-         * @param graphics a Graphics object to draw with.
+         * @param graphics A graphics object to draw with.
          */
         virtual void drawChildren(Graphics* graphics);
 
         /**
-         * Calls logic for children widgets.
+         * Calls logic for the children widgets of the basic
+         * container.
          */
         virtual void logicChildren();
 
         /**
-         * Finds a widget given an id.
+         * Finds a widget given an id. This function can be useful
+         * when implementing a GUI generator for Guisan, such as
+         * the ability to create a Guisan GUI from an XML file.
          *
-         * @param id the id to find a widget by.
-         * @return the widget with the corrosponding id, 
+         * @param id The id to find a widget by.
+         * @return The widget with the corrosponding id, 
                    NULL of no widget is found.
          */
         virtual Widget* findWidgetById(const std::string& id);
@@ -152,6 +161,9 @@ namespace gcn
         typedef WidgetList::iterator WidgetListIterator;
         typedef WidgetList::reverse_iterator WidgetListReverseIterator;
 
+        /**
+         * Holds all widgets of the basic container.
+         */
         WidgetList mWidgets;
     };
 }

include/guisan/cliprectangle.hpp

@@ -63,8 +63,10 @@
 namespace gcn
 {
     /**
-     * A rectangle used when dealing with clipping. It is a regular
-     * Rectangle extended with variables for x offsets and y offsets.
+     * A rectangle used when dealing with clipping. A clip rectangle is
+     * a regular rectangle extended with variables for x offsets and y 
+     * offsets. The offsets are used for calculations from relative
+     * screen coordinates to actual screen coordinates.
      */
     class GCN_CORE_DECLSPEC ClipRectangle : public Rectangle
     {
@@ -78,31 +80,35 @@ namespace gcn
         /**
          * Constructor.
          *
-         * @param x the rectangle x coordinate.
-         * @param y the rectangle y coordinate.
-         * @param width the rectangle width.
-         * @param height the rectangle height.
-         * @param xOffset origin of drawing (used by Graphics).
-         * @param yOffset origin of drawing (used by Graphics) .
+         * @param x The rectangle x coordinate.
+         * @param y The rectangle y coordinate.
+         * @param width The rectangle width.
+         * @param height The rectangle height.
+         * @param xOffset The offset of the x coordinate. Used to for
+         *                calculating the actual screen coordinate from
+         *                the relative screen coordinate.
+         * @param yOffset The offset of the y coordinate. Used to for
+         *                calculating the actual screen coordinate from
+         *                the relative screen coordinate.
          */
-        ClipRectangle(int x, int y, int width, int height,
-                      int xOffset, int yOffset);
+        ClipRectangle(int x, int y, int width, int height, int xOffset, int yOffset);
 
         /**
-         * Copies x, y, width and height field from a Rectangle.
+         * Copy constructor. Copies x, y, width and height 
+         * field from a rectangle to a clip rectangle.
          *
-         * @param other the Rectangle to copy from.
-         * @returns a ClipRectangle.
+         * @param other The rectangle to copy data from.
+         * @returns A clip rectangle with data copyied from a rectangle.
          */
         const ClipRectangle& operator=(const Rectangle& other);
 
         /**
-         * x-origin of drawing (used by Graphics).
+         * Holds the x offset of the x coordinate.
          */
         int xOffset;
 
         /**
-         * y-origin of drawing (used by Graphics).
+         * Holds the y offset of the y coordinate.
          */
         int yOffset;
     };

include/guisan/color.hpp

@@ -74,89 +74,99 @@ namespace gcn
         Color();
 
         /**
-         * Constructs a color from the bytes in an integer. Call it with
-         * a hexadecimal constant for HTML-style color representation.
-         * The alpha component will be set to 255.
+         * Constructor. Constructs a color from the bytes in an integer. 
+         * Call it with a hexadecimal constant for HTML-style color representation.
+         * The alpha component is 255 by default.
          *
-         * EXAMPLE: Color(0xff50a0) constructs Gui-chan's favourite color.
+         * EXAMPLE: Color(0xff50a0) constructs a very nice pinkish color.
          *
          * NOTE: Because of this constructor, integers will be automatically
          *       casted to a color by your compiler.
          *
-         * @param color the color.
+         * @param color The color to initialise the object with.
          */
         Color(int color);
 
         /**
-         * Constructor.
+         * Constructor. The default alpha value is 255.
          *
          * @param r Red color component (range 0-255).
          * @param g Green color component  (range 0-255).
          * @param b Blue color component (range 0-255).
-         * @param a Color alpha, used for transparency. A value of 0 means
-         *          totaly transparent, 255 is totaly opaque (the default).
+         * @param a Alpha, used for transparency. A value of 0 means
+         *          totaly transparent, 255 is totaly opaque.
          */
         Color(int r, int g, int b, int a = 255);
 
         /**
          * Adds the RGB values of two colors together. The values will be
-         * clamped if they go out of range.
+         * clamped if they go out of range. 
          *
-         * @param color a color to add to this color.
-         * @return the resulting color with alpha set to 255.
+         * WARNING: This function will reset the alpha value of the
+         *          returned color to 255.
+         *
+         * @param color A color to add to this color.
+         * @return The added colors with an alpha value set to 255.
          */
         Color operator+(const Color& color) const;
 
         /**
          * Subtracts the RGB values of one color from another.
          * The values will be clamped if they go out of range.
          *
-         * @param color a color to subtract from this color.
-         * @return the resulting color with alpha set to 255.
+         * WARNING: This function will reset the alpha value of the
+         *          returned color to 255.
+         *
+         * @param color A color to subtract from this color.
+         * @return The subtracted colors with an alpha value set to 255.
          */
         Color operator-(const Color& color) const;
 
         /**
          * Multiplies the RGB values of a color with a float value.
          * The values will be clamped if they go out of range.
          *
-         * @param value the value to multiply the color with.
-         * @return the resulting color with alpha untouched.
+         * @param value The value to multiply the color with.
+         * @return The multiplied colors. The alpha value will, unlike
+         *         the add and subtract operations, be multiplied as
+         *         well.
          */
         Color operator*(float value) const;
 
         /**
          * Compares two colors.
          *
-         * @return true if the two colors have the same RGBA components.
+         * @return True if the two colors have the same RGBA components
+         *         false otherwise.
          */
         bool operator==(const Color& color) const;
 
         /**
          * Compares two colors.
          *
-         * @return true if the two colors have different RGBA components.
+         * @return True if the two colors have different RGBA components,
+         *         false otherwise.
          */
         bool operator!=(const Color& color) const;
 
         /**
-         * Red color component (range 0-255).
+         * Holds the red color component (range 0-255).
          */
         int r;
 
         /**
-         * Green color component (range 0-255).
+         *  Holds the green color component (range 0-255).
          */
         int g;
 
         /**
-         * Blue color component (range 0-255).
+         *  Holds the blue color component (range 0-255).
          */
         int b;
 
         /**
-         * Color alpha, used for transparency. A value of 0 means totaly
-         * transparent, 255 is totaly opaque (the default)
+         * Holds the alpha color component. A value of 0 means totally
+         * transparent while a value of 255 is considered opaque.
          */
         int a;
     };