From 09c5c0783aef07e714c5613cbbf3a982774676aa Mon Sep 17 00:00:00 2001
From: deva <deva>
Date: Wed, 23 Mar 2011 08:02:32 +0000
Subject: Documentation step 1

---
 client/widgets/widget.h | 98 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)

(limited to 'client/widgets/widget.h')

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 \
-- 
cgit v1.2.3