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
-
enumerator BUTTON_GUID_BUTTON
-
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
-
enumerator BUTTON_TYPE_NORMAL
-
enum uie::t_button_state
Identifies the state of a button.
Combine multiple flags using bitwise or.
See also
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
-
enumerator BUTTON_STATE_ENABLED
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
- 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
- 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
- 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.
-
virtual const GUID &get_item_guid() const = 0
-
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
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.
-
virtual HANDLE get_item_bitmap(unsigned command_state_index, COLORREF cr_btntext, unsigned cx_hint, unsigned cy_hint, unsigned &handle_type) const = 0
-
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)
-
virtual void select_subcommand(const GUID &p_subcommand) = 0
-
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
- 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)
-
inline virtual t_button_guid get_guid_type() const override
-
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
- Parameters
p_new_state – [in] Index of new command state
-
virtual void on_button_state_change(unsigned p_new_state) = 0