mCtrl/button.h File Reference

Enhanced button control (MC_WC_BUTTON). More...

#include <mCtrl/defs.h>

Go to the source code of this file.

Data Structures

struct  mc_NMBCDROPDOWN

Defines

#define MC_WC_BUTTONW   L"mCtrl.button"
#define MC_WC_BUTTONA   "mCtrl.button"
#define MC_WC_BUTTON   MC_WC_BUTTONW
#define MC_BS_ICON   (BS_ICON)
#define MC_BS_SPLITBUTTON   (0x0000000CL)
#define MC_BS_DEFSPLITBUTTON   (0x0000000DL)
#define MC_BST_DROPDOWNPUSHED   0x0400
#define MC_BCN_DROPDOWN   (0xfffffb20U)

Functions

BOOL MCTRL_API mcButton_Initialize (void)
void MCTRL_API mcButton_Terminate (void)


Detailed Description

Enhanced button control (MC_WC_BUTTON).

MC_WC_BUTTON control is subclass of standard BUTTON class, providing two features:

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

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 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. Only BS_ICON is supported.
See also:
MC_BS_ICON

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 button. In most use-case the dropdown launches a popup menu.

button_split.png

Microsoft introduced split buttons in Windows Vista. Some applications use them even on older Windows versions, including some Microsoft products (e.g. MS Visual Studio 2005). However such applications don't use the standard control but implement their own in each application, so those are not available for 3rd party developers. And limiting an application for only Windows Vista by using new control is not acceptable for majority of developers, as well as end-users of their applications.

Therefore mCtrl comes with its own implementation of split buttons. 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 structure and check if mc_NMBCDROPDOWN::hdr.code is MC_BST_DROPDOWNPUSHED.

Note that all the styles and messages have values equal to the standard one as defined by Microsoft SDK so they can be used interchangably.

Attention:
that MC_WC_BUTTON implements only subset of styles and messages for split buttons offered on Window Vista.
The MC_WC_BUTTON is implemented as a subclass of standard BUTTON control. 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 developer: 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 but not on the older Windows versions.

Therefore it's recommanded practice that if you use MC_WC_BUTTON, you also stick with the mCtrl-defined messages and styles for split buttons (i.e. those with prefix MC_). This has yet another advantage: to use the split button, you don't need to define C preprocessor macro _WIN32_WINNT to 0x0600 (or higher) as you would to force the Win32API headers to declare the split button related stuff.

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

See also:
MC_BS_SPLITBUTTON MC_BS_DEFSPLITBUTTON MC_BST_DROPDOWNPUSHED MC_BCN_DROPDOWN mc_NMBCDROPDOWN

Define Documentation

#define MC_WC_BUTTONW   L"mCtrl.button"

Window class (unicode version).

#define MC_WC_BUTTONA   "mCtrl.button"

Window class (ANSI version).

#define MC_WC_BUTTON   MC_WC_BUTTONW

Window class.

#define MC_BS_ICON   (BS_ICON)

Synonymum for BS_ICON. See Icon buttons.

#define MC_BS_SPLITBUTTON   (0x0000000CL)

Style to create a split button. Binary compatible with BS_SPLITBUTTON. See Split buttons.

#define MC_BS_DEFSPLITBUTTON   (0x0000000DL)

Style to create a default split button. Binary compatible with BS_DEFSPLITBUTTON. See Split buttons.

#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. See Split buttons.

#define MC_BCN_DROPDOWN   (0xfffffb20U)

Notification code fired when user clicks on the dropdown button. It is equivalent to standard BCN_DROPDOWN. It is passed via the WM_NOTIFY message. See Split buttons.

Parameters:
[in] wParam Id of the control sending the notification.
[in] lParam Pointer to mc_NMBCDROPDOWN with associated data.
Returns:
You should return zero if you process the notification.
See also:
mc_NMBCDROPDOWN


Function Documentation

BOOL MCTRL_API mcButton_Initialize ( void   ) 

Registers the button control class.

Returns:
TRUE on success, FALSE on failure.
See also:
sec_initialization

void MCTRL_API mcButton_Terminate ( void   ) 

Unregisters the button control class.

See also:
sec_initialization


Generated on Wed Nov 4 00:45:25 2009 for mCtrl by  doxygen 1.5.9