Click here to Skip to main content
15,867,771 members
Articles / Programming Languages / C++

Using the Windows RunFile Dialog - The Documented and Undocumented Way

Rate me:
Please Sign up or sign in to vote.
4.64/5 (13 votes)
8 Aug 20023 min read 119K   1.8K   18   19
An article describing how to use system RunFile dialog, both documented and undocumented way

RunFile Dialog

Introduction

In this article, I am going to describe how to start the Run file dialog that you see when launching applications from the Start/Run menu. There are two ways of doing this - first documented, using the Shell object, and the second - using the undocumented Windows shell API function which is much more flexible.

Going the Documented Way

We should create an instance of the Shell object and call its FileRun method:

C++
// Do not forget to add AfxOleInit() in the InitInstance() of the app !!!

BOOL CRunFileDlgDlg::RunDocumented( void )
{	
    IShellDispatch* pShellDisp = NULL;
    
    HRESULT hr =  ::CoCreateInstance( CLSID_Shell, NULL, 
        CLSCTX_SERVER, IID_IShellDispatch, (LPVOID*)&pShellDisp );

    if( hr == S_OK )
    {
        pShellDisp->FileRun();  
        pShellDisp->Release();
        pShellDisp = NULL;
    }
    
    return ( hr == S_OK );
}

We can just launch run file dialog and that is all - it starts stuck to the Start menu.

Going the Undocumented Way

Declaration

This way is much more flexible - it allows us to define the dialog icon, title and description. I will not jump in the deeps of the implementation; you can look it in the header and source files I have provided. The function is exported from the shell32.dll by ordinal 61 (dynamically loaded) and its declaration is as follows:

C++
BOOL
FASTCALL
RunFileDlg( 
    IN HWND    hwndOwner,       // Owner window, receives notifications
    IN HICON   hIcon,           // Dialog icon handle, if NULL default icon is used
    IN LPCTSTR lpszDirectory,   // Working directory
    IN LPCTSTR lpszTitle,       // Dialog title, if NULL default is displayed
    IN LPCTSTR lpszDescription, // Dialog description, if NULL default is displayed
    IN UINT    uFlags           // Dialog flags (see below)
);

Parameters

You can specify one or more of the following values in the uFlags parameter:

  • RFF_NOBROWSE - Remove the browse button
  • RFF_NODEFAULT - No default item selected
  • RFF_CALCDIRECTORY - Calculate the working directory from the file name
  • RFF_NOLABEL - Remove the edit box label
  • RFF_NOSEPARATEMEM - Remove the Separate Memory Space check box, NT only

Notification Handling

Other nice feature of this dialog is that it allows us to control which applications the user should run. When the user selects the OK button, it sends a notification message with the details of the program, that should be started, to the window, whose handle you passed in to this function. The notification is in the form of a WM_NOTIFY message with the wParam set to RFN_VALIDATE (-510) code and the lParam pointing to an NMRUNFILEDLG structure:

C++
typedef struct tagNMRUNFILEDLG {
    NMHDR       hdr;           // NMHDR structure
    LPCWSTR     lpszFile;      // File that should be started
    LPCWSTR     lpszDirectory; // Working directory
    int         nShow;         // How an application is to be displayed when open
} NMRUNFILEDLG, *LPNMRUNFILEDLG, *PNMRUNFILEDLG;

RunFile Dialog Test A

Notification Handling Unicode Issue

As far as this is an undocumented function, it has different signatures in Windows NT and Windows 9x - Windows NT uses UNICODE version and Windows 9x - ANSI version despite you call RunFileA or RunFileW functions. In the implementation, the operating system version is checked and all necessary conversions are done. But when handling notification message, you should check it once again, because under Windows NT, you will receive NMRUNFILEDLGW and in Windows 9x - NMRUNFILEDLGA, no matter defined UNICODE or not. See the sample:

MFC Application Sample

C++
// ...
// Add the notify handler:
// ON_NOTIFY( RFN_VALIDATE, 0, OnRunFileDlgOK )
// ...

void CSomeDlg::OnRunFileDlgOK( NMHDR* pNMHDR, LRESULT* pResult )
{
    LPNMRUNFILEDLG lpNMRFD = (LPNMRUNFILEDLG)pNMHDR;
    TCHAR szFile[ MAX_PATH ] = { 0 };
    
    #ifndef UNICODE // If NT we get a unicode string anyway.
        if( ::GetVersion() <  0x80000000 )	// NT4/2K/XP
             ::WideCharToMultiByte( CP_ACP, 0, (LPCWSTR)lpNMRFD->lpszFile, 
                                    -1, szFile, 2 * MAX_PATH, NULL, NULL );
    #else
        if( ::GetVersion() >  0x80000000 )	// 95/98/Me
             ::MultiByteToWideChar( CP_ACP, 0, (LPCSTR)lpNMRFD->lpszFile, 
                                   -1, szFile, 2 * MAX_PATH );
    #endif
    
    CString strMsg( _T("") );
    strMsg.Format( _T("Run the file %s ?"), szFile );
    
    int nRet = ::MessageBox( GetSafeHwnd(), strMsg, 
        _T("RunFile Dialog notification test"),
        MB_YESNOCANCEL | MB_ICONQUESTION | MB_DEFBUTTON2 );
	
    switch ( nRet )
    {
        case IDYES: *pResult = RF_OK;     break;
        case IDNO:  *pResult = RF_RETRY;  break;
        default:    *pResult = RF_CANCEL;
    }
}

Win32 Application Sample

C++
//...
// In the WindowProc
//...
case WM_NOTIFY:
{
    LPNMHDR lpNMHDR = (LPNMHDR)lParam;
    if( lpNMHDR->code == RFN_VALIDATE )
    {
        LPNMRUNFILEDLG lpNMRFD = (LPNMRUNFILEDLG)lpNMHDR;
        // lpNMRFD->lpszFile ...
        return RF_OK;
    }
}
//...

Return Values

The return value determines whether the application will be run or not.

RunFile Dialog Test B

You can use the following return values:

  • RF_OK - Allow the application to run
  • RF_CANCEL - Cancel the operation and close the dialog
  • RF_RETRY - Cancel the operation, but leave the dialog open

Compatibility

  • Windows 9x - Requires Windows 95/98/ME
  • Windows NT - Requires Windows NT4.0/2000/XP

Related Links

History

  • 8th August, 2002 - Posted article

License

This article has no explicit license attached to it, but may contain usage terms in the article text or the download files themselves. If in doubt, please contact the author via the discussion board below.

A list of licenses authors might use can be found here.


Written By
Software Developer (Senior) SafeNet Inc
United States United States
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

 
BugWrong explanation of WM_NOTIFY in your article Pin
Kerem Guemruekcue19-Dec-12 17:43
Kerem Guemruekcue19-Dec-12 17:43 
GeneralMy vote of 5 Pin
Member 803644618-Aug-11 4:44
Member 803644618-Aug-11 4:44 
GeneralInitial position of the 'Run dialog', when going the undocumented way [modified] Pin
Alexandru Matei9-Aug-06 2:21
Alexandru Matei9-Aug-06 2:21 
QuestionHow did you find out the parameters of RunFileDlg? [modified] Pin
Alexandru Matei9-Aug-06 0:54
Alexandru Matei9-Aug-06 0:54 
GeneralRunFileDlg on VB 6.0 Pin
Willian.BR29-Apr-04 4:06
sussWillian.BR29-Apr-04 4:06 
GeneralRe: RunFileDlg on VB 6.0 Pin
Member 145156454-Aug-19 15:16
Member 145156454-Aug-19 15:16 
GeneralAnsi vs. Unicode Pin
Member 63269512-Oct-03 11:23
Member 63269512-Oct-03 11:23 
QuestionBut if I don't want to see the run dialog ? Pin
Zjxin10-Nov-02 16:03
Zjxin10-Nov-02 16:03 
AnswerRe: But if I don't want to see the run dialog ? Pin
Armen Hakobyan11-Nov-02 1:40
professionalArmen Hakobyan11-Nov-02 1:40 
AnswerRe: But if I don't want to see the run dialog ? Pin
Zjxin11-Nov-02 14:05
Zjxin11-Nov-02 14:05 
GeneralRe: But if I don't want to see the run dialog ? Pin
Armen Hakobyan12-Nov-02 6:24
professionalArmen Hakobyan12-Nov-02 6:24 
AnswerRe: But if I don't want to see the run dialog ? Pin
Anonymous7-Jan-04 4:12
Anonymous7-Jan-04 4:12 
GeneralRe: But if I don't want to see the run dialog ? Pin
Armen Hakobyan7-Jan-04 13:38
professionalArmen Hakobyan7-Jan-04 13:38 
QuestionClear RUN dialog? Pin
Frank.NET10-Aug-02 4:47
Frank.NET10-Aug-02 4:47 
AnswerRe: Clear RUN dialog? Pin
Armen Hakobyan10-Aug-02 9:55
professionalArmen Hakobyan10-Aug-02 9:55 
GeneralRe: Clear RUN dialog? Pin
Anonymous15-Aug-02 1:35
Anonymous15-Aug-02 1:35 
Thanks for the hint. But this only clears the RUN dialog that is displayed in your application, the standard Windows RUN dialog still contains the old values Frown | :(
Any other ideas? Big Grin | :-D
AnswerRe: Clear RUN dialog? Pin
Armen Hakobyan16-Aug-02 0:57
professionalArmen Hakobyan16-Aug-02 0:57 
GeneralRe: Clear RUN dialog? Pin
Anonymous11-Sep-02 3:08
Anonymous11-Sep-02 3:08 
GeneralRe: Clear RUN dialog? Pin
Armen Hakobyan28-Jul-04 6:38
professionalArmen Hakobyan28-Jul-04 6:38 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.