NetSurf
window.h
Go to the documentation of this file.
1/*
2 * Copyright 2014 Vincent Sanders <vince@netsurf-browser.org>
3 *
4 * This file is part of NetSurf, http://www.netsurf-browser.org/
5 *
6 * NetSurf is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
9 *
10 * NetSurf is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19/**
20 * \file
21 *
22 * Interface to platform-specific graphical user interface window
23 * operations.
24 */
25
26#ifndef NETSURF_WINDOW_H
27#define NETSURF_WINDOW_H
28
29#include "netsurf/console.h"
30
31struct browser_window;
32struct form_control;
33struct rect;
34struct hlcache_handle;
35struct nsurl;
36
38
39typedef enum gui_save_type {
55
56typedef enum {
62
63/**
64 * Window creation control flags.
65 */
66typedef enum {
67 GW_CREATE_NONE = 0, /**< New window */
68 GW_CREATE_CLONE = (1 << 0), /**< Clone existing window */
69 GW_CREATE_TAB = (1 << 1), /**< Create tab in same window as existing */
70 GW_CREATE_FOREGROUND = (1 << 2), /**< Request this window/tab is foregrounded */
71 GW_CREATE_FOCUS_LOCATION = (1 << 3) , /** Request this window/tab focusses the URL input */
73
74/**
75 * Window events
76 *
77 * these are events delivered to a gui window which have no additional
78 * parameters and hence do not require separate callbacks.
79 */
81 /**
82 * An empty event should never occur
83 */
85
86 /**
87 * Update the extent of the inside of a browser window to that of the
88 * current content.
89 *
90 * @todo this is used to update scroll bars does it need
91 * renaming? some frontends (windows) do not even implement it.
92 */
94
95 /**
96 * Remove the caret, if present.
97 */
99
100 /**
101 * start the navigation throbber.
102 */
104
105 /**
106 * stop the navigation throbber.
107 */
109
110 /**
111 * Starts drag scrolling of a browser window
112 */
114
115 /**
116 * Called when the gui_window has new content.
117 */
119
120 /**
121 * selection started
122 */
124
125 /**
126 * Page status has changed and so the padlock should be
127 * updated.
128 */
130};
131
132/**
133 * Graphical user interface window function table.
134 *
135 * function table implementing window operations
136 */
138
139 /* Mandatory entries */
140
141 /**
142 * Create and open a gui window for a browsing context.
143 *
144 * The implementing front end must create a context suitable
145 * for it to display a window referred to as the "gui window".
146 *
147 * The frontend will be expected to request the core redraw
148 * areas of the gui window which have become invalidated
149 * either from toolkit expose events or as a result of a
150 * invalidate() call.
151 *
152 * Most core operations used by the frontend concerning browser
153 * windows require passing the browser window context therefor
154 * the gui window must include a reference to the browser
155 * window passed here.
156 *
157 * If GW_CREATE_CLONE flag is set existing is non-NULL.
158 *
159 * \param bw The core browsing context associated with the gui window
160 * \param existing An existing gui_window, may be NULL.
161 * \param flags flags to control the gui window creation.
162 * \return gui window, or NULL on error.
163 */
164 struct gui_window *(*create)(struct browser_window *bw,
165 struct gui_window *existing,
167
168
169 /**
170 * Destroy previously created gui window
171 *
172 * \param gw The gui window to destroy.
173 */
174 void (*destroy)(struct gui_window *gw);
175
176
177 /**
178 * Invalidate an area of a window.
179 *
180 * The specified area of the window should now be considered
181 * out of date. If the area is NULL the entire window must be
182 * invalidated. It is expected that the windowing system will
183 * then subsequently cause redraw/expose operations as
184 * necessary.
185 *
186 * \note the frontend should not attempt to actually start the
187 * redraw operations as a result of this callback because the
188 * core redraw functions may already be threaded.
189 *
190 * \param gw The gui window to invalidate.
191 * \param rect area to redraw or NULL for the entire window area
192 * \return NSERROR_OK on success or appropriate error code
193 */
194 nserror (*invalidate)(struct gui_window *gw, const struct rect *rect);
195
196
197 /**
198 * Get the scroll position of a browser window.
199 *
200 * \param gw The gui window to obtain the scroll position from.
201 * \param sx receives x ordinate of point at top-left of window
202 * \param sy receives y ordinate of point at top-left of window
203 * \return true iff successful
204 */
205 bool (*get_scroll)(struct gui_window *gw, int *sx, int *sy);
206
207
208 /**
209 * Set the scroll position of a browser window.
210 *
211 * scrolls the viewport to ensure the specified rectangle of
212 * the content is shown.
213 * If the rectangle is of zero size i.e. x0 == x1 and y0 == y1
214 * the contents will be scrolled so the specified point in the
215 * content is at the top of the viewport.
216 * If the size of the rectangle is non zero the frontend may
217 * add padding or centre the defined area or it may simply
218 * align as in the zero size rectangle
219 *
220 * \param gw The gui window to scroll.
221 * \param rect The rectangle to ensure is shown.
222 * \return NSERROR_OK on success or appropriate error code.
223 */
224 nserror (*set_scroll)(struct gui_window *gw, const struct rect *rect);
225
226
227 /**
228 * Find the current dimensions of a browser window's content area.
229 *
230 * This is used to determine the actual available drawing size
231 * in pixels. This allows contents that can be dynamically
232 * reformatted, such as HTML, to better use the available
233 * space.
234 *
235 * \param gw The gui window to measure content area of.
236 * \param width receives width of window
237 * \param height receives height of window
238 * \return NSERROR_OK on success and width and height updated
239 * else error code.
240 */
241 nserror (*get_dimensions)(struct gui_window *gw, int *width, int *height);
242
243
244 /**
245 * Miscellaneous event occurred for a window
246 *
247 * This is used to inform the frontend of window events which
248 * require no additional parameters.
249 *
250 * \param gw The gui window the event occurred for
251 * \param event Which event has occurred.
252 * \return NSERROR_OK if the event was processed else error code.
253 */
255
256 /* Optional entries */
257
258 /**
259 * Set the title of a window.
260 *
261 * \param gw The gui window to set title of.
262 * \param title new window title
263 */
264 void (*set_title)(struct gui_window *gw, const char *title);
265
266 /**
267 * Set the navigation url.
268 *
269 * \param gw window to update.
270 * \param url The url to use as icon.
271 */
272 nserror (*set_url)(struct gui_window *gw, struct nsurl *url);
273
274 /**
275 * Set a favicon for a gui window.
276 *
277 * \param gw window to update.
278 * \param icon handle to object to use as icon.
279 */
280 void (*set_icon)(struct gui_window *gw, struct hlcache_handle *icon);
281
282 /**
283 * Set the status bar message of a browser window.
284 *
285 * \param g gui_window to update
286 * \param text new status text
287 */
288 void (*set_status)(struct gui_window *g, const char *text);
289
290 /**
291 * Change mouse pointer shape
292 *
293 * \param g The gui window to change pointer shape in.
294 * \param shape The new shape to change to.
295 */
296 void (*set_pointer)(struct gui_window *g, enum gui_pointer_shape shape);
297
298 /**
299 * Place the caret in a browser window.
300 *
301 * \param g window with caret
302 * \param x coordinates of caret
303 * \param y coordinates of caret
304 * \param height height of caret
305 * \param clip clip rectangle, or NULL if none
306 */
307 void (*place_caret)(struct gui_window *g, int x, int y, int height, const struct rect *clip);
308
309 /**
310 * start a drag operation within a window
311 *
312 * \param g window to start drag from.
313 * \param type Type of drag to start
314 * \param rect Confining rectangle of drag operation.
315 * \return true if drag started else false.
316 */
317 bool (*drag_start)(struct gui_window *g, gui_drag_type type, const struct rect *rect);
318
319 /**
320 * save link operation
321 *
322 * \param g window to save link from.
323 * \param url The link url.
324 * \param title The title of the link.
325 * \return NSERROR_OK on success else appropriate error code.
326 */
327 nserror (*save_link)(struct gui_window *g, struct nsurl *url, const char *title);
328
329 /**
330 * create a form select menu
331 *
332 * \param gw The gui window to open select menu form gadget in.
333 * \param control The form control gadget handle.
334 */
335 void (*create_form_select_menu)(struct gui_window *gw, struct form_control *control);
336
337 /**
338 * Called when file chooser gadget is activated
339 *
340 * \param gw The gui window to open file chooser in.
341 * \param hl The content of the object.
342 * \param gadget The form control gadget handle.
343 */
344 void (*file_gadget_open)(struct gui_window *gw, struct hlcache_handle *hl, struct form_control *gadget);
345
346 /**
347 * object dragged to window
348 *
349 * \param gw The gui window to save dragged object of.
350 * \param c The content of the object.
351 * \param type the type of save.
352 */
354
355 /**
356 * drag selection save
357 *
358 * \param gw The gui window to save dragged selection of.
359 * \param selection The selection to save.
360 */
361 void (*drag_save_selection)(struct gui_window *gw, const char *selection);
362
363 /**
364 * console logging happening.
365 *
366 * See \ref browser_window_console_log
367 *
368 * \param gw The gui window receiving the logging.
369 * \param src The source of the logging message
370 * \param msg The text of the logging message
371 * \param msglen The length of the text of the logging message
372 * \param flags Flags associated with the logging.
373 */
374 void (*console_log)(struct gui_window *gw,
376 const char *msg,
377 size_t msglen,
379};
380
381#endif
Browser window console stuff.
browser_window_console_source
Sources of messages which end up in the browser window console.
Definition: console.h:30
browser_window_console_flags
Flags for browser window console logging.
Definition: console.h:41
nserror
Enumeration of error codes.
Definition: errors.h:29
const char * type
Definition: filetype.cpp:44
struct atari_hotlist hl
Definition: hotlist.c:47
gui_pointer_shape
Definition: mouse.h:89
gui_window_create_flags
Window creation control flags.
Definition: window.h:66
@ GW_CREATE_NONE
New window.
Definition: window.h:67
@ GW_CREATE_TAB
Create tab in same window as existing.
Definition: window.h:69
@ GW_CREATE_FOREGROUND
Request this window/tab is foregrounded.
Definition: window.h:70
@ GW_CREATE_FOCUS_LOCATION
Definition: window.h:71
@ GW_CREATE_CLONE
Clone existing window.
Definition: window.h:68
gui_save_type
Definition: window.h:39
@ GUI_SAVE_OBJECT_ORIG
Definition: window.h:45
@ GUI_SAVE_DRAW
Definition: window.h:41
@ GUI_SAVE_HISTORY_EXPORT_HTML
Definition: window.h:51
@ GUI_SAVE_TEXT
Definition: window.h:43
@ GUI_SAVE_CLIPBOARD_CONTENTS
Definition: window.h:53
@ GUI_SAVE_SOURCE
Definition: window.h:40
@ GUI_SAVE_HOTLIST_EXPORT_HTML
Definition: window.h:50
@ GUI_SAVE_LINK_TEXT
Definition: window.h:49
@ GUI_SAVE_LINK_URI
Definition: window.h:47
@ GUI_SAVE_TEXT_SELECTION
Definition: window.h:52
@ GUI_SAVE_OBJECT_NATIVE
Definition: window.h:46
@ GUI_SAVE_LINK_URL
Definition: window.h:48
@ GUI_SAVE_COMPLETE
Definition: window.h:44
@ GUI_SAVE_PDF
Definition: window.h:42
gui_drag_type
Definition: window.h:56
@ GDRAGGING_NONE
Definition: window.h:57
@ GDRAGGING_SCROLLBAR
Definition: window.h:58
@ GDRAGGING_SELECTION
Definition: window.h:59
@ GDRAGGING_OTHER
Definition: window.h:60
gui_window_event
Window events.
Definition: window.h:80
@ GW_EVENT_NONE
An empty event should never occur.
Definition: window.h:84
@ GW_EVENT_SCROLL_START
Starts drag scrolling of a browser window.
Definition: window.h:113
@ GW_EVENT_PAGE_INFO_CHANGE
Page status has changed and so the padlock should be updated.
Definition: window.h:129
@ GW_EVENT_REMOVE_CARET
Remove the caret, if present.
Definition: window.h:98
@ GW_EVENT_NEW_CONTENT
Called when the gui_window has new content.
Definition: window.h:118
@ GW_EVENT_STOP_THROBBER
stop the navigation throbber.
Definition: window.h:108
@ GW_EVENT_UPDATE_EXTENT
Update the extent of the inside of a browser window to that of the current content.
Definition: window.h:93
@ GW_EVENT_START_SELECTION
selection started
Definition: window.h:123
@ GW_EVENT_START_THROBBER
start the navigation throbber.
Definition: window.h:103
struct nsurl nsurl
NetSurf URL object.
Definition: nsurl.h:31
int width
Definition: gui.c:160
int height
Definition: gui.c:161
Browser window data.
struct browser_window * bw
Form control.
Definition: form_internal.h:73
Graphical user interface window function table.
Definition: window.h:137
nserror(* get_dimensions)(struct gui_window *gw, int *width, int *height)
Find the current dimensions of a browser window's content area.
Definition: window.h:241
void(* set_title)(struct gui_window *gw, const char *title)
Set the title of a window.
Definition: window.h:264
nserror(* set_scroll)(struct gui_window *gw, const struct rect *rect)
Set the scroll position of a browser window.
Definition: window.h:224
bool(* drag_start)(struct gui_window *g, gui_drag_type type, const struct rect *rect)
start a drag operation within a window
Definition: window.h:317
void(* set_pointer)(struct gui_window *g, enum gui_pointer_shape shape)
Change mouse pointer shape.
Definition: window.h:296
nserror(* save_link)(struct gui_window *g, struct nsurl *url, const char *title)
save link operation
Definition: window.h:327
void(* set_icon)(struct gui_window *gw, struct hlcache_handle *icon)
Set a favicon for a gui window.
Definition: window.h:280
nserror(* invalidate)(struct gui_window *gw, const struct rect *rect)
Invalidate an area of a window.
Definition: window.h:194
nserror(* event)(struct gui_window *gw, enum gui_window_event event)
Miscellaneous event occurred for a window.
Definition: window.h:254
void(* destroy)(struct gui_window *gw)
Destroy previously created gui window.
Definition: window.h:174
bool(* get_scroll)(struct gui_window *gw, int *sx, int *sy)
Get the scroll position of a browser window.
Definition: window.h:205
void(* create_form_select_menu)(struct gui_window *gw, struct form_control *control)
create a form select menu
Definition: window.h:335
void(* drag_save_object)(struct gui_window *gw, struct hlcache_handle *c, gui_save_type type)
object dragged to window
Definition: window.h:353
void(* console_log)(struct gui_window *gw, browser_window_console_source src, const char *msg, size_t msglen, browser_window_console_flags flags)
console logging happening.
Definition: window.h:374
nserror(* set_url)(struct gui_window *gw, struct nsurl *url)
Set the navigation url.
Definition: window.h:272
void(* set_status)(struct gui_window *g, const char *text)
Set the status bar message of a browser window.
Definition: window.h:288
void(* drag_save_selection)(struct gui_window *gw, const char *selection)
drag selection save
Definition: window.h:361
void(* place_caret)(struct gui_window *g, int x, int y, int height, const struct rect *clip)
Place the caret in a browser window.
Definition: window.h:307
void(* file_gadget_open)(struct gui_window *gw, struct hlcache_handle *hl, struct form_control *gadget)
Called when file chooser gadget is activated.
Definition: window.h:344
first entry in window list
Definition: gui.c:297
char * title
Definition: gui.h:153
High-level cache handle.
Definition: hlcache.c:66
Rectangle coordinates.
Definition: types.h:40
struct rect rect
Rectangle coordinates.
static nserror text(const struct redraw_context *ctx, const struct plot_font_style *fstyle, int x, int y, const char *text, size_t length)
Text plotting.
Definition: plot.c:978
static nserror clip(const struct redraw_context *ctx, const struct rect *clip)
Sets a clip rectangle for subsequent plot operations.
Definition: plot.c:357