EDIT Command

  • Article

Displays fields for editing.

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

Parameters

  • FIELDS FieldList
    Specifies the fields that appear in the Edit 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 fields in the table are displayed in the order they appear in the table structure.

    The field list can specify any combination of fields or calculated fields, including fields from tables open in other work areas. 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. This expression may take any form but it must be a valid Visual FoxPro expression.

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

CalculatedFieldName = eExpression

This example creates a calculated field called location:

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

The FIELDS clause field list includes eight options, which enable special handling of fields displayed in the Edit window.

  • :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 alters only the way the field appears in the Edit window.

  • :R
    In the following example, an Edit 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
EDIT FIELDS cust_id:R, company

  • :V = lExpression1
    Specifies a verify option that performs field-level data validation within the Edit window. If lExpression1 evaluates to true (.T.) when you move the cursor from the 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 is displayed. If lExpression1 evaluates to 0, the data input is considered incorrect and the cursor remains in the field, but no error message is displayed.

    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.

    The verify option isn't executed for memo fields.

  • :F
    Specifies a forced validation option that determines if the expression in the verify option (lExpression1) is evaluated when you move the cursor from 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
    Displays an error message specified with cMessageText instead of the default system message.

    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 the error message appears.

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

    The error message is displayed only if SET NOTIFY is ON. The bell is sounded if SET BELL is ON.

    The following example opens the products table and displays the product_id and prod_name fields. Enter a value greater than 100 in the product_id field to perform the field validation.

    :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 is displayed in the status bar at the bottom of the main Visual FoxPro window.

    Press ESC to close the Edit 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
EDIT FIELDS in_stock :V = in_stock < 100 ;
   :F ;
   :E = 'The stock amount must be less than 100'

  • :P = cFormatCodes
    Specifies a picture option that lets you create an editing template specified with cFormatCodes that controls the display and input of data for each field in an Edit window.

    For more information on using picture editing codes, see the Format and InputMask properties.

    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
EDIT FIELDS unit_price :P = '99,999.99'

  • :B = eLowerBound, eUpperBound [:F]
    Specifies a set of boundaries between which data must fall. The boundary expressions eLowerBound and eUpperBound must match the data type of the field and cannot be the names of user-defined functions. If the data entered doesn't fall between eLowerBound and eUpperBound, a system message is displayed indicating the range between 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 is between 1 and 100. Press ESC to close the Edit window.

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

  • :H = cHeadingText
    Specifies a heading option (:H) that allows you to replace the default field names with your own headings, which you specify with cHeadingText. By default, field names are placed to the left side of the fields in the Edit 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
EDIT FIELDS prod_name :H = 'Product Name:', ;
   unit_price :H = 'Price per Unit:'

  • :W = lExpression2
    Specifies a WHEN option that allows you to conditionally prohibit the cursor from being moved to a field based on the value of the logical expression lExpression. (:W) evaluates lExpression. If lExpression2 evaluates to false (.F.), you can't move the cursor to the field. If lExpression2 evaluates to true (.T.), you can move the cursor to the field. User-defined functions are supported in lExpression2.

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

  • Scope
    Specifies a range of records that are displayed in the Edit window. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include Scope operate only on the table in the active work area. The default scope for EDIT is ALL records.

    For more information, see the Scope Clauses online topic.

  • FOR lExpression1
    Specifies that only the records that satisfy the logical condition lExpression1 are displayed in the Edit window. Using this argument allows you to filter out undesired records.

    Rushmore optimizes an EDIT FOR query if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • WHILE lExpression2
    Specifies a condition whereby records are displayed in the Edit window for as long as the logical expression lExpression2 evaluates to true (.T.).

  • FONT cFontName [, nFontSize]
    Specifies the Edit 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 an Edit window:

    FONT 'Courier',16

    If you include the FONT clause but omit the font size nFontSize, a 10-point font is used in the Edit 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 Edit window's font style in Visual FoxPro. 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.

    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 an Edit window and uses an underlined font:

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

  • FREEZE FieldName
    Allows changes to be made to only one field specified with FieldName in the Edit window. The remaining fields are displayed and cannot be edited.

  • KEY eExpression1 [, eExpression2]
    Limits the scope of records that are displayed in the Edit window. With KEY, you can specify an index key value (eExpression1) or a range of key values (eExpression1 , eExpression2) for the records displayed in the Edit window. The table 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 master tag.

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

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

  • LAST | NOINIT
    Saves any configuration changes made to the appearance of an Edit 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 Edit window. For more information on this file, see SET RESOURCE.

    If you issue EDIT with the LAST clause, the Edit window opens in the same configuration that was last saved in the FOXUSER file. This restores the previous Edit window configuration created with the last EDIT. If the last EDIT command issued in the Command window included a long list of clauses, issue EDIT LAST to avoid having to retype the command.

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

  • LPARTITION
    Places the cursor in the first field in the left partition of the Edit window. An Edit window can be split into left and right partitions by including the PARTITION clause. By default, the cursor is placed in the first field in the right partition when the Edit window is opened.

    The cursor is placed in the right partition of the Edit window if you include LPARTITION without the PARTITION clause.

  • NAME ObjectName
    Creates an object reference for the Edit window, allowing you to manipulate the Edit window with object-oriented properties available for the Grid control.

    For additional information about object-oriented programming in Visual FoxPro, see Object-Oriented Programming. For additional information about the Grid control properties that you can specify for an Edit 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 choosing Append Mode from the View menu.

    Note   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 Edit window.

  • NOCAPTION
    Specifies to always use the field name of a table or view for the column headers, even when the database contains a friendly caption for the table. This clause applies only to tables or views in a database.

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

    Note   Including NODELETE doesn't prevent you from marking a record for deletion from within a routine (created with VALID, WHEN or ON KEY LABEL) while in the Edit window.

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

  • NOLINK
    Unlinks partitions in the Edit window. By default, the left and right partitions of the Edit window are linked; when you scroll through one partition, the other partition scrolls.

  • NOMENU
    Removes the Table menu title in Visual FoxPro from the system menu bar, preventing access to the Edit menu.

  • NOOPTIMIZE
    Disables Rushmore optimization of EDIT.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • NORMAL
    Opens the Edit 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 Edit window assumes those user-defined settings as well.

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

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

  • PARTITION nColumnNumber
    Splits an Edit 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 Edit window.

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

  • REDIT
    Specifies that the right partition of the Edit window appears in Browse mode. The following examples opens an Edit window with the split bar placed in column 20 and the right partition open in Browse mode.

    Include both keywords to open both partitions in Browse mode.

    CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'data\testdata')
USE customer  && Opens customer table

EDIT PARTITION 30 REDIT

  • PREFERENCE PreferenceName
    Saves an Edit window's attributes and options for later use. Unlike LAST, which restores the Edit window as it appeared in the previous session, PREFERENCE saves an Edit window's attributes indefinitely in the FOXUSER resource file. Preferences can be retrieved at any time. For more information about the FOXUSER resource file, see SET RESOURCE.

    Issuing EDIT with the specified preference name PreferenceName for the first time creates an entry in the FOXUSER file that saves the Edit window configuration. Issuing EDIT later with the same preference name restores the Edit window to that preference state. When the Edit window is closed, the preference state 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 Edit window, issue SET RESOURCE OFF, open the FOXUSER file as a table, and change the field 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.

  • REST
    Prevents the record pointer from being moved from its current position to the top of the table. By default, EDIT positions the record pointer at the top of the table.

  • SAVE
    Keeps the Edit window and any of its memo field text-editing windows active and visible (open). You can then return to the Edit 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 EDIT in the Command window because EDIT SAVE is always the default in the interactive mode.

  • TIMEOUT nSeconds
    Specifies how long an Edit window waits for input. The numeric expression nSeconds specifies how many seconds can elapse without any input before the Edit window automatically closes.

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

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

  • TITLE cTitleText
    Overrides the default table name or alias that appears in the Edit 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 EDIT WINDOW to place the Edit window in a user-defined window, the Edit window's title replaces the user-defined window's title.

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

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

    If VALID returns true (.T.), you can move the cursor to another record. If VALID returns false (.F.), the cursor remains in the current field and Visual FoxPro displays an error message. You can display your own error message when VALID returns false by including the ERROR clause. The character expression cMessageText is displayed as the 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.

  • :F
    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 and whose contents you define with cMessageText. Visual FoxPro displays your error message when VALID returns false (.F.).

  • WHEN lExpression4
    Evaluates a condition when the user moves the cursor to another record. If lExpression4 evaluates to true (.T.), the user can modify the record moved to. If lExpression4 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 partition of the Edit window to nFieldWidth. Including the WIDTH clause doesn't change the size of fields in the table itself; it alters only the way the fields are displayed in the Edit 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 Edit window assumes. For example, if the user-defined window is created with the FLOAT clause, the Edit 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 Edit window is opened. The Edit window doesn't assume the characteristics of the parent window. An Edit window activated inside a parent window cannot be moved outside the parent window. If the parent window is moved, the Edit window moves with it.

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

  • IN SCREEN
    Explicitly places an Edit window in 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 Edit window's colors. In Visual FoxPro, the Edit window assumes the color scheme established using the Color Control Panel.

Remarks

EDIT allows you to edit the selected table within a window. EDIT behaves identically to CHANGE.

If you press ESC to exit the Edit 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.

In a program, use DEACTIVATE WINDOW to save your changes and close an Edit window. Include the name of the Edit window in DEACTIVATE WINDOW. For more information on Edit window names, see WTITLE( ).

SET SKIP Support

SET SKIP lets you establish a one-to-many relationship between two tables (see the example). 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 can use EDIT 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. In FoxPro for MS-DOS, shaded blocks are displayed in any column containing information from the parent table beyond the first matching record. In Visual FoxPro, the fill character for repeated parent information depends on the current Edit window font.

For more information, see SET SKIP.

COL( ) and ROW( ) Support

Use COL( ) and ROW( ) to return the current screen row and column position of the cursor in an Edit window. If an Edit window is opened in the main Visual FoxPro window, the returned cursor position is relative to the main Visual FoxPro window, not to the Edit window itself. If an Edit window is opened in a user-defined window, COL( ) and ROW( ) return the cursor position relative to the user-defined window.

Example

The following example uses SET SKIP to create a one-to-many relationship between two tables. There is a single record in the parent table (customer) for each invoice created. The child table (orders) contains multiple records for each record in the parent table.

After the relationship is created, an Edit window displaying records from both the parent and child tables is opened.

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
EDIT FIELDS customer.cust_id :H='Customer Number', ;
   customer.city :H='Customer City', orders.shipped_on

See Also

BROWSE | Grid Control | SET SKIP | WTITLE( ) | COL( ) Function | ROW( ) Function