![]() |
![]() |
![]() |
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); char* ephy_embed_get_title (EphyEmbed *embed); char* ephy_embed_get_location (EphyEmbed *embed, gboolean toplevel); 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); int ephy_embed_shistory_n_items (EphyEmbed *embed); void ephy_embed_shistory_get_nth (EphyEmbed *embed, int nth, gboolean is_relative, char **url, char **title); int ephy_embed_shistory_get_pos (EphyEmbed *embed); void ephy_embed_shistory_go_nth (EphyEmbed *embed, int nth); 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" gboolean user_function (EphyEmbed *embed, gpointer user_data) : Run last "content-blocked" void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run last "dom-content-loaded" void user_function (EphyEmbed *embed, gpointer arg1, gpointer user_data) : Run first "ge-content-change" void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run first "ge-context-menu" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run last "ge-document-type" void user_function (EphyEmbed *embed, EphyEmbedDocumentType *type, gpointer user_data) : Run first "ge-dom-mouse-click" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run last "ge-dom-mouse-down" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data) : Run last "ge-favicon" void user_function (EphyEmbed *embed, gchar *address, gpointer user_data) : Run first "ge-feed-link" void user_function (EphyEmbed *embed, gchar *type, gchar *title, gchar *address, gpointer user_data) : Run first "ge-location" void user_function (EphyEmbed *embed, gchar *address, gpointer user_data) : Run first "ge-modal-alert" gboolean user_function (EphyEmbed *embed, gpointer user_data) : Run last "ge-modal-alert-closed" void user_function (EphyEmbed *embed, gpointer user_data) : Run last "ge-net-state" void user_function (EphyEmbed *embed, gchar *uri, EphyEmbedNetState *state, gpointer user_data) : Run first "ge-new-window" void user_function (EphyEmbed *embed, GtkWidget *new_embed, gpointer user_data) : Run first "ge-popup-blocked" void user_function (EphyEmbed *embed, gchar *address, gchar *target, gchar *features, gpointer user_data) : Run first "ge-search-key-press" gboolean user_function (EphyEmbed *embed, GdkEvent *event, gpointer user_data) : Run last "ge-security-change" void user_function (EphyEmbed *embed, EphyEmbedSecurityLevel *level, gpointer user_data) : Run last "ge-zoom-change" void user_function (EphyEmbed *embed, gfloat zoom, gpointer user_data) : Run last
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; /* Signals that we inherit from gtkmozembed * * void (* net_stop) (GtkMozEmbed *embed); * void (* title) (EphyEmbed *embed); * void (* visibility) (EphyEmbed *embed, * gboolean visibility); * void (* destroy_brsr) (EphyEmbed *embed); * void (* size_to) (EphyEmbed *embed, * int width, * int height); * gint (* open_uri) (EphyEmbed *embed, * const char *url); */ 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 (* location) (EphyEmbed *embed, const char *location); void (* net_state) (EphyEmbed *embed, const char *uri, EphyEmbedNetState state); 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 (* security_change) (EphyEmbed *embed, EphyEmbedSecurityLevel level); void (* zoom_change) (EphyEmbed *embed, float new_zoom); void (* content_change) (EphyEmbed *embed, const char *uri); 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); /* Methods */ void (* load_url) (EphyEmbed *embed, const char *url); 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); char * (* get_title) (EphyEmbed *embed); char * (* get_location) (EphyEmbed *embed, gboolean toplevel); char * (* get_link_message) (EphyEmbed *embed); char * (* get_js_status) (EphyEmbed *embed); int (* shistory_n_items) (EphyEmbed *embed); void (* shistory_get_nth) (EphyEmbed *embed, int nth, gboolean is_relative, char **url, char **title); int (* shistory_get_pos) (EphyEmbed *embed); void (* shistory_go_nth) (EphyEmbed *embed, int nth); 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); } 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.
EPHY_EMBED_CHROME_MENUBAR |
TRUE for the EphyEmbed's containing EphyWindow
to display its menubar.
|
EPHY_EMBED_CHROME_TOOLBAR |
TRUE for the EphyEmbed's containing EphyWindow
to display its toolbars.
|
EPHY_EMBED_CHROME_STATUSBAR |
TRUE for the EphyEmbed's containing EphyWindow
to display its statusbar.
|
EPHY_EMBED_CHROME_BOOKMARKSBAR |
void ephy_embed_load_url (EphyEmbed *embed, const char *url);
Loads a new web page in embed
.
embed : |
an EphyEmbed |
url : |
a URL |
void ephy_embed_stop_load (EphyEmbed *embed);
If embed
is loading, stops it from continuing.
embed : |
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.
char* ephy_embed_get_title (EphyEmbed *embed);
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.
char* ephy_embed_get_link_message (EphyEmbed *embed);
When the user is hovering the mouse over a hyperlink, returns the URL of the hyperlink.
embed : |
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.
embed : |
an EphyEmbed |
Returns : | a message from JavaScript meant to be displayed in the statusbar |
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
.
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/".
embed : |
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.
embed : |
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.
embed : |
an EphyEmbed |
void ephy_embed_go_up (EphyEmbed *embed);
Moves embed
one level up in its web page's directory hierarchy.
embed : |
an EphyEmbed |
int ephy_embed_shistory_n_items (EphyEmbed *embed);
Returns the number of items in embed
's history. In other words, returns the
number of pages embed
has visited.
The number is upper-bound by Mozilla's browser.sessionhistory.max_entries preference.
embed : |
an EphyEmbed |
Returns : | the number of items in embed 's history
|
void ephy_embed_shistory_get_nth (EphyEmbed *embed, int nth, gboolean is_relative, char **url, char **title);
Fetches the url
and title
of the nth
item in embed
's session history.
If is_relative
is TRUE
, nth
is an offset from the browser's current
history position. For example, calling this function with is_relative
TRUE
and nth
0
will return the URL and title of the current page.
int ephy_embed_shistory_get_pos (EphyEmbed *embed);
Returns embed
's current position in its history. If the user never uses the
"Back" button, this number will be the same as the return value of
ephy_embed_shistory_n_items()
.
embed : |
an EphyEmbed |
Returns : | embed 's current position in its history
|
void ephy_embed_shistory_go_nth (EphyEmbed *embed, int nth);
Opens the webpage at location nth
in embed
's history.
embed : |
an EphyEmbed |
nth : |
desired history index |
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
.
embed : |
an EphyEmbed |
level : |
return value of security level |
description : |
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.
embed : |
an EphyEmbed |
zoom : |
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).
embed : |
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
find : |
an EphyEmbedFind |
search_string : |
|
case_sensitive : |
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.
embed : |
an EphyEmbed |
encoding : |
the desired encoding |
void ephy_embed_print (EphyEmbed *embed);
Sends a document to the printer.
embed : |
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.
embed : |
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.
embed : |
an EphyEmbed |
type : |
an EphyPrintPreviewNavType which determines where to navigate |
page : |
if type is EPHY_EMBED_PRINTPREVIEW_GOTO_PAGENUM , the desired page number
|
gboolean 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.
embed : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run last
The ::content-blocked signal is emitted when an url has been blocked.
embed : |
|
uri : |
blocked URI |
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data) : Run first
The ::ge_content_change signal is emitted when a new page content is being loadedinto 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.
embed : |
|
uri : |
URI of the new content |
user_data : |
user data set when the signal handler was connected. |
gboolean 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
.
embed : |
|
event : |
the EphyEmbedEvent which triggered this signal |
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
type : |
the new document type |
user_data : |
user data set when the signal handler was connected. |
gboolean 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
.
embed : |
|
event : |
the EphyEmbedEvent which triggered this signal |
user_data : |
user data set when the signal handler was connected. |
gboolean 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.
embed : |
|
event : |
the EphyEmbedEvent which triggered this signal |
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
address : |
the URL to embed 's web site's favicon
|
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
type : |
the mime-type of the news feed |
title : |
the title of the news feed |
address : |
the URL to embed 's web site's news feed
|
user_data : |
user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gchar *address, gpointer user_data) : Run first
The ::ge_location signal is emitted when embed
begins to load a new web
page. For example, if the user clicks on a link or enters an address or if
the previous web page had JavaScript or a META REFRESH tag.
The ::ge_location signal will be emitted even when embed
is simply
refreshing the same web page.
embed : |
|
address : |
the new URL embed is visiting
|
user_data : |
user data set when the signal handler was connected. |
gboolean 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.
embed : |
|
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
user_data : |
user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gchar *uri, EphyEmbedNetState *state, gpointer user_data) : Run first
The ::ge_net_state signal is emitted when embed
's network negotiation state
changes. For example, this will indicate when page loading is complete or
cancelled.
embed : |
|
uri : |
the URI embed is loading
|
state : |
the EmbedState of embed
|
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
new_embed : |
the newly opened EphyEmbed |
user_data : |
user data set when the signal handler was connected. |
void 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.
embed : |
|
address : |
The requested URL |
target : |
The requested window name, e.g. "_blank" |
features : |
The requested features: for example, "height=400,width=200" |
user_data : |
user data set when the signal handler was connected. |
gboolean 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.
embed : |
|
event : |
the GdkEventKey which triggered this signal |
user_data : |
user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, EphyEmbedSecurityLevel *level, gpointer user_data) : Run last
The ::ge_security_change signal is emitted when the security level of embed
changes. For example, this will happen when the user browses from an
insecure website to an SSL-secured one.
embed : |
|
level : |
embed 's new EphyEmbedSecurityLevel
|
user_data : |
user data set when the signal handler was connected. |
void 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 : |
|
zoom : |
embed 's new zoom level
|
user_data : |
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).