BROWSE Command

Opens the Browse window and displays records from the current or selected table.

Syntax

BROWSE
[FIELDS FieldList]
[FONT cFontName [, nFontSize]]
[STYLE cFontStyle]
[FOR lExpression1 [REST]]
[FORMAT]
[FREEZE FieldName]
[KEY eExpression1 [, eExpression2]]
[LAST | NOINIT]
[LOCK nNumberOfFields]
[LPARTITION]
[NAME ObjectName]
[NOAPPEND]
[NODELETE]
[NOEDIT | NOMODIFY]
[NOLGRID] [NORGRID]
[NOLINK]
[NOMENU]
[NOOPTIMIZE]
[NOREFRESH]
[NORMAL]
[NOWAIT]
[PARTITION nColumnNumber [LEDIT] [REDIT]]
[PREFERENCE PreferenceName]
[SAVE]
[TIMEOUT nSeconds]
[TITLE cTitleText]
[VALID [:F] lExpression2 [ERROR cMessageText]]
[WHEN lExpression3]
[WIDTH nFieldWidth]
[WINDOW WindowName1]
[IN [WINDOW] WindowName2 | IN SCREEN]
[COLOR SCHEME nSchemeNumber]

Arguments

FIELDS FieldList

Specifies the fields that appear in the Browse window. The fields are displayed in the order specified in FieldList. You can include fields from other related tables in the field list. When you include a field from a related table, preface the field name with its table alias and a period.

If you omit FIELDS, all the fields in the table are displayed in the order they appear in the table structure.

FONT cFontName [, nFontSize]

Specifies the Browse window's font and font size. The character expression cFontName specifies the name of the font, and the numeric expression nFontSize specifies the font size. For example, the following clause specifies 16-point Courier font for the fields displayed in a Browse window:

FONT 'Courier',16

If you include the FONT clause but omit the font size nFontSize, a 10-point font is used in the Browse window. If you omit the FONT clause, 8-point MS Sans Serif is used.

If the font you specify is not available, a font with similar font characteristics is substituted.

STYLE cFontStyle

Specifies the Browse window's font style. If you omit the STYLE clause, the Normal font style is used

If the font style you specify is not available, a font style with similar characteristics is substituted or the Normal font style is used.

Character	Font style
B	Bold
I	Italic
N	Normal
O	Outline
Q	Opaque
S	Shadow
–	Strikeout
T	Transparent
U	Underline

You can include more than one character to specify a combination of font styles. The following example opens a Browse window and uses an underlined font:

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
IF _WINDOWS
   BROWSE FIELDS contact FONT 'System', 15  STYLE 'NU'
ENDIF
IF _MAC
   BROWSE FIELDS contact FONT 'Geneva', 14  STYLE 'NU'
ENDIF

FOR lExpression1

Specifies a condition whereby only records for which lExpression1 is true are displayed in the Browse window.

Rushmore optimizes a query specified with a BROWSE FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE and "Understanding Rushmore Technology" in Chapter 15, Optimizing Applications, in the Programmer's Guide.

Include FOR to move the record pointer to the first record meeting the condition. Include REST to keep the record pointer at its current position.

REST

Prevents the record pointer from being moved from its current position to the top of the table when a Browse window is opened with the FOR clause. Otherwise, BROWSE positions the record pointer at the top of the table by default.

FORMAT

Specifies the use of a format file to control the display and data-entry format in a Browse window. The format file must first be opened with SET FORMAT. The following information is extracted from the format file and applied to the Browse window:

The list of fields to browse
All VALID clauses
All WHEN clauses
All RANGE clauses
Field sizes (as specified in PICTURE clauses)
All SAY expressions (included as calculated BROWSE fields)
The following example uses a format file to validate data entered into a Browse window. Positions specified with @ ... GET are ignored.

The first line creates a BROWSE field (cust_id) that is 5 characters wide and allows the entry of letters and digits only. The second line creates a BROWSE field (company) that cannot contain a blank value and can contain a maximum of 20 alphabetic characters.

The third line creates a BROWSE field (contact) into which you enter data only when the field is blank.

Here are the contents of the Custentr.fmt format file, which is used to validate data entered into the customer table:
```
@ 3,0 GET cust_id PICTURE 'NNNNN'
@ 3,0 GET company VALID company != SPACE(40) ;
   PICTURE 'AAAAAAAAAAAAAAAAAAAA'
@ 3,0 GET contact WHEN contact = SPACE(40)

* This is the program that uses the format file
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
SET FORMAT TO custentr.fmt
BROWSE FORMAT
```

FREEZE FieldName

Permits changes to be made to only one field in the Browse window. You specify this field with FieldName. The remaining fields are displayed but cannot be edited.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS phone :H = 'Phone Number:' , ;
   company :H = 'Company:' ;
   FREEZE phone

KEY eExpression1 [, eExpression2]

Limits the scope of records that are displayed in the Browse window. With KEY you can specify an index key value (eExpression1) or a range of key values (eExpression1, eExpression2) for the records that are displayed in the Browse window. The table you browse must be indexed, and the index key value or values included in the KEY clause must be the same data type as the index expression of the master index file or tag.

For example, the customer table includes a character field containing postal codes. If the table is indexed on the postal code field, you can specify a range of postal codes in the KEY clause.

In the following example, only records with postal codes falling within the range of 10,000 to 30,000 are displayed in the Browse window:

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
SET ORDER TO postalcode
BROWSE KEY '10000', '30000'

LAST | NOINIT

Saves any configuration changes made to the appearance of a Browse window. The changes are saved in the FOXUSER file and can include changes to the field list, the size of each field, and the location and size of the Browse window.

If you issue BROWSE with the LAST or NOINIT clause, the Browse window opens in the same configuration that was last saved in the FOXUSER file if SET RESOURCE is ON. This restores the Browse window configuration created with the last BROWSE command. If the last BROWSE issued in the Command window included a long list of clauses, issue BROWSE with the LAST or NOINIT option to avoid having to retype the command. For more information on the FOXUSER file, see SET RESOURCE.

If the last Browse window was opened with a BROWSE that included a PREFERENCE clause, BROWSE LAST won't restore the preference.

Any Browse window configuration changes you make in the current session aren't saved if you exit BROWSE by pressing CTRL+Q.

The LAST and NOINIT clauses are identical; NOINIT provides dBASEcompatibility.

LOCK nNumberOfFields

Specifies the number of fields you can see in the left partition of the Browse window without tabbing or scrolling. The left partition sizes automatically to be able to display the number of fields you specify with nNumberOfFields.

LPARTITION

Specifies that the cursor is placed in the first field in the left Browse window partition. By default, the cursor is placed in the first field in the right partition when the Browse window is opened.

NAME ObjectName

Creates an object reference for the Browse window, allowing you to manipulate the Browse window with object-oriented properties available for the Grid control. For additional information about object-oriented programming in Visual FoxPro, see Chapter 3, Object-Oriented Programming, in the Programmer's Guide. For additional information about the Grid control properties that you can specify for a Browse window created with the NAME clause, see the Grid Control topic.

NOAPPEND

Prevents the user from adding records to the table by pressing CTRL+Y or by choosing Append Record from the Table menu.

Important Including NOAPPEND doesn't prevent you from appending a record from within a routine (created with VALID, WHEN, or ON KEY LABEL) while in the Browse window.

NODELETE

Prevents records from being marked for deletion from within a Browse window. By default, a record can be marked for deletion by pressing CTRL+T, choosing Toggle Delete from the Table menu, or by clicking in the leftmost column of the record to be deleted.

NOEDIT | NOMODIFY

Prevents a user from modifying the table. NOEDIT and NOMODIFY are identical. If you include either clause, you can browse or search the table, but you cannot edit it. However, you can append and delete records.

NOLGRID

Removes the field gridlines in the left partition of the Browse window.

NORGRID

Removes the field gridlines in the right partition of the Browse window.

NOLINK

Unlinks the partitions in a Browse window. By default, the left and right partitions of the Browse window are linked together so that when you scroll through one partition, the other partition scrolls.

NOMENU

Removes the Table menu title from the system menu bar, preventing access to the Browse menu.

NOOPTIMIZE

Disables Rushmore optimization of BROWSE. For more information, see SET OPTIMIZE and "Understanding Rushmore Technology" in Chapter 15, Optimizing Applications, in the Programmer's Guide.

NOREFRESH

Prevents the Browse window from being refreshed. Browse windows are refreshed at the rate determined by SET REFRESH. NOREFRESH is useful with read-only files and improves performance.

NORMAL

Opens the Browse window with its normal default settings, such as its colors, size, position, title, and control options (GROW, FLOAT, ZOOM, and so on). If you omit NORMAL and the current output window is a user-defined window with its own settings, the Browse window assumes those user-defined settings also.

NOWAIT

Continues program execution immediately after the Browse window is opened. The program doesn't wait for the Browse window to be closed but continues executing on the program line immediately following the program line containing BROWSE NOWAIT. If you omit NOWAIT when BROWSE is issued from within a program, a Browse window is opened and program execution pauses until the Browse window is closed.

NOWAIT is available only from within a program. Including NOWAIT when issuing BROWSE from the Command window has no effect.

PARTITION nColumnNumber

Splits a Browse window into left and right partitions with nColumnNumber specifying the column number of the split bar. For example, if nColumnNumber is 20, the split bar is placed in column 20 of the Browse window.

LEDIT

Specifies that the left partition of the Browse window appears in Edit mode.

REDIT

Specifies that the right partition of the Browse window appears in Edit mode. This example opens a Browse window with the split bar placed in column 20 and the right partition open in Edit mode.

Include both keywords to open both partitions in Edit mode.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE PARTITION 20 REDIT

PREFERENCE PreferenceName

Saves a Browse window's attributes and options for later use. Unlike LAST, which restores the Browse window as it appeared in the previous session, PREFERENCE saves a Browse window's attributes indefinitely in the FOXUSER resource file. Preferences can be retrieved at any time.

Issuing BROWSE with the specified preference name for the first time creates an entry in the FOXUSER file that saves the Browse window configuration. Issuing BROWSE later with the same preference name restores the Browse window to that preference state. When the Browse window is closed, the preference is updated.

Preference names can be up to 10 characters long, must begin with a letter or an underscore, and can contain any combination of letters, numbers and underscores.

Once you have a preference the way you like it, you can prevent it from being changed. Close the Browse window, issue SET RESOURCE OFF, open the FOXUSER file as a table, and change the record containing the preference to read-only by changing the value of the logical field READONLY to true (.T.).

For more information about the FOXUSER resource file, see SET RESOURCE.

If you exit a Browse window by pressing CTRL+Q, no Browse window changes are saved to the resource file.

SAVE

Keeps the Browse window and any of its memo field text-editing windows active and visible (open). You can then return to the Browse window after cycling through other open windows with the keyboard or the mouse.

SAVE is available only from within a program. SAVE has no effect when included with BROWSE in the Command window because BROWSE SAVE is always the default in the interactive mode.

TIMEOUT nSeconds

Specifies how long a Browse window waits for input. The numeric expression nSeconds specifies how many seconds can elapse without any input before the Browse window automatically closes.

TIMEOUT is available only from within a program; it has no effect when you issue BROWSE from the Command window. In the following example, the Browse window is closed if no input occurs in 10 seconds.

DEFINE WINDOW wBrowse FROM 1,1 TO 24,40 ;
   CLOSE ;
   GROW ;
   COLOR SCHEME 10
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE WINDOW wBrowse ;
   FIELDS phone :H = 'Phone Number:' , ;
   company :H = 'Company:' ;
   TIMEOUT 10
RELEASE WINDOW wBrowse

TITLE cTitleText

Overrides the default table name or alias that appears in the Browse window title bar with the title you specify with cTitleText. Otherwise, the name or alias of the table being browsed appears in the title bar.

If you issue BROWSE WINDOW to place the Browse window in a user-defined window, the Browse window's title replaces the user-defined window's title.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE;
   TITLE 'My Browse Window' ;
   FIELDS phone :H = 'Phone Number' , ;
   company :H = 'Company:'

VALID lExpression2

Performs record-level validation in a Browse window. The VALID clause is executed only if a change is made to the record and you attempt to move the cursor to another record. The VALID clause is not executed if the only change is to a memo field.

If VALID returns a value that is true (.T.), the user can move the cursor to another record. If VALID returns a false value (.F.), the cursor remains in the current field and Visual FoxPro generates an error message. If VALID returns 0, the cursor remains in the current field, and an error message isn't displayed.

The VALID clause shouldn't be confused with the verify option (:V), which enables field-level validation.

Forces the VALID clause to execute before the user moves the cursor to the next record. In this case, VALID is executed even if the record isn't changed.

ERROR cMessageText

Specifies an error message that overrides the system default error message. Visual FoxPro displays cMessageText when VALID returns false (.F.).

WHEN lExpression3

Evaluates a condition when the user moves the cursor to another record. If lExpression3 evaluates to true (.T.), the user can modify the record moved to. If lExpression3 evaluates to false (.F.) or 0, the record the user moves to becomes read-only and cannot be modified.

The WHEN clause isn't executed when another window is activated.

WIDTH nFieldWidth

Limits the number of characters displayed for all fields in a Browse window to nFieldWidth. The contents of a field can be scrolled horizontally using the Left and Right Arrow keys or the horizontal scroll bar. Including the WIDTH clause doesn't change the size of fields in the table; it alters only the way the fields are displayed in the Browse window. If a width has been specified for an individual field with the FIELDS clause, it overrides the width specified with the WIDTH clause for that field.

WINDOW WindowName1

Specifies a user-defined window whose characteristics the Browse window assumes. For example, if the user-defined window is created with the FLOAT clause, the Browse window can be moved. The specified window doesn't have to be active or visible, but it must be defined.

IN [WINDOW] WindowName2

Specifies the parent window within which the Browse window is opened. The Browse window doesn't assume the characteristics of the parent window. A Browse window activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the Browse window moves with it.

To access the Browse window, the parent window must first be defined with DEFINE WINDOW and must be active and visible.

IN SCREEN

Explicitly places a Browse window on the main Visual FoxPro window when a user-defined window is active.

COLOR SCHEME nSchemeNumber

Specifies the number of a color scheme used for the Browse window's colors.

The Browse window assumes the color scheme established using the Windows Color Control Panel.

Remarks

A Browse window allows you to view records in a table, edit those records, and append additional records. Visual FoxPro allows you to have several Browse windows open at the same time.

If you press ESC to exit a Browse window, changes made to the last field you modified are discarded. However, if you move to another record after modifying a field, your changes to the field are saved.

For information on navigating in the Browse window, see Chapter 2, Creating Tables and Indexes, in the User's Guide.

The field list can specify any combination of fields or calculated fields.

The syntax of the field list is:

FieldName1 
   [:R] 
   [:nColumnWidth]
   [:V = lExpression1 [:F] [:E = cMessageText]]
   [:P = cFormatCodes] 
   [:B = eLowerBound, eUpperBound [:F]]
   [:H = cHeadingText]
   [:W = lExpression2]
   [, FieldName2 [:R]...]

Calculated Fields… The field list can contain statements for creating calculated fields. A calculated field contains read-only data created with an expression. The expression can take any form, but it must be a valid Visual FoxPro expression.

The format of the statement you use to create a calculated field is:

CalculatedFieldName = eExpression

The following example creates a calculated field called location:

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS location = ALLTRIM(city) + ', ' + country

city and country are the names of fields from the currently selected table.

The FIELDS clause field list includes options that enable special handling of fields displayed in a Browse window:

Specifies that the field is read-only. The data it contains can be viewed but not edited.

In the following example, a Browse window is opened with the cust_id and company fields. The cust_id field is read-only and cannot be changed.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Open customer table
BROWSE FIELDS cust_id:R, company

:nColumnWidth

Specifies the display size for a field in columns. The value of :nColumnWidth doesn't affect the size of the field in the table; it only alters the way the field appears in the Browse window.

:V = lExpression1 [:F] [:E = cMessageText]

Lets you perform field-level data validation within the Browse window. If lExpression1 evaluates to true (.T.) when you move the cursor from a field, the data input into the field is considered correct and the cursor moves to the next field.

If lExpression1 evaluates to false (.F.), the data input is considered incorrect, the cursor remains in the field and a message appears. If lExpression1 evaluates to 0, the data input is considered incorrect and the cursor remains in the field but no error message appears.

The verify option is not executed for memo fields.

By default, lExpression1 is evaluated only when the field is modified. To force verification, include the :F option.

You can display your own error message by including the :E option described below.

Determines whether the expression in the verify option is evaluated when you move the cursor out of a field or another window is activated. If :F is not included, lExpression1 is evaluated only if changes are made to the field. If :F is included, lExpression1 is evaluated even if the field isn't modified.

:E = cMessageText

If the validation expression :V = lExpression1 evaluates to true (.T), the cursor leaves the field normally. If the expression evaluates to false (.F.), the cursor remains in the field, and Visual FoxPro generates an error message.

If the error option (:E) is included, cMessageText appears instead of the system error message. cMessageText appears only if SET NOTIFY is ON. The bell is sounded if SET BELL is ON.

If :V = lExpression1 evaluates to 0, no message appears and the cursor remains in the field being validated. This option lets you display your own error messages in validation routines.

The following example opens the products table and displays the product_id and prod_name fields. The product_id field is a numeric field that will accept up to five numbers. For purposes of this example, we consider a product_id greater than 100 to be invalid.

:V specifies the validation criteria. :F forces the validation check to be performed whether the data is changed or not. :E replaces the Visual FoxPro system error message with a user-defined error message. In Visual FoxPro, the error message appears in the status bar at the bottom of the main Visual FoxPro window.

Press ESC to close the Browse window.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
IF _WINDOWS OR _MAC
   SET STATUS BAR ON
ENDIF
USE products
BROWSE FIELDS in_stock :V = in_stock < 100 ;
   :F ;
   :E = 'The stock amount must be less than 100'

:P = cFormatCodes

If you include a FIELDS clause, you can also specify a picture option (:P) for each field in the list. The picture option lets you create a list of codes that controls the display and input of data for each field in a Browse window. cFormatCodes is the list of codes.

The following example uses the picture option to allow only numeric data in a specific format to be entered in the unit_price field:

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS unit_price :P = '99,999.99'

See the Format and InputMask properties for more information about picture option codes.

:B = eLowerBound, eUpperBound [:F]

Specifies a set of boundaries between which data in a field must fall. The boundary expressions eLowerBound and eUpperBound must match the data type of the field. They cannot be user-defined functions. If the data entered doesn't fall between eLowerBound and eUpperBound, a system error message appears indicating the range within which the data must fall.

By default, the data you enter is checked against the boundary values only if you make a change to the contents of the field. To force checking against the boundary values, include the forced validation option (:F).

The following example ensures that the value in the in_stock field falls between 1 and 100. Press ESC to close the Browse window.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS in_stock :B = 1, 100    :F

:H = cHeadingText

Replaces the default field names with your own headings, which you specify with cHeadingText. By default, field names are used as the column headings in the Browse window.

The following example provides user-defined headings for the displayed fields.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE products  && Open products table
BROWSE FIELDS prod_name :H = 'Product Name:', ;
   unit_price :H = 'Price per Unit:'

:W = lExpression2

Determines whether the cursor can be moved to a field. If lExpression2 evaluates to false (.F.), moving the cursor to the field is prohibited. If lExpression2 evaluates to true (.T.), the cursor can be moved to the field. User-defined functions are supported in lExpression2.

If moving the cursor to all fields is prohibited, the current record is marked read-only. This occurs only when every field contains a WHEN clause that evaluates to false.

SET SKIP Support… SET SKIP lets you establish a one-to-many relationship between two tables. For each record in the parent table, there can be multiple related records in the child table. If you create a one-to-many relationship, you may use BROWSE to view records from both the parent and child tables.

The parent record appears once, along with the first matching record from the child table. Any subsequent matching records are displayed in the rows following the parent record and first matching child record. The fill character for repeated parent information depends on the current Browse window font.

If the record pointer is positioned on a parent record, you can move the pointer through the parent records in the Browse window by pressing CTRL+DOWN ARROW to move to the next parent record or CTRL+UP ARROW to move to the previous parent record. For more information on creating one-to-many relationships, see SET SKIP.

The FIELDS clause field list contains records from both the parent and child tables. The names of fields are prefaced with their table alias (orders or customer) and a period.

CLEAR
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer ORDER cust_id IN 0   && Parent table
USE orders ORDER cust_id IN 0  && Child table
SELECT customer     && Back to parent work area
SET RELATION TO cust_id INTO orders     && Establish relationship
SET SKIP TO orders  && One-to-many relationship
WAIT WINDOW 'Scroll to see shipping dates for each customer' NOWAIT
BROWSE FIELDS customer.cust_id :H='Customer Number', ;
   customer.city :H='Customer City', orders.shipped_on

Useful Functions… Several Visual FoxPro functions return useful information about a Browse window.

Function	Description
VARREAD( )	Returns the name of the field the cursor is in for the active Browse window.
RECNO( )	Returns the record number of the selected record in the active Browse window.