From d3cea4a501d33f5b747f4a54381660bdc1fac5a5 Mon Sep 17 00:00:00 2001 From: Adam Hooper Date: Tue, 23 Mar 2004 17:31:42 +0000 Subject: API documentation --- data/.cvsignore | 1 + doc/plan.xml | 9 +- doc/reference-howto.txt | 2 +- doc/reference/Makefile.am | 1 - doc/reference/tmpl/ephy-permission-manager.sgml | 88 +++++------ doc/reference/tmpl/ephy-window.sgml | 198 ++++++++++++++++++++++++ embed/ephy-permission-manager.c | 43 ++--- embed/ephy-permission-manager.h | 12 +- src/ephy-window.c | 129 ++++++++++++++- src/ephy-window.h | 5 +- 10 files changed, 404 insertions(+), 84 deletions(-) create mode 100644 doc/reference/tmpl/ephy-window.sgml diff --git a/data/.cvsignore b/data/.cvsignore index 7bb3a91a0..bbc091564 100644 --- a/data/.cvsignore +++ b/data/.cvsignore @@ -7,3 +7,4 @@ epiphany.desktop bme.desktop epiphany-1.0.pc epiphany-1.2.pc +epiphany-1.4.pc diff --git a/doc/plan.xml b/doc/plan.xml index 18326e01e..c850afa7a 100644 --- a/doc/plan.xml +++ b/doc/plan.xml @@ -79,9 +79,14 @@ - Extensions: Loading/Unloading + Extensions Lifecycle - Dynamic loading/unloading of extensions. + Right now the startup process is: "startup -> get session -> + get extensions manager -> load extensions -> get session". We + should make the extensions manager load extensions *later*, so that the + session is created for them by the time they need it. + + This should pave the way for dynamic loading/unloading of extensions. Adam Hooper diff --git a/doc/reference-howto.txt b/doc/reference-howto.txt index 743b636aa..66dc14f22 100644 --- a/doc/reference-howto.txt +++ b/doc/reference-howto.txt @@ -11,7 +11,7 @@ For example: * * Resume a crashed session when necessary (interactive) * - * Return value: TRUE if at least a window has been opened + * Return value: %TRUE if at least a window has been opened **/ gboolean ephy_session_autoresume (EphySession *session) diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index 5da5f7d7f..bf39bae09 100644 --- a/doc/reference/Makefile.am +++ b/doc/reference/Makefile.am @@ -138,7 +138,6 @@ IGNORE_HFILES = \ ephy-tab.h \ ephy-tabs-menu.h \ ephy-toolbars-model.h \ - ephy-window.h \ language-editor.h \ pdm-dialog.h \ popup-commands.h \ diff --git a/doc/reference/tmpl/ephy-permission-manager.sgml b/doc/reference/tmpl/ephy-permission-manager.sgml index 516bfac21..f62bd4de1 100644 --- a/doc/reference/tmpl/ephy-permission-manager.sgml +++ b/doc/reference/tmpl/ephy-permission-manager.sgml @@ -1,79 +1,77 @@ -ephy-permission-manager +EphyPermissionManager - +Sets webpages' cookie, image and popup permissions. - +The #EphyPermissionManager keeps a list of websites and their permissions. For +example, the user may want a certain website to display images but block +cookies and popup windows; this could correspond to three entries in the +#EphyPermissionManager. - - - +Use ephy_permission_manager_add() to set permissions for a website, +ephy_permission_manager_remove() to remove the permissions, and +ephy_permission_manager_test() to test them. Note that +ephy_permission_manager_test() may return %EPHY_PERMISSION_DEFAULT, which +means the caller might need to find the default permission some other way. - - - +The #EphyPermissionManager stores a list of site-specific permissions, but not +defaults. For popups, the default permission is determined by the GConf key +/apps/epiphany/web/allow_popups, which in turn determines Mozilla's +dom.disable_open_during_load preference. For cookies, the GConf key +/apps/epiphany/web/cookie_accept determines Mozilla's +network.cookie.cookieBehavior preference. For images, the default is determined +by Mozilla's network.image.imageBehavior preference. - -@k: - - - - +Though the word "host" is used in many function descriptions, Mozilla +does not act as one would expect. Always pass a URL to any functions which +need have a "host" parameter. However, the "host" in an +#EphyPermissionInfo is a simple DNS hostname. -@k: - - - + + + +Details a specific permission of a specific website. + +@host: The hostname of the website to which this permission applies. +@type: An #EphyPermissionType. +@permission: An #EphyPermission (either allow or deny). - +Determines what permission we're dealing with. @EPT_COOKIE: + Permission for the website to store cookies on the user's computer. @EPT_IMAGE: + Permission for the website to show images to the user. @EPT_POPUP: + Permission for the website to open popup windows (using JavaScript). - +Determines whether the website is allowed or denied access. @EPHY_PERMISSION_ALLOWED: + The website is unconditionally allowed to perform the desired action. @EPHY_PERMISSION_DENIED: + The website is unconditionally denied to perform the desired action. @EPHY_PERMISSION_DEFAULT: - - - - - - -@host: -@type: -@permission: -@Returns: - - - - - - - -@info: -@Returns: - + The user has not set a preference for this particular website; the + caller should therefore fall back to default settings. @@ -83,14 +81,6 @@ ephy-permission-manager @info: - - - - - -@Returns: - - diff --git a/doc/reference/tmpl/ephy-window.sgml b/doc/reference/tmpl/ephy-window.sgml new file mode 100644 index 000000000..391abd920 --- /dev/null +++ b/doc/reference/tmpl/ephy-window.sgml @@ -0,0 +1,198 @@ + +EphyWindow + + +Represents an Epiphany window. + + + +An #EphyWindow is what the user sees when opening Epiphany. Think of each +#EphyWindow as a giant container which holds many useful items: + + +A toolbar, available from ephy_window_get_toolbar(). +An #EphyStatusbar, available from +ephy_window_get_statusbar(). +A #GtkNotebook for holding #EphyTabs. Use ephy_window_get_notebook(), +ephy_window_get_tabs() and ephy_window_get_active_tab() to reach +them. Manipulate tabs using ephy_window_add_tab(), ephy_window_remove_tab() +and ephy_window_jump_to_tab(). + + +You can also perform simple manipulations of an #EphyWindow's active #EphyEmbed. +These are restricted to ephy_window_set_zoom() and ephy_window_load_url(). + + + + + + + + + + + + +@ui_merge: The #GtkUIManager this window uses to merge user interfaces + + + + + + +@Returns: + + + + + + + +@chrome: +@Returns: + + + + + + + +@window: +@Returns: + + + + + + + +@window: +@tab: +@position: +@jump_to: + + + + + + + +@window: +@tab: + + + + + + + +@window: +@tab: + + + + + + + +@window: +@Returns: + + + + + + + +@window: +@Returns: + + + + + + + +@window: +@Returns: + + + + + + + +@window: +@Returns: + + + + + + + +@window: +@Returns: + + + + + + + +@window: + + + + + + + +@window: + + + + + + + +@window: +@enabled: + + + + + + + +@window: +@zoom: + + + + + + + +@window: + + + + + + + +@window: +@url: + + + + + + + + + + + + diff --git a/embed/ephy-permission-manager.c b/embed/ephy-permission-manager.c index 6a4eb76c5..db841296d 100644 --- a/embed/ephy-permission-manager.c +++ b/embed/ephy-permission-manager.c @@ -47,7 +47,7 @@ ephy_permission_info_get_type (void) /** * ephy_permission_info_new: * @host: a host name - * @type: a #EphyPermissionType + * @type: an #EphyPermissionType * @allowed: whether @host should be allowed to do what @type specifies * * Return value: the new #EphyPermissionInfo @@ -68,7 +68,7 @@ ephy_permission_info_new (const char *host, /** * ephy_permission_info_copy: - * @info: a #EphyPermissionInfo + * @info: an #EphyPermissionInfo * * Return value: a copy of @info **/ @@ -86,7 +86,7 @@ ephy_permission_info_copy (const EphyPermissionInfo *info) /** * ephy_permission_info_free: - * @info: a #EphyPermissionInfo + * @info: an #EphyPermissionInfo * * Frees @info. **/ @@ -211,12 +211,11 @@ ephy_permission_manager_base_init (gpointer g_class) /** * ephy_permission_manager_add: * @manager: the #EphyPermissionManager - * @host: a host name - * @type: a #EphyPermissionType - * @permission: either #EPHY_PERMISSION_ALLOWED or #EPHY_PERMISSION_DENIED + * @host: a website URL + * @type: an #EphyPermissionType + * @permission: either %EPHY_PERMISSION_ALLOWED or %EPHY_PERMISSION_DENIED * - * Adds the permission @allow of type @type for host @host to the permissions - * database. + * Adds the specified permission to the permissions database. **/ void ephy_permission_manager_add (EphyPermissionManager *manager, @@ -231,11 +230,12 @@ ephy_permission_manager_add (EphyPermissionManager *manager, /** * ephy_permission_manager_remove: * @manager: the #EphyPermissionManager - * @host: a host name - * @type: a #EphyPermissionType + * @host: a website URL + * @type: an #EphyPermissionType * - * Removes the permission of type @type for host @host from the permissions - * database. + * Removes the specified permission from the permissions database. This implies + * that the browser should use defaults when next visiting the specified + * @host's web pages. **/ void ephy_permission_manager_remove (EphyPermissionManager *manager, @@ -250,7 +250,7 @@ ephy_permission_manager_remove (EphyPermissionManager *manager, * ephy_permission_manager_clear: * @manager: the #EphyPermissionManager * - * Clears the permissions database. + * Clears the permissions database. This cannot be undone. **/ void ephy_permission_manager_clear (EphyPermissionManager *manager) @@ -262,11 +262,13 @@ ephy_permission_manager_clear (EphyPermissionManager *manager) /** * ephy_permission_manager_test: * @manager: the #EphyPermissionManager - * @host: a host name - * @type: a #EphyPermissionType + * @host: a website URL + * @type: an #EphyPermissionType * - * Gets the permission of @host for type @type. If there is no entry - * for this type for @host, it will return #EPHY_PERMISSION_DEFAULT. + * Retrieves an #EphyPermissionType from the permissions database. If there is + * no entry for this @type and @host, it will return %EPHY_PERMISSION_DEFAULT. + * In that case, the caller may need to determine the appropriate default + * behavior. * * Return value: the permission of type #EphyPermission **/ @@ -282,12 +284,13 @@ ephy_permission_manager_test (EphyPermissionManager *manager, /** * ephy_permission_manager_list: * @manager: the #EphyPermissionManager - * @type: a #EphyPermissionType + * @type: an #EphyPermissionType * * Lists all permission entries of type @type in the permissions database, each - * as its own #EphyPermissionInfo + * as its own #EphyPermissionInfo. These entries must be freed using + * ephy_permission_info_free(). * - * Return value: the list of permission entries + * Return value: the list of permission database entries **/ GList * ephy_permission_manager_list (EphyPermissionManager *manager, diff --git a/embed/ephy-permission-manager.h b/embed/ephy-permission-manager.h index 0be7fbdee..4d85accdf 100644 --- a/embed/ephy-permission-manager.h +++ b/embed/ephy-permission-manager.h @@ -36,9 +36,6 @@ G_BEGIN_DECLS #define EPHY_TYPE_PERMISSION_INFO (ephy_permission_info_get_type ()) -typedef struct EphyPermissionManager EphyPermissionManager; -typedef struct EphyPermissionManagerIface EphyPermissionManagerIface; - typedef enum { EPT_COOKIE, @@ -53,12 +50,17 @@ typedef enum EPHY_PERMISSION_DEFAULT } EphyPermission; -typedef struct +typedef struct _EphyPermissionInfo EphyPermissionInfo; + +typedef struct EphyPermissionManager EphyPermissionManager; +typedef struct EphyPermissionManagerIface EphyPermissionManagerIface; + +struct _EphyPermissionInfo { char *host; EphyPermissionType type; EphyPermission permission; -} EphyPermissionInfo; +}; struct EphyPermissionManagerIface { diff --git a/src/ephy-window.c b/src/ephy-window.c index ccccebe16..7408c3cb7 100644 --- a/src/ephy-window.c +++ b/src/ephy-window.c @@ -2062,12 +2062,28 @@ ephy_window_finalize (GObject *object) g_object_unref (ephy_shell); } +/** + * ephy_window_new: + * + * Equivalent to g_object_new() but returns an #EphyWindow so you don't have + * to cast it. + * + * Return value: a new #EphyWindow + **/ EphyWindow * ephy_window_new (void) { return EPHY_WINDOW (g_object_new (EPHY_TYPE_WINDOW, NULL)); } +/** + * ephy_window_new_with_chrome: + * @chrome: an #EphyEmbedChrome + * + * Identical to ephy_window_new(), but allows you to specify a chrome. + * + * Return value: a new #EphyWindow + **/ EphyWindow * ephy_window_new_with_chrome (EphyEmbedChrome chrome) { @@ -2076,6 +2092,13 @@ ephy_window_new_with_chrome (EphyEmbedChrome chrome) NULL)); } +/** + * ephy_window_set_print_preview: + * @window: an #EphyWindow + * @enabled: %TRUE to enable print preview mode + * + * Sets whether the window is in print preview mode. + **/ void ephy_window_set_print_preview (EphyWindow *window, gboolean enabled) { @@ -2111,6 +2134,16 @@ ephy_window_set_print_preview (EphyWindow *window, gboolean enabled) } } +/** + * ephy_window_get_toolbar: + * @window: an #EphyWindow + * + * Returns this window's toolbar as an #EggEditableToolbar. Note that this + * toolbar is uneditable outside of Epiphany itself (i.e., extensions should not + * access it). + * + * Return value: an #EggEditableToolbar + **/ GtkWidget * ephy_window_get_toolbar (EphyWindow *window) { @@ -2119,6 +2152,14 @@ ephy_window_get_toolbar (EphyWindow *window) return GTK_WIDGET (window->priv->toolbar); } +/** + * ephy_window_get_notebook: + * @window: an #EphyWindow + * + * Returns the #GtkNotebook used by this window. + * + * Return value: the @window's #GtkNotebook + **/ GtkWidget * ephy_window_get_notebook (EphyWindow *window) { @@ -2127,6 +2168,14 @@ ephy_window_get_notebook (EphyWindow *window) return GTK_WIDGET (window->priv->notebook); } +/** + * ephy_window_get_statusbar: + * @window: an #EphyWindow + * + * Returns this window's statusbar as an #EphyStatusbar. + * + * Return value: This window's statusbar + **/ GtkWidget * ephy_window_get_statusbar (EphyWindow *window) { @@ -2135,6 +2184,15 @@ ephy_window_get_statusbar (EphyWindow *window) return GTK_WIDGET (window->priv->statusbar); } +/** + * ephy_window_add_tab: + * @window: an #EphyWindow + * @tab: an #EphyTab + * @position: the position in @window's #GtkNotebook + * @jump_to: %TRUE to switch to @tab's new notebook page after insertion + * + * Inserts @tab into @window. + **/ void ephy_window_add_tab (EphyWindow *window, EphyTab *tab, @@ -2152,6 +2210,13 @@ ephy_window_add_tab (EphyWindow *window, tab, position, jump_to); } +/** + * ephy_window_jump_to_tab: + * @window: an #EphyWindow + * @tab: an #EphyTab inside @window + * + * Switches @window's #GtkNotebook to open @tab as its current page. + **/ void ephy_window_jump_to_tab (EphyWindow *window, EphyTab *tab) @@ -2180,6 +2245,13 @@ real_get_active_tab (EphyWindow *window, int page_num) return EPHY_TAB (tab); } +/** + * ephy_window_remove_tab: + * @window: an #EphyWindow + * @tab: an #EphyTab + * + * Removes @tab from @window. + **/ void ephy_window_remove_tab (EphyWindow *window, EphyTab *tab) @@ -2209,8 +2281,8 @@ ephy_window_remove_tab (EphyWindow *window, * @window: a #EphyWindow * @url: the url to load * - * Load a new url in the active tab of the window. - * Unlike ephy_embed_load_url this function activate + * Loads a new url in the active tab of @window. + * Unlike ephy_embed_load_url(), this function activates * the embed. * **/ @@ -2229,11 +2301,24 @@ ephy_window_load_url (EphyWindow *window, ephy_embed_activate (embed); } -void ephy_window_activate_location (EphyWindow *window) +/** + * ephy_window_activate_location: + * @window: an #EphyWindow + * + * Activates the location entry on @window's toolbar. + **/ +void +ephy_window_activate_location (EphyWindow *window) { toolbar_activate_location (window->priv->toolbar); } +/** + * ephy_window_show: + * @widget: an #EphyWindow + * + * Shows @widget if it is hidden. + **/ void ephy_window_show (GtkWidget *widget) { @@ -2260,6 +2345,14 @@ ephy_window_show (GtkWidget *widget) GTK_WIDGET_CLASS (parent_class)->show (widget); } +/** + * ephy_window_get_active_tab: + * @window: an #EphyWindow + * + * Returns @window's active #EphyTab. + * + * Return value: @window's active tab + **/ EphyTab * ephy_window_get_active_tab (EphyWindow *window) { @@ -2269,6 +2362,15 @@ ephy_window_get_active_tab (EphyWindow *window) return window->priv->active_tab; } +/** + * ephy_window_get_active_embed: + * @window: an #EphyWindow + * + * Return @window's active #EphyEmbed. This is identical to calling + * ephy_window_get_active_tab() followed by ephy_tab_get_embed(). + * + * Return value: @window's active embed + **/ EphyEmbed * ephy_window_get_active_embed (EphyWindow *window) { @@ -2288,6 +2390,7 @@ ephy_window_get_active_embed (EphyWindow *window) * * Returns the list of #EphyTab:s in the window. * + * Return value: a list of #EphyTab:s */ GList * ephy_window_get_tabs (EphyWindow *window) @@ -2354,6 +2457,12 @@ ephy_window_notebook_switch_page_cb (GtkNotebook *notebook, update_tabs_menu_sensitivity (window); } +/** + * ephy_window_find: + * @window: an #EphyWindow + * + * Displays @window's Find dialog. + **/ void ephy_window_find (EphyWindow *window) { @@ -2376,6 +2485,12 @@ ephy_window_find (EphyWindow *window) ephy_dialog_show (window->priv->find_dialog); } +/** + * ephy_window_print: + * @window: an #EphyWindow + * + * Displays @window's Print dialog. + **/ void ephy_window_print (EphyWindow *window) { @@ -2418,6 +2533,14 @@ ephy_window_print (EphyWindow *window) ephy_dialog_show (window->priv->print_dialog); } +/** + * ephy_window_set_zoom: + * @window: an #EphyWindow + * @zoom: the desired zoom level + * + * Sets the zoom on @window's active #EphyEmbed. A @zoom of 1.0 corresponds to + * 100% zoom (normal size). + **/ void ephy_window_set_zoom (EphyWindow *window, float zoom) diff --git a/src/ephy-window.h b/src/ephy-window.h index 476c2d6b7..985029d21 100644 --- a/src/ephy-window.h +++ b/src/ephy-window.h @@ -38,16 +38,15 @@ G_BEGIN_DECLS #define EPHY_WINDOW_GET_CLASS(o)(G_TYPE_INSTANCE_GET_CLASS ((o), EPHY_TYPE_WINDOW, EphyWindowClass)) typedef struct EphyWindowClass EphyWindowClass; -typedef struct EphyWindow EphyWindow; +typedef struct _EphyWindow EphyWindow; typedef struct EphyWindowPrivate EphyWindowPrivate; -struct EphyWindow +struct _EphyWindow { GtkWindow parent; /*< private >*/ EphyWindowPrivate *priv; - /* Public to toolbar and statusbar, dont use outside */ /*< public >*/ GObject *ui_merge; }; -- cgit v1.2.3