3.3.2.32 Label (command)

Places a text label on the page.

1 Syntax:
2 Note--Using Escape Sequences to Control Text Format:
3 Options:
4 Examples:
5 See Also:

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;

-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;