If you include the JBCL StatusBar component in your application, LocatorControl prompts and messages are displayed on the status bar. Connect both the StatusBar and the LocatorControl to the same DataSet component to enable this feature.
The samples\borland\samples\tutorial\dataset\Locator directory of JBuilder includes a finished example of an application that uses the LocatorControl under the project name Locator.jpr. This sample shows how to set a particular column for the locate operation as well as using a TextFieldControl component to prompt the user for the column to locate in. The completed application (with the application window reduced in size) looks like this:
To create this application,
Check the screen shot of the running application (shown above) to see the approximate positioning of each component.
Property name | Value |
Database | database1 |
Query String | select * from employee |
if (e.getKeyCode() == KeyEvent.VK_ENTER) {
locatorControl1.setColumnName(textField1.getText());
locatorControl1.requestFocus();
}
This code tests for the Enter key being pressed. If it determines that the Enter was pressed, the columnName property for the LocatorControl is set to the column named in the TextFieldControl. This instructs the LocatorControl to perform locates in the specified Column. Focus is then shifted to the LocatorControl so that you can enter the value to search for.
Column to locate
Alternatively, if you want to locate only in a particular Column, set the LocatorControl component's columnName property to the DataSet column you want to locate on, for example, LAST_NAME.
Value to locate
Note: See the screen shot of the running application earlier in this section for additional instructional text.
When you run the application, you'll notice the following behavior:
Note: In this sample, there is no validation of the column name, so be sure to enter a correctly spelled column name.
When programmatically locating data:
The core locate functionality uses the locate(ReadRow, int) method. The first parameter, ReadRow, is of an abstract class type. Normally you use its (instantiatable) subclass DataRow class. The second parameter represents the locate option and is defined in Locate variables. The Locate class variables represent options that let you control where the search starts from and how it searches, for example with or without case sensitivity. (For more information on locate options, see Working with locate options.) If a match is found, the current row position moves to that row. All data-aware controls that are connected to the same located DataSet navigate together to the located row.
The Locate() method searches within the current view of the DataSet. This means that rows excluded from display by a RowFilterListener are not included in the search.
The view of the DataSet can be sorted or unsorted; if it is sorted, the locate() method finds matching rows according to the sort sequence.
To locate a null value in a given column of a DataSet, include the column in the DataRow parameter of the locate() method but do not assign it a value.
Tip: If the locate() method fails to find a match when you think it should succeed, check for null values in some columns; remember that all columns of the DataRow are included in the search. To prevent this, use a "scoped" DataRow containing only the desired columns.
When the DataRow is created based on the same located DataSet, the DataRow contains the same column names and data types and column order as the DataSet it is based on. All columns of the DataRow are included in the locate operation by default; to exclude columns from the locate, create a "scoped" DataRow that contains only specified columns from the DataSet. You create a "scoped" DataRow using either of the following DataRow constructors:
Both the DataRow and the DataSet are subclasses of ReadWriteRow. Both inherit the same methods for manipulation of its contents, for example, getInt(String), and setInt(String, int). You can therefore work with DataRow objects using many of the same methods as the DataSet.
You control the locate operation using locate options. These are constants defined in the borland.jbcl.dataset.Locate class. You can combine locate options using the bitwise OR operator; several of the most useful combinations are already defined as constants. Four of the locate options (FIRST, NEXT, LAST, and PRIOR) determine how the rows of the DataSet are searched. The CASE_INSENSITIVE and PARTIAL) options define what is considered a matching value. The FAST constant affects the preparation of the locate operation.
You must specify where the locate starts searching and which direction it moves through the rows of the DataSet. Choose one of the following:
To find all matching rows in a DataSet, call the locate() method once with the locate option of FIRST. If a match is found, re-execute the locate using the NEXT_FAST option, calling the method with this locate option repeatedly until it returns false. The FAST locate option specifies that the locate values have not changed, so they don't need to be read from the DataRow again. To find all matching rows starting at the bottom of the view, use the options LAST and PRIOR_FAST instead.
The CASE_INSENSITIVE option specifies that string values are considered to match even if they differ in case. Specifying whether a locate operation is CASE_INSENSITIVE or not is optional and only has meaning when locating in String columns; it is ignored for other data types. If this option is used in a multi-column locate, the case sensitivity applies to all String columns involved in the search.
The PARTIAL option specifies that a row value is considered to match the corresponding locate value if it starts with the first characters of the locate value. For example, you might use a locate value of "M" to find all last names that start with "M". As with the CASE_INSENSITIVE option, PARTIAL is optional and only has meaning when searching String columns.
Multi-column locates that use PARTIAL differ from other multi-column locates in that the order of the locate columns makes a difference. The constructor for a scoped, multi-column DataRow takes an array of column names. These names need not be listed in the order that they appear in the DataSet. The PARTIAL option applies only to the last column specified, therefore, control over which column appears last in the array is important.
For a multi-column locate operation using the PARTIAL option to succeed, a row of the DataSet must match corresponding values for all columns of the DataRow except the last column of the DataRow. If the last column starts with the locate value, the method succeeds. If not, the method fails. If the last column in the DataRow is not a String column, the locate() method throws a DataSetException of PARTIAL_SEARCH_FOR_STRING.
For example, you might want to write a generalized locate routine that accepts a value and looks for the row in the DataSet that contains that value. The same block of code can be made to work for any data type because the data stays a variant. To display the data, use the appropriate formatter class in the JBCL model package (or create your own custom formatter).