[libgda] GdaBrowser: added actions to help

[Vivien Malerba <vivien src gnome org>]

commit 5d1632ecf9d540f3b857cb118c0b53b5400da754
Author: Vivien Malerba <malerba gnome-db org>
Date:   Thu Jan 20 22:16:06 2011 +0100

    GdaBrowser: added actions to help

 tools/browser/help/C/actions.page                  |   59 ++++++++++++++++++++
 tools/browser/help/C/figures/action-1.png          |  Bin 0 -> 111905 bytes
 tools/browser/help/C/figures/action-2.png          |  Bin 0 -> 113038 bytes
 tools/browser/help/C/figures/action-3.png          |  Bin 0 -> 25047 bytes
 tools/browser/help/C/figures/action-4.png          |  Bin 0 -> 34122 bytes
 tools/browser/help/C/figures/query-exec-persp.png  |  Bin 41929 -> 90062 bytes
 .../help/C/query-execution-perspective.page        |   19 +++++-
 tools/browser/help/Makefile.am                     |    5 ++
 8 files changed, 79 insertions(+), 4 deletions(-)
---
diff --git a/tools/browser/help/C/actions.page b/tools/browser/help/C/actions.page
new file mode 100644
index 0000000..269d7cf
--- /dev/null
+++ b/tools/browser/help/C/actions.page
@@ -0,0 +1,59 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="actions">
+  <info>
+    <title type="sort">1</title>
+    <link type="topic" xref="query-execution-perspective"/>
+    <link type="topic" xref="data-manager-perspective"/>
+    <link type="guide" xref="index#presentation"/>
+  </info>
+  <title>Actions</title>
+  <p>
+    Actions are bits of SQL code which depends on variables and can be executed from the contextual
+    menu of any data set presented in a grid.
+  </p>
+  <p>
+    For example if there is a table "products" which lists some kind of products and
+    a table "comments" which lists all the comments left by users on a product (presumably
+    the "comments" table will have a foreign key on the "products" table to reference it).
+  </p>
+  <p>
+    An action can be defined to show all the entries in the "comments" table provided
+    the key defining a product. Then anytime a product is listed in a resultset, the
+    contextual menu will allow the user to execute this action and thus display all
+    the comments on the selected product. This situation is illustrated in the following figures.
+  </p>
+  <p>
+    The first step is to define an action, which is just a favorite in the <link xref="query-execution-perspective">query execution</link>
+    perspective which is defined as an action: bring up the properties for the favorite, and
+    make sure the "Is action" toggle is checked:
+  </p>
+  <figure>
+    <title>Action - define an action</title>
+    <desc>Define the action to list the comments for a product, from the query execution perspective</desc>
+    <media type="image" mime="image/png" src="figures/action-4.png"/>
+  </figure>
+  <figure>
+    <title>Action - display a list of products</title>
+    <desc>In the query execution perspective, let's select all the products. Notice that
+      there are here two defined actions: "Add comment on product" and "List comments
+      for product"</desc>
+    <media type="image" mime="image/png" src="figures/action-1.png"/>
+  </figure>
+  <p>
+    Now let's pop up the contextual menu:
+  </p>
+  <figure>
+    <title>Action - contextual menu</title>
+    <desc>Pop up the contextual menu and select <guiseq><gui>Execute action</gui><gui>List comments for product</gui></guiseq></desc>
+    <media type="image" mime="image/png" src="figures/action-2.png"/>
+  </figure>
+  <p>
+    After a confirmation of the parameters to execute the action, the result is there:
+  </p>
+  <figure>
+    <title>Action - executed</title>
+    <desc>The action is now executed</desc>
+    <media type="image" mime="image/png" src="figures/action-3.png"/>
+  </figure>
+</page>
diff --git a/tools/browser/help/C/figures/action-1.png b/tools/browser/help/C/figures/action-1.png
new file mode 100644
index 0000000..6877e6e
Binary files /dev/null and b/tools/browser/help/C/figures/action-1.png differ
diff --git a/tools/browser/help/C/figures/action-2.png b/tools/browser/help/C/figures/action-2.png
new file mode 100644
index 0000000..dd09af0
Binary files /dev/null and b/tools/browser/help/C/figures/action-2.png differ
diff --git a/tools/browser/help/C/figures/action-3.png b/tools/browser/help/C/figures/action-3.png
new file mode 100644
index 0000000..87db56c
Binary files /dev/null and b/tools/browser/help/C/figures/action-3.png differ
diff --git a/tools/browser/help/C/figures/action-4.png b/tools/browser/help/C/figures/action-4.png
new file mode 100644
index 0000000..be8d175
Binary files /dev/null and b/tools/browser/help/C/figures/action-4.png differ
diff --git a/tools/browser/help/C/figures/query-exec-persp.png b/tools/browser/help/C/figures/query-exec-persp.png
index 1212f3b..8e9271f 100644
Binary files a/tools/browser/help/C/figures/query-exec-persp.png and b/tools/browser/help/C/figures/query-exec-persp.png differ
diff --git a/tools/browser/help/C/query-execution-perspective.page b/tools/browser/help/C/query-execution-perspective.page
index f1ee15e..55d53ac 100644
--- a/tools/browser/help/C/query-execution-perspective.page
+++ b/tools/browser/help/C/query-execution-perspective.page
@@ -11,10 +11,6 @@
   to this perspective, use the <guiseq><gui>Perspective</gui><gui>Query execution (SQL)</gui></guiseq>
   menu, or the <keyseq><key>Ctrl</key><key>S</key></keyseq> shortcut.
 </p>
-<p>
-  The perspective is divided in two horizontal panes: the left pane for the user defined favorite statements,
-  and the right pane being the action area.
-</p>
 <figure>
   <title>Query exec perspective</title>
   <desc>The query exec perspective with one SELECT statement executed</desc>
@@ -22,6 +18,21 @@
 </figure>
 
 <p>
+  The perspective is divided in two horizontal panes: the left pane for the user defined favorite statements,
+  and the right pane being the action area.
+</p>
+<p>
+  In the figure above, there are two favorites: a SELECT
+  statement (named "List customers") and an INSERT statement (named "New customer ...").
+  The INSERT statement needs one "name" parameter, whereas the SELECT statement does not require
+  any parameter to be executed.
+</p>
+<p>
+  The icon difference between the two illustrates the fact that the INSERT favorite is also
+  marked to be an <link xref="actions">action</link>: it will be proposed as an action to
+  be executed when the contextual menu is brought up in any grid representation of a resultset.
+</p>
+<p>
   The left
   part of the perspective lists the favorite statements which have been user defined. Activating a
   favorite (double clicking) resets the SQL text area's contents to the selected statement's SQL.
diff --git a/tools/browser/help/Makefile.am b/tools/browser/help/Makefile.am
index ece0ccc..c413b7e 100644
--- a/tools/browser/help/Makefile.am
+++ b/tools/browser/help/Makefile.am
@@ -4,6 +4,10 @@ DOC_ID = gda-browser
 
 DOC_INCLUDES = legal.xml
 DOC_FIGURES = \
+	figures/action-1.png \
+	figures/action-2.png \
+	figures/action-3.png \
+	figures/action-4.png \
 	figures/cnc_open.png \
 	figures/data-man-mode.png \
 	figures/data-man-persp.png \
@@ -17,6 +21,7 @@ DOC_FIGURES = \
 	figures/table-insert-data.png
 
 DOC_PAGES = \
+	actions.page \
 	data-manager-perspective.page \
 	data-manager-xml-syntax.page \
 	diagram.page \