![]() |
![]() |
![]() |
Epiphany Reference Manual | ![]() |
---|---|---|---|---|
EphyEmbed; EphyEmbedIface; enum EphyEmbedChrome; void ephy_embed_load_url (EphyEmbed *embed, const char *url); void ephy_embed_stop_load (EphyEmbed *embed); void ephy_embed_reload (EphyEmbed *embed, gboolean force); const char* ephy_embed_get_title (EphyEmbed *embed); char* ephy_embed_get_location (EphyEmbed *embed, gboolean toplevel); const char* ephy_embed_get_link_message (EphyEmbed *embed); char* ephy_embed_get_js_status (EphyEmbed *embed); gboolean ephy_embed_can_go_back (EphyEmbed *embed); gboolean ephy_embed_can_go_forward (EphyEmbed *embed); gboolean ephy_embed_can_go_up (EphyEmbed *embed); GSList* ephy_embed_get_go_up_list (EphyEmbed *embed); void ephy_embed_go_back (EphyEmbed *embed); void ephy_embed_go_forward (EphyEmbed *embed); void ephy_embed_go_up (EphyEmbed *embed); void ephy_embed_get_security_level (EphyEmbed *embed, EphyEmbedSecurityLevel *level, char **description); void ephy_embed_set_zoom (EphyEmbed *embed, float zoom); float ephy_embed_get_zoom (EphyEmbed *embed); void ephy_embed_find_set_properties (EphyEmbedFind *find, const char *search_string, gboolean case_sensitive); void ephy_embed_set_encoding (EphyEmbed *embed, const char *encoding); void ephy_embed_print (EphyEmbed *embed); int ephy_embed_print_preview_n_pages (EphyEmbed *embed); void ephy_embed_print_preview_navigate (EphyEmbed *embed, EphyEmbedPrintPreviewNavType type, int page); gboolean ephy_embed_has_modified_forms (EphyEmbed *embed);
"close-request" : Run Last "content-blocked" : Run Last "dom-content-loaded" : Run First "ge-context-menu" : Run Last "ge-document-type" : Run First "ge-dom-mouse-click" : Run Last "ge-dom-mouse-down" : Run Last "ge-favicon" : Run First "ge-feed-link" : Run First "ge-modal-alert" : Run Last "ge-modal-alert-closed" : Run Last "ge-new-window" : Run First "ge-popup-blocked" : Run First "ge-search-key-press" : Run Last "ge-search-link" : Run First "ge-zoom-change" : Run Last "new-document-now" : Run First
Each EphyTab contains an EphyEmbed. An EphyEmbed is an interface; right now it is only implemented by MozillaEmbed, but whenever possible, EphyEmbed's functions should be used instead of their MozillaEmbed equivalents.
EphyEmbed's most important functions can be divided into sets:
The first two sets of functions are self-explanitory.
The session history functions are used to traverse the embedded browser's
history. Each EphyEmbed remembers a history of the web pages it has visited.
There can be a maximum limit, however; for MozillaEmbed, this limit is
determined by Mozilla's browser.sessionhistory.max_entries preference. Because
of this limit, ephy_embed_shistory_n_items()
will not necessarily return the
number of web pages visited in the embed's lifetime; likewise,
ephy_embed_shistory_go_nth()
will not always return to the user's home page
when called with a 0 argument.
typedef struct { GTypeInterface base_iface; int (* context_menu) (EphyEmbed *embed, EphyEmbedEvent *event); void (* favicon) (EphyEmbed *embed, const char *location); void (* feed_link) (EphyEmbed *embed, const char *type, const char *title, const char *address); void (* search_link) (EphyEmbed *embed, const char *type, const char *title, const char *address); gboolean (* dom_mouse_click) (EphyEmbed *embed, EphyEmbedEvent *event); gboolean (* dom_mouse_down) (EphyEmbed *embed, EphyEmbedEvent *event); void (* dom_content_loaded) (EphyEmbed *embed, gpointer event); void (* popup_blocked) (EphyEmbed *embed, const char *address, const char *target, const char *features); void (* zoom_change) (EphyEmbed *embed, float new_zoom); void (* content_blocked) (EphyEmbed *embed, const char *uri); gboolean (* modal_alert) (EphyEmbed *embed); void (* modal_alert_closed) (EphyEmbed *embed); void (* document_type) (EphyEmbed *embed, EphyEmbedDocumentType type); void (* new_window) (EphyEmbed *embed, EphyEmbed *new_embed); gboolean (* search_key_press) (EphyEmbed *embed, GdkEventKey *event); gboolean (* close_request) (EphyEmbed *embed); void (* new_document_now) (EphyEmbed *embed, const char *uri); /* Methods */ void (* load_url) (EphyEmbed *embed, const char *url); void (* load) (EphyEmbed *embed, const char *url, EphyEmbedLoadFlags flags, EphyEmbed *referring_embed); void (* stop_load) (EphyEmbed *embed); void (* reload) (EphyEmbed *embed, gboolean force); gboolean (* can_go_back) (EphyEmbed *embed); gboolean (* can_go_forward) (EphyEmbed *embed); gboolean (* can_go_up) (EphyEmbed *embed); GSList * (* get_go_up_list) (EphyEmbed *embed); void (* go_back) (EphyEmbed *embed); void (* go_forward) (EphyEmbed *embed); void (* go_up) (EphyEmbed *embed); const char * (* get_title) (EphyEmbed *embed); char * (* get_location) (EphyEmbed *embed, gboolean toplevel); const char * (* get_link_message) (EphyEmbed *embed); char * (* get_js_status) (EphyEmbed *embed); void (* shistory_copy) (EphyEmbed *source, EphyEmbed *dest, gboolean copy_back, gboolean copy_forward, gboolean copy_current); void (* get_security_level) (EphyEmbed *embed, EphyEmbedSecurityLevel *level, char **description); void (* show_page_certificate) (EphyEmbed *embed); void (* set_zoom) (EphyEmbed *embed, float zoom); float (* get_zoom) (EphyEmbed *embed); void (* scroll_lines) (EphyEmbed *embed, int num_lines); void (* scroll_pages) (EphyEmbed *embed, int num_pages); void (* scroll_pixels) (EphyEmbed *embed, int dx, int dy); char * (* get_encoding) (EphyEmbed *embed); gboolean (* has_automatic_encoding) (EphyEmbed *embed); void (* set_encoding) (EphyEmbed *embed, const char *encoding); void (* print) (EphyEmbed *embed); void (* set_print_preview_mode) (EphyEmbed *embed, gboolean mode); int (* print_preview_n_pages) (EphyEmbed *embed); void (* print_preview_navigate) (EphyEmbed *embed, EphyEmbedPrintPreviewNavType type, int page); gboolean (* has_modified_forms) (EphyEmbed *embed); void (* close) (EphyEmbed *embed); EphyEmbedDocumentType (* get_document_type) (EphyEmbed *embed); int (* get_load_percent) (EphyEmbed *embed); gboolean (* get_load_status) (EphyEmbed *embed); EphyEmbedNavigationFlags (* get_navigation_flags) (EphyEmbed *embed); const char * (* get_typed_address) (EphyEmbed *embed); void (* set_typed_address) (EphyEmbed *embed, const char *address, EphyEmbedAddressExpire expire); const char * (* get_address) (EphyEmbed *embed); const char * (* get_status_message) (EphyEmbed *embed); GdkPixbuf * (* get_icon) (EphyEmbed *embed); const char * (* get_icon_address) (EphyEmbed *embed); gboolean (* get_is_blank) (EphyEmbed *embed); const char * (* get_loading_title) (EphyEmbed *embed); gboolean (* get_visibility) (EphyEmbed *embed); GList * (* get_backward_history) (EphyEmbed *embed); GList * (* get_forward_history) (EphyEmbed *embed); EphyHistoryItem * (* get_next_history_item) (EphyEmbed *embed); EphyHistoryItem * (* get_previous_history_item) (EphyEmbed *embed); void (* go_to_history_item) (EphyEmbed *embed, EphyHistoryItem *history_item); } EphyEmbedIface;
typedef enum { EPHY_EMBED_CHROME_MENUBAR = 1 << 0, EPHY_EMBED_CHROME_TOOLBAR = 1 << 1, EPHY_EMBED_CHROME_STATUSBAR = 1 << 2, EPHY_EMBED_CHROME_BOOKMARKSBAR = 1 << 3 } EphyEmbedChrome;
Determines which aspects of the user interface should be displayed. Most of the
time, an EphyEmbed's chrome will simply be EPHY_EMBED_CHROME_DEFAULT
. However,
windows opened with JavaScript often use a nonstandard chrome.
TRUE for the EphyEmbed's containing EphyWindow
to display its menubar.
|
|
TRUE for the EphyEmbed's containing EphyWindow
to display its toolbars.
|
|
TRUE for the EphyEmbed's containing EphyWindow
to display its statusbar.
|
|
void ephy_embed_load_url (EphyEmbed *embed, const char *url);
Loads a new web page in embed
.
|
an EphyEmbed |
|
a URL |
void ephy_embed_stop_load (EphyEmbed *embed);
If embed
is loading, stops it from continuing.
|
an EphyEmbed |
void ephy_embed_reload (EphyEmbed *embed, gboolean force);
Reloads the web page being displayed in embed
.
If force
is TRUE
, cache and proxy will be bypassed when
reloading the page.
|
an EphyEmbed |
|
TRUE to bypass cache
|
const char* ephy_embed_get_title (EphyEmbed *embed);
|
an EphyEmbed |
Returns : |
the title of the web page displayed in embed
|
char* ephy_embed_get_location (EphyEmbed *embed, gboolean toplevel);
Returns the URL of the web page displayed in embed
.
If the web page contains frames, toplevel
will determine which location to
retrieve. If toplevel
is TRUE
, the return value will be the location of the
frameset document. If toplevel
is FALSE
, the return value will be the
location of the currently-focused frame.
|
an EphyEmbed |
|
FALSE to return the location of the focused frame only
|
Returns : |
the URL of the web page displayed in embed
|
const char* ephy_embed_get_link_message (EphyEmbed *embed);
When the user is hovering the mouse over a hyperlink, returns the URL of the hyperlink.
|
an EphyEmbed |
Returns : |
the URL of the link over which the mouse is hovering |
char* ephy_embed_get_js_status (EphyEmbed *embed);
Displays the message JavaScript is attempting to display in the statusbar.
Note that Epiphany does not display JavaScript statusbar messages.
|
an EphyEmbed |
Returns : |
a message from JavaScript meant to be displayed in the statusbar |
gboolean ephy_embed_can_go_back (EphyEmbed *embed);
|
an EphyEmbed |
Returns : |
TRUE if embed can return to a previously-visited location
|
gboolean ephy_embed_can_go_forward (EphyEmbed *embed);
|
an EphyEmbed |
Returns : |
TRUE if embed has gone back, and can thus go forward again
|
gboolean ephy_embed_can_go_up (EphyEmbed *embed);
Returns whether embed
can travel to a higher-level directory on the server.
For example, for http://www.example.com/subdir/index.html, returns TRUE
; for
http://www.example.com/index.html, returns FALSE
.
|
an EphyEmbed |
Returns : |
TRUE if embed can browse to a higher-level directory
|
GSList* ephy_embed_get_go_up_list (EphyEmbed *embed);
Returns a list of (char
*) URLs to higher-level directories on the same
server, in order of deepest to shallowest. For example, given
"http://www.example.com/dir/subdir/file.html", will return a list containing
"http://www.example.com/dir/subdir/", "http://www.example.com/dir/" and
"http://www.example.com/".
|
an EphyEmbed |
Returns : |
a list of URLs higher up in embed 's web page's directory
hierarchy
|
void ephy_embed_go_back (EphyEmbed *embed);
Causes embed
to return to the previously-visited web page.
|
an EphyEmbed |
void ephy_embed_go_forward (EphyEmbed *embed);
If embed
has returned to a previously-visited web page, proceed forward to
the next page.
|
an EphyEmbed |
void ephy_embed_go_up (EphyEmbed *embed);
Moves embed
one level up in its web page's directory hierarchy.
|
an EphyEmbed |
void ephy_embed_get_security_level (EphyEmbed *embed, EphyEmbedSecurityLevel *level, char **description);
Fetches the EphyEmbedSecurityLevel and a newly-allocated string description
of the security state of embed
.
|
an EphyEmbed |
|
return value of security level |
|
return value of the description of the security level |
void ephy_embed_set_zoom (EphyEmbed *embed, float zoom);
Sets the zoom level for a web page.
Zoom is normally controlled by the Epiphany itself and remembered in Epiphany's history data. Be very careful not to break this behavior if using this function; better yet, don't use this function at all.
|
an EphyEmbed |
|
the new zoom level |
float ephy_embed_get_zoom (EphyEmbed *embed);
Returns the zoom level of embed
. A zoom of 1.0 corresponds to 100% (normal
size).
|
an EphyEmbed |
Returns : |
the zoom level of embed
|
void ephy_embed_find_set_properties (EphyEmbedFind *find, const char *search_string, gboolean case_sensitive);
Sets the properties of find
|
an EphyEmbedFind |
|
|
|
TRUE for "case sensitive" to be set
|
void ephy_embed_set_encoding (EphyEmbed *embed, const char *encoding);
Sets embed
's character encoding to encoding
. These cryptic encoding
strings are listed in embed/ephy-encodings.c
.
Pass an empty string (not NULL) in encoding
to reset embed
to use the
document-specified encoding.
|
an EphyEmbed |
|
the desired encoding |
void ephy_embed_print (EphyEmbed *embed);
Sends a document to the printer.
|
an EphyEmbed |
int ephy_embed_print_preview_n_pages (EphyEmbed *embed);
Returns the number of pages which would appear in embed
's loaded document
if it were to be printed.
|
an EphyEmbed |
Returns : |
the number of pages in embed 's loaded document
|
void ephy_embed_print_preview_navigate (EphyEmbed *embed, EphyEmbedPrintPreviewNavType type, int page);
Navigates embed
's print preview.
|
an EphyEmbed |
|
an EphyPrintPreviewNavType which determines where to navigate |
|
if type is EPHY_EMBED_PRINTPREVIEW_GOTO_PAGENUM , the desired page number
|
"close-request"
signalgboolean user_function (EphyEmbed *embed, gpointer user_data) : Run Last
The ::close signal is emitted when the embed request closing.
Return TRUE
to prevent closing. You HAVE to process removal of the embed
as soon as possible after that.
|
|
|
user data set when the signal handler was connected. |
"content-blocked"
signalvoid user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run Last
The ::content-blocked signal is emitted when an url has been blocked.
|
|
|
blocked URI |
|
user data set when the signal handler was connected. |
"dom-content-loaded"
signalvoid user_function (EphyEmbed *embed, gpointer arg1, gpointer user_data) : Run First
The ::dom-content-loaded signal is emitted when the document has been loaded (excluding images and other loads initiated by this document). That's true also for frameset and all the frames within it.
|
|
|
user data set when the signal handler was connected. |
"ge-context-menu"
signalgboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run Last
The ::ge_context_menu signal is emitted when a context menu is to be
displayed. This will usually happen when the user right-clicks on a part of
embed
.
|
|
|
the EphyEmbedEvent which triggered this signal |
|
user data set when the signal handler was connected. |
"ge-document-type"
signalvoid user_function (EphyEmbed *embed, EphyEmbedDocumentType type, gpointer user_data) : Run First
The ::ge-document-type signal is emitted when embed
determines the type of its document.
|
|
|
the new document type |
|
user data set when the signal handler was connected. |
"ge-dom-mouse-click"
signalgboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run Last
The ::ge_dom_mouse_click signal is emitted when the user clicks in embed
.
|
|
|
the EphyEmbedEvent which triggered this signal |
|
user data set when the signal handler was connected. |
"ge-dom-mouse-down"
signalgboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run Last
The ::ge_dom_mouse_down signal is emitted when the user depresses a mouse button.
|
|
|
the EphyEmbedEvent which triggered this signal |
|
user data set when the signal handler was connected. |
"ge-favicon"
signalvoid user_function (EphyEmbed *embed, gchar *address, gpointer user_data) : Run First
The ::ge_favicon signal is emitted when embed
discovers that a favourite
icon (favicon) is available for the site it is visiting.
|
|
|
the URL to embed 's web site's favicon
|
|
user data set when the signal handler was connected. |
"ge-feed-link"
signalvoid user_function (EphyEmbed *embed, gchar *type, gchar *title, gchar *address, gpointer user_data) : Run First
The ::ge_rss signal is emitted when embed
discovers that a news feed
is available for the site it is visiting.
|
|
|
the mime-type of the news feed |
|
the title of the news feed |
|
the URL to embed 's web site's news feed
|
|
user data set when the signal handler was connected. |
"ge-modal-alert"
signalgboolean user_function (EphyEmbed *embed, gpointer user_data) : Run Last
The ::ge-modal-alert signal is emitted when a DOM event will open a modal alert.
Return TRUE
to prevent the dialog from being opened.
|
|
|
user data set when the signal handler was connected. |
"ge-modal-alert-closed"
signalvoid user_function (EphyEmbed *embed, gpointer user_data) : Run Last
The ::ge-modal-alert-closed signal is emitted when a modal alert put up by a DOM event was closed.
|
|
|
user data set when the signal handler was connected. |
"ge-new-window"
signalvoid user_function (EphyEmbed *embed, GtkWidget *new_embed, gpointer user_data) : Run First
The ::ge_new_window signal is emitted after a new window has been opened by the embed. For example, when a JavaScript popup window is opened.
|
|
|
the newly opened EphyEmbed |
|
user data set when the signal handler was connected. |
"ge-popup-blocked"
signalvoid user_function (EphyEmbed *embed, gchar *address, gchar *target, gchar *features, gpointer user_data) : Run First
The ::ge_popup_blocked signal is emitted when the viewed web page requests
a popup window (with javascript:open()
) but popup windows are not allowed.
|
|
|
The requested URL |
|
The requested window name, e.g. "_blank" |
|
The requested features: for example, "height=400,width=200" |
|
user data set when the signal handler was connected. |
"ge-search-key-press"
signalgboolean user_function (EphyEmbed *embed, GdkEvent *event, gpointer user_data) : Run Last
The ::ge-search-key-press signal is emitted for keypresses which should be used for find implementations.
|
|
|
the GdkEventKey which triggered this signal |
|
user data set when the signal handler was connected. |
"ge-search-link"
signalvoid user_function (EphyEmbed *embed, gchar *type, gchar *title, gchar *address, gpointer user_data) : Run First
The ::ge_rss signal is emitted when embed
discovers that a search
description is available for the site it is visiting.
|
|
|
the mime-type of the search description |
|
the title of the news feed |
|
the URL to embed 's web site's search description
|
|
user data set when the signal handler was connected. |
"ge-zoom-change"
signalvoid user_function (EphyEmbed *embed, gfloat zoom, gpointer user_data) : Run Last
The ::ge_zoom_change signal is emitted when embed
's zoom changes. This can
be manual (the user modified the zoom level) or automatic (embed
's zoom is
automatically changed when browsing to a new site for which the user
previously specified a zoom level).
A zoom
value of 1.0 indicates 100% (normal zoom).
|
|
|
embed 's new zoom level
|
|
user data set when the signal handler was connected. |
"new-document-now"
signalvoid user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run First
The ::new-document-now signal is emitted when a new page content is being loaded into the browser. It's a good place to do view related changes, for example to restore the zoom level of a page or to set an user style sheet.
|
|
|
URI of the new content |
|
user data set when the signal handler was connected. |
Using EphyEmbed instead of MozillaEmbed is good practice. However, using a MozillaEmbed or even a GtkMozEmbed may be necessary in certain cases (this can be done by casting).