From 93de7f375842c0afb72db8796c45bfda5f1a6f13 Mon Sep 17 00:00:00 2001
From: deva <deva>
Date: Fri, 25 Mar 2011 14:54:32 +0000
Subject: Finished documenting the last widgets. Also some changes in the
 docgen app.

---
 client/docgen/docgen.cc        |  3 ++-
 client/docgen/generate.cc      | 44 ++++++++++++++++++++++++++++++++++++++++--
 client/docgen/genimage.cc      | 17 ++++++++++++++++
 client/docgen/parse.cc         |  2 +-
 client/docgen/style.css        | 15 +++++++++++++-
 client/widgets/altcombobox.h   | 21 ++++++++++++++++++++
 client/widgets/button.h        | 10 ++++++++++
 client/widgets/checkbox.h      | 10 +++++++---
 client/widgets/checkgroupbox.h |  3 ++-
 client/widgets/combobox.h      | 20 +++++++++++++++++++
 client/widgets/datetime.h      | 20 +++++++++++++++++++
 client/widgets/frame.h         |  3 +++
 client/widgets/groupbox.h      | 17 ++++++++++++++++
 client/widgets/label.h         |  9 +++++++++
 client/widgets/lineedit.h      | 18 ++++++++++++-----
 client/widgets/listbox.h       | 15 ++++++++++++++
 client/widgets/metawidget.h    | 17 ++++++++++++++++
 client/widgets/multilist.h     | 15 ++++++++++++++
 client/widgets/radiobuttons.h  | 17 ++++++++++++++++
 client/widgets/textedit.h      | 11 +++++++++++
 client/widgets/widget.h        |  2 +-
 client/widgets/window.h        |  9 +++++++++
 22 files changed, 283 insertions(+), 15 deletions(-)

diff --git a/client/docgen/docgen.cc b/client/docgen/docgen.cc
index e5a8bff..ee5b8f4 100644
--- a/client/docgen/docgen.cc
+++ b/client/docgen/docgen.cc
@@ -145,7 +145,8 @@ int main(int argc, char *argv[])
   QStringList l = dir.entryList(QDir::Files);
   foreach(QString file, l) {
     Doc doc = parse(QString(INPUT) + "/" + file);
-    docs[doc.name] = doc;
+    if(doc.title != "" || doc.tag != "")
+      docs[doc.name] = doc;
   }
 
   writeIndex(docs);
diff --git a/client/docgen/generate.cc b/client/docgen/generate.cc
index 73734a5..5cff6b7 100644
--- a/client/docgen/generate.cc
+++ b/client/docgen/generate.cc
@@ -29,9 +29,47 @@
 
 #include <QTextStream>
 #include <QDate>
+#include <QStringList>
 
 #include "genimage.h"
 
+static QString function(QString f)
+{
+  QString out;
+
+  if(f.indexOf(" ") > f.indexOf("(") || f.indexOf(" ") == -1) {
+    printf("MISSING return type in \"%s\".\n", f.toStdString().c_str());
+    return f;
+  }
+
+  QString ret = f.left(f.indexOf(" "));
+  QString name = f.mid(f.indexOf(" ") + 1, f.indexOf("(") - f.indexOf(" ") - 1);
+  QString ps = f.mid(f.indexOf("(") + 1,
+                        f.indexOf(")") - f.indexOf("(") - 1);
+
+  QStringList parms = ps.split(",");
+
+  out += "<span class=\"luatype\">" + ret + "</span> ";
+  out += "<span class=\"luamethod\">" + name + "</span>";
+  out += "(<span class=\"luaparms\">";
+  for(int i = 0; i < parms.size(); i++) {
+    QStringList l = parms.at(i).split(" ", QString::SkipEmptyParts);
+    if(l.length() != 2) {
+      out += parms.at(i);
+      continue;
+    }
+    QString type = l.at(0);
+    QString name = l.at(1);
+    if(i != 0) out += ", ";
+    out += "<span class=\"luatype\">" + type + "</span>";
+    out += " <span class=\"luaparm\">" + name + "</span>";
+  }
+  out += "</span>)";
+  
+
+  return out;
+}
+
 static QString generateMethods(QVector<Method> meths)
 {
   QString out;
@@ -39,7 +77,7 @@ static QString generateMethods(QVector<Method> meths)
   foreach(Method meth, meths) {
     out += "        <div class=\"method\">\n";
     out += "          <a name=\"" + meth.name +
-      "\"></a><div class=\"name\">" + meth.name + "</div>\n";
+      "\"></a><div class=\"name\">" + function(meth.name) + "</div>\n";
     out += "          <div class=\"description\">" + meth.description +
       "</div>\n";
     
@@ -189,7 +227,9 @@ QString generate(Doc &doc, QMap<QString, QVector<Method> > &meths,
   out += "    </div>\n";
 
   out += "    <div class=\"footer\">This documentation is generated for"
-    " Pracro version "VERSION" at "+QDate::currentDate().toString()+"</div>\n";
+    " <a href=\"http://www.aasimon.org/pracro\">Pracro</a>"
+    " version "VERSION" at "+QDate::currentDate().toString()+"</div>\n";
+
   return out;
 }
 
diff --git a/client/docgen/genimage.cc b/client/docgen/genimage.cc
index 332887c..f598553 100644
--- a/client/docgen/genimage.cc
+++ b/client/docgen/genimage.cc
@@ -64,6 +64,15 @@ void genImage(QString widget)
   }
 
   if(widget == "combobox" || widget == "listbox") {
+
+    if(widget == "listbox") {
+      QDomElement e = node.createElement("item");
+      e.setAttribute("type", "header");
+      e.setAttribute("caption", "Header 1");
+      e.setAttribute("value", "Header 1");
+      elem.appendChild(e);
+    }
+
     {
       QDomElement e = node.createElement("item");
       e.setAttribute("caption", "List item 1");
@@ -77,6 +86,14 @@ void genImage(QString widget)
       elem.appendChild(e);
     }
 
+    if(widget == "listbox") {
+      QDomElement e = node.createElement("item");
+      e.setAttribute("type", "separator");
+      e.setAttribute("caption", "sep 1");
+      e.setAttribute("value", "sep 1");
+      elem.appendChild(e);
+    }
+
     {
       QDomElement e = node.createElement("item");
       e.setAttribute("caption", "List item 3");
diff --git a/client/docgen/parse.cc b/client/docgen/parse.cc
index bcf137b..d1631c1 100644
--- a/client/docgen/parse.cc
+++ b/client/docgen/parse.cc
@@ -69,7 +69,7 @@ Doc parse(QString filename)
 
     if(running) {
       line.remove(QRegExp("^[ \t*]*"));
-      printf("line [%s]\n", line.toStdString().c_str());
+      //      printf("line [%s]\n", line.toStdString().c_str());
       
       if(state == indesc && line.left(1) == "@") state = none;
       if(state == inatt && line.left(1) == "@") state = none;
diff --git a/client/docgen/style.css b/client/docgen/style.css
index 778c69d..9ef9a68 100644
--- a/client/docgen/style.css
+++ b/client/docgen/style.css
@@ -85,7 +85,6 @@ a:hover {
 		background-color: #D5E1E8;
 		width: *;
 		border: solid #84B0C7 1px;
-		font-weight: bold;
 		padding: 4px;
 		border-radius: 8px 8px 8px 8px;
 }
@@ -106,3 +105,17 @@ a:hover {
 .parameter .description {	
 		display: inline;
 }
+
+.method .luamethod {
+    font-weight: bold;
+}
+
+.method .luatype {
+    font-style: italic;
+    color: blue;
+}
+
+.method .luaparms {
+    font-style: italic;
+    color: green;
+}
\ No newline at end of file
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:
-- 
cgit v1.2.3