[tail]

Chapter 7
Labels, label formats and fields

TkZinc was initially developed for building interactive radar image working on X server. This requires very good performances, for displaying many hundred tracks and moving them every few second. Tracks are typically composed of some geometric parts and some textual parts. These two parts are connected together with a leader. The geometric parts are subject to scaling. For example the speed vector length in pixel depends on the scale. But the textual part must not be zoomed. Managing parts which are scaled and others which are not, can be a real challenge. Usual toolkits or widget are not suited to such behaviours, but TkZinc is.

To be able to manage many items mixing geometric parts and non-geometric parts, TkZinc introduces the concepts of label, labelformat, fields and fields attributes.

7.1 Labels and labelformats

A label is a set of rectangular fields attached to the following item types : track , waypoint and tabular . The fields of a label may contain either text or bitmaps or images. A label cannot be identified or manipulated by itself; There is no function nor method to get or manipulate a label as an object or an item. A label is always associated to an item and is manipulated through this item.

Some label global characteristics are set/get at the item level:

• The maximum number of fields is defined at item creation, as the second argument of the add method. The field number can not be changed after creation. These fields will be indexed from 0 to n-1. The number of fields can be read with the command numparts . For example:

  $track = $zinc->add('track',1, 4, ....);    # this creates a track item in root group with 4 fields, indexed from 0 to 3

• The rectangular geometries of displayable fields are defined through the item attribut -labelformat. The value is a string following the syntax of the labelformat type. This attribute can be set at any time; thus modifying its value is a way to quickly change the geometry (or the visibility) of some fields. Fields may overlap. They are drawn according to the index order: field 0 is drawn before (thus under) field 1. The labelformat also optionnaly describes a clipping rectangle. For example:

  $zinc->itemconfigure($track, -labelformat => 'a12a0+0+0 x20x10^0>0 a2a0>1>0');    #                                             ^         ^          ^    #                                             field0    field1     field2    # the labelformat indicates that only the first 3 fields will be displayed:    #  field 0 expands for the size of the text + 12 pixels.    #       It starts at the top left point    #  field 1 has a size of 20x10 pixels.    #       It is left aligned with field 0, just under field 0    #  field 2 expands for the size of the text + 2 pixels.    #       It is adjacent to the right of field 1, just under field 0

Characteristics of each individual field are called field attributes. They are all described in next section Attributes for fields . They may be set or get with the itemcget and itemconfigure command. These commands require as a second argument the field number. By configuring field attributes you can modify :

• the field content : -text , -image , -tile , -fillpattern ,
• the field colors : -backcolor , -bordercolor , -color ,
• the text general appearance : -alignment , -autoalignment , -font ,
• the field border : -border , -relief , -reliefthickness ,
• and the field visibility and sensitivity: -sensitive , -visible .

As an example:

# this should display "Hello World" in white on black in field 0    $zinc->itemconfigure($track, 0, -text => 'Hello World',                                    -color => 'white',                                    -backcolor => 'black',                                    -filled => 1);

It is possible to bind callbacks to fields, with the command bind and special tags (described Tags and bindings ). As an example:

# this binds &acallback to field 1    $zinc->bind("$track:1", '<1>', \&acallback);

Inside a callback function, it is possible to know which field the mouse cursor is over with the command currentpart .

A Perl module, called Tk::Zinc::Text (see the section Tk::Zinc::Text ) is provided for easing text input in text fields (it can also be used for easing text input in text item).

7.2 Attributes for fields

Fields are item parts of items supporting labelformat (i.e. track , waypoint and tabular ). They can be configured in a similar way of items themselves, with the command itemconfigure , but this command requires an additionnal parameter (in second position) the fieldId. To get the value of a field attribute, you can use the command itemcget with the fieldId as an additionnal second parameter.
NB: Field attributes cannot be configured at item creation with the command add .

Applicable attributes for fields are:

-alignment alignment

-autoalignment autoalignment

-backcolor gradient

-border edgelist

-bordercolor gradient

-color gradient

-filled boolean

-fillpattern bitmap

-font font

-image image

-relief relief

-reliefthickness dimension

-sensitive boolean

-text string

-tile image

-visible boolean

[front]