roTextWidget

this object is used to display text on the screen note that "scrolling ticker" mode is limited to 10 tickers at a time you can have 100 rotextwidgets, so long as they are in some other mode (for example, "static text") object creation this object is created using one of two variants option 1 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 scrolling ticker (strings are separated with a diamond by default; the separator can be modified using the setseparator() method) note that this option is not available for lsx22, hdx20, or hdx10 models 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 option 2 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 scrolling ticker (strings are separated with a diamond by default; the separator can be modified using the setseparator() method) note that this option is not available for lsx22, hdx20, or hdx10 models 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 scrolling ticker (strings are separated with a diamond by default; the separator can be modified using the setseparator() method) note that this option is not available for lsx22, hdx20, or hdx10 models 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 (note that the coordinates and dimensions of the rectangle itself are not rotated) 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 modes 0, 1, and 3 are useful for displaying rss feeds and ticker type text however, for dynamic data where immediate screen updates are required, mode 2 may be more appropriate mode 2 allows text to be drawn immediately to the screen text mode 3 (scrolling ticker) supports both right to left and left to right (e g arabic, hebrew) scrolling modes, depending on the language of the first string or file added to the widget to change the scrolling direction, you will first need to remove all strings from the ticker iftextwidget setglobalparameter(param as string, value as integer) as void configures parameters related to scrolling tickers (i e text mode 3) the following are accepted parameters startat the starting position of scrolling text, which can be any number between 0 (the left side of the screen) and the total width of the widget to start at the right side of the screen (i e offscreen), specify a value of 1 or the total width of the widget autopop the autopop setting for the widget if this value is set to 1, strings are automatically removed (popped from the stack) once they have scrolled offscreen if this value is set to 0 (the default behavior), strings are not automatically removed autoaddseparator the separator setting for the widget setting this value to 0 disables string separators (useful for displaying emojis with the pushsurface() method), while setting this value to 1 enables string separators (the default behavior) gap the gap (in pixels) between the string and the string separator (at both the beginning and end of strings) the default value is 0 this parameter may not be reliable if the ticker contains strings in its memory global parameters can be altered after show() is called, but in some cases (e g the startat parameter) their results are undefined the parameters autopop and autoaddseparator are intended to be used once show() has been called getglobalparameter(param as string) as integer returns the value of a parameter set using the setglobalparameter() method this method also returns a value for the read only " last string id " parameter, which is a unique identifier for the string most recently added to the list list value that is identical to the integer returned by the pushstring() and pushsurface() methods pushstring(str as string) as boolean adds the string to the list of elements to display in modes 0, 1, and 3 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 this method returns a unique identifier, which can be used with rotextwidgetevent messages to determine when the string has moved offscreen a failure to add an element to the list returns "0" adding too many strings without popping them from the stack will cause pushstring() to return false (the exact number depends on the font size for each string) the maximum recommended number of stored strings is 64 pushsurface(image as roimagebuffer) as integer adds a bitmap image to the list of elements to display in modes 0, 1, and 3 images are scaled to match the height of the ticker this method returns a unique identifier which can be used with rotextwidgetevent messages to determine when the image/surface has moved offscreen a failure to add an element to the list returns "0" there are currently no restrictions on formatting, but it is recommended to use the same color format as the main screen popstrings(number of string to pop as integer) as boolean pops elements off the front of the list (using "last in, first out" ordering) in modes 0, 1, and 3 this occurs the next time the widget wraps so that elements can be added to and removed from the widget seamlessly in mode 2, the element is cleared from the widget immediately getstringcount() as integer returns the number of elements that will exist once any pending pops have taken place clear() as boolean clears the list of elements, 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 ", "" setsyncmanager(domain as string) as boolean specifies a rosyncmanager docid\ wwc22zsphu1e689xe7en6 domain to use when executing the setmultiscreen() call when this method is called, it creates an internal domain that is based on the existing rosyncmanager domain and uses the same network parameters we recommend using this method instead of passing a multicast ip address and port to the setmultiscreen() method itself setmultiscreen(offset as integer, size as integer, ip address as string, port as integer) as boolean displays a smooth scrolling ticker across multiple screens to specify network synchronization parameters, you can either call the setsyncmanager() method first or pass the optional ip address and port values to the setmultiscreen() method (calling setsyncmanager() is preferred) if you use setsyncmanager() , do not specify the ip address / port ; doing so may lead to unexpected behavior the master 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 master 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 (master) 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 rosyncmanager docid\ wwc22zsphu1e689xe7en6 network traffic (e g "239 192 0 0") port a string specifying the multicast port for the ptp synchronization process (e g 1234) players can support more than one multiscreen ticker at a time ifwidget show() as boolean displays the widget after creation, the widget is hidden until show() is called hide() as boolean hides the widget raise() as void sends the widget to the top of the z order on the graphics plane (i e in front of all other surfaces that implement the ifwidget interface) by default, new widgets are placed at the top of the graphics z order some surfaces are always drawn at the top of the graphics z order, including the mouse cursor, closed captions, and scrolling tickers tip you can use the pausegraphics() / resumegraphics() methods on the rovideomode docid\ qq734nqz0hcwni0unsdmp object to ensure multiple changes to the graphics z order occur simultaneously lower() as void sends the widget to the bottom of the z order on the graphics plane (i e behind all other surfaces that implement the ifwidget interface) by default, new widgets are placed at the top of the graphics z order setforegroundcolor(color as integer) as boolean sets the foreground color in argb format the top 8 bits are "alpha" parameters zero is equivalent to fully transparent and 255 to fully non transparent foreground alpha values are currently unsupported with ticker mode 3 (scrolling ticker) and will be ignored by this method this behavior may change in future firmware versions hex color values should be converted to integers before being passed to this method (e g the value \&hffffffff should be passed as 4294967295) you can use the hextointeger() method (available in the core library extension docid\ leoo6do arr2igzxcripi ) to convert a hex string to an integer setbackgroundcolor(color as integer) as boolean sets the background color in argb format the top 8 bits are "alpha" parameters zero is equivalent to fully transparent and 255 to fully non transparent this feature allows for effects similar to subtitles for example, you can create a semi transparent black box containing text over video hex color values should be converted to integers before being passed to this method (e g the value \&hffffffff should be passed as 4294967295) you can use the hextointeger() method (available in the core library extension docid\ leoo6do arr2igzxcripi ) to convert a hex string to an integer setfont(font filename as string) as boolean specifies a custom font for the widget using a truetype font file from local storage (e g "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 widget 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 widget 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 see the roimageplayer docid 0umxqyvruy7drnluuzafp section in the roimageplayer entry for details on displaying encrypted images 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