Hans Dietrich Software

Announcements

We now offer the option of perpetual licenses for most components, which give you free upgrades for life. Please contact us for details.

A new Tips & Tricks page has been posted.

Also new: Font Survey: 50 of the Best Monospaced Programming Fonts.

Recent Updates

• XListCtrl
  • v2.4 is here! Now use hyperlinks in subitems.
• XCrashReport
  • v2.0 Add exception handling and crash reporting to your app. Now with 64-bit support and SMTP (gmail) send.
• XMessageBox
  • v1.17 Fixes problem with modal behavior.
  • v1.15 Fixes more problems and reduces stack usage.
  • v1.14 Fixes some problems with GUI demo apps.
• XDisplayImage 1.3
  • Lightweight API to display icon, bmp, gif, jpg, and png images without using a third-party library or DLL. Now supports overwriting images with standard Win32 text controls.

New Additions

• XCaptionButton
  • Add text or image caption buttons to a window caption bar.
• XTicker
  • A scrolling news/stock ticker with gradient background.
• XHtmlListBox
  • A virtual listbox that offers HTML text formatting and anchor links.
• XHexViewCtrl
  • Win32 control to display hex data. Customizable display, including colors, fonts, and scrolling marquee.
• XListBoxCS
  • C# listbox with per-item colors, bold, printf-style formatting, autoscroll, and built-in context menu. Perfect for color-coding log output.
• Resource Inspector
  • View resources contained in any Win32 PE file, including custom types, Win32 types, names, and language id.
• XHTMLCtrl
  • Ultra-lean HTML control to display fonts, colors, hyperlinks, and images. Non-MFC control, can be used in MFC or non-MFC app.
• Random Password Generator
  • Generate multiple passwords of any length. Customizable character set
• XDate
  • Gregorian, ISO, and fiscal date classes, 220 APIs, all in one convenient header file. Non-MFC, may be used in any C++ program.
      • CGregorianDate
      • CIsoDate
      • CFiscalDate
    

Links

• Software Catalog
• Contact Us
• Custom Software
• Font Survey: 50 of the Best Monospaced Programming Fonts
• Tips & Tricks
• Recommended Tools
• Terms of Use

XCaptionButton

Many different types of applications add buttons to a window's caption bar - UltraMon, for example adds these buttons:

eMule adds a "minimize to tray" button:

SplitView adds two buttons:

Placing buttons on the caption bar gives users of these apps handy access to additional functionality and expanded features, and saves the UI designer from having to figure out where to shoehorn in another button on the main UI or dialog.

XCaptionButton is a Win32 component that allows UI designers to display caption buttons on any themed or non-themed app, including apps running under Aero. XCaptionButton requires XP w/sp2, Vista, or Windows 7.

XCaptionButton Features

XCaptionButton offers the following features:

	Written in C++ using Win32 APIs, can be added to any C++ or MFC app
	As easy to use as standard Windows Minimize/Maximize/Close buttons
	Caption buttons can be added to any window in your app that has a Windows caption bar, including those with WS_EX_TOOLWINDOW style
	Compatible with both themed and non-themed apps
	Compatible with Aero Desktop Window Manager (DWM)
	Compatible with semi-transparent (layered) windows
	Each window can have its own set of caption buttons
	Each caption button can display text or an image selected from an image list
	Button images are displayed in one of four states: normal, hot, pressed, and disabled. The hot, pressed, and disabled states are generated automatically by XCaptionButton; all you have to do is specify the normal image.
	You can choose to have images automatically sized to fit caption bar
	Each caption button can have its own tooltip; the tooltip can display multiple lines of text, and an optional icon and title.
	Captions buttons can be aligned on the left, right, or centered on the caption bar. XCaptionButton also handles the WS_EX_LAYOUTRTL style.
	The image used on a button can be switched to any other image in the image list, allowing animation effects.

Demo Application

The demo application shows how XCaptionButton can display text and image buttons:

You can try the demo on your own system by downloading it here: http://www.hdsoft.org/download/XCaptionButtonTest.exe.

XCaptionButton Class Members

Construction
	XCaptionButton()	Default constructor
	virtual BOOL Create(HINSTANCE hInstance, HWND hParent, BOOL bToolTip = FALSE, COLORREF crTransparent = RGB(255, 0, 255))	Creates and initializes the window associated with the XCaptionButton object
Attributes
	m_hWnd	Window handle of XCaptionButton
	m_hParent	parent window (passed to Create())
	m_bLButtonDown	TRUE = left mouse button pressed in caption
	m_Buttons	array of button info structs
	int GetButtonCount()	Retrieve count of buttons displayed
	int GetButtonIndex(int id)	GetButtonIndex retrieves the array index for a button id.
	BOOL GetButtonInfo(int id, BUTTON_INFO& button_info)	GetButtonInfo retrieves button info for a button.
	LAYOUT GetButtonLayout()	GetButtonLayout gets the button layout.
	int GetCaptionHeight()	GetCaptionHeight retrieves the caption height.
	int GetDarkenFactor()	GetDarkenFactor retrieves the darken factor (used when button is pressed).
	HWND GetHWND()	GetHWND retrieves the HWND of the CXCaptionButton object.
	HIMAGELIST GetImageList()	GetImageList retrieves the image list handle.
	SIZE GetImageSize()	GetImageSize retrieves the image size for the current image list.
	int GetLightenFactor()	GetLightenFactor retrieves the lighten factor (used when button is hot).
	BOOL GetRibbon()	GetRibbon returns TRUE if the app uses a ribbon UI.
	int GetTooltipDelayTime(DWORD dwWhichDuration)	GetTooltipDelayTime retrieves the tooltip time specified by dwWhichDuration.
	BOOL IsButtonEnabled(int id)	IsButtonEnabled returns TRUE if button is enabled.
	BOOL IsGdiPlusEnabled()	IsGdiPlusEnabled returns TRUE if GSI+ is being used to draw button effects.
	BOOL IsThemed(BOOL bUseTheming)	IsThemed returns TRUE if theming is applied to buttons.
	CXCaptionButton& SetButtonLayout(LAYOUT eButtonLayout)	SetButtonLayout sets the button layout.
	CXCaptionButton& SetDarkenFactor(int nFactor)	SetDarkenFactor sets the darken factor used for pressed buttons.
	CXCaptionButton& SetImageList(HIMAGELIST hImageList, COLORREF crMask, BOOL bSizeToFit)	SetImageList sets m_hImageList with the normal images from hImageList, and also adds hot, pressed, and disabled images.
	CXCaptionButton& SetLightenFactor(int nFactor)	SetLightenFactor sets the darken factor used for hot buttons.
	CXCaptionButton& SetRibbon(BOOL bRibbon)	SetRibbon sets the ribbon UI flag according to bRibbon.
	void SetTooltipDelayTime(DWORD dwWhichDuration, int nTime)	SetTooltipDelayTime sets the tooltip time for the specified time type dwWhichDuration.
Operations
	int AddButton(BUTTON_INFO& button_info)	AddButton adds a new button to the CXCaptionButton object.
	void AdjustPoint(POINT& point)	AdjustPoint Converts a point from caption coordinates to screen coordinates.
	void EnableAllButtons(BOOL bEnable)	EnableAllButtons enables or disables all buttons.
	void EnableButton(int id, BOOL bEnable)	EnableButton enables or disables a button (draws as gray).
	void EnableTooltip(BOOL bEnable)	EnableTooltip enables or disables the tooltip for all buttons.
	void EnableWindow(BOOL bEnable)	EnableWindow enables or disables the CXCaptionButton object.
	int HitTest(POINT point)	HitTest determines if point lies within a button.
	void Initialize(HWND hParent)	Initialize gets the current set of system parameters, creates new caption fonts, gets the current caption rect, and gets current theme parameters. It is called when the WM_SETTINGCHANGE or WM_THEMECHANGED messages are received.
	void Invalidate()	Invalidate causes all buttons to be redrawn.
	void RelayMessage(MSG * pMsg)	RelayMessage relays messages from the app to XCaptionButton. Usually this is necessary only when the caption bar is not a standard Windows caption bar, like MFC apps using the ribbon UI.
	void RemoveAllButtons()	RemoveAllButtons removes all buttons from CXCaptionButton object.
	BOOL RemoveButton(int id)	RemoveButton removes a button.
	BOOL UpdateImage(int id, int nImage)	UpdateImage updates a button with a new image index.
	BOOL UpdateButtonText(int id, LPCTSTR lpszText)	UpdateButtonText updates the text displayed on a button.
	BOOL UpdateTipText(int id, LPCTSTR lpszText)	UpdateTipText updates the tip text of a button.
	BOOL UpdateButtons()	UpdateButtons sets up drawing rects for all the buttons.

How To Use

Step 1: Add Files

All the files you need to add to your project are in the XCaptionButton folder in the download:

• CXDC.h
• CXRect.h
• HDBitmapUtils.cpp
• HDBitmapUtils.h
• XArray.h
• XCaptionButton.cpp
• XCaptionButton.h
• XDWMHelper.cpp
• XDWMHelper.h
• XThemeHelper.cpp
• XThemeHelper.h
• XToolTip.cpp
• XToolTip.h
• XTrace.h

The .cpp files above should be set to Not Using Precompiled Headers.

Step 2: Create XCaptionButton

XCaptionButtonTestDlg.cpp shows how to create the XCaptionButton object:

    VERIFY(m_CaptionButton.Create(AfxGetInstanceHandle(), m_hWnd, 
			m_bEnableTooltip, RGB(250, 0, 250)));
);

Step 3: Set XCaptionButton Attributes and Add Button

Next add the button; see CXCaptionButtonTestDlg::OnAdd() for an example.

Tips & Tricks

1. Horizontal centering - By default, button layout is set to Auto, which usually means buttons will be displayed on the right side of the caption bar. However, if the flag bCenterHorz is set to TRUE, buttons will be centered horizontally. Note that the bCenterHorz flag must be set for the first button added, or it will have no effect.
2. Button IDs - XCaptionButton increments an internal counter for each button added, and CXCaptionButton.AddButton() returns this unique number as the button id. An application can save this id for later; for example, to use when the WM_CAPTION_BUTTON_CLICKED message is received.
3. MDI applications - XCaptionButton may be used to place buttons on both the mainframe caption and child frame captions. However, buttons will only be displayed on active child frames.

   

4. Ribbon applications - XCaptionButton supports VS2008 and VS2010 MFC ribbon applications, with one additional requirement: the CMainFrame::PreTranslateMessage() function must call CXCaptionButton::RelayMessage(). Please refer to the sample MDIRibbon for an example of this.
5. Initial tooltip delay - The initial tooltip delay for standard caption buttons (Close, Minimize, Maximize) is longer than the normal delay for other UI elements. To be consistent with this behavior, the initial tooltip delay for XCaptionButton is also longer than normal. You can change the tooltip delay by using SetTooltipDelayTime().

Revision History

Version 1.2

• First public release

Buy latest version

Buy XCaptionButton 1.2 license – $90.00 per developer. Includes full source code to XCaptionButton and MFC dialog, MDI, and ribbon samples, with VS6, VS2008, and VS2010 projects.