SHDoneButton
A version of this page is also available for
4/8/2010
This function is provided for applications that need to dynamically show or hide the OK button based on the state of the application.
Syntax
BOOL SHDoneButton(
HWND hwndRequester,
DWORD dwState
);
Parameters
- hwndRequester
[in] Handle to the top-level window requesting the Done button.
dwState
[in] Specifies the button state. The following table shows the possible states values for this parameter.State Description SHDB_SHOW
Adds WS_EX_CAPTIONOKBTN to hwndRequester. Next time this window becomes the foreground window, the Done button will appear. Note that hwndRequester cannot be set to the WS_CAPTION style. For more information on WS_EX_CAPTIONOKBTN and WS_CAPTION, see Non-client Area Styles.
SHDB_HIDE
Removes the WS_EX_CAPTIONOKBTN from hwndRequester. The Done button will not appear the next time this window becomes the foreground window.
SHDB_SHOWCANCEL
Enables the Cancel [x] button to have cancel semantics. SHDB_SHOWCANCEL shows the [x] button but makes it send a WM_COMMAND or IDCANCEL when pressed.
Return Value
This function returns TRUE if it is successful and FALSE if it fails.
Remarks
Typically, the Done button is managed by the shell, and showing or hiding the OK button happens automatically. A top-level window that needs the Done button to appear should use the WS_EX_CAPTIONOKBTN window style.
To make the OK button appear, ensure that your window does not have either the WS_CAPTION or WS_CHILD styles.
Whenever the foreground window changes, the shell checks the style bits of the window to determine if the OK button should appear in the taskbar. The OK button takes precedence over a menu bar added to the taskbar.
To suppress the OK button, use the WS_NONAVDONEBUTTON style.
Typically, the Done button (the OK button that appears in the upper-right corner of the screen) is managed by the shell, and showing or hiding the OK button happens automatically. A top-level window that needs the Done button to appear should use the following window styles:
- Must have WS_EX_CAPTIONOKBTN
- Must not have WS_CAPTION
WS_CHILD
Note
WS_CAPTION is defined as (WS_BORDER WS_DLGFRAME). To make the OK button appear, you must ensure that your window does not have either of these styles.
Whenever the foreground window changes, the shell checks the style bits of the window to determine if the OK button should appear in the navigation bar.
To suppress the OK button, use the WS_NONAVDONEBUTTON style.
Code Example
The following code example demonstrates how to use SHDoneButton.
Note
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
// Show or hide a window's Done button.
BOOL SHDoneButtonExample(HWND hWnd, BOOL fShow)
{
if (fShow)
{
// Show the Done button when the window moves to the foreground.
return SHDoneButton(hWnd, SHDB_SHOW);
}
else
{
// Hide the Done button when the window moves from the foreground.
return SHDoneButton(hWnd, SHDB_HIDE);
}
}
Requirements
| Header | aygshell.h |
| Library | aygshell.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Pocket PC 2000 and later, Smartphone 2002 and later |