44 treeview

{ export | reexport } { model } treeview { <Identifier> }
{
  <standard attributes>
  <plain attributes>
  <geometry attributes>
  <hierarchy attributes>
  <layout attributes>
  <text attributes>
  <object-specific attributes>
}

Two different operations can be carried out interactively:

• Opening/Closing of subtree

  This can be carried out either by switching the +/- button or by a double click on the text.

• Selection

  Single or double click on an entry or changing the entry via keyboard control such as the cursor keys Left, Right, Up, Down, Page Up, Page Down, Home and End. Left/Right has the effect to close/open the subtree when used for the first time. Only after this state has been achieved, Up/Down will work.

The textual "emulation" has other differences apart from the visible ones:

• The +/- button cannot be activated; a subtree is opened/closed with a double click.
• The state of the subtree is not changed by using cursor keys Left and Right.

For the complete setting of treeview content including .open[], .level[] and .picture[] from C or COBOL side, no new interface functions have been introduced. Please use the existing functions DM_SetVectorValue() and DM_GetVectorValue().

The following events are triggered by interactive user operations:

Further standard events, which are listed below, are available. Their meaning is described in manual “Rule Language”.

Events

activate

close

cut

dbselect

extevent

focus

help

hscroll

key

open

paste

scroll

select

vscroll

Children

document

record

transformer

Parent

groupbox

layoutbox

module

notepage

splitbox

toolbar

window

Menu

Pop-up menu

Methods

:childcount()

:childindex()

:delete()

:exchange()

:find()

:insert()

:parent()

:reparent()

44.1 Attributes

Further information is provided in the following chapters and in the “Attribute Reference”.

44.1.1 .content and Content-specific Attributes

The contents of the treeview are set in the .content[integer] attribute. The individual items (and therefore index I) have to be consecutive (1, 2, 3, …).

The .level[integer] attribute then determines the hierarchy level (indentation) of the respective item. If an image shall be displayed, this is defined in the attribute .picture[integer].

The attribute .open[integer] determines whether a node is expanded or collapsed.

Remark

Please note that only by setting .content[I] further access to the content-specific attributes of this item is allowed. Therefore, the content must first be set first, followed by the content-specific attributes.

44.1.2 Note on Obsolete Attributes

The obsolete attributes .focusitem and .focusable are no longer supported and generate an ignoring warning when setting or resetting (setinherit) them and a fail when querying them.

44.2 Types of Information

The hierarchical information is stored in attribute fields. For each entry (= node of hierarchical tree) a static text and a tile is stored in the attributes .content[] and .picture[]; in the attribute .level[] the hierarchical relation is defined with a numeric value. The boolean attribute .open[] is used to make subtrees visible/invisible.

These attributes are used to store dynamical information and are thus not inherited! For attribute .content[] the index range is from 1 ... n; n represents the value of .itemcount here. For the attributes .level[], .picture[] and .open[] the index range is defined from 0 ... n. The element 0 serves as default value for unset values in the index range 1 ... n. The field size can be defined in the attribute .itemcount or can dynamically be maximized by one item by setting the .content[] field to n+1.

44.3 Tree Concept

The representation of the items 1 ... n in a hierarchical structure, a tree with parent-child relations, is defined with the attribute .level[]. Its integer value indicates indention. Here the absolute value is not relevant, but the difference to the previous one.

If the value is greater than the previous value, then the entry will be a child of the previous one. If the value is the same, the entry will be a sibling. If the value is smaller than the previous one, then the entry will be a child of a previous one whose indention is even smaller. We talk about a root, if no parent is found in the index range 1 ... n.

Example

results in the following tree structure:

Please refer to ref: attribute .level[] for a more specific definition. All methods known by the listbox can be applied to the treeview. However these methods also affect the attributes .level[], .open[] and .picture[] in the same way. In addition special methods for the manipulation and query of the tree structure are available.

As with listbox the attribute .activeitem allows to activate an entry within range 1 ... n of a tree, or to query the selection state. The selectivity depends on the visibility of the tree entry, and thus also on the attributes .level[] and .open[]. The following is valid for the Rule Language as well as for the interactive operation: On setting .activeitem all parents are set to .open[] := true. If a subtree is set invisible with .open[I] := false, although it contains a selected child, the entry I will be selected and .activeitem will be adjusted correspondingly.

44.4 Representation

The representation differs from the listbox as follows:

1. The hierarchical relation of entries is represented by indention and optionally with additional lines (Ref. attributes .style[] and attributes .level[]). If the root of subtrees is set invisible (.open[] is false), only the root will be displayed.
2. Optional picture for a text entry (ref: attribute .picture[]).
3. Optional +/- button, which will become visible for entries with children and which is used to open(+)/close(-) a subtree (ref: attribute .open[]).

Moreover all geometry and layout attributes relevant for listbox are valid.

44.5 Specific Attributes

In this chapter the specific attributes are described in more detail. The standard and geometry attributes as well as the attribute content will not be described here as they behave exactly in the same way as those for the listbox. Please note that the content-specific attributes of the entry can be accessed only after having set .content[]. This is why you have to set content before setting the content-specific attributes.

44.5.1 open[I]

This attribute is used to define the visibility of a subtree within a treeview object. If .open[I] is set to false, the direct children of subtree I won't be displayed, if not, the direct children will be visible. The hierarchical division into subtrees is defined by the attribute .level[I].

The index range 0 ... n is valid, n represents the value of the attribute .itemcount for the treeview. The value of .open[0] represents the default value for unset values within the range 1 ... n.

This attribute is only statically available and is not inherited.

44.5.2 level[I]

This attribute of the treeview object defines the hierarchical order of the entries. The resulting tree is characterized by a parent-child hierarchy.

The valid index range is 0 ... n, n represents the value of attribute .itemcount. The default value for unset attribute values of the range 1 ... n is indicated in .level[0].

The hierarchy is defined by the difference between subsequent .level[I] values and not by its absolute value. This, however, can be achieved by assigning the .level[I] values in a disciplined manner.

A single hierarchy can thus be achieved by any number of different .level[] definitions.

For the tree hierarchy only the range 1 ... n is considered, as only this range actually has a content (.content[I]) to be displayed.

The following rules are valid:

Example: Let's have a look at the following treeview.

This hierarchy can be equally defined with e.g. the following .level[] values:

Note: This attribute is available only statically and is not inherited.

44.5.3 picture[I]

This attribute defines the tile to be displayed for an entry.

The index range is 0 … .itemcount with the value of .picture[0] representing the default value for unset values within 1 … .itemcount.

This attribute is available only statically and is not inherited.

Notes

The tile will be displayed on the left-hand side of the text. Please note that the size of the displayed tiles cannot vary in the treeview due to technical restrictions. The size of the tiles is predefined by the tile size of .picture[0]. If this size is not specified the size of Smallicons (16x16) will be used as default. Bigger tiles of the field .picture[] will be clipped; smaller ones will be enlarged. There will be space for the tile on the left of the text as soon as at least one tile has been set. When .picture[0] is not set, a substitute icon (white cross on red background) will be displayed for items without a tile.

This attribute is not supported by the IDM for Motif.

44.5.4 style[E]

This treeview attribute is used to activate specific representation properties. These properties are switched off by default.

This attribute is indexed with an enumeration. Its meaning is described in the following table:

The different styles have the following representation:

Note

The three styles are supported by IDM for Windows only. The textual simulation of the treeview on other platforms offers the option .style[style_buttons] only. This option can be compared to the "Buttons, Root" representation of the above picture.

44.6 Example

dialog Dialog

window Wn
{
  .active false;
  .xleft  229;
  .width  446;
  .ytop   131;
  .height 180;
  .title  "Beispielfenster";

  child treeview Tv
  {
    .xleft  38;
    .width  163;
    .ytop   15;
    .height 151;
    .content[1] "Firma A";
    .content[2] "Mueller";
    .content[3] "Meier";
    .content[4] "Firma B";
    .content[5] "Schulz";
    .content[6] "Schmidt";
    .content[7] "Fischer";
    .activeitem 1;
    .firstchar  1;
    .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;
    integer Index;
    boolean Select := false;

    on select
    {
      if Tv.Select then
        Tv:reparent(Tv.Index, 1, Tv.activeitem, Tv.activeitem);
        Tv.Select := false;
        St.text   := "";
      endif
    }
  }

  child pushbutton Pb_rep
  {
    .xleft 240;
    .width 194;
    .ytop  26;
    .text  "Firma angliedern";

    on select
    {
      variable integer Index;

      Tv.Index  := Tv.activeitem;
      St.text   := "Waehlen sie eine neue Firma";
      Tv.Select := true;
    }
  }

  child statictext St
  {
    .xleft 241;
    .ytop  72;
    .text  "";
  }

  child pushbutton Pb_Exit
  {
    .xleft 355;
    .width 78;
    .ytop  132;
    .text  "Exit";

    on select { exit(); }
  }
}