6.1-roTextWidget

Object Creation: This object is created using one of two variants.

CreateObject("roTextWidget", r As roRectangle, line_count As Integer, text_mode As Integer, pause_time As Integer)

• r : An roRectangle instance that contains the text
• line_count: The number of lines of text to show within the rectangle
• text_mode: The animation characteristics of the text:
  • 0: An animated view similar to teletype
  • 1: Static text
  • 2: Simple text with no queue of strings
  • 3: Smooth right-to-left scrolling ticker

• pause_time: The length of time each string is displayed before displaying the next string. This does not apply to text mode 2 or 3 because the strings on screen are updated immediately.

CreateObject("roTextWidget", r As roRectangle, line_count As Integer, text_mode As Integer, parameters As roAssociativeArray)

• r: An roRectangle instance that contains the text
• line_count: The number of lines of text to show within the rectangle
• text_mode: The animation characteristics of the text:
  • 0: An animated view similar to teletype
  • 1: Static text
  • 2: Simple text with no queue of strings
  • 3: Smooth scrolling ticker (strings are separated by a diamond)
• parameters: An associative array that can include the following values:
  
  • LineCount: The number of lines of text to show within the rectangle.
  • TextMode: The animation characteristics of the text:
    • 0: An animated view similar to teletype
    • 1: Static text
    • 2: Simple text with no queue of strings
    • 3: Smooth scrolling ticker (strings are separated with a diamond by default; the separator can be modified using the SetSeparator() method)
  • PauseTime: The length of time each string is displayed before displaying the next string. This does not apply to text mode 2 or 3 because the strings on screen are updated immediately.
  • Rotation: The rotation of the text within the widget:
    • 0: 0 degrees
    • 1: 90 degrees. This value can also be represented in degrees (90) or radians (.5Π).
    • 2: 180 degrees. This value can also be represented in degrees (180) or radians (Π).
    • 3: 270 degrees. This value can also be represented in degrees (270) or radians (1.5Π).
  • Alignment: The alignment of the text:
    • 0: Left
    • 1: Center
    • 2: Right

ifTextWidget

PushString(str As String) As Boolean

Adds the string to the list of strings to display in modes 0 and 1. Strings are displayed in order, and when the end is reached, the object loops, returning to the beginning of the list. In mode 2, the string is displayed immediately.

PopStrings(number_of_string_to_pop As Integer) As Boolean

Pops strings off the front of the list (using "last in, first out" ordering) in modes 0 and 1. This occurs the next time the widget wraps so that strings can be added to and removed from the widget seamlessly. In mode 2, the string is cleared from the widget immediately.

GetStringCount() As Integer

Returns the number of strings that will exist once any pending pops have taken place.

Clear() As Boolean

Clears the list of strings, leaving the widget blank and able to accept more PushString() calls.

SetStringSource(file_path As String) As Boolean

Displays the text file at the specified path as a single, continuous string. This method is only applicable to text mode 3 (scrolling ticker). When the end of the file is reached, the text widget loops to the beginning, using a diamond symbol as the separator.

SetAnimationSpeed(speed As Integer) As Boolean

Sets the speed at which animated text displays. This method is applicable to text modes 0 and 3 only:

• Mode 0: The default speed value is 10000. Setting an integer above this value decreases the speed of the teletype-style ticker: For example, specifying a value of 20000 will decrease the default speed at which text displays by half, while a value of 5000 will double the default speed.
• Mode 3: The default speed value is 10000. Because the speed of a scrolling ticker is measured in pixels per second (PPS), the speed must be a multiple of the current framerate, or else it will be rounded down to the nearest multiple (for example, a framerate of 60p will honor PPS values of 60, 120, 180, etc.). The software determines the speed of the scrolling ticker by performing the following calculation on the passed speed parameter:
  PPS = (speed * 60) / 10000

SetSeparator(separator As String) As Boolean

Changes the separator between strings. The default diamond separator will be replaced by the contents of the passed string. This method applies to Text Mode 3 (smooth scrolling ticker) only. The following strings indicate special symbols: ":diamond:", ":circle:", ":square:".

SetMultiscreen(offset As Integer, size As Integer, ip_address As String, port As Integer) As Boolean

Allows for a smooth-scrolling ticker to be displayed across multiple screens. The leader screen is designated as the instance with the rightmost offset of all the players in the multiscreen array; all PushString() and Show() calls (as well as any other changes) must be made on the leader instance. Follower instances of the text widget will remain blank until the leader starts. This method requires the following parameters:

• offset: The offset (in pixels) of the display in the multiscreen array. For example, using an offset of 1920 in a two-screen array of 1920x1080 screens would specify this player as the right-hand (leader) display.
• size: The total width (in pixels) of the multiscreen array. For example, defining a size of 3840 would specify a two-screen array of 1920x1080 screens.
• ip_address: A string specifying the multicast IP address for the PTP synchronization process (e.g. "239.192.0.0")
• port: A string specifying the multicast port for the PTP synchronization process (e.g. "1234").

ifWidget

Show() As Boolean

Displays the widget. After creation, the widget is hidden until Show() is called.

Hide() As Boolean

Hides the widget.

SetForegroundColor(color As Integer) As Boolean

Sets the foreground color in ARGB format.

SetBackgroundColor(color As Integer) As Boolean

Sets the background color in ARGB format.

SetFont(font_filename As String) As Boolean

Sets the font_filename using a TrueType font (for example, "SD:/ComicSans.ttf").

SetBackgroundBitmap(bitmap_filename As String, stretch As Boolean) As Boolean

Sets the background bitmap image. If stretch is True, then the image is stretched to the size of the window.

SetBackgroundBitmap(parameters As roAssociativeArray, stretch As Boolean) As Boolean

Sets the background bitmap image. If stretch is True, then the image is stretched to the size of the window. The associative array can contain the following parameters:

• Filename: The name of the image file
• EncryptionAlgorithm: The file-encryption algorithm. Currently the options are "AesCtr" and "AesCtrHmac".
• EncryptionKey: The key to decrypt the image file. This is a byte array consisting of 128 bits of key, followed by 128 bits of IV.

SetSafeTextRegion(region As roRectangle) As Boolean

Specifies the rectangle within the widget where the text can be drawn safely.

SetRectangle(r As roRectangle) As Boolean

Changes the size and positioning of the widget rectangle using the passed roRectangle object.

GetFailureReason() As String

Yields additional useful information if a function return indicates an error.