NetSurf
Data Structures | Macros | Functions | Variables
button_bar.c File Reference

Button bars (implementation). More...

#include <assert.h>
#include <stdio.h>
#include <stdbool.h>
#include <stdlib.h>
#include <string.h>
#include <oslib/dragasprite.h>
#include <oslib/os.h>
#include <oslib/osspriteop.h>
#include <oslib/wimp.h>
#include <oslib/wimpspriteop.h>
#include "utils/log.h"
#include "riscos/gui/button_bar.h"
#include "riscos/gui.h"
#include "riscos/mouse.h"
#include "riscos/theme.h"
#include "riscos/wimp.h"
Include dependency graph for button_bar.c:

Go to the source code of this file.

Data Structures

struct  button_bar_button
 
struct  button_bar
 

Macros

#define BUTTONBAR_SPRITE_NAME_LENGTH   12
 
#define BUTTONBAR_VALIDATION_LENGTH   40
 

Functions

static bool ro_gui_button_bar_place_buttons (struct button_bar *button_bar)
 Place the buttons on a button bar, taking into account the button arrangement and the current theme, and update the bar extent details. More...
 
static bool ro_gui_button_bar_icon_update (struct button_bar *button_bar)
 Update the icons on a button bar, creating or deleting them from the window as necessary. More...
 
static bool ro_gui_button_bar_icon_resize (struct button_bar *button_bar)
 Position the icons in the button bar to take account of the currently configured extent. More...
 
static void ro_gui_button_bar_drag_end (wimp_dragged *drag, void *data)
 Terminate a drag event that was initiated by a button bar. More...
 
static void ro_gui_button_bar_sync_editors (struct button_bar *target, struct button_bar *source)
 Synchronise the shading of a button bar editor source bar with the currently defined buttons in its target bar. More...
 
static struct button_bar_buttonro_gui_button_bar_find_icon (struct button_bar *button_bar, wimp_i icon)
 Find a button bar icon definition from an icon handle. More...
 
static struct button_bar_buttonro_gui_button_bar_find_opt_key (struct button_bar *button_bar, char opt_key)
 Find a button bar icon definition from an options key code. More...
 
static struct button_bar_buttonro_gui_button_bar_find_action (struct button_bar *button_bar, button_bar_action action)
 Find a button bar icon definition from an action code. More...
 
static struct button_bar_buttonro_gui_button_bar_find_coords (struct button_bar *button_bar, os_coord pos, bool *separator, bool *right)
 Find a button bar icon definition from coordinates. More...
 
struct button_barro_gui_button_bar_create (struct theme_descriptor *theme, const struct button_bar_buttons buttons[])
 Create a new button bar widget. More...
 
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. More...
 
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. More...
 
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 layout. More...
 
void ro_gui_button_bar_destroy (struct button_bar *button_bar)
 Destroy a button bar widget. More...
 
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. More...
 
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. More...
 
bool ro_gui_button_bar_hide (struct button_bar *button_bar, bool hide)
 Show or hide a button bar. More...
 
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. More...
 
void ro_gui_button_bar_redraw (struct button_bar *button_bar, wimp_draw *redraw)
 Handle redraw event rectangles in a button bar. More...
 
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. More...
 
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. More...
 
char * ro_gui_button_bar_get_config (struct button_bar *button_bar)
 Return a config string reflecting the configured order of buttons and spacers. More...
 

Variables

static char null_text_string [] = ""
 
static char separator_name [] = "separator"
 
static struct button_bardrag_start = NULL
 
static char drag_opt = '\0'
 
static bool drag_separator = false
 

Detailed Description

Button bars (implementation).

Definition in file button_bar.c.

Macro Definition Documentation

◆ BUTTONBAR_SPRITE_NAME_LENGTH

#define BUTTONBAR_SPRITE_NAME_LENGTH   12

Definition at line 43 of file button_bar.c.

◆ BUTTONBAR_VALIDATION_LENGTH

#define BUTTONBAR_VALIDATION_LENGTH   40

Definition at line 44 of file button_bar.c.

Function Documentation

◆ ro_gui_button_bar_arrange_buttons()

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 layout.

Parameters
*button_barThe button bar to update.
order[]The button order configuration string.
Returns
true if successful; else false.

Definition at line 303 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, button_bar::buttons, button_bar_button::next, ro_gui_button_bar_find_opt_key(), ro_gui_button_bar_place_buttons(), and button_bar_button::separator.

Referenced by ro_toolbar_add_buttons(), and ro_toolbar_set_button_order().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_click()

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.

Parameters
*button_barThe button bar to use.
*pointerThe Wimp mouse click event data.
*stateThe toolbar window state.
*actionReturns the selected action, or TOOLBAR_BUTTON_NONE.
Returns
true if the event was handled exclusively; else false.

Definition at line 723 of file button_bar.c.

References button_bar_button::adjust_action, drag_opt, drag_separator, drag_start, button_bar::edit, button_bar::edit_source, button_bar::extent, button_bar::hidden, NSLOG, button_bar_button::opt_key, ro_gui_button_bar_drag_end(), ro_gui_button_bar_find_coords(), ro_gui_button_bar_find_icon(), ro_mouse_drag_start(), button_bar_button::select_action, separator_name, button_bar::separator_width, button_bar_button::shaded, button_bar_button::sprite, button_bar::sprites, box::x, button_bar_button::x_size, box::y, and button_bar_button::y_size.

Referenced by ro_toolbar_click().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_create()

struct button_bar * ro_gui_button_bar_create ( struct theme_descriptor theme,
const struct button_bar_buttons  buttons[] 
)

Create a new button bar widget.

Parameters
*themeThe theme to apply (or NULL for the default).
buttons[]An array of button definitions for the bar.
Returns
A button bar handle, or NULL on failure.

Definition at line 130 of file button_bar.c.

References button_bar_buttons::adjust, button_bar::background, button_bar::bar, BUTTONBAR_SPRITE_NAME_LENGTH, BUTTONBAR_VALIDATION_LENGTH, button_bar::buttons, button_bar::edit, button_bar::edit_client_data, button_bar::edit_refresh, button_bar::edit_source, button_bar::edit_target, button_bar_buttons::help, button_bar::hidden, button_bar_button::icon, button_bar_buttons::icon, NSLOG, button_bar_buttons::opt_key, ro_gui_theme_get_sprites(), button_bar_buttons::select, button_bar::separator_width, button_bar::separators, button_bar::sprites, button_bar::theme, button_bar::vertical_offset, button_bar::window, button_bar::x_min, and button_bar::y_min.

Referenced by ro_toolbar_add_buttons().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_destroy()

void ro_gui_button_bar_destroy ( struct button_bar button_bar)

Destroy a button bar widget.

Parameters
*button_barThe button bar to destroy.

Definition at line 395 of file button_bar.c.

References button_bar::buttons, and button_bar_button::next.

Referenced by ro_toolbar_destroy(), and ro_toolbar_rebuild().

Here is the caller graph for this function:

◆ ro_gui_button_bar_drag_end()

void ro_gui_button_bar_drag_end ( wimp_dragged *  drag,
void *  data 
)
static

Terminate a drag event that was initiated by a button bar.

Parameters
*dragThe drag event data.
*dataNULL data to satisfy callback syntax.

Definition at line 866 of file button_bar.c.

References button_bar_button::bar_next, drag_opt, drag_separator, drag_start, button_bar::edit_client_data, button_bar::edit_refresh, button_bar::edit_source, button_bar::edit_target, NSLOG, ro_gui_button_bar_find_coords(), ro_gui_button_bar_find_opt_key(), ro_gui_button_bar_icon_update(), ro_gui_button_bar_place_buttons(), ro_gui_button_bar_sync_editors(), ro_warn_user(), button_bar_button::separator, and button_bar::window.

Referenced by ro_gui_button_bar_click().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_find_action()

struct button_bar_button * ro_gui_button_bar_find_action ( struct button_bar button_bar,
button_bar_action  action 
)
static

Find a button bar icon definition from an action code.

Parameters
*button_barThe button bar to use.
actionThe button action to find.
Returns
Pointer to the button bar icon, or NULL.

Definition at line 1162 of file button_bar.c.

References button_bar_button::adjust_action, button_bar::buttons, button_bar_button::next, and button_bar_button::select_action.

Referenced by ro_gui_button_bar_shade_button().

Here is the caller graph for this function:

◆ ro_gui_button_bar_find_coords()

struct button_bar_button * ro_gui_button_bar_find_coords ( struct button_bar button_bar,
os_coord  pos,
bool *  separator,
bool *  right 
)
static

Find a button bar icon definition from coordinates.

Parameters
*button_barThe button bar to use.
posThe coordinates to find, work area relative.
*separatorReturns true if the associated separator was matched; else false.
*rightReturns true if the coordinates were in the right hand side of the target; else false.
Returns
Pointer to the button bar icon, or NULL.

Definition at line 1193 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, button_bar::extent, button_bar_button::separator, button_bar::separator_width, button_bar_button::x_pos, button_bar_button::x_size, button_bar_button::y_pos, and button_bar_button::y_size.

Referenced by ro_gui_button_bar_click(), and ro_gui_button_bar_drag_end().

Here is the caller graph for this function:

◆ ro_gui_button_bar_find_icon()

struct button_bar_button * ro_gui_button_bar_find_icon ( struct button_bar button_bar,
wimp_i  icon 
)
static

Find a button bar icon definition from an icon handle.

Parameters
*button_barThe button bar to use.
iconThe icon handle.
Returns
Pointer to the button bar icon, or NULL.

Definition at line 1112 of file button_bar.c.

References button_bar::buttons, button_bar_button::icon, and button_bar_button::next.

Referenced by ro_gui_button_bar_click(), and ro_gui_button_bar_help_suffix().

Here is the caller graph for this function:

◆ ro_gui_button_bar_find_opt_key()

struct button_bar_button * ro_gui_button_bar_find_opt_key ( struct button_bar button_bar,
char  opt_key 
)
static

Find a button bar icon definition from an options key code.

Parameters
*button_barThe button bar to use.
opt_keyThe option key character code.
Returns
Pointer to the button bar icon, or NULL.

Definition at line 1137 of file button_bar.c.

References button_bar::buttons, button_bar_button::next, and button_bar_button::opt_key.

Referenced by ro_gui_button_bar_arrange_buttons(), ro_gui_button_bar_drag_end(), and ro_gui_button_bar_sync_editors().

Here is the caller graph for this function:

◆ ro_gui_button_bar_get_config()

char * ro_gui_button_bar_get_config ( struct button_bar button_bar)

Return a config string reflecting the configured order of buttons and spacers.

The string is allocated with malloc(), and should be free()d after use.

Parameters
*button_barThe button bar of interest.
Returns
Pointer to a config string, or NULL on failure.

Definition at line 1067 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, NSLOG, button_bar_button::opt_key, ro_warn_user(), and button_bar_button::separator.

Referenced by ro_toolbar_toggle_edit().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_get_dims()

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.

Parameters
*button_barThe button bar of interest.
*widthReturn the required width.
*heightReturn the required height.
Returns
true if values are returned; else false.

Definition at line 416 of file button_bar.c.

References height, width, button_bar::x_min, and button_bar::y_min.

Referenced by ro_toolbar_refresh_widget_dimensions().

Here is the caller graph for this function:

◆ ro_gui_button_bar_help_suffix()

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.

Parameters
*button_barThe button bar to process.
iThe wimp icon under the pointer.
*mouseThe mouse position.
*stateThe toolbar window state.
buttonsThe mouse button state.
**suffixReturn a help token suffix, or "" for none.
Returns
true if handled exclusively; else false.

Definition at line 826 of file button_bar.c.

References button_bar::extent, button_bar_button::help_suffix, button_bar::hidden, and ro_gui_button_bar_find_icon().

Referenced by ro_toolbar_get_help_suffix().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_hide()

bool ro_gui_button_bar_hide ( struct button_bar button_bar,
bool  hide 
)

Show or hide a button bar.

Parameters
*button_barThe button bar to hide.
hidetrue to hide the bar; false to show it.
Returns
true if successful; else false.

Definition at line 627 of file button_bar.c.

References button_bar::hidden, and ro_gui_button_bar_icon_update().

Referenced by ro_toolbar_add_buttons(), ro_toolbar_set_display_buttons(), and ro_toolbar_toggle_edit().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_icon_resize()

bool ro_gui_button_bar_icon_resize ( struct button_bar button_bar)
static

Position the icons in the button bar to take account of the currently configured extent.

Parameters
*button_barThe button bar to update.
Returns
true if successful; else false.

Definition at line 581 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, button_bar::extent, button_bar::hidden, button_bar_button::icon, NSLOG, ro_warn_user(), button_bar::vertical_offset, button_bar::window, button_bar_button::x_pos, button_bar_button::x_size, button_bar_button::y_pos, and button_bar_button::y_size.

Referenced by ro_gui_button_bar_icon_update(), and ro_gui_button_bar_set_extent().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_icon_update()

bool ro_gui_button_bar_icon_update ( struct button_bar button_bar)
static

Update the icons on a button bar, creating or deleting them from the window as necessary.

Definition at line 483 of file button_bar.c.

References button_bar::background, button_bar::bar, button_bar_button::bar_next, button_bar::buttons, button_bar::edit, button_bar::edit_target, button_bar::hidden, button_bar_button::icon, button_bar_button::next, NSLOG, null_text_string, ro_gui_button_bar_icon_resize(), ro_warn_user(), button_bar_button::shaded, button_bar_button::validation, and button_bar::window.

Referenced by ro_gui_button_bar_drag_end(), ro_gui_button_bar_hide(), and ro_gui_button_bar_rebuild().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_link_editor()

bool ro_gui_button_bar_link_editor ( struct button_bar target,
struct button_bar source,
void(*)(void *)  refresh,
void *  client_data 
)

Link two button bars together.

Join two button bars the target being the active bar, and the source being the editing bar used to supply valid buttons. The bars are checked to ensure that they are not already part of an edit pair, but are not checked for button-compatibility.

Parameters
targetThe target button bar.
sourceThe source button bar.
refreshThe refresh callback.
client_datacontext passed to the refresh callback
Returns
true if successful; else false.

Definition at line 220 of file button_bar.c.

References button_bar::edit_client_data, button_bar::edit_refresh, button_bar::edit_source, and button_bar::edit_target.

Referenced by ro_toolbar_add_buttons().

Here is the caller graph for this function:

◆ ro_gui_button_bar_place_buttons()

bool ro_gui_button_bar_place_buttons ( struct button_bar button_bar)
static

Place the buttons on a button bar, taking into account the button arrangement and the current theme, and update the bar extent details.

Parameters
*button_barThe button bar to update.
Returns
true if successful; else false.

Definition at line 359 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, height, button_bar_button::separator, button_bar::separator_width, button_bar::x_min, button_bar_button::x_pos, button_bar_button::x_size, button_bar::y_min, button_bar_button::y_pos, and button_bar_button::y_size.

Referenced by ro_gui_button_bar_arrange_buttons(), ro_gui_button_bar_drag_end(), and ro_gui_button_bar_rebuild().

Here is the caller graph for this function:

◆ ro_gui_button_bar_rebuild()

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.

Any previous incarnation of the bar will be forgotten: this is for use when a new toolbar is being created, or when a toolbar has been deleted and rebuilt following a theme change.

Parameters
*button_barThe button bar to rebuild.
*themeThe theme to apply (or NULL for current).
styleThe theme style to apply.
windowThe window that the bar is in.
editThe edit mode of the button bar.
Returns
true on success; else false.

Definition at line 245 of file button_bar.c.

References button_bar::background, button_bar::buttons, button_bar::edit, button_bar::edit_target, height, button_bar_button::icon, button_bar_button::next, ro_gui_button_bar_icon_update(), ro_gui_button_bar_place_buttons(), ro_gui_button_bar_sync_editors(), ro_gui_theme_get_sprites(), ro_gui_theme_get_style_element(), ro_gui_wimp_get_sprite_dimensions(), separator_name, button_bar::separator_width, button_bar::separators, button_bar_button::sprite, button_bar::sprites, button_bar::theme, THEME_ELEMENT_BACKGROUND, button_bar::window, button_bar_button::x_size, and button_bar_button::y_size.

Referenced by ro_toolbar_rebuild().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_redraw()

void ro_gui_button_bar_redraw ( struct button_bar button_bar,
wimp_draw *  redraw 
)

Handle redraw event rectangles in a button bar.

Parameters
*button_barThe button bar to use.
*redrawThe Wimp redraw rectangle to process.

Definition at line 672 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, button_bar::edit, button_bar::extent, button_bar::hidden, button_bar_button::icon, button_bar_button::separator, separator_name, button_bar::separator_width, button_bar::separators, button_bar::sprites, button_bar::vertical_offset, button_bar_button::x_pos, button_bar_button::x_size, and button_bar::y_min.

Referenced by ro_toolbar_redraw().

Here is the caller graph for this function:

◆ ro_gui_button_bar_set_extent()

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.

If these are greater than the minimum required, the button bar will fill the extended space; if less, the call will fail.

Parameters
*button_barThe button bar to update.
x0The minimum X window position.
y0The minimum Y window position.
x1The maximum X window position.
y1The maximum Y window position.
Returns
true if size updated; else false.

Definition at line 437 of file button_bar.c.

References button_bar::extent, ro_gui_button_bar_icon_resize(), button_bar::vertical_offset, button_bar::window, button_bar::x_min, and button_bar::y_min.

Referenced by ro_toolbar_reformat_widgets().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_shade_button()

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.

Parameters
*button_barThe button bar to update.
actionThe action to update.
shadedtrue to shade the button; false to unshade.
Returns
true if successful; else false.

Definition at line 640 of file button_bar.c.

References button_bar::edit, button_bar::edit_target, button_bar_button::icon, ro_gui_button_bar_find_action(), ro_gui_set_icon_shaded_state(), button_bar_button::shaded, and button_bar::window.

Referenced by ro_toolbar_set_button_shaded_state().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ ro_gui_button_bar_sync_editors()

void ro_gui_button_bar_sync_editors ( struct button_bar target,
struct button_bar source 
)
static

Synchronise the shading of a button bar editor source bar with the currently defined buttons in its target bar.

Parameters
*targetThe editor target bar.
*sourceThe editor source bar.

Definition at line 1032 of file button_bar.c.

References button_bar::bar, button_bar_button::bar_next, button_bar_button::icon, button_bar_button::opt_key, ro_gui_button_bar_find_opt_key(), ro_gui_set_icon_shaded_state(), button_bar_button::shaded, and button_bar::window.

Referenced by ro_gui_button_bar_drag_end(), and ro_gui_button_bar_rebuild().

Here is the call graph for this function:
Here is the caller graph for this function:

Variable Documentation

◆ drag_opt

char drag_opt = '\0'
static

Definition at line 105 of file button_bar.c.

Referenced by ro_gui_button_bar_click(), and ro_gui_button_bar_drag_end().

◆ drag_separator

bool drag_separator = false
static

Definition at line 106 of file button_bar.c.

Referenced by ro_gui_button_bar_click(), and ro_gui_button_bar_drag_end().

◆ drag_start

struct button_bar* drag_start = NULL
static

Definition at line 104 of file button_bar.c.

Referenced by ro_gui_button_bar_click(), and ro_gui_button_bar_drag_end().

◆ null_text_string

char null_text_string[] = ""
static

Definition at line 101 of file button_bar.c.

Referenced by ro_gui_button_bar_icon_update().

◆ separator_name

char separator_name[] = "separator"
static