Documented EphyTab

7 files changed, 379 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index 67f415b2a..c6fc01bfd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -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);