Bright Script Reference Manual (ver 7.0)
BrightScript%20Reference%20Manual%20(ver%207.0)
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 325
1. BrightScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 Language Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Variables, Literals, and Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Objects and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4 XML Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.5 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.7 Threading Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.8 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.9 Intrinsic Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.10 Program Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.11 Built-In Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.12 Core Library Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.13 BrightScript Debug Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.14 BrightScript Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.15 Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.16 Example Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Object Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Global Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 BrightScript Core Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.1 roArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.2 roAssociativeArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.3 roBoolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.4 roByteArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.5 roDouble, roIntrinsicDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.6 roFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.7 roInt, roFloat, roString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.8 roJRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.9 roList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.10 roMessagePort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.11 roRegex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.12 roXMLElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2.13 roXMLList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3 Presentation and Widget Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.1 roAudioConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.2 roAudioOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.3 roAudioPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.4 roAudioPlayerMx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.5 roAudioEventMx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.6 roCanvasWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.7 roClockWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.8 roHdmiInputChanged, roHdmiOutputChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.9 roHtmlWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.10 roHtmlWidgetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.11 roImageBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.12 roImagePlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.13 roImageWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.14 roRectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.15 roStreamQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.16 roTextField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.17 roTextWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.18 roTextWidgetEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.19 roTouchScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.20 roTouchEvent, roTouchCalibrationEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.21 roVideoEvent, roAudioEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.22 roVideoInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.23 roVideoMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3.24 roVideoPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 File Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.1 roAppendFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.2 roCreateFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.3 roReadFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4.4 roReadWriteFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5 Hashing and Storage Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.1 roBlockCipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.2 roBrightPackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.3 roDiskErrorEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.4 roDiskMonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.5 roHashGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.6 roPassKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.7 roRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.8 roRegistrySection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.9 roSqliteDatabase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.10 roSqliteEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
4
4
8
11
12
16
16
17
17
17
18
26
30
31
32
33
34
39
41
48
49
50
53
53
56
57
57
61
62
65
66
67
70
73
74
75
76
81
84
85
88
91
91
101
102
103
108
111
113
115
117
121
122
126
127
129
131
140
154
155
156
158
159
161
161
162
165
166
167
168
168
169
170
172
1.2.5.11 roSqliteStatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.12 roStorageAttached, roStorageDetached . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.13 roStorageHotplug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.14 roStorageInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5.15 roVirtualMemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6 Content Management Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.1 roAssetCollection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.2 roAssetFetcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.3 roAssetFetcherEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.4 roAssetFetcherProgressEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.5 roAssetPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.6 roAssetPoolFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.7 roAssetRealizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.8 roAssetRealizerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6.9 roSyncSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7 Networking Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.1 roDatagramReceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.2 roDatagramSender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.3 roDatagramSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.4 roDatagramEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.5 roHttpServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.6 roHttpEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.7 roKeyStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.8 roMediaServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.9 roMediaStreamer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.10 roMediaStreamerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.11 roMimeStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.12 roMimeStreamEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.13 roNetworkAdvertisement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.14 roNetworkConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.15 roNetworkAttached . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.16 roNetworkDetached . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.17 roNetworkDiscovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.18 roNetworkHotplug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.19 roNetworkStatistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.20 roPtp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.21 roPtpEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.22 roRssArticle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.23 roRssParser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.24 roRtspStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.25 roSnmpAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.26 roSnmpEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.27 roStreamByteEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.28 roStreamConnectResultEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.29 roStreamEndEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.30 roStreamLineEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.31 roSyncManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.32 roSyncManagerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.33 roTCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.34 roTCPConnectEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.35 roUPnPActionResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.36 roUPnPController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.37 roUPnPDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.38 roUPnPSearchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.39 roUPnPService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.40 roUPnPServiceEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.41 roTCPStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.42 roUrlTransfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.7.43 roUrlEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8 Input/Output Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.1 roBtManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.2 roBtClientManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.3 roBtClientManagerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.4 roBtClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.5 roBtClientEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.6 roCecInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.7 roCecRxFrameEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.8 roCecTxCompleteEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.9 roChannelManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.10 roControlPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.11 roControlUp, roControlDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.12 roGpioButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.13 roGpioControlPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.14 roIRReceiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.15 roIRDownEvent, roIRRepeatEvent, roIRUpEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
175
176
178
180
181
181
183
186
189
190
192
193
194
195
197
198
199
200
201
202
205
207
209
210
212
213
214
214
215
228
229
230
232
233
234
234
235
236
237
238
239
240
240
241
242
242
245
245
246
247
248
249
250
251
252
253
255
262
266
267
269
271
271
273
273
274
275
276
280
286
287
287
288
289
1.2.8.16 roIRTransmitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.17 roIRTransmitCompleteEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.18 roIRRemote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.19 roIRRemotePress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.20 roKeyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.21 roKeyboardPress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.22 roSequenceMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.23 roSequenceMatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.8.24 roSerialPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9 System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9.1 roDeviceCustomization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9.2 roDeviceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9.3 roResourceManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.9.4 roSystemLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10 Date and Time Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.1 roDateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.2 roNetworkTimeEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.3 roSystemTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.4 roTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.5 roTimerEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.10.6 roTimeSpan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11 Legacy Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11.1 roRtspStreamEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11.2 roSyncPool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11.3 roSyncPoolEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11.4 roSyncPoolFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.11.5 roSyncPoolProgressEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
290
291
292
293
294
295
296
297
298
301
301
302
306
307
309
309
311
312
315
317
318
319
319
320
323
323
324
BrightScript
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
Note
If you're having trouble viewing the above file, make sure you are accessing this site via HTTPS (e.g. https://docs.brightsign.biz).
BrightScript is a powerful scripting language for building media and networked applications for embedded devices. This language features
integrated support for a lightweight library of BrightScript objects, which are used to expose the API of the platform (device) that is running
BrightScript. The BrightScript language connects generalized script functionality with underlying components for networking, media playback, UI
screens, and interactive interfaces; BrightScript is optimized for generating user-friendly applications with minimal programmer effort.
The BrightScript section is divided into two categories:
Language Reference: Outlines the characteristics of the BrightScript language, such as syntax, operators, statements, types, core
library, etc.
Object Reference: Provides a directory of publicly available objects, interfaces, and methods that comprise the BrightScript API.
Language Reference
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
The following are some general characteristics of BrightScript, as compared to other common scripting languages:
BrightScript is not case sensitive.
Statement syntax is similar to Python, Basic, Ruby, and Lua (and dissimilar to C).
Like JavaScript and Lua, objects and named data-entry structures are associative arrays.
BrightScript supports dynamic typing (like JavaScript) and declared types (like C and Java).
Similar to .Net and Java, BrightScript uses "interfaces" and "components" (i.e. objects).
BrightScript code is compiled into bytecode that is run by an interpreter. The compilation step occurs every time a script is loaded and run. Similar
to JavaScript, there is no separate compilation step that results in a saved binary file.
BrightScript and its component architecture are written in 100% C for speed, efficiency, and portability. Since many embedded processors do not
have floating-point units, BrightScript makes extensive use of the "integer" type. Unlike some languages (including JavaScript), BrightScript only
uses floating point numbers when necessary.
Variables, Literals, and Types
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
Identifiers
Types
Type Declaration Characters
Literals (Constants)
Array Literals
Associative Array Literals
Invalid Object Return
Numbers
Dynamic Typing
Type Conversion
Type Conversion and Accuracy
Identifiers
Identifiers are names of variables, functions, and labels. They also apply to BrightScript object methods (i.e. functions) and interfaces (which
appear after a "." Dot Operator). Identifiers have the following rules:
Must start with an alphabetic character (a-z).
May consist of alphabetic characters, numbers, or the underscore symbol ("_").
Are not case sensitive.
May be of any length.
May not be a reserved word.
(variables only) May end with an optional type declaration ("$" for a string, "%" for an integer, "!" for a float, "#" for a double).
Examples
a
boy5
super_man$
42%
Types
BrightScript supports both dynamic typing and declared types. This means that every value has a type determined at runtime, but variables can
also be instructed to always contain a value of a specified type. If a value is assigned to a variable that has a specified type, the type of the value
will be converted to the variable type if possible. If conversion is impossible, a runtime error will occur.
A variable that does not end in a type declaration may change its type dynamically. For example, the statement a=4 will create an integer, while a
following statement specifying that a="hello" will change the type of the variable a to a string.
BrightScript supports the following types:
Boolean: True or False
Integer: A 32-bit signed integer number
Float: The smallest floating point number format supported by either the hardware or software
Double: The largest floating point number format supported by either the hardware or software. Although Double is an intrinsically
understood type, it is implemented internally with the roIntrinsicDouble object.
String: A sequence of ASCII (not UTF-8) characters. BrightScript uses two intrinsic string states:
Constant strings: A statement such as s="astring" will create an intrinsic constant string.
roString instances: Once a string is used in an expression, it becomes an roString instance. For example, the statement s =
s + "bstring" will cause the intrinsic string s to convert to an roString instance. If this is followed by the statement s2 = s,
the s2 value will be a reference to s, not a copy of it. The behavior of reference counting strings is new to BrightScript version
3.0.
Object: A reference to a BrightScript object (i.e. a native component). Note that the type() function will not return "Object" but the type
of object instead (e.g. roList, roVideoPlayer). Also note that there is no separate type for intrinsic BrightScript Objects. All intrinsic
BrightScript Objects are built on the roAssociativeArray object type.
Interface: An interface in a BrightScript Object. If a "." Dot Operator is used on an interface type, the member must be static (since there
is no object context).
Invalid: A type that can have only one value: Invalid. This type is returned in various instances when no other type is valid (for
example, when indexing an array that has never been sent). It can also be assigned to a variable with the statement var = invalid.
The following are examples of different types. The ? statement is a shortcut for print, while the type() function returns a string that identifies
the type of the passed expression.
BrightScript> ?type(1)
Integer
BrightScript> ?type(1.0)
Float
BrightScript> ?type("hello")
String
BrightScript> ?type(CreateObject("roList"))
roList
BrightScript> ?type(1%)
Integer
BrightScript> b!=1
BrightScript> ?type(b!)
Float
BrightScript> c$="hello"
BrightScript> ?type(c$)
String
BrightScript> d="hello again"
BrightScript> ?type(d)
String
BrightScript> d=1
BrightScript> ?type(d)
Integer
BrightScript> d=1.0
BrightScript> ?type(d)
Float
BrightScript>e=invalid
BrightSCript>?type(e)
Invalid
Type Declaration Characters
A type declaration may be used at the end of a variable or literal to fix its type. Variables with the same identifier but separate types are separate
variables: For example, defining a$ and a% would create two independent variables.
Character
Type
Examples
$
String
A$, ZZ$
%
Integer
A1%, SUM%
!
Single-Precision (Float)
B!, N1!
#
Double-Precision (Double)
A#, 1/3#, 2#
Literals (Constants)
The following are valid literal types:
Type Boolean: Either True or False
Type Invalid: Invalid only
Type String: A string in quotes (e.g. "This is a string")
Type Integer: An integer in hex (e.g. HFF) or decimal (e.g. 255) format
Type Float: A number with a decimal (e.g. 2.01), in scientific notation (e.g. 1.23456E+30), or with a Float type designator (e.g. 2!)
Type Double: A number in scientific notation containing a double-precision exponent symbol (e.g. 1.23456789D-12) or with a Double
type declaration (e.g. 2.3#)
Type Function: Similar to variable formatting (e.g. MyFunction)
Type Integer: LINE_NUM – The current source line number
Array Literals
The [] Array Operator can be used to declare an array. It can contain literals (constants) or expressions.
x = 5
Myarray = []
Myarray = [ 1, 2, 3]
Myarray = [ x+5, true, 1<>2, ["a","b"]]
Associative Array Literals
The { } Associative Array Operator can be used to define an associative array. It can contain literals (constants) or expressions.
aa = { }
aa = {key1:"value", key2: 55, key3: 5+3 }
Arrays and associative arrays can also be defined with the following format:
aa = {
Myfunc1: aFunction
Myval1 : "the value"
}
Invalid Object Return
Many methods (i.e. functions) that return objects can also return Invalid (for example, in cases where there is no object to return). In these cases,
the variable accepting the result must be dynamically typed since it may be assigned either type.
The following code will return a type mismatch: a$ is a string that has a string type declaration, and thus it cannot contain Invalid.
l = []
a$ = l.pop()
Numbers
Dynamic Typing
The following rules determine how integers, doubles, and floats are dynamically typed:
1. If a constant contains 10 or more digits, or if D is used in the exponent, the number is Double. Adding a # type declaration also forces a
constant to be a Double.
2. If the number is not double precision and it contains a decimal point, the number is a Float. Expressing a number in scientific notation
using the E exponent also forces a constant to be a Float.
3.
3. If neither of the above conditions is true for a constant, the number is an Integer.
Type Conversion
When operations are performed on one or two numbers, the result must be typed as an Integer, Float, or Double. When an addition (+),
subtraction (-), or multiplication (*) operation is performed, the result will have the same degree of precision as the most precise operand: For
example, multiplying an Integer by a Double will return a number that is a Double.
Only when both operands are Integers will the result be an Integer number. If the result of two Integer operands is outside the 32-bit range, the
operation and return will be carried out with Doubles.
Division (/) operates using the same rules as above, except that it can never be carried out at the Integer level: When both operators are Integers,
the operation and return will be carried out with Floats.
Comparison operations (e.g. <, >, =) will convert the numbers to the same type before they are compared. The less precise type will always be
converted to the more precise type.
Type Conversion and Accuracy
When a Float or Double number is converted to the Integer type, it is rounded down: The largest integer that is not greater than the number is
used. This also happens when the INT function is called on a number.
When a Double number is converted to the Float type, it is 4/5 rounded: The least significant digit is rounded up if the fractional part is >=5
(otherwise, it is left unchanged).
When a Float number is converted to the Double type, only the seven most significant digits will be accurate.
Operators
ON THIS PAGE
Logical and Bitwise Operators
Dot Operator
Associative Arrays
Array and Function-Call Operators
Array Dimensions
Equals Operator
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
Operations in the innermost level of parentheses are performed first. Evaluation then proceeds according to the precedence in the following table.
Operations on the same precedence are left-associative, except for exponentiation, which is right-associative.
Description
Symbol(s)
Function Calls or Parentheses
()
Array Operators
. , []
Exponentiation
^
Negation
–, +
Multiplication, Division, Modulus
*, /, MOD
Addition, Subtraction
+, -
Comparison
<, >, = , <>, <=, >=
Logical Negation
NOT
Logical Conjunction
AND
Logical OR
OR
String Operators: The following operators work with strings: <, >, =, <>, <=, >=, +
Function References: The = and <> operators work on variables that contain function references and function literals.
Logical and Bitwise Operators
The AND, OR, and NOT operators are used for logical (Boolean) comparisons if the arguments for these operators are Boolean:
a = 20
b = 20
c = 20
if a = c and not(b > 40) then print "success"
On the other hand, if the arguments for these operators are numeric, they will perform bitwise operations:
x = 1 and 2
' x is zero
y = true and false ' y is false
When the AND or OR operator is used for a logical operation, only the necessary amount of the expression is executed. For example, the first
statement below will print "True", while the second statement will cause a runtime error (because "invalid" is not a valid operand for OR):
print true or invalid
print false or invalid
Dot Operator
The "." Dot Operator can be used on any BrightScript object. It also has special meaning when used on an roAssociativeArray object, as well as r
oXMLElement and roXMLList objects. When used on a BrightScript object, it refers to an interface or method associated with that object. In the
following example, IfInt refers to the interface and SetInt() refers to a method that is part of that interface:
i = CreateObject("roInt")
i.ifInt.SetInt(5)
i.SetInt(5)
Every object method is part of an interface. However, specifying the interface with the "." Dot Operator is optional. If the interface is omitted, as in
the third line of the above example, each interface that is part of the object will be searched for the specified member. If there is a naming conflict
(i.e. a method with the same name appears in two interfaces), then the interface should be specified.
Associative Arrays
When the "." Dot Operator is used on an Associative Array, it is the same as calling the Lookup() or AddReplace() methods, which are
member functions of the roAssociativeArray object:
aa = {}
aa.newkey = "the value"
print aa.newkey
Note that the parameters of the "." Dot Operator are set at compile time; unlike the Lookup() and AddReplace() methods, they are not
dynamic.
The "." Dot Operator is always case insensitive: For example, the statement aa.NewKey=55 will create the entry "newkey" in the associative
array. To generate case-sensitive keys, instantiate an roAssociativeArray object and use the SetModeCaseSensitive() method.
Array and Function-Call Operators
The [ ] operator is used to access an array (i.e. any BrightScript object that has an ifArray interface, such as roArray and roList objects). It can
also be used to access an associative array. The [ ] operator takes expressions that are evaluated at runtime, while the "." Dot Operator takes
identifiers at compile time.
The ( ) operator can be used to call a function. When used on a function literal (or variable containing a function reference), that function will be
called.
The following code snippet demonstrates the use of both array and function-call operators.
aa = CreateObject("roAssociativeArray")
aa["newkey"] = "the value"
print aa["newkey"]
array = CreateObject("roArray", 10, true)
array[2] = "two"
print array[2]
fivevar = five
print fivevar()
array[1] = fivevar
print array[1]()
' print 5
function five() As Integer
return 5
end function
Array Dimensions
Arrays in BrightScript are one dimensional. Multi-dimensional arrays are implemented as arrays of arrays. The [ ] operator will automatically map
multi-dimensionality. For example, the following two fetching expressions are the same:
dim array[5,5,5]
item = array[1][2][3]
item = array[1,2,3]
If a multi-dimensional array grows beyond its hint size, the new entries are not automatically set to roArray.
Equals Operator
The = operator is used for both assignment and comparison:
a = 5
If a = 5 then print "a is 5"
Unlike the C language, BrightScript does not support use of the = assignment operator inside an expression. This is meant to eliminate a
common class of bugs caused by confusion between assignment and comparison.
When assignment occurs, intrinsic types are copied, while BrightScript objects are reference counted.
Objects and Interfaces
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
BrightScript Objects
Wrapper Objects
Interfaces
Statement and Interface Integration
PRINT
WAIT
Expression Parsing
Array Operator
Member Access Operator
BrightScript Objects
Though BrightScript operates independently of its object architecture and library, they are both required for programming BrightScript
applications. The API of a BrightSign platform is exposed to BrightScript as a library objects: Platforms must register a new BrightScript object to
expose some part of its API.
BrightScript objects are written in C (or a compatible language such as C++), and are robust against version changes: Scripts are generally
backwards compatible with objects that have undergone revisions.
BrightScript objects keep a reference count; they delete themselves when the reference count reaches zero.
Wrapper Objects
All intrinsic BrightScript types (Boolean, Integer, Float, Double, String, and Invalid) have object equivalents. If one of these intrinsic types is
passed to a function that expects an object, the appropriate wrapper object will be created, assigned the correct value, and passed to the function
(this is sometimes referred to as "autoboxing"): This allows, for example, roArray objects to store values (e.g. integers and strings) as well as
objects.
Any expression that expects one of the above types will work with the corresponding wrapper object as well: roBoolean, roInt, roFloat, roDouble, r
oString.
The following examples illustrate how wrapper objects work:
Print 5.tostr()+"th"
Print "5".toint()+5
-5.tostr()
(-5).tostr()
'This will cause an error. Instead, use the following:
if type(5.tostr())<> "String" then stop
if (-5).tostr()<>"-5" then stop
if (1+2).tostr()<>"3" then stop
i=-55
if i.tostr()<>"-55" then stop
if 100%.tostr()<>"100" then stop
if (-100%).tostr()<>"-100" then stop
y%=10
if y%.tostr()<>"10" then stop
if "5".toint()<>5 or type("5".toint())<>"Integer" then stop
if "5".tofloat()<>5.0 or type("5".tofloat())<>"Float" then stop
fs="-1.1"
if fs.tofloat()<>-1.1 or fs.toint()<>-1 then stop
if
if
if
if
if
if
if
"01234567".left(3)<>"012" then stop
"01234567".right(4)<>"4567" then stop
"01234567".mid(3)<>"34567" then stop
"01234567".mid(3,1)<>"3" then stop
"01234567".instr("56")<>5 then stop
"01234567".instr(6,"56")<>-1 then stop
"01234567".instr(0,"0")<>0 then stop
Interfaces
Interfaces in BrightScript operate similarly to Java or Microsoft COM: An interface is a known set of member functions that implement a set of
logic. In some ways, an interface is similar to a virtual base class in C++; any script or program that is compatible with C can use an object
interface without regards to the type of object it belongs to: For example, the roSerialPort object, which controls the standard serial interface,
implements three interfaces: ifSerialControl, ifStreamReceive, and ifStreamSend. Since the print statement sends its output to any object that has
an ifStreamSend interface, it works with the roSerialPort object, as well as any other object with the ifStreamSend interface.
Statement and Interface Integration
Some BrightScript statements have integrated functionality with interfaces. This section describes how to use statements with interfaces.
PRINT
Using the PRINT statement in the following format will print into an object that has an ifStreamSend interface, including the roTextField and roSeri
alPort objects:
port = CreateObject("roSerialPort",0,115200)
print port, "string"
If the expression being printed evaluates to an object with an ifEnum interface, the PRINT statement will print every item that can be enumerated.
In addition to printing the values of intrinsic types, the PRINT statement can also be used to print any object that exposes one of the following
interfaces: ifString, ifInt, ifFloat.
WAIT
The WAIT statement can work in conjunction with any object that has an ifMessagePort interface.
Expression Parsing
Any expression that expects a certain type of variable—including Integer, Float, Double, Boolean, or String—can accept an object with an
interface equivalent of that type: ifInt, ifFloat, ifDouble, ifBoolean, ifString.
Array Operator
The [ ] array operator works with any object that has an ifArray or ifAssociativeArray interface, including arrays, associative arrays, and lists.
Member Access Operator
The member access operator (i.e. Dot Operator) works with any object that has an ifAssociativeArray interface. It also works with any object
when used to call a member function (i.e. method). It also has special meaning when used on an roXMLElement or roXMLList object.
XML Support
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
Dot Operator
Attribute Operator
Examples
Flikr code clip
BrightScript provides XML support with two BrightScript objects and a set of dedicated language features:
roXMLElement: This object provides support for parsing, generating, and containing XML.
roXMLList: This object is used to contain a list of roXMLElement instances.
Dot Operator
The "." Dot Operator has the following features when used with XML objects:
When used with an roXMLElement instance, the "." Dot Operator returns an roXMLList instance of the child tags that match the dot
operand. If no tags match the operand, an empty list is returned.
When applied to an roXMLList instance, the "." Dot Operator aggregates the results of performing the above operation on each roXMLEle
ment in the list.
When applied to XML, which is technically case sensitive, the "." Dot Operator is still case insensitive. If you wish to perform a casesensitive XML operation, use the member functions of the roXMLElement/roXMLList objects.
Attribute Operator
The “@” Attribute Operator can be used with an roXMLElement instance to return a named attribute. Though XML is case sensitive, the Attribute
Operator is always case insensitive. If the Attribute Operator is used with an roXMLList instance, it will only return a value if that list contains
exactly one element.
Examples
Given the XML in the above example.xml file, then the following code will return an roXMLList instance with three entries:
rsp=CreateObject("roXMLElement")
rsp.Parse(ReadAsciiFile("example.xml"))
? rsp.photos.photo
The following will return an roXMLElement reference to the first photo (id="3131875696"):
? rsp.photos.photo[0]
The following will return an roXMLList reference containing the tag:
? rsp.photos
The following will return the string “100”:
rsp.photos@perpage
You can use the roXMLElement.GetText() method to return an element’s text: For example, if the variable contains the element The Dawn of Man, then the following code will print the string “The Dawn of Man”.
Print booklist.book.gettext()
Alternatively, using the Attribute Operator will print the string “eng”.
print booklist.book@lang
Flikr code clip
REM
REM
REM
REM
REM
REM
REM
Interestingness
pass an (optional) page of value 1 - 5 to get 100 photos
starting at 0/100/200/300/400
returns a list of "Interestingness" photos with 100 entries
Function GetInterestingnessPhotoList(http as Object, page=1 As Integer) As Object
print "page=";page
http.SetUrl("http://api.flickr.com/services/rest/?method=flickr.interestingness.
getList&api_key=YOURKEYGOESHERE&page="+mid(stri(page),2))
xml=http.GetToString()
rsp=CreateObject("roXMLElement")
if not rsp.Parse(xml) then stop
return helperPhotoListFromXML(http, rsp.photos.photo) 'rsp.GetBody().Peek().GetBody())
End Function
Function helperPhotoListFromXML(http As Object, xmllist As Object, owner=invalid As dynamic)
As Object
photolist=CreateObject("roList")
for each photo in xmllist
photolist.Push(newPhotoFromXML(http, photo, owner))
end for
return photolist
End Function
REM
REM newPhotoFromXML
REM
REM
Takes an roXMLElement Object that is an ...
REM
Returns an brs object of type Photo
REM
photo.GetTitle()
REM
photo.GetID()
REM
photo.GetURL()
REM
photo.GetOwner()
REM
Function newPhotoFromXML(http As Object, xml As Object, owner As dynamic) As Object
photo = CreateObject("roAssociativeArray")
photo.http=http
photo.xml=xml
photo.owner=owner
photo.GetTitle=function():return m.xml@title:end function
photo.GetID=function():return m.xml@id:end function
photo.GetOwner=pGetOwner
photo.GetURL=pGetURL
return photo
End Function
Function pGetOwner() As String
if m.owner<>invalid return m.owner
return m.xml@owner
End Function
Function pGetURL() As String
a=m.xml.GetAttributes()
url="http://farm"+a.farm+".static.flickr.com/"+a.server+"/"+a.id+"_"+a.secret+".jpg"
return url
End Function
Garbage Collection
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript automatically frees strings when they are no longer used, and it will free objects when their reference count goes to zero. This is
carried out at the time the object or string is no longer used; there is no background garbage collection task. The result is a predictable garbagecollection process, with no unexpected stalls in execution.
Objects may enter a state of circular reference counting: Objects that reference each other will never reach a reference count of zero and will
need to be freed manually using the RunGarbageCollector() method. This method is useful when destroying old presentation data structures
and creating a new presentation.
Events
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
Events in BrightScript center around an event loop and the roMessagePort object. Most BrightScript objects can post to a message port in the
form of an event object: For example, the roTimer object posts events of the type roTimerEvent when configured intervals are reached.
The following script sets the destination message port using the SetPort() method, waits for an event in the form of an roGpioButton object,
and then processes the event.
print "BrightSign Button-LED Test Running"
p =
CreateObject("roMessagePort")
gpio = CreateObject("roGpioControlPort")
gpio.SetPort(p)
while true
msg=wait(0, p)
if type(msg)="roGpioButton" then
butn = msg.GetInt()
if butn <=5 then
gpio.SetOutputState(butn+17,1)
print "Button Pressed: ";butn
sleep(500)
gpio.SetOutputState(butn+17,0)
end if
end if
REM ignore buttons pressed while flashing led above
while p.GetMessage()<>invalid
end while
end while
Note that lines 6-7 can be replaced using the following (and substituting end while with end for):
For each msg in p
Threading Model
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript runs in a single thread. In general, BrightScript object calls are synchronous if they return quickly, and asynchronous if they take a
substantial amount of time to complete. For example, methods belonging to the roArray object are all synchronous, while the Play() method
that is part of the roVideoPlayer object will return immediately (it is asynchronous). As a video plays, the roVideoPlayer object will post messages
to the message port, indicating such events as “media playback finished” or “frame x reached”.
The object implementer decides whether a BrightScript object should launch a background thread to perform a synchronous operation.
Sometimes, an object will feature synchronous and asynchronous versions of the same method.
This threading model ensures that the script writer does not have to deal with mutexes and other synchronization objects. The script is always
single threaded, and the message port is polled or waited on to receive events into the thread. On the other hand, those implementing
BrightScript objects have to consider threading issues: For example, the roList and roMessagePort objects are thread-safe internally, allowing
them to be used by multiple threads.
Scope
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript uses the following scoping rules:
Global variables are not supported; however, there is a single hard-coded global variable (“global”) that is an interface to the global
BrightScript object, which contains all global library functions.
Functions declared with the Function statement are global in scope; however, if the function is anonymous, it will still be local in scope.
Local variables exist within the function scope. If a function calls another function, that new function has its own scope.
Labels exist within the function scope.
Block statements such as For / End For and While / End While do not create a separate scope.
Intrinsic Objects
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
In general, this manual uses the term “object” to refer to “BrightScript components”, which are C or C++ components with interfaces and member
functions that BrightScript uses directly. With the exception of some core objects (roArray, roAssociativeArray, roInt, roMessagePort, etc.),
BrightScript objects are platform specific.
You can create intrinsic objects in BrightScript, but these objects are not BrightScript components. There is currently no way to create a
BrightScript component in BrightScript or to create intrinsic objects that have interfaces (intrinsic objects can only contain member functions,
properties, and other objects).
A BrightScript object is simply an roAssociativeArray: When a member function is called from an associative array, a “this” pointer is set to “m”,
and “m” is accessible inside the Function code to access object keys. A “constructor” in BrightScript is simply a normal function at a global scope
that creates an roAssociativeArray instance and fills in its member functions and properties
See the “snake” game in the appendix for examples of creating intrinsic objects.
Program Statements
ON THIS PAGE
Statement Syntax
LIBRARY
DIM
Assignment ("=")
END
STOP
GOTO
RETURN
PRINT
[@location]
TAB (expression)
POS(x)
FOR / END FOR
FOR EACH IN / END FOR
WHILE / EXIT WHILE
IF / THEN / ELSE
Block IF / ELSEIF / THEN / ENDIF
Function() As Type / End Function
"M" Identifier
Anonymous Functions
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript supports the following statement types (note that BrightScript is not case sensitive). The syntax of each statement is documented in
more detail later in this chapter.
Library
Dim
= (assignment)
End
Stop
Goto
Rem (or ')
print
For / To / End For / Step / Exit For
For Each / In / End For / Exit For
While / End While / Exit While
Function / End Function / As / Return
Example
Function Main() As Void
dim cavemen[10]
cavemen.push("fred")
cavemen.push("barney")
cavemen.push("wilma")
cavemen.push("betty")
for each caveman in cavemen
print caveman
end for
End Function
Statement Syntax
Each line may contain a single statement. However, a colon (:) may be used to separate multiple statements on a single line.
Example
myname = "fred"
if myname="fred" then yourname = "barney":print yourname
LIBRARY
LIBRARY Filename.brs
The LIBRARY statement allows you to include your own BrightScript libraries (.brs files), which can then be utilized by your script. The LIBRARY
statement(s) must occur at the beginning of a script, before any other statements, functions, operators, etc.
The system locates a library by searching the directory containing the current script, as well as the SYS:/script-lib/ directory. Note that the R
un() function does not currently change the path of a LIBRARY statement to that of the called script (i.e. the system will continue searching the
directory of the caller script). On the other hand, running a script directly from the BrightSign shell does modify the library search path to that of
the called script.
The first statement will include a library in the same folder as the script, while the second will include a library in a sub-folder.
LIBRARY "myBSL1.brs"
LIBRARY "new_lib/myBSL2.brs"
The following statement will include the bslCore.brs library, which has some useful BrightScript features, from the SYS:/script-lib/ directory.
LIBRARY "v30/bslCore.brs"
DIM
DIM Name (dim1, dim2, …, dimK)
The DIM (“dimension”) statement provides a shortcut for creating roArray objects. It sets the variable Name to type “roArray”. It can create arrays
of arrays as needed for multi-dimensionality. The dimension passed to DIM is the index of the maximum entry to be allocated (i.e. the array initial
size = dimension+1), though the array will be resized larger automatically if needed.
The following two lines create identical arrays.
Dim array[5]
array = CreateObject("roArray", 6, true)
Note
The expression x[a,b] is equivalent to x[a][b].
The following script demonstrates useful operations on a DIM array.
Dim c[5, 4, 6]
For x = 1 To 5
For y = 1 To 4
For z = 1 To 6
c[x, y, z] = k
k = k + 1
End for
End for
End for
k=0
For x = 1 To 5
For y = 1 To 4
For z = 1 To 6
If c[x, y, z] <> k Then print"error" : Stop
k = k + 1
End for
End for
End for
Assignment ("=")
variable = expression
The assignment statement (“=”) assigns a variable to a new value.
In each of the following lines, the variable on the left side of the equals operator is assigned the value of the constant or expression on the right
side of the equals operator.
a$="a rose is a rose"
b1=1.23
x=2.23
x=x-b1
END
The END statement terminates script execution normally.
STOP
The STOP statement interrupts script execution, returns a “STOP” error, and invokes the debugger. Use the cont command at the debugger
prompt to continue execution of the script or the step command to execute a single step in the script.
GOTO
GOTO label
The GOTO statement transfers program control to the line number specified by label. The GOTO label statement results in a branching
operation. A label is an identifier terminated with a colon on a line that contains no other statements or expressions.
Example
mylabel:
print "Hello World"
goto mylabel
RETURN
RETURN expression
The RETURN statement returns from a function back to its caller. If the function is not type Void, RETURN can also return a value to the caller.
PRINT
PRINT [#output_object], [@location], item list
The PRINT statement prints an item or list of items in the console. The item(s) may be strings, integers, floats, variables, or expressions. An
object with an ifInt, ifFloat, or ifString interface may also be printed. If the output_object is specified, this statement will print to an object with
an ifStreamSend interface.
If the statement is printing a list of items, the items must be separated with semicolons or commas. If semicolons are used, spaces are not
inserted between printed items; if commas are used, the cursor will automatically advance to the next print zone before printing the next item.
Positive numbers and zero are printed with a leading space (without a plus sign). Spaces are not inserted before or after strings.
Example
x = 5 : print 25; " is equal to"; x ^2
' prints "25 is equal to 25"
Example
a$ = "string"
print a$;a$,a$;" ";a$
'prints "stringstring
string string"
Each print zone in the following example is 16 characters wide. The cursor moves to the next print zone each time a comma is encountered.
> print "zone 1","zone 2","zone 3","zone 4"
'prints "zone 1
zone 2
zone 3
zone 4"
Example
print "print statement #1 ";
print "print statement #2"
'prints "print statement #1 print statement #2"
In some cases, semicolons can be dropped. For example, the following statement is legal:
Print "this is a five "5"!!"
A trailing semicolon overrides the cursor-return so that the next PRINT statement begins where the last left off. If no trailing punctuation is used
with a PRINT statement, the cursor drops to the beginning of the next line.
[@location]
If the console you are printing to has the ifTextField interface, you can use the @ character to specify where printing will begin.
Example
print #m.text_field,@width*(height/2-1)+(width-len(msg$))/2,msg$;
Whenever you use PRINT @ on the bottom line of the display, an automatic line-feed causes all displayed lines to move up one line. To prevent
this from happening, use a trailing semicolon at the end of the statement.
TAB (expression)
This statement moves the cursor to the specified position on the current line (modulo the width of the console if the TAB position is greater than
the console width).
Example
print tab(5)"tabbed 5";tab(25)"tabbed 25"
Note the following about the TAB statement:
The TAB statement may be used several times in a PRINT list.
No punctuation is required after a TAB statement.
Numerical expressions may be used to specify a TAB position.
The TAB statement cannot be used to move the cursor to the left.
If the cursor is beyond the specified position, the TAB statement is ignored.
POS(x)
This statement returns an integer that indicates the current cursor position from 0 to the maximum width of the window. This statement requires a
dummy argument in the form of any numeric expression.
print tab(40) pos(0)
'prints 40 at position 40
print "these" tab(pos(0)+5)"words" tab(pos(0)+5)"are";
print tab(pos(0)+5)"evenly" tab(pos(0)+5)"spaced"
FOR / END FOR
FOR counter_variable = initial_value TO final_value STEP increment / END FOR
The FOR statement creates an iterative loop that allows a sequence of program statements to be executed a specified number of times.
The initial_value, final_value, and increment can be any expression. The first time the FOR statement is executed, these three
variables are evaluated and their values are saved; changing the variables during the loop will have no affect on the operation of the loop.
However, the counter_variable must not be changed, or the loop will not operate normally. The first time the FOR statement is executed, the
counter is set to both the value and type of the initial_value.
At the beginning of each loop, the value of the counter_variable is compared with the final_value. If the value of the counter_variable
is greater than the final_value, the loop will complete and execution will continue with the statement following the END FOR statement. If, on
the other hand, the counter has not yet exceeded the final_value, control passes to the first statement after the FOR statement. If increment is
a negative number, the loop will complete when the value of the counter_variable is less than the final_value.
When program flow reaches the END FOR statement, the counter is incremented by the specified increment amount (or decremented if increment
is a negative value). If the STEP [increment] language is not included in the FOR statement, the increment defaults to 1.
Use EXIT FOR to exit a FOR block prematurely.
The following script decrements i at the beginning of each loop until it is less than 1.
for i=10 to 1 step -1
print i
end for
FOR EACH IN / END FOR
FOR EACH item IN object / END FOR
The FOR EACH statement can iterate through a set of items in any object that has an ifEnum interface (i.e. an enumerator). The FOR block is
terminated with the END FOR statement. Objects that are ordered intrinsically (such as roList) are enumerated in order, while objects that have no
intrinsic order (such as roAssociativeArray) are enumerated in apparent random order. It is possible to delete entries as they are enumerated.
Use EXIT FOR to exit a FOR block prematurely.
The following objects can be enumerated: roList, roArray, roAssociativeArray, roMessagePort.
The following script iterates over an associative array in random order, prints each key/value pair, then deletes it.
aa={joe: 10, fred: 11, sue:9}
For each n in aa
Print n;aa[n]
aa.delete[n]
end for
WHILE / EXIT WHILE
WHILE expression / EXIT WHILE
A WHILE loop executes until the specified expression is false. Use the EXIT WHILE statement to exit a WHILE block prematurely.
k=0
while k<>0
k=1
Print "loop once"
end while
while true
Print "loop once"
Exit while
End while
IF / THEN / ELSE
IF expression THEN statements [ELSE statements]
This is the single-line form of the IF THEN ELSE statement; see the next section for more details about the block form of the IF THEN
ELSE statement.
The IF statement instructs the interpreter to test the following expression. If the expression is True, control will proceed to the statements
immediately following the expression. If the expression is False, control will jump to either the matching ELSE statement (if there is one) or to the
next program line after the block.
Example
if x>127 then print "out of range" : end
THEN is optional in the above and similar statements. However, THEN is sometimes required to eliminate ambiguity, as in the following example
if y=m then m=o 'won't work without THEN
Block IF / ELSEIF / THEN / ENDIF
The block (i.e. multi-line) form of IF / THEN / ELSE has the following syntax:
If BooleanExpression [ Then ]
[ Block ]
[ ElseIfStatement+ ]
[ ElseStatement ]
End If
ElseIfStatement ::=
ElseIf BooleanExpression [ Then ]
[ Block ]
ElseStatement ::=
Else
[ Block ]
Example
vp_msg_loop:
msg=wait(tiut, p)
if type(msg)="rovideoevent" then
if debug then print "video event";msg.getint()
if lm=0 and msg.getint() = meden then
if debug then print "videofinished"
retcode=5
return
endif
else if type(msg)="rogpiobutton" then
if debug then print "button press";msg
if esc0 and msg=b0 then retcode=1:return
if esc1 and msg=b1 then retcode=2:return
if esc2 and msg=b2 then retcode=3:return
if esc3 and msg=b3 then retcode=4:return
else if type(msg)=" Invalid" then
if debug then print "timeout"
retcode=6
return
endif
goto vp_msg_loop
Function() As Type / End Function
Function name(parameter As Type, …) As Type
Each function has its own scope.
A function is declared using the Function() statement. The parentheses may contain one or more optional parameters; parameters can also
have default values and expressions.
The type of each parameter may be declared. The return type of the function may also be declared. If a parameter type or return type is not
declared, it is Dynamic by default. Intrinsic types are passed by value (and a copy is made), while objects are passed by reference. The Sub state
ment can be used instead of Function as a shortcut for creating a function with return type Void.
A parameter can be one of the following types:
Integer
Float
Double
String
Object
Dynamic
The function return can be one of the following types:
Void
Integer
Float
Double
String
Object
Dynamic
"M" Identifier
If a function is called from an associative array, then the local variable m is set to the associative array in which the function is stored. If the
function is not called from an associative array, then its m variable is set to an associative array that is global to the module and persists across
calls.
The m identifier should only be used for the purpose stated above: We do not recommend using m as a general-purpose identifier.
Example
sub main()
obj={
add: add
a: 5
b: 10
}
obj.add()
print obj.result
end sub
function add() As void
m.result=m.a+m.b
end function
Anonymous Functions
A function without a name declaration is considered anonymous.
The following is a simple anonymous function declaration:
myfunc=function (a, b)
Return a+b
end function
print myfunc(1,2)
Anonymous functions can also be used with associative-array literals:
q = {
starring : function(o, e)
str = e.GetBody()
print "Starring: " + str
toks = box(str).tokenize(",")
for each act in toks
actx = box(act).trim()
if actx <> "" then
print "Actor: [" + actx + "]"
o.Actors.Push(actx)
endif
end for
return 0
end function
}
q.starring(myobj, myxml)
Built-In Functions
ON THIS PAGE
Type()
GetGlobalAA()
Rnd()
Box()
Run()
Eval()
GetLastRunCompileError()
GetLastRunRuntimeError()
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript features a set of built-in, module-scope, intrinsic functions. A number of file I/O, string, mathematics, and system functions are also
available via the roGlobal object.
Type()
Type(a As Variable) As String
This function returns the type of the passed variable and/or object.
GetGlobalAA()
GetGlobalAA() As Object
This function fetches the global associative array for the current script.
Rnd()
Rnd(range As Integer) As Integer
Rnd(0) As Float
If passed a positive, non-zero integer, this function returns a pseudo-random integer between 1 and the argument value. The range includes the
argument value: For example, calling Rnd(55) will return a pseudo-random integer greater than 0 and less than 56.
If the argument is 0, this function returns a pseudo-random Float value between 0 and 1.
Note
The Rnd() functions utilize a pseudo-random seed number that is generated internally and not accessible to the user.
Box()
Box(type As Dynamic) As Object
This function returns an object version of the specified intrinsic type. Objects will be passed through.
Example
b = box("string")
b = box(b) ' b does not change
Run()
Run(file_name As String, [optional_arg As Dynamic, …]) As Dynamic
Run(file_names As roArray, [optional_arg As Dynamic, …]) As Dynamic
This function runs one or more scripts from the current script. You may append optional arguments, which will be passed to the Main() function
of the script(s). The called script may also return arguments to the caller script.
If a string file name is passed, the function will compile and run the corresponding file. If an array of files is passed, the function will compile each
file, link them together, and run them.
Example
Sub Main()
Run("test.brs")
BreakIfRunError(LINE_NUM)
Print Run("test2.brs", "arg 1", "arg 2")
if Run(["file1.brs","file2.brs"])<>4 then stop
BreakIfRunError(LINE_NUM)
stop
End Sub
Sub BreakIfRunError(ln)
el=GetLastRunCompileError()
if el=invalid then
el=GetLastRunRuntimeError()
if el=&hFC or el=&hE2 then return
'FC==ERR_NORMAL_END, E2=ERR_VALUE_RETURN
print "Runtime Error (line ";ln;"): ";el
stop
else
print "compile error (line ";ln;")"
for each e in el
for each i in e
print i;": ";e[i]
end for
end for
stop
end if
End Sub
Eval()
Eval(code_snippet As String) As Dynamic
This function runs the passed code snippet in the context of the current function. The function compiles the snippet, then executes the byte-code.
If the code compiles and runs successfully, it will return zero. If the code compiles successfully, but encounters a runtime error, it will return an
integer indicating the error code (using the same codes as the GetLastRunRuntimeError() function). If compilation fails, it will return an roList
object; the roList structure is identical to that of the GetLastRunCompileError() function.
The Eval() function can be useful in two cases:
When you need to dynamically generate code at runtime.
When you need to execute a statement that could result in a runtime error, but you don’t want code execution to stop.
Example
PRINT Eval("1/0") 'Returns a divide by zero error.
GetLastRunCompileError()
GetLastRunCompileError() As roList
This function returns an roList object containing compile errors (or Invalid if no errors occurred). Each roList entry is an roAssociativeArray object
containing the following keys:
ERRSTR: The compile error type (as String)
FILESPEC: The file URI of the script containing the error (as String)
ERRNO: The error number (as Integer)
LINENO: The line number where the error occurs (as Integer)
The following are possible ERRNO values:
Error Code
Description
Expanded Description
&hBF
191
ERR_NW
ENDWHILE statement occurs without
statement.
&hBE
190
ERR_MISSING_ENDWHILE
WHILE statement occurs without END
WHILE statement.
&hBC
188
ERR_MISSING_ENDIF
End of script reached without finding
an ENDIF statement.
&hBB
187
ERR_NOLN
No line number found.
&hBA
186
ERR_LNSEQ
Line number sequence error.
&hB9
185
ERR_LOADFILE
Error loading file.
&hB8
184
ERR_NOMATCH
MATCH statement does not match.
&hB7
183
ERR_UNEXPECTED_EOF
Unexpected end of string
encountered during string
compilation.
&hB6
182
ERR_FOR_NEXT_MISMATCH
Variable on NEXT does not match FOR
.
&hB5
181
ERR_NO_BLOCK_END
&hB4
180
ERR_LABELTWICE
Label defined more than once.
&hB3
179
ERR_UNTERMED_STRING
Literal string does not have end
quote.
&hB2
178
ERR_FUN_NOT_EXPECTED
&hB1
177
ERR_TOO_MANY_CONST
&hB0
176
ERR_TOO_MANY_VAR
&hAF
175
ERR_EXIT_WHILE_NOT_IN_WHILE
&hAE
174
ERR_INTERNAL_LIMIT_EXCEDED
&hAD
173
ERR_SUB_DEFINED_TWICE
&hAC
172
ERR_NOMAIN
&hAB
171
ERR_FOREACH_INDEX_TM
&hAA
170
ERR_RET_CANNOT_HAVE_VALUE
&hA9
169
ERR_RET_MUST_HAVE_VALUE
&hA8
168
ERR_FUN_MUST_HAVE_RET_TYPE
&hA7
167
ERR_INVALID_TYPE
&hA6
166
ERR_NOLONGER
&hA5
165
ERR_EXIT_FOR_NOT_IN_FOR
&hA4
164
ERR_MISSING_INITILIZER
&hA3
163
ERR_IF_TOO_LARGE
&hA2
162
ERR_RO_NOT_FOUND
&hA1
161
ERR_TOO_MANY_LABELS
&hA0
160
ERR_VAR_CANNOT_BE_SUBNAME
&h9F
159
ERR_INVALID_CONST_NAME
&h9E
158
ERR_CONST_FOLDING
Feature no longer supported.
GetLastRunRuntimeError()
GetLastRunRuntimeError() As Integer
This function returns the error code that resulted from the last Run() function.
These codes indicate a normal result:
Error Code
Description
Expanded Description
&hFF
255
ERR_OKAY
&hFC
252
ERR_NORMAL_END
Execution ended normally, but with
termination (e.g. END, shell "exit",
window closed).
&hE2
226
ERR_VALUE_RETURN
Return executed with value returned
on the stack.
&hE0
224
ERR_NO_VALUE_RETURN
Return executed without value
returned on the stack.
The following codes indicate runtime errors:
Error Code
Description
Expanded Description
&hFE
254
ERR_INTERNAL
Unexpected condition occurred.
&hFD
253
ERR_UNDEFINED_OPCD
Opcode could not be handled.
&hFB
251
ERR_UNDEFINED_OP
Expression operator could not be
handled.
&hFA
250
ERR_MISSING_PARN
&hF9
249
ERR_STACK_UNDER
No value to pop off the stack.
&hF8
248
ERR_BREAK
scriptBreak() function called.
&hF7
247
ERR_STOP
STOP statement executed.
&hF6
246
ERR_RO0
bscNewComponent failed because
object class not found.
&hF5
245
ERR_R01
BrightScript member function call
does not have right number of
parameters.
&hF4
244
ERR_RO2
BrightScript member function not
found in object or interface.
&hF3
243
ERR_RO3
BrightScript interface not a member
of the object.
&hF2
242
ERR_TOO_MANY_PARAM
Too many function parameters to
handle.
&hF1
241
ERR_WRONG_NUM_PARAM
Number of function parameters
incorrect.
&hF0
240
ERR_RVIG
Function returns a value, but is
ignored.
&hEF
239
ERR_NOTPRINTABLE
Value not printable.
&hEE
238
ERR_NOTWAITABLE
WAIT statement cannot be applied
to object because object does not
have an roMessagePort interface.
&hED
237
ERR_MUST_BE_STATIC
Interface calls from rotINTERFACE
type must be static.
&hEC
236
ERR_RO4
"." Dot Operator used on object that
does not contain legal object or
interface reference.
&hEB
235
ERR_NOTYPEOP
Operation attempted on two typeless operands.
&hE9
233
ERR_USE_OF_UNINIT_VAR
Uninitialized variable used illegally.
&hE8
232
ERR_TM2
Non-numeric index applied to array.
&hE7
231
ERR_ARRAYNOTDIMMED
&hE6
230
ERR_USE_OF_UNINIT_BRSUBREF Reference to uninitialized SUB.
&hE5
229
ERR_MUST_HAVE_RETURN
&hE4
228
ERR_INVALID_LVALUE
Left side of the expression is invalid.
&hE3
227
ERR_INVALID_NUM_ARRAY_IDX
Number of array indexes is invalid.
&hE1
225
ERR_UNICODE_NOT_SUPPORTED
&hE0
224
ERR_NOTFUNOPABLE
&hDF
223
ERR_STACK_OVERFLOW
&h20
32
ERR_CN
&h1C
28
ERR_STRINGTOLONG
&h1A
26
ERR_OS
String space has run out.
&h18
24
ERR_TM
A Type Mismatch (string /number
operation mismatch) has occurred.
&h14
20
ERR_DIV_ZERO
&h12
18
ERR_DD
Attempted to re-dimension array.
&h10
16
ERR_BS
Array subscript out of bounds.
&h0E
14
ERR_MISSING_LN
&h0C
12
ERR_OUTOFMEM
&h08
8
ERR_FC
Invalid parameter passed to function
/array (e.g. a negative matrix dim or
square root).
&h06
6
ERR_OD
Out of data (READ).
&h04
4
ERR_RG
Return without Gosub.
&h02
2
ERR_SYNTAX
&h00
0
ERR_NF
Core Library Extension
Continue (cont or c) not allowed.
Next without For.
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
There are a number of built-in functions that are not part of the BrightScript Core Library. You can use the LIBRARY statement to include this
subset of functions:
LIBRARY "v30/bslCore.brs"
bslBrightScriptErrorCodes() As roAssociativeArray
Returns an associative array of name/value pairs corresponding to BrightScript error codes and their descriptions.
bslGeneralConstraints() As roAssociativeArray
Returns an associative array of name/value pairs corresponding to system constants.
bslUniversalControlEventCodes() As roAssociativeArray
Returns an associative array of name/value pairs corresponding to the remote key code constraints.
AsciiToHex(ascii As String) As String
Returns a hex-formatted version of the passed ASCII string.
HexToAscii(hex As String) As String
Returns an ASCII-formatted version of the passed hex string.
HexToInteger(hex As String) As Integer
Returns the integer value of the passed hex string.
BrightScript Debug Console
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
If, while a script is running, a runtime error occurs or a STOP statement is encountered, the BrightSign application will enter the BrightScript debug
console. The debug console can be accessed from a terminal program using a null-modem cable connected to the serial, GPIO, or VGA port
(depending on the player model). Networked players can also be accessed via Telnet or SSH.You can access the debug console at bootup by
following these steps:
1.
2.
3.
4.
Power off the device.
Hold the SVC button and power on the device.
Wait until the brightsign> prompt appears in the terminal. You can now release the SVC button.
Enter script at the prompt. This will take you to the BrightScript debug console.
Note
The above instructions apply to Series 3 players (e.g. XTx43, XDx33, HDx23, LS423). To access the debug console on earlier player
models, power on the device and wait at least 5 seconds after the power LED (pwr) lights up. Then, use a paperclip or pen to press
and hold the SVC button on the side of the player until the brightsign> prompt appears in the terminal.
The console scope is set to the function that was running when a runtime error or STOP statement occurred. While in the console, you can type in
any BrightScript statement; it will then be compiled and executed in the current context.
In most cases, the debug console is the default device for the PRINT statement.
BrightScript Console Commands
The following console commands are currently available in the BrightScript debug console:
bt
Print a backtrace of call-function context frames.
classes
List all public classes.
cont or c
Continue script execution.
counts
List count of BrightScript Component instances.
da
Show disassembly and bytecode for this function.
down or d
Move one position down the function context chain.
exit
Exit the debug shell.
gc
Run the garbage collector and show collection statistics.
hash
Print the internal hash-table histograms.
last
Show the last line that executed.
method
List methods provided by specified class.
method .
List methods provided by the specified interface or class.
list
List the current source of the current function.
ld
Show line data (source records)
next
Show the next line to execute.
bsc
List all allocated BrightScript Component instances.
stats
Show statistics.
step or s
Step one program statement.
t
Step one statement and show each executed opcode.
up or u
Move one function up the context chain.
var
Display local variables and their types/values.
print or p or ?
Print variable value or expression.
BrightScript Versions
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript Version Matrix
January 9, 2009
SnapShot Date
HD20000 1.3 Branch
HD2000
2.0 Branch
Compact Main Line
1/7/2008
7/16/2008
1/9/2009
Defxxx, on, gosub, clear, random,
data, read, restore, err, errl, let,
clear, line numbers
X
X
Intrinsic Arrays
X
X
Compiler
X
X
AA & dot Op & m reference
X
X
Sub/Functions
X
X
ifEnum & For Each
X
X
For/Next Does Not Always Execute
At Least Once
X
X
Exit For
X
X
Invalid Type. Errors that used to be
Int Zero are now Invalid. Added
roInvalid; Invalid Autoboxing
X
Array's use roArray; Added ifArray
X
Uninit Var Usage No Longer Allowed
X
Sub can have "As" (like Function)
X
roXML Element & XML Ops dot and
@
X
Type() Change: Now matches
declaration names (eg. Integer not
roINT32)
X
Added roBoolean
X
Added dynamic Type; Type now
optional on Sub/Functions
X
And/Or Don't Eval un-needed Terms
X
Sub/Fun Default Parameter Values
(e.g. Sub (x=5 As Integer))
X
AA declaration Op { }
X
Array Declaration Op [ ]
X
Change Array Op from ( ) to []
X
Anonymous Functions
X
Added Circ. Ref. Garbage Collector
X
Add Eval(), Run(), and Box()
X
Reserved Words
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
AND
ENDSUB
LINE_NUM
RND
CREATEOBJECT
ENDWHILE
M*
STEP
DIM
EXIT
NEXT
STOP
EACH
EXITWHILE
NOT
SUB
EACH
FALSE
OBJFUN
TAB
ELSE
FOR
OR
THEN
END
FUNCTION
POS
TO
ENDFOR
GOTO
PRINT
TRUE
ENDFUNCTION
IF
REM
TYPE
ENDIF
INVALID
RETURN
WHILE
* Although M is not strictly a reserved word, it should not be used as an identifier outside of its intended purpose.
Example Script
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
The following code uses GPIO buttons 1, 2, 3, 4 for controls. It will work on any BrightSign model that has a video output and a GPIO port.
REM
REM The game of Snake
REM demonstrates BrightScript programming concepts
REM June 22, 2008
REM
REM Every BrightScript program must have a single Main()
REM
Sub Main()
game_board=newGameBoard()
While true
game_board.SetSnake(newSnake(game_board.StartX(), game_board.StartY()))
game_board.Draw()
game_board.EventLoop()
if game_board.GameOver() then ExitWhile
End While
End Sub
REM
REM
REM
REM
REM
REM
REM
*******************************************************
*******************************************************
***************
*********************
*************** GAME BOARD OBJECT *********************
***************
*********************
*******************************************************
*******************************************************
REM
REM An example BrightScript constructor.
scope
REM BrightScript Objects are "dynamic" and
REM The object container is a BrightScript
REM The AA is used to hold member data and
REM
"newGameBoard()" is regular Function of module
created at runtime. They have no "class".
Component of type roAssocitiveArray (AA).
member functions.
Function newGameBoard() As Object
game_board=CreateObject("roAssociativeArray")
' Create a BrightScript Component of
type/class roAssociativeArray
game_board.Init=gbInit
' Add an entry to the AA of type
roFunction with value gbDraw (a sub defined in this module)
game_board.Draw=gbDraw
game_board.SetSnake=gbSetSnake
game_board.EventLoop=gbEventLoop
game_board.GameOver=gbGameOver
game_board.StartX=gbStartX
game_board.StartY=gbStartY
game_board.Init()
(which is gbInit)
' Call the Init member function
return game_board
End Function
REM
REM gbInit() is a member function of the game_board BrightScript Object.
REM When it is called, the "this" pointer "m" is set to the appropriate instance by
REM the BrightScript bytecode interpreter
REM
Function gbInit() As Void
REM
REM button presses go to this message port
REM
m.buttons = CreateObject("roMessagePort")
m.gpio = CreateObject("roGpioControlPort")
m.gpio.SetPort(m.buttons)
REM
REM determine optimal size and position for the snake gameboard
REM
CELLWID=16
' each cell on game in pixels width
CELLHI=16
' each cell in pix height
MAXWIDE=30
' max width (in cells) of game board
MAXHI=30
' max height (in cells) of game board
vidmode=CreateObject("roVideoMode")
w=cint(vidmode.GetResX()/CELLWID)
if w>MAXWIDE then w = MAXWIDE
h=cint(vidmode.GetResY()/CELLHI)
if h>MAXHI then h=MAXHI
xpix = cint((vidmode.GetResX() - w*CELLWID)/2)
ypix = cint((vidmode.GetResY() - h*CELLHI)/2)
' center game board on screen
' center game board on screen
REM
REM Create Text Field with square char cell size
REM
meta=CreateObject("roAssociativeArray")
meta.AddReplace("CharWidth",CELLWID)
meta.AddReplace("CharHeight",CELLHI)
meta.AddReplace("BackgroundColor",&H202020)
'very dark grey
meta.AddReplace("TextColor",&H00FF00)
' Green
m.text_field=CreateObject("roTextField",xpix,ypix,w,h,meta)
if type(m.text_field)<>"roTextField" then
print "unable to create roTextField 1"
stop
endif
End Function
REM
REM As Object refers to type BrightScript Component
REM m the "this" pointer
REM
Sub gbSetSnake(snake As Object)
m.snake=snake
End Sub
Function gbStartX() As Integer
return cint(m.text_field.GetWidth()/2)
End Function
Function gbStartY() As Integer
return cint(m.text_field.GetHeight()/2)
End Function
Function gbEventLoop() As Void
tick_count=0
while true
msg=wait(250, m.buttons)
' wait for a button, or 250ms (1/4 a second) timeout
if type(msg)="roGpioButton" then
if msg.GetInt()=1 m.snake.TurnNorth()
if msg.GetInt()=2 m.snake.TurnSouth()
if msg.GetInt()=3 m.snake.TurnEast()
if msg.GetInt()=4 m.snake.TurnWest()
else 'here if time out happened, move snake forward
tick_count=tick_count+1
if tick_count=6 then
tick_count=0
if m.snake.MakeLonger(m.text_field) then return
else
if m.snake.MoveForward(m.text_field) then return
endif
endif
end while
End Function
Sub gbDraw()
REM
REM given a roTextField Object in "m.text_field", draw a box around its edge
REM
solid=191
' use asc("*") if graphics not enabled
m.text_field.Cls()
for w=0 to m.text_field.GetWidth()-1
print #m.text_field,@w,chr(solid);
print #m.text_field,@m.text_field.GetWidth()*(m.text_field.GetHeight()-1)+w,chr
(solid);
end for
for h=1 to m.text_field.GetHeight()-2
print #m.text_field,@h*m.text_field.GetWidth(),chr(solid);
print #m.text_field,@h*m.text_field.GetWidth()+m.text_field.GetWidth()-1,chr(solid);
end for
m.snake.Draw(m.text_field)
End Sub
Function gbGameOver() As Boolean
msg$= " G A M E
O V E R "
msg0$="
"
width = m.text_field.GetWidth()
height = m.text_field.GetHeight()
while true
print #m.text_field,@width*(height/2-1)+(width-len(msg$))/2,msg$;
sleep(300)
print #m.text_field,@width*(height/2-1)+(width-len(msg$))/2,msg0$;
sleep(150)
REM GetMessage returns the message object, or an int 0 if no message available
If m.buttons.GetMessage() <> invalid Then Return False
endwhile
End Function
REM
REM
REM
REM
REM
REM
REM
*******************************************************
*******************************************************
******************
***********************
****************** SNAKE OBJECT ***********************
******************
***********************
*******************************************************
*******************************************************
REM
REM construct a new snake BrightScript object
REM
Function newSnake(x As Integer, y As Integer) As Object
' Create AA BrightScript Component; the container for a "BrightScript Object"
snake=CreateObject("roAssociativeArray")
snake.Draw=snkDraw
snake.TurnNorth=snkTurnNorth
snake.TurnSouth=snkTurnSouth
snake.TurnEast=snkTurnEast
snake.TurnWest=snkTurnWest
snake.MoveForward=snkMoveForward
snake.MakeLonger=snkMakeLonger
snake.AddSegment=snkAddSegment
snake.EraseEndBit=snkEraseEndBit
REM
REM a "snake" is a list of line segments
REM a line segment is an roAssociativeArray that conains a length and direction (given by
the x,y delta needed to move as it is drawn)
REM
snake.seg_list = CreateObject("roList")
snake.AddSegment(1,0,3)
REM
REM The X,Y pos is the position
REM
snake.snake_X=x
snake.snake_Y=y
snake.body=191
' use asc("*")
snake.dx=1
' default snake
snake.dy=0
' default snake
of the head of the snake
if graphics not enabled.
direction / move offset
direction / move offset
return snake
End Function
Sub snkDraw(text_field As Object)
x=m.snake_X
y=m.snake_Y
for each seg in m.seg_list
xdelta=seg.xDelta
ydelta=seg.yDelta
for j=1 to seg.Len
text_field.SetCursorPos(x, y)
text_field.SendByte(m.body)
x=x+xdelta
y=y+ydelta
end for
end for
End Sub
Sub snkEraseEndBit(text_field As Object)
x=m.snake_X
y=m.snake_Y
for each seg in m.seg_list
x=x+seg.Len*seg.xDelta
y=y+seg.Len*seg.yDelta
end for
text_field.SetCursorPos(x, y)
text_field.SendByte(32)
' 32 is ascii space, could use asc(" ")
End Sub
Function snkMoveForward(text_field As Object)As Boolean
m.EraseEndBit(text_field)
tail=m.seg_list.GetTail()
REM
REM the following shows how you can use an AA's member functions to perform the same
REM functions the BrightScript . operator does behind the scenes for you (when used on an
AA).
REM there is not point to this longer method other than illustration
REM
len=tail.Lookup("Len")
' same as len = tail.Len (or tail.len, BrightScript
syntax is not case sensative)
len = len-1
if len=0 then
m.seg_list.RemoveTail()
else
tail.AddReplace("Len",len) ' same as tail.Len=len
endif
return m.MakeLonger(text_field)
End Function
Function snkMakeLonger(text_field As Object) As Boolean
m.snake_X=m.snake_X+m.dx
m.snake_Y=m.snake_Y+m.dy
text_field.SetCursorPos(m.snake_X, m.snake_Y)
if text_field.GetValue()=m.body then return true
text_field.SendByte(m.body)
head = m.seg_list.GetHead()
head.Len=head.Len+1
return false
End Function
Sub snkAddSegment(dx As Integer, dy As Integer, len as Integer)
aa=CreateObject("roAssociativeArray")
aa.AddReplace("xDelta",-dx) ' line segments draw from head to tail
aa.AddReplace("yDelta",-dy)
aa.AddReplace("Len",len)
m.seg_list.AddHead(aa)
End Sub
Sub snkTurnNorth()
if m.dx<>0 or m.dy<>-1 then m.dx=0:m.dy=-1:m.AddSegment(m.dx, m.dy, 0)
End Sub
'north
Sub snkTurnSouth()
if m.dx<>0 or m.dy<>1 then m.dx=0:m.dy=1:m.AddSegment(m.dx, m.dy, 0)
End Sub
'south
Sub snkTurnEast()
if m.dx<>-1 or m.dy<>0 then m.dx=-1:m.dy=0:m.AddSegment(m.dx, m.dy, 0)
End Sub
'east
Sub snkTurnWest()
if m.dx<>1 or m.dy<>0 then m.dx=1:m.dy=0:m.AddSegment(m.dx, m.dy, 0)
End Sub
'west
Object Reference
ON THIS PAGE
Interfaces and Methods
Classes
Object and Class Name Syntax
Zones
Event Loops
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightSign players use a standardized library of BrightScript objects to expose functionality for software development. To publish a new API for
interacting with BrightSign hardware, we create a new BrightScript object.
The pages in this section provide definitions for objects that can be used in BrightScript. A brief description, a list of interfaces, and the member
functions of the interfaces are provided for each object class. While most BrightScript objects have self-contained pages, some objects are
grouped on the same page if they are closely related or depend on one another for functionality.
Here is a sample of objects that are used frequently when creating applications in BrightScript:
roVideoMode
Configures video output and interacts with displays using CEC/EDID.
roRectangle
Used to define zones/widgets on the screen. This object is passed
to many other objects to define their screen area, including roVideoP
layer, roImagePlayer, roImageWidget, roHtmlWidget, roClockWidget,
and roCanvasWidget.
roVideoPlayer
Plays video files, streams, and HDMI input.
roImagePlayer
Displays images.
roHtmlWidget
Displays local or remote HTML content using the Chromium
rendering engine.
roNetworkConfiguration
Used to configure Ethernet, WiFi, and local network parameters.
roDeviceInfo
Used to retrieve a wide array of system information, including model
type, device serial number, and firmware version.
Interfaces and Methods
Every BrightScript object consists of one or more "interfaces." An interface consists of one or more "methods." For example, the roVideoPlayer obj
ect has several interfaces, including ifMessagePort. The interface ifMessagePort has one method: SetPort().
The abstract interface ifMessagePort is exposed and implemented by both the roControlPort and the roVideoPlayer objects. Once the SetPort()
method is called, these objects will send their events to the supplied message port. This is discussed more in the Event Loops section below.
Example
p = CreateObject("roMessagePort")
video = CreateObject("roVideoPlayer")
gpio = CreateObject("roControlPort", "BrightSign")
gpio.SetPort(p)
video.SetPort(p)
The above syntax makes use of a shortcut provided by the language: The interface name is optional, unless it is needed to resolve name
conflicts. For example, the following two lines of code carry out the exact same function:
gpio.SetPort(p)
gpio.ifMessagePort.SetPort(p)
BrightScript Objects consist only of interfaces, and interfaces define only methods. There is no concept of a "property" or variable at the object or
interface level. These must be implemented as "set" or "get" methods in an interface.
Classes
A class name is used to create a BrightScript object. For example, the class name for a video playback instance is roVideoPlayer, so, to initialize
a video playback instance, you would use code similar to the following:
Example
video = CreateObject("roVideoPlayer")
Note that "video" can be any name that follows the syntax outlined in the next section.
Object and Class Name Syntax
Class names have the following characteristics:
Must start with an alphabetic character (a – z).
May consist of alphabetic characters, numbers, or the "_" (i.e. underscore) symbol.
Are not case sensitive.
May be of any reasonable length.
Zones
With the BrightSign Zones feature, you can divide the screen into rectangles and play different content in each rectangle.
Depending on the BrightSign model, zones can contain video, images, HTML content, audio, a clock, or text. 4Kx42, XDx32, and XDx30 models
can display two video zones on screen, while the HDx22, HDx20, and LSx22 models can only display one. There can be multiple zones of other
types on the screen. A text zone can contain simple text strings or can be configured to display an RSS feed in a ticker-type display.
As of firmware 6.0.x, zone support is enabled by default. When zones are enabled, the image layer is on top of the video layer by default. The
default behavior can be modified using theroVideoMode.SetGraphicsZOrder() method.
Zone support can be disabled by calling EnableZoneSupport(false). When zones are not enabled, the image layer is hidden whenever
video is played, and the video layer is hidden whenever images are played.
Event Loops
When writing anything more than a very simple script, an "event loop" will need to be created. Event loops typically have the following structure:
1. Wait for an event.
2. Process the event.
3. Return to step 1.
An event can be any number occurrences: a button has been pressed; a timer has been triggered; a UDP message has been received; a video
has finished playing back; etc. By convention, event scripting for BrightScript objects follows this work flow:
1. An object of the type roMessagePort is created by the script.
2. Objects that can send events (i.e. those that support the ifMessagePort/ifSetMessagePort interface) are instructed to send their events to
this message port using the SetPort() method. You can set up multiple message ports and have each event go to its own message
port, but it is usually simpler to create one message port and have all the events sent to this one port.
3. The script waits for an event using the built-in Wait() statement (or the ifMessagePort.WaitMessage() method).
4. If multiple object instances are assigned to the same message port, the script determines from which instance the event originated, then
processes it. The script then jumps back to the Wait() statement.
Example
'Listens for UDP messages on two different ports and displays the image file requested in the
UDP message body.
mp = CreateObject("roMessagePort")
udp1 = CreateObject("roDatagramReceiver", 3000)
udp1.SetPort(mp)
udp1.SetUserData("port 3000")
udp2 = CreateObject("roDatagramReceiver", 5000)
udp2.SetPort(mp)
udp2.SetUserData("port 5000")
r = CreateObject("rorectangle",0, 0, 1920, 1080)
img = CreateObject("roImagePlayer")
img.SetRectangle(r)
loop:
event = Wait(0, mp)
if type(event) = "roDatagramEvent"
print "Image play command received on " + event.GetUserData() + "."
img = DisplayFile("SD:/" + event.GetString())
endif
endif
goto loop
Global Functions
ON THIS PAGE
ifGlobal
CreateObject(name As String) As Object
RestartScript() As Void
RestartApplication() As Void
Sleep(milliseconds As Integer)
asc(letter As String) As Integer
chr(character As Integer) As String
len(target_string As String) As Integer
str(value As Double) As String
strI(value As Integer) As String
val(target_string As String) As Double
abs(x As Double) As Double
atn(x As Double) As Double
csng(x As Integer) As Float
cdbl(x As Integer) As Double
cint(x As Double) As Integer
cos(x As Double) As Double
exp(x As Double) As Double
fix(x As Double) As Integer
int(x As Double) As Integer
log(x As Double) As Double
sgn(x As Double) As Integer
sgnI(x As Integer) As Integer
sin(x As Double) As Double
tan(x As Double) As Double
sqr(x As Double) As Double
Left(target_string As String, n As Integer) As String
Right(target_string As String, n As Integer) As String
StringI(n As Integer, character As Integer) As String
String(n As Integer, character As String) As String
Mid(target_string As String, start_position As Integer, length As Integer) As String
Instr(start_position As Integer, search_text As String, substring As String) As Integer
GetInterface(object As Object, ifname As String) As Interface
Wait(timeout As Integer, port As Object) As Object
ReadAsciiFile(file_path As String) As String
WriteAsciiFile(file_path As String, buffer As String) As Boolean
ListDir(path As String) As Object
MatchFiles(path As String, pattern_in As String) As Object
LCase(target_string As String) As String
UCase(target_string As String) As String
DeleteFile(file_path As String) As Boolean
DeleteDirectory(diretory As String) As Boolean
CreateDirectory(directory As String) As Boolean
RebootSystem() As Void
ShutdownSystem() As Void
UpTime(dummy As Integer) As Double
FormatDrive(drive As String, fs_type As String) As Boolean
EjectDrive(drive As String) As Boolean
CopyFile(source As String, destination As String) As Boolean
MoveFile(source As String, destination As String) As Boolean
MapFilenameToNative(path As String) As String
strtoi(target_string As String) As Integer
rnd(a As Dynamic) As Dynamic
RunGarbageCollector() As roAssociativeArray
GetDefaultDrive() As String
SetDefaultDrive(drive As String)
EnableZoneSupport(enable As Boolean)
EnableAudioMixer(enable As Boolean)
Pi() As Double
ParseJson(json_string As String) As Object
FormatJson(json As roAssociativeArray, flags As Integer) As String
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
BrightScript provides a set of standard, module-scope functions that are stored in the global object. If a global function is referenced, the compiler
directs the runtime to call the appropriate global object member. When calling a global function, you do not need to use the dot operator to
reference the roGlobal object.
Note
Global trigonometric functions accept and return values in radians, not degrees.
ifGlobal
CreateObject(name As String) As Object
Creates a BrightScript object corresponding to the specified class name. This method returns invalid if object creation fails. Some objects have
parameters in their constructor, which must be passed after the class name in a comma-separated list.
sw = CreateObject("roGpioControlPort")
serial = CreateObject("roSerialPort", 0, 9600)
RestartScript() As Void
Exits the current script. The system then scans for a valid autorun.brs file to run.
RestartApplication() As Void
Restarts the BrightSign application.
Sleep(milliseconds As Integer)
Instructs the script to pause for a specified amount of time without wasting CPU cycles. The sleep interval is specified in milliseconds.
asc(letter As String) As Integer
Returns the ASCII code for the first character of the specified string. A null-string argument will cause an error.
chr(character As Integer) As String
Returns a one-character string containing a character reflected by the specified ASCII or control. For example, because quotation marks are
normally used as string delimiters, you can pass ASCII code 34 to this function to add quotes to a string.
len(target_string As String) As Integer
Returns the number of characters in a string.
str(value As Double) As String
Converts a specified float value to a string. This method also returns a string equal to the character representation of a value. For example, if A is
assigned a value of 58.5, then calling str(A) will return "58.5" as a string.
strI(value As Integer) As String
Converts a specified integer value to a string. This method also returns a string equal to the character representation of a value. For example, if A
is assigned a value of 58.5, then calling stri(A) will return "58" as a string.
val(target_string As String) As Double
Returns a number represented by the characters in the string argument. This is the opposite of the str() function. For example, if A is assigned
the string "58", and B is assigned the string "5", then calling val(A+"."+B) will return the float value 58.5.
abs(x As Double) As Double
Returns the absoule vale of the argument x.
atn(x As Double) As Double
Returns the arctangent (in radians) of the argument x (i.e. Atn(x) returns "the angle whose tangent is x"). To get the arctangent in degrees,
multiply Atn(x) by 57.29578.
csng(x As Integer) As Float
Returns a single-precision float representation of the argument x.
cdbl(x As Integer) As Double
Returns a double-precision float representation of the argument x.
cint(x As Double) As Integer
Returns an integer representation of the argument x by rounding to the nearest whole number.
cos(x As Double) As Double
Returns the cosine of the arugment x. The argument must be in radians. To obtain the cosine of x when x is in degrees, use Cos(x*.
01745329).
exp(x As Double) As Double
Returns the natural exponential of x. This is the inverse of the log() function.
fix(x As Double) As Integer
Returns a truncated representation of the argument x. All digits to the right of the decimal point are removed so that the resultant value is an
integer. For non-negative values of x, fix(x) is equal to int(x). For negative values of x, fix(x) is equal to int(x)+1.
int(x As Double) As Integer
Returns an integer representation of the argument x using the largest whole number that is not greater than the argument. For example, int
(2.2) returns 2, while fix(-2.5) returns -3.
log(x As Double) As Double
Returns the natural logarithm of the argument i (i.e. loge(x)). This is the inverse of the exp() function. To find the logarithm of a number to a
base b, use the following formula: logb(x) = loge(x)/loge(b).
sgn(x As Double) As Integer
Returns an integer representing how the float argument x is signed: -1 for negative, 0 for zero, and 1 for positive.
sgnI(x As Integer) As Integer
Returns an integer representing how the integer argument x is signed: -1 for negative, 0 for zero, and 1 for positive.
sin(x As Double) As Double
Returns the sine of the argument x. The argument must be in radians. To obtain the sine of x when x is in degrees, use sin(x*.01745329).
tan(x As Double) As Double
Returns the tangent of the argument x. The argument must be in radians. To obtain the tangent of x when x is in degrees, use tan(x*.
01745329).
sqr(x As Double) As Double
Returns the square root of the argument x. This function is the same as x^(1/2), but calculates the result faster.
Left(target_string As String, n As Integer) As String
Returns the first n characters of the specified string.
Right(target_string As String, n As Integer) As String
Returns the last n characters of the specified string.
StringI(n As Integer, character As Integer) As String
Returns a string composed of a character symbol repeated n times. The character symbol is passed to the method as an ASCII code integer.
String(n As Integer, character As String) As String
Returns a string composed of a character symbol repeated n times. The character symbol is passed to the method as a string.
Mid(target_string As String, start_position As Integer, length As Integer) As String
Returns a substring of the target string. The first integer passed to the method specifies the starting position of the substring, and the second
integer specifies the length of the substring. The start position of a string begins with 1.
Instr(start_position As Integer, search_text As String, substring As String) As Integer
Returns the position of a substring within a string. This function is case sensitive and returns 0 if the specified substring is not found. The start
position of a string begins with 1.
Tip
The string object also offers an Instr() method (though it uses a zero-based index). See the roString documentation for more details.
GetInterface(object As Object, ifname As String) As Interface
Returns a value of the type Interface. All objects have one or more interfaces. In most cases, you can skip interface specification when calling an
object component. This will not cause problems as long as the method names within a function are unique.
Wait(timeout As Integer, port As Object) As Object
Instructs the script to wait on an object that has an ifMessagePort interface. This method will return the event object that was posted to the
message port. If the timeout is specified as zero, Wait() will wait indefinitely; otherwise, Wait() will return Invalid after the specified number of
milliseconds if no messages have been received.
p =
CreateObject("roMessagePort")
sw = CreateObject("roGpioControlPort")
sw.SetPort(p)
msg=wait(0, p)
print type(msg)
' should be roGpioButton
print msg.GetInt() ' button number
ReadAsciiFile(file_path As String) As String
Reads the specified text file and returns it as a string.
WriteAsciiFile(file_path As String, buffer As String) As Boolean
Creates a text file at the specified file path. The text of the file is passed as the second parameter. This method cannot be used to edit files: A
preexisting text file will be overwritten if it has the same name and directory path as the one being created.
Note
The roCreateFile object provides more flexibility if you need to create or edit files.
ListDir(path As String) As Object
Returns an roList object containing the contents of the specified directory path. File names are converted to all lowercase.
MatchFiles(path As String, pattern_in As String) As Object
Takes a directory to look in (it can be as simple as "." or "/") and a pattern to be matched and then returns an roList containing the results. Each
listed result contains only the part of the filename that is matched against the pattern, not the full path. The match is only applied in the specified
directory; you will get no results if the pattern contains a directory separator. The pattern is a case insensitive wildcard expression. It may contain
the following special characters:
? – Matches any single character.
* – Matches zero or more arbitrary characters.
[…] – Matches any single character specified within the brackets. The closing bracket is treated as a member of the character class if it
immediately follows the opening bracket (i.e. "[]]" matches a single closed bracket). Within this class, "-" can be used to specify a range
unless it is the first or last character (e.g. "[A-Cf-h"] is equivalent to "[ABCfgh]"). A character class may be negated by specifying "^" as
the first character. To match a literal of this character, place it elsewhere in the class.
Note
The special characters "?", "*", and "[" lose their function if preceded by a single "\", and a single "\" can be matched using "\\".
LCase(target_string As String) As String
Converts the specified string to all lowercase.
UCase(target_string As String) As String
Converts the specified string to all uppercase.
DeleteFile(file_path As String) As Boolean
Deletes the file at the specified file path. This method returns False if the delete operation fails or if the file does not exist.
DeleteDirectory(diretory As String) As Boolean
Deletes the specified directory. This method will recursively delete any files and directories that are necessary for removing the specified
directory. This method returns False if it fails to delete the directory, but it may still delete some of the nested files or directories.
CreateDirectory(directory As String) As Boolean
Creates the specified directory. Only one directory can be created at a time. This method returns True upon success and False upon failure.
RebootSystem() As Void
Instructs the player to perform a soft reboot.
ShutdownSystem() As Void
UpTime(dummy As Integer) As Double
Returns the uptime of the system (in seconds) since the last reboot.
FormatDrive(drive As String, fs_type As String) As Boolean
Formats the specified drive using one of the file systems listed below. This function returns True upon success and False upon failure:
vfat (DOS/Windows file system): Readable and writable by Windows, Linux, and MacOS.
ext2 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software.
ext3 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software.
ext4 (Linux file system): Writable by Linux and readable by Windows and MacOS with additional software. This is the recommended file
system for SSD devices and USB hard drives.
EjectDrive(drive As String) As Boolean
Ejects the specified drive (e.g. "SD:") and returns True if successful. If the script is currently accessing files from the specified drive, the ejection
process will fail.
CopyFile(source As String, destination As String) As Boolean
Copies the file at the specified source file-path to the specified destination directory. The function returns True if successful and False in the event
of failure.
MoveFile(source As String, destination As String) As Boolean
Moves the specified source file to the specified destination directory. The function returns True if successful and False in the event of failure.
Note
Both path names must be on the same drive.
MapFilenameToNative(path As String) As String
Converts the specified BrightScript-style path to the corresponding native path and returns it as a string (e.g. the path "SD:/mydir" will be returned
as "/storage/sd/mydir").
strtoi(target_string As String) As Integer
Converts the target string to an integer. Any non-integer characters (including decimal points and spaces), and any numbers to the right of a noninteger character, will not be part of the integer output.
rnd(a As Dynamic) As Dynamic
RunGarbageCollector() As roAssociativeArray
Destroys objects that are currently in a state of circular reference counting. BrightScript normally removes any objects that become unreferenced
as part of its automated garbage collection algorithm. However, objects that reference each other will never reach a reference count of zero, and
will need to be destroyed manually using this method.
This method is useful when destroying old presentation data structures and generating a new presentation. This method returns an associative
array outlining the results of the garbage-collection process.
GetDefaultDrive() As String
Returns the current default drive complete with a trailing slash. When running as autorun.brs, the drive containing the autorun is designated as
the current default.
SetDefaultDrive(drive As String)
Sets the current default drive, which does not need to include a trailing slash. This method does not fail; however, if the specified default drive
does not exist, it will not be possible to retrieve anything.
This method accepts the following values:
"USB1:" – The drive for USB storage devices connected to the player
"SD:" – The primary SD or microSD drive on the player.
"SD2:" – The internal microSD drive on the player (4Kx42, XDx32 models only)
"SSD:" – The internal SSD on the player (XTx43, XDx33 models only)
EnableZoneSupport(enable As Boolean)
Allows for display of multiple video, HTML, image, and text zones. As of firmware 6.0.x, zone support is enabled by default.
EnableAudioMixer(enable As Boolean)
Pi() As Double
Returns the value of pi as a double-precision floating-point number.
ParseJson(json_string As String) As Object
Parses a string formatted according to the RFC4627 standard and returns an equivalent BrightScript object, which can consist of the following:
Booleans, integers, floating point numbers, strings, roArray objects, and roAssociativeArray objects. The ParseJson() method has the
following properties:
Invalid will be returned if the string is not syntactically correct.
Any roAssociativeArray objects that are returned will be case sensitive.
An error will be returned if an roArray or roAssociativeArray is nested more than 256 levels deep.
The following script demonstrates how to use ParseJson() to process a JSON object containing the titles and URLs of a set of images.
JSON Script
{
"photos" : [
{
"title" : "View from the hotel",
"url" : "http://example.com/images/00012.jpg"
},
{
"title" : "Relaxing at the beach",
"url" : "http://example.com/images/00222.jpg"
},
{
"title" : "Flat tire",
"url" : "http://example.com/images/00314.jpg"
}
]
}
BrightScript
searchRequest = CreateObject("roUrlTransfer")
searchRequest.SetURL("http://api.example.com/services/rest/getPhotos")
response = ParseJson(searchRequest.GetToString())
For Each photo In response.photos
GetImage(photo.title, photo.url)
End For
FormatJson(json As roAssociativeArray, flags As Integer) As String
Converts an associative array to a JSON string (i.e. formatted according to the RFC4627 standard). The following are supported data types:
Boolean, Integer, Float, String, roArray, and roAssociativeArray. If the flags parameter is set to 0 or not specified, non-ASCII characters are
escaped in the output string as “\uXXXX”, where “XXXX” is the hexadecimal representation of the Unicode character value. If the flags paramete
r is set to 1, non-ASCII characters are not escaped.
If arrays or associative arrays are nested more than 256 levels deep, an error will occur. If an error occurs, an empty string will be returned.
Important
By default, using object-literal syntax (e.g. aa={relativePath:"Foo"}) to generate an associative array will convert keys to all
lower case. To preserve camel case for JSON, use the roAssociativeArray.AddReplace() method instead of object literals or call roAsso
ciativeArray.SetModeCaseSensitive() before adding entries.
BrightScript Core Objects
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This section describes objects that provide core BrightScript functionality.
roArray
roAssociativeArray
roBoolean
roByteArray
roDouble, roIntrinsicDouble
roFunction
roInt, roFloat, roString
roJRE
roList
roMessagePort
roRegex
roXMLElement
roXMLList
roArray
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
ifArray
Peek() As Dynamic
Pop() As Dynamic
Push(entry As Dynamic)
Shift() As Dynamic
Unshift(entry As Dynamic)
Delete(index As Integer) As Boolean
Count() As Integer
Clear()
Append(array As roArray)
ifEnum
Reset()
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
ifArrayGet
GetEntry(index As Integer) As Dynamic
ifArraySet
SetEntry(a As Integer, b As Dynamic)
This object stores objects in a continuous array of memory locations. Since an roArray contains BrightScript components, and there are object
wrappers for most intrinsic data types, entries can either be different types or all of the same type.
Object Creation: The roArray object is created with two parameters.
CreateObject("roArray", size As Integer, resize As Boolean)
size: The initial number of entries allocated for the array.
resize: If true, the array will be resized larger to accommodate more entries if needed. If the array is large, this process might take
some time.
The DIM statement may be used instead of the CreateObject() function to create a new array. The DIM statement can be advantageous
because it automatically creates array-of-array structures for multi-dimensional arrays.
ifArray
Peek() As Dynamic
Returns the last (highest index) array entry without removing it.
Pop() As Dynamic
Returns the last (highest index) entry and removes it from the array.
Push(entry As Dynamic)
Adds a new highest-index entry to the end of the array.
Shift() As Dynamic
Removes index zero from the array and shifts all other entries down by one unit.
Unshift(entry As Dynamic)
Adds a new index zero to the array and shifts all other entries up by one unit.
Delete(index As Integer) As Boolean
Deletes the indicated array entry and shifts all above entries down by one unit.
Count() As Integer
Returns the length of the array (i.e. the index of the highest entry in the array plus one).
Clear()
Deletes every entry in the array.
Append(array As roArray)
Appends one roArray to another. If the passed roArray contains entries that were never set to a value, they are not appended.
Note
The two appended objects must be of the same type.
ifEnum
Reset()
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns a typed value at the current position and increments the position.
IsNext() As Boolean
Returns True if there is a next element.
IsEmpty() As Boolean
Returns True if there is not an exact statement.
ifArrayGet
GetEntry(index As Integer) As Dynamic
Returns an array entry of a given index. Entries start at zero. If the entry at the specified index has not been set, this method will return Invalid.
ifArraySet
SetEntry(a As Integer, b As Dynamic)
Sets an entry of a given index to the passed type value.
roAssociativeArray
ON THIS PAGE
ifEnum
Reset() As Void
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
ifAssociativeArray
AddReplace(key As String, value As Object) As Void
Lookup(key As String) As Dynamic
DoesExist(key As String) As Boolean
Delete(key As String) As Boolean
Clear() As Void
SetModeCaseSensitive() As Void
LookupCi(key As String) As Dynamic
Append(aa As roAssociativeArray) As Void
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object allows you to store objects in an associative array (also known as a map, dictionary, or hash table), a data structure that associates
objects with string keys.
The roAssociativeArray object is created with no parameters:
CreateObject("roAssociativeArray")
Alternatively, an associative array can be created using brackets:
Example
aa1 = {}
aa2 = {key1:"value", key2: 55, key3: 5+3 }
ifEnum
Reset() As Void
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns a typed value at the current position and increments the position.
IsNext() As Boolean
Returns true if there is a next element.
IsEmpty() As Boolean
Returns true if the associative array contains no elements.
ifAssociativeArray
AddReplace(key As String, value As Object) As Void
Adds a new entry to the associative array, associating the supplied object with the supplied key string. Only one object may be associated with a
key, so any existing object linked to that key is discarded. This method is always case-sensitive when creating keys, whereas object-literal syntax
(e.g. aa={bright:"Sign"}) is case-insensitive when creating keys unless SetModeCaseSensitive() is called.
Lookup(key As String) As Dynamic
Looks up the specified key and returns the associated object. If there is no object associated with the key string, then this method will return
Invalid.
Tip
In many cases, the Dot Operator can be used as shorthand for the Lookup() and AddReplace() methods when working with
associative arrays.
DoesExist(key As String) As Boolean
Looks up the specified key in the associative array. If the key exists, true is returned; otherwise, false is returned.
Delete(key As String) As Boolean
Looks for an object in the associative array linked to the specified key. If there is such an object, it is deleted and true is returned; otherwise, fal
se is returned.
Clear() As Void
Removes all objects from the associative array.
SetModeCaseSensitive() As Void
Makes all subsequent actions case sensitive. All lookups and created keys (with the exception of the AddReplace() method) are case
insensitive by default.
LookupCi(key As String) As Dynamic
Looks for an object in the array associated with the specified key. This method functions similarly to Lookup(), with the exception that key
comparisons are always case insensitive, regardless of case mode.
Append(aa As roAssociativeArray) As Void
Appends a second associative array to the first.
Example
aa = CreateObject("roAssociativeArray")
aa.AddReplace("Bright", "Sign")
aa.AddReplace("TMOL", 42)
print aa.Lookup("tmol")
print aa.Lookup("bright")
The above script returns the following:
42
Sign
Alternatively, you can use the Dot Operator in place of the AddReplace() and Lookup() methods:
Example
aa = {}
aa.bright = "Sign"
aa.tmol = 42
print aa.tmol
print aa.bright
You can also specify an associative array as a multiline object literal:
Example
aa = {
bright : "Sign",
tmol : 42,
pie : 3.14
}
roBoolean
ON THIS PAGE
ifBoolean
GetBoolean() As Boolean
SetBoolean(a As Boolean)
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This is the object equivalent of the Boolean intrinsic type. It is useful in the following situations:
When an object is needed instead of an intrinsic value: For example, if a Boolean is added to roList, it will be automatically wrapped
in an roBoolean object by the language interpreter. When a function that expects a BrightScript component as a parameter is passed a
Boolean, BrightScript automatically creates the equivalent BrightScript component.
When an object exposes the ifBoolean interface: That object can then be used in any expression that expects an intrinsic value.
ifBoolean
GetBoolean() As Boolean
SetBoolean(a As Boolean)
roByteArray
ON THIS PAGE
ifByteArray
WriteFile(file_path As String) As Boolean
WriteFile(file_path As String, start_index As Integer, length As Integer) As Boolean
ReadFile(file_path As String) As Boolean
ReadFile(file_path As String, start_index As Integer, length As Integer) As Boolean
AppendFile(file_path As String) As Boolean
SetResize(minimum_allocation_size As Integer, autoresize As Boolean)
ToHexString() As String
FromHexString(hex_string As String)
ToBase64String() As String
FromBase64String(base_64_string As String)
ToAsciiString() As String
FromAsciiString(ascii_string As String)
GetSignedByte(index As Integer) As Integer
GetSignedLong(index As Integer) As Integer
IsLittleEndianCPU() As Boolean
ifArray
Peek() As Dynamic
Pop() As Dynamic
Push(entry As Dynamic)
Shift() As Dynamic
Unshift(entry As Dynamic)
Delete(index As Integer) As Boolean
Count() As Integer
Clear()
Append(array As roArray)
ifEnum
Reset()
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
ifArrayGet
GetEntry(index As Integer) As Dynamic
ifArraySet
SetEntry(index As Integer, entry As Dynamic)
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object contains functions for converting strings to or from a byte array, as well as to or from ASCII hex or ASCII base64.
Note
If you are converting a byte array to a string, and the byte array contains a zero, the string conversion will end at that point.
The byte array will automatically resize to become larger as needed. If you wish to disable this behavior, use the SetResize() method. If an
uninitialized index is read, Invalid is returned.
Since roByteArray supports the ifArray interface, it can be accessed with the [] array operator. The byte array is always accessed as unsigned
bytes while this interface is being used. This object also supports the ifEnum interface, and so can be used with a FOR EACH statement.
ifByteArray
WriteFile(file_path As String) As Boolean
Writes the bytes contained in the byte array to the specified file. This method returns True if successful.
WriteFile(file_path As String, start_index As Integer, length As Integer) As Boolean
Writes a subset of the bytes contained in the byte array to the specified file. This method writes length bytes, beginning at start_index of the
byte array.
ReadFile(file_path As String) As Boolean
Reads the specified file into the byte array. This operation will discard any data currently contained in the byte array.
ReadFile(file_path As String, start_index As Integer, length As Integer) As Boolean
Reads a section of the specified file into the byte array. This method reads length bytes, beginning at start_index of the file. This operation
will discard any data currently contained in the byte array.
AppendFile(file_path As String) As Boolean
Appends the contents of the byte array to the specified file.
SetResize(minimum_allocation_size As Integer, autoresize As Boolean)
Expands the size of the byte array to the minimum_allocation_size if it is less than the minimum_allocation_size. This method also
accepts a Boolean parameter that specifies whether the byte array should be resized automatically or not.
ToHexString() As String
Returns a hexadecimal string representation of the contents of the byte array. Each byte is represented as two hex digits.
FromHexString(hex_string As String)
Writes the contents of the passed hexadecimal string to the byte array. The passed string must contain an even number of hex digits. This
operation will discard any data currently contained in the byte array.
ToBase64String() As String
Returns the contents of the byte array as a base64-formatted string.
FromBase64String(base_64_string As String)
Writes the contents of a valid base64-formatted string to the byte array. This operation will discard any data currently contained in the byte array.
ToAsciiString() As String
Returns the contents of the byte array as an ASCII-formatted string.
FromAsciiString(ascii_string As String)
Writes the contents of a valid ASCII-formatted string to the byte array. This operation will discard any data currently contained in the byte array.
GetSignedByte(index As Integer) As Integer
Returns the signed byte at the specified zero-based index in the byte array. To read an unsigned byte within a byte array, use the ifArrayGet.
GetEntry() method or the [] array operator.
GetSignedLong(index As Integer) As Integer
Retrieves the integer located at the specified long-word index of the byte array. Note that this method cannot accept a byte index as its parameter.
IsLittleEndianCPU() As Boolean
Returns True if the CPU architecture is little-endian.
ifArray
Peek() As Dynamic
Returns the last (highest index) array entry without removing it.
Pop() As Dynamic
Returns the last (highest index) entry and removes it from the array.
Push(entry As Dynamic)
Adds a new highest index entry to the end of the array.
Shift() As Dynamic
Removes index zero from the array and shifts all other entries down by one unit.
Unshift(entry As Dynamic)
Adds a new index zero to the array and shifts all other entries up by one unit.
Delete(index As Integer) As Boolean
Deletes the indicated array entry and shifts all above entries down by one unit.
Count() As Integer
Returns the index of the highest entry in the array plus one (i.e. the length of the array).
Clear()
Deletes every entry in the array.
Append(array As roArray)
Appends one roArray to another. If the passed roArray contains entries that were never set to a value, they are not appended.
Note
The two appended objects must be of the same type.
ifEnum
Reset()
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns a typed value at the current position and increment position.
IsNext() As Boolean
Returns True if there is a next element.
IsEmpty() As Boolean
Returns True if there is not an exact statement.
ifArrayGet
GetEntry(index As Integer) As Dynamic
Returns an array entry of a given index. Entries start at zero. If this method attempts to fetch an entry that has not been set, it will return Invalid.
ifArraySet
SetEntry(index As Integer, entry As Dynamic)
Sets an entry of a given index to the passed type value.
roDouble, roIntrinsicDouble
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
ifDouble
GetDouble() As Double
SetDouble(a As Double)
ifDouble
GetDouble() As Double
SetDouble(a As Double)
roFunction
ON THIS PAGE
ifFunction
GetSub() As Function
SetSub(value As Function)
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ifFunction
GetSub() As Function
SetSub(value As Function)
roInt, roFloat, roString
ON THIS PAGE
ifInt
GetInt() As Integer
SetInt(value As Integer) As Void
ifIntOps
ToStr() As String
ifFloat
GetFloat() As Float
SetFloat(value As Float) As Void
ifString
GetString() As String
SetString(value As String) As Void
ifStringOps
SetString(str As String, str_len As Integer)
AppendString(str As String, str_len As Integer)
Len() As Integer
GetEntityEncode() As String
Tokenize(delim As String) As roList
Trim() As String
ToInt() As Integer
ToFloat() As Float
Left(n As Integer) As String
Right(n As Integer) As String
Mid(start_index As Integer) As String
Mid(start_index As Integer, n As Integer) As String
Instr(substring As String) As Integer
Instr(start_index As Integer, substring As String) As Integer
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
The intrinsic types Int32, Float, and String have object and interface equivalents. These are useful in the following situations:
An object is needed instead of a typed value (e.g. the roList object maintains a list of objects). When a function that expects a
BrightScript object as a parameter is passed an integer, float, or string, BrightScript automatically creates the equivalent object.
If any object exposes the ifInt, ifFloat, or ifString interfaces, that object can be used in any expression that expects a typed value. For
example, an roVideoEvent can be used as an integer with a value representing the event ID.
Integer Operations
If "o" is of type roInt, then these statements will have the following effects:
print o: Prints the value of o.GetInt()
i%=o: Assigns the integer i% the value of o.GetInt().
k=o: Presumably k is automatically typed, so it becomes another reference to the roInt o.
o=5: This is NOT the same as o.SetInt(5). Instead it releases o, changes the type of o to roINT32 (o is automatically typed), and
assigns it to 5.
ifInt
roInt contains the ifInt interface, which provides the following:
GetInt() As Integer
Returns the integer value of the object.
SetInt(value As Integer) As Void
Sets the integer value of the object.
ifIntOps
roInt also contains the ifIntOps interface, which provides the following:
ToStr() As String
Returns the integer value as a string. A space is not appended to the front for positive numbers.
ifFloat
roFloat contains the ifFloat interface, which provides the following:
GetFloat() As Float
Returns the float value of the object.
SetFloat(value As Float) As Void
Sets the float value of the object.
ifString
roString contains the ifString interface, which provides the following:
GetString() As String
Returns the string value of the object.
SetString(value As String) As Void
Sets the string value of the object.
ifStringOps
roString also contains the ifStringOps interface, which provides the following:
Note
Some global functions offer the same functionality as ifStringOps methods. The function indexes of ifStringOps methods start at zero,
while those of global functions start at one.
SetString(str As String, str_len As Integer)
Sets the string value of the object using the specified string and string-length values. This is similar to the SetSeting() method, which does not
accept a parameter for string length.
AppendString(str As String, str_len As Integer)
Appends to the string value of the object using the specified string and string-length values. This method modifies itself—this can cause
unexpected results when you pass an intrinsic string type, rather than a string object.
Example
x="string"
x.ifstringops.appendstring("ddd",3)
print x 'will print 'string'
y=box("string")
y.ifstringops.appendstring("ddd",3)
print y 'will print 'stringddd'
Len() As Integer
Returns the number of characters in a string.
GetEntityEncode() As String
Returns the string with certain characters replaced with HTML entity encoding sequences:
Character
Replaced with
" (double quote)
"
' (single quote)
'
<
<
>
>
&
&
Tokenize(delim As String) As roList
Splits a string into substrings using the specified delimiter character(s). The delim parameter can contain one or more characters to treat as
delimiters. If the string object contains multiple contiguous delimiters, they will be treated as a single delimiter. This method returns the substrings
as an roList object; the delimiters are not returned with the substrings.
Example
BrightScript> s = "one&&two"
BrightScript> print s.Tokenize("&")
one
two
Trim() As String
Returns the string with any leading and trailing whitespace characters (e.g. TAB, LF, CR, VT, FF, NO-BREAK SPACE) removed.
ToInt() As Integer
Returns the value of the string as an integer number.
ToFloat() As Float
Returns the value of the string as a floating point number.
Left(n As Integer) As String
Returns the first n characters of the string.
Right(n As Integer) As String
Returns the last n characters of the string.
Mid(start_index As Integer) As String
Returns a subset of the string that begins at the zero-based start_index and terminates at the end of the string.
Mid(start_index As Integer, n As Integer) As String
Returns a subset of the string, beginning at the zero-based start_index and consisting of n characters. If the string contains fewer than n
characters after the specified start_index, this method will return all characters after the start_index.
Instr(substring As String) As Integer
Returns the zero-based index of the first occurence of the substring in the string. If the substring does not occur in the string, this method returns
-1.
Instr(start_index As Integer, substring As String) As Integer
Returns the zero-based index of the first occurence of the substring after the specified start_index in the string. If the substring does not occur
after the specified start_index, this method returns -1.
Tip
Instr() is also offered as a global function (note that the string index of the global function starts at 1).
Example
BrightScript>
BrightScript>
BrightScript>
555
BrightScript>
555
BrightScript>
500
o=CreateObject("roInt")
o.SetInt(555)
print o
print o.GetInt()
print o-55
An integer value of 5 is converted to type roInt automatically because the AddTail() method expects a BrightScript object as its parameter:
Example
BrightScript> list=CreateObject("roList")
BrightScript> list.AddTail(5)
BrightScript> print type(list.GetTail())
Here the ListDir() method returns an roList object containing roString objects:
Example
BrightScript> l=ListDir("/")
BrightScript> for i=1 to l.Count():print l.RemoveHead():next
test_movie_3.vob
test_movie_4.vob
test_movie_1.vob
test_movie_2.vob
roJRE
This object allows you to load Java applications using the Java Runtime Environment (JRE) on the player. The JRE utilizes OpenJDK 7 and is
available on XTx43, XDx33, HDx23, LS423, and 4Kx42 models.
Object Creation
The roJRE object is instantiated with the Java package filename and an optional associative array that specifies JVM system properties and
program arguments. You can use the Type() global function to determine if the package was successfully loaded.
CreateObject("roJRE", filename As String, options As roAssociativeArray)
The associative array can contain two entries:
defines: An associative array specifying system properties.
arguments : An array specifying command-line arguments.
All property/argument values must be passed as strings. Note that associative-array keys are case insensitive (i.e. converted to all lowercase) by
default; use the roAssociativeArray.SetModeCaseSensitive() method to enable case-sensitive keys.
Example
props = {}
props.SetModeCaseSensitive()
props["SYS_PROP_1"] = "system prop 1"
props["SYS_PROP_2"] = "system prop 2"
props["java.io.tmpdir"] = "/var/tmp"
jre = CreateObject("roJRE", "app.jar", { defines: props, arguments: [ "arg 1", "arg 2" ] })
if type(jre)="roJRE" then
print "Successfully started Java runtime"
else
print "Unable to start Java runtime"
end if
roList
ON THIS PAGE
ifList
Count() As Integer
ResetIndex() As Boolean
AddTail(obj As Object) As Void
AddHead(obj As Object) As Void
RemoveIndex() As Object
GetIndex() As Object
RemoveTail() As Object
RemoveHead() As Object
GetTail() As Object
GetHead() As Object
Clear()
ifEnum
Reset()
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
ifArray
Peek() As Dynamic
Pop() As Dynamic
Push(entry As Dynamic)
Shift() As Dynamic
Unshift(entry As Dynamic)
Delete(index As Integer) As Boolean
Count() As Integer
Clear()
Append(list As roList)
ifArrayGet
GetEntry(a As Integer) As Dynamic
ifArraySet
SetEntry(a As Integer, b As Dynamic)
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object functions as a general-purpose, doubly linked list. It can be used as a container for arbitrary-length lists of BrightSign objects. The
array operator [ ] can be used to access any element in an ordered list.
ifList
Count() As Integer
Returns the number of elements in the list.
ResetIndex() As Boolean
Resets the current index or position in the list to the head element.
AddTail(obj As Object) As Void
Adds a typed value to the tail of the list.
AddHead(obj As Object) As Void
Adds a typed value to the head of the list.
RemoveIndex() As Object
Removes an entry from the list at the current index or position and increments the index or position in the list. It returns Invalid when the end of
the list is reached.
GetIndex() As Object
Retrieves an entry from the list at the current index or position and increments the index or position in the list. It returns Invalid when the end of
the list is reached.
RemoveTail() As Object
Removes the entry at the tail of the list.
RemoveHead() As Object
Removes the entry at the head of the list.
GetTail() As Object
Retrieves the entry at the tail of the list and keeps the entry in the list.
GetHead() As Object
Retrieves the entry at the head of the list and keeps the entry in the list.
Clear()
Removes all elements from the list.
ifEnum
Reset()
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns a typed value at the current position and increment position.
IsNext() As Boolean
Returns True if there is a next element.
IsEmpty() As Boolean
Returns True if there is not an exact statement.
ifArray
Peek() As Dynamic
Returns the last (highest index) list entry without removing it.
Pop() As Dynamic
Returns the last (highest index) entry and removes it from the list.
Push(entry As Dynamic)
Adds a new highest-index entry to the end of the list.
Shift() As Dynamic
Removes index zero from the list and shifts all other entries down by one unit.
Unshift(entry As Dynamic)
Adds a new index zero to the list and shifts all other entries up by one unit.
Delete(index As Integer) As Boolean
Deletes the indicated list entry and shifts all above entries down by one unit.
Count() As Integer
Returns the length of the list (i.e. the index of the highest entry in the list plus one).
Clear()
Deletes every entry in the list.
Append(list As roList)
Appends one roList to another. If the passed roList contains entries that were never set to a value, they are not appended.
Note
The two appended objects must be of the same type.
ifArrayGet
GetEntry(a As Integer) As Dynamic
Returns a list entry of a given index. Entries start at zero. If an entry that has not been set is fetched, Invalid is returned.
ifArraySet
SetEntry(a As Integer, b As Dynamic)
Sets an entry of a given index to the passed type value.
Example
list = CreateObject("roList")
list.AddTail("a")
list.AddTail("b")
list.AddTail("c")
list.AddTail("d")
list.ResetIndex()
x= list.GetIndex()
while x <> invalid
print x
x = list.GetIndex()
end while
print list[2]
roMessagePort
ON THIS PAGE
ifMessagePort
GetMessage() As Object
WaitMessage(timeout As Integer) As Object
PostMessage(msg As Object) As Void
PeekMessage() As Object
SetWatchdogTimeout(seconds As Integer) As Integer
DeferWatchdog(seconds As Integer)
DeferWatchdog()
ifEnum
Reset()
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
A message port is the destination where messages (events) are sent. See the explanation of Event Loops for more details. You do not call these
functions directly when using BrightScript. Instead, use the Wait() global function.
ifMessagePort
GetMessage() As Object
Returns the event object if available. Otherwise, Invalid is returned. In either case, this method returns immediately without waiting.
WaitMessage(timeout As Integer) As Object
Waits until an event object is available or the specified amount of milliseconds have passed. When an event object becomes available, it will be
returned. If the timeout is reached, Invalid will be returned. Passing a zero timeout value instructs this method to wait indefinitely for a message.
You can also use the Wait() global function to retrieve event objects over a specified interval. The following two statements have the same
effect:
msg = port.WaitMessage(timeout)
msg = wait(timeout, port)
PostMessage(msg As Object) As Void
PeekMessage() As Object
Returns the event object if available (or Invalid if otherwise), but does not remove the event object from the message queue; a later call to GetMe
ssage(), WaitMessage(), or PeekMessage() will return the same event object.
SetWatchdogTimeout(seconds As Integer) As Integer
Enables a watchdog timeout on the roMessagePort instance if passed a positive integer. The watchdog will crash and reboot the player if the
script does not call GetMessage() or WaitMessage() after the specified number of seconds (the timeout is blocked while the script waits on
the message port). Passing zero to this method disables the watchdog.
Some BrightScript operations (e.g. roAssetRealizer.Realize()) can take a long time to return. In these cases, it may be better to use a short
watchdog timeout in general but switch to a longer timeout before calling such operations.
The watchdog timeout only applies to its associated roMessagePort instance, so enabling the watchdog on one roMessagePort instance, then
calling WaitMessage() on another, may cause the watchdog to trigger unexpectedly. The watchdog will not trigger while waiting on the
BrightScript debugger prompt.
DeferWatchdog(seconds As Integer)
Defers the watchdog timeout set by the SetWatchdogTimeout() method. Passing an integer to this method defers the timeout for the specified
number of seconds.
DeferWatchdog()
Defers the watchdog timeout by the amount of seconds set in the SetWatchdogTimeout() method.
Note
Calls to either DeferWatchdog() method cannot cause the watchdog to trigger earlier than it already will. For example, calling Defer
Watchdog(100) followed by DeferWatchdog(10) will still cause the watchdog to trigger after 100 seconds.
ifEnum
Reset()
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns the typed value at the current position and increment position.
IsNext() As Boolean
Returns True if there is a next element.
IsEmpty() As Boolean
Returns True if there is not a next element.
roRegex
ON THIS PAGE
ifRegex
IsMatch(string As String) As Boolean
Match(string As String) As roArray
Replace(string As String, subset As String) As String
ReplaceAll(string As String, subset As String) As String
Split(string As String) As roList
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object allows the implementation of the regular-expression processing provided by the PCRE library. This object is created with a string to
represent the matching-pattern and a string to indicate flags that modify the behavior of one or more matching operations:
CreateObject("roRegex", "[a-z]+", "i")
The match string (in the example above, "[a-z]+", which matches all lowercase letters) can include most Perl compatible regular expressions
found in the PCRE documentation.
This object supports any combination of the following behavior flags (in the example above, "i", which can be modified to match both uppercase
and lowercase letters):
"i": Case-insensitive match mode.
"m": Multiline mode. The start-line ("^") and end-line ("$") constructs match immediately before or after any newline in the subject string.
They also match at the absolute beginning or end of a string.
"s": Dot-all mode, which includes a newline in the ".*" regular expression. This modifier is equivalent to "/s" in Perl.
"x": Extended mode, which ignores whitespace characters except when escaped or inside a character class. This modifier is equivalent
to "/x" in Perl.
ifRegex
IsMatch(string As String) As Boolean
Returns True if the string is consistent with the matching pattern.
Match(string As String) As roArray
Returns an roArray of matched substrings from the string. The entire match is returned in the form array[0].This will be the only entry in the
array if there are no parenthetical substrings. If the matching pattern contains parenthetical substrings, the relevant substrings will be returned as
an array of length n+1, where array[0] is the entire match and each additional entry in the array is the match for the corresponding
parenthetical expression.
Replace(string As String, subset As String) As String
Replaces the first occurrence of a matching pattern in the string with the subset and returns the result.
The subset may contain numbered back-references to parenthetical substrings.
Example
> r = CreateObject("roRegex", "(\d+)\s+(\w+)", "")
> ? r.Replace("123 abc", "word:\2 number:\1")
> word:abc number:123
ReplaceAll(string As String, subset As String) As String
Replaces the all occurrences of a matching pattern in the string with the subset and returns the result.
Example
> r = CreateObject("roRegex", "a", "i")
> ? r.ReplaceAll("Abracadabra", "x")
xbrxcxdxbrx
Split(string As String) As roList
Uses the matching pattern as a delimiter and splits the string on the delimiter boundaries. The function returns an roList of strings that were
separated by the matching pattern in the original string.
roXMLElement
ON THIS PAGE
ifXMLElement
GetBody() As Object
GetAttributes() As Object
GetName() As String
GetText() As String
GetChildElements() As Object
GetNamedElements(a As String) As Object
GetNamedElementsCi(a As String) As Object
SetBody(a As Object)
AddBodyElement() As Object
AddElement(a As String) As Object
AddElementWithBody(a As String, b As Object) As Object
AddAttribute(a As String, b As String)
SetName(a As String)
Parse(a As String) As Boolean
GenXML(a As Object) As String
Clear() As Void
GenXMLHdr(a As String) As String
IsName(a As String) As Boolean
HasAttribute(a As String) As Boolean
ParseFile(a As String) As Boolean
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object is used to contain an XML tree.
The roXMLElement object is created with no parameters:
CreateObject("roXMLElement")
The following examples illustrate how XML elements are parsed in BrightScript:
This is example text
Name = tag1
Attributes = Invalid
Body = roString containing "This is example text"
Name = tag2
Attributes = roAssociativeArray with one entry, {caveman, barney}
Body = Invalid
If the tag contains other tags, the body will be of type roXMLList.
To generate XML content, create an roXMLElement and call the SetBody() and SetName() methods to build it–then call the GenXML() metho
d to generate it.
Example
root.SetName("myroot")
root.AddAttribute("key1","value1")
root.AddAttribute("key2","value2")
ne=root.AddBodyElement()
ne.SetName("sub")
ne.SetBody("this is the sub1 text")
ne=root.AddBodyElement()
ne.SetName("subelement2")
ne.SetBody("more sub text")
ne.AddAttribute("k","v")
ne=root.AddElement("subelement3")
ne.SetBody("more sub text 3")
root.AddElementWithBody("sub","another sub (#4)")
PrintXML(root, 0)
print root.GenXML(false)
ifXMLElement
GetBody() As Object
GetAttributes() As Object
GetName() As String
GetText() As String
GetChildElements() As Object
GetNamedElements(a As String) As Object
GetNamedElementsCi(a As String) As Object
SetBody(a As Object)
Generates an roXMLList for the body if needed. The method then adds the passed item (which should be an roXMLElement tag).
AddBodyElement() As Object
AddElement(a As String) As Object
AddElementWithBody(a As String, b As Object) As Object
AddAttribute(a As String, b As String)
SetName(a As String)
Parse(a As String) As Boolean
Parses the XML content passed to it. In the event of failure, this method returns False. However, it also populates roXMLElement with whatever
text could be successfully parsed. To avoid passing along erroneous strings, it is always best to have the script check the return value of Parse()
before using them.
GenXML(a As Object) As String
Generates XML content. This method takes a single Boolean parameter, indicating whether or not the XML should have an tag at the
top.
Clear() As Void
GenXMLHdr(a As String) As String
IsName(a As String) As Boolean
HasAttribute(a As String) As Boolean
ParseFile(a As String) As Boolean
The following is an example subroutine to print out the contents of an roXMLElement tree:
PrintXML(root, 0)
Sub PrintXML(element As Object, depth As Integer)
print tab(depth*3);"Name: ";element.GetName()
if not element.GetAttributes().IsEmpty() then
print tab(depth*3);"Attributes: ";
for each a in element.GetAttributes()
print a;"=";left(element.GetAttributes()[a], 20);
if element.GetAttributes().IsNext() then print ", ";
end for
print
end if
if element.GetText()<>invalid then
print tab(depth*3);"Contains Text: ";left(element.GetText(), 40)
end if
if element.GetChildElements()<>invalid
print tab(depth*3);"Contains roXMLList:"
for each e in element.GetChildElements()
PrintXML(e, depth+1)
end for
end if
print
end sub
roXMLList
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
ON THIS PAGE
ifXMLList
Simplify() As Object
GetAttributes() As Object
GetText() As String
GetChildElements() As Object
GetNamedElements(a As String) As Object
GetNamedElementsCi(a As String) As Object
ifList
Count() As Integer
ResetIndex() As Boolean
AddTail(obj As Object) As Void
AddHead(obj As Object) As Void
RemoveIndex() As Object
GetIndex() As Object
RemoveTail() As Object
RemoveHead() As Object
GetTail() As Object
GetHead() As Object
Clear() As Void
ifEnum
Reset()
Next() As Dynamic
IsNext() As Boolean
IsEmpty() As Boolean
ifArray
Peek() As Dynamic
Pop() As Dynamic
Push(a As Dynamic)
Shift() As Dynamic
Unshift(a As Dynamic)
Delete(a As Integer) As Boolean
Count() As Integer
Clear() As Void
Append(a As Object) As Void
ifArrayGet
GetEntry(a As Integer) As Dynamic
ifArraySet
SetEntry(a As Integer, b As Dynamic) As Void
ifXMLList
Simplify() As Object
Returns an roXmlElement if the list contains exactly one element. Otherwise, it will return itself.
GetAttributes() As Object
GetText() As String
GetChildElements() As Object
GetNamedElements(a As String) As Object
Returns a new XMLList that contains all roXmlElements that match the name of the passed element. This action is the same as using the dot
operator on an roXmlList.
GetNamedElementsCi(a As String) As Object
ifList
Count() As Integer
Returns the number of elements in the list.
ResetIndex() As Boolean
Resets the current index or position in the list to the head element.
AddTail(obj As Object) As Void
Adds a typed value to the tail of the list.
AddHead(obj As Object) As Void
Adds a typed value to the head of the list.
RemoveIndex() As Object
Removes an entry from the list at the current index or position and increments the index or position in the list. It returns Invalid when the end of
the list is reached.
GetIndex() As Object
Retrieves an entry from the list at the current index or position and increments the index or position in the list. It returns Invalid when the end of
the list is reached.
RemoveTail() As Object
Removes the entry at the tail of the list.
RemoveHead() As Object
Removes the entry at the head of the list.
GetTail() As Object
Retrieves the entry at the tail of the list and keeps the entry in the list.
GetHead() As Object
Retrieves the entry at the head of the list and keeps the entry in the list.
Clear() As Void
Removes all elements from the list.
ifEnum
Reset()
Resets the position to the first element of enumeration.
Next() As Dynamic
Returns a typed value at the current position and increment position.
IsNext() As Boolean
Returns True if there is a next element.
IsEmpty() As Boolean
Returns True if there is not an exact statement.
ifArray
Peek() As Dynamic
Returns the last (highest index) array entry without removing it.
Pop() As Dynamic
Returns the last (highest index) entry and removes it from the array.
Push(a As Dynamic)
Adds a new highest index entry to the end of the array.
Shift() As Dynamic
Removes index zero from the array and shifts all other entries down by one unit.
Unshift(a As Dynamic)
Adds a new index zero to the array and shifts all other entries up by one unit.
Delete(a As Integer) As Boolean
Deletes the indicated array entry and shifts all above entries down by one unit.
Count() As Integer
Returns the index of the highest entry in the array plus one (i.e. the length of the array).
Clear() As Void
Deletes every entry in the array.
Append(a As Object) As Void
Appends one roArray to another. If the passed roArray contains entries that were never set to a value, they are not appended.
Note
The two appended objects must be of the same type.
ifArrayGet
GetEntry(a As Integer) As Dynamic
Returns an array entry of a given index. Entries start at zero. If an entry that has not been set is fetched, Invalid is returned.
ifArraySet
SetEntry(a As Integer, b As Dynamic) As Void
Sets an entry of a given index to the passed type value.
Presentation and Widget Objects
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This section describes objects that relate directly to audio/video playback on BrightSign players.
roAudioConfiguration
roAudioOutput
roAudioPlayer
roAudioPlayerMx
roAudioEventMx
roCanvasWidget
roClockWidget
roHdmiInputChanged, roHdmiOutputChanged
roHtmlWidget
roHtmlWidgetEvent
roImageBuffer
roImagePlayer
roImageWidget
roRectangle
roStreamQueue
roTextField
roTextWidget
roTextWidgetEvent
roTouchScreen
roTouchEvent, roTouchCalibrationEvent
roVideoEvent, roAudioEvent
roVideoInput
roVideoMode
roVideoPlayer
roAudioConfiguration
ON THIS PAGE
ifAudioConfiguration
ConfigureAudio(audio_routing As roAssociativeArray) As Boolean
GetConfiguration() As roAssociativeArray
GetClockStatus() As roAssociativeArray
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object allows for mixing and leveling of audio streams before they are passed to audio outputs.
Object Creation: The roAudioConfiguration object is created with no parameters.
CreateObject("roAudioConfiguration")
ifAudioConfiguration
ConfigureAudio(audio_routing As roAssociativeArray) As Boolean
Configures the audio routing. This method will fail if called when audio resources are in use (i.e. there are active roVideoPlayer or roAudioPlayer i
nstances). It returns true on success and false on failure. The passed associative array can have the following parameters:
[string] mode: Sets the audio routing mode:
"dynamic": The default mode. Mixing audio streams with differing sampling rates will cause playback to fail; differing volume
levels will not be normalized; and audio streams cannot be added to an output that currently has audio playing on it. Other
parameters in the associative array are ignored.
"prerouted": This setting was implemented in firmware 7.0. You can add and remove audio streams on an output that
currently has audio playing on it; additional audio routing behavior is determined with the autolevel, pcmonly, and srcrate
parameters.
[string] autolevel: Enables ("on") or disables ("off") volume leveling for audio outputs in the "prerouted" audio mode. When
this setting is enabled, all PCM audio streams on a particular output will play at a similar volume.
[string] pcmonly: Enables ("true") or disables ("false") compressed audio support in the "prerouted" audio mode.
[int] srcrate: Sets the sample rate to which all PCM audio streams are converted in the the "prerouted" audio mode. This value
can be either 44100 or 48000.
GetConfiguration() As roAssociativeArray
Returns audio configuration information as an associative array:
[string] mode: The audio routing mode ("dynamic" or "prerouted")
[int] decoder_count: The number of available decoders
[int] compressed_capable_count: The number of decoders that can route compressed audio
[Boolean] autolevel: A flag indicating whether the volume leveling setting is enabled
[Boolean] pcmonly: A flag indicating whether the compressed audio support setting is enabled
[int] srcrate: The sample rate to which all PCM audio streams are converted
Note
If the mode is "dynamic", the associative array will contain the mode and decoder_count parameter only.
GetClockStatus() As roAssociativeArray
Returns audio clock information about the I2C, Spdif, and Hdmi outputs.
roAudioOutput
ON THIS PAGE
ifAudioOutput
SetVolume(a As Integer) As Boolean
SetTone(treble As Integer, bass As Integer) As Boolean
SetMute(a As Boolean) As Boolean
GetOutput() As String
SetAudioDelay(delay_in_milliseconds As Integer) As Boolean
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object allows individual control of audio outputs on the player.
Object Creation: The roAudioOutput object requires a single output parameter upon creation.
CreateObject("roAudioOutput", output As String)
The output parameter can take the following strings:
“none”
“hdmi”
“usb”
“spdif”
"analog"
“analog:N” (N specifies the port enumeration, which is useful for models with multiple analog-audio ports; you can also use "analog:
1" to specify the analog output on a model with a single analog-audio port)
You can create any number of roAudioOutput objects. There can be multiple instances of this object that represent the same audio output, but in
these cases one object will override another.
ifAudioOutput
SetVolume(a As Integer) As Boolean
Sets the volume of the specified output as a percentage represented by an integer between 0 and 100.
SetTone(treble As Integer, bass As Integer) As Boolean
Sets the treble and bass of the specified output. The treble and bass integers can range from -1000 to 1000, with 0 indicating no modification to
the audio signal. Each increment represents a change of 0.01db.
SetMute(a As Boolean) As Boolean
Mutes the specified output if True. This method is set to False by default.
GetOutput() As String
Returns the string with which the roAudioOutput object was created.
SetAudioDelay(delay_in_milliseconds As Integer) As Boolean
Delays the audio for a specific audio output by lagging decoded samples before they reach that output. Delays are limited to 150ms or less.
Currently, the system software only supports positive delays; therefore, if you need to set the audio ahead of the video, you will need to use roVid
eoPlayer.SetVideoDelay() instead.
The SetVolume() and SetMute() methods work in conjunction with the volume and mute functionality offered by roAudioPlayer. The roAudioPl
ayer volume settings affect the audio decoder volume. The audio stream is then sent to the assigned outputs, which have an additional level of
volume control enabled by roAudioOutput.
The roAudioOutput object affects the absolute volume (as well as mute settings) for an audio output. If two players are streaming to the same
output, both will be affected by any settings implemented through roAudioOutput.
Note
To control which audio outputs connect to audio player outputs generated by roAudioOutput, use the SetPcmAudioOutputs()
and SetCompressedAudioOutputs() methods, which can be used for roVideoPlayer and roAudioPlayer. See the roAudioPlayer entry
for further explanation of these methods.
roAudioPlayer
ON THIS PAGE
ifMessagePort
SetPort(port As roMessagePort) As Void
ifUserData
SetUserData(user_data As Object)
GetUserData() As Object
IfIdentity
GetIdentity() As Integer
ifMediaTransport
ifAudioControl
SetPcmAudioOutputs(outputs As roArray) As Boolean
SetCompressedAudioOutputs(outputs As roArray) As Boolean
SetMultichannelAudioOutputs(array As Object) As Boolean
SetAudioOutput(audio_output As Integer) As Boolean
SetAudioMode(audio_mode As Integer) As Boolean
MapStereoOutput(mapping As Integer) As Boolean
MapDigitalOutput(mapping As Integer) As Boolean
SetVolume(volume As Dynamic) As Boolean
SetChannelVolumes(channel_mask As Integer, volume As Integer) As Boolean
SetPreferredAudio(description As String) As Boolean
SetUsbAudioPort(a As Integer) As Boolean
SetSpdifMute(a As Boolean) As Boolean
SetStereoMappingSpan(a As Integer) As Boolean
ConfigureAudioResources() As Boolean
SetAudioStream(stream_index As Integer) As Boolean
SetAudioDelay(delay_in_milliseconds As Integer) As Boolean
SetVideoDelay(delay_in_milliseconds As Integer) As Boolean
StoreEncryptionKey(a As String, b As String) As Boolean
StoreObfuscatedEncryptionKey(a As String, b As String) As Boolean
SetAudioOutputAux(audio_output As Integer) As Boolean
SetAudioModeAux(audio_mode As Integer) As Boolean
MapStereoOutputAux(mapping As Integer) As BooleanSetVolumeAux(volume As Integer) As Boolean
SetChannelVolumesAux(channel_mask As Integer, volume As Integer) As Boolean
SetAudioStreamAux(stream_index As Integer) As Boolean
Configuring Audio Outputs
Playing Multiple Audio Files Simultaneously
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
An audio player is used to play back audio files using the generic ifMediaTransport interface. If the message port is set, the object will send
events of the type roAudioEvent. All object calls are asynchronous. In other words, audio playback is handled in a different thread from the script.
The script may continue to run while audio is playing.
ifMessagePort
SetPort(port As roMessagePort) As Void
Posts messages of type roAudioEvent to the attached message port.
ifUserData
SetUserData(user_data As Object)
Sets the user data that will be returned when events are raised.
GetUserData() As Object
Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.
IfIdentity
GetIdentity() As Integer
Note
The ifIdentity interface has been deprecated. We recommend using the ifUserData interface instead.
ifMediaTransport
See roVideoPlayer for a description of ifMediaTransport methods.
ifAudioControl
SetPcmAudioOutputs(outputs As roArray) As Boolean
Specifies which audio connectors should output PCM audio. This method accepts one or more outputs in the form of an roArray of roAudioOutput
instances.
SetCompressedAudioOutputs(outputs As roArray) As Boolean
Specifies which audio connectors should output compressed audio (e.g. Dolby AC3 encoded audio). This method accepts one or more outputs in
the form of an roArray of roAudioOutput instances. When one or both of the above output methods are called, they will override the settings of the
following ifAudioControl methods: SetAudioOutput(), MapStereoOutput(), SetUsbAudioPort(), MapDigitalOutput().
SetMultichannelAudioOutputs(array As Object) As Boolean
SetAudioOutput(audio_output As Integer) As Boolean
Configures the audio output of the roAudioPlayer object. This method accepts the following values:
0: Analog audio
1: USB audio
2: Digital audio, stereo PCM
3: Digital audio, raw AC3
4: Onboard analog audio with HDMI mirroring raw AC3
SetAudioMode(audio_mode As Integer) As Boolean
Sets the audio mode of the roAudioPlayer object. This method accepts the following values:
0: AC3 Surround
1: AC3 mixed down to stereo
2: No audio
3: Left
4: Right
Note
Options 0 and 1 only apply to video files, while options 2, 3, and 4 apply to all audio sources.
MapStereoOutput(mapping As Integer) As Boolean
Determines which output to use when the output is set to the analog audio (i.e. SetAudioOutput(0)).
0: Stereo audio is mapped to onboard analog output.
1: Stereo audio is mapped to left output of the expansion module.
2: Stereo audio is mapped to middle output of the expansion module.
3: Stereo audio is mapped to right output of the expansion module.
MapDigitalOutput(mapping As Integer) As Boolean
Maps the digital audio output from the roAudioPlayer object. This method accepts the following values:
0: Onboard HDMI
1: SPDIF from expansion module
SetVolume(volume As Dynamic) As Boolean
Specifies the volume of the audio output as either a percentage or decibel amount. To use a percentage measurement, pass an integer value
between 0 and 100. To use a decibel measurement, pass an roAssociativeArray containing a single {db:} parameter. The
decibel measurement is an absolute value: passing 0 specifies no change to the audio output, and the effective range of measurements is from
approximately -80 to 20 decibels.
The volume value is clipped prior to use (i.e. SetVoume(101) will set the volume to 100 and return True). The volume is the same for all
mapped outputs and USB/SPDIF/analog.
Separate volume levels are stored for roAudioPlayer and roVideoPlayer.
SetChannelVolumes(channel_mask As Integer, volume As Integer) As Boolean
You can control the volume of individual audio channels. This volume command takes a hex channel mask, which determines the channels to
apply the volume to, and a level, which is a percentage of the full scale. The volume control works according to audio channel rather than the
output. The channel mask is a bit mask with the following bits for MP3 output:
&H01: Left
&H02: Right
&H03: Both left and right
SetPreferredAudio(description As String) As Boolean
Selects which audio track to use if there are multiple audio tracks in the stream. See the Preferred Streams section on the roVideoPlayer page
for more details.
SetUsbAudioPort(a As Integer) As Boolean
SetSpdifMute(a As Boolean) As Boolean
SetStereoMappingSpan(a As Integer) As Boolean
ConfigureAudioResources() As Boolean
SetAudioStream(stream_index As Integer) As Boolean
SetAudioDelay(delay_in_milliseconds As Integer) As Boolean
Adds a presentation time stamp (PTS) offset to the audio. This makes it possible to adjust for file multiplexing differences. Delays are limited to
150ms or less. Currently, the system software only supports positive delays; therefore, if you need to set the audio ahead of the video, you will
need to use SetVideoDelay() instead.
SetVideoDelay(delay_in_milliseconds As Integer) As Boolean
Adds a presentation time stamp (PTS) offset to the video. This makes it possible to adjust for file multiplexing differences. Delays are limited to
150ms or less.
StoreEncryptionKey(a As String, b As String) As Boolean
StoreObfuscatedEncryptionKey(a As String, b As String) As Boolean
HD2000 Only:
SetAudioOutputAux(audio_output As Integer) As Boolean
SetAudioModeAux(audio_mode As Integer) As Boolean
MapStereoOutputAux(mapping As Integer) As BooleanSetVolumeAux(volume As Integer) As Boolean
SetChannelVolumesAux(channel_mask As Integer, volume As Integer) As Boolean
SetAudioStreamAux(stream_index As Integer) As Boolean
Configuring Audio Outputs
If a audio/video file is playing or has played, you need to call Stop() before changing the audio output.
The following script shows how to use the SetPcmAudioOutputs() and SetCompressedAudioOutputs() methods in conjunction with roAu
dioOutput. The audio/video player is configured to output decoded audio to the analog output or compressed audio to the HDMI and SPDIF
outputs.
ao1=CreateObject("roAudioOutput", "Analog")
ao2=CreateObject("roAudioOutput", "HDMI")
ao3=CreateObject("roAudioOutput", "SPDIF")
a1=CreateObject("roAudioPlayer")
a1.SetPcmAudioOutputs(ao1)
ar = CreateObject("roArray", 2, true)
ar[0] = ao2
ar[1] = ao3
a1.SetCompressedAudioOutputs(ar)
Important
In most cases, rerouting audio outputs during audio/video playback will cause playback to stop. The system software will still be
responsive, so you can use commands to exit playback during or after an audio output modification.
This code sets audio output to the rightmost expansion module audio port:
video = CreateObject("roVideoPlayer")
video.SetAudioOutput(0)
video.MapStereoOutput(3)
This code sets the volume level for individual channels:
audio = CreateObject("roAudioPlayer")
audio.SetChannelVolumes(&H01, 60)
audio.SetChannelVolumes(&H02, 75)
audio.SetChannelVolumes(&H03, 65)
'left channel to 60%
'right channel to 75%
'all channels to 65%
Playing Multiple Audio Files Simultaneously
Multiple MP3 files, as well as the audio track of a video file, can be played to any combination of the following:
Analog outputs
SPDIF / HDMI
USB
Only a single file can be sent to an output at any given time. For example, two roAudioPlayers cannot simultaneously play to the SPDIF output.
The second one to attempt a PlayFile will get an error. To free an output, the audio or video stream must be stopped (using the ifMediaTransport
Stop or StopClear calls).
Note the following about multiple audio-file functionality:
The onboard analog audio output and HDMI output are clocked by the same sample-rate clock. Therefore, if different content is being
played out of each, the content must have the same sample rate.
Currently, only a single set of USB speakers is supported.
Each audio and video stream played consumes some of the finite CPU resources. The amount consumed depends on the bitrates of the
streams. Testing is the only way to determine whether a given set of audio files can be played at the same time as a video. The
maximum recommended usage is a 16Mbps video file with three simultaneous MP3 160kbps streams.
This code plays a video with audio over HDMI and an MP3 file to the onboard analog port.
video=CreateObject("roVideoPlayer")
video.SetAudioOutput(3)
video.PlayFile("video.mpg")
audio=CreateObject("roAudioPlayer")
audio.MapStereoOutput(0)
audio.PlayFile("audio.mp3")
roAudioPlayerMx
ON THIS PAGE
ifMediaTransport
PlayFile(a As Object) As Boolean
Stop() As Boolean
Play() As Boolean
Pause() As Boolean
Resume() As Boolean
SetLoopMode(a As Boolean) As Boolean
GetPlaybackStatus() As Object
ifAudioControl
MapStereoOutput(a As Integer) As Boolean
SetVolume(a As Integer) As Boolean
SetChannelVolumes(a As Integer, b As Integer) As Boolean
SetAudioOutput(a As Integer) As Boolean
SetAudioMode(a As Integer) As Boolean
SetAudioStream(a As Integer) As Boolean
SetUsbAudioPort(a As Integer) As Boolean
SetSpdifMute(a As Boolean) As Boolean
MapDigitalOutput(a As Integer) As Boolean
StoreEncryptionKey(a As String, b As String) As Boolean
StoreObfuscatedEncryptionKey(a As String, b As String) As Boolean
SetStereoMappingSpan(a As Integer) As Boolean
ConfigureAudioResources() As Boolean
SetPcmAudioOutputs(a As Object) As Boolean
SetCompressedAudioOutputs(a As Object) As Boolean
ifSetMessagePort
SetPort(a As Object)
ifUserData
SetUserData(user_data As Object)
GetUserData() As Object
ifIdentity
GetIdentity() As Integer
ifAudioControlMx
SetDecoderCount(a As Integer) As Boolean
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object allows you to mix audio files, as well as HLS audio streams. Each roAudioPlayerMx object contains two internal audio players: The
main audio playlist consists of queued audio tracks that play sequentially, while the audio overlay plays files on top of the main playlist. A fade will
not occur if it is called while an overlay is playing, but the next audio track will start playing as expected.
Tracks are queued to PlayFile with their fade parameters specified in an associative array. These are the parameters you can pass to PlayFile:
Filename: The filename of the track
FrontPorch: The length (in milliseconds) to skip from the start of the track. This value is 0 by default.
FadeOutLocation: The location (in milliseconds) of the fade out relative to the value of the FrontPorch. If the FrontPorch value is 0
(which is the default setting), and the FadeOutLength value is non-zero, then the fade out is calculated back from the end of the file.
FadeOutLength: The length of the fade out (in milliseconds). This value is 0 by default.
SegueLocation: The location (in milliseconds) of the event that triggers the next audio file to play. This location is relative to the first
audio file that is played. If the SegueLocation parameter is not included, the value defaults to the FadeOutLocation.
BackPorchLocation: The location (in milliseconds) of the termination point for the audio track. This location is relative to the first audio
file that is played. If the BackPorchLocation parameter is not included, the audio file plays to the end. The value is 0 by default, which
disables the back porch.
TrackVolume: The relative volume of of the audio track, measured as a percentage. Specify the percentage using values between 0
and 100.
EventID: The ID for an audio event.
EventTimeStamp: The timestamp for the audio event. There can only be one event per audio file.
QueueNext: The queuing of an audio track. Set the parameter value to 1 to queue an audio file to play after the current track.
Overlay: The overlay specification of an audio track. Set the parameter value to 1 to fade down the main audio playlist while playing the
audio track as an overaly. Overlays have additional parameters:
AudioBedLevel: The volume-level percentage of the main audio playlist while the overlay is playing. Specify the percentage
using values between 0 and 100.
AudioBedFadeOutLength: The fade-out length of the main audio playlist.
AudioBedFadeInLength: The fade-in lenth for the length of the underlying audio track once the segue is triggered.
FadeCurrentPlayNext: A fade command. Set the parameter value to 1 to fade out the current main audio playlist track and fade in
the designated audio file.
CrossfadeCurrentPlayNext: A crossfade command. Set the parameter value to 1 to force an immediate crossfade between the
current main audio playlist track and the designated audio file.
UserString: A string that can be set to a unique value for each roAudioPlayerMx instance. This string is returned with every event
generated by the instance. Since all current platforms can support multiple roAudioPlayerMx instances running at the same time, the
UserString allows the script to distinguish between event returns.
The following diagram illustrates how some of these timing parameters work together:
The following script illustrates a simple crossfade between audio tracks:
a = CreateObject("roAudioPlayerMx")
track1 = CreateObject("roAssociativeArray")
track1["Filename"] = "file1.mp3"
track1["FadeInLength"] = 4000
track1["FadeOutLength"] = 4000
track1["QueueNext"] = 1
track2 = CreateObject("roAssociativeArray")
track2["Filename"] = "file2.mp3"
track2["FadeInLength"] = 4000
track2["FadeOutLength"] = 4000
track2["QueueNext"] = 1
a.PlayFile(track1)
a.PlayFile(track2)
ifMediaTransport
PlayFile(a As Object) As Boolean
Stop() As Boolean
Play() As Boolean
Pause() As Boolean
Resume() As Boolean
SetLoopMode(a As Boolean) As Boolean
GetPlaybackStatus() As Object
ifAudioControl
MapStereoOutput(a As Integer) As Boolean
SetVolume(a As Integer) As Boolean
SetChannelVolumes(a As Integer, b As Integer) As Boolean
SetAudioOutput(a As Integer) As Boolean
SetAudioMode(a As Integer) As Boolean
SetAudioStream(a As Integer) As Boolean
SetUsbAudioPort(a As Integer) As Boolean
SetSpdifMute(a As Boolean) As Boolean
MapDigitalOutput(a As Integer) As Boolean
StoreEncryptionKey(a As String, b As String) As Boolean
StoreObfuscatedEncryptionKey(a As String, b As String) As Boolean
SetStereoMappingSpan(a As Integer) As Boolean
ConfigureAudioResources() As Boolean
SetPcmAudioOutputs(a As Object) As Boolean
SetCompressedAudioOutputs(a As Object) As Boolean
ifSetMessagePort
SetPort(a As Object)
ifUserData
SetUserData(user_data As Object)
Sets the user data that will be returned when events are raised.
GetUserData() As Object
Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.
ifIdentity
GetIdentity() As Integer
Note
The ifIdentity interface has been deprecated. We recommend using the ifUserData interface instead.
ifAudioControlMx
SetDecoderCount(a As Integer) As Boolean
roAudioEventMx
ON THIS PAGE
ifInt
GetInt() As Integer
SetInt(value As Integer) As Void
ifAudioUserData
SetUserData(user_data As String)
GetUserData() As String
ifSourceIdentity
GetSourceIdentity() As Integer
SetSourceIdentity() As Integer
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
The roAudioPlayerMx object can generate roAudioEventMx messages with the following values:
8 EVENT_MEDIAENDED
14 EVENT_OVERLAY_MEDIAENDED
16 EVENT_MEDIAERROR
17 EVENT_OVERLAY_MEDIAERROR
"Media ended" events are sent when a track finishes and there are no more queued tracks for the player, while "Media error" events are sent
when a queued file is not found (e.g. when it does not exist).
ifInt
GetInt() As Integer
Returns the event ID.
SetInt(value As Integer) As Void
Sets the value of the event.
ifAudioUserData
SetUserData(user_data As String)
Sets the user data.
GetUserData() As String
Returns the user data that has previously been set via SetUserData() (either on the source or event object). It will return Invalid if no data has
been set.
ifSourceIdentity
GetSourceIdentity() As Integer
SetSourceIdentity() As Integer
Note
The ifSourceIdentity interface has been deprecated. We recommend using the ifAudioUserData interface instead.
roCanvasWidget
ON THIS PAGE
ifCanvasWidget
Hide() As Boolean
Show() As Boolean
SetRectangle(r As roRectangle) As Boolean
SetLayer(content As Object, z-level As Integer) As Boolean
ClearLayer(z-level As Integer) As Boolean
Clear() As Boolean
EnableAutoRedraw(enable As Boolean) As Boolean
Object Content
Background color
Text
Image
QR Codes
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object composites background color, text, and images into a single rectangle, allowing you to layer images on a z-axis.
Object Creation: Like other widgets, roCanvasWidget is created with an roRectangle to set its size and position on the screen.
CreateObject ("roCanvasWidget", r As roRectangle) As Object
ifCanvasWidget
Hide() As Boolean
Hides the widget.
Show() As Boolean
Shows the widget.
SetRectangle(r As roRectangle) As Boolean
Changes the size and positioning of the widget rectangle using the passed roRectangle object.
SetLayer(content As Object, z-level As Integer) As Boolean
Sets the contents of a layer within the widget. The lowest z-level is drawn first, and the highest z-level is drawn last. The object content is
described below.
ClearLayer(z-level As Integer) As Boolean
Clears the specified layer.
Clear() As Boolean
Clears all of the layers.
EnableAutoRedraw(enable As Boolean) As Boolean
Enables or disables the automatic redrawing of the widget.
When this function is enabled, each call to SetLayer, ClearLayer, or Clear results in a redraw. If you need to change multiple layers, then
you should disable auto redraw while calling the SetLayer function.
SetLayer enables or disables redrawing of the widget when layer content is changed. When auto-redraw is enabled, each call to
SetLayer, ClearLayer, or Clear results in a redraw. To batch multiple updates together, you should first suspend drawing using
EnableAutoRedraw(false), then make the changes to the content, and finally re-enable drawing using EnableAutoRedraw(true). The
redraw happens in a separate thread, so EnableAutoRedraw returns almost immediately.
Object Content
The content specified in each layer can consist of one or more objects. Each object is defined by an roAssociativeArray. If there is more than one
object, then each is placed into an roArray prior to passing to the SetLayer() method. Currently, there are four object types.
Background color
color: The #[aa]rrggbb hex value of the background color
targetRect: A target rectangle, which is another roAssociativeArray consisting of x, y, w, and h values. These values are relative to the
top left corner of the widget.
Text
text: A string of text to display
targetRect: The rectangle in which the text is displayed
textAttrs: An roAssociativeArray containing attributes to be applied to the text. The attributes can be any of the following:
font: A string indicating whether the text should be displayed as "small"/"medium"/"large"/"huge"
fontSize: A point size that is used directly when creating the font. If the value is set to 0, then the font automatically resizes to
fit the targetRect.
fontfile: The filename for a non-system font to use
hAlign: A string indicating the "left"/"center"/"right" alignment of the text on a line
vAlign: A string indicating the "top"/"center"/"bottom" alignment of the text perpendicular to the line
rotation: A string indicating the "0"/'90"/"180"/"270" degree rotation of the text
color: The #[aa]rrggbb hex value of the text
Image
filename: The filename of the image
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.
Note
See the Image Decryption section in the roImagePlayer entry for details on displaying encrypted images.
targetRect: The rectangle in which the image is displayed. The image will be automatically resized to fit into the target area.
sourceRect: The source rectangle to clip from a source image
compositionMode: Enter either source or source_over. The latter alpha blends with underlying objects. The former replaces the
underlying values completely.
imgAttrs: An roAssociativeArray containing attributes to be applied to the image:
rotation: A string indicating the "0"/'90"/"180"/"270" degree rotation of the image
QR Codes
QR (quick response) codes appear as squares of black dots on a white background. They are used to encode URLs, email addresses, etc, and
they can be scanned using readily available software for smart phones. Although the codes usually appear as black on white, you can, in theory,
use any two contrasting colors.
targetRect: The rectangle in which the QR code is displayed. Regardless of the aspect ratio of this rectangle, the QR code itself will
always be squared with the background color that fills the gaps.
QrCode (simple form): Contains the string to encode into the QR code.
QrCode (complex form): Contains an array of parameters for the QR code. The parameters can be any of the following:
color: The foreground color in the QR code (the default is black)
backgroundColor: The background color in the QR code (the default is white)
rotation: A string indicating the "0"/'90"/"180"/"270" degree rotation of the code. The code will scan regardless of rotation.
qrText: Contains the text to encode into the QR code.
This code contains most of the roCanvasWidget features outlined above:
rect=CreateObject("roRectangle", 0, 0, 1920, 1080)
cw=CreateObject("roCanvasWidget", rect)
aa=CreateObject("roAssociativeArray")
aa["text"] = "Primal Scream"
aa["targetRect"] = { x: 280, y: 180, w: 500, h: 30 }
aa["textAttrs"] = { Color:"#AAAAAA", font:"Medium", HAlign:"Left", VAlign:"Top"}
aa1=CreateObject("roAssociativeArray")
aa1["text"] = "Movin' on up, followed by something else, followed by something else, followed
by something else, followed by something else"
aa1["targetRect"] = { x: 282, y: 215, w: 80, h: 500 }
aa1["textAttrs"] = { Color:"#ffffff", font:"Large", fontfile:"usb1:/GiddyupStd.otf", HAlign:"
Left", VAlign:"Top", rotation:"90"}
array=CreateObject("roArray", 10, false)
array.Push({ color: "5c5d5f" })
array.Push({ filename: "transparent-balls.png" })
array.Push(aa)
aa2=CreateObject("roAssociativeArray")
aa2["filename"] = "transparent-balls.png"
aa2["CompositionMode"] = "source_over"
aa2["targetRect"] = { x: 400, y: 200, w: 200, h: 200 }
aa3=CreateObject("roAssociativeArray")
aa3["QrCode"] = "www.brightsign.biz"
aa3["targetRect"] = { x: 100, y: 100,
w: 400, h: 400
}
aa4=CreateObject("roAssociativeArray")
aa4["QrCode"] = { qrText:"www.brightsign.biz", rotation:"90" }
aa4["targetRect"] = { x: 1200, y: 100, w: 400, h: 600 }
aa5=CreateObject("roAssociativeArray")
aa5["QrCode"] = { color:"#964969", backgroundColor:"#FFFF77", qrText:"www.brightsign.biz",
rotation:"180" }
aa5["targetRect"] = { x: 100, y: 600, w: 400, h: 400 }
cw.Show()
cw.EnableAutoRedraw(0)
cw.SetLayer(array, 0)
cw.SetLayer(aa1, 1)
cw.SetLayer(aa1, 2)
cw.SetLayer(aa3, 3)
cw.SetLayer(aa4, 4)
cw.SetLayer(aa5, 5)
cw.EnableAutoRedraw(1)
cw.ClearLayer(0)
roClockWidget
ON THIS PAGE
Control Characters
ifWidget
SetForegroundColor(color As Integer) As Boolean
SetBackgroundColor(color As Integer) As Boolean
SetFont(font_filename As String) As Boolean
SetBackgroundBitmap(bitmap_filename As String, stretch As Boolean) As Boolean
SetBackgroundBitmap(parameters As roAssociativeArray, stretch As Boolean) As Boolean
SetSafeTextRegion(region As roRectangle) As Boolean
Show() As Boolean
Hide() As Boolean
GetFailureReason() As String
SetRectangle(r As roRectangle) As Boolean
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object places a clock on the screen. It has construction arguments only.
Object Creation: The roClockWidget object is created with several parameters.
CreateObject("roClockWidget", rect As roRectangle, res As roResourceManager, display_type As
Integer)
rect: The rectangle in which the clock is displayed. The widget picks a font based on the size of the rectangle.
res: A resources.txt file that allows localization via the roResourceManager object (see below for further details).
display_type: Use 0 for date only, and 1 for clock only. To show both on the screen, you need to create two widgets.
Example
rect=CreateObject("roRectangle", 0, 0, 300, 60)
res=CreateObject("roResourceManager", "resources.txt")
c=CreateObject("roClockWidget", rect, res, 1)
c.Show()
The resource manager is passed into the widget, which uses the following resources within the resources.txt file to display the time and date
correctly. Here are the "eng" entries:
[CLOCK_DATE_FORMAT]
eng "%A, %B %e, %Y"
[CLOCK_TIME_FORMAT]
eng "%l:%M"
[CLOCK_TIME_AM]
eng "AM"
[CLOCK_TIME_PM]
eng "PM"
[CLOCK_DATE_SHORT_MONTH]
eng "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec"
[CLOCK_DATE_LONG_MONTH]
eng
"January|February|March|April|May|June|July|August|September|October|November|December"
[CLOCK_DATE_SHORT_DAY]
eng "Sun|Mon|Tue|Wed|Thu|Fri|Sat"
[CLOCK_DATE_LONG_DAY]
eng "Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday"
Control Characters
The following are the control characters for the date/time format strings:
//
//
//
//
//
//
//
//
//
//
//
//
Date format
//
//
//
//
//
//
//
//
Time format
%a
%A
%b
%B
%d
%e
%m
%n
%y
%Y
%H
%I
%k
%l
%M
%S
Abbreviated weekday name
Long weekday name
Abbreviated month name
Full month name
Day of the month as decimal 01 to 31
Like %d, the day of the month as a decimal number, but without leading zero
Month name as a decimal 01 to 12
Like %m, the month as a decimal number, but without leading zero
Two digit year
Four digit year
The hour using
The hour using
The hour using
The hour using
Minutes (00 to
Seconds (00 to
24-hour
12-hour
24-hour
12-hour
59)
59)
clock
clock
clock
clock
(00 to 23)
(01 to 12)
(0 to 23); single digits are preceded by a blank.
(1 to 12); single digits are preceded by a blank.
ifWidget
SetForegroundColor(color As Integer) As Boolean
Sets the foreground color in ARGB format. 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) to convert a
hex string to an integer.
SetBackgroundColor(color As Integer) As Boolean
Sets the background color in ARGB format. 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) to convert a
hex string to an integer.
Note
The top 8 bits of the SetForegroundColor() and SetBGackgroundColor() values 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 semitransparent black box containing text over video.
SetFont(font_filename As String) As Boolean
Sets the font_filename using a TrueType font (for example, SD:/Arial.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.
Note
See the Image Decryption 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.
Show() As Boolean
Displays the widget. After creation, the widget is hidden until Show() is called.
Hide() As Boolean
Hides the widget.
GetFailureReason() As String
Yields additional useful information if a function return indicates an error.
SetRectangle(r As roRectangle) As Boolean
Changes the size and positioning of the widget rectangle using the passed roRectangle object.
roHdmiInputChanged, roHdmiOutputChanged
ON THIS PAGE
ifInt
GetInt() As Integer
SetInt(value As Integer) As Void
ifUserData
SetUserData(user_data As Object)
GetUserData() As Object
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
The roVideoMode object generates an roHdmiInputChanged or roHdmiOutputChanged event object whenever the hotplug status of the HDMI
input or output changes.
At least one roHdmiOutputChanged event object will always be generated for a hotplug event, even for very quick disconnect/connect hotplug
events. In most cases, a disconnect/connect hotplug event will generate two event objects.
ifInt
GetInt() As Integer
Returns the event ID.
SetInt(value As Integer) As Void
Sets the value of the event.
ifUserData
SetUserData(user_data As Object)
Sets the user data that will be returned when events are raised.
GetUserData() As Object
Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.
roHtmlWidget
ON THIS PAGE
Object Creation
Initialization Parameters
[boolean] nodejs_enabled
[boolean] focus_enabled
[boolean] mouse_enabled
[boolean] scrollbar_enabled
[boolean] force_gpu_rasterization_enabled
[boolean] canvas_2d_acceleration_enabled
[boolean] javascript_enabled
[boolean] brightsign_js_objects_enabled
[string] transform
[string] user_agent
[string] url
[string] user_stylesheet
[string] hwz_default
[string] storage_path
[string or double] storage_quota
[roMessagePort] port
[roArray] fonts
[roArray] pcm_audio_outputs
[roArray] compressed_audio_outputs
[roArray] multi_channel_audio_outputs
[roAssociativeArray] inspector_server
[roAssociativeArray] security_params
[roAssociativeArray] javascript_injection
[roArray] assets
ifHtmlWidget
GetFailureReason() As String
Hide() As Boolean
Show() As Boolean
SetRectangle(r As roRectangle) As Boolean
SetURL(URL As String) As Boolean
MapFilesFromAssetPool(asset_pool As roAssetPool, asset_collection As roAssetCollection, pool_prefix As String,
uri_prefix As String) As Boolean
SetZoomLevel(scale_factor as Float) As Boolean
EnableSecurity(enable As Dynamic) As Boolean
EnableMouseEvents(enable As Boolean) As Boolean
SetPortrait(portrait_mode As Boolean) As Boolean
SetTransform(transform As String) As Boolean
SetAlpha(alpha As Integer) As Boolean
EnableScrollbars(scrollbars As Boolean) As Boolean
AddFont(filename As String) As Boolean
SetPcmAudioOutputs(outputs As roArray) As Boolean
SetCompressedAudioOutputs(outputs As roArray) As Boolean
SetMultichannelAudioOutputs(outputs As roArray) As Boolean
SetHWZDefault(default As String) As Void
SetVideoPlayerDefaults(defaults As roAssociativeArray) As Boolean
ForceGpuRasterization(enable As Boolean) As Boolean
EnableCanvas2dAcceleration(enable As Boolean) As Boolean
SetUserStylesheet(URI As String) As Boolean
SetAppCacheDir(file_path As String) As Boolean
SetAppCacheSize(maximum As Integer) As Boolean
FlushCachedResources() As Boolean
SetLocalStorageDir(file_path As String) As Boolean
SetLocalStorageQuota(maximum As Dynamic) As Boolean
SetWebDatabaseDir(file_path As String) As Boolean
SetWebDatabaseQuota(maximum As Dynamic) As Boolean
EnableJavaScript(enable As Boolean) As Boolean
AllowJavaScriptURLs(url_collection As roAssociativeArray)
PostJSMessage(data As roAssociativeArray) As Boolean
InjectJavaScript(code As String) As Boolean
StartInspectorServer(port As Integer) As Boolean
SetUserAgent(user_agent As String) As Boolean
GetUserAgent() As String
SetUserAgentSuffix(suffix As String) As Boolean
SetProxy(proxy as String) As Boolean
SetProxyBypass(hostnames As String) As Boolean
ifMessagePort
SetPort(port As roMessagePort)
ifUserData
SetUserData(user_data As Object)
GetUserData() As Object
Firmware Version 7.0
Version 7.0
Version 6.2
Version 6.1
Previous Versions
This object embeds the Chromium HTML rendering engine, which can be rendered at full screen or as a widget. You can display multiple roHtml
Widget instances at the same time.
Tip
Use the roKeyStore object to provide client certificates for websites. Use the roVirtualMemory object to set up a virtual memory
repository for Chromium.
Object Creation
The roHtmlWidget object is initialized with an roRectangle object, which specifies the size and positioning of the widget on the screen, and an
optional associative array, which defines properties for the widget.
CreateObject("roHtmlWidget", rect As roRectangle, properties As roAssociativeArray)
The properties of an roHtmlWidget instance can be set with an associative array at initialization or with equivalent methods after initialization.
Because many roHtmlWidget properties cannot be changed without reloading the page (and can produce unpredictable results while the page is
running), we recommend setting properties at initialization when possible, rather than using the equivalent methods.
Important
Defining initialization properties for an roHtmlWidget instance disables all property methods for that instance (e.g. SetTransform(), A
ddFont(), SetUserStylesheet()). Other methods that do not affect properties (e.g. Show(), FlushCachedResources()) can
still be used.
Initialization Parameters
The associative array passed during initialization can have the following parameters:
[boolean] nodejs_enabled
Enables Node.js on the widget. This value is false by default.
[boolean] focus_enabled
Enables focus for mouse/touchscreen events. This value is true by default.
[boolean] mouse_enabled
Enables mouse/touchscreen events. This value is false by default.
[boolean] scrollbar_enabled
Enables automatic scrollbars for content that does not fit into the viewport. This value is false by default.
[boolean] force_gpu_rasterization_enabled
Enables GPU rasterization for HTML graphics. By default, the decision to use GPU rasterization is based on internal Chromium logic. Setting this
value to true/false will enable/disable it for all content.
[boolean] canvas_2d_acceleration_enabled
Enables 2D canvas acceleration. This will improve the framerate of most HTML pages that use 2D animations, but can cause out-of-memory
issues with pages that use a large number of off-screen canvas surfaces. This value is true by default in firmware versions 7.0.x and later and f
alse by default in firmware versions 6.2.x and earlier.
[boolean] javascript_enabled
Enables JavaScript on the widget. This value is true by default.
[boolean] brightsign_js_objects_enabled
Enables BrightScript-JavaScript objects. This value is false by default.
[string] transform
Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the roRectangle containing the widget are not
affected by rotation). The following values are accepted:
"identity": There is no transform (i.e. the widget content is oriented as landscape). This is the default setting.
"rot90": The widget content is rotated to portrait at 90 degrees (clockwise).
"rot270": The widget content is rotated to portrait at 270 degrees (counter-clockwise).
[string] user_agent
Modifies the default user-agent string for the roHtmlWidget instance.
[string] url
The URL to use for display. See the SetUrl() entry below for more information on using URIs to access files from local storage.
[string] user_stylesheet
Applies the specified user stylesheet to pages in the widget. The parameter is a URI specifying any file: resource in the storage. The
stylesheet can also be specified as inline data.
[string] hwz_default
Specifies the default HWZ behavior. See the SetHWZDefault() entry below for more information.
[string] storage_path
Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage clas
s.
[string or double] storage_quota
Sets the total size (in bytes) allotted to all local storage applications (including IndexedDB). The default total size is 5MB.
[roMessagePort] port
Configures the message port to which the roHtmlWidget instance will send events. When using initialization parameters, the port parameter
should be used instead of the SetPort() method to ensure the script can catch load-started, load-finished, and load-error events.
[roArray] fonts
Specifies a list of font files that can be accessed by the webpage. Font files are specified as an array of string filenames. Supported font types
include TrueType Font files (.ttf) and Web Open Font files (.woff, .woff2).
[roArray] pcm_audio_outputs
Configures the PCM audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
[roArray] compressed_audio_outputs
Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. Outputs are specified as an array of roAudioOutput in
stances.
[roArray] multi_channel_audio_outputs
Configures multi-channel audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
[roAssociativeArray] inspector_server
Configures the Chromium Inspector for the widget.
[string] ip_addr: The Inspector IP address. This value is useful if the player is assigned more than one IP address (i.e. there are
multiple network interfaces) and you wish to limit the Inspector server to one. The default value is "0.0.0.0", which allows the
Inspector to accept connections using either IP address.
[int] port: The port for the Inspector server.
[roAssociativeArray] security_params
Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc.
[Boolean] websecurity: Enables Chromium security checks.
[Boolean] camera_enabled: Enables webpage access to USB cameras connected to the player (access is disabled by default).
This allows support for WebRTC applications.
[Boolean] insecure_https_enabled: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts
(insecure HTTPS is desabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments
and should only be used for testing.
Note
The camera_enabled parameter is currently supported on the XTx43, 4Kx42, XDx33, HDx23, and LS423 models.
[roAssociativeArray] javascript_injection
Specifies JavaScript code to inject at different initialization points (JavaScript code can also be injected during runtime using the InjectJavaScr
ipt() method). The associative array can contain three parameters (described below). Each parameter value is an array of associative arrays,
each containing a single key/value pair. The array must contain a source key. The source value is a string that can contain any of the
following: pure JavaScript code, a path to a JavaScript file, or a base64-encoded string (i.e. beginning with data:text/javascript;
charset=utf-8;base64, ). Mutliple source keys can be included, but the load order will be unpredictable. The array can also contain the
optional world key, which can be assigned one of the following values: "application", "user", or "main"(see this page for more details); if
the world parameter is not included in the array, "application" is selected by default.
document_creation: The script will run as soon as the document is created. This behavior is not suitable for any DOM operation.
document_ready: The script will run as soon as the DOM is ready. This behavior is equivelant to the DOMContentLoaded event firing
in JavaScript.
deferred: The script will run when the page load finishes. The DOM cannot be changed at this point.
config = {
javascript_injection: {
document_creation: [{source: "0.js" }],
document_ready: [{source: "1a.js" }, {source: "1b.js" }],
deferred: [{source: "2.js" }]
},
url: "..."
}
[roArray] assets
Allows the roHtmlWidget instance to access one or more asset pools. If a file exists in multiple specified asset pools, the asset pool with the
lowest index in the array has precedence. Each array entry is an associative array containing information about an asset pool:
[roAssetPool] pool: An asset pool containing files
[roAssetCollection] collection: A manifest identifying the files in the pool
[string] uri_prefix: The URI prefix of the webpage resources to retrieve from the pool
[string] pool_prefix: The pool prefix that will replace the URI prefix when looking up the resource in the pool
ifHtmlWidget
GetFailureReason() As String
Gives more information when a member function returns false.
Hide() As Boolean
Hides the widget.
Show() As Boolean
Shows the widget.
SetRectangle(r As roRectangle) As Boolean
Changes the size and positioning of the widget rectangle using the passed roRectangle object.
SetURL(URL As String) As Boolean
Displays content from the specified URL. When using this method to retrieve content from local storage, specify the file location as follows: "file
:/://". For example, an index.html file in the "Content" folder on the SD card can be selected with the
string "file:/SD:/Content/index.html". You can also omit the drive specification to select the currently active drive (i.e. whichever drive
the current autorun as loaded from).
MapFilesFromAssetPool(asset_pool As roAssetPool, asset_collection As roAssetCollection, pool_prefix As String, uri_prefix As String) As
Boolean
Sets the mapping between the URL space and the pool files. HTML content that has been deployed via BrightAuthor will typically reside in the
pool and have encrypted SHA1-based filenames. A mapping mechanism is required to allow any relative URIs contained in the HTML content to
continue working and to locate the appropriate resources in their respective pool locations.
You can use this method to bind part of the resource URI space onto pool locations. This method accepts the following arguments: an roAssetPool
object containing assets, an roAssetCollection object identifying the assets, and two semi-arbitrary strings (URI_PREFIX and POOL_PREFIX).
Any URI in the form "file:/[URI_PREFIX][RESOURCE_ID]" will be rewritten into the form "[POOL_PREFIX][RESOURCE_ID]". It will then
be located in the pool as if that name had been passed to the roAssetPoolFiles.GetPoolFilePath() method. This binding occurs for every instance
of roHtmlWidget, so different mappings can be used for different bundles of content.
SetZoomLevel(scale_factor as Float) As Boolean
Adjusts the scale factor for the displayed page (the default equals 1.0).
EnableSecurity(enable As Dynamic) As Boolean
Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc. (if the argument is Boolean). This
method can also accept an associative array, which can contain the following parameters:
[Boolean] websecurity: Enables Chromium security checks. This parameter is identical to passing a Boolean argument to the
method itself.
[Boolean] camera_enabled: Enables webpage access to USB cameras connected to the player (access is disabled by default).
This allows support for WebRTC applications.
[Boolean] insecure_https_enabled: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts
(insecure HTTPS is desabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments
and should only be used for testing.
Note
The camera_enabled parameter is currently supported on the XTx43, 4Kx42, XDx33, HDx23, and LS423 models.
EnableMouseEvents(enable As Boolean) As Boolean
Enables response to mouse/touchscreen presses if true. Setting this method to false (the default) disables this feature.
SetPortrait(portrait_mode As Boolean) As Boolean
Sets the widget orientation to portrait if true. If this method is false (the default), the widget is oriented as a landscape.
Important
The SetPortrait() method has been deprecated in firmware 6.1. We recommend using the SetTransform() method instead.
SetTransform(transform As String) As Boolean
Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the roRectangle containing the widget are not
affected by rotation). This method accepts the following strings:
"identity": There is no transform (i.e. the widget content is oriented as landscape). This is the default setting.
"rot90": The widget content is rotated to portrait at 90 degrees (clockwise).
"rot270": The widget content is rotated to portrait at 270 degrees (counter-clockwise).
SetAlpha(alpha As Integer) As Boolean
Sets the overall alpha level for the widget (the default equals 255).
EnableScrollbars(scrollbars As Boolean) As Boolean
Enables automatic scrollbars for content that does not fit into the viewport if true. Setting this method to false (the default) disables this feature.
AddFont(filename As String) As Boolean
Supplies additional or custom typefaces for the HTML rendering engine. Supported font types include TrueType Font files (.ttf) and Web Open
Font files (.woff, .woff2).
SetPcmAudioOutputs(outputs As roArray) As Boolean
Configures the PCM audio output for the HTML widget. This method accepts one or more outputs in the form of an roArray of roAudioOutput insta
nces.
SetCompressedAudioOutputs(outputs As roArray) As Boolean
Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. This method accepts one or more outputs in the form
of an roArray of roAudioOutput instances.
Note
When one or more audio-output methods are called, they will override the settings of the following ifAudioControl methods: SetAudioO
utput(), MapStereoOutput(), SetUsbAudioPort(), MapDigitalOutput(). Calls to HTML audio-output methods will only
take effect with subsequent calls to SetUrl(). Audio-output settings on an roHtmlWidget instance will be overwritten by equivalent
settings in the HTML.
SetMultichannelAudioOutputs(outputs As roArray) As Boolean
SetHWZDefault(default As String) As Void
Sets the default HWZ mode for HTML video. Normally, HWZ must be enabled in each
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.4
Linearized : No
Modify Date : 2018:04:06 18:44:05Z
Create Date : 2018:04:06 18:44:05Z
Producer : iText 2.1.7 by 1T3XT
Page Mode : UseOutlines
Page Count : 325
EXIF Metadata provided by EXIF.tools