This reference manual describes the complete Tcl API to Pad++. It describes how to create and modify a pad widget, and all the commands associated with a pad widget that allow you to create and modify items, attach event bindings to them, navigate within the pad widget, etc.
This document in organized into the following sections:
Each section contains all the relevant entries in alphabetical order. Related commands and options are also grouped together here to show which commands are related. Every command and itemconfigure option are listed.
|
Index | |||
|---|---|---|---|
allocimage[8]
Allocate data for an image item
create
[17] Create
new items
delete [19]
Delete existing items
find[27]
Search for items by various keys
freeimage [31]
Free data from an image item
itemconfigure[47]
Configure existing items
lower[49]
Push an item lower in the drawing order
pick[53]
Find the item under a point
popcoordframesc[54]
Pop a relative coordinate frame off of the stack
pushcoordframe[56]
Add a new relative coordinate frame to the stack
raise[57]
Bring an item higher in the drawing order
resetcoordrame[61]
Reset coordinate frame stack to empty
setid[67]
Change the id of an item
text[76]
Modify text item
type [78] Get
the type of an item
-arrow [78]
Some items only: Whether to draw arrow heads with this item
-arrowshape[52]
Some items only: The shape of drawn arrow heads
-dither [47]
Some items only: Render with dithering
-file[87]
Some items only: File an item should be defined by
-height[6]
Height of an item. Normally computed automatically, but can be set
-html [43]
Some items only: The HTML item associated with an htmlanchor
-htmlanchors[38]
Some items only: The anchors associated with an HTML page
-image[48]
Some items only: Image data associated with item (allocated by
allocimage)
-info[7]
A place to store application-specific information with an item
-ismap[44]
Some items only: True if an htmlanchor is an image map
-lock[9]
Locks an item so it can not be modified or deleted
-state[45]
Some items only: State of an item (such as visited, unvisited,
etc.)
-sticky [14]
Specifies if an item should stay put when the view changes
-title[70]
Some items only: Title of an item
-url[41]
Some items only: The URL associated with an item
-width[21]
Width of an item. Normally computed automatically, but can be set
-zoomaction[24]
A script that gets evaluated when an item is scaled larger or
smaller than a set size
bbox [9] Get
the bounding box of an item
coords[16]
Change the coordinates of an item
getsize [39]
Get the size of an item (possibly within portals)
scale[62]
Change the size of an item relatively
slide[74]
Move an item relatively in (x, y)
-anchor[2]
The part of the item that -place refers to
-place[12]
Transformation of an item - Translation (x, y), and magnification
(z)
-x[22]
X componenent of -place transformation
-y[23]
Y componenent of -place transformation
-z[25]
Z componenent of -place transformation
center[12]
Change the view so as to center an item
centerbbox[13]
Change the view so as to center a bounding box
getview[42]
Get the current view (possibly within portals)
moveto[50]
Change the view (possibly within portals)
zoom [83] Zoom
the view around a specified point
-viewscript
[19] A script that gets
evaluated whenever the view is changed
-view[71]
Some items only: Specifies the view this item sees
-lookon[67]
Some items only: Specifies the pad widget this item sees
addtag [4] Add a
tag to an item
deletetag[19]
Delete a tag from an item
dtag [19]
Synonym for deletetag
gettags[40]
Get the tags an item has
hastag[44]
Determine if an item has a particular tag
-tags[15]
List of tags associated with an item
addmodifier[2]
Add a new user-defined modifier for future use
bind[10]
Create, modify, access, or delete event bindings
bindtags[11]
Specify whether events should go to the most-specific or
most-general description
deletemodifier[20]
Delete a user-defined modifier
setmodifier[71]
Make the specified user-defined modifier the current one
-events [4]
True if item receives events, false otherwise
addgroupmember[1]
Add an item to a group
getgroup[33]
Get the group an item belongs to
removegroupmember[59]
Remove an item from a group
-divisible
[26] True if events go through
a group to its members
-members[28]
The list of members of a group
grid[43]
Layout pad items in a grid as with the Tk grid command
tree [77]
Layout pad items with a dynamic graphical-fisheye view tree
damage [18]
Specify that a group of items needs to be redrawn
update[79]
Force any requested render requests to occur immediately
-alwaysrender
[1] True if the item must be
rendered, even if the system is slow and the item is small
-border[31]
Some items only: Specifies border color of item
-borderwidth
[32] Some items only: Specifies
width of border
-capstyle[53]
Some items only: Specifies how to draw line ends
-faderange[5]
Range over which an item fades in or out
-fill [29]
Some items only: Specifies fill color of item
-font [37]
Some items only: Specifies font to use for text
-joinstyle[54]
Some items only: Specifies how to draw the joints within
multi-point lines
-layer[8]
The layer an item is on
-noisedata
[55] Some items only: Specifies
parameters to render item with noise
-maxsize [10]
The maximum size an item is rendered it (absolute or relative to
window size)
-minsize [11]
The minimum size an item is rendered it (absolute or relative to
window size)
-pen [30] Some
items only: Specifies pen color of item
-penwidth [57]
Some items only: Specifies width of pen
-relief[69]
Some items only: Specifies how a border should be rendered
-transparency[18]
Transparency of an item. 0 is completely transparent, 1 is
completely opaque
-visiblelayers[58]
The layers that are visible within this view (just for portals and
pad surface, item #1)
read[58]
Read a .pad file
write[82]
Write a .pad file (all the items on a widget)
configure[15]
Modify the pad widget
info[45]
Get type-specific information about an item
islinked [46]
Determine if the top-level window that a pad widget is in has been
mapped yet
setlanguage[69]
Set the language to be used for future calback scripts
settoplevel[72]
Set the language to be used by the top-level interpreter
windowshape[81]
Modify the shape of the top-level window that a pad widget is in
clock[14]
Create a clock to measure elapsed milliseconds
getdate [32]
Get the current date in unix format
getpads [37]
Get a list of all pad widgets currently defined
line2spline[48]
Generate points for a spline that approximate a line
noise[51]
Generate 'perlin' noise
padxy[52]
Convert a window point (x, y) to pad coordinates
spline2line[75]
Generate points for a line that approximate a spline
urlfetch[80]
Retrieve a URL over the internet in the background
-donescript[34]
Some items only: A script to evaluate when a background action has
completed
-errorscript
[35] Some items only: A script
to evaluate when a background action has an error
-updatescript
[40] Some items only: A script
to evaluate when a background action has made progress
allocborder[6]
Allocate a border for future rendering
alloccolor[7]
Allocate a color for future rendering
allocimage [8]
Allocate a image for future rendering
drawimage [23]
Draw an image within a renderscript
drawline[24]
Draw a line within a renderscript
drawpolygon
[25] Draw a polygon within a
renderscript
drawtext [26]
Draw text within a renderscript
freeborder [29]
Free a border previously allocated
freecolor
[30] Free a
color previously allocated
freeimage[31]
Free an image previously allocated
getlevel [34]
Get the render level within a renderscript
getmag[35]
Get the current magnification within a renderscript
getportals[38]
Get the list of portals being rendered within during a
renderscript
gettextbbox[41]
Get the bounding box of a text string
renderitem[60]
Render an item in a render callback
setcapstyle[63]
Specify how the end caps of lines should be drawn
setfont[65]
Specify the font to be used for renderscript drawing
setfontheight[66]
Specify the font height to be used for renderscript drawing
setjoinstyle[68]
Specify how the joints within multi-point lines should be drawn
setlinewidth[70]
Specify the penwidth of lines when they are drawn
-renderscript[13]
A script that gets evaluated every time an item is rendered
-bb
[50] A
script that gets evaluated to specify the bounding box of an item
printtree[55]
Print all the items on the pad surface in their internal tree
structure
addoption [3]
Create a new option for an existing type
addtype[5]
Create a new item type
When Pad++ is built and installed correctly, there are two
executable files that may be run. padwish runs a version of
the Tcl interpreter extended with the pad widget. This is a complete
superset of the standard Tk wish program. The pad
command is the sole addition which is described below. In addition,
the Pad++ distribution comes with an application written entirely in
Tcl called PadDraw. This application is a general-purpose drawing and
demo program that shows many capabilities of the pad widget. PadDraw
is started by running the pad script which automatically runs
padwish and starts the Tcl program. When running PadDraw by
executing pad, the Tcl interpreter is not available.
padwish [options] [arg arg ...]
Valid options are:
-display display
- Display (and screen) on which to display window.
-geometry geometry
- Initial geometry to use for window.
-name name
- Use name as the title to be displayed in the window, and as the name of the interpreter for send commands.
-sync
- Execute all X server commands synchronously, so that errors are reported immediately. This will result in much slower execution, but it is useful for debugging.
-colormap colormap
- Specifies the colormap that padwish should use. If colormap is "new", then a private colormap is allocated for padwish, so images will look nicer (although on some systems you get a distracting flash when you move the pointer in and out of a PadDraw window and the global colormap is updated).
-visual visual
- Specifies the visual type that padwish should use. The valid visuals depend on the X server you are running on. Some common useful ones are "truecolor 24" and "truecolor 12", which specify 24 bit and 12 bit mode, respectively.
-language
- Specifies what scripting language the top-level interpreter should use. Pad++ always supports Tcl, but can be compiled to use the Elk version of Scheme also. In addition, Pad++ provides a mechanism to support other interpreted scripting languages as well. Defaults to 'tcl'.
-sharedmemory
- Specifies if Pad++ should try and use X shared memory. Some machines (notably a particular Solaris 5.4 machine) crashes and the X server dies when Pad++ is used with shared memory, so it can be disabled if there is trouble. Defaults to 1 (true).
-help
- Print a summary of the command-line options and exit.
--
- Pass all remaining arguments through to the script's argv variable without interpreting them. This provides a mechanism for passing arguments such as -name to a script instead of having padwish interpret them.
pad [pathName [options]]
The pad command creates a new window (given by the
pathName argument) and makes it into a Pad++ widget. If
no pathName is specified, a unique top-level window name
will be generated. Additional options may be specified on the command
line or in the option database to configure aspects of the Pad++. The
pad command returns the name of the created window. At
the time this command is invoked, there must not exist a window named
pathName, but pathName's parent must exist.
Once a Pad++ widget is created, there are five ways of writing Tcl code for it. They are:
-width and -height control the
geometry of the widget.
pad .pad creates a widget named
.pad, and a command named .pad. For
example, to find out what the current view on the pad widget is,
use the getview command with: .pad
getview.
create sub-command. For example,
.pad create line 0 0 10 10 creates a line from the
origin to the point (10, 10).
itemconfigure
sub-command. For example, supposing that the previous line had an
id of 2, we could change its pen color and width with: .pad
itemconfigure 2 -pen red -penwidth 5
This version of Pad++ works only with Tcl7.5/Tk4.1.
Note that in this reference manual, optional parameters are listed in square brackets, [...]. While this is traditional for reference documentation, the Tcl/Tk documentation uses ?...? to denote optional parameters in order to avoid confusion with the meaning of [...] in the Tcl language. We decided to risk the confusion with Tcl for the increased clarity of square brackets.
background
Background
-background
.pad config -background gray50
closeEnough
CloseEnough
-closeEnough
colorCubeSize
ColorCubeSize
-colorCubeSize
cursor
Cursor
-cursor
debugBB
DebugBB
-debugBB
debugEvent
DebugEvent
-debugEvent
debugGen
DebugGen
-debugGen
debugOut
DebugOut
-debugOut
.pad config -debugOut
foo" will cause all future debug output to be appended
to the Tcl variable 'foo'.
debugRegion
DebugRegion
-debugRegion
debugstat
DebugStat
-debugstat
defaultRenderLevel
DefaultRenderLevel
-defaultRenderLevel
desiredFrameRate
DesiredFrameRate
-desiredFrameRate
-alwaysrender) flag, and some objects may be
rendered at low resolution. The default is 20 frames/second.
dissolveSpeed
DissolveSpeed
-dissolveSpeed
doubleBuffer
DoubleBuffer
-doubleBuffer
enableOpaque
EnableOpaque
-enableOpaque
fastPan
FastPan
-fastPan
fontCacheSize
fontCacheSize
-fontCacheSize
gamma
Gamma
-gamma
height
Height
-height
heightmmofscreen
HeightMMOfScreen
-heightmmofscreen
interruptible
interruptible
-interruptible
maxZoom
MaxZoom
-maxzoom
refinementDelay
RefinementDelay
-refinementDelay
sync
Sync
-sync
units
Units
-units
width
Width
-width
widthmmofscreen
WidthMMOfScreen
widthmmofscreen
The pad command creates a new Tcl command whose name
is pathName. This command may be used to invoke various
operations on the widget. It has the following general form:
[1] pathName addgroupmember
[-notransform] tagOrId groupTagOrId
removegroupmember, and getgroup
commands). Returns an empty string.
- .pad addgroupmember $id3 $gid
- .pad ic $gid -members
- 254 255 266
- .pad removegroupmember $id0 $gid
- .pad ic $gid -members
- 255 266
- .pad getgroup $id2
- 256
[2] pathName addmodifier
modifier
deletemodifier, setmodifier,
getmodifier, and bind commands).
[3] pathName addoption
[-nowrite] typename optionname optionscript default
- Add a new option (named optionname) to all objects of type typename. typename must either be a built-in type, a user-defined type previously defined by
addtype, or the special word "all" which means that this option applies to all types. When optionscript is called, the following arguments will be added on to the end of the script:- pathName: The name of the pad widget the item is on
- item: The id of the item being configured
- [value]: Optional value. If value is specified, then the option must be set to this value.
- optionscript must return the current (or new) value of the option. default specifies the default value of this option. This is used to determine if the option should be written out when the
writecommand is executed. Note that the option will only be written out if the value is different than the default. If -nowrite is specified, then this option won't be written out. See the section APPLICATION-DEFINED ITEM TYPES AND OPTIONS in the Programmer's Guide for more information. (Also see theaddtypecommand.)
[4] pathName addtag tagToAdd
tagOrId ...
eval .pad addtag foo [.pad find withtag
bar]
[5] pathName addtype
typename createscript
- Add typename to the list of allowed user defined types. When a new object of type typename is created, the createscript will be evaluated, and it must return an object id. When createscript is evaluated, the pad widget the object is being created on will be added on as an extra argument, followed by any parameters before the options. See the section APPLICATION-DEFINED ITEM TYPES AND OPTIONS in the Programmer's Guide for more information. (Also see the
addoptioncommand.)
[6] pathName allocborder
color
- Allocates a border for future use by render callbacks. A border is a fake 3D border created by a slightly lighter and a slightly darker color than specified. Color may have any of the forms accepted by Tk_GetColor. (Also see the
freeborderanddrawbordercommands).
- Allocates a color for future use by render callbacks. Color may have any of the forms accepted by Tk_GetColor. (Also see the
freecolorandsetcolorcommands).
[8] pathName allocimage file
[-norgb]
- Allocates an image for future use by image objects and render callbacks. file specifies the name of a file containing an image.
allocimagecan always read gif file formats. In addition, if Pad++ is compiled with the appropriate libraries,allocimagecan also read jpeg and tiff image file formats, and will automatically determine the file type. Normally, images are stored internally with their full rgb colors in addition to a colormap index. This allows images to be rendered with dithering, but takes 5 bytes per pixel. If the -norgb option is specified, then the original rgb information is not stored with the image and the image can not be rendered with dithering, but only takes 1 byte per pixel. The image may have transparent pixels. This returns an image token which can be used by related commands. (Also see thefreeimage,drawimage, andinfocommands, and the description ofimageitems.).
[9] pathName bbox [-sticky]
tagOrId [tagOrId tagOrId ...]
- Returns a list with four elements giving the bounding box for all the items named by the tagOrId argument(s). The list has the form "x1 y1 x2 y2" such that the drawn areas of all the named elements are within the region bounded by x1 on the left, x2 on the right, y1 on the bottom, and y2 on the top. If -sticky is specified, then the bounding box of the item in sticky coordinates, that is, the coordinates of a sticky item that would appear at the same location on the screen is returned. If no items match any of the tagOrId arguments then an empty string is returned.
- If the item is sticky then
bboxreturns the bounding box of the item as it appears for the current view. That is, the bounding box will be different when the view is different. If -sticky is specified, then the bounding box returned is independent of the current view (i.e., it returns the bounding box as if the view was "0 0 1").- If the item is the Pad++ surface (item #1), then
bboxwill refer to the bounding box of the portion of the surface that is currently visible (based on the view and window size).
- .pad bbox 27 37
- -75 -55 68 79
[10] pathName bind
tagOrId [sequence [command]]
- This command associates command with all the items given by tagOrId such that whenever the event sequence given by sequence occurs for one of the items the command will be invoked.
- This widget command is similar to the Tk bind command except that it operates on items on a Pad++ widget rather than entire widgets. See the Tk bind manual entry for complete details on the syntax of sequence and the substitutions performed on command before invoking it. The Pad++ widget defines extensions described below, but it is implemented as a complete superset of the standard
bindcommand. I.e., you can do everything you can with the canvas with exactly the same syntax, but you can also do more.- If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagOrId (if the first character of command is "+" then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If both command and sequence are omitted then the command returns a list of all the sequences for which bindings have been defined for tagOrId.
- The only events for which bindings may be specified are those related to the mouse and keyboard, such as Enter, Leave, ButtonPress, Motion, ButtonRelease, KeyPress and KeyRelease. In addition, Pad++ supports some extra bindings including: Create, Modify, Delete, PortalIntercept, and Write. The handling of events in Pad++ uses the current item defined in Item IDs and Tags in the Programmer's Guide. Enter and Leave events trigger for an item when it becomes the current item or ceases to be the current item; note that these events are different than Enter and Leave events for windows. Mouse-related events are directed to the current item, if any. Keyboard-related events are directed to the focus item, if any (see the
focuscommand below for more on this).- It is possible for multiple bindings to match a particular event. This could occur, for example, if one binding is associated with the item's id and another is associated with one of the item's tags. When this occurs, all of the matching bindings are invoked. The order of firing is controlled by the pad
bindtagscommand. The default is that a binding associated with the all tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. If there are multiple matching bindings for a single tag, then only the most specific binding is invoked. Acontinuecommand in a binding script terminates that script, and abreakcommand terminates that script and skips any remaining scripts for the event, just as for thebindcommand.- If bindings have been created for a
padwindow using the Tk bind command, then they are invoked in addition to bindings created for the pad's items using thebindwidget command. The bindings for items will be invoked before any of the bindings for the window as a whole.- The Pad++ bind command is extended in three ways:
- Extra macro expansions are added
- New events are added: <Create>, <Modify>, <Delete>, <Write>, and <PortalIntercept>.
- User-specified modifiers are added
- Extra macro expansions
- When a command is invoked, several substitutions are made in the text of the command that describe the specific event that invoked the command. In addition to the substitutions that the Tk
bindcommand makes, Pad++ makes a few more. As with the Tk bind command, all substitutions are made on two character sequences that start with '%'. The special Pad++ substitutions are:
- %P: The pad widget that received the event. This is normally the same as %W, but could be different if the event goes through a portal onto a different pad widget.
- %O: The id of the specific item that received the event.
- %I: Information about this event. This has different meanings for different event types. For
<Modify>events, it specifies the command that caused the modification. For<PortalIntercept>events, it specifies the name of the event type generating the PortalIntercept. Standard Tcl event names, such as ButtonPress or ButtonRelease are used. This can be used by PortalIntercept events to only let certain event types go through the portal. Note that only a single PortalIntercept event is generated for a Button, Motion, ButtonRelease sequence, so these three events can not be distinguished in this manner.- %i: The X-coordinate of the event on the Pad++ surface. This is specified in the current units (i.e., pixels or inches) of the pad widget.
- %j: The Y-coordinate of the event on the Pad++ surface. This is specified in the current units (i.e., pixels or inches) of the pad widget.
- %z: Size of event in pad coordinates. This is dependent on the view. It effectively says how much the event is magnified. I.e., if the view is zoomed in by a factor of two, then this will have a value of two. It is also affected by portals that the event travels through.
- %U: The X-coordinate of the event in object coordinates. This means that the point will be transformed so that it is in the same coordinate system of the object (independent of the object's transformation as well as the current view). This is specified in the current units (i.e., pixels or inches) of the pad widget.
- %V: The Y-coordinate of the event in object coordinates. This means that the point will be transformed so that it is in the same coordinate system of the object (independent of the object's transformation as well as the current view). This is specified in the current units (i.e., pixels or inches) of the pad widget.
- %Z: Size of event in object coordinates. This is dependent on the view and the magnifications of the object.
- %l: The list of portal ids that the event passed through.
- %L: The list of pad surfaces of the portals the event passed through. This list corresponds to the list of portal ids from '%l'.
- New Events
- Several new events fire at special times, depending on the semantics of the event.
<create>:This event gets fired whenever new pad items are created. Because items that this is attached to don't have id's yet, it only makes sense to attach this event to a tag. Then this event gets fired immediately after any item of the relevant tag is created. Example:
.pad bind foo <Create> {puts "A foo was created, id=%O"}
.pad create rectangle 0 0 50 50 -tags "foo"
=> A foo was created, id=5
<Modify>:This event gets fired whenever an item is modified. Modification occurs whenever an item's configuration options are changed, and whenever the following commands are executed on an item:coords,itemconfigure,scale,slide,text. The %I macro specifies the command that caused the modification. Example:
.pad bind foo <Modify> {puts "A foo was modified, cmd=%I"}
.pad create rectangle 0 0 50 50 -tags "foo"
.pad itemconfigure foo -pen red
=> A foo was modified, cmd=itemconfigure
<Delete>:This event gets whenever an item is deleted. It is typically used to clean up application resources associated with the item that was deleted.<Write>:This event fires whenever an item is written out with the padwritecommand. While Pad++ knows how to generate the Tcl code necessary to recreate itself, items are often part of an application with associated data structures, etc. When an item is written out, it is frequently necessary to write out these associated structures. Sometimes, the application may prefer to substitute its code for pad's. This event provides a mechanism to augment or replace (possibly with an empty string) the Tcl code written out to recreate a pad item.- Whatever string a
<Write>event returns is appended on to the string pad uses to write out that object. In addition, the application may modify the special global Tcl variable,Pad_Writewhich controls whether the item will get written out. This defaults to 1 (true), but may be set to 0 (false) by the event binding. In addition, the<Write>event gets fired on the special tags "preWrite" and "postWrite" at the beginning and end of the file, respectively, to allow an application to write out code at the ends of the file. Example:- .pad bind preWrite <Write> {
- return "Stuff at the beginning of the file"
- }
- .pad bind postWrite <Write> {
- return "Stuff at the end of the file"
- }
- .pad bind foo <Write> {
- return "Stuff after foo objects"
- }
- .pad bind bar <Write> {
- set Pad_Write 0
- return "Stuff instead of bar objects"
- }
- # This forces all objects with the "cat" tag
- # to have nothing written out. Notice that an
- # empty string must be returned, or "0", the
- # result of the set command, will be written out.
- .pad bind cat <Write> {
- set Pad_Write 0
- return ""
- }
- # This example also has nothing written out,
- # but in addition, no other event handlers
- # will fire (the object could have multiple
- # tags, each with <Write> event handlers).
- .pad bind dog <Write> {
- Set Pad_Write 0
- break
- }
<PortalIntercept>:This event gets fired just before an event passes through a portal. If the event handler executes the break command, then the event stops at the portal and does not pass through. Example:- # Events will not go through portals of type "foo"
- .pad bind foo <PortalIntercept> {
- break
- }
- User-specified modifiers
- Event handlers are defined by sequences as defined in the Tk
bindreference pages. A sequence contains a list of modifiers which are direct mappings to hardware such as the shift key, control key, etc. Event handlers fire only for sequences with modifiers that are active, as defined by the hardware.- Pad++ allows user-defined modifiers where the user can control which one of the user-defined modifiers is active (if any). The advantage of modifiers is that many different sets of event bindings may be declared all at once - each with a different user-defined modifier. Then, the application may choose which set of event bindings is active by setting the active user-defined modifier. This situation comes up frequently with many graphical programs where there are modes, and the effect of interacting with the system depends on the current mode.
- New modifiers must be declared before they can be used with the pad
addmodifiercommand (and may be deleted if they are no longer needed with the paddeletemodifiercommand.) Then, the modifier can be used in the padbindcommand just like a system defined modifier. There may be at most one active user-defined modifier per pad widget. The active user-defined modifier is set with thesetmodifiercommand (and may be retrieved with thegetmodifiercommand). The current modifier may be set to "" (the default) in which case no user-defined modifier is set. Example:- .pad addmodifier Create
- .pad addmodifier Run
- .pad bind all <Create-ButtonPress-1> {
- # Do stuff to create new objects
- }
- .pad bind all <Run-ButtonPress-1> {
- # Do stuff to interact with existing objects
- }
- # Now the system will be in "Create" mode
- .pad setmodifier Create
- ...
- # Now the system will be in "Run" mode
- .pad setmodifier Run
[11] pathName bindtags
tagOrId [type]
- If type is specified, this command changes the ordering of event firings on all objects referred to by tagOrId. Since more than one event handler may fire for a given event, this controls what order they fire in. If type is "general", events fire most generally first. That is, a binding associated with the all tag is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the item's id. (i.e., all, tags, id). If type is "specific", then events fire most specific first. That is, a binding associated with the item's id is invoked first, followed by one binding for each of the item's tags (in order), followed by a binding associated with the all tag (i.e., id, tags, all).
- If tagOrId is pathName, then it does not change the ordering of any objects, but controls the default ordering of objects created in the future.
- The default event firing order for all objects is "general". This command returns the current event firing order for the first item specified by tagOrId.
[12] pathName center
[-twostep] tagOrId [time x y [z [portalID ...]]]]
- Change the view so as to center the first of the specified items so the largest dimension of its bounding box fills the specified amount of screen (z). If -twostep is specified, then make the animation in two steps if appropriate (i.e., points not too close). The two steps are such that it zooms out to the midpoint between the two points far enough so that both start and endpoints are visible, and then zooms to the final destination. If time is specified, then make a smooth animation to the item in time milliseconds. The view is changed so that the item's center appears at the position on the screen specified by x and y, both in the range (0.0 ... 1.0). Here, 0.0 represents the left or bottom side of the window, and 1.0 represents the right or top side of the window. x and y default to (0.5, 0.5), i.e. the center of the screen. If a list of portalID's is specified, change the view within the last one specified.
- .pad center 23
[13] pathName centerbbox
[-twostep] x1 y1 x2 y2 [time [x y [z [portalID ...]]]]
- Change the view so as to center the specified bounding box so that its largest dimension fills the specified amount of screen (
z). If -twostep is specified, then make animation in two steps if appropriate (i.e., points not too close). The two steps are such that it zooms out to the midpoint between the two points far enough so that both start and endpoints are visible, and then zooms to the final destination. If time is specified, then make a smooth animation to the item in time milliseconds. The view is changed so that the item's center appears at the position on the screen specified by x and y, both in the range (0.0 ... 1.0). Here, 0.0 represents the left or bottom side of the window, and 1.0 represents the right or top side of the window. x and y default to (0.5, 0.5), i.e. the center of the screen. If a list of portalID's is specified, change the view within the last one specified.
[14] pathName clock
[clockName [reset | delete]]
- Creates a clock that is set to 0 at the time of creation. Returns the name of the clock. Future calls with clockName return the number of milliseconds since the clock was created (or reset). Calls with reset specified reset the clock counter to 0, and return an empty string. Calls with delete specified delete the clock, and return an empty string.
- .pad clock
- clock1
- .pad clock clock1
- 8125
- .pad clock clock1 reset
- .pad clock clock1
- 1825
- .pad clock clock1 delete
[15] pathName configure
[option] [value] [option value ...]
- Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see
Tk_ConfigureInfofor 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 widget 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 pad command. See the section on WIDGET-SPECIFIC OPTIONS for a description of all the options and their descriptions.
[16] pathName coords
[-objectcoords] [-append] [-nooutput] tagOrId [x0 y0 ...]
- Query or modify the coordinates that define an item. This command returns a list whose elements are the coordinates of the item named by tagOrId. If coordinates are specified, then they replace the current coordinates for the named item. If tagOrId refers to multiple items, then the first one in the display list is used. The flags may be specified in any order. Note that the
coordscommand generates a<Modify>event on the items modified by it (see thebindcommand for a description of the<Modify>event). Locked items may not be modified by the coords command (see the -lock itemconfigure option). Thecoordscommand can only be used on line, rectangle, polygon and portal items.- If the flag -objectcoords is specified, then all coordinates are returned in the item's local coordinate system (i.e., as they were originally specified). If this flag is not specified, then all coordinates are returned in the global coordinate system (i.e., they are transformed by that item's translation and scale parameters).
- If the flag -append is specified, then all the specified coordinates are appended on to the existing coordinates rather than replacing them.
- If the flag -nooutput is specified, then this command returns an empty string. Typically, the -append and -nooutput flags are specified together when adding points to an item and time is of the essence.
set id [.pad create line -200 200]
for {set i -20} {$i <= 20} {incr i} {
set x [expr $i * 10 ]
set y [expr 0.5 * ($i * $i)]
.pad coords -append -nooutput $id $x $y
}
[17] pathName create type
[option value ...]
- Create a new item in pathName of type type. The exact format of the arguments after type depends on type, but usually they consist of the coordinates for one or more points, followed by specifications for zero or more item options. See the OVERVIEW OF ITEM TYPES subsection below for detail on the syntax of this command. This command returns the id for the new item.
[18] pathName damage
[tagOrId]
- Indicates that some of the screen is damaged (needs to be redrawn). Damages the entire screen if tagOrId is not specified, or just the bounding box of each of the objects specified by tagOrId. The damage will be repaired as soon as the system is idle, or when the
updateprocedure is called. Returns an empty string.
[19] pathName delete
tagOrId [tagOrId ...]
- Delete each of the items given by each tagOrId, and return an empty string. Note that the
deletecommand generates a<Delete>event on the items modified by it (see thedeletecommand for a description of the<Delete>event). Locked items may not be modified by thedeletecommand (see the -lock itemconfigure option).
[20] pathName deletemodifier
modifier
addmodifier, setmodifier,
getmodifier, and bind commands).
[21] pathName deletetag tagToDelete tagOrId [tagOrId
...]
dtag is an
acceptable synonym for deletetag. This command returns an empty
string.
eval .pad deletetag foo [.pad find
withtag bar]
[22] pathName drawborder border type width x1 y1 x2
y2
- Draws a fake 3D border connecting the specified coordinates. (See
allocborderandfreebordercommands). This command can only be called within a render callback. Border must have been previously allocated byallocborder. Type must be one of "raised", "flat", "sunken", "groove", "ridge", "barup", or "bardown". The following example creates an object that draws a border:
set border [.pad allocborder #803030]
.pad create rectangle 0 0 100 100 -renderscript {
.pad drawborder $border raised 5 0 0 100 100
}
[23] pathName drawimage
imagetoken x y
- Draws the image specified by imagetoken at the point (x, y). (Also see
allocimage,freeimage,andinfocommands as well as the description ofimageitems). This command can only be called within a render callback.
[24] pathName drawline
x1 y1 x2 y2 [xn yn ...]
- Draws a multi-segment line connecting the specified coordinates. (See
setcolor,setlinewidth, setcapstyle,andsetjoinstylecommands). This command can only be called within a render callback.
[25] pathName
drawpolygon x1 y1 x2 y2 [xn yn ...]
- Draws a closed polygon connecting the specified coordinates. (See
setcolorandsetlinewidth). This command can only be called within a render callback.
[26] pathName drawtext
string xloc yloc
- Draws the specified text at the specified location. This command can only be called within a render callback. (Also see the
setcolor,setfont, andsetfontheightcommands.)
[27] pathName find
[-groupmembers] searchCommand [arg arg ...]
- This command returns a list consisting of all the items that meet the constraints specified by searchCommand and arg's. The objects are returned in display list order, and if -groupmembers is specified, then group members are returned, otherwise, they are not. Note that this command does not return the pad surface (id #1). SearchCommand may take any of these forms:
allReturns all the items on the pad.
below tagOrIdReturns the item just before (below) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the first (lowest) of these items in the display list is used.
closest x y [halo] [startTagOrId]Returns the single item closest to the point given by x and y. If more than one item is at the same closest distance (e.g. two items overlap the point), then the top-most of these items (the last one in the display list) is used. If halo is specified, then any item closer than halo to the point is considered to overlap it. (Halo must be a non-negative number.) If halo is not specified, then only items at the point (x, y) will be found.
The startTagOrId argument may be used to step circularly through all the closest items. If startTagOrId is specified, it names an item using a tag or id (if by tag, it selects the first item in the display list with the given tag). Instead of selecting the topmost closest item, this form will select the topmost closest item that is below start in the display list; if no such item exists, then the selection behaves as if the start argument had not been specified.
withinfo infoReturns all the items containing the string info in their info itemconfigure option.
withlayer layerReturns all the items on the layer layer.
withname nameReturns all the items having name.
withtag tagOrIdReturns all the items given by tagOrId.
withtext textReturns all the items containing text.
withtype typeReturns all the items of type type.
enclosed x1 y1 x2 y2Returns all the items completely enclosed within the rectangular region given by x1, y1, x2, and y2. x1 must be no greater then x2 and y1 must be no greater than y2.
overlapping x1 y1 x2 y2Returns all the items that overlap or are enclosed within the rectangular region given by x1, y1, x2, and y2. x1 must be no greater then x2 and y1 must be no greater than y2.
.pad find withtag selected- 52 72 92
[28] pathName focus
[tagOrId [portalID ...]]
- Set the keyboard focus for the Pad++ widget to the item given by tagOrId. If a list of portalID's are specified, then the item sits on the surface looked onto by the last portal. If tagOrId refers to several items, then the focus is set to the first such item in the display list. If tagOrId doesn't refer to any items then the focus isn't changed. If tagOrId is an empty string, then the focus item is reset so that no item has the focus. If tagOrId is not specified then the command returns the id for the item that currently has the focus, or an empty string if no item has the focus. If the item sits on a different surface than pathName, then this command also returns the pathName of the item.
- Once the focus has been set to an item, all keyboard events will be directed to that item. The focus item within a Pad++ widget and the focus window on the screen (set with the Tk focus command) are totally independent: a given item doesn't actually have the input focus unless (a) its pad is the focus window and (b) the item is the focus item within the pad. In most cases it is advisable to follow the focus widget command with the focus command to set the focus window to the pad (if it wasn't there already). Note that there is no restriction on the type of item that can receive the Pad++ focus.
[29] pathName freeborder
border
- Frees the border previously allocated by
allocborder. (Also see theallocborderanddrawbordercommands).
- Frees the color previously allocated by
alloccolor. (Also see thealloccolorandsetcolorcommands).
[31] pathName freeimage
imagetoken
- Frees the image previously allocated by
allocimage. (Also see theallocimageanddrawimagecommands, as well as the description ofimageitems).
- Returns the current date and time in the standard unix time format.
- % .pad getdate
- Wed May 29 20:01:49 1996
[33] pathName getgroup
tagOrId
addgroupmember, and
removegroupmember commands).
- Returns the current render level This command can only be called within a render callback. (See the sections on Refinement and Region Management and Screen Updating in the Programmer's Guide for more information about render levels).
- Returns the current magnification of tagOrId for this specific render (it could be rendered multiple times if visible through different portals). Magnification is defined as the multiplication of the current view (including portals) with the object's size (from the -place itemconfigure option). This command can only be called within a render callback.
addmodifier, deletemodifier,
setmodifier, and bind commands).
- Returns a list of all the Pad++ widgets currently defined.
- Returns the list of the portals the current object is being rendered within. This command can only be called within a render callback.
[39] pathName getsize
tagOrId ?portalID ...?
- Returns the largest dimension of the first item specified by tagOrId. If a portal list is specified, then the size of the item within the last portal is returned.
- Return a list whose elements are the tags associated with the item given by tagOrId. If tagOrId refers to more than one item, then the tags are returned from the first such item in the display list. If tagOrId doesn't refer to any items, or if the item contains no tags, then an empty string is returned.
[41] pathName
gettextbbox string
- Returns a list with four elements giving the bounding box of string if it is drawn with the
drawtextcommand. The list has the form "x1 y1 x2 y2" such that the text is within the region bounded by x1 on the left, x2 on the right, y1 on the bottom, and y2 on the top. The bounding box is affected by thesetfontandsetfontheightcommands.
[42] pathName getview
[portalID ...]
- Returns the current view of the main window in "xview yview zoom" form. Here, (xview, yview) specifies the point at the center of the window, and zoom specifies the magnification. If a list of portalID's is specified, than the view of the last portal is returned instead of the view of the main window. (See
movetoto set the current view).- .pad getview
- 14 134 2
- .pad ic 221 -place
- 8 118 1
- .pad moveto -250 -150 0.5
- .pad getview
- -250 -150 0.5
- .pad ic 221 -place
- 8.1125 118.753 1
[43] pathName grid option
arg [arg ...]
- The
gridcommand arranges one or more objects in rows and columns and treats them as a group. It is based on the Tk grid geometry manager and its behavior and Tcl syntax are very similar to it. In pad, all grid commands are sub-commands of the pad command. See the section on GRID ITEMS for a complete description of this command, and how to create and use grids.
[44] pathName hastag
tagOrId tag
- Determines if the item specified by tagOrId contains the specified tag. This command returns "1" if the item does contains the specified tag, or "0" otherwise. If tagOrId refers to more than one item, then the comparison is performed on the first item in the display list. If tagOrId doesn't refer to any items, then "0" is returned.
- A general command for accessing information about pad and items on the pad surface. subcommand may be any of the following: html or image. Each subcommand may have sub-subcommands and options. All the subcommands and their options follow:
html getlastchangedate <tagOrId>- Returns the last date this page was modified as specified by the server.
html getlength <tagOrId>- Returns length of this page in bytes.
html getsource <tagOrId>- Returns HTML source of this page.
html gettype <tagOrId>- Returns Mime type of this page as specified by the server.
image getdim <imagetoken>- Returns dimensions {x y} of this image in pixels.
image getname <imagetoken>- Returns filename this image was loaded from.
- WARNING:
islinkedis an obsolete command and will be removed in the next release. Replace all uses ofislinkedwith the Tk 'winfo ismapped' command.- Returns a flag specifying if pathName has been mapped to the display yet.
[47] pathName
itemconfigure [-nondefaults] tagOrId [option [value] ...]
- This command is similar to the
configurecommand except that it modifies item-specific options for the items given by tagOrId instead of modifying options for the overall pad widget.icis an allowed synonym foritemconfigure. If no option is specified, then this command returns a list describing all of the available options for the first item given by tagOrId. If the -nondefaults flag is specified, then only those options modified by an application will be returned. If option is specified with no value, then the command returns the value of that option. If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s) in each of the items given by tagOrId; in this case the command returns an empty string. If value is an empty string, then that option is set back to its default value.- The options and values are the same as those permissible in the
createcommand when the item(s) were created; see the sections below starting with OVERVIEW OF ITEM TYPES for details on the legal options. Note that theitemconfigurecommand generates a<Modify>event on the items modified by it (see theitemconfigurecommand for a description of the<Modify>event). Locked items may not be modified by theitemconfigurecommand (see the -lock itemconfigure option).
[48] pathName
line2spline error x1 y1 ... xn yn
- Takes the coordinates for a line, and uses an adaptive curve fitting algorithm to generate the coordinates for a spline that approximates the line. The spline coordinates are returned. error is a floating point number indicating how closely the spline curve should follow the line. Using a smaller error will tend to generate a spline made with more bezier segments that follow the line more accurately. Using a larger error will produce fewer bezier segments but the fit will be less accurate. See the section on SPLINE ITEMS on how splines are specified in Pad++. (Also see
spline2line.)
[49] pathName lower
[-one] tagOrId [belowThis]
- Move all of the items given by tagOrId to a new position in the display list just before the item given by belowThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. belowThis is a tag or id; if it refers to more than one item then the first (bottommost) of these items in the display list is used as the destination location for the moved items. If belowThis is not specified, then tagOrId is lowered to the bottom of the display list. If the -one flag is specified, then tagOrId is lowered down one item in display order which may or may not have a visible effect. -one and aboveThis may not both be specified. If any items to be lowered are group members, they are lowered within their group rather than being lowered on the pad surface. Returns an empty string.
[50] pathName moveto
[-twostep] xview yview zoom [time [portalID ...]]
- Change the view so that the point "xview yview" is at the center of the screen with a magnification of zoom. If xview, yview, or zoom is specified as "", then that coordinate is not changed. If -twostep is specified, then make animation in two steps if appropriate (i.e., points not too close). The two steps are such that it zooms out to the midpoint between the two points far enough so that both start and endpoints are visible, and then zooms to the final destination. If time is specified, then the change in view will be animated in enough evenly spaced frames to fill up time milliseconds. If a list of portalID's are specified, then the view will be changed within the last specified portalID rather than within the main view. The return value is the current view. (See
getviewto get the current view).
- Returns a repeatable noise value based on the floating-point value of index. This noise function is equal to 0 whenever index is an integer. Typically, noise is called with slowly incrementing values of index. The closer the consecutive values of index are, the higher the frequency of the resulting noise will be. This noise function is from Ken Perlin at New York University (http://www.mrl.nyu.edu/perlin).
- Example:
set coords ""
set noiseindex_x 0.1928
set noiseindex_y 100.93982
set noiseincr 0.052342
for {set i 0} {$i < 100} {incr i } {
set x [expr 500.0 * [.pad noise $noiseindex_x]]
set y [expr 500.0 * [.pad noise $noiseindex_y]]
lappend coords $x
lappend coords $y
set noiseindex_x [expr $noiseindex_x + $noiseincr]
set noiseindex_y [expr $noiseindex_y + $noiseincr]
}
eval .pad create line $coords
[52] pathName padxy
[-sticky] [-portals] winx winy [-gridspacing value]
- Given a window x-coordinate winx and y-coordinate winy, this command returns the pad x-coordinate and y-coordinate that is displayed at that location. If -sticky is specified, the coordinate transform is done ignoring the current view (i.e., as for sticky objects.) If -portals is specified, then the point (winx, winy) is passed through any portals it on. If -gridspacing is specified, then the pad coordinate is rounded to the nearest multiple of value units.
[53] pathName pick
[-divisible] [-indivisible] winx winy
- Given a window coordinate (winx, winy), it returns the visible object underneath that point. If the point should pass through any portals, a
<PortalIntercept>event will be fired which will determine if the event will pass through that portal. By default, thepickcommand uses the divisibility of individual groups to determine if group members should be picked. However the -divisible or -indivisible flags (only one of which may be specified) override group's divisibility. If -divisible is specified, then group members will be picked from any group the point hits. If -indivisible is specified, then group objects and not group members will be picked.
% .pad create line 0 0 100 100
22
.pad create rectangle 30 30 80 80
23
.pad addmodifier Pick
.pad bind all <Pick-ButtonPress-1> {
event_Press %i %j %x %y %O
}
proc event_Press {i j x y obj} {
# Get the group object not the group members
# underneath the point x y
set container [.pad pick -indivisible $x $y]
puts "container $container object: $obj coords: ($i, $j)"
}
.pad setmodifier Pick
Now, group the line and rectangle:
% .pad create group -members "22 23"
24
Now, click on the line, the system response with:
container 24 object: 22 coords: (37.5, 36)
Now, click on the rectangle, system response with:
container 24 object: 23 coords: (66.5, 28)
Now, change the pick command as:
set container [.pad pick -divisible $x $y]:
Then click on the line:
container 22 object: 22 coords: (52.5, 52)
Click on the rectangle:
container 23 object: 23 coords: (63.5, 30)
- Pops the top frame off the stack of coordinate frames. The resulting frame on the top of the stack becomes active. Also see
pushcoordframeandresetcoordframe. Returns the frame popped off the stack.
- Prints the current hierarchical tree of items to stdout (used for debugging). Returns an empty string.
[56] pathName
pushcoordframe tagOrId
pathName pushcoordframe x1 y1 x2 y2
- Pushes a coordinate frame onto the stack of coordinate frames. When any coordinate frames are on the stack, all coordinates are interpreted relative to the frame instead of as absolute coordinates. A frame is a bounding box, and all coordinates are specified within the unit square where the unit square is mapped to the frame.
- Note that the -penwidth and -minsize and -maxsize itemconfigure options are also relative to the coordinate frame. In these cases, a value of 1 refers to the average of the frame dimensions.
- Text and images are scaled so that one line of text, or the height of the image is scaled to the height of the coordinate frame at a scale of 1 (using the -place or -z itemconfigure options).
- For example, the following code makes 50 nested rectangles. Note that the width of the rectangles shrinks proportionally.
for {set i 0} {$i < 50} {incr i} {
set id [.pad create rectangle 10 10 80 80 -penwidth 2]
.pad pushcoordframe $id
}
.pad resetcoordframe
- Also see
popcoordframeandresetcoordframe. Returns the current coordinate frame.
[57] pathName raise
[-one] tagOrId [aboveThis]
- Move all of the items given by tagOrId to a new position in the display list just after the item given by aboveThis. If tagOrId refers to more than one item then all are moved but the relative order of the moved items will not be changed. aboveThis is a tag or id; if it refers to more than one item then the last (topmost) of these items in the display list is used as the destination location for the moved items. If aboveThis is not specified, then tagOrId is raised to the top of the display list. If the -one flag is specified, then tagOrId is raised up one item in display order which may or may not have a visible effect. -one and aboveThis may not both be specified. If any items to be raised are group members, they are raised within their group rather than being raised on the pad surface. Returns an empty string.
- .pad raise 24
If we use the -one option:
.pad raise -one 24
The original position turns to be:
- Executes the tcl commands in the filename. If filename is created with the write command, then this command reads the pad scene back in. Returns an empty string.
[59] pathName removegroupmember
[-notransform] tagOrId
addgroupmember, and getgroup
commands). Returns an empty string.
[60] pathName renderitem
[tagOrId]
- During a render callback triggered by the -renderscript option, this function actually renders the object. During a -renderscript callback, if
renderitemis not called, then the object will not be rendered. If tagOrId is specified, then all the items specified by tagOrId are rendered (and the current item is not rendered unless it is in tagOrId). This function may only be called during a render callback. Returns an empty string.
- Pops all the frames off of the coordinate stack. Results in an empty stack, so all coordinates are back to absolute coordinates. Also see
pushcoordframeandpopcoordframe. Returns an empty string.
[62] pathName scale
tagOrId [scaleAmount [padX padY]]
- Scale each of the items given by tagOrId by multiplying the size of the item with scaleAmount. Scale the items around the item's center, or around the point (padX, padY), if specified. This command returns the scale of the first item. Note that the
scalecommand generates a<Modify>event on the items modified by it (see thescalecommand for a description of the<Modify>event). Locked items may not be modified by thescalecommand (see the -lock itemconfigure option).
[63] pathName
setcapstyle capstyle
- Sets the capstyle of lines for drawing within render callbacks. Capstyle may be any of: "butt", "projecting", or "round". This command can only be called within a render callback.
[64] pathName setcolor color
- Sets the color for future drawing with render callbacks. Color must have previously been allocated by
alloccolor. This command can only be called within a render callback. (Also see thealloccolorandfreecolorcommands).
[65] pathname setfont
fontname
- Sets the font for future drawing with render callbacks. This affects the result of the
gettextbboxcommand. Fontname must specify a filename which contains an Adobe Type 1 font, or the string "System" which causes the Pad++ line-font to be used. Defaults to "System". (Also see thesetfontheightcommand).
[66] pathname setfontheight
height
- Sets the height of the font for future drawing with render callbacks. Height is specified in the current pad units. This affects the result of the
gettextbboxcommand. (Also see thesetfontcommand).
[67] pathname setid tagorid
id
- Sets the id of an existing item to id. If tagord specifies more than one item, then the first item is used. Returns an empty string. This generates an error if an invalid id is specified (i.e., if it is in use), or if tagorid does not specify an object.
[68] pathName setjoinstyle
joinstyle
- Sets the joinstyle of lines for drawing within render callbacks. Joinstyle may be any of: "bevel", "miter", or "round". This command can only be called within a render callback.
[69] pathName setlanguage
language
- Sets the language to be used for callback scripts that are created in the future. All callback scripts that have already been created will be evaluated in the language that was active at the time they were created. This command refers to all callback scripts including event handlers, render scripts, timer scripts, zoom actions, e