NetSurf
toolbar.h
Go to the documentation of this file.
1/*
2 * Copyright 2005 Richard Wilson <info@tinct.net>
3 * Copyright 2010, 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 * Window toolbars (interface).
22 */
23
24#include <stdbool.h>
25#include "riscos/theme.h"
27#include "riscos/gui/throbber.h"
28#include "riscos/gui/url_bar.h"
29
30#ifndef _NETSURF_RISCOS_TOOLBAR_H_
31#define _NETSURF_RISCOS_TOOLBAR_H_
32
33typedef enum {
38
39/**
40 * Widget action types that the toolbar can pass on to clients.
41 */
42
43typedef enum {
48
49/**
50 * Union to hold the different widget action data that can be passed
51 * from widget via toolbar to client.
52 */
53
57};
58
59struct toolbar;
60
62 /** Call on theme update */
63 void (*theme_update)(void *, bool);
64
65 /** Call on bar size change */
66 void (*change_size)(void *);
67
68 /** Call to update button states */
69 void (*update_buttons)(void *);
70
71 /** Call to handle user actions */
73
74 /** Call to handle keypresses. */
75 bool (*key_press)(void *, wimp_key *);
76
77 /** Call on change to button order. */
78 void (*save_buttons)(void *, char *);
79};
80
81
82#define ro_toolbar_menu_option_shade(toolbar) \
83 (((toolbar) == NULL) || ro_toolbar_get_editing(toolbar))
84
85#define ro_toolbar_menu_buttons_tick(toolbar) \
86 (ro_toolbar_get_display_buttons(toolbar) || \
87 ro_toolbar_get_editing(toolbar))
88
89#define ro_toolbar_menu_url_tick(toolbar) \
90 (ro_toolbar_get_display_url(toolbar))
91
92#define ro_toolbar_menu_throbber_tick(toolbar) \
93 (ro_toolbar_get_display_throbber(toolbar))
94
95#define ro_toolbar_menu_edit_shade(toolbar) ((toolbar) == NULL)
96
97#define ro_toolbar_menu_edit_tick(toolbar) (ro_toolbar_get_editing(toolbar))
98
99
100/* The new toolbar API */
101
102
103/**
104 * Initialise the RISC OS toolbar widget.
105 */
106
107void ro_toolbar_init(void);
108
109
110/**
111 * Create a new toolbar, ready to have widgets added and to be attached to
112 * a window. If a parent window is supplied, then the toolbar module will
113 * handle the window attachments; if NULL, it is up to the client to sort this
114 * out for itself.
115 *
116 * \param *descriptor The theme to apply, or NULL for the default.
117 * \param parent The window to attach the toolbar to, or NULL.
118 * \param style The theme style to apply.
119 * \param bar_flags Toolbar flags for the new bar.
120 * \param *callbacks A client callback block, or NULL for none.
121 * \param *client_data A data pointer to pass to callbacks, or NULL.
122 * \param *help The Help token prefix for interactive help.
123 * \return The handle of the new bar, or NULL on failure.
124 */
125
126struct toolbar *ro_toolbar_create(struct theme_descriptor *descriptor,
127 wimp_w parent, theme_style style, toolbar_flags bar_flags,
128 const struct toolbar_callbacks *callbacks, void *client_data,
129 const char *help);
130
131
132/**
133 * Add a button bar to a toolbar, and configure the buttons.
134 *
135 * \param *toolbar The toolbar to take the button bar.
136 * \param buttons[] The button definitions.
137 * \param *button_order The initial button order to use.
138 * \return true if the action completed; else false.
139 */
140
142 const struct button_bar_buttons buttons[], char *button_order);
143
144
145/**
146 * Add a throbber to a toolbar.
147 *
148 * \param *toolbar The toolbar to take the throbber.
149 * \return true if the action completed; else false.
150 */
151
153
154
155/**
156 * Add a URL bar to a toolbar.
157 *
158 * \param *toolbar The toolbar to take the URL bar.
159 * \return true if the action completed; else false.
160 */
161
163
164
165/**
166 * (Re-)build a toolbar to use the specified (or current) theme. If false
167 * is returned, the toolbar may not be complete and should be deleted.
168 *
169 * \param *toolbar The toolbar to rebuild.
170 * \return true if the action was successful; else false.
171 */
172
174
175
176/**
177 * Attach or re-attach a toolbar to its parent window.
178 *
179 * \param *toolbar The toolbar to attach.
180 * \param parent The window to attach the toolbar to.
181 * \return true if the operation succeeded; else false.
182 */
183
184bool ro_toolbar_attach(struct toolbar *toolbar, wimp_w parent);
185
186
187/**
188 * Process a toolbar, updating its contents for a size or content change.
189 *
190 * \param *toolbar The toolbar to update.
191 * \param width The width to reformat to, or -1 to use parent.
192 * \param reformat true to force a widget reflow; else false.
193 * \return true if the operation succeeded; else false.
194 */
195
196bool ro_toolbar_process(struct toolbar *toolbar, int width, bool reformat);
197
198
199/**
200 * Destroy a toolbar after use.
201 *
202 * \param *toolbar The toolbar to destroy.
203 */
204
206
207
208/**
209 * Change the client data associated with a toolbar's callbacks.
210 *
211 * \param *toolbar the toolbar whose data is to be updated.
212 * \param *client_data the new client data, or NULL for none.
213 */
214
216
217
218/**
219 * Force the update of all toolbars buttons to reflect the current state.
220 */
221
223
224
225/**
226 * Refresh a toolbar after it has been updated
227 *
228 * \param toolbar the toolbar to update
229 */
230
232
233
234/**
235 * Force the update of all toolbars to reflect the application of a new theme.
236 */
237
238void ro_toolbar_theme_update(void);
239
240
241/**
242 * Find the toolbar associated with a given RO window handle.
243 *
244 * \param w the window handle to look up.
245 * \return the toolbar handle, or NULL if a match wasn't found.
246 */
247
249
250
251/**
252 * Find the toolbar using a given RO window handle for its pane.
253 *
254 * \param w the window (pane) handle to look up.
255 * \return the toolbar handle, or NULL if a match wasn't found.
256 */
257
258struct toolbar *ro_toolbar_window_lookup(wimp_w w);
259
260
261/**
262 * Return the RO window handle of the parent window for a toolbar.
263 *
264 * \param *toolbar the toolbar to look up.
265 * \return the RO window handle of the parent.
266 */
267
269
270
271/**
272 * Return the RO window handle of a toolbar.
273 *
274 * \param *toolbar the toolbar to look up.
275 * \return the RO window handle of the bar.
276 */
277
279
280
281/**
282 * Return the current height of a toolbar, allowing for available window
283 * space.
284 *
285 * \param *toolbar The toolbar of interest.
286 * \return The current toolbar height in OS units.
287 */
288
290
291
292/**
293 * Return the full height that a toolbar could grow to, if space is available.
294 *
295 * \param *toolbar The toolbar of interest.
296 * \return The full toolbar height in OS units.
297 */
298
300
301
302/**
303 * Starts a toolbar throbber, if there is one active.
304 *
305 * \param *toolbar the toolbar to start throbbing.
306 */
308
309
310/**
311 * Stops a toolbar throbber, if there is one active.
312 *
313 * \param *toolbar the toolbar to stop throbbing.
314 */
315
317
318
319/**
320 * Animate a toolbar throbber, if there is one active.
321 *
322 * \param *toolbar the toolbar to throb.
323 */
324
325void ro_toolbar_throb(struct toolbar *toolbar);
326
327/**
328 * Change the arrangement of buttons and spacers on a button bar within a
329 * toolbar.
330 *
331 * \param *toolbar The toolbar to change.
332 * \param order[] The new button configuration.
333 * \return true of the order was updated; else false.
334 */
335
336bool ro_toolbar_set_button_order(struct toolbar *toolbar, char order[]);
337
338
339/**
340 * Set the shaded state of a toolbar button.
341 *
342 * \param *toolbar the toolbar to update.
343 * \param action the button action to update.
344 * \param shaded true if the button should be shaded; else false.
345 */
346
348 button_bar_action action, bool shaded);
349
350/**
351 * Give a toolbar input focus, placing the caret into the URL bar if one is
352 * present. Currently a toolbar can only accept focus if it has a URL bar.
353 *
354 * \param *toolbar The toolbar to take the caret.
355 * \return true if the caret was taken; else false.
356 */
357
359
360
361/**
362 * Set the content of a toolbar's URL field.
363 *
364 * \param *toolbar the toolbar to update.
365 * \param *url the new url to insert.
366 * \param is_utf8 true if the string is in utf8 encoding; false
367 * if it is in local encoding.
368 * \param set_caret true if the caret should be placed in the field;
369 * else false.
370 */
371
372void ro_toolbar_set_url(struct toolbar *toolbar, const char *url,
373 bool is_utf8, bool set_caret);
374
375
376/**
377 * Return a pointer to the URL contained in a browser toolbar. If the toolbar
378 * doesn't have a URL field, then NULL is returned instead.
379 *
380 * \param *toolbar The toolbar to look up the URL from.
381 * \return pointer to the URL, or NULL.
382 */
383
384const char *ro_toolbar_get_url(struct toolbar *toolbar);
385
386
387/**
388 * Update the state of the URL Bar hotlist icons in all open toolbars.
389 */
390
392
393
394/**
395 * Update the state of a toolbar's URL Bar hotlist icon to reflect any changes
396 * to the URL or the hotlist contents.
397 *
398 * \param *toolbar The toolbar to update.
399 */
400
402
403
404/**
405 * Return the current work area coordinates of the URL and favicon field's
406 * bounding box.
407 *
408 * \param *toolbar The toolbar to look up.
409 * \param *extent Return the coordinates.
410 * \return true if successful; else false.
411 */
412
413bool ro_toolbar_get_url_field_extent(struct toolbar *toolbar, os_box *extent);
414
415
416/**
417 * Update the favicon in a browser window toolbar to the supplied content, or
418 * revert to using filetype-based icons.
419 *
420 * \param *toolbar The toolbar to refresh.
421 * \param *h The new favicon to use, or NULL for none.
422 */
423
425 struct hlcache_handle *h);
426
427
428/**
429 * Update the favicon in a browser window toolbar to reflect the RISC OS
430 * filetype of the content within the supplied window. If the toolbar
431 * currently has a site favicon set, then this call will be ignored.
432 *
433 * \param *toolbar The toolbar to refresh.
434 * \param *g The gui window to set content favicon for.
435 */
436
438 struct gui_window *g);
439
440
441/**
442 * Update the state of the URL suggestion pop-up menu icon on a toolbar.
443 *
444 * \param *toolbar The toolbar to update.
445 */
446
448
449
450/**
451 * Set the display button bar state for a toolbar.
452 *
453 * \param *toolbar the toolbar to update.
454 * \param display true to display the button bar; else false.
455 */
456
457void ro_toolbar_set_display_buttons(struct toolbar *toolbar, bool display);
458
459
460/**
461 * Set the display URL bar state for a toolbar.
462 *
463 * \param *toolbar the toolbar to update.
464 * \param display true to display the URL bar; else false.
465 */
466
467void ro_toolbar_set_display_url(struct toolbar *toolbar, bool display);
468
469
470/**
471 * Set the display throbber state for a toolbar.
472 *
473 * \param *toolbar the toolbar to update.
474 * \param display true to display the throbber; else false.
475 */
476
477void ro_toolbar_set_display_throbber(struct toolbar *toolbar, bool display);
478
479
480/**
481 * Return true or false depending on whether the given toolbar is set to
482 * display the button bar.
483 *
484 * \param *toolbar the toolbar of interest.
485 * \return true if the toolbar exists and the button bar is
486 * shown; else false.
487 */
488
490
491
492/**
493 * Return true or false depending on whether the given toolbar is set to
494 * display the URL bar.
495 *
496 * \param *toolbar the toolbar of interest.
497 * \return true if the toolbar exists and the URL bar is
498 * shown; else false.
499 */
500
502
503
504/**
505 * Return true or false depending on whether the given toolbar is set to
506 * display the throbber.
507 *
508 * \param *toolbar the toolbar of interest.
509 * \return true if the toolbar exists and the throbber is
510 * shown; else false.
511 */
512
514
515
516/**
517 * Return true or false depending on whether the given toolbar is currently
518 * being edited.
519 *
520 * \param *toolbar the toolbar of interest.
521 * \return true if the toolbar exists and is beng edited;
522 * else false.
523 */
524
526
527
528/**
529 * Toggle toolbar edit mode on the given toolbar. Only a button bar can be
530 * edited, so edit mode can only be toggled if there's an editor button
531 * bar defined.
532 *
533 * \param *toolbar The toolbar to be toggled.
534 * \return true if the action was successful; false if
535 * the action failed and the toolbar was destroyed.
536 */
537
539
540
541/**
542 * Update the page information indicator.
543 *
544 * \param toolbar the toolbar to update the page info in.
545 */
547
548
549#endif
550
Button bars (interface).
button_bar_action
Definition: button_bar.h:32
wimp_w parent
Definition: dialog.c:88
Window themes(interface).
theme_style
Theme styles, collecting groups of attributes for different locations.
Definition: theme.h:31
Throbber (interface).
int width
Definition: gui.c:160
void ro_toolbar_update_hotlist(struct toolbar *toolbar)
Update the state of a toolbar's URL Bar hotlist icon to reflect any changes to the URL or the hotlist...
Definition: toolbar.c:1645
void ro_toolbar_theme_update(void)
Force the update of all toolbars to reflect the application of a new theme.
Definition: toolbar.c:1435
wimp_w ro_toolbar_get_window(struct toolbar *toolbar)
Return the RO window handle of a toolbar.
Definition: toolbar.c:1511
bool ro_toolbar_add_buttons(struct toolbar *toolbar, const struct button_bar_buttons buttons[], char *button_order)
Add a button bar to a toolbar, and configure the buttons.
Definition: toolbar.c:273
int ro_toolbar_height(struct toolbar *toolbar)
Return the current height of a toolbar, allowing for available window space.
Definition: toolbar.c:1519
toolbar_action_type
Widget action types that the toolbar can pass on to clients.
Definition: toolbar.h:43
@ TOOLBAR_ACTION_BUTTON
Definition: toolbar.h:45
@ TOOLBAR_ACTION_NONE
Definition: toolbar.h:44
@ TOOLBAR_ACTION_URL
Definition: toolbar.h:46
bool ro_toolbar_get_display_throbber(struct toolbar *toolbar)
Return true or false depending on whether the given toolbar is set to display the throbber.
Definition: toolbar.c:1763
void ro_toolbar_destroy(struct toolbar *toolbar)
Destroy a toolbar after use.
Definition: toolbar.c:947
void ro_toolbar_update_all_buttons(void)
Force the update of all toolbars buttons to reflect the current state.
Definition: toolbar.c:1387
int ro_toolbar_full_height(struct toolbar *toolbar)
Return the full height that a toolbar could grow to, if space is available.
Definition: toolbar.c:1527
bool ro_toolbar_process(struct toolbar *toolbar, int width, bool reformat)
Process a toolbar, updating its contents for a size or content change.
Definition: toolbar.c:588
void ro_toolbar_set_site_favicon(struct toolbar *toolbar, struct hlcache_handle *h)
Update the favicon in a browser window toolbar to the supplied content, or revert to using filetype-b...
Definition: toolbar.c:1669
bool ro_toolbar_get_url_field_extent(struct toolbar *toolbar, os_box *extent)
Return the current work area coordinates of the URL and favicon field's bounding box.
Definition: toolbar.c:1656
bool ro_toolbar_attach(struct toolbar *toolbar, wimp_w parent)
Attach or re-attach a toolbar to its parent window.
Definition: toolbar.c:524
bool ro_toolbar_add_throbber(struct toolbar *toolbar)
Add a throbber to a toolbar.
Definition: toolbar.c:308
bool ro_toolbar_rebuild(struct toolbar *toolbar)
(Re-)build a toolbar to use the specified (or current) theme.
Definition: toolbar.c:346
void ro_toolbar_refresh(struct toolbar *toolbar)
Refresh a toolbar after it has been updated.
Definition: toolbar.c:1417
const char * ro_toolbar_get_url(struct toolbar *toolbar)
Return a pointer to the URL contained in a browser toolbar.
Definition: toolbar.c:1619
struct toolbar * ro_toolbar_window_lookup(wimp_w w)
Find the toolbar using a given RO window handle for its pane.
Definition: toolbar.c:1489
struct toolbar * ro_toolbar_create(struct theme_descriptor *descriptor, wimp_w parent, theme_style style, toolbar_flags bar_flags, const struct toolbar_callbacks *callbacks, void *client_data, const char *help)
Create a new toolbar, ready to have widgets added and to be attached to a window.
Definition: toolbar.c:219
void ro_toolbar_set_content_favicon(struct toolbar *toolbar, struct gui_window *g)
Update the favicon in a browser window toolbar to reflect the RISC OS filetype of the content within ...
Definition: toolbar.c:1680
void ro_toolbar_stop_throbbing(struct toolbar *toolbar)
Stops a toolbar throbber, if there is one active.
Definition: toolbar.c:1543
void ro_toolbar_set_display_buttons(struct toolbar *toolbar, bool display)
Set the display button bar state for a toolbar.
Definition: toolbar.c:1703
bool ro_toolbar_get_editing(struct toolbar *toolbar)
Return true or false depending on whether the given toolbar is currently being edited.
Definition: toolbar.c:1772
void ro_toolbar_set_url(struct toolbar *toolbar, const char *url, bool is_utf8, bool set_caret)
Set the content of a toolbar's URL field.
Definition: toolbar.c:1609
bool ro_toolbar_toggle_edit(struct toolbar *toolbar)
Toggle toolbar edit mode on the given toolbar.
Definition: toolbar.c:1780
bool ro_toolbar_get_display_url(struct toolbar *toolbar)
Return true or false depending on whether the given toolbar is set to display the URL bar.
Definition: toolbar.c:1754
void ro_toolbar_init(void)
Initialise the RISC OS toolbar widget.
Definition: toolbar.c:199
void ro_toolbar_page_info_change(struct toolbar *toolbar)
Update the page information indicator.
Definition: toolbar.c:1551
void ro_toolbar_set_display_throbber(struct toolbar *toolbar, bool display)
Set the display throbber state for a toolbar.
Definition: toolbar.c:1731
void ro_toolbar_update_client_data(struct toolbar *toolbar, void *client_data)
Change the client data associated with a toolbar's callbacks.
Definition: toolbar.c:1378
bool ro_toolbar_set_button_order(struct toolbar *toolbar, char order[])
Change the arrangement of buttons and spacers on a button bar within a toolbar.
Definition: toolbar.c:1570
void ro_toolbar_update_urlsuggest(struct toolbar *toolbar)
Update the state of the URL suggestion pop-up menu icon on a toolbar.
Definition: toolbar.c:1692
struct toolbar * ro_toolbar_parent_window_lookup(wimp_w w)
Find the toolbar associated with a given RO window handle.
Definition: toolbar.c:1475
void ro_toolbar_throb(struct toolbar *toolbar)
Animate a toolbar throbber, if there is one active.
Definition: toolbar.c:1561
void ro_toolbar_set_button_shaded_state(struct toolbar *toolbar, button_bar_action action, bool shaded)
Set the shaded state of a toolbar button.
Definition: toolbar.c:1586
void ro_toolbar_update_all_hotlists(void)
Update the state of the URL Bar hotlist icons in all open toolbars.
Definition: toolbar.c:1630
toolbar_flags
Definition: toolbar.h:33
@ TOOLBAR_FLAGS_EDIT
Definition: toolbar.h:36
@ TOOLBAR_FLAGS_NONE
Definition: toolbar.h:34
@ TOOLBAR_FLAGS_DISPLAY
Definition: toolbar.h:35
void ro_toolbar_set_display_url(struct toolbar *toolbar, bool display)
Set the display URL bar state for a toolbar.
Definition: toolbar.c:1717
bool ro_toolbar_take_caret(struct toolbar *toolbar)
Give a toolbar input focus, placing the caret into the URL bar if one is present.
Definition: toolbar.c:1598
bool ro_toolbar_get_display_buttons(struct toolbar *toolbar)
Return true or false depending on whether the given toolbar is set to display the button bar.
Definition: toolbar.c:1745
wimp_w ro_toolbar_get_parent_window(struct toolbar *toolbar)
Return the RO window handle of the parent window for a toolbar.
Definition: toolbar.c:1503
bool ro_toolbar_add_url(struct toolbar *toolbar)
Add a URL bar to a toolbar.
Definition: toolbar.c:327
void ro_toolbar_start_throbbing(struct toolbar *toolbar)
Starts a toolbar throbber, if there is one active.
Definition: toolbar.c:1535
static BList * callbacks
List of all callbacks.
Definition: schedule.cpp:44
first entry in window list
Definition: gui.c:297
High-level cache handle.
Definition: hlcache.c:66
bool(* key_press)(void *, wimp_key *)
Call to handle keypresses.
Definition: toolbar.h:75
void(* save_buttons)(void *, char *)
Call on change to button order.
Definition: toolbar.h:78
void(* theme_update)(void *, bool)
Call on theme update.
Definition: toolbar.h:63
void(* update_buttons)(void *)
Call to update button states.
Definition: toolbar.h:69
void(* user_action)(void *, toolbar_action_type, union toolbar_action)
Call to handle user actions.
Definition: toolbar.h:72
void(* change_size)(void *)
Call on bar size change.
Definition: toolbar.h:66
struct button_bar * buttons
Details for the button bar.
Definition: toolbar.c:96
theme_style style
Definition: toolbar.c:80
void * client_data
Definition: toolbar.c:113
struct url_bar * url
Details for the URL bar.
Definition: toolbar.c:101
Union to hold the different widget action data that can be passed from widget via toolbar to client.
Definition: toolbar.h:54
url_bar_action url
Definition: toolbar.h:56
button_bar_action button
Definition: toolbar.h:55
URL bars (interface).
url_bar_action
Definition: url_bar.h:33