Copyright © 2009 Arndt Roger Schneider

Goolbar
Prev Chapter 4. Toolbar Templates Next

Name

goolbar — Create and manipulate goolbar windows

Synopsis

          ;; package require goolbar in Tcl/Tk.
          (with-ltk-goolbar
             (make-instance 'goolbar ?options ?))

Runtime Library Options

-creator

The RTL based option creator is used to instantiate the template goolbar with a Tk Window. The used creator window must have a -class property.

Acceptable Tk Windows are: toplevel for floating windows, and frame for embedded windows.

Standard Options

-activeBackground, -activeBorderWidth, -activeForeground, -background, -borderWidth, -disabledForeground, -foreground, -relief, -selectColor, -orient, -takeFocus, -highlightThickness, -highlightColor, -highlightBackground, -font

See the options manual entry for details on the standard options.

Window-specific Options

Command-Line Name: -usetoken, Database Name: useToken, Database Class; -

»useToken« activates the glyph vector graphics system implemented in the toolbar. If »useToken« is set to »1« (true), then the item property »iconFont« is evaluated and the provided image substituted through the glyph given by the property: »token«.

The item properties »bgImage« and »image« are recessive to »token«, whenever »useToken« is set.

Command-Line Name: -usegrid, Database Name: useGrid, Database Class; -

»useGrid« tells the toolbar to place each item aligned on a grid defined by »gridSize«.

Command-Line Name: -gridsize, Database Name: gridSize, Database Class; -

»gridSize« expects a distance denoting the size of a cell. An item may occupy one or more of such cells.

»gridSize« is used in a fuzzy-like way. If the dimensions of neighboring items are small in compared to the actual item, then the actual item may share some space from its neighbors. The same applies if the actual item is small compare to the neighboring items –it does yield some space to them.

Command-Line Name: -showimage, Database Name: showImage, Database Class; -

»showImage«, a boolean property, tells the toolbar to display images.

»image« may be »fgImage«, »image« or »token« and »iconFont« or »vector«.

Command-Line Name: -showtext, Database Name: showText, Database Class; -

»showText«, a boolean property, tells the toolbar to display the »label« of all its items.

Command-Line Name: -tearoff, Database Name: tearoff, Database Class; -

This option must have a proper boolean value, which specifies whether or not the window should include a tear-off entry at the left. The default windows bindings arrange for the window to be torn off when the tear-off entry is invoked.

Command-Line Name: -tearoffcommand, Database Name: tearoffCommand, Database Class; -

If this option has a non-empty value, then it specifies a Tcl command to invoke whenever the window is torn off.

The conventional Runtime Library template mechanism is used for the »tearoff« functionality. That is A torn-off toolbar is converted into a floating window and replaces the original –embedded– window.

Under Construction.

Command-Line Name: -show, Database Name: show, Database Class; -

Toolbar items may be visible or invisible. This setting is controlled via the »show« property. Suppose there are four items inside the toolbar named »a«, »b«, »c« and »d« in this situation all items will be initial visible –right after they were added to the toolbar, unless »show« was specified prior to the add commands.

Example 4.1. Implicit Visible Items


    # Create the toolbar without specifying
    # show makes all added items visible.

    .toolbar add command a …
    .toolbar add command b …
    .toolbar add command c …
    .toolbar add command d …

Example 4.2. Explicit Visible Items


    # Example hide d – and add variable space (~)
    .toolbar configure -show {a b ~ c}

Command-Line Name: -title, Database Name: title, Database Class; -

The »title« property is only used for a free-floating toolbar. The text property »title« is used as the caption for the created toplevel window.

Command-Line Name: -autobreak, Database Name: autobreak, Database Class; -

A boolean property. Either 0 or 1. Default is 0 (false/off). Tells the toolbar to break the items into multiple lines.

In addition, line break can be controlled by defining »columnbreak« for an item.

Command-Line Name: -usemenu, Database Name: useMenu, Database Class; -

»useMenu« expects a boolean value. if »useMenu« is set to »1« (true) then a context menu will presented after a <<Context>> (a right-button-click) occured. Do also use »customizeCommand« together with »useMenu«.

Command-Line Name: -hidecommand, Database Name: hideCommand, Database Class; -

The »hideCommand« is used inside the toolbar context menu. The conventional response to this command is to invoke the »Hide Toolbar« menu entry in the »View« menu.

Example 4.3. Hide Toolbar

# The application Toolbar:
goolbar .toolbar -hidecommand {
   .menubar.view invoke ?index of entry?
}

# The Application Menubar:
menu .menubar
. configure -menu .menubar

# The Menubar entry »View«:
.menubar add cascade \
              -label "View" \
               -menu .menubar.view

# The »Hide Toolbar« command inside the
# »View« menu: Record the index of this
# command:
.menubar.view add command \
              -label "Hide Toolbar"
            -command ...

Command-Line Name: -customizecommand, Database Name: customizeCommand, Database Class; -

A toolbar customization function.

The »customizeCommand« will be accessible from the toolbar context menu.

Use the »customizeCommand« in order to invoke the Gooleditor for this toolbar.

Example 4.4. Calling a Gooleditor


goolbar .toolbar
       -customizeCommand \
           [list customizeToolbar .toolbar]

proc customizeToolbar toolbar {
     if ![winfo exists $toolbar] return

     # An embedded dialog
     set fmt myicons
                
     # A different embedded dialog for glyphs:
     if [$toolbar cget -useToken] {
        set fmt mytbicons
     }
     
     # Display the toolbar editor inside
     # the parent window.           
     gooleditor [winfo parent $toolbar].custom \
          -goolbar $toolbar -custom $fmt
}

Command-Line Name: -vectorsize, Database Name: vectorSize, Database Class; -

The »vectorSize« is reported to the canvas graphics based vectors.

In the future: Vectors, glyphs and images may become fully interactively resize-able –with a scroll-wheel. This feature requires that all vector graphics originate from TkPath.

It is OK to ignore the size parameter, when creating a vector.

Always use resolution independent values like »24p« –24 points. 24p is the »vectorSize« default value.

The Zoolbar already supports »vectorSize« for images.

Description

Figure 4.1. Goolbar: Normal, Selection, Active, Focus


Figure 4.2. Goolbar: »Working« Active, Focus and Selected


Figure 4.3. Goolbar: »Generate« Disabled


Goolbar implements a toolbar window. goolbar supports: images, foreground and background bitmaps, glyph vector icons, fully vectorized icons based on the Tk canvas window and / or TkPath 0.2 and TkPath 0.3.

The goolbar follows the AQUA® Human Interface Guidelines, when it’s technical feasible.

The toolbar item state is reflected in the icons. foreground bitmap uses the »-activeforeground« to represent the active state (the item is pressed). »activeforground« may appear inside of vectors, too. The »-fill« property from the vector element with tag »activeforeground« is used to reflect the active state. The fill property is restored when the item state changes back to the normal state.

Example 4.5. activeforeground inside of a vector ...«

set item [$canvas create path [subst {
  M [expr { $x - $size * 0.5 }]
    [expr { $y - $size * 0.75 }]
  L [expr { $x - $size * 0.25 }]
    [expr { $y - $size * 0.75 }]
  L [expr { $x - $size * 0.25 }]
    [expr { $y - $size * 1.25 }]
  L [expr { $x + $size * 0.25 }]
    [expr { $y - $size * 1.25 }]
  L [expr { $x + $size * 0.25 }]
    [expr { $y - $size * 0.75 }]
  L [expr { $x + $size * 0.5 }]
    [expr { $y - $size * 0.75 }]
  L [expr { $x + $size * 0.5 }] $y
  L [expr { $x - $size * 0.5 }] $y
  Z }] \
       -fill $linear257 \
-fillopacity 0.5 \
     -stroke [opget $canvas foreground black] \
-strokewidth [winfo pixels $canvas 3.0p] \
       -tags [concat $tags [list activeforeground ]]]

For items of type »checkbutton« and »radiobutton« »-activebackground« is used for the selection rectangle.

The active item is also moved to the right bottom in order to create a press-like illusion.

»checkbutton« and »radiobutton« also support »-selectcolor« and ».selectForeground« , both colors are used to render the selected state these items. »selectcolor« may be a TkPath 0.2 gradient, too.

Focus, also known as highlighting is also supported for the internal items. Only »-highlightthickness« and »-highlightcolor« are supported, HighlightBackground will be ignored. The focus ring is rendered for TkPath based glyphs or vectors. The vector element must have a »focusframe« tag, telling the goolbar that this element is meant as the focus-ring. The TkPath property »-strokeopacity« is used.

Example 4.6. ...focus-ring management inside of a vector ...

::gstripes::focuspathes $canvas [list \
      [expr { $x - $size * 0.5 }] \
      [expr { $y - $size * 0.75 }] \
      [expr { $x - $size * 0.25 }] \
      [expr { $y - $size * 0.75 }] \
      [expr { $x - $size * 0.25 }] \
      [expr { $y - $size * 1.25 }] \
      [expr { $x + $size * 0.25 }] \
      [expr { $y - $size * 1.25 }] \
      [expr { $x + $size * 0.25 }] \
      [expr { $y - $size * 0.75 }] \
      [expr { $x + $size * 0.5 }] \
      [expr { $y - $size * 0.75 }] \
      [expr { $x + $size * 0.5 }] $y \
      [expr { $x - $size * 0.5 }] $y] \
   [$canvas bbox $item] \
   [opget $canvas focusWidth 3] \
   [$canvas cget -highlightcolor] 90 \
   [concat $tags [list focusframe]] {M %s Z}

Horizontal / Vertical:

The toolbar knows two directions hor/vert the different drawing schemas are represented by different namespaces with the same functionality.

03/01/2007, Roger Well this remains undecided! Horizontal and Vertical does not really matter in general. The toolbar will wrap items if needed –see also break column, below. Vertical might be implemented in the future by rotating its content (requires either tkpath or zinc (zoolbar).

Breakcolumn:

The breakcolumn attribute is used to determine the wrap conditions for the toolbar.

Custom Windows:

The toolbar supports custom windows. A creation procedure must be specified for the window. These procedures will be called when such an item is displayed inside the toolbar.

03/02/2007, Roger There will be a future extension covering this kind of stuff. In the immediate future new types such as search will be added as predefined entries –customizable. Windows or non-standard aggregation are now –and in the future– definable as part of a »vector«.

Groups:

Use a vector to do things like grouping.

Images, Glyph & Vector:

These three types are used in order to draw a symbol in the the toolbar. Images are the default method. A Glyph is used instead of images when an iconFont is defined and useToken is set to True. A vector takes precedence over either images & glyph.

Images in this context is not a typo: There are two images an image in the foreground, accessible via 'image' and an background image via 'bgimage'. The foreground image will partake in color changes (foreground, activeForeground, selectForeground) if it was created from a bitmap.

Zoom:

Use zooming (different image sets) via the customize dialog! I discarded it in general, because it would either require TkPath or zinc and the result does not look good enough. This is also more consistent with aqua.

Customize:

Customization is done within the gooleditor, which is another window. The customized toolbar has to be supplied with the -goolbar property. Add "Show Toolbar" / "Hide Toolbar" and "Customize Toolbar..." to the View menu. These entries should be placed in the bottom section just before "Show Status Bar" / "Hide Status Bar"

Revision : 05/16-18/2009, Roger 1.1

* activeforeground for ptext elements and vectors. * activeforground, activebackground, selectforeground management revisited and adapted to ptext! * Focus-Ring Implemented. * Drag and Drop improvement inside goolbar editor. * FullHeight improved.

Window Command

A Window created through the goolbar command exposes various functions. Using these functions has the following general form: 

(option object ?arg arg ...?)

PathName is the same as the window path name. Option and the args determine the exact behavior of the command. The following commands are possible for this window:

(cget object :option)

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the goolbar command.

(configure object ?:option? ?value option value ...?)

Query or modify the configuration options of the window. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given window option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the goolbar command.

(ungradient object )

Undocumented.

(deactivate object ?color? ?opacity? )

Undocumented.

(delete object item )

Remove »item« from the goolbar.

(pendingMbutton object width height )

Notification that the toolbar will be redrawn. The items, which do not fit on the toolbar, can be reached through the menu on the right.

(gridCenter object left width ?useGrid? )

Gridded size for an item to be placed inside the toolbar. The size is always in multiples of gridSize.

In cases where the previous item is far from the new item: Allow to overlap the neighboring cell.

This is required to get an even, but tightly spaced toolbar. The same holds true for an item much smaller then its cell, while the previous sibling overlaps into the designated cell.

(highlight object item )

Main focus-ring display. The »item« is drawn with the focus ring around it. The specific form of the focus ring depends on whether the given icon is a TkPath based glyph (iconfont) or a vector.

A vector should contain a »focusframe« tag element, this element is modified by »highlight«. »highlight« operates on the »-strokeopacity« property of the item with tag »focusframe«.

Not supported for vanilla Tk!

(dowhenidle object fcn ... )

Call the internal method »fcn« using an after idle call. The open argument list is attached to the call.

(customizeMenu object menu )

Prepare the context menu used for the toolbar.

(stepOverDisabled object items i ?by? )

Look inside »items«, whether next at position »i« is disabled or not, if it is disabled, select the next not-disabled item in »items« and return its current position.

Internal used by »next« and »previous«.

(itemcget object name attr )

Configure property 'attr' of item 'name'.

Together with »next«, manage the internal focus ring. »previous« moves it to the Left. See also: »rtl_tabset.tcl«.

(activate object )

Undocumented.

(add object type name ... )

»add« is similar to »Menu add«. It does accept: »command«, "checkbutton", »radiobutton« and »separator« as the value of »type«.

»cascade« is not supported.

»add« expects a name for each newly created item. Specify the item with »name«.

The open argument list is handed over to the newly created item and evaluated according to »itemconfigure« and »itemcget«.

(pendingRedraw object ?width? ?height? )

Parameters : base - goolbar width - width of 'goolbar' height - height of 'goolbar'

Description : Check if the size has been manipulated and ignore anything else. Store the last dimension for later and fire the pending trigger –if not set, yet.

Written : 2003, Roger Revision : 10/21/2007, Roger

(postMenu object menu )

Undocumented.

(insertCounter object item )

Expand the counter property by »item«.

(tearoff object x y )

Turn a managed toolbar into a floating window. Tear off is drawn a binding has been applied to the button.

Together with »previous«, manage the internal focus ring. »next« moves it to the Right.

Focus ring management differs from »rtl_tabset«’s »next« and »previous« are guarded against missing items.

(focusIn object )

Event Handler. The event handler »focusIn« is called in response to a »FocusIn« event, indicating that the goolbar gained the current keyboard focus.

See also: -takefocus.

(alternateStippleColor object fillcolor )

Undocumented.

(hideMB object )

Does indeed hide the menu in the right corner.

(active object type index ?color? ?fpassive? )

Display the item »index« of »type« in active state. The given »color« is used to change the »foreground« color of an image –if it is a »bitmap«. »activeForeground« is used whenever »color« is ommitted or empty.

Extended, in order to allow acitveForeground inside of vectors, too. An additional tag »activeforeground« is searched inside the selected item.

Be aware these vector element will be restored to foreground, and the fill property is used!

(fallback object )

Re-manage a floating toolbar. Does only work for grid.

(itemconfigure object name ... )

Find the type of the given item and apply the given properties to it. Redraw the toolbar afterwards.

(destroy object )

Additional, custom destructor. Required, in order to remove a possible local caché.

(invokeFocus object )

Event handler. »invokeFocus« is called in response to the »space« key.

The item, with the current »focus« is invoked (the assigned script executed).

See also: set-focusindex, next, previous, set-highlight, highlight.

(focusOut object )

Event Handler. The event handler »focusOut« is called in response to a »FocusOut« event, indicating that the goolbar did loose the current keyboard focus.

See also: -takefocus.

(type object name )

Retrieve the kind of the item identified by its »name«.

(init object )

tearoff has to be drawn each time the toolbar is resized or its orientation changes. The tearoff attribute does not affect the draw operation.

The color schemas are somewhat difficult. Tk lacks a Color Management System to compare colors ... especially under AQUA and Windows where symbolic color names are used (SystemWindow, SystemButtonFace ...). There is currently no way to derive a slightly different color from them to draw the stripes ... call stripes on AQUA, but not anywhere else…

Note 12/21/2007 - 13:14 : Use Tkpath!. See »gstripes.tcl« for details on stripes. As for now: Stripes are not only stripes, anymore.

Note 12/21/2007 - 13:11 : Well, there is no difference between a goolbar and any other window. Stripes is used in the usual fashion aka: "stripesCommand" and "adjustCommand". Both versions are simply required for more complex user interfaces.

Creates a local caché for each new goolbar window. This cache is mainly used under Aqua for the typical gradient whenever the application gets the focus.

(Elements object )

Access to all named items.

(gradient object )

Undocumented.

(showContext object widget x y )

Map the context menu on screen.

(goolbar object ... )

Undocumented.

(stepOver object items i ?by? )

Similar to »stepOverDisabled«. Ignore separators and variable space, too.

(stripes object )

Undocumented.

(execute object index widget x y ?execute? )

Perform »execute« when x,y are in the proximity of »index« ... aka Button Release.

(redraw object ?elements? ?fInactive? ?offsetY? ?offsetX? ?linebreak? )

Main drawing for all toolbar items. The items have to draw themselves. Redraw allots them space in an off-screen area and later moves those items into the visible region, after all items have been drawn. The toolbar width and height are changed as a side-effect (see ➊.

linebreak is handled in redraw (see ➋. varspace --partially-- also (see ➌.

(griddedSize object right distance ?useGrid? )

Calculate the item position in multiples of »gridSize«.

The grid is meant to give the toolbar –and toolbars– an even look. The items aren’t dependent on there dimensions.

Dependencies

  • gstripes

  • gcache

  • rtl_tooltip

Prev Up Next
Chapter 4. Toolbar Templates Home Galette
SourceForge Logo Gestalt Items