Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
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 OKbutton 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 Donebutton.

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 Donebutton will appear. Note that hwndRequestercannot 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 Donebutton 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 Donebutton is managed by the shell, and showing or hiding the OKbutton happens automatically. A top-level window that needs the Donebutton to appear should use the WS_EX_CAPTIONOKBTN window style.

To make the OKbutton 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 OKbutton should appear in the taskbar. The OKbutton takes precedence over a menu bar added to the taskbar.

To suppress the OKbutton, use the WS_NONAVDONEBUTTON style.

Typically, the Donebutton (the OKbutton that appears in the upper-right corner of the screen) is managed by the shell, and showing or hiding the OKbutton happens automatically. A top-level window that needs the Donebutton 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 OKbutton 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 OKbutton should appear in the navigation bar.

To suppress the OKbutton, 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.
Copy Code 
// 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

See Also