mirrors
/
netsurf
mirror of https://github.com/netsurf-browser/netsurf
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
netsurf/desktop/browser.h

716 lines
21 KiB
C
Raw Blame History

/*
* 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 "desktop/plot_style.h"
#include "desktop/frame_types.h"
#include "desktop/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
Reference in New Issue View Git Blame Copy Permalink