Synopsis
Creates a label.
Syntax
add_label([id,] xpos, ypos, text [,attributes]) Labels can also be created directly from the GUI using the "Annotate" menu item.
Description
The function arguments.
Argument | Description |
---|---|
id | A ChipsId structure identifying the item. |
xpos, ypos | The location of the label; the current coordinate system is used if the "coordsys" attribute is not set. The halign and valign attributes control the location of the label relative to the label text. |
text | The text of the label, which can include LaTeX formatting statements. |
attributes | Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object. |
The add_label command creates a label whose attributes are specified by user preferences or in an attribute list. The new label becomes current by default; providing a ChipsId overrides the currency state.
The position of the label is specified as a coordinate pair (xpos, ypos) in data, pixel, frame, or plot normalized coordinates using the 'coordsys' attribute. Labels specified in data coordinates will only be displayed if the are within the coordinate system range.
Alignment
Alignment attributes control how the text string is situated in relation to the reference position. Horizontal alignment can be specified as left (0), center (.5), right (1), or a numeric ratio of the text length. Vertical alignment is similarly controlled: bottom (0), center (.5), top (1), or a numeric ratio.
Customizing the Label
There are several attributes that control the label characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_label command, or values from the user's preference file.
The attributes may also be modified with the set_label command at any time; see "ahelp set_label" and "ahelp setget" for more information.
Please see the section "Label Preferences and Attributes" below the examples for a list of the label preferences.
Examples
Example 1
chips> add_label(0.4, 0.5, 'area={\\pi}r^2')
Add a label at position (.4,.5). Latex formatting is used in the label text, so the "\" character had to be protected. Alternatively, the r qualifier could have been used:
chips> add_label(0.4, 0.5, r'area={\pi}r^2')
Example 2
chips> add_label(100, 100, "Fig. B", ["color", "blue", "size", 14])
Create a blue label, specifying the attribute values in a list.
Example 3
chips> clear() chips> add_curve([1,2,3], [-9,2,-2]) chips> add_label(2, -6, "In data coordinates") chips> add_label(0.5, 0.92, "Frame coords", ["halign", 0.5, "coordsys", FRAME_NORM]) chips> add_label(0.1, 0.9, "Plot coords", ["coordsys", PLOT_NORM]) chips> limits(X_AXIS, 1.5, 4)
Three labels are added: the first is placed in the data-coordinate system created by the add_curve call; the second is placed in frame-normalized coordinates, and so appears as a plot title (the text has been horizontally aligned so that its center is at the middle of the frame); and the third is placed in plot-normalized coordinates (so appears at the top-left corner of the plot). The limits call causes only the first label to move; the second and third labels do not change position.
Example 4
chips> lbl = ChipsLabel() chips> lbl.color = "blue" chips> lbl.size = 8 chips> lbl.stem = "MyLabel" chips> add_label(100, 100, "Figure A", lbl)
Populate the "lbl" structure with the attribute values, then add the label "Figure A".
Example 5
chips> l = ChipsLabel() chips> l.coordsys = FRAME_NORM chips> l.halign = 1 chips> import time chips> add_label(0.95, 0.05, time.asctime(), l)
A label is added to the bottom-right corner of the frame (the text is right-aligned since halign=1) which contains the current time.
Label Preferences and Attributes
The attributes associated with labels are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_label() command. To change the label preference settings prepend "label." to the attribute name.
Attribute | Description | Options | Default | Set? |
---|---|---|---|---|
angle | Angle, in degrees, at which the label is drawn | -360.0 to 360.0 | 0.0 | Yes |
color | Color of the text | name or hex; see the Color section of "ahelp chipsopt" | default | Yes |
coordsys | coordinate system for the label | PIXEL, WINDOW_NORM, FRAME_NORM, PLOT_NORM, DATA | see "ahelp coordsys" | No |
depth | Integer value indicating label depth | see the Depth section of "ahelp chipsopt" | default | Yes |
font | text font | helvetica|courier|times|greek; see the Font section of "ahelp chipsopt" | helvetica | Yes |
fontstyle | style of the label text | normal|bold|italic|bolditalic; see the Font Style section of "ahelp chipsopt" | normal | Yes |
halign | Horizontal location of the string reference point of the label | auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" | left | Yes |
size | Font size of the text | 1 to 100 | 12 | Yes |
stem | stem used for label id | An alpha-numeric character sequence that does not contain a space | lbl | No |
valign | Vertical location of the string reference point of the label | auto|base|center|left|right|top; see the Text Alignment section of "ahelp chipsopt" | base | Yes |
Bugs
See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.
See Also
- chips
- chips, chipsgui, chipsrc, show_gui
- concepts
- aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
- labels
- current_label, delete_label, display_label, get_label, hide_label, move_label, set_label, shuffle_label
- utilities
- load_font