aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--ChangeLog19
-rw-r--r--doc/reference/Makefile.am1
-rw-r--r--doc/reference/epiphany-docs.sgml1
-rw-r--r--doc/reference/epiphany-sections.txt19
-rw-r--r--doc/reference/tmpl/ephy-tab.sgml139
-rw-r--r--src/ephy-tab.c213
-rw-r--r--src/ephy-tab.h7
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);