Documented EphyCommandManager

7 files changed, 167 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index 42ed2d2bf..d1be2d67e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2004-03-29  Adam Hooper  <adamh@cvs.gnome.org>
+
+	* doc/reference/Makefile.am:
+	* doc/reference/epiphany-docs.sgml:
+	* doc/reference/epiphany-sections.txt:
+	* embed/ephy-command-manager.c: (ephy_command_manager_base_init):
+	* embed/ephy-command-manager.h:
+
+	Document EphyCommandManager.
+
 2004-03-29  Federico Mena Quintero  <federico@ximian.com>
 
 	Fixes #138263.
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index 0b0df505d..ff7bb9f9e 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -65,7 +65,6 @@ IGNORE_HFILES = \
 	ephy-zoom-action.h \
 	ephy-zoom-control.h \
 	downloader-view.h \
-	ephy-command-manager.h \
 	ephy-download.h \
 	ephy-embed-dialog.h \
 	ephy-embed-event.h \
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index 1d399f151..9121ecf77 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -12,6 +12,7 @@
     <xi:include href="xml/ephy-window.xml"/>
     <xi:include href="xml/ephy-tab.xml"/>
     <xi:include href="xml/ephy-embed.xml"/>
+    <xi:include href="xml/ephy-command-manager.xml"/>
     <xi:include href="xml/ephy-embed-single.xml"/>
     <xi:include href="xml/ephy-embed-persist.xml"/>
   </chapter>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 398ef5c83..1ecc56bad 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -183,6 +183,22 @@ EPHY_IS_EMBED_PERSIST_CLASS
 EPHY_EMBED_PERSIST_GET_CLASS
 </SECTION>
 
+<SECTION>
+<FILE>ephy-command-manager</FILE>
+<TITLE>EphyCommandManager</TITLE>
+EphyCommandManager
+EphyCommandManagerIface
+ephy_command_manager_do_command
+ephy_command_manager_can_do_command
+<SUBSECTION Standard>
+EPHY_COMMAND_MANAGER
+EPHY_IS_COMMAND_MANAGER
+EPHY_TYPE_COMMAND_MANAGER
+ephy_command_manager_get_type
+EPHY_COMMAND_MANAGER_GET_IFACE
+EPHY_COMMAND_MANAGER_IFACE
+EPHY_IS_COMMAND_MANAGER_IFACE
+</SECTION>
 
 
 
diff --git a/doc/reference/tmpl/ephy-command-manager.sgml b/doc/reference/tmpl/ephy-command-manager.sgml
new file mode 100644
index 000000000..060d41615
--- /dev/null
+++ b/doc/reference/tmpl/ephy-command-manager.sgml
@@ -0,0 +1,112 @@
+<!-- ##### SECTION Title ##### -->
+EphyCommandManager
+
+<!-- ##### SECTION Short_Description ##### -->
+Performs commands, such as cut/copy/paste
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+An #EphyCommandManager is an interface to an #EphyEmbed which is used to perform
+commands, such as cut/copy/paste. To perform any command, use
+ephy_command_manager_do_command(). To test the availability of a command, use
+ephy_command_manager_can_do_command(). The availability of commands depends on
+the selection and actions previously performed in the #EphyEmbed. For instance,
+%cmd_copy is only available if text has been selected; %cmd_undo is only
+available if the user has a text input focused and has typed or erased some of
+its text.
+</para>
+<para>
+<example>
+<title>Copying selected text in an #EphyEmbed</title>
+<programlisting>#<![CDATA[include <ephy-embed.h>]]>
+#<![CDATA[include <ephy-command-manager.h>
+
+static void
+copy_selected_text (EphyEmbed *embed)
+{
+	EphyCommandManager *manager;
+
+	manager = EPHY_COMMAND_MANAGER (embed);
+	g_return_if_fail (EPHY_IS_COMMAND_MANAGER (manager));
+
+	if (!ephy_command_manager_can_do_command (manager, "cmd_copy")) return;
+
+	ephy_command_manager_do_command (manager, "cmd_copy");
+}]]>
+</programlisting>
+</example>
+</para>
+<para>
+The #EphyCommandManager interface can perform any command which is defined in
+Mozilla. However, for purposes of abstraction, only a certain subset of commands
+should be used:
+</para>
+<variablelist><title>Available Commands</title>
+<varlistentry><term>cmd_copy</term>
+<listitem><para>Copies selected text</para></listitem>
+</varlistentry>
+<varlistentry><term>cmd_cut</term>
+<listitem><para>Cuts selected text.</para></listitem>
+</varlistentry>
+<varlistentry><term>cmd_paste</term>
+<listitem><para>Pastes text from the clipboard (for example, into a text entry)
+</para></listitem>
+</varlistentry>
+<varlistentry><term>cmd_undo</term>
+<listitem><para>Undoes the last action (for example, typing text into a text
+entry</para></listitem>
+</varlistentry>
+<varlistentry><term>cmd_redo</term>
+<listitem><para>Redoes previously %undo<!-- -->ne actions (for example, in a
+text entry)</para></listitem>
+</varlistentry>
+</variablelist>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT EphyCommandManager ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT EphyCommandManagerIface ##### -->
+<para>
+
+</para>
+
+@base_iface: 
+@do_command: 
+@can_do_command: 
+@command_changed: 
+
+<!-- ##### FUNCTION ephy_command_manager_do_command ##### -->
+<para>
+
+</para>
+
+@manager: 
+@command: 
+
+
+<!-- ##### FUNCTION ephy_command_manager_can_do_command ##### -->
+<para>
+
+</para>
+
+@manager: 
+@command: 
+@Returns: 
+
+
+<!-- ##### SIGNAL EphyCommandManager::command-changed ##### -->
+<para>
+
+</para>
+
+@ephycommandmanager: the object which received the signal.
+@arg1: 
+
diff --git a/embed/ephy-command-manager.c b/embed/ephy-command-manager.c
index 2f9375d9e..9161b7a8c 100644
--- a/embed/ephy-command-manager.c
+++ b/embed/ephy-command-manager.c
@@ -57,6 +57,15 @@ ephy_command_manager_base_init (gpointer g_class)
 
 	if (!initialized)
 	{
+/**
+ * EphyCommandManager::command-changed:
+ * @manager:
+ * @command: The command whose avalability has changed
+ *
+ * The ::command-changed signal is emitted when @command has changed from being
+ * available to unavailable, or vice-versa. The new availability can be tested
+ * with ephy_command_manager_can_do_command().
+ **/
 		g_signal_new ("command_changed",
 			      EPHY_TYPE_COMMAND_MANAGER,
 			      G_SIGNAL_RUN_FIRST,
@@ -71,6 +80,13 @@ ephy_command_manager_base_init (gpointer g_class)
 	}
 }
 
+/**
+ * ephy_command_manager_do_command:
+ * @manager: an #EphyCommandManager
+ * @command: the command
+ *
+ * Performs @command.
+ **/
 void
 ephy_command_manager_do_command (EphyCommandManager *manager,
 				 const char *command)
@@ -79,6 +95,15 @@ ephy_command_manager_do_command (EphyCommandManager *manager,
 	iface->do_command (manager, command);
 }
 
+/**
+ * ephy_command_manager_can_do_command:
+ * @manager: an #EphyCommandManager
+ * @command: the command
+ *
+ * Returns %TRUE if @command can be performed.
+ *
+ * Return value: %TRUE if @command can be performed.
+ **/
 gboolean
 ephy_command_manager_can_do_command (EphyCommandManager *manager,
 					const char *command)
diff --git a/embed/ephy-command-manager.h b/embed/ephy-command-manager.h
index aee7004d3..b64c1c8b1 100644
--- a/embed/ephy-command-manager.h
+++ b/embed/ephy-command-manager.h
@@ -33,10 +33,10 @@ G_BEGIN_DECLS
 #define EPHY_IS_COMMAND_MANAGER_IFACE(k)	(G_TYPE_CHECK_CLASS_TYPE ((k), EPHY_TYPE_COMMAND_MANAGER))
 #define EPHY_COMMAND_MANAGER_GET_IFACE(inst)	(G_TYPE_INSTANCE_GET_INTERFACE ((inst), EPHY_TYPE_COMMAND_MANAGER, EphyCommandManagerIface))
 
-typedef struct EphyCommandManager	EphyCommandManager;
-typedef struct EphyCommandManagerIface	EphyCommandManagerIface;
+typedef struct _EphyCommandManager	EphyCommandManager;
+typedef struct _EphyCommandManagerIface	EphyCommandManagerIface;
 
-struct EphyCommandManagerIface
+struct _EphyCommandManagerIface
 {
 	GTypeInterface base_iface;