Home

Qlarity Foundry User's Manual

1. pp download size 2467 4 Flash required 64 kbytes Download application Baud rate 115200 Data Format en Send string over serial connection si RT Induce Set unit time Bee Results Download other BFF Upgrade firmware ee pee Clear results box Close Window 4 Open serial port whenever this screen is shown a Click Download Other BFF and the following dialog box is displayed Select BFF file to download Look in E larity Foundry ES EA EX 12 samples Df oie 2 basic_kepboard bit File name A Files of type Clarity application binary files bff Cancel wei 55 All BFF files in the default folder are listed change folders if necessary Click the file that you want to download and click Open A progress graph tracks the download and messages in the Results box indicate whether the download was success ful 7 4 Upgrade the Firmware Use the Upgrade Firmware function to download a new version of the terminal resident software firmware to the Qlarity based terminal e Refer to section 7 4 1 below for information on identi fying the version of your current terminal firmware e Refer to section 7 4 2 for information on preparing your terminal for downloading firmware e Refer to section 7 4 3 for information on downloading the new firmware 7 4 1 Determine Current Firmware Version If you are not sure what ver
2. yPos width and height properties to represent the position and size of the object on the display The code for xPos is representa tive of the code for all the new properties as shown below The horizontal position of the object dim xPos as integer init XPOS 0 func xPos newval as integer xPos newVal Relocate me xPos yPos endfunc xPos is an integer with a default value of 0 The valida tion method assigns the new value to the property as previ ously described then calls the Relocate API function to inform the system software that the object has moved to a new location on the display This generates a MSG_DRAW message for the appropriate regions of the display The MSG_INIT handler in the area object boilerplate code is similar to its counterpart in the non drawable code as fol lows Perform basic initialization for the object The function will be called once when gt the terminal starts up This function may also be called within gt Olarity Foundry whenever a property is gt set in the properties window func StartUp handles MSG_INIT Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 96 Relocate me xPos yPos Resize me width height Enable me enabled Attach me parent endfunc Notice that calls to Relocate and Resize have been added to the handler These properly initialize the location and size
3. amp Click to continue running the simulation after it has paused or stopped ir Click to execute the current line and stop on the next line Click to step into a function call If no function is on the current line this acts as a single step Click to step out of a function call This executes the rest of the current function and returns to the calling function It stops on the first executable line outside of the function call If there is another breakpoint in the current function execution stops there II Click to stop execution at the next executable line of Qlarity code e Click to remove all of the breakpoints that were set 3 6 Miscellaneous Bar The miscellaneous bar next to the toolbar contains the Lay out Scale Outline All Objects and Theme functions in Lay out View an error indicator in Code View and the Layout Scale in Simulation View Select Misc Bar from the View menu to show or hide the miscellaneous bar functions Layout View Misc Bar Layout scale 1 To change the scale of the work area click the drop down arrow and select the scale from the drop down list This function is also available in Simulation View Outline all objects Select this option to draw a line around all defined objects This 1s useful when you want to know the exact border loca tion of each object or when one or more objects were acci dently moved out of the work area Theme classic t To s
4. In Qlarity Foundry you use a workspace to define functions for the terminal at the Qlarity based terminal you use a user application to perform the functions When a workspace is compiled into a user application the Qlarity interpreter initializes the user application in Qlarity Foundry so you can see the results You can then download the user application to the Qlarity based terminal 8 2 2 Qlarity Objects A user application is constructed of Qlarity programmed objects An object instance 18 an occurrence of an object in the user application An object template contains the pro gramming code that defines an object When you create a basic design you will use objects from existing libraries several libraries are provided with Qlarity Foundry There are three types of objects as follows All three types of objects can be found in QSI libraries Non drawable object An object that serves a function not related to the display e g key definition communications etc Area object An object that can be represented visually on the terminal display An area object might be any of the following 63 e Bitmap an imported bitmap image e Lines circles or rectangles may include custom borders and fill colors e Text labels headings or a field where text may be typed or displayed Resources bitmaps and fonts are required for text and bit map objects Container object An area object that contains other obj
5. Li My Computer Qlarity files qly v Save as type Select the folder in which you want to save the file In the File name field type the name that you want to give the workspace you do not have to type the extension Click Save to save the workspace The original file is retained The new file is a copy of the original file If you are renaming the file you will need to delete the original file 4 4 3 Collect for Output Use this option to collect all of the resources used in a workspace into one file You can then move the file to another computer and all resources will be available to open the workspace To transfer a workspace to another computer select Collect for Output from the File menu The following dialog box is displayed Select where to output the workspace ax Save in Demo e e El Audio BDFFonts Binary Bitmaps Al Libraries My Computer TTFonts on 2 gssdemo aly EE 21 g70demo qly My Documents Z g70demomm qly gt 2 g75demo aly Desktop ES Cancel Li a File name History Qlarity files qly X Save as type In the File name field type the name that you want to give the output file you do not have to type the extension Click Save to save the file Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 26 4 5 Compile a Workspace Click on the toolbar or select Compile Workspace from the File m
6. The system generates a message indicating that the event has occurred and what it is The terminal s message han dling system determines which object or objects get the message and in what order the messages are processed The message is first passed to the root container which 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 this object first handles the message then passes it to each of its children beginning with the front most object in the container The terminal pro cesses the message to completion Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual 8 2 6 Enabled Disabled Objects An object instance can be enabled or disabled On the Qlar ity based terminal only enabled objects are displayed Dis abled objects still reside in the user application but they cannot receive or send most messages nor are they dis played on the terminal If a container object is disabled it cannot pass messages to its children In Qlarity Foundry all objects are displayed in the work area by default whether they are enabled or disabled However you can select the View Only Enabled Objects option on the Tools menu to hide disabled objects 8 3 Design a User Application This section provides instructions for adding and working with object instances in a worksp
7. Backlight On C Backlight Off For example you might use this action to provide a back light adjustment if the terminal is used in low light situa tions or in situations in which the light levels may vary dramatically You may also want to turn the backlight off to extend its life Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 74 Create two buttons for each adjustment one for lighter backlight and one for darker backlight one to turn the back light on and one to turn it off Each event e g button press changes the backlight as follows e Backlight Lighter and Backlight Darker adjust the back light one level brighter or darker with each event e Backlight Off turns the backlight off e Backlight On turns the backlight on to the level it was at before turning it off Custom Action This option allows you to program a custom action if an available Event Builder action does not meet your require ments Any action supported by the Qlarity programming language may be used Complex actions and events that require the full expressiveness of the Qlarity programming language such as loops and if then else logic should be entered in Code View Insert a Blank Line This action is not available from the drop down list of actions It appears only 1f the selected event has been previ ously edited in Code View and blank lines were inserted in the event s code This action does nothing It is used
8. af FunSer af NavScreen af Templates cr af ScreenSaver B p ey EHH HEHE HA 0060060008666 8800 To add a new object instance to a workspace you can right click Globals and select New Object Instance from the shortcut menu or use the icons on the Object Palette If any global code has been written for the workspace you can click Globals and see the properties associated with the global code Global properties apply to the entire work space 3 8 2 Object Templates A Qlarity program consists primarily of objects An object template contains the programming code that defines the object and how it behaves Once object templates are cre ated any number of object instances based on the tem plate can be added to a workspace Each object instance in a workspace must be associated with a template You will create object templates only if you are an advanced user Most users create object instances from predefined templates in libraries Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 16 NOTE library object templates Object templates in libraries are not listed in the Object Tree under the Templates heading Only object templates created in the workspace are listed under the Templates heading 3 9 Layout and Code Views Layout View is the default view mode You will generally use only Layout View unless you are customizing objects or creating your own objects using
9. and parent properties It also includes a handler method that handles the MSG_INIT message The code is as follows Perform basic initialization for the object The function will be called once when gt the terminal starts up This function may also be called within gt Olarity Foundry whenever a property is gt set in the properties window func StartUp handles MSG_INIT Enable me enabled Attach me parent endfunc The comments describe what the handler is and when it is called The method is called StartUp takes no parame 95 ters and has no return value It is declared as a handler for the MSG_INIT message The body of the method merely calls the Enable and Attach API functions passing the values of the enabled and parent properties This is necessary to properly ini tialize the objects by informing the system software about the state of the object at system startup All versions of the boilerplate code include a set of tool message handlers so that they can properly function in Qlar ity Foundry These methods are described in detail in the next section Other properties and methods can be added to the boilerplate code to implement the desired behavior in the object 10 5 1 2 Area Objects The area object boilerplate code implements a simple rect angular drawable object It also provides the enabled and parent properties as well as the xPos
10. as reference to GuiCursors closed as reference to boolean handles MSG _ TOOL GETHANDLES dim csrs 8 as GuiCursors init Esto CSR_UPLEFT CSR_UPDOWN gt CSR_UPRIGHT CSR_LEFTRIGHT gt CSR_DOWNRIGHT CSR_UPDOWN gt CSR_DOWNLEFT CSR_LEFTRIGHT redim xCoords 8 redim yCoords 8 xCoords 0 xPos xCoords 1 xPos width 2 1 xCoords 2 xPos width 1 xCoords 3 xCoords 2 xCoords 4 xCoords 2 xCoords 5 xCoords 1 xCoords 6 xPos xCoords 7 xPos yCoords 0 yPos yCoords 1 yPos yCoords 2 yPos yCoords 3 yPos height 2 1 yCoords 4 yPos height 1 yCoords 5 yCoords 4 yCoords 6 yCoords 4 yCoords 7 yCoords 3 cursors csrs closed true endfunc The MSG_TOOL_GETHANDLES message is sent to an object by Qlarity Foundry when the object is created All objects receive this message when a workspace is initial ized Qlarity Foundry requests the locations of the resize grips sizing handles that are drawn on an object when it is selected The handler is passed references to three arrays xCoords yCoords and cursors and a boolean variable named closed The handler places values in these parame ters to indicate the location and style of the resize grips The handler first creates and initializes an array of type Gui Cursors This is an enumerated type whose values indicate the style of the corresponding resize grip The selected style determines what curs
11. if threshold gt 10 then cal_screen enabled TRUE endif endfunc 5 Repeat steps 3 and 4 for as many handlers as desired Do not add two handlers for the same message 6 Click E or select Compile from the File menu to compile the workspace Any errors in the new source code are identified by messages in the Messages and Errors window If no errors are present the compiled workspace is returned to Layout View 9 6 Create a New Object Template The method override mechanism provides a powerful way to customize an individual object s behavior and response to events However you may want to change the behavior of all instances of a particular object Adding an identical override to all objects from a particular template would be tedious and prone to error It is better to modify an existing object template to create a new object template NOTE do not modify code in libraries It is recommended that you do not directly modify the code in the QSI standard object libraries QSI occasionally updates these libraries and your changes would be lost Rather you should copy the template code into your work space or a personal library e g mylib and make your modifications there Do the following to create a new object template based on a library object template 1 Click on the toolbar or select Add Edit Templates from the Edit menu and the Add Edit Templates dialog box is displayed You can also right click anywhere in th
12. tmp handleNum mod 4 if tmp O then handleNum handleNum 6 mod 8 elseif tmp 1 then handleNum handleNum 4 mod 8 else handleNum handleNum 2 mod 8 endif endif XPOS t NewAX yPos newY width newWidth height newHeight Relocate me xPos yPos Resize me width height Save any changes we just made Tool Persist xPos Tool_Persist yPos Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 100 width height Tool Persist Tool Persist endfunc When the user drags a resize grip in Layout View the object being resized receives a MSG_TOOL_MOVEHANDLE message from Qlarity Foundry The grip being manipulated and the change in position are passed to the handler as parameters The handler typically determines which grip is being dragged calculates its new size and position updates its properties requests a redraw and persists the values with Tool_Persist This is what the boilerplate code does There is also some validation code to prevent the object from being sized to a height or width of 0 The handleNum parameter is passed to the handler as a reference which allows the handler to change the currently selected grip if desired Notice that the boilerplate code reassigns handleNum when the object is dragged inside out 1 e a grip at the bottom is dragged above the top of the object or a grip on the right edge of the object is dragged
13. Bitmap name Filename Alarm resources alarm bmp all resources all bmp bottomLett resources bottomieft bmp bottornright resources bottormrght bmp lightott resources lightott bmp lightorn resources lighton bmp Temp resources temp bmp toplett resources toplett bmp topright resources topright bmp Resource data Preview Filename Ho selection Browse Rename bitmap Mew bitmap Remove bitmap cos EA All resources used in a workspace are managed from this dialog box Select the tab for the resource type you want to manage You can add a new resource rename an existing resource change the file for an existing resource name or remove a resource from the workspace Refer to section 5 2 for information on editing resources 8 1 5 Add Remove Libraries A library is a file that contains predefined object templates that you can use to create user applications Library object templates are programmed to be flexible This means that you can modify them without additional programming to meet most requirements In basic design libraries are your primary source of new objects When you create a new workspace your selections in the New Qlarity Project dialog box determine which libraries are automatically added to the new workspace You can also add or remove libraries after you open the workspace NOTE library object templates Object templates in libraries are not listed in the Object Tree
14. F EE aff HideFullScreenColorLblT EH of QwertyKeypad of TranslucentColorPicker E af BacklightD cup OptoTerminal Qlarity Foundry User s Manual 2 0demo gly GombFinderPlay E ES A BS 2 No Error Events Overrides hal Show only event functions init value t Play init parent funscr init xpos 193 init yoos 40 of Backlight ppl TtanslucentColorPicker ColorPickerv2 j 41 E af ContrastDownBtn init height 29 af Contrastl pBtri a ETH 8 yf EndGames ce SO af HelpSideButtonsS cr EE e fy ObjectsSer HEI af GraphicsS cr HE 5 DiagnosticsScr 280 af FunSer A E ff RetunToDemoLbl BombrinderPlay A E of BombFinderD ata A E of BombFinderLbl TA E af BombFinderlmg HEI ah NavScreen Bd af Templates cr u HE e 5 SplashScreen a af ScreenSaver a e af ScSaverOn a e af ScrSaverDit a af Scr2Home a af Scr2Next Be af Cun_DDL_ListBox ES af Cur_DDL_HideTimer mlali Toi lo if IncludeBombs func click endfunc fendif init xinset init yinset i ad Ho Errors Messages E Ready 9 2 Understanding Qlarity for Intermediate Design Before you can effectively design a user application at the intermediate level you need to understand some basic Qlar ity concepts which are explained in the following sections 9 2 1 Qlarity Programming Language Qlarity syntax is based on the BASIC programming lan guage with extensions added to handle creation an
15. Only object templates created in the workspace are listed under this heading However you can create a new object template based on an existing library object see section 5 1 Add Edit Templates To add a library to or remove a library from your work space click jgy on the toolbar or select Edit Libraries from the Edit menu A dialog box similar to the following is dis played Filename Status Name Edit Library common lib loaded sys1 52 common progobjs lib loaded sys1 52 progobis Remove library ezlib lib loaded sys1 45 ezlib Create new library Add existing library Entries Templates gt Animatedlmage Hit i Ser Animated mage Source AnimatedimageS ample Bitmap BackButton HomeButton Th Ser Backbutton Source ER aa a BasicEthernet Line Tat BackDownBitmap Bitmap A i BackUpBitmap Bitmap g BasicSerial NextButton CyTat BasicE thernet Source DisplaySetting a Polygon bad Tre ii ul PA Ethemet ine PolyLine isplay5 etting ource E Ethernet Source H Gauge 3 scale EthernetProtocolFunctions Gauge Source ha gt All libraries currently in the workspace are listed Click a library to display its entries and object templates at the bot tom of the dialog box 5 3 1 Add Existing Library Do the following to add a new library to the workspace 1 Click Add Existing Library and a dialog box appears that lists all the libraries included with Qlarity Foundr
16. OptoTerminal Qlarity Foundry User s Manual Name String ezimage_5 enabled boolear true parent objret default poz integer 46 ppos integer af transparent boolean falze transparentcolor color rgb_magenta ezimage bitmap blirik boolear blinkrate integer event ma ageew eventsourceobj obiret eventsourceprop string eventbargetoby obiret eventtargetprop sting i greenbuttori eventtangetvalue string hight eventoby ezevent If El appears in a property field when you select the prop erty a drop down list of property options is available Click to display the drop down list and then click the option you want to use If the property is a workspace resource bitmap image font sound or binary data a Select button ry is displayed next to the drop down arrow If the resource you want is not in the drop down list click _ to open the Qlarity Resources dialog box Select a resource and click OK to add it to the workspace and to the property s drop down list Select the resource from the drop down list to place it in the property Refer to section 5 2 Edit Resources for infor mation on the Qlarity Resources dialog box Refer to section 8 3 3 1 Select Color for information on selecting a color NOTE selecting a parent object If you want an object instance to be the child of a parent object placed in a container object from the parent property drop down list select a conta
17. To make the object the child of a parent object select a container object from the drop down list and the object instance is automatically moved and linked to the selected object in the Object Tree To move an object to the root con tainer select default sendtoport This property receives the data string that is to be sent through the Ethernet port Data can be sent to this property from an Ethernet object configured in Event Builder see OptoTerminal Qlarity Foundry User s Manual section 8 4 When the Ethernet object s sendtoport prop erty receives data it automatically sends the data followed by a semicolon out the port protocol Enter the protocol to be used to send the data e g UDP or TCP localport Enter the address for the UDP or TCP port on the Qlarity based For additional information refer to your Ethernet protocol or contact your network administrator foreignport Enter the address for the UDP or TCP port on the host For additional information refer to your Ethernet protocol or contact your network administrator targetipaddress Enter the IP address of the device to which you are sending data connected This property reflects the connected status of the Ethernet object appendterminator This property determines whether a semicolon is appended to the end of all data sent out the Ethernet port 8 5 3 Receive Data You can send data from an external device e g c
18. a Edi_CompositeObject Reset border to default I 6 CompositeSunken L Iv Fade Effect E Bdr_InnerButton Rounded Corners Preview Options Sirene Changing preview options has E Bdr_InnerLabel M Use foana Sapon no effect on the actual border neon Moa LabeBorder bles pi 5 TE Save current border and B Bdr_None nubs Boies Object fil color color settings as theme le m Bd_Scrolbar JV Use a double border Background color Mea sore Outer width 1 2 I Inverse Pressed a Bdr_T abBorder idth j1 i i nner wi IV Fill preview Cancel 5 5 1 Themes The colors and border definitions assigned to named colors and named borders are grouped together in themes See section 5 4 Edit Named Colors for information on named colors Several predefined themes are set up in Qlarity Foundry You can change the colors or border definitions in a predefined theme or you can save the changes as a new theme Generally a theme represents a color scheme such as a theme with all grayscale colors a theme with shades of blue or a theme with neon colors To view the borders in a OptoTerminal Qlarity Foundry User s Manual theme select the theme from the Theme drop down list The borders assigned to the named borders are shown Each theme uses the same named border labels only the border types assigned to them are different from theme to theme Theme Click the drop down list and select a theme Its defined bo
19. provided with Qlarity Foundry contains object templates that are programmed to send data to a computer or other compatible device through a serial or Ethernet port Once a communication object or objects is set up you can use Event Builder section 8 4 to set up an event to send data out the port No programming 1s required 8 5 1 Serial Objects To use the serial port to send data add a serial object to the workspace The optional second serial port can also be used by adding a second serial object Following are the properties of a Serial object Name Type a name for the new object type over the default name Each object in the workspace must have a unique name An object name has no size limitation but must start with a letter A name cannot contain spaces but may use the underline character _ The percent pound and dol lar sign symbols can be used at the end of the name enabled If the object is to be enabled select true from the drop down list To disable the object select false parent To make the object the child of a parent object select a container object from the drop down list and the object instance is automatically moved and linked to the selected object in the Object Tree To move an object to the root con tainer select default Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 76 comport From the drop down list select the communicatio
20. rides drop down list If this option is not selected all func tions that are eligible to be overridden are listed 3 8 Object Tree The Object Tree contains four branches e Globals e Templates e Advanced Code e Libraries The Globals branch is always visible the Templates Advanced Code and Libraries branches are only visible in Code View The Advanced Code and Libraries branches are disabled by default as they are intended only for advanced users refer to section 6 3 for information on enabling these sections The illustration below shows all branches of the Object Tree in Code View Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Er 7 Ela Globals EE af w atchdogT imer A iat af ExceptionDisplay E a TouchkKillnfoLbl E sf InfoLbl E af FullScreenColorLbl fea al FTPServer EE al HideFullScreenColorLbiTimer fo al O wertyKeypad pa gt af TranslucentColorPicker E af BacklightDownBtn mh Backlight pbtn ff Contrast ownBtn ser ee a Contrast pBtn E af EndGames 2 af HelpSideButtonsScr at a Graphic 5cr 5 SplashScreen E y ObjectsScr 5 DiagnosticeScr af Funser E af NavScreen 2 af TemplateScr F gf ScreenSaver ta Internal EfB Templates ls LaserPolygon Advanced Code Ey Libraries My Extra My LataProc My Basic Each object instance listed in the Object Tree has an icon that shows the type of object lab
21. 1s removed from the workspace 3 Click Close to save your changes and exit the dialog box The workspace is compiled and the objects in the library are no longer available for use in the workspace 5 3 3 Edit Library Library editing functions require an understanding of Qlar ity programming Refer to Chapter 9 Intermediate Design and Chapter 10 Advanced Design for informa tion on Qlarity programming NOTE do not edit QSI libraries You should not edit QSI libraries QSI libraries are regularly updated and the new libraries replace the existing ones so OptoTerminal Qlarity Foundry User s Manual any changes are overwritten You should edit only libraries that you created see section 5 3 5 Create a New Library You can modify an object template by importing it into your workspace see section 5 1 1 Add a New Object Template In the Libraries dialog box click a library to select 1t then click Edit Library and the following dialog box is dis played Edit Library x Fath le program flesgsi corporation glanty foundry comman ib Icon Foreground Icon Background O Hame E Version i 52 Warning Any changes you make to libraries may affect other projects Additionally any changes will take effect immedediatel and cannot be undone Version Edit Entry Animated mage Source 1 52 Animated mages ample Bitmap 0 00 Rename Erti Back button Source 152 BackDownBitma
22. Create New Named Color Click New named color to create a new named color You are prompted to enter a label A label has no size limitations but must start with a letter or underline character _ A label cannot contain spaces but may contain the underline character The percent pound and dollar sign symbols can be used at the end of the label Enter a label for the new named color and click OK The new named color is added to the list with a default color of white To change the color click a color in one of the color palettes The color selected will be the color in every theme unless you change it for a selected theme and click Save current border and color settings as theme 5 4 2 3 Delete Named Color To delete a named color that you created select it then click Delete named color A prompt is displayed to confirm that you want to delete it Click Yes to delete the named color You cannot delete the default named colors 5 4 2 4 Rename Named Color To rename a named color that you created select it then click Rename color A message is displayed to warn you that you should not rename a named color that has been assigned to objects If you do the workspace will not com pile Click Yes to rename the named color After changing the name click OK to save the change You cannot rename the default named colors 5 4 2 5 Reset Color to Theme Default To restore the originally assigned color to a theme s
23. Items When defining objects you may specify one default prop erty and one default function To edit the default function of an object double click the object in Layout View or the Object Tree and the editor of your choice either Code View or the Event Builder is opened To edit an object s property in the Properties window select the object in Lay out View and press lt Enter gt If the default property is of a data type that offers a Select button _ in the Properties window click to edit the property in the custom editor for the property default item lt item type gt lt item name gt lt item type gt is either func or prop lt item name gt is the name of a method or property in the current object template The Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual default item directive is only valid as following a doc obj directive doc object buttonv2 defaultitem func Click defaultitem prop value documentation as appropriate B 13 Defining Border Styles You can use the stylemap directive to specify a new border style element for an object stylemap lt style name gt lt style assignment gt lt style assignment gt lt style assignment gt Where lt style name gt is a valid Qlarity identifier name that names the style Each lt style assignment gt defines the style for a specific theme If the user selects
24. Objects IY Preview while dragging Object outlines Grid Time me the mouse must be held still before a drag or resize takes z250 ms vi Allow locked objects to be mowed within the Object Tree Cancel Show legend around display With touch screen displays you can add a border around the display for a stick on touch key legend If you are using a touch key legend select this option If you are not using a touch key legend leave the checkbox empty Grid Spacing You can display a grid over the work area to help you more accurately place and align objects Enter the space between grid lines in pixels between 2 and 25 Show Grid Select this option to make the work area grid visible Snap to Grid Select this option to force objects to snap to the nearest grid line when added or moved This is useful for more accurate placement and alignment of objects Preview while dragging only available in Windows 2000 and Windows XP This option controls the way objects appear while dragging them with the mouse to move them in Layout View If selected a preview of the object in the new location is displayed If not selected an outline of the object is displayed Time the mouse must be held This setting determines how long in milliseconds the redraw function is delayed when dragging an object For most systems the default should be optimum If you need to increase or decrease the time interval en
25. OptoTerminal CD ROM into your CD ROM drive The Setup program should auto start If it does not click Start and click Run The following window appears Type the name of a program Folder document or Internet resource and Windows will open it For you open Cancel Browse Type e setup in which e is the letter of your CD ROM drive The following window appears InstallShield Wizard Welcome to the InstallShield Wizard for Qlarity Foundry for Opto 22 version 2 50 OPTO 22 The InstallShield Wizard will install Qlarity Foundry for Opto 22 version 2 50 on pour computer To continue click Next Phone 951 695 3080 Toll free in the LSA 800 835 6786 Ernail support opto22 com www opto22 com Cancel If no other Windows based applications are ruming click Next and the License Agreement window is dis played InstallShield Wizard License Agreement OPTO 22 Please read the following license agreement carefully Expect more Get more Do more Press the PAGE DOWN key to see the rest of the agreement END USER LICENSE AGREEMENT FOR O51 CORPORATION SOFTWARE IMPORTANTIREAD CAREFULLY BY CLICKING THE ACCEPTANCE BUTTON OF INSTALLING THE SOFTWARE VOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING A PARTY TO THIS END USER LICENSE AGREEMENT THIS END USER LICENSE AGREEMENT EULA 1S A LEGAL AGREEMENT BETWEEN TOU EITHER AN INDIVIDUAL OF A SINGLE ENTITY AND G51
26. Serial Transmit e Play Note e Set Contrast e Set Backlight e Custom Action After you select an action options appear in the action con figuration area of the Event Builder dialog box to configure the action Refer to the following sections for information on each action s configuration Show Screen This action selects a new object to show While this action 1s typically used for screens any object may be selected When this action is executed the currently displayed screen is hidden and the newly selected screen is shown If you want to an object or screen to pop up over the current screen you should use the Enable Disable Object action instead Show Screen JEv_enable_screent OptoTerminal Qlarity Foundry User s Manual Click the drop down arrow and select the object from the list with which you want to replace the current object Enable Disable Object This action enables or disables the selected object When an object is disabled it is not shown on the terminal display and will not respond to most events In the following action example when the event occurs a spinner object is dis abled To enable the spinner object a second event and action are required Enable Disable Object Object Enable this object Disable this object Toggle this object s enabled state Set Property This action sets the value of an object property or global variable You can use Set Property for exampl
27. Source objects object templates e Embedded resources e g bitmaps BDF fonts and TT fonts Only resources that are used in an object template e g a custom button tab etc need to be embedded in the library Libraries can also reference any resource that has been loaded into a workspace However by embed ding the resource in the library you make certain that it is available when an object instance is created To add a new entry to a library click Add New Entry The following dialog box is displayed New Library Entry i x Entry name Entry type Source Filename Browse cos Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 36 Entry Name Enter a name for the new entry A name has no size limita tion but must start with a letter or underline character _ A name cannot contain spaces but may contain the underline character The percent pound and dollar sign symbols can be used at the end of the name Entry Type From the drop down list select the type of entry e Source object template e Bitmap resource e BDF font resource e TT font resource e Audio file e Binary file Filename If the library entry 1s a resource e g bitmap or font enter the location of the resource file Click Browse to find the file 1f necessary Click OK to continue If the library entry is a source object template a message 1s displayed explaining
28. The factoral of n gt written n is defined as n n 1 SCZ Fe chat ley fune CalerFactoral tocalc as integer gt returns integer endfunc 101 Note that Fparam lines must be completed in one line You cannot use the line continuation character to extend them to more than one line 10 6 Guidelines for Designing New Object Templates This section contains advice and collected wisdom regard ing the design of new Qlarity object templates Designing good object templates is the most complex task in Qlarity programming Once this skill is mastered the full potential of Qlarity can be utilized in your application development Look at template code in the QSI libraries Each library contains the full source code for every object template in the library You are encouraged to study the code in these libraries to learn the techniques and conven tions used in their design Often the easiest way to create a custom object is to modify a template that is similar to the desired object Use the boilerplate code This code provides a complete working Qlarity object ready for customization Do not unnecessarily reinvent the wheel Use a consistent style This is important in any programming project QSI has developed a set of Qlarity programming style conventions for objects that are designed in house This was also used in the boilerplate code The style guide is available on the Qlarity Web site www glarity
29. View Modify Seral Port Settings Remember to specify the terminal hardware with the Terminal tab Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Speaker Volume Click and drag the slide button to adjust the volume in Sim ulation View Mute Enable this option to turn sound off in Simulation View Ethernet Simulation Select a network simulation choice from the drop down list If you select Default simulation your computer s network connection if available will be used in Simulation View to transmit and receive data requested by the application Select Do not simulate if you do not want Qlarity Foundry to access the network in Simulation View If your PC has 2 or more IP addresses assigned to it those addresses will also appear in the drop down list and you can select the IP address to use when simulating TCP and UDP communication Play Sound at Breakpoint If this option is enabled a sound is played each time the source level debugger reaches a breakpoint in the code Refer to section 3 10 3 for more information Click Select to display an Open dialog box and select the waveform file you want to use 49 6 5 1 Communications Window Settings Click Communications Window Settings to set up com munication preferences for the Communications window in Simulation View x Communications Settings Display as Hexidecimal iY Wrap li
30. View Toolbar Deh fs tte gt 4 BABA Ly Click to start a new workspace Refer to section 4 1 for information cg Click to open an existing workspace Refer to section 4 2 for information E Click to save the current workspace Refer to section 4 4 for information E Click to compile the current workspace into the for mat required for a user application A workspace also must be compiled to properly display in Layout View Refer to section 4 5 for more information Click to open the Download Application dialog box Refer to Chapter 7 for information d Select code then click 4 to cut the selected code from the workspace The code remains in the Win dows buffer until replaced by other cut or copied code Select code then click to copy the selected code 15 ie The code remains in the Windows buffer until replaced by other cut or copy operation Click to place cut or copied code into a workspace or another Windows application at the cursor position Click to undo the last action performed Click to redo the most recent undone action Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Click to go to the next bookmark in the displayed object Use the Toggle Bookmark tool to add book marks to an object s code Click to add or remove a bookmark in an object s code at the cursor location Bookmarks m
31. When the resize grips are dragged the object should respond accordingly Requiring each object to implement its own Layout View behavior allows you to extend the functionality of Qlarity Foundry in unique and powerful ways This power and flex ibility comes at the price of some complexity in writing handlers for the tool messages Fortunately the boilerplate code is sufficient for most objects This section describes the implementation of the tool han dlers in the new template boilerplate code The tool mes sages are explained in detail in the Tool Messages section of the OptoTerminal Programmer s Reference Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Since a non drawable object is not visible on the display in Layout View its handler methods for tool messages are small and straightforward The code for the handlers is as follows FE TOOL TALS Function rs called by Olarity gt Foundry when you change the attachment gt of an object i e in response to gt dragging it around the object tree Note the purpose of this function is to gt allow you to attach to another gt container you should not change your gt parent property or call Tool_Persist gt until you receive a MSG_TOOL_ATTACHED gt A MSG_TOOL_ATTACHED will be sent in gt response to an Attach API function call fune To
32. aie A A a A E O 77 B27 ave and Complle a W ORK SD AC pestes dc odie elec TF Da Ea Y OPKSD ACE iia 1 9122 C Omp e a Works Dacia tio cra TI 5 0 Downloada USADA CAOS A AE 1 CHAPTER 9 INTERMEDIA TE DESTINA aucune cacsueseassscscsssacucuacccaescasseucedeuvaceluaseuseuvedecedsueutexcuassehcbececcouecccesesedutwescesss 79 Di VI WS te Codes A AAA con Re nena 79 9 2 Understanding Qlarity for Intermediate Design cccccccccnnnonnnonnnonnnnnonnnnnnnnnnnnnononononononononononnnnnnnnnnnn ocn non nn non n naar nnnnnnnns 80 02M Olarity Proc raimiinin 2am OU ase dada 80 92 2s Ob Je cisma T empia CS nr dit tt 80 93 Ol rity Code tor ODJe CiS kesian daveisth Rast eadin cad a A 81 Dal Property AMA AULAS a Di eee Gana Bianca ats 81 YIL NICTIOO Override Si cass tuescada E E E a E aceesieaecaaes 81 9 4 Handling Events With larity Code iii Ad A 81 941 Overmide an Blech MCtMOd eta dei di iia 82 DP MOM AO A serrse setae uae seers ae coe ee E E sees E ease aaah decease ansencaeseasealratesaeassaueecel care 83 OA Add Global Variable toa WOK space uM coi tel atin chs R 83 9 5 1 1 Add a Global Variable Using New Variable cocccccccncnnnnnnnnnnnnnnnnnnnnonnnononnnnonnnonononononnnnnnnnnnnnnos 83 9 5 1 2 Add a Global Variable in the Global Code Section ooooooooooooccccccocncnnnnnnnnnnnnonnnnnan ono ononnonocccncncnnnnnnnnos 83 9 5 2 Add a Global Function to a Workspace ta it de A 84 9 5 3 Add a Global Message Handler to a Workspace
33. application to unit Download pp download size 24614 Flash required 64 kbytes Download application Download other BFF Upgrade firmware Serial Ethemet Baud rate 115200 Data Format ani Send sting over serial connection st ra Induce Set unit time A E Results ee Eee Clear results box Close Window J Open serial port whenever this screen is shown a 2 Click Download Application to proceed A progress graph tracks the download and the Results box dis plays messages indicating whether the download was successful If an error occurs verify that your communications set tings are correct Power the terminal off and back on and once again place the terminal in the proper mode Repeat the download process NOTE clear results Click Clear Results Box to clear the messages in the Results box Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual 7 3 Download a BFF File You can download a user application that is not currently loaded in Qlarity Foundry to the Qlarity based terminal but the file must be in binary file format BFF Save a file to BFF using the Generate BFF function on the File menu see section 4 6 Select Download Application from the File menu and the Download dialog box is displayed E Download application to unit Download Serial Ethemet
34. be displayed at the angle at which it was created Availability BDF fonts and TrueType fonts are readily available from several sources including many public domain Internet sources TrueType fonts can be used on any Windows com puter Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Terminal Memory Use A BDF font file is smaller than a TT font file If you are using only one or two sizes of a specific font Arial Times Roman etc you can save terminal memory using BDF fonts If you are using several point sizes for a specific font the TT font will likely use less memory than three or more BDF fonts Display Speed BDF fonts are displayed more quickly than TrueType fonts on Qlarity based terminals While the terminal renders Tru eType fonts fast enough that the difference in drawing speed is rarely noticeable you might consider using BDF fonts for display items that will change their text frequently such as items that are frequently polled from a remote device Copyright Many fonts are copyrighted Be sure to purchase or obtain permission to use a copyrighted font in your user applica tions 5 2 8 Audio Some Qlarity based terminals have an audio decoder option that enables them to play waveform audio files If your ter minal supports an audio decoder you can add audio files in the wav format to your workspace You can play the audio fi
35. canes lode tears thoansoacstudens ndauntansanases 65 6 37 Addan Object From the Object Palettes nal asietnietnncsigntasisdt sain a nieibtusnmbane teas 65 Sole2 Add an Object From the Shortcut Menta tas dio 65 03 2 MOVE Resize and Reorder OD CCls ios os dd 66 A SP Geanstnonesecmesntehtuseenconbecamseniets 66 A O uaa taste anita an neta eal ede EE E E 66 Saz Clan ve Lhe Order oro Decidir keane 66 302 A AION SIZE Space OD CCIS ni a a aeaa 67 ns AS A tusetousate snags a a aao a duane nianndagsenasts 68 Bo ES O Le aaa alee E E T E E AAE TE ARE PT A EE uc daniatuesuantantadees 69 Bb Eve ne OTIC Eeoa n a n A E S T A 70 01 Over ew Or Event Bulder tes aiii a a a a A eee 70 042 Event Builder DIODO Sesta Ea rE E a a a 70 34 3 Select and Confiture ACHONS ideales ibcads 71 Ska SA A E N a a a 71 AZ COn Pure ACU ONS lar 12 044 Load Event Builder Sample Workspace ie ire ae aerea eona lolo ree 74 AI Tnk DO O Ea E A AEEA 74 BAe LOGOS DENO nerne een a E a a a Pane Genes tdenesencoss 74 odka Keypad DOMO a laicas 75 St Olanity Code and Event Builder seoran o E a e ENO Eea 75 40 TrOUDICS NOON easi E E a a A E 75 6 5 Communication OD SC Eo N a a A 75 Sede Sena OD COE aa nad 75 A EE ECOD E O eian aaa a A A 76 0 RECI Dd araara a e E AA EE AEA E AEA anise dantentta oust 76 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual 5 60 Test the User App Cate mica ei
36. click the item in the key word list 11 Show Qlarity Language Help Ctrl F1 Select this option or press lt CtrI gt lt F1 gt to view the Pro grammer s Reference Help file The Programmer s Refer ence provides information on the Qlarity programming language and message handling system detailed informa tion on the syntax to write programs in the Qlarity language descriptions of system messages a Qlarity API Applica tion Programming Interface function reference and other information on programming in the Qlarity language Show Qlarity Foundry Help Shift F1 Select this option or press lt Shift gt lt F1 gt to view the Qlar ity Foundry Help file The Help file provides the informa tion in this Qlarity Foundry manual so that you can access it online while you are working in Qlarity Foundry Sample Workspaces Code View only Select this option to open the Object Documentation Help file and select a sample workspace from the contents Tutorials Code View only Select this option to open the Object Documentation Help file and select a tutorial from the contents About Qlarity Foundry Select this option to identify the version of Qlarity Foundry BFF and the firmware that you are running 3 5 Toolbar The Qlarity Foundry toolbar contains icons for commonly used functions Click an icon to open the function Select Toolbar from the View menu to show or hide the toolbar The following sections describ
37. code AutoDoc will then Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual find the information you enter and add it to the Object Doc umentation To document a program item type the following in the same location as the item e g to document an object prop erty enter the documentation within the object This documents an object property OR gt global variable doc property lt name gt doc prop lt name gt This documents a global Tunctionr or gt object method doc func lt name gt doc function lt name gt doc override lt name gt only use this gt if the function is designed to be gt overridden This documents an object itself doc object lt name gt To enter a description of an item begin each line of the description with a tilde doc object buttonv2 The ButtonV2 object is a versatile gt object that responds to touchscreen gt TOG When you touch an instance of the gt Buttonv2 object the function called gt Click is called The tilde must be the first non whitespace character on the line otherwise it is treated as a comment When documenting a function you can add parameter doc umentation as follows doc func CalcFactoral param toCalc The function calculates the factoral of this parameter CalcFactoral calculates the factoral gt Of its parameter
38. colors in the workspace All object background and fill colors in the workspace are determined by the color or named color assigned to the objects or properties 5 5 2 5 Create New Named Border Click New named border to create a new named border You are prompted to enter a label A label has no size limi tations but must start with a letter or underline character _ A label cannot contain spaces but may contain the underline character The percent pound and dollar sign symbols can be used at the end of the label Enter the a label for the new named border and click OK The new named border is added to the list with default attributes To change the border change the General Effects Rounded Cor ners and Double Borders options The border attributes selected will be the same in every theme unless you change them for a selected theme and click Save current border and color settings as theme 5 5 2 6 Delete Named Border To delete a named border that you created select it then click Delete named border A prompt is displayed to con firm that you want to delete it Click Yes to delete the named border You cannot delete the default named bor ders 5 5 2 7 Rename Named Border To rename a named border that you created select it then click Rename border A message is displayed to warn that you should not rename a named border that has been assigned to objects If you do the workspace will
39. containers objects in front of the object are transparent Also the hierarchy determines the order for messaging Enabled and Disabled Objects An object may be enabled or disabled without deleting it from the user application An enabled object can process most messages Disabled objects are not drawn on the dis play and are not eligible to process messages In Qlarity Foundry an object can be enabled or disabled using its object properties but disabled objects continue to be dis played Event An occurrence that signals a change in the terminal state such as a touch screen press a keyboard press a serial char acter receive or a system time tick Events generate mes sages that allow the user application to react to the event in a defined way Globals Code and data that exists independently of objects in an application Libraries Collections of predefined object templates and or resources available in Qlarity Foundry Some libraries are provided by QSI however advanced users may create their own libraries Message Delivers information about an event to the user application User defined functions and object methods are called when the message they handle is generated Message Handling System System that handles event processing for the Qlarity based terminal When an event occurs the system software and or hardware drivers generate a message indicating that the event has occurred The message is passed through the
40. height and or width integer in the Properties window Select from the drop down list or type in the new value To move an object do one of the following e Click in the center of the object hold down the mouse button and drag the object to a different position You can hold down the lt Shift gt key while moving an object to limit its movement to horizontal vertical or a 45 angle Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual e Change the x and or y position integer in the Properties window Select from the drop down list or type in the new value 3 13 Move and Resize Windows The following windows can be moved resized or undocked separated from the main window e Object Tree e Properties window Layout View e Object Palette Layout View e Messages and Errors e Miscellaneous bar e Communications wndow Simulation View e Keyboard Simulation View e Keypad Simulation View Each window has its own title bar at the top the Miscella neous bar has a title bar on the left side under the Close but ton To move a window click the title bar hold down the mouse button and drag the window to another location elther in the main window or outside the main window As you drag it you will see an outline that indicates the posi tion and size it will be When it is in the position you want release the mouse button If you release the
41. mes sage handling system in the Qlarity based system software which reviews the object hierarchy and determines which object gets the message and in what order the message will be processed In order to process a message an object must be enabled which also causes area and container objects with a defined area to be drawn on the screen Disabled objects do not process most messages Methods Functions contained in an object comprising much of the code portion of the object The methods for each type of object are defined in the object template but each object instance may override some of the object template s meth ods Methods define the behavior of an object at runtime and typically either manipulate or depend on the values of the object s properties Method Override A function in an object instance that overrides or replaces the method defined in the object template Each object instance may override some of the template s meth ods The override function has the same name and parame ters as the template method and the code in an override may call the template method if desired Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 104 Non Drawable Object An object that has a purpose not directly related to the ter minal display Examples of non drawable objects include communication event and keyboard objects Object The basic unit of a user application You define objects by
42. ming language This chapter provides information to help users design their own objects using Qlarity Advanced users are not bound by the selection of objects available in QSI libraries As an advanced user you can design objects that best represent the data and user interface elements for a particular application For example if the Qlarity based terminal is replacing an existing control panel you can create objects that mimic the look and feel of the user interface elements on the old panel The variety of objects you can create with Qlarity is virtually unlimited This chapter introduces the Qlarity concepts that are crucial for object design including the following e Validation Functions e The Qlarity API Library e Exception Handling It also includes information on the following e Create a New Object Template e Guidelines for Designing New Object Templates Before proceeding you should be familiar with the con cepts presented in Chapter 8 Basic Design and Chapter 9 Intermediate Design and have some practice with Qlarity design at those levels In addition you should review the OptoTerminal Programmer s Reference Manual as 1t cov ers basic information needed for programming in Qlarity 10 1 Advanced Code Sections To add advanced code constructs and to view and debug code in Qlarity Foundry libraries you need to enable the advanced code sections in Code View To display the Advanced Code and
43. mouse button 21 close to a docked position in the main window the win dow snaps into place NOTE floating windows If you do not want the window to snap into a docked posi tion hold down the lt Ctrl gt key as you drag it It then becomes a floating window that can be positioned any where on the screen To resize a window move the mouse pointer over any side or corner until the pointer changes to directional arrows Click and hold the mouse button and drag the side or corner of the window until it is the size you want then release the mouse button NOTE resize the main window You can resize the main window using the same method To close a window click Ed To open a closed window select its name from the View menu 3 14 Where to Go From Here When you have finished reviewing Getting Started refer to Chapter 8 Basic Design to learn about the Qlarity design process and specifically to section 8 4 Event Builder for information on Qlarity Foundry s user friendly design tool for creating user applications Refer to chapters 3 through 7 as required to answer specific questions about using Qlarity Foundry Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 22 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 4 WORKSPACES 4 1 Start a New Workspace When you first start Qla
44. overridden method in the template The same parameters that were passed to the override method should be passed in Default Refer to the OptoTerminal Programmer s Reference Man ual for information on how functions are defined in Qlarity NOTE create a new template If you find that you are adding identical override functions to many instances of the same object consider modifying the object template to create a new template with the desired functionality 9 4 Handling Events With Qlarity Code Many Qlarity objects publish events to signal when an action has taken place such as the user pressing the touch screen data arriving on the serial port and so on Qlarity objects provide this notification in the form of functions that may be overridden in object instances to provide spe cific object behavior For example many button like objects such as the ButtonV2 or IconButtonV2 objects publish a function called Click By default this function does nothing but each instance of this object can include an override of the ClickQ function to take some action in response to a press event on the object A typical response might include send ing some characters to a communications port switching to Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 82 a different screen or modifying the contents of another object In this manner an object s response to events is pro grammed using the Qlarity p
45. size of the object Text Settings Contains properties that set the less common text attributes in an object such as the inset of the text from the edge of the object or the justification of the text within the object Misc Contains properties that do not fit into any of the above cat egories Some objects may contain other categories that are specific to the object Examples of properties include e Instance name required e Enabled disabled switch e Parent object to which the instance is attached often a form e xy coordinates x and y positions on the terminal display e Color including color of background text border etc selected from drop down lists or the Select Color palette e Font selected from a drop down list e Bitmap image selected from a drop down list e Transparent true false You can edit property values by clicking the property you want to edit Many properties have a drop down list from which to choose a valid entry You may also type in a value Click s to group or ungroup the properties by category Click aj to toggle between sorting the properties alphabeti cally or by the order defined by the object s author Click T to show or hide the data type for each property You can close the Properties window by clicking the Close button EJ Normally however you will want to keep the Properties window open Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321
46. stop when that point is reached during simulation Then variable values as well as the flow of execution can be examined to determine the problem The following options are available on the Simulation View Tools menu and toolbar to help debug an application y ToggleBreakpoint lt F9 gt Select to set or remove a breakpoint Run lt F5 gt Select to continue running the simulation after it has paused or stopped rl Single Step lt F8 gt Select to execute the current line and stop on the next line Step Into lt F11 gt When you select this option if the current line con tains a function call the first executable line of the function is displayed in the code otherwise performs a single step a Step Out Of lt Shift gt lt F1 1 gt Select to execute the rest of the current function and return to the calling function Stops on the first exe cutable line outside of the function call If there is another breakpoint in the current function execution stops there Il Pause Execution lt Ctrl gt lt Break gt Select to stop execution at the next executable line of Qlarity code If no Qlarity code is executing 1 e the application is idle execution does not pause until after it has been started by an event such as a screen touch or time tick 3 10 4 Call Stack Window The Call Stack window displays the line number and the object of the current function as well as that of all of its call OptoTerminal Ql
47. terminal is connected to an Ethernet port you will need to change it to a serial port to perform this function Do the following to download a new version of the Qlarity based terminal firmware 1 Select Download Application from the File menu 2 Click Induce Bootloader and an Inducing Boot loader message is displayed in the Results box After a time the following message is displayed Bootloader induction terminated Followed by the message NOTICE received command from host to enter bootloader Entering QSI Bootloader V1 014 3 Click Upgrade firmware to proceed and the follow ing dialog box is displayed Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Select firmware file to download Look in Firmware a G56 2 300 bin 8 G75 _mips_2 300 bin laa g55_ 201 3e bin a G75_xscale_2 300 bin laa 955_2100testl bin Z60_mips_2 300 bin 970_20138 bin laa G70_mips_2 300 bin laa G7O_xscale_2 300 bin Files of type Clarity firmware binary files bin Cancel WE 4 Select the firmware software file to be downloaded and click Open A progress graph tracks the download Messages in the Results box indicate whether the download was suc cessful When finished the new firmware version is shown in the Results box 25 Download application to unit Download p
48. the library s object icons Click Icon Foreground or Icon Background and a color palette is displayed A rectangle appears around the current foreground or background color Click a different color square to change the color then click OK 5 3 3 1 Edit Entry Click an object template entry in the Entry Name list to select 1t then click Edit Entry to edit the programming code of the selected object This function 1s only available for source type entries The object template is displayed in a text editor similar to Code View as shown below OT Library Entry DisplaySetting 2 File Edit Copyright 2004 OSI Corporation Permission is granted to copy distribute and modify this code provided that this copyright statement is preserved al IERIE library standard source Notes library standard source ToolMessages library basic source TextSupport library basic source StandardStyles library basic source ColorStyleMapSupport doc object DisplaySettingV2 The DisplaySetting object provides a simple method to set contrast and b using the touchscreen When this button is pressed and held the setting the button is released The change method override is also called Whether the object is displayed on the terminal dim enabled as boolean init enabled true func enabled nevval as boolean enabled newval Enable me enabled ispushed false waitingforsave false Ma Edit t
49. the undoc directive to suppress the documentation on other program elements such as global variables that are intended for internal use by a template undoc lt element type gt lt element name gt The undoc directive has the same syntax and supports the same lt element types gt as the doc directive You may also specify a documentation body for an item that uses the undoc directive While this body will never be displayed in the documentation it is a useful way to comment your code B 9 Property Flags You may use the flags directive to specify special flags meta data for a property flags is only valid after a doc prop directive The documentation flags are used by a few select data types in the Properties window of Qlarity Foundry to control how they are processed flags lt flag data gt lt flag data gt is interpreted by the Properties window based on the data type of the property flags directives must appear entirely on a single line The most common use of flags is to define the grid shown by the aggregate data type The aggregate data type Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 108 uses a flags directive to define the grid that is shown when editing the property The aggregate data type s flags directive uses the following format flags lt dialog title gt lt dialog Instruct ions gt lt column definition gt lt column definition gt lt column de
50. this location 6 Click or select Compile from the File menu to compile the workspace Any errors in the new source code are identified by messages in the Messages and Errors window If no errors are present the compiled workspace is returned to Layout View NOTE one message handler for each message You can include only one message handler with each mes sage type added to the Global Code section 9 5 3 2 Add a Global Message Handler in the Global Code Section Use the following method to enter a global message handler directly in the Globals section in the Code View window 1 Click the Code View tab 85 Click Globals in the Object Tree to open the Global Code section Any current global source code is dis played in the editor window On a blank line in the editor window outside of any other function declare a new function by typing the func keyword followed by the name of the function a left parenthesis the parameters of the new function and a right parenthesis If the function returns a value the right parenthesis should be followed by the key word returns and then the type of the returned value Indicate the end of the function with the endfunc keyword on its own line The parameters appear as new variable declarations see section 9 5 1 without the dim keyword Each parameter is separated from other parameters by a comma Since this is a message handler there are restrictions on
51. to for mat the code generated by Event Builder 8 4 4 Load Event Builder Sample Workspace A sample workspace eventbuilder qly containing events created with Event Builder is included with Qlarity Foundry You may find it helpful to load the sample work space and view examples of the objects events and actions that can be set up using Event Builder To open the sample workspace click Open and go to the folder Qlarity Foundry Samples Eventbuilder demo Select the file eventbuilder qly An image of the workspace 1s shown below OptoTerminal Qlarity Foundry User s Manual Event Builder Sample Demo Status The functions in the sample application are described in the following sections 8 4 4 1 Tank Demo The Tank Demo controls the level of liquid in a tank with a slider When the position of the slider in the Tank_Slider object changes 1t triggers the following actions e Transmits its current value out the serial port to a control ler that adds liquid to or drains liquid from a tank to achieve the required level e Changes the text label above the slider to the current value of the slider e Sets the fill level of the gauge In a real life situation the controller to which you transmit the value would start the process to fill or drain the tank and send a value back to the gauge to update it However in the sample simula tion the value is sent to the gauge directly e Plays a musical note when the s
52. type with each type representing a display element button or other function Properties and methods define what an object is and how it behaves Object types may take many forms and serve any number of purposes Object types fall into three categories container objects area objects and non drawable objects Object Hierarchy For the display it is the Z order or the order in which objects are layered For messaging it is the order in which objects are prioritized The top object in the object hierar chy receives the highest messaging and display priority 1 e it is on top of other objects However any enabled objects regardless of their position in the hierarchy may receive or send messages You can manipulate the position of an object in the hierarchy with API functions Each con tainer including the root container maintains a list of objects attached to it its children The order of objects on this list indicates the Z ordering of objects from front to back The Z ordering may also be manipulated at runtime using the Z order primitive API functions Object Instance An occurrence of an object in a user application An object instance is defined by the object template on which the object is based Each object maintains its own properties and may contain code for method overrides Object Template The programming code that defines an object Each object instance in a user application is based on a template Obje
53. under the Templates heading Only object templates created in the workspace are listed under this heading OptoTerminal Qlarity Foundry User s Manual To add a library to or remove a library from a workspace click My on the toolbar or select Edit Libraries on the Edit menu A dialog box similar to the following is displayed Edit Library Remove library Create new library Add existing library Edit Natives Close Filename Status loaded v1 00 loaded v1 00 ExExceptionDisplay loaded v1 00 ExRadioCheck1 loaded sys1 20 common loaded sys1 20 progobis exangletext lib exexceptiondisplay lib exradiocheck lib common lib progobjs lib Entries Templates Ex naleT ext Source Ex naleT ext Click Add Library to add a new library to the workspace Click Remove Library to remove the selected library For additional information on libraries refer to section 5 3 8 1 5 1 Libraries Provided with Qlarity Foundry Qlarity Foundry includes libraries of object templates that allow you to create interactive complex user applications without entering any programming code After you add one or more of these libraries to a workspace you can change the object properties to customize the object instances in your user application Two of the libraries provided with Qlarity Foundry that are used at the basic design level are e Basic library basic qlib e Data Processing library dataproc qlib Thes
54. workspace and the coordinates at which the mouse pointer is positioned in the work area Also if you position the mouse pointer over an option on a menu or a tool on the toolbar the function of the option or tool is displayed in the status bar 3 4 Menu Options The following sections describe the options available on each menu on the menu bar 3 4 1 File Menu New Workspace Use this option to start a new workspace Refer to section 4 1 for information Open Workspace Use this option to open an existing workspace Refer to section 4 2 for information Close Workspace Select this option to close the current workspace and open a new workspace Save Workspace Use this option to save the current workspace Refer to section 4 4 for information Save Workspace As Select this option to save a copy of the current workspace to a different file name The Save As dialog box is displayed Enter the new file name the extension is added automati cally and click Save Collect for Output Use this option to transfer a workspace to another computer See section 4 4 3 for information Compile Layout and Code View only Use this option to compile the current workspace into the format required for a user application A workspace must also be compiled to properly display in Layout View Refer to section 4 5 for information on compiling a workspace Generate BFF File Layout and Code View only You can download a user application tha
55. workspace is a file created in Qlarity Foundry that you will compile into a user application In Qlarity Foundry you use the workspace to define functions for the terminal at the Qlarity based terminal you use the user application to perform the functions When Qlarity Foundry starts a dialog box appears so you can open a workspace g Welcome to Qlarity Foundry Recent Files C Program Files 0 pto22 Q larity Foundry S amples D emo gr Odemo gly Open Selected Open Other File Start Hew Begin editing in Layout View Tutorials Open Selected Recently opened files if any are listed To open a recent file click the file name to select it then click Open Selected or double click the file name The workspace is opened in the main window Only one workspace at a time can be open in Qlarity Foundry Open Other File Click Open Other File and the Open dialog box appears showing workspaces in the default folder Use the Windows tools to change folders if necessary Click a file to select it then click Open The workspace is opened in the main window see next page Start New To start a new workspace click Start New The New Qlarity Project dialog box appears Refer to section 4 1 Start a New Workspace for information Tutorials Click Tutorials to open a sample workspace and to start a tutorial to help you learn the basics of Qlarity Foundry The Object Documentation Help file is opened with
56. 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual 6 3 8 1 Functions and Methods Use this option to set the level of help offered when writing a function or method call The following options are avail able None AutoHelp will not automatically appear when writing func tion or method calls Standard AutoHelp will attempt to appear whenever it seems likely that you are going to edit a function or method call High AutoHelp will attempt to appear when you position the cur sor in a function call 6 3 8 2 Identifier Completion Use this option to set the level of help offered when refer encing methods or properties of an object The following options are available None AutoHelp will not offer identifier completion assistance Standard AutoHelp will appear when it seems likely that you are ref erencing an object property or method In general this means after you type an object name and type in the dot operator High AutoHelp will attempt to appear any time the cursor is over an object property or method that is referenced via the dot operator 6 3 8 3 Assignment and Parameters Use this option to set the level of help offered when editing the right hand side of an assignment statement or entering parameters in a function call Some information is drawn from the last time the workspace was compiled Data types that have been added or changed since the last compile may not be available The followin
57. 4 If disabled the default event edi tor is Code View In Layout View double click an object that supports events to launch the default event editor 6 3 8 AutoHelp Settings The AutoHelp feature assists you in writing Qlarity source code If specific settings are enabled while writing code in Code View pop up lists are displayed from which you can make selections Click AutoHelp Settings to set up or dis able the AutoHelp options AutoHelp Settings Ea Functions and Methods Assignment and Parameters uses the resulte of the most recent compile to Standard determine possible values If you have modified pour source code since the last Assignment and Parameters Standard compile or if the last compile had errors it is M Show global variables and functions ieee the listed values may be Identifier Completion T Show object properties and methods T Show for built in data types ou map elect to fade SutoHelp bubbles as the mouse moves near obscured code to allow you to look at your source code as well as use the AutoHelp 4 Fade AutoHelp tips Cancel NOTE AutoHelp is an aid only AutoHelp is designed only to be an aid in code develop ment It may not be available in some circumstances and the information that it contains may be out of date or in an improper context Using AutoHelp is no substitute for good programming practices Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800
58. 6786 MANUAL CONVENTIONS Within Qlarity Foundry functions can be selected using a mouse a keyboard shortcut or an icon on a toolbar The following conventions are used to identify selections in this manual When instructed to press a specific key it is shown in a bold sans serif typeface and is lt Enter gt enclosed in angle brackets When instructed to press a key and hold it down while typing another key the keys are lt CTRL gt lt V gt shown together When instructed to click a button or icon it is shown in a bold sans serif typeface and is OK enclosed in square brackets Icons on toolbars are represented graphically When instructed to type a character or a word it is shown in the Courier typeface Directory paths file names and file name extensions are indicated by italics Syntax commands and examples are shown in the Courier typeface Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CONTENTS CHAPTER 1 INTRODUCTION coria A A AAA AAA A 1 Me lo o co Use Tus Vata Ue ines ines A A OE OE CESE A EE nuaaahaaniien l 12 DESCA DUO aa a a a A cesawtiuauan need ue aeons l CHAPTER 2 INSTALLATION A anaa easa eaa 3 ZV SS CET CUTE MOS AAA E E Eds 3 A A A AAA A A a cece Oa escuela da es irae Susie ea ouanwuuaiids 3 CHAPTER 3 GETTING STARTED oi desdesocasdcnansussyausdevecavacedeuncoeesheuteuyessuadedsustssesvusensUeesdunssevesteseonabescaene 5 De Start Ola TN AS AA AAA AA A E eco nua
59. 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 li OptoTerminal Qlarity Foundry User s Manual WORKSPACES sivisstai ii A apesvadessncuuesdonendeavsueeuatesustoaeenestunces 23 dele Sarra New WV OF RSD ACG oda tots iio iaisid 23 4 2 Open a WOrkSpat Cesise E AA 24 BD Close a WorkSpace erinrar a a EEE a EEEE EEE 25 J Savea Works pat n e a A 25 Aral Save ls seeaiek a ecce case E se olde Gesoeiaa ai aracnctided cen ie det eucenede Hawes sede tcarescencaeseea ys 25 A AnD Save OW OLKS DAC CAINS A ida 25 AAD CONECTE OUMU e a e ii 25 40 Compile a Workspace sossarna A T 26 AO Gre NC Ee BEF E ie eE a a T E 26 CHAPTER 5 ILEMPLATES RESOURCES AND LIBRARIES o iaa 27 Bl IC E T e pae eaa a E a ON 21 Saal Add a Now Object Templates iia 2 JEZ Edta Templie ICON saae a e ea a E 28 Jl Remme a Template triada i 29 dl Remove a Lempa cio 29 LS Send Templie OLDA a a a oido 29 ILO Gage Lemp PO curiosa EE 29 IF Erenda Template lin a 30 De Edi RESO UNC rs dicto d dilo oia 30 Zl Ada RESOU n a id iia 31 ENS WINGS OME COS tato it 31 290 Rename a RESOULCE nati dd le ai iria 31 D2 1G Man Cera ESO UIC le lcd ena 32 a Remove a RESOU Eero r E a a a A ada 32 TA EE PIANO PA EAE A ee A E A E E EE EE ATO os EIE E PE EE E aad A E ET 32 FA FONS a E 32 PA EPAL e iO PEE RATE IOANE Sage dite A ocala sors acetic EA daton sense neat eas apse ne ae aap cae AE A E T 33 PP E adauaneaaiecucease eaeneeewutee tees 33 IA 33 ol Add Esto LIDA Yersen ais 33 AN M
60. 9 5 1 Add a Global Variable to a Workspace A global variable is a variable that is declared in the Global Code section outside of any object There are two methods for adding a global variable e Use the New Variable option in Code View easiest method e Enter the variable directly into the Global Code section in the Code View window 9 5 1 1 Add a Global Variable Using New Variable Do the following to add a global variable using the New Variable option 1 Click the Code View tab 2 Click Globals in the Object Tree to open the Global Code section Any current global source code is dis played in the editor window 3 If you want the new variable inserted at a cursor loca tion select Insert at Cursor then click in the editor at the location where you want the variable inserted If you do not select this option the variable will be added to the bottom of the Global Code section 83 4 Click New Variable This button is only available when the Globals section is selected The following dialog box is displayed New Yariable Property E x Name Data Type M Create validation function Initial alue optional default Properties Window category optional PEA O Documentation optional 5 Inthe Name text box enter a name for the variable 6 In the Data Type text box enter the variable s data type 7 Select Create Validation Function if you want Qla
61. API to modify the behavior of workspace objects in Simulation View based on the display orientation of the target terminal Most users should select Landscape or Portrait Display Type Select one of the following options from the drop down list to indicate the type of display on your terminal Color Color TFT Color Enhanced TFT Grayscale Transflec tive or Grayscale Transmissive The Color TFT and Color Enhanced TFT options can be used by advanced programmers in conjunction with the GetHardwareInfo API to modify the behavior of work space objects in Simulation View based on the display type of the target terminal If you are not sure which type of color display you have select Color Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 44 If you select Grayscale Transflective the default color theme is dark text and borders on a light background If you select Grayscale Transmissive the default color theme is light text and borders on a dark background Refer to section 5 4 1 Themes for information on selecting and modifying a color theme If you are not sure which type of grayscale display you have select Grayscale Transflec tive Audio Decoder If the terminal has the audio decoder option which allows it to play waveform audio files you can select this option to enable it Ethernet If the terminal has an Ethernet port and you will be using it for communication select this
62. Application A user created program that controls the Qlarity based ter minal A user application interacts with the terminal s sys tem software firmware to define and control the terminal s display touch screen speaker and input output actions Validation Method An object method that is implicitly called when the object property of the same name is assigned a value Although the name validation implies that the function is used to validate the value before it is assigned to the property the validation method may be used for any purpose This is a powerful feature of Qlarity because it allows object behavior to be controlled solely by manipulating the object properties Workspace A file created in Qlarity Foundry that contains Qlarity pro gramming code and data for a user application You use Qlarity Foundry to compile the workspace file into a user application and to download the user application to the Qlarity based terminal You can create any number of workspaces Z Order The order in which objects are layered The order of objects in the Object Tree indicates the Z ordering of objects from front to back The Z ordering may also be manipulated at runtime using the Z order primitive API functions Also see Object Hierarchy Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 APPENDIX B AUTODOC SPECIFICATION AutoDoc is Qlarity meta data that automatically documents source code in a work
63. Browse to select a different folder or create a new folder in which to install Qlarity Foundry Click Next to con tinue The following window appears After all of the files are copied to your hard disk the following window appears InstallShield Wizard Setup Type Choose the setup type that best suits your needs oO P T oO z 2 Expect more Get more Do more InstallShield Wizard Click the type of Setup you prefer InstallShield Wizard Complete Description Install the features commonly required for Qlarity Foundry for Opto 22 version 2 50 The application and help files will be installed az well as some sample Setup has finished installing Qlanty Foundry for Opto 2 version 2 50 on your computer OPTO 22 Phone 951 695 3080 programs and basic tutorials Toll free in the USA 800 835 6786 Email support pto4 com www opto22 com 7 Click each type of system setup to read a description of the files that are installed Then select the type of setup that best suits your needs Complete Custom Mini Click Finish Installation is complete mal or Typical Click Next to continue If you Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 3 GETTING STARTED 3 1 Start Qlarity Foundry To start Qlarity Foundry click Start then click Programs and select QSI Corporation Click Launch Qlarity Foundry to start the program 3 2 Open a Workspace A
64. CORPORATION FOR THE GLARITY FOUNDRY SOFTWARE ACCOMPANYING THIS EULA WHICH INCLUDES COMPUTER SOFTWARE SAMPLE OBJECTS AND MAY INCLUDE Do vou accept all the terme of the preceding License Agreement IF you choose No the setup will close To install Qlarity Foundry for Opto 22 version 2 50 you must accept this agreement Ho Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 4 OptoTerminal Qlarity Foundry User s Manual 5 Read the agreement and click Yes if you accept the selected Custom a dialog box appears for you to terms The following window appears select the files and features you want to install The Setup Status window appears and displays the sta tus of the installation as each file is installed in the specified destination folder InstallShield Wizard ES Choose Destination Location cD P T oO rp rp Select folder where Setup will install files Expect more Get more Do more Setup will install Qlarity Foundry for Opto 22 version 2 50 in the following folder InstallShield Wizard To install to this folder click Next To install to a different folder click Browse and select another folder Setup Status OPTO 22 Expect more Get more Do more Glarty Foundry for Opto 22 version 2 50 Setup is performing the requested operations Destination Folder Validating install re C Program Files O pto22 Q larity Foundry 6 Accept the destination folder shown or click
65. Code View Descriptions The Event Builder dialog box contains the action table that lists all actions assigned to the selected event and the action configuration that contains options to set up each action O Event Builder ListBox SelChanged event A AA Set Property Set Tachometer s value property to selected 1 Action Table Action Configuration m Property to Set Set to this Value Object Tachometer y C Use the value of this object property Obiect Cancel Property saus y ES Globals Property py Edit in Code View X Descriptions Use this explicit value selected 1 gt Set an object property Use this action to set an object property or a global variable You can either set it to a specific value or copy the value of another property or variable Action Table The action table lists all actions configured for the selected event Each action is on a separate line in the table To modify an existing action click the action in the table To add a new action click the last line in the table labeled Click to add action and select the action from the drop down list Then modify or set up the selected action in the action configuration area Action Configuration After you select an action in the action table applicable options are displayed in the action configuration area to set up the action 71 Click OK to accept the event as curre
66. E B e El doc override animationDone func AnimationDone i validation method provide functionality for property changes The illustration above shows a portion of an example of the boilerplate code provided by QSI as an optional starting point when creating a new object template For example the enabled property is common to all The boilerplate code included in a new template depends on the type of object being created 1 e non drawable area object or container The purpose of the boilerplate code is to provide a set of properties and methods found in a typical object of the selected type It also provides fully functional tool methods The source code is well documented and serves as an example of a working Qlarity object Each property is defined as follows descriptive comment describe the property dim statement create the property init statement assign a default value objects and appears in the boilerplate code for any type of template The code that defines the property is as follows Whether the object is displayed on the gt terminal dim enabled as boolean init enabled true func enabled newval as boolean enabled newval Enable me enabled endfunc The comment describes the purpose of the property The dim statement creates a boolean property named enabled The init statement assigns a default value of Opto 22 Fax 800 832 OPTO 6786 Web www opto22
67. Edit Templates and to Chapter 10 Advanced Design for information on creating templates Edit Resources Use this option to open the Qlarity Resources dialog box to add resources to or remove them from the workspace Refer to section 5 2 Edit Resources for information Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Edit Libraries Use this option to open the Libraries dialog box to add libraries to or remove libraries from the workspace Refer to section 5 3 for information Edit Named Colors Layout View only Select this option to define named colors You assign named colors to objects to specify the object s background and foreground colors Refer to section 5 4 for information Edit Named Borders Layout View only Select this option to define named borders You assign named borders to objects to specify border attributes Refer to section 5 5 for information 3 4 3 View Menu Toolbar Select this option to show or hide the toolbar Refer to section 3 5 for information Status Bar Select this option to show or hide the status bar at the bot tom of the main window Misc Bar Select this option to show or hide the Layout Scale Outline All Objects and Theme functions next to the toolbar Refer to section 3 6 for information Messages and Errors Select this option to show or hide the Messages and Errors window wh
68. Instance The Instance Properties dialog box is opened All available objects are listed in the drop down list at the Type field as shown below Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 66 Instance Properties Ea Mame Newlnstancet ES LaserPolygon Pa EimapButtor2 Button z CheckBox2 EH DataGridw2 H DropDownList El EditBoww2 A ExceptionDisplayy E 3 At the Name field type a name for the new object type over the default name Each object in the work space must have a unique name An object name has no size limitation but must start with a letter A name can not contain spaces but may use the underline character _ The percent pound and dollar sign symbols can be used at the end of the name 4 At the Type field click the drop down list and select the type of object that you want to add After you select an object it is added to the work area at its default loca tion and is listed in the Object Tree The newly added object remains selected and its properties are displayed You can edit the properties as required 8 3 2 Move Resize and Reorder Objects To select an object to move resize or reorder click on it The selected object is outlined with a colored box You can only select one object at a time You cannot move or resize a locked object Press lt Tab gt to move forward from object to object in Z order Press l
69. Libraries branches in the Object Tree and to make the sections available in the editor window click on the toolbar or select Settings from the Tools menu or press lt F12 gt click the Editor tab and select the Show advanced code sections in the Object Tree option 10 1 1 Advanced Code The Advanced Code section is intended for advanced users that need more control over how Qlarity code is handled by Qlarity Foundry Code written in this area is treated as if it were written using a basic text editor rather than Qlarity Foundry Qlarity Foundry does not interact with any code authored in this section Normally Qlarity Foundry moni tors the code that you type in Code View When you type an advanced code construct such as a declare or define state ment Qlarity Foundry performs the action that you typed e g if you type in a define statement Qlarity Foundry removes the define statement and creates an object tem plate In the Advanced Code section this monitoring is dis abled and you can type in advanced code constructs without interference If you use the declare statement to create an object the object will be created and displayed in the Layout and Sim ulation Views but will not appear in the Object Tree nor will it have resize grips 10 1 2 Libraries The Libraries section allows an advanced user to view and debug code in the included libraries It is recommended that you do not edit QSI provided libraries By de
70. OPTO 6786 20 3 12 Object Palette The Object Palette contains a tab for each library in the workspace as well as an All tab and an Other tab Each tab has icons for all of the object templates in the library Click a tab to select an object from the specified library The All tab contains icons for all objects available to the workspace from all of the libraries in the workspace The background color of each icon identifies the library in which the object can be found The Other tab contains objects from various small libraries For more information on object libraries refer to section 5 3 Edit Libraries Move the mouse pointer over an icon to display the object s name and description Click to place the mouse pointer in select mode In this mode click an existing object to select it The pointer remains in select mode until you click a different icon Click to place the mouse pointer in scroll mode If the layout scale is larger than the work area use the scroll mode to view the parts of the workspace that are not visible Click EJ then click anywhere in the work area and hold the mouse button as you drag in the direction you want to view When the section you want to view is visible release the mouse button The pointer remains in scroll mode until you click a different icon or exit the workspace You can close the Object Palette by clicking the Close but ton fy or you can show or h
71. OPTOTERMINAL QLARITY FOUNDRY USER S MANUAL REVISION 2 5 Opto 22 43044 Business Park Drive Temecula CA 92590 3614 USA Phone 800 321 OPTO 6786 or 951 695 3000 Fax 800 8320PTO 6786 or 951 695 2712 Email sales O opto22 com www opto22 com Manual 0059 01 Opto 22 form 1344 070321 6345E1 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 G55 Z60 Qlarity and Qlarity Foundry are trademarks of QSI Corpora tion OptoTerminal is a trademark of Opto 22 Microsoft Windows Windows NT Windows 2000 Windows XP and their respective logos are trademarks or registered trademarks of Microsoft Corporation in the United States and other countries Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 FOREWORD Qlarity Foundry is a Windows based design tool that uses the Qlarity programming language to help you design user applications for a Qlarity based terminal Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7 Chapter 8 Chapter 9 Chapter 10 Appendix A Appendix B Introduction This chapter explains how to use this manual to get t
72. OV KIDE A II a E tac teiaelcet eit teers 34 O 34 E A A e o 5 In A 35 dz Rename Ena aca 35 dol REMO Ve LA lil ias 35 o 6 EMERY Voros eene E S O 35 SA A e a eE a 35 IIA AVANCE PP a E a a a a a A N 36 del Aa EERE ita 36 555 42 Edt Core core Ub qdo aia 37 5 3 4 3 System Libraries That Are Not Explicitly Included in This Workspace ccccccccccccceeeeeeeeeeeees 37 NI CLC Abe ra INOW LITA anida iii 37 A e cit Nant RPE N 38 IAr THEMES sasha was A A N i 38 DA TES O II II cate necte II A det iocs 39 34 2 1 Change Named Color eko aie die 39 9422 Create NEW Named Cola lidia 39 94 2 3 Delete Named Color Sa 39 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual FAA Rename Named CO A 39 34 2 5 Reset Color to Theme Detalla ti A aii 39 O Edt Named BO io 39 A A E o POE E O EEE eke 40 LN amed Bordes sa 40 SAN EN Ea fia PS CUS PO O o E UP RT ROO II O O Nh estseges 40 Li OUNAE COM oda 41 O LOUD le BOE iii aia Atico 41 IOA A A A a Soncueasau A N 41 35 2 0 Create New Named DOTA lat 41 5552 0 Delete Named BO daa 41 Ir Rename Nain DOE acta 41 5552270 Reset Borderto Delta di 41 CHAPTER 6 OLARY FOUNDRY PP REFERENCES aa eS Ad AA E 43 A a 0 O oa galt cease adideeis dco Sica wa e a a enced satu E N 43 CRE MOS VAY SC UU Bsc scat O e ltteers 43 A A ted eae de ened ii E E O ean 44 LS COMUNICAMOS dali 44 0 1 4 Miscelaneos id 44 O A eepotes bees Ste ce se ee age
73. TOGGLE 3 Like the param directive you may also embed link and importdoc directives in the item directive See section B 5 Function Parameters for an example B 7 Grouping Items Occasionally you may document several related items such as a suite of related functions or objects If you want the user to see which items are related and be able to easily nav igate from one item to another use groups Start by docu menting the group itself using the doc group lt group name gt directive and add any descriptive body Next add the group directive to each related item in the group group lt group name gt 107 Where lt group name gt is the same name used in the doc group directive There may be any number of documenta tion elements in a group and a single documentation ele ment may belong to more than one group doc group extended drawing functions These functions draw to the display doc func DecoratedCircle group extended drawing functions documentation as appropriate doc func TransformAndDraw group extended drawing functions group transformation functions documentation as appropriate B 8 Hiding Documentation AutoDoc will generally not display documentation informa tion on program elements that are not intended for general use This includes private methods and properties hidden variables validation functions and a few other unusual constructs Sometimes you may wish to use
74. These include drawing naviga tion keyboard and data communication and protocol objects required in all workspaces This workspace also includes default resources to communicate to Opto 22 prod ucts either through a PAC Control strategy 10Control strat egy or memory map location An OptoPACComm object is included in the workspace by default Configure this object to communicate with the Opto 22 controller PAC Control or ioControl communication only This option includes the Opto22 ioControl library Opto_ioControl lib the Basic library basic qlib and the Extra library extra qlib These include drawing naviga tion keyboard and data communication and protocol objects required in all workspaces This workspace also includes default resources to communicate to Opto 22 prod ucts through a PAC Control or ioControl strategy An 10ControlComm object is included in the workspace by default Configure this object to communicate with the Opto 22 controller OptoMMP communication only This option includes the Opto 22 library Opto22_1394 lib the Basic library basic qlib and the Extra library extra qlib These include drawing navigation keyboard and data communication and protocol objects required in all workspaces This workspace also includes default resources to communicate to Opto 22 products through memory map addresses An Opto22_Comm object is included in the workspace by default Configure this object to communi cat
75. To open a workspace click E on the toolbar or select Open Workspace from the File menu The following dia log box is displayed Select workspace to open 22222 workspace to open ax Look in C Olarity Foundry e f amp EE Ej J AppHelp L AutoDoc L auxsupport 3 bdf fonts Ez documentation Firmware L Samples Samples old hvac sample J tutorials OSI Corporation uan File name f y My Computer Files of type larity files qly y Cancel Workspace files have a gly extension All workspace files in the default folder are listed change folders if necessary Click a file to select 1t and 1ts name 1s displayed in the File name field Click Open to open the workspace You can also double click a file name to open it If you select a workspace that is open in another instance of Qlarity Foundry on the same computer a warning appears indicating that the workspace is in use If you want to save the workspace you will have to save it with a different name select Save Workspace As from the File menu to ensure that no data is overwritten 4 3 Close a Workspace Select Close Workspace from the File menu to close the current workspace and start a new workspace The follow ing prompt appears Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Qlarity Foundry xj 2 Save changes to Mew Workspace 9 coe Click Yes if yo
76. _slider 2 In the Properties window click the Events tab All events associated with the object are shown For exam ple the Tank_slider object in eventbuilder qly has one event Change 3 Click next to the event to open the Event Builder dialog box The action table lists all actions that have been configured for the event Action Description Serial Transmit Transmit Sends tank level out COM1 to your controller out COM1 2 Set Property Set Slider_label s caption property to Str T ank_slider value 5 et Property E et Tank_gauge s value property toT ank_slider value ME Play Note Play note 43 for 12 ms Ea Click to add action v Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 72 The last line of the action table always contains a drop down list that you use to add a new action to the event 4 Click anywhere on the line to open the drop down list and select an action The action and its description are added to the table If you want to add a new action in the middle of the table or remove an action from the table right click in the action line A shortcut menu is displayed with options to insert or remove actions 5 Refer to the next section for information on each type of action and how to configure them 8 4 3 2 Configure Actions The action drop down list contains the following actions e Show Screen e Enable Disable Object e Set Property e
77. a container object e g tab screen etc to your work area and then place new objects inside the container the objects automatically become children of the parent container object If an object is not placed inside a container object it is linked to the root container by default When you collapse the Object Tree you can quickly iden tify all objects in the root container In the following illus tration the first two objects EZBackButton_1 and EZBackButton_2 are area objects that have been placed in the root container The next to EZScreen_3 EZScreen_1 and EZScreen_2 indicate that they are container objects with other objects in them parents with children Object Tree aja Globals ER gt ai Ethernet oby iat ai backlight down iat ai backlight_up iat ai Contrast down ai Contrast_up ES a ai Ev_enable_ecreent 252 af SeralCom2 Th a senalComt TP 2 af MainScreen iat ai Tab_diagnostic e al Tab EZ obj Click next to a parent container object to see its chil dren as shown below Object Tree Ela Globals EAS af Ethernet_obj a ai backlight_dowrn yf backlight_up 2 yf Contrast_down 2 af Contrast_up za a ai Ev enable _screent TH af SeralCom2 Th gt ai SeralCom E la i af MainS creen Se a y ev_disable_scrm af diag_key 2 af EZ obj key a a MainBackground Era i Tab_diagnostic Ars y DisplayT ab af backlight_downlbl af backlight_uplbl B d Contrast _uplbl B ai Contras
78. a theme in which the specified style is not defined and you do not specify a style assignment for that theme Qlarity Foundry uses the first specified lt style assignment gt lt style assignment gt has the following syntax lt theme name gt lt value gt lt theme name gt represents the name of a theme such as standard or grayscale_light lt value gt is a border style value Sstylemap Bdr_ButtonBorder standard 0x00052025 classic 0x1c022001 Sstylemap Bdr_LabelBorder standard 331783 classic 0 109 stylemap directives are standalone directives and not part of any other doc directive These directives may not be broken over multiple lines B 14 Defining Named Colors You can use the colormap directive to specify a new named color element for an object colormap lt color name gt lt color assignment gt lt color assignment gt lt color assignment gt Where lt color name gt is a valid Qlarity identifier name that names the color Each lt color assignment gt defines the color for a specific theme If the user selects a theme in which the specified color is not defined and the directive does not specify a color assignment for that theme Qlarity Foundry uses the first specified lt color assignment gt lt color assign ment gt has the following syntax lt theme name gt lt value gt lt theme name gt represents the name of a theme such as standard or graysca
79. ace to create a user appli cation For information on adding opening and saving a workspace refer to Chapter 4 Workspaces 8 3 1 Add an Object Instance You can add object instances to your workspace from the Object Palette or from the Object Tree shortcut menu as explained in the following sections 8 3 1 1 Add an Object From the Object Palette The Object Palette contains a tab for each library in the workspace as well as an All tab and an Other tab Each tab has icons for all of the object templates in the library Click a tab to select an object from the specified library The All tab contains icons for all objects available to the workspace from all of the libraries in the workspace The background color of each icon identifies the library in which the object can be found The Other tab contains objects from various small libraries Refer to section 3 12 for more information on the Object Palette Do the following to add an object instance from the palette 1 Click the icon of the object you want to add 2 Move the mouse pointer to the work area The pointer changes to a cross hair 65 3 Click and hold the mouse button and drag the mouse to draw a rectangle in the work area then release the mouse button Some objects have a default starting size and shape so the size of the rectangle doesn t matter only its posi tion in the work area The size of other objects such as a line or rectangle is initial
80. ake it possi ble to find a location quickly which is useful in objects with several lines of code Click to open the Add Edit Templates dialog box to add or edit an object template Refer to section 5 1 Add Edit Templates and to Chapter 10 Advanced Design for information on creating templates Click to open the Edit Resources dialog box to add resources to or remove them from the workspace Refer to section 5 2 Edit Resources for informa tion Pa fm Click to open the Libraries dialog box to add libraries to or remove libraries from the workspace Refer to section 5 3 for information Click to open the Qlarity Foundry Preferences dialog box to define the Qlarity based terminal s configura tion and to enter Qlarity Foundry preferences Qlarity Foundry attempts to simulate the terminal s display area input type and so on as closely as possible Refer to Chapter 6 Qlarity Foundry Preferences for information Click to identify the version of Qlarity Foundry you are running 3 5 3 Simulation View Toolbar Deh taaan Ly Click to start a new workspace Refer to section 4 1 for information Click to open an existing workspace Refer to section 4 2 for information E E Click to save the current workspace Refer to section 4 4 for information Click to identify the version of Qlarity Foundry you are running Click to set or remove a breakpoint while running a simulation 13
81. alse enabled true font default keyfont default keypteize 10 maxlength 50 pleize 10 shiftstyle qpk_capslock_shitt value default Click an object in the work area or click its object name in the Object Tree to display its properties If the Properties window is not displayed pull down the View menu and click Properties Window NOTE more than one object selected If more than one object is selected only those properties that are common to all selected objects are shown in the Properties window If the same value is assigned to a prop erty for all selected objects that value is displayed If the selected objects have different values for the same property lt multiple values gt appears in grayed text In either case setting a value in the Properties window when more than one object is selected sets the property in all selected objects to the new value Properties are the data in an object instance They are grouped into categories to help you find and edit a defined property Properties are normally grouped into the follow ing categories Main Contains properties that you must set to use the object These might include enabling the status of the object or the object s current value 19 Border and Color Contains properties that set the appearance of the object General Contains properties that are required by the object but are rarely set in the Properties window These might include the position and
82. amming language Events created with Event Builder generate Qlarity program code This means that 1t is possible to develop events in Event Builder and then add advanced functionality in Code View It 1s also useful if you are learning the Qlarity programming lan guage to create events using Event Builder and then study the program code generated If you modify an event in Code View and later open the event in Event Builder your changes are reflected 8 4 6 Troubleshooting If you make a mistake while configuring an action an error message 1s displayed in red in the Description column of the action table Description Missing source property IEMe an Male c nee weg Am ge If any error messages are shown you will be unable to click OK to save and exit the dialog box In some cases Qlarity 75 Foundry may not detect the error until you click OK In those cases Event Builder remains open for you to correct the error After you correct the error click OK again If there are no more errors Event Builder closes and the event 1s configured If you cannot or do not want to correct the error click Cancel Event Builder closes and any changes you made are not saved Advanced users may click Edit in Code View to edit the object template code to correct any errors Errors must be corrected in Code View before you can exit or switch back to Layout View 8 5 Communication Objects The Common library common lib
83. anual amp Al T x Object Properties Properties Events NavFun Border and Color General HavEcreer 5 113 70 25 false note_usedetauit Main enabled true default_bdf 10 Fun valueon checked false _orb_button b Misc ww Text Settings inzet 2 inset fi 4 hjustify center justify center Note that the properties are grouped by category Click the name of a category to open or close the list of properties in the category Refer to section 3 11 for a description of each category The first column lists the name of each property Property names are defined in the object template The middle col umn optionally displayed see section 6 2 Layout lists the data type of each property for information only The property settings which you can change are listed in the third column Click the property that you want to change Enter the new property setting in the third column You can enter new property settings by typing the new information type over the default setting or by selecting from a drop down list or dialog box In the following illustration the property ezimage 1s selected This is the name of the bitmap image used in the object instance The drop down list shows all bitmap images available for use in the object instance A different image can be selected by clicking it Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786
84. ardware User s Manual for Power On Setup instructions NOTE if you cannot access the terminal If you cannot access the Qlarity based terminal use the Induce Bootloader function refer to section 7 4 4 for information 7 4 3 Download New Firmware Do the following to download a new version of the Qlarity based firmware 1 Select Download Application from the File menu and the Download dialog box is displayed 2 Click Upgrade firmware to proceed and the follow ing dialog box is displayed OptoTerminal Qlarity Foundry User s Manual Select firmware file to download Look in Firmware a G56 2 300 bin 8 G75 _mips_2 300 bin laa g55_ 201 3e bin a G75_xscale_2 300 bin laa 955_2100testl bin Z60_mips_2 300 bin sa 970_2013e bin laa G70_mips_2 300 bin laa G770_xscale_2 300 bin File name A Files of type Clarity firmware binary files bin Cancel We 3 Select the firmware upgrade file to be downloaded and click Open A progress graph tracks the download Messages in the Results box indicate whether the download was suc cessful When finished the new firmware version is shown in the Results box 7 4 4 Induce Bootloader If the firmware on your Qlarity based terminal has become corrupt and you cannot run the Power On Setup utility use the Induce Bootloader function to upgrade or reinstall the firmware NOTE Ethernet connection If your
85. arent is passed to the handler as a parameter In most cases the handler should merely call the Attach API func tion to request attachment to the new parent This is what the boilerplate code does If the object has restrictions on where it can be attached or what types of objects can serve as its parent code should be added to the handler to enforce the restrictions For exam ple the Tabs object in the QSI Common object library can only attach to a Tab Container object The MSG_TOOL_ATTACH handler for the Tabs object enforces this restriction After a requested attach is complete the attached object receives a MSG_TOOL_ ATTACHED message from Qlarity Foundry An objref referencing the new parent is passed to the handler as a parameter This provides an opportunity for the object to update its parent property after the attach has been completed successfully The new parent may be different from the parent that was passed to the Attach API function in the MSG_TOOL_ATTACH handler Also note that the boilerplate handler calls the Tool_Persist API function after the parent property has been updated The Tool_Persist function should be called after any property update in a tool message handler The last handler included in the non drawable boilerplate code is the MSG_TOOL_DRAGCREATE handler When an object instance is created by selecting the template on the Object Palette and dragging it into the Layout View display the ob
86. arity Foundry User s Manual ers Select Call Stack from the View menu to display the Call Stack window Call Stack E MSG_TIMETICE setalarm Global Section line 156 This window only displays information when execution has paused or stopped at a breakpoint By default the call stack 1s not displayed 3 10 5 Watch Window The Watch window allows you to monitor the value of any workspace variables To display the Watch window select Watch Window from the View menu or press lt Ctrl gt 9 i Mt ate h win d Oa Sm 1 Eg GetTime lt Wariable not Found gt rowe tue Type the name of the desired variables in the Name col umn When execution has paused or stopped at a break point the variables values are shown If execution is not within the scope of the variable no value is displayed Click T to show or hide the data type for each variable 3 11 Properties Window The Properties window displays the properties of the selected object instance An example of a keypad object is shown below Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Object Properties Sal Ti Properties Events name LiwerlyRevpad 1 Border and Color Y General height Bb Inactive false parent viewtopleft note_usedetault e tone_error note_usedetalt width 134 pog A ppoz A autoclear false autohide f
87. assascobecdscascesecdddecneenss 103 APPENDIX B Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 vi OptoTerminal Qlarity Foundry User s Manual AUTODOE SPECIBICA TION N cui E E E O 105 Bl Documentation Dec aration art tddi 105 B 22 Documentation BO inicia 105 A PE CO PEE N A semen nttaceered 105 BAe Mrmr ems a ads 106 Bo Funcion Ear amele Sasana ic 106 B0 Data Type Elemen Sarrea a E E 107 o O II aN 107 B S Hidins DoctmentaO Mita dias 107 BO A O O PO A scene eae neeattseseaes etna asen tenant miata acto 107 B10 Sample Cod aso aan aed cs seco ata a E E aeaceaaneees 108 BLE PEO Perey ee ale OMS OEA PP 5 o GE II II RENN 108 B 12 Detalles ds 108 Bro DEM o ad e cea avess 109 B 14 D tinino Named Col ios 109 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 1 INTRODUCTION 1 1 How to Use This Manual For instructions on installing Qlarity Foundry see Chap ter 2 Installation To get started using Qlarity Foundry and to learn design basics review the following chapters O Chapter 3 Getting Started J Chapter 8 Basic Design To learn more about user application design refer to the fol lowing chapters O Chapter 9 Intermediate Design J Chapter 10 Advanced Design Use the following chapters to learn about specific Qlarity Foundry functions J Chapter 4 Workspaces How to start open close save and use
88. ate functions in the base template are also listed Existing functions appear in bold select one to move the cursor to the function If you select a function that only exists in a base template the function is added to the template you are currently editing and overrides the existing function in the template New Variable Click New Variable to add a new variable to the code sec tion you are currently editing A dialog box appears to spec ify the variable name data type validation function and any documentation Refer to section 9 5 1 1 for more infor mation on adding a new variable using this method OptoTerminal Qlarity Foundry User s Manual Insert at Cursor Select this option before selecting a new function or vari able to place the item at the cursor location If not selected new functions and variables are added to the end of the cur rent code section 3 7 2 Object Instance Code When editing Object Instance code the navigation bar con tains the following components Events Overrides ha Show only event functions Events Overrides Click the drop down arrow to display a list of events that can be handled Events that have already been implemented are shown in bold Select an item to either add an event han dler or to position the cursor on an existing event handler Show Only Event Functions When this option is selected only those functions that are designated as event functions are shown in the Events Over
89. ated keypad Key Repeat Select this option to turn the key repeat feature on If selected a key entry repeats when you click and hold down the mouse button on a key on the simulated keypad OptoTerminal Qlarity Foundry User s Manual Repeat Delay If you selected Key Repeat enter the delay time in milli seconds that you want between when a key is pressed and when it begins to repeat automatically Repeat Rate If you selected Key Repeat enter the time in millisec onds that you want between each repeat when a key begins to repeat automatically Automatic Shift Key When this option is enabled clicking the Shift key on the simulated keypad does not register a key press 1t puts the keypad into the shifted state If there 1s a shift LED on the simulated keypad the LED state is automatically toggled Subsequent key presses are processed as shifted When this option is disabled clicking the Shift key is processed as a key press just like any other key Automatic Power Key When this option is enabled clicking the Power key on the simulated keypad does not register a key press While press ing this key on a real terminal would put the terminal in sleep mode clicking the simulated key has no effect other than to toggle the power LED if present When this option is disabled clicking the Power key is processed as a key press just like any other key 6 5 3 Serial Port Setup You can set up Simulation View to s
90. b is created for the Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 50 channel The tab displays the data that is sent and received on the channel On network channel open switch to its tab This option becomes available when you select the previous option If this option is enabled each time a network chan nel is opened the channel s tab is displayed Non printable character Space character Newline and carriage return Enter the character that you want to appear on the screen in Simulation View when a non printable space or newline carriage return character is encountered Click Default to enter the default character Maximum buffer size Enter the maximum amount of data in bytes to be held in the Communications window buffer When this number of bytes is reached data will be removed from the top of the buffer as new data appears at the bottom Click Default to enter the default buffer size 6 5 2 Keypad Settings This option only applies to applications that use an external keypad not a keyboard Click Keypad Settings to con figure the keypad simulation Keypad Settings MT Key Click errr E E T Key Repeat Repeat Delay 540 Repeat Rate fi 20 IY Automatic Shift Key IY Automatic Power Key Key Click Select this option to turn the audible key click on in Simula tion View If selected you will hear a tone or beep when you click a key on the simul
91. bar contains tools that provide quick links to com monly used Qlarity Foundry functions The tools available change depending on the selected view mode Layout View or Code View Refer to section 3 5 for a description of each tool on the toolbar Miscellaneous Bar The miscellaneous bar contains options to select the scale of the work area to add an outline to all objects and to select a 367 8 color and border theme for the objects in the workspace Refer to section 3 6 for more information on the miscella neous bar options Object Tree Object instances that have been added to the workspace are listed under Globals and object templates are listed under Templates in the Object Tree Some objects may be auto matically added to a workspace when it is created including the following e ScreenBlanker blanks the screen after a period of inac tivity e ExceptionDisplay displays unhandled Qlarity Excep tions Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Work Area This is the area in Layout View in which you place object instances to add them to the workspace The work area sim ulates the display of the Qlarity based terminal Object Palette The Object Palette contains an icon for each object template in the workspace and in any active libraries You click the icons to add new object instances Move the mouse pointer over an i
92. bitmap Before some objects can be added to a workspace at least one font or bitmap image must already exist in the work space if not an error occurs For this reason it is recom mended that you include the default fonts and bitmaps Include extra fonts To include additional fonts in your workspace select this option Include an error handling object By default an error handling object ExceptionDisplay is added to your workspace that identifies and displays descriptions of any errors in your code It is recommended that you include this object in all of your workspaces Screen Saver The default screen saver displays a pattern of dancing lines for a period of time before 1t blanks the display By default the display switches to dancing lines after fifteen minutes and to a blank display after thirty minutes You can change the default by selecting a new screen saver from the Screen Saver drop down box When you are done click Finish to proceed The default workspace name 1s New Workspace until you save 1t with OptoTerminal Qlarity Foundry User s Manual a new file name The Object Palette includes tools to create all of the objects contained in the supported libraries NOTE editing resources You can add or remove resources and libraries after the workspace is created using the options on the Edit menu Refer to section 5 2 Edit Resources and section 5 3 Edit Libraries 4 2 Open a Workspace
93. bject to indicate the new position at which the object will be placed when you release the mouse button E of ESB akest_ 7 E q EZB ext 3 EXBOFTest_10 A box appears around a container object as you drag another object over 1t If you release the mouse button when the box appears the object you are dragging is placed in the container object af E Rectangle_1 al Pal If you move a parent object a container object with chil dren the children move with it You can place a container object inside another container object Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual To change the Z order of an object within its family with out moving it to a different parent right click the object either in the Object Tree or in the work area and select one of the following options from the shortcut menu Forward one Move the object forward one position in the Z order one position up the Object Tree Back one Move the object back one position in the Z order one posi tion down the Object Tree Bring to front Move the object to the front of the Z order top of the list of children or top of the Object Tree Send to back Move the object to the back of the Z order bottom of the list of children or bottom of the Object Tree 8 3 2 4 Align Size Space Objects This option provides several tools for aligning sizing and spacing a gro
94. cccceccesssssseeseseeeseeseseseeeeeseeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeseeseeeas 84 9 5 3 1 Add a Global Message Handler From a LliSt occcccccnnnnnnnnnnnnnnnnnnnnnnnnnnnnnonononnnnnonnnnn nono nono ronca nnnnnanos 85 9 5 3 2 Add a Global Message Handler in the Global Code Section ccc ceeceseeeeeseeseeeeeseeeseeeeeseeseeeeeeees 85 9 6 Create New Object Template sd att ii 86 OF A db aaawsatueogadeededenonnt a sodacod ade Remade a a a e uecacecteed 87 CHAPTER 10 ADVANCED DESIGN cir A A A AA A A A 89 10 1 Advanced Code SECHONS or ol Sati ooo a aaa 89 TO Advanced Edad dto 89 IA e E N 89 10 2 Validation P UNC NONS ld a e e dci 89 10 3 The Ola APLI is 90 TOE Excepuon Handlino o eea E EE E R 90 103 Greate a New Object Template a a a a A 92 10531 New Template Boilerplate Codos senere e E a aE a ana 93 LOS Non Dra wable DIES sicn A 95 HARANE E S e a E A canes 95 105 3 Contamer OD jects ias ta 96 10 5 2 Getting New Object Templates to Work in Qlarity Foundry ccccccccsssssssssssseeceeeceeeeeeeeeceeeeeeeeeeeeeeeeeeess 96 10 5 3 Adding Object Template Documentation id 100 10 6 Guidelines for Designing New Object Templates ooooccccccnnncnnnonnnnnnnnnnnnnnnnnnnnonnnnonononnnnnnnnnnnnnnn nan nnnnnnnnnnnnnnnnnnoss 101 107 Wihere to Go From Here ads 102 APPENDIX A GLOSSARY OF SOFTWARE TERMS 3 isccsecedcssscssceascsbectetaiesancscuessssncesdesscsusedkadasdenstsedasdesetkusstdecsodessdddeansieec
95. ception level for exceptions thrown by the application via the Throw API function EXLEV_MIN This level represents the minimum severity for an excep tion The exception type is an error code that describes the cause of the error Each exception type is accompanied by a short text description of the problem The error code provides a convenient means for Qlarity exception handlers to deter mine what error occurred while the description provides a readable summary of the exception The location string indicates the Qlarity function or system software facility that was executing when the error occurred This is useful for debugging the application The error codes and descriptions are listed in the Excep tion List of the OptoTerminal Programmer s Reference Manual Exception handling code is supported in the Qlarity pro gramming language by check error on error blocks When an exception occurs the Qlarity execution engine determines if the offending code is inside a check error block If so execution immediately jumps to the first state ment in the on error block If the offending code is not in a check error block the Qlarity execution engine checks 91 the function that called the current Qlarity function for an enclosing check error block This process iterates until either an enclosing check error block is found or the mes sage handler for the current message is reached Si
96. ck the starting color next to the Fill Icon label e By default click a pixel with the left mouse button to make the pixel black click with the right mouse button to make 1t white You can also specify colors other than black and white for each mouse button as follows e Next to the Left Button label click the color that you want to apply when you click the left mouse button e Next to the Right Button label click the color that you want to apply when you click the right mouse button e Click An gt to move or offset the graphic in the grid y However any pixels with a color other than white are changed to white when they are moved from the display area For example if you change the default fill to black and click twice then click gt once a one pixel wide white border is added to the right side of the image Click a twice and a once to add a white top border Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual e Click Rever to return the graphic to its original design e Click Invert to invert the color of each pixel in the icon 5 13 Rename a Template In the Add Edit Templates dialog box do the following to change an object template s name 1 Click the template name that you want to edit It is highlighted in blue 2 Click Rename Template 3 Type the new name over the old name 4 Press lt Ente
97. com Although you may wish to modify these guidelines or develop your own use of a consistent style will make your object designs easier to develop maintain and use Use consistent naming conventions for properties and methods This is actually part of a consistent style The QSI Qlarity style guide lists the recommended names for properties that are commonly used in objects Using these conventions aids the designer when the object is used in an application it also increases readability of the object template source code Use validation functions A validation function is the link between an object s proper ties and its behavior Almost every property should have a validation function so that the object can properly respond to property changes Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 102 Become familiar with the API library All interaction with the Qlarity based hardware is achieved through API function calls You should be familiar with the functions available and their capabilities Provide default values for all properties This provides a predictable starting point for each newly created object instance Provide simple to use override functions Many of the objects in the QSI libraries include simple override functions that are called from message handlers Most of these functions are empty by default but they pro vide a way for each object instance to determine how it will respo
98. com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual TRUE to the enabled property which means that if the property is not assigned an initial value in the object instance the value defaults to TRUE Finally the validation function see section 10 2 Valida tion Functions describes the behavior of the object when the value of enabled is changed The validation function first does a strict assignment of the new value to the prop erty then calls the Enable API function to inform the firm ware that the enabled status of the object has changed Calling API functions to implement the effects of a property change is a very common activity in validation methods An example of another property found in all versions of the boilerplate code is the parent property as follows who do we attach to dim parent as objref init parent default func parent newval as objref parent newval Attach me parent endfunc This code creates a property of type objref named par ent Parent is given a default value of default which is the root container when assigned to objref variables The validation method assigns the new value to the property using the strict assignment operator then calls the Attach API function to attach the object to its new parent container 10 5 1 1 Non Drawable Objects The boilerplate code for a non drawable object template includes the enabled
99. con to display the object s name Refer to section 3 12 for more information Properties Window The Properties window is displayed by default Click an object instance in the Object Tree or work area and its prop erties are displayed Refer to section 3 11 for information View Tabs To set up the workspace you can work in either Layout View or Code View Simulation View can be used after you have created a workspace to simulate the performance of the workspace objects on the Qlarity based terminal Click the Layout View tab or Code View tab at the bottom of the work area default location to change views Click the Sim ulation View tab to start the terminal simulation Layout View is a graphics mode used to lay out the terminal display Generally unless you are making changes to the programming code you will work in Layout View Code View is used to write or edit an object s programming code You will generally only work in Code View if you are customizing objects or creating your own objects Refer to section 3 9 for more information on the Layout and Code Views Refer to section 3 10 for more information on Simulation View Messages and Errors Window The Messages and Errors window displays any errors or other messages generated when the workspace is compiled or during a debug operation These messages can help you identify and correct problems with the workspace Status Bar The status bar shows the status of the
100. ct templates can be a part of a workspace or supplied through one or more libraries The template defines which proper ties and methods are included in the object Properties Variables that are stored in an object and comprise the data portion of the object The properties for each type of object are defined in the object template but each object instance maintains its own properties In Qlarity Foundry object properties can be changed in the Properties window in Lay out View without the need to modify the programming code Properties may also be changed at runtime to reflect the current state of the object OptoTerminal Qlarity Foundry User s Manual Qlarity A BASIC like scripting language that is used to write user applications for the Qlarity based terminal Resources Bitmap images fonts audio files and binary data files available for use 1n an application Root Container A root level container that uses the global properties and methods as its properties and methods The root container is best viewed as an abstraction It gives you a place to attach all other objects An object that is not attached to a con tainer object is attached to the root container by default The root container is not a true object and cannot be disabled Its area cannot be modified The root container is a launching point for newly generated messages This means global message handlers have the highest priority for receiving new messages User
101. cts as a single step Step Out Of Simulation View only Select this option to step out of a function call This exe cutes the rest of the current function and returns to the call ing function It stops on the first executable line outside of the function call If there is another breakpoint in the current function execution stops there Pause Execution Simulation View only Select this option to stop execution at the next executable line of Qlarity code If no Qlarity code is executing 1 e the application is idle execution does not pause until after it has been started by an event such as a screen touch or time tick Clear All Breakpoints Simulation View only Select this option to remove all of the breakpoints that were set 3 4 5 Help Menu Show Object Documentation F1 Select this option or press lt F1 gt to view Object Documen tation which is a Help file containing information on library and workspace object templates as well as func tions variables and APIs in the workspace Documentation is included for all libraries provided with Qlarity Foundry Advanced users can add documentation for object templates they create refer to section 10 5 3 Adding Object Tem plate Documentation for information To use Object Documentation in the Qlarity Documenta tion index double click the item for which you want to view Help You can also type a keyword in the text box to search for an item then double
102. cumenting Sample code lines begin with the right point ing double angle quotation mark character The easiest way to generate sample code is to author and test the sample code then select the code in Qlarity Foundry and select Mark selected code as sample from the Tools menu OptoTerminal Qlarity Foundry User s Manual doc func Min param iteml The first item to be compared param item2 The second item to be compared Returns the minimum value of its two parameters func PrintMinimum Print The minimum value is str Min 9 9 Lao endfunc The preceding example would print out lt i gt The minimum value is 7 5 lt i gt B 11 Property Categories When authoring your own objects you may wish to specify the category for the object s properties in the Properties window To do this use the category directive category lt category name gt The category directive is only valid when used for a doc prop directive lt category name gt may be any string that defines a category title This will add lt category name gt to the Properties window when an instance of the specified type is selected and the property will appear in that cate gory All properties that share the same lt category name gt appear in the same category in the Properties window doc prop englishCaption category Language Data Defines the caption of this object when the English language is selected B 12 Default
103. current work space The following dialog box is displayed Create Compiled Binary BFF file ax Save in Demo e e Ee 7 Audio J BDFFonts J Binary J Bitmaps Libraries J TTFonts Cancel File name Clarity application binary files bff y Save as type 3 In the File name field type a name for the BFF file or accept the default file name you do not have to type the extension The workspace file name with a bff extension in place of the gly extension is used as the default 4 Click Save to generate the BFF file You can download the BFF file using the Download Other BFF option in the Download Application function File menu Refer to section 7 3 Download a BFF File for information Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 5 TEMPLATES RESOURCES AND LIBRARIES 5 1 Add Edit Templates Creating and designing object templates is an advanced function which is covered in depth in Chapter 10 Advanced Design This section provides an overview of the Add Edit Templates function Use Add Edit Templates to create a new object template The new template may be blank it may contain only boiler plate code or it may be based on a library object template New object templates are added to the Template branch of the Object Tree After adding a template you use Code View to add or edit your custom programming code Yo
104. d enter the code with which you want to replace it Click Find Next to find the code Then click Replace to replace it Or click Replace All to automatically find and replace all occurrences of the code To find only characters matching the entered case upper or lower select Match Case Undo Select this option to undo the last action performed Redo Code View only Select this option to redo the most recent undone action This option is only available after you have selected Undo in Code View Goto Bookmark Code View only Select this option to go to the next bookmark in the dis played object s code Use Set Bookmark to add or remove bookmarks in an object s code Set Bookmark Code View only Select this option to add or remove a bookmark in an object s code at the cursor location Bookmarks make it possible to find a location quickly which is useful in objects with several lines of code Go to Next Message Code View only If there are messages in the Messages and Errors window select this option to select the next message or the first one if none is selected and position the cursor on the line that generated the message This applies to messages due to compile errors compile warnings or runtime messages generated by the Tool_Trace API and runtime exceptions Add Edit Templates Select this option to open the Add Edit Templates dialog box to add or edit an object template Refer to section 5 1 Add
105. d Errors window An example of such a message is shown below Error in ButtonTTF_21 line 7 Parse error Error in parameter declaration Warning in ButonTTF_1 line 7 Missing statements Function body has no statements Fl a The message includes a description of the error includ mg the object and line number where the error occurred Double clicking the error message in the Messages and Errors window takes you to the location of the error in Code View Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual NOTE no errors If there are no errors found during the compile the work space 1s automatically returned to Layout View 9 5 Global Code In addition to method overrides an application can be cus tomized by adding variables and functions to the Global Code space Global variables can be used to hold data not stored in objects Global functions can implement com monly performed routines that might be shared by many objects Also most messages can be handled by global message handlers if desired Message handlers are special functions that are called by the system software when the message that the function handles is processed Refer to Chapter 10 Advanced Design for more information on messages Since global functions are not overrides there are few restrictions on the names parameters or return type for glo bal functions
106. d feedback about the Qlarity programming lan guage and the Qlarity based terminal should be sent via e mail to support qsicorp com You should also check the www qlarity com Web site occasionally for software and documentation updates new library objects and support materials Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 APPENDIX A GLOSSARY OF SOFTWARE TERMS API Function A function that is called from the user application to interact with the Qlarity based system software firmware and hardware You use API functions to draw to the screen ren der text and bitmaps send characters to the serial and net work ports enable disable objects manipulate object order in the hierarchy perform complex math and so on Area Object An object that directly interacts with the terminal display by drawing something on the display and or processing area based messages Examples of area objects include text objects bitmap objects and line objects BFF File Format Binary file format BFF required for a user application to run on a Qlarity based terminal When a workspace is com piled it is converted to a BFF format Container Object An object that contains other objects e g a form or screen On the Qlarity based display a container may represent a portion of the display or all of the display Whether or not a container is displayed depends on its position in the object hierarchy and whether or not
107. d manip ulation of objects This chapter provides examples of programming code written in the Qlarity language For additional examples and information refer to the OptoTer minal Programmer s Reference Manual Nav creen enabled false Funser enabled false Introscreen enabled true EndGames enabled Crue gt Line 1 Col 1 9 2 2 Objects and Templates A Qlarity application consists primarily of objects An object template defines a new type of object with certain properties and behaviors Any number of object instances that are based on the object template may be added to an application Object templates typically reside in libraries where they can be used in many different applications However templates can also exist in a normal workspace When templates are part of a workspace they appear at the bottom of the Object Tree when Code View is selected A template defines the properties variables and methods functions for a certain type of object The properties and methods in a template completely define the behavior of object instances that are created from the template Proper Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual ties may also be assigned default values in the template These values are used if the object instance does not assign an initial value to a property Details on creating templates are provided in C
108. d or edit an object template Refer to section 5 1 Add Edit Templates and to Chapter 10 Advanced Design for information on creating templates Click to open the Qlarity Resources dialog box to add resources to or remove them from the workspace Refer to section 5 2 Edit Resources for informa tion Click to open the Libraries dialog box to add libraries to or remove libraries from the workspace Refer to section 5 3 for information Click to turn on off the snap to grid function If enabled this feature forces objects to snap to the nearest grid line when added or moved The top left corner of an object s rectangle snaps to the nearest horizontal and vertical grid lines when you release the mouse button Click to show or hide the grid You can display a grid over the work area to help you more accurately place and align objects For information on changing OptoTerminal Qlarity Foundry User s Manual the spacing or color of the grid refer to section 8 1 3 Drawing Aids Click to open the Qlarity Foundry Preferences dialog box to define the Qlarity based terminal s configura tion and to enter Qlarity Foundry preferences Qlarity Foundry attempts to simulate the terminal s display area input type and so on as closely as possible Refer to Chapter 6 Qlarity Foundry Preferences for information Click to identify the version of Qlarity Foundry you are running 3 5 2 Code
109. default named color select the named color you want to restore and click Reset color to theme default Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 40 5 5 Edit Named Borders You can use named borders to assign borders to objects Rather than manually creating a border for each object you can assign one named border to any number of objects in the workspace All objects assigned a named border will then have the same border characteristics When you change the characteristics of a named border it is changed for all objects using that named border Qlarity Foundry includes several predefined named borders with each new workspace e g Bdr_ButtonBorder Bdr_LabelBorder etc You can create as many additional named borders as needed for a workspace The designs for named borders along with the colors for named colors see section 5 4 are set up in themes see section 5 5 1 You can create your own themes and named borders and you can edit the predefined themes and named borders To create or edit named borders and themes for a work space select Edit Named Borders from the Edit menu The following dialog box is displayed Border Designer x General Effects Preview E Bdr_BumpBorder aada cane la New named border Mea _tutontorde I 3D Bevel Delete named border E Bdr_CheckBoxBorder Rename border Border Color
110. displayed when a button is pressed enter the mes sage in this text box A drop down list may appear with available values depending on the object selected Some objects may require additional configuration such as selecting a color If additional configuration is available for the selected object a E button appears next to the text box NOTE some objects are not compatible Some object properties are not compatible If you select an incompatible value for the target property an error is gener ated when you click OK and close the Event Builder dia log box Serial Transmit This action transmits data out one of the terminal s serial ports Transmit out Serial Fort Select Serial Fort COM Message to Transmit Sends tank level out COM1 to ae pour controller Pause until transmission completed From the Select Serial Port drop down list select the communications port on the Qlarity based terminal from which the data will be sent If you have only one select COM1 For information on entering the number of serial ports on your terminal see section 6 1 3 In the Message to Transmit box enter the string to send out the serial port or a description of the value to be sent Enable Pause until transmission completed only if you want the terminal to pause Generally you should leave this disabled as it may decrease performance on the terminal Play Note This action sounds a tone on th
111. dollar sign symbols can be used at the end of the name 6 Click OK to create the new template Many library templates depend on global code or other resources in the library Qlarity Foundry will add these items to your workspace and inform you of the addi tional changes in a dialog box When the dialog box appears click OK to proceed 7 The template list in the Add Edit Templates dialog should now include the new template Click Close to close the dialog box Now do the following to edit the new template to your spec ifications 1 Select Code View The new template is now listed under the Templates heading in the Object Tree 2 Select the new template in the Object Tree The source code for the template is displayed in the editor window 3 Edit the template source code Variables declared inside a template become properties of the template object and functions declared inside the template become the object s methods Properties and methods can be added deleted or modified as desired You can add properties and methods just as described for the Global Code space see section 9 5 4 When you are finished editing the template click or select Compile from the File menu to compile the 87 workspace Any errors in the new source code are iden tified by messages in the Messages and Errors window If no errors are present the compiled workspace is returned to Layout View Notice that the Object Palette c
112. ds Add delete or modify properties and methods as desired When you are finished defining the template click or select Compile from the File menu to compile the workspace Any errors in the new source code are iden tified by messages in the Error Messages box If no 12 93 errors are present the compiled workspace is returned to Layout View Notice that the Object Palette contains a default icon representing the new template To edit the icon or change the name click on the toolbar or select Add Edit Templates from the Edit menu Click the template name in the Add Edit Tem plates dialog box then click Edit Icon Refer to section 5 1 2 Edit a Template Icon for more informa tion 10 5 1 New Template Boilerplate Code The new template boilerplate code can be used as a founda tion for building new objects Using the boilerplate code can greatly simplify the creation of new objects This section provides an overview of what the boilerplate code is and the functionality it provides The actual boilerplate code gener ated by Qlarity Foundry is continually being improved and may differ from the code described in this section The functionality however is mostly the same Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 94 OptoTerminal Qlarity Foundry User s Manual e Olarity Foundry 2 501 File Edit wiew Tools Help O Hgm 9 0demo gly LaserPolyoon A fl AM A Mo E
113. e to change the value of a property in another object The property to set is the action that results from the event Set to this Value Use the value of this object property DEEE Tank slicer E Property float Property to Set Object Tank_gauge Property value Use this explicit value El In the Property to Set section select the target object object to be changed when the event takes place such as moving a gauge from the Object drop down list From the Property drop down list select the target property property to be changed by the action In the Set to this Value section use one of the following options to set the value for the property Use the value of this object property Select this option to use the value of a specified object and property Then select the source object from the Object drop down list and the source property from the Property drop down list In the example above the target and source properties both use the value property but any compatible property can be used For example if the target object is a label you might select the caption property Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Use this explicit value For some properties you may need to enter or select an explicit value For example if you want your own mes sage
114. e Move Resize and Reorder Objects e Change an Object s Properties Event Builder e Overview of Event Builder Steps e Event Builder Dialog Box e Select and Configure Actions e Load Event Builder Sample Workspace e Qlarity Code and Event Builder e Troubleshooting Communication Objects e Serial Objects e Ethernet Objects e Receive Data Test the User Application Save and Compile a Workspace Download a User Application 8 1 Prepare Qlarity Foundry for Application Design This section provides information on how to set up Qlarity Foundry before you design a user application Begin by opening Qlarity Foundry and starting a new workspace Refer to Chapter 3 Getting Started for information 8 1 1 Basic Design Layout You work only in Layout View to create a basic design You should keep the following Qlarity Foundry windows open as you will use all of them e Toolbar e Properties window e Object Palette e Object Tree Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 60 OptoTerminal Qlarity Foundry User s Manual g Olarity Foundry 2 501 a70demo gly Globals File Edit View Tools Help 0 Bi 5 8208 2 1 Object Palette E Ea fe EERE y Cam Basic Y DataProc Y Extra ES af WatchdogT imer i Select display theme Qlarity o l A af ExceptionDisplay Rea aE e TouchkillnfoLbl ae v L a af InfoLb
115. e Templates branch of the Object Tree and click Add Edit Templates on the shortcut menu OptoTerminal Qlarity Foundry User s Manual Add Edit Templates Base Template Template 2 Click New Template and the following dialog box is displayed New Template Wizard Create a template ready to operate in Olarte Foundry f Create a completely blank template Copy the code of an existing template in a library Extend inherit a template from an existing template in a library Template name TabContainer_derived Based on SBT abContainer 3 Select Extend inherit a template from an existing template in a library This option is used to create a new object template based on the programming code from an existing library object When you select this option a Based on box replaces the Object type box 4 From the Based on list box select the existing library object on which you want to base the new object tem plate 5 In the Template name box type a name for the new template Each template in the workspace must have a unique name A template name has no size limitation but must start with a letter or underline character _ A name cannot contain spaces but may contain the under Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual line character or pound sign The percent and
116. e communications in Qlarity Foundry and at the terminal and prepare the termi nal for download For information on setting up communications refer to section 7 1 For information on preparing the terminal for downloading refer to section 7 2 1 For information on downloading a user application to the terminal refer to section 7 2 2 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 78 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 9 INTERMEDIATE DESIGN Chapter 8 Basic Design introduces some basic applica tion design techniques using Qlarity Foundry It also pro vides information on Qlarity Foundry s Event Builder which can be used to add events to your applications with no programming While this is enough for many applica tions if you require very complex flexible or custom applications you will want to have some Qlarity program ming skills To assist you with intermediate design and help you get started with Qlarity Programming this chapter provides information on overriding object functions to change the object s behavior and discusses adding global code and cre ating new object templates based on templates that already exist in libraries By applying a small amount of program ming you can add a great deal of flexibility and power to your applications Before proceeding you should b
117. e familiar with the con cepts presented in Chapter 8 Basic Design Also this chapter includes many references to the OptoTerminal Pro grammer s Reference Manual The OptoTerminal Pro grammer s Reference Manual will provide an invaluable resource to you as you learn intermediate Qlarity design and eventually advanced Qlarity design as explained in Chapter 10 This chapter covers the following information Viewing the Code Understanding Qlarity for Intermediate Design e Qlarity Programming Language e Objects and Templates Qlarity Code for Objects e Property Initializations e Method Overrides Handling Events With Qlarity Code e Override an Object Method Global Code e Add a Global Variable to a Workspace e Add a Global Function to a Workspace e Add a Global Message Handler to a Workspace Create a New Object Template 9 1 Viewing the Code To view and change the Qlarity code for an object select the object in Layout View or in the Object Tree and then click the Code View tab at the bottom of the work area see section 3 9 Layout and Code Views In the illustration on the next page the global code for an example work space is shown The Messages and Errors window at the bottom shows any compiling errors that occurred during the last compile Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 80 e larity Foundry 2 501 File Edit View Tools Help O e E e Fo
118. e libraries include the following types of objects e Container objects with tabs or buttons to switch from one screen to the next Basic library e Area objects with event functionality all libraries Refer to section 8 4 Event Builder for information on con figuring objects to respond to events e Communication objects Data Processing library Refer to section 8 4 Event Builder and section 8 5 Com munication Objects for information on using communi cation objects to send data to another device through the Qlarity based terminal s serial or Ethernet port Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual The Qlarity Foundry libraries are continually being added to and improved You can obtain the latest libraries at QSI Corporation s Web site www qsicorp com qlarity Also on the Web site you will find descriptions of the objects included in the libraries 8 2 Understanding Qlarity for Basic Design Before you can effectively design a user application you need to understand some basic Qlarity concepts which are explained in the following sections 8 2 1 Workspaces and User Applications A workspace is a Windows based file created in Qlarity Foundry that is compiled into a user application Work space files are stored as plain text and typically have a gly file name extension User application files have a bff exten sion
119. e terminal s speaker Play Mote on Speaker Hote e q E Duration je 73 Select which note to play at the Note field Valid values range from very low pitch to 86 very high pitch The standard beep when a button is pressed is 30 Selecting O generates no sound At the Duration field select the duration of the note in milliseconds The standard button beep lasts 100 ms Refer to the OptoTerminal Programmer s Reference Manual PlayNote section for more information Set Contrast This action changes the level of contrast on the terminal screen when the event occurs Adjust Contrast Contrast Lighter C Contrast Darker For example you might use this action to provide a contrast adjustment in case the display becomes difficult to read Create two buttons one for lighter contrast and one for darker contrast Each event e g button press changes the contrast one step lighter or darker NOTE contrast level temporary and TFT displays The contrast level set with this action is not permanent When the terminal is reset it reverts to the default contrast level If you want to save the contrast level use a DisplaySettingV2 object Terminals with TFT displays ignore this command as TFT displays do not support a con trast setting Set Backlight This action brightens darkens turns off or turns on the dis play backlight Adjust Backlight f Backlight Lighter Backlight Darker
120. e the tools available on the toolbar in Layout View Code View and Simulation View 3 5 1 Layout View Toolbar De GB eB ORAM Ala y Click to start a new workspace Refer to section 4 1 for information ge Click to open an existing workspace Refer to section 4 2 for information EH Click to save the current workspace Refer to section 4 4 for information Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 12 DA En Click to compile the current workspace into the for mat required for a user application A workspace also must be compiled to properly display in Layout View Refer to section 4 5 for information on compiling a workspace Click to open the Download Application dialog box Refer to Chapter 7 Download Software to the Ter minal for information Select an object in the work area then click e to cut the object from the workspace The object remains in the Windows buffer until replaced by another cut or copy operation Select an object in the work area then click to make a copy of the object The object remains in the Windows buffer until replaced by another cut or copy operation Click to place a cut or copied object in a new location in the same workspace or in a different workspace Click to undo the last action performed The Undo buffer is cleared after the workspace is compiled Click to open the Add Edit Templates dialog box to ad
121. e with the Opto 22 I O unit Create workspace like the last one created This option appears if you have previously created a work space Select this option to create a workspace containing the same libraries and resources that were in the last work space created Click the workspace type that you want to use and click Finish or Show Options depending on the workspace option you selected If you click Show Options the following dialog box is displayed Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 24 Select any additional items to add to the workspace Add additional items to your project Note Some objects require that at least Include a default EDF raster font ome font or bitmap be included in the Include a default Truel ppeltm font workspace Creating such an object Include a default bitmap without including E a a causes an error For additional fonts an me i Include extra fonts bitmaps select Edit Resources from the Edit menu Include an error handling object Screen Saver Dancing Lines Select additional object libraries No library selected Basic glib C DataProc glib Extra glib C Modbus 2 glib C multilingual glib Opto22 PAC glib irtualG larity qlib Tour project is now ready Select any addition options for your application then press Finish This dialog box allows you to add or remove resources Include a default font and
122. ear List Welete tem Enter an IP address in the text box at the bottom of the dia log box and click Add The address is added to the list In the same manner add each address to which you want to download Select an address in the list and click Delete Item to delete an address Click Clear List to remove all of the addresses from the list Click OK when you are done Recently Used IP Addresses Select a recently used IP address from the drop down list to insert 1t in the IP address of unit box 7 2 Download a User Application When you download a workspace to your Qlarity based ter minal 1t is automatically compiled into binary file format BFF for use as a user application on the terminal The following sections describe how to prepare your Qlar ity based terminal for downloading and how to download the user application OptoTerminal Qlarity Foundry User s Manual 7 2 1 Prepare the Terminal for Downloading You may need to set up the Qlarity based terminal for downloading using the terminal s Power On Setup utility Refer to the OptoTerminal Hardware User s Manual for information on using Power On Setup 7 2 2 Download the User Application Do the following to download a user application to the ter minal refer to the previous section for information on pre paring the terminal for download 1 Select Download Application from the File menu and the Download dialog box is displayed E Download
123. ects such as the Screen object in the common lib library A container object may occupy part of the terminal display or the full display area You use container objects to define an association between objects and to indicate how they are displayed All objects in a container process information as a group Con tainers are often stacked and identified with tabs 8 2 3 Parent Child Relationships Qlarity allows you to group objects together How objects are grouped determines how information is processed mes saging and how the terminal screen redraws The complex ity of your user application determines how much you need to group objects Grouped objects have a parent child relationship with the parent always a container object and the objects inside the container the children 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 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 64 In Qlarity Foundry when you add
124. ects are the same height 8 3 3 Change an Object s Properties Each object has properties that help define the object instance Click an object in the work area or click an object name in the Object Tree to display the Properties window If the Properties window is not displayed pull down the View menu and click Properties Window The default properties for an object instance are defined in the object template from which the object instance was added You can change any of the default properties for an object instance to create a unique object that meets your requirements Properties that are common to almost all objects include e Object name e Enable disabled status e Parent specification A wide range of additional properties vary depending on the type of object For example some typical properties for area objects include e Size height and width e Alignment xalign and yalign e Color for borders fill foreground background font etc e Font for a text area object e Position in display xpos and ypos where both posi tions start at the top left corner of the parent object The xpos value increases right ypos increases down For specific information about any QSI library object open Object Documentation lt F1 gt The following illustration shows an example of the Proper ties window for a button object OptoTerminal Qlarity Foundry User s M
125. ed in the Natives library Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual E dit Library Xx Path le program hles qs corporation tglarnte foundry natives lib Hame Standard Icon Foreground Icon Background E Version 2 10 Warning Any changes you make to libraries may affect other projects Additionally any changes will take effect immedediatel and cannot be undone Version Edit Entry 3D Colors Source MEE Absolute alues Source Rename Entry AggregateSuppart Source BoilerFlateC ont Source Remowe Entry e tsp AN ALE AA EollerPlateO by SOUICE Set Entry Version Draw sD Rect Source ForrnatFunctions Source IP Support Source Notes Source Add New Entry Skingra Source Text ligniment Source Textlonstants Source TexthultlineB DF Source Texthtultiline TTF Source Text5inoleLineB DF Source 37 Path le program iles qe corporation glanty foundry core glib ghide Name Icon Foreground Icon Background O Version 2 20 Warning Any changes you make to libraries may athect other projects Additionally any changes will take effect immedediatel and cannot be undone Edit Erit Version _megBanner Source 0 00 timer Coordinator Source 0 10 Henane Entry coreButtor Source 0 00 coreCommbkabel Source 2 20 Hembve Et coreCormmanication Source 2 10 coreD ataLogger Source 220 Set Entry Version coreE d
126. een for a QSI standard touch key legend enable if also be different This is the result of ongoing improve you are using a touch key legend disable if you are not ments to Qlarity Foundry libraries l T l ety y e Simulation setup volume in Simulation View and Com munications window defaults The Communications window simulates the data received and sent via the com munications port 8 1 2 Simulate the Terminal Display Qlarity Foundry requires information about the display con figuration of your Qlarity based terminal to simulate it accurately in the work area and in Simulation View The settings required for this include the following Click gt on the toolbar or select Settings from the View menu Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual The Qlarity Foundry Preferences dialog box is displayed Glarity Foundry Preferences Terminal Layout Editor Compile Simulation Hardware Configuration Assistant Base Terminal OTERM G70 Display Setup Impr Keyboard Keypad Select Communications pa of serial ports 2 Misc Manufacturer ID MID 65535 IM TouchScreen Dimensions 320g 240 OOO Onentation Landscape Display Type Color a M Audio Decoder I Ethemet Tabs are available to define your Qlarity based terminal display to define the layout of the Qlarity Fo
127. el button 3D event timer form line etc The objects are listed in Z order see Appendix A Glossary of Software Terms but you can move an object up or down the list using drag and drop The Object Tree also contains icons that can be used to show hide or lock unlock an object instance as follows Click to show eye open or hide eye closed the object instance in the work area This is useful if you have objects stacked You can hide an object if you want to see an object that is behind it This icon indicates objects that have no display repre sentation and are never displayed generally serial or Ethernet objects Click to lock lock closed or unlock lock open an object instance When an object is locked it cannot be changed or moved with the mouse E Eo 15 3 8 1 Globals In Layout View default view you see only the Globals branch of the Object Tree Under the Globals branch all object instances defined for the workspace are listed E Ela Globals EE af W atehdogTimer A iat af ExceptionDisplay ET af TouchkillnfoLbl E TimerkKilllnfoLb Ea af InfoLbl af FullScreenColorLbl gf FTPServer af HideFullScreenColorLblT imer af GwertyKeypad af TranslucentColorPicker af BacklightD ownBtri al BacklightlUpE tn al Contrast ownBtn af Contrast pBtn af EndGames af HelpSideB uttonsS cr af GraphicsScr 4 SplashScreen fy ObjectsScr fq Diagnostics cr
128. elect a theme for the colors and borders of the objects in the workspace click the drop down arrow and select the theme you want to use from the list See section 5 4 and section 5 5 for information on themes Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 14 Code View Misc Bar EN No Error This box indicates if the selected line of code contains an error 3 7 Navigation Bar Code View only The top of the Code View window contains a navigation bar to aid in code development The contents of the navigation bar may vary based on the section of code you are editing 3 7 1 Global Template or Library Code When editing Global Template or Library code the navi gation bar contains the following components Message Handlers Existing functions New Variable C Insert at cursor Message Handlers Click the drop down arrow to display a list of valid message handlers in the current code section Message handlers that have already been implemented are shown in bold Select a message handler to either add it to the selected message or to move the cursor to the selected message handler if it has already been added Refer to section 9 5 3 for more infor mation on message handlers Existing Functions or Existing and Inherited Functions Click the drop down arrow to display a list of all existing functions in the current code section If you are editing a template that extends another templ
129. element name gt lt alternate text gt Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 106 This will insert a link to the documentation element speci fied by lt element type gt and lt element name gt The optional lt alternate text gt specifies the text that will appear in the documentation doc prop comPort Specifies the com port used for communication The value of this property will be passed to the link func Transmit APT Fun tion doc prop resetNow Setting this property to true will cause the terminal to reset as 1f link func SoftReset SoftReset RESET NORMAL had been called B 4 Importing Items You can import all or part of the documentation from one item into another item This differs from linking in that the documentation is directly displayed as part of the item rather than indirectly displayed via a hyperlink importdoc lt element type gt lt element name gt lt import what gt indent box f111 This imports the documentation from lt element type gt lt ele ment name gt directly into the documentation for the current item lt element type gt of group is not supported The items after the optional sign control exactly how the import is handled lt import what gt is one of the following items none No import will occur all The specified item will be imported in its entirety decl Only the declaration line for the
130. emp nevrral as float clemp i newmral updatecurtemp i endfunoc func ctemp newval as float index as integer ctemp index newval 3 10 Simulation View Simulation View 1s used to simulate with some limitations the operation of a user application after it is downloaded to the Qlarity based terminal Both touch screen and keyboard actions are simulated On a simulated touch screen for example you can activate a button by clicking 1t with the mouse When you click it the programmed action occurs In the following illustrations the mouse pointer a hand is positioned over the activated button Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual i Lighting View HVAC view security i HVA View Lighting Temperature Cur zt Z onz temp tenp 1 70 37 A 0 3 9c oo lee ce All zones are at optimal temperature NOTE required settings for simulation To effectively simulate a Qlarity based terminal you need to define the terminal s hardware in Qlarity Foundry including whether you use a touch screen or keyboard Use the Settings option to define the terminal s hardware and to set the simulation s volume and display functions Refer to Chapter 6 Qlarity Foundry Preferences 17 3 10 1 Serial I O Support Simulation View partially supports serial I O using the Communications window bottom left c
131. end and receive appli cation data through a serial port or ports on your computer Use the serial port setup to set up the computer s ports to simulate the serial ports on the Qlarity based terminal The terminal s available serial ports are listed For informa tion on entering the number of serial ports on your terminal see section 6 1 3 To specify the PC port that you want to use for the simulation and to set up the port s configuration select the terminal port from the list and click Modify Serial Port Settings or double click the port The follow ing dialog box is displayed Simulation Port Settings Setup terminal senal port con for simulation 15200 Data Format 0 7 on Flow Control Mone Simulate on lt None gt CS PC Seral Port Baud Rate Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Baud Rate From the drop down list select the initial baud rate of the PC port selected in Sim on PC Port Data Format From the drop down list select the data bits parity and stop bits of the PC port selected in Sim on PC Port Flow Control From the drop down list select the flow control of the PC port selected in Sim on PC Port 51 Simulate on PC Port From the drop down list select the serial port on your PC that you want to use to transmit data in Simulation View If this option is
132. enu to compile the current workspace into the format required for a user application Compiling is also required to update modifications made in Code View before they can be seen in Layout View However if you make changes in Code View and then switch to Layout View the program compiles automatically If the compile is successful the program displays the appli cation in Layout View If any errors occur during the com pile the program switches to Code View and the error messages are displayed in the Compile dialog box Double click an error message to go to the location of the error in the code You can also select Goto Next Message from the Edit menu to select the next error message and view its location in Code View 4 6 Generate a BFF File Use this function to save a Qlarity workspace file to binary file format BFF which is the application format required by the terminal When you use the Download Application option to down load the current workspace to the Qlarity based terminal Qlarity Foundry automatically compiles the workspace into a BFF file however the BFF file is not saved To save a workspace s BFF file so that you can download it at any time without loading the workspace in Qlarity Foundry do the following OptoTerminal Qlarity Foundry User s Manual 1 Load the workspace that you want to save to a BFF file 2 Select Generate filename bff from the File menu where filename is the name of the
133. erencing or changing the terminal s communication settings refer to the OptoTerminal Hardware User s Man ual 7 1 1 Serial Port Settings Click the Serial tab to set up a serial port Serial Ethernet Port ate Baud rate 115200 Data Format en Send string over senal connection nt ae Induce Set unit time bootloader Port From the drop down list select the port used to communi cate with the Qlarity based terminal e g Com1 Baud rate From the drop down list select the baud rate for the port e g 115200 Data Format From the drop down list select the data format for the port e g 8n1 7 1 2 Ethernet Port Settings Click the Ethernet tab to set up an Ethernet port Cerial Ethernet Download via ethernet IP Address of unit 255 255 255 255 Download to multiple IP addresses Recently used IP addresses E Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 54 IP Address of Unit Enter the IP address assigned to the Qlarity based terminal or select it from the drop down list of recently used IP addresses Download to Multiple IP Addresses If you want to download a user application to multiple ter minals on the network select this option Then click the Select IP addresses button that appears The Setup IP List dialog box appears Setup IP List 255 222 212 121 255 255 211 122 255 255 255 255 Cancel Cl
134. erminals Bitmap Size The size of a bitmap image is normally shown as the num ber of pixels in width by the number of pixels in height e g 25 x 10 The standard Qlarity based terminal display is 320 pixels in width by 240 pixels in height 320 x 240 Therefore you can easily determine what size to make your bitmap images so they will be in proportion to the size of your terminal Refer to your Qlarity based terminal specifi cations for its exact size Transparent Background You can specify that a color in a bitmap image become transparent in the workspace If you want the background of a bitmap image to be transparent in the workspace make the background a color that is not used in the bitmap then select the background color as the transparent color in the bitmap object properties in Qlarity Foundry Bright magenta and bright green are often used as transparent background colors 5 2 7 Fonts Qlarity based terminals support BDF raster and TrueType fonts Use the following guidelines to help you determine which fonts to use in a workspace Scalable and Non scalable Fonts BDF raster fonts are non scalable which means that you need to load a separate font file for each point size e g Arial 8 Arial 14 Arial 20 etc TrueType TT fonts are scalable which means that a single font can typically be scaled to several different point sizes Rotating a Font A TT font can be rotated to any angle A BDF font can only
135. esults box as shown below Error setting clock Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 58 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 8 BASIC DESIGN You can use Qlarity Foundry to design a user application using library objects and or existing object templates This basic design requires no special programming skills This chapter provides instructions for using Qlarity Foundry to design a user application using only the objects and templates provided as well as information on the basic concepts of the Qlarity programming language All Qlarity Foundry users should review and become famil iar with the information in this chapter If you want to learn more about using Qlarity Foundry and Qlarity program ming you can then proceed to Chapter 9 Intermediate Design and Chapter 10 Advanced Design This chapter provides the following information Prepare Qlarity Foundry for Application Design e Basic Design Layout e Simulate the Terminal Display e Drawing Aids Zoom Grid Snap etc e Add Remove Resources e Add Remove Libraries Understanding Qlarity for Basic Design e Workspaces and User Applications e Qlarity Objects e Parent Child Relationships e Z Order e Events and Messaging e Enabled Disabled Objects Design a User Application e Add an Object Instance
136. fault library code entries are locked and may not be edited To unlock a library code entry click the lock icon next to the entry name To aid in debugging a workspace software break points can be set in the library code 10 2 Validation Functions Validation functions are special functions that are closely associated with object properties or global variables When a property is assigned a value using the validation assign ment operator the associated validation function is implicitly called and passed the new value as a parameter This facility allows objects to appropriately respond to Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 90 property changes Validation functions are also called when certain API functions such as Val and SetObjProp are used to assign a value to a property Validation functions are also useful for assuring that the new value is valid or within an appropriate range hence the term validation function To associate a validation function with a property the func tion must have the same name as the property In almost all cases 1t must take a single parameter of the same data type as the property The name of this parameter can be any legal Qlarity variable name but it is good style to use a common name for all your validation functions see section 10 6 Guidelines for Designing New Object Templates Valida tion functions should not have a return
137. finition gt Where lt column definition gt has the following format lt column name gt lt column data type gt lt min value gt lt max value gt lt column width gt lt default value gt In lt column definition gt most items are optional but if you omit an item or include an item later in the list you must include placeholder commas lt column data type gt may be one of string integer boolean byte unibyte float or color For example Provides a grid with a single column for string entry flags Enter List Type some strings List Item string Provide a grid with several columns flags Enter Data Enter the title min value and color for each display element Item Title string 200 Minimum Value integer 0 100 50 Item COLOr COLO e507 In the first example a single column is defined for string entry In the second example three columns are defined a string column called Item Title which is 200 pixels wide an integer column titled Minimum Value in which values between 0 and 100 are accepted for entry the column will have a default width based on the column title and the default value for the integers will be 100 and the final col umn Item Color will be of default width and its type is color There are no restrictions on what colors may be selected but the default color is 3 blue B 10 Sample Code You may specify sample Qlarity code for any item you are do
138. g a resize grip within Qlarity gt Foundry handleNum is the index into the gt arrays that were returned by the handler gt for MSG_TOOL_GETHANDLES You should gt return true from this function func ToolMoveHandle handleNum as gt reference to integer dx as integer dy gt as integer handles MSG_TOOL_MOVEHANDLE dim newX newY newWidth newHeight gt tmp as integer newX xPos newyY yPos newWidth width newHeight height if handleNum 0 then newX xPos dx newWidth width dx newY yPos dy newHeight height dy elseif handleNum 1 then newY lt yPos dy newHeight height dy elseif handleNum 2 then 99 newY yPos dy newHeight height dy newWidth width dx elseif handleNum 3 then newWidth width dx elseif handleNum 4 then newWidth width dx newHeight height dy elseif handleNum 5 then newHeight height dy elseif handleNum 6 then newX xPos dx newWidth width dx newHeight height dy else newX xPos dx newWidth width dx endif if newWidth lt 1 then newX newX newWidth 1 newWidth newWidth 2 tmp handleNum mod 4 if tmp O then handleNum handleNum 2 elseif tmp 2 then handleNum handleNum 2 else handleNum handleNum 4 mod 8 endif endif if newHeight lt 1 then newY newY newHeight 1 newHeight newHeight 2
139. g options are available None AutoHelp will not offer assignment and parameter comple tion assistance 47 Standard AutoHelp will appear whenever it seems likely hat you are editing the right hand side of an assignment or a parameter to a function or method call and AutoHelp has information about the current context High AutoHelp will always attempt to appear when the cursor is in the context of the right hand side of an assignment or a parameter to a function or method call and AutoHelp has information about the current context AutoHelp for assignment and parameters will always dis play constant values for user defined data types You can also configure AutoHelp for assignment and parameters to display additional items if desired 6 3 8 4 Show Global Variables and Functions Select this option if you want AutoHelp to add appropriate global variables and functions with return values to the lists displayed 6 3 8 5 Show Object Properties and Methods Select this option if you want AutoHelp to add object prop erties and methods to its lists This option may make the completion list quite large 6 3 8 6 Show for Built In Data Types By default AutoHelp does not show completion results for built in data types such as integer and float Select this option if you want AutoHelp to show the completion results for built in data types 6 3 8 7 Fade AutoHelp Tips Only available in Windows 2000 and Windows XP Select t
140. generates an exception An application may also throw an exception when it detects a problem The Qlarity exception handling system allows the exception handling code to be localized to a convenient location either within an object template or for the applica tion as a whole This section describes the facilities that Qlarity provides for generating and handling exceptions An exception is generated in one of two ways the system software throws an exception if it detects a problem or the application can throw an exception for any reason The application exception is thrown with a call to the Throw API function Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Each exception carries certain information regarding what occurred and where This information includes an exception level an indicator of severity an exception type a location where the exception occurred and a brief explanation of the error The exception level can assume the following values in order of decreasing severity EXLEV_COMPILER This level indicates a serious error most likely caused by the Qlarity compiler EXLEV_SYSTEM This level indicates a problem in the system software such as memory exhaustion a problem with the message queue and so on EXLEV_IGNORABLE This level indicates an unexpected condition that is gener ally serious but not fatal EXLEV_USER This is the ex
141. h a serial port There are two methods for adding message handlers in the Global Code space as fol lows e Use the Message Handlers drop down list at the top of the Code View window easiest method Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual e Enter the message handler directly into the Global Code section in the Code View window 9 5 3 1 Add a Global Message Handler From a List Do the following to add a global message handler from the Message Handlers drop down list 1 Click the Code View tab 2 Click Globals in the Object Tree to open the Global Code section Any current global source code is dis played in the editor window 3 If you want the message handler inserted at a cursor location select Insert at Cursor then click in the edi tor at the location where you want the handler inserted If you do not select this option the handler will be added to the bottom of the Global Code section 4 Click the drop down arrow at the Message Handlers box and select the message from the list The message handler code is inserted in the editor If the message handler is for a registered message such as the MSG_TIMETICK or MSG_COMM_RECEIVE message make sure you add code elsewhere e g the MSG_INIT message handler to register to receive it 5 A blank line is inserted in the message handler func tion Enter the user code at
142. hapter 10 Advanced Design Each object instance may be customized by changing the values of the properties and by overriding methods defined in the template A method override is a function defined in the object instance that replaces the method of the same name defined in the template for the specific instance only If the functionality of the template method is desired it can still be called from inside the override method Customizing object instances by changing their initial prop erties requires no programming and is discussed in Chapter 8 Conversely overriding methods does require some programming and is the main focus of this chapter 9 3 Qlarity Code for Objects The following sections describe the Qlarity code used to define an object and the method overrides in an object tem plate 9 3 1 Property Initializations Code for a typical object includes several lines in the fol lowing format init lt propertyname gt lt value gt lt propertyname gt This is the name of one of the object s properties lt value gt This assigns the initial value for the property in the applica tion If a property is not shown it is assigned the default ini tial value from the object template Changing lt value gt in one of these statements is the same as changing the property value in the Properties window 9 3 2 Method Overrides Most methods defined in an object template may be over ridden in any ins
143. he code and click OK when you are finished to save the changes The Edit Library Entry window has a File menu and an Edit menu with the standard save edit and find options The File menu also contains the following option Save changes to library as hidden code This option gives the developer the option of hiding the source code in the library Once the source code is hidden it cannot be viewed or edited 35 WARNING Make a copy of the source code before using the Save changes to library as hidden code option Once saved to the library 1t can no longer be viewed or edited by anyone 5 3 3 2 Rename Entry Click an entry in the list to select it then click Rename Entry to change the name of the selected entry A dialog box is displayed for you to type the new name Click OK to apply the change and close the dialog box 5 3 3 3 Remove Entry Click an entry in the list to select it then click Remove Entry to remove the selected entry from the library A mes sage is displayed warning you that this will permanently remove the entry from the library Click Yes to remove the entry 5 3 3 4 Set Entry Version Click an entry in the list to select it then click Set Entry Version to change the version number of the selected entry A dialog box is displayed for you to type the new number Click OK to apply the change and close the dialog box 5 3 3 5 Add New Entry A library contains two types of entries e
144. he most out of Qlarity Foundry and describes Qlarity Foundry Installation This chapter covers the installation and setup of the Qlarity Foundry software Getting Started This chapter outlines Qlarity Foundry s features and functions Workspaces This chapter explains how to start open close save and use workspaces in Qlarity Foundry Templates Resources and Libraries This chapter explains how to add and edit templates advanced func tion edit resources and edit libraries Qlarity Foundry Preferences This chapter explains how to set up and define your terminal settings for Qlarity Foundry and enter Qlarity Foundry preferences Download Software to the Terminal This chapter explains how to configure the terminal communications port download user applications and BFF files and upgrade new firmware Basic Design This chapter explains how to get started using Qlarity Foundry and covers user application design basics Intermediate Design This chapter provides instructions a step beyond design basics Advanced Design This chapter provides instructions for advanced user application design Glossary of Software Terms This appendix provides definitions of the terms used in Qlarity Foundry AutoDoc Specification This appendix contains the complete specification on how to write AutoDoc meta data to document the source code in a workspace and Qlarity libraries Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO
145. hich the programming is already done To adapt a library object to a user application you typically only need to enter properties e g name location color bitmap etc If custom programming is required Qlarity Foundry contains the tools you need to modify library objects or create your own objects Qlarity Foundry provides all the tools you need to work with user applications including those used to do the fol lowing e Create a user application basic to advanced levels e Modify a user application e Compile and download a user application to the Qlarity based terminal Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 2 INSTALLATION This chapter provides instructions for installing and setting up the Qlarity Foundry software 2 1 System Requirements Computer Requirements e Pentium 166 or better e 32 Mbytes of RAM 64 Mbytes recommended e 30 Mbytes available hard disk space Operating System Requirements Microsoft Windows 95 98 2000 NT or XP 4 0 or later Qlarity Foundry will not run in Windows 3 x or DOS Windows 95 requires Internet Explorer 4 01 or higher Win dows NT requires Service Pack 6 2 2 Install Qlarity Foundry To install Qlarity Foundry take the following steps 1 Close any open Windows applications 2 Insert the
146. his option if you want the AutoHelp display window to fade out as the mouse pointer approaches it This allows you to view the code under the AutoHelp window without clos ing AutoHelp 6 4 Compile Before you download a workspace to the Qlarity based ter minal it must be compiled into the format required for a user application Compiling is also required to update modi fications made in Code View before they can be seen in Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 48 Layout View Click the Compile tab to set up the options for compiling Qlarity Foundry Preferences x Terminal Layout Editor Compile Simulation Unicode support 7 Limit BOF Fonts to ASCII chars al i conserves terminal memar Enabled warnings Syntax error Parse error Internal compiler error Undefined reference Redetinition error legal native usage Unresolvable reference legal value Validation function error Override Function error p E Enable Unicode support in the standard objects M Start in Layout view Enabled Warnings All possible warning messages that may appear when com piling a workspace are listed Click the checkbox to select each warning that you want displayed after a compile When you first start programming in Qlarity Foundry you probably want to display all warnings however if you are an advanced user you may find some of the less serious warnings to be unnece
147. however you may want to remove any unused default bitmaps and fonts before you download the user application to the Qlar ity based terminal to conserve the terminal s flash and RAM memory Click amp on the toolbar or select Edit Resources from the Edit menu and the Edit Resources dialog box is displayed Edit Resources Bitmaps EDF Fonts TrueType Fonts Audio Binary Bitmap name Sys Filename Alarm resources alarm bmp all resources all bmp bottomLeft resources bottomlett bmp bottornright resources bottomright bmp lightotf resources lightott brp lighton resources lighton bmp Temp resources temp bmp topleft resources toplett bmp topright resources topright bmp Resource data Preview Filename No selection Browse Rename bitmap Mew bitmap Remove Gite cos 2 All resources used in a workspace are managed from this dialog box Click the tab for the resource type you want to manage then follow the procedures in the following sections as applica ble to add a new resource rename an existing resource change the file for an existing resource name or remove a resource from the workspace Additional information on each resource type is also provided in the following sec tions After you have finished adding editing or removing resources click OK to save your changes and exit the Edit Resources dialog box The workspace is compiled Resources that you added are availab
148. ib Cancel Ze 2 Enter a file name for the new library e g mylib and click Save The extension ib is added automati cally The following dialog box is displayed larity Foundry Enter a name for the library Jnewlib Carosi 3 Enter a descriptive name for the library e g arch library or Johns library and click OK The new library file is created and added to the Qlarity Foundry folder Use the Edit Library function to add entries object templates and resources to the library see section 5 3 3 5 Add New Entry for information You can also add new object templates to a library using the Send Template to Library option in Add Edit Templates see section 5 1 5 for information OptoTerminal Qlarity Foundry User s Manual 5 4 Edit Named Colors You can use named colors and themes to simplify the process of assigning fill and line colors to objects Rather than manually selecting a color from a palette for each property of an object you can assign one named color to one or more properties of an object and to any number of objects in the workspace This improves color matching and helps to control the range of colors used For example you can assign a named color to several objects and then change the color of all those objects at the same time by simply changing the color of the named color You can also assign colors to properties without using named col
149. ich displays any errors or other messages gener ated when the workspace is compiled or during a debug operation These messages can help you identify and correct problems with the workspace Object Tree Select this option to show or hide the Object Tree Refer to section 3 8 for information Object Palette Layout View only Select this option to show or hide the Object Palette Refer to section 3 12 for information Properties Window Layout View only Select this option to show or hide the Properties window Refer to section 3 11 for information Communications Simulation View only Select this option to show or hide the Communications win dow in Simulation View Refer to section 3 10 1 for infor mation Keyboard Simulation View only If you will be using keyboard input select this option to show or hide the Keyboard Entry window in Simulation View Keypad Simulation View only If you will be using keypad input select this option to show or hide the simulated keypad in Simulation View NOTE keyboard keypad input devices The Keyboard and Keypad options are only available if you have selected Keyboard or Keypad as an input device in the Qlarity Foundry Preferences Terminal tab see section 6 1 Watch Window Simulation View only Select this option to show or hide the Watch window in Simulation View Refer to section 3 10 5 for information Call Stack Simulation View only Select this option t
150. ide it by clicking Object Pal ette on the View menu OptoTerminal Qlarity Foundry User s Manual 3 12 1 Add a New Object Instance Do the following to add a new object instance from the pal ette 1 Click the icon of the object instance you want to add 2 Move the mouse pointer to the work area The pointer changes to a cross hair 3 Click and hold the mouse button and drag the mouse to draw a rectangle in the work area Then release the mouse button Some objects have a default starting size and shape so the size of the rectangle doesn t matter only its posi tion in the work area The size of other objects such as a line or rectangle is initially determined by the size of the rectangle you draw NOTE add multiple instances of the same object type To add more than one instance of the same type of object press and hold the lt Shift gt key when you click the object icon The object type remains selected and you can just click and drag in the workspace to add objects until you release the lt Shift gt key 4 After you add an object it remains selected and its properties are displayed You can then edit the proper ties as required including assigning the object a unique name To resize an object do one of the following e Use the mouse If the object has resize grips sizing handles you can click and drag any handle to resize the object Resize Grips e Use the Properties window Change the
151. ift the displayed area slightly Click OK to close the workspace image and the color you selected is shown in the Select Color palette Click OK at the Select Color palette to apply the selected color to the property 4 Event Builder Qlarity is an event driven programming language An event is any type of input such as a key or button press a value change a timer action data received through the serial port and so on When an event occurs a Qlarity user application responds with an action Event Builder is a tool in Qlarity Foundry to help you add events to your Qlarity user applications Event Builder allows you to assign actions to events without any program ming knowledge Using the options in the Event Builder dialog box you can link one or more actions to an event even when the action involves several objects or includes one or more serial objects You assign an action to an object and its properties from drop down lists The type of object you select determines the type of event or events that can be performed by the object For example a OptoTerminal Qlarity Foundry User s Manual button will have a click event and a serial object will have data receive and send data events Keep this in mind when you are adding objects to your workspace The Object Documentation Help file lt F1 gt provides informa tion about all object templates in the QSI libraries includ ing events and actions
152. iner object and the object instance is automatically moved and attached to the selected object in the Object Tree To move an object to the root container click default in the drop down list 8 3 3 1 Select Color If a color can be selected for an object property e g bor ders fill foreground background font etc when you select the property two Select buttons are displayed and 4 69 Click to display a drop down list of available named colors in the workspace You can use named colors to sim plify matching and coordinating colors to create a color scheme for the workspace Refer to section 5 4 for informa tion on named colors bgcolor MN cl_buttonbackgro 1 A M clr_buttonbackgro checkfgcolor borderstyle check borderstyle ransparent clr_buttonbackgro clr_buttonback gro General parent cl buttonforegrou MM cl_buttonforegrou 5 E pos cl_fillcolor idth eight ch_labelforeground Inactive a a cl_screenbackgr Ses cl_screentoregro F hize fed cl_softkeybarbac cl_softkeybarbutt w ext Settings aay ch sottkeybarbuth ch_labelback ground inset Hire Click a named color to select it for the object property Click _ to display a Select Color palette from which to choose a color for the property Select Color Named Color Custom Color Clr_ButtonBackground Cir_ButtonBackground lt e Clr_ButtonForeground EE Cir_Butt
153. ion e Show Grid show hide grid e Snap to Grid enable disable snap to grid e Grid Spacing set the spacing of the grid lines e Colors Grid set the color of the grid lines 8 1 4 Add Remove Resources Resources include all bitmap images fonts audio files and binary data files available in a workspace and eventually in the user application You must add resources to a work space before you can use them in object instances Use the Edit Resources option to add resources to your workspace or to change or remove the resources used Because resources become part of the user application when it is compiled you should delete any unnecessary resources NOTE default bitmaps and fonts When you create a new workspace you have the option to add default bitmap images and fonts to your workspace Some objects may require at least one bitmap BDF font or TT font resource before the object will function properly When you have finished creating a workspace however you may want to remove any unused default bitmaps and fonts before you download the user application to the Qlar ity based terminal to conserve the terminal s flash and RAM memory Click amp on the toolbar or select Edit Resources from the Edit menu and the Edit Resources dialog box is displayed Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 62 Edit Resources x Bitmaps BOF Fonts TrueType Fonts Audio Binary
154. isplayed Click in the area of the work space that has the color you want to match The color of the area you clicked is shown in the Sample box In addition the 4X box displays the area magnified four times T zm dy ICT Cancel You can click a color in the 4X box to select it This is useful if you want to identify a color in a congested area of the display You can also click in the 4X box and drag the mouse to shift the displayed area slightly Click OK to close the workspace image and the color you selected is shown in the Select Color palette Click OK at the Select Color palette to assign the selected color to the border Fade Effect If you have defined a wide border you can select Fade Effect to add a fading color effect to the border Refer to the preview for an illustration of the fade effect 41 5 5 2 2 Rounded Corners Select Use rounded corners to round the corners of the border Then enter or click the arrow buttons to select the radius of the corners in number of pixels The greater the number of pixels the more rounded the corner 5 5 2 3 Double Border Select Use a double border to create a double border Then enter or click the arrow buttons to select the width of each border in pixels 1 3 5 5 2 4 Preview The options in the Preview section including Object Fill Color and Background Color allow you to experiment with color combinations but have no effect on the
155. itB ox Source 0 00 coreF astLabel Source 2 20 corel auge Source 2 10 corelnputS upport Source 2 20 Add New Entry corek eppad5pinner Source 2 20 coreLabel Source 0 00 core umber eypad Source 2 20 corePathtrace Source 0 10 corellwertkeypad Source 2 20 O K coreSlider Source 2 20 as Do not modify these functions as objects in various librar ies also use them In addition any changes you make to Natives library functions are overwritten when you upgrade Qlarity Foundry Refer to section 5 3 3 Edit Library for information on editing functions 5 3 4 2 Edit Core core qlib qhide The Core library contains core object definitions that are used as a base for extension Many standard Qlarity objects extend templates in this library Objects in the Core library do not appear in the Object Palette Select this option to ref erence code in the Core library 5 3 4 3 System Libraries That Are Not Explicitly Included in This Workspace A system library is one that resides in the same directory as the OlarityFoundry exe executable file Some system library template code may rely on templates in other libraries This is common when extending templates If the other libraries are not available to the Qlarity compiler compile time errors will occur The drop down list at this field contains options to indicate how to include system libraries that are not specified in the workspace Do not include If you select thi
156. ject receives a MSG_TOOL_DRAGCREATE mes sage from Qlarity Foundry This allows the object to initial ize itself properly For a non drawable object the only parameter passed to the handler is an objref referencing the parent object The handler updates its parent property and calls Tool_Persist Note that the MSG _INIT handler is called from the handler to complete the object initialization Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 98 The tool message handlers for containers and area objects are identical In addition to the handlers described above the boilerplate code for these object types includes handlers for the MSG_TOOL_MOVE MSG_TOOL_GETHAN DLES and MSG _TOOL_MOVEHANDLE messages Also the MSG_TOOL_DRAGCREATE handler is larger and more complex than the handler for non drawables The MSG _TOOL_ATTACH and MSG _TOOL_AT TACHED handlers are identical to the handlers in the non drawable code so they are omitted here The code for the MSG_TOOL_MOVE handler is as follows This function is Called when the user gt drags an object instance with the mouse gt in Olarity FPounery dx and dy are gt relative offsets from the current gt location of the object func ToolMove dx as integer dy as integer handles MSG_TOOL MOVE XPOS xPos dx yPos yPos dy Relocate me xPos yPos Save the changes we just made xPos yPos Tool_Persist Too
157. l s l E ah FullScreenColorLbl Powerful E en creation of Tem al FTPServer 2 ee i z yf HideFullScreenColorLblT Stil Image sd Graphics ee St af Owertykeypad mia 2 af TranslucentColorPicker lle Nagnostics Er E af BacklightDownBtn Hings Sample text A IN ml E acklightUpeEtn aia n Object Properties z gt alte rete j Don i Help EEK Properties Events Eth af EndGames name lt Globals gt a af of HelpSideButtonsS cr ha mE e ObjectsSer HE af GraphicsSer ESEL 53 DiagnosticsScr 90 af FunScr HE af NavScreen eu Bl gt af Templates cr wE SplashScreen EN af ScreenSaver 2 E of ScSaverOn a e af Scrsaverdl a E of Scr2Home 9 E f Scr2Hext e af Cur DDL_ListB ox zs meee Paral Piao Ti a 85H E gt 0 Jg j f Al ie2oahad a Be oO cE ke EB lo gt O ga E s E E E 156 10 All four windows are open by default If one is inadvert e Display setup including landscape portrait and gray ently closed you can open it from the View menu scale color e Keyboard or valid input devices type of key input used NOTE workspace appearance variations wiih yonr terminal In the illustration above and elsewhere in this chapter the objects in the Object Palette and Object Tree may differ e Touch key legend border around the edge of the touch from what you see in Qlarity Foundry Object names may scr
158. l_Persist endfunc When the user drags an object in Layout View the object dragged receives MSG_TOOL_MOVE messages from Qlarity Foundry The change in position is passed to the handler in the dx and dy values The object updates its xPos and yPos properties to the new location and calls the Relocate API to generate a MSG_DRAW that updates the screen if necessary Finally the handler persists the values of the updated properties with calls to Tool_Persist The code for the MSG _ TOOL GETHANDLES handler is as follows This Funectton hs called by Olarity gt Foundry to obtain the coordinates of the gt resize grips The arrays xCoords gt VCOOrds and cursors all contain 10 gt elements initially This means that you gt should either call redim on those arrays gt and set their values or declare local gt set the values of the local gt arrays and th n assign kCoords yCoords gt arrays and cursors to those local arrays gt Closed indicates whether the Foundry gt should connect the Tirst and last Grips gt OptoTerminal Qlarity Foundry User s Manual to make a closed object xCoords gt Coords amd Cursors should all Conical gt the same number of elements when this gt function completes func ToolGetHandles reference to integer yCoords Cursors xCoords as gt as reference to integer
159. le for use in the Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual objects and resources that you removed are no longer avail able Save the workspace to save the new information to disk NOTE button labels The labels on the buttons used to edit resources change to match the resource tab you selected For example you click New bitmap to add a bitmap image New BDF font to add a BDF font and New audio resource to add an audio file The label on the Rename button changes to the name of the resource you selected to rename 5 2 1 Add a Resource In the Edit Resources dialog box do the following to add a new resource to the workspace 1 Click New resource type e g New BDF Font and an Open dialog box appears Resource files in the default folder are listed change folders 1f necessary 2 Select the resource file or files that you want to add NOTE select multiple files To select multiple files that appear consecutively in a list press and hold lt Shift gt then click the first and last file in the group you want to select To select multiple non consecu tive files press and hold lt Ctrl gt then click each file that you want to select 3 Click Open The resource is added to the list of resources When you add a resource it is given the name of the file by default The resource name is the name that appears in the Pro
160. le_light lt value gt is a numeric color value cOlormap Clr_LabelBackground standard 38 etasstces 183 cOlormap Clr_LabelForeground standard 255 Classic s 0 colormap directives are standalone directives and not part of any other doc directive These directives may not be broken over multiple lines Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 110 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786
161. lected object with the left most resize grip of the active object Align center horizontal Aligns the horizontal center of each selected object with the center of the active object Align right Aligns the right most resize grip of each selected object with the right most resize grip of the active object Align top Aligns the top most resize grip of each selected object with the top most resize grip of the active object Align center vertical Aligns the vertical center of each selected object with the center of the active object Align bottom Aligns the bottom most resize grip of each selected object with the bottom most resize grip of the active object Make same width Changes the width of each selected object to the width of the active object All objects must have a width property Make same height Changes the height of all selected objects to the height of the active object All objects must have a height property Space evenly horizontally Finds the left most and right most objects among the selected objects and positions the remaining selected objects evenly between them This option works best when all objects are the same width Space evenly vertically Finds the top most and bottom most objects among the selected objects and positions the remaining selected Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 68 objects evenly between them This option works best when all obj
162. les using the PlaySound API function 5 2 9 Binary Binary resources are files that you want to add to your user application unchanged For example you could use a binary resource in your application if you wanted the Qlarity based terminal to communicate with an embedded device with no PC connection You could for example add a configura tion or firmware file to the application as a binary resource file and then use the GetBinaryResource API function to download the file from the Qlarity based terminal to the embedded device when the application is running 5 3 Edit Libraries Object libraries are provided by QSI and other sources to assist you in designing user applications Each library con tains several predefined Qlarity objects This enables you to add object instances to your workspaces without the need to program new object templates When you add a library to a workspace the objects in the library are added to the Object Palette and to the drop down 33 list in the Instance Properties dialog box right click any where in the Object Tree and click New Object Instance NOTE default libraries When you create a new workspace you have the option to add default libraries to the workspace You can remove a default library or add new libraries to the workspace using the Edit Libraries option NOTE library object templates Object templates in libraries are not listed under Tem plates in the Object Tree
163. lication The Rescale Application feature should be used with care The changes cannot be undone so it is recommended that you save a backup copy of your workspace first Also res caling an application is just the first step in migration You should examine each object in the workspace after the rescale has occurred to ensure that it scaled correctly Toggle Breakpoint Code View and Simulation View Select this option to set or remove a breakpoint in Code View or while running a simulation New Variable Code View only Select this option to insert a new variable or property in the code A dialog box is displayed to specify the attributes of the new variable or property Mark Selected Code as Sample Code View only Select this option to flag or unflag selected code lines as sample code Sample code is a form of comment used by the AutoDocumentation system in Qlarity Foundry Sample code is ignored by the compiler and appears grayed out in Qlarity Foundry Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Run Simulation View only Select this option to continue running the simulation after it has paused or stopped Single Step Simulation View only Select this option to execute the current line and stop on the next line Step Into Simulation View only Select this option to step into a function call If no function is on the current line this a
164. lider is moved 8 4 4 2 Toggle Demo The Toggle Demo toggles a spinner on and off When on a spinner object is displayed that allows a user to increase decrease the value shown The Status_toggle object the button uses the following events TurnOn triggers the following actions e Changes the caption above the toggle button to reflect the current status of On e Enables the spinner object Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual TurnOff triggers the following actions e Changes the caption above the toggle button to reflect the current status of Off e Disables the spinner object 8 4 4 3 Keypad Demo The Keypad Demo provides a keypad that can be used to enter numerical data to be sent to a controller The follow ing objects have programmed events Enable_button A press or click event enables the numeric keypad makes it viewable so it can be used for data input Numeric_keypad The following two actions have been programmed to the keypad e When the lt Enter gt key is pressed any data entered the value is posted to the Keypad_value text box located above the keypad e When the lt Enter gt key is pressed the value is sent out the serial port to a controller expecting a value 8 4 5 Qlarity Code and Event Builder While Event Builder requires no programming experience 1t uses the Qlarity progr
165. ly determined by the size of the rectangle you draw If you are adding a non drawable object the location in the work area doesn t matter since the object is not part of the display You may want to use the shortcut menu to add a non drawable object in its default position see section 8 3 1 2 Add an Object From the Shortcut Menu for information NOTE add multiple instances of the same object type To add more than one instance of the same type of object press and hold the lt Shift gt key when you click the object icon The object type remains selected and you can just click and drag in the workspace to add objects until you release the lt Shift gt key 4 After you add an object it remains selected and its properties are displayed Click the Name property and type a name for the new object type over the default name Each object in the workspace must have a unique name An object name has no size limitation but must start with a letter A name cannot contain spaces but may use the underline character _ The percent pound and dollar sign symbols can be used at the end of the name Refer to section 8 3 2 for information on moving resizing and changing the order of objects 8 3 1 2 Add an Object From the Shortcut Menu Do the following to add a new object instance from the Object Tree shortcut menu 1 Right click anywhere in the Object Tree to display the shortcut menu 2 Click New Object
166. mmunications Pr is 53 Mihaly S aL EOC SSN Saee a a r a aa dd 53 1 27 Ethemet Port Setna Seanin li li a 53 L2 Download a User Applica ON usd llas 54 lez Prepare the Terminal tor Dow mlOagdimg a A A oc 54 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 Iv OptoTerminal Qlarity Foundry User s Manual 22 Download the Ser Application ia 54 TS Downloada BEET ches iiss snchtananscuctie E ea esate onanannatandnwendevatesetuaa a S 55 Ty porade LMS A A a aa S 55 TA Determine Current Firmware Vers ON tic 55 TA Prepare Terminator Upe rade one e E O T 56 145 Downoad New PIN A A ias 56 TAA Induce DOC HO Adepto EAA EE A ETA 56 MES OCCU OIE AIG ardia aE A AE AEE A T O EE 57 CHAPTER 8 BASIC DESTEN EE AAA A E AA AREAS 59 8 1 Prepare Qlarity Foundry for Application Design ccccceessseeseesssseeseeceseeeceeeeeeeeeeeeeeeeeeeeeeeeeeeeeseeeeaaaaaaaaeaaaaaaaaaags 59 Sls Basic Des oii LAvOUL Aoi 59 1 2 Simulate the Terminal Dipa yenen ic solis sedal 60 US A O 61 4 Add Remove RESOULCOS o de 61 Sl Add REMOVO LIBA S docs coee 62 8 1 5 1 Libraries Provided with Qlarity POUndi ld 62 9 2 Understandine Olarity Tor Basie DESIOM estrotanenae inet cabinas 63 9 2 1 Workspaces and User Applications dad iii 63 52 Ola ODIOS li ias ets 63 9 2 Paren Cha Re lan nips laa 63 E IL RO 64 82 Vents cand Messa lloc 64 5210 Eta bled Disabled OD ect tna 65 3 Desisna User Application A a 65 O AAA Senbnboens era
167. nce the message handler was called by the system in response to an event the call cannot be traced further than this function For example suppose a Qlarity statement in function Foo causes an exception Foo is in turn called by a func tion named Bar Bar is a handler called by the system in response to a message When the exception occurs the Qlarity execution engine first checks the function Foo to see if the offending statement is enclosed within a check error block If it is execution jumps to the first statement in the on error block that follows the check error block If it is not enclosed in a check error block the Qlarity execution engine then checks the Bar function to deter mine if the call to Foo was enclosed in a check error block If it is execution jumps immediately from the offending statement in Foo to the first statement in the corresponding on error block in Bar If no enclosing block is found in Bar the system handles the exception as described below Unhandled exceptions are maintained in a LIFO last in first out stack by the system software If multiple unhandled exceptions are pending a call to GetException always returns the most recently thrown exception on the stack If no enclosing check error block is found an exception remains in the system exception stack until the current mes sage completes processing The handler that caused the exce
168. nd to a given event These override functions often take no parameters and have no return value so they are easy to remember and use For example many button type objects have a Click function that is called from the han dler for a touch screen press and release This function is empty by default but it provides an interface for each object instance to customize its response to a press or release event Keep the MSG_ DRAW handler small Drawing requires the most computations on the Qlarity based terminal The MSG_DRAW handler for an object should be as concise and efficient as possible Where con OptoTerminal Qlarity Foundry User s Manual venient data needed for drawing should be pre calculated and stored in private properties for later use in the MSG_DRAW handler Use user messages to communicate between objects User messages provide an excellent way to communicate between objects because the sending object does not require any knowledge about the receiving object This fea ture allows Qlarity to be extended in a number of powerful ways 10 7 Where to Go From Here The full power and potential of the Qlarity programming language is now at your disposal As your experience with Qlarity grows you will likely create objects that might be useful for others QSI encourages Qlarity programmers to submit their object template designs to the Qlarity Web site www qlarity com where they can be shared with others Questions an
169. ne on newline characters M Favor wrapping lines on word breaks Show only transmitted data M Add a tab for each opened network channel i On network channel open switch to its tab lI Mon prntable character Default Space character e Newline and carage return Default Default 1192 Maximum buffer size Default eug Cancel The default settings are generally adequate for most users but you can change any of the following settings Display as hexadecimal If this option is enabled while in Simulation View data transmitted by the Qlarity based terminal appears in the Communications window in hex format rather than text e g ABCD appears as 41 42 43 44 Wrap line on newline characters Enable this option if you want characters in the Communi cations window to wrap to the next line when a newline character is encountered Favor wrapping lines on word breaks If Wrap line on newline characters is enabled select this option to wrap to the next line after a word rather than between characters in a word whenever possible Show only transmitted data If this option is enabled the Communications window will display only data that is transmitted from the application program Disable this option to show both data transmitted both received by the application Add a tab for each opened network channel If this option is enabled each time a network channel is opened in Simulation View a new ta
170. not com pile Click Yes to rename the named border After chang ing the name click OK to save the change You cannot rename the default named borders Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 42 OptoTerminal Qlarity Foundry User s Manual 5 5 2 8 Reset Border to Default To restore the originally assigned attributes to a theme s default named border select the named border you want to reset and click Reset border to default Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 6 QLARITY FOUNDRY PREFERENCES Use the Settings option to record the display configura tion of your Qlarity based terminal and to enter Qlarity Foundry preferences Qlarity Foundry requires this infor mation to simulate as accurately as possible the terminal display The Settings option is also used to set up options for the code editor Code View and to enable or disable warnings and other defaults for compiling Click on the toolbar or select Settings from the Tools menu and the Qlarity Foundry Preferences dialog box is displayed Glarity Foundry Preferences Terminal Layout Editar Compile Simulation Hardware Configuration Assistant Base Terminal OTERM G70 Display Setup Impr Keyboard Keypad Select Communications pa of serial ports 2 Misc Manufacturer ID MID 65535 IM TouchScreen Dimen
171. notes an object method that is explicitly intended to be overridden in object instances Only object methods designated as override may be edited in the Event Builder Type A user defined data type such as an enumeration or a start type Group This does not correspond directly with a Qlarity syntax structure rather it designates a collection of related items For example DrawBDFText GetBDFTextSize and GetB DFFontMetrics might all belong to the group BDF Text Functions When AutoDoc displays the documentation for items that belong to the group it contains a see also link to the group itself The documentation for the group dis plays a list of all items in the group Group names may con tain multiple words and are not restricted to the Qlarity naming rules B 2 Documentation Body A documentation declaration is usually followed by one or more documentation body elements A documentation body element must begin with the tilde character and must begin a line Documentation body elements may optionally contain HTML tags for formatting purposes doc func VerifyState This function checks the state of persistent variables in the application and verifies that each contains a valid value lt BR gt lt BR gt This function lt B gt must lt b gt be called during a MSG_INIT message B 3 Linking Items You can link related documentation items using the follow ing syntax link lt element type gt lt
172. ns port on the Qlarity based terminal from which the data will be sent If you have only one select COM1 sendtoport This property receives the data string that is to be sent through the serial port Data can be sent to this property from a serial object configured in Event Builder see section 8 4 When the serial object s sendtoport property receives data it automatically sends the data followed by a semicolon out the port appendterminator This property determines whether a semicolon is appended to the end of all data sent out the serial port 8 5 2 Ethernet Objects To use the Ethernet port to send data add one or more Ethernet objects If you want to send data to multiple addresses on a network you can create a separate Ethernet object for each address or you can send to different addresses from a single Ethernet object by changing the net work address in the object instance as required Following are the properties of an Ethernet object Name Type a name for the new object type over the default name Each object in the workspace must have a unique name An object name has no size limitation but must start with a letter A name cannot contain spaces but may use the underline character _ The percent pound and dol lar sign symbols can be used at the end of the name enabled If the object is to be enabled select true from the drop down list To disable the object select false parent
173. nt theme the changes to the unsaved theme are not saved when you click OK 5 4 2 Named Colors NOTE named colors not supported for older objects Named colors cannot be assigned to objects in libraries from Qlarity Foundry versions earlier than 2 1 To create or edit named colors begin by selecting a theme from the Theme drop down list Named colors are saved in themes The colors assigned to all named colors for the selected theme are displayed Both the named color label and the color currently assigned to the named color are shown NOTE changes to named colors and themes Any change to a named color only applies to the currently selected theme If you are making changes to more than one theme make sure you click Save current border and color settings as theme before you change themes 39 When you have finished editing or creating named colors click OK to save the changes and exit or click Cancel to discard the changes and exit 5 4 2 1 Change Named Color To change the color assigned to a named color click the named color to select it then click a color in one of the color palettes The new color is assigned to the named color Click Save current border and color settings as theme to save the new color in the theme NOTE named color changed for all assigned objects When you change the color assigned to a named color it is changed for all objects and properties to which the named color is assigned 5 4 2 2
174. ntly configured If any configuration contains an error a message 1s displayed Edit in Code View Click Edit in Code View to view the event s actions as programming code If you understand the Qlarity program ming language you may use Code View to work with pro gramming code You generally only work in Code View if you are customizing actions or creating actions If you are learning Qlarity programming it may also be helpful to view the code to understand how an event is programmed Descriptions Code Preview Click Descriptions to display the Qlarity programming code for the actions in the Description column of the action table The button label changes to Code Preview Click Code Preview to switch back to a description of each action in the table 8 4 3 Select and Configure Actions A sample workspace eventbuilder qly containing events created using Event Builder is included with Qlarity Foundry For information on loading and using the sample workspace refer to section 8 4 4 Load Event Builder Sample Workspace The sample workspace is used in the images and examples in this section You may find it helpful to load the sample workspace and use it to view examples of the actions described in this section 8 4 3 1 Select Actions To select actions for an object s events do the following 1 In the open workspace e g eventbuilder gly select the object for which you want to set up an event e g Tank
175. o show or hide the Call Stack window in Simulation View Refer to section 3 10 4 for information Refresh Layout View and Simulation View only Select this option to redraw the graphics on the screen in Layout View Layout View Select this option to switch to Layout View Code View Select this option to switch to Code View Simulation View Select this option to switch to Simulation View 3 4 4 Tools Menu View Only Enabled Objects Layout View only Disabled objects are displayed in Layout View by default Select this option if you want to see only enabled objects in the work area NOTE disabled objects vs hidden objects Keep in mind that the enable disable option is different from the show hide option Disabled objects are not dis Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 10 played on the Qlarity based terminal hidden objects are displayed on the terminal unless they are disabled they are only hidden in Qlarity Foundry Refer to section 3 8 for information on the show hide option Stop Qlarity Interpreter When a workspace is compiled the Qlarity interpreter runs a portion of the user application in Qlarity Foundry Select this option to stop the user application from running For example if an object instance contains an infinite loop you will not be able to work in Layout View You can select this option to terminate the interpreter and switch to Code View s
176. o you can correct the problem NOTE error message The Qlarity interpreter may detect the infinite loop when it tries to run the application and display a prompt for you to stop the application Settings Use this option to open the Qlarity Foundry Preferences dia log box to define the Qlarity based terminal s configuration and to enter Qlarity Foundry preferences Qlarity Foundry attempts to simulate the terminal s display area input type and so on as closely as possible Refer to Chapter 6 Qlar ity Foundry Preferences for information Snap to Grid Layout View only Select this option to enable or disable the snap to grid function If enabled this feature forces objects to snap to the nearest grid point when added or moved The top left corner of an object s rectangle snaps to the nearest grid point when you release the mouse button View Grid Layout View only Select this option to show or hide the grid You can dis play a grid over the work area to help you more accurately place and align objects For information on changing the spacing or color of the grid refer to section 8 1 3 Drawing Aids Align Size Space Objects Layout View only This option provides several tools for aligning sizing and spacing objects in your workspace Select the object you want to manipulate then select the tool from the submenu Refer to section 8 3 2 4 Align Size Space Objects for more informati
177. of the object on the display Since the area object is drawable a MSG_DRAW handler is required to do the actual drawing The boilerplate version of this method is as follows Display the object This function will be called whenever gt necessary to show the object func Draw handles MSG DRAW SetFGColor RGB _WHITE SetBGColor RGB GRAY DrawBox POSp VEL OS XPOS width Ly gt yPos height 1 DrawLine xPos yPos xPos width gt ube yPos MESTRE 13 DrawLine xPos yPos height 1 gt XPOS widely iby yPos endfunc NOTE code formatting A statement is defined as a single line 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 This function sets the foreground color to white and the background color to gray It then draws a box using the object s properties to determine the location and size The two calls to DrawLine draw an X inside the box This code is easily modified to provide the desired drawing behavior 10 5 1 3 Container Objects The boilerplate code for a container template is very similar to the code for an area object template The MSG_DRAW handler is slightly different as follows OptoTerminal Qlarity Foundry Use
178. olAttack tattacito as ob rer handles MSG_TOOL_ATTACH Attach me attachTo endfunc This function is called in response to gt calling Attach primarily in a handler gt tor MSG TOOL ATTACH but possibly 10 gt other places as well_ func ToolAttached newParent as objref handles MSG _ TOOL ATTACHED Set our parent property to reflect gt who we are attached to and save parent newParent parent Tool_Persist Save parent endfunc This function is called when the user gt created an instance of this template by gt selecting it from the object palette and gt dragging it in the layout view The handler for MSG_INIT is not called gt automatically and 1 you Want ab gt called you should call 4t manually You should call Tool Persist on all the gt properties that you set up in this gt message handler func ToolDragCreate parentObj as objref handles MSG _TOOL DRAGCREATE parent parentObj Tool_Persist parent Call our MSG_INIT handler Startup 97 endfunc endir First note that all of the tool handlers are enclosed inside a Hf TOOL endif block This excludes the tool handlers when the application is compiled for the Qlarity based ter minal As noted in the comments the MSG TOOL_ATTACH message is sent to an object when it has been dragged onto a new parent in the Object Tree An objref referencing the new p
179. omputer to a Qlarity based terminal via the port serial or Ethernet To do this you specify an object and its property to receive the data in a user application This changes the specified property value to the received data value Use the following format to send data to a user application lt Object name gt lt property name gt lt value gt Do not include the angle brackets lt Object name gt The name of the targeted object instance lt property name gt The name of the targeted property must be entered exactly as it appears in the Properties window Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual lt value gt The value that you want to insert in the targeted property You can also request that an object s property value be sent back to the external device from a Qlarity based terminal by sending the object name and property as follows lt object name gt lt property name gt Do not include the angle brackets lt Object name gt The name of the targeted object instance lt property name gt The name of the targeted property must be entered exactly as 1t appears in the Properties window The value of the property followed by a semicolon is sent back out the terminal s port to the device making the query NOTE property value requests You cannot request property values for the following properties color bitma
180. on Add Theme Selection Listbox Layout View only Select this option to create a listbox object that can be used to dynamically select color and border themes for all OptoTerminal Qlarity Foundry User s Manual objects in the workspace See section 5 4 and section 5 5 for information on themes The current themes available to the workspace will be listed If you previously created a theme selection listbox and have not renamed the object when you select this option the previous theme selection object is replaced with a new one Add Theme Selection DropDownList Layout View only Select this option to create a drop down list object that can be used to dynamically select color and border themes for all objects in the workspace similar to a theme selection listbox but uses less display space See section 5 4 and section 5 5 for information on themes The current themes available to the workspace will be listed If you previously created a theme selection drop down list and have not renamed the object when you select this option the previ ous theme selection object is replaced with a new one Rescale Application Code View only When migrating an application from a terminal with a 320x240 display to one with a 640x480 display select this option to automatically resize the objects in your workspace based on the new display settings A dialog box is displayed to specify the changes you want to make NOTE no undo for Rescale App
181. on for the last thrown exception check the error type and respond appropriately to each type of anticipated exception If the error type is not what was anticipated the exception should be rethrown using the Rethrow API function This gives higher level exception handling code the opportunity to handle the exception if desired NOTE GetException Ordinarily GetException should be called only ONCE in an on error block In a global MSG_ERROR handler GetException is typically called repeatedly until all excep tions have been retrieved Details on the syntax of check error on error can be found in the Exception Handling section of the OptoTer minal Programmer s Reference Manual 10 5 Create a New Object Template To create a new object template in your application do the following 1 Click on the toolbar or select Add Edit Templates from the Edit menu and the Add Edit Templates dialog box is displayed You can also right click anywhere in the Templates branch of the Object Tree and click Add Edit Templates on the shortcut menu OptoTerminal Qlarity Foundry User s Manual Add Edit Templates Template Base Template New Template 2 Click New Template and the following dialog box is displayed New Template Wizard Create a template ready to operate in Qlanty Foundry a Create a completely blank template c Copy the code of an existing template in a library Ex
182. on in Layout View this handler is necessarily more complex than the handler in the non drawable boilerplate code The x1 y1 and x2 y2 coordinates that are passed to the han dler as parameters indicate the locations of the initial click and release respectively at the end of the drag The handler calculates the position and size properties of the object based on the values of x1 y1 and x2 y2 It also sets the parent persists the changed properties and calls the MSG_INIT handler to complete the object initialization The boilerplate handlers should suffice for most objects and the code is easily modified to suit unusual circum stances Writing these handlers from scratch can be tedious and error prone For this reason using the boiler plate code as a basis for new object template designs is rec ommended 10 5 3 Adding Object Template Documentation AutoDoc is a Qlarity Foundry feature that automatically documents the object templates included in a workspace All libraries provided with Qlarity Foundry as well as func tions variables and APIs are already included in Object Documentation and the optional extra pop up Help see section 6 2 Layout Press lt F1 gt or select Object Documentation on the Help menu to open Object Documentation To add documentation on global variables global functions objects methods or properties that you create you must add the proper doc code to your
183. onForeground lt M ci_FiiCotor EE Clr_LabelB ackground Clr_LabelForeground EE Clr_ScreenBackground Cl_ScreenForeground Em Cir_SoftkeybarB ackground Cir_SoftkeybarButtonB q E Clr_SoftkeybarButtonF g Cir_ButtonB ackgroundalt 2 Edit named colors Preview Cancel The list of named colors is also displayed in this dialog box The current color of the property is displayed beneath the palette If it is a named color the named color label is high lighted in the list If it is a color from the color palette it is selected in the color palette To edit a named color click Edit Named Colors Refer to section 5 4 for information on editing and creating named colors Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 70 Click either a named color or a color in the palette to assign a different color to the property If you want to match a color from another object in the workspace click 2 and an image of the workspace 1s dis played Click in the area of the workspace that has the color you want to match The color of the area you clicked is shown in the Sample box In addition the 4X box displays the area magnified four times Scar E de ICT Cancel You can click a color in the 4X box to select it This is useful if you want to identify a color in a congested area of the display You can also click in the 4X box and drag the mouse to sh
184. ontains a new icon rep resenting the new template By default the new tem plate s icon is the same as the icon for the library template that served as the basis for the new template except that the background color is different Icons for local templates in a workspace appear before library template icons 5 To edit the icon or change the name click on the toolbar or select Add Edit Templates from the Edit menu Click the template name in the Add Edit Tem plates dialog box then click Edit Icon Refer to section 5 1 2 Edit a Template Icon for more informa tion 9 7 Where to Go From Here This chapter introduced the basics of programming applica tions using Code View and the Qlarity programming lan guage As your familiarity with Qlarity increases your ability to program complex tasks and customize your appli cation will grow To strengthen your background in Qlarity you should read the OptoTerminal Programmer s Refer ence Manual Next proceed to Chapter 10 Advanced Design in this manual to help you get started producing your own object templates Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 88 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 10 ADVANCED DESIGN The ability to completely design custom objects for a user application is the crowning feature of the Qlarity program
185. option to enable the port 6 1 2 Input Keyboard External Keypad TouchScreen Click the input mode or modes that are supported by your terminal and that you plan to use If you select External Keypad click Select to select an external keypad configuration create a new configuration or modify an existing one to match the actual keypad that you are using with the terminal 6 1 3 Communications Number of serial ports Select the number of serial ports available on your Qlarity based terminal Most terminals have either one or two serial ports 6 1 4 Miscellaneous Manufacturer ID MID If you purchased a custom MID code for your Qlarity based terminal enter it in the text box Your Qlarity based termi nal will emulate a terminal with the MID code If you did not purchase a custom MID code leave this value at the default 6 2 Layout Click the Layout tab to define the layout of the Qlarity Foundry work area to simulate your terminal display OptoTerminal Qlarity Foundry User s Manual Olarte Foundry Preferences Terminal Layout Editor Compile Simulation Ti how legend around I Highlight object under the mouse e E Grid Grid Spacing ho lt e Show Grid Snap to Grid Show data types in properties window IY Show popup help for objects amp properties Tab location Bottom Layout View colors double click to set Display Border Selected Object Hot object Dragging
186. or is drawn when the mouse passes Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual over the resize grip and the restrictions on drag movement for the resize grip See Tool Messages in the OptoTermi nal Programmer s Reference Manual The xCoords and yCoords arrays receive the horizontal and vertical locations for each resize grip respectively The size of the three arrays xCoords yCoords and cursors deter mines the number of resize grips that will be drawn All three arrays should be sized to the same value The boiler plate code sizes these arrays to 8 so 8 resize grips will be drawn for the object The code then locates the grips on the perimeter of the object at locations calculated from the posi tion and size properties Qlarity Foundry draws lines to connect each resize grip The closed parameter determines whether a line connecting the first and last grips will be drawn Ordinarily this is desirable However certain objects such as the Line and PolyLine objects in the QSI Common object library do not enclose a space on the screen and the last line is not desir able A value of TRUE causes this line to be drawn This property also determines whether clicking inside the object will select it in Layout View The code for the MSG _ TOOL MOVEHANDLE handler is as follows Hinis tu etion 1s Called an response to gt user movin
187. orner of the dis play Sc i cl S FY Test was completed l Test vas completed Serial data programmed to be transmitted through the termi nal s Com1 or Com2 port appears in the lower portion of the Communications window You can also enter data in the upper portion of the window and click Xmit to simulate data being sent to the terminal Click El to access the Communications Settings dialog box see section 6 5 1 for information Click Fl to clear flush the contents of the window 3 10 2 Simulation View Limitations Simulation View has the following limitations e When using a keyboard the repeat delay rate is determined by the global set ting in Windows This will only match your terminal s settings 1f you set 1t to match on your PC PrintScreen and Pause Break keys cannot be properly simulated e SetSystemSetting and related API functions may not be fully simulated e The flash file system 1s simulated but not persistent 1 e it is erased when you leave Simulation View Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 18 3 10 3 Source Level Debugger A source level debugger is included in Qlarity Foundry This allows an application developer to look at the execu tion of the Qlarity code line by line in order to find pro gramming errors If an error is expected in a specific place in the code a breakpoint can be set at that point and execu tion will
188. ors if you choose Qlarity Foundry includes several predefined named colors with each new workspace e g Clr_ScreenBackground and Clr_ScreenForeground Clr_ButtonBackground and Clr_ButtonForeground and so on You can create as many additional named colors as needed for a workspace e g Clr_StartEndButtons_BG and Clr_StartEndButtons_FG The colors of named colors along with named borders see section 5 5 are set up in themes see section 5 4 1 You can create your own themes and named colors and you can edit the predefined themes and named colors To create or edit named colors and themes for a workspace select Edit Named Colors from the Edit menu The follow ing dialog box is displayed Edit Named Colors Select a named color from the list then click on a new color to assign to it CALAS SEE orita EERE Bee A A xl Clr_ButtonBackground Clr_ButtonBackground lt i Clr_ButtonForeground Cl_ButtonForegroundalt M ci_FiiCotor Clr_LabelBackground rename color Reset color to theme defaut Theme standard y ie Save current border and lb A T color settings as theme III CS HHH _ Clr_ScreenB ackground Cl_ScreenForeground Clr_SoftkeybarB ackground Cir_SoftkeybarButtonB g ES Clr_SoftkeybarButtonFg O Cancel 5 4 1 Themes The colors and border definitions assigned to named colors and named borders are grouped togethe
189. p ttfont and bdffont 8 6 Test the User Application You can test most of your application s functionality in Simulation View before you download it to the terminal If the application uses serial communication you may want to configure Simulation View to use your PC s serial port s to simulate serial communication refer to section 6 5 3 Serial Port Setup 17 8 7 Save and Compile a Workspace 8 7 1 Save a Workspace You should save your workspace often while you are work ing on it to prevent losing work in the event of a computer lockup or power failure To save a workspace click p on the toolbar or select Save Workspace from the File menu For more information on saving a workspace refer to section 4 4 8 7 2 Compile a Workspace You should compile your workspace periodically while you are working on it to properly display the changes in Layout View Compiling is also required before you download a user application Click 2 on the toolbar or select Com pile Workspace from the File menu to compile the current workspace into the format required for a user application If the compile is successful the program displays the work space in Layout View If any errors occur during the com pile the program switches to Code View and the error messages are displayed in the Compile dialog box 8 8 Download a User Application Before you can download a user application to the Qlarity based terminal you need to configur
190. p Bitmap 0 00 Renare Ent BacklUpEitmap Bitmap 0 00 BasicEthernet Source 1 52 Set Entry Version BasicSerial Source 1 52 DisplaySettinmg Source 1 52 Ethernet Source 1 52 EthernetProtocolFunctions Source 1 52 Add New Entry Gauge Source 1 52 Grid Source 1 52 Homebuttar Source 1 52 homecdownbitrnap Bitmap 0 00 homeupbitmap Bitmap 0 00 O K Line Source 1 52 a as NOTE use caution in editing libraries Changes that you make to libraries take effect immediately and cannot be undone Remember that a library may be used in more than one workspace and changes made to the library affect every workspace in which it is loaded You can change the library name version or icon colors as well as change the entries in the library Name To change the library s name click in the Name text box and type over the existing entry The change is reflected in the Filename column in the Libraries dialog box Version To change the version number of the library click in the Version text box and type over the existing number The change is reflected in the Status column in the Libraries dialog box Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Icon Foreground Icon Background On the Object Palette icons for all objects in a library use a common color scheme Use these options to specify or change the foreground and or background color of
191. p download size 4601 Flash required 64 kbytes Download application Download other BFF Serial Ethemet Port com Baud rate 115200 Data Format en Send sting over senal connection nt ag Induce Set unit time e In Apploader NOTICE receiwed request from kernel to enter bootloader Entering G5 Bootloader 1 07 4 ln Bootloader gt Bootloader entered O51 Bootloader 41 074 Built Jan 20 2003 at 17 22 15 Received new kernel 266626 bytes yO Clear results box Close Window If Open serial port whenever this screen is shown a 57 7 4 5 Set Unit Time Use the Set Unit Time function to set the real time clock on the Qlarity based terminal as follows 1 The terminal must be in download or develop mode If necessary set up the Qlarity based terminal for downloading using the terminal s Power On Setup utility Refer to the OptoTerminal Hardware User s Manual for information on using Power On Setup NOTE time set through serial port The time is set through the serial port connection If your terminal is connected to an Ethernet port you will need to change it to a serial port to perform this function 2 Click Set Unit Time bottom of the Serial tab The message lt Setting Time gt is displayed in the Results box If no further message is displayed the terminal s time has been set If an error occurs it 1s dis played in the R
192. past its left edge Finally the container area object boilerplate code for the MSG_TOOL_DRAGCREATE handler is as follows The following function is called when gt the user created an instance of this gt template by selecting it from the object gt palette and dragging it in the layout view The handler for MSG_INIT is not called gt automatically and if you want it gt called you should call it manually You should call Tool_Persist on all the gt properties that you set up in this gt message handler xl yl are the gt coordinates that the user started his gt drag and x2 y2 are the coordinates gt that the mouse was released parentObj as objref gt xl as integer yl as integer x2 as gt func ToolDragCreate integer y2 as integer handles MSG _TOOL DRAGCREATE if x2 lt x1 then xPos x2 width x1 x2 1 else xPos x1 width x2 x1 1 endif ie Aya lt yl then yPos y2 OptoTerminal Qlarity Foundry User s Manual height yl y2 1 else yPos yl height y2 yl 1 endif parent parentObj Save the properties that we just set Tool_Persist parent Tool Persist xPos Tool_Persist yPos Tool Persist width Tool_Persist height Call our MSG_INIT handler StartUp endfunc Since the location and size of an area object container is determined by the extent of the click and drag operati
193. perties window for you to select the resource for an object instance For information on changing the name refer to section 5 2 3 5 2 2 Preview Resources When you select a resource in the list a preview of the resource is displayed in the Preview box as shown below 1f appropriate If you selected an audio resource click the button in the Preview box to listen to the sound 31 Edit Resources Bitmaps BDF Fonts TrueType Fonts Audio Binary Catalog resources catalog bmp default Glarity bmp E I cita resources gbermq U brp resources splash2 bmp resources tankap bmp splash tank ap Resource data Filename resources gterm a70 bmp Browse Rename gterm_gr 0 Resource data Filename larabiet ttf Browse Rename larabieb Mew TrueType fort Remove TrueType font Cancel 10 The Quick Broun Fox The Quick Brown A gt The Quick Bro A The Quick H The Huic The Qui ei 5 2 3 Rename a Resource In the Edit Resources dialog box do the following to change the name of a resource This changes the name that appears in the Properties window for you to select the resource for an object instance it does not change the file name of the resource Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 32 1 From the list of resources select the resource that you want to rename and click Rename re
194. plate in a library Use this option to copy an object template from an existing library object When you select this option a Based on box replaces the Object type box Select the object you want to copy from the drop down list Extend inherit a template from an existing tem plate in a library Use this option to create a new object template based on the programming code from an existing library object When you select this option a Based on box replaces the Object type box Select the object you want to copy from the drop down list Refer to the Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 28 5 OptoTerminal Programmer s Reference Manual for more information on extending templates In the Template Name box type a name for the new template Each template in the workspace must have a unique name A template name has no size limitation but must start with a letter A name cannot contain spaces but may use the underline character _ The percent pound and dollar sign symbols can be used at the end of the name The last box is labeled either Object Type or Based on depending on the option you selected In the Object Type box select the type of object you are creating from the drop down list as follows An object that contains other objects Container e g a form It can be defined as part or all of the terminal screen l A di
195. ption is aborted but the current message continues to propagate to other objects until it has been processed to completion At this point if there are any exceptions in the system exception stack the system software generates a MSG_ERROR message which is processed immediately 1 e before any other pending messages are processed MSG_ERROR is a special message that can only be pro cessed by handlers in the Global Code space This allows applications to provide a last chance global error handler routine that receives all unhandled exceptions The MSG_ERROR handler has no parameters so the exceptions must still be retrieved by calls to GetException Retrieving an exception by calling GetException removes the exception from the system exception stack Therefore calling GetException terminates an exception unless it is rethrown by calling the Rethrow API function Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 92 If the exception has not been handled 1 e removed from the system exception stack after MSG_ERROR is pro cessed or if there is no global MSG_ERROR handler the exception is either discarded for exception levels of EXLEV_IGNORABLE or lower or the exception location and description are transmitted from the primary serial port for exceptions of EXLEV_SYSTEM or higher The typical check error block or global MSG_ERROR handler calls GetException to retrieve informati
196. r ders are shown next to the named border labels Save Current Border and Color Settings As Theme To save as a theme any changes you made to the named bor ders click Save current border and color settings as theme A prompt appears with the name of the currently selected theme If you do not want to change the border designs in the theme displayed enter a new name to create a new theme Remember that the current named colors see section 5 4 Edit Named Colors are also saved as part of the theme NOTE save current theme If you change themes without saving the changes you made to the current theme the changes to the unsaved theme are not saved when you click OK 5 5 2 Named Borders NOTE named borders not supported on older objects Named borders cannot be assigned to objects in libraries from Qlarity Foundry versions earlier than 2 1 To create or edit named borders begin by selecting a theme from the Theme drop down list The attributes of named borders are saved in themes All named border attributes for the selected theme are dis played Both the named border label and the border attributes currently assigned to the named border are shown To change the attributes for a named border click the named border to select it then select from the General Effects Rounded Corners and Double Borders options see the following sections for details to modify the border The new attributes are shown in
197. r s Manual Display the object This function will be called whenever gt necessary to show the object func Draw pass as boolean handles MSG DRAW if not pass then SetFGColor RGB _WHITE SetBGColor RGB_GRAY DrawBox XPOS YPS XPOS F width gt ls YPOS bergh 1 DrawLine xPos yPos xPos width gt lig POS Herghte 1 DrawLine xPos yPos height 1 gt XPOS E WHGER 1 YPOS endif endfunc Notice that the MSG_DRAW handler for a container takes a boolean parameter This is because a container receives two opportunities to handle a MSG_DRAW message once before the message is passed to its children and once after the children have finished handling the message The value that the handler receives in the pass parameter indicates whether or not the message has already been passed to the container s children see Draw Messages section of the OptoTerminal Programmer s Reference Manual 10 5 2 Getting New Object Templates to Work in Qlarity Foundry Since Qlarity Foundry does not have knowledge of the implementation of a Qlarity object the object template must implement handlers for several tool messages to work prop erly in Qlarity Foundry These messages are generated by Qlarity Foundry when the user interacts with the object in Layout View For example when an object is selected it should display a series of resize grips to allow the user to resize the object by dragging the mouse
198. r gt to save the new name or press lt Esc gt to revert to the old name 5 1 4 Remove a Template In the Add Edit Templates dialog box do the following to remove an object template from the workspace 1 Click the template that you want to remove It is high lighted in blue 2 Click Remove Template 3 A prompt is displayed to confirm that you want to remove the template Select Yes to remove the object template from the workspace 5 1 5 Send Template to Library After you have created and customized an object template you can add it to a library By placing your object templates in a library they can easily be distributed to other locations or computers by copying the library file e g libraryname lib NOTE do not add to QSI libraries You should not save your new object templates to QSI libraries QSI libraries are regularly updated and the new 29 libraries replace the existing ones so your templates would be overwritten Instead you should create a new library in which to store your own object design work Refer to section 5 3 Edit Libraries for more information In the Add Edit Templates dialog box do the following to add an object template to a library 1 Click the template that you want to add to a library It is highlighted in blue 2 Click Send Template to Library The following dia log box is displayed Send to Library l x Select ibrar Es Entry name NewM ha Leave templa
199. r in themes See section 5 5 Edit Named Borders for information on named borders Several predefined themes are set up in Qlarity Foundry You can change the colors or border defi Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual nitions in a predefined theme or you can save the changes as a new theme Generally a theme represents a color scheme such as a theme with all grayscale colors a theme with shades of blue or a theme with neon colors To view the colors in a theme select the theme from the Theme drop down list The colors assigned to the named colors are shown Each theme uses the same named color labels only the colors assigned to them are different from theme to theme Theme Click the drop down list and select a theme Its defined col ors are shown next to the named color labels Save Current Border and Color Settings As Theme To save as a theme any changes you made to the named col ors click Save current border and color settings as theme A prompt appears with the name of the currently selected theme If you do not want to change the colors in the theme displayed enter a new name to create a new theme Remember that the current named border definitions see section 5 5 Edit Named Borders are also saved as part of the theme NOTE save current theme If you change themes without saving the changes you made to the curre
200. r more detail Validation functions may also be associated with global variables These global validation functions should be included in the Global Code space NOTE strict assignment operator Ordinarily the validation function assigns the new value to the property using the strict assignment operator It is important to use the strict assignment operator when assign ing the new value to the property inside the validation func tion If the validation assignment operator is used the validation function recursively calls itself until the system software stack overflows Refer to Validation Methods section in the OptoTerminal Programmer s Reference Manual for additional details on validation functions 10 3 The Qlarity API Library The Qlarity API Application Programming Interface is a library of functions built into the Qlarity system software These functions allow Qlarity applications to interact with the Qlarity based hardware to perform tasks such as draw ing on the display or sending data to a communications interface Other functions perform common tasks that would be tedious or difficult to implement using the Qlarity language Over 100 functions are available All functions are documented in Qlarity API Function Reference sec tion of the OptoTerminal Programmer s Reference Manual 10 4 Exception Handling When an abnormal condition arises while a Qlarity applica tion is running the system software
201. riables as desired 6 Click or select Compile from the File menu to compile the workspace Any errors in the new source code are identified by messages in the Messages and Errors window If no errors are present the compiled workspace is returned to Layout View 9 5 2 Add a Global Function to a Workspace To add a global function to the workspace do the following 1 Select Globals in the Object Tree to access the Global Code space 2 Select Code View The editor window displays any cur rent global source code 3 On a blank line in the editor window outside of any other function declare a new function by typing the func keyword followed by the name of the function a left parenthesis the parameters of the new function and a right parenthesis If the function returns a vari able the right parenthesis should be followed by the keyword returns then the type of the returned value The end of the new function is indicated by the end func keyword on its own line The parameters appear as new variable declarations see section 9 5 1 without the dim keyword Each parameter is separated from other parameters by a comma OptoTerminal Qlarity Foundry User s Manual For example the following code declares a new func tion named average that takes two floats named first and second as parameters and returns a float func average first as float second as gt float endfunc returns floa
202. rity Foundry to automatically create a validation function 8 Optionally enter an initial value for the variable the Properties window category in which the variable should be placed i e General Main etc and any text that you want added to the variable s online docu mentation 9 Click OK to add the global variable 9 5 1 2 Add a Global Variable in the Global Code Sec tion Use the following method to enter the variable directly in the Globals section in the Code View window 1 Click the Code View tab 2 Click Globals in the Object Tree to open the Global Code section Any current global source code is dis played in the editor window 3 Ona blank line in the editor window separate from any other function declare a new variable by typing the Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 84 dim dimension keyword followed by the name of the variable the keyword as and then the type of the new variable For example the following code declares a new integer variable named count dim count as integer 4 If desired also assign an initial value to the variable by adding a new line containing the keyword init the name of the new variable the operator and the ini tial value of the variable For example the following line initializes the new count variable to a value of 10 init count 10 5 Repeat steps 3 and 4 for as many va
203. rity Foundry the Welcome to Qlarity Foundry dialog box is displayed To start a new workspace from this dialog box click Start New To start a new workspace with Qlarity Foundry open click y on the toolbar or select New Workspace from the File menu The following dialog box is displayed Select the type of workspace to create Choose the type of project to create Workspace for PAC Control loControl andor Opto F operation Workspace for PAC Control or ioControl communication anly Workspace for OptoMMP communication anly Create workspace like the last one created Workspace for PAC Control ioContral Description Enables an OptoT erminal to communicate with Opto 22 controllers using PAC Control or ioControl strategy vanables andor the UptoMMP memon map protocol The workspace also has several display options and objects not available in other workspaces This workspace can only be used with Opto 22 controllers that can run a PAC Control or ioControl strategy and have firmware AB O or later Show Details gt gt The upper box lists several types of workspaces you can create The difference between workspace types is deter mined by the library or libraries included with the selection The following workspace types are available PAC Control ioControl and or OptoMMP operation This option includes the Opto22 PAC library Opto22_PAC qlib the Basic library basic qlib and the Extra library extra qlib
204. rogramming language Once you are familiar with the basics of Qlarity programming it is easy to program complex event handling into objects without the need to manage numerous event properties 9 4 1 Override an Object Method To override an object method in your application do the following 1 Add the object that will be used to handle the event e g ButtonV2 TimerV2 2 Select the object in the workspace in Layout View or in the Object Tree and select Code View 3 From the Events Overrides drop down list above the code select the method you want to override Select Show only event functions if you want the drop down list to displays only methods that have been designated event methods If Show only event functions is not selected all possible override meth ods are listed Move the mouse pointer over a method in the list to display a description of the function 4 When you select a method from the list code similar to the following appears beneath all code for the object func click endfunc 5 Between the func statement and the endfunc state ment add Qlarity code to implement the desired response to the event A typical event response might include code to set properties in this or another object The Qlarity code to do this is as follows lt objname gt lt propertyname gt lt value gt lt objname gt This is the name of the object whose property will be changed To a
205. rror Message Handlers we Existing functions wt New Variable Insert at a ARRE r RENA ARRE RARA ARRE RARA RAR RARA RAR RARA RARA RRA ARA RRA a a a a r aa 8 0 Author Date i FTFSerwer EE af HideFullS creenColorLbIT i of QwertyKeypad of TranslucentColorPicker E af BacklightDownBtn E af BacklightUpBtn Description E af ContrastDownBtn Version 1 0 2 iT E af ContrastUpBtn Copyright 001 051 Corporation Em af EndGames Permission is granted to copy distribute and modify this code Bl gt af HelpSideButtonsS cr i y ObjectsScr provided that this copyright statement is Preserved Cee TTT a a a a a a a a a a a r a a aa a a a a aa af GraphicsS cr y CiagnosticsS cr af FunScr af NavScreen af TemplateS cr y SplashScreen af ScreenSaver af SorSaverdn af ScrSaverLlf af Scr2Home a e af Scr2Next Be af Cur DDL ListBox af Curr DDL_HideT immer return a Templates endfunc ES _ODLHideTimer Jm DropDownList 2 CE DropDownLis Layout View E Code View SA FodeFinmap Line 1 Col 1 Polyqonve Randy Flint 2 Novy 2003 This object Draws a Polyline library standard source 3dcolors doc object LaserPolygon This object can be used to draw polygons multiple connected line segments that share a first and last endpoint fdefaultitem func fdefaultiterm prop gl gt 50 gl gt 50 sae 50 e 50 sae gl gt a E a E aE a sE p
206. ry default 6 3 2 Font From the Font drop down list select a font for the text in Code View A sample of the font is shown in the Sample Text box From the Point Size drop down list select a point size for the selected font The Sample Text reflects the selected point size 6 3 3 Tab Spacing Enter the number of characters or use the selection arrows to select the number to be indented when you press lt Tab gt 6 3 4 Show Advanced Code Sections in Object Tree Normally disabled Select this option to show the advanced code sections in Code View This adds an Advanced Code Libraries and Internals branch to the Object Tree and enables advanced users to work with advanced OptoTerminal Qlarity Foundry User s Manual and library code For information on these functions refer to section 10 1 6 3 5 Fast Selection This option determines how text selected in Code View is displayed If you enable this option selected text is inverted If disabled text is blocked and highlighted 6 3 6 Parenthesis Matching If you enable this option when the cursor in Code View is at a parenthesis or square bracket character both the charac ter at the cursor and the matching parenthesis or square bracket are underlined If disabled parentheses and square brackets are not matched 6 3 7 Edit Events in the Event Builder If you enable this option the default event editor is Event Builder see section 8
207. s ces aren ese eae tuceie ie as taste E seatace sa neea heen E E meee 44 M EONO corar sass ve oois sea Saaa adore crea dloeanaha E I 45 E A A A II II elo ad ne adele de route a oon 45 E OAC sss ced sata PP nce eased skies nak aS oo tga ceca Sas acess oes oceans eo a das bbe GasuaiTas uae ca aed ue thal sew muaceontahaastoaia test 46 Sree So A A nS er 46 6 34 Show Advanced Code Sections in Object TE iia 46 E A A AE 46 6 3 0 Parenthesis Mate hii mesias loco dea dicta 46 6a Edi Events in the Event DUI dE a A tail 46 6 Auto Help SEIS ai aia 46 G53 8 Functions and Methods misil di 4 030 2 Tener Completo ia doa ie Mi atesced dacanestbeeoned imagens uneeser ees E sue eu eal 47 6 3 8 3 Assignment and Parameters cxtshateadececcessedeebencecaendesecodadeeicanesacnsracnsseebenaytiiee wvedasdeelonigts session 47 6 3 9 4 Show Global Variables and Functions desainer n ida 47 6 3 8 5 Show Object Properties and Methods ccccccccccccecccceeeeeeeeeeececeeseeeeaaeeaeaessaeesseseseessseseeeseeeeeseseeees 47 6 3 5 6 SHOW for Built Data TiPesira iaa 47 030 2 Fade AMORE P TIDS ee E E E Ena 47 04 COMPE N E R 48 o aR TII ao 1R VIE Weiss cet E AET ENE AAA ANA AA A E 48 631 Communications Window SEC GS isc shin dec hens io 49 EA Gy DAG SeN S i A 50 00 Sem all PORE SEUS bid 50 CHAPTER 7 DOWNLOAD SOFTWARE TO THE TERMINA Locas ieron chica dacsadecnsedcusnesetasseutiesadetdadssasescuasdedesecbedseidccusdvestecastecbicauoetasuseesssdeeuss 53 TA Configure Co
208. s in the Object Tree Feet Selection popup pep packoround ll Set color Automatic colo Edit events in the Event Builder Reset all colors to default AutoHelp settings 6 3 1 Colors You can specify a background color or different colors for different parts of the programming code as follows e Background e Normal text e Keywords e Strings e Symbols Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 46 e Comments e Documentation e Errors e Selection e Popup help background e Popup help border e Help accent color You can specify that keywords strings symbols comments or errors appear in colors different from normal text to assist in finding and identifying them within the code Click an item to display its color in the Sample Text box Double click an item or click Set Color to change the color A color selector dialog box appears Click a color in the basic colors section to select it To create a custom color drag the color selector in the rainbow palette to a color and then drag the slider up or down to adjust the saturation and lightness of the color or enter the HSL or RGB of a color Click OK to change the item to the selected color Automatic Color Click an item then click Automatic Color to set the color to the automatic color Reset All Colors to Default Click Reset All Colors to Default to set the color of every item to the Qlarity Found
209. s option other system libraries are not included If code in one library relies on code in another library that is not included in the Qlarity workspace the compiler will generate errors Include as reference If you select this option a reference to all system libraries in your workspace is included A library that is included as a reference is available to the Qlarity compiler but will not generate an error if the workspace is moved to a computer that does not have that library Include directly If you select this option all system libraries are included directly If the workspace is moved to a computer that does not have one of the system libraries compile time errors will occur Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 38 NOTE included system library objects If you select an option to include additional system librar ies the library objects do not appear in the Object Palette 5 3 5 Create a New Library Do the following to create a new Qlarity Foundry library 1 Click Create New Library A dialog box similar to the one shown below is displayed Create new library Save in E Qlarity Foundry __ AppHelp C Samples a 8 E El e multilingual glib pan LJ AutoDoc LITT Fonts o 2warld glib LJ auxsuppor tutorials CI bdf fonts E Basic lib L documentation 2 DataProc glib 2 Firmware 2 Extra qlib File name A Save as type Library files l
210. set to lt None gt any serial send and receive requests by the application are ignored If you are setting up more than one port assign a different PC serial port to each terminal serial port Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 52 OptoTerminal Qlarity Foundry User s Manual Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 CHAPTER 7 DOWNLOAD SOFTWARE TO THE TERMINAL This chapter provides information to do the following Configure Communications Port e Download a User Application e Download a BFF File e Upgrade the Firmware 7 1 Configure Communications Port To configure the communications port used to download user applications to your Qlarity based terminal select Download Application from the File menu The following dialog box is displayed 25 Download application to unit Download pp download size 24614 Flash required 64 kbytes Download application Download other BFF Upgrade firmware Serial Ethemet Port fealty H Baud rate 115200 Data Format en Send sting over senal connection nt a je Induce Set unit time bootloader Results oe Clear results box Close Window W Open serial port whenever this screen is shown a NOTE settings must match the terminal Your communication settings in Qlarity Foundry must match those at the Qlarity based terminal For information on ref
211. sion of firmware is on the Qlar ity based terminal do the following to determine the cur rent version of terminal firmware 1 Verify that the Qlarity based terminal is connected to your computer 2 Put the Qlarity based terminal in Develop mode App Mode Develop Refer to the OptoTerminal Hardware User s Manual for instructions 3 Select Download Application from the File menu 4 Power the terminal on If it is already on power it off and back on The firmware version and date of issue are displayed in the Results box as shown in the figure below Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 56 E Download application to unit Download pp download size 4607 Flash required 64 kbytes Download other BFF Upgrade firmware Serial Ethemet Port com Baud rate 115200 Data Format ani Send sting over serial connection srt oe Induce aci Wilk ime bootloader Engineering ethernet address detected Development mode Firmware version 1 570 c 1 016 BFF Built Mar 19 2003 at 13 38 12 Download application ee Eee Clear results box Close Window y Open serial port whenever this screen is shown e 7 4 2 Prepare Terminal for Upgrade To prepare the terminal to receive new firmware using a serial or Ethernet connection set the App Mode option to either Develop or Download Refer to the OptoTerminal H
212. sions Onentation Landscape Display Type Color M Audio Decoder I Ethernet Tabs are available to define your Qlarity based terminal display to define the layout of the Qlarity Foundry work area to set up the code editor and to set up compile defaults as described in the following sections 6 1 Terminal The options in the Terminal tab are for advanced users or for those setting up a custom hardware configuration Gen erally you should use the Hardware Configuration Assis tant to set up your terminal Base Terminal To change the type of Qlarity based terminal you want to program select the new terminal type from the drop down list The type of terminal selected determines the legend you will see around the display in Layout View The display Dimensions setting changes to match that of the selected terminal 6 1 1 Display Setup Dimensions From the drop down list select the display dimensions in pixels of your model of Qlarity based terminal Refer to your Qlarity based terminal specifications for this informa tion Orientation A terminal may be mounted in landscape longest dimen sion is horizontal or portrait longest dimension is vertical mode Select one of the following options from the drop down list Portrait Landscape Portrait Il or Landscape II The Portrait Il and Landscape Il options can be used by advanced programmers in conjunction with the GetSystem Setting
213. sons 5 Sli Hardware Oni lS uracon ASS ta a S 5 Bel ADEM WO E e a 5 ILL AO WO AA A A A meine 7 sA MIEL OPUS A OO LOS 8 A A o O o ME autacnieniameniias sshsteaatituutesadae sh aseamandacedinias 8 ee A A 9 IAV ION NE A PP An 10 IA TOOLS MA A tT ae 10 O e A AAA PPP ta dutuieeieaes i unseeaesdeunsd E E 12 OO NAM sta cetiese st icate E sass tatnod aa nua palscaee ead E Aen eae eee 12 0 Layout View TOD atea 12 IZ C ode Vie wT OOM A Cana end eee ee cerca ee naan 13 IAS SIMU AON nn o o coats A a 14 DOs IVINS Ce ATC OUS Bar ak ca see Basis areas sisted a round da Pucgawinsc a eats dvad Ga aa gaiooa nb lutea decal a acl a weAe sees eecue 14 Sl Navicanon Bat Code VIEW ONY anio 15 SL Global Template or LDL COS A A a 15 ate ODjEC E stance Codere ral ia ia inci 15 KOOD ECEE e O Ae uel masta tunin AA cadmas a eta toad 15 SOL ll is 16 FSL OB EE emplee Ni 16 5 9 Layout and Code VCW S taa mewcnancedats 17 ni AAA a O an sees 17 SAO Sena MO SUP DUE add iisids 18 521022 Simulation VIEW AUTOS o E 18 LO Source Level DEDO dlls cuendo inca 19 DAOA Carle Stack WING OWN 19 SMS Wate Wind Wiese a eiii 19 Se lil A esac rusia Pataca Cees Dea hea TE a Beale asia ceeds clue 19 DAZ ODC CEPA E a aa E A ana 21 3 121 Add a New Object IMS tan Si ios A oan 21 JLS MONE and Resize WW IMG OWS dd 22 Sy Where CO iO Prom TCC eine a daa casein cd tad ede ats aie a ante a ieee eee aed es eae Steieaetiae sie 22 CHAPTER 4 Opto 22 Fax 800
214. source name e g Rename qterm_g70 A dialog box is dis played with the current name of the resource selected in the text box Olarte Foundry Enter the new name for the resource 2 Type over the name with the new name or edit the name as desired 3 Click OK to rename the resource and close the dialog box The new name appears in the name column of the resource list 5 2 4 Change a Resource File In the Edit Resources dialog box do the following to change the file assigned to an existing resource name 1 From the list of resources select the resource for which you want to change the file 2 Click Browse and an Open dialog box appears 3 Select the file that you want to assign to the resource name 4 Click Open to accept the file and close the dialog box and the file is changed 5 2 5 Remove a Resource In the Edit Resources dialog box do the following to remove a resource from the workspace 1 From the list of resources select the resource or resources that you want to remove You can select mul tiple resources as described in the note above 2 Click Remove resource type e s Remove BDF Font The selected resource s is removed from the workspace OptoTerminal Qlarity Foundry User s Manual 5 2 6 Bitmaps Qlarity Foundry supports bitmap images in the standard bmp format Use the following guidelines when creating bitmap images to be displayed on Qlarity based t
215. space and Qlarity libraries All of the libraries provided with Qlarity Foundry have been docu mented using the AutoDoc feature This appendix contains the complete specification on how to write AutoDoc meta data If you choose not to add AutoDoc meta data your templates properties and methods will still appear in the object documentation and be available for the AutoHelp feature in Qlarity Foundry but they will not contain helpful descriptions B 1 Documentation Declaration To begin documenting a program element use the follow ing syntax doc lt element type gt lt element name gt Where lt element type gt is one of func prop obj override type group and lt element name gt is the name of the element you are documenting Normally you would place the documentation declaration immedi ately before the element declaration However doc obj declarations for object templates often appear inside the template definition itself All AutoDoc constructs that follow a documentation decla ration apply to that declaration until a new declaration is encountered AutoDoc constructs that appear before a docu mentation declaration are not allowed doc func MyNewFunc doc obj NewObject doc type DataType The following program elements may be documented Func A global function or an object method Prop A global variable or object property Obj An object template Override The same as a function except that it de
216. specified item will be imported itemlist Only valid for type lt element types gt Imports a simple list of enumeration or start type items for the specified data type OptoTerminal Qlarity Foundry User s Manual itemdesc Only valid for type lt element types gt Imports the list of enumeration or start type items for the specified data type as well as those items descriptions The items and descrip tions are displayed in a table format In addition to lt import what gt importing items also supports the following non exclusive format commands indent The imported text tables will be indented from the left mar gin box The imported text tables will be displayed in a box fill The imported text tables will be displayed in a box that is filled with a gradient fill Examples This function will return one of the following values importdoc type weekday itemlist indent box Please review the following valid protocols importdoc type netprotocol all B 5 Function Parameters When documenting functions you may use the param directive to describe the parameters of the function When the documentation is displayed the parameters are summa rized in an easy to read table param directives are also used for the AutoHelp feature in Qlarity Foundry param lt parameter name gt lt parameter description gt This assigns lt parameter name gt the given lt parameter description g
217. splay element e g text object bitmap object line object etc An object that serves a function not related to the display e g key defi nition communications etc Non drawable object For more information on object types refer to Chapter 8 Basic Design and to Appendix A Glossary of Software Terms In the Based on box select the library object on which the new object template is to be based The pro gramming code from the library object will be copied to the new object template Click OK to create the new template 5 1 2 Edit a Template Icon Each template 1s identified in the Object Tree by an icon To customize the icon for a template click the template name in the Add Edit Templates dialog box then click Edit Icon The following dialog box is displayed OptoTerminal Qlarity Foundry User s Manual Edit Template Icon Invert Left Button E Dl pm Right Button mi El Filicon lm Copy icon Py OR Cancel The icon form is graphically represented as a grid Each square in the grid is an individual pixel On the grid draw the icon for the template using the following tools e If you want to modify an existing icon to create a new one click the drop down arrow at the Copy icon box and select an icon from the list The selected icon is dis played e If you would like to start with all pixels the same color 1 e white black or a shade of gray cli
218. ssary An error message is displayed when an error occurs that prevents compiling Error mes sages cannot be disabled Limit BDF Fonts to ASCII Characters If this option is enabled only the ASCII characters in BDF fonts are displayed Unless you need to use characters beyond the standard ASCII character set you should enable this option to reduce the memory requirements for BDF fonts The Qlarity based terminal contains 256 ASCII characters Enable Unicode support in the standard objects If this option is enabled the workspace is compiled so that all text is drawn using the Unicode character set This option is primarily used when developing Qlarity applica tions that support non Latin based languages such as Chi nese or Japanese To use the extended characters in the Unicode character set you must include one or more fonts in the workspace that contain the Unicode characters that you want to display There are many such BDF and True Type fonts available on the Internet OptoTerminal Qlarity Foundry User s Manual NOTE Unicode support and advanced programming When Unicode support is enabled Qlarity Foundry treats the charstr data type as a unistring rather than a string Since most objects value or caption properties are of type charstr string or byte array data must be converted to a charstr before they can be displayed in an object This includes all data received from a serial or Ethernet port as well as many API f
219. ssign values to its own properties the override function in an object can refer to itself using the me keyword as the lt objname gt OptoTerminal Qlarity Foundry User s Manual lt propertyname gt This is the name of the property to change lt value gt This is the new value to assign to the property Another common activity is switching screens display pages or hiding one object and displaying another To switch screens the method typically disables the cur rent screen object and enables the screen object for the desired new screen as follows false curscreen enabled newscreen enabled true where curscreen and newscreen are the names of the screen objects to be manipulated Since the override method is a complete Qlarity func tion local variables can be declared and code including conditional statements if else looping for next do while etc and any other legal Qlarity code can be added to the function Complete details on the Qlarity programming language are found in the OptoTerminal Programmer s Reference Manual NOTE return from functions Since Qlarity is an event driven program you should return from functions in a timely manner Writing code that does not return will cause the system to hang 6 Click Compile button or select Compile from the File menu to compile the workspace If there are com pile errors in your code messages are displayed in the Messages an
220. t NOTE code formatting A statement is defined as a single line 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 4 Fill the body of the function between the func state ment and the endfunc statement with the Qlarity code to implement the desired function If the function returns a value be sure to include a return statement followed by an expression that yields the value being returned For more information see the OptoTerminal Programmer s Reference Manual In the example above the completed function is as fol lows func average first as float second as gt float returns float return first second 2 1 endfunc 5 Repeat steps 3 and 4 for as many functions as desired 6 Press or select Compile from the File menu to compile the workspace Any errors in the new source code are identified by messages in the Messages and Errors window If no errors are present the compiled workspace is returned to Layout View 9 5 3 Add a Global Message Handler to a Workspace Message handlers are functions that are called by the system in response to a message generated by an event Examples of such events are a touch screen press or the receipt of characters throug
221. t The param directive must appear entirely on one line It may not be split into multiple lines doc func sqrt param real The value whose square root will be calculated Calculates the square root of the parameter lt b gt read lt b gt and returns that value func sqrt real as float returns float Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual calculate the square root endfunc You may also use the link or importdoc directives in a param directive as follows param LEDCommand Determines the behavior of the LED One of the following values importdoc type ledcmd itemdesc param PixmapToProcess A pixmap to process This should be an array returned from the link func GetOb jPixmap function B 6 Data Type Elements When documenting data types you may assign descriptions to each enumeration or start type item item lt item name gt lt item description gt This assigns lt item name gt the specified lt item description gt The item directive must be completely specified on a sin gle line It may not be split into multiple lines doc type ledcmd Used by the Flank func SetLED APT to determine the state to put the LED in item LED_ON Turn on the specified LED item LED_OFF Turn off the specified LED item LED_TOGGLE Toggle the state of the specified LED enumerate ledcmd as LED_ON 1 LED_OFF 2 LED_
222. t Shift gt lt Tab gt to move backwards NOTE Properties window When you press lt Tab gt the Properties window changes to match the newly selected object 8 3 2 1 Move an Object To move an object do one of the following e Use the mouse Click in the center of the object hold down the mouse button and drag the object to a different position You can hold down the lt Shift gt key while mov OptoTerminal Qlarity Foundry User s Manual ing an object to limit its movement to horizontal vertical or a 45 angle e Use the Properties window Enter a new x and or y posi tion integer in the Properties window 8 3 2 2 Resize an Object To resize an object do one of the following e Use the mouse If the object has resize grips sizing handles you can click and drag any grip to resize the object Click and drag a corner grip to maintain the height width proportions while resizing Resize Grips E e Use the Properties window Change the height and or width integer in the Properties window 8 3 2 3 Change the Order of Objects You can change the Z order of an object or the parent child relationship simply by changing the object s position in the Object Tree To move an object to a different location in the Object Tree click and drag it to the desired position The icon for the object is dragged to the new location A horizontal placement line as shown in the illustration below appears as you drag the o
223. t is not currently loaded in Qlarity Foundry to the Qlarity based terminal but the file must be in binary file format BFF Use this option to save a file to BFF Refer to section 4 6 for information Download Application Layout and Code View only Select this option to download files to the Qlarity based ter minal You can download the currently loaded workspace any BFF file or a firmware upgrade Refer to Chapter 7 Download Software to the Terminal for information Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 Recent Files After you have created and saved Qlarity files you can use this option as a shortcut to open a file that was recently opened Click Recent Files and a list of previously opened files is displayed Click the file that you want to open Exit Select this option to exit Qlarity Foundry 3 4 2 Edit Menu The options in the Edit menu change depending on whether you are in Layout View or Code View The Edit menu is not available in Simulation View Select All Code View only Select this option to select all code in the Code View win dow Cut In Layout View select an object in the work area then select this option or press lt CtrI gt lt X gt to cut the object from the workspace In Code View select code then select this option or press lt Ctrl gt lt X gt to cut the selected code from the workspace The object or code remains on the Windows clipboard
224. t_dowmnibl B a Instructions YS gf Lines Ea ai ColorPalette EHD yf SpeakerTab sl Line 6 B d Instructions a HighButton men Mrs r na OptoTerminal Qlarity Foundry User s Manual A parent object can also be a child a container object with children inside another container object HardwareNew and SoftwareNew in the illustration are examples of par ent objects within other parent objects 8 2 4 Z Order Z order is the order in which objects are layered The Z order determines how objects are displayed whether they are behind or in front of another object or objects and the order in which information is processed messaging In a Qlarity Foundry workspace the Object Tree lists objects in their Z order with those listed first receiving the highest display and messaging priority To change an object s Z order click and drag the object name to a different position in the Object Tree To learn more about how parent child relationships and Z order affect user applications read the next section 8 2 5 Events and Messaging Qlarity is an event driven programming language An event is any type of input such as the following e A keyboard key press or release e A touch screen press or release e A change in a value increment or decrement e A timer action e Data received through the serial port When an event occurs a Qlarity user application responds with all appropriate and specified actions
225. tance created from the template Indeed many objects have methods that are intended only for over ride the default method in the template does nothing This allows an object to provide or publish a way to customize the behavior of the object without modifying the template For example a timer object might provide a function called Alarm which is called by the object each time a preset 81 time period expires The function in the template does noth ing but it allows instances to override the function to pro vide a desired response to the timer expiration The code for the method override is defined inside the object instance The override method must have the same name parameters and return type as the template method that is being overridden For example if the method in the template is named foo and it takes an integer and a float as parameters and returns a float then the override function must also be named foo and must also take an integer and a float as parameters in the same order as the template method and return a float In addition if the template method handles one or more messages the override must handle the same message s This may require you to examine the code in the template possibly in a library Otherwise the method is like any other Qlarity function and may contain whatever Qlarity code is desired The special function Default when placed inside an over ride method calls the
226. te in workspace when done Cancel 3 Inthe Select Library box select the library to which you want the object template copied 4 The Entry Name box displays the name of the object template To assign it a different name within the library type a new name 5 If you want to leave the template in the current work space after you copy it to the library select Leave tem plate in workspace when done 6 Click OK to place the object template in the selected library 5 1 6 Change Template Type In the Add Edit Templates dialog box do the following to change the object type of a template 1 Click the template that you want to change It is high lighted in blue Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 30 2 Click the radio button for the object template type to which you want to change the template as follows An object that contains other objects e g a form It can be defined as part or all of the terminal screen Container Area object A display element 8 text object bitmap object line object etc An object that serves a function not related to the display e g key defi nition communications etc Non drawable object For more information on object types refer to Chapter 8 Basic Design and to Appendix A Glossary of Software Terms 5 1 7 Extend a Template A template may extend another base template A
227. template that extends another template inherits the base template s properties and methods In the Add Edit Templates dialog box do the following to extend a template 1 Click the template that you want to modify It is high lighted in blue 2 From the Extends template drop down list select the base template that you want the selected template to extend If you do not want the template to extend another template select lt none gt from the drop down list Refer to the OptoTerminal Programmer s Refer ence Manual for detailed information on extending object templates 5 2 Edit Resources Resources include all bitmap images fonts audio files and binary data files that are available in a workspace and even tually in the user application You must add resources to a workspace before you can use them in object instances Use the Edit Resources option to add resource files to your workspace or to change or remove the resources avail able Because resources become part of the user application when it is compiled you should delete any unnecessary resources OptoTerminal Qlarity Foundry User s Manual NOTE default bitmaps and fonts When you create a new workspace you have the option to add default bitmap images and fonts to your workspace Some objects may require at least one bitmap BDF font or TT font resource before the object will function properly When you have finished creating a workspace
228. tend inherit a template from an existing template in a library Template name Area Object Caneel Object type 3 Select one of the following options to start the new template Create a template ready to operate in Qlarity Foundry Use this option to insert the new template boilerplate code into your workspace see section 10 5 1 New Template Boilerplate Code Create a completely blank template Use this option to start with a blank unprogrammed object template You will need to add all Qlarity code 4 Type a name for the new template in the Template Name edit box 5 Select the type of object non drawable area object or container from the Object Type list box Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual 10 11 Click OK The new template name appears in the Add Edit Templates dialog box Click Close to close the Add Edit Templates dialog box Select Code View The new template name appears under the Templates icon in the Object Tree Templates are not shown in the Object Tree in Layout View Click on the new template in the Object Tree If you created a template ready to operate in QF the boiler plate code appears in the edit window Variables declared inside a template become properties of the template object and functions declared inside the template become the object s metho
229. ter a new value Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Highlight object under the mouse If this option is enabled each object s outline is highlighted as you move the mouse pointer over it If disabled an object s outline only appears when you click it Show data types in properties window If this option is enabled the data type of each property integer color string boolean bdf font etc 1s shown in the Properties window Show pop up help for objects and properties If this option is enabled a Help pop up appears when you move the mouse pointer over icons in the Object Palette and when you click on properties in the Properties window The text for the pop up Help is based on the Object Documenta tion file which you can view by pressing lt F1 gt Tab Location From the drop down list select your preferred location in the window for the Layout View and Code View tabs Layout View Colors The components that appear in the work area layout are listed Click a component to display an example in the Sample box of the color in which it appears in the work area Double click an item to change the color A color selector dialog box appears Click a color in the basic colors section to select it To create a custom color drag the color selector in the rainbow palette to a color and then drag the slider up or down to adjust the satura
230. that Qlarity Foundry will insert a blank entry in the library To enter the programming code for the object template select the new entry and click Edit Entry You can also add new object templates that you have already created with the Send Template to Library option in Add Edit Templates see section 5 1 5 for information 5 3 4 Advanced Click Advanced to display the advanced options for edit ing the standard and core libraries OptoTerminal Qlarity Foundry User s Manual Advanced Library Options Edit standard natives lib System libraries that are not explicitly included in this Workspace Include as reference recommended OF Cancel 5 3 4 1 Edit Standard natives lib In addition to native API functions as described in the OptoTerminal Programmer s Reference Manual the stan dard Natives library natives lib contains several utility functions written in the Qlarity language To make these functions available type the following in the Globals sec tion of your workspace library standard source lt entryname gt lt entryname gt is the name of the library that contains the additional API functions you want to use To determine the entry in which a function resides locate the function in the Object Documentation Help file Each utility function in the library begins with the underscore _ character Click the Edit standard button to view the utility func tions includ
231. that can be performed by the object type 8 4 1 Overview of Event Builder Steps To design a user application using Event Builder you will generally take the following steps e Decide what you want your Qlarity application to do e Determine which objects you need Some objects will be used for events others will perform the actions associ ated with the events Place all of the objects in the work space e Outline each event action association e g when a but ton 1s pressed an action or actions occur e Use Event Builder to assign actions to each event 8 4 2 Event Builder Dialog Box In Layout View select an object in the workspace for which you want to set up an event The properties and events asso ciated with the object are displayed in the Properties win dow Click the Events tab to see the events associated with the selected object Object Properties Properties Events click Bi handler elease Ej handlePress E amp a T Click El next to an event to open the Event Builder dialog box to assign actions to the event Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual Action AA Fa 1 Click to add action Select what type of action you wish to add from the drop down list in the grid Once you have selected a general action type you may customize what exactly occurs during that action Cancel Edit in
232. the Qlarity programming language An example of the work area of a workspace in Layout View is shown below Security View Gutside On Dutside Off gt Layout View closely simulates how the workspace will appear after it has been compiled and downloaded to the Qlarity based terminal If you understand the Qlarity programming language you may use Code View to work with an object s programming code Select an object instance and click the Code View tab to display the property initializations for the object instance Object instance code may also contain method overrides which change the behavior of an object instance from that specified in the object template The following example shows the code for a text object in the sample workspace in the Layout View example above OptoTerminal Qlarity Foundry User s Manual parent i SetTernp xpos i 42 yoos 210 width 236 height 20 caption Currently set to font helvi4 transparent true fgcolor rgb white The following example shows the first portion of the pro gramming code for the TemperatureUpdate template Him enabled as boolean init enabled true func enabled newval as boolean enabled newval enable me enabled endfunc dim parent as objref func parent newval as objref parent neral attach me parent endfunoc current temperature values dim ctemp 4 as float init ctemp i F1 71 Fl 71 func ct
233. the list of tutorials displayed Click the tutorial you want to work and the tutorial pdf file 1s opened in Adobe Acrobat Read through the tutorial and follow the instructions using the sample workspace Begin editing in Layout View If this option is enabled a workspace is automatically com piled and shown in the Layout View when it is opened If disabled the workspace is displayed in Code View and will need to be compiled before it can be displayed in Lay out View You can also change this setting using the Set tings function Compile tab see section 6 4 Compile Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 3 3 Main Window The Qlarity Foundry main window is shown below g Olarity Foundry 2 501 New Workspace Globals File Edit view Tools Help Vienu Bar Deng xl Layout scale 1 v Outline all objects Theme classic w Misc Bar A af ExceptionDisplay EN a OptoPACComm Hs ae af ScreenSaver Object Tree Work Area Duo Errors OptoTerminal Qlarity Foundry User s Manual Gal AM il A 2 Toolbar Object Palette Seas 40 Be 1 E El E _defaulipaccommo optopaccornm Properties window Messages and Errors window Menu Bar The menu bar contains the File Edit View Tools and Help menus Refer to section 3 4 for a brief description of the menu options You can access all Qlarity Foundry options from the menus Toolbar The tool
234. the parameters and return type for this function The allowed parameters and return type depend on what message is being handled There are no restrictions on the name of the function except those imposed by Qlar ity See the OptoTerminal Programmer s Reference Manual for more details Also a handles statement is needed on the line fol lowing the function declaration The statement begins with the keyword handles followed by the name of the message that is being handled by the function For example the following code declares a new mes sage handler named timer that handles MSG_TIMETICK As explained in the OptoTerminal Programmer s Reference Manual the handler takes no parameters and does not return a value func timer handles MSG_TIMETICK endfunc Fill the body of the handler on lines between the han dles statement and the endfunc statement with the Qlarity code to implement the desired function If the handler returns a value be sure to include a return statement For more information see the OptoTerminal Programmer s Reference Manual For example the handler described above could check the value of a global variable named threshold and enable an object named cal_screen if threshold is greater than 10 Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 86 The complete function example follows func timer handles MSG _TIMETICK
235. the small image next to the label as well as in the preview box NOTE named border changed for all assigned objects When you change the border design for a named border it is changed for all objects and properties to which the named border is assigned Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 OptoTerminal Qlarity Foundry User s Manual NOTE changes to named borders and themes Any change to a named border only applies to the currently selected theme If you are making changes to more than one theme make sure you click Save current border and color settings as theme before you change themes When you have finished editing or creating named borders click OK to save the changes and exit or click Cancel to discard the changes and exit 5 5 2 1 General Effects Border Width In the Border width box enter or click the arrow buttons to select the width of the border in number of pixels 3D Bevel If you want a beveled border as for a button select 3D Bevel The options to select a raised or sunken bevel appear You can see the effect of each option in the pre view Border Color If you do not select a 3D bevel you can select a different color for the border Click Border Color and a Select Color palette appears from which to select the color If you want to match a color from another object in the workspace click 2 beneath the color palette and an image of the workspace is d
236. tion and lightness of the color or enter the HSL or RGB of a color Click OK to change the component to the selected color The work area components include the following Out of Display The area that the legend covers not shown if Show Legend Around Display is enabled Display Border The line separating the border and the work area not shown if Show Legend Around Display is enabled Selected Object An object that you click The selected color outlines the object to show that it is selected Hot Object The object under the mouse pointer if Highlight object under the mouse is selected The selected color out lines the object as the pointer moves over it 45 Object Outlines The outlines around objects if Outline all objects on the toolbar is enabled Grid Grid lines appear in the selected color if Show Grid is enabled Allow Locked Objects to be Moved within Object Tree If an object is locked it cannot be moved in the work area If this function is enabled however a locked object can be moved in the Object Tree 6 3 Editor Click the Editor tab to set up options for Code View The code editor is displayed when Code View is selected and is used to enter and edit objects programming code Glarity Foundry Preferences Terminal Layout Editor Compile Simulation Colors Font sample Text Courier New Tab Spacing E r Show advanced code section
237. u can also use the Add Edit Templates function to change the name of an existing template Click on the toolbar or select Add Edit Templates from the Edit menu and the Add Edit Templates dialog box is displayed You can also right click anywhere in the Templates branch of the Object Tree and click Add Edit Templates on the shortcut menu FE Add Edit Templates Base Template Template New Template Remove lempate 5 1 1 Add a New Object Template In the Add Edit Templates dialog box do the following to create a new object template 1 Click New Template and the following dialog box is displayed New Template Vizard SETENTA O e eormne Create a completely blank template Copy the code of an existing template in a library C E stend inherit a template from an existing template in a library Template name Area Object Caneel Object type 2 Select one of the following options to start the new template Create a template ready to operate in Qlarity Foundry Use this option to create a new object template by start ing with the programming code for a basic object that will function in Qlarity Foundry and display on the screen Additional programming is required to define the object s function appearance and so on Create a completely blank template Use this option to start with a blank unprogrammed object template Copy the code of an existing tem
238. u want to save the workspace that was loaded or click No if you do not want to save it A new unnamed project is started using the default resources from the previous workspace At this point you can start a new project or open a different project using the Open Work space option 4 4 Save a Workspace The first time you save a new workspace the Save As dia log box appears so that you can enter a name for the work space file see section 4 4 2 Then when you save the file 1t 1s saved to the file name you entered If you want to make a copy of the workspace or change the file name use Save Workspace As If you want to transfer a workspace to another computer use the Collect for Output function see section 4 4 3 below 4 4 1 Save Workspace To save a workspace click E on the toolbar or select Save Workspace from the File menu If you have already named the workspace the file is saved If it is a new work space and you have not yet named it the Save As dialog box appears see section 4 4 2 4 4 2 Save Workspace As To save a workspace to a different name select Save Work space As from the File menu The following dialog box is displayed 25 Save in a Samples e 1 Ed communications packet parsing Demo g7Odemo g Sdemo games hvac sample transflective demo Libasic_keyboard aly Libasic_serial_communication qly Lipassword _protected_screen qly File name o Cancel
239. unctions such as Str Also data in objects must be converted to strings before they can be transmitted out the serial port You may use the _StrToCharstr and _CharstrToStr functions to convert between string types For more information press lt F1 gt to view Object Docu mentation refer to section 3 4 5 Help Menu Start in Layout View If this option is enabled a workspace is compiled as soon as you load it If you typically work in Layout View you will want this feature enabled If you work more often in Code View or your workspace has errors that haven t been cor rected yet you may want to disable it 6 5 Simulation View Use the options in the Simulation View tab to adjust or mute the sound during terminal simulation to set up communica tions for the Communications window in Simulation View to set up the computer s ports to simulate the serial ports on the Qlarity based terminal and to specify simulated keypad settings for applications that use an external keypad Qlarity Foundry Preferences l x Terminal Layout Editor Compile Simulation Speaker Volume Communications Window Settings Keypad Settings Select T Mute Ethernet simulation Default simulation Play sound at break paint Serial Port Setup Terminal Port 115200 aH Hone 115200 aH Hone lt hOre gt nones These settings are the initial communications settings that the com port s use in Simulation
240. undry work area which includes the QSI standard touch key legend set ting to set up compile defaults and to set up the Simula tion display Refer to Chapter 6 Qlarity Foundry Preferences for more information 8 1 3 Drawing Aids When arranging the graphical objects on the terminal dis play proper alignment is important Qlarity Foundry pro vides the following tools to assist you with object layout Layout scale 1 To change the scale of the work area click the drop down arrow and select the scale from the drop down list Outline all objects Select this option to draw a line around all defined objects This is useful when you want to know the exact border loca tion of each object or when one or more objects was acci dently moved out of the work area 61 Grid You can display a grid over the work area to help you more accurately place and align objects You can turn the grid off and on and change the spacing and color of the grid lines Snap to Grid If enabled this feature forces objects to snap to the near est grid line when added or moved The top left corner of an object s rectangle snaps to the nearest horizontal and verti cal grid lines when you release the mouse button To customize the grid and enable Snap to Grid click on the toolbar or select Settings from the View menu Click the Layout tab and edit the follow settings as needed refer to section 6 2 for more informat
241. until replaced by another cut or copy operation Copy In Layout View select an object in the work area then select this option or press lt Ctrl gt lt C gt to make a copy of the object In Code View select code then select this option or press lt Ctrl gt lt C gt to copy the selected code The object or code remains on the Windows clipboard until replaced by another cut or copy operation Paste In Layout View select this option or press lt Ctrl gt lt V gt to place a cut or copied object in a new location in the same workspace or in a different workspace In Code View select this option or press lt Ctrll gt lt V gt to place cut or copied code at the cursor position in the same or a different work space or in a different Windows application Find Code View only Select this option to find code in the displayed object instance template or workspace Enter the characters or code you want to find and click Find Next To find only characters matching the entered case upper or lower select Match Case To search through all object instances and templates in the workspace select Entire Workspace OptoTerminal Qlarity Foundry User s Manual Replace Code View only Select this option to find code in the displayed object instance or template and replace it with specified code In the Find What field enter the characters or code you want to find In the Replace With fiel
242. up of objects in the workspace Before select ing a tool select the group of objects you want to manipu late using one of the following methods e Click and drag to create a selection box that encompasses all of the objects you want to select To cancel the box click outside it e Press and hold lt Ctrl gt or lt Shift gt and select objects either by clicking on them in the workspace or by clicking on their names in the Object Tree NOTE objects must have common parent When aligning or spacing objects all selected objects must share the same object parent 1 e must be in the same ter minal screen When sizing objects all selected objects must have a width or height property With the group of objects selected either right click one of the selected objects in the work area or pull down the Tools menu and select Align Size Space Objects If you are aligning or sizing the objects they will be aligned or sized with the actively selected object in the group To make an object active do one of the following e Right click the object to select Align Size Space Objects from its right click menu 67 e Press and hold lt Ctrl gt while you click the object in the workspace or the Object Tree The active object is indicated by solid resize grips and by bold highlighting in the Object Tree The following options are available on the Align Size Space Objects menu Align left Aligns the left most resize grip of each se
243. value Apart from these restrictions the function is written and behaves as a normal function The validation function can be explicitly called from other Qlarity functions if desired For example when the graph level property of a bar graph object is changed you need to redraw the graph at the new level Also values outside the range of the gauge should be clipped to a maximum or minimum value These can both be accomplished with a validation function for the graph level property Suppose that the property is an integer named graphlevel The validation function might look like the following func graphlevel newval as integer clip to the max or min value 1f newval gt maxval then newval maxval elseif newval lt minval then newval minval endif Now assign newval to level Note the use of strict assignment op graphlevel newval Now request this object to redraw rerender me endfunc The Rerender function is a Qlarity API function see section 10 3 The Qlarity API Library that generates a MSG_DRAW message for the area of the object For array properties separate validation functions can be written for assignment of the entire array and assignment of individual elements of the array See Array Validation Functions and Array Element Validation Function sec OptoTerminal Qlarity Foundry User s Manual tions of the OptoTerminal Programmer s Reference Man ual fo
244. workspaces in Qlarity Foundry J Chapter 5 Templates Resources and Libraries How to add and edit templates advanced function edit resources and edit libraries O Chapter 6 Qlarity Foundry Preferences How to set up and define your terminal settings for Qlarity Foundry and enter Qlarity Foundry preferences J Chapter 7 Download Software to the Terminal How to configure the terminal communications port download user applications and BFF files and upgrade new firmware J Appendix A Glossary of Software Terms A list of Qlarity terms and their definitions You should read and understand these terms before you attempt to perform the functions described in Chapter 9 and Chapter 10 Also available is the OptoTerminal Quick Start Guide Opto 22 form 1338 1 2 Description Olarity pronounced clarity the programming language used to program the Qlarity based terminal is a powerful BASIC like language that utilizes the full potential of the Qlarity based terminal Qlarity Foundry is a Windows based design tool that uses Qlarity to help you design user applications for the Qlarity based terminal Qlarity uses objects as the building blocks for all user applications An object can take many forms including text labels and fields bitmaps lines forms key definitions clocks counters and so on Libraries which are supplied with Qlarity Foundry contain predefined objects for w
245. y that have not been added to the workspace 2 Select one or more libraries from the list Opto 22 Fax 800 832 OPTO 6786 Web www opto22 com Phone 800 321 OPTO 6786 34 To select multiple libraries that appear consecutively in the list press and hold lt Shift gt then click the first and last library in the group you want to select To select multiple non consecutive libraries press and hold lt Ctrl gt then click each library that you want to select The objects in the selected library or libraries are dis played at the bottom of the dialog box 3 Click OK to close the dialog box and the selected libraries are added to the workspace The objects in the new libraries are added to the Object Palette 4 To add a library that is not listed click Add Other Library and an Open dialog box appears Select the library or libraries that you want to add change the folder if necessary and click Open The library is added to the workspace 5 Click Close to save your changes and exit the dialog box The workspace is compiled and the objects in the new library are available for use in the workspace 6 Save the workspace to save the information to disk 5 3 2 Remove Library Do the following to remove a library from the current work space 1 All libraries that are loaded in the workspace are listed Click the library that you want to remove It is high lighted 2 Click Remove Library and the library file

Qlarity Foundry User's Manual

Contents

Download Pdf Manuals

Related Search

Related Contents