The following steps show you how to use the Picklist Builder to build Picklist Help for a field.
1. Set Up Referential Validation
At anytime after you have set up Referential validation for a field, you can use the Picklist Builder to create the Help Picklist. The illustration below shows the Referential validation setup for the Job Code field.
The Referential validation Integrity page provides access to everything you need to set up Picklist Help for a field. You can build Picklist Help with the Picklist Builder. You can turn on the Auto List feature with the Auto List check box.
2. Run the Picklist Builder
1. Click the Picklist Builder button. VPME displays the Picklist Builder.
2. Picklist ID: If you need to create only one picklist definition, leave the Picklist ID set to “<Default>” and go to step 3.
· Multiple Picklist Definitions: If you need to create more than one picklist definition, click the New button and start a new definition by entering a Picklist ID in the text box to the right of the Picklist ID combo box. You can enter up to 20 characters that will uniquely identify each picklist definition for the field.
· <Default> Picklist ID: A picklist definition with the “<Default>” Picklist ID will be used by default when you put a control on a form for the field and leave the control’s cPickListID property empty. If there is one picklist definition that you want to make the default definition, give it the “<Default>” picklist ID.
3. Picklist Cursor: Use the Picklist Cursor combo box to select the table, view or CursorAdapter to use for Picklist Help for the current picklist definition.
Tip: The Picklist Cursor is a table, view or CursorAdapter that contains primary key values the foreign key field matches. Normally, you will use the Parent RI Cursor that you select for Referential Integrity for Picklist Help also.
4. Select Picklist Grid / Combo Box Fields: On the Picklist Builder select the following items:
· Select Fields: The Picklist Builder lists the fields in the Picklist Cursor. Move the fields you want to be in the Picklist grid from the Unselected Fields list to the Selected Fields list. If you will be putting the field for which you are defining Picklist Help on a form with a VPME combobox control, the fields you select will be in the combo box list.
Tip: The valid entries for the field being validated are the primary key field values in the Picklist table. However, you do not have to show the primary key field(s) in the Picklist. You can show only a descriptive field. When a user makes a selection from the Picklist, the primary key value will be entered into the field even if it is not shown in the Picklist.
For example, the Picklist for the Job Code field does not need to show the primary key Job Codes. It could show just the Job Titles. When a Job Title is selected from the Picklist, the Job Code would be entered into the Job Code field on the Job Status form even if the Job Code is not shown in the Picklist.
· Order Fields: The fields in the Selected Fields list will be placed in the grid in the order in which they are listed. Therefore, change the order of the fields so that the order meets your specifications.
Combobox Tip: If you will be placing the field on a form with a VPME combobox control, the combo box list will display each field you select in a separate column. The first field in the combobox list is the field displayed when the list is not expanded and is the only field with incremental search. None of the fields in the list are sortable. If you will be displaying a descriptive field from the Picklist table on the form instead of the field itself, the description field should be the first field listed in the Picklist Builder so that it is displayed when the list is not expanded and so that the incremental search will be enabled on that field.
5. Calculated Fields: The Picklist Builder allows you to easily create calculated fields for the Selected Fields list. To create a calculated field for the list:
· Click the Calc button at the bottom of the column of buttons on the Builder. The Builder displays the Visual FoxPro Expression Builder.
· Create your calculation expression in the Expression Builder. When you close the Expression Builder, the calculation expression will be added to the Selected Fields list with the prefix “Calc:”.
· You can edit a calculated field by selecting the field in the Selected Fields list and clicking the Calc button.
6. Selected Field Properties: When you highlight a field in the Selected Fields list, the Selected Field Properties box shows:
· Caption: This is the field Description (Short) property from the Data Builder. The Picklist Builder will make the Description (Short) property the header caption for the grid column that contains the field. If you want to modify the caption, modify the field’s Description (Short) property in the Data Builder. If the field has no Description (Short) property entry, the column caption defaults to the Description (Long) property entry. If the field has no Description (Long) property entry, the caption defaults to the field name. The Caption field is editable for a calculated field so that you can specify a header caption, since calculated field descriptions are not stored in the Data Builder.
· Order Tag: If you want to make a field’s grid column sortable, select a tag for the field in the Order Tag combo box. The tags listed in the Order Tag combo box are the tags you create for the Picklist table.
View & CursorAdapter Tip: The Order Tag combo box is disabled for a Picklist view or CursorAdapter. For a view or CursorAdapter, Incremental Search tags are created at runtime if either the Case Sensitive or the Not Case Sensitive option is chosen for a field.
7. Incremental Search: If you want to provide incremental search for a field, first select an Order Tag for the field (not necessary for a Picklist view or CursorAdapter). Then, select the Case Sensitive or Not Case Sensitive option button.
· Case Sensitive: Selecting the Case Sensitive option button makes the incremental search case sensitive.
· Not Case Sensitive: Selecting the Not Case Sensitive option button makes the incremental search not case sensitive if you also do one of the following:
· Alternative 1 - Create Upper Index Tag: Create an index tag for the field that uses the UPPER function in the index expression to force the tag to upper case. Select this tag as the Order Tag. (Not necessary for Picklist views or CursorAdapters.)
· Alternative 2 - Upper Field Format Property: Enter a Format property for the field in the Data Builder that uses the “!” symbol to force entry into the field on a form to upper case. If you do this, the Order Tag you select for the field does not have to use the UPPER function. (Not necessary for Picklist views or CursorAdapters.)
Warning: You probably do not want to use Alternative 2 if the data in the field already contains mixed or lower case entries.
8. Records Displayed: Select the number of records to display when the Picklist grid appears. If you leave the records displayed field set to zero, by default the Picklist displays 5 records. The Picklist form is resizable and users can change the number of records displayed after the form appears.
9. Max. Form Width: Select the maximum Picklist form width in pixels. If you leave the maximum form width field set to zero, by default the form automatically sizes itself to fit the fields you select for the grid. Normally, you will want to leave the maximum form width at zero. However, if you select more fields for the grid than can be displayed on the desktop, you may want to enter a value for the maximum form width.
If you select more fields than can be displayed on the desktop screen, the Picklist form automatically leaves a 20 pixel left and right margin. At low resolutions the form may become unacceptably wide if the grid contains more columns than can be displayed on the screen. In this case, you may want to set a maximum form width that matches its associated form’s width in pixels.
3. Build Picklist
After you have set up the Picklist Help definition as you want it, click the Close button. The Picklist Builder will build the Picklist for you.
4. Test and Clean Up
After the Picklist Builder creates a Picklist, you will want to test it. Run the form that contains the field from the VPME Form Editor and bring up the Picklist. If you want to run the form from your application, build the application first.
You may need to clean up the grid. In particular, if a grid header caption is much longer than the field displayed in the column, you may want to reduce the size of the header by modifying the field’s Description (Short) property in the Data Builder.
To change a Picklist, go to the field’s Integrity page in the Data Builder and click the Picklist Builder button. The Picklist Builder will display the fields and properties that you previously selected. Make any changes you want and click OK.