CMFCEditBrowseCtrl Class

The CMFCEditBrowseCtrl class supports the edit browse control, which is an editable text box that optionally contains a browse button. When the user clicks the browse button, the control performs a custom action or displays a standard dialog box that contains a file browser or a folder browser.

Syntax

class CMFCEditBrowseCtrl : public CEdit

Members

Public Constructors

Public Methods

Remarks

Use an edit browse control to select a file or folder name. Optionally, use the control to perform a custom action such as to display a dialog box. You can display or not display the browse button, and you can apply a custom label or image on the button.

The browse mode of the edit browse control determines whether it displays a browse button and what action occurs when the button is clicked. For more information, see the GetMode method.

The CMFCEditBrowseCtrl class supports the following modes.

• custom mode

  A custom action is performed when the user clicks the browse button. For example, you can display an application-specific dialog box.

• file mode

  A standard file selection dialog box is displayed when the user clicks the browse button.

• folder mode

  A standard folder selection dialog box is displayed when the user clicks the browse button.

How-To: Specify an Edit Browse Control

Perform the following steps to incorporate an edit browse control in your application:

1. If you want to implement a custom browse mode, derive your own class from the CMFCEditBrowseCtrl class and then override the CMFCEditBrowseCtrl::OnBrowse method. In the overridden method, execute a custom browse action and update the edit browse control with the result.

2. Embed either the CMFCEditBrowseCtrl object or the derived edit browse control object into the parent window object.

3. If you use the Class Wizard to create a dialog box, add an edit control ( CEdit) to the dialog box form. Also, add a variable to access the control in your header file. In your header file, change the type of the variable from CEdit to CMFCEditBrowseCtrl. The edit browse control will be created automatically. If you do not use the Class Wizard, add a CMFCEditBrowseCtrl variable to your header file and then call its Create method.

4. If you add an edit browse control to a dialog box, use the ClassWizard tool to set up data exchange.

5. Call the EnableFolderBrowseButton, EnableFileBrowseButton, or EnableBrowseButton method to set the browse mode and display the browse button. Call the GetMode method to obtain the current browse mode.

6. To provide a custom image for the browse button, call the SetBrowseButtonImage method or override the OnDrawBrowseButton method.

7. To remove the browse button from the edit browse control, call the EnableBrowseButton method with the bEnable parameter set to FALSE.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CEdit

CMFCEditBrowseCtrl

Example

The following example demonstrates how to use two methods in the CMFCEditBrowseCtrl class: EnableFolderBrowseButton and EnableFileBrowseButton. This example is part of the New Controls sample.

CMFCEditBrowseCtrl m_wndFolderEdit;
CMFCEditBrowseCtrl m_wndFileEdit;

// enable the browse button and put the control in file browse mode
m_wndFolderEdit.EnableFolderBrowseButton();
// enable the browse button and put the control in the folder browse mode
m_wndFileEdit.EnableFileBrowseButton();

Requirements

Header: afxeditbrowsectrl.h

CMFCEditBrowseCtrl::EnableBrowseButton

Displays or does not display the browse button on the current edit browse control.

void EnableBrowseButton(
    BOOL bEnable=TRUE,
    LPCTSTR szLabel=_T("..."));

Parameters

bEnable
TRUE to display the browse button; FALSE not to display the browse button. The default value is TRUE.

szLabel
The label that is displayed on the browse button. The default value is " ...".

Remarks

If the bEnable parameter is TRUE, implement a custom action to perform when the browse button is clicked. To implement a custom action, derive a class from the CMFCEditBrowseCtrl class and then override its OnBrowse method.

If the bEnable parameter is TRUE, the browse mode of the control is BrowseMode_Default; otherwise, the browse mode is BrowseMode_None. For more information about browse modes, see the GetMode method.

CMFCEditBrowseCtrl::EnableFileBrowseButton

Displays the browse button on the current edit browse control and puts the control in file browse mode.

void EnableFileBrowseButton(
    LPCTSTR lpszDefExt=NULL,
    LPCTSTR lpszFilter=NULL,
    DWORD dwFlags = OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT);

Parameters

lpszDefExt
Specifies the default file name extension that is used in the file selection dialog box. The default value is NULL.

lpszFilter
Specifies the default filter string that is used in the file selection dialog box. The default value is NULL.

dwFlags
Dialog box flags. The default value is a bitwise combination (OR) of OFN_HIDEREADONLY and OFN_OVERWRITEPROMPT.

Remarks

When the edit browse control is in file browse mode and the user clicks the browse button, the control displays the standard file selection dialog box.

For a full list of available flags, see OPENFILENAME structure.

CMFCEditBrowseCtrl::EnableFolderBrowseButton

Displays the browse button on the current edit browse control and puts the control in folder browse mode.

void EnableFolderBrowseButton();

Remarks

When the edit browse control is in folder browse mode and the user clicks the browse button, the control displays the standard folder selection dialog box.

CMFCEditBrowseCtrl::GetMode

Retrieves the browse mode of the current edit browse control.

CMFCEditBrowseCtrl::BrowseMode GetMode() const;

Return Value

One of the enumeration values that specifies the current mode of the edit browse control. The browse mode determines whether the framework displays the browse button and what action occurs when a user clicks that button.

The following table lists the possible return values.

Remarks

By default, a CMFCEditBrowseCtrl object is initialized to BrowseMode_None mode. Modify the browse mode with the CMFCEditBrowseCtrl::EnableBrowseButton, CMFCEditBrowseCtrl::EnableFileBrowseButton, and CMFCEditBrowseCtrl::EnableFolderBrowseButton methods.

CMFCEditBrowseCtrl::OnAfterUpdate

Called by the framework after the edit browse control is updated with the result of a browse action.

virtual void OnAfterUpdate();

Remarks

Override this method in a derived class to implement a custom action.

CMFCEditBrowseCtrl::OnBrowse

Called by the framework after the user clicks the browse button of the edit browse control.

virtual void OnBrowse();

Remarks

Use this method to execute custom code when the user clicks the browse button of the edit browse control. Derive your own class from the CMFCEditBrowseCtrl class and override its OnBrowse method. In that method, implement a custom browse action and optionally update the text box of the edit browse control. In your application, use the EnableBrowseButton method to put the edit browse control in custom browse mode.

CMFCEditBrowseCtrl::OnChangeLayout

Redraws the current edit browse control.

virtual void OnChangeLayout();

Remarks

The framework calls this method when the browse mode of the edit browse control changes. For more information, see CMFCEditBrowseCtrl::GetMode.

CMFCEditBrowseCtrl::OnDrawBrowseButton

Called by the framework to draw the browse button on the edit browse control.

virtual void OnDrawBrowseButton(
    CDC* pDC,
    CRect rect,
    BOOL bIsButtonPressed,
    BOOL bIsButtonHot);

Parameters

pDC
A pointer to a device context.

Rect
The bounding rectangle of the browse button.

bIsButtonPressed
TRUE if the button is pressed; otherwise, FALSE.

bIsButtonHot
TRUE if the button is highlighted; otherwise, FALSE.

Remarks

Override this function in a derived class to customize the appearance of the browse button.

CMFCEditBrowseCtrl::SetBrowseButtonImage

Sets a custom image on the browse button of the edit browse control.

void SetBrowseButtonImage(
    HICON hIcon,
    BOOL bAutoDestroy= TRUE);

void SetBrowseButtonImage(
    HBITMAP hBitmap,
    BOOL bAutoDestroy= TRUE);

void SetBrowseButtonImage(UINT uiBmpResId);

Parameters

hIcon
The handle of an icon.

hBitmap
The handle of a bitmap.

uiBmpResId
The resource ID of a bitmap.

bAutoDestroy
TRUE to delete the specified icon or bitmap when this method exits; otherwise, FALSE. The default value is TRUE.

Remarks

Use this method to apply a custom image to the browse button. By default, the framework obtains a standard image when the edit browse control is in file browse or folder browse mode.

CMFCEditBrowseCtrl::OnIllegalFileName

Called by the framework when an illegal file name was entered in the edit control.

virtual BOOL OnIllegalFileName(CString& strFileName);

Parameters

strFileName
Specifies the illegal file name.

Return Value

Should return FALSE if this file name cannot be passed further to the file dialog. In this case, focus is set back to the edit control and the user should continue editing. The default implementation displays a message box telling the user about the illegal file name and returns FALSE. You can override this method, correct the file name, and return TRUE for further processing.

Remarks

See also

Hierarchy Chart
Classes