2.9 :clear()

There are two different forms of the :clear() method:

2.9.1 :clear() (List Objects)

This method deletes the values from rows and columns in the contents of an object whose contents consist of multiple entries indexed with integer or index. Along with the contents, the values of the associated attributes are deleted as well.

In contrast to the :delete() method, :clear() only deletes the values in the rows or columns. The entries themselves remain as empty entries, which will have the default value if available. Thus :clear() will not reduce the number of rows or columns.

Definition

boolean :clear
(
      integer Start input
  { , integer Count := 1 input }
  { , boolean Direction := false input }
)

Parameters

integer Start input
This parameter defines the position from which the contents of the rows or columns should be deleted.
integer Count := 1 input
This optional parameter defines the number of rows or columns whose contents are to be deleted. If the parameter is not specified, 1 is taken as default.
boolean Direction := false input)

This optional parameter controls whether the contents of rows or of columns are deleted in the tablefield. This depends on the value of the tablefield attribute .direction.

The parameter may only be passed for the tablefield. For other objects than the tablefield, passing the parameter will result in an error.

Value range

false
Deletes against the direction given in the .direction attribute
true
Deletes in the same direction as given in the .direction attribute

Thus these contents are deleted from the tablefield:

Parameter Direction

.direction 1 (vertical)

.direction 2 (horizontal)

false

row(s)

column(s)

true

column(s)

row(s)

Return value

The method returns true if the contents of the rows or columns could be deleted.

If an error has occurred when deleting the contents, the method will return a fail.

Objects with this method

Example 

window Wn
{
  .title "Example for method :clear()";

  child listbox Lb
  {
    .content[1] "McCusker";
    .content[2] "McNeill";
    .content[3] "Pinter";
    .content[4] "Tilly";
    .content[5] "Miller";
    .content[6] "Meyer";
    .content[7] "Davis";
  }

  child pushbutton Pb_clear
  {
    .text "Clear entry";

    on select
    {
      Lb:clear(Lb.activeitem);
    }
  }
}

2.9.2 :clear() (Arrays)

This method deletes the contents of elements in fields (indexed, non-associative, user-defined attributes).

In contrast to the :delete() method, :clear() only deletes the contents of the items. The items themselves remain as empty items, which will have the default value if available. Thus :clear() will not reduce the number of items.

Particularity

The :clear() method can also be used to delete all items of an associative array. In this case, neither the Start nor the Count parameter may be specified. Therefore, :clear() cannot be used to delete single items from an associative array. Additionally, not only the contents but the elements themselves are deleted in this case. Thus, the number of elements afterwards will be 0.

Definition

boolean :clear
(
      attribute Attr input
  { , integer Start input }
  { , integer Count input }
)

Parameters

attribute Attr input
This parameter defines the user-defined attribute on which the method should be applied.
integer Start input

This parameter defines the position from which the contents of the items should be deleted.

The value range for Start is 0 … .count[Attr], i.e. the default value can also be deleted.

If neither Start nor Count is specified, the contents of all elements are deleted.

integer Count input

This optional parameter defines the number of items whose contents are to be deleted.

If neither Start nor Count is specified, the contents of all elements are deleted.

If Start is specified, the default value of Count is 1.

Return value

The method returns true if the contents of the items could be deleted.

If an error has occurred when deleting the contents, the method will return a fail.

Objects with this method

All objects that may have user-defined attributes.

See also

Chapter “Methods for Arrays of User-defined Attributes” in manual “User-defined Attributes and Methods”