40 tablefield

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

Using the two scroll bars, the contents of the tablefield can be scrolled both horizontally and vertically. The content of the tablefield consists of static texts that can be selected.

Events

activate

cut

charinput

deactivate

dbselect

extevent

focus

help

hscroll

key

modified

paste

scroll

select

vscroll

Children

document

record

transformer

Parent

groupbox

layoutbox

module

notepage

splitbox

toolbar

window

Menu

Pop-up Menu

Methods

:clear()

:delete()

:exchange()

:find()

:insert()

Remark

To allow the dialog programmer to distinguish more precisely what the user has really done, additional querying of attributes may be necessary. The editable text belonging to the tablefield does not send any events. These are all sent to the tablefield and can be queried there.

Remarks for important events of the tablefield

The select event is triggered whenever the user clicks the mouse (exception see below “Release mouse capture” or when the user presses the space bar.

The select event is available in two forms:

• With Index

  A sensitive field has been selected.

• Without Index

  A select event has occurred that cannot be assigned to a single field. I.e. the user has either clicked in an insensitive field or in an area where there are no fields.

The dbselect event is triggered whenever the user double-clicks the mouse (exception see“Release mouse capture” below) or when the user presses the Ctrl and Return keys simultaneously.

The dbselect event comes in two forms:

• With Index

  A dbselect event has occurred in a field that is sensitive.

• Without Index

  A dbselect event has occurred that cannot be assigned to a single field. I.e. the user has either clicked into an insensitive field or into an area where there are no fields.

However, for DM with Motif, the dbselect event is always sent with index. dbselect for insensitive fields does not exist.

The focus event is generated whenever the focus object or the focus field changes. The focus event comes in two forms:

• With Index

  A new field that can be focused has received the focus.

• Without Index

  The tablefield has received the focus. There is no field that can receive the focus.

The modified event contains the index of the field that was modified.

The activate or deactivate events are generated without an index, since the activation state usually changes for more than one field.

Handling of events with index

It must always be ensured that - before accessing an index - it is checked whether an index is set at all. A check can be done with the following code fragment:

if (typeof (thisevent.index) = index) then

  /*

   * here you can work with the index.

   * "thisevent.index.first" corresponds to the line and

   * "thisevent.index.second" .corresponds to the column

   */

else

endif

Implicit reset of tablefield states when changing tablefield attributes

For Motif, the content is not discarded for any of the attributes listed below.

The following list is for Microsoft Windows.

The list does not claim to be complete. The index attributes for the inside of the tablefield are not included in the list; however, the corresponding applies.

Deactivate the edit text without saving the content

Regardless of .edittype, the edit text is deactivated and the possibly changed content is discarded for the following attribute changes:

.colcount, .colvisible[integer], .edittext, .rowcount, .rowvisible[integer]

As of IDM version A.05.02.h, using a method that changes the content (e.g. :insert, :exchange) causes the linked edit text to be deactivated without saving its content. In previous IDM versions, the edit text remained enabled, but not all changes were displayed immediately.

Deactivating the edit text with saving the content

With the following attribute changes the edit text is deactivated and the possibly changed content is saved or discarded. If .edittype = locking, the edit text is disabled and the content is discarded.

If the .active attribute is implemented without an index, the edit text is enabled or disabled, and the content is saved only if .edittype is not locking.

Release mouse capture

When the left mouse button is pressed, a mouse capture (exclusive mouse access) is fetched. When the mouse button is released, this mouse capture is released again and a select event is generated. No select event is generated if no mouse capture is active when the left mouse button is released. The mouse capture is also released on the attribute changes listed below. Thus, it is possible that select events are prevented. This risk exists especially when processing focus events, since the focus is triggered when the mouse buttons are pressed. This complicated processing is justified to be able to assign mouse clicks correctly.

Remark

This behavior does not apply to DM with Motif.

40.1 attributes

.acc_label

.acc_text

.accelerator

.active

.active[index]

.activeitem

.bgc

.bgc[index]

.borderraster

.borderwidth

.class

.colalignment[integer]

.colcount

.colfirst

.colheader

.colheadfgc

.colheadfont

.colheadshadow

.colheadvisible

.collinewidth[integer]

.colsizeable[integer]

.colwidth[integer]

.colvisible[integer]

.content[index]

.contentfunc

.control

.cursor

.cut_pending

.cut_pending_changed

.direction

.document[integer]

.editpos

.editable

.editable[index]

.edittext

.edittype

.external

.external[integer]

.fgc

.fgc[index]

.field[index]

.fieldactive[index]

.fieldfocus

.fieldfocus[index]

.fieldfocusable

.fieldshadow

.firstrecord

.focus

focus[I,J]

.font

.font[index]

.format[index]

.formatfunc

.function

.height

.help

.hsb_optional

.index

.label

.lastrecord

.layoutbox

.mapped

.maxchars[index]

.member[integer]

.membercount

.menu

.model

.navigable

.nextactive[index]

.notepage

options[enum]

.posraster

.preeditsel

.real_height

.real_sensitive

.real_visible

.real_width

.real_x

.real_y

.record[integer]

.recordcount

.reffont

.rowalignment[integer]

.rowcount

.rowfirst

.rowheader

.rowheadfgc

.rowheadfont

.rowheadshadow

.rowheadvisible

.rowheight[integer]

.rowlinewidth[integer]

.rowsizeable[integer]

.rowvisible[integer]

.scope

.selection[enum]

.selstyle

.sensitive

.sensitive[index]

.sizeraster

.statushelp

.toolbar

.toolhelp

.userdata

.userdata[index]

.visible

.vsb_optional

.width

.xalignment[index]

.xauto

.xleft

.xraster

.xright

.yalignment[index]

.yauto

.ybottom

.yraster

.ytop

40.2 Specific attributes

40.2.1 Size calculation in tablefield

The .height and .width attributes can also have the value 0. This means that the Dialog Manager should calculate the corresponding size so that all elements can be displayed in the corresponding direction without the need for a scrollbar. For example, if the width of the tablefield is set to 0, it will be so wide that all columns can be completely displayed in the object.

If the tablefield has .sizeraster set, and both .xraster/.yraster and .reffont = 0, the raster definition of the direct parent object is taken. So the tablefield calculates its own size like a normal object from the raster factors of its parent. Only the size definitions inside the tablefield, collinewidth[I] and rowheight[I], refer to the raster attributes defined for the tablefield.

However, the pixel values are calculated according to the method defined for the tablefield.

40.2.2 Text alignment in tablefield

The horizontal and vertical alignment of text in a tablefield cell is set by the .colalignment[integer] and .rowalignment[integer] attributes, but the horizontal alignment is set only column-wise and the vertical alignment is set only row-wise.

Using the options[opt_new_align] option with the value true, the .xalignment[I,J] and .yalignment[I,J] attributes are taken into account instead of .colalignment[I] and .rowalignment[I]. These have the same value range/meaning as .colalignment[I] and .rowalignment[I]; however, .xalignment[I,J] and .yalignment[I,J] are double-indexed and inheritance is by direction as with all other double-indexed attributes.

The default value of .options[opt_new_align] is false.

Supported under Motif and MS Windows.

40.2.3 Attribute default values

For some attributes .attribute[0] is defined as default. This is always taken if no more value is available for the really needed value. The first correctly usable element is always .attribute[1]!

For some attributes .attribute[0,0] or .attribute[y,0] and .attribute[0,x] is defined as default. These are always taken if no more value is available for the really needed value. The first correctly usable element is always .attribute[1,1]! With the use of these Defaults two-stage one proceeds:

• If no value is defined for the required index, the index defined by the .direction attribute is set to 0. If a value is defined here, it will be taken
• However, if no value is defined here either, the global default for the attribute at .attribute[0,0] is taken.

Because of this approach, you should always define a default .attribute[0,0] for used attributes.

40.2.4 Indexing the table

All attributes provided with two indices are always indexed with [I] = Row/row and [J] = Column/column, i.e. .attribut[I, J].

In the image above, all indices are specified as this must be defined.

40.3 Note on deprecated attributes

The deprecated .focusable attribute is no longer supported and generates an ignoring warning when setting and resetting (setinherit) the attribute, and a FAIL when reading the attribute.

40.4 Alignment of the tablefield

The .direction attribute defines the orientation of the tablefield and controls whether rows or columns take precedence. The attribute influences the adopting of row and column default values, the selection and navigation as well as certain methods.

Value range

1 (default)

Vertical orientation with column priority.

2

Horizontal orientation with row priority.

Effects

Default values

With . direction = 1, the column defaults, i.e. the attribute values with the indices [0,<C>], will be used for cell values (.content[index], .bgc[index], .fgc[index]…) that are not set. With .direction = 2, the row default values, i.e. the attribute values with the indices [<R>,0], will be used.

Selection

Navigation

:find() method

The .direction attribute affects the search direction of the :find() method. If .direction = 1, the tablefield is searched row by lrow, if .direction = 2, it is searched column by column. For example, if the searched value is located in cells [4,2] and [3,5], :find() without specifying a search range will return the location [3,5] if .direction = 1 and the location [4,2] if .direction = 2.

Methods :clear(), :delete(), :exchange(), :insert() and :move()

The attribute .direction, together with the optional Direction parameter of the methods, controls whether the methods are applied to rows or columns. If the Direction parameter is not specified, the methods are applied to rows if .direction = 1 and to columns if .direction = 2.

40.5 Mouse interactions

If available, the following interactions are possible with the mouse:

• selection
• scrolling

40.5.1 Selection in the tablefield

The selection of a field is only possible if it is sensitive. This is defined via the attribute .sensitive for the entire tablefield and via the field-specific attribute .sensitive[I,J]. In addition to these attributes, the .selstyle attribute also influences the selectability of a field. Normally, the field on which the user has clicked is selected. The input focus is set to this field and marked as selected and with focus. The content of the field is immediately transferred to the associated editable text and released there for modification.

In order to distinguish the single field selection from a row/column selection, two mouse selection types must be defined. The single field selection is done as the user normally selects an object, i.e. by clicking on the object with the left mouse button. The row/column selection should be done by pressing the left mouse button and simultaneously pressing the shift key. When determining the action to be triggered, the weight of each selection type must be taken into account.

The following order applies ( > = "more important than", "takes precedence"):

• For mouse single selection

  single > row/column

• For the row/column selection

  row/column > single

This results in the following procedure for the evaluation:

• Single field selection

  First, it is checked whether the mouse click can be interpreted as a "single" selection or a "header" selection. If this is not possible, it is interpreted as a "row/column" selection. The direction specified in the .direction attribute is examined first.

• Row/column selection

  First, it is checked whether the mouse click can be interpreted as a "row/column" selection. The direction specified in the .direction attribute is examined first. If this is not possible, an attempt is made to interpret it as a "single" selection or a "header" selection.

Actions on the individual tablefield selection types:

40.5.2 Scrolling the tablefield

Scrolling in all directions is always done in sense units. Scrolling is always done in such a way that entire rows or columns are deleted from the display area and replaced by new ones. This applies to both row/column scrolling and page scrolling. It is always possible to scroll so far that the last column or row is just completely visible and there might be an empty area on the right and at the bottom. This is because the Dialog Manager guarantees that an element is visible in the upper left corner.

In detail, this looks as follows:

Through this scrolling, Dialog Manager guarantees that the first row and the first column in the tablefield interior are always displayed correctly and completely, if the tablefield is only large enough. The last visible row and the last visible column can only be partially displayed if the tablefield has unfavorable dimensions. If the scrolling action is not feasible in the described form, the scrolling is performed as far as possible.

Example

The user wants to scroll page by page, but only one column is not displayed. It is then scrolled so that this column just comes completely into the display area. It can happen that an empty space remains on the right and below, because the upper left corner is always displayed correctly.

The calculation of the slider size and the maximum value of the slider is based on pixels, not on sense units of the tablefield. When calculating the slider size, the available space in the tablefield interior is set in relation to the actually required area.

This is done according to the following formula:

• for the horizontal scrollbar

  Slidersize = Scrollbarsize * (usable width /sum of the width of all columns (without row headers))

• for the vertical scrollbar

  Slidersize = Scrollbarsize * (usable height /sum of heights of all lines (without headers))

When scrolling, the focus in the tablefield is not changed. This makes it possible for the focus to sit on an object in the tablefield that is not currently visible. To visualize this, the focus frame is then painted around the entire object. If the object with the focus is scrolled back into the visible area of the tablefield, the focus is only painted around the field and no longer around the entire object.

40.6 Interactions via the keyboard

The tablefield can be operated completely without a mouse. With tablefield cursor control, the tablefield must automatically perform all necessary scroll operations so that the field reached by cursor control is in the visible area of the tablefield. The cursor control is not cyclic for any direction; i.e. if there is no field allowed for cursor control in the actual search direction, the cursor stops. A field that is allowed for cursor control is either .sensitive = true or the attribute .fieldfocusable was set to true for the tablefield (i.e. non-sensitive objects can also be reached with the cursor control).

40.6.1 Keyboard mapping for navigation

The keyboard layout for navigation looks like this:

Remark for Cursor Up, Down, Right, Left

If the cursor control is used to move from the header area to the tablefield area inside, the cursor is placed on the first element visible below/next to the headers without triggering scrolling.

If the cursor control is triggered in the direction of the header (cursor Up, cursor Left) in the first element below/next to the headers, the cursor is not positioned on the header until the corresponding scrollbar is at its initial value.

(this->tablefield.?->first = this->tablefield.?->header + 1)

As long as this is not the case, scrolling is performed accordingly.

This means that the actions cursor Left followed by cursor Right and cursor Down followed by cursor Up do not have to be inverse operations.

40.6.2 Keyboard mapping for scrolling

The keyboard layout for scrolling looks like this:

For all these scrolling actions, the scrolling behavior described in the chapter “Mouse interactions” applies.

Remark Remark on scrolling via keyboard

If scrolling is triggered via the keyboard, the focus does not change its position on the screen. However, this can change its internal position or the element that currently has the focus. For example, if the cursor is in a heading and scrolling vertically, the cursor will remain in the same position both on the screen and internally. However, if the cursor is inside the tablefield, it will change its internal position in any case; the position visible on the screen, however, will remain largely unchanged.

40.6.3 Keyboard mapping for the selection

The two keys "logical selection" and "logical row/column selection" depend on the window system.

40.7 Interactions with the editable text

The editable text belonging to the tablefield is automatically provided with the content of the field that currently has the focus. Additionally, the attributes .maxchars[I,J] and .format[I,J] corresponding to the current focus object are taken over.

Depending on the .edittype attribute, the actions in the editable text are transferred to the tablefield.

• With .edittype online, all changes in the editable text are immediately applied to the tablefield.

• With .edittype offline, the changes are not applied to the tablefield until the editable text is deselected.

• With .edittype locking the tablefield is locked after the first input into the editable text and only after input of Return released again and the content is taken over.

  If the editable text is left without a return and only by a normal deselection or the input of ESC, the changes are not accepted, but the tablefield is released again. The editable text itself does not send any events.

Remarks

• An editable text is not activated by the cursor navigation, but only by the first character designated for the editable text.

• When an editable text is enabled, the following navigation applies:

  Key	single-line ET	multiline ET
  Cursor Left, Right	ET receives key	ET receives key
  Cursor Up, Down	ET receives key (can also be ignored)	ET receives key
  Return	Next (previous) entry	ET receives key
  Tab (Shift + Tab)	Next (previous) entry	Next (previous) entry

• A multiline editable text always has scrollbars, regardless of .editpos.
• The height of an entry does not affect the number of text lines that can be entered by the user.
• Since the .format attribute is controlled by the tablefield, the attribute of the bound edit text should not be used.

40.8 Interactive column and row resizing

When the mouse is moved over the edge of a manipulable field, the mouse cursor changes and shows a resize icon. The appearance of the cursor cannot be specified by the application programmer. For columns, resizing can be done at the right border of each column. For the rows, the lower boundary is relevant.

The user can initiate the resizing with the left mouse button. A gray hatched line appears, indicating the position of the mouse (the width of the hatched line depends on the attributes .collinewidth[I] and .rowlinewidth[I]). If the mouse is moved (with the left mouse button pressed), the hatched line moves with it. The resizing is completed by releasing the mouse button.

The new attribute values of the enlarged or reduced rows/columns are automatically applied and the tablefield is redrawn accordingly (The attribute values of .rowheight[I] and .colwidth[I] are changed). This is consistent with resizing the window.

The indexed event resize[I,J] is sent to the tablefield and can be reacted to. One component of thisevent.index is zero at a time. If a row was changed, second(thisevent.index) is zero and with first(thisevent.index) the changed row can be queried. If a column was changed, then the changed column can be queried with second(thisevent.index).

The assignment at a glance:

40.9 Note for the tablefield with Microsoft Windows

40.9.1 Application code page selection

The utfwin code page is not suitable as an application code page when strings containing <Carriage-Return> characters must be processed. The reason is that <Linefeed> characters (line breaks) are converted to the <Carriage-Return><Linefeed> string. To avoid duplicate <Carriage-Return> characters, they are skipped. Instead of utfwin, the code pages utf16 or utf16l should be used, which do not perform this special handling.

40.9.2 Use of colors and Visual Styles

If no colors are set for the tablefield, the IDM uses the system colors of the respective state. If .fieldshadow = true, those Visual Styles of the Windows object pushbutton are used. It defines the assigned colors. If .rowheadshadow or .colheadshadow are switched on, the colors are taken from those Visual Styles of the Windows object headeritem.

If colors are set, they are used. For an active field, .fgc determines the background color and .bgc the foreground color. If only one of the two colors is set, the corresponding system color is used for the other color. Thus, if only one color is set, the foreground and background colors are not swapped, but the set color is assigned differently. There is no separate color assignment for an active and insensitive field. It is displayed in the same way as an active field.

Recommendation

Set either both colors – .fgc and .bgc – or neither of the two colors.

Remark

The colors were also already assigned as described in the IDM for Windows 2000. However, for active objects practically only foreground and background colors were swapped, which brought mostly a good result even with only one color set. Only the Visual Styles (especially that of the Windows pushbutton) partly do not swap the colors anymore, but only use a different background.

40.10 Note for the tablefield with Motif

The Motif tablefield ignores leading line breaks in the table cells (one or more \n at the beginning of the texts). To nevertheless display blank lines before a text, a space can be inserted in the text before the line breaks.

Example

" \nXYZ" instead of "\nXYZ"

40.11 Note for the tablefield with Qt

Scrollbars are present in an extremely small tablefield where the header rows and columns cannot be displayed completely. However, these have no effect.

The tablefield has an empty row and column at the bottom and right, which fill the free area when scrolling all the way down or to the right. If the tablefield is dimensioned in such a way that the last content line or content column cannot be displayed completely, then the user can scroll to this empty line 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 typical for Qt. If several of the elements sel_column, sel_row and sel_single have the value true for the attribute .selection[enum], then sel_single is used. If none of the elements sel_column, sel_row and sel_single has the value true for the .selection[enum] attribute, sel_single is used.

Activated cells are deactivated when a header cell is clicked at .selstyle[sel_header] = false.

With .fieldfocusable = true a click on an insensitive cell also causes a reactivation. The corresponding activate and deactivate events are generated, but there is no select event with index.

The following attributes are not implemented:

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

40.12 Example

The following example shows how to use the extensions:

The tablefield headings can be manipulated interactively.

window
{
  .title "Title";

  child tablefield Tf1
  {
    .xauto 0;
    .xleft 2;
    .width 30;
    .xright 2;
    .ytop 2;
    .height 30;
    .colcount 5;
    .colsizeable[1] true;
    .rowsizeable[1] true;
    .rowheight[0] 5;
    .colheader 1;
    .rowheader 1;
  }
}

!!
!! Output of changed items into Tracefile
!!
on Tf1 resize
{
  print "row: " + itoa(first(thisevent.index)) + " has been changed";
  print "column: " + itoa(second(thisevent.index)) + " has been changed";
}