An introductory tutorial: TextDataFile

In this introductory tutorial, we'll create an application that reads data from a text file and step through building the user interface (UI) for the application using JBuilder design tools. We'll explore the JBuilder DataExpress architecture and apply database concepts to the tutorial even though we're not connecting to a true database in this first tutorial.

The UI consists of three controls: a grid control that displays the data from the text file, and a navigator to aid in browsing through the data, and a status area that displays messages.

The basic steps to completing this sample application are

  1. Creating the application structure describes using the Project and Application wizards to create the basic application files.
  2. Adding UI components to your application explains how to add the GridControl and NavigatorControl to your application.
  3. Adding Data Access components to your application explains how to add the TableDataSet and TextDataFile components which do not have a visual representation at runtime.
  4. Setting properties to connect the components describes how to get the components "talking" to each other by setting the appropriate properties.
  5. Compiling, running, and debugging your program explores getting your application to run and do what you want it to do.

When you have completed the tutorial, your application will look like this:

You can see the code for the completed tutorial by opening the sample project file samples\borland\samples\tutorial\dataset\TextDataFile\TextDataFile.jpr of your JBuilder installation.

Creating the application structure

Let's start by creating the application using the Project and Application Wizards. To start the Project Wizard,

  1. Choose File|New Select the Project icon.
  2. Keep the specified path, and change the default project name to TextDataFile.jpr.
  3. Optionally, enter a name and description for this project, your name, and company.
  4. Choose Finish.
The AppBrowser window displays the project's structure:

Now that the basic project structure is created, let's start the Application Wizard.

  1. Select the File|New menu option, then select the Application icon. The first page of the Application Wizard appears.
  2. Leave the default package name as is.
  3. Enter TextDataFileApp as the application class name.
  4. Choose the Next button.
  5. Enter TextDataFileFrame as the class name in the Frame Class box.
  6. Enter TextDataFile Tutorial as the title of the application window in the Frame Style box.
  7. Place a check beside the Generate status bar and and center frame on screen options. Leave the remaining options (menu bar, tool bar, and generate About box) at their default values; we won't be needing these options for this example.
  8. Choose Finish.
In the Navigation pane (top left pane) of the AppBrowser, you see that the Application and Frame files were added to the project.

Adding UI components to your application

We'll use the JBuilder UI Designer to build the user interface portion of our application. We'll add two UI elements to the application: a GridControl and a NavigatorControl. The GridControl is used to display two-dimensional data, in a format similar to a spreadsheet. The NavigatorControl is a set of buttons that help you navigate through the data displayed in a control such as a GridControl. As the names suggest, both are found on the Controls tab of the Component Palette.

Displaying the UI design tools

To display the UI design tools that we'll use for this example:
  1. Select the TextDataFileFrame.java entry in the Navigation pane of the AppBrowser
  2. Click the Design tab at the bottom of the Content pane (the large pane to the right).
The UI Designer displays in the Content Pane(the large pane on the right side of the AppBrowser), the Component Tree in the Structure Pane (bottom left) and a separate window for the Component Inspector.

The Navigation pane allows you to easily and quickly select a file. Based on your selection, the other panes of the AppBrowser update as appropriate. The Component Tree, for example, updates to display the elements in the selected file. Use the Component Tree to navigate through these elements. The Content Pane also updates to display the contents of the selected item.

Adding a UI component

  1. Open the UI Designer as indicated above.
  2. Click the Controls tab of the Component Palette to see the various controls.
  3. Click the GridControl component: .
  4. Click where you want the upper left corner of the GridControl to start in the Designer window and hold the mouse button while you draw the GridControl to the desired size, ending at the lower right corner. The rectangular area displayed in the Designer is the default size of your application UI. You'll notice a larger rectangular area with a long thin rectangle beneath it. To keep this tutorial simple, draw your GridControl within the bounds of the larger shaded area. The long thin rectangle is the status bar we asked the wizard to include in the application.

Your UI Designer window should look similar to this:

Tip:
To resize a UI component, click the mouse on the component to select it. When a component is selected, a border for the component becomes visible with small squares on the edges of the borders -- these are the component's "handles". Move the mouse over any handle; when the cursor changes to a double arrow, click the mouse and drag to resize the component.

Notice that the Component Tree in the lower left pane of the AppBrowser has a new entry: gridControl1. This is the GridControl you just placed in your application. JBuilder creates the corresponding source code immediately for the elements you've added to or modified in your application. To see this code, click the Source tab.

Switch back to the Design window (click the Design tab) and add a NavigatorControl just above the GridControl. The NavigatorControl button is: .

Your application should look similar this:

You've just finished creating the UI for your application. Before we continue, select the File|Save All menu option to save your work. Next we'll add Data Access components and hook them up to the controls you just created.

For more information on the fine points of UI design, see Designing a user interface in the Users Guide.

Adding Data Access components to your application

With Data Access components, you have the choice of dropping them on the UI Designer as with visual controls, or you can drop them directly on the Component Tree. The only indication that the Data Access component is added is the reference to an instance of that object which appears in the Tree (and of course the source code generated in the Content pane); Data Access components have no visual representation in the UI.

This application requires two Data Access components:

These components are found on the Data Access tab of the Component Palette. To add the TableDataSet Data Access component to your application,
  1. Click the Data Access tab.
  2. Click the button to select the TableDataSet component.
  3. Click in the application design window or in the Component Tree to add this component to your application. An entry for an instance of a TableDataSet object appears in the Data Access folder of the Component Tree as tableDataSet1.
Now add the TextDataFile component to your application following the steps above. The button for the TextDataFile is and once added, appears in the Component Tree as textDataFile1.

We've now added all the components for the application. Before we continue, select the File|Save All menu option to save your work. Next we'll connect them together by setting their properties.

Setting properties to connect the components

Now we have all the pieces we need for the application, but they're distinct pieces that don't yet "talk" to each other. Setting the appropriate component properties will connect the pieces. Properties are set from the Properties tab of the Inspector. The Inspector window displays the properties for the component selected in the Designer window (for UI components) or the Component Tree (for both UI and Data Access components).

Setting properties of Data Access components

First let's work on getting the two Data Access components "talking" to each other. We'll set the fileName property of the TextDataFile component. This tells JBuilder where to find the text file that contains the data we want read into textDataFile1. Since TextDataFile is a Data Access component, we select it from the Component Tree rather than the Designer window.

To set the fileName property of the textDataFile component,

  1. Click the textDataFile1 object in the Component Tree. The Inspector displays the properties for this component.
    Note: Make sure the Properties page is selected in the Inspector, not the Events page.
  2. Double-click the edit area next to the fileName property in the Inspector. It changes color to show that it is active for editing.
  3. Click the ellipsis button to display the File Name dialog.
  4. Click the Browse button to display the Open dialog. Click the parent directory icon to select the path of samples\borland\samples\tutorial\dataset\TextDataFile. Select the employee.txt file. Click the Open button to close the dialog.
  5. Choose the OK button to close the File Name dialog. The resulting source code in the Content pane that sets this property is: textDataFile1.setFileName("c:\\JBuilder\\samples\\borland\\samples\\tutorial\\dataset\\TextDataFile\employee.txt"); If you installed JBuilder in a directory other than the one listed above, change the code to reflect the location of the sample files on your computer.
Note: Please do not use a different text file than employee.txt at this time. Later examples (see Importing data from a text file") show you how to work with your own data files.

Next, let's connect tableDataSet1 to the textDataFile1 component.

  1. Select tableDataSet1 in the Component Tree. The Inspector displays the properties for this component.
  2. Double-click the area beside the dataFile property. Click the down arrow and select the entry for textDataFile1. This generates the following source code: tableDataSet1.setDataFile(textDataFile1);
  3. Save your work using the File|Save All menu option.

The employee.txt file works with the default settings stored in the TextDataFile component for properties such as delimiter, separator, and locale. If it required anything other than default values, we would set the appropriate properties at this point.

Now that the Data Access components are connected to each other, let's move on to the UI components.

Setting properties of UI components

Next we will work with the two UI components that we added, GridControl and NavigatorControl, as well as the StatusBar control that the wizard added for us. To work with these components, we can select them in either the UI Designer or the Component Tree. You can tell when a UI component is selected in the Designer by the presence of borders and handles around the component.

To set the dataSet property of the GridControl component,

  1. In the UI Designer, select the GridControl component.
  2. Double-click the edit area beside the dataSet property in the Inspector.
  3. Click the down arrow that appears.
  4. Select tableDataSet1 from the drop-down list. This list contains all instantiated DataSet components of which we only have one in this example.
Setting this property fills the GridControl with data from the text file. You should see live data in your application's Design window.

Set both the navigator and the status bar's dataSet properties to tableDataSet1 as well, following the steps as above. Then save your work.

When you set the dataSet property of the navigator, the two right-most buttons become dimmed and unavailable. This reflects that the functionality provided by those buttons do not apply to DataSet objects whose data source is not a SQL server database.

When you set the dataSet property of the status bar, it displays the current row position and the row count. You cannot navigate the data in the Designer; but when you run the application, the status will update as you move the cursor through the data in the grid.

Your application should look like this:

Compiling, running, and debugging a program

Although you are in the Designer and have not run the program yet, data appears in the GridControl and your application looks complete. But your users won't be using your application in the JBuilder Designer. So, we need to compile, run, test, and possibly debug the application.

If you need to do so, please review the chapters covering compiling and debugging as they discuss the two topics in much greater depth. To compile and run the application,

Note: If you select the Run button when your program has not been compiled, JBuilder automatically compiles your source and, if no compile errors are generated, runs your application.

If there are syntax errors, the program is not automatically run. If syntax errors are found, an Error pane containing error messages appears in the lower right of the AppBrowser window. Compiler or syntax errors tend to be easier to correct than logic errors. Logic errors are most noticeable at run-time when the application doesn't quite do what you'd like it to.

In this simple application, all properties were selected from drop-down lists or browsers that presented values to select from so syntax erors shouldn't be encountered. Had there been a need for manual typing, for example, a directory path and file name or custom code, chances would be greater for a syntax error to occur.

If all goes well, a message indicating a successful compile appears in the message line at the bottom of the Main window, and your application's UI should appear.

When you run your application, you'll notice the following behavior:

Summary

Congratulations! You've completed your first data connectivity program. We created a program that reads data from a text file, displays the data in a GridControl for viewing and editing, displays status messages to a StatusBar, and includes a NavigatorControl component to help browse though the data quickly.

In other examples, we'll explore more complex tasks, show how JBuilder presents warnings and errors, and work with additional UI and Data Access components.