[WJG] (22/Jan/09) A few lines from the manual give some indication on how to use this powerful widget.

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".
----
======
#!/bin/sh
# the next line restarts using tclsh \
exec tclsh "$0" "$@"

package require Gnocl

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

gnocl::mainLoop
======
 
Produces the following output:

[http://wjgiddings.googlepages.com/ScreenShot-gnocl_canvas.png]


[pcam] Which version of Gnocl is required for the gnocl::canvas widget ? I am running 0.9.91 on Win XP, I guess I need to upgrade to 0.9.94. Any chance of making a Windows binary build available ?

[WJG] (28-Apr-09) At present Gnocl is only supported on the Linux platform. Other platform compilations have been provided by other users. Since 0.9.91 there has been no one coming forward to maintain the Windows and Maemo packages. It would be really useful if someone did step forward to fill the void! Fancy volunteering? The compilation instructions for the later versions are available in the Gnocl for Windows documentation.  

----

[D. McC] 2009 Jan 22:  Are there things the standard Tk canvas can do that the gnocl canvas can't? If so, what?

[RLH] -- That would be a good list to make what [Gnocl] has or hasn't versus [Tk].

[WJG] (23/Jan/09) Straight from the docs. This are the current opts and cmds for the gnocl::canvas widget. 

[ZB] 2009-05-18 Unfortunately, there aren't any cmds/opts similar to Tk's closest/enclosed/overlapping... any plans to introduce?

[WJG] (19/05/09) No, not at the moment. I can put it on the list of things to to. Mind you, these features shouldn't be too problematic to implement with Tcl.

[ZB] Going this way, the only feature really needed is "set/erase a point at given coords" - the rest can be implemented with TCL. But I believe, it wouldn't be neither convenient nor efficient?

[WJG] (19/05/09) How do you see this comman working? Are you looking to modify an existing canvas object by adding or deleting points. Something along the lines of:

$canvasId item id addPoints ??coords list?? , and

$canvasId item id erasePoints ??coords list??

Perhap you could email me or open a wiki page with the features you're proposing.

[RLH] Where are the docs?

[WJG] Included in the full distribution of Gnocl, available for download from Sourceforge.

[RLH] Maybe a domain like gnocl-docs.org or something, kind of like Tcl/Tk has? That would be nice. Of course, there is overhead there.

[WJG] (24/Apr/09) Yes, that would be useful and indeed its something that I thought about. Mind you, it would still be useful to have some extra help with Gnocl. Any offers? 

[RLH] What kind of help do you need? I am not very good at Tcl or Gtk...just putting that out there but yes I would love to help. There is actually pretty cheap hosting with NearlyFreeSpeech.net. Is Dr. Baum still involved with Gnocl at all or is it pretty much "yours" now? Maybe we can create a Gnocl ideas page on the wiki. I think good docs that everyone can get to and understand and good tutorials would go a long way for Gnocl.

[WJG] (19/05/09) Peter is no longer interesting in either Tcl or Gnocl. His professional programming commitments lead him to work almost exclusively in Python. I keep him informed on the latest changes, but I get the impresion that he feels Tcl is not as vital or important as it once was.

**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: ''boolean'' (default: 1)
    :   This sets the focus to the widget. To unset the focus it must be set to another widget.
'''-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 (if non-empty) is executed if a mouse button is press inside the widget. Before evaluation the following percent strings are substituted:
         %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)
'''-onButtonRelease'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituted:
         %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)
'''-onEnter'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if the mouse enters the widget. Before evaluation the following percent strings are substituted:
         %w        widget name
         %x        x coordinate
         %y        y coordinate
         %s        state of the buttons and modifiers (bitmask)
'''-onKeyPress'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if a key is pressed while the widget is having the focus. Before evaluation the following percent strings are substituted:
         %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)
'''-onKeyRelease'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if a key is released while the widget is having the focus. Before evaluation the following percent strings are substituted:
         %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)
'''-onLeave'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if the mouse leaves the widget. Before evaluation the following percent strings are substituted:
         %w        widget name
         %x        x coordinate
         %y        y coordinate
         %s        state of the buttons and modifiers (bitmask)
'''-onMap'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) 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 substituted:
         %w        widget name TABLE
'''-onMotion'''
    :   type: ''string'' (default: "")
    :   Tcl command which (if non-empty) is executed if the mouse is moved inside the widget. Before evaluation the following percent strings are substituted:
         %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 (if non-empty) is executed if the widget resized. Before evaluation the following percent strings are substituted:
         %w        widget name
         %x        x coordinate
         %y        y coordinate
         %W        new width
         %H        new height
'''-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 substituted:
         %w        widget name
'''-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.

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


----
!!!!!!
%| [Category GUI] |%
!!!!!!