mCtrl 0.8.1
Data Structures | Functions

mCtrl/button.h File Reference

Enhanced button control (MC_WC_BUTTON). More...

Go to the source code of this file.

Data Structures

struct  MC_NMBCDROPDOWN
 Structure for notification MC_BCN_DROPDOWN. More...

Defines

Window Class
#define MC_WC_BUTTONW   L"mCtrl.button"
 Window class name (unicode variant).
#define MC_WC_BUTTONA   "mCtrl.button"
 Window class name (ANSI variant).
Control Styles
#define MC_BS_SPLITBUTTON   (0x0000000CL)
 Style to create a split button.
#define MC_BS_DEFSPLITBUTTON   (0x0000000DL)
 Style to create a default split button.
Control States
#define MC_BST_DROPDOWNPUSHED   0x0400
 State of the split button when dropdown button is pressed.
Control Notifications
#define MC_BCN_DROPDOWN   ((0U-1250U) + 0x0002)
 Notification fired when user clicks on the dropdown button.
Unicode Resolution
#define MC_WC_BUTTON   MC_WC_BUTTONW
 Unicode-resolution alias.

Functions

BOOL MCTRL_API mcButton_Initialize (void)
 Registers window class of the button control.
void MCTRL_API mcButton_Terminate (void)
 Unregisters window class of the button control.

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 avaiable 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 avaiable and enabled on the system. If your application supports XP theming, you should prefer MC_WC_BUTTON windows class over BUTTON for icon buttons.

Comparision 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 devided to two parts. The main part behaves as the normal push buttons and the other part (called dropdown) opens some options closely related with the function of the main button part. In a typical use-case the dropdown 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 dropdown 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 interchangably. The advamtage 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).


Define Documentation

#define MC_BS_SPLITBUTTON   (0x0000000CL)

Style to create 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   (0x0000000DL)

Style to create 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 dropdown 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 dropdown 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   MC_WC_BUTTONW

Unicode-resolution alias.

See also:
MC_WC_MDITABW MC_WC_MDITABA

Function Documentation

BOOL MCTRL_API mcButton_Initialize ( void  )

Registers window class of the button control.

Returns:
TRUE on success, FALSE on failure.
See also:
About Initialization and Termination
void MCTRL_API mcButton_Terminate ( void  )

Unregisters window class of the button control.

See also:
About Initialization and Termination