DISPLAY SELECTION

version 2004 (Modified)

DISPLAY SELECTION ({table}{; selectMode{; enterList{; *{; *}}}})

DISPLAY SELECTION displays the selection of table, using the output form. The records are displayed in a scrollable list similar to the User environment's list. If the user double-clicks a record, by default the record is displayed in the current input form. The list is displayed in the frontmost window.

To display a selection and also modify a record in the current input form after you have double-clicked on it (as you do in the User environment window), use MODIFY SELECTION instead of DISPLAY SELECTION.

All of the following information applies to both commands, except for the information on modifying records.

After DISPLAY SELECTION is executed, there may not be a current record. Use a command such as FIRST RECORD or LAST RECORD to select one.

The selectMode parameter is used to set the possibilities for selecting records in the list using the mouse. You can pass one of the following constants of the "Form Parameters" theme in this parameter:

• if you pass No Selection (0), it will not be possible to select a record in the list.

• if you pass Single Selection (1), only one record can be selected at a time.

• if you pass Multiple Selection (2), the user can select several records at once. To select adjacent records, click on the first record to be selected, then press the Shift key before clicking on the last record you want to include in the selection. To select non-adjacent records, click on each record separately while holding down the Ctrl (under Windows) or Command (under Mac OS) key.

If you do not pass the selectMode parameter, the "Multiple Selection" mode is used by default.

The enterList parameter lets you authorize the "Enter in List" mode for the displayed list. This lets the user select and modify the record values directly in the output form. Pass True to enable this mode or False to disable it. By default, if you do not pass the enterList parameter, the "Enter in List" mode is disabled.

Keep in mind that with the DISPLAY SELECTION command, this parameter only allows the selection of the values in the list and not their modification. In fact, the DISPLAY SELECTION command makes the current table Read only. Only the MODIFY SELECTION command allows the actual entry of values.

Note: The SET ENTERABLE command can be used to enable or disable the Enter in list mode on the fly.

Some rules regarding the optional * parameter:

- If the selection contains only one record and the first optional * is not used, the record appears in the input form instead of the output form.

- If the first optional * is specified, a one-record selection is displayed, using the output form.

- If the first optional * is specified and the user displays the record in the input form by double-clicking on it, the scroll bars will be hidden in the input form. To reverse this effect, pass the second optional *.

Custom buttons may be put in the Footer or Header area of the output form in order to terminate the execution of the DISPLAY SELECTION command. You can use automatic Accept or Cancel buttons to exit, or use an object method that calls ACCEPT or CANCEL. When an output form called by the DISPLAY SELECTION command has no buttons, only the Escape (Windows) or Esc (Mac OS) key can be used to exit the list.

During and after execution of DISPLAY SELECTION, the records that the user highlighted (selected) are kept in a set named UserSet. The UserSet is available within the selection display for object methods when a button is clicked or a menu item is chosen. It is also available to the project method that called DISPLAY SELECTION after the command was completed.

1. The following example selects all the records in the [People] table. It then uses DISPLAY SELECTION to display the records, and allows the user to select the records to print. Finally, it selects the records with USE SET, and prints them with PRINT SELECTION:

   ALL RECORDS([People])  ` Select all records 
   DISPLAY SELECTION ([People]; *)  ` Display the records 
   USE SET ("UserSet")  ` Use only records picked by user 
   PRINT SELECTION ([People])  ` Print the records that the user picked

2. See example #6 for the Form event command. This example shows all the tests you may need to check in order to fully monitor the events that occur during a DISPLAY SELECTION.

3. To reproduce the functionality provided by, for example, the Queries menu of the User environment when you use DISPLAY SELECTION or MODIFY SELECTION in the Custom Menus environment, proceed as follows:

a. In the Design environment, create a menu bar with the menu commands you want, for example, Show All, Query and Order By.

b. Associate this menu bar (using the "Associated menu bar" menu in the form properties dialog box) with the output form used with DISPLAY SELECTION or MODIFY SELECTION.

c. Associate the following project methods to your menu commands:

      ` M_SHOW_ALL (attached to menu item Show All)
   $vpCurTable:=Current form table
   ALL RECORDS($vpCurTable->)

      ` M_QUERY (attached to menu item Query)
   $vpCurTable:=Current form table
   QUERY($vpCurTable->)

      ` M_ORDER_BY (attached to menu item Order By)
   $vpCurTable:=Current form table
   ORDER BY($vpCurTable->)

You can also use other commands, such as PRINT SELECTION, QR REPORT, and so on, to provide all the "standard" menu options you may want each time you display or modify a selection in the Custom Menus environment. Thanks to the Current form table command, these methods are generic, and the menu bar they support can be attached to any output form of any table.

Form event, MODIFY SELECTION, Sets.