Documentation|Client|Widgets: Cleanup and more apidocs

doomsday/client/include/ui/widgets/buttonwidget.h

@@ -25,6 +25,8 @@
 
 /**
  * Clickable button widget.
+ *
+ * @ingroup gui
  */
 class ButtonWidget : public LabelWidget
 {

doomsday/client/include/ui/widgets/consolecommandwidget.h

@@ -27,6 +27,8 @@
  *
  * Whenever the current game changes, the lexicon is automatically updated to
  * include the terms of the loaded game.
+ *
+ * @ingroup gui
  */
 class ConsoleCommandWidget : public QObject, public LineEditWidget
 {

doomsday/client/include/ui/widgets/consolewidget.h

@@ -31,6 +31,8 @@
  *
  * ConsoleWidget expects to be bottom-left anchored. It resizes its height
  * automatically. The user can drag the right edge to resize the widget.
+ *
+ * @ingroup gui
  */
 class ConsoleWidget : public QObject, public GuiWidget
 {

doomsday/client/include/ui/widgets/fontlinewrapping.h

@@ -38,12 +38,21 @@ class FontLineWrapping : public de::shell::ILineWrapping
     void setFont(de::Font const &font);
     de::Font const &font() const;
 
-    bool isEmpty() const;
+    /**
+     * Clears the wrapping completely. The text is also cleared.
+     */
     void clear();
+
+    /**
+     * Resets the existing wrapping (isEmpty() will return @c true) but does not
+     * clear the text.
+     */
     void reset();
+
     void wrapTextToWidth(de::String const &text, int maxWidth);
     void wrapTextToWidth(de::String const &text, de::Font::RichFormat const &format, int maxWidth);
 
+    bool isEmpty() const;
     de::String const &text() const;
     de::shell::WrappedLine line(int index) const;
     int width() const;
@@ -52,13 +61,28 @@ class FontLineWrapping : public de::shell::ILineWrapping
     int indexAtWidth(de::Rangei const &range, int width) const;
 
     /**
-     * Calculates the total height of the wrapped lined in pixels, taking into
-     * consideration the appropriate amount of line spacing.
+     * Calculates the total height of the wrapped lined in pixels. If there are
+     * multiple lines, takes into consideration the appropriate leading between
+     * lines.
      */
     int totalHeightInPixels() const;
 
+    /**
+     * Determines the coordinates of a character's top left corner in pixels.
+     *
+     * @param line       Wrapped line number.
+     * @param charIndex  Index of the character on the wrapped line. Each
+     *                   wrapped line is indexed starting from zero.
+     *
+     * @return XY coordinates of the character.
+     */
     de::Vector2i charTopLeftInPixels(int line, int charIndex);
 
+    /**
+     * Returns the left indentation for a wrapped line.
+     *
+     * @param index  Wrapped line number.
+     */
     int lineIndent(int index) const;
 
 private:

doomsday/client/include/ui/widgets/guirootwidget.h

@@ -29,6 +29,7 @@ class ClientWindow;
 
 /**
  * Graphical root widget.
+ *
  * @ingroup gui
  */
 class GuiRootWidget : public de::RootWidget

doomsday/client/include/ui/widgets/guiwidget.h

@@ -29,20 +29,59 @@ class GuiRootWidget;
 
 /**
  * Base class for graphical widgets.
+ *
+ * Each GuiWidget has one RuleRectangle that defines the widget's position in
+ * the view. However, all widgets are allowed to draw outside this rectangle
+ * and react to events occurring outside it. In essence, all widgets thus cover
+ * the entire view area and can be thought as a (hierarchical) stack.
+ *
+ * GuiWidget is the base class for all widgets of a GUI application. However, a
+ * GuiWidget does not necessarily need to have a visible portion on the screen:
+ * its entire purpose may be to handle events, for example.
+ *
+ * The common features GuiWidget offers to all widgets are:
+ *
+ * - Background geometry builder. All widgets may use this to build geometry for
+ *   the background of the widget. However, widgets are also allowed to fully
+ *   generate all of their geometry from scratch.
+ *
+ * - Access to the UI Style.
+ *
+ * - GuiWidget can be told which font and text color to use using a style
+ *   definition identifier (e.g., "editor.hint"). These style elements are then
+ *   conveniently accessible using methods of GuiWidget.
+ *
+ * - Opacity properity. Opacities respect the hierarchical organization of
+ *   widgets: GuiWidget::visibleOpacity() returns the opacity of a particular
+ *   widget where all the parent widgets' opacities are factored in.
+ *
+ * - Hit testing: checking if a view space point should be considered to be
+ *   inside the widget. The default implementation simply checks if the point is
+ *   inside the widget's rectangle. Derived classes may override this to adapt
+ *   hit testing to their particular visual shape.
+ *
+ * - Logic for handling more complicated interactions such as a mouse pointer
+ *   click (press then release inside or outside).
+ *
  * @ingroup gui
  */
 class GuiWidget : public de::Widget
 {
 public:
+    /**
+     * Properties of the widget's background's apperance.
+     * GuiWidget::glMakeGeometry() uses this to construct the background
+     * geometry of the widget.
+     */
     struct Background {
         enum Type {
-            None,
-            GradientFrame
+            None,               ///< No background or solid fill.
+            GradientFrame       ///< Use the "gradient frame" from the UI atlas.
         };
         de::Vector4f solidFill; ///< Always applied if opacity > 0.
         Type type;
-        de::Vector4f color;
-        float thickness;
+        de::Vector4f color;     ///< Secondary color.
+        float thickness;        ///< Frame border thickenss.
 
         Background() : type(None), thickness(0) {}
         Background(de::Vector4f const &solid) : solidFill(solid), type(None), thickness(0) {}
@@ -85,8 +124,9 @@ class GuiWidget : public de::Widget
     de::ColorBank::Colorf textColorf() const;
 
     /**
-     * Determines whether the contents of the widget are scissor-clipped to its
-     * boundaries.
+     * Determines whether the contents of the widget are supposed to be clipped
+     * to its boundaries. The Widget::ContentClipping behavior flag is used for
+     * storing this information.
      */
     bool clipped() const;
 
@@ -137,7 +177,21 @@ class GuiWidget : public de::Widget
     MouseClickStatus handleMouseClick(de::Event const &event);
 
 protected:
+    /**
+     * Called by GuiWidget::update() the first time an update is being carried
+     * out. Native GL is guaranteed to be available at this time, so the widget
+     * must allocate all its GL resources during this method. Note that widgets
+     * cannot always allocate GL resources during their constructors because GL
+     * may not be initialized yet at that time.
+     */
     virtual void glInit();
+
+    /**
+     * Called by GuiWidget before the widget is destroyed. This is the
+     * appropriate place for the widget to release its GL resources. If one
+     * waits until the widget's destructor to do so, it may already have lost
+     * access to some required information (such as the root widget).
+     */
     virtual void glDeinit();
 
     /**

doomsday/client/include/ui/widgets/labelwidget.h

@@ -57,6 +57,8 @@
  *
  * Additionally, LabelWidget::setImageFit() defines how the image will be
  * scaled inside the area reserved for the image.
+ *
+ * @ingroup gui
  */
 class LabelWidget : public GuiWidget
 {

doomsday/client/include/ui/widgets/legacywidget.h

@@ -24,6 +24,7 @@
 
 /**
  * Widget for legacy UI components.
+ *
  * @ingroup gui
  */
 class LegacyWidget : public GuiWidget

doomsday/client/include/ui/widgets/lineeditwidget.h

@@ -27,6 +27,8 @@
  *
  * As a graphical widget, widget placement and line wrapping is handled in
  * terms of pixels rather than characters.
+ *
+ * @ingroup gui
  */
 class LineEditWidget : public GuiWidget, public de::shell::AbstractLineEditor
 {

doomsday/client/include/ui/widgets/logwidget.h

@@ -27,6 +27,8 @@
 
 /**
  * Widget for output message log.
+ *
+ * @ingroup gui
  */
 class LogWidget : public QObject, public GuiWidget
 {

doomsday/client/include/ui/widgets/taskbarwidget.h

@@ -27,6 +27,8 @@
 
 /**
  * Task bar that acts as the primary UI element of the client's UI.
+ *
+ * @ingroup gui
  */
 class TaskBarWidget : public QObject, public GuiWidget
 {

doomsday/client/include/ui/widgets/widgetactions.h

@@ -27,7 +27,9 @@
 
 /**
  * User actions bound to widgets. Traditionally called the bindings and binding
- * contexts. @ingroup ui
+ * contexts.
+ *
+ * @ingroup gui
  *
  * @todo "WidgetActions" is a work-in-progress name.
  *

doomsday/client/src/ui/widgets/consolecommandwidget.cpp

@@ -104,7 +104,7 @@ bool ConsoleCommandWidget::handleEvent(Event const &event)
 
     if(hasFocus() && event.isKeyDown())
     {
-        // Fallback to history navigation.
+        // Fall back to history navigation.
         return d->history.handleControlKey(event.as<KeyEvent>().qtKey());
     }
     return false;

doomsday/libgui/include/de/gui/font.h

@@ -41,7 +41,7 @@ class LIBGUI_PUBLIC Font
 {
 public:   
     /**
-     * Rich formatting instructions for a string of text.
+     * Rich formatting instructions for a string of plain text.
      *
      * The formatting instructions are composed of a sequence of ranges that
      * specify various modifications to the original font. It is important to
@@ -155,14 +155,15 @@ class LIBGUI_PUBLIC Font
         /**
          * Iterates the rich format ranges of a RichFormat.
          *
-         * @note Iterator::next() must be called before at least once after
+         * @note Iterator::next() must be called at least once after
          * constructing the instance to move the iterator onto the first range.
          */
         struct LIBGUI_PUBLIC Iterator
         {
             RichFormat const &format;
             int index;
 
+        public:
             Iterator(RichFormat const &f);
             bool hasNext() const;
             void next();
@@ -200,7 +201,6 @@ class LIBGUI_PUBLIC Font
     Font();
 
     Font(Font const &other);
-
     Font(QFont const &font);
 
     QFont toQFont() const;
@@ -216,10 +216,20 @@ class LIBGUI_PUBLIC Font
      */
     Rectanglei measure(String const &textLine) const;
 
+    /**
+     * Determines the size of the given line of rich text, i.e., how large an
+     * area is covered by the glyphs. (0,0) is at the baseline, left edge of
+     * the line. The rectangle may extend into negative coordinates.
+     *
+     * @param textLine  Text to measure.
+     * @param format    Rich formatting for @a textLine.
+     *
+     * @return Rectangle covered by the text.
+     */
     Rectanglei measure(String const &textLine, RichFormat const &format) const;
 
     /**
-     * Returns the advance width of a line of text. This is not the same as
+     * Returns the advance width of a line of text. This may not be the same as
      * the width of the rectangle returned by measure().
      *
      * @param textLine  Text to measure.

doomsday/libshell/include/de/shell/libshell.h

@@ -71,8 +71,13 @@ class LIBSHELL_PUBLIC ILineWrapping
     /// Returns the advance width of the range.
     virtual int rangeWidth(Rangei const &range) const = 0;
 
-    /// Calculates which index in the provided content range occupies a
-    /// character at a given width.
+    /**
+     * Calculates which index in the provided content range occupies a
+     * character at a given width.
+     *
+     * @param range  Range within the content.
+     * @param width  Advance width to check.
+     */
     virtual int indexAtWidth(Rangei const &range, int width) const = 0;
 };