summaryrefslogtreecommitdiff
path: root/include/netsurf/browser_window.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/netsurf/browser_window.h')
-rw-r--r--include/netsurf/browser_window.h714
1 files changed, 714 insertions, 0 deletions
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 <monkeyson@users.sourceforge.net>
+ * Copyright 2006 James Bursa <bursa@users.sourceforge.net>
+ *
+ * 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 <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * \file
+ * Browser window creation and manipulation interface.
+ */
+
+#ifndef _NETSURF_DESKTOP_BROWSER_H_
+#define _NETSURF_DESKTOP_BROWSER_H_
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#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