#

## setlabel

Manipulate rendered font labels

### Usage:

> setlabel [-default] option

> > where option is one of the following:
> > box [llx lly urx ury]
> >   Report the bounds of the attachment box for all selected labels, or set the coordinates of the attachment box to the indicated values.
> > font [name [scale]]
> >   Report the font of all selected labels, or set the font to the font named name, where name is one of the known fonts returned by the command "setlabel fontlist". If the named font is not in the list, magic will attempt to load it, if the font vector list can be found (the font vector list should be in an unencoded PostScript Type3 font format). Magic scales all fonts such that label size can be specified in database units. Unfortunately, fonts tend to have characters (accents, for example) well above the height of a standard capital letter, and these characters result in the inability to extract the font height from the font metrics. In such (common) cases, the optional floating-point scale value specifies the difference between the character height and the font height reported by the font metrics. Typically, this number is around 0.6.
> > font number
> >   For number zero or larger, this option returns the name of the font that is index number into the list of loaded fonts. No other action is taken. For number equal to -1, the font of the selected label is reset to the default X11 font, and properties such as scale, offset, and rotation are ignored. Justification is retained.
> > fontlist
> >   Return a list of the known, loaded fonts.
> > justify [position]
> >   Report the justification of all selected labels, or change the justification to position, which may be any compass direction or "center".
> > layer [name]
> >   Report the layer type to which the label is attached. If the optional name is given, and is a valid layer name, then the label is modified to be attached to that layer type. Note that if the layer is not also declared "sticky" (see below), then it is likely to be reattached to the original layer during certain operations.
> > offset [x y]
> >   Report the offset of all selected labels (in x y pairs), or change the offset, which is the spacing between the point marked by the label and the label text. In the case of a rectangle identifying a label, the spacing is measured from the center of the rectangle.
> > rotate [value]
> >   Report the angle of rotation of all selected labels, or change the angle, which is measured in degrees counterclockwise. Any integer angle is acceptable. Labels are always drawn upright, so labels rotated from 90 to 270 degrees undergo an additional 180 degree rotation within their bounding box to ensure that the text always remains upright. Likewise, rotations and reflections of subcells are applied to the label bounding box, with the text rotated within the bounding box to ensure an upright orientation. If this explanation is a bit obscure, then the rule is: if a label is drawn on a cell such that it occupies a specific place with respect to the cell layout, then it will always appear in that same place regardless of how the cell is oriented in the hierarchy of a layout.
> > size [value]
> >   Report the size of all selected labels, or change the size of selected labels to value, which may be given in units of lambda, or a metric measurement (e.g., "1um"). The text will be adjusted so that the height of capitalized text from the text baseline is equal to the requested value.
> > sticky [true|false]
> >   Report the status of the "sticky" flag for the label. Labels which have the "sticky" flag set can only attach to the assigned layer type. Such labels may be placed over a layer that exists only in a subcell, unlike non-sticky labels, which will reattach to any available layer or else be assigned to "space". Value returned is 1 (true) or 0 (false). If "true" or "false" is specified, then the sticky flag is set or cleared, respectively.
> > text [string]
> >   Report the text string of all selected labels, or change the text string of selected labels to string.

### Summary:

> The setlabel command manipulates selected text labels. In versions of magic prior to 8.0, labels could not be manipulated, but could only be changed by removing and replacing the label. Labels were drawn in an X11 font that was scaled relative to the window, not the layout. setlabel not only allows text strings to be modified on any labels, but also allows labels to be drawn in scaled fonts, rotated and offset to a specific position. Fonts are read from simple, ASCII-encoded PostScript Type-3 font files, such as provided by the Freefont project.
> If -default is specified, then the given option is set as a default, if a value is supplied. If no value is supplied, then the value of the default is returned. The default values are applied when the "label command is issued without the full set of values. The -default option may be used with any label property except for text and box.
> The default values, if not changed by using the -default option, are as follows:
> font
>   default Fixed-width X11 bitmap font.
> justify
>   -1 Default justification, automatically determined.
> size
>   0 Size is determined by the default font.
> offset
>   0 0 Text is not offset.
> rotate
>   0 Text is not rotated.
> layer
>   -1 Default layer type, automatically determined.
> sticky
>   0 Labels are not sticky by default.

### Implementation Notes:

> setlabel is implemented as a built-in command in magic version 8.0 (or higher) only.

### See Also:

> label

Return to command index

Last updated: March 17, 2021 at 11:16am