Home

OptoTerminal Programmer`s Reference Manual

Contents

1. type has been created to simplify use of this API Legal values are PINO PIN1 PIN2 etc Multiple values may be OR ed together to select any combination of input pins Description This function reads the input state of one or more GPIO pins Pins may be set to inputs using the SetGPIODirection API function The function reads the inputs on the pins selected by pins and returns a unibyte containing the read values The return value must be AND ed with the appropriate gpio_pin to determine the value on that pin non zero result indicates that the input is set logic HIGH while a zero result indicates that the input is clear logic LOW 4 18 3 SetGPIODirection Syntax setgpiodirection pins as unibyte input gt as boolean Parameters pins A value of type unibyte indicating which gpio pins to set to the desired direction The gpio pin type has been created to simplify use of this API Legal values are PINO PINI PIN2 etc Multiple values may be OR ed together to select any combination of pins input A boolean flag that should be set to TRUE if the desired direction is input and FALSE if the desired direction is out put Description This function sets the input output direction of one or more GPIO pins The function sets the pins selected by pins to inputs if input is TRUE otherwise the pins are set to outputs 4 18 4 GetVersion Syntax getve
2. 1 2 3 4 5 6 7 8 9 syscmd_powerkeymode POWERKEY NORMALKEY POWERKEY AUTOPOWER syscmd readfrom SYSREAD CURRENT SYSREAD PENDINGSAVE SYSREAD SAVED syscmd stopbits STOPBITS 1 STOPBITS 2 syscmd_usedrawcache DRAWCACHE ON DRAWCACHE OFF syscmd_usepassword USEPASSWORD_OFF USEPASSWORD_ON syscmd_mode MODE_DEVELOFF MODE_DEVELON MODE_DEFAULTAPP syscmd_orient ORIENT_LANDSCAPE ORIENT_PORTRAIT ORIENT_LANDSCAPE2 ORIENT_PORTRAIT2 typeval INTEGER_TYPE FLOAT_TYPE BOOLEAN_TYPE BYTE_TYPE UNIBYTE_TYPE ARRAY_TYPE OBJREF_TYPE volume_adjust VOLUME_LOUDER VOLUME_QUIETER syscmd_parity PARITY_NONE PARITY_ODD PARITY_EVEN weekday SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 2 Tool Types 101 A 4 Key Codes Defined Type Values Key Codes CSR ALL KEY ANY m KE NONE CSR UPLEFT KEY KEYPAD 2 Ho KEY CAPS LOCK ies SSR DOWNRIGHT SR B LOCK KEY SCROLL LOCK CSR SELECT KEY SHIFT CSR_NOLINETO KEY_ALT CSR_OBJECTFIXED KEY SPECIAL
3. 66 OptoTerminal Programmer s Reference Manual Number Note Frequency Number Note Frequency 23 G Ab 207 5 Hz 56 F 1396 Hz 24 A 220 Hz 57 F Gb 1480 Hz 25 A Bb 233 Hz 58 G 1568 Hz 26 B 247 5 Hz 59 G Ab 1660 Hz 27 262 Hz 60 A 1760 Hz 28 C Db 277 Hz 61 A Bb 1864 Hz 29 D 294 Hz 62 B 1980 Hz 30 D Eb 311 Hz 63 2096 Hz 31 E 330 Hz 64 C Db 2216 Hz 32 F 349 Hz 65 D 2352 Hz 33 F Gb 370 Hz 66 D Eb 2488 Hz 34 G 392 Hz 67 E 2640 Hz 35 G Ab 415 Hz 68 F 2792 Hz 36 A 440 Hz 69 F Gb 2960 Hz 37 A Bb 466 Hz 70 G 3136 Hz 38 B 495 Hz 71 G Ab 3320 Hz 39 Midl C 524 Hz 72 A 3520 Hz 40 C Db 554 Hz 73 A Bb 3728 Hz 41 D 588 Hz 74 B 3960 Hz 42 D Eb 622 Hz 75 4192 Hz 43 E 660 Hz 76 C Db 4432 Hz 44 F 698 Hz 77 4704 Hz 45 F Gb 740 Hz 78 D Eb 4976 Hz 46 G 784 Hz 79 5280 Hz 47 G Ab 830 Hz 80 F 5584 Hz 48 A 880 Hz 81 F Gb 5920 Hz 49 A Bb 932 Hz 82 G 6272 Hz 50 B 990 Hz 83 G Ab 6640 Hz 51 1048 Hz 84 A 7040 Hz 52 C Db 1108 Hz 85 A Bb 7456 Hz 53 D 1176 Hz 86 B 7920 Hz 54 D Eb 1244 Hz 55 E 1320 Hz Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 8 2 PlayNoteNotify Syntax playnotenotify obj as objref parm as gt integer note as byte duratio as integer Parameters obj The object to notify when the sound has finished parm Optional parameter to send with the message produced when the sound h
4. EXCEPT_BADARCMATH Ilegal arc function value EXCEPT FFSTOOMANYOPEN many open files EXCEPT BADLOG Illegal log function value EXCEPT FFSBADOPEN Unable to open file as indicated EXCEPT BADSQRT EXCEPT DIVBYZERO Illegal sqrt function value Division by zero EXCEPT NOBYTES No byte representation for given type EXCEPT FFSDUPNAME EXCEPT FFSBADOP File with given name already exists File not set up to allow requested oper ation EXCEPT_BADBYTES Bad byte representation for given type EXCEPT_FFSPATHNOTFOUND Path not found EXCEPT_DOMAINERROR Math function domain error 29 EXCEPT_FFSBADNAME name speci fied B 11 Flash Write Exceptions EXCEPT_FFSTOOLONG Path or name too long EXCEPT_PBLK_TOO_BIG Block is too large EXCEPT_FLASHMEMORIZE Unable to place neces sary routine in RAM EXCEPT_FFSDELOPEN EXCEPT_FFSNOINIT Unable to delete open file File system not inited perhaps low on space Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 108 OptoTerminal Programmer s Reference Manual EXCEPT_FFSBADDIR Indicated file not directory EXCEPT_XCPTSTACKPOPPED Exception stack deci mated EXCEPT_FFSBADOFFSET Invalid offset
5. Parameters lt newparent gt A reference to the container to which the object should attach itself This handler code works for any object with an objref prop erty named parent that holds a reference to the object s parent Note that the strict assignment operator is used to avoid calling a validation function that will likely call the Attach API and that the Tool Persist API function is called to inform the system software that the value of the parent property has changed Message MSG_TOOL_MOVE Description This message indicates that the object has been moved in Qlarity Foundry probably due to a mouse drag The han dler should update any properties relating to object position call API functions to update the system software position attributes for the object and call Tool Persist for any properties that have changed Handler Format func name dx as integer dy as gt integer handles MSG TOOL MOVE xpos xpos dx ypos ypos dy tool_persist xpos tool_persist ypos ices endfunc Parameters lt dx gt The change in the object x position caused by the move OptoTerminal Programmer s Reference Manual lt dy gt The change in the object y position caused by the move This code assumes that the object has properties xpos and ypos which hold the current position of the object Nor mally the validation functions for these properties will han dl
6. CSR_NONE Cursor does not indicate the pres ence of a resize grip and the resize grip is not drawn The loca tion cannot be dragged CSR_SELECT Cursor has a different color resize grip for selection Resize grip cannot be dragged Usually com bined with CSR_NOLINETO CSR_NOLINETO Cannot draw a line between Opto 22 GuiCursors Description Use on first resize grip to indicate that the object cannot be moved by the mouse in a fixed location CSR_OBJFIXED Cursor has a different color resize CSR_DELETE grip for selection Resize grip cannot be dragged Cursor has a different color resize CSR_PLUS grip for selection Resize grip cannot be dragged CSR_NOLINETO and CSR_OBJFIXED are flags that should be combined with another flag using the opera tor e g cursor 2 CSR_ALL or CSR_NOLINETO The typical handler for this function has three local arrays one integer array for x one integer array for y and one array of GuiCursors for cursors with the dimension size indicating the number of resize grips The array elements should be assigned to the desired values The arrays are then assigned to xCoords yCoords and cursors respectively Since the parameters are references to arrays the values assigned in the handler are passed back to the system which uses the data to create the resize grips for the object NOTE The initial size for the parameters
7. EXCEPT_FFSNOOVERWRITE No overwrite sup port for given mode EXCEPT_NOREAD Unable to read item of given type EXCEPT_NOWRITE Unable to write item of given type EXCEPT_FFSCORRUPT Corrupt file system detected EXCEPT_FFSBADMOVE Ilegal rename requested 13 Compiler Error Exceptions EXCEPT_MISALIGNED Data misalignment problem EXCEPT_PARMERR Parameter error EXCEPT_BADFONTNUM Non existent font reference EXCEPT_BADBMPNUM Non existent bitmap reference EXCEPT_TYPEMISMATCH Incorrect types EXCEPT_BADOPCODE Illegal instruction opcode EXCEPT_BADDEREFTYPE Unable to derefer ence item EXCEPT BADMATHOP Invalid operation for given type EXCEPT_BADPROMTYPE Unable to promote to desired type EXCEPT_STACKPOPPED Interpreter stack dec imated EXCEPT_BLOWNSTACK Interpreter stack blown EXCEPT_STACKNOTEMPTY Returning with inter preter stack not empty EXCEPT_XCPTSTACKMORE Returning with exception stack not empty EXCEPT_BADAPI EXCEPT_BADSNDNUM Attempting to call a non existent API function Non existent sound reference EXCEPT_INVALRES Invalid resource EXCEPT_BADBASEFUNC Invalid call to default function The following are fatal system e
8. arr An array of any type OptoTerminal Programmer s Reference Manual len The number of data elements to extract Description This function returns an array that contains the last len elements of arr 49 4 Mid Syntax mid arr as reference to sametype gt index as integer len as integer returns gt sametype Parameters arr An array of any type index The location of the first data element to extract 0 based len The number of data elements to extract or 1 to indicate all elements from the element at index to the end of 11 arr A Description This function returns an array containing len elements from arr starting with the element located at index into arr 49 5 Trim Syntax trim arr returns gt string as reference to byte Parameters arr Byte array Description This function removes any leading or trailing white space spaces tabs carriage returns or line feeds from the byte array returning the remaining characters Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 9 6 Find Syntax find match as reference to sametype gt start as integer length as integer gt pattern as reference to sametype gt returns integer Parameters match An array of any type to examine start The locati
9. getchildren contobj as objref returns gt objref Parameters contobj A reference to a container type object Description This function returns an array containing references to all of the object s direct children all objects whose parent is contobj The children are returned in Z order 43 7 GetEnableInfo Syntax getenableinfo obj as objref eval as gt enable_info returns boolean Parameters obj The object for which the status information is to be returned OptoTerminal Programmer s Reference Manual eval The type of information desired Description This function returns the status of the object obj based on the information desired indicated by eval Legal values for eval are GET ENABLED Request the enabled status of an object GET ZENABLED Request whether the object s parents are enabled to root does not include the object itself 4 3 8 GetPosInfo Syntax getposinfo obj as objref pval as gt position_info returns integer Parameters obj The object for which the position information is to be returned pval The type of information desired Description This function returns the requested position information for obj based on the information desired indicated by pval Legal values for pval are GET X The current x position of the object relative to its par ent GET Y The curr
10. is of type drawcache level The values are CACHE ALL CACHE OFF CACHE ENABLED CACHE EFFECTIVE ENABLED SYS PASSWORD Change the password used to enter the Power On Setup utility newvalue is a unibyte array containing exactly sixteen elements To allow the use of multiple OptoTerminal Programmer s Reference Manual input methods to access Power On Setup on units with some combination of keypad keyboard and touch screen use the following constants in place of the cor responding Power On Setup keys on the input source i e for the Enter key on the keyboard use POSKEY ENTER rather than KEY ENTER Other wise key codes may be used to define the appropriate key sequence However all sequences must have a POSKEY ENTER in them and keys following this key are ignored Note that for the keyboard only the bits in KEY ASCII MASK are used Available POS KEY keys on all input devices are as follows POSKEY UP POSKEY DOWN POSKEY LEFT POSKEY RIGHT POSKEY ENTER The following POSKEY keys are also available on key boards and some keypads POSKEY ESC POSKEY 0 POSKEY 1 POSKEY 2 POSKEY 3 POSKEY 4 POSKEY 5 POSKEY 6 POSKEY 7 POSKEY 8 POSKEY 9 As there is no current value for this setting using SYSACT DONOW will not do anything and using SYSACT ALWAYS will only set the pending save set ting SYS USEPASSWORD Specify whether or not a password is required to get full functionality in the Power On Setup uti
11. roce mr ra CUI P RR Ee c e ED t ied 83 4 18 5 GetHa rdwa relInfo teet eei n au n SRL eset i thee ae 83 4 18 6 SetContrast zie eh IIR EE ENT ENTIER EET EUN RE RORIS LENT EN EE FERENT CIO 84 4 18 7 SetBacklight 5 ic e e e ete Bet be re etae en EE CH A E REO ERIT ER 85 4 18 8 EnableKeypadBacklght eonun eee Renee aped e 85 4 16 SCULED 85 4 18 10 Get Time acaso p o P et e pe t NER A t DR Rd 85 4 18 11 SetTime eet pe ed degere eb e ie ce vt paul e EN tea 86 4 18 12 GetTemperature o eese de eenieeac eg e Dota a ene va eei ite ie eet b 86 4 18 13 Ty peO RT 86 4 18 14 SetSystemSettng in entero tei eti ae te pe T ER ei esee et e co te a Ea Ce 87 4 18 15 GetSystenmsSetting oed d v die EHE RR tb e de basic d aed e 92 4 18 16 Soft Reset cse de e ere RR sabes HER T TER HE ERN CREE UR er EL RHET 93 4 18 17 denen 93 4 18 I8 SeedRandomNdUltn nieto o a RO SER ERR ERES EORR RUE saves iat Ir EARE 93 4 18 19 SetSeedRandombum id ecd RN ade ea ie ite e Ee TX en eve eie 93 4 18 20 WatchdogEnable ate ee ete teen ete n e et 93 4 18 21 WatchdogReset eR ted ette t a e RES e RE Reeth no ERE D aide 94 4 1822 GetProfile Tick eto nece te Det
12. Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual wordbrks An array of the same type as data that determines which characters to treat as word breaks spaces tabs etc linebrks An array of the same type as data that determines which characters to treat as line breaks newline form feed etc flags A value of type font_flags see below that determines how the text will be rendered Description This function tries to find the best text fit for data A good understanding of the GetBDFTextSize and DrawBDF Text functions should prelude attempts to use this function The parameter flags is of type font flags which is a type that can have any combination of following legal val ues other font flags settings are ignored FONT NORMAL Render the text horizontally with the text in the fore ground color and remainder of the region in the back ground color FONT VERTICAL Render the text vertically with the text in the fore ground color and the remainder of the region in the background color Most fonts that use Latin characters do not support this option FONT INVERSE Render the text horizontally with the text in the back ground color and the remainder of the region in the foreground color FONT DRAWLINEBREAKS Consider all line break characters as actually drawn when calculating fit ot
13. constant pi 3 1415926536 as float Defined Type Values Defined Type Values fake_screen SCREEN_PUSH SCREEN_MOVE SCREEN_RELEASE ARRAY_CONVERT ARRAY_PALETTE ARRAY_REVERSE ARRAY PFIELD arrayOp filedesc FILE NONE arrayHandle NULL HANDLE BACKLIGHT ON BACKLIGHT OFF BACKLIGHT LIGHTER BACKLIGHT DARKER backlight adjust file flags FILE NOFLAGS FILE READ FILE WRITE FILE TEXT FILE BINARY FILE NO CREATE FILE APPEND COMI COM2 COM3 COM4 5 comm COM6 COM7 COM8 COM9 COM10 COM_INVALID fileinfo_flags FILEINFO_ISNOT FILEINFO_ISTEXT FILEINFO_ISBIN FILEINFO_ISDIR FILEINFO_ISOPEN CONTRAST_LIGHTER contrast_adjust CONTRAST DARKER CACHE_OFF CACHE_ALL CACHE_ENABLED CACHE_EFFECTIVE_ENABLED drawcache_level ELLIPSE_NORMAL ELLIPSE_FILL font_flags FONT_NORMAL FONT_VERTICAL FONT_INVERSE FONT_DRAW_HPARTIAL FONT_DRAW_VPARTIAL FONT_DRAWSPACE FONT_DRAWLINEBREAKS FONT_DRAWWORDBREAKS FONT_NOSOFTBREAKS FONT_HBASELINE FONT_HFIT FONT_HABS FONT_HLEFT FONT_HCENTER FONT_HRIGHT FONT_VBASELINE FONT_VFIT FONT_VABS FONT_VTOP FONT_VCENTER FONT_VBOTTOM ellipse_flags ELLIPSE_CONNECT_CENTER ELLIPSE_CONNECT_ENDS enable_info SEI ENABLED GET ZENABLED KEY PUSH fake key KEY REPEAT KEY RELEASE gpio action GPIO SET GPIO CLEAR GPIO TOGGLE Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 32
14. lt keycode gt A unibyte containing the keycode for the key that was pressed Most keycodes are defined as constants which are listed in Appendix A lt pass gt False if the container s children have not yet received the message and true if the container s children have already received the message Message MSG_KEY_PRESS Description This message indicates that a key has been pressed on the keyboard or keypad The keyboard and keypad are distin guished by unique keycodes If the key repeat feature is available on the keyboard or keypad and the key is held down then the MSG_KEY_PRESS will occur for the initial key immediately after the MSG KEY DOWN message is sent and for each key repeat event To be eligible to process OptoTerminal Programmer s Reference Manual this message an object must register for it using the Regis terKey API function see section 4 2 3 Handler Format if handled by a container object global func name lt keycode gt as unibyte pass gt as boolean handles MSG KEY PRESS Ds endfunc if handled by an area non drawable object func name keycode as unibyte handles MSG KEY PRESS endfunc Parameters lt keycode gt A unibyte containing the keycode for the key that was pressed Most keycodes are defined as constants which are listed in Appendix A lt pass gt False if the container s children have not yet received
15. see below that deter mines the time at which the new settings take effect 87 Description This function modifies most of the hardware terminal set tings for the Qlarity based terminal These settings can also be saved in the non volatile flash memory of the terminal making the settings effective across power cycles When writing changes that are to be saved to the flash settings are first written to a pending save area The pending changes are only saved to the flash when this function is called with the command SYS_SAVE The action argument is of type SYSCMD_ACTION and can take the following values SYSACT_DONOW The new setting will take effect immediately but not persist after the terminal power is cycled A value set using this action will not be saved when this function is called with the SYS SAVE command SYSACT ONBOOT The new setting will not take effect immediately but should take effect after the terminal power is cycled This value is placed into a list of pending changes that is saved to the non volatile flash memory when this function is called with the SYS SAVE command SYSACT ALWAYS The new setting will take effect immediately and after the terminal power is cycled The current setting is changed and this value is also placed into a list of pend ing changes that is saved to the non volatile flash mem ory when this function is called with the SYS SAVE command The cmd argument specifies
16. 5 endfunc Parameters lt newparent gt A reference to the container to which the object should attach itself Do not assign the parent property to newparent i e do not do parent newparent This will be done in the MSG_TOOL_ATTACHED handler This handler code will suffice for almost any conceivable object because Qlarity Foundry first calls attach but the object doesn t have to attach Message MSG_TOOL_ATTACHED Description When API functions that change Z order such as Attach are called the requested change is scheduled Because Z order is critical to the proper functioning of the message handling system the actual changes are postponed until the current message has been processed to completion There fore it is not possible to know if an Attach succeeded until the handler that called Attach has finished executing If the attach fails properties that indicate an object s parent should not be changed If the attach succeeds then the prop erty needs to be updated Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 30 The MSG_TOOL_ATTACHED message is sent when a successful attachment has occurred The handler is respon sible for updating any property that is affected by a change in parent Handler Format func lt name gt lt newparent gt as objref handles MSG_TOOL_ATTACHED parent newparent tool_persist parent ese endfunc
17. 5 002 edi ees sse ehe todo oreet ee 35 4 1 Communications 2202 eene ee eiit etim t P Ee begehrt 35 E ete ae este nis adel Navies 35 Opto 22 Fax 800 832 6786 Web www opto22 com Phone 800 321 6786 OptoTerminal Programmer s Reference Manual iii 4 12 Tram Smid e eee e eve ck soe acess e 35 4 1 3 SetBreak 5 evene dti ie ime o p up ed 35 4 1 4 GetComMessageSOUrce RR d EE P ER POE EE nerd iig 36 41 5 NetOpen eoa IN ore ur E d HER IE an te cu en 36 4 1 6 NetServerOpen ipee e d Weed A sui ae ge d e dant est eb e t ede e E det E todas 37 4 17 NetClose een esce Sper eot p n RC Cnr 37 4 1 8 NetServerClose eat RR DERE ERR R 37 41 9 ChangePOtt oe nv eU ROO er e t T E p D 38 4 1 10 Transmit re ents ie etre eee tte tbe E A rH IE DO e de e od eei 38 4 1 11 GetNetChannelInfo 5 nb enden cree i eri i eei a ed ei pe tl pedes pct 38 41 12 SetSerialRecvSize us at RR REO RERO HP wie EN RE E RR Mina 38 4 1 13 SetSenialTimeout cce e REC ER pe 39 41 14 C 39 4 1 15 ReadRTS i a2 onere RERO a ok apd sce sos ta des ADUREO RID E ODORE 39 4 1 16 SetDS me ete em i aea P P e
18. API function The resulting value is stored in var Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 16 11 WriteFile Syntax writefile fnum as filedesc data as gt reference to anytype Parameters File handle of the desired file data A variable of any type containing data to write to the file Description This function writes data to the specified file based on the file s access method If the file is in binary mode the data is written in bytes exactly as it is in data In binary mode bytes in the file are overwritten if the current file position is not at the end of the file In text mode the current file posi tion must be at the end of the file Also the data is con verted to a string as with a call to the Str API function and the resulting string is written to the file followed by a newline character 0x10 4 16 12 SetFilePos Syntax setfilepos fnum as filedesc offset as gt integer absolute as boolean Parameters File handle of the desired file offset An integer containing the offset to be added to the current position or the beginning of the file absolute A flag determining the basis for the new position calcula tion A value of true adds offset from the beginning of the file A value of false adds offset to the current file positi
19. C 68 4 93 68 4 9 3 Right de eee d tee ERR dad 68 4 94 Mid p DH rene 68 49 5 Trim oett eA Hee ed RU RERUM aita mmis 68 49 6 Findet seca RO eeu teer quite HER Ubuntu 69 4 9 7 Concati i ied e e eli e t e EE ee eee Hc a aec ste R ERE e CR Meese 69 4 9 8 ROAM nego pesada o tuer p pU E e 69 4 9 9 Array ODeratiOni obere RIS RN UR UO DUE ERE EROR E 69 4 9 10 Fre ArrayHandle 2 utet me ea e OD dee ade teg 70 4911 ReadArrayHandle e eed eei ad piece i e e ene Eee E EHE ed oda et be 70 4 9 12 eeiam ete 70 40 13 Reye rse Find a Re o e D RETE Rn Ee EE ERR Eee NEEE 70 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 49 14 Replica race ted diet er ed estesa ES 71 4 10 Conversion Punctions idee ent teri dn eerta e er a ri eer E deri 71 ALLOA at eed et adn dae 71 4 10 2 o E Ne I t e UM eeu
20. SYS COMGFLOWCONTROL SYS COMAFLOWCONTROL SYS COMSFLOWCONTROL SYS COM6FLOWCONTROL SYS COM7FLOWCONTROL SYS COMSFLOWCONTROL Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 SYS_COM9FLOWCONTROL SYS_COM10FLOWCONTROL Set the flow control for the selected serial interface newvalue is of type syscmd_flowcontrol which is an enumerated type with three legal values FLOWCONTROL_NONE FLOWCONTROL_XON _OFF FLOWCONTROL RTS CTS RTS CTS flow control is only supported for the EIA 232 interface SYS COMIFLOWTIMEOUT SYS COM2FLOWTIMEOUT Set the flow control transmit timeout for the selected serial interface newvalue is of type integer and can be any number from 0 to 65535 zero meaning no time out It tells how many 20 ms intervals to wait if neces sary to send any character before timing out SYS IPADDRESS For terminals with an Ethernet interface set the IP address of the terminal newvalue is a 4 byte array containing the new IP address SYS IPSUBNET For terminals with an Ethernet interface set the subnet mask newvalue is a 4 byte array containing the new subnet mask SYS IPGATEWAY For terminals with an Ethernet interface set the gate way IP address newvalue is a 4 byte array con taining the new gateway IP address SYS USEDRAWCACHE Change the status of whether the unit uses draw cach ing to increase draw performance newvalue
21. Typed objrefs are empty by default If you use an objref that is empty a runtime error will occur Use the keyword empty to indicate an empty objref In the example above the function has a typed objref of type bitmapobj that is used to access the enabled property of the bitmap object instance The bitmapobj method foo is also called 2 8 3 Special Object References The object reference me always refers to the object in which it is used is considered a typed object refer ence Default when used in the context of an untyped object reference refers to the root container When default is used in the context of a typed object reference it is the same as empty The object reference empty indicates that no object is referenced by this value This is similar to a null or a nil value in other programming languages 2 9 Arrays Syntax dim array name array size as gt data type 11 init array name val 0 val 1 gt Description Array declaration is similar to variable declaration The array size is an integer value Arrays can be declared of any type except string and unistring byte array or string may be assigned a string of alphanumeric characters within double quotes An array that is not initialized is automati cally initialized to the default value of the data type An array can be initialized with fewer values than the size of the a
22. drawpixmap x as integer as integer pixmap gt as reference to byte mapwidth as integer gt mapheight as integer section 4 6 11 page 47 DrawPixmapRegion DrawPolygon drawpixmapregion x as integer as integer gt xoffset as integer yoffset as integer width as gt integer height as integer pixmap as gt reference to byte mapwidth as integer gt mapheight as integer drawpolygon xpoints as integer ypoints as gt integer flags as poly_flags section 4 6 12 page 47 section 4 6 15 page 48 DrawSysText drawsystext x as integer as integer width as gt integer height as integer xoffset as integer gt yoffset as integer font as sysfont facenum as gt integer ptsize as integer data as reference gt to anytype flags as font_flags section 4 7 14 page 63 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 115 Function Syntax Reference DrawSysTextFit drawsystextfit multiflags as reference to gt multiline_flags xpos as reference to integer gt ypos as reference to integer widths as gt reference to integer heights as reference to gt integer xoffsets as reference to integer gt yoffsets as reference to integer indices as gt reference to integer lengths as reference integer font as sysfont facenum as
23. heights An array of integers indicating the height for each line of text 1 array of integers indicating the horizontal offset from the upper left corner of the rendered region to the origin of the first character for each line Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual yoffsets An array of integers indicating the vertical offset from the upper left corner of the rendered region to the origin of the first character for each line indices An array of integers the tells the index into data where each line of text begins lengths An array of integers indicating the number of elements to draw in each line of data font The sysfont resource This may be either a BDF or a True Type font The number for the desired face This value is only used with TrueType fonts and is typically zero 0 ptsize The desired point size of the rendered text This value is ignored unless font specifies a TrueType font data The data to be rendered as text The type can be a unibyte or byte array unistring or string flags A value of type font_flags see below that determines how the text will be rendered Description This function renders the text contained in data The parameters are typically obtained by a call to GetSysText The rendered text is clipped as necessary A g
24. to multiline_flags xpos as reference gt to integer ypos as reference to gt integer widths as reference to gt integer heights as reference to gt integer xoffsets as reference to gt integer yoffsets as reference to gt integer indices as reference to gt integer lengths as reference to gt integer font as sysfont facenum as gt integer ptsize as integer data as gt reference to sametype wordbrks as gt reference to sametype linebrks as gt reference to sametype flags as gt font_flags Parameters multiflags An array of type multiline flags returned by the function giving information on how each line was fitted xpos An array of integers returned by the function that tells the relative horizontal offset for where each line of text should be drawn An array of integers returned by the function that tells the relative vertical offset for where each line of text should be drawn widths An integer array used as both an input and an output For input the 0 th element is used to indicate the total width in pixels of the box that the text needs to fit into if FONT HFIT is specified this value is only used for align ment purposes On return the width for each line of text will be in the individual elements of the array with the 0 th element always containing the final full width of all the text lines if FONT HFIT is specified then th
25. transmit resource as comm data as gt reference to anytype block as boolean Parameters resource The communications resource to transmit the data data An array of any type that contains the data for transmission block A boolean flag to select buffered or unbuffered transmis sion Description The transmit function sends the data in data to the com munications interface specified by resource If the block parameter is true then the unit waits until the transmission has finished before returning from the API function If block is false then the system software buffers the data and returns immediately Transmission takes place in the background Using buffered output is gen erally a more efficient use of system resources and is rec ommended for most transmissions 41 3 SetBreak Syntax setbreak resourc state as boolean as comm Parameters resource The communications resource to change the state of state A boolean flag used to indicate whether a break state should begin A value of true indicates to place the resource in break where as false indicates that the break condition should be terminated Description This function allows the user to set the break state of a com munications port Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 36 414 GetComMessageSource Syntax getcommessagesource r
26. which parameter This parameter must of type syscmd readfrom and has the following possible values SYSREAD CURRENT The current value of the setting being used by the firm ware OptoTerminal Programmer s Reference Manual SYSREAD PENDINGSAVE The value of the setting that is pending a save com mand SYSREAD SAVED The value of the setting that is actually saved The variable value is passed as a reference and receives the value of the setting The value variable must be of the correct data type for each value of cmd as follows see also section 4 18 14 SetSystemSetting SYS CONTRAST integer SYS BACKLIGHT integer SYS VOLUME integer SYS NOTEAMPLITUDE integer SYS MODE syscmd mode SYS ORIENT syscmd orient SYS KBDRPTDELAY SYS KBDRPTRATE syscmd kbdrptdelay syscmd kbdrptrate SYS KEYRPTDELAY integer SYS KEYRPTPERIOD integer SYS KEYCLICK boolean SYS KEYRPT boolean SYS COMIBAUD SYS COMIDATABITS SYS COMIPARITY SYS COMISTOPBITS SYS COMIFLOWCONTROL SYS COMIFLOWTIMEOUT SYS COM2BAUD SYS_COM2DATABITS SYS_COM2PARITY SYS_COM2STOPBITS SYS_COM2FLOWCONTROL syscmd_baud syscmd_databits syscmd parity syscmd stopbits syscmd flowcontrol integer syscmd baud syscmd databits syscmd parity syscmd_stopbits syscmd_flowcontrol SYS_COM2FLOWTIMEOUT integer SYS IPADDRESS byte array SYS IPSUBNET byte array SYS IPGATEWAY byte array SYS USEDRAWCACHE SYS PASSWORD unibyte array SYS USEPASSWO
27. A5 Colors KEY ASCII MASK KEY SPACE Colors KEY BACKSPACE RGB BLACK RGB BLUE KEY TAB RGB BROWN BURNTORANGE KEY UPARROW RGB CYAN RGB DKBROWN KEY DOWNARROW RGB DKGRAY RGB DKSTEELGRAY KEY LEFTARROW RGB FORESTGREEN RGB GRAY KEY RIGHTARROW RGB GREEN RGB KELLYGREEN KEY ENTER RGB LTBROWN RGB MAGENTA KEY ESCAPE RGB MAROON RGB MIDNIGHTBLUE KEY DELETE RGB MOSSGREEN RGB NAVY KEY INSERT RGB ORANGE RGB PURPLE KEY HOME RGB RED RGB STEELGRAY KEY END RGB VIOLET RGB WARMGRAY KEY PAGEUP RGB WHITE RGB YELLOW KEY PAGEDOWN COL 0 through COL 255 KEY NUMPAD 5 KEY PRINTSCREEN KEY PAUSE KEY OS KEY MENU KEY Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 102 OptoTerminal Programmer s Reference Manual Key Codes Key Codes KEY_F2 KEY_7 KEY_F3 KEY_8 KEY_F4 KEY_9 5 KEY COLON KEY F6 KEY SEMICOLON KEY F7 KEY LESS THAN KEY KEY EQUALS KEY F9 KEY GREATER THAN KEY 10 KEY QUESTION KEY KEY AT KEY 12 KEY A KEY EXCLAMATION KEY B KEY QUOTE KEY C KEY POUND KEY D KEY DOLLAR KEY E KEY PERCENT KEY F KEY AMPERSTAND KEY G KEY APOSTROPHE KEY H KEY OPEN PAREN KEY I KEY CLOSE PAREN KEY J KEY ASTERISK KEY K KEY PLUS KEY L KEY COMMA
28. FERR MSGQSTALLED Unknown message in mes sage queue Message queue has stalled FERR HAVE PREV BFF Previous BFF not freed FERR NO PREV BFF No BFF to be freed B 18 Network Fatal Exceptions FERR BAD BFF bad or missing EXCEPT OUTOFBUF Out of network packet buffers FERR BAD OBJVERSION Incompatible instance and template versions B 19 Miscellaneous Fatal Exceptions FERR TTFENGINE DEAD engine failed to start FERR MAXEXCEPT many exceptions FERR TTFENGINE NODIE TTF engine failed to ter minate FERR_TASKSTART Unable to start required task FERR_MSGSYSSTART Unable to start messag ing system FERR_FFSSTART FERR_FONTERR Unable to start flash file system Unable to use built in font FERR DECOMPRESS Decompression error FERR NATIVEOBJECT Native objects not supor ted BADINIT Initialization error B 20 Fatal Qlarity Foundry Exceptions FERR POSTWINMSG Unable to post Windows mes sage FERR WINSYNC Unable to synchronize to design tool FERR NOFINDOBJ FERR BADGUI Unable to find object given by design tool Ilegal design tool request FERR_SOFTTERM Executing soft termination request FERR_APIRESET Application requested soft ter min
29. drawn Rather than specify your own value for this parame ter you should use either a value created by the PC develop ment tool s border editor and stored in the _stylemap array or you should use value returned from the _CreateBorderStyle function drawFlags Flags which modify how the border is drawn See the description below Description This API allows objects to draw complex borders with ease To use this function specify the boundary rectangle for your border as well as a border style In general you should use either _CreateBorderStyle to create a border style or you should pass in a value that was stored in the global array _styleMap this array is only available for workspaces created using the PC development tool This style defines such things as whether the border is flat or 3d the border width the corner radius etc The drawFlags parameter is one or more of the following values combined using the OR operator OptoTerminal Programmer s Reference Manual BDR_FILL Fill the interior of the border rectange with the current background color BDR_WIDTHHEIGHT If specified the x2 and y2 parameters represent the width and height of the border rectangle Otherwise x2 and y2 are the right and bottom edges of the border rectangle BDR_CLEARCURVES For rounded borders this flag removes any drawing that may have occurred in the rectangle specified by x1 yl x2 and y2 but outside the corner radius i e
30. else statements are optional There is no limit to the number of elseif clauses that can be added to the if statement Example dim x as integer if x 10 then x x 1 lseif x 10 then 2 else 2 endif 2 14 Looping and Leaping 2 14 1 For Next loops Syntax for lt name gt start expression to gt stop expression step lt expression gt OptoTerminal Programmer s Reference Manual 5 2 next Description The loop executes starting with lt name gt start expression and increments lt name gt by the amount specified in step until lt name gt is equal to stop expression Step may be positive or negative If no step is specified lt name gt is incremented by 1 When lt name gt lt stop_expression gt the loop executes for the last time If lt name gt has a validation function it is called each time through the loop When the loop terminates lt name gt will have been incremented or decremented beyond lt stop_expression gt In the example below the final value for countdown is 1 Also stop expression is evalu ated each time through the loop If stop expression is complex or involves a function call and the value of lt stop_expression gt does not change it is recommended that you store the value of lt stop_expression gt in a vari able and use tha
31. gt reference to anytype flags as font flags section 4 7 1 page 53 GetBinaryResource getbinaryresourc byte resourceID as integer returns gt section 4 18 24 page 94 GetBitmapSize getbitmapsize width as reference to integer gt height as reference to integer bmp as bitmap section 4 6 13 page 48 GetBytes getbytes tobreak as anytype boolean returns byte bigendian as gt section 4 10 4 page 72 GetCapture getcapture obj as objref returns integer section 4 13 2 page 76 GetChildren getchildren contobj as objref returns objref section 4 3 6 page 42 GetComMessageSource getcommessagesource returns comm section 4 1 4 page 36 GetContainer getcontainer obj as objref returns objref section 4 3 5 page 42 GetCurDir getcurdir returns string section 4 16 4 page 79 GetDirEntry getdirentry index as integer returns string section 4 16 5 page 79 GetEllipseSize getellipsesize maxleft as reference to integer gt maxright as reference to integer maxup as gt reference to integer maxdown as reference to gt integer a as float xfocal as float yfocal gt as float theta as float gamma as float flags gt as ellipse flags section 4 6 17 page 50 GetEnableInfo getenableinfo obj as objref eval as enable info gt returns boolean section 4 3 7 page 42 GetException getexce
32. pad LEDs The cmd parameter of type led cmd is a defined type with the following legal values LED ON Turn on the specified LED LED OFF Turn off the specified LED LED TOGGLE Toggle the state of the specified LED 4 18 10 GetTime Syntax gettime day as reference to integer gt month as reference to integer dig2year gt as reference to integer dotw as reference gt to weekday hour as reference to integer gt minute as reference to integer second as gt reference to integer Parameters day An integer to receive the current day of the month month An integer to receive the current month dig2year An integer to receive the last two digits of the current year Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 86 dotw A variable of type weekday see below to receive the current day of the week hour An integer to receive the current hour military time minute An integer to receive the current minute second An integer to receive the current second Description This function returns the current time as maintained by the real time clock hardware The variable dotw is of type weekday which is a defined type with the follow self explanatory legal values SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY 4 18 11 SetTime Syntax settime day as integer month as integer gt dig2year as i
33. toset as section 4 10 3 page 72 byte bigendian as boolean GetAvailFilespace getavailfilespace returns integer section 4 16 1 page 78 getbdffontmetrics maxleft as reference to integer gt maxright as reference to integer maxup as gt f to int to GetBdfFontMetrics S PU i ion Cee LR diae section 4 7 3 page 56 integer xnextline as reference to integer gt ynextline as reference to integer font as gt bdffont flags as font_flags Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 116 OptoTerminal Programmer s Reference Manual Function Syntax Reference GetBDFTextFit getbdftextfit counts as reference to integer gt multiflags as reference to multiline_flags gt xpos as reference to integer ypos as gt reference to integer widths as reference to gt integer heights as reference to integer gt xoffsets as reference to integer yoffsets as gt reference to integer font as bdffont data as gt reference to sametype start as integer length gt as integer wordbrks as reference to sametype gt linebrks as reference to sametype flags as gt font flags section 4 7 2 page 54 GetBdfTextSize getbdftextsize width as reference to integer gt height as reference to integer xoffset as gt reference to integer yoffset as reference to gt integer font as bdffont data as
34. which means that x2 y2 might be above and to the left of x1 y1 The handler should normalize these coordinates if necessary before calculating the initial position and size of the object A typical handler for a rectangular object will normalize 1 1 and x2 y2 if necessary set the values for local properties that indicate position size and parent call Tool_Persist for all modified properties and then call the object s MSG_INIT handler to handle the object initializa tion For more information on these messages and their handlers refer to Chapter 10 in the OptoTerminal Qlarity Foundry User s Manual Message MSG_TOOL_DELETEOBJ Description This message is sent to an object in the GUI development environment just before the object is deleted This allows the object to notify other objects that it is being removed from the workspace so other objects can respond appropri ately Handler Format func lt name gt handles MSG_TOOL_DELETE endfunc OBJ Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 3 8 Special Messages This section describes messages that are unique or that do not fit into another message category Message MSG_ERROR Description This message is issued by the system software if an excep tion remains unhandled after all possible enclosing check error on error blocks hav
35. 10 GetSysFontCharacters Syntax getsysfontcharacters font as sysfont gt facenum as integer bRange as unibyte gt eRange as unibyte returns unibyte Parameters font The sysfont resource facenum The number for the desired face in a ttfont resource typi cally 0 bRange The first character to be checked for in a font Character codes greater than bRange but less than eRange are also checked eRange The last character to be checked for in a font Character codes less than eRange but greater than bRange are also checked Description GetSysFontCharacters returns a unibyte array indicating the existing character codes between bRange and eRange inclusive in a font 4 7 11 GetSysTextSize Syntax getsystextsize width as reference to gt integer height as reference to integer gt xoffset as reference to integer yoffset gt as reference to integer font as sysfont gt facenum as integer ptsize as integer gt data as reference to anytype flags as gt font_flags 61 Parameters width An integer to receive the width of the text box height An integer to receive the width of the text box xoffset An integer to receive the horizontal offset from the upper left corner of the rendered region to the origin of the first character yoffset An integer to receive the vertical offset from the upper left corner of the rendered region
36. 71 4 10 3 ErombBytes uiid de RE EO eer e Re t e EE D o ERAS 72 4 10 4 GetBytes eoa tee ete e pa RU e er o tease tied 72 410 5 TeOWer Case 72 4 10 6 UpperC ase cie to t rro nO PR GE ed on pU pps RE 73 4 11 Math Functions ete ep n epa ta diete ise e esie e eR 73 n eeteetielipe tentem 73 4 112 COS cene ui ERN e e t USE 73 4 11 3 e a ROTE OO RO ING E t E Update aum 73 AV VA Cg C R 73 A VAS A608 ian nBpHEID sucusci ses es sopdesscesies GRE IDR GU UU ERRERRRUN BHO 73 ATEGO XCIM M 73 4 11 7 e et e p Nue nae nm D RO 73 AVL SEXP cesses ete eet eae ade eet LO ete C E bei etit de 74 AVVO Enzo rene DROPPING ep OD anie 74 AVVO C 74 4 12 User Message Punctions apt pte e RED OO ETE CI Nee CO RECTE t itt 74 4 12 1 UserBroadcastMsg uc bel OCA bete e ete tad e E Heed dead 74 4 12 2 teret egeret RE GR E 74 4 12 3 EO ERU Het PUR Mi wien inom E RU RE ERR 75 4 12 4 FakeKeyMSg ases e PO e e SE E
37. 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual numerat value 1 lt name_2 gt enumeration name as name 1 gt gt value 2 gt 1 NOTE The keyword enum can be substituted for enumerate Example numerate mysize as small 1 medium gt 2 large 3 enum stooge as larry curly moe shemp dim favorite as stooge Description An enumeration allows you to define a data type that has a restricted set of values Any variable declared with an enu meration type can only hold the values defined in the enu meration The default value of an enumeration is the first value that it defines Numeric integer values can also be given to each enumeration item Comparisons such as greater than or less than can be used between variables of the enumeration type In the example above the variable favorite can only be assigned the values larry curly moe and shemp 99 66 2 6 3 Start Type Syntax starttype lt name gt as lt data_type gt lt namel gt lt valuel gt lt name2 gt lt value2 gt etc endtype Example starttype control char as byte STX 0x02 ETX 0x03 ACK 0x06 AK 0x15 endtype Description Starttype is similar to an enumeration The difference is that the items in a starttype must be initialized to a value and can be used in any mathema
38. AutoDoc are used to document Qlarity software elements and are described in the OptoTerminal Qlarity Foundry User s Manual Regardless of which type of comment you use it is ignored by the compiler 2 4 Naming of Identifiers Reserved keywords may not be used as object variable or constant names in Qlarity Identifier names must begin with any letter A through Z or the underscore character _ After the initial character any alphanumeric character is legal and names may optionally end with a or character Identifier names and keywords in Qlarity are not case sensi tive Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 8 OptoTerminal Programmer s Reference Manual 2 5 Built In Data Types Data Type Description Range Data types are used to tell the compiler how a specific vari Any type is able or property will be used A variable must be given a anytype allowed only type when it is declared The following built in types are allowed in API supported functions Aggregate Array of Bytes Data Type Description Range pue Enc A 32 bit signed 2 147 483 648 to P value Styleman 22 bit signed 2 147 483 648 to 3 402823 38 to whole number 2 147 483 647 float A 32 bit floating 3 402823e 38 small point number est positive float is 2 r Defined D T 1 175494351 38 9 sE
39. Dereference Operator not or NOT operator amp AND operator Operator Description or or OR operator This operator allows access to object proper ties and methods from outside the object The xor or XOR operator dot is placed between the object name or ref erence and the property or method that will lt Less than or equal be accessed gt Greater than or equal to 2 10 5 Miscellaneous Operators lt Less gt Greater than Line Continuation Equals operator inti Operator Description lt gt Not equal to This construct is used to continue a statement gt on the next line if it is too long This increase the readability of your code Strings enclosed in double or single quotes e g Hello world Operator Description Mn Newline character Nr Carriage return Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Operator Description Represents a hexadecimal value where each is 0 through 9 or A through You must xDD Wm use two hexadecimal digits for example x00 not X0 not XA and so on NN Backslash character X Quotation marks Vi Apostrophe 2 11 Casting It is possible to convert a value from one numeric data type to another While Olarity will automatically convert data types when necessary it is
40. Drawing EXCeptornSc aus ima e tete p REP ERU RE D HU E Ee SER Mg eet P Seah er et 105 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Vii B 6 Array Exceptions aee e el e ip er bai et Ee Hoe e Nesters Aaa cu 106 B7 Z OrderzBxceptions i eei i piatto dapidus 106 B 8 Miscellaneotis EXceptions eee teer P ER RI Are dh Re ERR EN ERE etre e e es 106 9 Communications Networking Exceptions eeeeseeseseeseeeeeeee iia n a I EE E e R T 106 B 10 Math Exceptions itin e te da ee d ip v t d RP AESA 107 B 11 Flash Write Exceptions ies rtt ee tp p i er rr 107 B 12 File System PAY Ae B caa ARE RE RUE EL REEL BERE RU ER RE 107 B 18 Compiler Error EXCeptions uc git iot e e a RU I ERR Reg E R 108 14 Fatal ct ca cud Heu Rr ca dye oe bna ed de at 108 B 15 Fatal Flash Exceptions ito tei e eg t er ere dr dede 108 B 16 Fatal Initialization Exceptions i t da dua 109 B 17 Fatal Message System Exceptions ier eed pe ei Ped eee Se dE RH ela Cip Rep erede 109 B 18 Network Fatal Exceptions uec d dee ete Bove ret e eheu d us epa ct Aene sva 109 B 19 Miscellan
41. ED te pe T c te t eint 57 4 7 6 GetETEEextS1ze 5 i ete eter etse te HP RERO TR det uel E 59 4 7 7 Get LE TEEontMetrics ier d PR rer ETE UR D ER Peg et 59 4 7 8 Draw LTP TOR is E 60 479 SetLEFAngle eco Hem ri HERR DO GU DS Cae a 60 4 7 10 GetSysFontCharacters 4 rade etm t ter ER id ei t Y e a b te due SS 61 47 11 GetSysTextSize is duet retia ep en n RH Oe iere 61 47 12 GetSysTextFit ted etie dete E oe E asad C HR RE T HR ERE Ee 62 4 7 13 GetSysFontMetrics aep e E To RE a E e o iR e quete 63 ALT U4 Text iie ettet tee d eie v d Hae er ca CRIT ERR 63 4 7 15 Draw SyS unte erem 64 4 3 Controlling the Speaker s ERI b EO E ER Hd ER RT ats 65 4 81 PlayNOte ene ep et e e NR UB aed m P nU 65 4 8 2 e ertet ete De vt p ne EI ebat 67 4 8 3 Play Soundin eg egi dus 67 48 4 PlaySoundNotfy 4 eee ete te ut nde 67 4 85 StopSpkr eoe donee eR e qr epe Read andi 67 4 86 SetVolume dde ROB ee RO ree te n RE ER a eV dee E e de 67 4 9 Array and String Functions eine een em pe ii e sie 68 4 921
42. KEY M KEY HYPHEN KEY N KEY PERIOD KEY O KEY SLASH KEY P KEY 0 KEY Q KEY 1 KEY R KEY 2 KEY S KEY 3 KEY T KEY 4 KEY U KEY 5 KEY V KEY 6 KEY W Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 103 Key Codes Key Codes KEY_X KEY_LCASE_L KEY_Y KEY_LCASE_M KEY_Z KEY_LCASE_N KEY_OPEN_BRACKET KEY_LCASE_O KEY_BACKSLASH KEY_LCASE_P KEY_CLOSE_BRACKET KEY_LCASE_Q KEY_CARET KEY_LCASE_R KEY_UNDERSCORE KEY_LCASE_S KEY_GRAVE KEY_LCASE_T KEY_LCASE_A KEY_LCASE_U KEY_LCASE_B KEY_LCASE_V KEY_LCASE_C KEY_LCASE_W KEY_LCASE_D KEY_LCASE_X KEY_LCASE_E KEY_LCASE_Y KEY_LCASE_F KEY LCASE Z KEY LCASE G KEY OPEN BRACE KEY LCASE H KEY PIPE KEY LCASE I KEY CLOSE BRACE KEY LCASE J KEY TILDE KEY LCASE K Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 104 OptoTerminal Programmer s Reference Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 APPENDIX EXCEPTION LIST This appendix lists the names and associated descriptions of all possible exceptions All non fatal exception names begin with the prefix EXCEPT_ B 1 Special Exceptions EXCEPT_OPENFACE EXCEPT_MISSCMAP Unable to initialize requested TTF face No appropriate TTF char te
43. Msg have a boolean parameter that determines whether the current message processing is suspended while the user message is handled by the messaging system Passing a value of true will suspend the current processing until the user message has been processed Processing of the sus pended message then resumes at the statement following the API call to send the user message Passing a value of false in this parameter causes the message to be enqueued as any other message Any exceptions occurring during immediate handling filter up to where the message was initiated All user messages carry a single integer parameter that can be used for any desired purpose The integer is passed as a parameter to the particular API function and is received as a parameter in the handler function 3 5 3 Handlers for User Messages Description This message indicates that a user message named lt msg_ name gt has been sent Handler Format func lt name gt lt intdata gt as integer gt returns boolean handles msg_name endfunc Parameters lt intdata gt An integer that can be used for any desired purpose The meaning of the return value depends on how the mes sage was sent as follows Broadcast The return value is ignored User A return value of true kill message false continue Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 28 Direct If immediate processing
44. Phone 800 321 OPTO 6786 80 To check the attributes of the file logically AND flags with the appropriate value and check to see if it is equal to that flag ie flags AND FILEINFO ISOPEN FILEINFO ISOPEN If the path included in name begins with or it starts with the root directory otherwise it is relative to the current directory 4 16 8 OpenFile Syntax openfile name as reference to byte gt flags as file flags returns filedesc Parameters name A string containing the name possibly including path of the desired file flags A combination of the following values logically ANDed together FILE_READ Open file for reading if FILE_WRITE is not specified FILE_NO_CREATE is automatic and FILE_APPEND cannot be specified FILE_WRITE Open file for writing FILE_TEXT Open file in text mode FILE_BINARY may not be specified FILE_BINARY Open file in binary mode FILE_TEXT may not be specified FILE_NO_CREATE Do not create the file or destroy old file contents it must exist FILE_APPEND When opening a file for writing do not destroy old file contents and adjust file position to be at the end of the file OptoTerminal Programmer s Reference Manual Description This function opens a file for accessing the data and returns a file handle used to reference the file in other function calls When opening at least FILE READ or FILE WRITE must be specif
45. Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 16 4 GetCurDir Syntax getcurdir returns string Description This function returns a string containing the current direc tory 4 16 5 GetDirEntry Syntax getdirentry index as integer returns string Parameters index The index of the desired directory entry see below Description This function lists the contents of the current directory If index is 0 the first entry in the current directory is returned Subsequent calls to GetDirEntry with index set to 1 return subsequent entries in the directory empty string is returned if no more entries are available If the file system is accessed with other API function calls that alter the file system or current directory such as ChangeCurDir GetDirEntry 0 should always be called before GetDirEntry 1 or the returned results will be invalid Calling GetDirEntry N will return the Nth entry in the directory or an empty string if the Nth entry does not exist 4 16 6 EraseFile Syntax rasefil name as reference to byte Parameters name A string containing the name possibly including path of the file to remove Description This function removes the specified file from the file sys tem If the path included in name begins with or V it starts with the root directory otherwise it is relative to the current direct
46. RR ur edge 43 4 42 SendtoEtont 2 o Une ete te rt tite dre REIR EE 43 4 4 3 SendtoBack uen RED eet Ree e E IR e n ieu RM 43 AE NICE CLE 44 4 4 5 LOWE dite eee tinere D gre OR HUP RE 44 4 5 Redrawing Portions of the Display eese entree tette hne Enea NE ecu Put adeo Een etd o Pd 44 4 54 Rerender a Uem ir erit eg EH RR e Ee PR RE 44 LIRE Tp E o 44 4 5 3 Relocate tee d etie a ta e EE I dee beer 44 4 6 Painting to the Display ate RS EE UD EE ERR TESI e HERR SORA HIE RET e EYE 44 4 6 1 Set Transparent 1e o tenet e tis Pat e e ER a onda au edu 45 4 6 2 Use Transparent seitei ic eet et rte o s a ER d e RE ERR EGER 45 4 6 3 SetEgColor a eost eee euge po eget RE e E e EU D ERU RE 45 GRE ENIM 45 4 65 RGB oec eie ieatuc t Ete ee a e ned 45 466 SetPixel iiie tasa et rt iet teda ee te n EE Era etae vt p ee CO E dde Dn 46 4 6 7 DrawLme uova ettet AB Hea des died atte elas een a ep D RE dup gd 46 4 6 8 DrawBitmap ote tne t ee tee eet ti abe eto 46 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 6 9 DrawBitmapRegion eee td ee e a UR SE 46 4 6 10 GetObjPiximap io dere
47. Syntax netclose channel as comm Parameters channel The communications channel to be closed Description This function closes the channel associated with the speci fied comm resource which must have been obtained from a previous call to NetOpen 4 1 8 NetServerClose Syntax netserverclose channel as servercomm Parameters channel The communications channel to be closed Description This function closes the channel associated with the speci fied servercomm resource which must have been obtained from a previous call to NetServerOpen Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 38 4 1 9 ChangePort Syntax changeport channel as comm unibyte newport as gt Parameters channel The communications resource to modify newport The new local port number for the communications resource Description This function modifies a UDP communications resource that was previously obtained from a call to NetOpen The local port number for the communications resource is changed to newport ChangePort can only be called for UDP resources other resource types are not affected by this function 4 1 10 TransmitUrgent Syntax transmiturgent channel as comm data as gt reference to anytype Parameters channel The TCP communications resource to transmit the data data An array of any type that contains the data
48. Trim trim arr as reference to byte returns string section 4 9 5 page 68 typeof unique as reference to integer obj as gt TypeOf objref name as reference to byte returns gt section 4 18 13 page 86 typeval j handl j jref gt UnregisterMsgHandler Ree ME mud 3S as section 4 2 2 page 40 message msgparm as unibyte UpperCase uppercase str as byte returns string section 4 10 6 page 73 UseDrawCache usedrawcache useit as boolean section 4 6 19 page 51 UseTransparent usetransparent flag as boolean section 4 6 2 page 45 b d t tartobj bjref gt UserBroadcastMsg PG CR boda eats ae CE AM EE section 4 12 1 page 74 message parm as integer donow as boolean UserSendMsg usersendmsg startobj as objref msgnum as message gt section 4 12 2 page 74 parm as integer donow as boolean Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 122 OptoTerminal Programmer s Reference Manual Function Syntax Reference userdirectmsg startobj as objref msgnum as gt UserDirectMsg message parm as integer donow as boolean gt section 4 12 3 page 75 returns boolean 1 1 E y gt Val val value as r rence to anytype text as section 4 10 2 page 71 reference to byte tchd bl bl bool t gt WatchdogEnable dcc ee SOR a rere Mayo section 4 18 20 page 93 integer WatchdogReset watchdogreset sec
49. a a eR DDR dO nOeoadeuatecuniie 94 4 18 23 Del yMS s ic ei e eere te ter HE RP Fe psc ces Sethe anes en D RARI ceed 94 4 18 24 GetBimary Resource soi oie Rete diiGurtii eae ti edere nte pedea 94 4 18 25 SetArrayD at OR OU EAD NR E EET EROR DURER Ee HERD ARE RARUS 94 4 18 26 CreateC RC Table rot DERE GR UR NE HER UG Ee dE 95 4 18 27 CalculateCRQC ice tete tepida het EC Eb UE Ie Here vt a a seb eta out e eve i E pad 95 4 18 28 ZlibCompiress sedute rete eno areae eee iie pe 96 4 18 29 ZlibDecompress ue Ree b P E a o SERE EHE Adee dnd aida iu 96 418 30 SetPalette ot ptt t EE P ET LORS CO RR ER READ a 96 APPENDIX A BUILT IN CONSTANTS AND DEFINED TYPES e eeeee eere ternera tntn netta tasa teta tatnen stata tne 97 IT CODSEIDLE nine i petet c CHE rte aui ati upto 97 A2 TOOL Types c ee eire a ede ere ese eet pee eeu bel Avene 101 A 3 eine DD e RR eO pU Ds 101 101 APPENDIX 10 Coo du COH Buc 105 B 1 Special Exceptions 1 aig ae e m e Ge ERE EE AM OE ER 105 B 2 Memory Exceptions periere e ob o ete p p Ht ep ee e e ae e prende 105 B 3 Message oec ei tee tete sa ve Ee beetle EA Ec ee e eR kt M Ve adde cava 105 B4 Font Exceptions uiae eed ever eigene eod PEBID DRE 105 B
50. an object the system software must be informed that these properties have changed so that it can update its object data structures This is the purpose of the Tool Persist API function Tool Persist is a special API function available only in Qlarity Foundry that takes a property name as its only parameter If Tool Persist is not called when a property is changed by a message handler the change is not properly recorded in the application There fore Tool Persist must be called once for each changed object property in a tool message handler If you use Qlarity Foundry to create the object you have the option to create an object that already handles these mes sages in a manner appropriate for most types of objects 29 Refer to Chapter 10 Advanced Design in the OptoTermi nal Qlarity Foundry User s Manual for sample implementa tions of the functions If you elect to have Qlarity Foundry generate an object ready to operate in Qlarity Foundry handlers appropriate for most objects are included Message MSG_TOOL_ATTACH Description This message is sent by Qlarity Foundry when an object needs to be attached to a parent container usually due to mouse activity in the object hierarchy window The handler should call the Attach API function using lt newparent gt as the new parent Handler Format func lt name gt lt newparent gt as objref handles MSG_TOOL_ATTACH Attach me lt newparent gt
51. and may be set through the Qlarity API NAME character string the name of the object Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 ENABLED boolean indicates whether the object is eligible to process messages PARENT reference to a container the parent con tainer for the object CHILDREN ordered list of object references the list of objects attached to the container maintained in 7 order see section 1 4 XPOSITION integer the horizontal displacement in pixels from the origin of the object s parent container Positive values indicate displacement to the right YPOSITION integer the vertical displacement in pixels from the origin of the object s parent container Positive values indicate downward displacement XSIZE integer the width of the object in pixels YSIZE integer the height of the object in pixels ORIGINX integer the x coordinate of the top left pixel in the container relative to the parent container ORIGINY integer the y coordinate of the top left pixel in the container relative to the parent container These attributes are identical to the attributes of an area type object except for the list of children The position and size of the container are accessible through the Relocate and Resize API functions The enabled status of an object is accessible through the Enable API function and the par ent and children
52. attributes can be manipulated with the Attach API function and the Z order change functions 1 3 Event Processing Qlarity is event driven which means that instead of one long linear program being run that has constant control of the terminal relatively short and independent sections of code are run in response to specific events These code sec tions are called event handlers Typical events include a timer tick a keypad press or release a touch screen press or release or a serial character receive In Qlarity event handlers can be defined as object methods or global functions that are registered to handle a given OptoTerminal Programmer s Reference Manual event Events are sent through the message handling system see section 1 5 Message Handling System 1 4 Z Order Z order describes front to back ordering which is the same as the object hierarchy ordering On a two dimen sional display where X denotes left to right spacing and Y denotes top to bottom spacing the Z axis extends out nor mal to the plane of the display Thus Z ordering is the implied third dimension on the display allowing objects to be in front of or behind other objects 1 5 Message Handling System When an event occurs the system software firmware and or hardware drivers generate a message indicating that the event has occurred When a message is generated it is passed through the message handling system located in the
53. beni dm ende e dide 4 1 5 Message Handling Syste pret do e t t p tet tees e eee Pire ee iuter 4 1 541 Broadcast Messages oet eH dp be pre t De egest oett 5 1 5 2 Area MESSAGES cer hr b e pt D o ita tee eet dust pede ebat 5 15 3 det ten pte e tede tie E iore ne 5 15 4 Registered Messages eoe e pe tie Rn ree deed el i 5 159 5 User MeSSages eee ue ea e eed ne t PEIUS er EE es i e PER 5 1 5 6 Direct M SSageS snae eie ple rte ne dta PE 5 1 577 Tool Messagesy tse tee eina ad d te in e e e e eee 5 1 5 8 Handling Exents aui edt tte teu ee re e d ie tp eet omens 6 CHAPTER 2 OLARITY LANGUAGE SYNTAX e ei 7 2 1 Olanity Statements dete eee ee eh oet et Ae te re dites 7 2 2 Space eee RD nee e eee hu E Qu HUE 7 2 3 COMME NS me rmi 7 2 4 Naming of Identfiers io god ene eee pde ete ER Pe PU Re Ra aa 7 25 Built In Data e tp t e oct et i tette eite ee etes 8 2 6 Us r Detined Data dau e te endete ue t E T eil 8 PESE GIC E 8 2 6 2 Enumerationss osea littl has etn eaves ien dip nte adatta eire tbe 8 20 3 b I 9 2 7 Matiables ees n RI n e d d en 9 2 7 1 Declaration ettet eee eoe ee e e eain meditatio
54. breaks spaces tabs etc linebrks An array of the same type as data that determines which characters to treat as line breaks newline form feed etc flags A value of type font flags that determines how the text will be rendered Description This function tries to find the best text fit for data A good understanding of the GetSysTextSize and DrawSys Text functions should prelude attempts to use this function The parameter flags is of type font flags which is a type that can have any combination of legal values 4 7 13 GetSysFontMetrics Syntax getsysfontmetrics maxleft as reference to gt integer maxright as reference to integer gt as reference to integer maxdown as gt reference to integer xnextline as gt reference to integer ynextline as gt reference to integer font as sysfont gt facenum as integer ptsize as integer gt flags as font flags Parameters maxleft An integer to receive the maximum distance in pixels from a character origin to the left edge of any character in the font maxright An integer to receive the maximum distance from a charac ter origin to the right edge of any character in the font 63 maxup An integer to receive the maximum distance from a charac ter origin to the top edge of any character in the font maxdown An integer to receive the maximum distance from a charac ter origin to the bottom edg
55. changing settings during run time operation By creating a custom terminal configuration facility in an application any desired subset of the terminal settings and other application specific settings can be made available to the user 4 18 15 GetSystemSetting Syntax getsystemsetting cmd as syscmd var as gt reference to anytype which as gt syscmd_readfrom Parameters cmd A value of type syscmd see section 4 18 14 SetSystem Setting that determines which terminal control setting will be returned in var value The variable that will receive the value of the system setting being retrieved which A value of type syscmd_readfrom that determines the mode of the setting that is read Description This function retrieves a value for the terminal setting spec ified by cmd This parameter is an enumerated type described in section 4 18 14 SetSystemSetting There are three versions of each setting the current setting the pending setting and the saved setting The current set ting is the setting that the terminal is using The pending set ting is setting that was changed using SetSystemSetting and is awaiting a SYS SAVE command in order to be saved to the flash The pending setting may or may not be the current setting The saved setting is the value of the setting that is saved in the non volatile flash memory Each of these values is accessible through the
56. cheer Rte e un a P RO ro HT ERREUR RE Es 20 2 21 5 dtSetfile egit et op e ei tete po e au eda 20 MAII 20 2 2 T imei cim ur abe 20 2 2 1 8 4S TPBullderApp pte tee let scene dep RR ARE RR Ed 20 2 219 tendhle oe eb eap P que Pip qn 20 CHAPTER 3 MESSAGES AND MESSAGE HANDLER eentnntn tns n ene tn tatnen stata ente tatnen esee tata enean ene 21 31 Broadcast Messages eise o nte et a ted RR ED ERR or dieu tt 21 3 2 Area aede de DR OU eR EET Ie eR Ep EE EGO tb epe P E 21 3 3 Draw Messages este ode D OR UR DD RE Neg 23 3 4 Registered Messages ie SIE eT ute i REG Ee a E ILE ate 23 3 5 User Messages i ove HR OR E e EI te OO ERES GURCU UE 27 3 5 1 Defining User Messages c ce tete EE e ie pea pel ge YR Fue IRE ra eere 27 3 5 2 Sending User Messages isses eei init e teer n aed n e pe aderit 27 3 35 23 Handlers for User Message Sinore ei IER ERR E E Tee Re SERRE RU SERES D rte eva Haass 27 3 6 Direct Messages innne ee e ut i t itp OO HI E Hp e ieu 28 3 77 Tool Messages ie ed et e e et dots UR EE P ANNO ER ERR DR HER EE oh CREDI ERR 29 3 8 Special MesSag s a5 eode oue d tee iecit tee p ep o t dire ed 33 CHAPTER 4 QLARITY API FUNCTION REFERENGE
57. code such as inside an on error block Once information about an exception is retrieved via a call to GetException the exception is removed from the exception queue system handling for the exception is terminated If the user excep tion handling code is insufficient the exception can be returned to the exception queue by calling Rethrow Important If you do not call GetException in an on error clause the exception remains in the exception queue A MSG_ ERROR message is sent through the messaging system if there are still errors in the queue at the end of a message 4 14 3 Rethrow Syntax rethrow Description This function returns an exception to the exception queue after it has been removed by a previous call to GetException Rethrow is typically called inside error handling code such as inside an on error block when an exception is retrieved that is not handled in that block of code 4 15 User Non Volatile Configuration Functions The user configuration block is a nonvolatile section of sys tem memory that can be used for any purpose Typically it is used to store configuration data that is specific to the user application Data written to this memory is persistent across power cycles Up to 8 kilobytes of data can be stored in the user configuration block Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 78 4 15 1 ReadUserConfig Syntax returns gt read
58. definition of an ellipse is that the sum of the distances from the focal points to any point on the ellipse is a constant In this case the constant is defined as 2 a The elliptical arc is drawn counterclockwise from theta to gamma The simplest way to draw a closed ellipse is to draw a circle Set theta to 0 and gamma to 2 PI is a constant defined as 3 14159 A circle is an ellipse with both focal points at the center To draw a circular arc set a to the desired radius and set xfocal and yfocal to 0 To draw the complete cir cle also set theta to 0 and set gamma to 2 PI Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 50 Center lt xoffset gt yoffset gt A gt b J ZX ios Secondary NS focal point AN Primary focal point Primary focal point vector Y length a The flags parameter has type ellipse flags which is an enumerated type with the following legal values ELLIPSE NORMAL Draw the specified arc in the foreground color ELLIPSE FILL Draw the specified arc in the foreground color and fill the arc with the background color If only this flag is specified the boundaries of the filled region are the arc and a line segment connecting the endpoints of the arc Also known as ELLIPSE CONNECT ENDS ELLIPSE CONNECT CENTER Draw li
59. drawpolygon xpoints as integer gt ypoints as integer flags as poly_flags Parameters xpoints An array of integers containing the x position for each point of the polygon relative to the calling object s parent ypoints An array of integers containing the y position for each point of the polygon relative to the calling object s parent flags A value of type poly flags see below that determines how the polygon will be drawn Description This function draws a polygon by connecting line segments between each of the points defined in the xpoints and Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual ypoints arrays The flags parameter has type poly flags which is an enumerated type with the follow ing legal values POLY NORMAL Draw the outline of the polygon in the foreground color Do not fill the polygon POLY FILL Draw the outline of the polygon in the foreground color and fill it with the background color POLY NOCONNECT Do not connect the ends of the polygon it is a line the POLY FILL flag is ignored The polygon may have intersecting regions if desired 4 6 16 DrawEllipse Syntax drawellipse xoffset as integer yoffset gt as integer as float xfocal as gt float yfocal as float theta as float gt gamma as float flags as ellipse flags Parameters xoffset
60. error B 8 Miscellaneous Exceptions EXCEPT ZLIB ADLER Missing or partial adler for compressed data EXCEPT_INVAL_SIZE EXCEPT_PLAYNOTE Invalid size Unable to play note EXCEPT_TFT_CONTRAST TFT displays do not support a contrast value EXCEPT_BADPERSIST Unable to persist a non variable B 9 Communications Networking Exceptions EXCEPT BADLEDNUM Invalid LED number EXCEPT NORETHROW No exception to EXCEPT NOCHANNEL EXCEPT NOFREECHANNEL Transmission channel not setup No free transmission channel EXCEPT CHANNELUSED Transmission channel is in use rethrow EXCEPT NOFINDOBJ Unable to find object by name EXCEPT_NOFINDPROP a by name EXCEPT_NOVARSTRING Unable to stringify given variable EXCEPT_SEND Transmission error EXCEPT_BADIP Bad IP address EXCEPT_NOTALLOWED Permission Denied EXCEPT_BADPROPVAL Ilegal value given by string EXCEPT_INVAL_OBJREF Invalid objref possibly empty EXCEPT_BADSERIAL EXCEPT_BADSERIALSET Bad serial port identi fier Unable to set serial port EXCEPT_BADSET Attempt to set non set able variable EXCEPT_UNSUP_ON_PORT Not supported for this serial port EXCEPT_HWARE_UNAVAIL Hardware unavailable Opto
61. ert RR er nu epe ee bae nuire edt 47 4 6 11 DrawPixmap z 23 Ht EROR RH RERO ae rr e EE 47 4 6 12 DrawPixmapReglo0n iiit eet e ee EID Pe IERI EE a UE 47 4 6 13 GetBitmapSize iude et dt ae ae te d e Ee V e se d b er cp e id RIT ERR 48 4 614 DrawBOX esee ven gl o ge e OU TR HR REN Pp e 48 4 6 15 DrawPolygon zu nie etr erret ee UP EORR OR V EHE RITU I 48 4 66 DrawEllipse re RO o ge RH a TH ep pp nti 49 4 6 17 GetBIlipseSize tpe d ee Rd eH p Ree E e et 50 4 6 18 GetScreenPixmap diete eee i t d Hr E Ue I eti sa a i las a ea idee pn 51 4 6 19 UseDrawCache ete eter eR a RE IU HI ER Mia 51 4 6 20 IgnoreDrawCache iii 2 n netu e et e C ER VR RU uei ie unes 51 A621 DrawBotder cni ee e Hee tes epe da gt et toons qe E E RIT E 52 4 6 22 GetObjPixmapRegion 52 4 7 Rendering Text on the Display aeter de I REX ER Ee REN EUER e cuss Ee y YR buted 53 ALTA GetBdfTextSize sci nce tace mem teet eio c p aD Rep ne 53 47 2 GetBDETextFit inet e ete ipei ecd bed ee ete vt navi e e e bee EORR 54 4 7 3 GetBdfFEontMetrics ote tet e e e DU RP Rr ene a edita erp i eet 56 4 7 4 C 57 4 75 DrawBDE TextFit ertt e o euo
62. face in ttfont resource typi cally 0 ptsize The point size flags A value of type font_flags see section 4 7 1 that deter mines how the text is rendered Description This function returns important metrics for the font resource that can be used to determine values for parameters in calls to DrawTTFText It is very similar to the analo gous GetBdfFontMetrics API function 47 8 DrawTTFText Syntax drawttftext x as integer as integer gt width as integer height as integer gt xoffset as integer yoffset as integer gt font as ttfont facenum as integer gt ptsize as integer data as reference gt to anytype flags as font flags Parameters x The x position of the upper left corner of the rendered region relative to the calling object s parent ty The y position of the upper left corner of the rendered region relative to the calling object s parent width The width of the region to use for rendering OptoTerminal Programmer s Reference Manual height The height of the region to use for rendering xoffset The horizontal offset from the upper left corner of the ren dered region to the origin of the first character yoffset The vertical offset from the upper left corner of the rendered region to the origin of the first character font The ttfont resource facenum The number for the desired face in the ttfont resource ty
63. gt section 4 1 19 page 40 as reference to byte NetServerClose netserverclose channel as servercomm section 4 1 8 page 37 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 119 Function Syntax Reference netopen obj as objref prot as netprotocol gt NetOpen localport as unibyte foreignport as unibyte gt section 4 1 5 page 36 pag ipaddr as reference to byte jref 1 gt NetServerOpen netseryeropentob as objre prot as netprotoco section 4 1 6 page 37 localport as unibyte returns servercomm openfile name as reference to byte flags gt section 4 16 8 page 80 OpenFile file flags returns filedesc pag PlayNote playnote note as byte duration as integer section 4 8 1 page 65 y pag playnotenotify obj as objref parm as integer gt PlayNoteNotif section 4 8 2 page 67 note as byte duration as integer pag PlaySound playsound sound as audio section 4 8 3 page 67 y pag i j jref i gt PlaySoundNotify a obj as objref parm as integer section 4 8 4 page 67 sound as _audio Power power x as float exp as float returns float section 4 11 7 page 73 Raise raise obj as objref section 4 4 4 page 44 readarrayhandle data as reference to anytype gt dArrayHandle section 4 9 11 page 70 Rea y handle as A
64. have the same yoffset and thus will always line up properly Multiple flags may be specified by combining them with a boolean AND operation Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 54 Typically this function is called as a precursor to calling the DrawBDFText API function The width height xoffset and yoffset values obtained from this func tion call are used as parameters in the call to DrawBdf Text 4 7 2 GetBDFTextFit Syntax getbdftextfit multiflags as reference gt to multiline_flags xpos as reference gt to integer ypos as reference to gt integer widths as reference to gt integer heights as reference to gt integer xoffsets as reference to gt integer yoffsets as reference to gt integer indices as reference to gt integer lengths as reference to gt integer font as bdffont data as gt reference to sametype wordbrks as gt reference to sametype linebrks as gt reference to sametype flags as gt font_flags Parameters multiflags An array of type multiline_flags returned by the function giving information on how each line was fitted see below xpos An array of integers returned by the function that tells the relative horizontal offset for where each line of text should be drawn An array of integers returned by the function that tells the
65. integer height as reference to integer gt returns color Parameters width Variable in which the width of object pixmap is to be stored height Variable in which the height of object is to be stored Description This function is used to retrieve the pixel map for an object The pixel map indicates the individual colors drawn in each pixel location for the object based on the size of the object given to the Resize function The returned array is a color of size width height indicating the colors drawn at each location in the object up to this point Thus the color drawn at pixel coordinate x y in the object with 0 0 being the top left pixel of the object is the color indi cated by the y width x element in the returned array 4 6 11 DrawPixmap Syntax drawpixmap x as integer as integer gt pixmap as reference to byte mapwidth gt as integer mapheight as integer 47 Parameters x The desired x position of the upper left corner of the pixel map relative to the calling object s parent The desired y position of the upper left corner of the pixel map relative to the calling object s parent The pixel map array mapwidth The width of the pixel map mapheight The height of the pixel map Description This function draws a pixel map The pixmap array must have a size of ma
66. is 0 zero elements Message MSG_TOOL_MOVEHANDLE Description This message indicates that one of the object s resize grips has been dragged in Qlarity Foundry The typical response to this activity is to resize the object although certain han dles may be associated with other object properties The handler should set object properties relating to size or whatever property is associated with the dragged grip call API functions to alter attributes in the system software usu ally done in property validation functions and call Tool_Persist for any property that has been modified Handler Format func lt name gt lt handle gt as reference to gt integer lt dx gt as integer lt dy gt as integer handles MSG_TOOL_MOVEHANDLE Peak endfunc Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 32 Parameters lt handle gt An index of the handle defined in the arrays in the MSG_TOOL_GETHANDLES handler If the handle type is CSR_SELECT lt gt and lt dy gt are zero If the handle number changes due to dragging change the value of the handle to the appropriate number lt dx gt The change in the resize grip s x position caused by the drag lt dy gt The change in the resize grip s y position caused by the drag Message MSG_TOOL_DRAGCREATE Description This message indicates that an object is being created by a click and drag operation in
67. is converted to a string identical to calling the API function Str on the property 4 33 SetObjProp Syntax setobjprop obj as objref name as gt reference to byte value as gt reference to byte Parameters obj A reference to the object with the desired property name A string containing the name of the property to set value The new value for the property converted to a string Description This functions converts the string in value to the correct data type for the specified property then assigns that value to the property refer to the Val function for conversion rules see section 4 10 2 4 3 4 Enable Syntax enable obj as objref flag as boolean Parameters obj A reference to the object to be enabled disabled Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 42 flag A boolean flag containing the desired status A value of true enables the object and a value of false disables it Description This function enables or disables an object according to the parameter An object must be enabled to receive messages and appear on the display 4 3 5 GetContainer Syntax getcontainer obj as objref returns objref Parameters obj A reference to a child object Description This function returns a reference to the parent container of the obj object 4 3 6 GetChildren Syntax
68. message Message MSG INIT Description This message is sent to all objects on system startup It is the first message generated in the system It allows each object to synchronize its system software attributes enabled parent position size etc with its properties and to perform other startup functions Do not rely on the order of reception for the init message don t assume others are already inited Handler Format func name handles MSG INIT 2056 7 endfunc MSG INIT handlers take no parameters and do not have a return value 3 2 Area Messages Area messages are associated with a given area or point X Y coordinate on the terminal display A message is first passed to the root container where it is possibly handled by global functions which then checks for any enabled chil dren that contain or overlap the area of the message This checking is done in Z order starting with the front most object If a child is eligible to receive the message the mes sage is passed to the child When the message is passed to a container object including the root container it first han dles the message then does a similar check for enabled chil dren that contain or overlap the message area After all of a container s children have received the message the handler in the container if any is called a second time In this man ner the message filters down through and back up the object hierarchy until all eligibl
69. object the container object first handles the message then passes it to each of its children beginning with the front most object In this manner the message filters down through the object hierarchy until all objects have received the message Refer to section 3 1 for a list of valid broadcast messages 1 5 2 Area Messages Area messages are associated with a given area or point X Y coordinate on the terminal display The message is first passed to the root container which checks for any enabled children that contain or overlap the area of the mes sage This checking is done in Z order starting with the front most object If a child is eligible to receive the mes sage the message is passed to the child When the message is passed to a container object it first handles the message then does a similar check for enabled children which con tain or overlap the message area In this manner the mes sage filters down through the object hierarchy until all eligible objects have received it Refer to section 3 2 for a list of valid area messages 1 5 3 Draw Messages A draw message is a type of area message that is processed in reverse Z order or back to front see section 1 4 7 Order Refer to section 3 3 for more information on draw mes sages 1 5 4 Registered Messages Registered messages are associated with system events such as a serial character receive or timer tick Event han dlers that process these messages a
70. objects behind the container and therefore hidden from receiving the message Message MSG SCREEN PRESS Description This message indicates that a touch screen press event has occurred Handler Format if handled by a container object global func lt name gt lt x gt as integer y as gt integer pass as boolean returns boolean handles MSG SCREEN PRESS coe endfunc if handled by an area object func name lt gt as integer lt y gt as gt integer returns boolean handles MSG SCREEN PRESS endfunc Parameters lt x gt The x location of press event with respect to the parent s origin lt y gt The y location of press event with respect to the parent s origin lt pass gt False if the container s children have not yet received the OptoTerminal Programmer s Reference Manual message and true if the container s children have already received the message Message MSG_SCREEN_RELEASE Description This message indicates that a touch screen release event has occurred Handler Format if handled by a container object global func name lt gt as integer y as gt integer pass as boolean returns boolean handles MSG SCREEN RELEASE endfunc if handled by an area object func lt name gt lt gt as integer lt y gt as gt integer returns boolean handles MSG_SCREEN_RE
71. occasionally useful to manually cast a value to a new data type You can cast values to the following built in data types integer float byte unibyte Additionally you can cast the keyword default to type objref To cast a value type the data type to which you want to cast and then enter the value to cast in parentheses You can use the casting operators as part of any legal expression Example Calculate the sum of two simulated dice diel integer 6 GetRandomNum 1 die2 integer 6 GetRandomNum 1 diceTotal diel die2 Casting is commonly used to allow integer literals to be used with bitwise operators such as the AND operator Calculate th components for a given color red green and blue gt The resultant values range from 0 to 7 rValue myColor byte OxEO 32 gValue myColor and byte 0x1C 4 bValue myColor and byte 0x03 2 Casting a value may cause a loss of precision if the target data type is incapable of expressing the original value For example the expression integer 6 7 produces the value 6 13 since integers cannot express fractional values and the expression byte 257 produces the value 1 since bytes can only express values from 0 to 255 You may cast the keyword default to any of the allowed casting data types The default value for integer float byte and unibyte is zero 0 You may also cast default to an objre
72. resource to draw Description This function displays a bitmap at the coordinate given The origin of the x and y values is at the top left corner of the parent container 4 6 9 DrawBitmapRegion Syntax drawbitmapregion x as integer as gt integer xoffset as integer yoffset as gt integer width as integer height as gt integer bmp as bitmap Parameters x The desired x position of the upper left corner of the bitmap relative to the calling object s parent The desired y position of the upper left corner of the bitmap relative to the calling object s parent xoffset The x position of the pixel in the bitmap to draw at x py yoffset The y position of the pixel in the bitmap to draw at width Number of pixels per row to copy from the bitmap Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual height Number of pixels per column to copy from the bitmap bmp The bitmap resource to draw Description This function prints a portion of a bitmap at the coordinate specified by x y The displayed portion of the bitmap is specified by xoffset yoffset width and height The location of the x and y values is relative to the top left corner of the parent container 4 6 10 GetObjPixmap Syntax getobjpixmap width as reference to gt
73. size If the array is increased in size then the new elements of the array are initialized to the default value for the data type assigned to arr 4 9 9 ArrayOperation Syntax arrayoperation arrl as reference to gt anytype arr2 as reference to anytype gt as ArrayOp Parameters 1 array variable that will receive the result of the array operation Depending on the operation to be performed this parameter may also be used as an input parameter to the function arr2 An array used in the operation How this parameter will be used is determined by the op parameter op Determines which operation to perform on the input array s Description This function performs one of several array operations based on the value of the op parameter The op parameter can take on the following values Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 70 ARRAY_CONVERT This operation converts arr2 to the same data type as arr1 and stores the result of that conversion in arr1 Most types of arrays can be converted This operation is particularly useful when you are developing a work space that uses both unicode strings and traditional byte strings and you need to convert between the two for mats ARRAY PALETTE Both arr2 and arr1 must be of type byte or type color Arr2 should contain 256 elements For each element in arrl the following assignment is pe
74. system software which determines who gets the message and in what order the message is processed An object must be enabled to process most messages This also causes area and container objects with non zero area to be drawn on the screen Disabled containers do not process most messages and therefore cannot pass those messages to their children attached objects Broadcast tool and direct user messages are processed by enabled or disabled objects Each message is processed to completion before the next message is examined and distributed Processing of the cur rent message is never preempted by another message except for certain user messages See Chapter 3 Messages and Message Handler Prototypes for more details There are seven different types of events classified by how each type is handled by the messaging system as follows Broadcast messages Area messages Draw messages Registered messages User messages Direct messages Tool messages generated only in Qlarity Foundry Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 1 5 1 Broadcast Messages Broadcast messages are sent to all objects regardless of enabled or disabled status in Z order A message is first passed to the root container which passes it to each of its children beginning with the front most object highest Z order When the message is passed to a container
75. that determines how the text will be rendered Description This function finds the size of a given text string and returns it in the variables passed as parameters The and height variables receive the width and height in pixels of the rendered region The xoffset and yoffset variables receive the offset from the upper left corner of the region to the origin of the first rendered character The parameter flags is of type font flags which is a type that can have any combination of following legal val ues other font flags settings are ignored FONT NORMAL Render the text horizontally with the text in the fore ground color and remainder of the region in the back ground color FONT VERTICAL Render the text vertically with the text in the fore ground color and the remainder of the region in the background color Most fonts that use Latin characters do not support this option FONT INVERSE Render the text horizontally with the text in the back ground color and the remainder of the region in the foreground color FONT HBASELINE Instead of calculating the standard width text fits exactly in this width calculate the baseline width multiple lines will always have the same xoffset and thus will always line up properly FONT VBASELINE Instead of calculating the standard height text fits exactly in this height calculate the baseline height multiple lines will always
76. using the RGB function see section 4 6 5 For grayscale displays the luminances of the selected col ors are automatically converted to grayscale This allows an application to run on either the color or grayscale display with little modification Since the grayscale conversion compresses multiple colors into each grayscale value the transparency settings may cause some differences in how the application is displayed The default foreground color is RGB_WHITE and the default background color is RGB_BLACK 4 6 1 SetTransparent Syntax settransparent newcolor as byte Parameters newcolor A byte specifying the transparent color Description This function sets the transparent color to newcolor for the current message handler This color setting persists until the message handler returns The transparent color is not drawn on the display allowing objects behind any transpar ent regions to remain visible 4 6 2 UseTransparent Syntax usetransparent flag as boolean Parameters flag A boolean value specifying whether transparency is enabled true or disabled false Description This function enables or disables transparency for the dura tion of the current message handler or until it is called again As transparency is disabled by default this function must be called at least once in each message handler that uses the transparency feature 45 4 6 3 SetFgColor Syntax setfgc
77. value OptoTerminal Programmer s Reference Manual Often when a message is handled by an object or function it is desirable that the message be terminated i e not passed on to other objects This is indicated by the boolean return value of the message handler If the handler returns true the message is terminated If the handler returns false then the message is allowed to propagate to the next eligible object in the hierarchy Some messages the draw message in particular cannot be terminated in this manner If a global message handler is defined it is considered to be a method of the root container It therefore will be called before the message is passed to any other object Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 2 QLARITY LANGUAGE SYNTAX The syntax of the Qlarity language is based on the BASIC programming language with extensions to handle objects allow structured programming and facilitate the develop ment of user interface applications When referring to language syntax the following notations are used Notation Description Language examples shown on monospaced font Any part of a statement in brackets is optional A word that appears in angle brackets lt gt lt gt must be replaced by an appropri ate name keyword or value 21 Qlarity Statements A statement is defined as a single line
78. which setting will be mod ified It is of type which is an enumerated type with the following legal values SYS_CONTRAST Sets the display contrast using a scale from 0 to 255 with 255 the brightest The value 1 may also be passed in to cause the current contrast value to be used Note that incrementing by one in the scale will not neces sarily change the contrast value and values returned by GetSystemSetting may not match what was passed into SetSystemSetting To change the contrast by one contrast increment use the SetCon trast function and then pass in 1 for the contrast set ting in this function to save to the flash Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 88 SYS_BACKLIGHT Sets the display backlight using a scale from 0 to 255 with 255 the brightest The value 1 may also be passed in to cause the current backlight value to be used Note that incrementing by one in the scale will not neces sarily change the backlight value and values returned by GetSystemSetting may not match what was passed into SetSystemSetting To change the backlight by one backlight increment use the Set Backlight function and then pass in 1 for the back light setting in this function to save to the flash SYS VOLUME For units that have an audio decoder this sets the unit volume using a scale from 0 to 255 with 255 the loud est The value 1 may also be passed in to cause the
79. 1 8 Exp Syntax exp x as float returns float Parameters x The exponent operand floating point Description This function returns e raised to the x power 4 11 9 Ln Syntax ln x as float returns float Parameters x The floating point operand Description This function returns the natural logarithm of x 4 11 10 Sqrt Syntax sqrt x as float returns float Parameters x The floating point operand Description This function returns the square root of x OptoTerminal Programmer s Reference Manual 4 12 User Message Functions 4 12 1 UserBroadcastMsg Syntax userbroadcastmsg startobj as objref gt msgnum as message parm as integer donow gt as boolean Parameters startobj First object in Z order to receive the message Only this object and its children will receive the message Specify a value of default to send the message to all objects msgnum The user message to send parm The integer parameter to associate with the sent message donow A flag to select preemption of the current message while the user message is processed Description This function sends the msgnum user message as a broadcast message it will go to all objects enabled or dis abled starting with startobj in Z order Any object with a handler for msgnum is eligible to handle the message Messages sent with this function cannot b
80. 1 OPTO 6786 98 OptoTerminal Programmer s Reference Manual Defined Type Values Defined Type Values PINO POLY_NORMAL poly_flags POLY_FILL PIN2 POLY_NOCONNECT di FIN GET_X gpio_pin PIN4 PINS SEDE PING GET WIDTH PIN7 osition info P GET_ORIGIN_X GET ORIGIN Y HW ETHERNET GET XGLOBAL HW TOUCH GET YGLOBAL HWEKEYPAD RESET_NORMAL HW_KEYBOARD RESET_ENTER_BL HW_TEMPCONTROL rstmode RESET_LOADAPP HW_CLOCK RESET_ENTER_POS HNGDISEEAY RESET TOUCH CAL hwinfo HW_DEFAULTAPP HW_MACADDRESS servercomm NULL_SERVER HW_AUDIOCODEC SYS SAVE HW GPIO HW CPU SYS CLEAR z SYS_CONTRAST HW_COMLIST SYS_BACKLIGHT HW_MEMORY SYS MODE HW_KEYPADBACKLIGHT SY 5 ORIENT HW POWER OVER ETHERNET SY S KBDRPTDEL AY KEYBOARD PRESENT SYS KBDRPTRATE keyboardcontrol KEYBOARD WRITECOMMAND SYS KEYRPTDELAY BYTE SYS KEYRPTPERIOD LED ON SYS KEYCLICK SYS KEYRPT ledcmd LED OFF SYS COMIBAUD LED TOGGLE ou multiline flags MULTILINE MASK BREAK MULTILINE NOBREAK MULTILINE SOFTBREAK MULTILINE WORDBREAK MULTILINE LINEBREAK MULTILINE MASK WIDTH MULTILINE PARTIAL WIDTH MULTILINE NONE WIDTH MULTILINE MASK HEIGHT MULTILINE PARTIAL HEIGHT MULTILINE NONE HEIGHT netprotocol NET TCP NET UDP NET RAW syscmd SYS COMIDATABITS SYS COMIPARITY SYS COMISTOPBITS SYS COMIFLOWCONTROL SYS COM2BAUD SYS COMODATABITS SYS COM2PARITY SYS_COM2STOPBITS SYS_COM2FLOWCONTROL SYS_IPADD
81. 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 107 EXCEPT_NOT_COMM Current message is not communications related EXCEPT SERVER COMM Cannot transmit on server comm resource EXCEPT TCPSETUPFAIL EXCEPT NO UDP SUPPORT Cannot open the requested TCP connec tion UDP protocol does not support this feature EXCEPT FLASHERASE Error occurred erasing block EXCEPT_FLASHWRITE Error occurred writing to flash EXCEPT_FLASHBADVERIFY EXCEPT_FLASHBADREAD Verification of written data to flash failed Unable to read flash EXCEPT_INVAL_COM Invalid comm resource B 12 File System Exceptions EXCEPT BADPORT Bad port number EXCEPT FFSNOSPACE Not enough space left in file system EXCEPT TCPRESET TCP connection reset EXCEPT_FFSNOEXIST File does not exist EXCEPT_TCPREFUSED TCP connection refused EXCEPT_FFSNODELROOT Unable to delete root directory EXCEPT_TCPTOOBIG TCP transmission buffer overflow EXCEPT_FFSBADFD File resource num ber is invalid EXCEPT_TCPTIMEOUT TCP transmission timed out EXCEPT_FFSENDOFFILE End of file reached without sufficient data B 10 Math Exceptions EXCEPT_FFSALREADYOPEN File is already open
82. Creating Instances of an Object To create instances of an object you give the instance a name and declare the name of the template from which the instance will be created The properties of the object instance are those defined in the template New properties may not be defined in the instance but initial values for the instance may be assigned inside the instance declaration using the init statement The methods of the instance are also those defined in the template You may override these methods by declaring a function inside the instance with the same name parame ters and return value as the method defined in the template This function replaces the template function for that instance only The code for the override function may call the template method if desired 12 2 Object Types There are three basic types of object templates non draw able objects area objects and container objects Each of these object types has certain built in functionality that helps the system software handle the object efficiently 1 2 2 1 Non Drawable Objects The non drawable object type includes objects that do not directly interact with the terminal display Examples include a keypad object not a touch key object and a serial com munications object Non drawable objects have the follow ing built in data that is maintained by the system software and accessible through the Qlarity API Application Pro gramming Interface NAME charact
83. HR E Rp UD REPE 39 421517 FREAD IER eet e up D D ede 39 4 1 18 Read ede pere re ea dc BO e etes BA e vt i e e aT ERR 40 41 19 NetSendDatagram 5 eese eo ene onion eani bete eue bete inire 40 4 2 Registering for Messages nice situa cbs suey Hn D ee E ct Des E HR Ee eR Unt ese EEK cu edv utr ete nae 40 42 T RegaisterMsgHandler 2 etin teen Rep ete a tene ie e E Cae t de e 40 4 2 2 UnregisterMsgHandler ets CER Rete P E HV Re S HIT ERR 40 4 2 3 RegisterKey eiue ere e doe eto p o sass e RR isl deste n 41 4 3 Mampulating Objects n t RE HERR I ERE UE TRU P EE I HH D EE HRS 41 4 31 GetObjrelt oae HERO ut e eH Ru dd D S RUE 41 4 32 GetObjProp tet beoe e De i eO Ee e e y peu edd 41 4 3 3 SetObJProp 3a utt reed ren eq ett bem eo d uere 41 4 3 4 Enable ueniet ut E RR HU RES oe chi Ra RR RR ah etl 41 4 3 5 GetContather e ett e p te RT D E I em RO bond eua aunt 42 4 3 6 GeiChnuldren iii dei eee Ee eR DDR EAR C ee Acdsee 42 4 3 7 GetEnabl lInfo ae Seen e ie eda e Pet rede ru 42 4 38 GetPos IMO sie iine Rt b UO EP EE PE HR E FIR HERD RE PE 42 4 59 SetOrigin qe o Rem e RR Op RU d P Re E 43 4 4 M mpulating Z Order 5 itat etui ttt eater pt ed deeem pev hie i teint ae dus e te y od centes 43 44 1 Attacbiueesonc eene ER DIR
84. IT and MSG_DRAW messages as well as MSG_ERROR and user messages that originate in these messages so any calls to Tool_Trace must originate from handlers for these messages 4 18 Miscellaneous Functions 4 18 1 SetGPIO Syntax setgpio pins as unibyte action as gt gpio action Parameters pins A value of type unibyte indicating which outputs to set The gpio pin type has been created to simplify use of this API Legal values are PINO PIN1 PIN2 etc Multiple val ues may be OR ed together to select any combination of output pins action A value of type gpio action see below indicating how the outputs should be set Description This function sets the output state of one or more GPIO pins The pins must be set to outputs using the SetGPIODi rection API function before this function can be used The function sets the outputs on the pins selected by pins according to the desired action Legal values for action include GPIO SET Set the outputs logic HIGH on the selected pins GPIO CLEAR Clear the outputs logic LOW on the selected pins GPIO TOGGLE Toggle the outputs on the selected pins 4 18 2 ReadGPIO Syntax readgpio pins as unibyte returns gpio pin Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Parameters pins A value of type unibyte indicating which inputs to read The
85. LEASE 204 endfunc Parameters lt gt The x location of press event with respect to the parent s origin lt y gt The y location of the press event with respect to the par ent s origin lt pass gt False if the container s children have not yet received the message and true if the container s children have already received the message Message MSG_SCREEN_MOVE Description This message indicates that the user has moved his or her finger across the touch screen without lifting it Objects whose area contains the starting or ending or both coordi nates receive this message Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Handler Format Gf handled by a container object func lt name gt lt x_to gt as integer lt y_to gt as gt integer lt x_from gt as integer lt y_from gt as gt integer lt pass gt as boolean returns boolean handles MSG SCREEN MOVE ose endfunc if handled by an area object func name xto as integer lt yto gt as gt integer xfrom as integer lt yfrom gt as gt integer returns boolean handles MSG SCREEN MOVE endfunc Parameters lt x_to gt The final x location after the move with respect to the par ent s origin lt y_to gt The final y location after the move with respect to the par ent s o
86. O 6786 14 Variables declared inside the function are local to that func tion and cannot be accessed from outside the function The returns clause specifies the type of value that is returned from the function If a returns type is specified then the function is required to return a value of that type The value is passed back from the function using the return statement which also terminates the function Multiple return statements can be included in a function in separate execution paths The first return statement executed will end the function Return statements with no value may be used to terminate a function with no return value Functions with no return value have an implied return at the endfunc statement The actual code for the function is entered between the local variable declarations and initialization if any and the end func statement Example func getChar data as byte returns boolean handles msg comm receive dim newData 5 as byte init newData 10 20 30 40 50 dim countdown countup as integer init countup 0 if len data 5 for countdown 4 to 0 step 1 newData countup data countdown countup countup 1 next endif return true endfunc 2 12 1 Calling a Function Use the following syntax to call a function lt funcname gt lt parameter gt Use the following syntax to call an object method lt objname gt lt funcname gt lt parameter gt The p
87. OPTO 6786 82 Parameters name A string containing the old name possibly including path of the file to rename A string containing the new name possibly including path to be used to refer to the file Description This function will rename a file that is contained in the flash file system 4 17 Qlarity Foundry Functions These functions are only available in Qlarity Foundry and calls to them should be enclosed in a if _TOOL Zendif directive to prevent their inclusion in the runtime applica tion 4 17 1 Tool Persist Syntax tool persist x as reference to anytype Parameters The name of a variable modified in a tool message handler Description This function informs Qlarity Foundry that an object prop erty has been modified in a tool message handler Qlarity Foundry must be informed of the change in order to update the application properly Only call this if you want a value permanently saved See section 3 7 Tool Messages for more details 4 17 2 Tool_Trace Syntax tool_trace str as string Parameters str A message to display in Qlarity Foundry Description This function causes Qlarity Foundry to display the mes sage contained in str when the function is called It is OptoTerminal Programmer s Reference Manual useful for debugging code Note that in Layout View Qlar ity Foundry usually only executes handlers for the MSG_IN
88. OPTOTERMINAL PROGRAMMER S REFERENCE MANUAL REVISION 2 5 Opto 22 43044 Business Park Drive Temecula CA 92590 3614 USA Phone 800 321 6786 or 951 695 3000 Fax 800 832 6786 or 951 695 2712 Email sales opto22 com www opto22 com Manual 0060 01 Opto 22 form 1345 070321 6345 1 Printed in USA Copyright QSI Corporation 2006 2007 QSI reserves the right to modify this manual and or the product s it describes without notice In no event shall QSI be liable for incidental or consequential damages or for the infringement of any patent rights or third party rights due to the use of its products QTERM G70 QTERM G75 QTERM G55 QTERM Z60 QTERM G70 G75 655 760 Qlarity and Qlarity Foundry are trademarks of QSI Corporation OptoTerminal is a trademark of Opto 22 Microsoft Windows Windows NT Windows 2000 and their respective logos are registered trademarks of Microsoft Corporation in the United States and other countries Opto 22 Fax 800 832 6786 Web www opto22 com Phone 800 321 6786 FOREWORD The Qlarity based terminals software is divided into four major components User Application created in Qlarity Foundry or a compatible text editor using the Qlarity programming language Application Binary the user application compiled as binary so it can be downloaded to the terminal System Software and Operating System written C using uC OS and the Hardware Abstraction fo
89. Pim 9 2 7 2 V anable Initialization ung teste E ee Reti bee o BN Eee i ce ene HRS 10 2 733 Private and Protected Variables diet hte th eth e co edd er er ee ec ts 10 2 9 Object References aed ae e REL e eiedeude 10 2 8 1 Untyped Object Referentes eet eat o tee re tg rn t iR SUR ab EN DRE C et Re Re deter dd 10 282 Typed Object References iae ied eee ed eet aede rte Ue eg rete Steed 11 2 8 3 Special Object Refetences a eer ppt ie er e RE erp ere e ee Rs SERERE 11 2 9 ATT AYS VD ee RE C UR IU RAO HEe ns eats Edd en E 11 2 TO Operators MP 12 2 10 Arnithmetc Operators een ia we nite eo e E Ee ipe de Rt 12 CONTENTS Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 ii OptoTerminal Programmer s Reference Manual 2 10 4 Dereference Operator ee a Ve IRR RU e e ev re Den ete Pe sd e 12 2 10 5 Miscellaneous Operators 5 este nire eere ge iR e He P rte tii iade ia bees 12 2 viscid ache hn elle 13 2 12 Furnctions o anoo aee ne I e e t t Ete etie tee 13 2121 Calling F nction e eee e d tg a e E e e dad e e Reo ie epa ees 14 2 12 2 Private Protected and Fixed 14 2 123 Validation Methods iet eR CHER ERR oaa rg Hebe Enn 14 2 12 4 Array Validation Functio
90. RD syscmd usepassword SYS TEMPERATURE float SYS FEEDBACK TYPE syscmd feedback SYS FEEDBACK IPADDRESS byte array SYS FEEDBACK FPORT integer SYS FATALREBOOTTIMEOUT integer drawcache level SYS KEYPADBACKLIGHT boolean SYS AUTOSHIFT boolean SYS KEYPADGATEDELAY integer SYS AUTOPOWER syscmd powerkeymode Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual The following cmd values are not legal for this func tion SYS_SAVE SYS_CLEAR Note that the following values for cmd have no defined current value SYS_MODE SYS_PASSWORD SYS_USEPASSWORD 4 18 16 SoftReset Syntax softreset rst as rstmode Parameters rst A value of type rstmode indicating how the reset is to be performed Description This function causes the terminal to undergo a warm reboot cycle rst can take the following values RESET NORMAL Causes the unit to perform a reset as if the power had been cycled If the unit is in development mode it waits for an application to be loaded RESET LOADAPP Causes the unit to perform a reset and go directly into the download application mode RESET ENTER BL Causes the unit to perform a reset entering into the bootloader where the firmware can be upgraded seri ally RESET ENTER POS Causes the unit to perform a reset entering the Power On Setup utility upon reboot RESET TOUCH CAL Causes
91. RE UR RU OH Cat Py 75 4 12 5 5 pee be deret pote etes e e dia midland 75 4 13 User Input Capt re eite eee ne pere tmp geeinigt 76 4 13 1 SetCapture siete mtn e E a e RR eae dist ee FIR IE ahd RE 76 4 13 2 GetCapture er qp RO HEU D onde aum 76 4 13 3 RemoveCapture oa ee eer ete ERR ERIT E 76 4 14 Exception Furictions i i enne Rer ener da er E EE Ee e Ebr TI T ALT Throw 77 414 2 iet e cho m Oe qun mega ne TI 4 143 RethfoW 2 iota to eet deste te eb eec Le d et ed oi eid ARR 77 4 15 User Non Volatile Configuration Functions 000 0 ccc eeeescesceseesecesecsecesecseeesesseesseeseeeaecseseaecsaeeaeseceaesneseaesneeeaeenas 77 4 15 1 ReadUserConfig e ER haa suds ieee dass E Re tie RR REED 78 4 15 2 WriteUSerConii pssst td eterno tee et e ttp ee e c i e c t eek 78 4 16 File System Functions eed e er etd e Me ea tha etg eb i e RE S vehe evs a ees 78 4 16 1 GetA vallFilesp ce ente Rn eren re ped tp peg er 78 4 16 2 78 4 16 3 Chan geC unit ssc ito o to m ar e EH E EDO EC aad ipe 78 4 16 4 E ea ea teet p e E ED a lead et aaa da 79 4 16 5 GetDirEntty uires rete ta ane e ee eti eniti eg a reda R
92. RESS SYS_IPSUBNET SYS_IPGATEWAY SYS_USEDRAWCACHE SYS_PASSWORD SYS_USEPASSWORD SYS_TEMPERATURE SYS_COM3BAUD Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 99 Defined Type Values Defined Type Values SYS_COM8STOPBITS SYS_COM7FLOWTIMEOUT SYS_COM8FLOWCONTROL SYS_COM8FLOWTIMEOUT SYS_COM9BAUD SYS_COM9FLOWTIMEOUT SYS_COM9ODATABITS SYS_COM10FLOWTIMEOUT SYS 9 SYS_VOLUME SYS_COM9OSTOPBITS SYS_NOTEAMPLITUDE SYS_COM9FLOWCONTROL SYS_FATALBOOTTIMEOUT SYS_COM10BAUD SYS_KEYPADBACKLIGHT SYS COMIODATABITS syscmd continued SYS AUTOSHIFT SYS COMIOPARITY SYS COMIIBAUD SYS COMIOSTOPBITS SYS COMIIDATABITS SYS COMIOFLOWCONTROL SYS COMIIPARITY SYS FEEDBACK TYPE SYS COMIISTOPBITS SYS FEEDBACK IPADDRESS SYS COMIIFLOWCONTROL SYS FEEDBACK FPORT SYS COMIIFLOWTIMEOUT SYS COMIFLOWTIMEOUT SYS KEYPADGATEDELAY SYS COM2FLOWTIMEOUT SYS AUTOPOWER SYS COMS3DATABITS SYSACT DONOW SYS COM3PARITY action SYSACT ONBOOT SYS COMS3STOPBITS SYSACT ALWAYS SYS COM3FLOWCONTROL SYS_COM4BAUD BAUD_115200 SYS_COM4DATABITS BAUD_57600 SYS_COM4PARITY BAUD_38400 SYS COMASTOPBITS BAUD 19200 SYS COMAFLOWCONTROL BAUD 14400 SYS COMSBAUD baud BAUD 9600 SYS COMSDATABITS 4800 SYS COMSPARITY BAUD 2400 SYS COMSSTOPBITS BAUD 1200 SYS COMSFLOWCONTROL BAUD 600 SYS_COM6BAUD BAUD_300 SYS_COM6DATABITS
93. SYS_COM6PARITY syscmd_databits 42 aoe SYS_COM6STOPBITS SYS_COM6FLOWCONTROL FBTYPE_SERIAL SYS_COM7BAUD syscmd_feedback FBTYPE_VIDEO SYS_COM7DATABITS FBTYPE_UDP Sie FLOWCONTROL_NONE SYS COMTSTOPBITS FLOWCONTROL XON XOFF SYS COMT7FLOWCONTROL syscmd flowcontrol FLOWCONTROL RTS CTS FLOWCONTROL_DTR_DSR SYS_COM8DATABITS z E SYS COMSPARITY KBDRPTDELAY 250 SYS COMIFLOWTIMEOUT KBDRPTDELAY 500 SYS COM2FLOWTIMEOUT KBDRPTDELAY 750 SYS_COM3FLOWTIMEOUT KBDRPTDELAY 1000 syscmd kbdrptdelay SYS COMAFLOWTIMEOUT SYS COMSFLOWTIMEOUT SYS COM6FLOWTIMEOUT Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 100 OptoTerminal Programmer s Reference Manual Defined Type Values Defined Type Values syscmd_kbdrptrate KBDRPTRATE_30_0 KBDRPTRATE_26_7 KBDRPTRATE 24 0 KBDRPTRATE 21 8 KBDRPTRATE 20 0 KBDRPTRATE 18 5 KBDRPTRATE 17 1 KBDRPTRATE 16 0 KBDRPTRATE 15 0 KBDRPTRATE 13 3 KBDRPTRATE 12 0 KBDRPTRATE 10 9 KBDRPTRATE 10 0 KBDRPTRATE 9 KBDRPTRATE 8 KBDRPTRATE 8 KBDRPTRATE 7 KBDRPTRATE 6 KBDRPTRATE 6 KBDRPTRATE 5 KBDRPTRATE 5 KBDRPTRATE 4 KBDRPTRATE 4 KBDRPTRATE 4 KBDRPTRATE 3 KBDRPTRATE 3 KBDRPTRATE 3 KBDRPTRATE 2 KBDRPTRATE 2 KBDRPTRATE 2 3 KBDRPTRATE 2 1 KBDRPTRATE 2 0 2 29 _0 _5 7 0 _0 _6 3 _0 _7 3 _0 7 5 syscmd_poskeys POSKEY_UP POSKEY_DOWN POSKEY_LEFT POSKEY_RIGHT POSKEY_ENTER POSKEY_ESC POSKEY_0
94. Subtraction operator Multiplication operator Division operator Modulus operator cannot be used mod with floats 2 10 2 Boolean Operators OptoTerminal Programmer s Reference Manual 2 10 3 Assignment Operators Operator Description Strict assignment operator This must be used anytime a variable or constant is initialized No validation is performed on the assign ment In most cases this operator should not be used to assign properties of other objects because no validation will be performed Validation assignment operator This operator is the same as unless a validation function with the same name as the variable was writ ten If this is the case then a validation is per formed Validation functions are discussed later Generally this operator should be used except when initializing a variable or assign ing a value inside a validation function See section 2 12 3 for an explanation of validation methods 1 Can be used with variables literals or constants of the fol lowing types boolean byte unibyte 2 Can be used with variables literals or constants of the fol lowing types float integer byte unibyte and arrays of those types A boolean expression is generated 3 Can be used with variables literals constants or arrays of any type A boolean expression is generated Operator Description 2 10 4
95. The x position of the center of the ellipse relative to the calling object s parent yoffset The y position of the center of the ellipse relative to the calling object s parent The distance along the primary focal point vector from the center to the edge of the ellipse relative to the calling object s parent xfocal The horizontal distance from the center to the primary focal point of the ellipse relative to the calling object s parent 49 yfocal The vertical distance from the center to the primary focal point of the ellipse relative to the calling object s parent theta The angle in radians from the primary focal point vector segment to the starting point of the arc Positive angles increase counter clockwise from the primary focal point vector segment gamma The angle in radians from the primary focal point vector segment to the ending point of the arc Positive angles increase counter clockwise from the primary focal point vector segment flags A value of type ellipse_flags see below that determines how the ellipse will be drawn Description This complex but powerful function draws an open or closed elliptical arc centered at xoffset yoffset rela tive to the calling object s parent The focal points of the ellipse are at the following points xoffset xfocal and yoffset yfocal xoffset xfocal and yoffset yfocal The mathematical
96. UAL CONVENTIONS The following conventions are used to identify selections in this manual Syntax commands and examples are shown in the Courier typeface rem lt comment gt Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 Opto 22 Fax 800 832 6786 Web www opto22 com Phone 800 321 6786 1 QLARITY BASED TERMINAL SOFTWARE FUNDAMENTALS ccscsssssssscsscsssccscccsccssscscsssccssssescscssesssessesssessessscesccsscssessscssesssesees 1 1 1 Qlarity based Terminal SoftWare 2 eet il CE eis qa p Re ett e tere ee ee bete 1 1 I T System Software FMW aTe a e d Ee eh 1 11 2 User Application n a ep Re e EU ERE UE Rees ae eee alee 1 1 2 Qlarity Programiming Languages e pS en e e ten delen eiim eei 1 1 221 Object Templates te ee eee cede Ris eet e re AG a NE apa eed 2 1 2 1 1 Defining a New Object Template eee narn n ni aie iad a E E N 2 1 2 1 2 Creating Instances of an Object aded eei N E e EE 2 122 Object LY POS A 2 1222221 Non Drawable Objects iue eade eie Det e en tet tes de one see gis 2 VDDD ODJeCts er te de Re e i P e P 3 122 23 Container Objects oe REDE tod REEL OR M OR 3 123 Event Processing oer nC mte ed tieu i 4 145 Z Order uou senio RR
97. YS COMS8BAUD SYS_COM9BAUD SYS COMIOBAUD Set the baud rate for the selected serial interface newvalue is of type syscmd baud which is an enumerated type with the following legal values BAUD 115200 BAUD 57600 BAUD 38400 BAUD 19200 BAUD 14400 89 BAUD 9600 BAUD 4800 BAUD 2400 BAUD 1200 BAUD 600 SYS COMIDATABITS SYS COM2DATABITS SYS COMGDATABITS SYS COMADATABITS SYS COMSDATABITS SYS_COM6DATABITS SYS_COM7DATABITS SYS COMSDATABITS SYS COMODATABITS SYS COMIODATABITS Set the number of data bits for the selected serial inter face newvalue is of type syscmd_databits which is an enumerated type with two legal values DATABITS 7 DATABITS 8 SYS COMIPARITY SYS COM2PARITY SYS COMGPARITY SYS COMAPARITY SYS COMSPARITY SYS_COM6PARITY SYS COMTPARITY SYS COMSPARITY SYS COMOPARITY SYS COMIOPARITY Set the parity for the selected serial interface newvalue is of type syscmd parity which is an enumerated type with three legal values PARITY NONE PARITY ODD PARITY EVEN SYS COMISTOPBITS SYS_COM2STOPBITS SYS COMGSTOPBITS SYS COMASTOPBITS SYS COMSSTOPBITS SYS_COM6STOPBITS SYS COMTSTOPBITS SYS COMSSTOPBITS SYS COMOSTOPBITS SYS COMIOSTOPBITS Set the number of stop bits for the selected serial inter face newvalue is of type syscmd_stopbits which is an enumerated type with two legal values STOPBITS 1 STOPBITS 2 SYS COMIFLOWCONTROL SYS COM2FLOWCONTROL
98. a function either a global func tion or object methods are local to that function and are not accessible outside the function The declaration of each variable need not be stated before it is initialized or used on a global level or in an object defini tion This is not true in a function function variable declara tions must appear before any other code in the function It is possible to declare multiple variables of the same type on one line as follows Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 10 dim lt name gt gt lt data_type gt lt name gt lt name gt Example dim varl var2 var3 var4 as string 27 22 Variable Initialization Syntax init lt name gt lt value gt Examples dim myVar as integer init myVar 10 dim myString as string init myString Hello World r n Description The init keyword is used to initialize a variable to a speci fied value at compilation Variables can be initialized with literal values other constants enumerations or names of object instances for objref variables The value given must be of the same type as the variable and it cannot be an expression containing another variable Runtime changes to variable values must take place within a function 2 7 3 Private and Protected Variables Syntax private dim lt name gt as lt data_type gt protected dim lt name gt as lt data_type
99. ach API function to attach an object to a parent container Because they are untyped these variables can refer to an object of any type It is possible to convert an untyped object reference to a typed object reference by converting the untyped object ref erence to a string then converting the string to a typed object reference func ConvertToButton untypedObj as objref dim buttonRef as objref ButtonV2 dim buttonName as string buttonName str untypedObj check error val buttonRef on error _print Illegal conversion rethrow enderr return buttonRef ETEN endfunc buttonName Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 2 8 2 Typed Object References Syntax dim lt name gt as objref lt template_name gt init lt name gt lt obj_instance gt Example func typedobjref dim bmpobjref as objref bitmapobj init bmpobjref mybitmap bmpobjref enabled tru bmpobjref foo 10 20 endfunc Description Variables of this type can only refer to instances of the named template For example if there is an object template gauge and the variable mygauge is an objref of gauge then mygauge can only refer to gauge objects and to no other types In addition to the capabilities of an untyped objref typed objrefs can be used to access proper ties and methods of the specified object template
100. allows you to define user messages and a flexible set of Qlarity API functions to send these messages 3 5 1 Defining User Messages Syntax constant message lt msg_name gt Description This statement declares user message named msg name gt The name can be any legal identifier how ever it is advisable to use a common convention for naming user messages such as UMSG XXXX Like other user defined types this declaration must appear in the global code area Messages cannot be declared inside object definitions or instances 3 5 2 Sending User Messages User messages are sent using the UserBroadcastMsg UserSendMssg and UserDirectMsg API functions These functions are described in detail in section 4 12 User Mes sage Functions in this manual Messages sent with UserBroadcastMsg behave as broad cast messages They go to all objects enabled or disabled in Z order and cannot be terminated Messages sent with UserSendMsg behave as area mes sages They are passed to eligible enabled objects in Z 27 order and may be terminated with a handler return value of true Unlike area messages these user messages are not sent to container objects twice Container handlers are called before the message is passed to the container s chil dren A message sent with UserDirectMsg goes to the object regardless of the object s enabled status UserBroadcastMsg UserSendMsg and UserDirect
101. an parameter is used to indicate which pass is taking place when the handler is called The parameter value is false if the children have not yet received the message and true if the children have already received it Also similar to area message handlers registered message handlers return a boolean value that is used to terminate the message Returning a value of true from the handler ter OptoTerminal Programmer s Reference Manual minates the message while returning a value of false allows the message to continue on through the system NOTE The messages MSG COMM RECEIVE MSG COMM RECEIVE URGENT and MSG COMM RECEIVE MULTICAST are all registered for at the same time In other words if an object registers for one of these messages then it registers for all of them Message MSG COMM RECEIVE Description This message indicates that one or more characters have been received from a communications interface COM port or Ethernet port You can register for multiple communica tions resources As a result you will receive this message each time data is received from any one of the resources for which you are registered Use the GetComMessageSource API to determine the communications resource that resulted in the generation of this message Handler Format func name returns gt boolean handles MSG COMM RECEIVE endfunc data as byte Parameters data A byte array
102. arameters and the type of return value The message handler formats may vary depending on whether the message is being handled by a global function a function inside a container type object or a function inside an area or non drawable object Message handler functions that return a boolean value can typically terminate the message stop it from moving for ward through the message handling system by returning a value of true Returning a value of false allows the mes sage to continue on through the message handling system Descriptions of all system messages are provided in this chapter Included is the format number and types of param eters and return type used to declare a handler for each message 3 1 Broadcast Messages Broadcast messages are sent to all objects regardless of their enabled or disabled status according to the Z order A message is first passed to the root container where it is pos sibly handled by global functions which then passes the message to each of its children beginning with the front most object highest Z order When the message is passed to a container object the container object first handles the message then passes it to each of its children beginning with the front most object In this manner the message fil ters down through the object hierarchy until all objects have received the message Broadcast message handlers do not have a return value and therefore cannot terminate the
103. arameters to call a function can be literal values vari ables of the correct data type or expressions that produce the correct data type OptoTerminal Programmer s Reference Manual 2 12 2 Private Protected and Fixed Functions Syntax private func name endfunc lt parameters gt protected func lt name gt endfunc lt parameters gt fixed func lt name gt s endfunc parameters protected fixed func name se endfunc parameters Description A function can be declared private or protected A function that is declared private can be used throughout the definition of an object but cannot be overridden and cannot be called from outside the object definition A protected function may be accessed in the object template and in the declaration of an object instance of that template 1 in override functions within the instance Protected functions may also be accessed by templates that extend inherit from the template in which they are defined No other access is allowed A function can also be declared fixed or protected fixed A fixed function cannot be overridden A protected fixed func tion cannot be overwritten either in an instance of the tem plate or in another template that extends the template which defines the fixed function Additionally the protected fixed function like a protected function may only be used my instances of the temp
104. are gate delay in the keypad scanning routine This is the delay between writing the row latch and reading the column latch Some keypads which are highly resistive and or capacitive may require longer delays to read the proper row and column The actual value is dimensionless but higher values will yield longer delays If your keypad is not working try setting to a higher value SETTING THIS TO AN INCOR RECT VALUE USUALLY TOO LOW MAY PRE VENT THE KEYPAD FROM FUNCTIONING PROPERLY value is an integer indicating the delay Values from 1 to 100 are acceptable SYS AUTOPOWER For systems with a keypad interface and Auto Power capability such as the QTERM G55 set the mode of the Auto Power feature Value is of type syscmd powerkeymode The values are POWERKEY NORMALKEY POWERKEY AUTOPOWER IMPORTANT NOTE Changes made to the terminal settings via SetSystemSet ting using SYSACT ALWAYS and SYSACT ONBOOT are not permanent saved to the non volatile flash memory until SetSystemSetting is called with the SYS SAVE command Many changes may be made via multiple calls to SetSystemSetting before they are saved to the flash using the SYS SAVE command Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 92 The intent of this command is two fold to allow the cre ation of a custom terminal configuration facility at the application level similar to the built in Power On Setup facility and to allow
105. as been played note The pitch from 0 to 86 duration The duration of the note in milliseconds Description This function plays a note at the specified pitch for the spec ified duration The duration is rounded to the nearest multi ple of 20 milliseconds The function returns immediately and the rates are queued After the note has played the MSG_SOUND_DONE message is sent directly to the spec ified object with parm as an optional parameter 4 8 3 PlaySound Syntax playsound sound as _audio Parameters sound The audio resource to play Description This function plays the audio resource identified by sound This function will only play the desired audio resource on units that have the audio decoder option installed 4 8 4 PlaySoundNotify Syntax playsoundnotify obj as objref parm as gt integer sound as audio 67 Parameters obj The object to notify when the sound has finished parm Optional parameter to send with the message produced when the sound has been played sound The audio resource to play Description This function plays the audio resource identified by sound After the sound has played the MSG SOUND DONE message is sent directly to the spec ified object with parm as an optional parameter 4 8 5 StopSpkr Syntax stopspkr Description This function immediately silences the speaker terminating any note that is currently playing and
106. ased on the size of the object given to the resize function The returned array will be a color array of size width height indicating the colors drawn so far Thus the color drawn at pixel coordinate x y in the object with 0 0 being the top left pixel of the region has the color indicated by the y width x th element in the returned array 4 7 Rendering Text on the Display Qlarity includes support for both raster BDF and True Type TTF font resources This section describes the API functions to render and paint text using these fonts 471 GetBdfTextSize Syntax getbdftextsize width as reference to gt integer height as reference to integer gt xoffset as reference to integer yoffset gt as reference to integer font as bdffont gt data as reference to anytype flags gt as font_flags Parameters width An integer to receive the width of the text box height An integer to receive the height of the text box xoffset An integer to receive the horizontal offset from the upper left corner of the rendered region to the origin of the first character yoffset An integer to receive the vertical offset from the upper left corner of the rendered region to the origin of the first char acter font The bdffont resource 33 data The data to be rendered as text The type can be a unibyte or byte array unistring or string flags A value of type font flags see below
107. atally wrong in the system soft ware The time will cause a system reset if the timeout period expires For normal operation the timer should be periodically reset using the WatchdogReset API function 4 18 21 WatchdogReset Syntax watchdogreset Description This function restarts the timeout period in the watchdog timer If the watchdog timer is enabled via the WatchdogE nable API function this function must be called periodi cally to reset the timer or the system will be reset when the timeout period elapses This function has no effect if the watchdog timer is not enabled 4 18 22 GetProfileTick Syntax getprofiletick returns integer Description This function is used to profile execution speed When this function is called it returns the number of profiling ticks that have occurred since the last time the function was called One profile tick is 1 32768 s 4 18 23 DelayMS Syntax delayms delay as integer Parameters delay The desired delay in milliseconds Description This function delays the requested number of milliseconds before returning OptoTerminal Programmer s Reference Manual 4 18 24 GetBinaryResource Syntax getbinaryresourc returns byte resourceID as integer gt Parameters resourceID The identifier of the binary resource Description This function returns a byte array containing the data of a binary resource that was included with the ap
108. ation FERR_FAILEDREINIT Failed to re init object Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 110 OptoTerminal Programmer s Reference Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 APPENDIX QLARITY COMMAND LINE COMPILER You can use the Qlarity compiler to compile your BASIC file rather than using Qlarity Foundry to compile it This is useful if you created your user application in a text editor The compiler looks for a file called natives lib This file contains information message prototypes and functions for the API This file must be in the same directory as the com piler or the program cannot be compiled NOTE The command line compiler is available as a Win32 or Linux executable file The Win32 compiler is distributed with Qlarity Foundry Contact QSI to obtain the Linux com piler Please be aware that the Linux compiler is often in flux and may only be available as a snapshot of current Qlarity developement To compile a Qlarity BASIC file at the command prompt type the following qlarify file name To specify the name of the output file type add the follow ing parameters qlarify o output file name file name If any errors occur they are output to the display To output the compiler errors to a file type the following qlarify e error file name file name To display Help on the c
109. awn between the last grip and the first grip outline segments are always drawn between all other grips A value of true causes the outline segment to be Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 31 drawn This also indicates whether clicking inside the object will select it GuiCursors is a standard defined type with the following possible values GuiCursors Description Cursor has arrows pointing up CSR_UPDOWN and down The resize grip can only be dragged vertically CSR_LEFTRIGHT Cursor has arrows pointing left and right The resize grip can only be dragged horizontally CSR_UPLEFT Cursor has arrows pointing diago nally up and left and down and right The resize grip can be dragged in any direction CSR_UPRIGHT Cursor has arrows pointing diago nally up and right and down and left The resize grip can be dragged in any direction CSR_DOWNLEFT Cursor has arrows pointing diago nally down and left and up and right The resize grip can be dragged in any direction CSR_DOWNRIGHT Cursor has arrows pointing diago nally down and right and up and left The resize grip can be dragged in any direction CSR_ALL Cursor has four arrows pointing in all directions The resize grip can be dragged in any direction CSR_BLOCK Cursor appears as a block The resize grip may not be dragged
110. based on the object s location in the Object Tree This command is useful when writing Qlarity applications in a text editor Qlarity Foundry typically ignores any Level commands typed in the Code View window 2 19 Including Files and Resources Syntax include lt file path gt Description This includes the specified file to be compiled with your project The include command is also used to make bit maps ttfonts and bdffonts available as resources in the application Syntax include bitmap lt bitmap_file_path gt as gt lt name gt Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual include ttfont lt ttfont_file_path gt as gt lt name gt include bdffont lt bdffont_file_path gt as gt lt name gt Description The lt name gt field is any name to be used to refer to the included bitmap ttfont or bdffont If the keyword default is used as the name of the resource then that bitmap ttfont or bdffont becomes the default resource of that type Resource variables that are not explicitly initialized will receive the default resource Since the backslash character is a special character used in strings it is necessary to use either a single forward slash or a double backslash to separate directories in file paths 2 20 Libraries Libraries are similar to other files that can be included except
111. bject type typ Name 2224 enddef lt name gt extends gt Description An object type must be defined in order for an instance of that object to be declared Object properties are defined using dim statements Default values are assigned using init statements Methods are defined by putting function definitions inside the definition of the object Any instances of an object type will have these properties and functions lt object_type gt may be any of the three object type key words object area object or container lt name gt may be any legal and unique identifier and becomes the name of the defined object type Extends indicates that this template will extend the tem plate lt name gt where lt name gt is the name of the template this one will extend By extending a template the new tem plate will inherit all methods and properties of the base tem plate Extending templates via inheritance can be a powerful tool to allow you to reuse existing code and create modified objects quickly When extending templates there are several items to remember Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 18 The extending template receives all of the base tem plate s variables and functions Care should be exer cised not to declare any variables or functions with the same name as those in the base template unless the extending template is ove
112. by localport NetProtocol is an enumerated type with the fol lowing legal values NET_UDP Use the User Datagram Protocol UDP IP NET_TCP Use the Transmission Control Protocol TCP IP NetServerOpen starts the server and returns a server com munications resource of type servercomm Connections or datagrams with any foreign port number are accepted on the local server port When a new connection or datagram from a unique foreign port is accepted a network commu nications resource is allocated and passed to the object ref erenced by obj ina MSG_COMM_ ACCEPT message 37 This communications resource is used with the Send and Transmit API functions to indicate which network channel should be used for transmission It is also used to register for MSG_COMM_RECEIVE messages generated by the network channel Connections or datagrams with any foreign port number are accepted on this local port When a new connection or data gram from a unique foreign port is accepted a network channel is allocated and passed to the application in a MSG_COMM_ ACCEPT message The application contin ues to listen on the specified local port until the terminal is reset Up to 64 channels 32 TCP channels may be open at any given time Channels may be released by calling Net Close The server will continue to listen on the specified local port until it is closed by calling the NetServerClose API function 4 1 7 NetClose
113. calling FreeArrayHandle 4 9 12 AllocateArrayHandle Syntax as reference gt returns arrayhandle allocatearrayhandle data to anytype Parameters data An array to be associated with the returned handle Description This function makes a copy of the array that is passed in as the data parameter and returns a handle which can be used to access the new copy via the ReadArrayHandle function When the array is no longer needed you MUST call Free ArrayHandle to release the array handle This function is an advanced API function and if misused may cause the termi nal to exhaust its memory resources 4 9 13 ReverseFind Syntax reversefind match as reference to gt sametype start as integer len as gt integer pattern as reference to gt sametype returns integer Parameters match An array of any type to examine start The location in match to begin the search characters Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual after the start character are not searched 1 starts at the emd len The number of elements before start to search in match or 1 to indicate all elements from start to the beginning of match pattern The pattern of data elements to search for in match Description This function searches for pattern in match If pattern is f
114. ce some or all of the text outside of the rendering region 4 7 45 DrawSysTextFit Syntax drawsystextfit multiflags as reference gt to multiline flags xpos as reference gt to integer ypos as reference to gt integer widths as reference to gt integer heights as reference to gt integer xoffsets as reference to gt integer yoffsets as reference to gt integer indices as reference to gt integer lengths as reference to gt integer font as sysfont facenum as gt integer ptsize as integer data as gt reference to anytype flags as font flags Parameters multiflags An array of type multiline flags indicating some informa tion on how well the lines fit within the specified region array of integers The 0 th element indicates the x posi tion of the upper left corner of the rendered region relative to the calling object s parent Subsequent elements identify the relative horizontal offset from the initial x position where each line of text should be drawn ypos An array of integers The 0 th element indicates the y posi tion of the upper left corner of the rendered region relative to the calling object s parent Subsequent elements identify the relative vertical offset from the initial y position where each line of text should be drawn widths An array of integers indicating the width for each line of text
115. check If more than one object has regis tered for a given message the objects receive the message in Z order as with area messages with the root container global handlers receiving highest priority Objects with handlers for registered messages may be regis tered to receive these messages by calling the RegisterMsg Handler API function This is typically done in the MSG_INIT handler for the object but it can be done at any time Each different type of message must be registered individually for a given object Key handlers are registered using the RegisterKey API function Objects may be registered for a specific key or for all keys using the parameter KEY_ALL The actual key code is passed to the handler as a parameter so a handler registered for KEY_ALL can determine what key was pressed or released A list of constants defining all keys for the keyboard or keypad is included in Appendix A Built in Constants and Defined Types Registered objects may also be unregistered by calling the UnregisterMsgHandler API function after which the object will no longer receive the message To unregister a key handler register the object with the parameter KEY_NONE The key messages MSG KEY DOWN MSG KEY PRESS and MSG KEY RELEASE are similar to area messages in that container objects receive the message twice once before it is passed to the container s children and once after all of its children have received it A boole
116. clears the speaker queue 4 8 6 SetVolume Syntax setvolume direction as volume_adjust Parameters direction A value of type volume_adjust see below that deter mines how to adjust the volume Description This function adjusts the volume of the unit at runtime The adjustment is temporary and is forgotten when power is removed from the terminal Permanent changes to the vol ume setting must be made with the Power On Setup utility or the SetSystemSetting API function The SetVolume function takes an argument of type volume adjust which is a defined type with the following legal values Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 68 VOLUME_LOUDER Adjust the volume up VOLUME_QUIETER Adjust the volume down 4 9 Array and String Functions 491 Len Syntax len arr as reference to anytype gt returns integer Parameters arr An array of any type Description This function returns the number of elements in the array 4 9 2 Left Syntax left as reference to sametype len as integer returns sametype gt Parameters arr An array of any type len The number of data elements to extract Description This function returns an array that contains the first len elements of arr 49 3 Right Syntax right arr as reference to sametype gt len as integer returns sametype Parameters
117. containing the data that was received from the communications interface Message MSG COMM RECEIVE URGENT Description This message indicates that one or more characters have been received via the Transmission Control Protocol TCP urgent or out of band data channel This message is only generated by a TCP communications resource You can reg ister for multiple communications resources As a result you will receive this message each time data is received from any one of the resources for which you are registered Use the GetComMessageSource API to determine the com munications resource that resulted in the generation of this message Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Handler Format func name data returns gt boolean handles MSG COMM RECEIVE URGENT Listers endfunc as byte Parameters lt data gt A byte array containing the data that was received via a TCP urgent data channel Message MSG_COMM_RECEIVE_MULTICAST Description This message indicates that a packet has been received from a multicast communications interface You can register for multiple communications resources As a result you will receive this message each time data is received from any one of the resources for which you are registered Use the GetComMessageSource API to determine the communica tions resource that resu
118. creating object templates for the objects you want to use Each object template has properties and methods that define the function of the object You cre ate object instances from the object templates by setting up the properties for each object in the user application Code written in Qlarity defines the objects their properties and their functions Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 Objects are the basic units of a Qlarity application Each object template is an abstract representation of a user inter face element such as text a picture a line a window a but ton and so on The abstract representation allows you to control each element by setting familiar properties of the element without worrying about the low level details of the actual manipulation Objects are characterized by their properties data and methods code The properties and methods define what an object is and how it behaves 1 2 1 Object Templates An object template is defined by the properties and methods that it contains as well as those of the template it extends Gf any All object instances created from the same object template have the same number and type of properties although the values stored in these properties may be dif ferent Similarly all object instances from the same tem plate have the same list of methods although each object may override the default functionality of a method with use
119. ctangular section of the pixel map is copied so that the total number of rows copied is height and the total number of columns cop ied is width 4 6 13 GetBitmapSize Syntax getbitmapsize width as reference to gt integer height as reference to integer gt bmp as bitmap Parameters width An integer to receive the width of the bitmap resource height An integer to receive the height of the bitmap resource bmp The bitmap resource Description This function determines the size of a bitmap resource width and height receive values in pixels corre sponding to the width and height of the bitmap resource OptoTerminal Programmer s Reference Manual 4 6 14 DrawBox Syntax drawbox left as integer top as integer gt right as integer bottom as integer Parameters left The x position for the left side of the box relative to the calling object s parent top The y position for the top of the box relative to the calling object s parent right The x position for the right side of the box relative to the calling object s parent bottom The y position for the bottom of the box relative to the call ing object s parent Description This function draws a filled box at the position specified The box has a one pixel border drawn in the foreground color and is filled with the background color 4 6 15 DrawPolygon Syntax
120. ctions Refer to section 2 15 Exception Handling for general information and to the OptoTerminal Qlarity Foundry User s Manual for more specific information on the Qlarity exception handling system Exception names types and description strings are listed in Appendix B 4 14 1 Throw Syntax throw loc as reference to byte msg gt as reference to byte Parameters loc An array of bytes or a string indicating where the excep tion occurred 1 in which function msg An array of bytes or string detailing specific information about what exception occurred Description This function throws a user exception to the exception han dling system loc should give information on where the exception was thrown msg should give details on what actual exception occurred The error type is always EXCEPT_USER and the error level is always EXLEV_ USER 4 14 2 GetException Syntax getexception msg as reference to byte gt rrtype as reference to unibyte gt rrlevel as reference to unibyte returns gt boolean 77 Parameters msg An array of bytes or a string to receive specific informa tion about what exception occurred errtype A unibyte to receive the error type errlevel A unibyte to receive the error level Description This function retrieves information about the last exception that occurred and is typically called in error handling
121. cur rent volume to be used Note that incrementing by one in the scale will not necessarily change the volume and values returned by GetSystemSetting may not match what was passed into SetSystemSetting To change the volume by one volume increment use the SetVol ume function and then pass in 1 for the volume set ting in this function to save to the flash SYS NOTEAMPLITUDE For units that have an audio decoder this sets the amplitude of the generated note waveforms using a scale from 0 to 255 with 255 the loudest SYS MODE Change the current terminal mode development mode on development mode off and default application In this case newvalue is of type syscmd_mode which is an enumerated type with the following legal values MODE DEVELOFF MODE DEVELON MODE DEFAULTAPP If the terminal does not have a default application selecting MODE DEFAULTAPP will be the same as MODE DEVELOFF As there is current value for this setting using SYSACT DONOW will not do any thing and using SYSACT_ ALWAYS will only set the pending save setting SYS_ORIENT Change the display orientation portrait or landscape In this case newvalue is of type syscmd_orient which is an enumerated type with four legal values OptoTerminal Programmer s Reference Manual ORIENT_PORTRAIT ORIENT_LANDSCAPE ORIENT_PORTRAIT2 ORIENT_LANDSCAPE2 SYS_KBDRPTDELAY For systems with a keyboard interface chang
122. d it doesn t matter what local port a device uses when transmitting to the multicast group The localport parameter is normally used to filter incoming data Generally you will only receive data pack ets that are directed at the multicast group specified by ipaddr and directed to the port specified by localport If you specify zero 0 for the local port then Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual ALL transmissions directed to the multicast group are received You cannot transmit on a comm channel that was opened with a local port of zero Incoming data on a multicast channel will be received via MSG_COMM_RECEIVE_MULTICAST messages You should call RegisterMsgHandler as normal in a MSG COMM ACCEPT message to register for the MSG COMM RECEIVE MULTICAST message 4 1 6 NetServerOpen Syntax netserveropen obj as objref prot as gt netprotocol localport as unibyte gt returns servercomm Parameters obj A reference to the object that will receive MSG COMM ACCEPT messages for this server see below prot The protocol to be used for the connection see below localport The local port number where the server will listen for data grams UDP or connection requests TCP Description The NetServerOpen function is used to start an Ethernet communications server listening on the port specified
123. d whenever an element of an array is assigned a new value with the validation assignment oper ator The lt gt parameter contains the index of the array that is being assigned a new value Example dim myarray 10 as integer func myarray newval as integer index gt as integer if index 0 then if newval 10 then myarray index newval endif endif endfunc 2 12 6 Reference Parameters Syntax func func name lt varname gt as referenc gt to lt datatype gt endfunc Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 16 Description Qlarity normally uses a pass by value convention which means that functions receive a copy of variables passed as parameters They cannot modify the value of the original variable Reference parameters make it possible to modify the values of the variables that are passed into a function as parameters These are especially useful when a function needs to return more than one value Example func myFunc newVar as reference to integer newVar 5 endfunc When myFunc is executed a reference to the variable is passed into the function The value of newVar reflects the change after the function returns 2 13 Conditionals if Statement Syntax if boolean expr then EPA elseif boolean gt then 53 27 else rea endif The then is required The elseif and
124. direction as contrast_adjust section 4 18 6 page 84 SetCTS setcts resource as comm outValue as boolean section 4 1 14 page 39 SetDSR setdsr resource as comm outValue as boolean section 4 1 16 page 39 SetFgColor setfgcolor newcolor as byte section 4 6 3 page 45 f filed y ffset int poc SetFilePos RM NM S section 4 16 12 page 81 absolute as boolean SetGPIO setgpio pins as unibyte action as gpio action section 4 18 1 page 82 SetGPIODirection setgpiodirection pins as unibyte input as boolean section 4 18 3 page 83 SetLED setled cmd as ledcmd lednum as integer section 4 18 9 page 85 setobjprop obj as objref name as reference to gt tObjP tion 4 3 41 PEIOBIPXOD byte value as reference to byte page ina setorigin cont as objref originX as integer gt SetOrigin aped section 4 3 9 page 43 setpalette red as reference to byte green gt p etPalette section 4 18 age 5 as reference to byte blue as reference to byte 8 30 page 96 SetPixel setpixel x as integer y as integer section 4 6 6 page 46 SetSeedRandomNum setseedrandomnum seed as integer section 4 18 19 page 93 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 121 Function Syntax Reference SetSerialRecvSize setserialrecvsize res as comm newsize as integer s
125. dle the message Messages sent with this function can be terminated by a handler returning true If false is returned the message contin ues through Z order The parm parameter may be set to any integer value may be used for any purpose If donow is set to true processing of the current message is suspended while the user message is processed by the system When the user message processing is complete this function returns and the current message continues processing Any pending exceptions are thrown in the calling function Set ting donow to false causes the user message to be enqueued and handled as any other message 4 12 3 UserDirectMsg Syntax userdirectmsg startobj as objref msgnum gt as message parm as integer donow as gt boolean returns boolean Parameters startobj The object to which the message is being sent msgnum The user message to send parm The integer parameter to associate with the sent message 75 donow A flag to select preemption of the current message while the user message is processed Description This function sends a user message directly to the startobj object If startobj has a handler for msgnum and donow is true the handler is imme diately called and executed Otherwise the msgnum message is posted in the messaging queue as a direct mes sage to startobj The ret
126. e DrawBDFTextFit DrawBitmap drawbdftextfit counts as reference to integer gt multiflags as reference to multiline_flags gt xpos as reference to integer ypos as gt reference to integer widths as reference to gt integer heights as reference to integer gt xoffsets as reference to integer yoffsets gt as reference to integer font as bdffont data gt as reference to anytype start as integer gt length as integer flags as font flags drawbitmap x as integer y as integer bmp as gt bitmap section 4 7 5 page 57 section 4 6 8 page 46 DrawBitmapRegion drawbitmapregion x as integer y as integer gt xoffset as integer yoffset as integer width as gt integer height as integer bmp as bitmap section 4 6 9 page 46 DrawBorder drawborder xl as integer yl as integer x2 as gt integer y2 as integer style as integer gt drawFlags as unibyte section 4 6 21 page 52 DrawBox drawbox left as integer top as integer righ as gt integer bottom as integer section 4 6 14 page 48 DrawEllipse drawellipse xoffset as integer yoffset as gt integer as float xfocal as float yfocal as gt float theta as float gamma as float flags as gt ellipse_flags section 4 6 16 page 49 DrawLine drawline xl as integer yl as integer x2 as gt integer y2 as integer section 4 6 7 page 46 DrawPixmap
127. e On return the elements indicate how far from the left edge each line s origin should be placed yoffsets An integer array used as both an input and an output For input if FONT_VTOP FONT_VBOTTOM FONT_VCENTER is not specified by default this is the case the 0 th element is used to determine how far from the top edge the origin of the first text character should be On return the elements indicate how far from the top edge each line s origin should be placed indices An integer array used as both an input and an output For input the 0 th element gives the first index into data indicating where to begin the text fitting Characters before this index are not fitted A value of 0 starts at the beginning On return the index to the first character for each line of text will be in the individual elements of the array with the 0 th element containing the index where text fitting began lengths An integer array used as both an input and an output For input The number of elements of data to fit or 1 to indicate all elements from the starting index to the end of data On return the number of elements that should be drawn for each line of text is indicated in the individual ele ments of the array with the 0 th element containing the total length of data fitted font The bdffont resource data The data to be rendered as text The type can be a unibyte or byte array unistring or string
128. e been checked It indicates to the handler that at least one unhandled exception resides in the system exception stack The MSG ERROR message can only be handled by a global message handler Since the han dler takes no parameters the exception information must be retrieved by calling the GetException API function Refer to the OptoTerminal Qlarity Foundry User s Manual for more information on the exception handling system Handler Format func name handles MSG ERROR Posad endfunc Parameters MSG_ERROR handlers take no parameters and do not have a return value 33 Message MSG_DRAW_DONE Description This message is sent by the system after a draw message has completed The parameters indicate the bounding rectangle which was redrawn This message like MSG_ERROR is only sent to a global message handler Handler format func DrawDone lt left gt as integer lt top gt gt as integer lt width gt as integer lt height gt gt as integer handles MSG_DRAW_DONE return endfunc Parameters lt left gt The x location of the upper left corner pixel of the invalid region lt top gt y location of the upper left corner pixel of the invalid region lt width gt Width of the invalid region in pixels lt height gt Height of the invalid region in pixels Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 34 OptoTerminal Programmer s Re
129. e objects have received it Global area message handlers are considered to be methods of the root container They are therefore eligible to receive a message twice once before any of the root s children and once after all of root s children have received the message Only area and container objects can receive area messages Non drawable objects are not eligible to handle them The parameters of an area message handler indicate the location of the event on the screen Area message handlers have a boolean return value used to terminate the message Returning a value of true terminates the message while returning a value of false allows the message to continue through the message handling system Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 22 The format for the handler is different for container and area objects Containers have an additional boolean parameter The value of this parameter is false when the container handler is called before the message passes to the con tainer s children When the handler is called after the con tainer s children have received the message the value of this parameter is true A container such as a form object that doesn t handle an area message directly e g a screen press generally returns false the first time the handler is called This allows the container s children to handle the message However true is returned on the second call to prevent
130. e of any character in the font xnextline An integer to receive the horizontal offset from the origin of the first character on a line to the origin of the first character on the next line ynextline An integer to receive the vertical offset from the origin of the first character on a line to the origin of the first character on the next line font The sysfont resource This may be either a BDF or a True Type font facenum The number for the desired face This value is only used with TrueType fonts and is typically zero 0 ptsize The point size This value is ignored unless font specifies a TrueType font flags A value of type font flags See section 4 7 1 GetBdf TextSize for a description Description GetSysFontMetrics function returns important metrics for the font resource which can be used to determine values for parameters in calls to DrawSysText 4 7 14 DrawSysText Syntax drawsystext x as integer y as integer gt width as integer height as integer gt xoffset as integer yoffset as integer gt font as sysfont facenum as integer gt ptsize as integer data as reference gt to anytype flags as font flags Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 64 Parameters x The x position of the upper left corner of the rendered region relative to the calling object s parent y The y position of the upper left co
131. e terminated by a handler The return value of the handler is ignored The parm parameter may be set to any integer value and may be used for any purpose If donow is set to true processing of the current message is suspended while the user message is processed by the system When the user message processing is complete this function returns and the current message continues processing Any pending exceptions are thrown in the calling function Setting donow to false causes the user message to be enqueued and handled as any other message 4 12 2 UserSendMsg Syntax usersendmsg startobj as objref msgnum as gt message parm as integer donow as boolean Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Parameters startobj First object in Z order to receive the message Only this object and its children will receive the message Specify a value of default to send the message to all objects msgnum The user message to send parm The integer parameter to associate with the sent message donow A flag to select preemption of the current message while the user message is processed Description This function sends the msgnum user message as a nor mal message it will go only to enabled objects starting with startobj in Z order Any object with a handler for msgnum is eligible to han
132. e the key board repeat delay which is the amount of time after the key is pressed before the first repeat character is generated In this case newvalue is of type syscmd_kbdrptdelay which is an enumerated type with the following legal values KBDRPTDELAY 250 KBDRPTDELAY 500 Delay 500 ms KBDRPTDELAY 750 Delay 750 ms KBDRPTDELAY 1000 Delay 1000 ms Delay 250 ms SYS KBDRPTRATE For systems with a keyboard interface change the key board repeat rate which is the number of characters generated per second after repeat begins In this case newvalue is of type syscmd_kbdrptrate which is an enumerated type with the following legal values KBDRPTRATE 300 30 0 KBDRPTRATE 26 7 26 7 cps KBDRPTRATE 24 0 24 0cps KBDRPTRATE 218 21 8cps KBDRPTRATE 200 20 0 KBDRPTRATE 18 5 18 5 cps KBDRPTRATE 17 17 1 cps KBDRPTRATE_16_0 16 0 cps KBDRPTRATE_15_0 15 0 cps KBDRPTRATE 13 3 13 3 cps KBDRPTRATE 120 12 0 cps KBDRPTRATE 10 9 10 9 cps KBDRPTRATE 100 10 0 cps KBDRPTRATE 9 2 9 2 cps KBDRPTRATE 8 5 8 5cps KBDRPTRATE 8 0 8 0cps KBDRPTRATE 7 5 7 5cps KBDRPTRATE 6 7 6 7cps KBDRPTRATE 6 0 6 0 cps KBDRPTRATE 5 5 5 5 cps KBDRPTRATE 5 0 5 0 cps KBDRPTRATE 4 6 4 6 cps KBDRPTRATE 4 3 4 3 cps KBDRPTRATE 4 0 4 0 cps KBDRPTRATE 3 7 3 7 cps KBDRPTRATE 3 3 3 3 cps Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTer
133. e updating the system software attributes so xpos and ypos should be assigned using the validation assignment operator The Tool_Persist function is called once for each property that was changed Message MSG_TOOL_GETHANDLES Description This message indicates that the object has been selected in Qlarity Foundry causing sizing handles resize grips to appear on the outline of the object The object designer has significant freedom to specify the number and location of the resize grips and the cursor that appears as the mouse cursor is positioned over the grip The handler is passed ref erences to three arrays that must be filled with the x posi tion y position and desired cursor respectively for each grip The handler should size the arrays to the number of grips that will be displayed on the object Handler Format func lt name gt lt xCoords gt as reference to gt integer lt yCoords gt as reference to gt integer lt cursors gt as reference to gt GuiCursors lt closed gt as reference to gt boolean handles MSG_TOOL_GETHANDLES 3 9 endfunc Parameters lt xcoords gt An array that defines the x position of each grip lt ycoords gt An array that defines the y position of each grip lt cursor gt An array that defines the cursor type for each grip lt closed gt A boolean value that determines whether a selection outline segment should be dr
134. ection 4 1 12 page 38 SetSerialTimeout setserialtimeout res as comm newtimeout as integer section 4 1 13 page 39 SetSystemSetting UIS ME atid section 4 18 14 page 87 settime day as integer month as integer gt SetTime dig2year as integer dotw as weekday hour as gt section 4 18 11 page 86 integer minute as integer second as integer SetTransparent settransparent newcolor as byte section 4 6 1 page 45 SetTTFAngle setttfangle theta as float section 4 7 9 page 60 SetVolume setvolume direction as volume adjust section 4 8 6 page 67 Sin sin x as float returns float section 4 11 1 page 73 SoftReset softreset rst as rstmode section 4 18 16 page 93 Sqrt as float returns float section 4 11 10 page 74 StopSpkr stopspkr section 4 8 5 page 67 Str str value as reference to anytype returns string section 4 10 1 page 71 Tan tan x as float returns float section 4 11 3 page 73 Throw throw loc as reference to byte msg as gt section 4 14 1 page 77 reference to byte Tool Persist tool persist x as reference to anytype section 4 17 1 page 82 Tool Trace tool trace str as string section 4 17 2 page 82 transmit resource as comm data as reference Transmit section 4 1 2 page to anytype block as boolean page 35 i h 1 gt TransmitUrgent transmiturgent channel as comm data as section 4 1 10 page 38 reference to anytype
135. ects in the object hierarchy Because the message handling system is highly dependent on Z order all changes to Z order requested by these functions are postponed until processing of the current message is complete Z order changes are then executed in the order in which they were requested 43 4 4 1 Attach Syntax attach obj as objref parent as objref Parameters obj A reference to the object that will be attached parent A reference to the new parent object Description This function attaches an object to a container The object being attached is placed in front of any other objects already attached to the parent If the object is already attached to the parent it will be moved to the top of the Z order 4 42 SendtoFront Syntax sendtofront obj as objref Parameters obj A reference to the object to be moved in Z order Description This function moves the object to the front of the list of chil dren of the object s parent If the object is the only child of its parent or is already at the front this has no effect 4 4 5 SendtoBack Syntax sendtoback obj as objref Parameters obj A reference to the object to be moved in Z order Description This function moves the object to the back of the list of chil dren for the object s parent If the object is the only child of its parent or is already at the back this function has no effect Opto 22 Fax 800 832 OPTO 6786 Web w
136. edge of any character in the font xnextline An integer to receive the horizontal offset from the origin of the first character on a line to the origin of the first character on the next line ynextline An integer to receive the vertical offset from the origin of the first character on a line to the origin of the first character on the next line font The bdffont resource flags A value of type font_flags see section 4 7 1 that deter mines how the text will be rendered Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Description This function returns important metrics for the font resource which can be used to determine values for parame ters in calls to DrawBdfText The diagram below illus trates the meaning of the various metrics This function is particularly useful when rendering multiple lines of text 4 maxright maxdown i i PONDE FORA U GU 1 lt gt maxleft gt v Origin of 4 5 xnextline next line 47 4 DrawBdfText Syntax drawbdftext x as integer y as integer gt width as integer height as integer gt xoffset as integer yoffset as integer gt font as bdffont data as reference to gt anytype flags as font flags Parameters x The x position of the upper left corner of the rend
137. eference gt to integer ypos as reference to gt integer widths as reference to gt integer heights as reference to gt integer xoffsets as reference to gt integer yoffsets as reference to gt integer indices as reference to gt integer lengths as reference to gt integer font as bdffont data as gt reference to anytype flags as font flags Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 58 Parameters multiflags An array of type multiline_flags indicating some infor mation on how well the lines fit within the specified region xpos An array of integers 0 th element indicates the x posi tion of the upper left corner of the rendered region relative to the calling object s parent Subsequent elements identify the relative horizontal offset from the initial x position where each line of text should be drawn array of integers 0 element indicates the y posi tion of the upper left corner of the rendered region relative to the calling object s parent Subsequent elements identify the relative vertical offset from the initial y position where each line of text should be drawn widths An of integers indicating the width for each line of text heights An array of integers indicating the height for each line of text xoffsets An array of integers indicating the horizontal off
138. ent y position of the object relative to its par ent GET WIDTH The current width of the object GET HEIGHT The current height of the object GET ORIGIN X The current origin x value for a container only Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual GET_ORIGIN_Y The current origin y value for a container only GET_XGLOBAL The current x position of the object top left of dis play 0 0 GET_YGLOBAL The current y position of the object top left of dis play 0 0 4 3 9 SetOrigin Syntax setorigin cont as objref originX as gt integer originY as integer Parameters cont The container for which to set the origin originX The x coordinate of the top left pixel in the container rela tive to the parent container origin Y The y coordinate of the top left pixel in the container rela tive to the parent container Description This function sets the origin of the container so that the upper left pixel of the container has the coordinates orig inX originY with a default value of 0 0 The orig inX and originY coordinates are relative to the container itself This causes all objects drawn on the con tainer to be shifted appropriately This does not change the manner in which the container s background is drawn 4 4 Manipulating Z Order These functions change the Z order of obj
139. eous Fatal Exceptions 109 B 20 Fatal Qlarity Foundry amp nennen nennen ettet nennen eene enne trennen enne 109 APPENDIX C QrARITY COMMAND LINE COMPILER svssissssscescsscsssssecscscasscenscossdeteisecsssecsdceciscossscacesboasssescassesetessscteesenscesossocsesescssssedssessiostee 111 APPENDIX D QLARITY FUNCTIONS QUICK REFERENCE 8 setae eaae stan seen see an sean seen ses ea seen sesta seen 113 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 Viii OptoTerminal Programmer s Reference Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 1 OPTOTERMINAL SOFTWARE FUNDAMENTALS 1 1 OptoTerminal Software OptoTerminal software is divided into four major compo nents as shown below Development User Objects and Environment SER Qlarity Foundry ay or text editor Qlarity Library Qlarity Objects Compiler lib Y Application Binary ile bff Download to Qlarity Terminal Runtime Environment Application Qlarity Terminal Event Qlarity API Messages Function Calls Qlarity Qlarity Terminal System Terminal Software amp Operating Hardware System 111 System Soft
140. er message handlers 1 5 6 Direct Messages Direct messages are sent by the system to a specific object These messages are enqueued in the message queue as are most other messages but they are only passed to a single object when they are handled Refer to section 3 6 for more information on direct mes sages 1 5 7 Tool Messages Because objects may be completely defined by the user Qlarity Foundry has no knowledge of the appearance or behavior of a given object Therefore the object itself must define its behavior for Qlarity Foundry development activi ties such as drag and drop resize by dragging resize grips on a selected object and so on Tool messages are generated by the Qlarity Foundry software to tell an object that these activities are taking place These messages are sent directly to the target object i e they do not propagate through the Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 object hierarchy The object should have message handlers for these events to properly function in Qlarity Foundry Refer to section 3 7 for a list of valid tool messages 1 5 8 Handling Events A message is handled by defining a global function or a function within an object that handles that event Because information about the event is often passed as a parameter to the handler function the handlers for a given message must follow a specific format number and type of parame ters and type of return
141. er string the name of the object ENABLED boolean indicates whether the object is eligible to process messages PARENT reference to container the parent container for the object Note that these attributes are NOT actual properties of the object However when using Qlarity to create an object property variables that represent these attributes are often Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual added to the object Regardless of whether the object itself maintains properties analogous to these attributes the attributes must be initialized and maintained by the object through Qlarity API function calls The enabled status of an object can be modified through the Enable API function and the parent can be assigned with the Attach API func tion All Qlarity API functions are described in Chapter 4 Qlarity API Function Reference 1 2 2 2 Area Objects The area object type includes objects that directly interact with the terminal display by drawing something on the dis play and or processing area based messages All area objects are rectangular Examples include a text object a bitmap object and a touch key object Area objects have the following built in data that is maintained by the system soft ware and accessible through the Qlarity API NAME character string the name of the object ENABLED boolean indicates w
142. ered region relative to the calling object s parent ty The y position of the upper left corner of the rendered region relative to the calling object s parent 57 width The width of the region to use for rendering height The height of the region to use for rendering xoffset The horizontal offset from the upper left corner of the ren dered region to the origin of the first character yoffset The vertical offset from the upper left corner of the rendered region to the origin of the first character font The bdffont resource data The data to be rendered as text The type can be a unibyte or byte array unistring or string flags A value of type font flags see section 4 7 1 which determines how the text will be rendered Description This function renders the text contained in and paints the rendered region to the display The width height xoffset and yoffset values are typically obtained from a call to GetBdfTextSize or inferred from metrics obtained from a call to GetBdfFontMetrics The rendered text is clipped if the area of the region defined by width and height is not sufficient or if the values of xoffset and yoffset place some or all of the text outside of the rendering region 4 7 5 DrawBDFTextFit Syntax drawbdftextfit multiflags as reference gt to multiline flags xpos as r
143. es that a system timer has expired When registering for this message an object specifies the interval between messages in 20 millisecond increments The minimum interval is 40 milliseconds A MSG TIMETICK message is sent to the registered object at each time interval Handler Format func name handles MSG TIMETICK Pewee endfunc Handlers for MSG_TIMETICK have no parameters and no return value Message MSG_KEY_DOWN Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 26 Description This message indicates that a key has been pressed on the keyboard or keypad The keyboard and keypad are distin guished by unique keycodes If the key repeat feature is available on the keyboard or keypad and the key is held down then the MSG_KEY_DOWN will only occur on the initial press not as the key is repeated Use this message to determine a key s state up or down use MSG_KEY_ PRESS to determine the character typed e g for a text edi tor To be eligible to process this message an object must register for it using the RegisterKey API function see section 4 2 3 Handler Format if handled by a container object global func lt name gt lt keycode gt as unibyte lt pass gt gt as boolean handles MSG_KEY_DOWN poss s endfunc Gf handled by an area non drawable object func name keycode as unibyte handles MSG KEY DOWN 8 65 endfunc Parameters
144. eturns comm Description This function returns the comm identifier for the current communications message 4 1 5 NetOpen Syntax netopen obj as objref prot as gt netprotocol localport as unibyte gt foreignport as unibyte ipaddr as gt reference to byte Parameters obj A reference to the object that will MSG COMM ACCEPT message see below receive the prot The protocol to be used for the connection see below localport The local port number to be used for TCP or UDP transmis sions foreignport The port number on the remote machine to be used for TCP or UDP transmissions ipaddr A 4 byte array containing the IP address of the remote machine Description The NetOpen function is used to establish an Ethernet communications channel NetProtocol is an enumerated type with the following legal values NET UDP Use the User Datagram Protocol UDP IP NET TCP Use the Transmission Control Protocol TCP IP NetOpen issues the request to open a communications channel When the channel is established the communica OptoTerminal Programmer s Reference Manual tions resource used to receive and transmit data is passed by the system to the object referenced by obj by the system in MSG COMM ACCEPT message This com munications resource is passed to the Send and Transmit API functions to indicate which network channel should be used for transmission It
145. eypad The keycodes must by logically OR ed with 0x8000 to obtain the actual keycodes that will be received by the application via keypad messages HW KEYBOARD Request information on the keyboard The returned byte array contains one byte which is set to 1 if a key board is present otherwise it is cleared to 0 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 84 HW_TEMPCONTROL Request information on the temperature compensation controller The returned byte array contains one byte which is set to 1 if a temperature compensation control ler is present otherwise it is cleared to 0 HW_CLOCK Request information on the real time clock The returned byte array contains one byte which is set to 1 if a battery backed real time clock is present otherwise it is cleared to 0 HW_DISPLAY Request information on the display The returned byte array combines four bytes with the display pixel width stored in the first two bytes MSB first and the display pixel height stored in the last two bytes MSB first Following the four bytes are three bytes indicating more about the type of display in the following order color tft and transflective A value of 0 for any of those three fields indicates that the display does not have that property HW_DEFAULTAPP Request information on whether a default application is available in the unit The returned byte array contains one byte which is set to if a defau
146. f The value obtained from this cast is the root or global container This is useful for certain comparisons for example if parent objref default then transmit coml str me gt is attached to ROOT n false endif 2 12 Functions Syntax func lt name gt lt var gt as lt data_type gt gt returns lt data_type gt handles lt msg_name gt Variable declarations and gt initializations statements endfunc Example func circ area x as float returns float dim pi as integer init pi 3 1415927 return x x pi endfunc Description A function can contain any number of input parameters separated by commas and statements If the function han dles any event messages the handles statement is used The handles statement must be the first statement in the function The dim and init statements must be the next statements in a function The actual order of dim and init statements is unimportant When a message is received by an object the function that handles the message is called The handles statement specifies the message type that must be sent for the function to be called There can be more than one handles message in a function as long as they appear before any other decla ration or statement See Chapter 3 Messages and Message Handler Prototypes for a complete listing of messages Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPT
147. f option name statements else statements endif Description statements are used by the compiler to determine if an option has been declared If so the code between the and the else or endif is compiled into the project Otherwise the enclosed code is not compiled Code in the Helse section is compiled only if the option was not declared ifnot else endif is also a legal construct where the code between the if and the else or endif is compiled if the option is not declared Otherwise the enclosed code is com piled Code in the else section is compiled only if the option was previously declared 2 21 2 option Syntax option lt option_name gt Description This function is used to define a keyword that will be checked by the statement Unlike Qlarity variables option declaration for a given keyword must be used before it can be examined by the statement Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 20 common predefined option is _TOOL which is defined if Qlarity Foundry is currently running the application Code that should only run in Qlarity Foundry and be excluded from the application that runs in the terminal should be enclosed in an if _TOOL endif block 2 21 3 Toolimage Syntax Toolimage lt string of hexadecimal digits gt Description This directi
148. f the text box height An integer to receive the height of the text box xoffset An integer to receive the horizontal offset from the upper left corner of the rendered region to the origin of the first character yoffset An integer to receive the vertical offset from the upper left corner of the rendered region to the origin of the first char acter font The ttfont resource The number for the desired face in the ttfont resource typi cally 0 ptsize The desired point size of the rendered text data The data to be rendered as text same types as BDF func tions allowed 59 flags A value of type font flags see below that determines how the text will be rendered Description This function finds the size of a given text string rendered in the given point size and typeface The calculated values are returned in the variables passed as parameters The width and height variables receive the width and height in pixels of the rendered region respectively The xoffset and yoffset variables receive the offset from the upper left corner of this region to the origin of the first rendered character The flags is of type font flags which is described in section 4 7 1 Typically this function is called as a precursor to calling DrawTTFText The width height xoffset and values obtained from this funct
149. ference Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 4 QLARITY API FUNCTION REFERENCE The Qlarity API Application Programming Interface is a library of functions that allow Qlarity applications to inter act with the Qlarity based hardware and perform common tasks that would be tedious or difficult to program in Qlar ity This chapter describes the available API functions their parameters and return values and the operations they per form 4 1 Communications Interface The communications API functions use an enumerated type called comm to specify the communications resource or interface Variables of type comm may be assigned the values COM1 for the primary serial interface 2 for the secondary serial interface or a value may be obtained from a call to NetOpen which assigns access to the Ethernet interface 411 Send Syntax send resource as comm data as anytype Parameters resource The communications resource to transmit the data data A byte array that contains the data for transmission Description This function generates a MSG_COMM_TRANSMIT mes sage The data in data is passed to any handlers for the message This function is useful when implementing a com mon transmission interface the MSG_COMM_TRANS MIT handler to perform protocolization gather statistics and so on 4 1 2 Transmit Syntax
150. ffer for serial communications on the specified interface The receive buffer is the maximum number of characters that can be received with a single MSG COMM RECEIVE message MSG COMM RECEIVE message is generated when ever 1 the receive buffer is full or 2 the receive buffer is not empty and no characters have been received for the tim eout period see SetSerialTimeout Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 1 13 SetSerialTimeout Syntax setserialtimeout res as comm newtimeout gt as integer Parameters res A serial communications resource COMI or COM2 newtimeout The desired number of 20 ms intervals that should elapse before a timeout occurs 1 20ms Description This function sets the timeout period for serial communica tions on the specified interface The timeout period is the maximum period of time between received characters before MSG COMM RECEIVE message is generated MSG COMM RECEIVE message is generated whenever 1 the receive buffer is full see SetSerialRecvSize or 2 the receive buffer is not empty and no characters have been received for the timeout period Setting the timeout period to 0 disables timeout meaning that MSG COMM RECEIVE messages are only generated when the receive buffer is full 4 1 14 SetCTS Syntax setcts resource as comm outValue as gt boolea
151. for urgent trans mission via TCP Description This function sends the data in data via TCP urgent data mode to the TCP communications interface specified by channel Transmission takes place in the back ground 4 1 11 GetNetChannellInfo Syntax getnetchannelinfo channel as comm prot gt as reference to netprotocol lport as gt reference to unibyte fport as reference gt to unibyte ipaddr as reference to byte OptoTerminal Programmer s Reference Manual Parameters channel The communications resource whose information will be returned prot A reference to type NetProtocol that will receive chan nel s protocol lport A unibyte variable that will receive channel s local port number fport A unibyte variable that will receive channel s foreign port number ipaddr A byte array that will receive channel s foreign IP address Description This function retrieves information about the channel communications resource The protocol local port number foreign port number and foreign IP address are stored in the reference parameters 4 1 12 SetSerialRecvSize Syntax setserialrecvsiz integer res as comm newsize as Parameters res A serial communications resource COM1 or 2 newsize The desired size for the receive buffer Description This function sets the size of the receive bu
152. ger gt yoffsets as reference to integer indices as gt reference to integer lengths as reference to gt integer font as sysfont facenum as integer gt ptsize as integer data as reference to gt sametype wordbrks as reference to sametype gt linebrks as reference to sametype font_flags flags as gt section 4 7 12 page 62 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 118 OptoTerminal Programmer s Reference Manual Function Syntax Reference getsystextsize width as reference to integer gt height as reference to integer xoffset as gt f to int ffset f t gt GetSysTextSize RA Wi as A 3 section 4 7 11 page 61 integer font as sysfont facenum as integer gt ptsize as integer data as reference to gt anytype flags as font flags GetTemperature gettemperature returns integer section 4 18 12 page 86 gettime day as reference to integer month as gt reference to integer dig2year as reference to gt GetTime integer dotw as reference to weekday hour as section 4 18 10 page 85 reference to integer minute as reference to gt integer second as reference to integer getttfontmetrics maxleft as reference to integer gt maxright as reference to integer maxup as gt reference to integer maxdown as reference t
153. getbytes tobreak as anytype bigendian as gt boolean returns byte Parameters tobreak The variable see description below containing the desired binary data bigendian The desired byte order for the data stored in tobreak A value of true stores the data in big endian byte order while a value of false stores the data in little endian byte order Description This function returns a byte array containing the binary data from the tobreak variable Only certain built in data types for tobreak are supported and the length of the returned byte array is as follows Data Type Size Integer 4 bytes Float 4 bytes in IEEE 754 format Boolean 1 byte Byte 1 byte Unibyte 2 bytes Array of one of the Size of data type see above Number of elements above data types 4 10 5 LowerCase Syntax lowercase str as byte returns string Parameters str The string to convert to lower case Description This function converts all capital letters in the str string to lower case letters and returns the resulting string Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 10 6 UpperCase Syntax uppercase str as byte returns string Parameters str The string to convert to upper case Description This function converts all lower case letters in st
154. gorithms can be found in A Painless Guide to CRC Error Detection Algorithms by Ross N Wil liams To continue calculating the CRC for a set of data in multiple parts call the function subsequently with the initial CRC set to the calculated CRC from the previous call In all but the final call xoronout should be 0 and reflectout should be FALSE Following are examples of some common algorithms CRC 16 CITT width 16 reflect FALSE lercin OxFFFF reflectout FALSE xoronout 0x0000 CRC 32 width 32 reflect TRUE fercin OxFFFFFFFF reflectout TRUE OXFFFFFFFF CRC 16 width 16 f reflect TRUE fercin 0x0 reflectout TRUE xoronout 0x0 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 96 Modbus width 16 reflect TRUE ercin OxFFFF reflectout TRUE 0 0 4 18 28 ZlibCompress Syntax zlibcompress out as reference to byte gt in as reference to byte Parameters out A data array to accept the compressed data This array is sized to fit the compressed data in The uncompressed data Description This function is used to compress data using the zlib library The zlib format is not fully compatible with other zip for mats alt
155. gt Example private dim hiddenvar as integer Description Object property variables can be declared as private or pro tected A variable that is declared as private can be used throughout the object template but cannot be referenced outside the template including in any object instance A protected variable may be accessed in the object template and in the declaration of an object instance of that template i e in variable initializations and in override functions within the instance Protected variables may also be accessed by templates that extend inherit from the tem plate in which they are defined No other access is allowed OptoTerminal Programmer s Reference Manual 2 8 Object References Object references are variables of type objref These vari ables can refer to an instance of an object There are two types of object references typed and untyped When writing Qlarity code the name of an object may be used wherever a reference to the object is desired 2 81 Untyped Object References Syntax dim lt name gt as objref Example assume that the object mycircle exists func untypedobjref dim anyobject as objref init anyobject mycircle zs endfunc Description Variables of this type cannot be used to access object prop erties or methods but they can be used anywhere else that an object name or object reference is required For example an objref can be passed to the Att
156. he top edge the origin of the text should be placed NOTE Specifying FONT_VTOP FONT_VBOTTOM or FONT_VCENTER overrides FONT_VABS FONT_VTOP Fit the text such that it is all top justified Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 56 FONT_VCENTER Fit the text such that it is all center justified vertically FONT_VBOTTOM Fit the text such that it is all bottom justified Multiple flags may be specified by combining them with a boolean AND operation Typically this function is called as a precursor to calling the DrawBDFTextFit API function All values obtained from this function call are used as parameters in the call to DrawBDFTextFit On return the array multiflags will contain information about how each line was rendered Any combination of the following flags can be expected MULTILINE_SOFTBREAK Use a boolean AND with this flag and the returned multiflags element to determine if the line was ter minated by using a soft break MULTILINE_WORDBREAK Use a boolean AND with this flag and the returned multiflags element to determine if the line was ter minated at a word break element MULTILINE_LINEBREAK Use a boolean AND with this flag and the returned multiflags element to determine if the line was ter minated at a line break element MULTILINE PARTIAL WIDTH Use a boolean AND with this flag and the returned multiflags element t
157. herwise line break characters are NOT drawn FONT DRAWWORDBREAKS Consider all word break characters as actually drawn when calculating fit otherwise word break characters are NOT drawn FONT NOSOFTBREAKS Disallow breaking a line anywhere that is not a line break or a word break 55 FONT_HBASELINE Instead of calculating the standard width text fits exactly in this width calculate the baseline width multiple lines will always have the same xoffset and thus will always line up properly FONT_HFIT Don t use the passed in width but calculate the actual width needed to fit all of the given text FONT_HABS Use the 0 th element of the xoffsets array to determine how far from the left edge the origin of the text should be placed NOTE Specifying FONT_HLEFT FONT_HRIGHT or FONT_HCENTER overrides FONT_HABS FONT_HLEFT Fit the text such that it is all left justified FONT_HCENTER Fit the text such that it is all center justified horizon tally FONT_HRIGHT Fit the text such that it is all right justified FONT_VBASELINE Instead of calculating the standard height text fits exactly in this height calculate the baseline height multiple lines will always have the same yoffset and thus will always line up properly FONT_VFIT Don t use the passed in height but calculate the actual height needed to fit all of the given text FONT_VABS Use the 0 th element of the yoffsets array to determine how far from t
158. hether the object is eligible to process messages PARENT reference to container the parent container for the object XPOSITION integer the horizontal displacement in pixels from the origin of the object s parent container Positive values indicate displacement to the right YPOSITION integer the vertical displacement in pixels from the origin of the object s parent container Positive values indicate downward displacement XSIZE integer the width of the object in pixels YSIZE integer the height of the object in pixels As with non drawable objects these attributes are not strictly properties of an object but the object often defines analogous properties In any event every object of this type must initialize and maintain these attributes through Qlarity API function calls The position and size of the object are established and can be modified through the Relocate and Resize API functions The enabled status of an object be modified through the Enable API function and the par ent can be assigned with the Attach API function The separation of these system software attributes and the object properties provides you with the freedom to choose properties that best describe an object There is no need to make the built in properties or system software attributes visible outside the object For example a circle object might best be described with a center point and a radius When the
159. hough it is possible to convert a zlib file to one that is compatible with the gzip file format For more informa tion visit the zlib web site 4 18 29 ZlibDecompress Syntax zlibdecompress out as reference to byte gt in as reference to byte Parameters out A data array to accept the compressed data This array is sized to fit the compressed data OptoTerminal Programmer s Reference Manual in The uncompressed data Description This function is used to compress data using the zlib library The zlib format is not fully compatible with other zip for mats although it is possible to convert a zlib file to one that is compatible with the gzip file format For more informa tion visit the zlib web site 4 18 30 SetPalette Syntax setpalette red as reference to byte gt green as reference to byte blue as gt reference to byte Parameters red Eight bit red color palette 256 byte array green Eight bit green color palette 256 byte array blue Eight bit blue color palette 256 byte array Description This function sets the color palette for many terminal dis plays Not all terminals support this API This function is considered an advanced function Please contact Technical Support if you need more details on this API Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 APPENDIX BUILT IN CONSTANTS AND DEFINED TYPES A 1 Constants
160. id You may wish to suppress those warnings from the output For applications developed in Qlarity Foundry you should usu ally specify s 19 58 25 which will suppress superfluous conversion warnings and BDF font warnings p option Defines an option as if you had used option option at the beginning of the source file Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 This appendix provides a list of the Qlarity API functions in alphabetical order for quick reference The syntax for each function s code is also listed For more information and a description of each function refer to the section and page APPENDIX D the statement is continued listed in the Manual Reference column QLARITY API FUNCTIONS QUICK REFERENCE LIST Each API function statement is defined as a single line of code In the following list when a statement wraps to the next line gt appears at the end of the line to indicate that Function Syntax Reference Acos acos x as float returns float section 4 11 5 page 73 11 h 1 f gt AllocateArrayHandle abe IIS PR section 4 9 12 page 70 anytype returns ArrayHandle arrayoperation arrl as reference to anytype gt Arra eration section 4 9 9 page arr2 as reference to anytype ArrayOp 9 9 page 69 Asin asin x as float retur
161. ied If neither FILE TEXT nor FILE BINARY is specified the access mode is determined as follows if the file exists it is opened in the same mode in which it was created if the file does not exist it is opened in text mode by default as if FILE TEXT were specified Files opened in text mode do not support overwriting data in the file There are a limited number of files that can be open at any one time currently 7 4 16 9 CloseFile Syntax closefile fnum as filedesc Parameters fnum File handle returned from an OpenFile call Description This function closes a file The fnum file handle is invalid after a call to this function 4 16 10 ReadFile Syntax readfile fnum as filedesc var as gt reference to anytype Parameters fnum File handle of desired file var Variable of any type to receive data read from the file Description This function reads data from the specified file and stores the data in variable var Data is read starting at the cur rent position in the file If the access mode of the file is binary the number of bytes needed for var is read from the file and stored in var For arrays in binary mode the size of the array determines the number of items read from the file In text mode one line of data bytes up to but not including the newline character 0x10 is read from the file and is converted to var s data type as with a call to the Val
162. iet gt 79 4 16 6 Erase File uni eR ted RR ette e E ahi re idi 79 4 16 7 GetFileInto o n tei ip t Pat n ee uode aum 79 4 6 8 Open Files 2 4 d ndn c ete er Ret a TN ER ER Seeds Ed 80 4 16 9 CloseFile teer irent RD EUER 80 4 16 10 ReadEMe eim e tc er REA send ORE FO S le EFRON RE REC Pd 80 AV Oe bE WriteEtle iet teta meteo ed nra RE 81 4 16 12 SetFilePO0S ene tere ttt ee A E RM E e ERR ed od eti dde 81 4 16 13 GetEileP68 inerte reo tae ee rd ee o pede 81 4 16 14 EndOfFile ere teet e ete e Re dus E 81 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 vi OptoTerminal Programmer s Reference Manual 4 16 15 ErasePileS pace ote eee ett eee tle pall Ave diese asl e Sede 81 4 16 16 RenambeEile isque rd o RH URS UR er a tne o e te n d 81 4 17 Qlarity Foundry F nctions eet tdv t b eet ERE re E ge Ege cules REN CY t e Yee ER 82 Zi Lool otio eese ito ete ttes alten sie 82 4 172 Tool LT PAC Cs d cbe e ee ree OE 82 4 18 Miscellaneous Eunctions s utei e Re e e RERO ER E e e ca e RR erbe 82 CHIMICA E 82 4 182 ReadGPIO nece e e RARO IDEO att up 82 4 18 3 SeEtGPIOD rect Om ite ettet te ee e DS ERR ERU E ee ecu ue iens 83 4 184 GetV
163. integer gt ptsize as integer data as reference to gt anytype flags as font flags section 4 7 15 page 64 DrawTTFText drawttftext x as integer y integer height as integer yoffset as integer font as integer ptsize as integer to anytype as integer width as gt xoffset as integer gt ttfont facenum as gt data as reference gt flags as font flags section 4 7 8 page 60 Enable enable obj as objref flag as boolean section 4 3 4 page 41 EnableKeypadBacklight enablekeypadbacklight enable as boolean section 4 18 8 page 85 EndOfFile endoffile fnum as filedesc returns boolean section 4 16 14 page 81 EraseFile rasefile name as reference to byte section 4 16 6 page 79 EraseFileSpace rasefilespace section 4 16 15 page 81 Exp exp x as float returns float section 4 11 8 page 74 FakeKeyMsg fakekeymsg msgtype as fake key keycode as UNIBYTE section 4 12 4 page 75 fakescreenmsg msgtype as fake screen xl as gt FakeScreenMsg integer yl as integer x2 as integer y2 as section 4 12 5 page 75 integer find match as reference to sametype start as gt Find integer length as integer pattern as section 4 9 6 page 69 reference to sametype returns integer FreeArrayHandle freearrayhandle handle as ArrayHandle section 4 9 10 page 70 f f gt 1 FromBytes rombytes yar as reference to anytype
164. ion This directive informs Qlarity Foundry about the visible state of an object whether an object should be dis played or hidden Normally Qlarity Foundry inserts or alters this directive whenever you click on the eye icon in the Object Tree This directive is ignored when a workspace is compiled with the command line compiler 2 21 7 Lock Syntax Lock lt true false or me gt Description This directive informs Qlarity Foundry about the lock state of an object i e whether an object or its children can be altered in Qlarity Foundry Normally Qlarity Foundry inserts or alters this directive whenever you click on the lock icon in the Object Tree This directive is ignored when a workspace is compiled with the command line com piler 2 21 8 STPBuilderApp Syntax STPBuilderApp Description This directive appears on the first line of a workspace that has been saved by Qlarity Foundry It is ignored when a workspace is compiled with the command line compiler 2 21 9 endfile Syntax endfile Description This directive instructs the compiler to immediately cease processing the current file Any code after the endfile directive is ignored Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 3 MESSAGES AND MESSAGE HANDLER PROTOTYPES In Qlarity functions that handle messages must fit a speci fied format or number and type of p
165. ion call are used as parameters in the call to DrawTTFText 477 GetTTFFontMetrics Syntax getttfontmetrics maxleft as reference to gt integer maxright as reference to integer gt maxup as reference to integer maxdown as gt reference to integer xnextline as gt reference to integer ynextline as gt reference to integer font as ttfont gt facenum as integer ptsize as integer gt flags as font_flags Parameters maxleft An integer to receive the maximum distance in pixels from a character origin to the left edge of any character in the font maxright An integer to receive the maximum distance from a charac ter origin to the right edge of any character in the font maxup An integer to receive the maximum distance from a charac ter origin to the top edge of any character in the font maxdown An integer to receive the maximum distance from a charac ter origin to the bottom edge of any character in the font Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 60 xnextline An integer to receive the horizontal offset from the origin of the first character on a line to the origin of the first character on the next line ynextline An integer to receive the vertical offset from the origin of the first character on a line to the origin of the first character on the next line font The ttfont resource The number for the desired
166. is also used to register for MSG COMM RECEIVE messages generated by the net work channel If foreignport is set to 0 the Olarity based terminal acts as a server listening for TCP connection requests or UDP datagrams on the port specified by localport Connec tions or datagrams with any foreign port number are accepted on this local port When a new connection or data gram from a unique foreign port is accepted a network channel is allocated and passed to the application in a MSG COMM ACCEPT message If no TCP connection is established or UDP datagram received the application con tinues to listen on the specified local port until the terminal is reset NOTE This is a deprecated method for starting network servers Use the NetServerOpen API function instead Up to 64 channels 32 TCP channels may be open at any given time Channels may be released by calling Net Close Multicast Information Only If you are opening a multicast channel any class D IP address the following information applies Calling NetOpen and specifying any class D IP address for the ipaddr parameter will open a multicast channel You must specify NET UDP as the protocol TCP IP does not support multicast communication The foreignport parameter is only used to specify which port outgoing transmissions will be directed to Incoming transmission s foreign port are not compared against this parameter In other wor
167. is is calculated otherwise it is the same value as was passed in heights An integer array used as both an input and an output For input the O th element is used to indicate the total height in pixels of the box that the text needs to fit into if OptoTerminal Programmer s Reference Manual FONT VFIT is specified this value is only used for align ment purposes On return the height for each line of text will be in the individual elements of the array with the 0 th element always containing the final full height of all the text lines if FONT VFIT is specified then this is calculated otherwise it is the same value as was passed in 1 An integer array used as both an input and an output For input if FONT_HLEFT FONT HRIGHT FONT HCENTER is not specified by default this is the case the O th element is used to determine how far from the left edge the origin of the first text character should be On return the elements indicate how far from the left edge each line s origin should be placed yoffsets An integer array used as both an input and an output For input if FONT_VTOP FONT_VBOTTOM FONT_VCENTER is not specified by default this is the case the 0 th element is used to determine how far from the top edge the origin of the first text character should be On return the elements indicate how far from the top edge each line s origin should be placed indices An integer arra
168. it erases any drawing in the corners of the border when using a curved border This is intended for objects drawing their outside border where previous drawing code may have drawn outside the border BDR_INVERSE Draw the border in inverse This causes raised borders to appear sunken and sunken borders to appear raised Flat borders draw using their natural inverse color BDR_FGCURVES This option is occasionally used for borders on the inte rior of an object Specify this option with a rounded border to cause the area inside the border rectangle but outside of the curves to be filled in with the foreground color 4 6 22 GetObjPixmapRegion Syntax getobjpixmapregion x as integer as gt integer width as integer height as gt integer Parameters x The x position of the first pixel to read relative to the object The y position of the first pixel to read relative to the object width The variable passed in as width should contain the desired width of the resultant pixmap Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual height The variable passed in as height should contain the desired height of the resultant pixmap Description This function is used to retrieve a region of the pixel map for an object This pixel map indicates the individual colors drawn up to this point in each pixel location for the object b
169. ithin the same function Jumping between functions is not allowed Also you cannot jump into out of or between different check error blocks It is generally good coding practice to avoid goto when ever possible 2 15 Exception Handling Syntax check error 6 1 error sate enderr Description The purpose of the check error block is to check for an error and then resolve the error The code between check error and error is executed normally If an exception is thrown by the system or by using the Throw API func tion then execution immediately jumps to the first state 17 ment in the on error block with no option to return to the previous execution point Within the on error block the application can retrieve the last exception using the GetException API function Code in the on error block is intended to handle exceptions in a manner defined by the application If the error block doesn t resolve the exception it can call Rethrow to allow a higher level check error to handle it If no check error block appears in the function the error bubbles up to the function that called it and eventually out to the system where MSG ERROR functions can handle it For more detailed information on exception handling refer to the section onf Exception Handling in the OptoTerminal Qlarity Foundry User s Manual 2 16 Defining Objects Syntax define o
170. late and by other templates which extend the template 2 12 3 Validation Methods A very powerful and useful feature of Qlarity is the valida tion method These special functions are tied to variables usually object properties When the variable is assigned a value using the validation assignment operator the vali dation method is implicitly called and passed the new value as a parameter This allows the object property or global variable to perform validation on the new value e g is the value within allowable bounds and to perform other Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual actions that update the state of the object or variable in the application Qlarity objects derive much of their power from this feature For example a simple area object might have properties defining the location of the object on the display The vali dation methods for the x and y position properties might check to make sure that the value is within the boundaries of the screen and call Qlarity API functions to redraw the object at the new location All of this occurs from simple assignment of a new value to the object property A validation function must have the same name as the vari able being validated Also there can be only one parameter to the function and it must be of the same data type as the associated variable Otherwise these functions have the sa
171. layNoteNotify and PlaySoundNotify API functions The lt parm gt parameter Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual allows the application to determine which sound has com pleted Handler Format func lt name gt lt remaining gt as integer gt lt parm gt as integer handles MSG_SOUND_DONE 2524 endfunc Parameters lt remaining gt Number of sound events notes and sounds that remain to be played by the system lt parm gt The identifier that was passed to the PlayNoteNotify or PlaySoundNotify API functions as the lt parm gt parameter 3 7 Tool Messages Because objects may be completely defined by the user Olarity Foundry has no knowledge about the appearance or behavior of a given object Therefore the object itself must define its behavior for Qlarity Foundry development activi ties such as drag and drop resize by dragging resize grips on a selected object and so on Tool messages are generated by the Qlarity Foundry system software to tell an object that these activities are taking place The object must have mes sage handlers for these events to properly function in Qlar ity Foundry Tool message handlers must be enclosed in if TOOL ftendif compiler directives This only includes the handlers used during development with Qlarity Foundry Since the tool message handlers usually change the proper ties of
172. le which is used in calculating CRCs More information on specifying CRC algorithms can be found in A Painless Guide to CRC Error Detection Algorithms by Ross N Williams Following are examples of some common algorithms CRC 16 CITT width 16 poly 0x1021 reflect FALSE CRC 32 width 32 poly 0x04C11DB7 reflect TRUE 16 width 16 0 8005 freflect TRUE Modbus f width 16 poly 0x8005 freflect 4 18 27 CalculateCRC Syntax calculatecrc table as reference to gt integer width as integer reflect as gt boolean crcin as integer reflectout as gt boolean xoronout as integer data as gt reference to byte returns integer 95 Parameters table The CRC table calculated from CreateCRCTable width The number of bits minus one used in the polynomial for the desired CRC reflect Whether or not to use a reflected algorithm reflects incom ing data crcin The initial CRC value reflectout Whether or not to reflect the final CRC before xor ing it with xoronout xoronout The value to xor the final CRC to before returning data The array of byte data for which to calculate the CRC Description This function calculates the CRC for a set of data using the parameters to describe the algorithm More information on specifying CRC al
173. led by a container object func lt name gt lt pass gt as boolean handles MSG_DRAW 3 55 7 endfunc if handled by an area object func name handles MSG DRAW Es endfunc Parameters if handled by a container object pass False if the container s children have not yet received the message and true if the container s children have already received the message A container should draw its back ground when pass false and its borders when pass true Gf handled by an area object No parameters 3 4 Registered Messages Registered messages are associated with system events such as a serial character receive network packet receive or Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 24 timer tick Event handlers that process these messages registered with the system software using registration func tions in the Qlarity API Because these events are usually handled by a small number of functions registration avoids the need to filter the message through the entire object hier archy If the handler in the registration list is an object method the object owning the method is checked by the system software to ensure that it and every parent container back to the root container are enabled If this condition is satisfied the event handler is called Because the root con tainer cannot be disabled global function event handlers are called without this
174. legal focal distance edge distance ratio EXCEPT NOSTARTPT start point EXCEPT_NOENDPT Sahe some up end point EXCEPT_SCANFILLERROR Scanfill of area unsuc cessful EXCEPT_MISMATCHPTS EXCEPT_NOGETPIXMAP Mismatch in number of points Unable to capture chil dren in object pixel map Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 106 B 6 Array Exceptions OptoTerminal Programmer s Reference Manual EXCEPT BAD FORMAT Bad format string EXCEPT ARR NOREDIM Particular array is not redimmable EXCEPT BADVALUE Value is not within expected range EXCEPT_NOARRSUPPORT No support for action on array EXCEPT_BAD_ARRSIZE Array has incorrect size EXCEPT_ARRINDEX Illegal index into an array B 7 Z Order Exceptions EXCEPT MISSING ENTER No enter key specified in password EXCEPT HWARE INUSE Hardware currently in use EXCEPT_NOATTACHABLE Impossible attach ment request EXCEPT_INVAL_TYPE Invalid type EXCEPT_INVAL_HANDLE Invalid array handle EXCEPT NOZACTION Unable to queue up Z order change EXCEPT INVAL ARROP Invalid array operation EXCEPT DATA CORRUPT Corrupted data EXCEPT OBJNOTCONTAINER Object is not con tainer EXCEPT ZLIBFAULT ZLib library
175. lity newvalue must be of type syscmd_usepassword As there is no current value for this setting using SYSACT DONOW will not do anything and using SYSACT ALWAYS will only set the pending save set ting The values are USEPASSWORD OFF USEPASSWORD ON Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual SYS_TEMPERATURE Set this value to the current temperature to calibrate the temperature reported by the terminal newvalue must be a float SYS FEEDBACK TYPE Specify the method of feedback that the unit will use to report development information as well as any severe runtime errors through newvalue must be of type syscmd feedback and must at least have one of the methods selected The values are FBTYPE SERIAL FBTYPE VIDEO FBTYPE UDP The values can be combined together to produce any combination desired using the AND operator as in SERIAL AND FBTYPE VIDEO SYS FEEDBACK IPADDRESS If the unit is Ethernet enabled and using UDP feedback this option specifies the IP address to send all UDP feedback information to newvalue is therefore a 4 byte array containing the IP address SYS FEEDBACK FPORT If the unit is Ethernet enabled and using UDP feedback this option specifies the foreign port number to send all UDP feedback packets to newvalue in this case is an integer and can be any numbe
176. lt application is present otherwise it is cleared to 0 HW_MACADDRESS Request information on what the Ethernet address of the unit is The returned byte array contains a six byte Ethernet address HW_AUDIOCODEC Request information on the audio capabilities of the terminal The returned byte array contains one byte which is set to 1 if an audio decoder is present other wise it is cleared to 0 HW_GPIO Request information on the general purpose digital input output GPIO capabilities of the terminal The returned byte array contains one byte which is set to 1 if GPIO is present otherwise it is cleared to 0 HW_CPU Request information on the type of CPU present in the unit and its execution frequency The returned byte contains the text name of the CPU a character OptoTerminal Programmer s Reference Manual and some text indicating the instruction execution fre quency in Hertz HW_COMLIST Request information on which communications ports are present The returned byte array will contain a 1 in every location that a com exists COMI would corre late with the 0 th element in the array The size of the array will depend on how many serial ports are installed Serial ports do not exist if there is no corre sponding element in the array HW MEMORY Request statistics on unit memory The first four ele ments of this byte array indicate the total amount of RAM that the unit has MSB The next four ele
177. lted in the generation of this mes sage Handler Format func lt name gt lt data gt as byte lt lport gt as gt unibyte lt fport gt as unibyte lt ip gt as gt byte returns boolean handles MSG_COMM_RECEIVE_MULTICAST endfunc Parameters lt data gt A byte array containing the information that was received from the communications interface port The local port number on the unit that the received data was destined for lt fport gt The foreign port number on the host that was the origin of the data lt ip gt The IP address of the host that was the origin of the data 25 Message MSG_COMM_TRANSMIT Description This message indicates that one or more characters are to be transmitted by the communications interface EIA 232 422 485 Ethernet etc This message is generated by call ing the Send API function and it is useful for implement ing a protocolizing function adding a header tail checksum etc for transmitted data in a single location Handlers for this message should call the Transmit API function to actually send the data Handler Format func name returns gt boolean handles MSG COMM TRANSMIT endfunc data as byte Parameters data A byte array containing the data that is to be transmitted by the communications interface Message MSG TIMETICK Description This message indicat
178. me syntax as normal functions IMPORTANT Do not use the validation assignment operator on the validated variable within the validation method This will recursively call the validation function until the system software gives an exception Example dim x as integer dim flag as integer func x newval as integer if newval gt 20 amp newval lt 100 then x newval else flag 1 endif endfunc In this example if the new value being assigned is not between 20 and 100 then flag is given 1 and x retains its old value If no new value is assigned to the variable during its validation function then it will retain its old value 2 12 4 Array Validation Functions Syntax func lt array_name gt lt data_type statements endfunc lt newarray gt as gt These functions are called when the entire array is assigned a new value with the validation assignment operator 15 Example dim array1 10 array2 20 arrayl array2 as integer If a validation function for array1 exists it will be called and passed to 2 as a parameter Example dim myarray 10 as integer func myarray newarray as integer if len newarray 10 then myarray newarray endif endfunc 2 12 5 Array Element Validation Functions Syntax func array name new value as gt data type index as integer statements endfunc Description These functions are calle
179. ments indicate the total amount of flash memory available MSB The last four elements indicate an estimate of the current amount of RAM the unit still has available MSB 4 18 6 SetContrast Syntax setcontrast direction as contrast adjust Parameters direction A value of type contrast adjust see below that deter mines how to adjust the contrast Description This function adjusts the contrast of the display at runtime 1 not with Power On Setup The adjustment is tempo rary and is forgotten when power is removed from the ter minal Permanent changes to the contrast setting must be made with the Power On Setup utility or the SetSystemSet ting API function The SetContrast function takes an argument of type contrast adjust which is a defined type with the follow ing legal values CONTRAST LIGHTER Adjust the contrast one step lighter CONTRAST DARKER Adjust the contrast one step darker Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 18 7 SetBacklight Syntax setbacklight command as backlight adjust Parameters command A value of type backlight_adjust see below that deter mines how to adjust the backlight setting Description This function adjusts the backlight setting of the display at runtime i e not with Power On Setup The adjustment is temporary and is forgotten when power is rem
180. minal Programmer s Reference Manual KBDRPTRATE 3 0 3 0 cps KBDRPTRATE 2 7 2 7 cps KBDRPTRATE 2 5 2 5 cps KBDRPTRATE 2 3 2 3 cps KBDRPTRATE 2 2 1 cps KBDRPTRATE 2 0 2 0 cps SYS KEYRPTDELAY For systems with a keypad interface change the keypad repeat delay which is the amount of time after the key is pressed before the first repeat character is generated newvalue is an integer indicating the number of milliseconds for the delay The minimum delay is 20 ms and the maximum delay is 2000 ms The value is rounded to the nearest 20 ms increment SYS KEYRPTPERIOD For systems with a keypad interface change the keypad repeat period which is the amount of time between repeat characters after repeat has begun newvalue is an integer indicating the number of milliseconds for the delay The minimum delay is 20 ms and the maxi mum delay is 2000 ms The value is rounded to the nearest 20 ms increment SYS KEYCLICK For systems with a keypad interface enable or disable the audible key click which is a short beep generated whenever a key is pressed newvalue must be a boolean TRUE enables the key click and FALSE dis ables it SYS KEYRPT For systems with a keypad interface enable or disable the key repeat feature newvalue must be a bool ean TRUE enables key repeat and FALSE disables it SYS COMIBAUD SYS COM2BAUD SYS_COM3BAUD SYS COMABAUD SYS COMSBAUD SYS_COM6BAUD SYS COMT7BAUD S
181. n Parameters resource The communications resource in which to change the CTS line outValue The value to be placed on the CTS line Description This function is used to set the CTS line on a serial port of the Qlarity based terminal if the line is available for use RTS CTS flow control is only supported for the 232 interface 39 4 1 15 ReadRTS Syntax readrts resource as comm returns boolean Parameters resource The communications resource from which to read Description This function is used to read the RTS line on a serial port of the Qlarity based terminal if the line is available for use RTS CTS flow control is only supported for the EIA 232 interface 4 1 16 SetDSR Syntax setdsr resourc outValue as boolean as comm Parameters resource The communications resource to change the DSR line of outValue The value to be placed on the DSR line Description This function is used to set the DSR line on a serial port of the Qlarity based terminal if that line is available for use NOTE The DSR line is not available on the Qlarity based terminal primary or auxiliary serial ports It may be available on expansion serial ports 4 1 17 ReadDTR Syntax readdtr resource as comm returns boolean Parameters resource The communications resource from which to read Description This function is used to read the DTR line on a serial p
182. n DEPRECATED USAGE This function will also accept a boolean value A value of true for cachelevel selects CACHE ALL and a value of false selects CACHE OFF 4 6 20 IgnoreDrawCache Syntax ignoredrawcache obj as objref ignore as gt boolean Parameters obj A reference to the object desiring to change status flag A boolean flag containing the desired status A value of true sets the object to ignore the drawcache setting and a value of false sets the object to use the drawcache setting the default setting Description This function is used to cause an object to ignore the draw cache settings so it will always get a draw when another object is drawn in its area Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 52 4 6 21 DrawBorder Syntax drawborder xl as integer yl as integer gt x2 as integer 2 as integer style as gt integer drawFlags as unibyte Parameters 1 The left edge of the border yl The top edge of the border 2 Either the right edge of the border or the width of the bor der rectangle depending on whether BDR_WIDTHHEIGHT was specified for the drawFlags parameter y2 Either the bottom edge of the border or the height of the border rectangle depending on whether BDR_WIDTHHEIGHT was specified for the drawFlags parameter style A special integer value that specifies how the border is to be
183. nce to byte section 4 3 1 page 41 GetPosInfo getposinfo obj as objref returns integer pval as position info section 4 3 8 page 42 GetProfileTick getprofiletick returns integer section 4 18 22 page 94 GetRandomNum getrandomnum returns float section 4 18 17 page 93 GetScreenPixmap getscreenpixmap x as integer as integer height as integer y as integer width gt returns color section 4 6 18 page 51 GetSysFontCharacters getsysfontcharacters font as sysfont facenum as gt integer bRange as unibyte eRange as unibyte gt returns unibyte section 4 7 10 page 61 GetSysFontMetrics getsysfontmetrics maxleft as reference to integer gt maxright as reference to integer maxup as gt maxdown as reference to gt xnextline as reference to integer gt as reference to integer font as gt facenum as integer ptsize as integer gt font flags reference to integer integer ynextlin sysfont flags as section 4 7 13 page 63 GetSystemSetting getsystemsetting cmd as syscmd var as reference gt to anytype which as syscmd_readfrom section 4 18 15 page 92 GetSysTextFit getsystextfit multiflags as reference to gt multiline_flags xpos as reference to integer gt ypos as reference to integer widths as gt reference to integer heights as reference to gt integer xoffsets as reference to inte
184. ne 800 321 OPTO 6786 120 OptoTerminal Programmer s Reference Manual Function Syntax Reference REECE OUT objref width as integer height gt section 4 5 2 page 44 as integer Rethrow rethrow section 4 14 3 page 77 reversefind match as reference to sametype gt ReverseFind start as integer len as integer pattern as gt section 4 9 13 page 70 reference to sametype returns integer b d byte byte bl byt gt RGB bI Me ee RL ES section 4 6 5 page 45 returns color Right PrgHtuert Dl as reference to sametype len as gt section 4 9 3 page 68 integer returns sametype SeedRandomNum seedrandomnum section 4 18 18 page 93 Send send resource as comm data as anytype section 4 1 1 page 35 SendtoBack sendtoback obj as objref section 4 4 3 page 43 SendtoFront sendtofront obj as objref section 4 4 2 page 43 setarraydata arr reference to sametype index gt SetArrayData as integer srcdata as reference to sametype gt section 4 18 25 page 94 Srcindex as integer len as integer SetBacklight setbacklight command as backlight adjust section 4 18 7 page 85 SetBgColor setbgcolor newcolor as byte section 4 6 4 page 45 SetBreak setbreak resource as comm state as boolean section 4 1 3 page 35 SetCapture setcapture obj as objref section 4 13 1 page 76 SetContrast setcontrast
185. ne segments connecting the endpoints of the arc to the center in the foreground color ELLIPSE CONNECT ENDS Draw a line segment connecting the endpoints of the arc in the foreground color Multiple flags may be specified by combining them with a boolean AND operation 4 6 17 GetEllipseSize Syntax getellipsesize maxleft as reference to gt integer maxright as reference to integer maxup as reference to integer maxdown as gt reference to integer as float xfocal gt as float yfocal as float theta as float gt gamma as float flags as ellipse flags OptoTerminal Programmer s Reference Manual Parameters maxleft An integer to receive the maximum distance in pixels from the center to the left edge of the ellipse maxright An integer to receive the maximum distance from the center to the right edge of the ellipse maxup An integer to receive the maximum distance from the center to the top edge of the ellipse maxdown An integer to receive the maximum distance from the center to the bottom edge of the ellipse a The distance along the primary focal point vector from the center to the edge of the ellipse xfocal The horizontal distance from the center to the primary focal point of the ellipse yfocal The vertical distance from the center to the primary focal point of the ellipse theta The angle in radians from the primary focal point vector segment to the starting point
186. ns aieo tates t pe dues e Dna HER de A o t p ea eges 15 2 12 5 Array Element Validation Functions nennen nenne nennen nennen etre tenni teen ene nnns 15 2 12 6 Reference Parameters uio eee eode peine HE rode eu ertet 15 213 Conditionals if Statement dese ese ele enna ees URN tmv ua x uH 16 2 14 Looping and Leapimng ii oet ee tr etit i ERI Re cro m d e i e ede ete eite deeds 16 2 4 1 For Next loops rr EE Oe ae ed o We d o e v EP RE Se 16 2 142 While Eoops edet DDGPHQUDBGUPUM OH REERHHIUHHERREIUHUON 16 2 4 3 Do While Eo09ps iini ee ette HERE E E HY RE Ee P e d dede RR 17 2 14 4 Goto LEabel 5 ge eto m RO D E aea tat ten 17 2 15 Exception Handling ee ese ade eed ca te e e Ee CE D e Ee ea cec e ae NS 17 2 16 Defining Objects elo ad die m em TERRE QE 17 2 17 Declaring Object Instances in t dette tr IN De e Re cubes e D ERE vere ee 18 2218 Level iino eta ee Det a b o ere etie tete 18 2 19 Including Files and Resources hack em d eae ped des eet Eea codi ea e e vecta Vea eMe 18 2 20 Jabraries A eno teo eipegnP peque iqq neue pedites 19 2 2 Precompile Directiv68 in as ee e RR ERU HE HR ETE RUE TREE EET UE ERI RE E CHER aaa E eq Ln 19 2 2L 1 T tftelse Bendit 5 ioa heu qu a at pe ds 19 D212 oL E n 19 2 21 3 f Toolimage icit B dom dp 20 2 214 dS Ihddens nue eased
187. ns float section 4 11 4 page 73 Atan atan x as float returns float section 4 11 6 page 73 Attach attach obj as objref parent as objref section 4 4 1 page 43 calculatecrc table as reference to integer gt width as integer reflect as boolean crcin as gt CalculateCRC integer reflectout as boolean xoronout as gt section 4 18 27 page 95 integer data as reference to byte returns gt integer ChangeCurDir changecurdir name as reference to byte section 4 16 3 page 78 ChangePort changeport channel as comm newport as unibyte section 4 1 9 page 38 CloseFile closefile fnum as filedesc section 4 16 9 page 80 Concat concat strA as reference to sametype gt section 4 9 7 page 69 strB as reference to sametype returns sametype Cos cos x as float returns float section 4 11 2 page 73 1 idth 1 i 1 j gt x CreateCRCTable createcrctable width as INESIS poly as integer section 4 18 26 page 95 reflect as boolean returns integer DelayMS delayms delay as integer section 4 18 23 page 94 drawbdftext as integer as integer width as gt DrawBdfText integer height as integer xoffset as integer gt section 4 7 4 page 57 yoffset as integer font as bdffont reference to anytype data as gt flags as font_flags Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 114 OptoTerminal Programmer s Reference Manual Function Syntax Referenc
188. nteger dotw as weekday hour gt as integer minute as integer second as gt integer Parameters An integer indicating the current day of the month month An integer indicating the current month dig2year An integer indicating the last two digits of the current year dotw A variable of type weekday see below indicating the current day of the week OptoTerminal Programmer s Reference Manual hour An integer indicating the current hour military time minute An integer indicating the current minute second An integer indicating the current second Description This function sets the current time which is maintained by the real time clock hardware The variable dotw is of type weekday which is a defined type with the following self explanatory legal values SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY 4 18 12 GetTemperature Syntax gettemperature returns integer Description This function returns the current temperature degrees Cel sius inside the terminal case The Qlarity based hardware includes a temperature sensor that is used to implement temperature compensation of display contrast The sensor is accurate to approximately 2 C and is calibrated by a set ting in the Power On Setup utility 4 18 13 TypeOf Syntax as reference to integer gt name as reference to gt typeof uniqu obj as objref byte
189. o gt GetTTFFontMetrics integer xnextline as reference to integer gt section 4 7 7 page 59 ynextline as reference to integer font as gt ttfont facenum as integer ptsize as integer gt flags as font flags getttftextsize width as reference to integer gt height as reference to integer xoffset as gt reference to integer yoffset as reference to gt GetTTFTextSize 1 section 4 7 6 page 59 integer font as ttfont facenum as integer gt pag ptsize as integer data as reference to gt anytype flags as font_flags GetVersion getversion returns float section 4 18 4 page 83 IgnoreDrawCache ignoredrawcache obj as objref ignore as boolean section 4 6 20 page 51 Left Pere as reference to sametype len as gt section 4 9 2 page 68 integer returns sametype Len len arr as reference to anytype returns integer section 4 9 1 page 68 Ln 1 as float returns float section 4 11 9 page 74 Lower lower obj as objref section 4 4 5 page 44 LowerCase lowercase str as byte returns string section 4 10 5 page 72 MakeDir makedir name as reference to byte section 4 16 2 page 78 Mid midtarrt as PERCE CREE to sametype index as gt section 4 9 4 page 68 integer len as integer returns sametype NetClose netclose channel as comm section 4 1 7 page 37 netsenddatagram localport as unibyte foreignport gt NetSendDatagram as unibyte ipaddr as reference to byte data
190. o determine if the line only fits partially inside the given width MULTILINE NONE WIDTH Use a boolean AND with this flag and the returned multiflags element to determine if the line did not fit at all inside the given width MULTILINE PARTIAL HEIGHT Use a boolean AND with this flag and the returned multiflags element to determine if the line only fits partially inside the given height MULTILINE NONE HEIGHT Use a boolean AND with this flag and the returned OptoTerminal Programmer s Reference Manual multiflags element to determine if the line did not fit at all inside the given height 4 7 3 GetBdfFontMetrics Syntax getbdffontmetrics maxleft as reference to gt integer maxright as reference to gt integer maxup as reference to integer gt maxdown as reference to integer gt xnextline as reference to integer gt ynextline as reference to integer font gt as bdffont flags as font flags Parameters maxleft An integer to receive the maximum distance in pixels from a character origin to the left edge of any character in the font maxright An integer to receive the maximum distance from a charac ter origin to the right edge of any character in the font maxup An integer to receive the maximum distance from a charac ter origin to the top edge of any character in the font maxdown An integer to receive the maximum distance from a charac ter origin to the bottom
191. object that opened the channel In general the network channel should be closed with a call to NetClose in the MSG COMM ERROR handler If necessary the OptoTerminal Programmer s Reference Manual comm resource can be obtained with a GetComMessage Source API call Handler Format func as byte handles MSG COMM ERROR biss endfunc lt errcode gt as integer lt errmsg gt Parameters lt errcode gt An integer indicating what type of error occurred lt errmsg gt A byte array containing an error message string Message MSG_ZENABLED Description This message is a direct message sent by the system soft ware to notify an object whether or not it is enabled back to root this does not include the object s enabled status Any changes in the object s enabled path to root generate this message Handler Format func lt name gt lt status gt as boolean handles MSG_ZENABLED ee endfunc Parameters lt status gt Indicates whether the path to root is enabled true enabled to root This does not take into account whether the object receiving the message is enabled Message MSG_SOUND_DONE Description This message is issued by the system software when a sound event note or sound is generated by the PlayNo teNotify or PlaySoundNotify API functions has been com pleted The object that receives this message is determined by the lt obj gt parameter passed to the P
192. of code In order for the compiler to distinguish between statements each state ment must be separated by a newline character If a state ment must be split into multiple lines type gt at the end of the line to tell the compiler to look for the rest of the state ment on the next line 2 2 White Space While spaces and tabs are ignored by the compiler judi cious use of white space is encouraged to make programs more readable 2 3 Comments Syntax rem comment comment where is an apostrophe Example rem this is a comment f this is another comment Description Comments help to explain and increase the readability of the code Comments can be placed on the same line as a statement or they can be placed on their own line Every thing between the rem keyword or apostrophe and the end of the line is considered part of the comment and ignored NOTE The apostrophe character is also used to denote character literals For example For this reason you cannot spec ify an apostrophe as the second character of a comment Example I ll fix this tomorrow Would be an error This could be alternately written REM I ll fix this tomorrow or I ll fix this tomorrow space after the first apostrophe There is another class of comments that may be used to define documentation meta data for an object property or method These documentation meta data comments referred to as
193. of the arc Positive angles increase counter clockwise from the primary focal point vector segment gamma The angle in radians from the primary focal point vector segment to the ending point of the arc Positive angles increase counter clockwise from the primary focal point vector segment flags A value of type ellipse_flags see section 4 6 16 DrawEllipse that determines how the ellipse is drawn Description This function determines the size of an elliptical arc relative to its center The size is determined from the major axis focal point starting angle and ending angle Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 6 18 GetScreenPixmap Syntax getscreenpixmap x as integer as gt integer width as integer height as gt integer returns color Parameters The x position of the first screen location to read relative to root ty The y position of the first screen location to read relative to root width The width indicates how many pixels per row should be copied from the screen height The height indicates how many pixels per column should be copied from the screen Description This function is used to retrieve the pixel map for a section of the screen as it is currently drawn This pixel map indi cates the individual colors drawn up to this point in each pixel location of the
194. olor newcolor as byte Parameters newcolor A byte specifying the foreground color Description This function sets the foreground color to newcolor for the current message handler or until this function is called again The last color setting persists until the message han dler returns The foreground color is used by various draw ing API functions 4 6 4 SetBgColor Syntax setbgcolor newcolor as byte Parameters newcolor A byte specifying the background color Description This function sets the background color to newcolor for the current message handler or until this function is called again The last color setting persists until the message han dler returns The background color is used by various draw ing API functions 4 6 5 RGB Syntax rgb red as byte green as byte blue as gt byte returns color Parameters An 8 bit integer indicating the amount of red in the desired color 255 is maximum 0 is minimum green An 8 bit integer indicating the amount of green in the desired color 255 is maximum 0 is minimum blue An 8 bit integer indicating the amount of blue in the desired color 255 is maximum 0 is minimum Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 46 Description This function is used to obtain a color value at runtime from user specified red green and blue values The returned color value may be used any
195. ommand line syntax type the fol lowing qlarify h A typical call to the compiler to compile an application in Qlarity Foundry might look like this qlarify t keypaddef charstr t gt aggregate string s 19 s 25 a o gt lt output_file_name gt lt file_name gt This would have the compiler define the pseudotypes key paddef as a charstr and aggregate as string It would suppress warnings 19 and 25 dangerous conversion and font definition warning remove font encodings for Uni code characters from BDF fonts and output the resultant bff file to lt output_file_name gt Qlarify supports the following command line switches e error file Redirect error output to error file If this option is not speci fied all error information is sent to the display o output file Generate the output file as the compiled Qlarity application If this is not specified then output will be sent to a file with the same name as the input file where the qly extension if present is replaced with bff Case sensitive This makes the compiler case sensitive By default the compiler is not case sensitive Do not use this option with QSI provided code or libraries which assume case insensi tivity This is not recommended and should only be used if you have authored your entire application including libraries and object templates from scratch h Print out help information v P
196. on Description This function sets the current read write position for the specified file To reset the position to the beginning of the file use an offset of 0 and absolute as true An offset of 81 1 is the end of the file For files in text mode the position and offset refer to the line number in the file For files in binary mode these refer to the byte offset in the file 4 16 13 GetFilePos Syntax getfilepos fnum as filedesc returns integer Parameters fnum File handle of the desired file Description This function returns the current position in the file For files in text mode this refers to the line number of the cur rent line in the file For files in binary mode the current position is a byte offset into the file 4 16 14 EndOfFile Syntax endoffile fnum as filedesc returns boolean Parameters fnum File handle of the desired file Description This function determines if the current position in the file is at the end of the file A value of true is returned if this is the case other false is returned 4 16 15 EraseFileSpace Syntax rasefilespace Description This function unconditionally erases the entire file space all files and directories USE WITH CAUTION 4 16 16 RenameFile Syntax renamefile name as reference to byte gt newname as reference to byte Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321
197. on in match to begin the search elements before the start element are not searched 0 starts at the beginning length The number of elements after start to search match or 1 to indicate all elements from start to the end of match pattern The pattern of data elements to search for in match Description This function searches for pattern in match If pattern is found then the index of the first element of pattern in match is returned If pattern is not found in match 1 is returned 4 97 Concat Syntax concat strA as reference to sametype gt strB as reference to sametype gt returns sametype Parameters strA An array of any type to be placed first in the returned array strB An array of the same type as strA to be placed last in the returned array Description This function concatenates the arrays strB and returns the resulting array strA and 69 NOTE It is generally easier to use the plus operator to concate nate arrays 4 9 8 Redim Syntax redim arr as reference to anytype gt newsize as integer Parameters arr An array of any type newsize The new size of the array arr Description This function resizes an array of any type to the size speci fied by newsize No data is lost unless the array is decreased in
198. ood understanding of the GetSysTextSize and DrawSysText functions should prelude attempts to use this function The parameter flags is of type font_flags which is a type that can have any combination of legal values 4 8 Controlling the Speaker 4 81 PlayNote Syntax playnote note as byte duration as integer 65 Parameters note The pitch from 0 to 86 duration The duration of the note in milliseconds Description The PlayNote function plays a note at the specified pitch for the specified duration The duration is rounded to the near est multiple of 20 milliseconds The function returns imme diately and the rates are queued Values for each note number are shown in the table below Number Note Frequency 0 rest note 0 Hz 1 A Bb 58 25 Hz 2 B 61 875 Hz 3 65 5 Hz 4 C Db 69 25 Hz 5 D 73 5 Hz 6 D Eb 77 75 Hz 7 E 82 5 Hz 8 F 87 25 Hz 9 F Gb 92 5 Hz 10 G 98 Hz 11 103 75 Hz 12 A 110 Hz 13 A Bb 116 5 Hz 14 B 123 75 Hz 15 131 Hz 16 C Db 138 5 Hz 17 D 147 Hz 18 D Eb 155 5 Hz 19 E 165 Hz 20 F 174 5 Hz 21 F Gb 185 Hz 22 G 196 Hz Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786
199. ort of the Qlarity based terminal if that line is available for use Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 40 NOTE The DTR line is not available on the Qlarity based terminal primary or auxiliary serial ports It may be available on expansion serial ports 4 1 18 Read DCD Syntax readdcd resource as comm returns boolean Parameters resource The communications resource from which to read Description This function is used to read the DCD carrier detect line on a serial port of the Qlarity based terminal if that line is available for use 4 1 19 NetSendDatagram Syntax netsenddatagram localport as unibyte gt foreignport as unibyte ipaddr as gt reference to byte data as reference gt to byte Parameters localport The local port number to be used for the UDP datagram foreignport The port number on the remote machine to be used for the UDP datagram ipaddr A 4 byte array containing the IP address of the remote machine data An array of bytes that contains the data for transmission in the datagram Description The NetSendDatagram function is used to send a single datagram on the network using the User Datagram Protocol UDP IP This function allows a datagram to be transmit ted without opening a network channel i e with the NetOpen function Both foreignport localport must be set to non zero value
200. ory This function also erases directories 79 4 16 7 GetFileInfo Syntax getfileinfo name as reference to byte gt size as reference to integer gt usedfilespace as reference to integer gt flags as reference to fileinfo flags Parameters A string containing the name possibly including path of the desired file size A variable to receive the size of the file in bytes directories return a size of 0 bytes usedfilespace A variable to receive the number of bytes allocated to the file by the file system which includes file system over head flags A variable of type fileinfo_flags to receive information about the file see below Description This function returns information about a file in the file sys tem The actual size of the specified file is returned in the size variable The number of bytes that the con sumes in the file space is returned in the usedfilespace variable The flags parameter is variable of type fileinfo flags which can take on the following legal val ues logically ORed together FILEINFO ISTEXT Indicates that the file was created in text mode FILEINFO ISBIN Indicates that the file was created in binary mode FILEINFO ISDIR Indicates that the file is a directory FILEINFO ISOPEN Indicates that the file has been opened with a previous call to OpenFile Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com
201. osed in double quotes Each character in the quoted string is converted and assigned to a corresponding array member 4 10 3 FromBytes Syntax frombytes var as reference to anytype gt toset as byte bigendian as boolean Parameters var A variable see description below to receive the binary data toset A byte array containing the binary data bigendian A flag indicating the endianness of the data in toset A value of true indicates big endian byte order while a value of false indicates little endian byte order Description This function stores the binary data in toset in variable var This is useful for extracting variable data such as integers or floating point numbers from a byte stream Only certain built in data types are supported and the toset array must be the correct size for var s data type as follows Data Type Size Integer 4 bytes Float 4 or 8 bytes in IEEE 754 format Boolean 1 byte Byte 1 byte Unibyte 2 bytes Array of one of the above data types Size of data type see above Number of elements 1 When an 8 byte array is passed for storage in a float vari able the data in toset is assumed to be a double precision floating point number and it is automatically converted to sin gle precision before storage in OptoTerminal Programmer s Reference Manual 4 10 4 GetBytes Syntax
202. ound then the index of the first element of pattern in match is returned If pattern is not found in match 1 is returned 4 9 14 Replace Syntax replace match as reference to gt sametype start as integer len as gt integer pattern as reference to gt sametype newdata as reference to gt sametype count as integer returns integer Parameters match An array of any type to examine start The location in match to begin the search characters before the start character are not searched 0 starts at the beginning len The number of elements after start to search in match or 1 to indicate all elements from start to the end of match pattern The pattern of data elements to search for in match newdata What to replace an occurrence of pattern with in match count The maximum number of times pattern should be replaced newdata in match or 1 to replace all occurrences of pattern by match 71 Description This function searches for pattern in match and replaces up to count occurrences with newdata The returned value indicates how many replacements actu ally occurred 4 10 Conversion Functions 4 10 1 Str Syntax str value as reference to anytype gt returns string Parameters value The value to convert to a string Description This function convert
203. oved from the terminal Permanent changes to the backlight setting should be made with the Power On Setup facility or the SetSystem Setting API function The SetBacklight function takes an argument of type backlight_adjust which is a defined type with the follow ing legal values BACKLIGHT_ON Turn backlight on set to previous on setting BACKLIGHT_OFF Turn backlight off power saving mode BACKLIGHT_LIGHTER Adjust the backlight one step lighter BACKLIGHT_DARKER Adjust the backlight one step darker 4 18 8 EnableKeypadBacklight Syntax enablekeypadbacklight enable as boolean Parameters enable A boolean value that sets the state of the keypad backlight A setting of TRUE turns on the backlight while a setting of FALSE turns it off Description The EnableKeypadBacklight function sets the current state of the keypad backlight if one is available The setting is temporary and is forgotten when power is removed from the terminal Permanent changes to the keypad backlight setting 85 should be made with the Power On Setup facility or the Set SystemSetting API function 4 18 9 SetLED Syntax setled cmd as ledcmd lednum as integer Parameters A value of type cmd see below that determines how the LED setting is adjusted lednum An integer indicating which LED is adjusted Description This function changes the state on or off of one of the key
204. pi cally 0 ptsize The desired point size for the rendered text data The data to be rendered as text The type can be a unibyte or byte array unistring or string flags A value of type font flags see section 4 7 1 that deter mines how the text is rendered Description This function renders the text contained in and paints the rendered region to the display The width height xoffset and yoffset values are typically obtained from a call to GetTTFTextSize or inferred from metrics obtained from a call to GetTTFontMetrics The rendered text is clipped if the area of the region defined by width and height is not sufficient or if the values of xoffset and yoffset place some or all of the text outside of the rendering region 4 7 5 SetTTFAngle Syntax setttfangle theta as float Parameters theta The angle of the rendered text in radians relative to hori zontal Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Description This function sets the angle at which text is rendered in using a ttfont resource relative to the horizontal plane The default angle is 0 indicating standard left to right horizon tal rendering This function should be called before GetTTFTextSize The last angle setting persists until the current message handler returns 4 7
205. plication 4 18 25 SetArrayData Syntax setarraydata arr reference to gt sametype index as integer srcdata gt as reference to sametype srcindex as gt integer len as integer Parameters arr An array variable already holding data index The location in arr to start inserting the srcdata srcdata An array containing the data to be inserted into The index into srcdata indicating the start of the data to be inserted into arr len The length of the data or 1 for all to be copied from f srcdata to arr Description This function copies data from srcdata into arr It is mostly used to improve efficiency when only parts of an array change Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 18 26 CreateCRCTable Syntax createcrctable width as integer poly as gt integer reflect as boolean returns gt integer Parameters width The number of bits minus one used in the polynomial for the desired CRC poly The polynomial to be used in calculating the CRC the most significant bit is always implicitly set for example 16 12 5 0 is 0x1021 reflect Whether or not to use a reflected algorithm reflects incom ing data Description This function is used to generate a CRC tab
206. ption msg as reference to byte as reference to unibyte unibyte returns boolean errtype gt rrlevel as reference to gt section 4 14 2 page 77 GetFileInfo getfileinfo name as reference to byte size as gt reference to integer usedfilespace as referenc gt to integer flags as reference to fileinfo_flags section 4 16 7 page 79 GetFilePos getfilepos fnum as filedesc returns integer section 4 16 13 page 81 GetHardwareInfo gethardwareinfo req as hwinfo returns byte section 4 18 5 page 83 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 117 Function Syntax Reference GetNetChannelInfo getnetchannelinfo channel as comm prot as gt reference to netprotocol lport as reference to gt unibyte fport as reference to unibyte ipaddr gt as reference to byte section 4 1 11 page 38 GetObjPixmap getobjpixmap width as reference to integer as reference to integer returns color height section 4 6 10 page 47 GetObjPixmapRegion getobjpixmapregion x as integer y as integer gt width as integer height as integer section 4 6 22 page 52 GetObjProp getobjprop obj as objref name as reference to gt byte returns string section 4 3 2 page 41 GetObjref getobjref name returns gt objref as refere
207. ptoTerminal Programmer s Reference Manual it is considered to be relative to the current directory The root directory is the default initial current directory This section describes functions for creating and using the file system Since flash memory will fatigue and eventually fail after many write cycles 100 000 care should be taken to avoid excessive calls to these functions 4 16 1 GetAvailFilespace Syntax getavailfilespace returns integer Description This function returns an estimate of the file space available for storing user data As there is some storage overhead in the file system the amount that is available for storing user data is slightly less than the returned value 4 16 2 MakeDir Syntax makedir name as reference to byte Parameters name A string containing the desired name and possibly path for the new directory Description This function creates a new directory in the file system at the specified location If the path included in name begins with or it starts with the root directory otherwise it is relative to the current directory 4 16 3 ChangeCurDir Syntax changecurdir name as reference to byte Parameters name A string containing the desired path and directory name to make the current directory Description This function changes the current directory to the specified directory Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com
208. pwidth mapheight The entire pixel map is copied starting with the top left pixel of the pixel map copied to the location specified by x y 4 6 12 DrawPixmapRegion Syntax drawpixmapregion x as integer as gt integer xoffset as integer yoffset as gt integer width as integer height as gt integer pixmap as reference to byte gt mapwidth as integer mapheight as integer Parameters x The desired x position of the upper left corner of the pixel map relative to the calling object s parent The desired y position of the upper left corner of the pixel map relative to the calling object s parent xoffset The x position of the pixel in the pixel map to draw at yoffset The y position of the pixel in the pixel map to draw at Opto 22 Fax 800 832 6786 Web www opto22 com Phone 800 321 6786 48 width Number of pixels per row to copy from the pixel map height Number of pixels per column to copy from the pixel map pixmap The pixel map array mapwidth The width of the pixel map mapheight The height of the pixel map Description This function draws a section of a pixel map The pix map variable must have a size of mapwidth mapheight The coordinate xoffset yoffset indi cates which pixel in the pixel map should map to the posi x y Starting at that point a re
209. r formed arrl i arr2 arrl i This performs in essence a software palette translation on a pixmap This is used for the translucency and plasma effects you see in some objects ARRAY REVERSE Reverses the order of elements in arr2 and stores the result in arr1 ARRAY PFIELD Reserved for future use Do not use 4 9 10 FreeArrayHandle Syntax freearrayhandle handle as arrayhandle Parameters handle An array handle that was previously allocated with a call to AllocateArray Handle Description This function releases an array handle that was allocated by calling AllocateArrayHandle and reclaims the memory used by that handle After the handle has been freed it is invalid and should not be used any more This function is an advanced API function and if misused may cause the terminal to exhaust its memory resources 4 9 11 ReadArrayHandle Syntax readarrayhandle data as reference to gt anytype handle as arrayhandle OptoTerminal Programmer s Reference Manual Parameters data An array which will receive a copy of the array associated with handle handle An array handle that was previously allocated with a call to CreateArray Handle Description This function reads an array associated with an array handle and stores the array in data You must call this function only with array handles that have been allocated with the Allo cateArrayHandle function and which have not been freed by
210. r to upper case letters and returns the resulting string 4 11 Math Functions 4 11 1 Sin Syntax sin x as float returns float Parameters x The floating point operand Description This function returns the Sine of x 4 11 2 Cos Syntax cos x as float returns float Parameters x The floating point operand Description This function returns the Cosine of x 4 11 3 Tan Syntax tan x as float returns float Parameters x The floating point operand 73 Description This function returns the Tangent of x 4 11 4 Asin Syntax asin x as float returns float Parameters x The floating point operand Description This function returns the Arc Sine of x 4 11 5 Acos Syntax acos x as float returns float Parameters x The floating point operand Description This function returns the Arc Cosine of x 4 11 6 Atan Syntax atan x as float returns float Parameters x The floating point operand Description This function returns the Arc Tangent of x 411 7 Power Syntax power x as float exp as float returns float Parameters x The base operand floating point Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 74 The exponent operand floating point Description This function returns x raised to the exp power 4 1
211. r between 0 and 65535 SYS FATALREBOOTTIMEOUT This is the number of 20 ms increments to wait after hitting a major system error before rebooting value of 0 the default is interpreted as indefinitely Hope fully you will never need this Two additional values are also legal for SYS KEYPADBACKLIGHT For systems with a keypad interface and keypad back light turn the backlight on or off newvalue must be a boolean TRUE turns the backlight on and FALSE turns it off SYS AUTOSHIFT For systems with a keypad interface and Auto Shift capability such as the QTERM G55 enable or dis able the Auto Shift feature When Auto Shift is off the 91 Shift Key behaves like any other key newvalue must be a boolean TRUE enables the Auto Shift fea ture and FALSE turns it off SYS_SAVE Causes the terminal settings that are pending to be saved to the terminal s non volatile flash memory newvalue is a boolean value that determines whether the system is reset after the new terminal set tings are saved A value of TRUE will cause the system to reset RESET NORMAL The parameter is ignored SYS CLEAR Clears the terminal settings that are pending without saving them to the terminal s non volatile flash mem newvalue must be set to 0 The parameter faction is ignored SYS KEYPADGATEDELAY For systems with a keypad interface change the keypad hardw
212. r defined code Each object template can define default values for its prop erties and default code for its methods When an object is instantiated i e an object instance is created from the object template any properties that are not explicitly given values retain their default values Any method that is not explicitly overridden with user defined code retains its default functionality 1 2 1 4 Defining a New Object Template To define a new object template you give the object a name declare what type of object it will be non drawable area or container and then add the properties and methods to the object definition Variables that are created using the dim statement inside the object definition are object properties These variables may be given a default initial value using the init state ment that will be assigned to the variable if no initial value is given the object instance Functions that are created inside the object definition are object methods These methods may consist of ordinary functions validation functions or event handlers Methods need not contain any actual code however a method must be declared in the object definition before it can be overrid den in instances of that object template OptoTerminal Programmer s Reference Manual The actual syntax for defining a new object template is cov ered in the chapter on Advanced Design in the OptoTer minal Qlarity Foundry User s Manual 1 2 1 2
213. r map Unable to set requested EXCEPT NONE No String ERCBETSUHRNOEET TTF point size EXCEPT USER No String EXCEPT GLYPHCOPY Unable to copy TTF glyph B 2 Memory Exceptions EXCEPT NOSCALABLE not scalable EXCEPT NOMEM Unable to allocate memory EXCEPT NODCMEM Draw cache memory exhausted reducing level B 3 Message System Exceptions EXCEPT NOPOST Unable to post message queue is full EXCEPT NOSYSMSG Unable to initiate a system message EXCEPT BADREGMSG Not a registerable message B 4 Font Exceptions EXCEPT NOMODEVERT Vertical text unsupported by font EXCEPT NOMODEHORZ Horizontal text unsup ported by font EXCEPT GLYPHRETR Unable to retrieve TTF glyph EXCEPT GLYPHTRANS Unable to transform TTF glyph EXCEPT_GLYPHBMP Unable to render TTF glyph EXCEPT_CLOSEFACE 2 EXCEPT_NOSPACE Text does not fit as speci fied in area B 5 Drawing Exceptions EXCEPT_NOTDRAWING Unable to perform while not drawing EXCEPT_DRAWING Unable to perform while drawing EXCEPT_CORRUPT_BMP Corrupted bitmap EXCEPT_UNSUP_BMP Unsupported bitmap EXCEPT_NONDRAWN_OBJ EXCEPT_ROOT_OBJ Object is non drawable Unable to change root container information EXCEPT FOCALDIST Il
214. r the Windows and the terminal s hardware drivers Chapter 1 Chapter 2 Chapter 3 Chapter 4 Appendix A Appendix B Appendix C Appendix D OptoTerminal Software Fundamentals This chapter provides basic information on the Qlarity based ter minal software including the Qlarity programming language and the message handling system Qlarity Language Syntax This chapter provides detailed information on the syntax for writing in Qlarity Messages and Message Handler Prototypes This chapter provides descriptions of all system messages Included is the format number and types of parameters and return type that must be used to declare a han dler for each message Qlarity API Function Reference This chapter describes the available API Application Programming Inter face functions their parameters and return values and the operations they perform Built in Constants and Defined Types This appendix contains tables showing all of the Qlarity built in constants and defined types Exception List This appendix lists the names and associated descriptions of all possible exceptions Qlarity Command Line Compiler This appendix provides information on the Qlarity command line com piler which is used to compile the BASIC file if you created your user application in a text editor Qlarity API Functions Quick Reference List This appendix provides an alphabetical listing of all Qlarity API functions for quick reference MAN
215. rameter is ignored for other types of screen events y2 For SCREEN_MOVE events this is the y location at the end of the move event This parameter is ignored for other types of screen events Description This function allows the programmer to introduce a fake screen message into the messaging system The variable msgtype must be one of the following SCREEN_PUSH SCREEN_MOVE SCREEN_RELEASE 4 13 User Input Capture Some objects in Qlarity may want to capture or pre process user input messages for themselves Input messages are touch screen keyboard and keypad messages To provide this a capture list identifies objects wishing to receive input messages before they are passed through the normal mes saging tree Any object may appear in the list but it will only appear once Input messages are handled as follows All input messages go to the objects in the capture list first Each object in the capture list is treated as a root object receiving all touch screen messages regardless of loca tion OptoTerminal Programmer s Reference Manual Container objects in the capture list behave normally by passing the message to their children and then receiving a second pass If an object in the capture list is not enabled back to root that object does not capture an input mes sage although it still appears in the capture list input message is killed while being processed by the capture list i
216. re registered with the system software using registration functions in the Qlarity API Because these events are usually handled by a small number of functions registration avoids the need to filter the message through the entire object hierarchy If the handler in the registration list is an object method the object owning the method is checked by the system soft ware to ensure that it and every parent container back to the root container is enabled If this condition is satisfied the event handler is called Because the root container cannot be disabled global function event handlers are called without this check If more than one object has registered for a given message the objects receive the message in Z order as with area messages with the root container global handlers receiv ing highest priority Refer to section 3 4 for a list of valid registered messages 1 5 5 User Messages Although hardware events are generated by the system soft ware it is often desirable for the application to have the ability to send messages to indicate software events Qlarity provides a mechanism to define user messages and a flexi ble set of Qlarity API functions to send these messages User messages may be broadcast messages object may be enabled or disabled send messages behave like area mes sages or direct object may be enabled or disabled Refer to section 3 5 for details on defining and sending user messages and defining us
217. relative vertical offset for where each line of text should be drawn widths An integer array used as both an input and an output For input the 0 th element is used to indicate the total width in pixels of the box that the text needs to fit into unless FONT_HFIT is specified in which case it is ignored On return the width for each line of text will be in the individ ual elements of the array with the 0 th element always con taining the final full width of all the text lines if FONT HFIT is specified then this is calculated otherwise it is the same value as was passed in heights An integer array used as both an input and an output For OptoTerminal Programmer s Reference Manual input the O th element is used to indicate the total height in pixels of the box that the text needs to fit into unless FONT VFIT is specified in which case it is ignored On return the height for each line of text will be in the individ ual elements of the array with the 0 th element always con taining the final full height of all the text lines if FONT VFIT is specified then this is calculated otherwise it is the same value as was passed in 1 An integer array used as both an input and an output For input if FONT HLEFT FONT HRIGHT or FONT HCENTER is not specified by default this is the case the O th element is used to determine how far from the left edge the origin of the first text character should b
218. returns typeval Parameters unique An integer to receive a type identifier if the property or vari able to be typed is user defined Built in types cause to be stored in this parameter Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual objref Objref of the object default for global whose property type will be returned name Name of the property variable whose type will be returned Description This function determines the type of an object property or variable The returned value is of type TYPEVAL with legal values as shown below Value Type INTEGER_TYPE Integer FLOAT_TYPE Floating Point BOOLEAN_TYPE Boolean BYTE_TYPE Byte UNIBYTE_TYPE Unibyte ARRAY_TYPE Array OBJREF_TYPE Object Reference If the object property or variable is a user defined type a unique non zero value corresponding to the type will be stored in unique 4 18 14 SetSystemSetting Syntax setsystemsetting cmd as syscmd gt newvalue as anytype action as gt syscmd_action Parameters cmd A value of type syscmd see below that determines what terminal control setting will be modified newvalue The new value for the selected terminal control setting This value expects an integer if not otherwise noted in the description of the syscmd action A value of type syscmd_action
219. rigin lt x_from gt The initial x location before the move with respect to the parent s origin lt y_from gt The initial y location before the move with respect to the parent s origin lt pass gt False if the container s children have not yet received the message and true if the container s children have already received the message 3 3 Draw Messages A draw message cannot be terminated and it is passed to containers including the root container twice as described in section 3 2 Area Messages This allows the container to draw borders around itself or perform other actions that should take place after the container s children have fin ished handling the message Unlike area messages the actual invalid region is not passed to the handler as a set of parameters Rather the handler 23 should just repaint the object entirely and the system soft ware clips the repainted region to the invalid region Non drawable objects are not eligible to receive this mes sage Draw messages are handled by the system as a low priority Draw messages are placed in a separate message queue that is serviced when the regular message queue is empty Also the system software may combine multiple invalid regions into a single draw message to increase drawing efficiency Message MSG_DRAW Description This message indicates that the receiving object needs to paint itself on the screen Handler Format Gf hand
220. ring for the message keycode The keycode that causes a message to be generated for the object Description This function registers an object to receive MSG KEY DOWN MSG KEY PRESS and MSG KEY RELEASE messages when the keyboard or keypad key associated with keycode is activated A list of valid keycodes is included in Appendix A In addition there are two special keycodes not directly associated with specific keys The KEY ANY keycode reg isters the object to receive key messages for all keys The KEY NONE keycode effectively unregisters the object for key messages A given object may only be registered for one keycode value Each call to RegisterKey preempts any keycode that was previously registered for the obj object 4 3 Manipulating Objects 431 GetObjref Syntax getobjref name as reference to byte gt returns objref Parameters name A string byte array that contains the name of the desired object Description This function takes the name of an object and returns an objref to the object 41 4 3 2 GetObjProp Syntax getobjprop obj as objref name as gt reference to byte returns string Parameters obj A reference to the object with the desired property A string containing of property to retrieve Description This function returns the value for the desired property con verted to a string The returned value
221. rint out the compiler version only Do not compile anything Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 112 OptoTerminal Programmer s Reference Manual Remove character encodings greater than 255 i e Unicode char acters from BDF fonts This can save a lot of memory in appli cations that do not use Unicode This is the default setting for applications compiled with Qlarity Foundry Normally if you use this option you will not specify u Unicode support Specifying this option will cause the char data type to be 16 bits wide like a unibyte and characters in a charstr to be 16 bits each This effectively enables Unicode support Normally you do not use this option in conjunction with a t new data type existing data type Create a new pseudo data type name new data type with the same attributes as existing data type The KeypadDef and Aggregate data types often used in applications developed in Qlarity Foundry are examples of pseudo data types Since specifying the percent character in a command line can be difficult you may substitute the bang character wherever you need to use a percent For applications developed in Qlarity Foundry you should usu ally specify t keypaddef charstr t aggregate string s warning number Suppress warnings with the number warning number Some warnings may be overly repetitive and difficult to avo
222. rner of the rendered region relative to the calling object s parent width The width of the region to use for rendering height The height of the region to use for rendering xoffset The horizontal offset from the upper left corner of the ren dered region to the origin of the first character yoffset The vertical offset from the upper left corner of the rendered region to the origin of the first character font The sysfont resource This may be either a BDF or a True Type font facenum The number for the desired face This value is only used with TrueType fonts and is typically zero 0 ptsize The desired point size of the rendered text This value is ignored unless font specifies a TrueType font data The data to be rendered as text The type can be a unibyte or byte array unistring string or charstr flags A value of type font flags See section 4 7 1 GetBdf TextSize for a description Description DrawSysText renders the text contained in data and paints the rendered region to the display The width height xoffset and yoffset values are often obtained from a call to GetSysTextSize or inferred from metrics obtained from a call to GetSysFontMetrics The rendered text is clipped if the area of the region defined by OptoTerminal Programmer s Reference Manual width and height is not sufficient or if the values of xoffset and yoffset pla
223. round color and the remainder of the region in the background color Most fonts that use Latin characters do not support this option FONT INVERSE Render the text horizontally with the text in the back ground color and the remainder of the region in the foreground color FONT DRAW HPARTIAL Draw any horizontal lines that are marked as appearing partially within the fitted text region FONT DRAW VPARTIAL Draw any vertical lines that are marked as appearing partially within the fitted text region Multiple flags may be specified by combining them with a boolean AND operation This function is included mostly to increase the efficiency of drawing multiline text In Qlarity it would look some thing like the following Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual for tmp 1 to len lengths 1 drawbdftext x 0 x tmp 0 y tmp gt widths tmp heights tmp xoffsets tmp gt yoffsets tmp thefont mid text indices tmp lengths tmp flags next 4 7 6 GetTTFTextSize Syntax getttftextsize width as reference to gt integer height as reference to integer gt xoffset as reference to integer yoffset gt as reference to integer font as ttfont gt facenum as integer ptsize as integer gt data as reference to anytype flags gt as font flags Parameters width An integer to receive the width o
224. rray In which case the remainder of the array is ini tialized to the default value The array size is optional If it is omitted the array will be sized to the number of elements in the initialization If the initialization is omitted the array will remain unsized until it is assigned Array elements can be accessed using integer indices in the array as follows array name index Arrays in Qlarity are zero based that is the index of the first element of an array is O Example dim myArray 11 as byte init myArray Hello World dim anotherArray 4 as integer init anotherArray 1 2 3 4 An array can be assigned to another array as shown in the following example The array receiving the assignment is automatically resized to the size of the assigned array Example func test dim a 2 b 2 init a hi b a 1 as integer is being assigned to b 1 endfunc Unlike some languages arrays that are passed as parameters to a function are not passed by reference unless the array parameter to the function is a reference parameter There fore passing large arrays to functions can be computation ally expensive Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 12 2 10 Operators 2 10 1 Arithmetic Operators Arithmetic operators can be used with any float integer byte or unibyte value Operator Description Addition operator
225. rrayHandle pag Read DCD readdcd resource as comm returns boolean section 4 1 18 page 40 ReadDTR readdtr resource as comm returns boolean section 4 1 17 page 39 file f fil 7 f to ReadFile readfile fnum as filedesc var as reference to section 4 16 10 page 80 anytype ReadGPIO readgpio pins as unibyte returns GPIO_PIN section 4 18 2 page 82 ReadRTS readrts resource as comm returns boolean section 4 1 15 page 39 ReadUserConfig readuserconfig len as integer returns byte section 4 15 1 page 78 i f 2 i gt fedim arri as reference to anytyp newsize as section 4 9 8 page 69 integer RegisterKey registerkey obj as objref keycode as unibyte section 4 2 3 page 41 1 h IE bj bjref gt RegisterMsgHandler 2 15 section 4 2 1 page 40 message msgparm as unibyte Relocate relocate obj as objref x as integer y as integer section 4 5 3 page 44 pag RemoveCapture removecapture obj as objref section 4 13 3 page 76 pag fil f to byte gt RenameFile oM EM e section 4 16 16 page 81 as reference to byte replace match as reference to sametype start gt as integer len as integer pattern as gt section 4 9 14 page 71 Replace reference to sametype newdata as reference gt 9 to sametype count integer returns integer Rerender rerender obj as objref section 4 5 1 page 44 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Pho
226. rriding those elements The extending template may not access the base template s private variables and functions The extending template may override any variable declaration variable initialization or function defini tion When overriding a variable or function the extend ing template may reduce the access to the element For instance a template may override a protected variable declaration in a base template as private Conversely it is not allowed to increase access to an element in the extending template For example you could not override a private function in a base tem plate as protected in the extending template Anextending template may add validation functions for variables in a base template The compiler will issue a warning for this unless you also override the variable in the extending template Anextending template may add variables that would be validated by functions in the base template As this is usually undesired behavior the compiler will issue a warning in this case To avoid the warning either rename the variable or override the validation function in the extending template Chapter 10 in the OptoTerminal Qlarity Foundry User s Manual gives examples of defining an object type and creat ing instances of the object 2 17 Declaring Object Instances Syntax declare lt name gt as lt defined_type gt Description Once an object type is defined instances of tha
227. rsion returns float 83 Description This function returns the version of the system software firmware currently programmed into the terminal 4 18 5 GetHardwarelInfo Syntax gethardwareinfo req as hwinfo returns gt byte Parameters A value of type hwinfo see below indicating the desired hardware information Description This function returns information about the terminal hard ware It returns a byte array containing the requested infor mation The returned information is determined by the req argument This argument is of type hwinfo which is an enumerated type with the following legal val ues HW_ETHERNET Request information on the Ethernet interface The returned byte array contains two bytes The first byte is set to 1 if the Ethernet interface is present otherwise it is set to 0 The second byte is set to 1 if the Ethernet link is currently active otherwise it is set to 0 HW_TOUCH Request information on the touch screen The returned byte array contains one byte which is set to 1 if a touch screen is present otherwise it is cleared to 0 HW KEYPAD Request information on the keypad The function returns a byte array of variable length The first byte is set to 1 if a keypad is present otherwise it is cleared to 0 and the length of the returned byte array is 1 If a keypad is present the remaining bytes in the array con tain all possible keycodes for the k
228. s value to a string representing the value The system software uses heuristic rules to determine how to convert different types of values Integers and float ing point numbers are converted to text representations of the passed value with sign if negative and decimal point if floating point Bytes and unibytes are treated as unsigned integers Booleans convert to the strings true or false Objrefs convert to a string containing the referenced object s name Arrays convert to a comma separated list of con verted values enclosed in brackets User defined data types such as enumerations are treated as integers 4 10 2 Val Syntax val value as referenc as reference to byte to anytype text gt Parameters value A variable of any type to receive the converted value text An array of bytes or a string to be converted Description This function converts the text in text to a variable of value s type and stores the result in value The con versions follow a similar heuristic to the Str API function Enumerations cannot be assigned a value with Val Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 72 If value is an array then text should be a list of val ues separated by commas and enclosed within brackets Alternatively if value is an array of bytes unibytes or integers text may contain text encl
229. s This function OptoTerminal Programmer s Reference Manual is for transmission only No response to the datagram will be received unless the appropriate channel has been estab lished 4 2 Registering for Messages 42 1 RegisterMsgHandler Syntax registermsghandler obj as objref msgnum gt as message msgparm as unibyte Parameters obj The object registering for the message msgnum The name of the message e g MSG_TIMETICK msgparm A parameter whose meaning depends on the message see section 3 4 Description This function registers an object to receive registered mes sages After this call the object passed in obj is eligible to receive msgnum messages if it has an enabled path to root 4 2 2 UnregisterMsgHandler Syntax unregistermsghandler obj as objref gt msgnum as message msgparm as unibyte Parameters obj The object registering for the message msgnum The name of the message e g MSG_ TIMETICK msgparm A parameter whose meaning depends on the message see section 3 4 Description This function unregisters the obj object so that it will no longer receive msgnum messages Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 4 2 3 RegisterKey Syntax registerkey obj as objref keycode as gt unibyte Parameters obj The object registe
230. screen The returned array will be a color array of size width height indicating the colors drawn so far Please note that for grayscale units the color returned may not be the exact color that was drawn to that location but it will map to the same gray color as the origi nal The color drawn at pixel coordinate x y in the object with 0 0 being the top left pixel of the object has the color indicated by the y width x th element in the returned array Any requests for an area off of the screen will be transparent when drawn using drawpixmap 4 6 19 UseDrawCache Syntax usedrawcache cachelevel as anytype Parameters cachelevel Selects the method for draw caching see below 51 Description This function sets the method of draw caching which is used by the system software to improve graphics perfor mance The parameter cachelevel is of type drawcache level can take on any one of the following values CACHE OFF Disables draw caching CACHE ALL Maintains a cache for all objects in the application best performance highest memory requirement CACHE ENABLED Maintains a cache for all enabled objects intermediate performance and memory requirement CACHE EFFECTIVE ENABLED Only maintains a cache for objects that are both enabled and their ancestors are enabled tracing back to root Thus the level of draw caching can be tailored to the mem ory requirements of the applicatio
231. se properties are set code inside the object calculates the position and size from the property values and calls the Qlarity API functions that set the attributes 1 2 2 3 Container Objects The container object type is very similar to the area object type except that container objects may contain other objects Container objects can be used to create a hierarchi cal organization of objects in an application thus they are central to the Qlarity messaging system Each user application starts with a root container Though invisible it is the container in which you place all other objects The following illustration shows a root container with several objects in it Root Container Container Object Container Object Object Object Object Object Object Object linked to Root Container In this illustration two container objects plus another object are linked to the root container In addition each container object has objects linked to it which are referred to as its children The container object is the parent If an object is not attached to a container object it is linked to the root container by default All container objects are rectangular Examples might include a form object or a window object which could serve as generic containers to organize objects into areas on the terminal display Container type objects have the following built in data that is maintained by the system software
232. sereDelinca Data Types boolean True false TRUE FALSE In addition to the built in data types there are four kinds of user defined types Objects are the major forms of user byte oe 0 to 255 defined types and are described elsewhere in this manual Constants enumerations and starttypes are other user unibyte 16 bit unsigned 0 to 65535 defined types value NOTE sing User defined data types must be declared in the global unistring Array of unibytes space they cannot be declared inside of object templates or Reference to a instances color 0 to COL 255 2 6 1 Constants User defined Items have integer enumerations types integer val valies Syntax ues constant lt name gt lt value gt as lt data_type gt bdffont A raster font or resource const lt name gt lt value gt as lt data_type gt A TrueType font resource const myConstant 100 A bitmap image bitmap Description Reference to an With the constant keyword a value of any type can be objref as object assigned to a name for use throughout the application That is the value and the name are synonymous to the compiler If desired the constant can be given a data type Because it is a constant its value cannot be changed at runtime 2 6 2 Enumerations Syntax numerate enumeration name as name 1 gt name n or Opto 22 Fax 800
233. set from the upper left corner of the rendered region to the origin of the first character for each line yoffsets An array of integers indicating the vertical offset from the upper left corner of the rendered region to the origin of the first character for each line indices An array of integers the tells the index into where each line of text begins lengths An array of integers indicating the number of elements to draw in each line of data font The bdffont resource data The data to be rendered as text The type can be a unibyte or byte array unistring or string OptoTerminal Programmer s Reference Manual flags A value of type font flags see below that determines how the text will be rendered Description This function renders the text contained in data The parameters are typically obtained by a call to GetBDFText The rendered text is clipped as necessary A good understanding of the GetBDFTextSize and DrawB DFText functions should prelude attempts to use this func tion The parameter flags is of type font flags which is a type that can have any combination of following legal val ues other font flags settings are ignored FONT NORMAL Render the text horizontally with the text in the fore ground color and remainder of the region in the back ground color FONT VERTICAL Render the text vertically with the text in the fore g
234. t does not pass to other objects in the cap ture list or to root for normal message processing If an input message is not killed normal message processing occurs on the message it is passed to root which may cause objects in the capture list to receive the message twice The following API functions are used to examine and mod ify the capture list 4 13 1 SetCapture Syntax setcapture obj as objref Parameters obj The object to appear in the capture list Description This function places obj in the capture list if it is not already If it is already in the list the object is moved to the front of the list 4 13 2 GetCapture Syntax getcapture obj as objref returns integer Parameters obj The object to look for in the capture list Description This function checks the capture list to determine if obj appears in the list The return value indicates the location of the object in the list with 0 being first 1 second and so on A 1 indicates that the object does not appear in the list 4 13 3 RemoveCapture Syntax removecapture obj as objref Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Parameters obj The object to remove from the capture list Description This function looks for obj in the capture list If it is found it is removed from the list 4 14 Exception Fun
235. t for stop expression Example dim Data 5 as byte init Data 10 20 30 40 50 dim stepamount as integer init stepamount 1 dim countdown countup as integer init countup 0 for countdown 4 to 0 step stepamount newData countup data countdown countup countup 1 next 2 14 2 While Loops Syntax while lt boolean_expression gt do loop Description The statements inside the while loop are executed until the boolean expression becomes false If the boolean is false before the while loop starts then the loop is not executed Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual 2 14 3 Do While Loops Syntax do loop whil lt boolean_expression gt Description The do while loop is similar to the while loop except that it will always execute at least once The boolean expression is evaluated each time execution reaches the end of the loop When the expression becomes false the loop is finished 2 14 4 Goto Label Syntax goto lt label_name gt label lt label_name gt Description The goto command is used to stop executing the code at the goto command and begin where the lt label_name gt is specified The label command is used to mark a spot to be jumped to with the goto command These two statements must appear w
236. t object may be created by declaring them lt name gt may be any legal unique identifier it is used to refer to the instance of the object lt defined_type gt is the name of the object type and it specifies the template to be used when creating the object instance OptoTerminal Programmer s Reference Manual All functions and properties defined for an object type will be included in any instance of that type Variables may not be created using a dim statement inside an object instance but they may be given initial values for that instance using init statements Functions declared in an instance must also have been declared in the object template they will override the func tions in the template The function name events handled parameters name type and return type must match the dec laration of the function in the template Chapter 10 in the OptoTerminal Qlarity Foundry User s Manual gives examples of defining an object type and creat ing instances of the object 2 18 Level Syntax Level lt integer gt Description The Level command specifies the Z order of an instance at application startup Instances with a higher level appear higher towards the front in the Z order If two instances have the same level then their Z order relative to each other is undefined This directive must immediately follow a declare statement Qlarity Foundry normally sets this directive
237. th the old and new area of the object are invalidated and a MSG_DRAW message is generated If you specify 1 for either parameter the dimension for that parameter remains unchanged 4 5 3 Relocate Syntax relocate obj as objref x as integer y gt as integer Parameters obj A reference to the object to be relocated x The new x position horizontal coordinate in pixels for the object relative to the calling object s parent The new y position vertical coordinate in pixels for the object relative to the calling object s parent Description This function relocates an object to the specified position by altering the system software object attributes for the speci fied object The display regions for both the old and new positions of the object are invalidated and a MSG_DRAW message is generated 4 6 Painting to the Display Functions that draw on the display must be placed inside a MSG_DRAW message handler Attempting to call these functions outside a MSG_DRAW message handler will cause a runtime exception to occur Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual Many of these functions take a parameter of type color which is an enumerated type representing the many colors that are available on the color display See Appendix A for a complete list of available colors Color values may also be obtained at runtime
238. the message and true if the container s children have already received the message Message MSG_KEY_RELEASE Description This message indicates that a key has been released on the keyboard or keypad The keyboard and keypad are distin guished by unique keycodes This message is unaffected by the key repeat feature To be eligible to process this mes sage an object must register for it using the RegisterKey API function see section 4 2 3 Handler Format Gf handled by a container object global func name lt gt as unibyte pass gt as boolean handles MSG KEY RELEASE EEN endfunc if handled by an area non drawable object func lt name gt lt keycode gt as unibyte Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual handles MSG_KEY_RELEASE endfunc Parameters lt keycode gt A unibyte containing the keycode for the key that was pressed Most keycodes are defined as constants which are listed in Appendix A lt pass gt False if the container s children have not yet received the message and true if the container s children have already received the message 3 5 User Messages Although hardware events are generated by the system soft ware it is often desirable for the application to have the ability to send messages to indicate software events Qlarity
239. the Qlarity Foundry workspace The format for the handler differs depending on the type of object being created Non drawable objects receive infor mation about the parents to which they should attach Area and container objects receive information about their posi tion size and parents The handler should set the object s initial properties call API functions to set the object attributes in the system software usually done in property validation functions and finally call Tool_PersistQ for any property that has been modified Handler Format if handled by an area or container object func name lt parent gt as objref xl as gt integer lt yl gt as integer lt 2 gt as integer gt lt y2 gt as integer handles MSG TOOL DRAGCRE sco endfunc ATE if handled by a non drawable object func lt name gt lt parent gt as objref handles MSG TOOL DRAGCREATE endfunc OptoTerminal Programmer s Reference Manual Parameters lt parent gt A reference to the parent to which the new object should attach itself lt 1 gt The x position of the location where the drag was initiated lt yl gt The y position of the location where the drag was initiated lt x2 gt The x position of the location where the drag was com pleted lt y2 gt The y position of the location where the drag was com pleted The coordinates x1 y1 and x2 y2 are not normalized
240. the unit to perform a reset entering the screens used to calibrate the touch screen 93 4 18 17 GetRandomNum Syntax getrandomnum returns float Description This function returns a pseudo random number The return value is always a floating point number between 0 to 1 4 18 18 SeedRandomNum Syntax seedrandomnum Description This function seeds the random number generator with a value from an internal hardware timer Calling this function at a non deterministic time such as a user input event pro duces the best pseudo random numbers obtained with calls to GetRandomNum 4 18 19 SetSeedRandomNum Syntax setseedrandomnum seed as integer Description This function seeds the random number generator with a specific value enabling pseudo random sequences to be produced and reproduced This is most useful for debug ging 4 18 20 WatchdogEnable Syntax watchdogenable enable as boolean timeout gt as integer Parameters enable A boolean value specifying whether to enable use true or disable use false the watchdog timer timeout The desired number of 20 ms intervals that should elapse before a system reset occurs 1 2 20ms Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 94 Description This function enables disables the software watchdog timer The purpose of the watchdog timer is to cause a system reset if something goes f
241. they may contain more than just source code A library may contain any of the following Qlarity source code Native source code Bitmaps BDF fonts TrueType fonts Modules To include a library Syntax Include library file name The library natives lib is automatically included by the compiler Do not manually include this file in your project See Chapter 10 of the OptoTerminal Qlarity Foundry User s Manual for more information on libraries Including a library simply informs the compiler of the exist ence of the library To use the code or other entries in a library you must reference them explicitly as shown below Syntax Library library name gt lt entry type gt lt entry gt name 19 Description library name gt is the name of the library in which the entry resides This is generally different from the library file name lt entry type gt is the type of entry in the library source bitmap bdffont ttfont native or module entry name gt is the name of the library entry By referencing the library entries explicitly you can use only the entries you want Qlarity Foundry may bring in certain library entries automatically To determine the name of a library and the names and types of entries in it refer to the documentation that came with the library or view the library in Qlarity Foundry 2 21 Precompile Directives 2 21 1 if else endif Syntax i
242. tical operations available to the base type Starttypes can only be defined for booleans unibytes bytes integers and floats There is no limit to the number of values that can be placed in a starttype The first value listed is the default 2 7 Variables 27 1 Declaration Syntax dimension name as data type Or dim name as data type Example dim myVar as integer dimension myVar as integer Description Variables that are used must be declared somewhere in the application A variable must be assigned a type when it is declared The dim keyword is used to declare a variable as shown above When a variable is declared it is automatically ini tialized to a default value The init keyword is used to ini tialize a variable to a specific value see section 2 7 2 Variables declared outside of object definitions and func tions are considered global These variables are accessible anywhere in the application Variables declared inside an object definition but outside the object methods are considered to be properties of the object Each instance of an object maintains its own object properties Inside the object definition or instance a vari able is referenced with its name only Outside the instance or object definition the property of a given object instance can be referenced using the instance name and the dot operator as described in section 2 10 4 Variables declared inside
243. tion 4 18 21 page 94 WriteFile writefile fnum as filedesc data as reference gt section 4 16 11 page 81 to anytype WriteUserConfig writeuserconfig cfg as reference to byte section 4 15 2 page 78 li f EE 1 ZlibCompress zlibcompress out as reference to byte in as section 4 18 28 page 96 reference to byte libd t f to byte i gt ZlibDecompress cc eee T noe section 4 18 29 page 96 as reference to byte Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786
244. to the origin of the first char acter font The sysfont resource This may be either a BDF or a True Type font facenum The number for the desired face This value is only used with TrueType fonts and is typically zero 0 ptsize The desired point size of the rendered text This value is ignored unless font specifies a TrueType font data The data to be rendered as text The type can be a unibyte or byte array unistring string or charstr flags A value of type font flags see GetBDFTextSize that determines how the text will be rendered Description This function finds the size of a given text string rendered in the given point size and typeface The calculated values are returned in the variables passed as parameters The width and height variables receive the width and height in pixels of the rendered region respectively The xoffset and yoffset variables receive the offset from the upper left corner of this region to the origin of the first rendered character The flags is of type font flags Typically this function is called as a precursor to calling DrawSysText The width height xoffset Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 62 and yoffset values obtained from this function call may be used as parameters in the call to DrawSysText 4 712 GetSysTextFit Syntax getsystextfit multiflags as reference gt
245. urn value is the value returned by the called handler if donow is true or false if startobj has no handler for msgnum or if donow is false The message is delivered whether startobj Y is enabled or disabled 4 12 4 FakeKeyMsg Syntax fakekeymsg msgtype as fake key keycod gt UNIBYTE Parameters msgtype The type of key message to post keycode The keycode of the key to post Description This function allows the programmer to introduce a simu lated key message into the messaging system simulating a physical key press or release The variable msgtype must be one of the following KEY_PUSH KEY_REPEAT KEY_RELEASE 4 12 5 FakeScreenMsg Syntax fakescreenmsg msgtype as fake screen xl gt as integer yl as integer x2 as integer gt y2 as integer Parameters msgtype Type of screen message to post Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 76 1 The x location of the simulated screen event for SCREEN_PUSH and SCREEN_RELEASE messages For SCREEN_MOVE events this is the x location at the start of the move event yl The y location of the simulated screen event for SCREEN_PUSH and SCREEN_RELEASE messages For SCREEN_MOVE events this is the y location at the start of the move event x2 For SCREEN MOVE events this is the x location at the end of the move event This pa
246. userconfig len as integer byte Parameters len The number of bytes to read from the user configuration block Description This function reads len number of bytes from the user configuration block and returns them in a byte array If the bytes were not previously written with a call to WriteUser Config the bytes will contain garbage 4 15 2 WriteUserConfig Syntax writeuserconfig cfg as reference to byte Parameters cfg An array of bytes to write to the user configuration block Description This function writes the bytes contained in cfg to the user configuration block These bytes may subsequently be retrieved with a call to ReadUserConfig Since flash mem ory will fatigue and eventually fail after many write cycles 100 000 care should be taken to avoid excessive calls to this function 4 16 File System Functions The Qlarity based terminal implements a simple file system for storage of user data in flash non volatile memory The file system supports a directory structure of any depth with path directory names delimited by either a forward slash or a backslash Directory and file names are lim ited to 128 characters in length and the maximum path length is 256 characters The file system root directory is designated by a single for ward slash or backslash Any path beginning with or starts at the root directory If a path does not start with or O
247. ve defines the icon used by a template and instances of the template in Qlarity Foundry Qlarity Foundry automatically generates and updates the Toolim age line for each template in a workspace The line with the Toolimage directive must follow a template defini tion statement and it must appear before any code in the template Manually editing a Toolimage line is not rec ommended This directive is ignored when a workspace is compiled with the command line compiler 221 4 Hidden Syntax Hidden lt dimension statement gt Description This directive informs the Qlarity Foundry compiler that the variables declared in lt dimension statement gt should not be displayed in the Object Properties list This only applies to global variables and object properties it has no effect on local variables in a function This directive is ignored when a workspace is compiled with the command line compiler 2 21 5 Setfile Syntax Setfile lt line number gt lt filename gt Description This directive tells the compiler to change file names and line numbers for error reporting The line number is imme diately set to line number gt Qlarity Foundry uses this directive internally and ignores any such directives typed in by the user Altering these directives is not recommended OptoTerminal Programmer s Reference Manual 2 21 6 Visible Syntax Visible lt true or false gt Descript
248. ware Firmware The system software firmware is the terminal resident software that controls the Qlarity based terminal System software consists of the following Operating system Qlarity execution engine Message handling system Olarity API functions operating system calls The following third party components are used in the sys tem software The operating system is based on uC OS the Real Time Kernel by Jean Labrosse The FreeType library is used to render TrueType fonts The TCP IP stack is based on code in the XINU operat ing system written by Douglas Comer and others The ZLIB library is used for compression decompres sion 1 1 2 User Application The user application code consists of Object templates Global code and data Object instances You can create a user application using Qlarity Foundry which runs in Microsoft Windows or by writing a text description of the application in the Qlarity language using a text editor You then compile the design file which con verts it to an application binary file that can be downloaded to the terminal and stored in flash memory 1 2 QOlarity Programming Language The Qlarity language provides an object based event driven framework for the user application The user application is a collection of objects and data that determine how a user will interact with the terminal at runtime You design the appli cation by selecting or
249. was specified the return value is the return value of the UserDirectMsg API func tion If not immediate the return value is ignored 3 6 Direct Messages Direct messages are sent by the system to a specific object They are similar to a direct user message except that they are sent by the system rather than the user application The messages are enqueued in the message queue as are most other messages but they are only passed to a single object when they are handled The object must have a handler for the message Message MSG_COMM_ACCEPT Description This message is generated as the result of a successful call to the NetOpen API function When the network channel is opened the associated communications resource is passed to the object that called NetOpen via this message The communications resource may then be used to transmit data using the Send Transmit and for TCP channels TransmitUrgent API functions The resource may also be used to register for the MSG COMM RECEIVE message Handler Format func name socket as comm handles MSG COMM ACCEPT zs endfunc Parameters socket A value of type comm that is associated with the opened network communications channel See section 4 1 Com munications Interface Message MSG COMM ERROR Description This message is generated when errors are detected with a network channel An error code and an error message are passed to the
250. where a color value is required e g SetFgColor 4 6 6 SetPixel Syntax setpixel x as integer y as integer Parameters x The x position of the pixel to draw relative to the calling object s parent y The y position of the pixel to draw relative to the calling object s parent Description This function draws the pixel at the specified location using the foreground color 4 6 7 DrawLine Syntax drawline xl as integer yl as integer x2 gt as integer y2 as integer Parameters x1 The x position of the first endpoint of the line relative to the calling object s parent y1 The y position of the first endpoint of the line relative to the calling object s parent x2 The x position of the second endpoint of the line relative to the calling object s parent y2 The y position of the second endpoint of the line relative to the calling object s parent Description This function draws a line using the foreground color between the two points defined by x1 y1 and x2 y2 OptoTerminal Programmer s Reference Manual 4 6 8 DrawBitmap Syntax drawbitmap x as integer as integer gt bmp as bitmap Parameters x The desired x position of the upper left corner of the bitmap relative to the calling object s parent The desired y position of the upper left corner of the bitmap relative to the calling object s parent The bitmap
251. ww opto22 com Phone 800 321 OPTO 6786 44 4 4 1 Raise Syntax raise obj as objref Parameters obj A reference to the object to be moved in Z order Description This function moves the object in front of the sibling object directly in front of it If the object is the only child of its par ent or is already at the front this function has no effect 4 4 5 Lower Syntax lower obj as objref Parameters obj A reference to the object to be moved in Z order Description This function moves the object behind the sibling object directly behind it If the object is the only child of its parent or is already at the back this function has no effect 4 5 Redrawing Portions of the Display 4 51 Rerender Syntax rerender obj as objref Parameters obj A reference to the object to be redrawn Description This function invalidates the display region for the area of the specified object causing a MSG_DRAW message to be generated 4 5 2 Resize Syntax resize obj as objref width as integer gt height as integer OptoTerminal Programmer s Reference Manual Parameters obj A reference to the object to resize width The new width of the object height The new height of the object Description This function resizes an object to the specified height and width by altering the system software object attributes for the specified object The display regions for bo
252. xceptions These exceptions typically cause the system to stop processing after the description string is transmitted to the primary serial port B 14 Fatal Memory Exceptions FERR_NOMEM _ NO STACK MEM Unable to allocate mem ory Unable to allocate memory on stack FERR HEAPPTR Invalid heap pointer found FERR HEAPCORRUPT Heap corruption detected B 15 Fatal Flash Exceptions FERR FLASHWRITE Error writing to flash FERR FLASH Flash programming error FERR NODEFRAG Missing required defragmen tation area FERR_FFSCORRUPT Corrupted flash file system detected FERR_BADFFSSTART Current flash file system start is invalid FERR_BADSECNUM Bad sector number FERR_BADFFSWRITE Ilegal write attempted Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual FERR_FFSCANTSETUP Unable to setup flash file system 109 B 17 Fatal Message System Exceptions FERR FLASHREAD Error reading from flash FERR_BADINITPOST Unable to post MSG_INIT FERR_FLASHERASE Error erasing flash B 16 Fatal Initialization Exceptions FERR_BADSEMCOUNT Unexpected message queue error FERR GONEHWAREFIG Missing hardware con figuration contact QST FERR BADMESSAGE
253. y used as both an input and an output For input the 0 th element gives the first index into data indicating where to begin the text fitting Characters before this index are not fitted A value of 0 starts at the beginning On return the index to the first character for each line of text will be in the individual elements of the array with the 0 th element containing the index where text fitting began lengths An integer array used as both an input and an output For input The number of elements of data to fit or 1 to indicate all elements from the starting index to the end of data On return the number of elements that should be drawn for each line of text is indicated in the individual ele ments of the array with the 0 th element containing the total length of data fitted font The sysfont resource This may be either a BDF or a True Type font facenum The number for the desired face This value is only used with TrueType fonts and is typically zero 0 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Programmer s Reference Manual ptsize The desired point size of the rendered text This value is ignored unless font specifies a TrueType font data The data to be rendered as text The type can be a unibyte or byte array unistring string or charstr wordbrks An array of the same type as data that determines which characters to treat as word

Download Pdf Manuals

Related Search

Related Contents

Westinghouse 7726900 Instructions / Assembly  IGNITION EARTH 取扱説明書  Samsung LN40B650 manual do usuário  Curso de Automação III - Portal do Eletrodomestico  Valueline VLMB22000B20  Abrasifs agglomérés - Guide de dépannage  Mehmet Yilmaz - Badminton club Genève  取扱説明書 追補版（仕様） 住宅用太陽光発電システム構成機器仕様  カタログPDFダウンロード  MANUALE DI USO ED INSTALLAZIONE  

Copyright © All rights reserved. Failed to retrieve file