Displaying status information
Many data applications provide status information about the data in addition to displaying the data itself. For example, a particular area of a window often contains information on the current row position, error messages, and other similar information. The JBCL includes a StatusBar control which provides a mechanism for such status information. It has a text property that allows you to assign a text string to be displayed in the StatusBar. This string overwrites the existing contents of the StatusBar and is overwritten itself when the next string is written to the StatusBar.
You can also connect the StatusBar control to a DataSet. The StatusBar control doesn't display the data from the DataSet but displays the following status information generated by the DataSet:
- Current row position
- Row count
- Validation errors
- Data update notifications
- Locate messages
Building an application with a StatusBar control
This section serves both as general step-by-step instructions for your real-world application, and as a tutorial with sample code and data.
You can add a StatusBar control to your application in two ways:
- Have the Application Wizard add the StatusBar automatically when creating the structure for your application.
- Add the StatusBar control manually to the UI of your application Frame.
To include a StatusBar when creating your application:
- Select the File|New... menu option and select the Application icon.
- Enter appropriate values in the first page of the Application Wizard.
- Click the Next button. The second page appears.
- Place a checkmark beside the Generate status bar option. Enter appropriate values for the remaining options on this page.
- Select Finish to generate the application files. The Frame object will automatically include the StatusBar control.
To add the StatusBar to the UI of your existing application:
- Open the project files for the application you want to add a StatusBar to. You can use the files created from the Querying a database topic, or you can start with the completed files that are located in the samples\borland\samples\tutorial\dataset\QueryProvide directory of your JBuilder installation in the project file QueryProvide.jpr.
Note: If you use the completed sample files, make a backup of the files before you start modifying them since these files are used as the starting point for several tutorials in this book.
- Select the Frame file in the Navigation Pane of the AppBrowser, then click the Design tab that appears at the bottom of the AppBrowser.
- Click the Controls tab of the Component Palette and select the StatusBar component button:
- Draw the StatusBar below the GridControl component.
Note: The exact location of the StatusBar may change depending on the layout manager in use. For more information on layouts, see the Using layout managers chapter in the User Guide.
- Set the dataSet property of the StatusBar control to the DataSet object whose status messages you want displayed in the StatusBar. You typically connect a StatusBar control to the same DataSet as the UI control which displays the data from the DataSet. This sets both controls to track the same DataSet together and is often referred to as a shared cursor.
Note: Once you set the dataSet property, you'll notice that the StatusBar control displays information that the cursor is on Row 1 of x (where x is the number of records in the DataSet).
- Click the plus sign beside the QueryDataSet in the Component Tree. This expands to show the Column components in the QueryDataSet. Select the
Last_Name and First_Name columns and set the required property to true for both. Set the SALARY column's min property to 25000.
- Run the application.
Running the StatusBar application
When you run the application, you'll notice that when you navigate the dataset, the row indicator updates to reflect the current row position. Similarly, as you add or delete rows of data, the row count is updated simultaneously as well.
To test its display of validation information:
- Insert a new row of data. Attempt to post this row without having entered a value for the FIRST_NAME or LAST_NAME columns. A message displays in the StatusBar indicating that a the row cannot be posted due to invalid or missing field values.
- Enter a value for the FIRST_NAME and LAST_NAME columns. Enter a number in the SALARY column that doesn't meet the minimum value. When you attempt to move off the row, the StatusBar displays the same message that the row cannot be posted due to invalid or missing field values.
By setting the text of the StatusBar at relevant points in your program programmatically, you can overwrite the current message displayed in the StatusBar with your specified text. This text message, in turn, gets overwritten when the next text is set or when the next DataSet status message is generated. The status message can result from a navigation through the data in the grid, validation errors when editing data, and so on.
For other examples of applications that include a StatusBar control, see the following topics: