#
Prev |  | Next

# canvas

## Name

canvas -- A widget which displays graphic objects (in gnoclCanvas).

## Synopsis

canvas [`-option` `value`...]

## Screenshot

## Options

-antialiased

  type: boolean (default: 1)

  Whether the canvas is antialiased. This cannot be changed after creation.

-background

  type: color

  Background color of the canvas.

-centerScroll

  type: boolean

  Whether to center the scrolling region in the canvas window when it is smaller than the canvas' allocation.

-data

  type: string

  User defined data which can be retrieved via the cget subcommand.

-hasFocus

  type: 1

  This sets the focus to the widget. To unset the focus it must be set to another widet.

-height

  type: integer

  Height of the widget.

-name

  type: string

  Name of the widget, can be used to set options in an rc file.

-onButtonPress

  type: string (default: "")

  Tcl command which is executed if a mouse button is press inside the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %t | type of event: one of buttonPress, button2Press or button3Press %x | x coordinate %y | y coordinate %b | button number %s | state of the buttons and modifiers (bitmask) TABLE

-onButtonRelease

  type: string (default: "")

  Tcl command which is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %t | type of event: always buttonRelease %x | x coordinate %y | y coordinate %b | button number %s | state of the buttons and modifiers (bitmask) TABLE

-onEnter

  type: string (default: "")

  Tcl command which is executed if the mouse enters the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %x | x coordinate %y | y coordinate %s | state of the buttons and modifiers (bitmask) TABLE

-onKeyPress

  type: string (default: "")

  Tcl command which is executed if a key is pressed while the widget is having the focus. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %k | key code as integer %K | key code as symbol %a | unicode unicode character, or the empty string if there is no corresponding character. %s | state of the buttons and modifiers (bitmask) TABLE

-onKeyRelease

  type: string (default: "")

  Tcl command which is executed if a key is released while the widget is having the focus. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %k | key code as integer %K | key code as symbol %a | unicode unicode character, or the empty string if there is no corresponding character. %s | state of the buttons and modifiers (bitmask) TABLE

-onLeave

  type: string (default: "")

  Tcl command which is executed if the mouse leaves the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %x | x coordinate %y | y coordinate %s | state of the buttons and modifiers (bitmask) TABLE

-onMap

  type: string (default: "")

  Tcl command which is executed if the widget is mapped to the screen, i.e. if it appears on the screen. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name TABLE

-onMotion

  type: string (default: "")

  Tcl command which is executed if the mouse is moved inside the widget. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %x | x coordinate %y | y coordinate %s | state of the buttons and modifiers (bitmask) TABLE

-onResize

  type: string (default: "")

  Tcl command which is executed if the widget resized. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name %x | x coordinate %y | y coordinate %W | new width %H | new height TABLE

-onUnmap

  type: string (default: "")

  Tcl command which is executed if the widget is unmapped, i.e. it disappears from the screen. Before evaluation the following percent strings are substituated: TABLE %% | % %w | widget name TABLE

-pixelPerUnit

  type: float (default: 1.)

  Zoom factor of the canvas.

-scrollRegion

  type: list-of-four-floats

  Region in which the canvas will then be able to scroll. The view of the canvas is adjusted as appropriate to display as much of the new region as possible.

-visible

  type: boolean (default: 1)

  Whether or not the item is visible.

-width

  type: integer

  Width of the widget.

## Description

Canvas widgets implement structured graphics. A canvas displays any number of items, which may be rectangles, circles, lines, text, bezier paths or standard widgets. Items may be manipulated (e.g. moved, scaled, rotated or re-colored) and commands may be associated with items with the bind command. For example, a particular command may be associated with the <button>-event so that the command is invoked whenever a button is pressed with the mouse cursor over an item. This means that items in a canvas can have behaviors defined by the Tcl scripts bound to them. Each canvas item has an integer value as uniq ID, which is returned on item creation. Furthermore each item may be associated with one or more tags. All canvas commands which operate on canvas items accept a tag-or-id-expression. This expression may contain tags or IDs combined with the operators (in descending order) ! (not), & (and), ^ (xor), | (or) and parenthezised subexpressions. E.g. "t1|(t2^t3)" or "!t2".

## Commands

`id` affine `tag-or-id-expr` `list-of-coordinates`

  Makes and affine transformation of id. Length of list-of-coordinates must be 6. The new coordinates are calculated by x_new = af[0] * x_old + af[2] * y_old + af[4]; y_new = af[1] * x_old + af[3] * y_old + af[5];

`id` canvasToWindow `list-of-coordinates`

  Converts canvas coordinates to window coordinates. This takes scrollRegion and pixelPerUnit into account.

`id` cget `option`

  Returns the value for one option. The option may have any of the values accepted by configure.

`id` configure [`-option` `value`...]

  Configures the widget. Option may have any of the values accepted on creation of the widget.

`id` create `type` [`-option` `value`...]

  Create a new item of type type. Type can be one of "line", "rectangle", "ellipse", "image", "bPath", "text", "richText", or "widget". Options are dependent on the type. Returns a numerical id with which this item can be identified. IDs are guaranteed to be unique during the lifetime of a canvas.

`id` delete

  Deletes the widget and the associated tcl command.

`id` findItemAt `x` `y`

  Returns ID of item at the world coordinates x and y.

`id` findWithTag `tag-or-id-expr`

  Returns the IDs of items matching tag-or-id-expr.

`id` getBounds `tag-or-id-expr`

  Returns the bounds (x1, y1, x2, y2) that enclose all items with tag-or-id-expr in world coordinates.

`id` getCurrentSize

  Returns the current size of the widget as list of 4 integer: x coordinate, y coordinate, width and height.

`id` isMapped

  Returns whether the canvas is mapped.

`id` itemCommand `tag-or-id-expr` `cmd` [`-option` `value`...]

  Calls a subcommand for all items with tag-or-id-expr. The subcommand and the options are dependent on the type of the items.

`id` itemConfigure `tag-or-id-expr` [`-option` `value`...]

  Configures all items with tag-or-id-expr. Valid options are dependent on the type of the items.

`id` itemCget `tag-or-id-expr` `?option?`

  Returns the value of option for tag-or-id-expr. Valid options are dependent on the type of the items.

`id` itemDelete `tag-or-id-expr`

  Deletes all items with tag-or-id-expr.

`id` itemHide `tag-or-id-expr`

  Hides all items with tag-or-id-expr.

`id` itemShow `tag-or-id-expr`

  Shows all items with tag-or-id-expr.

`id` lower `tag-or-id-expr` `?level?`

  Lowers tag-or-id-expr in the drawing stack. If no level is given, tag-or-id-expr is lowered to the bottom.

`id` move `tag-or-id-expr` `list-of-coordinates`

  Moves tag-or-id-expr. Length of list-of-coordinates must be 2 (delta x and delta y).

`id` raise `tag-or-id-expr` `?level?`

  Raises tag-or-id-expr in the drawing stack. If no level is given, tag-or-id-expr is raised to the top.

`id` rotate `tag-or-id-expr` `list-of-coordinates`

  Rotates tag-or-id-expr. Length of list-of-coordinates must be 3 (center point and angle).

`id` scale `tag-or-id-expr` `list-of-coordinates`

  Scales tag-or-id-expr. Length of list-of-coordinates must be 3 (center point and scale) or 4 (center point, x scale, and y scale).

`id` update

  Forces an immediate update and redraw of a canvas. This is not needed by normal applications.

`id` windowToCanvas `list-of-coordinates`

  Converts window coordinates to canvas coordinates. This takes scrollRegion and pixelPerUnit into account.

## Example

    set canv [gnocl::canvas -background white -antialiased 1]
    set coords {10 100 30 60 50 20 110 20 150 60 190 100}
    foreach {x y} $coords {
       $canv create ellipse -coords [list $x $y 3] -centerRadius 1 -tags dots
    }
    $canv create bPath -coords {30 60 curveTo 50 20 110 20 150 60} -outline red -width 2 -tags "path t2"
    $canv create line -coords [lrange $coords 0 5] -fill blue
    $canv create line -coords [lrange $coords 6 11] -fill blue
    $canv create ellipse -coords {70 140 50} -centerRadius 1 -fill "" -outline mediumOrchid -width 3 -dash {16 4}
    $canv create rectangle -coords {90 110 180 180} -fill "blue 0.2" -outline green -width 3
    $canv create text -coords {105 80} -text "gnocl" -font "Utopia 14"
    $canv itemConfigure dots -fill darkgreen
    $canv itemConfigure "dots|path" -onButtonPress "puts pressed" -onButtonRelease "puts released"
    gnocl::window -title "Canvas" -child $canv -onDestroy exit

results in

## See also

canvas line, canvas rectangle, canvas ellipse, canvas text, canvas richText, canvas widget, `GnomeCanvas`

Prev | Home | Next
Commands | Up | canvas bPath