DISPLAY SELECTION

version 6.0 (Modified)

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

Parameter	Type		Description
table	Table		Table to display, or
			Default table, if omitted
*			Use output form for one record selection
			and hide scroll bars in the input form
*			Show scroll bars in the input form
			(overrides second option of first optional *)

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, the record is displayed in the input form. The list is displayed in the frontmost window.

To display a selection and also modify a record 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.

The following figure shows an output form displayed by the DISPLAY SELECTION command.

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.

DISPLAY SELECTION does not allow the user to modify a record when in the input form. MODIFY SELECTION does.

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 *.

A button labeled Done is automatically included at the bottom of the list. Adding any variable or active object on the form removes the Done button. Clicking this button exits the command. Custom buttons may be used instead; you can put these buttons in the Footer area of the output form. You can use automatic Accept or Cancel buttons to exit, or use an object method that calls ACCEPT or CANCEL.

The user can scroll through the selection and click a record to select it. If the user clicks a different record, the first record is deselected and the second record is selected. A user can select a group of contiguous records by clicking the first record and Shift+clicking (Windows or Macintosh) the last record. To select records that are not adjacent, the user can Ctrl+click (Windows) or Command-click (Macintosh) each record.

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.