Class ::tycho::Graphics


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.


Itk_options

-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

Public Methods

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

Protected Methods

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.

Protected Variables

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.

Protected Commons

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.