C++ Builder: Run external application / Open document

Can you run an external program from within a C++ program? How to print documents from within your program, without explicitly starting the application that created the document, such as: print a Word-document without starting Word? How to open your browser with a local HTML document? How to surf to a site, i.e. open an external HTML page?

All of this is possible by calling ShellExecute, a Windows API function.

The syntax is:

ShellExecute( hwnd, pOperation, pFile, pParameters, pDirectory, nShowCmd )

• hwnd: handle to the parent window. This value can be NULL.
• pOperation: the action to be performed. 
  • "explore": explores the folder specified by pFile.
  • "open": opens the item specified by pFile. The item can be a file or folder.
  • "print": prints the file specified by pFile. If pFile is not a document file, the function fails.
• pFile: the file or object on which to execute the action specified with pOperation.
• pParameters: the parameters to be passed to the application. If pFile specifies a document file, pParameters should be NULL.
• pDirectory: the default (working) directory for the action. If this value is NULL, the current working directory is used.
• nShowCmd: how the application is to be displayed. Can be: SW_HIDE, SW_MAXIMIZE, SW_MINIMIZE, SW_SHOWNORMAL.

Important notes

• ShellExecute does not accept C++ Unicode strings in the parameters pOperation, pFile, pParameters or pDirectory. It expects pointers to C-style "null-terminated" strings. Don't worry, just look at the examples.
• In order to open a document with the correct application, Windows looks at the file extension, such as .doc, .txt, .htm, .html,...
  Thus, "MyFile.doc" will be opened with MS Word or with Open Office, but usually Windows doesn't know what to do with simply "MyFile".
• Some of the parameters of ShellExecude are optional, they can be NULL.
• C++ treats a backslash as an "escape" character. Thus, "\" must be coded as "\\".

Examples

Run the application NotePad.exe:

void __fastcall TForm1::Button1Click(TObject *Sender)
{
  String Prog = "notepad.exe";
 // ShellExecute does not accept Unicode strings, use a literal...
  // ...such as L"open" or convert from Unicode with c_strc()
  ShellExecute(NULL, L"open", Prog.c_str(), NULL, NULL, SW_SHOWNORMAL);
}

Run NotePad.exe and specify a text file:

void __fastcall TForm1::Button2Click(TObject *Sender)
{
  String Prog = "notepad.exe";
  String TheFile = "C:\\test\\text.txt"; // double backslashes!
  ShellExecute(NULL, L"open", Prog.c_str(), TheFile.c_str(), NULL, SW_SHOWNORMAL);
}

Open a text file with Windows' default text editor:

void __fastcall TForm1::Button3Click(TObject *Sender)
{
  String TheFile = "C:\\test\\text.txt";
  ShellExecute(NULL, L"open", TheFile.c_str(), NULL, NULL, SW_SHOWNORMAL);
}

Explore a folder (directory):

void __fastcall TForm1::Button4Click(TObject *Sender)
{
  String TheFolder = "C:\\";
  ShellExecute(NULL, L"explore", TheFolder.c_str(), NULL, NULL, SW_SHOWNORMAL);
}

Open a local HTML file in your default browser:

void __fastcall TForm1::Button5Click(TObject *Sender)
{
  String TheFile = "C:\\test\\test.htm";
  ShellExecute(NULL, L"open", TheFile.c_str(), NULL, NULL, SW_SHOWNORMAL);
}

Open a web page in your default browser:

void __fastcall TForm1::Button6Click(TObject *Sender)
{
  String ThePage = "http://www.festra.com";
  ShellExecute(NULL, L"open", ThePage.c_str(), NULL, NULL, SW_SHOWNORMAL);
}