Finished documenting the last widgets. Also some changes in the docgen app.

17 files changed, 207 insertions, 10 deletions

diff --git a/client/widgets/altcombobox.h b/client/widgets/altcombobox.h
index 9f90f8b..93ae124 100644
--- a/client/widgets/altcombobox.h
+++ b/client/widgets/altcombobox.h
@@ -34,6 +34,27 @@
 #include <QDomNode>
 #include <QMap>
 
+/***
+ * ComboBox Widget with Alternate Value
+ * @tag altcombobox
+ * @extends combobox
+ * @container
+ * @screenshot
+ * The AltComboBox is used to make a normal selection with a ComboBox but with
+ * a special list item that shows an alternate widget and uses this widget for
+ * input. The AltComboBox contains <code>&gt;item&lt;</code> tags in the same
+ * way as the ComboBox, but may also contain an <code>&gtaltitem&lt;</code> tag
+ * which can again contain widgets.
+ * @att value [altitem] The value of the item. This will be the value of the
+ * AltComboBox if this item is selected.
+ * @att caption [altitem] The caption of this item. This is the text presented
+ * to the user in the ComboBox.
+ * @att layout [altitem] The layout of the altitem. Can be one of 'hbox' or
+ * 'vbox'.
+ * @att innerwidget [altitem] The name of the widget that will produce the
+ * AltComboBox value if the altitem is selected.
+ */
+
 class QFrame;
 class AltComboBox : public Widget
 {
diff --git a/client/widgets/button.h b/client/widgets/button.h
index 80594db..0fa7521 100644
--- a/client/widgets/button.h
+++ b/client/widgets/button.h
@@ -31,6 +31,16 @@
 
 #include <QDomNode>
 
+/***
+ * PushButton Widget
+ * @tag button
+ * @screenshot
+ * @extends widget
+ * This is a normal pushbutton that can be clicked by the user.
+ * @att caption The caption of the button.
+ * @att action The action of the button. 'commit' commits tha macro when
+ * clicked, 'cancel' cancels (close without saving) the macro when clicked.
+ */
 class QPushButton;
 class Button : public Widget
 {
diff --git a/client/widgets/checkbox.h b/client/widgets/checkbox.h
index de71732..92cc4b3 100644
--- a/client/widgets/checkbox.h
+++ b/client/widgets/checkbox.h
@@ -31,10 +31,14 @@
 #include <QDomNode>
 
 /***
- * CheckBox Widget.
+ * CheckBox Widget
  * @tag checkbox
  * @extends widget
  * @screenshot
+ * This widget is used to retrieve boolean values from the user. The widget can
+ * either be in checked state or unschecked state. The value of the widget
+ * depends on its state and the values of the falseval and trueval attributes.
+ * @att caption The caption of the checkbox.
  * @att trueval The value of the widget if it is checked.
  * @att falseval The value of the widget if it is unchecked.
  */
@@ -68,7 +72,7 @@ private:
 };
 
 /***
- * @method checked()
+ * @method boolean checked()
  * This method retrives the current check state of the checkbox.
  * @return the boolean value true if the checkbox is checked. Return
  * false if not.
@@ -76,7 +80,7 @@ private:
 int chk_checked(lua_State *L);
 
 /***
- * @method setChecked(checked)
+ * @method nil setChecked(boolean checked)
  * This method sets the current check state of the checkbox.
  * @param checked A boolean value. If the value is true the checkbox is set to
  * the state 'checked', otherwise it is set to the state 'unchecked'.
diff --git a/client/widgets/checkgroupbox.h b/client/widgets/checkgroupbox.h
index b8a85c1..eac85f9 100644
--- a/client/widgets/checkgroupbox.h
+++ b/client/widgets/checkgroupbox.h
@@ -32,11 +32,12 @@
 #include <QDomNode>
 
 /***
- * CheckGroupBox Widget.
+ * Checkable GroupBox Widget
  * @tag checkgroupbox
  * @extends checkbox
  * @screenshot
  * @container 
+ * @att layout the layout used in the groupbox. Can be one of 'vbox' or 'hbox'.
  */
 
 class QGroupBox;
diff --git a/client/widgets/combobox.h b/client/widgets/combobox.h
index 657d458..8a8fbd3 100644
--- a/client/widgets/combobox.h
+++ b/client/widgets/combobox.h
@@ -32,6 +32,26 @@
 
 #include "widget.h"
 
+/***
+ * ComboBox Widget
+ * @tag combobox
+ * @extends widget
+ * @screenshot
+ * The ComboBox is used to make a selection from a list of items.
+ * The ComboBox contains <code>&gt;item&lt;</code> tags each describing 
+ * an entry in the selection list.
+ * @att type The selection method of the ComboBox. Can be one 'select', where
+ * the user can select items using either the mouse or the arrow keys, 'edit',
+ * where the user can write freely in the ComboBox in the same way as in a
+ * LineEdit during which it will present but not limit to the matching values
+ * of its list, and finally 'search', where the user can write in the ComboBox
+ * but is restricted to writing strings matching the items in the list.
+ * @att value [item] The value of the item. This will be the value of the
+ * ComboBox if this item is selected.
+ * @att caption [item] The caption of this item. This is the text presented
+ * to the user in the ComboBox.
+ */
+
 typedef enum {
   SELECT,
   EDIT,
diff --git a/client/widgets/datetime.h b/client/widgets/datetime.h
index b6e2d36..d238ea0 100644
--- a/client/widgets/datetime.h
+++ b/client/widgets/datetime.h
@@ -32,6 +32,26 @@
 #include <QDomNode>
 #include <QDateTime>
 
+/***
+ * Date and Time Widget
+ * @tag datetime
+ * @screenshot
+ * @extends widget
+ * This widget is used to get structured time and date information.
+ * <em>NOTE</em>: The value attribute must be a unix timestamp (number of
+ * seconds since epoch: 1/1-1970).
+ * @att fuzziness The precision of the display. Values from 1 - 7 can be used
+ * with the following meaning:
+ * <ul>
+ *   <li>1: yyyy</li>
+ *   <li>2: MMMM yyyy</li>
+ *   <li>3: dd MMMM yyyy</li>
+ *   <li>4: dd MMMM yyyy hh</li>
+ *   <li>5: dd MMMM yyyy hh:mm</li>
+ *   <li>6: dd MMMM yyyy hh:mm:ss</li>
+ *   <li>7: dd MMMM yyyy hh:mm:ss:zzz</li>
+ * </ul>
+ */
 class QDateTimeEdit;
 class DateTime : public Widget
 {
diff --git a/client/widgets/frame.h b/client/widgets/frame.h
index 04e6b9e..177d77c 100644
--- a/client/widgets/frame.h
+++ b/client/widgets/frame.h
@@ -31,6 +31,9 @@
 
 #include <QDomNode>
 
+/*
+ * NOTE: The documentation for this class is in groupbox.
+ */
 class QFrame;
 class Frame : public Widget
 {
diff --git a/client/widgets/groupbox.h b/client/widgets/groupbox.h
index f2da306..73b6508 100644
--- a/client/widgets/groupbox.h
+++ b/client/widgets/groupbox.h
@@ -31,6 +31,23 @@
 
 #include <QDomNode>
 
+/*
+ * NOTE: This documentation is both for the groupbox and frame classes.
+ */
+/***
+ * Layout or Frame Widget 
+ * @tag frame
+ * @extends widget
+ * @screenshot
+ * This widget is used to control the layout of the child widgets and/or produce
+ * a frame and caption for them. <em>NOTE</em>: The value of this widget is
+ * always the empty string. It cannot be set.
+ * @att layout The layout assigned to the frame. Can be one of 'hbox' or
+ * 'vbox'.
+ * @att caption The optional caption of the frame. (leave this out to draw
+ * without the frame and caption). En empty caption attribute will produce a
+ * nameless frame.
+ */
 class QGroupBox;
 class GroupBox : public Widget
 {
diff --git a/client/widgets/label.h b/client/widgets/label.h
index b4e352c..7c32916 100644
--- a/client/widgets/label.h
+++ b/client/widgets/label.h
@@ -31,6 +31,15 @@
 
 #include <QDomNode>
 
+/***
+ * Label Widget
+ * @tag label
+ * @screenshot
+ * @extends widget
+ * This widget is used to present text to the user. It is a read-only widget
+ * and its value will always be the empty string.
+ * @att caption The text to show in the label.
+ */
 class QLabel;
 class Label : public Widget
 {
diff --git a/client/widgets/lineedit.h b/client/widgets/lineedit.h
index 5dbdc6b..650924c 100644
--- a/client/widgets/lineedit.h
+++ b/client/widgets/lineedit.h
@@ -36,9 +36,9 @@
  * @tag lineedit
  * @extends widget
  * @screenshot
- * The lineedit tag is used to insert a lineedit into the macro. It is used to
- * gather textual input from the user, who using the keyboard will be able to
- * express him or herself in plaintext.
+ * The lineedit is a single line textual input field.
+ * @att readonly Make the lineedit readonly (not changeable by the user), but
+ * still able to select and copy text.
  */
 
 class QLineEdit;
@@ -74,12 +74,20 @@ private:
   QStringList suggestions;
 };
 
+/***
+ * @method nil clearSuggestions()
+ * This method clears the suggestion list.
+ */
 int lin_clear_suggestions(lua_State *L);
 
+/***
+ * @method nil showSuggestions()
+ * This method forces showing of the suggestion list.
+ */
 int lin_show_suggestions(lua_State *L);
 
 /***
- * @method isSuggested(value)
+ * @method boolean isSuggested(string value, boolean joker)
  * This method makes a lookup in the suggestion list, searching for value.
  * @param value A string containing the text to look for in the suggestion list.
  * @return a boolean with the value true if the string was found, false
@@ -88,7 +96,7 @@ int lin_show_suggestions(lua_State *L);
 int lin_is_suggested(lua_State *L);
 
 /***
- * @method addSuggestion(suggestion)
+ * @method nil addSuggestion(string suggestion)
  * Adds a suggestion to the suggestion list. The list is popped up each time 
  * a character is entered into the lineedit by the user, or it is explicitly
  * opened by calling @ref showSuggestions().
diff --git a/client/widgets/listbox.h b/client/widgets/listbox.h
index d775655..fcfc1b0 100644
--- a/client/widgets/listbox.h
+++ b/client/widgets/listbox.h
@@ -31,6 +31,21 @@
 
 #include <QDomNode>
 
+/***
+ * ListBox Widget
+ * @tag listbox
+ * @screenshot
+ * @extends widget
+ * This widget is a list of selectable items.
+ * @att value [item] The value of the item and the value of the widget if this
+ * item is selected.
+ * @att caption [item] The caption of the item. This is the text presented to
+ * the user.
+ * @att type [item] The item type. Can be either 'separator' which will show
+ * the item as a line or 'header' which will highlight its caption. Ommit this
+ * attribute if the item is selectable.
+ */
+
 class QListWidget;
 class ListBox : public Widget
 {
diff --git a/client/widgets/metawidget.h b/client/widgets/metawidget.h
index f44fd79..ef3f198 100644
--- a/client/widgets/metawidget.h
+++ b/client/widgets/metawidget.h
@@ -34,6 +34,23 @@
 #include <QListWidget>
 #include <QVector>
 
+/***
+ * Meta Widget
+ * @extends widget
+ * @tag metawidget
+ * @container
+ * This widget is simply a caotainer compositing its value from the widgets
+ * within it. The value of the widget cannot be set and its value attribute is
+ * therefore ignored.
+ * @att layout the layout of the widget. Can be one of 'vbox' or 'hbox'.
+ * @att storechildren This attribute indicates wether the child widgets should
+ * be stored on macro commit. It can be either 'true' or 'false'.
+ * @att format This attribute comtains lua code. The return value of the code
+ * is the resulting value of the meta widget.
+ * @att layout The layout assigned to the widget. Can be one of 'hbox' or
+ * 'vbox'.
+ */
+
 class QFrame;
 class MetaWidget : public Widget
 {
diff --git a/client/widgets/multilist.h b/client/widgets/multilist.h
index 8e806fa..e86df28 100644
--- a/client/widgets/multilist.h
+++ b/client/widgets/multilist.h
@@ -34,6 +34,21 @@
 #include <QListWidget>
 #include <QVector>
 
+/***
+ * Multi List Widget
+ * @tag multilist
+ * @container
+ * @extends widget
+ * @screenshot
+ * This widget is used to produce a list of text items constructed using other
+ * widgets. The value of the widget is contained in a simple string using the
+ * newline character to seperate items.
+ * @att layout the layout of the widget. Can be one of 'vbox' or 'hbox'.
+ * @att innerwidget This attribute contains the name of the child widget used
+ * when producing a new value for the list. In order to use multiple widgets see
+ * the @see metawidget.
+ */
+
 class QFrame;
 class MultiList : public Widget
 {
diff --git a/client/widgets/radiobuttons.h b/client/widgets/radiobuttons.h
index b83f7a9..3ddb05c 100644
--- a/client/widgets/radiobuttons.h
+++ b/client/widgets/radiobuttons.h
@@ -32,6 +32,23 @@
 
 #include "widget.h"
 
+/***
+ * Radio Button Group Widget
+ * @tag radiobuttons
+ * @extends widget
+ * @screenshot
+ * @container
+ * This widget is in many ways similar to the @see listbox widget. It is a
+ * container for radiobuttons represented by <code>&lt;radiobutton&gt;</code>
+ * tags. The value of the widget is retrieved from the selected radiobutton.
+ * When the value of the radiobuttons widget is set the corresponding
+ * radiobutton will be selected.
+ * @att layout the layout of the widget. Can be one of 'vbox' or 'hbox'.
+ * @att caption [radiobutton] This is the caption of the radio button.
+ * @att value [radiobutton] This is the value of the radiobutton, which will
+ * be the value of the radiobuttons widget should this radiobutton be selected.
+ */
+
 class QFrame;
 class QEvent;
 class RadioButton;
diff --git a/client/widgets/textedit.h b/client/widgets/textedit.h
index 86d6e42..4398878 100644
--- a/client/widgets/textedit.h
+++ b/client/widgets/textedit.h
@@ -32,6 +32,17 @@
 #include <QDomNode>
 #include <QKeyEvent>
 
+/***
+ * Multiline Text Edit Widget
+ * @tag textedit
+ * @extends widget
+ * @screenshot
+ * The textedit is a multiline textual input field. Unlike the @see lineedit it
+ * accepts the newline character which will also be part of its resulting value.
+ * @att readonly Make the textedit readonly (not changeable by the user), but
+ * still able to select and copy text.
+ */
+
 class QTextEdit;
 class TextEdit : public Widget
 {
diff --git a/client/widgets/widget.h b/client/widgets/widget.h
index fcad521..ef23294 100644
--- a/client/widgets/widget.h
+++ b/client/widgets/widget.h
@@ -36,7 +36,7 @@
 #include "lua.h"
 
 /***
- * Widget Virtual Tag.
+ * Virtual Base Widget
  * This tag is purely virtual. It is inherited by all other widgets.
  * @att name The name of the widget. This is also the name used by the scripts.
  * @att value The initial value of the widget. It is overwritten if there is a
diff --git a/client/widgets/window.h b/client/widgets/window.h
index 109cf11..ea3af0a 100644
--- a/client/widgets/window.h
+++ b/client/widgets/window.h
@@ -30,6 +30,15 @@
 #include "widget.h"
 #include <QDomNode>
 
+/***
+ * Widgets Outer Container
+ * @tag widgets
+ * @container
+ * This is the outer tag of the macro widgets.
+ * @att caption This is the name that will be shown in the macro.
+ * @att layout this is the layout that is used by the macro. It can be one of
+ * 'hbox' or 'vbox'.
+ */
 class Window : public Widget
 {
 public: