Documentation step 1

4 files changed, 156 insertions, 0 deletions

diff --git a/client/widgets/checkbox.h b/client/widgets/checkbox.h
index 0930d50..de71732 100644
--- a/client/widgets/checkbox.h
+++ b/client/widgets/checkbox.h
@@ -30,6 +30,15 @@
 #include "widget.h"
 #include <QDomNode>
 
+/***
+ * CheckBox Widget.
+ * @tag checkbox
+ * @extends widget
+ * @screenshot
+ * @att trueval The value of the widget if it is checked.
+ * @att falseval The value of the widget if it is unchecked.
+ */
+
 class QCheckBox;
 class CheckBox : public Widget
 {
@@ -58,7 +67,20 @@ private:
   QCheckBox *checkbox;
 };
 
+/***
+ * @method 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.
+ */
 int chk_checked(lua_State *L);
+
+/***
+ * @method setChecked(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'.
+ */
 int chk_set_checked(lua_State *L);
 
 #define CHKBOX_METHS \
diff --git a/client/widgets/checkgroupbox.h b/client/widgets/checkgroupbox.h
index 7088832..b8a85c1 100644
--- a/client/widgets/checkgroupbox.h
+++ b/client/widgets/checkgroupbox.h
@@ -31,6 +31,14 @@
 #include "widget.h"
 #include <QDomNode>
 
+/***
+ * CheckGroupBox Widget.
+ * @tag checkgroupbox
+ * @extends checkbox
+ * @screenshot
+ * @container 
+ */
+
 class QGroupBox;
 class CheckGroupBox : public Widget
 {
diff --git a/client/widgets/lineedit.h b/client/widgets/lineedit.h
index 6ddb9af..5dbdc6b 100644
--- a/client/widgets/lineedit.h
+++ b/client/widgets/lineedit.h
@@ -31,6 +31,16 @@
 
 #include "widget.h"
 
+/***
+ * Line Edit Widget
+ * @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.
+ */
+
 class QLineEdit;
 class QEvent;
 class LineEdit : public Widget
@@ -65,8 +75,26 @@ private:
 };
 
 int lin_clear_suggestions(lua_State *L);
+
 int lin_show_suggestions(lua_State *L);
+
+/***
+ * @method isSuggested(value)
+ * 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
+ * if not.
+ */
 int lin_is_suggested(lua_State *L);
+
+/***
+ * @method addSuggestion(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().
+ * @param suggestion A string containing the value to be added to the
+ * suggestion list.
+ */
 int lin_add_suggestion(lua_State *L);
 
 #define LINEDT_METHS \
diff --git a/client/widgets/widget.h b/client/widgets/widget.h
index bb7ce6c..fcad521 100644
--- a/client/widgets/widget.h
+++ b/client/widgets/widget.h
@@ -35,6 +35,25 @@
 
 #include "lua.h"
 
+/***
+ * Widget Virtual Tag.
+ * 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
+ * map with a recent value or if the database contains a recent value. 
+ * @att onChange Change event script callback. This attribute contains script
+ *  code that are executed each time the widget is changed.
+ * @att onInit Init event script callback. This attribute contains script code
+ *  that are executed when the widget has just been created.
+ * @att map This attribute binds the value of the widget to a map.
+ * @att width Use this attribute to set the width of the widget to a fixed
+ *  value.
+ * @att height Use this attribute to set the height of the widget to a fixed
+ *  value.
+ * @att help This attribute contains a help text for this widget. It will be
+ *  shown to the user when the mouse is hovering over the widget.
+ */
+
 class QLayout;
 class MacroWindow;
 class LUA;
@@ -124,15 +143,94 @@ protected:
   QString onInitEventScript;
 };
 
+/***
+ * @method string name()
+ * This method is used to get the name of the widget. This name is the same as
+ * the one specified in the <code>name</code> attribute.
+ * @return a string containing the name of the widget.
+ */
 int wdg_name(lua_State *L);
+
+/***
+ * @method string type()
+ * This method is used to get the type of the widget. This type is the same as
+ * the widget tagname and can be used by script to verify the type before
+ * calling any type specific methods.
+ * @return a string containing the type of the widget.
+ */
 int wdg_type(lua_State *L);
+
+/***
+ * @method string value()
+ * This method is used to get the current value of the widget.
+ * @return a string containing the value of the widget.
+ */
 int wdg_value(lua_State *L);
+
+/***
+ * @method nil setValue(string value)
+ * This method is used to set the value of the widget.
+ * @param value A string containing the value to set.
+ */
 int wdg_set_value(lua_State *L);
+
+/***
+ * @method boolean enabled()
+ * This method is used to get the current enable state of the widget.
+ * @return a boolean value. If the widget is enabled the method returns true
+ * otherwise it returns false.
+ */
 int wdg_enabled(lua_State *L);
+
+/***
+ * @method nil setEnabled(boolean enabled)
+ * This method is used to either enable (make editable) or disable (grey out)
+ * the widget. <em>NOTE</em>: A disabled widget will not supply its value to
+ * the server during a commit.
+ * @param enabled A boolean value. If true the widget is enabled. If false the
+ * widget is disabled.
+ */
 int wdg_set_enabled(lua_State *L);
+
+/***
+ * @method boolean visible()
+ * This method is used to get the current enable state of the widget.
+ * @return a boolean value. If the widget is enabled the method returns true
+ * otherwise it returns false.
+ */
 int wdg_visible(lua_State *L);
+
+/***
+ * @method nil setVisible(boolean visible)
+ * This method is used to either show or hide the widget. 
+ * The widget will take up an equal amount of layout space regardless of its
+ * visibility state meaning that the layout will remain static after a
+ * hiding/showing of the widget.
+ * <em>NOTE</em>: A hidden widget will not supply its value to the server
+ * during a commit.
+ * @param visible A boolean value. If true the widget is shown. If false the
+ * widget is hidden.
+ */
 int wdg_set_visible(lua_State *L);
+
+/***
+ * @method boolean valid()
+ * This method is used to get the current validity state of the widget.
+ * @return a boolean value. If the widget is valid the method returns true
+ * otherwise it returns false.
+ */
 int wdg_valid(lua_State *L);
+
+/***
+ * @method nil setValid(boolean valid)
+ * This method is used to set the widgets validity state. Most widgets have a
+ * visual indication of their validity state (a red background colour for
+ * example) and this will also be set using this method.
+ * <em>NOTE</em>: An invalid widget that are not an inner widget will block a
+ * server commit.
+ * @param valid A boolean value. If true the widgets validity state is set to
+ * 'valid'. If false the widgets validity state is set to 'invalid'.
+ */
 int wdg_set_valid(lua_State *L);
 
 #define WDG_METHS \