[tail]

Chapter 2
Widget creation and options

The TkZinc command creates a new TkZinc widget, the general form are in Tcl and Perl:

zinc

$version = $mainwindow->zinc();

$Tk::Zinc::VERSION;

These expressions can be used to get the version of TkZinc. The string returned by the last expression also details the graphic head available. For example : “zinc-version-3205d X11 GL”.

zinc pathname ?options?

$mainwindow->Zinc(?option=>value?, ..., ?option=>value?);

pathname name the new widget and specifies where in the widget hierarchy it will be located.

You can set the $ZINC_GLX_INFO environment variable in order to display some information about the OpenGL instance used by TkZinc (New since TkZinc v3.2.6i).

Any new TkZinc widget comes with a root group item, always identified by the item id 1. This group will contain all other items, either directly or through groups created themselves in the root group. Together the items form a tree rooted at the root group, hence its name. The chapter Groups, Display List and Transformations describes the use of groups. The chapter Item ids, tags and indices describes the item ids and item tags, used as argument in most commands.

The options are used to configure how the newly created widget will behave. They can be changed later by using the configure and itemconfigure Tk commands.

Options apply only to the widget itself. They are a Tk supported concept and benefit from the option database an other mechanisms used to externally adapt the application to different environments. Attributes are a similar concept available for items and other TkZinc objects. But they are private to TkZinc and do not benefit from Tk support. They have been named differently to avoid confusion.

Any number of options may be specified on the command line or in the option database to modify the global behavior of the widget. Available options are described below.

Command line switch:-backcolor
Database name:backColor
Database class:BackColor

This is the color that will be used to fill the TkZinc window. It is also used as a default color for some item color attributes. See each color attribute for the actual source of the default color. Its default value is #c3c3c3, a light grey.

Command line switch:-borderwidth
Database name:borderWidth
Database class:BorderWidth

Specifies the width of the 3d border that should be displayed around the widget window. This border does overlap the active TkZinc display area. The area requested from the geometry manager (or the window manager if applicable) is the area defined by -width and -height , the border is not taken into account. This value can be given in any of the forms valid for coordinates (See TkGet_Pixels). The default value is 2.

Command line switch:-confine
Database name:confine
Database class:Confine

Specifies a boolean value that indicates whether or not it should be allowable to set the TkZinc’s view outside the region defined by the -scrollregion . Defaults to true, which means that the view will be constrained within the scroll region.

Command line switch:-cursor
Database name:cursor
Database class:Cursor

Specifies the cursor to use when the pointer is in the TkZinc window. The default value is set to preserve the cursor inherited at widget creation.

Command line switch:-followpointer
Database name:followPointer
Database class:FollowPointer

Set this option to zero to disable emission of enter and leave events. Motion processing is still performed as usual. It is in some application state annoying to receive enter and leave events which may result in an endless loop. This is a mean to temporarily deactivate the cause. Use with care. The default value is one, enabled. The name is somewhat a misnommer for Tkzinc is still following the pointer.

Command line switch:-font
Database name:font
Database class:Font

The font specified by this option is used as a default font for item attributes of type font. Its default value is -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*.

Command line switch:-forecolor
Database name:foreColor
Database class:Foreground

The color specified by this option is used as a default color for many item color attributes. See each each color attribute for the actual source of the default color. Its default value is black.

Command line switch:-fullreshape
Database name:fullReshape
Database class:FullReshape

If this option is True, the shape applied to the TkZinc window will propagate up the window hierarchy to the toplevel window. The result will be a shaped toplevel. See also the -reshape option, it controls whether a shape is applied to the TkZinc window or not. The default is true.

Command line switch:-height
Database name:height
Database class:Height

Specifies the height of the TkZinc window. This value can be given in any of the forms valid for coordinates (See Tk_GetPixels). The default is 100 pixels.

Command line switch:-highlightbackground
Database name:highlightBackground
Database class:HighlightBackground

Specifies the color to display in the traversal highlight region when the widget does not have the input focus. The default value is #c3c3c3.

Command line switch:-highlightcolor
Database name:highlightColor
Database class:HighlightColor

Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. The default value is black.

Command line switch:-highlightthickness
Database name:highlightThickness
Database class:HighlightThickness

Specifies a non-negative value indicating the width of the highlight rectangle drawn around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to Tk_GetPixels. If the value is zero, no focus highlight is drawn around the widget. The default value is 2.

Command line switch:-insertbackground
Database name:insertBackground
Database class:Foreground

Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). The default value is black.

Command line switch:-insertofftime
Database name:insertOffTime
Database class:OffTime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain off in each blink cycle. If this option is zero then the cursor is on all the time. The default value is 300.

Command line switch:-insertontime
Database name:insertOnTime
Database class:OnTime

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain on in each blink cycle. The default value is 600.

Command line switch:-insertwidth
Database name:insertWidth
Database class:InsertWidth

Specifies a value indicating the width of the insertion cursor. The value may have any of the forms acceptable to Tk_GetPixels. The default value is 2.

Command line switch:-lightangle
Database name:lightAngle
Database class:LightAngle

Specifies the lighting angle in degre used when displaying relief. The default value is 120.

Command line switch:-mapdistancesymbol
Database name:mapDistanceSymbol
Database class:MapDistanceSymbol

This option specifies the symbol to be used as a milestone along map lines. This option can be given any Tk bitmap which can be obtained by Tk_GetBitmap. The spacing between markers is 10 nautic miles. The default value is AtcSymbol19 (see Other resources provided by the widget ).

Command line switch:-maptextfont
Database name:mapTextFont
Database class:MapTextFont

Specifies the font used to draw the texts contained in maps. The default is -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-*-*.

Command line switch:-overlapmanager
Database name:overlapManager
Database class:OverlapManager

This option accepts an item id. It specifies if the label overlapping avoidance algorithm should be allowed to do its work on the track labels and which group should be considered to look for tracks. The default is to enable the avoidance algorithm in the root group (id 1). To disable the algorithm this option should be set to 0.

Command line switch:-pickaperture
Database name:pickAperture
Database class:PickAperture

Specifies the size of an area around the pointer that is used to tell if the pointer is inside an item. This is useful to lessen the precision required when picking graphical elements. This value must be a positive integer. It defaults to 1.

Command line switch:-relief
Database name:relief
Database class:Relief

Specifies the border relief. This option can be given any legal value for a relief (See relief for a description of possible values). The default value is flat.

Command line switch:-render
Database name:render
Database class:Render

Specifies whether to use or not the openGL rendering. The value is a positive integer that can have the values 0, 1 and 2. The value 0 specifies a X11 rendering while the other two ask for an OpenGL rendering and as such requires the GLX extension to the X server. A value of 1 asks for direct OpenGL rendering which is the faster but is limited to a local session with the display while a value of 2 requests an indirect rendering which is slower but can be streamed to a distant display (at least under X11). If a direct rendering mode is requested but can’t be achieved the indirect render mode will be tried automatically. If neither OpenGL modes are available the X11 mode is used as a fallback. This option must be defined at widget creation time and is readonly for the rest of the session. It can be used to ask if the widget is drawing in OpenGL mode or in plain X mode (to adapt the application code for example). The default value is 0.

Command line switch:-reshape
Database name:reshape
Database class:Reshape

Specifies if the clipping shape that can be set in the root group item should clip the root group children or be used to reshape the TkZinc window. This option can be used with the fullreshape option to reshape the toplevel window as well. The default value is true.

Command line switch:-scrollregion
Database name:scrollRegion
Database class:ScrollRegion

Specifies a list with four coordinates describing the left, top, right, and bottom coordinates of a rectangular region. This region is used for scrolling purposes and is considered to be the boundary of the information in the TkZinc.

Command line switch:-selectbackground
Database name:selectBackground
Database class:Foreground

Specifies the background color to use for displaying the selection in text items. The default value is #a0a0a0.

Command line switch:-speedvectorlength
Database name:speedVectorLength
Database class:SpeedVectorLength

Specifies the duration of track speed vectors. This option is expressed using a time unit that should be chosen by the application (usually minutes) and kept coherent with the unit of the track attribute -speedvector (usually nautic mile / minute). The default value is 3.

Command line switch:-takefocus
Database name:takeFocus
Database class:TakeFocus

(Slightly adapted from the Tk options manpage).

Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the takeFocus option. A value of 0 means that the window should be skipped entirely during keyboard traversal. 1 means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). An empty value for the option means that the traversal scripts make the decision about whether or not to focus on the window: the current algorithm is to skip the window if it is disabled, if it has no key bindings, or if it is not viewable. If the value has any other form, then the traversal scripts take the value, append the name of the window to it (with a separator space), and evaluate the resulting string as a callback. The script must return 0, 1, or an empty string: a 0 or 1 value specifies whether the window will receive the input focus, and an empty string results in the default decision described above. Note: this interpretation of the option is defined entirely by the callbacks (part of the keyboard traversal scripts) that implement traversal; the widget implementations ignore the option entirely, so you can change its meaning if you redefine the keyboard traversal scripts. The default value is empty.

Command line switch:-tile
Database name:tile
Database class:Tile

Specifies an image name to be used as a tile for painting the TkZinc window background. The default value is "" (the empty string).

Command line switch:-trackmanagedhistorysize
Database name:trackManagedHistorySize
Database class:TrackManagedHistorySize

This option accepts only positive integers. It specifies the number of positions collected in the history list by the track items. When this many positions have been collected, the oldest is dropped to make room for a new one on a first-in first-out basis. See also the -trackvisiblehistorysize option and the -historyvisible track attribute. The default value is 6.

Command line switch:-trackvisiblehistorysize
Database name:trackVisibleHistorySize
Database class:TrackVisibleHistorySize

This option accepts only positive integers. It specifies the number of past positions to display for tracks. It is a widget wide control. Users of previous releases used the -visiblehistorysize track attribute for the same effect. The number of past positions displayed can not exceed the accumulated positions controlled by the option -trackmanagedhistorysize . The track -historyvisible attribute controls whether a track should display its history. The default value is 6.

Command line switch:-tracksymbol
Database name:trackSymbol
Database class:TrackSymbol

Specifies the symbol displayed at the current position of a track. This option accepts a bitmap . The default value is AtcSymbol15.

Command line switch:-xscrollcommand
Database name:xScrollCommand
Database class:ScrollCommand

Specifies a callback used to communicate with horizontal scrollbars. When the view in the widget’s window changes (or whenever anything else occurs that could change the display in a scrollbar, such as a change in the total size of the widget’s contents), the widget will make a callback passing two numeric arguments in addition to any specified in the callback. Each of the numbers is a fraction between 0 and 1, which indicates a position in the document. 0 indicates the beginning of the document, 1 indicates the end, .333 indicates a position one third the way through the document, and so on. The first fraction indicates the first information in the document that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. Typically the xScrollCommand option consists of the scrollbar widget object and the method “set” i.e. [set = $sb]: this will cause the scrollbar to be updated whenever the view in the window changes. If this option is not specified, then no command will be executed.

Command line switch:-xscrollincrement
Database name:xScrollincrement
Database class:ScrollIncrement

Specifies an increment for horizontal scrolling. If the value of this option is greater than zero, the horizontal view in the window will be constrained so that the TkZinc x coordinate at the left edge of the window is always an even multiple of xScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the left and right arrows of a scrollbar are selected) will also be xScrollIncrement. If the value of this option is less than or equal to zero, then horizontal scrolling is unconstrained.

Command line switch:-yscrollcommand
Database name:yScrollCommand
Database class:ScrollCommand

Specifies a callback used to communicate with vertical scrollbars. This option is treated in the same way as the xScrollCommand option, except that it is used for vertical scrollbars and is provided by widgets that support vertical scrolling. See the description of xScrollCommand for details on how this option is used.

Command line switch:-yscrollincrement
Database name:yScrollincrement
Database class:ScrollIncrement

Specifies an increment for vertical scrolling. If the value of this option is greater than zero, the vertical view in the window will be constrained so that the TkZinc y coordinate at the left edge of the window is always an even multiple of yScrollIncrement; furthermore, the units for scrolling (e.g., the change in view when the top and bottom arrows of a scrollbar are selected) will also be yScrollIncrement. If the value of this option is less than or equal to zero, then vertical scrolling is unconstrained.

Command line switch:-width
Database name:width
Database class:Width

Specifies the width of the TkZinc window. This value can be given in any of the forms valid for coordinates (See Tk_GetPixels). The default is 100 pixels.

[front]