element

Usage:

element option

where option is one of the following:

add type name parameters

Create a new element. The name is a unique name to be assigned to the new element. The parameters depend on the type, and are as follows:

line name style x1 y1 x2 y2

Create a new line element, with position starting at coordinate x1 y1 and ending at x2 y2. The line does not need to be on a Manhattan grid. Initial coordinates must be on internal magic grid points (that is, must be integer). However, half-grid units can be generated with the configure option (see below).

rectangle name style llx lly urx ury

Create a new box element, with lower left corner at coordinate llx lly and upper right corner at coordinate urx ury.

text name style cx cy label_text

Create a new text label at coordinate position cx cy with text string "label_text".

For an explanation of the style parameter, see the configure option, below.

delete name

Delete an existing element by name.

configure name config_option

Configure or query an existing element named name. config_option may be one of the following:

text [new_label_text]

style [add|remove [style_type]]

With no arguments, return the list of styles used to draw the element. With option add or remove, add or remove, respectively, a style from the list of styles for an element. Styles are the same as styles for tile types in magic, and are defined in the "dstyle" file in the magic install directory. The "dstyle" file declares a "long name" for each style type. This "long name" is what is expected for parameter style_type. The most useful values are the colors defined in the "dstyle" file, such as black, white, red, etc.

Like tile types, elements may be drawn in multiple styles. So, styles are maintained as a list and the element configure style option takes the keyword add or remove to add or remove specific styles from the list. Removing the last remaining style for an element is prohibited. Changing styles requires first adding the new style type, then removing the original.

position [x y [x2 y2]]

With no arguments, returns the position of the element. For text elements, this is the label position (a single coordinate). For lines, both endpoint coordinates are returned, and for rectangles, the lower-left and upper-right coordinates are returned. With one or two coordinate specified, the position of the element is changed. For text, a single coordinate indicates the new position of the text. For lines and rectangles, the two coordinates completely describe the line or box.

flags flag_type

Add or change flags of an element. The specific flag indicated is set. Valid flags are as follows. All elements have these flags:

temporary

Indicates an element that is not saved to the database with a save or writeall command (the default flag).

persistant

Indicates an element that is saved to the database with a save or writeall command, and can be recovered with a load command.

Text elements have the following additional flags:

small, medium, large, xlarge

One of four text sizes.

direction

Any valid direction specification in magic will be translated to a text justification; that is, the text will be printed relative to its position in the indicated direction.

Line elements have the following additional flags:

halfx, halfy

Adjust the position of the line endpoints by one-half unit (postive, that is, right or up). This allows lines to be drawn on, for example, wire centerlines. There is no allowance for having only one endpoint on the half-integer grid.

exactx, exacty

Set line endpoints on the exact coordinates of the line position (the default flag).

arrowleft, arrowbottom arrowtop, arrowright

Add arrows to the line endpoints at the indicated end. Note that four possible positions are allowed, although only two will be relevant for any given line. Arrowheads are of fixed size and may not be visible at large zoom factors.

plainleft, plainbottom plaintop, plaintright

Draw plain lines, with no arrowheads (the default flags).

Rectangle elements have no additional flags.

names

Print names of all elements

inbox

Print name of element in (or nearest) the box

help

Print help information

Summary:

The element command creates and manipulates general-purpose "elements", which are lines, rectangles, and text that have no inherent meaning to the database. They are positioned in units of the layout and so scale and move with zooms and pans. They are intended to be used for layout annotation, measurement rulers, user-defined feedback, flylines, wire paths, and so forth.

Implementation Notes:

element is implemented as a built-in magic command. The syntax is complicated and is expected to be driven by Tcl scripts with simpler syntax for specific purposes such as annotation or measurement rulers.

Return to command index

Last updated: October 5, 2004 at 6:32am