diff options
| -rw-r--r-- | ChangeLog | 19 | ||||
| -rw-r--r-- | doc/reference/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/reference/epiphany-docs.sgml | 1 | ||||
| -rw-r--r-- | doc/reference/epiphany-sections.txt | 19 | ||||
| -rw-r--r-- | doc/reference/tmpl/ephy-tab.sgml | 139 | ||||
| -rw-r--r-- | src/ephy-tab.c | 213 | ||||
| -rw-r--r-- | src/ephy-tab.h | 7 |
7 files changed, 379 insertions, 20 deletions
@@ -1,5 +1,24 @@ 2004-03-23 Adam Hooper <adamh@cvs.gnome.org> + * doc/reference/Makefile.am: + * doc/reference/epiphany-docs.sgml: + * doc/reference/epiphany-sections.txt: + * doc/reference/tmpl/ephy-tab.sgml: + * src/ephy-tab.c: (ephy_tab_get_size), (ephy_tab_visibility_cb): + * src/ephy-tab.h: + + Added EphyTab API documentation. + + Also removed ephy_tab_set_visibility + and moved its functionality into ephy_tab_visibility_cb (), since I + doubt it's got any practical use outside of there. (Though admittedly, + I don't know whether "visibility" has any practical use anywhere.) + + Lastly, let ephy_tab_get_size () be called with NULL width or height, + like gtk_window_get_size (). + +2004-03-23 Adam Hooper <adamh@cvs.gnome.org> + * doc/reference/epiphany-docs.sgml: * doc/reference/epiphany-sections.txt: * doc/reference/tmpl/epiphany-unused.sgml: diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am index bf39bae09..c1026de81 100644 --- a/doc/reference/Makefile.am +++ b/doc/reference/Makefile.am @@ -135,7 +135,6 @@ IGNORE_HFILES = \ ephy-navigation-action.h \ ephy-notebook.h \ ephy-statusbar.h \ - ephy-tab.h \ ephy-tabs-menu.h \ ephy-toolbars-model.h \ language-editor.h \ diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml index 23a8b0ef5..7adab1ca0 100644 --- a/doc/reference/epiphany-docs.sgml +++ b/doc/reference/epiphany-docs.sgml @@ -10,6 +10,7 @@ <title>Epiphany</title> <xi:include href="xml/ephy-permission-manager.xml"/> <xi:include href="xml/ephy-window.xml"/> + <xi:include href="xml/ephy-tab.xml"/> </chapter> <chapter> <title>Incomplete</title> diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt index 91e21bbc4..f77ba5439 100644 --- a/doc/reference/epiphany-sections.txt +++ b/doc/reference/epiphany-sections.txt @@ -36,6 +36,25 @@ ephy_window_activate_location ephy_window_load_url </SECTION> +<SECTION> +<FILE>ephy-tab</FILE> +<TITLE>EphyTab</TITLE> +EphyTab +ephy_tab_new +ephy_tab_get_window +ephy_tab_get_embed +ephy_tab_for_embed +ephy_tab_get_icon_address +ephy_tab_get_location +ephy_tab_get_security_level +ephy_tab_get_title +ephy_tab_get_zoom +ephy_tab_get_load_status +ephy_tab_get_load_percent +ephy_tab_get_link_message +ephy_tab_get_status_message +</SECTION> + diff --git a/doc/reference/tmpl/ephy-tab.sgml b/doc/reference/tmpl/ephy-tab.sgml new file mode 100644 index 000000000..c598e77a8 --- /dev/null +++ b/doc/reference/tmpl/ephy-tab.sgml @@ -0,0 +1,139 @@ +<!-- ##### SECTION Title ##### --> +EphyTab + +<!-- ##### SECTION Short_Description ##### --> +Represents an Epiphany tab + +<!-- ##### SECTION Long_Description ##### --> +<para> +Each #EphyWindow contains a #GtkNotebook which holds one or more #EphyTab:s. +An #EphyTab is basically a container for an #EphyEmbed. +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### STRUCT EphyTab ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION ephy_tab_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_window ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_embed ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_for_embed ##### --> +<para> + +</para> + +@embed: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_icon_address ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_location ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_security_level ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_title ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_zoom ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_load_status ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_load_percent ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_link_message ##### --> +<para> + +</para> + +@tab: +@Returns: + + +<!-- ##### FUNCTION ephy_tab_get_status_message ##### --> +<para> + +</para> + +@tab: +@Returns: + + diff --git a/src/ephy-tab.c b/src/ephy-tab.c index 73668100b..dece74ea7 100644 --- a/src/ephy-tab.c +++ b/src/ephy-tab.c @@ -441,6 +441,14 @@ address_has_web_scheme (const char *address) /* Public functions */ +/** + * ephy_tab_new: + * + * Equivalent to g_object_new(), but returns an #EphyTab so you don't have to + * cast it. + * + * Returns: a new #EphyTab + **/ EphyTab * ephy_tab_new (void) { @@ -457,6 +465,16 @@ ephy_tab_set_load_status (EphyTab *tab, gboolean status) g_object_notify (G_OBJECT (tab), "load-status"); } +/** + * ephy_tab_get_load_status: + * @tab: an #EphyTab + * + * Returns whether the web page in @tab has finished loading. A web page is + * only finished loading after all images, styles, and other dependencies have + * been downloaded and rendered. + * + * Return value: %TRUE if the page is still loading, %FALSE if complete + **/ gboolean ephy_tab_get_load_status (EphyTab *tab) { @@ -476,6 +494,20 @@ ephy_tab_set_link_message (EphyTab *tab, char *message) g_object_notify (G_OBJECT (tab), "message"); } +/** + * ephy_tab_get_link_message: + * @tab: an #EphyTab + * + * Returns the message displayed in @tab's #EphyWindow's #EphyStatusbar when + * the user hovers the mouse over a hyperlink. + * + * The message returned has a limited lifetime, and so should be copied with + * g_strdup() if it must be stored. + * + * Listen to "notify::message" to be notified when the message property changes. + * + * Return value: The current link statusbar message + **/ const char * ephy_tab_get_link_message (EphyTab *tab) { @@ -484,6 +516,14 @@ ephy_tab_get_link_message (EphyTab *tab) return tab->priv->link_message; } +/** + * ephy_tab_get_embed: + * @tab: an #EphyTab + * + * Returns @tab's #EphyEmbed. + * + * Return value: @tab's #EphyEmbed + **/ EphyEmbed * ephy_tab_get_embed (EphyTab *tab) { @@ -492,6 +532,14 @@ ephy_tab_get_embed (EphyTab *tab) return EPHY_EMBED (gtk_bin_get_child (GTK_BIN (tab))); } +/** + * ephy_tab_for_embed + * @embed: an #EphyEmbed + * + * Returns the #EphyTab which holds @embed. + * + * Return value: the #EphyTab which holds @embed + **/ EphyTab * ephy_tab_for_embed (EphyEmbed *embed) { @@ -505,6 +553,13 @@ ephy_tab_for_embed (EphyEmbed *embed) return EPHY_TAB (parent); } +/** + * ephy_tab_set_window: + * @tab: an #EphyTab + * @window: @tab's #EphyWindow + * + * FIXME: DO NOT USE + **/ void ephy_tab_set_window (EphyTab *tab, EphyWindow *window) { @@ -519,6 +574,14 @@ ephy_tab_set_window (EphyTab *tab, EphyWindow *window) } } +/** + * ephy_tab_get_window: + * @tab: an #EphyTab\ + * + * Returns the #EphyWindow which holds @tab in its #GtkNotebook. + * + * Return value: @tab's #EphyWindow + **/ EphyWindow * ephy_tab_get_window (EphyTab *tab) { @@ -527,15 +590,38 @@ ephy_tab_get_window (EphyTab *tab) return tab->priv->window; } +/** + * ephy_tab_get_size: + * @tab: an #EphyTab + * @width: return location for width, or %NULL + * @height: return location for height, or %NULL + * + * Obtains the size of @tab. This is not guaranteed to be the actual number of + * pixels occupied by the #EphyTab. + **/ void ephy_tab_get_size (EphyTab *tab, int *width, int *height) { g_return_if_fail (EPHY_IS_TAB (tab)); - *width = tab->priv->width; - *height = tab->priv->height; + if (width != NULL) + { + *width = tab->priv->width; + } + if (height != NULL) + { + *height = tab->priv->height; + } } +/** + * ephy_tab_get_visibility: + * @tab: an #EphyTab + * + * FIXME: Nobody really knows what this does. Someone must investigate. + * + * Return value; %TRUE if @tab's "visibility" property is set + **/ gboolean ephy_tab_get_visibility (EphyTab *tab) { @@ -544,17 +630,6 @@ ephy_tab_get_visibility (EphyTab *tab) return tab->priv->visibility; } -void -ephy_tab_set_visibility (EphyTab *tab, - gboolean visible) -{ - g_return_if_fail (EPHY_IS_TAB (tab)); - - tab->priv->visibility = visible; - - g_object_notify (G_OBJECT (tab), "visible"); -} - static void ephy_tab_icon_cache_changed_cb (EphyFaviconCache *cache, const char *address, @@ -597,6 +672,14 @@ ephy_tab_set_icon_address (EphyTab *tab, const char *address) g_object_notify (G_OBJECT (tab), "icon"); } +/** + * ephy_tab_get_icon_address: + * @tab: an #EphyTab + * + * Returns a URL which points to @tab's favicon. + * + * Return value: a URL to @tab's favicon + **/ const char * ephy_tab_get_icon_address (EphyTab *tab) { @@ -946,7 +1029,9 @@ ephy_tab_visibility_cb (EphyEmbed *embed, gboolean visibility, gtk_widget_hide (GTK_WIDGET (tab)); } - ephy_tab_set_visibility (tab, visibility); + tab->priv->visibility = visible; + + g_object_notify (G_OBJECT (tab), "visible"); } static void @@ -1257,6 +1342,13 @@ ephy_tab_init (EphyTab *tab) tab, 0); } +/** + * ephy_tab_set_load_percent: + * @tab: an #EphyTab + * @percent: a percentage, from 0 to 100. + * + * Sets the load percentage. This will be displayed in the progressbar. + **/ void ephy_tab_set_load_percent (EphyTab *tab, int percent) { @@ -1270,6 +1362,14 @@ ephy_tab_set_load_percent (EphyTab *tab, int percent) } } +/** + * ephy_tab_get_load_percent: + * @tab: an #EphyTab + * + * Returns the page load percentage (displayed in the progressbar). + * + * Return value: a percentage from 0 to 100 + **/ int ephy_tab_get_load_percent (EphyTab *tab) { @@ -1306,6 +1406,16 @@ ephy_tab_update_navigation_flags (EphyTab *tab, EphyEmbed *embed) } } +/** + * ephy_tab_get_navigation_flags: + * @tab: an #EphyTab + * + * DO NOT USE + * + * Returns @tab's navigation flags. + * + * Return value: @tab's navigation flags + **/ TabNavigationFlags ephy_tab_get_navigation_flags (EphyTab *tab) { @@ -1314,6 +1424,22 @@ ephy_tab_get_navigation_flags (EphyTab *tab) return tab->priv->nav_flags; } +/** + * ephy_tab_get_status_message: + * @tab: an #EphyTab + * + * Returns the message displayed in @tab's #EphyWindow's #EphyStatusbar. If the + * user is hovering the mouse over a hyperlink, this function will return the + * same value as ephy_tab_get_link_message(). Otherwise, it will return a + * network status message, or NULL. + * + * The message returned has a limited lifetime, and so should be copied with + * g_strdup() if it must be stored. + * + * Listen to "notify::message" to be notified when the message property changes. + * + * Return value: The current statusbar message + **/ const char * ephy_tab_get_status_message (EphyTab *tab) { @@ -1404,6 +1530,14 @@ ephy_tab_set_title (EphyTab *tab, EphyEmbed *embed, const char *new_title) g_object_notify (G_OBJECT (tab), "title"); } +/** + * ephy_tab_get_title: + * @tab: an #EphyTab + * + * Returns the title of the web page loaded in @tab. + * + * Return value: @tab's loaded web page's title + **/ const char * ephy_tab_get_title (EphyTab *tab) { @@ -1412,6 +1546,20 @@ ephy_tab_get_title (EphyTab *tab) return tab->priv->title; } +/** + * ephy_tab_get_location: + * @tab: an #EphyTab + * + * Returns the text that @tab's #EphyWindow will display in its location toolbar + * entry when @tab is selected. + * + * This is not guaranteed to be the same as @tab's #EphyEmbed's location, + * available through ephy_embed_get_location(). As the user types a new address + * into the location entry, ephy_tab_get_location()'s returned string will + * change. + * + * Return value: @tab's #EphyWindow's location entry when @tab is selected + **/ const char * ephy_tab_get_location (EphyTab *tab) { @@ -1420,6 +1568,14 @@ ephy_tab_get_location (EphyTab *tab) return tab->priv->address; } +/** + * ephy_tab_set_location: + * @tab: an #EphyTab + * @address: a string (ideally a URL) + * @expire: beats me + * + * DO NOT USE + */ void ephy_tab_set_location (EphyTab *tab, const char *address, @@ -1453,6 +1609,14 @@ ephy_tab_set_security_level (EphyTab *tab, EmbedSecurityLevel level) g_object_notify (G_OBJECT (tab), "security-level"); } +/** + * ephy_tab_get_security_level: + * @tab: an #EphyTab + * + * Returns the security level of the webpage loaded in @tab. + * + * Return value: @tab's loaded page's security level + **/ EmbedSecurityLevel ephy_tab_get_security_level (EphyTab *tab) { @@ -1471,6 +1635,15 @@ ephy_tab_set_zoom (EphyTab *tab, float zoom) g_object_notify (G_OBJECT (tab), "zoom"); } +/** + * ephy_tab_get_zoom: + * @tab: an #EphyTab + * + * Returns the zoom level of the web page loaded in @tab. A return value of + * 1.0 corresponds to 100% zoom (normal size). + * + * Return value: @tab's loaded page's zoom level + **/ float ephy_tab_get_zoom (EphyTab *tab) { @@ -1479,6 +1652,18 @@ ephy_tab_get_zoom (EphyTab *tab) return tab->priv->zoom; } +/** + * ephy_tab_get_action: + * @tab: an #EphyTab + * + * DO NOT USE + * + * Returns the #GtkToggleAction represented by the labelled tab displayed at the + * top of @tab's #EphyWindow when multiple tabs are loaded. Activating this + * action will switch the window to display @tab. + * + * Return value: @tab's #GtkToggleAction + **/ GObject * ephy_tab_get_action (EphyTab *tab) { diff --git a/src/ephy-tab.h b/src/ephy-tab.h index 69408213f..18007e040 100644 --- a/src/ephy-tab.h +++ b/src/ephy-tab.h @@ -36,7 +36,7 @@ G_BEGIN_DECLS #define EPHY_TAB_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), EPHY_TYPE_TAB, EphyTabClass)) typedef struct EphyTabClass EphyTabClass; -typedef struct EphyTab EphyTab; +typedef struct _EphyTab EphyTab; typedef struct EphyTabPrivate EphyTabPrivate; typedef enum @@ -53,7 +53,7 @@ typedef enum TAB_ADDRESS_EXPIRE_CURRENT } TabAddressExpire; -struct EphyTab +struct _EphyTab { GtkBin parent; @@ -111,9 +111,6 @@ const char *ephy_tab_get_status_message (EphyTab *tab); const char *ephy_tab_get_title (EphyTab *tab); -void ephy_tab_set_visibility (EphyTab *tab, - gboolean visible); - gboolean ephy_tab_get_visibility (EphyTab *tab); float ephy_tab_get_zoom (EphyTab *tab); |