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 31 struct browser_window; 32 struct form_control; 33 struct rect; 34 struct hlcache_handle; 35 struct nsurl; 36 37 enum gui_pointer_shape; 38 39 typedef enum gui_save_type { 40 GUI_SAVE_SOURCE, 41 GUI_SAVE_DRAW, 42 GUI_SAVE_PDF, 43 GUI_SAVE_TEXT, 44 GUI_SAVE_COMPLETE, 45 GUI_SAVE_OBJECT_ORIG, 46 GUI_SAVE_OBJECT_NATIVE, 47 GUI_SAVE_LINK_URI, 48 GUI_SAVE_LINK_URL, 49 GUI_SAVE_LINK_TEXT, 50 GUI_SAVE_HOTLIST_EXPORT_HTML, 51 GUI_SAVE_HISTORY_EXPORT_HTML, 52 GUI_SAVE_TEXT_SELECTION, 53 GUI_SAVE_CLIPBOARD_CONTENTS 54 } gui_save_type; 55 56 typedef enum { 57 GDRAGGING_NONE, 58 GDRAGGING_SCROLLBAR, 59 GDRAGGING_SELECTION, 60 GDRAGGING_OTHER 61 } gui_drag_type; 62 63 /** 64 * Window creation control flags. 65 */ 66 typedef 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 */ 72 } gui_window_create_flags; 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 */ 80 enum gui_window_event { 81 /** 82 * An empty event should never occur 83 */ 84 GW_EVENT_NONE = 0, 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 */ 93 GW_EVENT_UPDATE_EXTENT, 94 95 /** 96 * Remove the caret, if present. 97 */ 98 GW_EVENT_REMOVE_CARET, 99 100 /** 101 * start the navigation throbber. 102 */ 103 GW_EVENT_START_THROBBER, 104 105 /** 106 * stop the navigation throbber. 107 */ 108 GW_EVENT_STOP_THROBBER, 109 110 /** 111 * Starts drag scrolling of a browser window 112 */ 113 GW_EVENT_SCROLL_START, 114 115 /** 116 * Called when the gui_window has new content. 117 */ 118 GW_EVENT_NEW_CONTENT, 119 120 /** 121 * selection started 122 */ 123 GW_EVENT_START_SELECTION, 124 125 /** 126 * Page status has changed and so the padlock should be 127 * updated. 128 */ 129 GW_EVENT_PAGE_INFO_CHANGE, 130 }; 131 132 /** 133 * Graphical user interface window function table. 134 * 135 * function table implementing window operations 136 */ 137 struct gui_window_table { 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, 166 gui_window_create_flags flags); 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 */ 254 nserror (*event)(struct gui_window *gw, enum gui_window_event event); 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 */ 353 void (*drag_save_object)(struct gui_window *gw, struct hlcache_handle *c, gui_save_type type); 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, 375 browser_window_console_source src, 376 const char *msg, 377 size_t msglen, 378 browser_window_console_flags flags); 379 }; 380 381 #endif 382