tkined(1)

NAME
tkined - a tk-based interactive network editor

SYNOPSIS
tkined [ files ]

DESCRIPTION
tkined is an interactive network editor for drawing network maps. tkined can be used as a graphical frontend for quite a number of applications that normally act on a network map (e.g. network management systems, network simulators). Applications run as separate processes that communicate with tkined through a simple protocol, which is encapsulated in a set of commands that extend the tool command language Tcl(3) with tkined specific commands. tkined has evolved from the original ined version which was written on top of the Unidraw/Interviews framework. tkined in its current form is a set of tk scripts and some C code that handles tkined objects.

PULL-DOWN MENUS
The menu bar contains pull down menus that control tkined. The File menu contains commands to save, load or print network maps.

New Clear the current buffer.

Open
    Load a previously saved tkined map. The saved map file contains a script of ined commands (see below) that will reconstruct the map.

Save
    Save the current map. The current file name may be changed using the save as command. Tkined will write into the file named unknown if you never opened a file.

Save As
    This lets you choose a file name in which tkined will save the current map.

PostScript
    Dump the current network in postscript format. You are prompted to enter a file name that should capture the PostScript dump.

Print
    Print the current network on a PostScript printer. This command currently uses the lpr command without any options. It may be neccessary to adjust you PRINTER environment variable on your site.

Import
    Import a background image. The file must have the X11 bitmap format.

History
    Show the history of the last used tkined maps. The history is kept in the users $HOME/.tkined/.history file and can be used to jump from map to map very quickly.

Quit
    Close all open tkined views and quit. Note that tkined will not ask you to save a probably modified map.

The Edit menu contains the following commands for editing maps.

Scale Factor
    Set the scaling factor of all selected bar- and stripcharts.

Grid Spacing
    Set the spacing between grid points in pixel.

Align to Grid
    Align the selected objects on the grid. Objects not selected will not be touched.

Undo
    Undo the last change you made. Note that undo currently can not undo a delete command. If you are not sure you really want to delete, use the cut command (see below).

Redo
    Redo the last undone change. A sequence like undo undo redo redo should always bring you back in the initial state.

Delete
    Delete the current selection. All objects will get lost since this command does not update the undo buffer.

Cut Delete the current selection and place all deleted objects on a clipboard. The clipboard is a global buffer shared by all views. You can use the cut command to copy objects form one view to another.

Copy
    Copy the current selection on the clipboard without deleting the objects from the current view.

Paste
    Paste the objects stored on the clipboard into the current view.

The Select menu contains commands that modify the current selection

Select All
    This command selects all objects shown on the canvas.

Select neighbours
    Add all objects linked directly to a selected object to the current selection.

Select member
    Add all member of all selected groups to the current selection.

Select by type
    Add all object of a given type to the current selection.

Select by name
    Query the user for a regular or glob style expression and add all objects to the current selection whose name matches the expression.

Select by address
    Query the user for a regular or glob style expression and add all objects to the current selection whose address matches the expression.

Select by label
    Query the user for a regular or glob style expression and add all objects to the current selection whose current label contents matches the expression.

The Structure menu contains commands to modify the structure of the map.

Set Label to
    Change the contents of the labels of the current selection to show the name, address or text attribute.

Bring to Front
    Bring the selected objects to the front of the map. Background images ignore this command.

Send to Back
    Send the selected objects to the back of the map.

Group
    Create a new group object. The current selection will become the members of the new group object.

Ungroup
    Delete a group object. The member of the group will become visible again or the group frame will be deleted if the group is currently expanded.

Collapse
    Collapse an expanded group to show its icon. A new group is always initially collapsed.

Expand
    Expand a group object so that the member of the group become visible. The group itself is shown as a rectangle enclosing its members.

Join Group
    This command can be used to add objects to an existing group. You have to select the objects to add and the group to add to. A dialog will ask you to select the parent group if there are ambiguities.

Leave Group
    All selected objects will be removed from any group they belong to.

The Icon menu up to five sub menus to manipulate the appearance of tkined objects.

Node
    This sub menu contains all configured node icons.

Network
    This sub menu contains all configured network representations.

Group
    This sub menu contains icons for group objects.

Reference
    This sub menu contains icons for reference objects.

Font
    The Font sub menu contains symbolic names for all available fonts.

Color
    The Color sub menu contains symbolic names for the colors available. This sub menu will only appear if you are working on a color display. Tkined will map all colors to black if your application or your saved map expects color definitions and you are sitting in front of a monochrome display.

The View menu allows you to set the page size and to open additional editor windows. This allows you to work on different maps of large networks simultaneously without starting lots of tkined processes.

Media
    This sub menu controls the size of the drawing area. All sizes are scaled down to DIN A4 size when you select the Print or PostScript command of the File menu.

Orientation
    Set the orientation of the selected media. You can choose between landscape and portrait mode.

New View
    Open a new view.

Close View
    Close the current view. Closing the last view will quit tkined.

Show / Hide Toolbox
    You can hide the tkined toolbox (the box containg the tools to create new tkined objects) using the hide toolbox command. You will get the toolbox back by klicking on the show toolbox entry.

The Help menu contains some short help texts.

General
    General information about tkined.

Status
    Some status information for the editor. This is mainly for maintenance.

Key Bindings
    A short note about the key bindings inside the canvas. This may help you to learn about the various ways to use the mouse buttons.

TCL INTERFACE
The tkined network editor can be extended using its tcl (tool command language, see Tcl(3)) interface. The following sections describe the basic commands understood by the tkined editor. Every tcl interpreter that can write to stdout and read from stdin can be used as an tcl interpreter for tkined. The interpreter must source the file ined.tcl which contains the definition of the ined commands described below.

TCL OBJECT FORMAT
The tkined editor distinguishes four basic kinds of objects: networks, nodes, links and groups. A network describes networks like Ethernet or Token Ring networks. It is represented as a list containing six fields: { NETWORK <id> <name> <address> <oid> <list of links> } The first list item defines that the list represents a network object. The <id> is an identifier for the network object while tkined is running. The name and the address of the network are contained in the <name> and <address> fields. The field <oid> contains an object identifier that is stored with the object and may be used by applications to link additional information to a tkined object. The last field contains the id's of the links connected to the network. { NODE <id> <name> <address> <oid> <list of links> } A node object represents a device that can be connected to a network. The external representation is similar to the representation for network objects. { LINK <id> <src> <dst> } Link objects represent connections between node objects or a node and a network object. The first list item defines that the list describes a link object. The second element contains the identifier of the link object. <src> and <dst> contain the id's of the node or the network objects that are connected by this link. { GROUP <id> <name> <oid> <list of objects> } A group object can contain other network, node, link and group objects. The external representation starts with the type name GROUP followed by the group id. The last component contains the id's of all objects contained in that group. Four additional object types are used by tkined to let the user make annotations in a map, to put background images into a map and to manipulate the menus provided by external interpreters. { TEXT <id> <text>} Some text that is displayed to comment the map. Text objects may be selected, moved and deleted. { IMAGE <id> <filename> } An object of type image can be used to put a background image in your map, e.g. a floor plan or a geographical map. Image objects may be selected, moved and deleted. Note that a saved file contains the filename of the image and not the image itself. So you must ensure that the image file exists when you load a saved file again. { MENU <id> <name> <list of commands> } This object describes a menu. Its name is the string that appears in the menu bar and the list contains all command names provided by this menu. { INTERPRETER <id> <name> } Interpreter objects are external processes that normally execute tcl scripts. The name is the file name of the program that was started when the object was created. { LOG <id> <name> <address> } Log objects are simple text logging windows and provide a way for scripts to write large texts to the user interface. A log object contains some buttons that allow a user to load, save, print or email the contents of the text window. The name attribute defines the title of the log window and the address contains the default email address used by the email button. { REFERENCE <id> <name> <address> } Reference objects are pointers to other tkined maps. You can use these references to tie logical and physical maps for the same network or to break large maps into smaller ones. The address of a reference may be a ftp URL like ftp://ftp.ibr.cs.tu-bs.de/pub/local/tkined/maps/ibr.tki in which case the file will be retrieved via anonymous ftp. This feature allows you to let different people maintain their private network maps while sharing the whole picture globally. { STRIPCHART <id> <name> <address> } A stripchart object to display performance data. The name and address attributes are the same as the attributes of a node object. { BARCHART <id> <name> <address> } A barchart object to display performance data. The name and address attributes are the same as the attributes of a node object. { GRAPH <id> <name> <address> } A graph object displays performance data in a XY graph. The name and address attributes are the same as the attributes of a node object. Note, graph objects will be mapped to stripchart objects if there is no BLT extension available at your site.

TCL COMMANDS
This section briefly describes the tcl commands processed by tkined. You can use them to write applications running under the control of tkined. All operations related to objects handled by tkined are done using a handle (a simple id). Whenever you create a new tkined object, you will receive its id that you can use to manipulate the object later.

ined create NODE

ined create NETWORK [<x1> <y1> <x2> <y2> ...]

ined create LINK <id1> <id2> [<x1> <y1> ...]

ined create GROUP [<ida> <idb> ...]

ined create TEXT <string>

ined create IMAGE <filename>

ined create MENU <name> <command1> [<command2> ...]

ined create INTERPRETER <name>

ined create LOG

ined create REFERENCE

ined create STRIPCHART

ined create BARCHART

ined create GRAPH
    You can create objects with the create command. Creating a node object does not required any arguments. The node will appear with the builtin icon and the default name. Its initial position is the upper left corner. To create a network object, you can define the coordinates of the fixed points of the network. tkined will use the default values 0 0 130 0 if you do not specify any coordinates. A new group object can be created without any elements or with the elements given by the id's. The position of the group object will be determined by the position of its elements. The initial position will be the upper left corner if there are no elements. A link object is created by specifying the two objects connected by that link. Link objects find their position based on the position of the nodes connected by this link. It is possible to specify fixed points that will be respected by the link positioning algorithm. Text objects are always created at the upper left corner and simply display the given string (which may contain newline characters if they are written as \n). Background images are read from the given filename and positioned at the upper left corner. The filename must point to a valid X11 bitmap file. A menu is a set of tcl procedures that are called with a list of the current selection. The name of a registered menu appears in the menu bar of the editor. The commands provided by the menu will pop up when the menu is opened. You can start additional tcl interpreters from a running interpreter by creating a new one. The name usually refers to a tcl script file that gets started. Log windows are simply created by the ined create LOG command. Reference objects are icons that point to other tkined maps. The address of a reference may be a local file name or an URL pointing to a file that can be retrieved via anonymous ftp. Stripchart, barchart and graph objects can be used by applications to display status and monitoring information. They are much like node objects but they can not have any links.

ined delete <id>
    The delete command deletes objects from the editor. This command works on all object types known by tkined.

ined type <id>
    This command returns the type of the object given by id.

ined name <id> [<string>]

ined address <id> [<string>]

ined oid <id> [<number>]

ined attribute <id> <attribute> [<string>]
    These commands can be used to get or set the attributes name, address, oid and text of the object given by id. All commands return the current value of the attribute or an empty string if the object does not have an appropriate attribute. The last format sets the attribute <attribute> to the string or retrieves its value.

ined select [<id>]

ined unselect <id>
    Modify the current selection. The first allows an application to add the object given by id to the current selection. The select command without any arguments returns the list of the current selection. You can unselect objects using the unselect command.

ined retrieve [<id>]
    This command retrieves object descriptions from the tkined editor. It will return the description of the object with the given id. If you call ined retrieve without any arguments, you will get the list of all objects loaded into the current view.

ined icon <id> [<name>]
    The icon of an object can be changed using the ined icon command. The argument of the icon command is assumed to be an entry of the corresponding tkined menu (Node, Network, Group).

ined label <id>

ined label <id> clear

ined label <id> name

ined label <id> address

ined label <id> <attribute>
    The label command allows an application to query, modify or delete the text displayed in the label of an icon. The first format returns the current settings and the second removes the current label from the canvas. The third, fourth and fifth format tells ined to use the contents of the name, address or the attribute given by <attribute> as a label.

ined font <id> [<fontname>]
    Set the font used by object id to fontname. This will change the label of group, node and network objects and the contents of text objects. The command returns the current fontname or an empty string.

ined color <id> [<colorname>]
    Change the color of the object given by id to colorname. The current color of object id is returned.

ined move <id> [<x> <y>]
    This command lets you move an object. The coordinates x and y are relative to the current position of the object, which will be returned by the move command. You can call ined move without x and y coordinates to retrieve the current position of an object.

ined size [<id>]
    This command returns the size of the object given by id. The size is given as the coordinates of the bounding box, that is the upper left and the lower right corners of the bounding box. Calling ined size without an id will return the size of the canvas window.

ined text <id> [<text>]
    This command is only valid for text objects and retrieves or sets the text of the text object given by id.

ined links <id>
    This command returns the links currently connected to id. This command is only valid for objects that can be connected by links like nodes and networks.

ined collapse <id>

ined expand <id>
    These commands are only valid for group objects. The collaps command tells tkined to shown the group as a single icon and the expand command restores the contents of the group. The group itself is shown as a rectangle enclosing the members of the group.

ined clear <id>

ined append <id> <text>

ined hyperlink <id> <cmd> <text>
    These commands are only understood by log objects. The clear command removes all text from a log object (that is the log window) and the append command appends <text> to the log object. The hyperlink command adds the <text> to the log object and associates the command <cmd> with it. A button press on <text> will send <cmd> to the interpreter belonging to the log object.

ined send <id> <command>
    This command is understood by interpreter objects. The given tcl command will be send to the interpreter given by <id> for execution. This allows scripts to use and control other scripts.

ined values <id> [<number> ...]
    This command can be used to write new data to a barchart, stripchart or graph. If called without an argument, the command returns all data currently stored in the graph, bar- or stripchart.

ined scale <id> <value>
    Set the scaling factor of a graph, bar- or stripchart. The default scale is 100. An application can use this command to adjust the default if it knows a reasonable value.

ined clear <id>
    Clear all values contained in a graph, bar- or stripchart.

ined jump <id> [<number>]
    This commands sets or retrieves the amount of pixels that are scrolled when the stripchart reached the right border.

ined acknowledge <line> [<line> ...]

ined browse [<line> ...] <list>

ined confirm <line> [<line> ...] <button list>

ined request [<line> ...] <request list> <button list>

ined list [<line> ...] <element list> <button list>

ined fileselect title [directory] [file]
    These five commands allow tcl scripts to open simple dialog windows from within the tkined editor. Each dialog has a number of text lines. The acknowledge command displays the text until the user clicks on the ok button. The confirm command issues a dialog which displays the text given in the first arguments. The last argument is a list of buttons that appear below the test. The name of the selected button is returned by the confirm command. The request command displays a dialog box that contains an entry widget for every element in <list>. Each element is again considered to be a list. The first element of this list is the entry label and the second is the default value. Additional arguments give hints how to obtain the input. Tkined will use a scale widget if the third argument contains the keyword scale. In this case, the fourth and the fifth argument may specify the range of the scale. If the third argument contains the keyword radio, tkined will use subsequent words as values presented in radio buttons. A script may use a request dialog to request information from the tkined user. The fourth dialog window is a simple text browser. You can scroll the text shown in the browser by pressing the middle or the right mouse button. The list dialog opens a list box displaying <list>. The selection is returned when the user hits a button. The result is the button name and the select list element if any. The fileselect dialog has a name (usually a hint what should be selected) an optional directory and and optional default file. It returns the selected file or an empty result.

ined page [<size> [<orientation>]]
    This command can be used to get or set the page size. Ined page always returns a string with the current page size and its orientation. Legal sizes are Letter, Legal, DIN A1, DIN A2, DIN A3 and DIN A4. The orientation may be portrait or landscape.

ined trace <callback-proc>
    This command tells tkined to trace all operations performed on its objects. For every operation that modifies an object state, the callback procedure will be called. It is expected to have two arguments. The first one will be set to the ined command and the second one will be set to the result returned by the command. Applications may use this trace for debugging or communication purposes.

ined restart [<command-list>]
    Tell tkined that the interpreter wishes to get restarted when a saved map gets loaded. tkined will send the commands contained in the command-list to the interpreter to let it initialize itself properly. The command returns the current list of commands stored for the current interpreter.

CUSTOMIZATION
You can customize the tkined editor to your specific needs. You may load your own icon bitmaps and define the width of various network types. All customization is done using tkined.defaults files, that are very similar to xrdb(1) files. Since there is no way to access the defaults database of the server from within tk, the defaults files are searched along the tkined_path. The default setting of this path is TKINED_PATH=.:$HOME/.tkined:/usr/local/lib/tkined/site:/usr/local/lib/tkined. You can add elements to this path by setting the environment variable TKINED_PATH.

width

height
    You can specify the default width and height of the tkined window using the with and height attribute.

node i
    You may specify icons to represent machines for the i-th node menu entry. The definition consists of two strings. The first one is the filename of the bitmap and the second is the name of the icon as shown in the node menu. A colon can be used to create a path of submenus, e.g. Sun:SparcStation 2.

group i
    The definition of an icon for a collapsed group is done in the same way as for a node icon.

network i
    The definition of the i-th network consists of the line thickness to use and the name that appears in the menu.

reference i
    The definition of an icon for a reference object is done in the same way as for a node icon.

interpreter i
    The i-th interpreter is defined by its file name. It is the responsibility of the interpreter to define new menus using the ined create MENU command.

font i
    The font menu is build using the font definitions. The i-th menu entry represents font i which must be given as an X11 font name followed by the name used in the font menu.

color i
    The contents of the color menu is given by an X11 color name and the name for this color used in the color menu. The color menu does not appear on monochrome displays.

SEE ALSO
Tcl(3), Tk(n), scotty(1)

FILES

/usr/local/lib/tkined/tkined.defaults

/usr/local/lib/tkined/init.tcl

/usr/local/lib/tkined/bitmaps/*.bm

$HOME/.tkined/tkined.defaults

$HOME/.tkined/*.bm

$HOME/.tkined/.history

AUTHORS
Juergen Schoenwaelder (schoenw@ibr.cs.tu-bs.de). The stripchart and the barchart canvas items are written by Guntram Hueske (hueske@ibr.cs.tu-bs.de). Thanks to Thomas Birke (birke@ibr.cs.tu-bs.de) and Hinnerk Ruemenapf (rueme@ibr.cs.tu-bs.de) who implemented the Unidraw/Interviews ined version which has been 'heavily hacked' by me to include a tcl interface, stripcharts and color support and lately became the basis of tkined. The emacs key bindings are taken from the emacs binding definitions written by Mark Weissman (weissman@gte.com).