BFFCALLBACK function pointer

Article
04/30/2018

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

Share via