From 7fc0a4c481d7adad14a42740037d50b2f9e1cdc1 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Mon, 30 May 2016 17:32:57 +0100 Subject: move desktop window header into public API --- include/netsurf/browser_window.h | 714 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 714 insertions(+) create mode 100644 include/netsurf/browser_window.h (limited to 'include') diff --git a/include/netsurf/browser_window.h b/include/netsurf/browser_window.h new file mode 100644 index 000000000..36ed65a49 --- /dev/null +++ b/include/netsurf/browser_window.h @@ -0,0 +1,714 @@ +/* + * Copyright 2003 Phil Mellor + * Copyright 2006 James Bursa + * + * This file is part of NetSurf, http://www.netsurf-browser.org/ + * + * NetSurf is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; version 2 of the License. + * + * NetSurf is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +/** + * \file + * Browser window creation and manipulation interface. + */ + +#ifndef _NETSURF_DESKTOP_BROWSER_H_ +#define _NETSURF_DESKTOP_BROWSER_H_ + +#include +#include + +#include "utils/errors.h" +#include "netsurf/mouse.h" + +struct browser_window; +struct hlcache_handle; +struct gui_window; +struct history; +struct selection; +struct fetch_multipart_data; +struct form_control; +struct nsurl; +struct rect; +struct redraw_context; +enum content_debug; + +typedef enum { + DRAGGING_NONE, + DRAGGING_SELECTION, + DRAGGING_PAGE_SCROLL, + DRAGGING_FRAME, + DRAGGING_SCR_X, + DRAGGING_SCR_Y, + DRAGGING_CONTENT_SCROLLBAR, + DRAGGING_OTHER +} browser_drag_type; + +typedef enum { + BW_EDITOR_NONE = 0, /**< No selection, no editing */ + BW_EDITOR_CAN_COPY = (1 << 0), /**< Have selection */ + BW_EDITOR_CAN_CUT = (1 << 1), /**< Selection not read-only */ + BW_EDITOR_CAN_PASTE = (1 << 2) /**< Can paste, input */ +} browser_editor_flags; + +typedef enum { + BW_SCROLLING_AUTO, + BW_SCROLLING_YES, + BW_SCROLLING_NO +} browser_scrolling; + +/** flags to browser_window_create */ +enum browser_window_create_flags { + /** No flags set */ + BW_CREATE_NONE = 0, + + /** this will form a new history node (don't set for back/reload/etc) */ + BW_CREATE_HISTORY = (1 << 0), + + /** New gui_window to be tab in same window as "existing" gui_window */ + BW_CREATE_TAB = (1 << 1), + + /** New gui_window to be clone of "existing" gui_window */ + BW_CREATE_CLONE = (1 << 2), + + /** Window not opened by user interaction (e.g. JS popup) + * + * rfc2965: + * A transaction is verifiable if the user, or a + * user-designated agent, has the option to review + * the request-URI prior to its use in the transaction. + * A transaction is unverifiable if the user does not + * have that option. + */ + BW_CREATE_UNVERIFIABLE = (1 << 3), +}; + +/** flags to browser_window_navigate */ +enum browser_window_nav_flags { + /** No flags set */ + BW_NAVIGATE_NONE = 0, + + /** this will form a new history node (don't set for back/reload/etc) */ + BW_NAVIGATE_HISTORY = (1 << 0), + + /** download rather than render the uri */ + BW_NAVIGATE_DOWNLOAD = (1 << 1), + + /** Transation not caused by user interaction (e.g. JS-caused) + * + * rfc2965: + * A transaction is verifiable if the user, or a + * user-designated agent, has the option to review + * the request-URI prior to its use in the transaction. + * A transaction is unverifiable if the user does not + * have that option. + */ + BW_NAVIGATE_UNVERIFIABLE = (1 << 2) +}; + +/** + * Page features at a specific spatial location. + */ +struct browser_window_features { + /** URL of a link or NULL. */ + struct nsurl *link; + + /** Object at position or NULL. */ + struct hlcache_handle *object; + + /** handle of top level content. */ + struct hlcache_handle *main; + + /** type of form feature. */ + enum { + CTX_FORM_NONE, + CTX_FORM_TEXT, + CTX_FORM_FILE + } form_features; +}; + +/** + * Create and open a new root browser window with the given page. + * + * \param flags Flags to control operation + * \param url URL to fetch in the new window or NULL for blank + * \param referrer The referring uri or NULL if none + * \param existing The an existing bw or NULL, required for some flags. + * \param bw Updated to created browser window or untouched on error. + * \return NSERROR_OK, or appropriate error otherwise. + */ +nserror browser_window_create(enum browser_window_create_flags flags, + struct nsurl *url, struct nsurl *referrer, + struct browser_window *existing, + struct browser_window **bw); + +/** + * Start fetching a page in a browser window. + * + * \param bw browser window + * \param url URL to start fetching + * \param flags Flags to control operation + * \param referrer The referring uri or NULL if none + * \param post_urlenc url encoded post data or NULL if none + * \param post_multipart multipart post data or NULL if none + * \param parent Parent content or NULL if none + * + * Any existing fetches in the window are aborted. + * + * If post_urlenc and post_multipart are NULL the url is fetched using + * GET rather than POST. + * + */ +nserror browser_window_navigate(struct browser_window *bw, + struct nsurl *url, + struct nsurl *referrer, + enum browser_window_nav_flags flags, + char *post_urlenc, + struct fetch_multipart_data *post_multipart, + struct hlcache_handle *parent); + +/** + * Return true if a browser window can navigate upwards. + * + * \param bw the browser window to test. + * \return true if navigation up is possible otherwise false. + */ +bool browser_window_up_available(struct browser_window *bw); + +/** + * Navigate to a browser_window's parent URL. + * + * \param bw browser window + * \param new_window whether to open parent in a new window, or existing + */ +nserror browser_window_navigate_up(struct browser_window *bw, bool new_window); + +/** + * Get a browser window's URL. + * + * \param bw browser window + * \return pointer to nsurl. Doesn't create a ref for caller. + * + * \note guaranteed to return a valid nsurl ptr, never returns NULL. + */ +struct nsurl* browser_window_get_url(struct browser_window *bw); + +/** + * Get the title of a browser_window. + * + * \param bw The browser window. + */ +const char* browser_window_get_title(struct browser_window *bw); + +/** + * Get a browser window's history object. + * + * \param bw browser window + * \return pointer browser window's history object + * + * Clients need history object to make use of the history_* functions. + */ +struct history * browser_window_get_history(struct browser_window *bw); + +/** + * Get a browser window's content extents. + * + * \param bw browser window + * \param scaled whether to apply current browser window scale + * \param width updated to content width extent in px + * \param height updated to content height extent in px + * \return NSERROR_OK, or appropriate error otherwise. + */ +nserror browser_window_get_extents(struct browser_window *bw, bool scaled, + int *width, int *height); + +/** + * Find out if a browser window is currently showing a content. + * + * \param bw browser window + * \return true iff browser window is showing a content, else false. + */ +bool browser_window_has_content(struct browser_window *bw); + +/** + * Get a cache handle for the content within a browser window. + */ +struct hlcache_handle *browser_window_get_content(struct browser_window *bw); + +/** + * Set the dimensions of the area a browser window occupies + * + * \param bw The browser window to set dimensions of + * \param width Width in pixels + * \param height Height in pixels + */ +void browser_window_set_dimensions(struct browser_window *bw, + int width, int height); + +/** + * Redraw browser window, set extent to content, and update title. + * + * \param bw browser_window + * \param scroll_to_top move view to top of page + */ +void browser_window_update(struct browser_window *bw, bool scroll_to_top); + +/** + * update an area of a browser window. + * + * \param bw The browser window to update. + * \param rect The area to redraw + */ +void browser_window_update_box(struct browser_window *bw, struct rect *rect); + +/** + * Stop all fetching activity in a browser window. + * + * \param bw The browser window to stop activity in. + */ +void browser_window_stop(struct browser_window *bw); + +/** + * Reload the page in a browser window. + * + * \param bw browser window + * \param all whether to reload all objects associated with the page + */ +void browser_window_reload(struct browser_window *bw, bool all); + +/** + * Close and destroy a browser window. + * + * \param bw browser window + */ +void browser_window_destroy(struct browser_window *bw); + +/** + * Reformat a browser window contents to a new width or height. + * + * \param bw The browser window to reformat. + * \param background Reformat in the background. + * \param width new width + * \param height new height + */ +void browser_window_reformat(struct browser_window *bw, bool background, + int width, int height); + + +/** + * Sets the scale of a browser window. + * + * \param bw The browser window to scale. + * \param scale The new scale. + * \param all Scale all windows in the tree (ie work up as well as down) + */ +void browser_window_set_scale(struct browser_window *bw, float scale, bool all); + + +/** + * Gets the scale of a browser window + * + * \param bw The browser window to get the scale of. + * \return The scale of the window. + */ +float browser_window_get_scale(struct browser_window *bw); + +/** + * Get access to any page features at the given coordinates. + * + * Fetches page features like content, link URLs and objects (images) + * at the specified co-ordinates within the browsing context. + * + * Fields within the supplied features structure are updated with + * pointers to any relevent content, or set to NULL if none. + * + * \param[in] bw browser window to examine. + * \param[in] x x-coordinate of point of interest + * \param[in] y y-coordinate of point of interest + * \param[out] data Feature structure to update. + * \return NSERROR_OK or appropriate error code on faliure. + */ +nserror browser_window_get_features(struct browser_window *bw, + int x, int y, struct browser_window_features *data); + +/** + * Send a scroll request to a browser window at a particular point. The + * 'deepest' scrollable object which can be scrolled in the requested + * direction at the given point will consume the scroll. + * + * \param bw browser window to look inside + * \param x x-coordinate of point of interest + * \param y y-coordinate of point of interest + * \param scrx number of px try to scroll something in x direction + * \param scry number of px try to scroll something in y direction + * \return true iff scroll request has been consumed + */ +bool browser_window_scroll_at_point(struct browser_window *bw, + int x, int y, int scrx, int scry); + +/** + * Drop a file onto a browser window at a particular point, or determine if a + * file may be dropped onto the content at given point. + * + * \param bw browser window to look inside + * \param x x-coordinate of point of interest + * \param y y-coordinate of point of interest + * \param file path to file to be dropped, or NULL to know if drop allowed + * \return true iff file drop has been handled, or if drop possible (NULL file) + */ +bool browser_window_drop_file_at_point(struct browser_window *bw, + int x, int y, char *file); + +/** + * set filename on form control. + * + * \param bw browser window to look inside. + * \param gadget form control. + * \param fn filename to set. + */ +void browser_window_set_gadget_filename(struct browser_window *bw, + struct form_control *gadget, const char *fn); + +/** + * Update URL bar for a given browser window to bw's content's URL + * + * \param bw Browser window to update URL bar for. + */ +nserror browser_window_refresh_url_bar(struct browser_window *bw); + +/** + * Handle mouse clicks in a browser window. + * + * \param bw browser window + * \param mouse state of mouse buttons and modifier keys + * \param x coordinate of mouse + * \param y coordinate of mouse + */ +void browser_window_mouse_click(struct browser_window *bw, + browser_mouse_state mouse, int x, int y); + +/** + * Handle non-click mouse action in a browser window. (drag ends, movements) + * + * \param bw browser window + * \param mouse state of mouse buttons and modifier keys + * \param x coordinate of mouse + * \param y coordinate of mouse + */ +void browser_window_mouse_track(struct browser_window *bw, + browser_mouse_state mouse, int x, int y); + +/** + * Locate a browser window in the specified stack according. + * + * \param bw the browser_window to search all relatives of + * \param target the target to locate + * \param mouse The current mouse state + * \return The browser window the mouse is in + */ +struct browser_window *browser_window_find_target( + struct browser_window *bw, const char *target, + browser_mouse_state mouse); + +/** + * Cause the frontends reformat entry to be called in safe context. + * + * The browser_window_reformat call cannot safely be called from some + * contexts, this call allows for the reformat to happen from a safe + * top level context. + * + * The callback is frontend provided as the context information (size + * etc.) about the windowing toolkit is only available to the + * frontend. + */ +nserror browser_window_schedule_reformat(struct browser_window *bw); + + + +void browser_select_menu_callback(void *client_data, + int x, int y, int width, int height); + +/** + * Redraw a rectangular region of a browser window. + * + * \param bw browser window to be redrawn + * \param x x co-ord of top-left + * \param y y co-ord of top-left + * \param width width of rectangle + * \param height height of rectangle + */ +void browser_window_redraw_rect(struct browser_window *bw, int x, int y, + int width, int height); + +/** + * Change the shape of the mouse pointer + * + * \param bw Browser window to set shape in + * \param shape The pointer shape to use + */ +void browser_window_set_pointer(struct browser_window *bw, + browser_pointer_shape shape); + +/** + * Start drag scrolling the contents of the browser window + * + * \param bw browser window + * \param x x ordinate of initial mouse position + * \param y y ordinate + */ +void browser_window_page_drag_start(struct browser_window *bw, int x, int y); + +/** + * Check availability of Back action for a given browser window + * + * \param bw browser window + * \return true if Back action is available + */ +bool browser_window_back_available(struct browser_window *bw); + +/** + * Check availability of Forward action for a given browser window + * + * \param bw browser window + * \return true if Forward action is available + */ +bool browser_window_forward_available(struct browser_window *bw); + +/** + * Check availability of Reload action for a given browser window + * + * \param bw browser window + * \return true if Reload action is available + */ +bool browser_window_reload_available(struct browser_window *bw); + +/** + * Check availability of Stop action for a given browser window + * + * \param bw browser window + * \return true if Stop action is available + */ +bool browser_window_stop_available(struct browser_window *bw); + +/** + * Redraw an area of a window. + * + * Calls the redraw function for the content. + * + * \param bw The window to redraw + * \param x coordinate for top-left of redraw + * \param y coordinate for top-left of redraw + * \param clip clip rectangle coordinates + * \param ctx redraw context + * \return true if successful, false otherwise + * + * The clip rectangle is guaranteed to be filled to its extents, so there is + * no need to render a solid background first. + * + * x, y and clip are coordinates from the top left of the canvas area. + * + * The top left corner of the clip rectangle is (x0, y0) and + * the bottom right corner of the clip rectangle is (x1, y1). + * Units for x, y and clip are pixels. + */ +bool browser_window_redraw(struct browser_window *bw, int x, int y, + const struct rect *clip, const struct redraw_context *ctx); + +/** + * Check whether browser window is ready for redraw + * + * \param bw The window to redraw + * \return true if browser window is ready for redraw + */ +bool browser_window_redraw_ready(struct browser_window *bw); + +/** + * Get the position of the current browser window with respect to the root or + * parent browser window + * + * \param bw browser window to get the position of + * \param root true if we want position wrt root bw, false if wrt parent bw + * \param pos_x updated to x position of bw + * \param pos_y updated to y position of bw + */ +void browser_window_get_position(struct browser_window *bw, bool root, + int *pos_x, int *pos_y); + +/** + * Set the position of the current browser window with respect to the parent + * browser window + * + * \param bw browser window to set the position of + * \param x x position of bw + * \param y y position of bw + */ +void browser_window_set_position(struct browser_window *bw, int x, int y); + +/** + * Scroll the browser window to display the passed area + * + * \param bw browser window to scroll + * \param rect area to display + */ +void browser_window_scroll_visible(struct browser_window *bw, + const struct rect *rect); + +/** + * Set scroll offsets for a browser window. + * + * \param bw The browser window + * \param x The x scroll offset to set + * \param y The y scroll offset to set + * + * \todo Do we really need this and browser_window_scroll_visible? + * Ditto for gui_window_* variants. + */ +void browser_window_set_scroll(struct browser_window *bw, int x, int y); + +/** + * Set drag type for a browser window, and inform front end + * + * \param bw browser window to set the type of the current drag for + * \param type drag type + * \param rect area pointer may be confined to, during drag, or NULL + */ +void browser_window_set_drag_type(struct browser_window *bw, + browser_drag_type type, const struct rect *rect); + +/** + * Get type of any current drag for a browser window + * + * \param bw browser window to set the type of the current drag for + * \return drag type + */ +browser_drag_type browser_window_get_drag_type(struct browser_window *bw); + +/** + * Check whether browser window can accept a cut/copy/paste, or has a selection + * that could be saved. + * + * \param bw The browser window + * \return flags indicating editor flags + */ +browser_editor_flags browser_window_get_editor_flags(struct browser_window *bw); + +/** + * Find out if given browser window content is selectable + * + * \param bw browser window to look at + * \return true iff browser window is selectable + */ +bool browser_window_can_select(struct browser_window *bw); + +/** + * Get the current selection from a root browser window, ownership passed to + * caller, who must free() it. + * + * \param bw The browser window + * \return the selected text string, or NULL + */ +char * browser_window_get_selection(struct browser_window *bw); + +/** + * Find out if given browser window can be searched + * + * \param bw browser window to look at + * \return true iff browser window is searchable + */ +bool browser_window_can_search(struct browser_window *bw); + +/** + * Find out if a browser window contains a frameset + * + * \param bw browser window to look at + * \return true iff browser window contains a frameset + */ +bool browser_window_is_frameset(struct browser_window *bw); + +/** + * Get the browser window's scrollbar details. + * + * Vertical and horizontal scrollbars may be {YES|NO|AUTO}, although + * it is entirely up to the front end whether this is implemented. + * e.g. if the gui toolkit style-guide says all windows must have + * scrollbars then this API can be ignored. + * + * \param bw browser window to look at + * \param h Updated to indicate horizontal scrollbar type + * \param v Updated to indicate vertical scrollbar type + * \return NSERROR_OK, or appropriate error otherwise + */ +nserror browser_window_get_scrollbar_type(struct browser_window *bw, + browser_scrolling *h, browser_scrolling *v); + +/** + * Set the DPI of the browser. + * + * \param dpi The DPI to set. + */ +nserror browser_set_dpi(int dpi); + +/** + * Get the browser DPI. + * + * \return The DPI in use. + */ +int browser_get_dpi(void); + +/** + * Dump debug info concerning the browser window's contents to file + * + * \param bw The browser window. + * \param f The file to dump to. + * \param op The debug operation type to dump. + * \return NSERROR_OK on success or error code on faliure. + */ +nserror browser_window_debug_dump(struct browser_window *bw, FILE *f, enum content_debug op); + +/** + * Set debug options on a window + * + * \param bw The browser window. + * \param op The debug operation type. + * \return NSERROR_OK on success or error code on faliure. + */ +nserror browser_window_debug(struct browser_window *bw, enum content_debug op); + +/** + * Obtain a browsing contexts name. + * + * The returned pointer is owned bu the browsing context and is only + * valid untill the next operation on that context. + * The returned name may be NULL if no name has been set. + * \todo This does not consider behaviour wrt frames + * + * \param bw The browser window. + * \param name recives result string. + * \return NSERROR_OK + */ +nserror browser_window_get_name(struct browser_window *bw, const char **name); + +/** + * Set a browsing contexts name. + * + * Changes a browsing contexts name to a copy of that passed and the + * value is not subsequently referenced. + * + * \param bw The browser window. + * \param name The name string to set. + * \return NSERROR_OK and the name is updated or NSERROR_NOMEM and the + * original name is untouched. + */ +nserror browser_window_set_name(struct browser_window *bw, const char *name); + +#endif -- cgit v1.2.3