Class ::tycho::Slate


Inherits: ::tycho::TWidget - Related constructs - Source File - Contents: public methods - protected variable
The slate is a widget based on the Tk canvas that support "complex" items, each of which can contain many "simple" canvas items. All methods of the Slate can manipulate either simple or complex items more-or-less transparently.

This is a total re-write of the earlier design. In this new design, complex items are not represented by [incr Tcl] objects, but by an associative array containing just enough information to allow hierarchical item construction and object-oriented-like item manipulation.

In addition to the Slate class itself, there are a number of other classes that work with the slate to implement its full functionality. These classes are grouped into several categories, according to their function in the slate:

To create a slate, do not call the constructor directly, but call the procedure ::tycho::slate:

    ::tycho::slate .s
    pack .s -fill both -expand on
    wm deiconify .

The Slate class is designed to be fully compatible with the canvas, so some of the methods are less efficient than they could be. We are considering writing a second class which will provide a faster interface for code that doesn't need backwards compatibility.


Public constructs

Public Methods

addtag add searchSpec args
Add a tag to specified items. Uses find to get all relevant items, and then tags them; optimized for some special cases.
aspect id args
Return the value of one or more "aspects" of an item. An aspect is a point on the complex item, such as its center or north-east corner. The returned value is a list of coordinates, two (x and y) for each given aspect.

The aspects supported depends on the type (or more specifically, the shape type -- see the type method) of the complex item. Some item types will support a more complex set of aspects. If the complex item is rectangular, is supports at least the aspects c or center, and the eight compass points: n, s, e, w, ne, nw, se, and sw. If the -region option is given, these aspects will be assumed regardless of the complex item's actual shape, and will denote the corners of the complex item's region (see the region method).

If there are no arguments, return the list of valid aspects for this complex item.

bbox args
Return the bounding box of any number of items, as a four-list. Each argument can be an item or a tag. If there are no items matching the tags, return the null string -- the caller must check for this condition. (This behavior matches that of the canvas).
bind id {sequence {}} args
Bind a command to an item, complex item, or tag. The command accepts the following argument formats:

Caveat: The bind command dpes not work properly on hierarchical complex items yet. There are some interactions with canvas bindings, multiple bindings on the same tag/object, and hierarchical complex items that need to be explored and clarified.

call id method args
Call a "method" on an item. This just looks up the method in the global "virtual function table" and calls it.

In the Slate code itself, this method is called in non-critical situations; in time-critical situations, the (very obscure) code here is "in-lined.".

canvasx screenx {gridspacing {}}
Convert a screen x coordinate into a canvas x coordinate.
canvasy screeny {gridspacing {}}
Convert a screen y coordinate into a canvas y coordinate.
coords id args
Get or set the coordinates of an item. If the argument is a tag, perform this operation on the first item on the slate returned by `find withtag'.
component id args
Access a component of a complex item. Items only support components if they have been explicitly declared as such in the "components" variable in the complex item class.

With one argument, return the names of the components of this complex item. With two arguments, return the specified component. With more than two arguments, call the specified method on the component and return its result.

Since this method shadows the default itk method of the same name, this one checks for the argument "canvas" and returns the canvas name if it matches -- using component to access the canvas inside the slate thus still works as expected.

Note: The first argument cannot be an arbitrary tag.

FIXME: The bulk of this method should probably be moved into the Picture class.

create type args
Create an item. If the type arg starts with a lower-case letter, create an item; if not, create a complex item. In either case, args is the coordinates and options used to create the complex item. See the canvas documentation for primitive canvas items; see the href="../../../complex items/doc/codeDoc/index.html">complex items hierarchy for complex items implemented by the slate. If the options include -tag with tags returned by calling gettags on a complex item, the new item will be added to that complex item.
dchars id first {last {}}
Delete characters.
delete args
Delete items.
describe id args
Return a description of an item on the canvas. This description will be understood by recreate so that the item can be recreated or duplicated later in various forms. Do not make any assumptions about the contents of the string returned by this method.

Note: If saving the description for later recreation, you may also need to save other information about the complex item, such as its type or whether it has certain tags that affect how you will recreate it.

describe accepts the following optional arguments:

FIXME: -hierarchical and -constraints options do nothing.

dtag tag {tagToDelete {}}
Delete tags from items. If delete is not given, delete tag from all items; if it is, delete the tag delete from all items tagged with tag.
find searchSpec args
Find a items, as given by searchSpec. The argument formats are the same as for the Tk canvas; however, because of hierarchy, the behavior for the different search modes differ from each other. As a general rule, the slate does not attempt to deal with hierarchy, but blindly returns a set of complex items and items -- the caller must eliminate unwanted parents or children explicitly (see the complex item method). The following argument formats are supported:

.
focus args
Focus on an item.
focusin
Put the focus into the canvas. This is needed for explicit focus control: there seems to be no way to detect that the focu command has been called with a megawidget as an argument, so instead of calling
    focus $slate
you need to call
    $slate focusin
.
gettags id
Returns the tags of an item. The slate does not attempt to hide its internal tags, so they are all returned by this method in addition to any "user-specified" tags. If the argument is a tag, perform this operation on the first item on the slate returned by `find withtag'.
icursor id index
Set the insertion cursor.
index id index
Return the numerical value of a symbolic index.
insert id beforeThis string
Insert text at the insertion cursor.
interact command item args
Interact with items.
itemcget id option
Read a configuration option. If the argument is a tag, perform this operation on the first item on the slate returned by `find withtag'.
itemconfigure id args
Set configuration option. If the argument is a tag, perform this operation on the first item on the slate returned by `find withtag'.

Note also that dtag, gettags, and addtag are faster (and safer) ways of manipulating tags and should be used in preference to itemcget and itemconfigure.

lower id {belowThis {}}
Lower the specified complex items to the bottom of the display list. If belowThis is specified, then lower below that item, or if belowThis is a tag, then lower below the first item with that tag.

FIXME: I am by no means certain that this works correctly!

move tag xAmount yAmount
Move one or more items the specified amount. The first argument can either be a tag or an id.
moveto tag x y {aspect center}
Move one or more complex items to an absolute location. The point of the complex item that is moved to the specified location is specified by the fourth argument, the aspect. If omitted, this argument defaults to center.

If a tag is specified and the tag denotes more than one complex item, then the complex items are moved so that the indicated point on the region covered by those complex items is at the specified location.

picture mode args
Manipulate complex items. This is a "safe" interface to some of the complex item manipulation methods used within the slate.

Note: The functionality of the method is still evolving, and much of it may end up in other methods, such as component.

postscript args
Generate postscript.
raise id {aboveThis {}}
Raise the specified complex items to the top of the display list. If aboveThis is specified, then raise above that item, or if aboveThis is a tag, then raise above the first item with that tag.

FIXME: I am by no means certain that this works correctly!

recreate description args
Re-create a complex item from a description returned by describe. By default, the complex item will be created in exactly the same position as when describe was called, and without any hierarchy. A number of options can modify this behavior (these options do not have to be used, but are really just short-cuts to save other calls:

-move, -at and -coords are mutually exclusive.

region id args
FIXME: Not working yet.

FIXME: Be sure to give Picture classes the chance to override.

scale id xOrigin yOrigin xScale yScale
FIXME: Won't work if first argument is a tag!!!
scan option args
Scanning on an item.
select option {id {}} {index {}}
Manipulate the selection.
type id args
Return the type of an item. Note that types are case-sensitive.

With the -shape option, return the "shape" of the complex item. The value returned is a subset of the types.

xview args
Set the horizontal view for scrolling.
yview args
Set the vertical view for scrolling.

Protected constructs

Protected Variable

canvas
The canvas on which I draw.

Index of classes



Author: H. John Reekie
Version: @(#)Slate.itcl 1.52 12/16/96
Copyright: (c) 1996 The Regents of the University of California.