ccanvas - a wrapper around canvas that allows length and angle arguments to be expressions, provides each ccanvas window its own scale factor, adds some new units, and drawing functions.
Package ccanvas is a wrapper around the Tk canvas command. All length and angle arguments to subcommands and options can be expressions. Some additional length units (% of screen, user defined) and angle units (r -radians, R - revolutions) can be used in canvas expressions. There are additional subcommands to do calculations with canvas lengths and angles and manipulate canvas items.
All the canvas subcommands still work as described in the canvas documentation. Only additions and other changes are described here.
Options with length arguments will take expressions, and can use some new units.
In most cases % will be 0.01 times the smaller of screen width and height. There are exceptions for some options:
If the -height and -width options are set after the -scale option, units used to define them will reflect the changes in scaling.
-scrollregion can be a list of four length expressions, or one of the special values: center, centered, n, ne, e, se, s, sw, w or nw which put the origin (0,0) at the given point in the canvas window based on the current window height and width.
The ccanvas command creates a new canvas with additional capabilities.
Any length or coordinate value can be an expression making full use of the canvas units (c, i, m, p) and some new units (r-radians and R-revolutions for angles, %-percent of screen size for lengths). Expressions are evaluated by Tcl command expr so all its operators and functions can be used. See EXPRESSIONS
pathName create line $xo $yo $xo+2i $yo -fill red
will draw a line from coordinates in xo, yo to a point 2 inches to the right.
Expressions can include variables (as in expr)
Expressions can include references to x and y coordinates from an associated coordinate list.
pathName create rectangle $xo-$w/2 $yo-$h/2 x+$w y+$h -fill red
x and y refer to the previously defined point coordinates. This draws a rectangle with width in w, height in h, centered at xo, yo.
Any expression result can be saved in a variable for later use.
The -height and -width can be set as a percent of screen size other lengths can be set as a % of the smaller of screen width or height.
ccanvas pathName -height 80% -width 60%
canvas pathName will be 80% of screen height tall and 60% of screen width wide.
a new option -scale allows each canvas to have their own scaling for length units to pixels.
ccanvas pathName -height 80% -width 60% -scale 16i
canvas pathName will be 80% of screen height tall and 60% of screen width wide. Lengths will be scaled so that a 16 inch long line will fit in the shorter of the window's height or width.
new subcommands to do calculations in the context of the canvas and its scaled units:
expr evaluate an expression, optionally referring to coordinates from a supplied list. The result of the calculation is returned.
exprs evaluate multiple expressions in the context of a given coordinate list. A list of results is returned.
There are additional subcommands to transform items:
crotate - rotates lines, polygons and text. Can rotate circles and circular arcs, but not general ovals or arcs (generates error message). Can rotate rectangles by multiples of 90 degrees (other angles are an error). Bitmaps, images, and window item`s anchor point is moved, but the items orientation does not change.
Tk9.0b1 adds a rotate sub-command with somewhat different logic than crotate.
flip - mirror item`s coordinates in the y axis. The orientation of arcs, bitmaps, images and windows does not change, the e/w anchors are swapped. Text anchor, location and orientation change, but the text still reads in the same direction.
flop - mirror item`s coordinates in the x axis. The orientation of bitmaps, images and windows does not change, the n/s anchors are swapped and location changes. Text location, anchor and orientation change.
dup duplicate items and modify the new copy's configuration. Modifications include adding and removing tags as well as changing any other configuration option given. Returns a list of new ids.
dupid duplicates a single item. Returns the id of the new item.
itemcfg returns a list of an items configuration options and values that can be used to create a duplicate of that item. Coordinates, and item type are not included in the list.
itemmincfg returns a list of an items configuration options and values that can be used to create a duplicate of that item. Options with default values, coordinates, and item type are not included in the list.
In addition to the normal canvas units (c-centimeters i-inches m-millimeters p-points and the default pixels) ccanvas adds several new units:
% - percent of screen. This unit is normally 0.01 times the minimum of screen height or width in pixels. However when used in the -height argument it is 0.01 times the screen height. Similarly it is 0.01 times the screen width for -width. Useful for defining window size and screen size dependent lengths (such as -closeenough)
r - radians. Can be used for trigonometric functions. The canvas defaults to angles in degrees which have no unit designator.
R - revolutions. One revolution is 360 degrees.
Additional length units specific to a canvas can be defined. See subcommand addLengthUnit below.
canvas widgets documentation only mentions single letter unit names. Actually the widget will allow multiple character names, but only uses the first character. In fact this is included in the canvas.test file (where "cm" is used as a unit). The following will work with no errors:
.c create rectangle -1inch -1centimeter 100millimeter 150points
only the first letter in the unit designator is used, however these "work" too:
.c create rectangle -1iguana -1cubicFurlong 100miles "150pouncing tigers"
and the units are still inches, centimeters, millimeters, except for 150pouncing tigers, which canvas widgets see as points (as of Tk8.6.13), but ccanvas widgets give an error (caused by the space).
ccanvas will accept multi-letter unit names, but outputs that use units will only have single character unit names.
Any length, x or y coordinate, or angle input value can be an expression.
Values with units consist of a magnitude followed by a unit specifier. For example an expression for the length along the y axis of a 5 inch long line at a 30 degree angle is:
pathName expr 5i*sin(30)
In this case 5i is 5 inches. The angle argument for the sin function defaults to degrees.
Values with units are always converted to pixels, or for angles to radians before the expression is evaluated by the Tcl expr command. Results in radians from inverse trig functions are converted to degrees before further use in an expression.
pathName expr asin(0.5)
returns 30 (in an angle's default degree units)
If one inch is 100 pixels:
pathName expr 2*1i+7
returns 207 pixels.
The expressions are evaluated by the Tcl expr command after units and coordinate references are substituted. The Tcl expr command sees all lengths as pixels and all angles as radians. The results are converted back to ccanvas default units (pixels and degrees). The results from the expr, exprs and coords subcommands can be reported in any selected unit.
Expressions can include variables as in expr
Expressions can contain references to x and y coordinates from an associated coordinate list. When defining an items coordinates the associated list is the one being defined. In other cases it can be specified as part of the subcommand.
pathName create line $xo $yo x+1i y x y+2.5i x(0) y -fill red
Draws a line starting at coordinates in variables xo and yo, goes right 1 inch, then down 2.5 inches, finally left until it is below the original point. x and y refer to the x or y coordinate from the previous point in the coordinate list being defined. x(0) refers to the x coordinate of the first point in the coordinate list.
Negative coordinate pair indexes count back from the end of the coordinate list. x is short hand for x(-1), similarly for y and y(-1). When used while defining coordinates for a new item x(...) and y(...) only see the completed x,y coordinate pairs. In particular if x or x(-1) is used to define a y coordinate, the value will be from the previously defined x,y pair, not the x value associated with the y being defined. For example the coordinates for the line:
pathName create line 1i 2i 3i x(-1)
the coordinates actually used will be {1i 2i 3i 1i} not {1i 2i 3i 3i}.
x() is a special case that refers to the most recently defined x coordinate, even if the corresponding y coordinate has not been defined yet (or is being defined by this expression). x() is different from x or x(-1). When x() is used to define a y coordinate it will return the last defined x coordinate (the one just before the y coordinate being defined). x or x(-1) will return the x coordinate from the last complete x,y coordinate pair. x() can be useful when defining a circle or square around the canvas origin:
pathName create oval -1i x() -x -y -fill red
defines a circle with 1 inch radius centered at 0,0. The coordinates for the circle would be {-1i -1i 1i 1i}.
Any expression can have an optional result specifier on the right end. The result specifier starts with a single "=" followed by a variable name (which can include namespace qualifiers "::", but cannot include a single ":").
pathName create line $xo $yo x+1i=x1 y-2i=y1 -fill red
saves the x,y coordinates of the last point in the line in x1 and y1
If a result is saved in a variable, which is later used in another expression in the same command, the expression using the variable must be in curly braces {} or otherwise be prevented from being substituted as the command line is processed before the command executes.
pathName create line 1i 1i x+1i=xo y x+1i y+1i {$xo-1i} y -fill red
if {$xo-1i} was not in braces, the value of xo before the command was executed would be used (or cause an error if xo was not already defined), rather than the value saved earlier in the coordinate list. As a general rule expressions using variables should be braced (just like Tcl expr, and for similar reasons).
Results from the expr and exprs subcommands can be in any selected unit by adding a colon ":" and unit designator to the end of the result specifier.
pathName expr 45i+3c
return the result in default units (pixels)
pathName expr 45i+3c=rr
return the result in default units (pixels) and save it in rr
pathName expr 45i+3c=:m
the result is returned in millimeters
pathName expr 45i+3c=rr:m
return the result in millimeters and save it in rr
Units are a convenience feature to simplify calculating coordinates, lengths and angles. They are not checked to see that they make sense. None of the following nonsense expressions will cause an error.
ccanvas .c -height 5i+3R
would set height to 5 inches plus 1020 (3*360) pixels.
pathName expr sin(4i)
would convert 4i to a number of pixels, then interpret that as an angle in degrees. Probably not what anyone would want.
All canvas subcommands that expect lengths, coordinates or angles can now accept expressions using canvas units.
Other modifications to canvas subcommands are:
Return a list of the coordinates in the specified units for the item with the tagOrID. If multiple items are selected, return coords for the first one on the display list. See canvas for more details and other forms of the coords subcommand.
creates a new length unit with the length set by the following expression. The unit name is a single alphabetic character (char), and can be used like any other length unit. Additional units are specific to the canvas they are defined in. For example:
pathName cmd addLengthUnit g 0.1i
defines a new length defined as 0.1 inch. Useful for drawing on a 0.1 inch grid.
expr evaluates the expression and returns the result. If a coordinate list, a tag or id is given, its coordinates can be referenced in the expression using x(...) or y(...) as noted above.
pathName expr x(1)*2+1i 4
Would multiply x coordinate of item 4's second point by 2, add 1 inch and return the value in pixels. Note item 4's coordinates are not changed.
exprs expects a possibly empty coordinate list, tag or Id to supply an optional set of coordinates for use in the following expressions (using x(..) and y(..)), followed by one or more expressions. The results of all expressions are returned as a list. Individual expression results can be saved in variables too.
pathName exprs 33 x(0)+5i y(0)+5i x(1)+4i y(1)+4i=yy
returns a list of 4 numbers and saves the last result in yy, all based on the first 2 coordinate pairs of item 33
rotates all items specified by the tagOrId counter clockwise about the origin (0,0) or the point specified by xo and yo, by the angle specified.
crotate normally just rotates the points in the coordinate list. Where this does not make sense rotate might be able to calculate new coordinates that properly rotate the item. When new coordinates that properly rotate the item cannot be calculated an error occurs:
arc - can only be rotated if it is a segment of a circle. Consider converting to a polygon or line before rotation.
oval - can only be rotated if it is a circle. Consider converting it to a polygon before rotation.
rectangle - if not rotating by a multiple of 90 deg, consider converting to a polygon.
pathName crotate 4 90 1i 1i
rotate item 4 90 degrees counter clockwise around the point at 1i,1i
mirror all the items specified by the tag through a line parallel to the y axis and through xo (or the origin) on the x axis.
Mirror all the items specified by the tag through a line parallel to the x axis and through yo (or the origin) on the y axis.
Return a list of all configuration options and values to define the item with the tag or Id. If multiple items were selected, only the first in the display list is used.
Return a minimum list of configuration options and values to define the item with the tag or Id. If multiple items were selected, only the first in the display list is used. Configuration options set to their default value are not returned.
Duplicate all items with the given tag or Id , modifying their configuration with all of the following option/value pairs. Returns a list of new item ids. In addition to the items normal configuration options two new ones are added to allow manipulating the newly created duplicates:
-addtag tagOrId ... Append the supplied list of tags to the new item's existing tags. Useful to separate the new items from the originals.
-dtags tagOrIds ... Delete any of the tags in the supplied list from the new item's existing tags.
similar to dup but only duplicates a single item. Returns the new items id.
See layout.tcl and rdraw.tcl
The image manipulation subcommands will likely be refined based on how they work in actual use.
canvas
Canvas
Copyright © 2023 J.D. Bruchie (BSD license, see license file)