SHDoneButton

Article
11/18/2015

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

Share via