Pad++ Reference Manual

(Version 0.9)

This document in organized into the following sections:

• Padwish Synopsis

• TCL Synopsis

• Widget-Specific Options

• Widget Commands

• Overview of Item Types

• Default Bindings

• Global TCL Variables

• KPL-Pad++ Interface

Items

create [21] Create new items

delete [23] Delete existing items

find[31] Search for items by various keys

isvisible [55] Return true if the specified item is visible.

itemconfigure Configure existing items

lower[60] Push an item lower in the drawing order

pick[65] Find the item under a point

popcoordframe[66] Pop a relative coordinate frame off of the stack

pushcoordframe[68] Add a new relative coordinate frame to the stack

raise[69] Bring an item higher in the drawing order

resetcoordframe[75] Reset coordinate frame stack to empty

setid[82] Change the id of an item

text[91] Modify text item

type [93] Get the type of an item

-aliases [1] (Read-only) Returns all aliases of the item

-arrow [7] Whether to draw arrow heads with this item

-arrowshape [8] The shape of drawn arrow heads

-height [26] Height of an item. Normally computed, but can be set to squash/stretch item

-html [27] The HTML item associated with an htmlanchor

-htmlanchors [28] The anchors associated with an HTML page

-image [29] Image data associated with item (allocated by image alloc)

-info [30] A place to store application-specific information with an item

-ismap [31] True if an htmlanchor is an image map

-lock [35] Locks an item so it can not be modified or deleted

-state [53] State of an item (such as visited, unvisited, etc.)

-sticky [54] Specifies if an item should stay put when the view changes

-text [56] The text of any item containing text

-timerrate [57] Frequency timerscript should fire

-timerscript [58] Script associated with an item that fires at regular intervals

-title [59] Some items only: Title of an item

-url [63] The URL associated with an item

-width [68] Width of an item. Normally computed, but can be set to squash/stretch item

-zoomaction [70] A script that gets evaluated when an item is scaled larger or smaller than a set size

Item Transformations

animate [1] Animate item options asynchronously

bbox [10] Get the bounding box of an item

coords [20] Change the coordinates of an item

getsize [44] Get the size of an item (possibly within portals)

rotate [76] Rotate an item

scale [77] Change the size of an item relatively

slide [88] Move an item relatively in (x, y)

-anchor [3] The part of the item that -position refers to

-anchorpt [4] The (x, y) portion of -position

-angle [5] Specifies absolute rotation of item

-anglectr [6] Specifies absolute rotation of item, rotating about specified point

-position [47] The absolute position of the object (x, y, scale)

-rposition [51] The relative position of the object (to groups)

-scale [52] The (scale) portion of -position

View Transformations

center [15] Change the view so as to center an item

centerbbox [16] Change the view so as to center a bounding box

getview [47] Get the current view (possibly within portals)

getzoom [48] Get the current view magnification (possibly within portals)

moveto [62] Change the view (possibly within portals)

zoom [99] Zoom the view around a specified point

-lookon [36] Specifies the pad widget this item sees

-view [65] Specifies the view this item sees

-viewscript [66] A script that gets evaluated whenever the view is changed

Tags

addtag [5] Add a tag to an item

deletetag [23] Delete a tag from an item

dtag [23] Synonym for deletetag

gettags [45] Get the tags an item has

hastag [51] Determine if an item has a particular tag

-tags [55] List of tags associated with an item

Events

bind [11] Create, modify, access, or delete event bindings

bindtags [12] Specify whether events should go to the most-specific or most-general description

focus [32] Set the focus for keyboard events

modifier [61] Manipulate user-defined modifiers

-events [20] True if item receives events, false otherwise

Groups

addgroupmember [2] Add an item to a group

getgroup [38] Get the group an item belongs to

removegroupmember [72] Remove an item from a group

-divisible [16] True if events go through a group to its members

-members [38] The list of members of a group

Layout

grid [50] Manage item layout in a grid as with the Tk grid command

layout [58] Layout items once

tree [92] Manage item layout with a dynamic graphical-fisheye view tree

Rendering

damage [22] Specify that a group of items needs to be redrawn

update [94] Force any requested render requests to occur immediately

-alwaysrender [2] True if the item must be rendered, even if the system is slow and the item is small

-border [10] Specifies border color of item

-borderwidth [11] Specifies width of border

-capstyle [12] Specifies how to draw line ends

-clipping [13] Controls if items are clipped to their bounding box when rendered

-dither [15] Render with dithering

-faderange [21] Range over which an item fades in or out

-fill [23] Specifies fill color of item

-font [24] Specifies font to use for text

-joinstyle [32] Specifies how to draw the joints within multi-point lines

-layer [33] The layer an item is on

-noisedata [42] Specifies parameters to render item with noise

-maxsize [37] The maximum size an item is rendered it (absolute or relative to window size)

-minsize [41] The minimum size an item is rendered it (absolute or relative to window size)

-pen [45] Specifies pen color of item

-penwidth [46] Specifies width of pen

-relief [49] Specifies how border should be rendered (raised, flat, sunken, ridge, groove)

-transparency [61] Transparency of an item. 0 is completely transparent, 1 is completely opaque

-visiblelayers [67] The layers that are visible within this view (just for portals and surface, item #1)

Renderscripts

border [13] Manipulate a fake 3D border for use in a render callback

color [18] Manipulate a color for use in a render callback

render [73] Configure and use renderer

renderitem [74] Render an item in a render callback

-renderscript [50] A script that gets evaluated every time an item is rendered

-bb [9] A script that gets evaluated to specify the bounding box of an item

File I/O

cache [14] Control item cache

read [71] Read a .pad file

write [98] Write a .pad file (all the items on a widget)

-file [22] File an item should be defined by

-writeformat [69] Controls whether disk-based item is written out by copy or reference

Miscellaneous

configure [19] Modify the pad widget

font [33] Manipulate fonts and the font path

html [52] Manipulate and query an html page and its anchors.

image [53] Manipulate images

info [54] Get type-specific information about an item

layer [57] Manipulates layers

random [70] Generates a random integer

setlanguage [84] Set the language to be used for future callback scripts

settoplevel [87] Set the language to be used by the top-level interpreter

sound [89] Manipulate and play sounds

windowshape [97] Modify the shape of the top-level window that a pad widget is in

-donescript [17] A script to evaluate when a background action has completed

-errorscript [19] A script to evaluate when a background action has an error

-reference [48] What item an alias references

-updatescript [62] A script to evaluate when a background action has made progress

Utilities

clock [17] Create a clock to measure elapsed milliseconds

getdate [37] Get the current date in unix format

getpads [42] Get a list of all pad widgets currently defined

line2spline [59] Generate points for a spline that approximate a line

noise [63] Generate 'perlin' noise

padxy [64] Convert a window point (x, y) to pad coordinates

spline2line [90] Generate points for a line that approximate a spline

urlfetch [95] Retrieve a URL over the internet in the background

warp [96] Warp (move) the core pointer

Widgets

-command [14] Callback for widgets

-editable [18] True if text item is editable

-from [25] Starting value of valuator widget

-linesize [34] Amount widget should change to represent a line change

-memberlabels [39] List of labels for a pull-down or pop-up menu

-menubar [40] Menubar associated with a frame

-orientation [43] Orientation of widget (horizontal or vertical.)

-pagesize [44] Amount widget should change to represent a page change

-to [60] Ending value of valuator widget

-value [64] Current value of valuator widget

Debugging

printtree [67] Print all the items on the pad surface in their internal tree structure

Extensions

addoption [4] Create a new option for an existing type

addtype [6] Create a new item type

Item Types

• Item Options

• Alias Items

• Button Items

• Canvas Items

• Checkbox Items

• Checkboxmenuitem Items

• Choicemenu Items

• Frame Items

• Grid Items

• Group Items

• HTML Items

• Image Items

• KPL Items

• Label Items

• Line Items

• Menu Items

• Menubar Items

• Menuitem Items

• Menu Items

• Pad Items

• Panel Items

• Polygon Items

• Portal Items

• Rectangle Items

• Scrollbar Items

• Spline Items

• TCL Items

• Text Items

• Text items have default event bindings which can be used for emacs-style editing of them. See the section on Default Bindings for more info.

• Textfield Items

• Window Items

padwish [options] [arg arg ...]

-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).

-display display

Display (and screen) on which to display window.

-geometry geometry

Initial geometry to use for window.

-help

Print a summary of the command-line options and exit.

-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'.

-name name

Use name as the title to be displayed in the window, and as the name of the interpreter for send commands.

-norgb

Force all images to be loaded without RGB data. This means that images will be stored with one byte per pixel instead of the normal 5 bytes per pixel. As a result, images will not be able to be dithered.

-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).

-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.

-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.

--

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]]

Once a Pad++ widget is created, there are five ways of writing Tcl code for it. They are:

• Configuring the widget: Each widget has several configuration options that control the widget as a whole. For example, -width and -height control the geometry of the widget.

• Executing widget commands: There are many commands associated with the widget. They are actually sub-commands of the primary widget command. When a new pad widget is created, a command is also created whose name is the name of the widget. For instance, evaluating 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.

• Creating items on the widget: Each pad widget can contain many graphical items, such as lines, text, etc. These are all created with the create sub-command. For example, .pad create line 0 0 10 10 creates a line from the origin to the point (10, 10).

• Configuring those items: Once items have been created, they can be modified with the 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

• Accessing global Pad variables: The pad widget declares certain global Tcl variables that can be used by applications. For example, to see the current version of Pad++, examine the Pad_Version variable.

This version of Pad++ works with either Tcl7.5/Tk4.1 or Tcl7.6/Tk4.2.

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.

Name: background

Class: Background

Command-Line Switch: -background

Specifies the normal background color to use when displaying the widget.

Example:

			.pad config -background gray50

Name: closeEnough

Class: CloseEnough

Command-Line Switch: -closeEnough

Specifies a floating-point value indicating how close the mouse cursor must be to an item before it is considered to be "on" the item. Defaults to 3.0.

Name: cursor

Class: Cursor

Command-Line Switch: -cursor

Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor.

Name: debugBB

Class: DebugBB

Command-Line Switch: -debugBB

Turns on and off display of bounding boxes. Default is 0.

Name: debugEvent

Class: DebugEvent

Command-Line Switch: -debugEvent

Turns on and off debugging of events. Default is 0. When event debugging is turned on, pad outputs a description of event handlers as they fire. In addition, if a break or event in a handler stops some events from firing, those events not fired are shown. By default, the event debugging output goes to stdout, however, it can be sent to a Tcl variable with the -debugOut configure option. Also note that PadDraw comes with a graphical interface that creates a GUI for seeing and examining events as they fire. This graphical event debugger can be used in other pad applications. See draw/debugevent.tcl.

Name: debugGen

Class: DebugGen

Command-Line Switch: -debugGen

Turns on and off general debugging. Default is 0.

Name: debugOut

Class: DebugOut

Command-Line Switch: -debugOut

Controls where debug output goes. By default, debug output is sent to stdout. However, the -debugOut configure option can specify a Tcl variable that all debug output will be appended to. It is then possible to set a Tcl trace on that variable to be notified whenever debug output is available. Currently, only -debugEvent uses the -debugOut variable.

Example: Evaluating ".pad config -debugOut foo" will cause all future debug output to be appended to the Tcl variable 'foo'.

Name: debugRegion

Class: DebugRegion

Command-Line Switch: -debugRegion

Turns on and off visual display of portion of the screen that actually gets re-rendered. Used to debug region management. Default is 0.

Name: defaultEventHandlers

Class: DefaultEventHandlers

Command-Line Switch: -defaultEventHandlers

Turns on and off the default navigation event handlers. The default handlers are very simple. They allow basic panning with mouse button #1, zooming in with button #2, and zooming out with button #3. Default is 0.

Name: defaultRenderLevel

Class: DefaultRenderLevel

Command-Line Switch: -defaultRenderLevel

Specifies the default render level to use to display the Pad if no specific level is specified. The render level is generally used for efficiency where render level 0 is the fastest and least pretty way to render the pad (text is uglier, smaller items are not rendered, some items are rendered at a lower resolution). As the render level goes higher, the pad is rendered slower and prettier

Name: desiredFrameRate

Class: DesiredFrameRate

Command-Line Switch: -desiredFrameRate

Specifies the desired frame rate (in frames per second). This number is used by the Pad++ rendering engine to decide how to render the scene while animating. If a high frame rate is requested, small objects may not be rendered (see -alwaysrender) flag, and some objects may be rendered at low resolution. The default is 20 frames/second.

Name: dissolveSpeed

Class: DissolveSpeed

Command-Line Switch: -dissolveSpeed

Specifies how quickly dissolves should occur upon refinement. When the pad widget refines, it uses a dissolve effect instead of a simple buffer swap. The dissolve is controlled by -dissolveSpeed. This option may vary between 0 and 3 where 0 is a simple buffer swap, 1 is a fast dissolve, and 3 is the slowest dissolve. The default is 2.

Name: doubleBuffer

Class: DoubleBuffer

Command-Line Switch: -doubleBuffer

Specifies if the system should use double buffering for rendering. If doubleBuffer is set to 0 (off), rendering will be a little faster, but the screen will flash quite a bit. Mostly useful for debugging. Default is 1.

Name: fastPan

Class: FastPan

Command-Line Switch: -fastPan

Pad++ normally does fast pans, i.e., copying the portion of the screen that doesn't change, and re-rendering the new portion. This results in an approximation which can make the view be off by up to a half of a pixel. Fast panning can be disabled by setting this flag to 0 which results in slower but more accurate pans. Default is 1.

Name: fontCacheSize

Class: fontCacheSize

Command-Line Switch: -fontCacheSize

Pad++ employs a simple caching mechanism when drawing text in Type1 fonts. The caching mechanism remembers what size, font and bitmap it used when it last drew a particular character, and if that character is drawn again at the same size and font, Pad++ reuses the last bitmap image for that character rather than generating the bitmap for the character from its outline description. This greatly increases the speed of rendering large quantities of text.

You can configure the caching mechanism using the -fontCacheSize option. The font cache size is measured in Kilobytes (rounded to the nearest 100K). Setting -fontCacheSize to 0 turns off font caching, and characters are always drawn from their outline descriptions. The default value is 100 which produces significantly faster font rendering than using no font cache. Values above 100 have a lesser impact on performance, but may be effective for applications which use a lot of text with different fonts and sizes.

Name: gamma

Class: Gamma

Command-Line Switch: -gamma

Specifies 'gamma' used for allocating colors for images. This number controls how light or dark an image appears to be. Larger numbers will make images appear lighter. Default is 1.0.

Name: height

Class: Height

Command-Line Switch: -height

Specifies the height of the Pad in pixels. Defaults to 400.

Name: heightmmofscreen

Class: HeightMMOfScreen

Command-Line Switch: -heightmmofscreen

Specifies the height of the physical screen in millimeters. Normally, this information is given by the X server, but sometimes it is incorrect (for example, on some laptops). If it is incorrect, coordinates on the Pad++ surface will be incorrect. If this value is set to 0, the X server information will be used. Defaults to 0.

Name: interruptible

Class: interruptible

Command-Line Switch: -interruptible

If this flag is true (1), then animations and slow renders will be interrupted by events (mouse and keyboard). Defaults to true (1).

Name: maxZoom

Class: MaxZoom

Command-Line Switch: -maxzoom

This controls the maximum zoom (in and out) that any view is allowed. This way, it not possible to crash pad by zooming in or out too far. It defaults to 100,000,000 which gives 16 orders of magnitude of zooming (8 in and 8 out). Note that the amount one can zoom in is determined by the product of the (x, y) position and the zoom. So, while you can zoom into the position (0, 0, 100000000), you can only zoom into (1000, 1000, 100000). Setting -maxzoom to 0 disables the checking.

Name: mediumObjSize

Class: MediumObjSize

Command-Line Switch: -mediumObjSize

Pad++ tries to keep up the display rate, even when the scene gets complicated. If the system becomes slower than the requested frame rate, it both stops drawing small objects, and it draws medium-sized objects in a very ugly fashion. This option configures the size below which objects are considered to be medium-sized. Default is 100 pixels. (Also see -smallObjSize configuration option.)

Name: refinementDelay

Class: RefinementDelay

Command-Line Switch: -refinementDelay

Specifies the delay in milliseconds after the last X event to start refinement. Default is 1000.

Name: smallObjSize

Class: SmallObjSize

Command-Line Switch: -smallObjSize

Pad++ tries to keep up the display rate, even when the scene gets complicated. If the system becomes slower than the requested frame rate, it both stops drawing small objects, and it draws medium-sized objects in a very ugly fashion. This option configures the size below which objects are considered to be small-sized. Default is 10 pixels. (Also see -mediumObjSize configuration option.)

Name: sync

Class: Sync

Command-Line Switch: -sync

Specifies if X event synchronization should be turned on. When it is on, the X server executes every command as it is executed rather than caching them and executing commands in groups. Generally useful just for debugging. Default is 0.

Name: units

Class: Units

Command-Line Switch: -units

Specifies unit dimensions for all coordinates used by Pad++. It can be any of "points", "mm", "inches", or "pixels". Default is points.

Name: width

Class: Width

Command-Line Switch: -width

Specifies the width of the Pad in pixels. Defaults to 400.

Name: widthmmofscreen

Class: WidthMMOfScreen

Command-Line Switch: -widthmmofscreen

Specifies the width of the physical screen in millimeters. Normally, this information is given by the X server, but sometimes it is incorrect (for example, some laptops). If it is incorrect, coordinates on the Pad++ surface will be incorrect. If this value is set to 0, the X server information will be used. Defaults to 0.

pathName option [arg arg ...]

Option and the args determine the exact behavior of the command. The following widget commands are possible for Pad++ widgets:

The 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.

The basic units of an animation are:

• path: Defines the values visited by the changing option

• channel: Associates an object with a path and the property to animate

• animation: Groups channels and animations as a single unit

A very simple example that creates and then zooms some text follows:

			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

The animate command contains several subcommands. Briefly, they are:

• create: Create an animation unit

• configure: Configure an animation unit

• delete: Delete an animation unit

• start: Begin play of channel or animation

• interrupt: Stop channel or animation before it is complete

• getvalue: Get interpolated value from path

The animate subcommands in more detail are:

pathName anim create AnimationUnit [option value ...]

This creates one of the basic animation units (paths, channels, and animations.) When one creates an animation unit, a unique token for that unit is returned. Use the returned token to refer to that unit for future configuration/manipulations.

Example:

					set path [.pad anim create path -path {0 1}]
					set channel [.pad anim create channel -path $path]
					.pad anim configure $channel -endtime 3

Following are all of the options that can be specified for each AnimationUnit:

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 order

The 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

• constant: If the current time is after -endtime, the last value of the path is applied.

• cycle: If the current time passes -endtime, the interpolated value is projected back to the first value in the path, and the path is cycled through from the beginning.

• oscillate: If the current time passes -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

• constant: If the current time is before -endtime, the first value of the path is applied.

• cycle: If the current time is just before -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.

• oscillate: If the current time is before -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:

• -angle

• -penwidth

• -transparency

  Order 3:

• -position (min. abbreviation -pos)

• -rposition (min. abbreviation -rpos)

• -fillcolor (rgb values from 0 to 255)

• -pencolor (rgb values from 0 to 255)

• -view (applies only to pad surfaces)

• -anglectr (angle Xcenter Ycenter)

-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.

pathName anim configure AnimationUnit [option value ...]

One can configure an animation unit by using its configuration options. If a configuration option is entered without specifying a value to set the option, the current value of the option is returned. The options that can be configured on any animation unit are the same that apply with the create command.

Example:

					.pad anim config path0 -endtime 10

pathName anim delete AnimationUnit

Deletes an AnimationUnit.

pathName anim start AnimationUnit

Begins the playing of an animation or of a channel.

pathName anim interrupt AnimationUnit

Stops the playing of an animation or of a channel, before play has completed.

pathName anim getinterpval timeInSec

Returns the the interpolated value along the path given the the time in seconds. This may be useful when one wants to use a path for something other than animations, or just to check values along an animation path. This command applies only to animation paths.

Notes concerning animations:

Commands and options can be abbreviated with any string that uniquely identifies the command or option of interest.

When one changes the -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.

When directly playing channels via a command such as '.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.

There is a conflict between angles, groups, and animations. For example, if we have a group (10) with items 5 and 6 in it, and we make an animation that changes that relative position of item 5 and tries to rotate the group at the same time, there is a problem. -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.

Example animations:

######################################################################
# 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

Add all items specified by tagOrId to the group specified by groupTagOrId. If groupTagOrId specifies more than one item, the first one is used. The items are added to the end of the group in the order specified by tagOrId. Groups automatically update their bounding boxes to enclose all of their members. Thus, they will grow and shrink as their members change.

By default, items are transformed so they don't change their location when added to a group, even if the group has a transformation. This is implemented by transforming the item's transformation to be the inverse of the group's transformation. If the -notransform flag is specified, this inverse transformation is not applied, and the item will move by the group's transformation when added. (Also see the removegroupmember, and getgroup commands). Returns an empty string.

Example :

set id0 [.pad create line 0 0 100 100]

254

set id1 [.pad create line -10 20 80 -60]

255

set gid [.pad create group -members "$id0 $id1"]

256

.pad ic $gid -members

254 255

set id3 [.pad create rectangle -20 -20 130 40]

266

.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

WARNING: addmodifier is an obsolete command and will be removed in the next release. Replace all uses of addmodifier with the 'modifier add' command.

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 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.)

For each item specified by the list of tagOrIds, add tagToAdd to the list of tags associated with the item if it isn't already present on that list. It is possible that no items will be specified by tagOrId, in which case the command has no effect. This command returns an empty string.

This command is designed to be used in conjunction with the find command. Notice the necessity of using eval in this example: eval .pad addtag foo [.pad find withtag bar]

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 addoption command.)

WARNING: allocborder is an obsolete command and will be removed in the next release. Replace all uses of allocborder with the 'border alloc' command.

WARNING: alloccolor is an obsolete command and will be removed in the next release. Replace all uses of alloccolor with the 'color alloc' command.

WARNING: allocimage is an obsolete command and will be removed in the next release. Replace all uses of allocimage with the 'image alloc' command.

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 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").

If the item is the Pad++ surface (item #1), then bbox will 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

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 bind command. 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 focus command 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 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.

If bindings have been created for a 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.

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 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:

%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, 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.

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_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:

.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 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.

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 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:

.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

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.

This is the command for manipulating borders. There are several subcommands:

border alloc <bordercolor>

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. This returns a bordertoken. (Also see the render command for an example of how to use a border).

border free <bordertoken>

Frees the border previously allocated by allocborder.

cache in tagOrId

Forces the items specified by tagOrId to be cached in

cache out tagOrId

Forces the items specified by tagOrId to be cached out

cache configure [option [value] ...]

Configures the state of the cache manager. Option-value pairs may be specified as with the itemconfigure command, or if no options are specified, a list of all options and values are returned.

-dir dir

Specifies 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 size

Size 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 viewmultiple

Viewmultiple 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 delay

Delay 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.

The following criteria are used for caching:

• When an object has to be rendered, the cache manager is requested to cache it in if necessary (ensures its data are in memory). Other objects may be cached out to make room for this object.

• When an object doesn't need to be rendered the cache manager marks it as a cache out candidate.

Cache out candidates are selected by a least-recently-rendered policy. The cache manager only selects objects that have been marked for cache out and does not attempt to select objects currently rendered (or visible within its multiple of the view area).

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 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 item on the lower left corner of the screen. (1, 1) puts the upper right corner of the item 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.

.pad center 23

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 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.

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

This is the command for manipulating color. There are several subcommands:

color alloc <file>

Allocates a color for future use by render callbacks. Color may have any of the forms accepted by Tk_GetColor. This returns a colortoken. (Also see the render command).

color free <colortoken>

Frees the color previously allocated by alloccolor.

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_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.

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 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.

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
   }

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 section below for details on the syntax of this command. This command returns the id for the new item.

The available item types are: Alias Items, Button Items, Frame Items, Grid Items, Group Items, HTML Items, Image Items, KPL Items, Label Items, Line Items, Menu Items, Pad Items, Panel Items, Polygon Items, Portal Items, Rectangle Items, Scrollbar Items, Spline Items, TCL Items, Text Items, Text items have default event bindings which can be used for emacs-style editing of them. See the section on Default Bindings for more info., Note that when the -width or -height of a textfile item is set, the textfile item is clipped to those dimensions rather than being squashed or stretched as most items are., and Textfield Items.

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 update procedure is called. Returns an empty string.

Delete each of the items given by each tagOrId, and return an empty string. Note that the 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).

WARNING: deletemodifier is an obsolete command and will be removed in the next release. Replace all uses of deletemodifier with the 'modifier delete' command.

dtag is an alias for deletetag

For each item specified by the list of tagOrIds, delete tagToDelete from the list of tags associated with the item if it isn't already present on that list. It is possible that no items will be specified by tagOrId, in which case the command has no effect.

This command is designed to be used in conjunction with the find command. Notice the necessity of using eval in this example: eval .pad deletetag foo [.pad find withtag bar]

WARNING: drawborder is an obsolete command and will be removed in the next release. Replace all uses of drawborderwith the 'render draw border' command.

WARNING: drawimage is an obsolete command and will be removed in the next release. Replace all uses of drawimage with the 'render draw image' command.

WARNING: drawline is an obsolete command and will be removed in the next release. Replace all uses of drawline with the 'render draw line ' command.

WARNING: drawpolygon is an obsolete command and will be removed in the next release. Replace all uses of drawpolygon with the 'render draw polygon' command.

WARNING: drawtext is an obsolete command and will be removed in the next release. Replace all uses of drawtext with the 'render draw text' command.

				[arg arg ...] ["&&" | "||"] [searchCommand [arg arg ...]]

This command returns a list consisting of all of the items that meet the constraints specified by the searchCommands and arg's. All found items are returned in display list order. Multiple searchCommands may be used as long as they are delimited by "&&" or "||". Parenthesis are allowed to

group expressions. The following characters are reserved: '&', '|', '(', ')', and '!'. To search for these symbols, they must be escaped. The escaping of reserved characters requires two backslashes, i.e. "\\".

If -groupmembers is specified, then group members to also be returned, otherwise, they are not.

If -regexp is specified, this causes all of the strings in ensuing searchCommands to be treated as regular expressions.

If -glob is specified, this causes all of the strings in ensuing searchCommands to be treated as glob-style expressions. This means that the special character '*' will be expanded to mean any number of any kind of character. I.e., 'foo*' means all the strings starting with 'foo'.

The find command does not return the pad surface (id #1). All digits are treated as item ids, i.e.

".pad find -regexp withtag 5*" will look for the object with an id of 5.

The fastest find possible is a 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.

SearchCommand may take any of these forms:

all

Returns 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 tagOrId

Returns 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 info

If 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 layer

If 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 name

If 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 type

Returns all the items that are sticky type.

withtag tagOrId

If 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 text

If 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 type

If 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 y2

Returns 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 y2

Returns 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

.pad find withtag selected && !withtype rectangle

52 72

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.

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 names follow the format "<facename>-<stylename>-<size>", where <facename> is the typeface, e.g. Times, Helvetica, etc. <stylename> is "plain", "bold", "italic", or "bolditalic". <size> is the height of the font in pixels. <style> is optional (default is "plain"). <size> is also optional (default is 12). Fonts are substituted when the original cannot be located. Fonts specified using the old scheme are automatically translated to this scheme. The special font name "Line" specifies to use the Pad++ built-in line font. This font is ugly, but is faster than the regular fonts. Some Example font names are: "Times", "Helvetica", "Times-12", "Helvetica-bold", "Times-bold-18". The font subcommands are:

font bbox string font [fontheight]

Returns a list with four elements giving the bounding box of string if it is drawn with the 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]

Pad++ uses a search path to locate font files. Set or get the global font path used in Pad++. path is a list of directory names, separated by spaces. Font files in these directories are expected to have the extension ".pfa". The default path is /usr/lib/X11/fonts/Type1

If the '+' character is included, then the specified path is appended on to the existing search path. Otherwise, it replaces the path.

font loadbitmaps font

Attempts to load a set of X Bitmaps for font, which are used for drawing text at small sizes. e.g. ".pad loadbitmaps Helvetica-Bold".

font maxbitmapsize size

Specifies the maximum size for which X font bitmaps should be loaded when the 'font loadbitmaps' command is executed. This can be useful when making presentations if you want to force large fonts to be loaded.

font names

Returns the names of all the font faces/styles available on the current system as a list.

WARNING: freeborder is an obsolete command and will be removed in the next release. Replace all uses of freeborder with the 'border free' command.

WARNING: freecolor is an obsolete command and will be removed in the next release. Replace all uses of freecolor with the 'color free' command.

WARNING: freeimage is an obsolete command and will be removed in the next release. Replace all uses of freeimage with the 'image free' command.

Returns the current date and time in the standard unix time format.

% .pad getdate

Wed May 29 20:01:49 1996

Return the group id that tagOrId is a member of. If tagOrId is not a member of a group, then this command returns an empty string. If tagOrId specifies more than one object, then this command refers to the first item specified by tagOrId in display-list order. (Also see the addgroupmember, and removegroupmember commands).

WARNING: getlevel is an obsolete command and will be removed in the next release. Replace all uses of getlevel with the 'render configure -level' command.

WARNING: 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.

WARNING: getmodifier is an obsolete command and will be removed in the next release. Replace all uses of getmodifier with the 'modifier get' command.

Returns a list of all the Pad++ widgets currently defined.

WARNING: getportals is an obsolete command and will be removed in the next release. Replace all uses of getportals with the 'render configure -portals' command.

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.

WARNING: freeborder is an obsolete command and will be removed in the next release. Replace all uses of freeborder with the 'border free' command.

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 moveto to set the current view).

.pad getview

14 134 2

.pad ic 221 -position

8 118 1

.pad moveto -250 -150 0.5

.pad getview

-250 -150 0.5

.pad ic 221 -position

8.1125 118.753 1

Returns the current magnification of the main window. 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. This is a shortcut for the last parameter returned by the getview command. (See moveto to set the current view).

[-dim {width height}] x y width height

This captures a rectangular portion of the screen and makes an imagedata which can then be used to create image items (Also see 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.)

The window the region is relative to can be specified with the -root, -path, or -win flags. -path is used to specify an existing Tk window. -root is used to specify that the region is relative to screen. -win is used to specify any X window by the window id. X window id's can get accessed from the xlswins program that comes with most X systems. If a dimension is specified, then the image is shrunk through simple decimation to produce the desired resolution before it is returned. Images can only be shrunk, not grown with the dimension flag. Note that images can be distorted by setting a dimension with a different aspect ratio than the source.

X displays support multiple display characteristics called visuals (8-bit pseudocolor, 24-bit truecolor, etc.). Windows on the same screen can use different visuals. Because of this, grabbing from the root can grab from different windows. If the windows have a different visual than the root, those colors of those windows will be undefined.

Grab returns an imagedata token that could be used to create an image:

			set imagedata [.pad grab 0 0 200 200]
			.pad create image -image $imagedata

The 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.

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.

This is the command for manipulating html pages and html anchors. There are several subcommands:

html configure tagOrId [option [value] ...]

Configures the specified html page. Option-value pairs may be specified as with the itemconfigure command, or if no options are specified, a list of all options and values are returned.

-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] ...]

Configures the specified html anchor. Option-value pairs may be specified as with the itemconfigure command, or if no options are specified, a list of all options and values are returned.

-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

-state

Returns the current state of the anchor (unvisited, visited, or active).

-url (read only)

The URL this anchor is linked to.

This is the command for manipulating image data. In Pad++, the data associated with an image is manipulated separately from an image item. With this approach, the multiple Pad++ image items can use the same image data. There are several subcommands:

image alloc <file>

Allocates an image data for future use by image items and render callbacks. file specifies the name of a file containing an image. 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>

Frees the image data previously allocated by image alloc.

image names

Returns a list of all allocated image data tokens.

image configure <imagetoken> [option [value] ...]

Configures the specified image data. Option-value pairs may be specified as with the itemconfigure command, or if no options are specified, a list of all options and values are returned.

-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.

For example, the following code creates two image items that use the same image data:

				set imagedata [.pad image alloc "foo.gif"]
				.pad create image -image $imagedata -anchorpt "0 0"
				.pad create image -image $imagedata -anchorpt "200 0"

A command for accessing information about the pad. subcommand may be any of the following: status. Each subcommand may have sub-subcommands and options. All the subcommands and their options follow:

status render

This returns a debugging line specifying some information relevant to the last render. It returns the number of objects on the surface, the number ob objects rendered in the last render, the render level, and the time in milliseconds the last render took.

status sharedmemory

When Pad++ is running on X, it uses X shared memory to render images quickly. This return true if Pad++ is using X shared memory.

Returns true if the first item specified by tagOrId is visible. If any portals are specified, then this returns true if the item is visible within the last portal on the list.

ic is an alias for itemconfigure

A command for accessing information about the pad. subcommand may be any of the following: status. pathName itemconfigure [-nondefaults] tagOrId [option [value] ...]

This command is similar to the 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.

The options and values are the same as those permissible in the 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).

This command controls creation and deletion of layers, and provides a method to return the current layers. Layers are used to control rendering order, and visibility. Every item sits on a single layer. Each surface can have any number of layers, and the layers are rendered in sequence. In addition, each view can specify which layers can be seen within that view (via the -visiblelayers [67] itemconfigure option.)

While layers are implicitly defined when they are used, this command allows the creation of a layer before it is used, and thus ordering of layers can be defined before objects are created. There are several subcommands:

layer create <layer>

Creates a new layer, and gives it the name layer. There are no items on a new layer, and the layer is put on top of all existing layers.

layer delete <layer>

Deletes the specified layer. If any items are on a layer when it is deleted, then all of those items are deleted as well.

layer names

Returns a list of all the current layer names.

This command performs various kinds of one-time layouts. That is, it repositions and resizes objects based on subcommands, but does not manage the objects in the future. Attaching a layout call to a <Modify> event provides a way to define custom layout managers. The subcommands are:

layout align <type> [-anchor] [-coords {x y ...} [-overlaponly]] \

tagOrId [tagOrId ...]

<type> can be -left, -right, -top, or -bottom

Align the specified items so that their bounding boxes line up on the specified side. If -anchor is specified, then line up by anchor point instead of by bounding box. If coordinates are specified with -coords, then align items to the path specified by those coordinates. Otherwise, use the item furthest in the alignment direction to align the others to. If -coords is specified, then -overlaponly may be specified which means that items should only be aligned if they overlap the specified path. In all cases, items are aligned so the furthermost object doesn't move. That is, if you are aligning to the left, then all objects are moved to be aligned with the left-most object.

A simple example moves all the items that have the tag "foo" so they are aligned on top:

.pad layout align -top foo

layout distribute <type> [-space space] tagOrId [tagOrId ...]

<type> must be "-horizontal", "-vertical", or "-coords {x1 y1 x2 y2 ...}"

Distribute the specified items so that the space between them is equalized horizontally or vertically (by bounding box). Alternatively, -coords can be specified in which case the items will be distributed along the path specified by the coordinates with equal spacing between items. -space can be specified in which case the items will be distributed so there is space between each item. If -space and -coords are specified, then the items will be distributed along with the path specified by the coordinates with space between each item. If the items take up more space than is available on the specified path, they will continue along an extension of the last portion of the path.

layout position [-time animationTime] x1 y1 <type> x2 y2 tagOrId \

[tagOrId ...]

<type> must be "-ref tagOrId" or "-bbox {bbx1 bby1 bbx2 bby2}"

Position the specified objects relative to a target object, or a bounding box. Specify target point by a point on the unit square, and specify the source point by a point on the unit square. If animationTime is specified, then the objects are animated to their new position in the specified time (in milliseconds).

The following code moves all the objects with the tag "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 ...]

<type> must be "-width", "-height"

Scale the specified objects so that their bounding boxes are scaled (width or height) to the target. If a reference object is specified, then scale relative to that object. Otherwise, scale to an absolute dimension. Objects are scaled around their anchor points.

layout snap grid tagOrId [tagOrId ...]

Position the objects so that their anchor points are snapped to grid.

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.)

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.

If -layer is specified, then rather than lowering a set of items, it lowers the layer specified by tagOrId. (See the layer [57] command for more information about layers.)

The modifier command manipulates the user-specified modifier for event bindings. A user-specified modifier is a software equivalent of the Shift, Control, or other modifier keys. They can be used to isolate event bindings that all belong to one mode. See the documentation of the bind command for a more complete description. There are several subcommands:

modifier create <modifier>

Define modifier to be a user-defined modifier that can be used in future event bindings.

modifier delete <modifier>

Return the current active modifier.

modifier get

Delete modifier from the list of valid user-defined modifiers. Any event bindings that are defined with this modifier become invalid.

modifier set <modifier>

Make modifier be the current active modifier for this widget. modifier must have been previously defined with the 'modifier create' command.

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 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).

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

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.

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, 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)

Pops the top frame off the stack of coordinate frames. The resulting frame on the top of the stack becomes active. Also see pushcoordframe and resetcoordframe. Returns the frame popped off the stack.

Prints the current hierarchical tree of items to stdout (used for debugging). Returns an empty string.

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 -position or -scale 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 popcoordframe and resetcoordframe. Returns the current coordinate frame.

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.

If -layer is specified, then rather than raising a set of items, it raises the layer specified by tagOrId. (See the layer [57] command for more information about layers.)

.pad raise 24

   If we use the -one option:
   .pad raise -one 24 

       The original position turns to be:

Returns a random integer between the specified min and max points, inclusively.

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.

Remove all items specified by tagOrId from the group they are a member of, and return them to the pad surface. If any of the items were members of hierarchical groups, they are removed from all groups. If any of the items are not a member of a group, then they are not affected. Items removed are added to the pad surface just after the group in terms of display-list order.

By default, items are transformed so they don't change their location when removed from a group - even if the group has a transformation. This is implemented by transforming the item's transformation to be the inverse of the group's transformation. If the -notransform flag is specified, this inverse transformation is not applied, and the item will move by the group's transformation when removed. (Also see the addgroupmember, and getgroup commands). Returns an empty string.

The 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

Magnifies all rendering performed in the current renderscript by dz.

render translate dx dy

Translates all rendering performed in the current renderscript by (dx, dy).

render draw border bordertoken relief width x1 y1 x2 y2

render draw filledborder bordertoken relief width x1 y1 x2 y2

Draws a fake 3D border connecting the specified coordinates. (See 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

Draws the image specified by imagetoken at the point (x, y). This command can only be called within a render callback.

render draw line x1 y1 x2 y2 [xn yn ...]

Draws a multi-segment line connecting the specified coordinates.This command can only be called within a render callback.

render draw polygon x1 y1 x2 y2 [xn yn ...]

Draws a closed polygon connecting the specified coordinates. This command can only be called within a render callback.

render draw text string x y

Draws the specified text at the specified location. This command can only be called within a render callback.

render configure [option [value] ...]

Configures the state of the renderer. Option-value pairs may be specified as with the itemconfigure command, or if no options are specified, a list of all options and values are returned.

-capstyle capstyle

Sets the capstyle of lines for drawing within render callbacks. Capstyle may be any of: "butt", "projecting", or "round".

-joinstyle joinstyle

Sets the joinstyle of lines for drawing within render callbacks. Joinstyle may be any of: "bevel", "miter", or "round".

-linewidth width

Sets 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.

During a render callback triggered by the -renderscript option, this function actually renders the object. During a -renderscript callback, if 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.

Pops all the frames off of the coordinate stack. Results in an empty stack, so all coordinates are back to absolute coordinates. Also see pushcoordframe and popcoordframe. Returns an empty string.

Rotates all the items specified by tagOrId angle degrees. If (xctr, yctr) is specified, then all the items are rotated around the specified point. If the rotation point is not specified, then each item is rotated around its anchor point. All item types are rotatable except html pages, and widgets (such as buttons, scrollbars, and textfields). If a non-rotatable item is rotated, a Tcl error will be generated. (see the -angle itemconfigure option).

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 (ctrx, ctry), if specified. This command returns the scale of the first item. Note that the 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).

If animationTime is specified, then all the items moved will be animated over a period of animationTime milliseconds.

WARNING: setcapstyle is an obsolete command and will be removed in the next release. Replace all uses of setcapstyle with the 'render configure -capstyle' command.

WARNING: setcolor is an obsolete command and will be removed in the next release. Replace all uses of setcolor with the 'render configure -color' command.

WARNING: setfont is an obsolete command and will be removed in the next release. Replace all uses of setfont with the 'render configure -font' command.

WARNING: setfontheight is an obsolete command and will be removed in the next release. Replace all uses of setfontheight with the 'render configure -fontheight' command.

Sets the id of an existing item to id. If tagorid 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.

WARNING: joinstyle is an obsolete command and will be removed in the next release. Replace all uses of joinstyle with the 'render configure -joinstyle' command.

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, etc. Pad++ always includes at least the Tcl scripting language, but others may be active, depending on how Pad++ was built. This command controls whatever languages are currently installed. The language defaults to "automatic" where it tries to guess the language based on the syntax of the script. See the SCRIPTING LANGUAGES section in the Programmer's Guide for more details. (Also see the settoplevel command.)

WARNING: setlinewidth is an obsolete command and will be removed in the next release. Replace all uses of setlinewidth with the 'render configure -linewidth' command.

WARNING: setmodifier is an obsolete command and will be removed in the next release. Replace all uses of setmodifier with the 'modifier set' command.

Sets the language that the top-level interpreter should use. Pad++ always includes at least the Tcl scripting language, but others may be added. Returns an empty string. See the SCRIPTING LANGUAGES section in the Programmer's Guide for more details. (Also see the setlanguage command.)

Slide each of the items given by tagOrId by adding dx and dy to the x and y coordinates of the item's transformation (i.e., their -position itemconfigure option). This command returns a string with the (x, y) position at the item's anchor point. Note that the 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).

If animationTime is specified, then all the items moved will be animated over a period of animationTime milliseconds.

.set id [.pad create line 0 0 200 200]

.pad slide $id -80 30

20.000000 70.000000

Rudimentary sound support is available for the Irix (SGI) and Linux platforms. Currently, only ".au" sound file formats are supported. By default, Pad++ is built without sound. See the README file for instructions on building Pad++ with sound. The following subcommands implement sound:

.pad sound load file

This command loads a sound file, and returns a sound token that can be used to play the sound later.

.pad sound play sound_token [-volume volume]

This will play a sound specified by sound_token which is a sound loaded with the "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

This stops the sound referenced by 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].

Takes the coordinates for a spline and uses an adaptive bezier algorithm to generate the coordinates for a line that approximates the spline. error is how much error is allowed - a small error produces a greater number of points and more accuracy. A large error yields fewer points but the line is less accurate. See the section on SPLINE ITEMS for details on how splines are created. (Also see line2spline.)

Allows interaction with all text item types. This includes text, textfile, textfield, and textarea items. See TEXT ITEMS for a description of indices and marks. tagOrId specifies the text item to apply the following command to. Option and the args determine the exact behavior of the command. Note that the 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

Compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators <, <= ==, >=, >, or !=. If op is == then 1 is returned if the two indices refer to the same character, if op is < then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.

• delete index1 [index2]

Delete a range of characters from the text. If both index1 and index2 are specified, then delete all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at index1 is deleted. The command returns an empty string.

• get index1 [index2]

Return a range of characters from the text. The return value will be all the characters in the text starting with the one whose index is index1 and ending just before the one whose index is index2 (the character at index2 will not be returned). If index2 is omitted then the single character at index1 is returned. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then an empty string is returned.

• index index [char]

Returns the position corresponding to index in the form line.char where line is the line number and char is the character number. If char is specified, then the position is returned in the form char which is the character index from the beginning of the file. Index may have any of the forms described under INDICES.

• insert index chars

Inserts chars into the text just before the character at index and returns an empty string.

• mark option [arg arg ...]

This command is used to manipulate marks. The exact behavior of the command depends on the option argument that follows the mark argument. The following forms of the command are currently supported:

mark names

mark set markName index

mark unset markName [markName ...]

[92] pathName tree subcommand [args ...]

This command creates, maintains, and animates dynamic trees of Pad items. Items are created by other pad functions, and are placed into hierarchical tree structures to be managed by this code. These trees support a focus + context viewing structure, multiple foci, and a focus function which has a controlled level of influence on the tree.

Each node has a layout object associated with it which controls the position and resizing of the pad item at that node during a layout. Each layout controls a link item - a pad item created by the tree code, which graphically connects the node to its parent. This link item is maintained automatically by the tree code, but may be accessed and manipulated through the tree subcommand.

Each pad has a treeroot object, which is a list of all pad tree nodes on the surface. Each of these "root nodes" is an invisible treenode which controls certain subtrees on the pad surface. This organization is necessary to keep trees independent. Animation done at a node affects that node and its children, so we need to be careful to organize the nodes in such a way that all nodes we wish to "know" about each other are connected in some manner. Separate hierarchies can be made to "avoid" each other during animation by connecting them together under an invisible root node. When the layout function is called on the root node, both hierarchies will be laid out according to the layout object which resides at the root node.

A dynamic tree supports an arbitrary number of foci. Management of these foci is left up to the user. A node's focus is spread by a function which has several parameters. See the setfocus subcommand for more information.

Manipulation of the tree structure falls into four parts - tree management, layout, animation control, and parameter control.

Tree Management

A tree can be added to by creating new nodes and adding them to the existing tree structure. Nodes and subtrees can be moved within trees. Nodes and subtrees can be deleted, which will also delete the pad item associated with the treenode. Nodes and subtrees can be removed, which simply removes the treenode associated with the object, but leaves the object itself alone.

Layout

The default layout provided with the current version of this code creates a hierarchical tree in which a node's children are laid out to the right of the node. This layout prevents any overlapping of nodes by calculating the bounding box of the subtree rooted at a node, and laying out nodes so that these bounding boxes do not intersect.

Animation control

A tree always animates its members. It may also animate the view at the same time the members are being animated.

Parameter control.

There are a variety of parameters associated with the layout at a node, and the control of animation of a tree.

Trees are created and manipulated through the tree subcommands:

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.

Returns the type of the item given by tagOrId, such as rectangle or text. If tagOrId refers to more than one item, then the type of the first item in the display list is returned. If tagOrId doesn't refer to any items at all then an empty string is returned.

This forces any outstanding updates to occur immediately. If the -dissolve flag is specified, then speed determines how quickly the update is done. If speed is 0, the update will happen quickly with a swap buffer. If speed is between 1 and 3, the update will happen with a dissolve effect where 1 is the fastest and 3 is the slowest. If the withRefinement flag is specified, this forces all refinements to occur immediately as well - which could be a slow process. Returns an empty string.

   	pathName urlfetch Token
   where valid options are:
        -file <filename>
		-var <variable>
        -updatescript <updateScript>
        -donescript <doneScript>
        -errorscript <errorScript>

Retrieves the specified URL (Universal Resource Locator) from the World Wide Web. This command returns immediately, and the retrieval is done in the background (within the same process using a file handler.) As portions of the data comes in, updateScript will be executed, and doneScript will be executed when all of the data has completely arrived. If there are any errors retrieving the data, then errorScript will be executed. 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.

There are three methods to access the data retrieved by urlfetch. The first method is to specify a file (with -file) in which case the data is written to that file as it is retrieved. The second method is to specify a Tcl variable (with -var) in which case the data is stored in that global variable as it is retrieved. The variable will be updated with the current data before updateScript and doneScript are executed. Note that the variable is not cleared by 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"

This moves the core pointer relative to its current position by (dx, dy) pixels. Moving the pointer is often called "warping", and thus the name of the command is warp. Note that generally speaking, warping the cursor is frowned upon in user interfaces, but this command is supplied as there are some cases where it is ok.

Changes the shape of the top-level window containing the Pad++ widget specified by pathName. The two parameters each specify lists of coordinates that specify the shape of the window. All coordinates are scaled to fit the existing width of the window, larger numbers in X go to the right, and larger numbers in Y go up. innercoords represents the area that can be painted in, and outercoords represents the overall window shape. The difference between these two shapes becomes the windows border. If innercoords and outercoords are both empty strings, then the window returns to its default rectangular shape. This command returns the current window shape. If window has the default shape, it returns {} {}.

For example, the following command changes the top-level window shape to an inverted triangle.

		.pad windowshape {0 50 50 50 25 0} {0 50 50 50 25 0}

Writes out all the items on the Pad++ surface into file. If tagOrId's are specified, then just those items are written out. The file that is written out should be read back in with the read command. If file is an empty string, than this command returns a string containing the data instead of writing it to a file. If a valid filename is specified, then this command returns an empty string. Only non-default slots of each object are written out.

Files may be written in different formats (all of which can be read with the 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.

If the -relative flag is specified, then all referenced files (such as textfiles and images) are referenced with filenames relative to the file that is saved. This makes it easier to move files between machines as an entire directory structure with the images can be copied, and the pad files will still work. If the -relative flag is not specified, then all referenced files are referenced with absolute pathnames.

As the write command writes out objects on the pad, it generates a <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 around specified pad position by multiplicitive factor. If animateTime is specified, then animate the zoom and take animateTime milliseconds for the animation. If an optional list of portals is specified, then change the view within the last portal. The entire list is necessary in case the last portal is sitting on a different surface then this function is called with. Returns an empty string.

The available item types are:

Alias, Button, Canvas, Checkbox, Checkboxmenuitem, Choicemenu, Frame, Grid, Group, HTML, Image, KPL, Label, Line, Menu, Menubar, Menuitem, Oval, Pad, Panel, Polygon, Portal, Rectangle, Scrollbar, Spline, Tcl, Text, Textarea, Textfield, Textfile, and Window.

Button, Canvas, Checkbox, Checkboxmenuitem, Choicemenu, Frame, Menu, Menubar, Menuitem, Panel, Scrollbar, Textarea, Textfield, and Window.

This is a summary of every itemconfigure option in alphabetical order. Each option either applies to every possible item type, or has a list of item types to which it applies

-aliases [1] (Read-only) Returns all aliases of the item

-alwaysrender [2] True if the item must be rendered, even if the system is slow and the item is small

-anchor [3] The part of the item that -position refers to

-anchorpt [4] The (x, y) portion of -position

-angle [5] Specifies absolute rotation of item

-anglectr [6] Specifies absolute rotation of item, rotating about specified point

-arrow [7] Whether to draw arrow heads with this item

(Available only for line, spline types)

-arrowshape [8] The shape of drawn arrow heads

(Available only for line, spline types)

-bb [9] A script that gets evaluated to specify the bounding box of an item

(Available only for kpl, tcl types)

-border [10] Specifies border color of item

(Available only for html, portal types)

-borderwidth [11] Specifies width of border

(Available only for html, portal types)

-capstyle [12] Specifies how to draw line ends

(Available only for line, spline types)

-clipping [13] Controls if items are clipped to their bounding box when rendered

-command [14] Callback for widgets

(Available only for button, command types)

-dither [15] Render with dithering

(Available only for image types)

-divisible [16] True if events go through a group to its members

(Available only for frame, grid, group, html, panel types)

-donescript [17] A script to evaluate when a background action has completed

(Available only for html types)

-editable [18] True if text item is editable

(Available only for text, textfile, textfield types)

-errorscript [19] A script to evaluate when a background action has an error

(Available only for html types)

-events [20] True if item receives events, false otherwise

-faderange [21] Range over which an item fades in or out

-file [22] File an item should be defined by

(Available only for textfile types)

-fill [23] Specifies fill color of item

(Available only for button, frame, html, label, scrollbar, panel, fill, polygon, portal,

rectangle, textfield types)

-font [24] Specifies font to use for text

(Available only for button, html, label, portal, text, textfile, textfield types)

-from [25] Starting value of valuator widget

(Available only for scrollbar types)

-height [26] Height of an item. Normally computed, but can be set to squash/stretch item

-html [27] The HTML item associated with an htmlanchor

(Available only for htmlanchor types)

-htmlanchors [28] The anchors associated with an HTML page

(Available only for html types)

-image [29] Image data associated with item (allocated by image alloc)

(Available only for htmlanchor, image types)

-info [30] A place to store application-specific information with an item

-ismap [31] True if an htmlanchor is an image map

(Available only for htmlanchor types)

-joinstyle [32] Specifies how to draw the joints within multi-point lines

(Available only for line, spline, oval, polygon, rectangle types)

-layer [33] The layer an item is on

-linesize [34] Amount widget should change to represent a line change

(Available only for scrollbar types)

-lock [35] Locks an item so it can not be modified or deleted

-lookon [36] Specifies the pad widget this item sees

(Available only for portal types)

-maxsize [37] The maximum size an item is rendered it (absolute or relative to window size)

-members [38] The list of members of a group

(Available only for frame, group, html, panel types)

-memberlabels [39] List of labels for a pull-down or pop-up menu

(Available only for menu and choicemenu types)

-menubar [40] Menubar associated with a frame

(Available only for frame types)

-minsize [41] The minimum size an item is rendered it (absolute or relative to window size)

-noisedata [42] Specifies parameters to render item with noise

(Available only for line line types)

-orientation [43] Orientation of widget (horizontal or vertical.)

(Available only for scrollbar types)

-pagesize [44] Amount widget should change to represent a page change

(Available only for scrollbar types)

-pen [45] Specifies pen color of item

(Available only for button, label, line, spline, oval, polygon, portal, rectangle, text

textfile, textfield types)

-penwidth [46] Specifies width of pen

(Available only for line, spline, oval, polygon, rectangle types)

-position [47] The absolute position of the object (x, y, scale)

-reference [48] What item an alias references

(Available only for alias types)

-relief [49] Specifies how border should be rendered (raised, flat, sunken, ridge, groove)

(Available only for button, portal types)

-renderscript [50] A script that gets evaluated every time an item is rendered

-rposition [51] The relative position of the object (to groups)

-scale [52] The (scale) portion of -position

-state [53] State of an item (such as visited, unvisited, etc.)

(Available only for button, htmlanchor types)

-sticky [54] Specifies if an item should stay put when the view changes

-tags [55] List of tags associated with an item

-text [56] The text of any item containing text

(Available only for button, label, text, textfile, textfield types)

-timerrate [57] Frequency timerscript should fire

-timerscript [58] Script associated with an item that fires at regular intervals

-title [59] Some items only: Title of an item

(Available only for portal types)

-to [60] Ending value of valuator widget

(Available only for scrollbar types)

-transparency [61] Transparency of an item. 0 is completely transparent, 1 is completely opaque

-updatescript [62] A script to evaluate when a background action has made progress

(Available only for html types)

-url [63] The URL associated with an item

(Available only for html, htmlanchor types)

-value [64] Current value of valuator widget

(Available only for scrollbar types)

-view [65] Specifies the view this item sees

(Available only for pad, portal types)

-viewscript [66] A script that gets evaluated whenever the view is changed

-visiblelayers [67] The layers that are visible within this view (just for portals and surface, item #1)

(Available only for pad, portal types)

-width [68] Width of an item. Normally computed, but can be set to squash/stretch an item

-writeformat [69] Controls whether disk-based item is written out by copy or reference

(Available only for image types)

-zoomaction [70] A script that gets evaluated when an item is scaled larger or smaller than a set size

[1] -aliases (read-only)

(Available for all item types)

This returns all the alias items that reference this item.

(Available for all item types)

The rendering engine may decide to not render an item for reasons of efficiency (although it may get rendered at higher levels of refinement). When this flag is set (i.e., equals 1), the item will be rendered no matter how big it is (as long as it is bigger than its -minsize. Defaults to false (0).

(Available for all item types)

AnchorPos tells how to position the object relative to the positioning point for the item (see -position); it may have any of the forms accepted by Tk_GetAnchor. For example, if anchorPos is "center" then the object is centered on the point; if anchorPos is "n" then the object will be drawn so that its top center point is at the positioning point. This option defaults to center.

(Available for all item types)

This is an alias for the first two elements of the -position itemconfigure option. (x, y) specifies the anchor point of the item. This means that the item will be positioned so that its anchor (north, center, southwest, etc.) will appear at the specified anchor point. (x, y) are absolute quantities, independent of the current view and independent of any group membership. (Also see the -anchor, -position, -rposition, and -scale itemconfigure options.)

(Available for all item types except HTML and widgets)

Sets the absolute rotation of an item in degrees. The item is rotated around its anchor so that it is rotated angle degrees relative to its creation. (Also see the rotate command.)

(Available for all item types except HTML and widgets)

Sets the absolute rotation of an item in degrees. The item is rotated around the point (xctr, yctr) so that it is rotated angle degrees relative to its creation. (Also see the rotate command.)

(Available only for line, spline types)

Indicates whether or not arrowheads are to be drawn at one or both ends of the line. where must have one of the values "none" (for no arrowheads), "first" (for an arrowhead at the first point of the line), "last" (for an arrowhead at the last point of the line), or "both" (for arrowheads at both ends). This option defaults to "none".

(Available only for line, spline types)

This option indicates how to draw arrowheads. The shape argument must be a list with three elements, each specifying a distance. The first element of the list gives the distance along the line from the neck of the arrowhead to its tip. The second element gives the distance along the line from the trailing points of the arrowhead to the tip, and the third element gives the distance from the outside edge of the line to the trailing points. If this option isn't specified then Pad++ picks a "reasonable" shape.

(Available only for kpl, tcl types)

A script that will be evaluated to compute the bounding box of this item. For Tcl, It should return a 4 element list whose members are "x1 y1 x2 y2" which are the lower left and upper right corners of this items bounding box. For KPL, It should return two two-element vectors that specify (x1, y1), (x2, y2).

(Available only for html, portal types)

Color specifies a color to use for drawing the border of the portal; it may have any of the forms accepted by Tk_GetColor. If color is "none", the outline will not be drawn. This option defaults to the fill color.

(Available only for html, portal types)

Width specifies the width of the border in current units to be drawn around the item. Wide borders will be drawn completely inside the path specified by the points of this object. Note that this is different than pens. If width is 0, then the border will always be drawn one pixel wide, independent of the zoom. Width defaults to 1 pixel.

(Available only for line, spline types)

Specifies how the ends of the line are drawn. cap may be one of:

• butt: The ends are drawn square, at the end point.

• projecting: The ends are drawn square, past the endpoint.

• round: The ends are rounded.

(Available for all item types)

By default, built-in items (such as lines, text, etc.) do not get clipped to their bounding box, and procedural items (items with -renderscripts) do. This flag turns clipping on or off. Be warned, that turning off clipping for a procedural object is dangerous. If you draw outside the object's bounding box, you can end up with screen garbage. Defaults to true (1) for items with -renderscripts, and false (0) for all other items.

(Available only for button, command types)

A script that gets executed when the widget is activated. The definition of activation for each widget is different. For example, a button is activated when it is pressed and released while the pointer is still over the button. A scrollbar is activated whenever the thumb is moved. Some widgets append information about the activation on the end of the script (for instance, scrollbars append the current value). See the description of each widget for information about this.

(Available only for image types)

Specifies if and when the image is rendered with dithering. Dithering is a rendering technique that allows closer approximation to the actual image colors, even when the requested colors are not available. Rendering images with dithering is much slower than without, so this option allows control as to when (if at all), dithering is used. dithermode may be any of

• nodither: The image is never rendered with dithering.

• dither: The image is always rendered with dithering.

• refinedither: The image is initially rendered without dithering, and then refined with dithering.

Defaults to refinedither (dither only on refinement).

(Available only for frame, grid, group, html, panel types)

Specifies whether events should go to the grid members. If -divisible is 1 (true), events never go to the grid object, but pass through it to the members. If the event is within the bounding box of the group, but does not hit any members, then it will be ignored by the group. If -divisible is 0 (false), then the event will go to the group if it is within the bounding box of the group whether there is a member at the place the event points to or not. Defaults to 1 (true).

(Available only for html types)

If script is specified, it gets evaluated when the html item has completed loading - including all in-line images. script is postpended with the id of the html object. This is necessary because the script is typically specified on the create line where the id of the html object is not yet known.

(Available only for text, textfile, textfield types)

If editable is TRUE, then the item's default event handlers will allow the item to be edited. This applies only to text widgets. Default text editing includes mouse copy and paste, and uses basic emacs-like bindings for manipulating the cursor.

(Available only for html types)

If script is specified, it gets evaluated if there is an error creating the html item. An error can occur for many reasons - especially because creating an html typically starts a network communication process for fetching the URL. script is postpended with the id of the html object. This is necessary because the script is typically specified on the create line where the id of the html object is not yet known.

(Available for all item types)

Controls whether an item receives input events. If set to false (0), it does not respond to events. Defaults to true (1).

(Available for all item types)

Controls over how long a period an item fades out as it approaches its minimum or maximum size. value specifies this period as a percentage of the object's size (from 0.0 to 1.0). Where 0.0 means that the item doesn't fade out all, it just blinks off when its extreme is reached, and 1.0 means that it slowly fades out over its entire range of sizes. Defaults to 0.3. (Also see the -minsize and -maxsize itemconfigure options.)

(Available only for textfile types)

fileName specifies the filename to read a text file from.

(Available for button, frame, html, label, scrollbar, panel, fill, polygon, portal, rectangle, textfield types)

Fill the background of the html item with color, which may be specified in any of the forms accepted by Tk_GetColor. If color is "none", the background will not be drawn. It defaults to the background of the Pad++ widget it is created on.

(Available only for button, html, label, portal, text, textfile, textfield types)

Specifies the font to be used for rendering text for this item. 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".

(Available only for scrollbar types)

Specifies the starting (lowest) value for a valuator widget to use. (Also see the -to, -linesize and -pagesize itemconfigure options.)

(Available for all item types)

By default, the height of every item is automatically computed based on its contents. If the -height option is set, however, then this overrides the automatically computed value. Most items are squashed or stretched to fit the specified height. Note that text and alias items, however, are clipped instead of being squashed or stretched. (Also see the -width itemconfigure option.)

(Available only for htmlanchor types)

Returns the html item this anchor belongs to. This is a read-only option.

(Available only for html types)

Returns all the anchors that are part of this HTML item. This is a read-only option, and may not be set.

(Available only for htmlanchor, image types)

Specifies the image data associated with this item. Note that changing which image data an item uses does not effect the image data. Specifically, if the -image is set to the empty string, the image data it previously specified is unaffected and still needs to be deallocated with the "image free" command if it is no longer being used. (Also see the image command.)

(Available for all item types)

A generic info field where the user may place any string. (See the find withinfo command).

(Available only for htmlanchor types)

Returns true if this anchor is an imagemap. This is a read-only option.

(Available only for line, spline, oval, polygon, rectangle types)

Specifies how the joints at vertices are drawn. join may be one of:

• bevel: The joints are drawn without protruding. They are cut-off and sharp.

• miter: The joints are drawn protruding to a point.

• round: The joints are rounded.

(Available for all item types)

Specifies the layer the item is on. Every item sits on a layer (which is specified by a string), and each view (top-level window and portals) specifies which layers are visible within that view. This gives control over objects are visible where and can be used with portals to implement very simple filters. (See the -visiblelayers itemconfigure option of portals and the top-level window which is specified by the surface (item 1). Defaults to "main".

(Available only for scrollbar types)

Specifies the amount a valuator widget should change to represent a line change. For a scrollbar, this is the amount changed when the trough is clicked. (Also see the -from, -to and -pagesize itemconfigure options.)

(Available for all item types)

When an item is locked, it can not be deleted or modified (except for changing the lock status). Note that attempting to modify or delete a locked item does not generate an error. It fails silently. This is so it is easy to modify all items associated with a tag and if certain items are locked they will just not get modified. The restricted commands on locked items are: coords, delete, itemconfigure, scale, slide, and text.

(Available only for portal types)

Specifies which Pad++ surface this portals looks onto. surface should be the complete pathName of a Pad++ widget. Defaults to the surface the portal was created on.

(Available for all item types)

Specifies the maximum size (in current units) this item should be rendered at. That is, if the view is such that the largest dimension of this object is greater than size units, it will not be displayed. When an object is not displayed because it is too large, it does not receive events. When an object approaches its maximum size it will fade out until it completely disappears when it reaches its maximum size. If size is -1, then it has no maximum size and will never disappear because it is too large. See the -faderange itemconfigure option to control how quickly an item fades out.

size may also be specified as a percentage of the view it is visible in (top-level window or portal). To specify size as a percentage, it should be in the range from 0 to 100 and end with a "%". Example:

		.pad ic 5 -minsize 55%

size defaults to 10,000 pixels.

Also note that the rendering engine may decide to not display an item for reasons of efficiency if it is reasonably small. See the -alwaysrender flag to avoid this.

(Available only for frame, group, html, panel types)

members is a list of object ids that specify the list of members of this group. Setting the members of a group first removes all existing members, and then inserts the new members. The members are rendered in the order they are specified in members.

(Available only for menu and choicemenu types)

Specifies a list of labels that can be used when creating a menu or choicemnu instead of explicitly creating a menuitem for each label. I.e.:

			.pad create menu -memberlabels {"Content" "Index" "Help"} \
				-text "Help"

(Available only for frame types)

Specifies the menubar associated with this frame (if any). By associating a menubar with a frame, the menubar is resized so as to be positioned along the top of the frame in the traditional manner. When the frame is resized, the associated menubar is also resized.

(Available for all item types)

Specifies the minimum size (in current units) this item should be rendered at. That is, if the view is such that the largest dimension of this object is less than size units, it will not be displayed. When an object is not displayed because it is too small, it does not receive events. When an object approaches its minimum size it will fade out until it completely disappears when it reaches its minimum size. See the -faderange itemconfigure option to control how quickly an item fades out.

size may also be specified as a percentage of the view it is visible in (top-level window or portal). To specify size as a percentage, it should be in the range from 0 to 100 and end with a "%". Example:

		.pad ic 5 -minsize 55%

size defaults to 0.

Also note that the rendering engine may decide to not display an item for reasons of efficiency if it is reasonably small. See the -alwaysrender flag to avoid this.

(Available only for line types)

Specifies the noise parameters used to make rough-looking lines. noisedata is a four element list of numbers of the form:

"Pos Freq Amp Steps"

Rough lines are generated using the Perlin noise function. The Perlin noise function is like a sin function with a very irregular amplitude - like sin, noise has a constant period (one), but no two segments of the noise curve are alike. Noisy lines are generated by adding noise to the tangent direction of a line.

In the current implementation, there are four noise parameters: Pos, Freq, Amp, and Steps. Pos determines what part of the noise curve is sampled for that object. Freq determines the rate of sampling, Amp indicates the level, and Steps indicates how many samples to introduce per line segment. The drawing algorithm is straightforward. For each line segment, coordinates are generated as follows:

	DrawRoughLine(x1, y1, x2, y2, Pos, Freq, Amp, Steps) :
		step  = 1.0/Steps;
		mag   = length(x1,y1,x2,y2);
		theta = direction(x1,y1,x2,y2);

		xmag = Amp * sin(theta) * mag;
		ymag = Amp * cos(theta) * mag;

		vertex(x1, y1);

		for (a = step; a < steps; a += step) {
			n = noise(Pos);
			vertex(lerp(a,x1,x2) + n*xamp, lerp(a,y1,y2) + n*yamp);
			Pos += Freq;
		}
		vertex(x2, y2);

Note that we multiply Amp by mag, the length of the line. This is necessary in Pad++ since the zooming functionality means that lines can be of nearly any size. Making the level of noise proportional to the length of the line keeps the informality uniform at all sizes. (We should probably also modulate the number of points generated by the thickness of the line, so small thin lines are cheap).

Values of 0.3 for Freq, 0.1 for Amp, 10 for Steps produces pleasant-looking lines. Pos can be an arbitrary floating point number - giving different objects unique values for Pos ensures that each object has a different appearance.

(Available only for scrollbar types)

Specifies the orientation of a rectangular widget. orientation can be "horizontal" or "vertical".

(Available only for scrollbar types)

Specifies the amount a valuator widget should change to represent a page change. For a scrollbar, this is the amount changed when an arrow is clicked. (Also see the -from, -to and -pagesize itemconfigure options.)

(Available for button, label, line, spline, oval, polygon, portal, rectangle, text, textfile, textfield types)

Color specifies a color to use for drawing the line; it may have any of the forms acceptable to Tk_GetColor. It may also be "none", in which case the line will not be drawn. This option defaults to black.

(Available only for line, spline, oval, polygon, rectangle types)

Width specifies the width of the pen in current units to be drawn around the item. Wide lines will be drawn centered on the path specified by the points. If width is 0.0, then the pen will always be drawn one pixel wide, independent of the zoom. Width defaults to 1 pixel.