BFFCALLBACK function pointer

  • Article

Specifies an application-defined callback function used to send messages to, and process messages from, a Browse dialog box displayed in response to a call to SHBrowseForFolder.

Syntax

typedef int ( CALLBACK *BrowseCallbackProc)(
   HWND   hwnd,
   UINT   uMsg,
   LPARAM lParam,
   LPARAM lpData
);

Parameters

hwnd

Type: HWND

The window handle of the browse dialog box.

uMsg

Type: UINT

The dialog box event that generated the message. One of the following values.

BFFM_INITIALIZED

The dialog box has finished initializing.

BFFM_IUNKNOWN

An IUnknown interface is available to the dialog box.

BFFM_SELCHANGED

The selection has changed in the dialog box.

BFFM_VALIDATEFAILED

The user typed an invalid name into the dialog's edit box. A nonexistent folder is considered an invalid name.

lParam

Type: LPARAM

A value whose meaning depends on the event specified in uMsg as follows:

uMsg lParam
BFFM_INITIALIZED Not used, value is NULL.
BFFM_IUNKNOWN A pointer to an IUnknown interface.
BFFM_SELCHANGED A PIDL that identifies the newly selected item.
BFFM_VALIDATEFAILED A pointer to a string that contains the invalid name. An application can use this data in an error dialog informing the user that the name was not valid.

 

lpData

Type: LPARAM

An application-defined value that was specified in the lParam member of the BROWSEINFO structure used in the call to SHBrowseForFolder.

Return value

Type: int

Returns zero except in the case of BFFM_VALIDATEFAILED. For that flag, returns zero to dismiss the dialog or nonzero to keep the dialog displayed.

Remarks

To attach your BrowseCallbackProc to a dialog, specify its address in the lpfn member of the BROWSEINFO structure used in a SHBrowseForFolder call.

BrowseCallbackProc can also send messages to the dialog box through SendMessage, to control these aspects:

  • OK button enabled/disabled
  • OK button text
  • Selected folder
  • Expanded folder
  • Status text

Set the SendMessage function's Msg parameter to one of the following values, providing additional information in the wParam and lParam parameters as indicated for each message type.

Msg Meaning wParam lParam
BFFM_ENABLEOK Enables or disables the dialog box's OK button. Not used. To enable, set to a nonzero value. To disable, set to zero.
BFFM_SETOKTEXT Version 6.0 or later. Sets the text that is displayed on the dialog box's OK button. Not used. A pointer to a null-terminated Unicode string that contains the desired text.
BFFM_SETSELECTION Specifies the path of a folder to select. The path can be specified as a string or a PIDL. TRUE to use a string; FALSE to use a PIDL. The string or PIDL that specifies the path.
BFFM_SETEXPANDED Version 6.0 or later. Specifies the path of a folder to expand in the Browse dialog box. The path can be specified as a Unicode string or a PIDL. TRUE to use a string; FALSE to use a PIDL. The string or PIDL that specifies the path.
BFFM_SETSTATUSTEXT Sets the status text. Set the BrowseCallbackProc lpData parameter to point to a null-terminated string with the desired text. Not used. A pointer to a null-terminated string that contains the desired text.

 

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

 Shlobj.h

See also

SHBrowseForFolder

BROWSEINFO

SendMessage