NetSurf
button_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 * Button bars (interface).
22 */
23
24#ifndef _NETSURF_RISCOS_BUTTONBAR_H_
25#define _NETSURF_RISCOS_BUTTONBAR_H_
26
27#include <stdbool.h>
28#include "riscos/theme.h"
29
30/* A list of possible toolbar actions. */
31
32typedef enum {
33 TOOLBAR_BUTTON_NONE = 0, /* Special case: no action */
61
62/* Button bar button source definitions.
63 *
64 * Help tokens are added to the help prefix for the given toolbar by the
65 * help system, and correspond to the hard-coded icon numbers that were
66 * assigned to the different buttons in the original toolbar implementation.
67 * If the Messages file can be updated, these can change to something more
68 * meaningful.
69 */
70
72 const char *icon; /**< The sprite used for the icon. */
73 button_bar_action select; /**< The action for select clicks. */
74 button_bar_action adjust; /**< The action for Adjust clicks. */
75 const char opt_key; /**< The char used in option strings. */
76 const char *help; /**< The interactive help token. */
77};
78
79/* \TODO -- Move these to the correct modules.
80 */
81
84 {"up", TOOLBAR_BUTTON_UP, TOOLBAR_BUTTON_UP_NEW, 'b', "11"},
86 {"stop", TOOLBAR_BUTTON_STOP, TOOLBAR_BUTTON_NONE, '2', "2"},
88 {"home", TOOLBAR_BUTTON_HOME, TOOLBAR_BUTTON_NONE, '4', "4"},
91 {"print", TOOLBAR_BUTTON_PRINT, TOOLBAR_BUTTON_NONE, '7', "7"},
93 {"scale", TOOLBAR_BUTTON_SCALE, TOOLBAR_BUTTON_NONE, '9', "9"},
94 {"search", TOOLBAR_BUTTON_SEARCH, TOOLBAR_BUTTON_NONE, 'a', "10"},
96};
97
98struct button_bar;
99
100
101/**
102 * Create a new button bar widget.
103 *
104 * \param *theme The theme to apply (or NULL for the default).
105 * \param buttons[] An array of button definitions for the bar.
106 * \return A button bar handle, or NULL on failure.
107 */
108
110 const struct button_bar_buttons buttons[]);
111
112
113/**
114 * Link two button bars together
115 *
116 * Join two button bars the target being the active bar, and the
117 * source being the editing bar used to supply valid buttons. The bars are
118 * checked to ensure that they are not already part of an edit pair, but are
119 * not checked for button-compatibility.
120 *
121 * \param target The target button bar.
122 * \param source The source button bar.
123 * \param refresh The refresh callback.
124 * \param client_data context passed to the refresh callback
125 * \return true if successful; else false.
126 */
127
128bool ro_gui_button_bar_link_editor(struct button_bar *target,
129 struct button_bar *source, void (* refresh)(void *),
130 void *client_data);
131
132/**
133 * Place a button bar into a toolbar window and initialise any theme-specific
134 * settings. Any previous incarnation of the bar will be forgotten: this
135 * is for use when a new toolbar is being created, or when a toolbar has been
136 * deleted and rebuilt following a theme change.
137 *
138 * \param *button_bar The button bar to rebuild.
139 * \param *theme The theme to apply (or NULL for current).
140 * \param style The theme style to apply.
141 * \param window The window that the bar is in.
142 * \param edit The edit mode of the button bar.
143 * \return true on success; else false.
144 */
145
147 struct theme_descriptor *theme, theme_style style,
148 wimp_w window, bool edit);
149
150
151/**
152 * Arrange buttons on a button bar, using an order string to specify the
153 * required button and separator layout.
154 *
155 * \param *button_bar The button bar to update.
156 * \param order[] The button order configuration string.
157 * \return true if successful; else false.
158 */
159
161 char order[]);
162
163
164/**
165 * Destroy a button bar widget.
166 *
167 * \param *button_bar The button bar to destroy.
168 */
169
171
172
173/**
174 * Return the MINIMUM dimensions required by the button bar, in RO units,
175 * allowing for the current theme.
176 *
177 * \param *button_bar The button bar of interest.
178 * \param *width Return the required width.
179 * \param *height Return the required height.
180 * \return true if values are returned; else false.
181 */
182
184 int *width, int *height);
185
186
187/**
188 * Set or update the dimensions to be used by the button bar, in RO units.
189 * If these are greater than the minimum required, the button bar will fill
190 * the extended space; if less, the call will fail.
191 *
192 * \param *button_bar The button bar to update.
193 * \param x0 The minimum X window position.
194 * \param y0 The minimum Y window position.
195 * \param x1 The maximum X window position.
196 * \param y1 The maximum Y window position.
197 * \return true if size updated; else false.
198 */
199
201 int x0, int y0, int x1, int y1);
202
203
204/**
205 * Show or hide a button bar.
206 *
207 * \param *button_bar The button bar to hide.
208 * \param hide true to hide the bar; false to show it.
209 * \return true if successful; else false.
210 */
211
212bool ro_gui_button_bar_hide(struct button_bar *button_bar, bool hide);
213
214
215/**
216 * Shade or unshade a button in a bar corresponding to the given action.
217 *
218 * \param *button_bar The button bar to update.
219 * \param action The action to update.
220 * \param shaded true to shade the button; false to unshade.
221 * \return true if successful; else false.
222 */
223
225 button_bar_action action, bool shaded);
226
227
228/**
229 * Handle redraw event rectangles in a button bar.
230 *
231 * \param *button_bar The button bar to use.
232 * \param *redraw The Wimp redraw rectangle to process.
233 */
234
236 wimp_draw *redraw);
237
238
239/**
240 * Handle mouse clicks in a button bar.
241 *
242 * \param *button_bar The button bar to use.
243 * \param *pointer The Wimp mouse click event data.
244 * \param *state The toolbar window state.
245 * \param *action Returns the selected action, or
246 * TOOLBAR_BUTTON_NONE.
247 * \return true if the event was handled exclusively;
248 * else false.
249 */
250
252 wimp_pointer *pointer, wimp_window_state *state,
253 button_bar_action *action);
254
255
256/**
257 * Translate mouse data into an interactive help message for a button bar.
258 *
259 * \param *button_bar The button bar to process.
260 * \param i The wimp icon under the pointer.
261 * \param *mouse The mouse position.
262 * \param *state The toolbar window state.
263 * \param buttons The mouse button state.
264 * \param **suffix Return a help token suffix, or "" for none.
265 * \return true if handled exclusively; else false.
266 */
267
269 os_coord *mouse, wimp_window_state *state,
270 wimp_mouse_state buttons, const char **suffix);
271
272
273/**
274 * Return a config string reflecting the configured order of buttons
275 * and spacers. The string is allocated with malloc(), and should be
276 * free()d after use.
277 *
278 * \param *button_bar The button bar of interest.
279 * \return Pointer to a config string, or NULL on failure.
280 */
281
283
284#endif
285
void ro_gui_button_bar_destroy(struct button_bar *button_bar)
Destroy a button bar widget.
Definition: button_bar.c:395
bool ro_gui_button_bar_help_suffix(struct button_bar *button_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 a button bar.
Definition: button_bar.c:826
bool ro_gui_button_bar_arrange_buttons(struct button_bar *button_bar, char order[])
Arrange buttons on a button bar, using an order string to specify the required button and separator l...
Definition: button_bar.c:303
button_bar_action
Definition: button_bar.h:32
@ TOOLBAR_BUTTON_BOOKMARK_OPEN
Definition: button_bar.h:49
@ TOOLBAR_BUTTON_SEARCH
Definition: button_bar.h:52
@ TOOLBAR_BUTTON_HISTORY_GLOBAL
Definition: button_bar.h:45
@ TOOLBAR_BUTTON_SCALE
Definition: button_bar.h:51
@ TOOLBAR_BUTTON_HOME
Definition: button_bar.h:43
@ TOOLBAR_BUTTON_HISTORY_LOCAL
Definition: button_bar.h:44
@ TOOLBAR_BUTTON_NONE
Definition: button_bar.h:33
@ TOOLBAR_BUTTON_CLOSE
Definition: button_bar.h:57
@ TOOLBAR_BUTTON_LAUNCH
Definition: button_bar.h:58
@ TOOLBAR_BUTTON_BACK_NEW
Definition: button_bar.h:35
@ TOOLBAR_BUTTON_UP
Definition: button_bar.h:36
@ TOOLBAR_BUTTON_SAVE_COMPLETE
Definition: button_bar.h:47
@ TOOLBAR_BUTTON_DELETE
Definition: button_bar.h:53
@ TOOLBAR_BUTTON_BACK
Definition: button_bar.h:34
@ TOOLBAR_BUTTON_FORWARD_NEW
Definition: button_bar.h:39
@ TOOLBAR_BUTTON_BOOKMARK_ADD
Definition: button_bar.h:50
@ TOOLBAR_BUTTON_RELOAD
Definition: button_bar.h:41
@ TOOLBAR_BUTTON_COLLAPSE
Definition: button_bar.h:55
@ TOOLBAR_BUTTON_SAVE_SOURCE
Definition: button_bar.h:46
@ TOOLBAR_BUTTON_CREATE
Definition: button_bar.h:59
@ TOOLBAR_BUTTON_UP_NEW
Definition: button_bar.h:37
@ TOOLBAR_BUTTON_FORWARD
Definition: button_bar.h:38
@ TOOLBAR_BUTTON_RELOAD_ALL
Definition: button_bar.h:42
@ TOOLBAR_BUTTON_PRINT
Definition: button_bar.h:48
@ TOOLBAR_BUTTON_OPEN
Definition: button_bar.h:56
@ TOOLBAR_BUTTON_EXPAND
Definition: button_bar.h:54
@ TOOLBAR_BUTTON_STOP
Definition: button_bar.h:40
bool ro_gui_button_bar_rebuild(struct button_bar *button_bar, struct theme_descriptor *theme, theme_style style, wimp_w window, bool edit)
Place a button bar into a toolbar window and initialise any theme-specific settings.
Definition: button_bar.c:245
struct button_bar * ro_gui_button_bar_create(struct theme_descriptor *theme, const struct button_bar_buttons buttons[])
Create a new button bar widget.
Definition: button_bar.c:130
char * ro_gui_button_bar_get_config(struct button_bar *button_bar)
Return a config string reflecting the configured order of buttons and spacers.
Definition: button_bar.c:1067
static const struct button_bar_buttons brower_toolbar_buttons[]
Definition: button_bar.h:82
bool ro_gui_button_bar_set_extent(struct button_bar *button_bar, int x0, int y0, int x1, int y1)
Set or update the dimensions to be used by the button bar, in RO units.
Definition: button_bar.c:437
bool ro_gui_button_bar_shade_button(struct button_bar *button_bar, button_bar_action action, bool shaded)
Shade or unshade a button in a bar corresponding to the given action.
Definition: button_bar.c:640
bool ro_gui_button_bar_link_editor(struct button_bar *target, struct button_bar *source, void(*refresh)(void *), void *client_data)
Link two button bars together.
Definition: button_bar.c:220
bool ro_gui_button_bar_get_dims(struct button_bar *button_bar, int *width, int *height)
Return the MINIMUM dimensions required by the button bar, in RO units, allowing for the current theme...
Definition: button_bar.c:416
void ro_gui_button_bar_redraw(struct button_bar *button_bar, wimp_draw *redraw)
Handle redraw event rectangles in a button bar.
Definition: button_bar.c:672
bool ro_gui_button_bar_hide(struct button_bar *button_bar, bool hide)
Show or hide a button bar.
Definition: button_bar.c:627
bool ro_gui_button_bar_click(struct button_bar *button_bar, wimp_pointer *pointer, wimp_window_state *state, button_bar_action *action)
Handle mouse clicks in a button bar.
Definition: button_bar.c:723
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
const char * icon
The sprite used for the icon.
Definition: button_bar.h:72
const char * help
The interactive help token.
Definition: button_bar.h:76
button_bar_action select
The action for select clicks.
Definition: button_bar.h:73
const char opt_key
The char used in option strings.
Definition: button_bar.h:75
button_bar_action adjust
The action for Adjust clicks.
Definition: button_bar.h:74
bool edit
Definition: button_bar.c:86
wimp_w window
The window details and bar position.
Definition: button_bar.c:79
struct button_bar_button * buttons
The list of all the defined buttons.
Definition: button_bar.c:94
Definition: theme.h:64