Clearing data, controls and buffers

clear | clearall | cleardata

Clear data, controls and buffers


SYNTAX

clear | clearall | cleardata [object_id] [, object_id]…

The clear command

The clear command alone, with no arguments, does the following:

1

Clears all textboxes in all windows, whether open or closed, and clears all temporary fields attached to those textboxes. Temporary fields not linked to textboxes are not cleared.

2

Clears all checked radio and checkbox buttons.

3

Clears all record buffers, except those which have been preserved by means of the preserve command. This includes closed files.

4

Unlocks all locked files and all locked records.

The clear command, with no arguments, does not affect:

1

The current position of file pointers.

2

Key values set up for matching by a find command.

3

The data in temporary fields that are not linked to a textbox.

4

Window control label text.

5

Listboxes and tables.

6

Text displayed with the put command.

7

Graphic lines displayed with the draw hline, draw vline and draw rectangle commands.

8

The values in a temporary record layout defined in a !record statement which contains a field list.


The clearall command

The clearall command is identical to the clear command, except that it also clears window backgrounds, listboxes and tables. The window background includes text displayed with put and graphic lines displayed with the draw hline, draw vline and draw rectangle commands. Text created from the headings of a0 type fields is not background text and is not cleared by clearall.

The clearall command may be used with or without arguments. It is identical to clear if used with any control type except a window_id.


The cleardata command

The cleardata command is identical to clear, except that it does not unlock records or files.


The clear tmp command

This use of clear clears all the temporary fields in a program, excluding those declared as part of a !record structure and local variables declared within a user function. All temporary fields not excluded for these reasons are automatically placed in the default temporary field group tmp. See !temp.


Object list

The clear command may be assigned an object list, consisting of a single object or of a list of objects separated by commas. Different types of object may be freely mixed in the list. The objects that may be specified are listed below.

Fields

clear field_id[[subscript]] [, field_id[[subscript]]]….

Clears the specified fields. Fields are cleared by setting alphanumeric fields to spaces and numeric fields to zero. If the field is linked to a textbox or textboxes, no change is made to the currently displayed data. In order to display the new value of its linked field, the textbox must be displayed (display box_id).

Note that clearing an object pointer type field clears the object to which it points, which may be any type of object.

If the field is subscripted, the command clear field_id, with no subscript specified, does not clear the entire array. Only the current element is cleared. This is determined by the current default subscripts (stored in the variables sys.Row , sys.Col , sys.Plane and sys.Dim4).

It is possible to avoid the need to clear each element of a subscripted field individually by assigning the field to a !record structure:

!record ArrayRec {
      ArrayField[20,100,100]
}

The command:

clear ArrayRec

clears every element of the array ArrayField.

See also The clear tmp command.

Textbox groups

clear group_id [, group_id]…

group_id can be any group of textboxes. All rows of multiple-row textboxes are cleared. Groups may be explicitly declared by the programmer. See also The clear tmp command.

Listboxes

clear listbox_id [, listbox_id]…

Clears all the values in the listbox. For LIST_BUTTON and LIST_EDIT types, both the current selection and the items in the list are cleared. A global clear does not clear listboxes, though clearall does.

Record buffers

clear record_id[[subscript]] [, record_id[[subscript]]]….

Clears the specified record buffer or buffers, setting alphanumeric fields to spaces and numeric fields to zero. If the buffer is a file buffer, it is unlocked. When a record buffer is explicitly cleared by name, the preserve command has no effect. Every declared file has a default record_id, which has the same name as its file_id.

Since version 6.2.0 the nested record and record array features are supported, meaning that just a subrecord can be cleared.

The ability to specify a subscript was added in Sculptor V 5.1. If the record is not a record array the specified element of all array fields in the record buffer is cleared. Non-array fields are not cleared, and records are not unlocked. But if the record is a record array the subscript refers to the record array, clearing the entire fields on that record array position.

Note

If a program using this feature is run with an earlier version of Sculptor, the entire record is cleared.

Tables

clear table_id [, table_id]…

Clears all the values in the table. A global clear does not clear tables, though clearall does.

Textboxes

clear box_id[[subscript]][, box_id[[subscript]]]….

Clears the visible data in the screen textbox, and clears the field linked to it. Fields are cleared by setting alphanumeric fields to spaces and numeric fields to zero.

Multiple-row textboxes: the box in the row specified by subscript is cleared, together with the element of the linked field which is displayed in that box. If subscript is greater than the number of textbox elements, wrapping takes place. Normally the field linked to a multiple-row textbox is itself subscripted. Note that wrapping does not take place on the subscripts of a field unless the Sculptor system variable sys.IndexWrap is explicitly set to ON. If the box is multiple-row but no subscript is specified, the current value of the system variable sys.Row determines the box to be cleared.

If the linked field has more elements than the textbox has rows, then whenever a row is cleared (or displayed), Sculptor links the set of elements containing that row to the textbox. For example, if the textbox has 4 rows and the linked field has 12 elements, then the command

clear box_id[6]

indicates to Sculptor that elements 5-8 are currently linked to the textbox. This ensures that the correct element of the linked field is updated. If the user now moves to another row by means of the mouse or arrow keys, Sculptor updates the display value of that row. Therefore row 1 would display the value of element 5, row 3 element 7, and row 4 element 8.

If all rows of a textbox are to be cleared using subscripts greater than the number of textbox rows, clear from the highest value of subscript down to 1, to avoid side-effects.

Free format textboxes: If a textbox is free format (the textbox height is greater than 1) then the clear command clears every line of the textbox.

Windows

clear window_id [, window_id]…

Clears all the controls in the specified window or windows. The window background is not cleared unless the clearall version is used.


EXAMPLES

clearall
clear Win1, Win2
clear FileBuf1, ButtGrp2
clear ArrayField[6]

An example with nested record arrays:

!record RecArray[2] {
    txt,,a8
    !record SubRec[2] {
        num,,i4[2]
        txt,,a8
    }
}
clear RecArray[1].SubRec
/* Clears all fields from RecArray[1].SubRec[1] and RecArray[1].SubRec[2] */

RELATED TOPICS

preserve