Label (command)
Label-cmd
Places a text label on the page.
Syntax:
label [options] message
By adding one or more option switches you can modify the manner in which the label is created. The message to be displayed by the label is always the final argument. The label command allows multiple option switches. When -xb, -yl, -xt, -yr, -zf, or -zb are used, they must be the final option (immediately preceding the label message). Also, when -n is used, it must be the final option (immediately preceding the label message). Options can be combined only when it makes sense to do so and when they do not conflict with each other.
In addition to entering literal text for message, you can specify $[OMGfileName].Section.Title. This enables you to access a string title in a message file. The OMGfileName extension is assumed to be OMG. If OMGfileName is not specified, the ORIGIN.OMG file is assumed. For an example using this syntax, see the Type command.
Note--Using Escape Sequences to Control Text Format:
You can use escape sequences in a string to customize the text display. These sequences begin with the backslash character (\). All text objects (those created with the label command or with the Text tool) as well as text plotted from a Label column will display according to the rules of these sequences.
The following text formatting commands are available:
\(ASCII character code) |
Displays the specified ASCII symbol. For example
\(65); // Means "A"
|
\+(text) |
Format text as superscript. |
\-(text) |
Format text as subscript. |
\=(text1,text2) |
Format text1 as subscript, text2 as superscript. |
\ab(text) |
Display a bar above text. |
\ad(text) |
Display a short line - a dot - above text. |
\at(text) |
Add tilde above text. |
\b(text) |
Format text as bold. |
\cnumber(text) |
Displays text in the color located at position number in the Color drop-down lists. For example:
\c4(This is blue); // Set font color as blue
|
\f:fontname(text) |
Displays text using the fontname font. You can abbreviate font name, as long as you use enough letters for the name to be unique.For example:
\f:Times New Roman(This font is "Times New Roman");
|
\g(text) |
Format text in Greek symbols. For example:
\g(a); // Shows alpha
|
\h(text) |
Block substitution notation. For example:
\h(\l(1) %(?Y)); // display literal \l(1) %(?Y)
|
\i(text) |
Format text as italics. |
\p%pointsize(text) |
Change the point size of text. 200 doubles the size, 100 results in no change, etc. For example:
\p200(Double font size);
|
\s(text) |
Strike the text. |
\sc(text) |
Insert one conditional horizontal space in a string even there are multiple consecutive spaces. For example:
\b(%(1Y,@LL)\sc%(1Y,@LD3)\sc%(1Y,@LD4)\sc(%(1Y,@LU)))//assume @LD3 and @LD4 not exist, so there will be two spaces. \sc make one space only
|
\u(text) |
Underline the text. |
\v(text) |
Override interpreting escape sequences, so that \n is not recognized as New Line, and \r is not recognized as Return, etc. For example:
// Path cannot be shown correctly if not using \v()
label -p 0 0 -s \v(My UFF is: %Y);
|
The following characters are supported, some of them are non-printable:
\\ |
Backslash |
\' |
Single quote mark |
\" |
Double quote mark |
\y(') |
Full height prime |
\y(") |
Full height double prime |
\+(\y(')) |
Combining prime |
\+(\y(")) |
Combining double prime |
\n |
New line |
\r |
Return |
\d |
Delete/backspace |
\t |
Tab |
\xhh |
ASCII character in hexadecimal notation, where hh are two hex digits |
Note: Some escape sequences may be not listed in above two tables, you can see User Guide for more information.
|
Options:
no option, Place a unnamed label in the default location
Syntax: label message
Place an unnamed text label message in the default location on the page in the active window.
label test; //Add a label shown as "test" in the default location.
-a; Place a new label at specified point in the Cartesian coordinate
Syntax: label -a x y message
Place the label at coordinates xy, where x and y are Cartesian coordinate values.
label -a 10 15 test; //Add a label shown as "test" at (10,15).
-al; Arrange the 2D legend object into multiple columns
Syntax: label -al number of columns
label -al 3; //Arrange legend entries into 3 columns
Also, see the legend command flags -av and -ah.
-b; Set the label border style
Syntax: label -b n message
Set the text label border style to the nth style in the Show Background drop down list of the Text Control dialog box.
//Add a text label shown as test2 and the Background
//is 2nd style "Black Line".
label -b 2 test2;
-d; Place a new label at the specified point measured in screen pixels
Syntax: label -d x y message
Place the label at coordinates xy, as measured in screen pixels from the top left corner of the page.
-e; Open the Object Properties dialog box with the specified message
Syntax: label -e message
Open the Text Control dialog box with message in the text box.Click OK to create a text label with the message.
label -e test5;
-f; Change the label font type
Syntax: label -f fontName message
Change the label font type to fontName.fontName can be abbreviated as long as the name remains unique. For multi-word font names, you must include quotations around fontName.
-fp; Remove escape code
Syntax: label -fp name
Remove escape code for name object
Syntax: label -fpp *
Remove escape code for all text object in layer
-j; Justify the label message text
Syntax: label -j n message
Justify the label message text.n can be 0 (left), 1 (center), or 2 (right). Justification of axis titles is preset and cannot be altered.
label -j 1 test6;
-l, -lr; Get all connected graphic objects
Syntax: label -l graphicObject stringArray
Get all graphic objects which are connected to graphicObject. The stringArray is used to store their names.
StringArray sa;
// get all objects connected to rect and store their name to sa
label -l rect sa;
Syntax: label -lr graphicObject stringArray
Get all connected graphic objects of graphicObject recursively. The stringArray is used to store their names. Because of searching recursively, the name of graphicObject itself is also stored in stringArray.
StringArray sa;
// get all objects connected to rect recursively and store their name to sa
label -lr rect sa;
See also: GetConnected method
-n; Create a new label or replace the specified label
Syntax: label -n labelName message
Create a new, or replace the existing, message of the named label.labelName specifies the name of the label, which appears in the Label Control dialog box.
label -n text1 aa; //replace the text1 label as a new label shown as aa.
Note: The -n switch must be placed as the last switch, that is, immediately preceding the label message.
-o; Set the label offset
Syntax: label -o dx dy message
Set the label offset (in percent).This option is only applicable for labels attached to Layer and Scales (the Attach To group of the label's Label Control dialog box).
//Add a label shown as "tt" with 10% offset
//from the current location of mouse.
label -o 10 10 tt;
-p; Place a new label at the point specified by the percent distance
Syntax: label -p x y message
Place the label at coordinates xy, where x and y represent the percent distance from the top left corner of the layer frame.
label -p 50 50 Center; //Add a label at center of layer frame.
-px; Place a label at the point specified by pixel
Syntax: label -px x y message
Place the label at (x, y), where x and y represent the pixel distance from the top left corner of the graph window.
label -px 10 20 Place Label by Pixel;
-q; Place a label into the nth quarter
Syntax: label -q n message
Place the label into one of the four active layer quadrants n.The quadrants are numbered from 1 to 4, counterclockwise from the top right.
label -q 3 hello; //Add a label in the third quadrants.
-r; Delete the specified label or graph object
Syntax: label -r labelName/objectName
Minimum Origin Version Required: 8.51 SR0
Delete the label named labelName, not including any connected objects.
label -r text2; //Delete the label, text2.
label -r Rect; // Remove the rectangle object on active graph page
Note: The objectName here supports wildcard. For example
label -r text*; // Delete all object started with "text".
-ra; Delete all labels with the specified prefix in label name
Syntax: label -ra labelNamePrefix
Delete all objects whose names start with labelNamePrefix.If labelNamePrefix is not included, then all labels on the page are deleted.
label -ra text; //Delete all the label named with prefix "text".
-rc; Delete the specified label and all its connected ones
Syntax: label -rc labelName
Remove the graphic object named labelName, with the connected objects.
// In a new graph window, draw a line and a rectangle, and supposed
// the object names are "line" and "rect". Run the following script:
// Connect the line to the rectangle
line.connect(rect, 1);
// Delete the line, and the connected rectangle will also be remove.
label -rc line;
-s; Enable the use of substitution notation (% and $) in the argument string
Syntax: label -s message
Enable the use of substitution notation (% and $) in the argument string.By default, the label command does not substitute the % and $ notation. This option allows you to insert numeric and string variables into the label message.
// Add a label shown as the path of User File folder
// Note: You should use the escape sequences, \v(),
// to enclose the text to show "\" in file path correctly
label -s \v(%Y);
-sa; Enable conversion of \r\n\t type of notation
Syntax: label -sa message
Enable conversion of \r\n\t type of notation.Use this option to create multiple line text labels (\r\n) without adding new lines to the script. To also enable substitution, use -s -sa together.
label -sa Hello\nHello;
This command will add a label shown as
Hello
Hello
-sl; Create a message label with the Link to Variables check box
Syntax: label -sl message
Create a message label and select the Link to Variables check box in the Label Control dialog box.See Examples below.
-t; Create a label with message
Syntax: label -t message
Create a label with message and name the object TITLE.
label -t abc; //Add a label shown as "abc" and named as TITLE.
-xb; Reset the bottom X axis title
Syntax: label -xb message
Create a new, or replace the existing, bottom X axis title.
label -xb time; //The bottom X axis title will be set as time.
-xt; Reset the top X axis title
Syntax: label -xt message
Create a new, or replace the existing, top X axis title.
-yl; Reset the left Y axis title
Syntax: label -yl message
Create a new, or replace the existing, left Y axis title.
-yr; Reset the right Y axis title
Syntax: label -yr message
Create a new, or replace the existing, right Y axis title.
-zb; Reset the back Z axis title
Syntax: label -zb message
Create a new, or replace the existing, back Z axis title.
-zf; Reset the front Z axis title
Syntax: label -zf message
Create a new, or replace the existing, front Z axis title.
Examples:
Example 1
The following script creates a label that reads New Label Text which is center justified and named MYLABEL. It draws the label in quadrant 3 of the active layer of the active window.
label -q 3 -j 2 -n MYLABEL New Label Text;
Example 2
The next script creates a bottom X axis label Maximum Current.
lab -xb (Maximum Current);
Example 3
The next script updates the content of the label named myLabel with run time values. Note that you could also set up the label with the same text with the Link to Variables option enabled in the Label Control dialog box (see the next example).
%A = "position = $(x)";
label -s -n myLabel %A;
Example 4
The next script creates a label named myLabel with the Link to Variables check box in the Label Control dialog box selected. The label displays the current value of the x system variable, which is the current X coordinate of the Screen Reader, Data Reader, or Data Selector tools.
label -sl -n mylabel "position = $(x)";
Example 5
This script shows how to add the file path as graph label, and delete it after exporting the graph. %G and %X are string registers for the current file name and path, while \v() is a escape sequence.
label -s -px 20 10 -n ForPrintOnly \v(Generated from %X%G.opj);
expGraph type:=png filename:=MySampleGraph path:=D:\;
label -r ForPrintOnly;
See Also:
Legend (command) to create a legend in a graph.
|