NetSurf
url_bar.h
Go to the documentation of this file.
1/*
2 * Copyright 2005 Richard Wilson <info@tinct.net>
3 * Copyright 2011 Stephen Fryatt <stevef@netsurf-browser.org>
4 *
5 * This file is part of NetSurf, http://www.netsurf-browser.org/
6 *
7 * NetSurf is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; version 2 of the License.
10 *
11 * NetSurf is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20/** \file
21 * URL bars (interface).
22 */
23
24#ifndef _NETSURF_RISCOS_URLBAR_H_
25#define _NETSURF_RISCOS_URLBAR_H_
26
27#include <stdbool.h>
28#include "riscos/menus.h"
29#include "riscos/theme.h"
30
31/* A list of possible URL bar actions. */
32
33typedef enum {
34 TOOLBAR_URL_NONE = 0, /* Special case: no action */
42
43struct url_bar;
44struct hlcache_handle;
45struct gui_window;
46
47/**
48 * Initialise the url bar module.
49 *
50 * \return True iff success, else false.
51 */
52
53bool ro_gui_url_bar_init(void);
54
55/**
56 * Finalise the url bar module
57 */
58
59void ro_gui_url_bar_fini(void);
60
61/**
62 * Create a new url bar widget.
63 *
64 * \param *theme The theme to apply (or NULL for the default).
65 * \return A url bar handle, or NULL on failure.
66 */
67
69
70
71/**
72 * Place a URL bar into a toolbar window and initialise any theme-specific
73 * settings. Any previous incarnation of the bar will be forgotten: this
74 * is for use when a new toolbar is being created, or when a toolbar has been
75 * deleted and rebuilt following a theme change.
76 *
77 * \param *url_bar The URL bar to rebuild.
78 * \param *theme The theme to apply (or NULL for current).
79 * \param style The theme style to apply.
80 * \param window The window that the bar is in.
81 * \param display true if the bar should be for display only.
82 * \param shaded true if the bar should be shaded; else false.
83 * \return true on success; else false.
84 */
85
87 struct theme_descriptor *theme, theme_style style,
88 wimp_w window, bool display, bool shaded);
89
90
91/**
92 * Destroy a url bar widget.
93 *
94 * \param *url_bar The url bar to destroy.
95 */
96
98
99
100/**
101 * Return the MINIMUM dimensions required by the URL bar, in RO units,
102 * allowing for the current theme.
103 *
104 * \param *url_bar The URL bar of interest.
105 * \param *width Return the required width.
106 * \param *height Return the required height.
107 * \return true if values are returned; else false.
108 */
109
111 int *width, int *height);
112
113
114/**
115 * Set or update the dimensions to be used by the URL bar, in RO units.
116 * If these are greater than the minimum required, the URL bar will fill
117 * the extended space; if less, the call will fail.
118 *
119 * \param *url_bar The URL bar to update.
120 * \param x0 The minimum X window position.
121 * \param y0 The minimum Y window position.
122 * \param x1 The maximum X window position.
123 * \param y1 The maximum Y window position.
124 * \return true if size updated; else false.
125 */
126
128 int x0, int y0, int x1, int y1);
129
130
131/**
132 * Show or hide a URL bar.
133 *
134 * \param *url_bar The URL bar to hide.
135 * \param hide true to hide the bar; false to show it.
136 * \return true if successful; else false.
137 */
138
139bool ro_gui_url_bar_hide(struct url_bar *url_bar, bool hide);
140
141
142/**
143 * Handle redraw event rectangles in a URL bar.
144 *
145 * \param *url_bar The URL bar to use.
146 * \param *redraw The Wimp redraw rectangle to process.
147 */
148
149void ro_gui_url_bar_redraw(struct url_bar *url_bar, wimp_draw *redraw);
150
151
152/**
153 * Handle mouse clicks in a URL bar.
154 *
155 * \param *url_bar The URL bar to use.
156 * \param *pointer The Wimp mouse click event data.
157 * \param *state The toolbar window state.
158 * \param *action Returns the selected action, or
159 * TOOLBAR_URL_NONE.
160 * \return true if the event was handled exclusively;
161 * else false.
162 */
163
165 wimp_pointer *pointer, wimp_window_state *state,
166 url_bar_action *action);
167
168
169/**
170 * Process offered menu prepare events from the parent window.
171 *
172 * \param *url_bar The URL bar in question.
173 * \param i The icon owning the menu.
174 * \param *menu The menu to be prepared.
175 * \param *pointer The Wimp Pointer data from the event.
176 * \return true if the event is claimed; else false.
177 */
178
179bool ro_gui_url_bar_menu_prepare(struct url_bar *url_bar, wimp_i i,
180 wimp_menu *menu, wimp_pointer *pointer);
181
182
183/**
184 * Process offered menu select events from the parent window.
185 *
186 * \param *url_bar The URL bar in question.
187 * \param i The icon owning the menu.
188 * \param *menu The menu to be prepared.
189 * \param *selection The wimp menu selection data.
190 * \param action The selected menu action.
191 * \return true if the event is claimed; else false.
192 */
193
194bool ro_gui_url_bar_menu_select(struct url_bar *url_bar, wimp_i i,
195 wimp_menu *menu, wimp_selection *selection, menu_action action);
196
197
198/**
199 * Translate mouse data into an interactive help message for the URL bar.
200 *
201 * \param *url_bar The URL bar to process.
202 * \param i The wimp icon under the pointer.
203 * \param *mouse The mouse position.
204 * \param *state The toolbar window state.
205 * \param buttons The mouse button state.
206 * \param **suffix Return a help token suffix, or "" for none.
207 * \return true if handled exclusively; else false.
208 */
209
210bool ro_gui_url_bar_help_suffix(struct url_bar *url_bar, wimp_i i,
211 os_coord *mouse, wimp_window_state *state,
212 wimp_mouse_state buttons, const char **suffix);
213
214
215/**
216 * Give a URL bar input focus.
217 *
218 * \param *url_bar The URL bar to give focus to.
219 * \return true if successful; else false.
220 */
221
223
224
225/**
226 * Set the content of a URL Bar field.
227 *
228 * \param *url_bar The URL Bar to update.
229 * \param *url The new url to insert.
230 * \param is_utf8 true if the string is in utf8 encoding; false
231 * if it is in local encoding.
232 * \param set_caret true if the caret should be placed in the field;
233 * else false.
234 */
235
236void ro_gui_url_bar_set_url(struct url_bar *url_bar, const char *url,
237 bool is_utf8, bool set_caret);
238
239
240/**
241 * Update the state of a URL Bar's hotlist icon to reflect any changes to the
242 * URL or the contents of the hotlist.
243 *
244 * \param *url_bar The URL Bar to update.
245 */
246
248
249
250/**
251 * Return a pointer to the URL contained in a URL bar.
252 *
253 * \param *url_bar The URL Bar to look up the URL from.
254 * \return Pointer to the URL, or NULL.
255 */
256
257const char *ro_gui_url_bar_get_url(struct url_bar *url_bar);
258
259
260/**
261 * Return the current work area coordinates of the URL and favicon field's
262 * bounding box.
263 *
264 * \param *url_bar The URL bar to check.
265 * \param *extent Returns the field extent.
266 * \return true if successful; else false.
267 */
268
270
271
272/**
273 * Test a pointer click to see if it was in the URL bar's text field.
274 *
275 * \param url_bar The URL Bar to test.
276 * \param pointer The pointer event data to test.
277 * \return true if the click was in the field; else false.
278 */
279
281 wimp_pointer *pointer);
282
283
284/**
285 * Test a keypress to see if it was in the URL bar's text field.
286 *
287 * \param url_bar The URL Bar to test.
288 * \param key The key pressed
289 * \return true if the keypress was in the field; else false.
290 */
291
293 wimp_key *key);
294
295
296/**
297 * Set the favicon to a site supplied favicon image, or remove the image
298 * and return to using filetype-based icons.
299 *
300 * \param *url_bar The URL Bar to update the favicon on.
301 * \param *h The content to use, or NULL to unset.
302 * \return true if successful; else false.
303 */
304
306 struct hlcache_handle *h);
307
308
309/**
310 * Set the favicon to a RISC OS filetype sprite based on the type of the
311 * content within the supplied window.
312 *
313 * \param *url_bar The URL Bar to update the favicon on.
314 * \param *g The window with the content to use.
315 * \return true if successful; else false.
316 */
317
319 struct gui_window *g);
320
321
322/**
323 * Update the state of the URL suggestion pop-up menu icon on a URL bar.
324 *
325 * \param *url_bar The URL bar to update.
326 * \return true if successful; else false.
327 */
329
330
331/**
332 * Update the page info icon
333 *
334 * \param url_bar The URL bar to update.
335 * \return true if successful; else false.
336 */
338
339
340#endif
341
menu_action
Definition: scaffolding.h:77
Window themes(interface).
theme_style
Theme styles, collecting groups of attributes for different locations.
Definition: theme.h:31
int width
Definition: gui.c:160
int height
Definition: gui.c:161
first entry in window list
Definition: gui.c:297
High-level cache handle.
Definition: hlcache.c:66
Definition: theme.h:64
os_box extent
Definition: url_bar.c:70
bool shaded
Definition: url_bar.c:77
bool display
Definition: url_bar.c:76
wimp_w window
The window and icon details.
Definition: url_bar.c:69
bool ro_gui_url_bar_test_for_text_field_click(struct url_bar *url_bar, wimp_pointer *pointer)
Test a pointer click to see if it was in the URL bar's text field.
Definition: url_bar.c:1344
void ro_gui_url_bar_fini(void)
Finalise the url bar module.
Definition: url_bar.c:1603
bool ro_gui_url_bar_page_info_change(struct url_bar *url_bar)
Update the page info icon.
Definition: url_bar.c:1455
bool ro_gui_url_bar_get_url_extent(struct url_bar *url_bar, os_box *extent)
Return the current work area coordinates of the URL and favicon field's bounding box.
Definition: url_bar.c:1309
bool ro_gui_url_bar_take_caret(struct url_bar *url_bar)
Give a URL bar input focus.
Definition: url_bar.c:1134
bool ro_gui_url_bar_set_extent(struct url_bar *url_bar, int x0, int y0, int x1, int y1)
Set or update the dimensions to be used by the URL bar, in RO units.
Definition: url_bar.c:677
url_bar_action
Definition: url_bar.h:33
@ TOOLBAR_URL_DRAG_FAVICON
Definition: url_bar.h:36
@ TOOLBAR_URL_ADJUST_PGINFO
Definition: url_bar.h:40
@ TOOLBAR_URL_NONE
Definition: url_bar.h:34
@ TOOLBAR_URL_SELECT_PGINFO
Definition: url_bar.h:39
@ TOOLBAR_URL_DRAG_URL
Definition: url_bar.h:35
@ TOOLBAR_URL_SELECT_HOTLIST
Definition: url_bar.h:37
@ TOOLBAR_URL_ADJUST_HOTLIST
Definition: url_bar.h:38
const char * ro_gui_url_bar_get_url(struct url_bar *url_bar)
Return a pointer to the URL contained in a URL bar.
Definition: url_bar.c:1280
void ro_gui_url_bar_redraw(struct url_bar *url_bar, wimp_draw *redraw)
Handle redraw event rectangles in a URL bar.
Definition: url_bar.c:744
bool ro_gui_url_bar_hide(struct url_bar *url_bar, bool hide)
Show or hide a URL bar.
Definition: url_bar.c:732
bool ro_gui_url_bar_menu_prepare(struct url_bar *url_bar, wimp_i i, wimp_menu *menu, wimp_pointer *pointer)
Process offered menu prepare events from the parent window.
Definition: url_bar.c:1013
void ro_gui_url_bar_set_url(struct url_bar *url_bar, const char *url, bool is_utf8, bool set_caret)
Set the content of a URL Bar field.
Definition: url_bar.c:1160
bool ro_gui_url_bar_get_dims(struct url_bar *url_bar, int *width, int *height)
Return the MINIMUM dimensions required by the URL bar, in RO units, allowing for the current theme.
Definition: url_bar.c:653
bool ro_gui_url_bar_set_site_favicon(struct url_bar *url_bar, struct hlcache_handle *h)
Set the favicon to a site supplied favicon image, or remove the image and return to using filetype-ba...
Definition: url_bar.c:1394
bool ro_gui_url_bar_init(void)
Initialise the url bar module.
Definition: url_bar.c:1578
bool ro_gui_url_bar_test_for_text_field_keypress(struct url_bar *url_bar, wimp_key *key)
Test a keypress to see if it was in the URL bar's text field.
Definition: url_bar.c:1360
void ro_gui_url_bar_update_hotlist(struct url_bar *url_bar)
Update the state of a URL Bar's hotlist icon to reflect any changes to the URL or the contents of the...
Definition: url_bar.c:1261
struct url_bar * ro_gui_url_bar_create(struct theme_descriptor *theme)
Create a new url bar widget.
Definition: url_bar.c:516
bool ro_gui_url_bar_rebuild(struct url_bar *url_bar, struct theme_descriptor *theme, theme_style style, wimp_w window, bool display, bool shaded)
Place a URL bar into a toolbar window and initialise any theme-specific settings.
Definition: url_bar.c:593
bool ro_gui_url_bar_set_content_favicon(struct url_bar *url_bar, struct gui_window *g)
Set the favicon to a RISC OS filetype sprite based on the type of the content within the supplied win...
Definition: url_bar.c:1508
bool ro_gui_url_bar_update_urlsuggest(struct url_bar *url_bar)
Update the state of the URL suggestion pop-up menu icon on a URL bar.
Definition: url_bar.c:1559
bool ro_gui_url_bar_help_suffix(struct url_bar *url_bar, wimp_i i, os_coord *mouse, wimp_window_state *state, wimp_mouse_state buttons, const char **suffix)
Translate mouse data into an interactive help message for the URL bar.
Definition: url_bar.c:1081
bool ro_gui_url_bar_menu_select(struct url_bar *url_bar, wimp_i i, wimp_menu *menu, wimp_selection *selection, menu_action action)
Process offered menu select events from the parent window.
Definition: url_bar.c:1034
bool ro_gui_url_bar_click(struct url_bar *url_bar, wimp_pointer *pointer, wimp_window_state *state, url_bar_action *action)
Handle mouse clicks in a URL bar.
Definition: url_bar.c:936
void ro_gui_url_bar_destroy(struct url_bar *url_bar)
Destroy a url bar widget.
Definition: url_bar.c:634