FORM.VIEWQUERIED()

Syntax

<FORM> as P = FORM.VIEWQUERIED( Form_Name as C [, Filter_Expn as C [, Order_Expn as C [, Style as C [, Horizontal_Position as N [, Vertical_Position as N [, IsBaseQuery as L   ]]]]]] )

Argument

 

Description

Form_Name

 V5

The name of the form to open. In the case where there are duplicate form names in the database, you can qualify the form name with the table name using this syntax: Form_Name@Table_Name. For example, if a database has a form called Customers for the Current_Customers and the Past_Customers tables, you can specify the form as: " Customers@Current_Customers, or Customers@Past_Customers.

Filter_Expn

 V5

Optional. Default = ".T." (All records). A character filter expression that evaluates to a logical value and selects the records to show in the dialog.

Order_Expn

 V5

Optional. Default = record order. A character order expression that sorts selected records.

Style

 V5

Optional. Default = "Dialog". Determines the mode of the form.

  • "" = normal

  • "dialog"

  • "hidden"

  • "hidden-dialog"

  • "popup"

Horizontal_Position

 V5

Optional. Default = "center". The horizontal position of the window. Possible values are:

  • "left"

  • "right"

  • "center"

  • "fill"

V6

"pixel_coordinate"

Vertical_Position

 V5

Optional. Default = "center". The vertical position of the window. Possible values are:

  • "top"

  • "bottom"

  • "center"

  • "fill"

V6

"pixel_coordinate"

IsBaseQuery V8 The default value for this property is .T. Specify if the query is a 'base query' or not. See 'Understanding Base Query' below.

Description

The FORM.VIEWQUERIED() method opens Form Name and returns an object pointer, <Form>, to the form window. In the case where there are duplicate form names in the database, you can qualify the form name with the table name using this syntax: Form Name@Table Name. For example, if a database has a form called "Customers" for the "Current_Customers" and the "Past_Customers" tables, you can specify the form as: "Customers@Current_Customers", or "Customers@Past_Customers".

To open the form as a modal dialog box, specify "Dialog" as the optional Style parameter. You can also specify a style of "Popup". See FORM.VIEW() for details.

To load the form into memory, without displaying it, specify "Hidden" as the Style or, use the FORM.LOAD() method.

Note : If you do not close the form at the end of your script, you will leave the underlying table(s) open.

Understanding 'Base Query'

When you design a form you can go to the Form, Properties dialog and and specify a filter expression for the form. When the form is opened, only records that satisfy the filter will be shown. This filter is referred to as a 'base query' because it is always applied regardless of what additional filter the user might add to the form after the form has been opened (by using Query by Form, Query Genie, Query by expression, etc.). If the user applies some filter to the form and then clicks the 'show all' button to remove the filter that he added, the base query is still in place. The user cannot remove the base query. (You will notice that when a base query has been defined, the Select Index/Query command is disabled, and the button to change the search key on the Find by Key dialog is also disabled because enabling them would allow the user to remove the base query.).

So, for example, if a form has a base query of 'State = "MA" ' and the user defines a query to search for ' Lastname = "Smith" ', the actual query is ' State = "MA" .and. Lastname = "Smith" '. When the user clicks the 'Show All' button, the 'State = "MA"' query is still in place.

When the FORM.VIEWQUERIED() method is used with IsBaseQuery set to its default vlaue of .t. the filter that is specified becomes the form's new base query and it cannot be removed by the user.

If IsBaseQuery is set to .f., then the form is opened showing just the records that satisfy the filter condition, but the filter is not a base query and the user can click the 'Show All' button to remove the filter.

Note. After a form has been opened, the <form>.BaseQueryRun() method can be used to specify a different base query for the form.

Supported By

Alpha Five Version 5 and Above

Limitations

Desktop applications only.

Examples

This script opens the Customer form and displays the record whose number is stored in the variable, recno.

dim shared recno as N

dim frm as P

dim filter as C

filter = "between(recno(), " + recno + "," + recno + ")"

'e.g. if recno = 23, filter = "between(recno(), 23,23)"

frm = form.viewQueried("customer",filter)

... do things

frm.close()

This script opens the Customer form for all MA customers. Data is sorted by lastname and firstname

dim frm as P

dim filter as C

dim order as C

filter = "bill_state_region = 'MA'"

order = "lastname + firstname"

frm = form.viewQueried("customer",filter,order)

... do things

frm.close()

This script does the same as the previous script, but it opens the form as a modal dialog box. Note the <FORM>.CLOSE() method which is needed to close the dialog after the user dismisses the dialog.

dim frm as P
dim filter as C

dim order as C

filter = "bill_state_region = 'MA'"

order = "lastname + firstname"

frm = form.viewQueried("customer",filter,order,"dialog")

... do things

frm.close()

This script opens the Customer form for all customers in the state specified by the whatState variable.

dim frm as P

dim filter as C

filter = between_char("state",whatState,whatState)

frm = form.viewQueried("customer",filter)

... do things

frm.close()

This script opens the Customer form and shows the record in the range of record numbers specified by startrec and endrec.

dim frm as P

filter = between_record(startrec, endrec)

frm = form.viewQueried("customer",filter)

... do things

frm.close()

See Also

FORM.VIEW(), FORM.LOAD(), BROWSE.LOAD(), Form Functions and Methods, Writing Expressions