37 A.06.01.a

37.1 Qt Support

37.1.1 Supported Platforms

The IDM for Qt is available in 32- and 64-bit versions for Qt 4.6 on Red Hat Enterprise Linux (RHEL) 5.5 and Qt 4.8 on RHEL 7. These versions are also executable on SUSE Enterprise Linux.

Qt itself is not included in the IDM for Qt. The required Qt versions can be installed via the package managers of the systems. If multiple Qt versions are installed on one system, attention must be paid to link with the correct version when building applications.

37.1.2 Error and Warning Messages

In the case of an inappropriate Qt version, the IDM outputs the error message WSIQT version mismatch.

Access to not yet implemented or unsupported objects, attributes and functions is indicated by messages such as …NOT-IMPLEMENTED… or …UNSUPPORTED… in the log file.

37.1.3 Special Features of Qt

Qt supports transparent colors and may use them in the default palette. This can lead to the fact that visible objects can not be operated, because an overlying object with a transparent background prevents their operation. For example, this case occurs with two overlapping statictexts of fixed size.

Because Qt supports different UI styles, colors (foreground, background) may vary in different styles or be ignored altogether. The appearance may vary depending on the UI style. In addition to colors, this also affects other display aspects, for example, existing or missing frames depending on the UI style.

The depiction of color gradients also depends very much on the object and the UI style.

Example

For a poptext with the style poptext or edittext and set .bgc in the UI style cleanlooks the background color is ignored by the pop-up list in the opened state.

37.1.4 Differences to Other IDM Versions (Compatibility)

This chapter describes differences from the versions of the ISA Dialog Manager for other toolkits. These differences are due to specific features of the Qt toolkit, which may also mean that the IDM uses capabilities of Qt that are not provided by the other toolkits.

37.1.4.1 Objects

37.1.4.1.1 Canvas

The canvas object has the option opt_graphicsview on Qt. It controls whether the canvas is implemented using a QFrame (opt_graphicsview = false) or a QGraphicsView (opt_graphicsview = true). The option is turned off by default. Then, it can be drawn directly into the QWidget in the expose event. If the option is turned on, no expose message will be forwarded to the canvas. For example, this mode, in which the QGraphicsView is the container of a QGraphicsScene, is used to add objects to the scene, which the scene then draws on its own.

Depending on the option value, there are differences in the DM_CanvasUserArgs, which is now defined as follows:

typedef struct {
  DM_ID  object;
  int    reason;
  #  ifdef QCOREEVENT_H
       QEvent*  event;
  #  else
       DM_Pointer  event;
  #  endif
  #  ifdef QWIDGET_H
       QWidget*  widget;  // depending on opt_graphicsview
                          // QFrame* or QGraphicsView*
       QWidget*  window;
  #  else
       DM_Pointer  widget;
       DM_Pointer  window;
  #  endif
  #  ifdef QFONT_H
       QFont*  font;
  #  else
       DM_Pointer  font;
  #  endif
  #  ifdef QCOLOR_H
       QColor*  fgc;
       QColor*  bgc;
  #  else
       DM_Pointer  fgc;
       DM_Pointer  bgc;
  #  endif
  DM_Int2     x;
  DM_Int2     y;
  DM_UInt2    width;
  DM_UInt2    height;
  DM_Pointer  userdata;
} DM_CanvasUserArgs;

In addition, .fgc, .bgc, and .font are passed to the canvas function because in some cases they must be explicitly set when drawing or adding new objects.

The canvas object has a new option opt_addevents. The option is turned off by default. When turned on, it causes all QEvents to invoke the canvas function in addition to the usual calls to the canvas function. For example, you can react to a MouseMove. The reason, which in this case is given to the canvas function, is CCR_event.

37.1.4.1.2 Edittext

There are behavioral differences between single-line and multi-line edittexts in regard to the depiction of the selection on focus loss. In single-line mode, the selection is removed and, like the cursor position, is no longer displayed. When the focus is regained, the IDM restores the selection. In multi-line mode, the selection remains on focus loss.

Depending on the UI style, the presentation of the focus frame may be limited in the single-line edittext.

The edittext has the option .options[opt_html] on Qt, which controls its HTML capability.

37.1.4.1.3 Filereq

The attribute .text[enum] is not supported by the IDM for Qt, analogous to the IDM for Windows.

When displayed via the querybox or DM_Querybox functions, the file or directory dialog is displayed centered in the desktop or window – if one is specified as a parameter.

The option .options[opt_createprompt] is not supported. When combining .mustexist = true with .options[fro_overwriteprompt] = true, no dialog will be displayed to confirm overwriting.

Multiple selection is only possible for existing files. If .multisel = true, .mustexist is ignored.

The use of .bgc, .fgc and .font is possible, but it is not recommended.

To filter the displayed files, a file type list can be specified. The different file types are separated by tabs \t. For each file type, multiple patterns *.<suffix> can be given. The patterns are separated by spaces or semicolons, the list of patterns should be enclosed in parentheses. The Windows format of the file type list, with a tab between the name of the file type and the associated patterns, without parentheses around the pattern list, is also supported. Both variants lead to the display of the pattern list in parentheses after the name of the file type.

Example

.pattern := "IDM Files (*.dlg *.idm *.mod)\tIDM Interfaces (*.if)\tAll (*.*)";
.pattern := "IDM Files\t*.dlg;*.idm;*mod\tIDM Interfaces\t*.if\tAll\t*.*;

Both assignments produce the following selection list:

IDM Files (*.dlg; *.idm; *.mod)
IDM Interfaces (*.if)
All (*.*)

37.1.4.1.4 Image

The color .bgc is used if .imagebgc is not specified for internally defined tiles and to color transparent areas of external tiles.

With .borderwidth = 0, the image gets the style flat, meaning that no frame is drawn. However, pressing the mouse button draws a frame to represent the pressed state.

37.1.4.1.5 Menubox, Menuitem, Menusep

The colors of the menu bar in a window are determined by the attributes .menubgc and .menufgc. The colors of the menuitems and sub-menus in pop-up menus as well as in menu bars are determined by .bgc and .fgc of the menubox. This means that the background and foreground color of individual menuitems cannot be changed.

Keyboard navigation behaves differently depending on the UI style. In general, the current entry can always be selected with Enter. With regard to the selection with Space, however, there are differences:

Table 19-5: Behavioral differences of menus in different UI styles

37.1.4.1.6 Messagebox

The attribute .sysmodal is not supported by the IDM for Qt.

For the .icon attribute, the display symbols listed in “Table 19-6” are available whose appearance is determined by the selected UI style.

Table 19-6: Icon values and display symbols

37.1.4.1.7 Poptext

On Qt, a maximum of 10 entries are displayed in an open poptext by default. If the poptext list contains more than 10 entries, then a scrollbar is additionally displayed in the list.

The .showitem attribute is ignored in the mac and gtk+ UI styles. In UI style cleanlooks, .showitem is ignored with .style = poptext, here always the complete list is displayed.

With .style = listbox, .showitem is completely ignored.

With the styles poptext and edittext, navigating through the open list using the arrow keys does not automatically select the accessed entry. A final selection must be completed with Enter. This is Qt default behavior.

37.1.4.1.8 Progressbar

The option .option[continuous] is not supported. Qt draws the progress bar depending on the used UI style (cleanlooks, plastique etc.). By default, a continuous bar is drawn in which a subdivision is indicated by color change. However, once you set .fgc, the bar will be drawn continuously in that color.

The .borderwidth attribute is not supported.

The attribute .textfgc is applied. As soon as the bar runs under the caption, the font is displayed in the background color .bgc.

The progressbar with .value = .minvalue displays a small piece of the bar on the left and the text 0%. It is only displayed completely empty if .value = -1. Then, however, no value is displayed in percent.

37.1.4.1.9 Scrollbar

In certain UI styles (e. g. cleanlooks) with .arrows = false a part of the background (left or above the slider) is colored.

37.1.4.1.10 Setup

In the IDM for Qt, the attribute .toolkit has the enum value toolkit_qt and .toolkit_string has the value Qt.

The setup object has the new attributes .colorname[integer], .cursorname[integer] and .fontname[integer], which contain lists of the available color names, cursor names and fonts (see chapters “colorname[integer]” to “fontname[integer]”).

The attribute .toolhelp for influencing the display duration is not supported. Additionally, the toolhelp appearance cannot be changed using .options[opt_balloon_toolhelp].

37.1.4.1.11 Spinbox

The .direction attribute and the horizontal alignment of the arrows are not supported.

37.1.4.1.12 Statusbar

Qt ignores the width of the statusbar children. Apart from the last visible child, the child objects are always as wide as necessary for the complete presentation of their content. Therefore, the attribute .alignment has no visible effect except for the last visible child.

Tabulators to center or right-justify the text of .statushelp are not supported.

37.1.4.1.13 Tablefield

In an extremely small tablefield, where the line and column headers cannot be displayed completely, scroll bars are available. These have no effect, however.

The tablefield has an empty line or empty column at the bottom and on the right, which fill the free area when scrolling all the way up or to the right. If the tablefield is dimensioned such that the last content row or content column can not be displayed completely, then the user can scroll to this empty row or empty column. This position cannot be queried or set programmatically.

The selection model of Qt is used, so there may be slight differences to the other window systems. However, the behavior is Qt-typical. If with the attribute .selection multiple of the elements sel_column, sel_row and sel_single have the value true, then sel_single is used. The element sel_header is ignored, the header is always selected.

The border of the tablefield can only be switched off via .borderwidth = 0 and switched on via .borderwidth = 1. The color and partly the width of the border cannot be influenced.

The following attributes are not yet implemented in this version:

• .colheadshadow
• .fieldshadow
• .rowheadshadow
• .xmargin
• .ymargin

37.1.4.1.14 Toolbar

The toolbar can have two different forms on Qt, which are set via the .style attribute. By default, the style toolbar is active, which visually matches the familiar toolbars.

Table 19-7: Attribute .style of the toolbar

“Figure 19-14” shows the division of a window with different toolbars in the docked and undocked state. Tb16 and Tb18 as well as Tb19 and Tb20 are tabbed toolbarsthat share their space. Tb17 is a nested toolbar embedded in the second row of the right pane.

The style notepage allows to nest multiple toolbars in in one docking area and arrange them as tabs (see chapter “Window”, “Table 19-9” for the corresponding control options). The toolbars then have a title bar and can be undocked and closed using their title buttons.

Toolbars of different styles defined in the same docking area cannot be mixed and are grouped according to their style. Toolbars with the style toolbar are always positioned at the outer edge of the window and toolbars with the style notepage are always positioned between the client area of the window and the toolbars with the style toolbar (see “Figure 19-15”).

Toolbars cannot be positioned with spaces between them. The attribute .autoalign has no function.

Toolbars with the toolbar style cannot be resized with the mouse and do not create move events when moved.

The attribute .sizeable behaves when true like the attribute .autosize, that is, the entire available width or height is filled. If false, the set size is retained under all circumstances.

Toolbars are not automatically wrapped in the next row or column if not all of them fit into the given window width or height. In this case, Qt enlarges the window accordingly to accommodate all toolbars. A new row or column can only be forced through the .dock_line attribute.

For toolbars with the notepage style, positioning depends on the opt_nested_docks and opt_tabbed_docks window options. If both options are deactivated (default), then .dock_line is ignored and all toolbars are arranged side by side (horizontal) or one above the other (vertically).

If the option opt_nested_docks is active, then .dock_line is considered. Nesting is always relative to the previous toolbar of the same docking area. In “Figure 19-16” the toolbars eins, zwei and drei each have .dock_line = 1, vier has .dock_line = 2 and is embedded into „drei“.

If the opt_tabbed_docks option is active, all toolbars with the same .dock_line are displayed as consecutive tab pages (“Figure 19-17”).

Depending on the UI style, no boundary from the client area may be displayed for .style = notepage.

When switching between horizontal and vertical docking, the width and height are not reversed, because depending on the type of the toolbar, changes of orientation may already occur during the move.

The attributes .height[] and .width[] are only supported and applied in the notepage style.

37.1.4.1.14.1 Behavior

With tabbed toolbars, activating a tab or the associated visualization sends an activate event (similar to notebook and notepage).

Sending events such as activate, deactive, close, move and resize strongly depends on the Qt toolbar object in use. Internal states such as User is still dragging cannot be taken into account.

“Table 19-8” summarizes the differences and limitations of the toolbar in the IDM for Qt.

Table 19-8: Differences and limitations of the toolbar

37.1.4.1.15 Window

The window object has four additional options for supporting toolbars and tabbed docks, as well as sizing and positioning a window to be Qt-compliant.

Table 19-9: Options of the window object

As on Motif (and unlike Microsoft Windows), on Qt the .sensitive attribute does not affect the title bar of the window. Even if .sensitive = false (and the window content is no longer operable), the title bar functions (close, move, minimize, maximize…) can still be used.

The attribute .moveablehas no effect on Qt. Windows can always be moved.

In general, the IDM for Qt generates significantly more move and resize events than the other IDM versions, because for each pixel to be increased, decreased, or moved a corresponding event is triggered. There is no reliable way to determine the state and end of the actions.

Some window states can only be changed by internally clobbering, which triggers activate and deactivate events, however.

It may still happen that size specifications in certain constellations are not correctly put into effect (e.g. when changing them in the minimized state). Currently, the behavior may vary depending on the Window Manager (for example, when minimizing).

37.1.4.2 Resources

37.1.4.2.1 Mnemonics

The following objects support mnemonics:

• Checkbox
• Menubox
• Menuitem
• Pushbutton
• Radiobutton
• Statictext

37.1.4.2.2 Color

37.1.4.2.2.1 Color Identifiers and Null Color

As color identifiers all SVG color names can be used (http://www.w3.org/TR/SVG/types.html#ColorKeywords), where upper and lower case is ignored. When using these color names (for example, green), the colors are realized according to the SVG color names of the W3C. Therefore, some colors differ in tone and intensity from the X11 colors.

In addition, the following Qt default colors depending on the current settings are available:

• BASE  background of input fields and certain container objects (lists)
• BASETEXT  foreground of input fields and certain container objects (lists)
• BUTTON  button background
• BUTTONTEXT  button foreground
• HIGHLIGHT  background for selection and active entry
• HIGHLIGHTTEXT  foreground for selection and active entry
• SHADOW  shadow color, mostly very dark to black
• WINDOW  window background
• WINDOWTEXT  window foreground
• BRIGHTTEXT Text color for low contrast
• ALTERNATEBASE alternatively background color (mostly for tables)
• TOOLTIPBASE  tooltip background
• TOOLTIPTEXT tooltip foreground
• LINK link foreground
• LINKVISITED visited link foreground
• PLACEHOLDERTEXT placeholder foreground for various input windgets, since Qt 5.12
• ACTIVE_BASE
• ACTIVE_BASETEXT
• ACTIVE_BUTTON
• ACTIVE_BUTTONTEXT
• ACTIVE_HIGHLIGHT
• ACTIVE_HIGHLIGHTTEXT
• ACTIVE_SHADOW
• ACTIVE_WINDOW
• ACTIVE_WINDOWTEXT
• ACTIVE_BRIGHTTEXT
• ACTIVE_ALTERNATEBASE
• ACTIVE_TOOLTIPBASE
• ACTIVE_TOOLTIPTEXT
• ACTIVE_LINK
• ACTIVE_LINKVISITED
• ACTIVE_PLACEHOLDERTEXT since Qt 5.12
• DISABLED_BASE
• DISABLED_BASETEXT
• DISABLED_BUTTON
• DISABLED_BUTTONTEXT
• DISABLED_HIGHLIGHT
• DISABLED_HIGHLIGHTTEXT
• DISABLED_SHADOW
• DISABLED_WINDOW
• DISABLED_WINDOWTEXT
• DISABLED_BRIGHTTEXT
• DISABLED_ALTERNATEBASE
• DISABLED_TOOLTIPBASE
• DISABLED_TOOLTIPTEXT
• DISABLED_LINK
• DISABLED_LINKVISITED
• DISABLED_PLACEHOLDERTEXT since Qt 5.12
• INACTIVE_BASE
• INACTIVE_BASETEXT
• INACTIVE_BUTTON
• INACTIVE_BUTTONTEXT
• INACTIVE_HIGHLIGHT
• INACTIVE_HIGHLIGHTTEXT
• INACTIVE_SHADOW
• INACTIVE_WINDOW
• INACTIVE_WINDOWTEXT
• INACTIVE_BRIGHTTEXT
• INACTIVE_ALTERNATEBASE
• INACTIVE_TOOLTIPBASE
• INACTIVE_TOOLTIPTEXT
• INACTIVE_LINK
• INACTIVE_LINKVISITED
• INACTIVE_PLACEHOLDERTEXT since Qt 5.12

Normal and active states are identical.

The identifier DEFAULT serves as null color. If this color is assigned, the respective color is reset to the corresponding default color (depending on the current system settings).

37.1.4.2.2.2 Gradients

Color resources support gradients on Qt. These are defined as follows:

color {<Identifier>} gradient("<kind>[,<arg>]");

The parameter <kind> defines the gradient type. Only one gradient type may be specified.

The other parameters may include:

• Supplementary parameters for the gradient type
• Stop point definitions
• Color definitions

These gradient types are available:

Table 19-10: Types of gradients

The color definitions are always appended after the gradient type and any supplementary parameters. You can use color names, HTML notation, and the rgb(…), hls(…), and grey(…) notations known for color resources.

In addition, a stop point can be specified for each color definition, which determines the weighting of the color. A stop point is a percentage with an optional percentage sign that always precedes each color and affects how much space that color occupies in the gradient. A gradient starts at 0% and ends at 100%, based on the area it fills. The specification … , 20%, green, ... means, for example, that after 20% of the area to be filled, the color green is set. If no other color is set for the 0–20% range, the first 20% of the range is colored green. If another color is already set before 20%, then a transition between this color and green is displayed.

Stop points should always be set in ascending order. If several colors are defined with the same stop point, the color that is furthest at the end of the parameter list applies. For example, the definition .... , 20%, green, 40%, blue, 20%, red, ... produces a gradient with a shade of red at 20%, which changes to a blue tone that is shown as saturated at 40%.

Examples

gradient("Linear, green, yellow, red");  named colors, evenly distributed
gradient("Linear, #00FFFF, #00FF00, #FF0000");  HTML notation,
                                                colors evenly distributed
gradient("Linear,red, #00FF00, rgb(0,0,255)");  mixed notations,
                                                colors evenly distributed
gradient("Linear, 20%, green, 60%, yellow, 80%, red");  named colors with
                                                        percentage stop points
gradient("Linear, 20, green, 60, yellow, 80 ,red");  the % sign at the
                                                     stop points is optional

Notes

Qt allows the setting of gradients in most places, but does not necessarily apply them. Whether a gradient is displayed depends very much on the object and the UI style. In this case, areas (e.g. backgrounds) are usually unproblematic, with delicate structures (e.g. texts) the gradient is often replaced by a single color. For grouping objects, gradients as a background are usually displayed.

37.1.4.2.3 Cursor

There are the following named cursors where the corresponding Qt CursorShape is loaded:

• arrow
• blank
• busy
• closedhand
• cross
• dragcopy  since Qt 4.7
• dragmove  since Qt 4.7
• draglink  since Qt 4.7
• forbidden
• ibeam
• openhand
• pointinghand
• sizeall
• sizebdiag
• sizefdiag
• sizehor
• sizever
• splith
• splitv
• uparrow
• wait
• whatsthis

The appearance of the cursors may vary depending on the UI style.

37.1.4.2.4 Font

Fonts can be defined in the following ways:

X Logical Font Description (XLFD)

"-adobe-helvetica-medium-r-normal--12-*-*-*-p-*-iso8859-1"
"*adobe-helvetica-bold-r-normal-*-100-*-iso8859-1"

Notes

• Qt has problems processing wildcards in XLFD's.
• If Qt can't match a font exactly, it takes the font family that is most likely to match. Inevitably, substitution of values occurs.
• Font aliases (file fonts.alias in the font directory of X11) are not supported by Qt. Therefore, for example, font fixed cannot be used.

Attention

• Since Qt5, supporting functionality for processing XLFD fonts has been depricated.
• Using XLFD fonts is not recommended.

Qt Style with Comma-separated Parameter List

Family, PointSize, PixelSize, QFont::StyleHint, QFont::Weight, QFont::Style,
Flag underline, Flag strikeout, Flag pixedPitch, Flag rawMode

"Helvetica, 12, -1, 5, 75, 1, 0, 0, 0, 0"

Not all parameters have to be specified, "Helvetica, 12" is sufficient, for example.

Font with Independent Display Attributes (Size and Style)

"Helvetica", 12, bold

The styles bold, italic and oblique are supported.

Qt style specifications can be combined with independent display attributes:

"Helvetica, 12", bold

37.1.4.3 Attributes

37.1.4.3.1 colorname[integer]

Attribute of the setup object that contains a list with the names of the colors available in the WSI.

Availability

IDM for Qt only, since IDM version A.06.01.a.

37.1.4.3.2 cursorname[integer]

Attribute of the setup object that contains a list with the names of the cursors available at the WSI.

Availability

IDM for Qt only, since IDM version A.06.01.a.

37.1.4.3.3 fontname[integer]

Attribute of the setup object that contains a list with the names of the fonts available in the WSI.

Availability

IDM for Qt only, since IDM version A.06.01.a.

37.1.4.3.4 picture and picture_hilite

If in listbox and poptext a tile is only set for .picture_hilite, but not for .picture, then Qt will display the tile defined in .picture_hilite (or a slight modification of it) even in the unselected state. Qt always tries to provide images for all states for the list entries. If the image is missing for a state, Qt generates it from the images provided.

37.1.4.3.5 statushelp

When hovering over different objects with the mouse, the corresponding status texts are displayed when changing from a parent object to a child object. However, if the mouse is moved back from the child to the parent object, the status text of the parent object will not be displayed again.

37.1.4.4 Interface Function DM_PictureHandler

The structure DM_PicInfo on Qt corresponds to that on Motif.

typedef struct {
  ...
  #  if defined(MOTIF) || defined(QT)
       DM_UInt2    type;        // image type
       DM_Pointer  image;       // pointer to the image data
       DM_Pointer  trans_mask;  // pointer to the transparency mask
  #  endif
  ...
} DM_PicInfo;

Image type (type) can be one of the following values:

• DM_GFX_QPIXMAP
• DM_GFX_QIMAGE
• DM_GFX_QICON

The data type of image and trans_mask must match the specified image type.

37.1.5 Known Issues and Limitations of this Release

37.1.5.1 Qt 4.6

We recommend – also for reasons of stability – to use the Qt version 4.8:

• On Qt 4.6, drawing problems can occur in certain constellations, so that, for example, objects are clipped, parts of the borders are missing or control elements (arrows of poptext or spinbox) are distorted.
• It was also observed that fonts did not look quite smooth but rather pixelated.
• There are problems with the keyboard navigation or the detection of the pressed keys in remote constellations (WinAxe, VM ...). These problems were solved not before Qt 4.8.
• The attribute .preeditsel of the tablefield is always treated as presel_all if a single-line edittext is attached. The reason is that the used QTableView object executes a selectAll() before passing the keystroke.
• Scrolling within a virtual area slows down as the number of child objects increases. This problem was solved not before Qt 4.8.
• It may happen that a list entry is displayed too much in the poptext if .showitem is set.

37.1.5.2 Borders

If an object that has a border with style border_plain (or border_compat and .borderwidth > 1) is horizontally negatively positioned, or if it is made visible within a virtual area by horizontal scrolling, then a diagonal line or notch ( in the background color of the father) may exist in the lower right corner of its borders.

37.1.5.3 Events

It can still happen that an object without intermediate focus loss receives multiple focus events. Certain attribute changes that require internal recreation of objects (clobbering) still influence the event processing.

37.1.5.4 Drag-and-Drop

The following explanations refer to the drag-and-drop with the mouse.

The resources source and target as well as the data transfer between applications or objects have been implemented with the classes and events offered by Qt. The functionality is similar to Microsoft Windows, with only the types type_text and type_object supported. The cursors displayed during drag-and-drop (while dragging, dropping possible or impossible) are controlled by Qt and depend on the UI style.

Possible responses of some objects to drag-and-drop actions (for example, unwanted scrolling of listbox and treeview while dragging with the mouse) are currently not considered.

37.1.5.5 Command Line Option -IDMserver

The IDM for Qt displays the following information with the command line option:

• runtime environment,
• build version,
• UI style (QStyle),
• vendor name of the X11 server,
• release.

37.2 Border Attributes

37.2.1 New Features

Up to now, object borders were rendered in different forms depending on the WSI and its possibilities and influenced the position and extent of an object in different ways.

As of IDM version 6, the handling and application of border attributes and their effects on the appearance and geometry of an object have been standardized – also in terms of the portability of dialogs.

Starting with IDM Version 6, the user has at hand a largely uniform availability, implementation and enhancement of the border attributes as well as their effects on appearance and geometry across all WSI's.

This ensures better portability of dialogs to other WSI's, which was previously not the case due to the sometimes significant differences in geometry implementation and representation between the individual WSI's or resulted in more complex porting work.

The new attribute .borderstyle now provides the user with extended design options for the style and characteristics of borders at certain objects.

37.2.2 Border Design

The attribute .borderstyle is decisive for the border style of an object. Possible style options are: border off, toolkit border, line-shaped border, raised 3D border, and sunken 3D border.

The following objects have the attribute .borderstyle:

• Canvas
• Edittext
• Groupbox
• Image
• Layoutbox
• Progressbar
• Rectangle
• Splitbox
• Statusbar
• Toolbar
• Window

The value range for the objects edittext, image, progressbar, statusbar, toolbar, and window is restricted to the two values border off and toolkit border.

The .borderstyle attribute is closely related to the attributes .borderwidth and .bordercolor. In the style of a line-shaped border, .borderwidth and .bordercolor affect the width and color of the border. With the two 3D border styles, the width of the frame can be influenced via .borderwidth.

The attribute .borderstyle always takes precedence over the attributes .borderwidth and .bordercolor. That is, .borderwidth and .bordercolor are only observed if permitted by the .borderstyle set.

Examples

groupbox Gb 
{
  .borderstyle border_plain;  // simple line-shaped border
  .borderwidth 5;             // frame is 5 pixels wide
  .bordercolor CoRed;         // frame is drawn in red
}
 
groupbox Gb2 
{
  .borderstyle border_none;  // switch off border
  .borderwidth 5;            // remains without effect, because without border
  .bordercolor CoRed;        // remains without effect, because without border
}
 
groupbox Gb3 
{
  .borderstyle border_toolkit;  // default toolkit border of the WSI
  .borderwidth 5;               // remains without effect as WSI draws
  .bordercolor CoRed;           // remains without effect as WSI draws
}
 
groupbox Gb4 
{
  .borderstyle border_plain;  // simple line-shaped border
  .borderwidth 0;             // is converted to the standard border width
                              // of the WSI
  .bordercolor CoRed;         // border is drawn in red
}

Objects that do not support the .borderstyle attribute but have the attributes .borderwidth and .bordercolor from the history can still set and read these attributes, but they no longer affect the graphical display of these objects.

37.2.2.1 Compatibility Regarding Design

Existing dialogs are started in a compatibility mode. This means that objects, which have .borderwidth or .bordercolor set and now also support the new .borderstyle attribute, are rendered according to how IDM 5 works. That is, no visible changes occur for the affected objects.

In this case, the .borderstyle attribute is set to border_compat. However, the user is encouraged to adapt .borderstyle of these objects accordingly to a desired variant, since the compatibility mode border_compat may be omitted in the future. The compatibility mode border_compat cannot be actively set by the user.

There are objects for which setting borders is no longer supported and the rendering is left entirely to the WSI. These include listbox, notebook, notepage, tablefield, and treeview.

For these objects, where .borderwidth and .bordercolor are no longer supported, a warning message about obsolete attribute settings is output. The settings are no longer observed by the WSI and show no effects. The user should rewrite the places where these warnings now appear, since in future versions these attributes may be omitted from these objects.

37.2.2.2 Motif-Option .options[opt_xmborder_compat]

.borderwidth at the tablefield now has the default value 0 instead of former 1. This only has effects on Motif. There is the compatibility option .options [opt_xmborder_compat] available for Motif to convert the tablefield back to its former representation. A setting of .borderwidth = 1 also leads to the previous appearance, however, an additional warning message appears because .borderwidth will no longer be supported for the tablefield in the future.

37.2.2.3 WSI Limitations and Specifics

37.2.2.3.1 Motif

The toolkit border of the groupbox is a 3D border.

Objects with a virtual area – these include the groupbox with .vwidth or .vheight and the layoutbox – cannot display the border_raised and border_sunken border styles; instead, a border is drawn that corresponds to the border_plain style and can therefore also apply the correct .borderwidth. Only a groupbox without a virtual area is not restricted.

Since there may be drawing problems on Motif when an object has position 0 or negative, drawing of the border is omitted in this case.

37.2.2.3.2 Windows

The objects canvas and rectangle had 3-dimensional, colored borders in the IDM 5. These borders are only available in border_compat border style. With the new border styles, there are either 3-dimensional borders in the system color or flat, colored borders.

The objects notepage and tablefield have no .borderstyle attribute and thus no compatibility to the IDM 5 The tablefield object now has a default border width and the object notepage no longer has a border of its own.

The height of the poptext object was calculated 2 pixels too high in the IDM 5 when Visual Styles were active. This is now corrected, except in the style listbox, where the height already was correct.

The styles border_raised and border_sunken require a minimum width of 2 pixels in order to display feedback if necessary. That is, if the user has specified a .borderwidth of 0 or 1 pixel here, the border will still be drawn with 2 pixels.

37.2.2.3.3 Qt

For the following objects, the attribute .borderstyle has no effect at all:

• Progressbar
• Statusbar
• Toolbar
• Window

The spinbox object always draws a border on Qt. The attribute .borderstyle only determines where this border is drawn. With border_none the border is drawn inside the object, with .borderstyle = border_toolkit outside.

The frames are determined and drawn significantly by the set UI style. The appearance may vary depending on the UI style.

37.2.3 Geometry

Across all WSI's, grouping objects now always draw their frame outside the object.

The geometry calculation – no matter whether normal or with grid – is performed according to previous rules and based on the reference points .xleft and .ytop as well as .xright and .ybottom.

However, these points as well as .width and .height only define the object position and size excluding the border. They define the client area of the grouping object. This provides the maximum available space for the child objects. The border is drawn by the WSI on the outside around this dimension.

The exception to this is the window object, whose positioning and dimensions remain unchanged.

Example

Groupbox Gb {
  .width  100;  // The inner area of the groupbox has a size of
  .height 50;   // 100x50 pixels.
  .xleft  20;   // The outermost point of the interior is [20,15].
  .ytop   15;
  .borderstyle border_plain;
  .borderwidth 5;
}
// => The actual size of the object including the border is 110x60
//    (width + left border + right border and height + upper border +
//    lower border). Outer point on the top left is [15,10].

For non-grouping objects, there are no changes regarding the geometry. They continue to draw their borders inside. The attributes .xleft and .ytop as well as .xright and .ybottom thus define the outermost points, .width und .height the entire size of the object.

37.2.3.1 Compatibility Regarding Positioning

On Motif, there may be a slight shift of grouping objects in existing dialogs because the real size of grouping objects with borders is now larger than before and the real position is shifted one border width to the left and up. But this also means that the client area of such grouping objects is now larger and offers more space for its children.

Furthermore, this results in several groupboxes, which are nested via.xauto = 0 and .yauto = 0, now optimally use the space and themselves, as well as their children are no longer displayed cropped.

37.2.3.2 Command Line Option -IDMborder5_compat

On Motif, objects with negative coordinates and their children are partly not navigable and focusable. This also applies if the object is only partially out of the visible area. This is a limitation of the WSI.

Because borders of grouping objects are now always drawn outside, resulting in a position shift, it is possible that grouping objects and their children in existing dialogs may suddenly no longer be navigable, for example, because the border has been moved into the negative. Therefore, a geometry compatibility mode is introduced via a command line option ‑IDMborder5_compat, which computes the geometry according to IDM 5 rules.

On Microsoft Windows, there are a number of compatibility options that are no longer evaluated. If existing dialogs cannot be adjusted immediately, the evaluation of these compatibility options can be reactivated via the command line option ‑IDMborder5_compat. The following options (attribute .options[]) are affected:

• opt_wntsizebug_compat
• opt_w2kprefsize_compat
• opt_win31_sizing

In addition, the height of the poptext object is calculated as in IDM 5.

The border5_compat mode can also be activated through setting the environment variable IDM_BORDER5_COMPAT.

37.2.4 Attribute .borderstyle

This attribute defines the style, i.e. the representation and characteristics of the borders of an object.

The following value range is predefined:

• border_compat
• border_none
• border_plain
• border_raised
• border_sunken
• border_toolkit

* if supported by the respective WSI

Table 19-11: Support of the .borderstyle attribute

37.2.5 Enhancements in the Editor

Using the Properties tool palette, you can select the Borderstyle of an object on the Layout tab in the Object pane, provided that this object supports the attribute.

Since the compatibility mode cannot be set actively, the user receives an error message on Apply after switching to border_compat.

To restore the default border_compat it is recommended to uncheck the box next to Borderstyle. Thus the standard is applied again (unless one of the parents has set a different value, then this is inherited).

37.3 New Objects datetime and listview

37.3.1 datetime

The datetime object (class name dmw_datetime) provides a simple and intuitive way to enter dates and times. It can display date or time values or both in different formats. Besides keyboard input, the user can change the values, for example by selecting a date from a calendar (upper datetime object in “Figure 19-23”) or using spin buttons (lower datetime object in “Figure 19-23”). In addition, the user can be enabled to set the value to indefinite using a checkbox (right part of “Figure 19-23”).

“Figure 19-24” shows a datetime object with the calendar unfolded. The appearance of the calendar can be adjusted by several attributes. For example, in the right part of “Figure 19-24”, the numbers of the calendar weeks and the current date are displayed in the calendar.

The presentation of the date and time values can be controlled using a format string. You can use predefined system formats or define own display formats using the corresponding formatting characters. In both cases, the language and region settings of the system are taken into account (for example, for the month names). “Figure 19-25” shows datetime objects with formats that contain extra, non-editable text in addition to parts of the date or time.

Availability

• Microsoft Windows only.
• Can only be used with the USW option of the ISA Dialog Manager.
• The idmwidgets.dll must be in the USW class path (default: <IDM installation directory>\uswclasses).

37.3.1.1 Definition

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

37.3.1.2 Description of Events

37.3.1.2.1 deselect

The deselect event occurs when the datetime has lost the focus. This is an indication that the user has completed entering or selecting the date or time. However, it should be noted that this event is not only triggered by direct user actions, but may also occur as a side effect of other actions:

• The user sets the focus with the mouse or keyboard to another object.
• The user activates another application or another application pushes itself into the foreground and captures the focus.

Note

Opening a menu or pop-up does not necessarily move the focus. Therefore, it cannot be predicted whether a deselect event will occur for these actions. For example, a deselect event may not be triggered until the select event rule of a menuitem is executed, if it is triggered at all.

37.3.1.2.2 select

The select event will occur each time the content of the .value attribute changes. The event can be triggered by various actions of the user:

• The user edits the value in the input field of the datetime.
• The user navigates in the calendar to reach a specific date.
• The user selects a value with mouse or keyboard.
• The user scrolls the spinbox of the datetime.

This means that multiple select events will typically occur before the user has entered, set or selected the final value. Therefore, the event rule for the select event should not perform any extensive actions.

The .real_modified attribute can be used to check whether the value of the datetime has actually changed due to the user actions, compared to the value of the datetime when it received the focus.

The select event may also occur if .minvalue or .maxvalue are violated. This depends on the system object, but here too a content change of .value must be present.

37.3.1.3 Attribute Overview

37.3.1.4 Description of Attributes

37.3.1.4.1 .allowundefined

This attribute determines whether the user can set the value of the object to indefinite.

If the attribute has the value true, a checkbox is displayed in the datetime. Deactivating the checkbox sets the value to indefinite. The attribute .value then has the value "".

With .allowundefined = true, invalid values of .value cause the checkbox to be activated.

Value range

Note

Changing .allowundefined in the visible state may lead to a reset of the object.

37.3.1.4.2 .calendaralignment

This attribute defines the position of the fold-out calendar relative to the object.

Value range

37.3.1.4.3 .format

This attribute defines the display format of the datetime object.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

Value range

System formats

The system formats depend on the language and region settings of the operating system. They completely determine the display format and cannot be combined with each other or with format strings. For example, no caption can be added to a system format.

Format strings

37.3.1.4.4 .maxvalue

This attribute determines the maximum value.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

Value range

The attribute defines the largest value that can be entered or selected by the user. An existing content of .value is usually not corrected to comply with .maxvalue. It is also not defined whether the displayed value is corrected when the datetime is made visible.

37.3.1.4.5 .minvalue

This attribute determines the minimum value.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

Value range

The attribute defines the smallest value that can be entered or selected by the user. An existing content of .value is usually not corrected to comply with .minvalue. It is also not defined whether the displayed value is corrected when the datetime is made visible.

37.3.1.4.6 .real_modfied

Indicates whether the .value attribute has changed since the focus was obtained.

Setting the .value attribute resets .real_modified to false.

On an invisible datetime object, .real_modified is always false.

Value range

37.3.1.4.7 .shortdaynames

This attribute determines whether short weekday names are displayed in the fold-out calendar.

The attribute is only effective as of Windows Vista.

Value range

Note

In German there is no difference between short and normal weekday names.

37.3.1.4.8 .style

The attribute determines the appearance and the method of operation at the datetime object.

Value range

Note

Changing the attribute in the visible state leads to a reset of the object and should be avoided.

37.3.1.4.9 .today

The attribute determines whether the current date is displayed at the bottom of the fold-out calendar.

The attribute is only effective as of Windows Vista.

Value range

37.3.1.4.10 .todaymarker

This attribute controls whether the current date is marked in the fold-out calendar.

The attribute is only effective as of Windows Vista.

Value range

37.3.1.4.11 .trailingdates

This attribute controls whether the fold-out calendar displays the days adjacent to the current month.

The attribute is only effective as of Windows Vista.

Value range

37.3.1.4.12 .value

This attribute defines the value of the datetime object.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

Value range

""

The current date or time is displayed.

<value_string>

Sets the contained date or time value.

Syntax and Evaluation of the Value String

The value is evaluated according to the “Definition of Time Spans” for the timer object, whereby the following absolute time definition is permitted:

<Value>     ::= {<Datevalue>}{ <TimeValue>}
<DateValue> ::= {<day>}.{<month>}.{<year>}
<TimeValue> ::= {<hour>}:{<minute>}{:{<second>}}

Deviating from the definition of time spans for the timer, it is permitted to specify only a date.

The datetime uses the Gregorian calendar. The value range extends from 01/01/1601 00:00:00 to 12/31/9999 23:59:59. Two-digit years are mapped to the time range 1970 to 2069.

When the user selects, sets or enters a value in the datetime, .value contains this value in full format dd.MM.yyyyy HH:mm:ss (see attribute .format). When a change occurs, a select event is triggered.

Parts not specified are completed in the display by the corresponding values of the current system date or the current system time. For example, for a missing year, the current year is inserted.

If the value string is syntactically incorrect, the current date or time is displayed (as with "").

Examples

The current date is 06/25/2014 and the current time is 11:53:07.

If the value string is syntactically correct but does not represent a valid date or time (for example 29.2.2013 or 33.33.33), then it is undefined what is shown in the datetime. If the system returns an error, the current date or time is displayed. Otherwise, the system displays what it has made of the value string.

If .value ="" or is erroneous and the .allowundefined attribute has the value true, then the value is shown as indefinite (checkbox unchecked).

The additions and corrections made by the object for displaying the value do not change the attribute value. That is, .value keeps its set content until the user selects, sets or enters a value in the datetime.

The current date and time are calculated on visualization. In addition, they are calculated when in the visible state .value is set to a different value that the object adds or corrects for display (for example ""). Again, the attribute value is usually not adjusted to the shown value. Repeated setting of the same value (also of "") therefore does not represent a change in value, so in this case there is no update of the displayed value either.

37.3.1.4.13 .weeknumbers

This attribute controls whether the calendar week numbers are displayed in the fold-out calendar.

The attribute is only effective as of Windows Vista.

Value range

Note

The first calendar week of a year is the first week with at least 4 days in that year.

37.3.2 listview

The listview (class name dmw_listview) is an advanced list object that supports various display types. The object is known in principle by the Windows Explorer, where it is used to display the directories of the file system.

The following figures show the different display types of the listview object:

1. The icon view displays large icons along with a caption. The first content column is used as the caption.

   

   Figure 19-26: Icon view with large icons of the listview

2. The small icon view is very similar to the icon view, the only difference is that small icons are used.

   

   Figure 19-27: Icon view with small icons of the listview

3. The list view also uses the small icons and the caption, but the items are arranged in a list from top to bottom. If necessary, additional columns are added.

   

   Figure 19-28: List view of the listview

4. The detail view displays all available information in a table. Now the listview object resembles a table.

   

   Figure 19-29: Detail view of the listview

5. The tile view is like the list view, but shows large icons. The caption appears next to them.

   

   Figure 19-30: Tile view of the listview

Availability

• Microsoft Windows only.
• Can only be used with the USW option of the ISA Dialog Manager.
• The idmwidgets.dll must be in the USW class path (default: <IDM installation directory>\uswclasses).

37.3.2.1 Definition

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

37.3.2.2 Description of Events

37.3.2.2.1 activate

The activate event is triggered when a list item is selected (.selected[I] := true).

The .index attribute of thisevent contains the index of the item that was selected. The data type of thisevent.index is index and thus consistent with the select event. The column value of thisevent.index is always 1, since only this column has a selection status.

37.3.2.2.2 dbselect

The dbselect event occurs when a double-click is carried out in the listview.

The .index attribute of thisevent contains the index of the item that was clicked. The data type of thisevent.index is index and thus consistent with the select event. If no item was hit, thisevent.index is not set.

The header in the detail view (column headings) does not have a double-click event.

37.3.2.2.3 deactivate

The deactivate event is triggered when a list item loses its selection (.selected[I] := false).

The .index attribute of thisevent contains the index of the item that has lost its selection. The data type of thisevent.index is index and thus consistent with the select event. The column value of thisevent.index is always 1, since only this column has a selection status.

37.3.2.2.4 resize

The resize event occurs when a column width has been changed in the detail view.

The event does not arise for columns whose width has been set to 0 and is calculated by the listview.

37.3.2.2.5 select

The select event occurs when a click is carried out in the listview.

The .index attribute of thisevent contains the index of the item that was clicked. The data type of thisevent.index is index and thus consistent with the activate event. The column value can be different from 1 only in the detail view.

If no item was hit, thisevent.index is not set. When the header (column headings) of the detail view is clicked, the row value of thisevent.index is 0.

37.3.2.3 Attribute Overview

37.3.2.4 Description of Attributes

37.3.2.4.1 .colcount

The attribute defines the number of columns in the detail view.

Value range

The value of .colcount can be implicitly increased by adding one new column to .content at a time.

Column 1 is shown in all views.

For invalid values, the default value 1 is used. The attribute value is not changed, however.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.2 .coltitle[integer]

This attribute is used to set the column headings in the detail view.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

The value range of the index is 0 … .colcountt, where the value with index 0 is used as default value for not set values in the range 1 … .colcount.

If no heading is defined for a column and no default value .coltitle[0] is defined either, then this column is displayed without a column heading.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.3 .colwidth[integer]

This attribute defines the column widths in the detail view.

The value range of the index is 0 … .colcountt, where the value with index 0 is used as default value for not set values in the range 1 … .colcount.

Value range

For invalid values, the default value 0 is used. However, the attribute value is not changed.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.4 .content[index]

The attribute defines the list items of the listview.

For write access (set), values of the data type string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type string.

The value range of the index is [0,1] … [.rowcount,.colcount], where the value with index [0,C] is used as default value for not set values in the range [1,C] … [.rowcount,C].

Column 1 is the caption of the list item that will be shown in all views. The other columns are only displayed in the detail view.

If no content is defined for .content[R,C] and no default value .content[0,C] is set, then nothing is displayed, but the item still exists.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.5 .mincolwidth[integer]

The attribute specifies the minimum column widths in the detail view of the listview object. Users cannot interactively make the columns narrower than defined in this attribute.

The value range of the index is 0 … .colcountt, where the value with index 0 is used as default value for not set values in the range 1 … .colcount.

Value range

For invalid values, the default value 0 is used. However, the attribute value is not changed.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.6 .picheight

This attribute defines the height of the large icons.

Value range

The large icons will be shown in the icon view (.style = "icon", .style = "picture") and in the tile view (.style = "tile").

For invalid values, the default value 0 is used. However, the attribute value is not changed.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.7 .picture[integer]

The attribute defines the large icon for each list item.

The value range of the index is 0 … .rowcountt, where the value with index 0 is used as default value for not set values in the range 1 … .rowcount.

Value range

The large icon will be shown in the icon view (.style = "icon", .style = "picture") and in the tile view (.style = "tile").

Large and small icons belong together and should represent the same information. Both icons can only be referenced together. Therefore, different combinations should be avoided, as each combination will consume additional memory.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.8 .picwidth

This attribute defines the width of the large icons.

Value range

The large icons will be shown in the icon view (.style = "icon", .style = "picture") and in the tile view (.style = "tile").

For invalid values, the default value 0 is used. However, the attribute value is not changed.

If .picheight = 0 then .picwidth also determines the height of the large icons.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.9 .rowcount

This attribute defines the number of list items.

The value range of .rowcount is 0 … n (n > 0).

The value of .rowcount can be implicitly increased by adding one new row to .content at a time.

For invalid values, the default value 0 is used. The attribute value is not changed, however.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.10 .selected[integer]

This attribute determines for each list item of the listview object whether it is selected.

The value range of the index is 0 … .rowcountt, where the value with index 0 is used as default value for not set values in the range 1 … .rowcount.

Value range

The attribute will be modified through user interaction (activate and deactivate events).

Note

The appearance of selected items depends on the system. This applies in particular to the visibility of the selection when the listview does not have the focus.

37.3.2.4.11 .smallpicheight

This attribute defines the height of the small icons.

0

The width .smallpicwidth is used. If this is also 0, the size of the icons is determined by the system.

> 0

Height of the small icons.

The small icons will be shown in the small icon view (.style = "smallicon", .style = "smallpicture"), in the list view (.style = "list") and in the detail view (.style = "detail", .style = "report").

For invalid values, the default value 0 is used. However, the attribute value is not changed.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.12 .smallpicture[integer]

The attribute defines the small icon for each list item.

The value range of the index is 0 … .rowcountt, where the value with index 0 is used as default value for not set values in the range 1 … .rowcount.

Value range

The small icons will be shown in the small icon view (.style = "smallicon", .style = "smallpicture"), in the list view (.style = "list") and in the detail view (.style = "detail", .style = "report").

Small and large icons belong together and should represent the same information. Both icons can only be referenced together. Therefore, different combinations should be avoided, as each combination will consume additional memory.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.13 .smallpicwidth

This attribute defines the width of the small icons.

Value range

The small icons will be shown in the small icon view (.style = "smallicon", .style = "smallpicture"), in the list view (.style = "list") and in the detail view (.style = "detail", .style = "report").

For invalid values, the default value 0 is used. However, the attribute value is not changed.

If .smallpicheight = 0 then .smallpicwidth also determines the height of the small icons.

Changing the attribute in the visible state may cause the object to flicker.

37.3.2.4.14 .style

This attribute determines the presentation mode of the listview.

For write access (set), values of the data type integer, string and text resources can be specified. text resources are automatically converted to string.

Read access (get) always returns a value of the data type integer.

Value range

For invalid values, the default value 0 is used. However, the attribute value is not changed.

37.4 Enhancement of the USW Interface

37.4.1 UC_InqName

The data type UC_InqName has been extended:

typedef enum {
  UC_I_undef = 0,
  ...
  UC_I_notify,
  UC_I_replace  // since IDM version A.06.01.a
} UC_InqName;

37.4.2 UC_API

The structure UC_API has been extended:

typedef struct {
  DM_UInt1 version;
  ...
  UC_ControlFunc          control;          // since IDM version A.05.02.g
  UC_GetToolkitDataExFunc getToolkitDataEx  // since IDM version A.06.01.a
} UC_API;

37.4.3 UC_InqArg

The structure UC_InqArg has been extended:

typedef struct {
  DM_InqName name;
  union {
    ...
    UC_Notify  notify;
    UC_Replace replace;  // since IDM version A.06.01.a
  } arg;
} UC_InqArg;

37.4.4 UC_Replace

Notification that the definition of a used IDM resource has changed. It is up to the WSI when and for which resources UC_Inquire is called with UC_I_Replace.

typedef struct {
  DM_ID dmid;
} UC_Replace;

The element dmid indicates the resource that has been changed.

37.4.5 getToolkitDataEx

Function for retrieving toolkit data (e.g. resources).

typedef FPTR (DML_default DM_EXPORT *UC_GetToolkitDataExFunc)
  __((DM_ID        dmid,
      DM_Attribute attr,
      FPTR         data,
      DM_Options   options));

Parameters

DM_ID dmid

Identifier of the object.

DM_Attribute attr

IDM attribute to be queried.

FPTR data

Pointer to additional data, if not used this must be NULL.

DM_Options options

IDM option, currently none available.

Return value

Depending on the kind of value being queried, this function returns the corresponding values converted to FPTR (see C interface function DM_GetToolkitDataEx).

37.4.6 UC_Inquire

name == UC_I_Replace

arg.replace.dmid

37.5 Data Types for Collections

37.5.1 Enhancement of the Data Types

The following new collection data types are now allowed in the IDM. Please note that only scalar types are permitted for the addressing as well as for the addressed single values. Therefore a structure of multidimensional lists is not possible.

Table 19-13: Data types for collections

Similar to predefined vector and matrix attributes like .content[], .userdata[] etc. an expansion of collections directly after their last element is possible and allowed.

However, it is not possible to use these collection data types for user-defined attributes. User-defined and predefined attributes do not have a unique assignment (attributes exist on an object in both a scalar and a field variant) and allow for unindexed access to the default value.

37.5.2 Extension of the Expressions

List and Hashes

Collections with the data types hash, list, matrix, refvec or vector can be defined using the following syntax within the rule code. A definition in the static part of a dialog or module is not possible with expressions, only constant values may be used. Without explicitly specifying a list data type, a list of the data type list is created. When the reference operator => is used, a hash (associative array) is automatically created, with the expression before => defining the key or index, and the second defining the value.

Attention

For compatibility reasons, index expression takes priority. Thus, to build a two-element list of two integer values, the list data type should be prepended.

Syntax

<list> = [ <data type> ] '[' [ <expression> { ',' <expression> } ] ']'
<hash list> = [ <data type> ] '[' [ <expression> '=>' <expression>
    { ',' <expression> '=>' <expression> } ] ']'

Examples

[1, .xleft, 17+4, Wi.Pb]
["CBS" => 2, itoa(7) => 7]
matrix[ [1,1]=>"first name", [1,2]=>"last name", [1,3]=>"telephone no." ]

37.5.3 List Size and Default Values

In principle, each collection data type has a current size, which results from the values set. There are no value gaps in this currently valid indexing range, only unset values (see also the descriptions of itemcount(), countof()).

In order to achieve consistency with the previous static local variables, the data types hash, list and matrix allow for a default value.

This is displayed at unset value positions within the currently valid indexing range up to the current size. For hash data types, if the default value is set, it is returned for all possible indexings.

The sequence of access to the default values for an unset value at the position <row>,<col> in a matrix M is M[<row>,<col>] → M[0,<col>] → M[<row>,0] → M[0,0].

The access sequence to the default value for an unset value at <index> in a list L is L[<Index>] → L[0].

37.5.4 Access and Assignment of Collections

The indexed values (items) of a collection are accessed via the [] operation, just as known for local variables or predefined and user-defined attributes.

Without the [] operation, the entire value is fetched or set.

Attention

It should be noted that accessing a user-defined or predefined attribute without the [] index fetches or sets the default value or scalar attribute. To fetch or set all values of an attribute, the functions getvector() or setvector() should be used.

Examples

variable list Primes := [2,3,5,7,11,13];
variable vector[integer] Numbers;
variable hash Months := [1=>"Jan", 2=>"Feb", 3=>"Mar"];

print Primes[1];
Months[4] := "Apr";
Numbers := Primes;
Primes[0] := -1;
Primes := [17, 19, 23];

Output of collections via print or sprintf() is also possible. However, no default values are output. For the data types hash and matrix the output is including the index.

Specific Features of refvec

It should also be noted that the refvec data type is handled in a special way because it ensures uniqueness of the values and does not store null values.

With an indexed assignment of an already existing object ID, the object ID at this position is replaced and afterward uniqueness is ensured, which may also result in a shift of the already existing object ID to another position and a reduction of the refvec list.

In case of an indexed assignment of a null, the object ID is deleted from the refvec list and the following object IDs advance, which in turn results in a reduction of the refvec list.

37.5.5 Automatic Conversion

In assignments or parameter calls, collections are automatically converted to the required list type. All values without index are copied in their natural order, including the default values if possible, e.g. [0] for a list variable will be passed on if the target type also has a default value.

Exception

When assigning a hash with index data type to a matrix, the index will be taken over. With the reverse assignment of a matrix to a hash, the index will also be transferred. To prevent this, the built-in function values() should be used.

37.5.6 Performance

In general, it should be considered that the use of collections (entire values) within expressions initially requires the values to be copied, but then in reading operations only references of this list are used, i.e. without further copying. This ensures the necessary performance when working with collections. Passing on to application functions or manipulation by built-in functions, however, requires another copy action, possibly with a code page conversion of string values.

For this reason, it should be kept in mind that complex expressions that process collections may well temporarily lead to large amounts of data. Coding and splitting of expressions should take into account the maximum list sizes.

37.5.7 Local and Global Variable

The new collection data types are available for local and global variables now. It is also possible to initialize a global collection with constant values.

Until now, local, static variables could also be an array or an associative array, which only could be initialized in a very limited way. Collection data types are now allowed for both local and local static variables. The initialization expression is no longer restricted.

Attention Behavior Change

The existing notation of arrays and associative arrays for static local variables is still allowed and mapped to the data types list or hash. The static initialization via .<identifier>[<index>] := <value>; after the variable part is no longer possible to ensure consistency with other local variables! The initial value sets the entire value of the variable, not just the default value!

Example

dialog D

variable hash Prices := [ "iMac" => 1300, "Samsung Tab" => 300 ];
variable vector[string] Weekdays := ["Mon","Tue","Wed"];

on dialog start
{
  variable string Stations[integer] := [1=>"ABC", 2=>"CBS"];
  variable hash Stations2 := [3=>"NBC", 4=>"HBO"];
  static variable list AllStations := join(Stations,Stations2);
  /* No longer allowed:
   * variable string Stations[integer] := "UNKNOWN";
   * .Stations[1] := "ABC";
   * or
   * static variable integer AssArray[string] := -1;
   * Instead possible:
   * static variable integer AssArray[string] := [nothing=>-1];
   */
  exit();
}

37.5.8 Relational Operators

For collections, only the relational operators = and <> are allowed.

Equality prevails under the following conditions:

1. The data type must be the same.
2. All contained values or index/value pairs must be equal, including the default values.
3. The number of values contained and their positions must be the same.

Comparison between a string and a text ID is done on a string basis.

When using relational operators, particular attention should be paid to the data type.

Example

dialog D
window Wi {
  listbox Lb {
    .content[1] "Sat";
    .content[2] "Sun";
  }
}
on dialog start {
  variable list WeekendDays := ["Sat", "Sun"];
  variable hash DayNumber := ["Sat"=>6,"Sun"=>7];
  variable list Days;

  print WeekendDays = getvector(Lb, .content);
  print vector["Sat","Sun"] = getvector(Lb, .content);
  print values(WeekendDays) = values(getvector(Lb, .content));
  print WeekendDays = keys(DayNumber);
  Days := WeekendDays;
  WeekendDays[0] := "??";
  print Days=WeekendDays;
  exit();
}

Output

false => Different data types (list<>vector)
true
true
true
false => WeekendDays has a default value, but Days does not!

37.5.9 Uninitialized variables

As before, the IDM behaves differently when accessing uninitialized values. If an uninitialized local or static variable is accessed, nothing is returned. When accessing an uninitialized global variable ( equivalent to a variable object) or a user-defined attribute, access is denied with a cannot get value error.

37.5.10 New and Modified Built-in Functions

37.5.10.1 itemcount()

This function returns the number of indexed values in a collection. The default value(s) are excluded from that number. Together with indexat() and valueat() it is thus easy to loop through any collection.

Typically, countof() and itemcount() return the same result for values of the data types refvec, vector, and list. However, itemcount() offers the more generic use, whereas countof() is better suited for structured, type-adapted use.

Definition

integer itemcount
(
  anyvalue Value input
)

Parameters

anyvalue Value input

This parameter specifies the value for which the number shall be determined.

Return value

Example

dialog D

on dialog start
{
  variable matrix Matrix := [
    [0,0] => "-?-",
    [1,1] => "germany",
    [1,2] => "berlin",
    [2,1] => "france"
    /* [2,2] => inherited from default [0,0] */ ];
  variable integer I;
  variable anyvalue Idx;

  /* print the Matrix values [1,1] [1,2] ... [2,2] */
  for I:=1 to itemcount(Matrix) do
    Idx := indexat(Matrix, I);
    print sprintf("%s : %s", Idx, Matrix[Idx]);
  endfor
  exit();
}

Output

"[1,1] : germany"
"[1,2] : berlin"
"[2,1] : france"
"[2,2] : -?-"

See also

indexat(), valueat(), countof(), .itemcount[<A>], :index(), DM_ValueCount()

37.5.10.2 countof()

This function returns the size of a collection. This is usually the highest index value.

Typically, countof() and itemcount() return the same result for values of the data types refvec, vector, and list. However, itemcount() offers the more generic use, whereas countof() is better suited for structured, type-adapted use.

anyvalue countof
(
  anyvalue Value input
)

Parameters

anyvalue Value input

This parameter specifies the value for which the indexing type or the highest index value shall be determined.

Return value

Example

dialog D

on dialog start
{
  variable matrix Matrix := [
    [0,0] => "-?-",
    [1,1] => "germany",
    [1,2] => "berlin",
    [2,1] => "france"
    /* [2,2] => inherited from default [0,0] */ ];
  variable integer Row, Col;
  variable anyvalue Count, Idx;

  /* print the Matrix values [0,0] [0,1] ... [2,2] */
  Count := countof(Matrix);
  for Row:=0 to first(Count) do
    for Col:=0 to second(Count) do
      Idx := [Row,Col];
      print sprintf("%s : %s", Idx, Matrix[Idx]);
    endfor
  endfor
  exit();
}

See also

valueat(), itemcount(), .count[<A>], :index(), DM_ValueCount()

37.5.10.3 indexat()

This function returns the index of a collection at a specific position. The allowed positions are 1 … itemcount() and thus allow a loop through all indexed values.

For values of type list, refvec and vector, the position is identical to the actual index. For a hash value, there is no defined order of the indexes returned. For matrix values, the increasing positions are mapped in a sequence where all ( column) values of a row are arranged in ascending order.

The function returns an error (fail) if the position is outside the allowed range or if the Value parameter is not a collection.

Definition

anyvalue indexat
(
  anyvalue Value input,
  integer  Pos   input
)

Parameters

anyvalue Value input

This parameter specifies the value list from which the index shall be queried.

integer Pos input

Position for which the index value shall be determined.

Return value

Index value at the position passed as parameter.

Example

dialog D

on dialog start
{
  variable matrix Matrix := [
    [0,0] => "-?-",
    [1,1] => "germany",
    [1,2] => "berlin",
    [2,1] => "france" ];
  variable integer Pos;

  /* print the Matrix elements [1,1] [1,2] ... [2,2] */
  for Pos:=1 to itemcount(Matrix) do
    print sprintf("%s : %s", indexat(Matrix, Pos), valueat(Matrix, Pos));
  endfor
  exit();
}

See also

itemcount(), valueat(), keys(), :index(), DM_ValueIndex()

37.5.10.4 valueat()

This function returns the indexed value in a collection at the specified position. The allowed positions are 1 … itemcount() and thus allow looping through all indexed values without knowing the actual index.

The function returns an error (fail) if the position is outside the allowed range or if the Value parameter is not a collection.

Definition

anyvalue valueat
(
  anyvalue Value input,
  integer  Pos   input
)

Parameters

anyvalue Value input

This parameter specifies the value list from which the indexed value shall be determined.

integer Pos input

Position for which the indexed value shall be determined.

Return value

Value found in the collection at the position passed as a parameter.

Example

dialog D

on dialog start
{
  variable matrix Matrix := [
    [0,0] => "-?-",
    [1,1] => "germany",
    [1,2] => "berlin",
    [2,1] => "france" ];
  variable integer Pos;

  /* print the Matrix elements [1,1] [1,2] ... [2,2] */
  for Pos:=1 to itemcount(Matrix) do
    print sprintf("%s : %s", indexat(Matrix, Pos), valueat(Matrix, Pos));
  endfor
  exit();
}

See also

indexat(), values(), :index(), DM_ValueGet(), DM_ValueIndex()

37.5.10.5 keys()

This function returns a list of all index values in a collection. The indexes of the default values are not included in the list. If a scalar is specified as parameter, an empty list is returned.

Definition

list keys
(
  anyvalue Value input
)

Parameters

anyvalue Value input

This parameter specifies the value on which the function is applied.

Return value

A list containing all indexes of a collection.

Example

dialog D

on dialog start
{
  variable matrix Matrix := [
    [0,0] => "-?-",
    [1,1] => "germany",
    [1,2] => "berlin",
    [2,1] => "france" ];
  variable anyvalue Idx;

  /* print the Matrix elements [1,1] [1,2] ... [2,2] */
  foreach Idx in keys(Matrix) do
    print sprintf("%s : %s", Idx, Matrix[Idx]);
  endfor
  exit();
}

See also

indexat(), itemcount(), countof(), values(), foreach

37.5.10.6 values()

This function returns a list of all values in a collection. Default values are not included. Applied to a scalar value, this is returned as a list.

Definition

anyvalue values
(
  anyvalue Value input
)

Parameters

anyvalue Value input

This parameter specifies the value on which the function is applied.

Return value

A list containing all values of a collection without the default values.

For a scalar parameter, a list containing only this parameter is returned.

Example

dialog D

on dialog start
{
  variable hash DomainHash := [
    ".de" => "germany",
    ".us" => "usa",
    ".fr" => "france",
    ".uk" => "united kingdom" ];
  variable string Country;

  /* print all country names from the DomainHash */
  foreach Country in values(DomainHash) do
    print Country;
  endfor
  exit();
}

Output

"germany"
"france"
"united kingdom"
"usa"

See also

valueat(), :index(), DM_ValueCount()

37.5.10.7 join()

This function creates a new value list from the specified parameters. The type of the value list is determined by the first call parameter. If this is a collection or a collection data type (list, vector, refvec, hash, matrix), the resulting value list has the same type. A data type as the first parameter value never is included in the result list. If the specified parameters are collections, only the values (without default values) are used. Scalar values are added to the resulting value list.

The order of the values in the resulting value list will correspond to the order of the parameters and for collections to their natural order (see indexat()).

Indexing is usually done by incrementing the last index value or the number of values (see countof() and itemcount()). That is, the values in the result list usually get an indexing by 1, 2, 3, … or [1,1], [1,2], [1,3], ….

If the result list type and the parameter value are both a hash, the index of the hash values is adopted. Added scalar parameters will get the increased itemcount() value of the result list as index.

When using refvec as the result list type, it should be noted that an error (fail) occurs if a value is not of the data type object.

Definition

anyvalue join
(
      anyvalue Value input
  { , anyvalue Par2  input }
  ...
  { , anyvalue Par16 input }
)

Parameters

anyvalue Value input

This parameter specifies the value on which the function is applied. The parameter is also used to determine the type for the result list.

anyvalue Par2 input
…
anyvalue Par16 input

Additional optional parameters on which the function is applied.

Return value

A collection containing all values from the passed parameters. If the first parameter is a collection data type or a collection, the returned collection has this data type. A data type as the first parameter is not included in the returned collection.

Modification as of IDM Version A.06.01.b When Passing the Data Type string as First Parameter

If the data type string is passed as first argument to the function join(), the subsequent arguments are converted to the data type string and then concatenated. If the subsequent arguments are collections, first their values are concatenated to a string in the natural order of the index.

If the first argument is a data type that is neither string nor a collection data type, join() returns an error.

Example

dialog D

on dialog start
{
  variable hash DomainHash := [
    ".de" =>" germany",
    ".us" => "usa",
    ".fr" => "france",
    ".uk" => "united kingdom" ];
  variable list Countries;
  variable hash Domains;

  /* join the values to a list */
  Countries := join(list, DomainHash, "norway", "spain");
  /* join the values and keys into a hash */
  Domains := join(DomainHash, [".us" => "united states of america"]);

  print Countries;
  print Domains;

  exit();
}

Output

["norway","spain","germany","usa","france","united kingdom"]
[".de"=>"germany",".us"=>"united states of america",".fr"=>"france",
".uk"=>"united kingdom"]

See also

keys(), DM_ValueChange()

37.5.10.8 find()

This function searches for a specified value in a list of values and returns the first found index where this search value can be found.

The search never includes the default element (e.g. index [0] or [0,0]).

By specifying a start and end index, the search can be restricted. The valid values are:

• No value specified.
• integer value in the range 1 … field size (but must be > 0) for collections with data types vector, refvec, list or hash.
• index value in the range from [1,1] to [rowcount,colcount] where rowcount and colcount must also be > 0.
• Valid index of a hash.

When searching for strings it is also possible to search case-insensitive or for the first occurrence as prefix.

Since the indices of hashes are not subject to any order, only an integer value in the range 1 … itemcount() should be specified as index, which indicates the position of the start or end element.

For two-dimensional arrays (similar to the :find() method for .content[] at the tablefield), specifying an index range [Sy,Sx] to [Ey,Ex] restricts the search scope to the range [min(Sy,Ey),min(Sx,Ex)] … [max(Sy,Ey),max(Sx,Ex)]. Thus the restriction to rows and columns is easily possible.

Definition

anyvalue find
(
      anyvalue ListValue  input,
      anyvalue Value      input
  { , anyvalue StartIndex input
  { , anyvalue EndIndex   input } }
  { , boolean  CaseSensitive := false       input }
  { , enum     MatchType     := match_exact input }
)

Parameters

anyvalue ListValue input

In this parameter, a list value is expected in which to search.

anyvalue Value input

The value specified in this parameter is searched for. Only values are compared whose types are equal or can be converted (a text is converted to a string for this purpose).

anyvalue StartIndex input

This optional parameter specifies the start index from which to search for the value in the collection. If no value is specified here, 1 is assumed for one-dimensional and [1,1] for two-dimensional collections.

anyvalue EndIndex input

This optional parameter specifies the end index up to which the collection shall be searched for the value. This argument is only permitted if a start index has also been specified.

boolean CaseSensitive := false input

This optional parameter only applies to string values and defines whether the search should be case-sensitive or not. The default value is false.

enum MatchType := match_exact input

This optional parameter only applies to string values and defines how to search for strings. Valid values are:

MatchType	Meaning
match_begin	Finds the first string in the collection that starts with the search string.
match_first	Finds the string in the collection whose beginning has the largest match with the search string. If the collection contains a string that matches the search string exactly, its index will be returned.
match_exact (default value)	Finds the first string in the collection that exactly matches the string that is searched for.
match_substr	Finds the first string in the collection that contains the string that is searched for.

Return value

Fault behavior

The function call fails if the ListValue parameter is not a collection, the index ranges are outside the valid range, or another invalid parameter value exists.

Remark

If the StartIndex and EndIndex parameters have a data type other than integer when searching in hashes, the position of the start and end elements is calculated from the specified indexes. In this respect, searching in hashes with the find() function differs from searching in associative arrays with the :find() method.

Example

dialog D

on dialog start
{
  variable hash Hash := [
    "030"  => "berlin",
    "0711" => "stuttgart",
    "089"  => "munich" ];
  variable matrix Matrix := [
    [1,1] => "area code", [1,2] => "call number",
    [2,1] => 089,         [2,2] => 713400,
    [3,1] => 0711,        [3,2] => 805439 ];
  variable anyvalue Idx;

  Idx := find(Hash, "stuttgart");
  if Idx <> nothing then
    print "Found: stuttgart => " + Idx;
    Idx := find(Matrix, atoi(Idx), [2,1], [3,1]);
    if Idx <> [0,0] then
      print "Call: " + Matrix[first(Idx),2];
    endif
  endif
  exit();
}

See also

sort(), :find()

37.5.10.9 sort()

This function returns a sorted copy of a given list value. Only the values are sorted, not the indexes. Therefore, a sorting of values is also possible for associative arrays (hash data type).

Sorting is carried out grouped by the data types of the value elements, ascending by the ordinal of the data types and values. When sorting texts or strings, comparison is always done using the string data type, which is more suitable for sorting.

Sorting can be controlled like this:

• With the Reverse parameter the sort sequence can be inverted.
• Through the SortType parameter the sort sequence of strings and texts can be influenced.

Definition

anyvalue sort
(
      anyvalue ListValue input
  { , boolean  Reverse  := false       input }
  { , enum     SortType := sort_binary input }
)

Parameters

anyvalue ListValue input

This parameter specifies the list value to be sorted.

boolean Reverse := false input

If this optional parameter is set to true, sorting is carried out in descending order. The default value is false, which corresponds to an ascending sort.

enum SortType := sort_binary input

This optional parameter only applies to item values that have the data type string or are temporarily converted to a string for sorting. Permitted values are:

SortType	Meaning
sort_binary (default value)	Sorting based on the Unicode character code.
sort_linguistic	Sorting based on the language and region settings (locale) of the system. Depending on the system settings and the set code page, upper and lower case as well as umlauts are taken into account. For Unix or Linux we recommend using the UTF8 locale. Since this sort requires code page conversions, it is slower than sort_binary. See also Documentation of locale, LC_CTYPE, LC_COLLATE, strcoll for your operating system.

Return value

Sorted collection of the same data type as the passed collection.

Fault behavior

The function call fails if the ListValue parameter is not a collection or another parameter has an invalid value.

Example

// UTF8
dialog D

on dialog start
{
  variable list List := [ "Äcker", "Bande", "Bäcker", "binden",
                          "Bund", "Aachen", "an" ];
  variable string S;

  foreach S in sort(List, sort_linguistic) do
    print S;
  endfor
  exit();
}

/* returns: Aachen Äcker an Bäcker Bande binden Bund */

See also

find(), keys(), values()

37.5.10.10 min()

This function returns the smallest integer value found in all its call parameters.

The call parameters may be scalar integer values or collections (vector, list, matrix, hash). For the latter, the indexed elements (without the default values) are used to determine the minimum value.

Definition

integer min
(
      anyvalue Par1  input
  { , anyvalue Par2  input }
  ...
  { , anyvalue Par16 input }
)

Parameters

anyvalue Par1 input

anyvalue Par2 input
…
anyvalue Par16 input

These parameters specify the values on which the function is applied.

Return value

The smallest integer value to be found will be returned.

Fault behavior

The function call fails if the arguments do not contain a scalar integer value or if arguments or their elements contain a value that is not an integer value.

Example

dialog D

on dialog start
{
  variable list List := [17, 3, 23, 5];

  print min(List, 24, 4);  /* print 3 */
  exit();
}

See also

max()

37.5.10.11 max()

This function returns the largest integer value found in all its call parameters.

The call parameters may be scalar integer values or collections (vector, list, matrix, hash). For the latter, the indexed elements (without the default values) are used to determine the maximum value.

Definition

integer max
(
      anyvalue Par1  input
  { , anyvalue Par2  input }
  ...
  { , anyvalue Par16 input }
)

Parameters

anyvalue Par1 input

anyvalue Par2 input
…
anyvalue Par16 input

These parameters specify the values on which the function is applied.

Return value

The largest integer value to be found will be returned.

Fault behavior

The function call fails if the arguments do not contain a scalar integer value or if arguments or their elements contain a value that is not an integer value.

Example

dialog D

on dialog start
{
  variable list List := [17, 3, 23, 5];

  print max(List, 24, 4);  /* print 24 */
  exit();
}

See also

min()

37.5.10.12 getvector()

This function may be used to obtain the entire value of vector or matrix attributes (both user-defined and predefined), i.e. a list of all indexed values, or a section thereof, in a vector.

Definition

vector getvector
(
      object    Object     input,
      attribute Attribute  input
  { , anyvalue  FirstIndex input
  { , anyvalue  LastIndex  input } }
)

Parameters

object Object input

This parameter defines the object whose attribute values shall be queried.

attribute Attribute input

This parameter defines the attribute to be queried.

anyvalue FirstIndex input

This optional parameter defines the start index as of which the element values are retrieved. For one-dimensional array attributes an integer value should be specified, for two-dimensional arrays an index value. The default value for one-dimensional array attributes is the integer value 1, for two-dimensional arrays the index value [1,1].

anyvalue LastIndex input

This optional parameter specifies the end index up to which the values from the attribute are taken into the resulting value list. Again, an integer value is expected for one-dimensional array attributes and an index value for two-dimensional arrays. If no LastIndex parameter is specified, all values up to the end of the array are included. The LastIndex value should be after the FirstIndex value.

Return value

The indexed values determined from the object attribute are returned as a value list with type vector.

Fault behavior

The function call fails for an invalid object or attribute or for an invalid index range.

Example

dialog D
{
  string Extra[integer];
  .Extra[1] := "Anna";
  .Extra[2] := "William";
}

window Wi
{
  .title "Names";
  
  listbox Lb
  {
     .xauto 0;  .yauto 0;
     .content[1] "..NAMES..";
     .content[2] "Irene";
     .content[3] "David";
     .content[4] "Henry";
  }
  
  on close { exit(); }
}

on dialog start {
  variable vector Names;

  Names := join(getvector(Lb, .content, 2), getvector(D,.Extra));
  setvector(Lb, .content, sort(Names), 2);
}

See also

setvector(), DM_GetVectorValue(), DM_SetVectorValue()

37.5.10.13 setvector()

This function may be used to modify vector attributes (predefined or user-defined). It is possible to assign new values to the attribute as a whole or to only a continuous portion of it.

Definition

boolean setvector
(
      object    Object     input,
      attribute Attribute  input,
      vector    NewValue   input
  { , anyvalue  FirstIndex input
  { , anyvalue  LastIndex  input } }
  { , boolean   SendEvent := true input }
)

Parameters

object Object input

This parameter defines the object whose attribute values shall be modified.

attribute Attribute input

This parameter defines the attribute to be set.

vector Value input

This parameter specifies the value list that will be assigned to the vector attribute.

anyvalue FirstIndex input

This optional parameter defines the start index as of which the element values are modified. For one-dimensional array attributes an integer value should be specified, for two-dimensional arrays an index value. The default value for one-dimensional array attributes is the integer value 1, for two-dimensional arrays the index value [1,1].

anyvalue LastIndex input

This optional parameter specifies the end index up to which the values of the attribute are are modified through the values from the value list. Again, an integer value is expected for one-dimensional array attributes and an index value for two-dimensional arrays. The LastIndex value should be after the FirstIndex value.

If no LastIndex parameter is specified (default value nothing), the size of the Value vector defines the number up to which the vector attribute is modified. The subsequent element values of the attribute are then truncated.

boolean SendEvent := true input

This optional parameter controls whether setting the attribute should trigger an attribute-changed event. The default value is true, which causes the changed event to be sent for the attribute. If the parameter value is false, no event is sent.

Return value