EphyEmbed

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

## Object Hierarchy

      GInterface
       +----EphyEmbed

## Signals

    "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-search-link"
                void        user_function      (EphyEmbed *embed,
                                                gchar     *type,
                                                gchar     *title,
                                                gchar     *address,
                                                gpointer   user_data)      : Run first
    "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

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

    	/* 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	 (* search_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		   (* 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);

    	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;

### 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 ()

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

    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_shistory_n_items ()

    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

### ephy_embed_shistory_get_nth ()

    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

### ephy_embed_shistory_get_pos ()

    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

### ephy_embed_shistory_go_nth ()

    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

### 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-content-change" signal

    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.

### 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-location" signal

    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.

### 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-net-state" signal

    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.

### 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-security-change" signal

    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.

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

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