Button

These interfaces are used to implement custom buttons for the Columns UI buttons toolbar.

Constants

enum uie::t_button_guid

Identifies the type of GUID.

Values:

enumerator BUTTON_GUID_BUTTON

GUID identifies a button command

enumerator BUTTON_GUID_MENU_ITEM_CONTEXT

GUID identifies a context menu command

enumerator BUTTON_GUID_MENU_ITEM_MAIN

GUID identifies a main menu command

enum uie::t_button_type

Identifies the type of button.

Values:

enumerator BUTTON_TYPE_NORMAL

The button acts as a standard click button

enumerator BUTTON_TYPE_DROPDOWN

The button displays a drop-down menu when pressed

enumerator BUTTON_TYPE_DROPDOWN_ARROW

The button displays an arrow which displays a drop-down menu

enum uie::t_button_state

Identifies the state of a button.

Combine multiple flags using bitwise or.

See also

button::get_button_state

Values:

enumerator BUTTON_STATE_ENABLED

The button is enabled

enumerator BUTTON_STATE_PRESSED

The button is in an active state

enumerator BUTTON_STATE_SHOW_TOOLTIP

The button displays a ToolTip

enumerator BUTTON_STATE_DEFAULT

The default button state

enum uie::t_mask

Values:

enumerator MASK_NONE

No transparency mask is used.

enumerator MASK_BITMAP

1bpp bitmap transparency mask is used

enumerator MASK_COLOUR

Pixels with specified colour are transparent.

Interfaces

class button : public service_base

Service that provides buttons for a toolbar.

Subclassed by uie::button_v2, uie::custom_button, uie::menu_button

Public Functions

virtual const GUID &get_item_guid() const = 0

Get the identifier of the button.

Use get_type_guid() to determine what the GUID repreesnts.

Returns:

GUID identifying the command represented by the class

inline virtual t_button_guid get_guid_type() const

Get whether get_item_guid() specifies a main menu item, a context menu, or a custom button command.

\Note Only recommended use of button-only buttons are dropdown-only buttons

See also

t_button_guid

Returns:

type of command represnted by this class

virtual HBITMAP get_item_bitmap(unsigned command_state_index, COLORREF cr_btntext, t_mask &p_mask_type, COLORREF &cr_mask, HBITMAP &bm_mask) const = 0

Get a handle to a bitmap and its transparency mask of the menu item.

Deprecated:

Use button_v2::get_item_bitmap() instead.

Caller presumes ownership of bitmap.

Remark

Masks generated from a colour are only supported on bitmaps with a colour depth less than or equal to 8bpp.

Note

In the toolbar control, transparency masks are supported on all versions of windows; where as 32 bpp bitmaps with 8bpp alpha channel are supported only under common controls version 6.

Note

Ensure you do not create a mask bitmap if you fail to create main bitmap

Parameters:

• cr_btntext – [in] Colour to use for text/foreground

• bm_mask – [out] HBITMAP of transparency mask. This is a monochrome bitmap.

Returns:

HBITMAP of menu item

inline virtual t_button_type get_button_type() const

Get type of button.

See also

t_button_type

Returns:

Type of button

inline virtual void get_menu_items(menu_hook_t &p_out)

Gets menu items for drop-down buttons.

Parameters:

p_out – [out] Receives menu items

inline virtual unsigned get_button_state() const

Gets buttons state.

See also

t_button_state

Returns:

Button state

inline virtual unsigned get_command_state_index() const

Gets current state of the command. For example, in a “Play or pause” command this would indicate the play or pause state.

Returns:

Index of current command state

inline virtual unsigned get_command_state_count() const

Gets total count of possible command states.

Returns:

Total count of possible command states

inline virtual void get_command_state_name(unsigned index, pfc::string_base &p_out) const

Gets name of specified command state.

Parameters:

• index – [in] Index of command state’s name to retrieve

• p_out – [out] Receives command state name

inline virtual void register_callback(button_callback &p_callback)

Registers a button_callback class to receive callbacks.

Parameters:

p_callback – [in] Reference to callback object requesting callbacks

inline virtual void deregister_callback(button_callback &p_callback)

Deregisters a button_callback class to stop receiving callbacks.

The object implementing this method must not keep any references to the specified callback object after this method returns

Parameters:

p_callback – [in] Reference to callback object being deregistered.

FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(button)

class button_v2 : public uie::button

Extension of button interface; allows icons to be used as default button images.

New in SDK version 6.5.

Public Types

enum handle_type_t

Values:

enumerator handle_type_bitmap

HBITMAP

enumerator handle_type_icon

HICON

Public Functions

virtual HANDLE get_item_bitmap(unsigned command_state_index, COLORREF cr_btntext, unsigned cx_hint, unsigned cy_hint, unsigned &handle_type) const = 0

Get a handle to a image of the menu item.

Caller presumes ownership of bitmap.

Note

Use alpha channel for transparency.

Note

You can vary the returned image depending on whether dark mode is active by using cui::colours::is_dark_mode_active(). All button images are flushed when the dark mode status changes.

Parameters:

• command_state_index – [in] Not used.

• cr_btntext – [in] Colour to use for text/foreground

• cx_hint – [in] Displayed bitmap width

• cy_hint – [in] Displayed bitmap height

• handle_type – [out] Receives the type of handle returned (icon or bitmap)

Returns:

Handle of image

inline virtual HBITMAP get_item_bitmap(unsigned command_state_index, COLORREF cr_btntext, t_mask &p_mask_type, COLORREF &cr_mask, HBITMAP &bm_mask) const override

Deprecated uie::button method, not used for uie::button_v2.

FB2K_MAKE_SERVICE_INTERFACE(button_v2, button)

class menu_button : public uie::button

Sub-class of uie::button, for buttons based upon a context menu item.

Public Functions

virtual void select_subcommand(const GUID &p_subcommand) = 0

Sets subcommand that subsequent function calls will refer to.

Called after instantiation, but before other command-related methods.

Parameters:

p_subcommand – [in] Specifies the subcommand that this object wll represent

FB2K_MAKE_SERVICE_INTERFACE(menu_button, button)

class custom_button : public uie::button

Sub-class of uie::button, for buttons that implement their own command.

Public Functions

inline virtual t_button_guid get_guid_type() const override

Get whether get_item_guid() specifies a main menu item, a context menu, or a custom button command.

\Note Only recommended use of button-only buttons are dropdown-only buttons

See also

t_button_guid

Returns:

type of command represnted by this class

virtual void execute(const pfc::list_base_const_t<metadb_handle_ptr> &p_items) = 0

Executes the custom button’s command.

Parameters:

p_items – [in] Items to perform the command on

virtual void get_name(pfc::string_base &p_out) const = 0

Gets the name of the custom button.

Parameters:

p_out – [out] Recieves the name of the button, UTF-8 encoded

inline virtual bool get_description(pfc::string_base &p_out) const

Gets the description of the custom button.

Parameters:

p_out – [out] Recieves the description of the button, UTF-8 encoded

Returns:

true iff the button has a description

FB2K_MAKE_SERVICE_INTERFACE(custom_button, button)

Public Static Functions

static inline bool g_button_get_name(const GUID &p_guid, pfc::string_base &p_out)

class button_callback

Class implemented by button hosts to receive notification of button events.

Public Functions

virtual void on_button_state_change(unsigned p_new_state) = 0

Called when the state of the button changed

Parameters:

p_new_state – [in] Combination of uie::t_button_state

virtual void on_command_state_change(unsigned p_new_state) = 0

Called when the state of the command changed

See also

button::get_command_state_index, button::get_command_state_count

Parameters:

p_new_state – [in] Index of new command state

Factories

template<class T>
class button_factory : public service_factory_t<T>

Service factory for buttons.