EphyEmbedPersist documentation

5 files changed, 344 insertions, 1 deletions

diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index cf981f0b6..0b0df505d 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -69,7 +69,6 @@ IGNORE_HFILES = \
 	ephy-download.h \
 	ephy-embed-dialog.h \
 	ephy-embed-event.h \
-	ephy-embed-persist.h \
 	ephy-embed-popup-control.h \
 	ephy-embed-prefs.h \
 	ephy-embed-shell.h \
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index aa8abfa73..1d399f151 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -13,6 +13,7 @@
     <xi:include href="xml/ephy-tab.xml"/>
     <xi:include href="xml/ephy-embed.xml"/>
     <xi:include href="xml/ephy-embed-single.xml"/>
+    <xi:include href="xml/ephy-embed-persist.xml"/>
   </chapter>
   <chapter>
     <title>Incomplete</title>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 3cb40f04e..398ef5c83 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -150,6 +150,39 @@ EPHY_EMBED_SINGLE_IFACE
 EPHY_IS_EMBED_SINGLE_IFACE
 </SECTION>
 
+<SECTION>
+<FILE>ephy-embed-persist</FILE>
+<TITLE>EphyEmbedPersist</TITLE>
+EmbedPersistFlags
+ephy_embed_persist_set_dest
+ephy_embed_persist_set_embed
+ephy_embed_persist_set_fc_title
+ephy_embed_persist_set_fc_parent
+ephy_embed_persist_set_flags
+ephy_embed_persist_set_max_size
+ephy_embed_persist_set_persist_key
+ephy_embed_persist_set_source
+ephy_embed_persist_get_dest
+ephy_embed_persist_get_embed
+ephy_embed_persist_get_fc_title
+ephy_embed_persist_get_fc_parent
+ephy_embed_persist_get_flags
+ephy_embed_persist_get_max_size
+ephy_embed_persist_get_persist_key
+ephy_embed_persist_get_source
+ephy_embed_persist_save
+ephy_embed_persist_cancel
+ephy_embed_persist_to_string
+<SUBSECTION Standard>
+EPHY_EMBED_PERSIST
+EPHY_IS_EMBED_PERSIST
+EPHY_TYPE_EMBED_PERSIST
+ephy_embed_persist_get_type
+EPHY_EMBED_PERSIST_CLASS
+EPHY_IS_EMBED_PERSIST_CLASS
+EPHY_EMBED_PERSIST_GET_CLASS
+</SECTION>
+
 
 
 
diff --git a/doc/reference/epiphany.types b/doc/reference/epiphany.types
index 098dc3f66..58dd8ba78 100644
--- a/doc/reference/epiphany.types
+++ b/doc/reference/epiphany.types
@@ -30,6 +30,7 @@ ephy_cell_renderer_progress_get_type
 #include <ephy-password-manager.h>
 #include <ephy-permission-manager.h>
 #include <mozilla-embed.h>
+#include <mozilla-embed-persist.h>
 
 ephy_embed_get_type
 downloader_view_get_type
@@ -43,6 +44,7 @@ ephy_cookie_manager_get_type
 ephy_permission_manager_get_type
 ephy_password_manager_get_type
 mozilla_embed_get_type
+mozilla_embed_persist_get_type
 
 #include <ephy-window.h>
 #include <ephy-tab.h>
diff --git a/doc/reference/tmpl/ephy-embed-persist.sgml b/doc/reference/tmpl/ephy-embed-persist.sgml
new file mode 100644
index 000000000..be75437c8
--- /dev/null
+++ b/doc/reference/tmpl/ephy-embed-persist.sgml
@@ -0,0 +1,308 @@
+<!-- ##### SECTION Title ##### -->
+EphyEmbedPersist
+
+<!-- ##### SECTION Short_Description ##### -->
+A class to download files
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+An #EphyEmbedPersist is a relatively simple way to save a web page or file to
+disk. It is an abstract class, implemented by #MozillaEmbedPersist.
+</para>
+<para>
+To create an #EphyEmbedPersist, use ephy_embed_factory_new_object(). Next, call
+ephy_embed_persist_set_flags() and ephy_embed_persist_set_embed(). Depending
+on the flags, you may also want to call ephy_embed_persist_set_dest() or
+ephy_embed_persist_set_source(). Finally, call ephy_embed_persist_save() to
+save the file.
+</para>
+<para>
+<example>
+<title>Saving the current web page to disk</title>
+<programlisting>#<![CDATA[include <epiphany/ephy-embed-persist.h>]]>
+#<![CDATA[include <epiphany/ephy-embed.h>
+
+static void
+save_source_completed_cb (EphyEmbedPersist *persist,
+			  gpointer dummy)
+{
+	g_print ("Download to %]]><![CDATA[s complete.\n",
+		 ephy_embed_persist_get_dest (persist));
+}
+
+void
+save_page (EphyEmbed *embed,
+	   const char *filename)
+{
+	EphyEmbedPersist *persist;
+
+	persist = EPHY_EMBED_PERSIST
+		(ephy_embed_factory_new_object ("EphyEmbedPersist"));
+
+	ephy_embed_persist_set_embed (persist, embed);
+	ephy_embed_persist_set_flags (persist, EMBED_PERSIST_NO_VIEW |
+					       EMBED_PERSIST_COPY_PAGE);
+	ephy_embed_persist_set_dest (persist, filename);
+
+	g_signal_connect (persist, "completed",
+			  G_CALLBACK (save_source_completed_cb), NULL);
+	
+	ephy_embed_persist_save (persist);
+
+	g_object_unref (persist);
+}]]>
+</programlisting>
+</example>
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM EmbedPersistFlags ##### -->
+<para>
+Determines how the #EphyEmbedPersist should act.
+</para>
+
+@EMBED_PERSIST_COPY_PAGE: If set, download a copy of the page being browsed by
+			  the #EphyEmbedPersist's #EphyEmbed. This should be
+			  specified with ephy_embed_persist_set_embed(). If
+			  unset, ephy_embed_persist_set_source() must have been
+			  called.
+@EMBED_PERSIST_MAINDOC: If set and %EMBED_PERSIST_COPY_PAGE is set, download the
+			#EphyEmbedPersist's #EphyEmbed's page's frameset. If
+			unset, download the currently-focused frame.
+@EMBED_PERSIST_NO_VIEW: If set, do not display this download in the download
+			manager.
+@EMBED_PERSIST_ASK_DESTINATION: If set, display a filechooser dialog. You must
+				call ephy_embed_persist_set_fc_title() and
+				ephy_embed_persist_set_fc_parent() before
+				ephy_embed_persist_save() if this is the case.
+				If unset, use the destination specified with
+				ephy_embed_persist_set_dest().
+
+<!-- ##### FUNCTION ephy_embed_persist_set_dest ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_embed ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_fc_title ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_fc_parent ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_flags ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_max_size ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Param2: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_persist_key ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_source ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_dest ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_embed ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_fc_title ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_fc_parent ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_flags ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_max_size ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_persist_key ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_source ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_save ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_cancel ##### -->
+<para>
+
+</para>
+
+@persist: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_to_string ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### SIGNAL EphyEmbedPersist::cancelled ##### -->
+<para>
+
+</para>
+
+@ephyembedpersist: the object which received the signal.
+
+<!-- ##### SIGNAL EphyEmbedPersist::completed ##### -->
+<para>
+
+</para>
+
+@ephyembedpersist: the object which received the signal.
+
+<!-- ##### ARG EphyEmbedPersist:dest ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:embed ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:filechooser-parent ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:filechooser-title ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:flags ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:max-size ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:persist-key ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:source ##### -->
+<para>
+
+</para>
+