![]() | ![]() | ![]() | Epiphany Reference Manual | ![]() |
---|
EphyEmbed — An interface to the widget displaying web pages
struct EphyEmbed; struct EphyEmbedIface; enum EmbedState; enum EphyEmbedChrome; enum EmbedPrintPreviewNavType; enum EmbedSecurityLevel; 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, EmbedSecurityLevel *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 (EphyEmbed *embed, const char *search_string, gboolean case_sensitive, gboolean wrap_around); gboolean ephy_embed_find_next (EphyEmbed *embed, gboolean backwards); 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, EmbedPrintPreviewNavType type, int page); void ephy_embed_activate (EphyEmbed *embed); gboolean ephy_embed_has_modified_forms (EphyEmbed *embed);
"ge-content-change" void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data); "ge-context-menu" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data); "ge-dom-mouse-click" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data); "ge-dom-mouse-down" gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data); "ge-favicon" void user_function (EphyEmbed *embed, gchar *address, gpointer user_data); "ge-location" void user_function (EphyEmbed *embed, gchar *address, gpointer user_data); "ge-modal-alert" gboolean user_function (EphyEmbed *embed, gpointer user_data); "ge-modal-alert-closed" void user_function (EphyEmbed *embed, gpointer user_data); "ge-net-state" void user_function (EphyEmbed *embed, gchar *uri, gint state, gpointer user_data); "ge-new-window" void user_function (EphyEmbed *embed, gpointer new_embed, gint mask, gpointer user_data); "ge-popup-blocked" void user_function (EphyEmbed *embed, gpointer address, gpointer features, gpointer user_data); "ge-security-change" void user_function (EphyEmbed *embed, gint level, gpointer user_data); "ge-zoom-change" void user_function (EphyEmbed *embed, gfloat zoom, gpointer user_data);
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.
struct EphyEmbedIface { 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 (* location) (EphyEmbed *embed, const char *location); void (* net_state) (EphyEmbed *embed, const char *uri, EmbedState state); void (* new_window) (EphyEmbed *embed, EphyEmbed **new_embed, EphyEmbedChrome chromemask); gboolean (* dom_mouse_click) (EphyEmbed *embed, EphyEmbedEvent *event); gboolean (* dom_mouse_down) (EphyEmbed *embed, EphyEmbedEvent *event); void (* popup_blocked) (EphyEmbed *embed, const char *address, const char *features); void (* security_change) (EphyEmbed *embed, EmbedSecurityLevel level); void (* zoom_change) (EphyEmbed *embed, float new_zoom); void (* content_change) (EphyEmbed *embed, const char *uri); /* 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 (* get_security_level) (EphyEmbed *embed, EmbedSecurityLevel *level, char **description); void (* set_zoom) (EphyEmbed *embed, float zoom); float (* get_zoom) (EphyEmbed *embed); void (* find_set_properties) (EphyEmbed *embed, const char *search_string, gboolean case_sensitive, gboolean wrap_around); gboolean (* find_next) (EphyEmbed *embed, gboolean backwards); 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, EmbedPrintPreviewNavType type, int page); void (* activate) (EphyEmbed *embed); gboolean (* has_modified_forms) (EphyEmbed *embed); /* added at the end to preserve ABI */ /* Signals */ gboolean (* modal_alert) (EphyEmbed *embed); void (* modal_alert_closed) (EphyEmbed *embed); /* Methods */ void (* show_page_certificate) (EphyEmbed *embed); };
typedef enum { EMBED_STATE_UNKNOWN = 0, EMBED_STATE_START = 1 << 0, EMBED_STATE_REDIRECTING = 1 << 1, EMBED_STATE_TRANSFERRING = 1 << 2, EMBED_STATE_NEGOTIATING = 1 << 3, EMBED_STATE_STOP = 1 << 4, EMBED_STATE_IS_REQUEST = 1 << 5, EMBED_STATE_IS_DOCUMENT = 1 << 6, EMBED_STATE_IS_NETWORK = 1 << 7, EMBED_STATE_IS_WINDOW = 1 << 8 } EmbedState;
Represents the state of an EphyEmbed with regards to networking negotiations.
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 |
typedef enum { PRINTPREVIEW_GOTO_PAGENUM = 0, PRINTPREVIEW_PREV_PAGE = 1, PRINTPREVIEW_NEXT_PAGE = 2, PRINTPREVIEW_HOME = 3, PRINTPREVIEW_END = 4 } EmbedPrintPreviewNavType;
Specifies the action to perform in ephy_embed_print_preview_navigate().
typedef enum { STATE_IS_UNKNOWN, STATE_IS_INSECURE, STATE_IS_BROKEN, STATE_IS_SECURE_MED, STATE_IS_SECURE_LOW, STATE_IS_SECURE_HIGH } EmbedSecurityLevel;
Represents the security status of an EphyEmbed. For example, a page with an invalid SSL certificate will have an EmbedSecurityLevel of STATE_IS_BROKEN.
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.
embed : | an EphyEmbed |
force : | TRUE to bypass cache |
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.
embed : | an EphyEmbed |
toplevel : | FALSE to return the location of the focused frame only |
Returns : | the URL of the web page displayed in embed |
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_back (EphyEmbed *embed);
embed : | an EphyEmbed |
Returns : | TRUE if embed can return to a previously-visited location |
gboolean ephy_embed_can_go_forward (EphyEmbed *embed);
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.
embed : | 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/".
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.
embed : | an EphyEmbed |
nth : | index of the desired page in embed's browser history |
is_relative : | if TRUE, add embed's current history position to nth |
url : | returned value of the history entry's URL |
title : | returned value of the history entry's title |
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, EmbedSecurityLevel *level, char **description);
Fetches the EmbedSecurityLevel 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 (EphyEmbed *embed, const char *search_string, gboolean case_sensitive, gboolean wrap_around);
Sets the properties of embed's "Find" dialog.
embed : | an EphyEmbed |
search_string : | the desired search string |
case_sensitive : | TRUE for "case sensitive" to be set |
wrap_around : | TRUE for "wrap around" to be set |
gboolean ephy_embed_find_next (EphyEmbed *embed, gboolean backwards);
Equivalent to pressing "Next" in embed's Find dialog.
embed : | an EphyEmbed |
backwards : | FALSE to search forwards in the document |
Returns : | TRUE if a next match was found |
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, EmbedPrintPreviewNavType type, int page);
Navigates embed's print preview.
embed : | an EphyEmbed |
type : | an EphyPrintPreviewNavType which determines where to navigate |
page : | if type is PRINTPREVIEW_GOTO_PAGENUM, the desired page number |
void ephy_embed_activate (EphyEmbed *embed);
Gives focus to embed (i.e., Mozilla).
embed : | an EphyEmbed |
void user_function (EphyEmbed *embed, gchar *uri, gpointer user_data);
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);
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. |
gboolean user_function (EphyEmbed *embed, GObject *event, gpointer user_data);
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);
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);
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 *address, gpointer user_data);
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);
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);
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, gint state, gpointer user_data);
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, gpointer new_embed, gint mask, gpointer user_data);
The ::ge_new_window signal is emitted when a new window has been opened by the embed. For example, when a JavaScript popup window is opened.
embed : | |
new_embed : | a newly-generated child EphyEmbed |
mask : | new_embed's EphyChromeMask |
user_data : | user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gpointer address, gpointer features, gpointer user_data);
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 |
features : | The requested features: for example, "height=400,width=200" |
user_data : | user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gint level, gpointer user_data);
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 EmbedSecurityLevel |
user_data : | user data set when the signal handler was connected. |
void user_function (EphyEmbed *embed, gfloat zoom, gpointer user_data);
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).
<< EphyTab | EphyCommandManager >> |