Pad++ Reference Manual
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:
pathName animate subcommand [args ...]
animate command is the key to a sophisticated animation engine that allows asynchronous animations of most options of items on the Pad++ surface. An item can be moved across the screen while its color is being changed while another is being rotated. This all happens in the background so that Pad++ continues to process events while animations happen.
set txt [.pad create text -text "Hello World" -pen yellow \
-pos {0 -50 0.2} -anchor center]
set txtpath [.pad anim create path -path {{0 -50 0.2} {0 -50 5}} \
-endtime 2]
set txtchannel [.pad anim create channel -object $txt \
-path $txtpath -option -pos]
.pad anim start $txtchannel
create AnimationUnit [option value ...]
set path [.pad anim create path -path {0 1}]
set channel [.pad anim create channel -path $path]
.pad anim configure $channel -endtime 3
Path configuration options:
-path [path]: path is the set of "points" that defines the values to be visited by the curve. The "points" define a "polyline" in one, two, or three dimensions.
Example:
.pad anim config -path {1.0 2.0 3.0}
.pad anim config -path {{1.0 2.0} {3.0 4.0} {5.0 6.0}}
.pad anim config -path {{1.0 2.0 3.0} {4.0 5.0 6.0} \
{7.0 8.0 9.0}}
-timepath [timepath]:
Timepath is a set of time value pairs that define both the values and the time that each value should be reached. This allows one to more exactly specify the the timing of the animation and to produce animations that do not operate at a constant speed. One use for such animations is when one wants to simulate a physics-like animation by calculating position of an object at specific times to define an animation. If a path is specified with -endtime instead of -endtime, the first value of each data set is treated as a time. Times must increase in value from one data set to the next. Each data set must contain at least two values, a time value and one, two, or three values to specify the configuration values defining the path.
Examples:
.pad anim config -timepath {{1.0 2.0} {3.0 4.0} {5.0 6.0}}
.pad anim config -timepath {{1.0 2.0 3.0} {4.0 5.0 6.0} \
{7.0 8.0 9.0}}
(See bouncing ball example below.)
-begintime [timeInSec]Time, in seconds, that defines when the first value of the path is obtained
-endtime [timeInSec]: Time, in seconds, that defines when the last value of the path is obtained
-intime [inTime]:
One may want to have the animation start somewhere other than at the first value of the path. This can be accomplished be specifying the -endtime which must lie between -endtime and -endtime (inclusive). In combination with -endtime, a slice of an animation can be specified.
-order orderThe number of parameters per entry in the path. Order may be 1, 2, or 3, and must match the order of the option the path is used with.
-outtime [inTime]:
One may want to have the animation end somewhere other than at the last value of the path. This can be accomplished be specifying the -endtime which must lie between -endtime and -endtime (inclusive). In combination with -endtime, a slice of an animation can be specified.
-post [postCondition]This specifies what happens when the current time passes -endtime. The possible values for this option are: constant, cycle, or oscillate
-endtime, the last value of the path is applied.
-endtime, the interpolated value is projected back to the first value in the path, and the path is cycled through from the beginning.
-endtime, the interpolated value is reflected from the final value in the path, toward the first value.
-pre [preCondition]:
This specifies what happens when the current time is before -endtime. The possible values for this option are: constant, cycle, or oscillate
-endtime, the first value of the path is applied.
-endtime, the interpolated value is projected to the last value in the path, and the path is cycled through from the end toward the beginning.
-endtime, the interpolated value is reflected back from the first value in the path, toward the final value.
-siso [boolean]Indicates whether to apply a slow-in-slow-out effect to the animation. Default value is "0" (off).
Example:
set rec [.pad create rectangle 0 0 100 100 -fill blue]
set recp [.pad anim create path -path {{-100 0 1} {100 0 1}} \
-endtime 2 -siso 1]
set recc [.pad anim create chan -path $recp -object $rec \
-option -pos]
.pad anim start $recc
Channel configuration options:
-path [pathToken]pathToken specifies the animation path to be applied to the channel's option
-object [tagOrId]tagOrId specifies the object/objects that are to be affected by the channel
-option [option]
Option specifies the item configuration option that will be animated by interpolating along the animation path. The channel's path must be of the same order as the option. This means that if the option to be animated is -endtime, the path is a single list of values (i.e. -path {1.0 2.0 4.0 8.0}), if the option is -endtime, the path should be a list of lists containing three values each (i.e. -path {{1.0 3.0 4.0} {2.0 1.0 7.0} {5.0 8.0 10.0}} ).
Presently supported options that one may want to animate:
Order 1:
Order 3:
-begintime [timeInSec]
Sets the -endtime of the path associated with the channel. This is just a convenience. Beware that if you set the -endtime of a channel, all channels using this same path are affected. (See -endtime for paths, above)
-endtime [timeInSec]
Sets the -endtime of the path associate with the channel. This is just a convenience. Beware that if you set the -endtime of a channel, all channels using this same path are affected. (See -endtime for paths, above)
Animation configuration options:
-members [listOfChannelsAndAnimations]:Used to add animatables to an animation. Both channels and animations are animatable and can be a member of an animation. An animation cannot be a member of itself.
Example:
.pad anim config anim0 -members "chan0 chan1 anim1"
-begintime [timeInSec]:
If an animation (anim0) is a member of another animation (anim1), -endtime specifies the delay time after anim1 is started, that anim0 should be started
-endtime [timeInSec]
By default, this is the amount of time for all animatables to finish their animation. If set to a value less than the default, all animatables will stop at the parent animation -endtime. If set to a value greater than the default, there is no noticeable effect.
-speedfactor [speedFactor]By default this is 1.0. If one sets it to 2, the animation will be played twice as fast etc.
configure AnimationUnit [option value ...]
create command.
.pad anim config path0 -endtime 10
delete AnimationUnit
start AnimationUnit
interrupt AnimationUnit
getinterpval timeInSec
-endtime or -begintime of a channel, it is the path that is associated with the channel that is actually affected. Be careful that the affected path is not also being used in another channel that needs a different -endtime and -begintime. If it is, make another path with the same data and the desired -endtime and -begintime.
.pad anim start channelToken', each channel has its own timer. So if you have several channels playing in overlapping time, you have several timers going. If you place several channels into a parent animation, when you play that animation all the channels are played using one timer. If you place animations within a parent animation, when the child animations are playing, each uses its own timer.
-rposition does not account for the -angle of the group. So the orientation of the motion of item 5 is not rotated with the group.
######################################################################
# IMPROVED HELLO WORLD ANIMATION
# Here is an animation to illustrate the combining of
# channels and animations into a single animation.
######################################################################
# Set up hello world channel
set txt [.pad create text -text "Hello World" -pen yellow \
-pos {0 -50 0.2} -anchor center]
set txtpath [.pad anim create path -path {{0 -50 0.2} {0 -50 5}} \
-endtime 2]
set txtchannel [.pad anim create channel -object $txt -path $txtpath \
-option -pos]
# Make four rectangles
for {set i 0} {$i<4} {incr i} {
.pad create rectangle 0 0 100 100 -fill black -pos {0 50 1} -tags rect$i
}
# Make a two paths, one first order and one third order
set p0 [.pad anim create path -path {0 180 90}]
set p1 [.pad anim create path -path {{0 0 0} {255 0 0} {0 255 0} \
{0 0 255} {0 0 0}} -post cycle]
# Make two channels for each object.
# One channel for changing -angle
# the other for changing -fill
set j 0
for {set i 0} {$i<8} {incr i 2} {
set obj [.pad find withtag rect$i]
set c$i [.pad anim create channel -object $obj -option -angle \
-path $p0 -begintime 0 -endtime 6]
set c[expr $i+1] [.pad anim create channel -object $obj -option -fill \
-path $p1 -begintime 3 -endtime 12]
incr j
}
# Make three animations containing only channels
# and one animation containing channels and the
# other animations
set a0 [.pad anim create anim -members "$c0 $c1" -endtime 10 \
-begintime 2.5]
set a1 [.pad anim create anim -members "$c2 $c3" -endtime 10 \
-begintime 5.0]
set a2 [.pad anim create anim -members "$c4 $c5" -endtime 10 \
-begintime 7.5]
set a3 [.pad anim create anim -members "$txtchannel $c6 $c7 $a0 $a1 $a2" \
-endtime 10 -begintime 0]
.pad anim start $a3
#################################################
# BOUNCE:
# This example shows a bouncing ball animation.
# Kinematic equations are used to calculate the
# path for a bouncing ball that looses energy.
# A -timepath is created and applied to an oval
# in a rectangular box.
#################################################
.pad moveto 0 500 0.2
set box [.pad create rectangle -165 -50 165 1400 -penwidth 20]
set ball [.pad create oval 0 0 100 100 -fill blue -pos "0 0 1"]
set boxBall [.pad create group -members "$ball $box"]
set t 0.0
set a -98.0
set v0 500.0
set x0 0.0
set tpath ""
set delT 0.01
set coefRes 0.90
set endt [expr 2.0*$v0/$a]
set endit [expr abs(int($endt/$delT))]
set refTime 0.0
for {set j 1} {$j < 20} {incr j 1} {
for {set i 0} {$i <= $endit} {incr i 1} {
set t [expr $i*$delT ]
lappend tpath "[expr $refTime + $t] 0 [expr ((0.5)*$a*$t*$t \
+ $v0*$t + $x0)] 1"
}
set v0 [expr ($v0*pow($coefRes,$j))]
set refTime [expr $refTime + $t]
set endt [expr 2.0*$v0/$a]
set endit [expr abs(int($endt/$delT))]
}
set ballpath [.pad anim create path -timepath $tpath \
-endtime [expr $refTime + $t] -intime 5]
set ballchan [.pad anim create channel -object $ball -path $ballpath \
-option -rpos]
set ballanim [.pad anim create animation -members $ballchan]
# run the animation with:
.pad anim start $ballanim
####################################################
# USING A POLYLINE TO DEFINE A PATH:
# Here is an example of using a polyline to define
# a -path (a -timepath could be created by adding
# times in the "for" loop creating the pathlist).
####################################################
# To use the script, create a polyline (try one in the
# form of a big spiral), make sure it is selected,
# then enter the following code:
set coordlist [.pad coords [.pad find withtag selected]]
if {$coordlist == ""} {
set coordlist {0 0 100 0 100 100 0 100 0 0}
}
set len [llength $coordlist]
set curscale [lindex [.pad getview] 2]
set pathlist ""
for {set i 0} {$i < $len} {incr i 2} {
lappend pathlist "[lindex $coordlist $i] [lindex $coordlist \
[expr $i + 1]] $curscale"
}
# Here is an example of using "pathlist" to
# create an animation to move a rectangle
set obj [.pad create rectangle 0 0 50 50 -fill red]
set coordPath [.pad anim create path -path $pathlist]
set rectChan [.pad anim create channel -path $coordPath -object $obj \
-option -pos -endtime 10]
set myanim [.pad anim create anim -members $rectChan]
.pad anim start $myanim
##############################################
# USING A TIMEPATH
# Here is an example of using the coordinates
# to make a -timepath from coordPath, enter:
# This assumes that the previous example has
# already been run.
##############################################
set timepathlist ""
set time 0.0
for {set i 0} {$i < $len} {incr i 2} {
lappend timepathlist "[expr $time + log(int($i+1))] \
[lindex $coordlist $i] [lindex $coordlist [expr $i + 1]] $curscale"
set time [expr $time + (1.0/($i+1.0))]
}
set coordPath [.pad anim create path -timepath $timepathlist]
set rectChan [.pad anim create channel -path $coordPath -object $obj \
-option -pos]
set mytanim [.pad anim create anim -members $rectChan]
.pad anim start $mytanim
pathName addgroupmember [-notransform] tagOrId groupTagOrId
removegroupmember, and getgroup commands). Returns an empty string.
pathName addmodifier modifier
addmodifier is an obsolete command and will be removed in the next release. Replace all uses of addmodifier with the 'modifier add' command.
addoption [-nowrite] typename optionname optionscript default
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:
write command 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 the addtype command.)
[5]
pathName addtag tagToAdd tagOrId ...
eval .pad addtag foo [.pad find withtag bar]
addtype typename createscript
addoption command.)
[7] pathName
allocborder color
allocborder is an obsolete command and will be removed in the next release. Replace all uses of allocborder with the 'border alloc' command.
alloccolor color
alloccolor is an obsolete command and will be removed in the next release. Replace all uses of alloccolor with the 'color alloc' command.
allocimage file [-norgb]
allocimage is an obsolete command and will be removed in the next release. Replace all uses of allocimage with the 'image alloc' command.
bbox [-sticky] tagOrId [tagOrId tagOrId ...]
bbox returns 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").
bbox will refer to the bounding box of the portion of the surface that is currently visible (based on the view and window size).
bind tagOrId [sequence [command]]
bind command. I.e., you can do everything you can with the canvas with exactly the same syntax, but you can also do more.
focus command below for more on this).
bindtags command. 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. A continue command in a binding script terminates that script, and a break command terminates that script and skips any remaining scripts for the event, just as for the bind command.
pad window using the Tk bind command, then they are invoked in addition to bindings created for the pad's items using the bind widget command. The bindings for items will be invoked before any of the bindings for the window as a whole.
bind command 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:
<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.
<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, and moveto (on a portal) 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 pad write command. 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.
<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_Write which 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:
<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:
bind reference 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.
addmodifier command (and may be deleted if they are no longer needed with the pad deletemodifier command.) Then, the modifier can be used in the pad bind command 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 the setmodifier command (and may be retrieved with the getmodifier command). The current modifier may be set to "" (the default) in which case no user-defined modifier is set. Example:
bindtags tagOrId [type]
border subcommand arg ...
border alloc <bordercolor>
render command for an example of how to use a border).
border free <bordertoken>
allocborder.
[14] pathName
cache subcommand arg ...
cache in tagOrId
cache out tagOrId
cache configure [option [value] ...]
-dir dirSpecifies the directory to use for the cache. The actual directory will be <dir>/<pid> where pid is the process id of Pad++. It will be removed when the process exits. The cache should be on a local disk for reasonable I/O performance. It is not set by default and caching is disabled until the cache dir is explicitly set by the application.
-size sizeSize is the total memory available to the cache manager before it starts to cache out objects. It defaults to two megabytes. Caching can be disabled by setting size to zero.
-viewmultiple viewmultipleViewmultiple specifies a multiple of the view area the cache manager should use when deciding object visibility for purposes of caching. Its default value is 2 (so objects visible within twice the view are not cache out candidates). Setting it to 1 will cause images to be potentially get cached out when not in the view.
-delay delayDelay specifies the interval (in seconds) the cache manager should check and perform any actual cache outs. Its default value is 5 seconds. Setting it to 0 will cause immediate cache outs.
[15] pathName
center [-twostep] tagOrId [time x y [z [portalID ...]]]]
centerbbox [-twostep] x1 y1 x2 y2 [time [x y [z [portalID ...]]]]
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 bounding box appears at the position determined by (x, y), both of which are 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, y) specifies the portion of the item that should appear at the portion of the screen, relatively. So, specifying (0, 0) puts the lower left corner of the bounding box on the lower left corner of the screen. (1, 1) puts the upper right corner of the bounding box on the upper right corner of the screen. 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.
clock [clockName [reset | delete]]
color subcommand arg ...
color alloc <file>
render command).
color free <colortoken>
alloccolor.
[19] pathName
configure [option] [value] [option value ...]
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 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.
coords [-objectcoords] [-append] [-nooutput] tagOrId [x0 y0 ...]
coords command generates a <Modify> event on the items modified by it (see the bind command for a description of the <Modify> event). Locked items may not be modified by the coords command (see the -lock itemconfigure option). The coords command can only be used on line, rectangle, polygon and portal items.
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
}
[21] pathName create type [option value ...]
damage [tagOrId]
update procedure is called. Returns an empty string.
delete tagOrId [tagOrId ...]
delete command generates a <Delete> event on the items modified by it (see the delete command for a description of the <Delete> event). Locked items may not be modified by the delete command (see the -lock itemconfigure option).
pathName deletemodifier modifier
deletemodifier is an obsolete command and will be removed in the next release. Replace all uses of deletemodifier with the 'modifier delete' command.
pathName deletetag tagToDelete tagOrId [tagOrId ...]
dtag is an alias for deletetag
eval .pad deletetag foo [.pad find withtag bar]
[26] pathName
drawborder border type width x1 y1 x2 y2
drawborder is an obsolete command and will be removed in the next release. Replace all uses of drawborderwith the 'render draw border' command.
drawimage imagetoken x y
drawimage is an obsolete command and will be removed in the next release. Replace all uses of drawimage with the 'render draw image' command.
drawline x1 y1 x2 y2 [xn yn ...]
drawline is an obsolete command and will be removed in the next release. Replace all uses of drawline with the 'render draw line ' command.
drawpolygon x1 y1 x2 y2 [xn yn ...]
drawpolygon is an obsolete command and will be removed in the next release. Replace all uses of drawpolygon with the 'render draw polygon' command.
drawtext string xloc yloc
drawtext is an obsolete command and will be removed in the next release. Replace all uses of drawtext with the 'render draw text' command.
find [-groupmembers] [-regexp | -glob] searchCommand \
[arg arg ...] ["&&" | "||"] [searchCommand [arg arg ...]]
.pad find -regexp withtag 5*" will look for the object with an id of 5.
withtag searchCommand without a regular or glob-style expression. The slowest finds occur when regular or glob-styles expression are used on string arguments. In this case, for every item on the surface, the regular or glob-styles expression is compared to the particular attribute of each object.
allReturns all the items on the pad.
above tagOrId: Returns the items above (after) the one given by tagOrId in the display list. If tagOrId denotes more than one item, then the lowest (first) of these items in the display list is used to search above. If the search type is a regular expression or glob-style search which denotes more than one item, then the first tag will be used, based on alphabetical order, and then the highest (last) of these items is used to search above.
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]Returns the items closest to the point given by x and y. If halo is specified, then any items closer than halo to the point will be returned. Halo must be a non-negative number. If halo is not specified, then only items overlapping the point (x, y) will be returned.
withinfo infoIf a regular expression or glob-style search is used, this returns all the items for which their info itemconfigure option matches the pattern info. If an exact search is used, this returns all the items for which their info itemconfigure option is the same as the string info.
withlayer layerIf a regular expression or glob-style search is used, this returns all the items for which the name of their layer matches the pattern layer. If an exact search is used, this returns all the items in which the name of their layer is the same as the string layer.
withname nameIf a regular expression or glob-style search is used, this returns all the items for which their name matches the pattern name. If an exact search is used, this returns all the items for which their name is equal to the string name. A name is a URL for an HTML item, and a filename for textfile and image items.
withsticky typeReturns all the items that are sticky type.
withtag tagOrIdIf tagOrId is a number, this returns that item. If a regular expression or glob-style search is used, this returns all the items for which their tag matches the pattern tagOrId. If an exact search is used, this returns all the items for which their tag is equal to the string tagOrId.
withtext textIf a regular expression or glob-style search is used, this returns all the items for which their text matches the pattern text. If an exact search is used, this returns all the items for which their text is equal to the string text.
withtype typeIf a regular expression or glob-style search is used, this returns all the items for which their type matches the pattern type. If an exact search is used, this returns all the items for which their type is equal to the string 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
focus [tagOrId [portalID ...]]
font subcommand [args ...]
This command is used for manipulating fonts. Fonts are specified using a logical font naming scheme similar to Java's, rather than using a platform-specific filename as a font name.
font bbox string font [fontheight]
render draw text command. 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 the render configure -font and -fontheight commands.
font path [[+]path]
font loadbitmaps font
.pad loadbitmaps Helvetica-Bold".
font maxbitmapsize size
font names
freeborder border
freeborder is an obsolete command and will be removed in the next release. Replace all uses of freeborder with the 'border free' command.
freecolor color
freecolor is an obsolete command and will be removed in the next release. Replace all uses of freecolor with the 'color free' command.
freeimage imagetoken
freeimage is an obsolete command and will be removed in the next release. Replace all uses of freeimage with the 'image free' command.
getdate
pathName getgroup tagOrId
addgroupmember, and removegroupmember commands).
getlevel
getlevel is an obsolete command and will be removed in the next release. Replace all uses of getlevel with the 'render configure -level' command.
getmag tagOrId
getmag is an obsolete command and will be removed in the next release. Replace all uses of getmag drawtext with the 'render configure -mag' command.
pathName getmodifier
getmodifier is an obsolete command and will be removed in the next release. Replace all uses of getmodifier with the 'modifier get' command.
[42] pathName
getpads
getportals
getportals is an obsolete command and will be removed in the next release. Replace all uses of getportals with the 'render configure -portals' command.
getsize tagOrId ?portalID ...?
gettags tagOrId
gettextbbox string
freeborder is an obsolete command and will be removed in the next release. Replace all uses of freeborder with the 'border free' command.
[47] pathName
getview [portalID ...]
moveto to set the current view).
[48] pathName
getzoom [portalID ...]
getview command. (See moveto to set the current view).
grab [-root | -path pathName | -win winId] \
[-dim {width height}] x y width height
image [53] command and Image Items.) The grab command takes a region (x, y, width, height) which specifies the area to grab. Note that y represents the top of the region. The region can be relative to a specific Tk window, any other X window, or the entire screen. By default, the region is relative to the pad widget window. The region actually grabbed is clipped to the specified window (or to the screen for root grabbing.)
set imagedata [.pad grab 0 0 200 200] .pad create image -image $imagedata
grid option arg [arg ...]
grid command 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.
hastag tag tagOrId
html subcommand arg ...
html configure tagOrId [option [value] ...]
-source (read only)Returns the HTML source of the page
-type (read only)Returns the mime type of the page contents
-lastchangedate (read only)Returns the last time the html source was modified, as specified by the server.
-length (read only)Returns the length of the html source in characters.
html anchor configure tagOrId [option [value] ...]
-html (read only)Returns the id of the html page this anchor is associated with.
-image (read only)Returns the image token this anchor is represented by if the anchor is an image anchor.
-ismap (read only)Returns true if the anchor is an imagemap.
-name (read only)Returns the name of the anchor
-stateReturns the current state of the anchor (unvisited, visited, or active).
-url (read only)The URL this anchor is linked to.
image subcommand arg ...
image alloc <file>
image alloc can always read gif file formats. In addition, if Pad++ is compiled with the appropriate libraries, it can also read jpeg and tiff image file formats, and will automatically determine the file type. The image may have transparent pixels. This returns an image token which can be used by related commands.
image free <imagetoken>
image alloc.
image names
image configure <imagetoken> [option [value] ...]
-dimensions (read only)Returns a list of the dimensions of the image data (width, height).
-name (read only)Returns the file the image data token was created from.
-rgb (can set only to 0)Normally, image data 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.
set imagedata [.pad image alloc "foo.gif"] .pad create image -image $imagedata -anchorpt "0 0" .pad create image -image $imagedata -anchorpt "200 0"[54] pathName
info subcommand
status render
status sharedmemory
[55] pathName
isvisible tagOrId [portalId ...]
[56] pathName
itemconfigure [-nondefaults] tagOrId [option [value] ...]
ic is an alias for itemconfigure
itemconfigure [-nondefaults] tagOrId [option [value] ...]
configure command except that it modifies item-specific options for the items given by tagOrId instead of modifying options for the overall pad widget. 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.
create command when the item(s) were created; see the sections below starting with OVERVIEW OF ITEM TYPES for details on the legal options. Note that the itemconfigure command generates a <Modify> event on the items modified by it (see the itemconfigure command for a description of the <Modify> event). Locked items may not be modified by the itemconfigure command (see the -lock itemconfigure option).
layer subcommand [args ...]
-visiblelayers [67] itemconfigure option.)
layer create <layer>
layer delete <layer>
layer names
layout subcommand [args ...]
layout align <type> [-anchor] [-coords {x y ...} [-overlaponly]] \
tagOrId [tagOrId ...]
foo" so they are aligned on top:
.pad layout align -top foo
layout distribute <type> [-space space] tagOrId [tagOrId ...]
layout position [-time animationTime] x1 y1 <type> x2 y2 tagOrId \
[tagOrId ...]
foo" so they have the same lower left corner as item #72. Then, all the objects with the tag "bar" are moved so that their upper right corner is at the same position as the lower left corner of item #72.
.pad layout position 0 0 72 0 0 foo
.pad layout position 0 0 72 11 bar
layout size <type> [-ref tagOrId] [-scale scale] tagOrId [tagOrId ...]
layout snap grid tagOrId [tagOrId ...]
line2spline error x1 y1 ... xn yn
spline2line.)
lower [-one] [-layer] tagOrId [belowThis]
layer [57] command for more information about layers.)
pathName modifier subcommand [args ...]
bind command for a more complete description. There are several subcommands:
modifier create <modifier>
modifier delete <modifier>
modifier get
modifier set <modifier>
modifier create' command.
moveto [-twostep] xview yview zoom [time [portalID ...]]
getview to get the current view). Note that the moveto command generates a <Modify> event if a portal's view is changed (see the bind command for a description of the <Modify> event).
noise index
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
padxy [-sticky] [-portals] winx winy [-gridspacing value]
pick [-divisible] [-indivisible] winx winy
<PortalIntercept> event will be fired which will determine if the event will pass through that portal. By default, the pick command 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)
popcoordframe
pushcoordframe and resetcoordframe. Returns the frame popped off the stack.
printtree
pushcoordframe tagOrId
pathName pushcoordframe x1 y1 x2 y2
for {set i 0} {$i < 50} {incr i} {
set id [.pad create rectangle 10 10 80 80 -penwidth 2]
.pad pushcoordframe $id
}
.pad resetcoordframe
popcoordframe and resetcoordframe. Returns the current coordinate frame.
raise [-one] [-layer] tagOrId [aboveThis]
layer [57] command for more information about layers.)
If we use the -one option:
.pad raise -one 24
The original position turns to be:
[70] pathName random min max
read filename
pathName removegroupmember [-notransform] tagOrId
addgroupmember, and getgroup commands). Returns an empty string.
render subcommand arg ...
render command is used to manipulate the state of the renderer, and to render onto the screen during a renderscript. This command can only be called within a render callback.
render scale dz
render translate dx dy
render draw border bordertoken relief width x1 y1 x2 y2
render draw filledborder bordertoken relief width x1 y1 x2 y2
border commands). This command can only be called within a render callback. Border must have been previously allocated by border. Type must be one of "raised", "flat", "sunken", "groove", "ridge", "barup", or "bardown". The 'draw border' command draws just the border while the 'draw filledborder' command draws the border with the inside filled with the color of the border. The following example creates an object that draws a border:
set border [.pad allocborder #803030]
.pad create rectangle 0 0 100 100 -renderscript {
.pad render draw border $border raised 5 0 0 100 100
}
render draw image imagetoken x y
render draw line x1 y1 x2 y2 [xn yn ...]
render draw polygon x1 y1 x2 y2 [xn yn ...]
render draw text string x y
render configure [option [value] ...]
-capstyle capstyleSets the capstyle of lines for drawing within render callbacks. Capstyle may be any of: "butt", "projecting", or "round".
-joinstyle joinstyleSets the joinstyle of lines for drawing within render callbacks. Joinstyle may be any of: "bevel", "miter", or "round".
-linewidth widthSets the linewidth (in current units) to width for future drawing with render callbacks. The actual width of the line will depend on the size of the object and the magnification of the view. If width is 0, then the line is always drawn 1 pixel wide.
-color color
Sets the color for future drawing with render callbacks. Color must have previously been allocated by color alloc.
-font fontname
Sets the font for future drawing with render callbacks. This affects the result of the font bbox command. Fontname must specify a filename which contains an Adobe Type 1 font, or the string "Line" which causes the Pad++ line-font to be used. Defaults to "Times-12".
-fontheight 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 font bbox command.
-level (read-only)Returns the current render level. (See the sections on Refinement and Region Management and Screen Updating in the Programmer's Guide for more information about render levels).
-mag (read-only)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 -position itemconfigure option).
-portals (read-only)Returns the list of the portals the current object is being rendered within.
renderitem [tagOrId]
renderitem is 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.
resetcoordframe
pushcoordframe and popcoordframe. Returns an empty string.
rotate tagOrId angle [xctr yctr]
scale tagOrId [scaleAmount [ctrx ctry [animationTime]]]
scale command generates a <Modify> event on the items modified by it (see the scale command for a description of the <Modify> event). Locked items may not be modified by the scale command (see the -lock itemconfigure option).
setcapstyle capstyle
setcapstyle is an obsolete command and will be removed in the next release. Replace all uses of setcapstyle with the 'render configure -capstyle' command.
[79] pathName
setcolor color
setcolor is an obsolete command and will be removed in the next release. Replace all uses of setcolor with the 'render configure -color' command.
setfont fontname
setfont is an obsolete command and will be removed in the next release. Replace all uses of setfont with the 'render configure -font' command.
[81] pathname
setfontheight height
setfontheight is an obsolete command and will be removed in the next release. Replace all uses of setfontheight with the 'render configure -fontheight' command.
[82] pathname
setid tagorid id
[83] pathName
setjoinstyle joinstyle
joinstyle is an obsolete command and will be removed in the next release. Replace all uses of joinstyle with the 'render configure -joinstyle' command.
[84] pathName
setlanguage language
settoplevel command.)
[85] pathName
setlinewidth width
setlinewidth is an obsolete command and will be removed in the next release. Replace all uses of setlinewidth with the 'render configure -linewidth' command.
pathName setmodifier modifier
setmodifier is an obsolete command and will be removed in the next release. Replace all uses of setmodifier with the 'modifier set' command.
pathName settoplevel language
setlanguage command.)
slide tagOrId [dx dy [animationTime]]
slide command generates a <Modify> event on the items modified by it (see the slide command for a description of the <Modify> event). Locked items may not be modified by the slide command (see the -lock itemconfigure option).
.set id [.pad create line 0 0 200 200]
sound subcommand args ...
.pad sound load file
.pad sound play sound_token [-volume volume]
sound load" command. This returns a token that is used to stop the sound if needed. If volume is specified (at a range of [0-100]), then the sound is played at the given volume (temporarily overriding the system configuration). Short sounds are played asynchronously. There are no guarantees, but in practice, sounds under about a half second are played in the background, and this function immediately. In the future, there will be better control over this.
.pad sound stop play_token
.pad sound configure [option [value] ...]
-sounds (read-only)This returns a list of the currently loaded sounds.
-volume master
-volume {left right}This sets the volume of all sounds to be played. If a single parameter is given, it is treated as the master volume, and sets the sound for both channels. If two parameters are given (as a two-element list), they set the left and right speaker volumes separately. In all cases, this returns a list of the left and right speaker volumes. Volumes are specified in the range [0-100].
spline2line error x1 y1 ... xn yn
line2spline.)
text tagOrId option [arg ...]
text command generates a <Modify> event on the items modified by it (see the text command for a description of the <Modify> event). Locked items may not be modified by the text command (see the -lock itemconfigure option). The following command options are available:
compare index1 op index2
delete index1 [index2]
get index1 [index2]
index index [char]
insert index chars
mark option [arg arg ...]
mark names
Returns a list whose elements are the names of all the marks that are currently set.
mark set markName index
Sets the mark named markName to a position just before the character at index. If markName already exists, it is moved from its old position; if it doesn't exist, a new mark is created. This command returns an empty string.
mark unset markName [markName ...]
Remove the mark corresponding to each of the markName arguments. The removed marks will not be usable in indices and will not be returned by future calls to
pathName mark names. This command returns an empty string.
[92] pathName tree subcommand [args ...]
tree subcommand.
setfocus subcommand for more information.
addnode childtagOrId parenttagOrId
Adds childtagOrId to parenttagOrId as a child. If childtagOrId already has a parent, this command also removes childtagOrId from that parent. When it is added to the tree, the item's current zoom is recorded, and is used in all future calculations in the dynamic tree layouts. This means that an item's size when it is added to the tree is the size that it will have when it has a focus of 1.0. (See the tree setscale command to modify the size of an item after it has been added to a tree.)
animatelayout tagOrId [-view view]
Used in conjunction with computelayout, this command performs the animated layout of a tree. It may be given a view, which forces the system to animate the system view while the tree animation is taking place. Use getlayoutbbox to calculate a view for the finished animation. See computelayout for specific implementation instructions.
Using animatelayout with the -view option forces an animation of the view as the tree is animating. The view animates from the current view to the one specified as the tree animation is taking place.
animateview tagOrId [value]
Sets the animateView flag at tagOrId. Controls whether or not a layout will animate the view when layout is called at tagOrId.
connect tagOrId
Draws links from tagOrId to its parent, and from tagOrId's children to tagOrId.
computelayout tagOrId
Computes the final layout state for a dynamic tree. This places final layout state information in the tree, some of which can be accessed in order to control the layout. For information on accessing some of this information, see the getlayoutbbox command.
This code computes the future layout of a tree, then animates its view so that the center of the tagOrId's future position is in the center of the screen at the end of the animation. Note that any treenode which is a descendant of tagOrId will return valid information on a call to get layoutbbox. Other nodes are not guaranteed to have valid information.
.pad tree computelayout $node set futureBbox [.pad tree getlayoutbbox $node] set view [bbcenter $futureBbox] .pad tree animatelayout -view $view
create tagOrId
Creates a treenode to monitor tagOrId. Creates default layout for treenode. Adds tagOrId to the padroot, in preparation for placement somewhere else in the hierarchy.
createroot
Creates an invisible root node which is used to organize subtrees of information, and returns the pad id of the dummy object at that node. Used to connect several nodes together so that they appear to be root nodes at the same level. Because this is an invisible node, no links will be drawn to it.
delete [-subtree] tagOrId
Delete the tagOrId and its associated pad object, layout, and link. By default, when there is no subtree option, tagOrId's children are promoted to be children of tagOrId's parent. If the -subtree option is used, the entire subtree and all of its associated data and pad objects are deleted.
getchildren tagOrId
Returns a list of the ids of the pad objects which are children of tagOrId
getfocus tagOrId
Returns the focus value at a tagOrId, which is a number on the interval [0.0, 1.0]
getlayoutbbox tagOrId
Returns the approximate bbox tagOrId will have at the end of the current animation. This is only valid when used after computelayout, and before any manipulation of any member of the tree. Moving or resizing any object affected by computelayout will cause a few bugs in the animation of those objects when animatelayout is called. The system will not break, but any moved object will first instantly move to the position it held when computelayout was called, and then will animate to the position computelayout determined for that object. Relative sizing of objects will be ignored by the system.
getlink tagOrId
Return the id of the item which graphically links tagOrId to its parent.
getparent tagOrId
Return the id of the parent of tagOrId.
getroot tagOrId
Gets the root node of tagOrId's hierarchy - the node which resides just below the padroot.
isnode tagOrId
Returns a boolean indicating whether or not tagOrId has a treenode attached to it, and is therefore a member of a hierarchy.
layout tagOrId [-view view]
Performs a recursive layout of the subtree rooted at tagOrId. If the -view option is used, the tree will animate to the view provided.
lower tagOrId [belowtagOrId]
Controls the position of tagOrId in the order of its siblings. If belowtagOrId is not provided, tagOrId is moved to the bottom of the list. If belowtagOrId is provided, tagOrId is moved to a position just above (after) belowtagOrId.
raise tagOrId [abovetagOrId]
Controls the position of tagOrId in the order of its siblings. If abovetagOrId is not provided, tagOrId is moved to the top of the list. If abovetagOrId is provided, tagOrId is moved to a position just above (after) abovetagOrId.
removenode [-subtree] tagOrId
Removes the treenode and layout objects associated with tagOrId. If the -subtree is not included, tagOrId's information is removed, and tagOrId's children are promoted. If the -subtree option is used, the entire treenode hierarchy is removed.
reparent [-subtree] tagOrId parenttagorid
Reparents tagOrId to belong to parenttagorid. The default case, in which the -subtree option is not used, reparents tagOrId, and promotes any children tagOrId may have to be children of tagOrId's original parent. If the -subtree option is used, the subtree rooted at tagOrId is moved.
setanimatespeed tagOrId milliseconds
Sets the time for an animation to occur. If this number is 0, the animation will proceed immediately to the end state. During an animation, if any event is detected, the animation will proceed to the end state. Thus, a double click on a treenode forces the animation to happen instantaneously.
setfocus tagOrId [value [levels [falloff]]]
Set the focus value at a tagOrId. This must be a number on the range [0,1]. If no value is provided, the focus is set to 1.0. The levels parameter controls the number of levels this focus is allowed to spread. The falloff parameter is a multiplier which controls the portion of focus which is passed on to the next level of recursion. For example, if this number is 0.75, then focus*0.75 of the focus is passed on at the next level of recursion.
setfocusmag tagOrId value
Recursive set command - works on the entire subtree of the tagOrId is is given. Set the magnification difference between an object of focus 0 and an object of focus 1.
setlinkmode mode
If mode is "fixed", this sets the penwidth of treelinks to fixed width 1 pixel. If mode is "scaling", then penwidth scales. The change is applied to all descendants of the specified treenode
setscale tagOrId value
Set the scale that an object will have when its focus is 0. This is the smallest size that an object will have in a dynamic tree. When a tree tagOrId is created, this value is automatically set to the z value of the object.
setspacing tagOrId xvalue [yvalue]
Set the x and y spacing at a tagOrId. This is the amount of spacing between a tagOrId and its spatial neighbors.
[93] pathName
type tagOrId
update [-dissolve speed [withRefinement]]
urlfetch URL ?option value ...?
pathName urlfetch Token
where valid options are:
-file <filename>
-var <variable>
-updatescript <updateScript>
-donescript <doneScript>
-errorscript <errorScript>
urlfetch returns a token that can be used to interact with this retrieval. This token is appended to updateScript, doneScript and errorScript when the scripts are executed.
urlfetch and it is the responsibility of the caller to free it (with unset). The third method is to use the second form of urlfetch by passing it url token during an updatescript callback in which case it will return the data retrieved by that fetch. Three code segments follow which show the use of urlfetch.
#
# urlfetch example using a file
#
proc done {filename token} {
set file [open $filename "r"]
... # handle file
}
set file "foo"
.pad urlfetch http://www.cs.unm.edu -file $file \
-donescript "done $file"
#
# urlfetch example using a Tcl global variable
#
proc done {token} {
global foo
... # handle data in "foo"
unset foo ;# no longer need URL data
}
.pad urlfetch http://www.cs.unm.edu -var foo \
-donescript "done"
#
# urlfetch example using a token to incrementally
# handle data as it comes in.
#
proc update {token} {
set data [.pad urlfetch $token]
... # handle incremental data
}
.pad urlfetch http://www.cs.unm.edu \
-updatescript "update" -donescript "done"
warp dx dy
windowshape [innercoords outercoords]
.pad windowshape {0 50 50 50 25 0} {0 50 50 50 25 0}
[98] pathName
write [-format type] [-relative] file [tagOrId tagOrId ...]
read command.) If type is "text", then the Tcl code that is used to recreate the items is written. If type is "binary-interchange", then a custom binary format is used. Both formats are intended to be readable by all future versions of Pad++. The text format is somewhat larger and slower to read, while the binary format is somewhat smaller and faster to read. The binary file format is described in the document doc/fileformat.txt.
<Write> event for each item it writes. The return string from the <Write> event handler will be appended to whatever string this function writes out for each item. See the bind command for more information on this.
zoom zoomFactor padXloc padYloc [animateTime [portalID ...]]
Copyright Computer Science Department, The University of New Mexico