CMFCEditBrowseCtrl Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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.

class CMFCEditBrowseCtrl : public CEdit  

Public Constructors

NameDescription
CMFCEditBrowseCtrl::CMFCEditBrowseCtrlDefault constructor.
CMFCEditBrowseCtrl::~CMFCEditBrowseCtrlDestructor.

Public Methods

NameDescription
CMFCEditBrowseCtrl::EnableBrowseButtonEnables or disables (hides) the browse button.
CMFCEditBrowseCtrl::EnableFileBrowseButtonEnables the browse button and puts the edit browse control in file browse mode.
CMFCEditBrowseCtrl::EnableFolderBrowseButtonEnables the browse button and puts the edit browse control in folder browse mode.
CMFCEditBrowseCtrl::GetModeReturns the current browse mode.
CMFCEditBrowseCtrl::OnAfterUpdateCalled by the framework after the edit browse control is updated with the result of a browse action.
CMFCEditBrowseCtrl::OnBrowseCalled by the framework after the user clicks the browse button.
CMFCEditBrowseCtrl::OnChangeLayoutRedraws the current edit browse control.
CMFCEditBrowseCtrl::OnDrawBrowseButtonCalled by the framework to draw the browse button.
CMFCEditBrowseCtrl::OnIllegalFileNameCalled by the framework when an illegal file name was entered in the edit control.
CMFCEditBrowseCtrl::PreTranslateMessageTranslates window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. For syntax and more information, see CWnd::PreTranslateMessage.
CMFCEditBrowseCtrl::SetBrowseButtonImageSets a custom image for the browse button.

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.

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.

CObject

CCmdTarget

CWnd

CEdit

CMFCEditBrowseCtrl

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();

Header: afxeditbrowsectrl.h

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.

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.

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.

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.

ValueDescription
BrowseMode_Defaultcustom mode. A programmer-defined action is performed.
BrowseMode_Filefile mode. The standard file browser dialog box is displayed.
BrowseMode_Folderfolder mode. The standard folder browser dialog box is displayed.
BrowseMode_NoneThe browse button is not displayed.

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.

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.

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.

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.

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.

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.

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 can not 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

Hierarchy Chart
Classes

Show: