Gstripes

Gstripes
Prev	Appendix A. Reference	Next

Name

gstripes — Create and manipulate gstripes windows

Synopsis

          package require gstripes

          gstripes pathName ?options ?

Runtime Library Options

-creator

The RTL based option creator is used to instantiate the template gstripes 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

-background: See the options manual entry for details on the standard options.

Window-specific Options

Command-Line Name: -stripescommand, Database Name: stripesCommand, Database Class; -

»stripesCommand« is used in combination with »adjustCommand«. These two properties allow to replace the default stripes with a custom variant. »stripesCommand« is responsible to fill the background of the stripes window, whereas »adjustCommad« realigns the background after a resize event has happened.

A predefined »stripesCommand«, called »nilstripes«, is provided with gstripes. Use »nilstripes« to gain the best performance.

Example A.22. Use nilstripes for high Performance

# Add this to your code or the XRDB resource
# file, for a plain coloured background: 
option add *stripes.stripesCommand nilstripes
option add *Goolbar.stripesCommand nilstripes

... ;# or ... Resource file:
*stripes.stripesCommand: nilstripes
*Goolbar.stripesCommand: nilstripes

Command-Line Name: -adjustcommand, Database Name: adjustCommand, Database Class; -

»adjustCommand« realigns the Gstripes background in response to a Configure event. A typical adjust action is to redraw the focus frames.

Example A.23. An adjustCommand for Rtl_gridwin

option add \
  *Rtl_gridwin.stripes.adjustCommand \
  gwadjust

proc gwadjust {base canvas} {
  adjustCommon $base $canvas
  set gridwin [winfo parent $base]

  # Force to redraw the focus ring:
  if ![string first $gridwin [focus]] {
       $gridwin focusIn 
  }
}

Command-Line Name: -repaircommand, Database Name: repairCommand, Database Class; -

Needed for TkPath lower before version 0.2.7. »repairCommand« was called in response to missing gradients. This could happen with TkPath whenever multiple Tk Window hierarchies, using TkPath, existed inside a single application.

Issue is solved and »repairCommand« is no longer necessary.

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

static property.

Boolean value, default is »1«, on.

»touch« controls whether or not the created Gstripes window interacts with hijacked windows or not. When »touch« is set to 1, the window Z-Order is altered. Event handlers are registered between Gstripes and hijacked windows.

A Gstripes window, where touch is disabled (0), is used as a pre-print preview for an already striped dialog.

Description

Gstripes creates white space. A striped window –a dialog– uses a gstripes window for rendering its background.

The gstripes created white space can be enriched with various elements such as background frames, contours , images, vector graphics, labels, messages checkbutton, radiobutton, button, menubutton, menus, menubars and groups .

Gstripes is also used for creating AQUA® like focus frames, which fade into white space. This is used in the Runtime Library templates rtl_combobox, rtl_gridwin; and the gestalt items template gistbox. Three focus functions are present: »gstripes::focusframes«, »gstripes::focuspathes« and »gstripes::focuscircles«. TkPath is required for using focuspathes and focuscircles.

White Space is created by the »gstripes::stripes« and »gstripes::adjust« functions. Both functions can be substituted by defining the option database entries »stripesCommand« and »adjustCommand«. Thus white space of any kind can be used within gstripes.

Controls, passive such as label an message, active such as button, radiobutton, ... are absorbed by gstripes through hijacking. A hijack function exists for each supported control such as »hijackbutton« for »Button« controls. These hijack functions are not to be used directly but rather through the general function »hijackwindow«.

A special gstripes feature are »groups« and »contours«. A contour is created from a combination of overlapping »frame« windows. Boolean operations (+ and -) can be used for contours. Holes are not supported.

groups are created from active controls: button, menubutton, radiobutton and checkbutton. radiobutton and checkbutton must not have an indicator for being used as part of a group.

A somewhat special case are striped menus. Menus are themselve white space but treated by gstripes as an active control. radiobutton and checkbutton, inside of menus, are rendered identical to their indicator based dialog counterpart.

Menu hijacking is only possible under X11.

The radiobutton and checkbutton indicators can be replaced with a »vector«. This vector is defined for the individual radiobutton, checkbutton via the option database entry »indicatorVector«.

Example A.24. Indicators

option add *Grefadvance$w(6).indicatorVector
  {gstripesvector::triangleButton}
option add *Grefadvance$w(8).indicatorVector
  {gstripesvector::triangleButton}

The above Example A.24, “Indicators” , from the »grefadvance« template, replaces the standard checkbutton indicator –a checkmark – with a triangle button. This »triangleButton« is used to represent visual disclosure. The vector »triangleButton« also contains a »focusframe« element for highlighting.

The option database entry indicatorVector is also applied on striped menus, but cannot being used for an individual menu entry–menu entries do not have access to the option database.

TkPath

TkPath 0.2:
Most –if not all– of gstripes effects require an elaborated graphical subsystem. The chosen subsystem is TkPath, which must have version 0.2.4, better higher than 0.2.7. Which also means Tk 8.5 is mandatory, too – sorry for this. Under X11 CAIRO, too.
TkPath 0.3.0 and caché:
There are changes necessary for using TkPath 0.3.0; these changes are ➊ import of tkp::canvas into the gstripes namespace and ➋ an entirely new caching strategy for gradients.The module gcache is used for this new caché strategy. Originally, gcache used a global strategy for caching, this mechanism is changed to ➌ a local base variety. Another issue though: ➍ the used caché must be deleted whenever the gstripes window is ➎ destroyed –the caché must not survive the associated window.
Gradients:
TkPath 0.3 and 0.2 gradients are partly incompatible. Gstripes will support global gradients from TkPath 0.2 as long as possible. TkPath 0.2 can be used under Tk 8.4 and moving entirely to TkPath 0.3 means to abandon Tk 8.4, too –which I don’t want right now. This means there are four (4) different »gradient« varieties. The TkPath 0.2 starts with a »fixme« to warn about such duplications. The alternating versions are dedicated to AQUA® or X11, respectively.

Open Issues

How is it possible to alter the selectColor for menubutton, button, checkbutton and radiobutton when a dialog is deactivated?
Replacing »Control«, »Alt«, »Meta«, »Shift« inside of menu short-cuts does not work. Unicode related issue in Tk. Implemented but disabled.

Window Command

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

pathName option ?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:

pathName cget option

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

pathName configure ?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 gstripes command.

pathName deactivate ?color? ?opacity?

Cover the stripes window with a semi-transparent sheet. To indicate that this dialog is no longer accessible. See also goolbar, activate. See Open Issues.

pathName hijackmenubutton window x y wd hg ?grouped?

Undocumented.

pathName traced window an idx action ...

Trace handler for checkbutton and radiobutton kind of controls.

The variable might being used as part of a radiobutton group, in which instance the event handler must be used to notify all related responders for this variable. The unconventional Expose event is being used for this purpose.

pathName isGradientMissing gradient

Test whether the expected gradient was destroyed. Return 1, when a gradient is expected but not available.

pathName modifyGroup path1 sorted

OBSOLETE! DO NOT USE

Does modify the coordinates of a group. A group is defined by its outer items. The inertia is drawn from the individual item. First and last are used to draw the control itself. Both require new focus frames, too.

The complexity of groups exceed the ability of »modifyGroup« Using »modifyGroup« will yield a disected group.

Consequently group modification is also removed from the »hijackwindow« function. Which leaves the direct operation from the general event-handler (configure). Internal modifications have thus to be accompanied with a hijackgroup call, to reflect those changes inside the group presentation.

pathName check window

Changes the visual state of the item to resemble a pressed button. The way how pressed is done depends on the state model selected for the »window«.

Applies for menubutton, button and checkbutton, radiobuttons inside of »groups«.

pathName hijackgroup ...

A Group is a collection of button, checkbutton and radiobutton treated as a single control. The outer elements do receive rounded corners while the inner elements are square. Images (and later compound???) are allowed for grouped elements! Images are left alone.

Pimage, which provides scaling, is to limited anchor-wise for being used, here. In addition, activeImage & disabledImage are definable from the option database. Scaling is a gut turning thing for groups anyway. Using the normal image with activeImage and disabledImage is the better way for doing this.

In cases when this button is part of a group and if it is the first one (path1) it is required to move the caption with hl and borderwidth to the right. Ditto for the last item, but to the left.

For groups, not managed by their parent window, an »update idletask« call is needed. In order to get the proper (real) position! This is specified for the first group element, which need not to be the »groupleader«. Option database entry »update« set to »1« (true) causes it.

pathName groupitemsize path1 pathn x wd hl bd

Realign the items inside of a group, so that text and space is even distributed among the group members.

pathName checkmark window l t r b type opacity selected t1 ?state? ?tags?

Draws a checkbutton indicator.

pathName repair

Call the »repairCommand« when registered And report the repair result back to the caller.

Currently only used by stripesmenu. Intended to repair selection failures.

pathName left window

...from leave. Left is called in response to an enter event. That is when another control receives the input focus left is executed. This delay is needed in order to prevent flicker effects with layered graphical objects –belonging to the same control. left may also being triggered due to a after timer event.

pathName adjust ?canvas?

Do call adjust each time the window gets visible. Only the stripes should be aligned, not the hijacked or individual stuff. Also the modulo value must be definable. As "moduloY"" and "moduloX" inside the option database.

See also »leftborder«.

Extended with local caché strategy, needed by tkpath 0.3.0.

pathName shadow window bbox tags ?state? ?radius?

A control may feature a shadow. Shadows are only allowed for groups, menubuttons, buttons if the control in question has rounded corners and shadow is activated for it.

See hijackprototype, hijackgroup and modifyGroup.

pathName bindings window tag ...

Create the bidirectional bindings for the »window« and its stripes imposter –identified via »tags«.

An »unmap« event is being added, unmap is used to remove any resedue of that window from gstripes. »unmap« is activated by the ».unmap« option database entry set to 1 (true).

Normally no unmap should being monitored for a given window –is unnecessary. Only windows with visual disclosure shall use this feature.

Motion event is cruical for menubutton, apparently selecting the internal menu structure originates from the menubutton and not from the menu. Hijacking the motion event lay lead to a deadlock inside of global grabed dialogs.

pathName hijackmenu menu

Creates a striped menu from the »menu« in question. »menu« must be the real window, that is a clone when it is part of a menubar. hijackmenu iterates over the menuentries and creates striped representations for each entry.

pathName radiomark window l t r b type opacity selected t1 ?state? ?tags?

Draws a Radio indicator. This is a circle using an radial gradient. If »window« is selected, then the selecColor is used for the indicator background and an opaque inner circle is drawn to indicate selection.

Radio and Check- indicators are only allowed for stand alone controls. In truth they must have an indicator.

Local caché strategy using gcache.

pathName hijacklabel window x y wd hg

Same as hijackmessage, but supports »state«.

pathName alienhijack template ...

Replacement for »hijack« see description at »hijack«. The procedure »alienhijack« allows the hijacking of alien templates, that is the the stripes window need not to be part of the templates hierarchy.

pathName isSelected window

Test whether or not the item is selected. The procedure returns false if the associated variable does not, yet, exist.

pathName hijackimage window x y

Externalize the hijacking of images. can be used inside hijackprototype and label.

This code is currently unused (no need). Has to be used directly.

pathName mapevent ...

Formats the proper event handler for the Map Event. Hijacked windows must be reevaluated whenever the template is remapped.

pathName hijackmenuentry menu i height iwidth iheight

Hijack a menu entry of »menu« given by it's index »i«. The Height »height« is used to position the text where it belongs.

Used by »stripesmenu«.

pathName keyboard menu accelerator

Shift-Option-Command-x There is some trouble with UTF-8, CAIRO and tkpath, therefore not used, yet.

Default glyphs from »gestalt.ttf«:

option add *Menu.keyboardfont {gestalt}
option add *Menu.controlkey  b
option add *Menu.optionkey   d
option add *Menu.shiftkey    r

Default glyphs from AQUA®:

option add *Menu.keyboardfont {apple symbols}
option add *Menu.controlkey  ⌃
option add *Menu.optionkey   ⌥
option add *Menu.shiftkey   ⇧

Not implemented, yet:

option add *Menu.deletekey   ⌫
option add *Menu.Upkey      ↑
option add *Menu.downkey    ↓
option add *Menu.leftkey    ←
option add *Menu.rightkey   →
option add *Menu.homekey    ↖
option add *Menu.endkey     ↘
option add *Menu.pageupkey   ⇞
option add *Menu.pagedownkey ⇟
option add *Menu.cascade     ▸

pathName menuindy menu i tx y width height