The Simplest C++ Builder Program

Introduction

OK, it's probably not the simplest - after all, an empty form runs and it's simpler. But it's the simplest C++Builder program which uses all of the basic features of a typical, non-database C++ Builder program.

What does the simplest program do? It lets you input two numbers into standard Windows Edit controls (TEdit component). A result is produced by dividing the two numbers and is displayed in a label component. If the input is not a number, no result is shown.

Getting Started

First you need to create a project.

Begin by deciding where you want to put the project. I recommend creating a directory structure like this on one of your drives:

drive:\Develop\Cbuilder\Test

From the IDE (Integrated Development Environment), pick from the menu File | New Application. That creates a new project and a form. Let's save it right away. Pick File | Save Project. Get the save dialog to show the directory you created above. In that directory, create a new directory called "Simplest" (so you now have drive:\Develop\CBuilder\Test\Simplest). Save the project into that directory as "Simplest". Next, click on the form window and save the form as (File | Save As) "MainFormUnit".

Change the size of the form using the Object Inspector to Height: 150, Width: 400.

Creating The Controls On The Form

C++ Builder uses a language to describe user interfaces. Most of the time, you never see this language, because the IDE creates and manages the controls for you. But when you save a form, the controls are saved in a special file with the .dfm extension. While you don't normally look at the contents of that file, you can open it from the IDE and see the form language by specifying that you want to open the .dfm file.

What makes this especially exciting is that this language makes it possible to cut, copy, and paste components from and to a form. You can copy components from a form and edit them in a text editor, and then copy the text and paste it onto a form, and you get the controls on the form.

That's how you're going to do it. Select the following in your web browser and copy it (CTRL-C).

object Label1: TLabel
    Left = 16
    Top = 72
    Width = 337
    Height = 16
    Alignment = taRightJustify
    AutoSize = False
    Caption = 'Label1'
end
object Edit1: TEdit
    Left = 16
    Top = 8
    Width = 121
    Height = 24
    TabOrder = 0
    Text = 'Edit1'
    OnChange = Edit1Change
end
object Edit2: TEdit
    Left = 16
    Top = 40
    Width = 121
    Height = 24
    TabOrder = 1
    Text = 'Edit2'
    OnChange = Edit1Change
end

Then click on the form and paste the text. Voila! Magically, components will appear. The form will look like this:

Edit1 and Edit2 are for the numbers. Label1 displays the result. In normal projects, you should not accept the default names for components (Edit1, Edit2, and Label1 are names given the components by the IDE). If you want, you can rename these components. I recommend calling Edit1 "DividendEdit", Edit2 "DivisorEdit", and Label1 "ResultLabel". Name the form "MainForm" (note how we saved it as a file calld MainFormUnit - that's because the name of the form and the name of its file can't be the same).

The Program Logic

The form we've made will compile and run. You can File | Save All and Project | Run and it will compile, link and run. You can enter data into the edit box, but no result will appear.

To get something to happen, you need to use event handlers.

Event handlers are special functions which are invoked automatically when a certain event occurs. Almost all components have a set of event handlers, which can be seen on the Events page of the Object Inspector. Double-click on an event, and the IDE creates the header for your handler function in the class definition for the form, and adds an empty function body to the .cpp file.

For this example, click once on Edit1 and then go to the Object Inspector Events page and double-click on the OnChange event. Add code to the handler so it reads as follows:

What's in the handler?

It's really simple. The core of the function is the expression which sets the label caption (note: if you renamed the components, change the names in the handler above). Note that it accesses the Text property of each edit control and converts that to a double (a floating point number). It then sets the label caption to the result of the division.

The try / catch block traps any error which occurs - such as one which happens when an edit control is empty, or when it contains something other than a number. When that happens, the line that follows the catch is executed and sets the caption of the label to "Error".

Note, however, that the Borland C++ Builder IDE will, by default, display an exception dialog for every exception that occurs. So when one edit box is empty, execution in the IDE will stop, and you will be shown the offending line. You can use F9 to continue.

To disable this, in BCB5, uncheck Tools | Debugger Options | Language Exceptions | Delphi / C++ Exceptions, and on Tools | Debugger Options | OS Exceptions, turn off all of the displayed exceptions. The other versions of C++Builder have these options in slightly different places, so please consult your documentation and help files.

Sharing The Event Handler

This event handler will only be triggered when Edit1 experiences a change in value. If Edit2 changes, nothing will be done, since it does not have an event handler. You could copy the logic from the Edit1 handler, but that would be wasteful. Instead, click on Edit2. In the object inspector find the OnChange event. This time, don't double click, just single click, and a list of event handlers that fit the event will drop down - in this case Edit1Change. Click on that entry and now the Edit1 event handler will also be triggered when a change occurs in Edit2.

The Project Is Complete

Compile and run the project. Then enter values into Edit1 and 2. Change them and watch the result change. Your first C++ Builder program is completed.