GUIText

Description:	Draws formatted text in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns:	GUI Object Return Codes
Usage:	Steady State only.
Function Groups:	Graphics
Format:	GUIText(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Opacity, Options, Button, FocusID, FocusTrigger, Brush, Pen, Font, HCenter, VCenter, Format, V1, V2, ...)
Parameters:

LeftReference

A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.

BottomReference

A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.

RightReference

A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.

TopReference

A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.

ScaleLeft

Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.

ScaleBottom

ScaleRight

ScaleTop

ScaleWhole

Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.

Trajectory

Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.

Rotation

Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.

Opacity

Required. Any Numeric expression, setting the opacity of the object. A value of one results in a solid, zero is invisible and values between zero and one are used as an alpha setting for opacity.

Options

Required. Any numeric expression giving how a font behaves with regards to scaling, as follows:

Options

Font Behavior

The text will stay at its native font size, even though all the other graphics around it are being scaled with the page

The font size will scale proportionally to the vertical scaling of the page.

If the text is drawn by a widget, it will scale doubly, both with the containing widget and the containing page.

Typically used by a widget that draws its own GUIText. By setting Options to 2, the text inside the widget will only scale in proportion to the topmost scaling, i.e. the page's scaling, and will ignore any scaling of the intermediate widget(s).

Text squeezing is on by default, reducing text by as much as 35% to fit within the available space. If you set bit 3 (add 0b1000 to whatever value you are using in the Options parameter), then text will not scale down to fit within the available space. Text that does not fit is clipped.

Button

Required. Any numeric expression giving the button combination that activates this graphic.

Button	Locator Buttons
0	No buttons
1	Right button
2	Middle button
3	Right and middle buttons
4	Left button
5	Left and right buttons
6	Left and middle buttons
7	All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID

Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.

FocusTrigger

Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.

Brush

Required. Any expression that returns a Brush value to describe the background. A solid-color background may be defined by using any of the following:

a palette index VTScada Color Palette
a system color Constants for System Colors
-1 (transparent)
an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.

Pen

Required. Any expression that returns a Pen value. Only the color property of the pen will be used. You may also use any of the following:

a palette index VTScada Color Palette
a system color Constants for System Colors
-1 (transparent)
an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.

Font

Required. Any expression that returns a Font value used to display the text.

HCenter

Required. Any numeric expression that specifies the horizontal justification and clipping, as shown in the following table:

Value	H. Justification	Clipping
0	Left	Right
1	Left	Both
2	Left	Left
3	Center	Right
4	Center	Both
5	Center	Left
6	Right	Right
7	Right	Both
8	Right	Left

VCenter

Required. Any numeric expression that specifies the vertical justification and clipping, as shown in the following table:

Value	V. Justification	Clipping
0	Top	Bottom
1	Top	Both
2	Top	Top
3	Center	Bottom
4	Center	Both
5	Center	Top
6	Bottom	Bottom
7	Bottom	Both
8	Bottom	Top

Format

Required. Any text expression giving the format of how the values (Vn parameters) are to be written. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the GUIText statement is assigned to a % format specification in the order in which each appears in the list. Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format. For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[ - ][ + ][ SPACE ][ # ][ width ][ .precision ]type

where:

% is mandatory.

+ causes the data to be left justified within the field. For binary types b and ASCII character types c, this option is ignored.

- causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column of numbers. For binary types b and non-numerical types, this option is ignored.

SPACE represents the single space character, and is similar to the [ + ] option but places a single space rather than a plus sign in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored.

# When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively..

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value will be output in their entirety without truncation. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether the [ - ] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored.

.precision has a different meaning for each of the type options as follows:

Integer types d, i, u, o, x and X - precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeroes will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is not truncated.

Floating point types e and E - precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0 or if the decimal point appears without a number following it, no decimal point appears in the output.

Floating point type f - precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.

Floating point types g and G - precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.

String type s - precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated and only the first characters are written. If the precision is not specified, all of the string characters are output.

ASCII character type c - this option is ignored.

Binary type b - this option is ignored.

type is a mandatory specification that must be one of those listed here. Note that the case of the letter is important. Specifying a character for the type which is not in this list will result in all the characters following the % up to that point to be output exactly as they appear in the Format string.

Type	Meaning
nb	Binary format, where n is a number indicating the type of value (following table)
c	Single ASCII character (byte)
d	Signed decimal integer
e	Signed exponential. Exponent key is "e"
E	Signed exponential. Exponent key is "E"
f	Signed floating point
g	e or f format, whichever is shorter
G	E or f format, whichever is shorter
i	Signed decimal integer
o	Unsigned octal integer
s	Text string
u	Unsigned decimal integer
x	Unsigned hex integer using "abcdef"
X	Unsigned hex integer using "ABCDEF"

Binary type b - For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices:

n Value	Type
0	Byte
1	Short integer (2 bytes, low byte first)
2	Long integer (4 bytes, low bytes first)
3	IEEE single precision float (4 bytes)
5	IEEE double precision float (8 bytes)

Notice that the other options such as width and precision do not apply to the b type.

ASCII character type c - This type is not representative of a single character in a string, but rather, represents single byte ASCII characters. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255 in order for the output to be a valid ASCII equivalent character. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as GUIText than when used in an input statement, such as BuffRead.

Text string type s - Text in the string is written exactly as it appears, with two exceptions. First, since format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the text string, precede it with a backslash character (i.e. \%). Also, since the backslash character is used in this manner, as well as with special control characters such as form feed, to write a backslash as part of the text string, use two backslash characters (i.e. \\).

Note: Omitting the %s format character for parameters that are to display as strings can result in errors such as "Area\Place" being displayed as "AreaPlace".

Control characters - In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed here to produce the desired result (notice that the letters must be lower case):

Code	Meaning
\b	Backspace
\f	Form feed
\t	Horizontal tab
\v	Vertical tab

In addition to the predefined codes, an alternate form may be used :

\nnn

Where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes. This is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, ...

Required. Any expressions giving the values to be output in the form described by the Format parameter. Each of the Vn parameters is evaluated and written in the order in which each appears in the parameter list. The way in which they are formatted is dictated by the % format specifications. V1 is formatted by the first % sequence in the Format parameter, V2 by the second, and so on. If there are more V parameters than % sequences in the Format string, the remainder are ignored. If there are fewer V parameters than % sequences in the Format string, the remaining % sequences are written literally without any translation.
If a numeric value is Invalid or outside of the range of the type indicated by the format specifier, a 0 is used as its value. If a text string value is Invalid, spaces will be output. Invalidity of Vn parameters does not preclude execution of this function.

Comments:

This function is a layered graphics statement. See Use Scaling to Position GUI Objects for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1^st 42 pixels of a VTScada application will be obscured by the title bar, if present.

It produces formatted text in exactly the same manner as BuffWrite, FWrite, and SWrite. The text is displayed directly on the screen, centered in the reference box after any animation is applied.. Binary formats are not useful here and will produce strings with non-printable characters.

As of version 12.0, VTScada expects all strings to be encoded using UTF-8.

Will not display tab characters.

Example:

GUIText(0, 100, 100, 0 { Bounding box of text },
        1, 1, 1, 1, 1 { No scaling },
        0, 0 { No trajectory or rotation },
        1, 0 { Text is visible; reserved },
        0, 0, 0 { Cannot be focused/selected },
        Brush(12, 0, 1){ Brush is red, background
                        ignored (style is solid) },
        Pen(15, 1, 1) { White solid line 1 pixel wide },
        Font("Courier" { Font name },
                0 { Character set },
               14 { Height },
               0 { No rotation },
               0 { Weight },
               0 { Not italicized },
               1 { Fixed pitch }),
         4 { Center horizontally },
         4 { Center vertically },
        "Valve = %6.2f%% open." { Format specifier },
        valvePosition { First value });

This shows text in the upper left corner of the window. It cannot be focused. No scaling or animation is performed. If valvePosition contains the number 56.789, the text is displayed as:

Valve = 56.78% open.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.

Related Functions: