From e140d51204deb9868887ad2ccb3431973448f8a5 Mon Sep 17 00:00:00 2001 From: Adam Hooper Date: Sat, 27 Mar 2004 21:51:59 +0000 Subject: EphyEmbedPersist documentation --- ChangeLog | 14 ++ doc/reference/Makefile.am | 1 - doc/reference/epiphany-docs.sgml | 1 + doc/reference/epiphany-sections.txt | 33 ++++ doc/reference/epiphany.types | 2 + doc/reference/tmpl/ephy-embed-persist.sgml | 308 +++++++++++++++++++++++++++++ embed/ephy-embed-persist.c | 193 +++++++++++++++++- embed/ephy-embed-persist.h | 10 +- 8 files changed, 554 insertions(+), 8 deletions(-) create mode 100644 doc/reference/tmpl/ephy-embed-persist.sgml diff --git a/ChangeLog b/ChangeLog index e215dfb77..f9c3edc88 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2004-03-27 Adam Hooper + + * doc/reference/Makefile.am: + * doc/reference/epiphany-docs.sgml: + * doc/reference/epiphany-sections.txt: + * doc/reference/epiphany.types: + * doc/reference/tmpl/ephy-embed-persist.sgml: + * embed/ephy-embed-persist.c: (ephy_embed_persist_get_type), + (ephy_embed_persist_class_init): + * embed/ephy-embed-persist.h: + + Document EphyEmbedPersist. Also, make it an abstract class. Change + the return type of ephy_embed_persist_get_type() to long. + 2004-03-27 Piers Cornwell * src/bookmarks/ephy-bookmarks-editor.c: (cmd_bookmarks_import): 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 @@ + Incomplete 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 +
+ephy-embed-persist +EphyEmbedPersist +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 + +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 +
+ 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 #include #include +#include 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 #include 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 @@ + +EphyEmbedPersist + + +A class to download files + + + +An #EphyEmbedPersist is a relatively simple way to save a web page or file to +disk. It is an abstract class, implemented by #MozillaEmbedPersist. + + +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. + + + +Saving the current web page to disk +#]]> +# + +static void +save_source_completed_cb (EphyEmbedPersist *persist, + gpointer dummy) +{ + g_print ("Download to %]]> + + + + + + + + + + + +Determines how the #EphyEmbedPersist should act. + + +@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(). + + + + + + +@persist: +@value: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@Param2: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@value: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: +@Returns: + + + + + + + +@persist: + + + + + + + +@persist: +@Returns: + + + + + + + +@ephyembedpersist: the object which received the signal. + + + + + + +@ephyembedpersist: the object which received the signal. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/embed/ephy-embed-persist.c b/embed/ephy-embed-persist.c index 5431af1d9..48eeb2a30 100644 --- a/embed/ephy-embed-persist.c +++ b/embed/ephy-embed-persist.c @@ -82,12 +82,19 @@ ephy_embed_persist_get_type (void) type = g_type_register_static (G_TYPE_OBJECT, "EphyEmbedPersist", - &our_info, 0); + &our_info, G_TYPE_FLAG_ABSTRACT); } return type; } +/** + * ephy_embed_persist_set_dest: + * @persist: an #EphyEmbedPersist + * @value: the path to which @persist should save data + * + * Sets the path to which @persist should save data. + **/ void ephy_embed_persist_set_dest (EphyEmbedPersist *persist, const char *value) @@ -97,6 +104,18 @@ ephy_embed_persist_set_dest (EphyEmbedPersist *persist, persist->priv->dest = g_strdup (value); } +/** + * ephy_embed_persist_set_embed: + * @persist: an #EphyEmbedPersist + * @value: a parent #EphyEmbed + * + * Sets the #EphyEmbed from which @persist will download data. + * + * An #EphyEmbed is absolutely required to download if @persist's + * #EmbedPersistFlags include %EMBED_PERSIST_COPY_PAGE. Regardless, an + * #EphyEmbed should be set for every #EphyEmbedPersist, + * since it determines request information such as the referring page. + **/ void ephy_embed_persist_set_embed (EphyEmbedPersist *persist, EphyEmbed *value) @@ -106,6 +125,15 @@ ephy_embed_persist_set_embed (EphyEmbedPersist *persist, persist->priv->embed = value; } +/** + * ephy_embed_persist_set_fc_title: + * @persist: an #EphyEmbedPersist + * @value: the title to be displayed by the filechooser + * + * Sets the title of the filechooser window. The filechooser will only be + * displayed if %EMBED_PERSIST_ASK_DESTINATION has been set with + * ephy_embed_persist_set_flags(). + **/ void ephy_embed_persist_set_fc_title (EphyEmbedPersist *persist, const char *value) @@ -115,6 +143,15 @@ ephy_embed_persist_set_fc_title (EphyEmbedPersist *persist, persist->priv->fc_title = g_strdup (value); } +/** + * ephy_embed_persist_set_fc_parent: + * @persist: an #EphyEmbedPersist + * @value: the #EphyWindow which should be the filechooser's parent + * + * Sets the #EphyWindow which should be @persist's filechooser's parent. The + * filechooser will only be displayed if %EMBED_PERSIST_ASK_DESTINATION has been + * set with ephy_embed_persist_set_flags(). + **/ void ephy_embed_persist_set_fc_parent (EphyEmbedPersist *persist, GtkWindow *value) @@ -124,6 +161,13 @@ ephy_embed_persist_set_fc_parent (EphyEmbedPersist *persist, persist->priv->fc_parent = value; } +/** + * ephy_embed_persist_set_flags: + * @persist: an #EphyEmbedPersist + * @value: the desired #EmbedPersistFlags + * + * Sets the flags to be used for @persist's download. + **/ void ephy_embed_persist_set_flags (EphyEmbedPersist *persist, EmbedPersistFlags value) @@ -133,6 +177,18 @@ ephy_embed_persist_set_flags (EphyEmbedPersist *persist, persist->priv->flags = value; } +/** + * ephy_embed_persist_set_max_size: + * @persist: an #EphyEmbedPersist + * @value: maximum size of requested download, in bytes + * + * Sets the maximum size of @persist's download. + * + * If the requested file is discovered to be larger than @value, the download + * will be aborted. Note that @persist will have to actually begin downloading + * before it can abort, since it doesn't know the filesize before the download + * starts. + **/ void ephy_embed_persist_set_max_size (EphyEmbedPersist *persist, long value) @@ -142,6 +198,14 @@ ephy_embed_persist_set_max_size (EphyEmbedPersist *persist, persist->priv->max_size = value; } +/** + * ephy_embed_persist_set_persist_key: + * @persist: an #EphyEmbedPersist + * @value: a GConf key + * + * Sets the GConf key from which @persist will determine the default download + * directory. + **/ void ephy_embed_persist_set_persist_key (EphyEmbedPersist *persist, const char *value) @@ -151,6 +215,14 @@ ephy_embed_persist_set_persist_key (EphyEmbedPersist *persist, persist->priv->persist_key = g_strdup (value); } +/** + * ephy_embed_persist_set_source: + * @persist: an #EphyEmbedPersist + * @value: the URL from which @persist should download + * + * Sets the URL from which @persist should download. This should be used in + * conjunction with ephy_embed_persist_set_embed(). + **/ void ephy_embed_persist_set_source (EphyEmbedPersist *persist, const char *value) @@ -160,6 +232,14 @@ ephy_embed_persist_set_source (EphyEmbedPersist *persist, persist->priv->source = g_strdup (value); } +/** + * ephy_embed_persist_get_dest: + * @persist: an #EphyEmbedPersist + * + * Returns the destination filename to which @persist will save its download. + * + * Return value: @persist's destination filename + **/ const char * ephy_embed_persist_get_dest (EphyEmbedPersist *persist) { @@ -168,6 +248,14 @@ ephy_embed_persist_get_dest (EphyEmbedPersist *persist) return persist->priv->dest; } +/** + * ephy_embed_persist_get_embed: + * @persist: an #EphyEmbedPersist + * + * Returns the #EphyEmbed from which @persist will download. + * + * Return value: the #EphyEmbed from which @persist will download + **/ EphyEmbed * ephy_embed_persist_get_embed (EphyEmbedPersist *persist) { @@ -176,6 +264,14 @@ ephy_embed_persist_get_embed (EphyEmbedPersist *persist) return persist->priv->embed; } +/** + * ephy_embed_persist_get_fc_title: + * @persist: an #EphyEmbedPersist + * + * Returns the title to be displayed in @persist's filechooser. + * + * Return value: the title to be displayed in @persist's filechooser + **/ const char * ephy_embed_persist_get_fc_title (EphyEmbedPersist *persist) { @@ -184,6 +280,15 @@ ephy_embed_persist_get_fc_title (EphyEmbedPersist *persist) return persist->priv->fc_title; } +/** + * ephy_embed_persist_get_fc_parent: + * @persist: an #EphyEmbedPersist + * + * Returns the #EphyWindow which should serve as a parent for @persist's + * filechooser. + * + * Return value: the #EphyWindow parent for @persist's filechooser + **/ GtkWindow * ephy_embed_persist_get_fc_parent (EphyEmbedPersist *persist) { @@ -192,6 +297,14 @@ ephy_embed_persist_get_fc_parent (EphyEmbedPersist *persist) return persist->priv->fc_parent; } +/** + * ephy_embed_persist_get_flags: + * @persist: an #EphyEmbedPersist + * + * Returns @persist's #EmbedPersistFlags. + * + * Return value: @persist's #EmbedPersistFlags + **/ EmbedPersistFlags ephy_embed_persist_get_flags (EphyEmbedPersist *persist) { @@ -200,7 +313,15 @@ ephy_embed_persist_get_flags (EphyEmbedPersist *persist) return persist->priv->flags; } -int +/** + * ephy_embed_persist_get_max_size: + * @persist: an #EphyEmbedPersist + * + * Returns the maximum size of @persist's requested download, in bytes. + * + * Return value: the maximum size of @persist's requested download, in bytes + **/ +long ephy_embed_persist_get_max_size (EphyEmbedPersist *persist) { g_return_val_if_fail (EPHY_IS_EMBED_PERSIST (persist), 0); @@ -208,6 +329,14 @@ ephy_embed_persist_get_max_size (EphyEmbedPersist *persist) return persist->priv->max_size; } +/** + * ephy_embed_persist_get_persist_key: + * @persist: an #EphyEmbedPersist + * + * Returns the GConf key which determines Epiphany's default download directory. + * + * Return value: the GConf key to the default download directory + **/ const char * ephy_embed_persist_get_persist_key (EphyEmbedPersist *persist) { @@ -216,6 +345,14 @@ ephy_embed_persist_get_persist_key (EphyEmbedPersist *persist) return persist->priv->persist_key; } +/** + * ephy_embed_persist_get_source: + * @persist: an #EphyEmbedPersist + * + * Returns the source URL of the file to download. + * + * Return value: a source URL + **/ const char * ephy_embed_persist_get_source (EphyEmbedPersist *persist) { @@ -341,6 +478,12 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass) object_class->get_property = ephy_embed_persist_get_property; /* init signals */ +/** + * EphyEmbedPersist::completed: + * + * The ::completed signal is emitted when @persist has finished downloading. The + * download must have started with ephy_embed_persist_save(). + **/ g_signal_new ("completed", G_OBJECT_CLASS_TYPE (object_class), G_SIGNAL_RUN_LAST, @@ -349,6 +492,12 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass) g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); +/** + * EphyEmbedPersist::cancelled: + * + * The ::cancelled signal is emitted when @persist's download has been + * cancelled with ephy_embed_persist_cancel(). + **/ g_signal_new ("cancelled", G_OBJECT_CLASS_TYPE (object_class), G_SIGNAL_RUN_LAST, @@ -430,6 +579,13 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass) g_type_class_add_private (object_class, sizeof(EphyEmbedPersistPrivate)); } +/** + * ephy_embed_persist_cancel: + * @persist: an #EphyEmbedPersist + * + * Cancels @persist's download. This will not delete the partially downloaded + * file. + **/ void ephy_embed_persist_cancel (EphyEmbedPersist *persist) { @@ -437,12 +593,45 @@ ephy_embed_persist_cancel (EphyEmbedPersist *persist) klass->cancel (persist); } +/** + * ephy_embed_persist_save: + * @persist: an #EphyEmbedPersist + * + * Begins saving the file specified in @persist. + * + * If @persist's #EmbedPersistFlags include %EMBED_PERSIST_ASK_DESTINATION, a + * filechooser dialog will be shown first. + * + * The file will continue to download in the background until either the + * ::completed or the ::cancelled signals are emitted by @persist. + * + * Return value: %TRUE if the download began successfully + **/ gboolean ephy_embed_persist_save (EphyEmbedPersist *persist) { EphyEmbedPersistClass *klass = EPHY_EMBED_PERSIST_GET_CLASS (persist); return klass->save (persist); } + +/** + * ephy_embed_persist_to_string: + * @persist: an #EphyEmbedPersist + * + * Returns the download specified by @persist as a string instead of downloading + * it to a file. + * + * The download is synchronous. An #EphyEmbed must be specified with + * ephy_embed_persist_set_embed(). The function implicitly assumes that + * @persist's #EmbedPersistFlags include %EMBED_PERSIST_COPY_PAGE. If @persist's + * #EphyEmbed has not finished downloading, this function will only return the + * portion of data which has already been downloaded. + * + * The document will be modified: it will only include absolute links and it + * will be encoded as UTF-8. + * + * Return value: The contents of @persist's #EphyEmbed's web page + **/ char * ephy_embed_persist_to_string (EphyEmbedPersist *persist) { diff --git a/embed/ephy-embed-persist.h b/embed/ephy-embed-persist.h index dbd0272ae..2d785bfaa 100644 --- a/embed/ephy-embed-persist.h +++ b/embed/ephy-embed-persist.h @@ -38,8 +38,8 @@ G_BEGIN_DECLS #define EPHY_IS_EMBED_PERSIST_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), EPHY_TYPE_EMBED_PERSIST)) #define EPHY_EMBED_PERSIST_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), EPHY_TYPE_EMBED_PERSIST, EphyEmbedPersistClass)) -typedef struct EphyEmbedPersistClass EphyEmbedPersistClass; -typedef struct EphyEmbedPersist EphyEmbedPersist; +typedef struct _EphyEmbedPersistClass EphyEmbedPersistClass; +typedef struct _EphyEmbedPersist EphyEmbedPersist; typedef struct EphyEmbedPersistPrivate EphyEmbedPersistPrivate; typedef enum @@ -50,7 +50,7 @@ typedef enum EMBED_PERSIST_ASK_DESTINATION = 1 << 3 } EmbedPersistFlags; -struct EphyEmbedPersist +struct _EphyEmbedPersist { GObject parent; @@ -58,7 +58,7 @@ struct EphyEmbedPersist EphyEmbedPersistPrivate *priv; }; -struct EphyEmbedPersistClass +struct _EphyEmbedPersistClass { GObjectClass parent_class; @@ -113,7 +113,7 @@ GtkWindow *ephy_embed_persist_get_fc_parent (EphyEmbedPersist *persist); EmbedPersistFlags ephy_embed_persist_get_flags (EphyEmbedPersist *persist); -int ephy_embed_persist_get_max_size (EphyEmbedPersist *persist); +long ephy_embed_persist_get_max_size (EphyEmbedPersist *persist); const char *ephy_embed_persist_get_persist_key (EphyEmbedPersist *persist); -- cgit v1.2.3