2.23 :insert()

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

2.23.1 :insert() (List Objects)

This method inserts rows and columns into the contents of an object whose contents consist of multiple entries indexed with integer or index. Inserting is also possible if there are no entries yet. When inserting, the associated attributes are also extended accordingly. The newly inserted entries are empty or have the default value if available.

Definition

boolean :insert
(
      integer Position input
  { , integer Count := 1 input }
  { , boolean Direction := false input }
)

Parameters

integer Position input
This parameter defines the position where the new rows or columns are inserted. If its value is 0, the rows or columns are appended to the end.
integer Count := 1 input
This optional parameter defines the number of rows or columns that are inserted. If the parameter is not specified, 1 is taken as default.
boolean Direction := false input

This optional parameter controls whether rows or columns are inserted 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
Inserts against the direction given in the .direction attribute
true
Inserts in the same direction as given in the .direction attribute

Thus these contents are inserted in 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 rows or columns could be inserted.

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

Objects with this method

Example 

dialog D

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

  child treeview Tv
  {
    .content[1] "Company A";
    .content[2] "Miller";
    .content[3] "Mayer";
    .content[4] "Company B";
    .content[5] "Jones";
    .content[6] "Smith";
    .content[7] "Fisher";
    .style[style_lines]   true;
    .style[style_buttons] true;
    .style[style_root]    true;
    .level[2] 2;
    .level[3] 2;
    .level[5] 2;
    .level[6] 2;
    .level[7] 2;
  }

  child pushbutton Pb
  {
    .text "Add new employee";

    on select
    {
      if fail(atoi(Et_level.content)) then
        Et_level.content := "You have not entered a level";
      else
        Tv:insert((Tv.activeitem + 1));
        Tv.level[(Tv.activeitem + 1)] := atoi(Et_level.content);
        Tv.content[(Tv.activeitem + 1)] := Et_name.content;
        Et_level.content := "On which level?";
      endif
    }
  }
  child edittext Et_name
  {
    .content "Enter name here";
  }
  child edittext Et_level
  {
    .content "On which level?";
  }
}

2.23.2 :insert() (Arrays)

This method inserts new items into arrays (indexed, non-associative, user-defined attributes). The newly inserted items are empty or have the default value if available.

Definition

boolean :insert
(
      attribute Attr input,
      integer Position input
  { , integer Count := 1 input }
)

Parameters

attribute Attr input
This parameter defines the user-defined attribute on which the method should be applied.
integer Position input
In this parameter the index where the new elements should be inserted is passed. If its value is 0, the elements are appended to the end.
integer Count := 1 input
This optional parameter defines the number of items that are inserted. If the parameter is not specified, 1 is taken as default.

Return value

The method returns true if the items could be inserted.

If an error has occurred when inserting, 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”