In order for the steps outlined in this tutorial to work properly, you must have already loaded the TApolloTable package into the Delphi / C++Builder development. This example uses Delphi, however the complete C++Builder source for this is also available in the ..\VCL\Samples\CBuilder\AmazoApp subdirectory.
This section combines a TApolloTable component with Delphi's TDataSource, TDBGrid, and TDBNavigator components to create a simple, single-form, single-table, non-Client/Server application called Amazo-App. For a step-by-step intoduction to using TApolloTable and/or TApolloQuery on remote tables through the Apollo Database Server, see the "Step-By-Step Client/Server Tutorial" section.
For those new Apollo VCL users who are new to Delphi as well, this tutorial assumes almost no working knowledge or previous experience with Delphi at all. In its basic form, Amazo-App could require no code at all. It would also require no TApolloTable component. However, to also provide a demonstration of accessing table data directly, without data aware controls like TDBGrid, we'll also add two other 'features' to Amazo-App which utilize the extended functionality found in TApolloTable.
The complete source and project file for Amazo-App is installed by default to ...\VCL\Samples\..\AmazoApp.
Step 1 - Know your data
Before we create Amazo-App, we first need to have an existing table of data to work with. This example uses a table called TEST.DBF. This file will have been installed, by default, in your ..\x86\Data and/or ..\x64\Data\ directory and contains 50 records of the following structure:
NAME TYPE LEN DEC
FIRST C 20
LAST C 20
STREET C 30
CITY C 30
STATE C 2
ZIP C 10
HIREDATE D 8
MARRIED L 1
AGE N 2 0
SALARY N 6 0
NOTES C 70
Step 2 - Create a new project:
To begin creating the application itself, select New Project from Delphi's File menu. From the Object Inspector window, change the Caption property of Form1 to 'Amazo-App'.
Step 3 - Add the data access components:
From the component palette's Apollo page click and drop a TApolloTable component on the form. Then, from the component palette's Data Access page, click and drop a TDataSource component onto the form.
On the form, click on the TApolloTable icon to select it. By default, this object will be called ApolloTable1, but we will change that to ApTbl for short. We'll also set some other design-time values for this object. To do this, in the Object Inspector window, set the following properties for the TApolloTable object:
32-bit
DatabaseName : ..\Apollo\9.9\x86\VCL\Samples\Delphi\AmazoApp
64-bit
DatabaseName : ..\Apollo\9.9\x64\VCL\Samples\Delphi\AmazoApp
Name : ApTbl
TableName : TEST
TableType : ttSXFOX
Active : True
Then, click on the TDataSource icon to select it, and set the following properties for it in the Object Inspector window:
DataSet : ApTbl
This tells TDataSource that it will be getting its data from ApTbl. This TDataSource object will, by default, be called DataSource1. It will relay information between ApTbl and your visual data aware controls.
Step 4 - Add the data aware components
Actually, before we add the data aware components, we need to add a panel to the form, just for aesthetic reasons. So, from the Standard page of the component palette, click and drop a TPanel component onto the form. Blank out the Caption property, and then set the Align property to alTop. This locks it to the top of the form.
Okay, now we're ready to grab some data aware components. First, from the Data Controls page, select the TDBNavigator component and drop it onto the panel we just added. Click and drag it to the left side of the panel so it looks just about like the picture above. Then just set the DataSource property to DataSource1. This points to the TDataSource component we previously placed on the form.
Now, also from the Data Controls page of the component palette, select a TDBGrid control and drop it on the form, below the panel. Then, set the following properties:
Align : alClient
DataSource : DataSource1
At this point, running the application will display the data in the browse window from TEST.DBF. This is a basic Delphi database application requiring no code and no BDE.
Now to do some hands-on data access in code...
Step 5 - Add the new features
Feature #1:
The first additional feature we'll add to Amazo-App is a TLabel component used as a record position indicator, just to the right of the TDBNavigator buttons. This shows which record number we're on as we move through the table with the navigator buttons.
From the component palette's Standard page select a TLabel component and position it just to the right of the TDBNavigator buttons on the panel. You can either blank out the label's Caption property, or leave it alone. It's not critical since Amazo-App will end up changing it when it starts up anyway.
To dynamically update the record position display each time a navigator button is clicked, we only need to add the following bit of code to the OnDataChange event of the TDataSource component:
Label1.Caption := IntToStr( ApTbl.RecNo ) + '/' +
IntToStr( ApTbl.RecCount );
Feature #2:
The second additional feature we'll add to Amazo-App also demonstrates a need for hand-coding. This is the 'Index' button (a TButton component). When the user clicks on the 'Index' button, it simply creates a tag in a FoxPro compound (.CDX) index file, displaying a progress meter during the process.
To add this feature, select a TButton component from the component palette's Standard page and drop it on the panel to the right of the record position label we've just added. Make sure to leave the label enough room to the right. Size and position the button so it looks about the same as in the Amazo-App picture above. Set the button's Caption property to 'Index'.
From the Object Inspector window, select the Events page, double click on the OnClick event to open the source window. Add the following code to the TButton's OnClick event:
// Create index on UPPER(LAST+FIRST)
Screen.Cursor := crHourGlass;
ProgressBar1.Visible := True;
with ApTbl do
begin
SetGaugeHook( Form1.Handle );
IndexTag( '', 'NAME', 'UPPER(LAST+FIRST)', IDX_NONE, False, '' );
SetGaugeHook( 0 );
end;
ProgressBar1.Visible := False;
Screen.Cursor := crDefault;
The SetGaugeHook method (used above) allows you to attach a progress meter to time-consuming processes, such as index creation, to allow your users to know how far along the process is.
Drop a TProgressBar component (from the Win95 page) just to the right of the 'Index' button previously placed on the panel. Size this to be positioned as in the picture of Amazo-App above. You can modify the colors of the gauge from the Object Inspector if you'd like, but this is not required for this demo.
Now set the following property:
Visible : False
In this example, SetGaugeHook will be sending the progress information to the TProgressBar control via Form1's OnKeyDown event.
To do this, we must get to Form1's events in the Object Inspector. This is usually easily done by just clicking on the form to give it focus. However, with the TDBGrid control aligned to fill the form, there is no open spot on the form to click on. So, just click on the TDBGrid control and then press the Esc key. This will change focus to the grid's Parent control – Form1.
Now, Select the Events page on the Object Inspector, double-click on the OnKeyDown event, and add the following code:
Delphi
procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word; Shift: TShiftState);
var
wVal : Word;
begin
if (Key and $7000) <> 0 then
begin
wVal := -SmallInt( Key );
ProgressBar1.Position := wVal;
Application.ProcessMessages;
Key := 0;
end;
end;
C++Builder
void __fastcall TForm1::FormKeyDown(TObject * Sender, int *Key, TShiftState * Shift)
{
WORD wVal;
if ((Key && 0x7000) != 0)
{
wVal = -Char(Key);
ProgressBar1->Position = wVal;
Key = 0;
}
}
Step 6 - All Done!:
That's it! All that's left is to press F9 and run it. Scroll through the browse window and watch the record number status change. Click the 'Index' button and watch the progress gauge display as the index tag is created and the data in the browse window is now sorted by Last and First names.
See Also
Step-By-Step Client/Server Tutorial, TApolloConnection, TApolloTable, TApolloQuery