A overview of the ButtonEx custom control contained in wlib.lib - created by John Findlay
library version 1.03
( library version 1.03 ) Added BXS_XP a WinXP look-alike button.
BXS_FLAT & BXS_FLATROUND have been removed. All buttons now require WS_VISIBLE if used on a Window - as is normal this is not required when using a button on a dialog.
Added 28th April 2004 BXM_CLEARIMAGE - use this if you want to set a new image or images for a button that has either a bitmap or an icon.
E.G.
SendMessage(h, BXM_CLEARIMAGE, IMAGE_ICON, 0);
// clears previous image/images
SendMessage(h, BXM_SETIMAGE, IMAGE_ICON, (long)hIco ); // sets new image
InvalidateRect(h, NULL, TRUE);
// make the change immediate.
=================================================================
If created without WS_VISIBLE you must make the button visible by explicitly showing, .e.g. by using the API ShowWindow() or Butx_ShowWindow().
BXS_XP uses a fixed colour scheme and will not respond to Butx_SetBkColor().
( library version 1.02 ) Two fixes: I had not taken into account the ampersand when positioning the button text. Also the Butx_SetToolGroup() function caused a stack problem on Win2k)
The ButtonEx control is similar to a normal button but supports a few features that button's do not. It does not support all normal button features however.
The reason for making this control was to enable having text and an image on the same button. Other features were added as a matter of course.
#include "ButtonEx.h" and link with wlib.lib
There are three ways to create a ButtonEx control.
1. Using the main creation API CreateButtonEx()
2. Using the normal Windows CreateWindow() API
3. Using a CONTROL statement in a dialog template.
When using CreateButtonEx the control is automatically initialized but when using CreateWindow() or the CONTROL statement in a dialog template you must use InitButtonEx first.
Examples.
The above creates a button with text and a bitmap with a flat style as shown below.
The above creates a button using CreateWindow() with a border. Always use the WS_CHILD style when using the Windows API CreateWindow().
CONTROL "ButtonExClass", 201, "ButtonExClass", 0, 20, 24, 70, 18
The above creates a button on a dialog from the resource control statement. A button created on a dialog with automatically have the dialog's font. Use InitButtonEx(); before your call to create the dialog. See the example listing.
Examples of images within the button.
From the image above you can guess that icons or bitmaps can be used for the image, also by specifying BXS_BMPONLY one can have the image positioned in the center of the button irrespective of the text. Also with the BXS_BMPONLY style the erasing of the background is suppressed - erasing the background can cause flickering. When no text is supplied the control will position the image in the center. So, by creating a button the same size as your image the effect above will be realized, by having an image smaller than the button there will be a normal border around the button. Like so:
At this time these are the styles possible with ButtonEx
BXS_ICON | The button will have one or two icon images. Note: both Icons are assumed to be the same size. |
BXS_BITMAP | The button will have one or two bitmap images. The two images should be the same size. |
BXS_BORDER | Specifies a thicker border as well as the default border. |
BXS_LITE | Specifies that the default border uses white and black instead of the default colour scheme of COLOR_BTNSHADOW and COLOR_BTNHIGHLIGHT. |
BXS_BMPONLY | Use this style when only the bitmap should be shown. The bitmap will be centered in the button. This flag also ensures that the background is not erased before drawing the image in the button. This is important for large images when you don't want any flicker. |
BXS_LEFTTEXT | Places the text on the left side of the image. |
BXS_RIGHTTEXT | Places the
text on the right side of the image. (Default)
Note: when there are no images all text centered. |
BXS_TOPTEXT | Places the text centered above image. |
BXS_BOTTOMTEXT | Places the text centered below image. |
BXS_NOSYSCOLORCHANGE | When a
WM_SYSCOLORCHANGE message arrives your application must pass on that
message to the ButtonEx control - the reason is the system does not send
child windows this message.
All bitmaps by default are altered by the ButtonEx control to reflect the system color change for the button background colour, however, you may not want any changes to your bitmap - use this style flag, BXS_NOSYSCOLORCHANGE to stop ButtonEx from changing your bitmap. See the example listing for clarification. |
BXS_TABSTOP | Causes the
input focus to move to the next control that has BXS_TABSTOP style when
the tab key is pressed.
Using the 'space bar' or 'return' when the control has the input focus is equivalent to causing a WM_LBUTTONDOWN followed by WN_LBUTTONUP. |
BXS_FOCUSRECT | Causes the control to have a Focus Rectangle drawn when it has the input focus. |
BXS_TOOL | This style of control behaves more like a toolbar button. In the normal state the button does not have a border, when the mouse is over the control the button will become raised and when clicked with the left mouse will become sunken. |
BXS_TOOLGROUP | As a BXS_TOOL but each button stays depressed when clicked until another button with the BXS_TOOLGROUP is depressed. Each depressed button excludes all others of the same style from being depressed. |
BXS_NORMAL | If BXS_NORMAL style gives the same border as a normal windows border - if it is used it will over-ride all other styles that affect the border. Colours will also be the normal windows colours. |
BXS_XP | Not the same as an XP button but looks good and is similer to the XP button. When using the BXS_FOCUSRECT style in combination with BXS_XP the shading of the button turns blue when it has the ficus. |
This is what the XP button looks like. The first has the BXS_FOCUSRECT style added and has the focus. | ![]() |
![]() |
|
Here is the image from the example listing showing the various styles possible.
Current list of functions for the buttonex control
HWND CreateButtonEx(char * text, DWORD dwStyle, int x, int y, int cx, int cy, HWND hWndParent, DWORD ctrlID);
This creates the ButtonEx control - the control is always a child of the parent window and will usually have various styles specified. The default style is a border using the system default colours of COLOR_BTNSHADOW and COLOR_BTNHIGHLIGHT.
Return values:
If successful the function returns the handle to the newly created control. If not successful NULL is returned.
BOOL InitButtonEx(void);
When using the main creation API CreateButtonEx() the control is automatically initialized so there is no need to use InitButtonEx.
However, when using either a CONTROL statement in a dialog template or using the Windows API CreateWindow() one must call InitButtonEx to initialize the control first. InitButtonEx only initializes the control once, all other calls are ignored so you can safely have more than one instance of this call in your code. For example when using a control on a dialog one should call InitButtonEx first.
switch (message){
case WM_COMMAND:
switch(LOWORD(wParam)){
case IDM_ABOUT:
InitButtonEx();
DialogBox(hInst,
MAKEINTRESOURCE(DLG_100), hWnd, AboutDlg);
break;
If one tries a create a ButtonEx control without the control being registered by a call to InitButtonEx() there will be no button unless you have called the API CreateButtonEx() first.
Return values:
If successful the function returns TRUE, otherwise it returns FALSE.
void ExitButtonEx(void);
When your application terminates use ExitButtonEx so that a few GDI objects can be destroyed.
Note: The ButtonEx control does not cleanup any GDI objects that you create, these GDI objects should be explicitly destroyed by you when no longer needed.
Return values:
No return value.
syntax:
int Butx_AddToolTipText(HWND hBut, char * str);
Butx_AddToolTipText adds a tooltip to the control. To split the text into separate lines use the return/newline combination sequence.
"Tooltip\r\nText"
Return values:
On success returns 0, on failure returns -1;
syntax:
int Butx_GetBkColor( HWND hBut );
This retrieves the background colour. One can use the Windows API SendMessage() instead.
Example
COLOREF col = SendMessage(hBut, BXM_GETBKCOLOR, 0, 0);
Return values:
The COLORREF of the background colour.
syntax:
void Butx_SetBkColor(HWND hBut, COLORREF colref);
This sets the background colour for the button.
The Windows API SendMessage() can be used instead.
SendMessage(hBut, BXM_SETBKCOLOR, 0, colref);
Use RGB(r,g,b) to create the COLORREF value.
Return values:
No return value.
syntax:
HFONT Butx_GetFont( HWND hBut );
Butx_GetFont retrieves the button's font. When first created the font is set to "MS Sans Serif" 8
You can set the font with Butx_SetFont.
SendMessage can be used instead.
SendMessage(hBut, BXM_GETFONT, 0, 0);
Return Values:
The Font handle.
syntax:
void Butx_SetFont( HWND hBut, HFONT hFont );
Butx_SetFont sets the button's font. Use a Windows font API to create the font.
SendMessage can be used instead.
SendMessage(hBut, BXM_SETFONT, (WPARAM)hFont, 0);
Return Values:
No return value
syntax:
void Butx_SetCursor(HWND hBut, HCURSOR hCur);
Butx_SetCursor sets the button's cursor. The default cursor is an the system's IDC_ARROW.
Return Values:
No return value
syntax:
Butx_GetText(HWND hBut, char * buf, int len);
Butx_GetText retrieves the text of the control. One should pass a pointer to a buffer and the maximum length of the buffer.
One can use SendMessage instead.
SendMessage(hBut, BXM_GETTEXT, (WPARAM)len, (LPARAM)char * buffer);
Return Values:
No return value.
syntax:
int Butx_SetText(HWND hBut, char * str);
Butx_SetText replaces or sets the text in the button.
SendMessage(hBut, BXM_SETTEXT, 0, (LPARAM)char * text);
Return Values:
On success returns 0, on failure returns -1.
syntax:
COLORREF Butx_GetTextColor( HWND hBut );
Butx_GetTextColor returns the colour of the text as a COLORREF value.
syntax:
void Butx_SetTextColor( HWND hwndBx, COLORREF colref );
Butx_SetTextColor sets the colour for the button's text. No return value.
syntax:
Butx_ShowWindow( HWND hwndBx, int nShow );
Butx_ShowWindow is only necessary when creating the button with Windows API CreateWindow() when the WM_VISIBLE style has not been used.
No return value.
syntax:
Butx_Style( HWND hwndBx, DWORD style );
Butx_Style is used to change the current style and will include WS_CHILD and WS_VISIBLE when updating the style.
When using Windows API SetWindowLong() you must include WS_CHILD otherwise it'll change the window to a non-child window, plus when using SetWindowLong() you should include WS_VISIBLE otherwise the window will vanish.
Examples
No return value.
syntax:
void Butx_libvers( void );
Butx_libvers dislays a MessageBox showing the version number of this custom control library.
syntax:
void Butx_SysColorChange(HWND hWndParent);
Butx_SysColorChange needs to be called when your application receives a WM_SYSCOLORCHANGE message. It means the user has changed some of the system's default colours.
Pass the window handle of the button's Parent Window, the control library will enumerate all child windows and adjust colours accordingly.
Note: Some bitmaps may not need any colours changing, use BXS_NOSYSCOLORCHANGE as one of the sytle flags of the button if you want your bitmap to remain untouched.
See the example listing for usage.
No return value.
syntax:
void Butx_SetToolGroup(HWND hBut);
Butx_SetToolGroup will cause a button with the BXS_TOOL and BXS_TOOLGROUP to be depressed.
The parent Window will receive a WM_COMMAND message as if the button had been clicked by the user. This is intended specifically for use on start-up when you may need to set a particular button as depressed.
This function will only work with BXS_TOOLGROUP buttons.
No return value.
syntax:
HBITMAP LoadConvertBitmapCols(int res, COLORREF colfrom, COLORREF colto);
LoadConvertBitmapCols will load a resource bitmap and convert one colour to another. This will be used mainly for ensuring the background colour is the same as a button colour, COLOR_BTNFACE.
See the example listing for usage.
END