July 1997

Using forms in console applications

It's no secret that C++Builder is an incredible programming tool. C++Builder really shines when it comes to designing the user interface for an application. In addition, C++Builder's visual programming capability lets you prototype your application in the shortest possible amount of time, as compared to other C++ programming environments.

But C++Builder is more than just another pretty face--you can use it to write console applications and Dynamic Link Libraries (DLLs), too. Even though a console application is character-based (non-graphical), you can still call common dialog boxes or VCL forms from the application if you need to. In this article, we'll explain how. (If you need a refresher on console applications, see "What's a Console Application?")

Getting started

Okay, that was easy enough. Now you need to create a form that you can display from the console app. To do so, click the New Form button on the C++Builder ToolBar, or choose File | New Form from the main menu. Obviously, we haven't yet written any code to display the form, but you might be surprised to learn that the application won't even compile right now. The console application has no knowledge of VCL at this point, so you'll have to educate it. To better understand this process, let's talk a little about how C++Builder operates when you're building a GUI application.

When you add a form to a Windows GUI application, C++Builder places the following line in the project source file:

USEFORM("Unit1.cpp", Form1);

When you add a form to a console application, C++Builder adds the same line to the application's source code. The problem is that your console application--since it isn't a VCL application--doesn't know what the USEFORM macro is. So, you need to include the VCL.H header. To do that, add the following line below the other includes and just above the #pragma hdrstop line:

#include <vcl\vcl.h>

Next, you need to be sure that the console application can find the declaration for the form's class. When you add a new form to a GUI application, you make the form available to any units that reference the form by choosing File | Include Unit Hdr... from the C++Builder main menu. For some inexplicable reason, this menu item is unavailable when you're building a console application. As a result, at the time you add a form to a console application, you must manually enter the code to include the form's header. To do so, add a line like the following to the project's main unit, this time below the #pragma hdrstop line:

#include "Unit1.h";

In a GUI application, C++Builder auto-creates forms unless you specify that it shouldn't. If a form is auto-created, then you can show it without any fuss, as follows:

Form1->ShowModal();

But, in real-world applications, not all forms are auto-created. If a form isn't auto-created, you need to specifically create the form before you can show it. In that case, the code looks like the following:

Form1 = new
TForm1(this);
Form1->ShowModal();

TForm1* form = new TForm1(0);
form->ShowModal();
delete form; 

Typically, when you create a form at runtime in a GUI application, you'll use code like the following:

TForm1* form = new TForm1(this);

So what should you do? You have two basic choices. One choice is to supply no owner for the form. In other words, you can just pass a 0 in a form's constructor, as follows:

TForm1* form = new TForm(0);

Your second choice is to supply the Application object as the form's parent. (Even though you've written a console application, VCL still creates an Application object--it does so automatically whenever you use VCL objects in a console application.) If you choose this route, you'll write code something like this:

TForm1* form = new TForm(Application);

First, you must determine the window handle of the console window. (For more information on finding the window handle for a console application, see "Finding a Console Window.") Once you know the window handle, the code to simulate a modal dialog box in a console application looks like the following:

EnableWindow(hWnd, false);
TForm1* form = new TForm1(0);
form->ShowModal();
delete form;
EnableWindow(hWnd, true);

ShowWindow(Application->Handle, SW_HIDE);

Listing A: ConsForm.cpp

//--------------------------------------------------
#include <vcl\condefs.h>
#include <stdio.h>
#include <stdlib.h>

// Add these includes:
#include <vcl\vcl.h>
#include <conio.h>
#include <iostream.h>
#pragma hdrstop

// Include STL string header.
#include <string>

// Include the form's header.
#include "Form.h"

// Declaration for the GetHWND() function.
HWND GetHWND();

//--------------------------------------------------
USERES("ConsForm.res");
USEFORM("Form.cpp", Form1);
//--------------------------------------------------

int main(int argc, char **argv)
{
  // Get the window handle of the console window.
  HWND hWnd = GetHWND();
  // This is just so that the console window has
  // focus when run from the debugger.
  BringWindowToTop(hWnd);
  // A little menu loop.
  bool done = false;
  do {
    clrscr();
    cout << endl;
    cout << "Please choose one of the following.";
    cout << endl << endl;
    cout << "0. Quit" << endl;;
    cout << "1. Simulate File Open" << endl;
    cout << "2. Show Form" << endl;
    int choice;
    do {
      choice = getch();
      choice -= 48;
    } while (choice < -1 || choice > 2);

    // Do something based on the choice made.
    switch (choice) {
    // All done. Get out of loop.
      case 0 : {
        done = true;
        break;
      }

    // Show the common file open dialog.
      case 1 : {
        // Disable the console window.
        EnableWindow(hWnd, false);

        // Create an instance of the TOpenDialog
        // class and set the filter.
        TOpenDialog* dlg = new TOpenDialog(0);
        dlg->Filter = "All files (*.*)|*.*";

        // Show the dialog.
        bool result = dlg->Execute();

        // Enable the console window and bring it to the top.
        EnableWindow(hWnd, true);
        BringWindowToTop(hWnd);

        // If the OK button was pressed then
        // show the name of the file chosen.
        if (result) {
          cout << endl << "The file opened was: " << dlg->FileName << endl << endl;
          cout << "Press any key to continue...";
          getch();
        }

        // Delete the dialog object.
        delete dlg;
        break;
      }
      case 2 : {
        // Disable the console window.
        EnableWindow(hWnd, false);

        // Create an instance of the TForm
        // class and show the form.
        TForm1* Form1 = new TForm1(0);
        int x = Form1->ShowModal();

        // Enable the console window and
        // bring it to the top.
        EnableWindow(hWnd, true);
        BringWindowToTop(hWnd);

        // Display the results of the modal form.
        cout << endl << "Modal result: " << x << endl;
        cout << endl <<  "Press any key to continue...";
        getch();
        delete Form1;
        break;
      }
    }
  } while(!done);
  return 0;
}

//------------------------------------------------------------
// This routine gets the window handle of the console 
// window. Win95 and NT handle console windows 
// differently so we have to check and see what OS 
// we're running under and take appropriate measures.
HWND GetHWND()
{
  char title[256] = "";
  char className[20] = "";
  
  // Get the name of this executable.
  GetModuleFileName(0, title, sizeof(title));

  // See if we're running on Win95 or NT.
  TOSVersionInfo info;
  info.dwOSVersionInfoSize = sizeof(info);
  GetVersionEx(&info);
  int platform = info.dwPlatformId;

  // If NT then the class name is 'ConsoleWindowClass'
  // and the title is the entire path and filename.
  if (platform == VER_PLATFORM_WIN32_NT)
    strcpy(className, "ConsoleWindowClass");
  
  // If Win95 then the class name is 'tty' and
  // the window title is just the filename
  // without path and extension.
  else {
    strcpy(className, "tty");
 
    // Strip off everything but the file name.
    std::string name = title;
    int pos = name.find_last_of("\\");
    name.remove(0, ++pos);
    name.remove(name.length() - 4, 4);
    strcpy(title, name.c_str());
  }

  // Return the result of FindWindow().
  return FindWindow(className, title);
}