From 2dc702089f58f707d84e138816d2b40f3d07e096 Mon Sep 17 00:00:00 2001 From: Diego Escalante Urrelo Date: Wed, 9 Dec 2009 20:37:39 -0500 Subject: docs: ephy-web-view --- embed/ephy-web-view.c | 210 +++++++++++++++++++++++++++++++++++++++++++------- embed/ephy-web-view.h | 2 +- 2 files changed, 185 insertions(+), 27 deletions(-) (limited to 'embed') diff --git a/embed/ephy-web-view.c b/embed/ephy-web-view.c index 7fcb7f408..47960a256 100644 --- a/embed/ephy-web-view.c +++ b/embed/ephy-web-view.c @@ -49,6 +49,14 @@ #include "ephy-web-view.h" #include "ephy-zoom.h" +/** + * SECTION:ephy-web-view + * @short_description: Epiphany custom #WebkitWebView + * + * #EphyWebView wraps #WebkitWebView implementing custom functionality on top of + * it. + */ + static void ephy_web_view_class_init (EphyWebViewClass *klass); static void ephy_web_view_init (EphyWebView *gs); @@ -361,6 +369,12 @@ disconnect_popup (EphyEmbedContainer *container, (container, G_CALLBACK (popups_manager_remove_window), view); } +/** + * ephy_web_view_popups_manager_reset: + * @view: an #EphyWebView + * + * Resets the state of the popups manager in @view. + **/ void ephy_web_view_popups_manager_reset (EphyWebView *view) { @@ -1300,6 +1314,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) widget_class->key_press_event = ephy_web_view_key_press_event; +/** + * EphyWebView:address: + * + * View's current address. + **/ g_object_class_install_property (gobject_class, PROP_ADDRESS, g_param_spec_string ("address", @@ -1307,6 +1326,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) "The view's address", "", G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:typed-address: + * + * User typed address for the current view. + **/ g_object_class_install_property (gobject_class, PROP_TYPED_ADDRESS, g_param_spec_string ("typed-address", @@ -1314,6 +1339,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) "The typed address", "", G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:embed-title: + * + * Title for this embed. + **/ g_object_class_install_property (gobject_class, PROP_EMBED_TITLE, g_param_spec_string ("embed-title", @@ -1322,6 +1353,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) EMPTY_PAGE, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); +/** + * EphyWebView:security-level: + * + * One of #EphyWebViewSecurityLevel, determining view's current security level. + **/ g_object_class_install_property (gobject_class, PROP_SECURITY, g_param_spec_enum ("security-level", @@ -1330,6 +1366,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) EPHY_TYPE_WEB_VIEW_SECURITY_LEVEL, EPHY_WEB_VIEW_STATE_IS_UNKNOWN, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:document-type: + * + * Document type determined for the view. + **/ g_object_class_install_property (gobject_class, PROP_DOCUMENT_TYPE, g_param_spec_enum ("document-type", @@ -1339,6 +1381,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) EPHY_WEB_VIEW_DOCUMENT_HTML, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); +/** + * EphyWebView:navigation: + * + * View's navigation flags as #EphyWebViewNavigationFlags. + **/ g_object_class_install_property (gobject_class, PROP_NAVIGATION, g_param_spec_flags ("navigation", @@ -1347,6 +1394,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) EPHY_TYPE_WEB_VIEW_NAVIGATION_FLAGS, 0, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:status-message: + * + * Statusbar message corresponding to this view. + **/ g_object_class_install_property (gobject_class, PROP_STATUS_MESSAGE, g_param_spec_string ("status-message", @@ -1354,6 +1407,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) "The view's statusbar message", NULL, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:link-message: + * + * ??? + **/ g_object_class_install_property (gobject_class, PROP_LINK_MESSAGE, g_param_spec_string ("link-message", @@ -1361,6 +1420,12 @@ ephy_web_view_class_init (EphyWebViewClass *klass) "The view's link message", NULL, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); + +/** + * EphyWebView:icon: + * + * View's favicon set by the loaded site. + **/ g_object_class_install_property (gobject_class, PROP_ICON, g_param_spec_object ("icon", @@ -1369,6 +1434,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) GDK_TYPE_PIXBUF, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); +/** + * EphyWebView:hidden-popup-count: + * + * Number of hidden (blocked) popup windows. + **/ g_object_class_install_property (gobject_class, PROP_HIDDEN_POPUP_COUNT, g_param_spec_int ("hidden-popup-count", @@ -1379,6 +1449,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) 0, G_PARAM_READABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); +/** + * EphyWebView:popups-allowed: + * + * If popup windows from this view are to be displayed. + **/ g_object_class_install_property (gobject_class, PROP_POPUPS_ALLOWED, g_param_spec_boolean ("popups-allowed", @@ -1387,6 +1462,11 @@ ephy_web_view_class_init (EphyWebViewClass *klass) FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)); +/** + * EphyWebView:visibility: + * + * + **/ g_object_class_install_property (gobject_class, PROP_VISIBLE, g_param_spec_boolean ("visibility", @@ -1404,14 +1484,14 @@ ephy_web_view_class_init (EphyWebViewClass *klass) * the view. For example, when a JavaScript popup window is opened. **/ g_signal_new ("ge_new_window", - EPHY_TYPE_WEB_VIEW, - G_SIGNAL_RUN_FIRST | G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (EphyWebViewClass, new_window), - NULL, NULL, - g_cclosure_marshal_VOID__OBJECT, - G_TYPE_NONE, - 1, - GTK_TYPE_WIDGET); + EPHY_TYPE_WEB_VIEW, + G_SIGNAL_RUN_FIRST | G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (EphyWebViewClass, new_window), + NULL, NULL, + g_cclosure_marshal_VOID__OBJECT, + G_TYPE_NONE, + 1, + GTK_TYPE_WIDGET); /** * EphyWebView::ge-popup-blocked: * @view: the #EphyWebView that received the signal @@ -1482,7 +1562,7 @@ ephy_web_view_class_init (EphyWebViewClass *klass) * @view: the #EphyWebView that received the signal * @event: the #EphyEmbedEvent which triggered this signal * - * The ::ge_dom_mouse_click signal is emitted when the user clicks in @embed. + * The ::ge_dom_mouse_click signal is emitted when the user clicks in the @view. **/ g_signal_new ("ge_dom_mouse_click", EPHY_TYPE_WEB_VIEW, @@ -1583,7 +1663,7 @@ ephy_web_view_class_init (EphyWebViewClass *klass) * EphyWebView::close-request * @view: the #EphyWebView that received the signal * - * The ::close signal is emitted when the embed request closing. + * The ::close signal is emitted when the embed requests closing. * Return %TRUE to prevent closing. You HAVE to process removal of the embed * as soon as possible after that. **/ @@ -1621,15 +1701,15 @@ ephy_web_view_class_init (EphyWebViewClass *klass) * related changes, for example to restore the zoom level of a page * or to set an user style sheet. **/ - g_signal_new ("new-document-now", - EPHY_TYPE_WEB_VIEW, - G_SIGNAL_RUN_FIRST, - G_STRUCT_OFFSET (EphyWebViewClass, new_document_now), - NULL, NULL, - g_cclosure_marshal_VOID__STRING, - G_TYPE_NONE, - 1, - G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE); + g_signal_new ("new-document-now", + EPHY_TYPE_WEB_VIEW, + G_SIGNAL_RUN_FIRST, + G_STRUCT_OFFSET (EphyWebViewClass, new_document_now), + NULL, NULL, + g_cclosure_marshal_VOID__STRING, + G_TYPE_NONE, + 1, + G_TYPE_STRING | G_SIGNAL_TYPE_STATIC_SCOPE); g_type_class_add_private (gobject_class, sizeof (EphyWebViewPrivate)); } @@ -1943,28 +2023,28 @@ normalize_or_autosearch_url (EphyWebView *view, const char *url) /** * ephy_web_view_load_request: - * @web_view: the #EphyWebView in which to load the request + * @view: the #EphyWebView in which to load the request * @request: the #WebKitNetworkRequest to be loaded * * Loads the given #WebKitNetworkRequest in the given #EphyWebView. **/ void -ephy_web_view_load_request (EphyWebView *web_view, +ephy_web_view_load_request (EphyWebView *view, WebKitNetworkRequest *request) { WebKitWebFrame *main_frame; const char *url; char *effective_url; - g_return_if_fail (EPHY_IS_WEB_VIEW(web_view)); + g_return_if_fail (EPHY_IS_WEB_VIEW(view)); g_return_if_fail (WEBKIT_IS_NETWORK_REQUEST(request)); url = webkit_network_request_get_uri (request); - effective_url = normalize_or_autosearch_url (web_view, url); + effective_url = normalize_or_autosearch_url (view, url); webkit_network_request_set_uri (request, effective_url); g_free (effective_url); - main_frame = webkit_web_view_get_main_frame (WEBKIT_WEB_VIEW(web_view)); + main_frame = webkit_web_view_get_main_frame (WEBKIT_WEB_VIEW(view)); webkit_web_frame_load_request(main_frame, request); } @@ -2044,6 +2124,14 @@ ephy_web_view_copy_back_history (EphyWebView *source, webkit_web_back_forward_list_add_item (dest_bflist, item); } +/** + * ephy_web_view_set_address: + * @view: an #EphyWebView + * @address: address to set @view to + * + * Sets @view location to be @address. Note that this function might also set + * the typed-address property to %NULL. + */ void ephy_web_view_set_address (EphyWebView *view, const char *address) @@ -2078,6 +2166,13 @@ get_title_from_address (const char *address) return ephy_string_get_host_name (address); } +/** + * ephy_web_view_set_title: + * @view: an #EphyWebView + * @view_title: new title for @view + * + * Sets @view title to @view_title. + */ void ephy_web_view_set_title (EphyWebView *view, const char *view_title) @@ -2236,6 +2331,14 @@ update_navigation_flags (EphyWebView *view) } } +/** + * ephy_web_view_update_from_net_state: + * @view: an #EphyWebView + * @uri: the uri associated with @view + * @state: an #EphyWebViewNetState + * + * Update @view at @uri with info from @state. + **/ void ephy_web_view_update_from_net_state (EphyWebView *view, const char *uri, @@ -2277,6 +2380,15 @@ ephy_web_view_update_from_net_state (EphyWebView *view, } } +/** + * ephy_web_view_set_loading_title: + * @view: an #EphyWebView + * @title: new loading title for @view + * @is_address: %TRUE if @title is an address + * + * Update @view's loading title to @title, if @is_address is %TRUE it will + * retrieve the title of the page at @title. + **/ void ephy_web_view_set_loading_title (EphyWebView *view, const char *title, @@ -2452,6 +2564,14 @@ ephy_web_view_update_file_monitor (EphyWebView *view, g_free (url); } +/** + * ephy_web_view_location_changed: + * @view: an #EphyWebView + * @location: new location for @view + * + * Sets @location as the new address for @view while preventing notify events + * in @view. + **/ void ephy_web_view_location_changed (EphyWebView *view, const char *location) @@ -2553,6 +2673,14 @@ ephy_web_view_is_loading (EphyWebView *view) return status != WEBKIT_LOAD_FINISHED && status != WEBKIT_LOAD_FAILED; } +/** + * ephy_web_view_get_loading_title: + * @view: an #EphyWebView + * + * Returns the loading title for @view. + * + * Return value: the provisional title of @view while loading + **/ const char * ephy_web_view_get_loading_title (EphyWebView *view) { @@ -2560,7 +2688,7 @@ ephy_web_view_get_loading_title (EphyWebView *view) } /** - * ephy_wew_view_get_icon: + * ephy_web_view_get_icon: * @view: an #EphyWebView * * Returns the view's site icon as a #GdkPixbuf, @@ -2663,6 +2791,14 @@ ephy_web_view_get_visibility (EphyWebView *view) return view->priv->visibility; } +/** + * ephy_web_view_set_link_message: + * @view: an #EphyWebView + * @link_message: new value for link-message in @view + * + * Sets the value of link-message property which tells the URL of the hovered + * link. + **/ void ephy_web_view_set_link_message (EphyWebView *view, char *link_message) @@ -2677,6 +2813,13 @@ ephy_web_view_set_link_message (EphyWebView *view, g_object_notify (G_OBJECT (view), "link-message"); } +/** + * ephy_web_view_set_security_level: + * @view: an #EphyWebView + * @level: the new #EphyWebViewSecurityLevel for @view + * + * Sets @view's security-level property to @level. + **/ void ephy_web_view_set_security_level (EphyWebView *view, EphyWebViewSecurityLevel level) @@ -2690,6 +2833,14 @@ ephy_web_view_set_security_level (EphyWebView *view, } } +/** + * ephy_web_view_set_visibility: + * @view: an #EphyWebView + * @visibility: value for the visibility property of @view + * + * Sets whether the @view's toplevel is visible or not. See + * ephy_web_view_get_visibility(). + **/ void ephy_web_view_set_visibility (EphyWebView *view, gboolean visibility) @@ -2960,7 +3111,7 @@ ephy_web_view_get_go_up_list (EphyWebView *view) } /** - * ephy_embed_utils_get_title_composite: + * ephy_web_view_get_title_composite: * @view: an #EphyView * * Returns the title of the web page loaded in @view. @@ -3209,6 +3360,13 @@ ephy_web_view_save_sub_resources (EphyWebView *view, const char *uri, GList *sub ephy_web_view_save_sub_resource_start (subresources, destination_uri); } +/** + * ephy_web_view_save: + * @view: an #EphyWebView + * @uri: location to store the saved page + * + * Saves the currently loaded page of @view to @uri. + **/ void ephy_web_view_save (EphyWebView *view, const char *uri) { diff --git a/embed/ephy-web-view.h b/embed/ephy-web-view.h index 5ed358be7..37852bccd 100644 --- a/embed/ephy-web-view.h +++ b/embed/ephy-web-view.h @@ -206,7 +206,7 @@ const char * ephy_web_view_get_address (EphyWebView const char * ephy_web_view_get_title_composite (EphyWebView *view); /* These should be private */ -void ephy_web_view_set_address (EphyWebView *embed, +void ephy_web_view_set_address (EphyWebView *view, const char *address); void ephy_web_view_update_from_net_state (EphyWebView *view, const char *uri, -- cgit v1.2.3