EphyEmbed

EphyEmbed — An interface to the widget displaying web pages

Synopsis

                    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);

Object Hierarchy

  GInterface
   +----EphyEmbed

Signals

  "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

Description

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:

  • Functions which affect navigation
  • Functions which return information about the displayed web page
  • Functions which manipulate the session history

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.

Details

EphyEmbed

typedef struct _EphyEmbed EphyEmbed;


EphyEmbedIface

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;


enum EphyEmbedChrome

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


ephy_embed_load_url ()

void                ephy_embed_load_url                 (EphyEmbed *embed,
                                                         const char *url);

Loads a new web page in embed.

embed :

an EphyEmbed

url :

a URL

ephy_embed_stop_load ()

void                ephy_embed_stop_load                (EphyEmbed *embed);

If embed is loading, stops it from continuing.

embed :

an EphyEmbed

ephy_embed_reload ()

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

ephy_embed_get_title ()

const char*         ephy_embed_get_title                (EphyEmbed *embed);

embed :

an EphyEmbed

Returns :

the title of the web page displayed in embed

ephy_embed_get_location ()

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

ephy_embed_get_link_message ()

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.

embed :

an EphyEmbed

Returns :

the URL of the link over which the mouse is hovering

ephy_embed_get_js_status ()

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

ephy_embed_can_go_back ()

gboolean            ephy_embed_can_go_back              (EphyEmbed *embed);

embed :

an EphyEmbed

Returns :

TRUE if embed can return to a previously-visited location

ephy_embed_can_go_forward ()

gboolean            ephy_embed_can_go_forward           (EphyEmbed *embed);

embed :

an EphyEmbed

Returns :

TRUE if embed has gone back, and can thus go forward again

ephy_embed_can_go_up ()

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

ephy_embed_get_go_up_list ()

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

ephy_embed_go_back ()

void                ephy_embed_go_back                  (EphyEmbed *embed);

Causes embed to return to the previously-visited web page.

embed :

an EphyEmbed

ephy_embed_go_forward ()

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

ephy_embed_go_up ()

void                ephy_embed_go_up                    (EphyEmbed *embed);

Moves embed one level up in its web page's directory hierarchy.

embed :

an EphyEmbed

ephy_embed_get_security_level ()

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

ephy_embed_set_zoom ()

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

ephy_embed_get_zoom ()

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

ephy_embed_find_set_properties ()

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

ephy_embed_set_encoding ()

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

ephy_embed_print ()

void                ephy_embed_print                    (EphyEmbed *embed);

Sends a document to the printer.

embed :

an EphyEmbed

ephy_embed_print_preview_n_pages ()

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

ephy_embed_print_preview_navigate ()

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

ephy_embed_has_modified_forms ()

gboolean            ephy_embed_has_modified_forms       (EphyEmbed *embed);

Returns TRUE if the user has modified <input> or <textarea> values in embed's loaded document.

embed :

an EphyEmbed

Returns :

TRUE if embed has user-modified forms

Signal Details

The "close-request" signal

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.

The "content-blocked" signal

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.

The "dom-content-loaded" signal

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.

The "ge-context-menu" signal

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.

The "ge-document-type" signal

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.

The "ge-dom-mouse-click" signal

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.

The "ge-dom-mouse-down" signal

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.

The "ge-favicon" signal

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.

The "ge-feed-link" signal

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.

The "ge-modal-alert" signal

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.

The "ge-modal-alert-closed" signal

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.

The "ge-new-window" signal

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.

The "ge-popup-blocked" signal

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.

The "ge-search-key-press" signal

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.

The "ge-search-link" signal

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 search description is available for the site it is visiting.

embed :

type :

the mime-type of the search description

title :

the title of the news feed

address :

the URL to embed's web site's search description

user_data :

user data set when the signal handler was connected.

The "ge-zoom-change" signal

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.

The "new-document-now" signal

void                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.

embed :

uri :

URI of the new content

user_data :

user data set when the signal handler was connected.

See Also

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).