What's in a (form) name?

by Mark G. Wiseman

To paraphrase Shakespeare, "What’s in a form name? That which we call TForm1 by any other name would display as well." As it turns out there is a lot to consider when naming a form, particularly the main form in a program.

I’ll leave Romeo to Juliet and continue by paraphrasing T. S. Eliott:

The naming of forms is a difficult matter,

It isn’t just one of your programmer games;

You may think that I am as mad as a hatter

When I tell you, a form must have THREE DIFFERENT NAMES.

The form class

First of all, there's the name that programmers use daily, Such as TForm1, TMainForm or TOpenDialog,

When you create a new Application in the IDE, a new class is created for you. This class is named TForm1 by default. (The Name property in the Object Inspector.) This is a class derived publicly from TForm. TForm is the VCL encapsulation of a typical Windows application window or form.

You could leave this class named TForm1; but there is good reason to change it. TForm1 gives no clue as to the function of the form. You could change it to TMainForm. In simple applications, I sometimes use TMainForm, especially if I will have other forms in the application.

However, when the form becomes complicated—when it has a lot of components, properties, data members and methods, I may want to be able to reuse that form. The IDE makes form reuse easy with the Object Repository. If you’re not familiar with the Object Repository, check the IDE online help.

Naming a form’s class TMainForm may be descriptive enough within an application, but it is not descriptive enough for the Object Repository.

Let’s assume that we’re writing a text editor program that mimics the Notepad program that comes with Windows. It uses only one form, but it is a form that we might want to use again in another application. What if we named that form TTextEditorForm or TNotepadForm? Either of these would do nicely.

We can make it even better though. Below is the prototype for the Windows API function, FindWindow():

HWND FindWindow(
   LPCTSTR lpClassName,
   LPCTSTR lpWindowName
   );

This function retrieves the handle to the top-level window whose class name and window name match the specified string arguments. The argument lpClassName is the form’s class name, e.g. TTextEditorForm. The lpWindowName argument can be null or it can be the caption of the window. I’ll talk more about window captions later.

If we wanted to find a running instance of our text editor application in Windows, we could make the following call to FindWindow():

HWND h = 
  FindWindow("TTextEditorForm", 0);

This would work fine, if there were no other program running that has a form with the same class name. But, since we can’t control what other programmers may name their form classes, let’s make our name more unique. Let’s take the initials of Bridges Publishing and prefix our class name with them in lowercase. We’ll use lowercase to make things more readable. Now we have TrpTextEditorForm. You can never be sure that this class name will be 100% unique, but it is unlikely you run into a conflict.

The form caption

But I tell you, a form needs a name that’s particular, a name that’s peculiar, and more dignified

The form’s caption is the name that is displayed in the form’s title bar. The Caption property of the form contains this text. This is the name that the user sees. It should be descriptive of the function of the form and may include additional information. Microsoft recommends that it contain the document name followed by a hyphen and the application name. In our text editor example, the Caption might be "Cats.txt – RP Text Editor". This tells the user that a document named "Cats.txt" is being edited by an application named "RP Text Editor".

To learn more about title bar captions, you can access Microsoft’s Official Guidelines for User Interface Developers and Designers online at

http://msdn.microsoft.com/library/
  default.asp?url=/library/en-us/
    dnwue/html/welcome.asp

Here is a function we might use in our editor application to set the form’s caption:

void __fastcall TrpTextEditorForm
  ::SetCaption(String filename)
{
  Caption = filename + " – " +
    Application->Title;
}

You could call this function with "Untitled" as the filename argument when the application starts and call the function again whenever a file is loaded or saved.

The Application title

I’d also like to talk a little bit about the Title property of TApplication. You’ll notice that I used it to build the forms caption in the example function above.

Normally, you set the application’s title using the Project Options dialog box, under the Application tab. If you don’t set this property, it will default to the name of the application’s executable file.

Here’s something you may not know. VCL applications create a hidden form to handle Windows messages and other tasks. This form’s class name is "TApplication" and its caption is the value in the application’s Title property. This can be useful information when you are using the FindWindow() function I mentioned above.

Conclusion

Hopefully, I’ve convinced you to give some thought to how you name your forms. If you were reading carefully, you’ll notice that I talked about two names for your forms, the class name and the caption; but that I hinted there were three names.

But above and beyond there’s still one name left over, and that is a name that you never will guess; the name that no programmer can discover—But Windows knows and will never confess.

Actually, Windows will confess if you named your form class well. It is the handle returned by the FindWindows() function. A deep and inscrutable singular name.