mCtrl  0.11.0
Data Structures
button.h File Reference

Go to the source code of this file.

Detailed Description

Enhanced button control (MC_WC_BUTTON).

MC_WC_BUTTON control is subclass of standard BUTTON class.

In fact, MC_WC_BUTTON does not provide any new functionality. It only helps to overcome some compatibility limitations between button implementation in various versions of COMCTL32.DLL.

In all other aspects the MC_WC_BUTTON control behaves as the standard BUTTON (strictly speaking it inherits those features by subclassing) as available on the Windows version and COMCTL32.DLL version available on the system where your application runs. So you can use MC_WC_BUTTON everywhere, instead of all buttons and use the standard flags when creating them, e.g. BS_GROUPBOX or BS_CHECKBOX.

Icon Buttons

On Windows XP, the standard BUTTON uses the old and boring look from Windows 95/98 when you use style BS_ICON and set image of the button with BM_SETIMAGE. If you have enabled the XP theming (as it is by default in Windows XP), then the button simply does not look consistently with other controls in your application.

If you use MC_WC_BUTTON, the button is styled if XP styles are available and enabled on the system. If your application supports XP theming, you should prefer MC_WC_BUTTON windows class over BUTTON for icon buttons.

Comparison of icon button without and with Windows XP Styles:

button_icon.png

From developer's point of view, the use of icon button is absolutely the same as the standard BUTTON control. Use standard BS_ICON style and BM_SETIMAGE message.

Attention
MC_WC_BUTTON does not implement support for XP styling of buttons with style BS_BITMAP. Currently only BS_ICON is supported. I.e. on Windows XP, the buttons with style BS_BITMAP still look as if not styled with the XP theme.

Split Buttons

Split button is a push button divided to two parts. The main part behaves as the normal push buttons and the other part (called drop-down) opens some options closely related with the function of the main button part. In a typical use-case the drop-down launches a popup menu.

button_split.png

To make a split button, just specify style MC_BS_SPLITBUTTON or MC_BS_DEFSPLITBUTTON when you create the control.

To handle clicks on the main part of the button, handle WM_COMMAND as for any other normal push buttons.

To handle clicks on the drop-down part of the button, handle message WM_NOTIFY. If the message originates from MC_BS_SPLITBUTTON control, recast LPARAM to MC_NMBCDROPDOWN* and check if MC_NMBCDROPDOWN::hdr.code is MC_BST_DROPDOWNPUSHED.

Note that all the mCtrl split button styles and messages supported by MCTRL.DLL (those defined in this header with the prefix "MC_") have values equal to their standard counterparts as defined by Microsoft SDK in <commctrl.h> so they can be used interchangeably. The advantage of those mCtrl ones is that they are defined always when you include <mCtrl/button.h>, while the standard identifiers in <commctrl.h> are defined only if _WIN32_WINNT >= 0x0600.

Attention
Remember that MC_WC_BUTTON implements only subset of styles and messages for split buttons offered by COMCTL32.DLL version 6.0.

If the Windows support split button in a natural way (Vista or newer), the MC_WC_BUTTON just simply passes all messages down to the original BUTTON window procedure. This guarantees good consistency of the control's look and feel with other system controls, but it also brings a minor pitfall for developers: If you use standard identifiers of split button messages and styles (e.g. BS_DEFSPLITBUTTON instead of MC_BS_DEFSPLITBUTTON) then it is easy to forget about the limitation. It then will work in runtime as intended on Windows Vista or newer but not on the Windows XP or older.

For more information, you can refer to documentation of split buttons on MSDN (but still keep in mind that only some of the features are reimplemented in mCtrl).

Data Structures

struct  MC_NMBCDROPDOWN
 Structure for notification MC_BCN_DROPDOWN. More...
 

Initialization Functions

BOOL mcButton_Initialize (void)
 
void mcButton_Terminate (void)
 

Window Class

#define MC_WC_BUTTONW   L"mCtrl.button"
 
#define MC_WC_BUTTONA   "mCtrl.button"
 

Control Styles

#define MC_BS_SPLITBUTTON   0x000C
 Style of a split button. More...
 
#define MC_BS_DEFSPLITBUTTON   0x000D
 Style of a default split button. More...
 

Control States

#define MC_BST_DROPDOWNPUSHED   0x0400
 State of the split button when drop-down button is pressed. More...
 

Control Notifications

#define MC_BCN_DROPDOWN   ((0U-1250U) + 0x0002)
 Notification fired when user clicks on the drop-down button. More...
 

Unicode Resolution

#define MC_WC_BUTTON   MCTRL_NAME_AW(MC_WC_BUTTON)
 

Data Structure Documentation

struct MC_NMBCDROPDOWN

Structure for notification MC_BCN_DROPDOWN.

It is equivalent to standard NMBCDROPDOWN. It is provided because the standard NMBCDROPDOWN is defined only if _WIN32_WINNT >= 0x0600.

Data Fields
NMHDR hdr

Standard notification structure header.

RECT rcButton

Client rectangle of the drop-down button.

Macro Definition Documentation

#define MC_WC_BUTTONW   L"mCtrl.button"

Window class name (Unicode variant).

#define MC_WC_BUTTONA   "mCtrl.button"

Window class name (ANSI variant).

#define MC_BS_SPLITBUTTON   0x000C

Style of a split button.

It is equivalent to standard BS_SPLITBUTTON. It is provided because the standard BS_SPLITBUTTON is defined only if _WIN32_WINNT >= 0x0600.

#define MC_BS_DEFSPLITBUTTON   0x000D

Style of a default split button.

It is equivalent to standard BS_DEFSPLITBUTTON. It is provided because the standard BS_SPLITBUTTON is defined only if _WIN32_WINNT >= 0x0600.

#define MC_BST_DROPDOWNPUSHED   0x0400

State of the split button when drop-down button is pressed.

It is a possible value returned by standard BM_GETSTATE message. It is equivalent to standard BST_DROPDOWNPUSHED. It is provided because the standard BST_DROPDOWNPUSHED is defined only if _WIN32_WINNT >= 0x0600.

#define MC_BCN_DROPDOWN   ((0U-1250U) + 0x0002)

Notification fired when user clicks on the drop-down button.

It is equivalent to standard BCN_DROPDOWN. It is passed via the WM_NOTIFY message. It is provided because the standard BCN_DROPDOWN is defined only if _WIN32_WINNT >= 0x0600.

Parameters
[in]wParam(int) Id of the control sending the notification.
[in]lParam(MC_NMBCDROPDOWN*) Data associated with the notification.
Returns
Application should return zero if it processes the notification.
See also
MC_NMBCDROPDOWN
#define MC_WC_BUTTON   MCTRL_NAME_AW(MC_WC_BUTTON)

Unicode-resolution alias.

See also
MC_WC_MDITABW MC_WC_MDITABA

Function Documentation

BOOL mcButton_Initialize ( void  )

Registers window class of the control.

Returns
TRUE on success, FALSE on failure.
void mcButton_Terminate ( void  )

Unregisters window class of the control.