SetFormat (Obox widget)

SetFormat (Obox widget)

SetFormat(windowID, oboxID), SetFormat(, oboxID), SetFormat

parameters: Identifier of a Windows and an object box

For the same command for FString widgets, see SetFormat (FString).

Which data an object box represents in which way is controlled by format elements. SetFormat uses the parameters from the stack to build a format element for the object box specified as an operand. The following parameters can be passed:

The first parameter listed in the table is necessary. If FillObox wants to represent an object, all format elements are evaluated for the class or a base class of the object. It is possible to display objects of different classes at the same time in one object box. On the other hand, the object box acts as a filter for a collection with objects of different classes, as it only displays elements that match its format list. The access expression in the first parameter leads to the data field which - converted into a string - is to be displayed at position x, y in a line of the list box.
Default assumption for y is zero. For an object box with flag AUTO_POSITION the x-value can also be omitted, because it is calculated automatically. (In the ObjectTree the position/AutoPosition is ignored, because the position results from the structure).

The AUTO_POSITIONing in the ObjectListView can be deactivated interactively by the user for each column by changing the column width by mouse drag in the column header to the right of the column. A column width changed in this way remains the same for the next AUTO_POSITIONing (e.g. when scrolling). Only when double-clicking in the column header to the right of the column, the AUTO_POSITIONing for the column is switched on again.
If AUTO_POSITION is set as flag for the ObjectListView, AUTO_POSITIONing is enabled by default for each column of this ObjectListView. This default behaviour can be overridden with the parameter FIX_WIDTH. With FIX_WIDTH(width), width greater than or equal to 0, the list is displayed exactly as if the user had already set it to the width width (in minicells) by mouse drag in the column header.
The set width can therefore be changed by double-clicking (reactivate AUTO_POSITION) or by dragging the mouse again in the column header, as if the user had made the setting interactively.

Since multiple SetFormat statements can be effective for a column, it is possible that multiple FIX_WIDTH widths are specified for a column. In this case, the largest specified value is always used.

FLAG

With parameter 9 flags can be passed to the conversion function of an object (ViewExport).
The notation FLAG flag is obsolete (i.e. prefixing the marker FLAG), but is accepted for compatibility with older versions of the ClassiX system.

If the 10th parameter is specified, the string is further modified as input for sprintf. For this purpose the format string must contain exactly one placeholder ("%s") for the original string.
If you only want to limit the length of the display, a specification with FIX_WIDTH is preferable to a formatting of the form "%.30s" or "%-.30s". This gives the user the opportunity to view the entire text if desired. It also prevents constant AUTO_POSITIONing for the corresponding column.

COLUMN
Normally, each column is described by a single SetFormat statement. Each SetFormat without COLUMN advances an internal counter by 1. If a column is to have several formats, proceed as follows:

[ Path(CX_X::aaa) ] SetFormat   // Spalte 0
[ Path(CX_X::bbb) ] SetFormat   // Spalte 1
[ Path(CX_Z::bbb) COLUMN 1 ] SetFormat // Spalte 1
[ Path(CX_X::ccc) ] SetFormat   // Spalte 2

Only the columns defined more than once must have a COLUMN statement. COLUMN prevents the internal counter from being advanced, so that in the example the fourth SetFormat statement describes the third column, even without COLUMN.
Reasons for multiple defined columns are bitmaps and the representation of different classes.

If several format specifications are defined for a column, only one of them may be used. The one to be selected is determined as follows:

1. A preselection is made via the class name: A format statement is only defined for the specified class and does nothing for other classes. As an example see above
2. INVALID is returned via the access path: During the evaluation, a part or the whole expression returns INVALID. This causes the evaluation to be aborted and the format statement to be ignored. Example:

Define(LocalIsNotPointer)
  Dup Copy(Type()) "POINTER" = if { Drop INVALID }
  ;
Define(LocalIsPointer)
  Dup Copy(Type()) "POINTER" = ifnot { Drop INVALID }
  ;

[ "CX_SLOT_ATTRIBUTE::call(LocalIsNotPointer).Value()" HEADER T("Wert", "Value") COLUMN 3 ] SetFormat
[ NO_DRAIN "CX_SLOT_ATTRIBUTE::call(LocalIsPointer).call(G_GetAttributePointerValue)" HEADER T("Wert", "Value") COLUMN 3 ] SetFormat

The macro calls in the access expressions of the format instructions are used to select exactly one of the two lines, depending on the object to be displayed. LocalIsPointer and LocalIsNotPointer return either the object or INVALID in the opposite case. The header value is the same for both representations, so that no conflicts occur here.

PUSH / call

If FillObox evaluates this format element for an object o, the specified statement is executed with the following stack allocation:

A simple example shows this possibility.
If the execution of the statement returns a bitmap, it is inserted accordingly: Without specifying the flag BITMAP_SIZE as parameter of the ObjectBox in its original size, otherwise it will be stretched to fill the whole width of the respective column.
Just as bitmap and string columns can be mixed (by specifying the COLUMN parameter), the same statement can return bitmaps for some objects and strings for others.

An expression with call() can also return an object, and then different Pozedur calls can be concatenated in the access path. For example

[ Path(CX_PERSON::call(FindNiece).call(FindUncle)) ] SetFormat

If a procedure in this chain returns INVALID, the subsequent procedures are no longer evaluated. If the last procedure returns an object and no string, then string is implicitly executed.

With the "modern" variant of the ObjectBox, ObjectListView, it is absolutely necessary that the result of such a format instruction depends exclusively on the object itself and not on the state of the system (global variables / module variables). The reason for this is, that the time, when the visual representation of the elements is created and therefore the order, in which the format instructions are executed, is not known from the beginning; and not the order of filling the objects into the ObjectListView.

If an ObjectListView is intended for printing and it happens that a cell contains both text and a bitmap, it is only reasonable to sort by number if the column definition with the number is defined first, followed by that of the image:

// At first the definition of the column with the number (to enable right sorting!)
[ Path(CX_LINK_TXN::UniqueID()) HEADER T("Auftrag", "Order") FIX_WIDTH(100) ] SetFormat

// Then the definition of the column with the picture!

[ Path(CX_LINK_TXN::call(Local_G_GetPicture)) COLUMN 0 ] SetFormat
...

If the text in this constellation is to be printed right-aligned, the specification JUSTIFY_RIGHT must be made for both the bitmap and the text format specification.

If a format specification with the BREAK flag is selected as applicable for a class, the format list is not searched further. Flag BREAK solves the following problem: If a format list contains formats for both a class A and a derived class B, both format specifications are normally used for a class B object. This is wrong if the format for B is a specialisation of a more general specification for A; i.e. for objects A the format A։։expression should be used, while for objects B only the specification B։։expression is valid. To achieve this, the more specific specification (B։։expression) must be specified with flag BREAK and before A։։expression.

NODE Lists,Tree and GROUPs:
The NODE specification gives the format a different meaning. Instead of being responsible for the presentation of an expression, NODE-SetFormats specify the data elements by which structured data is linked.
The class in parameter 1 filters the objects for which substructures are to be evaluated. The access expression of the 1st parameter specifies the data source of these substructures, e.g. a collection or a pointer. Of all other parameters, only BREAK and COLUMN are supported, whereby COLUMN has no effect on the respective format(NODE always implies COLUMN 0). It is advisable to always define NODE formats as the last SetFormat statements. With NODE the access path can be evaluated several times (see ObjectTree)!
Data is also structured via the GROUP flag. GROUPs differ from NODEsin that they do not define access to object collections (such as Collections), but rather access to normal data fields, for example, an enumeration. While NODE evaluates the access expression and branches into objects addressed by it, GROUP collects all objects addressed (via class specification) and inserts virtual superordinate elements, the groups, for them. In doing so, all objects are combined into a group, which are identical in the data field addressed by the access expression. While NODE always inserts a subordinate level (to which it also branches) GROUP inserts a (further) superordinate level.
Several GROUPs may also apply to one property. In this case, several levels (Groups) are inserted in a tree-like manner.
All other specifications in the SetFormat parameters are used to represent the newly inserted element(s). In the ObjectTree these group elements get a bitmap, if further SetFormats are specified, which return bitmaps via a non-primitive statement. Thereby the first (0.) bitmap format is used for the object itself, every further (ith) bitmap is used for the next (ith) group. Surplus bitmaps are ignored. If a group does not get a bitmap, a default icon ( ) is used.
If, for example, the additional parameter GROUP is given to a format with the specification sexEnum for the class CX_PERSON, the persons (below a certain NODE) are sorted in the representation of the persons according to gender into a group "female" or "male".

A special feature should be noted when using NODE-SetFormats in ObjectLists:
Since the ListBox, unlike the TreeView box, does not inherently (i.e. by platform) have graphical representation means for hierarchy visualisation, additional specifications are required for this in InstantView. For example, the drawing of the steps in the element arrangement and the + and - buttons, which are important for interactive expanding and collapsing, require the specification of three bitmaps in the 0th column in the following exemplary form:

Define(GetLeafBitmap)
  leafBmp //= ""
;
Define(GetCollapseBitmap)
   collBmp //= ""
;
Define(GetExpandBitmap)
    expBmp //= ""
;
.....
[ Path(CX_CLASS::call(GetLeafBitmap))     COLUMN 0 ] SetFormat
[ Path(CX_CLASS::call(GetCollapseBitmap)) COLUMN 0 ] SetFormat
[ Path(CX_CLASS::call(GetExpandBitmap))   COLUMN 0 ] SetFormat

It is important to specify the column(COLUMN), since the system only searches for the required bitmaps in the 0th column. It is also possible to structure the list without bitmaps, but then graphical expansion and collapse is no longer possible. The order of the specification is important, because this is how the assigned status is determined. To avoid confusing representations, all bitmaps should have the same size and the ObjectBox should be provided with the flag BITMAP_SIZE.
An ObjectList with NODEscannot be sorted afterwards. Also changes cannot be saved. To avoid unsuccessful change attempts of the users, an ObjectList with NODEsshould have the attribute VIEW_ONLY .
The advantage of using an ObjectList compared to the ObjectTree for the representation of structured data is that the (format-)strings of an object are not simply hung one after the other with spaces, but the columns of the ObjectList are preserved. So the whole output remains tabulated. The indentation of subordinate objects to visualise the structure is only in the 0th column in the ObjectList. In this column a dotted line is displayed in front of the indentation string, which connects the text with the bitmaps (according to the example above). The overall visual impression is similar to that of the ObjectTree in the 0. column.

HEADER
If in SetFormat each column is named using this parameter, the header statement can be omitted. If several HEADERS have been defined for a column (this also applies to multiline ListViews), the first SetFormat statement with HEADER for this column always wins.
If there are several HEADers for one column, there is a logical error which should be corrected!

Example format for the format of an ObjectTree from the tutorial:

ObjectTree(tree, 5, 15, 380, 170)
[
  INITIALIZE: [ Path(CX_PERSON::call(Symbol)) ] SetFormat // Sets a picture if male or female
              [ Path(CX_PERSON::name) ] SetFormat
              [ Path(CX_PERSON::firstName) ] SetFormat

// The children will be displayed in a node under the partens
              [ Path(CX_PERSON::children) NODE ] SetFormat
]

URL(Expression)

The passed expression is evaluated with the object of the current row and should return an absolute (with http://, https://) or relative URL as STRING or ML_STRING or INVALID if no link should be displayed for the object. This will display the text shown in the cell as a link to the specified URL. When the link is triggered, no SELECT is triggered on the ListView.

TOOLTIP(printout)

The passed expression is evaluated with the object of the current line and should return a tooltip as STRING or ML_STRING. To avoid displaying a tooltip for certain objects, an empty string can be returned. The tooltip is displayed as tooltip at the cell when hovering.

THUMBNAIL(width,height)

If the access print provides an image, this format instruction can be used to specify the size (in pixels) in which the image is displayed in the list. Only when clicking on the image, the image will be displayed in its full size

BUTTON(Id, expression) & LINK(Id, expression) - Cell widgets (TreeList & ObjectListView only)

For MorphIT, cell widgets can be specified, which display themselves in a ListView/TreeList cell and allow interaction to a limited extent. The optional access expression defines the access expression that is used to display the text of the cell widget. If no access expression is specified, the primary access expression of the cell is used.

The messages of the cell widgets are defined in the action list of the corresponding list. There is a special syntax for this to indicate to which cell widget the event refers.

The syntax for this is: MESSAGE@ID (currently only SELECT is supported). If such an event is triggered, the row of the cell widget is the only selected row and the corresponding object can be fetched using GetObject.

Code example:

[ 
    INITIALIZE: [ Path(CX_CONTAINER::str) TOOLTIP(strB) BUTTON(ID_BTN) ] SetFormat
    SELECT@ID_BTN: "Cell button selected on Object " GetObject String + Attention(, INFO)
    SELECT: "List entry selected" Attention(, INFO)
]