Inherits:
::tycho::File
-
Source File -
Contents:
itk_options
- public methods
- protected methods
- protected variables
- protected commons
This widget is the principal Tycho interface to the Tk Canvas.
It creates a widget that contains a canvas with optional scrollbars.
A set of methods support commonly used operations and encourage a
a consistent look to graphical displays and editors.
The widget manages a set of items consisting of one or more
canvas items. Items can be saved in files and edited using
customizable editors. Their creation and deletion can be interfaced
to the undo and clipboard mechanisms. The create
method
is the simplest way to create an item, which in this case is a simple
canvas item. The create
method passes all its arguments
to the Tk canvas create
command. Items with more complex
behavior, such as centered text that adjusts to changes in window
sizes and insertion of other items, can also be created. Derived
classes provide yet more complex items.
If you use its create
method to create items in the
canvas, then then undo and clipboard operations will work on this
item and the details about the item will be reported by the
describe
method, which is used to save the contents to a
file. If this object is embedded in a Graphics
object,
then items created this way are automatically saved in files. Any
item created with the create
method should be removed
using the delete
method. Commands that are issued
directly to the canvas are ignored for the purposes of undo, the
clipboard, and saving to a file. The describe
method
will not reflect any such commands.
The describe
method also reports the current canvas size.
Thus, if the data reported by this method is saved (as is done by the
Graphics
class), then the size of the canvas is persistent.
A set of methods and options are provided to encourage a consistent
look and feel in graphical editors and displays. The
centeredText
method can be used to create titles, subtitles,
author information, etc. These can be specified or edited interactively.
The widget supports a set of default interaction mechanisms using
tags. Drawn items tagged with "selectable" can be selected with button
1; items also tagged with "movable" can be selected and moved freely, and
text items tagged with "editable" can be edited in-place by clicking on
them with the button 2. Button 1 can also be used to "drag-select" one
or more items. If the shift key is pressed when selecting an item or when
starting drag-selecting, items are toggled in and out of the selection set.
This class is a base class for more interesting graphical displays
and editors. It is not meant to be used on its own. Derived classes
may create objects in the canvas without using the create
method. Such objects can be registered using the register
method.
This design has borrowed some ideas from the scrolled canvas widget
written by Mark Ulferts and Sue Yockey of DSC Technologies Corporation,
but goes well beyond the intent of that widget.
-canvasheight
300
- Specify the height of the canvas widget, in pixels.
-canvaswidth
400
- Specify the width of the canvas widget, in pixels.
-scrolling
auto
- If the value is "bars", then the canvas is equipped with scrollbars.
If the value is "auto", then the canvas is equipped with scrollbars
only when its contents are not all visible.
Otherwise, scrolling is turned off. For the change to take effect
after configuring this option, call
updateScrollbars
.
Public constructs
-
canvasName
- Return the name of the Tk canvas, for interfacing to non-Itcl code.
-
centeredText
text {tag {}} {below {}} {color black} {font {}}
- Create text that is centered in the portion of the canvas that will
be visible when the window is first opened. The first argument is the
text to insert. The text will be wrapped at word boundaries if it is
wider than the window. The remaining arguments are optional, although
if any one of them is given, then the ones before it must also be
given. The second argument is a tag to assign to the text (in
addition to "selectable" and "editable", which are always assigned).
If any items
already exist with this tag, then they are deleted. The third
argument is a list of tags identifying tagged items in the canvas
below which the text will be placed. If the tag is given, and this
list is non-null, then the dependence is registered so that when
dependenceUpdate
is called, if any of the items in the
"below" list have moved, then this item will be moved. The fourth
argument specifies the color. Any color name accepted by
::tycho::color
will work. The fifth argument specifies the
font in a form accepted by the findFont
method of the
FontManager
class. If the color and font are not
specified, then the text is black using the default variable font.
The text is tagged "selectable" and "editable," and the id of the
text object is
returned. If the text is an empty string and the tag is given, then
items with that tag are simply deleted and a null string is returned.
The action is registered for undoing, and dependenceUpdate
is called with the argument being either the tag (if given) or
"centeredtext". Thus, any object that is registered as depending
on "centeredtext" using dependenceAdd
will be updated.
-
centeredTextEdit
{tag {}}
- Interactively edit centered text. If the optional argument is given,
and a centered text item exists in the canvas with the specified tag,
then that item is edited. Otherwise, if there is a selected item and
that item is a centered text item, that item is edited. Otherwise,
an error occurs.
-
clear
- Clear the display, discarding the current graphics.
-
copy
{ids {}}
- Copy the commands to create the specified items to the clipboard. If
no items are specified, then copy the selected items. The argument is
a list of item ids. Only items that were created with the
create
method or registered with the
register
method can be copied to the clipboard.
-
create
args
- Create a canvas item, recording for undo. The arguments are exactly
those of the Tk canvas widget. Also register the creation command so
that the item can be saved. Return the id of the item created.
-
cut
{ids {}}
- Remove the specified list of items, or if none, the selected items,
adding to the clipboard commands to recreate them. The argument is a
list of item ids.
This method should be called via the
modify
method.
-
delete
args
- Delete one or more canvas items, recording for undo. If the items
were created with
create
or registered with
register
, then the deletion is implemented by executing
the registered delete command, and the corresponding create command
is recorded for undo. The arguments are tags or ids of items to be
deleted.
Note that this method shadows the Itcl delete
command
because it has the same name. To invoke that command within a method
or proc of a class derived from this one, use the syntax
::delete
.
This method should be called via the modify
method.
-
dependenceAdd
parenttag childtag {update {}}
- Declare that a child item depends on a parent item.
The items are specified by tag. There is no need for items to
exist with the given tags. If the optional third argument is given,
it is a command that will be evaluated by
dependenceUpdate
when a parent has been modified. If such a command has been previously
set for this child tag, it is overwritten.
-
dependenceUpdate
args
- Update items in the dependence graph that have been registered with
calls to
dependenceAdd
. The optional arguments are nodes
in the dependence graph representing items that have changed. Nodes
that depend on those items will be updated. If no argument is given,
then all items that depend on root items in the dependence graph will
be updated. An update consists of one of two actions. If an update
command was given when dependenceAdd
was called, then
that command is executed. Otherwise, for each updated item in the
dependence graph, if any items exist in the canvas with tags that
match the name of the item, the item is deleted and recreated using
registered deletion and creation commands. If interactive mode is not
enabled or there is no dependence graph, this method simply returns.
-
describe
- Describe the contents of the canvas as a list of commands.
All items are included if they have been registered using the
register
method, or were created using
the create
method.
-
edit
{ids {}}
- Edit the specified items, or if none, the selected items. If an edit
command was registered using the
register
method, then that
command is used to edit the item. Otherwise, if the command was
created using create
, or a creation command was registered
using the register
method, then a text editor is invoked
to edit that creation command. If the item has not been
registered at all, then the item is ignored. The argument is a list
of item ids.
Note that the edit command will be invoked even if the object is
read-only. Thus, it is up to that command to ensure that no
destructive changes are made.
-
export
- Open a print dialog for exporting the contents of the canvas in various
formats.
-
exportGif
filename
- Generate a GIF file with the contents of the canvas.
NOTE: Unix-only implementation. Also, depends on the programs
xwdtopnm, ppmtogif, and xwd, which must be in your path.
-
exportEps
filename {orientation portrait} {colormode color} {pwidth {}}
- Generate an encapsulated postscript file. The first argument (the
only one required) is the name of a file into which to write the
postscript. The second argument specifies the orientation, and should
be either "normal" (the default) or "rotated" (by 90 degrees). The
third argument specifies the color mode and should have value color
(the default, for full color output), gray (convert all colors to
their gray-scale equivalents) or mono (convert all colors to black or
white). The final argument optionally specifies the width of the
postscript image. It consists of a floating-point number followed by
c for centimeters, i for inches, m for millimeters, or p or nothing
for printer's points (1/72 inch). If it is not given, then the image
size is the same as on the screen.
NOTE: Currently postscript is generated for the entire image in a single
file. It would be good to be able to break it down into subimages.
If the image does not fit on the page, then how it is cropped is
unpredictable.
NOTE: It would be nice to take advantage of the colormap option
in the canvas postscript command to be able to map colors for monochrome
printing.
-
exportXwd
filename
- Generate an X window dump with the contents of the canvas.
NOTE: The xwd program seems to consistently give a "BadMatch" error,
but works nonetheless, albeit a bit slowly. Thus, we ignore the
error.
NOTE: Unix-only implementation.
-
focusin
- Put the focus in the canvas.
-
help
- Open a help window.
-
insertData
data
- Append the specified data to the existing display.
The data should be a list of items of the form methodname args,
where methodname is a method of this class (i.e. any class
derived from
Graphics
), and args is the
set of arguments appropriate for that method.
Every 30 items, this calls ::tycho::safeUpdate
in order
to preserve interactivity.
-
interactiveEnable
bool
- If the argument is non-zero, enable the undo system and automatic updates.
-
modify
args
- Modify the canvas by executing the arguments in the scope of this object.
The command is identified as a distinct action for undo, the window
is marked modified (if appropriate), the display is updated, and the
focus is returned to this object. If the object is read-only,
ring the bell and return, doing nothing.
-
paste
- Paste the items in the clipboard by executing the commands stored
in the clipboard in the context of the current object. If an error
occurs doing this, then assume that the item in the clipboard is raw
text, and insert it into the canvas as a label.
-
print
- Print the contents of the canvas. It is first converted to postscript.
Then the user is queried for a print command.
-
redo
- Execute the current command in the redo buffer.
This method calls
undoBoundary
.
-
scrollQuery
- Query the user for the type of scrollbars to use.
-
scrollSet
dialog
- Set the scrolling style of the child widget depending on the user's
response in the specified dialog box.
-
select
{append 0}
- Select all objects under the current mouse position that have the tag
"selectable". If there are none, then clear any selection.
If the argument is non-zero, then append to the selection rather than
replacing it.
-
selected
- Return a list of the ids of selected objects.
-
selectionClear
- Clear the selection.
-
setReadOnly
bool
- Specify whether or not modifications are allowed in the displayed text.
Note that this is independent of whether the associated file is readonly.
It merely determines whether the buffer can be modified, not whether the
file can be modified. To control the file, use
toggleReadOnly
.
-
titleAdd
{newcategory 0}
- Interactively add title information to the window. The types of title
information directly supported and the order in which they appear are
given by the titleTypes option. The dialog lists those of these that are
not already specified in the canvas. If all of these are specified,
or the optional argument is given and is non-zero, then a more
complicated dialog is opened allowing the user to create a new title
category. That more complicated dialog can also be opened via a
button in the first dialog.
-
titleSet
category text
- Specify title information for the window. The types of title
information directly supported and the order in which they appear are
given by the titleTypes option. The first argument is one of these types
or some other type (all other types will appear below titleTypes types).
Any previous instance of such a title type will be removed.
The second argument is the text of the title.
-
undo
- Execute the command in the undo buffer.
This method calls
undoBoundary
.
-
undoAppend
command
- Append a command to the end of the undo or redo buffer (the latter
only happens if an undo is in progress). This should be called
anytime an object is deleted, to ensure that the deletion can be
undone. If an object is being created, call
register
instead.
-
undoBoundary
- Break a sequence of commands for the purposes of undo. Any commands
appended or prepended to the undo buffer between calls to this method
will be undone together.
-
undoPrepend
command
- Append a command to the beginning of the undo or redo buffer (the
latter only happens if an undo is in progress). This should be called
anytime an object is deleted, to ensure that the deletion can be
undone. If an object is being created, call
register
instead.
-
updateScrollbars
- Update the range of the scrollbars so that they cover the bounding box
of the contents of the canvas. This should be called after each action
that changes the bounding the box of the items in the canvas or the size
of the canvas.
Protected constructs
-
addInfo
tag label value {width {}} {description {}}
- Add or configure textual information displayed at the bottom.
The arguments are: a name for the widget, the label to be displayed,
the value to be displayed, an optional width field and an optional
textual description
If the description argument is non-empty, then when the user moves
the mouse over the widget, the status line will have the description
displayed in it.
For example:
addInfo foo {Value of foobar} $foobar 3 {foobar is a variable}
will create a widget with a label 'Value of foobar', a value that
is the value of the foobar variable and displayed with a width of 3
characters.
-
bottomOf
args
- Given any number of tags, return the distance from the top of the
canvas (in pixels) of the bottom of the lowest item found in the
canvas with one of the tags. This can be used in derived classes to
determine the uppermost range of their drawing area (placing text
below centered text for example). If no matching items are found,
return 2 (suggesting two pixels of margin at the top).
-
findAll
args
- Find all the items in the canvas that have all of the tags given
as arguments. Return a list of ids. If no tags are given as
arguments, then return a list of all ids. If no items have all
the specified tags, return an empty list. Note: This will execute
fastest if the most restrictive tag is given first.
-
itemlist
{items {}}
- If the argument is non-null, just return it. Otherwise, return a list
of the ids of selected items, if there are any. If there are also no
selected items, return the id of the item under the cursor, if it has
tag "selectable". If there is also no such item, report an error.
-
preference
mode args
- Access the preferences associated with this widget. This method
overrides the default method in ::tycho::TWidget to access the
"graphics" preferences.
-
register
id create undo remove {edit {}}
- Register the creation, undo, deletion, and (optionally) edit commands for
an item in the canvas. This is necessary for the item to be saved when
the canvas is saved to a file. It also permits cut, copy, undo, and redo
to work with this item. The first argument is the id of a representative
canvas item. This need not be the only item associated with the
object being registered. The representative item should normally have
the tag "selectable". The second argument is a command (a method
invocation actually) that can be used to recreate the item. When
recreating the item, that command will be invoked verbatim as a
method of this object. That command should, as a side effect, also
register items it creates. The third argument is a command
to undo the creation of the object. This may, for example, restore
some previous item, in which case the command should register the new
item. The fourth argument is a command to delete the object, which
will be used to delete or cut the object. This may be the same as
the undo command, and should have the side effect of calling
appendUndo
to enable undoing the deletion. The
delete
method provides a convenient way to do this.
The final argument is an optional edit command. That command will
be invoked to edit the item.
That command should, as a side effect, append to the undo buffer a
command that will undo the editing operation.
-
saveText
- Return the text to be saved.
-
canvas
- The name of the raw Tk canvas. Use with caution!
-
dragselector
- An object that manages dragging and selecting of items.
-
fileformats
- An array of commands that will export the graphic some file format.
-
interactiveEnabled
0
- Flag indicating whether undo and automatic updates are enabled.
-
lineeditor
- An object that manages editing of text items.
-
selector
- An object that manages selection of items.
-
slate
- The name of the slate contained within this widget.
-
exportFormat
eps
- The default file format for the export command.
-
printWidth
- Width of most recent print request.
-
printColor
color
- Color mode of most recent print request.
-
printOrient
landscape
- Orientation of most recent print request.
Index of classes
Author: Edward A. Lee
Version: @(#)Graphics.itcl 1.31 12/15/96
Copyright: (c) 1995-1996 The Regents of the University of California.