E4CoderGUI Reference Manual

Transcription

1 E4CoderGUI Reference Manual Rapid User Interface Prototyping for Scicos Models Version: 1.2 May 30, 2014

2 About Evidence S.r.l. Evidence is a company operating in the field of software for embedded real-time systems. It started in 2002 as a spin-off company of the Real-Time Systems (ReTiS) Lab of the Scuola Superiore Sant Anna (Pisa, Italy). Today, Evidence is a dynamic company having collaborations in the field of electronics, telecommunications, automotives, and industrial automation. People at Evidence are experts in the domain of embedded and real-time systems, with a deep knowledge on the design and specification flow of embedded software, especially for the embedded market. Besides providing consultancy services, Evidence also provides: BSPs based on Linux for embedded devices, evaluation boards featuring most innovative 8, 16 and 32-bit microcontrollers for the embedded market, development tools for making embedded software development easier, and tools for the schedulability analysis of real-time tasks running on your final product. For more information see: Contact Info Evidence Srl, Via Carducci 56 Località Ghezzano S.Giuliano Terme PISA Italy Tel: Fax: For more information about Evidence products, please send an to the following address: info@evidence.eu.com. Other information about the Evidence product line can be found at the Evidence web site at: This document is Copyright Evidence S.r.l. Information and images contained within this document are copyright and the property of Evidence S.r.l. All trademarks are hereby acknowledged to be the properties of their respective owners. The information, text and graphics contained in this document are provided for information purposes only by Evidence S.r.l. Evidence S.r.l. does not warrant the accuracy, or completeness of the information, text, and other items contained in this document. Matlab, Simulink, Mathworks are registered trademarks of Matworks Inc. Microsoft, Windows are registered trademarks of Microsoft Inc. Java is a registered trademark of Sun Microsystems. in the USA. and other countries, and are used under license. All other trademarks used are properties of their respective owners. This document has been written using L A TEX. 2

3 Contents 1. Introduction Quick feature list Requirements Licensing Installation Technical support Use Cases Rapid Prototyping Simulation Code Generation Quick Start Creating a New Diagram Designing the User Interface Laying out the Scicos Diagram Simulation Integration with ScicosLab Simulation of a User Interface The E4CoderGUI Editor Frame and Elements Properties Managing Ports Connections Menus Interface Elements Button Button Image Button Knob Button LED Color Bar Image Needle Plot Plotter 2D

4 Contents Rectangle Roller and Slider SpinBox Switch Text Label Tracker 2D Code Generation of an E4CoderGUI Block Examples Dashboard Plotting Fullscreen Integers A. QT Libraries Licensing 52 4

5 List of Figures 2.1. A user interface used for rapid prototyping Menu option to load the E4Coder toolbox Commands to launch Scicos with a new diagram Message warning that the specified file does not exist and will be created upon save The menu item to access the Palette Tree, containing all the blocks that can be added to a diagram An item from the Palettes window can be dragged into the diagram to create a new block In order to set the name of the GUI file for a block, double-click on it, choose Properties (a), and then type the file name (b) The system will report that tutorial.xml does not exist The Name property of the Frame is used to set the title of the user interface window (a) Adding an Integer input port and (b) setting its name (a) Adding a Boolean output port and (b) setting its name To add a Text Label element, select it from the Palette (a), drag it into the frame (b), and drop it at the center (c) The InputPort property links the Text Label element to an input port To add a Text Label element, select it from the palette (a), drag it into the frame (b), and drop it at the center (c) The OutputPort property links the Button element to an output port (a), the Text property sets the title of the button The unsaved changes dialog shown when closing the GUI editor The menu option to resize a block (a), and the resize window (b) The E4CoderGUI block displays the GUI file name ( tutorial.xml ), and the input and output ports names The properties for the Counter block Flipping a block The properties for the DOLLAR m block The complete Scicos diagram with all the connections in place The Setup option of the Simulate menu (a) allows to set many simulation parameters (b) The GUI window during simulation An E4CoderGUI block with two inputs and two outputs

6 List of Figures 4.2. E4CoderGUI block properties dialog box E4CoderGUI block parameters The E4CoderGUI editor window An empty UI with the frame selected for editing Adding an element from the palette Adding new elements by selecting them from the Add button (a) or from the Insert menu (b) You can use these buttons to align the items in E4CoderGUI An image path property Importing an image from outside the resource folder, i.e. the location of the user interface definition file (.xml) Input (a) and output (b) ports in the content panel Connecting an input port to an element The File menu The Edit menu About panel Button element Button Image element Button Knob element Button LED element Color Bar element Image element Needle element Plot element Plotter 2D element Rectangle element Roller element Slider element SpinBox element Switch element Text Label element Tracker 2D element The examples for E4CoderGUI are available through the E4coder Demos option of the E4coder menu in the Scicos window (a), which will show the examples list (b) The E4CoderGUI block in the Dashboard Scicos diagram The user interface for the Dashboard example Curve modeling the input function for the Throttle in the Dashboard example The Scicos diagram for the Plotting example The user interface shown in the Plotting example The Scicos diagram for the Fullscreen example

7 List of Figures 7.8. Setting the fullscreen property for a frame in the E4CoderGUI editor The user interface of the Fullscreen example The Integers example user interface The Integers example Scicos model

8 List of Tables 5.1. List of the kinds of ports available and their corresponding types in Scicos. 35 8

9 About this document This document describes E4CoderGUI, a rapid prototyping tool to create graphical user interfaces and integrate them with a Scicos model. Function of the document The function of this document is to provide a reference manual for the various functionalities offered by E4CoderGUI. Document history Version Date Author Company Change Description Oct 2012 Alessandro Evidence Srl Released version 1.0 Passaro, Paolo Gai May 2013 Paolo Gai Evidence Srl Added code generation details Nov 2013 Paolo Gai Evidence Srl Updated screenshots. Added toolbar for item alignment. Updated description of of the Plot widget. 9

10 List of Tables Acronyms Acronym E4Coder E4Coder GUI GUI Meaning E4Coder is a factorized acronym meaning Evidence Erika Enterprise Embedded Coder. Initially meant as a code generation tool supporting the ERIKA Enterprise RTOS, it is now a general purpose code generation toolset. In that sense, it can be now also interpreted as Evidence For Coder, as a set of tools for simulation and code generation of complex designs. E4Coder GUI is the GUI editor for fast prototyping of graphical user interfaces. Graphical User Interface 10

11 1. Introduction E4CoderGUI is a tool useful for designing and simulating graphical user interfaces. With E4CoderGUI, you will be able to: Design interactive graphical panels composed by a number of widgets. Integrate the panels inside a ScicosLab [1] Diagram, connecting the widget animations to the inputs and to the outputs of a E4CoderGUI ScicosLab block. Interact with panels during ScicosLab simulations. Generate Qt code to be used in standalone applications. The following Chapters will describe the main functionalities of E4CoderGUI, as well as its integration with ScicosLab Quick feature list This is a quick feature list of E4CoderGUI version 1.0: Visual design of Graphical User Interfaces (GUIs), with undo support. XML file format. Configuration of multiple input and output data with different types. Visualization of the GUI in a window during simulation. Export of GUIs screenshots in PNG format. Qt code generation integrated with the E4Coder Code Generator for Linux and Windows targets Requirements E4CoderGUI is distributed with E4Coder, and has the following requirements: ScicosLab for Windows; Visual C (or 2010) Express edition. On Linux: tested on Ubuntu LTS 10.04, other 32 bit versions should also work 1. 1 Please contact us in case of issues in supporting a specific Linux distribution. 11

12 Chapter 1. Introduction 1.3. Licensing E4CoderGUI is distributed with a commercial license together with the E4Coder toolbox. E4CoderGUI uses the Qt Libraries, which are dynamically linked to allow you to change the library with new versions at your choice. Licensing information about the Qt Libraries is available in Appendix A Installation E4CoderGUI is installed as part of E4Coder. Please refer to the E4Coder manual for the installation procedure[2] Technical support For control the order status and license renewals you can refer to the E4Coder web site: Technical support for E4Coder is available directly from Evidence. Please, contact us using the forum: For sales, pricing and general information, please contact Evidence Srl directly at the address and phone numbers available at the following web page: 12

13 2. Use Cases 2.1. Rapid Prototyping E4CoderGUI can be used for rapid prototyping of graphical user interfaces. When creating a Scicos diagram, the user can also design a user interface mimicking the final physical implementation and connect the model I/O to the interface. In particular, E4CoderGUI provides many graphical elements whose appearance can be modified with custom image, so that they can resemble the intended concrete interface. This feature allows to work on the functional model and test the results in a simulated environment as close as possible to the final interface (see Figure 2.1). Figure 2.1.: A user interface used for rapid prototyping Simulation E4CoderGUI can also assist in the creation of the functional model, by providing a quick way to set up an user interface that allows the configuration and fine-tuning of the model. In this scenario, graphical elements such as sliders and plots can be used during the simulation to dynamically change the input parameters of the model and to visualize the results immediately. 13

14 Chapter 2. Use Cases 2.3. Code Generation Finally, E4CoderGUI can be used to generate, together with the E4Coder Code Generator, a standalone graphic executable which can be used either as a GUI standalone prototype (useful to show implementations previews to a customer) or as a final GUI application that includes both the graphical interface as well as the multithread control aspects. 14

15 3. Quick Start This chapter will describe a step by step tutorial to create a simple Scicos diagram with a Graphical User Interface (GUI). The tutorial is intended to offer a quick look at the functionalities provided by E4CoderGUI and an introduction to how to use it. More detailed information will be found in the next chapters Creating a New Diagram The first steps detail the creation in Scicos of a new diagram with a GUI block: Launch ScicosLab. Load the E4Coder Toolbox (see Figure 3.1). Figure 3.1.: Menu option to load the E4Coder toolbox. Change to the directory where you want to save the new diagram, e.g. C:\tutorial (see Figure 3.2). Figure 3.2.: Commands to launch Scicos with a new diagram. 15

16 Chapter 3. Quick Start Launch Scicos with the new diagram file tutorial.cos (see Figure 3.2). Figure 3.3.: Message warning that the specified file does not exist and will be created upon save. Dismiss the warning about creating a new diagram (see Figure 3.3). Figure 3.4.: The menu item to access the Palette Tree, containing all the blocks that can be added to a diagram. Once the Scicos diagram window is open, select the Pal Tree option from the Palette menu (see Figure 3.4). Look for the item E4CoderGUI, under E4Coder - GUI creator. 16

17 Chapter 3. Quick Start Figure 3.5.: An item from the Palettes window can be dragged into the diagram to create a new block. Drag E4CoderGUI into the diagram window, as shown in Figure 3.5. Double-click on the new block to edit it. (a) (b) Figure 3.6.: In order to set the name of the GUI file for a block, double-click on it, choose Properties (a), and then type the file name (b). Choose the Properties button as in Figure 3.6 (a). Type the name of the new GUI file (e.g. tutorial.xml ), as in Figure 3.6 (b). Note that the file name and path are relative to the current working directory. The system will report that the file does not exist, as in Figure 3.7. Please select Yes, and the E4CoderGUI window will appear. 17

18 Chapter 3. Quick Start Figure 3.7.: The system will report that tutorial.xml does not exist Designing the User Interface This section will describe the creation of the user interface linked to the E4CoderGUI block which was added to the diagram in the previous section. The GUI will consist of a simple window with a text label and a button. The text label will show the integer value read from an input port on the block, while the button state will be forwarded to an output port. Figure 3.8.: The Name property of the Frame is used to set the title of the user interface window. Type the Name of the frame as in Figure 3.8. Select the Input Ports section on the left panel. 18

19 Chapter 3. Quick Start (a) (b) Figure 3.9.: (a) Adding an Integer input port and (b) setting its name. Click on the Add button on the toolbar and select Integer, as in Figure 3.9 (a). Type the Name of the input port as in Figure 3.9 (b). Select the Output Ports section on the left panel. (a) (b) Figure 3.10.: (a) Adding a Boolean output port and (b) setting its name. Click on the Add button on the toolbar and select Boolean, as in Figure 3.10 (a). Type the Name of the output port as in Figure 3.10 (b). (a) (b) (c) Figure 3.11.: To add a Text Label element, select it from the Palette (a), drag it into the frame (b), and drop it at the center (c). 19

20 Chapter 3. Quick Start Add a Text Label element from the palette on the right (Figure 3.11 (a)). Drag it to the center of the frame and drop it (Figure 3.11 (b-c)). Figure 3.12.: The InputPort property links the Text Label element to an input port. Edit the Name property of the Text Label. Set the InputPort property to input-port, as in Figure (a) (b) (c) Figure 3.13.: To add a Text Label element, select it from the palette (a), drag it into the frame (b), and drop it at the center (c). Add a Button element from the palette on the right (Figure 3.13 (a)). Drag it to the center of the frame and drop it (Figure 3.13 (b-c)). 20

21 Chapter 3. Quick Start (a) (b) Figure 3.14.: The OutputPort property links the Button element to an output port (a), the Text property sets the title of the button. Edit the Name property of the Button. Set the OutputPort property to output-port, as in Figure 3.14 (a). Set the Text property to Hold, as in Figure 3.14 (b). Figure 3.15.: The unsaved changes dialog shown when closing the GUI editor. Close the editor window and choose to save the changes (see Figure 3.15). Note that the new file will be saved in the current working directory (if you followed this tutorial, it will be saved as c:\tutorial\tutorial.xml ). At this point the work on the user interface is done and we can return to the Scicos diagram Laying out the Scicos Diagram Once the user interface has been designed, it is time to add the other blocks to complete the diagram and connect them to the interface block. Left-click on the E4CoderGUI block, and select Resize under Block Properties, as in Figure 3.16 (a). Set the width to 180 and the height to 80 in the Set Block Size window of Figure 3.16 (b). 21

22 Chapter 3. Quick Start (a) (b) Figure 3.16.: The menu option to resize a block (a), and the resize window (b). Figure 3.17.: The E4CoderGUI block displays the GUI file name ( tutorial.xml ), and the input and output ports names. The E4CoderGUI block should now look as in Figure Note how the input and output ports names are now fully visible and correspond to those set in the editor. From the Sources palette, add a CLOCK c block. Figure 3.18.: The properties for the Counter block. 22

23 Chapter 3. Quick Start Again from the Sources palette, add a Counter block. Double-click on the Counter block, and set its properties as follows (Figure 3.18): set the Minimum to 0, set the Width to 100, set the Rule to 2 (Decrement). Figure 3.19.: Flipping a block. Add a IFTHEL f block from the Branching palette. Flip the IFTHEL f block by left-clicking on it and selecting Flip, as in Figure Figure 3.20.: The properties for the DOLLAR m block. From the Linear palette, add a DOLLAR m block and flip it too. Double-click on the DOLLAR m block and set its Inherit property to 1 (yes). Add a CONVERT block from the Integer palette. Make the following connections: 23

24 Chapter 3. Quick Start The EventOut port of the CLOCK c block to the EventIn ports of the IFTHEL f, DOLLAR m, and E4CoderGUI blocks. The else EventOut port of the IFTHEL f block to the EventIn port of the Counter block. The Output port of the Counter block to the Input port of the CONVERT block. The Output port of the CONVERT block to the input-port of the E4CoderGUI block. The output-port of the E4CoderGUI block to the Input port of the DOLLAR m block. The Output port of the DOLLAR m block to the Input port of the IFTHEL f block. Figure 3.21.: The complete Scicos diagram with all the connections in place. The whole diagram should now look as in Figure Simulation We are now almost ready to start simulating our model. But first we need to set-up a few simulation parameters: Select Setup from the Simulate menu, as in Figure 3.22 (a). Set the following properties (Figure 3.22 (b)): 24

25 Chapter 3. Quick Start (a) (b) Figure 3.22.: The Setup option of the Simulate menu (a) allows to set many simulation parameters (b). Final integration time to 300, Realtime scaling to 1. Figure 3.23.: The GUI window during simulation. In order to start the simulation, choose Run from the Simulate menu. A window containing the user interface will appear, as in Figure The Text Label element will display the value from the counter, decreasing over time from 100 to 0. The Hold button will allow the user to pause the counter when pressed. 25

26 4. Integration with ScicosLab E4CoderGUI provides a customized block which can be used to integrate one or more user interface windows inside a Scicos diagram. The block, named E4CoderGUI (see Figure 4.1), allows to design and then simulate a graphical user interface with a variable number of inputs and outputs. Figure 4.1.: An E4CoderGUI block with two inputs and two outputs. The number and types of inputs and outputs depends on the ports configured in the interface editor. There can be more than one E4CoderGUI block inside a ScicosLab diagram. Double clicking on the E4CoderGUI block opens the Property Dialog Box as shown in Figure 4.2. The window shows two possible options: Properties: which can be used to specify the XML file that will contain the description of the user interface associated with the block (See Figure 4.3). Editor: which can be used to design the user interface (see Chapter 5). Figure 4.2.: E4CoderGUI block properties dialog box. 26

27 Chapter 4. Integration with ScicosLab Figure 4.3.: E4CoderGUI block parameters. The description of the user interface is stored in an external XML file (GUI file); you can specify just the file name (e.g. example.xml ) or the file name with path information (e.g. C:\E4CoderGUI\Demo\example.xml ). The same file can be specified for more than one E4CoderGUI Scicos blocks. Before opening Scicos, please change the current directory to the folder containing the diagram file (.cos). For example, supposing that the Scicos diagram is saved in C:\E4CoderGUI\Demo\example.cos, the commands to type in the Scicos shell are: --> cd C:\E4CoderGUI\Demo --> scicos( example.cos ); 4.1. Simulation of a User Interface Each GUI block represents a single frame, which is a graphical interface containing multiple elements. When laying out the diagram, the E4CoderGUI editor is used to design the frame and configure both the communication ports and the elements inside the frame (see Chapter 5). During simulation, instead, the frame related to each block is displayed in its own window and the I/O ports are connected to the elements according to the configuration. Passive elements such as text labels, which are connected to input ports, will be updated at every simulation step. On the other hand, active elements, such as buttons, connected to output ports, can be operated by the user at any time during simulation. Active elements update the state of the output ports, which will in turn by forwarded to the Scicos block at the next occurring step in the simulation. In summary, the following operations are performed at each step in the simulation: The data is collected from the connections on the input ports of the block and is forwarded to the GUI. 27

28 Chapter 4. Integration with ScicosLab Each element connected with an input port is updated with the new data. The state of the output ports is read and forwarded to the Scicos block. Note that if an active element changes its state multiple times between two simulation steps, only the final state will be forwarded to Scicos. 28

29 5. The E4CoderGUI Editor The E4CoderGUI editor is started after clicking on the Editor button in the E4CoderGUI block properties dialog box. The E4CoderGUI editor appears as shown in Figure 5.1. Figure 5.1.: The E4CoderGUI editor window. The user interface is composed of the following graphical regions: A menu bar, with the usual commands for file handling, Cut & Paste, Export, and so on.. The contents panel (on the left), showing a list of the elements already placed in the user interface, together with the input and output ports. The elements palette (on the right), containing the elements that can be added to the user interface. The working area (at the center), which is a representation of the user interface panel. The properties editor (at the bottom), which allows to set the properties of the selected element. 29

30 Chapter 5. The E4CoderGUI Editor 5.1. Frame and Elements A user interface designed with E4CoderGUI is composed by a frame and several elements inside it. In the simulation phase the frame will appear inside a window; in the design phase, it is represented graphically in the working area and can also be found at the root of the contents tree on the left (see Figure 5.2). Figure 5.2.: An empty UI with the frame selected for editing. While the frame is selected, the user can modify it in two ways: By dragging the blue triangle in the lower left corner of the frame shown in the working area, the user can resize the frame to the desired width and height. By editing its properties in the Properties Editor at the bottom of the window. Figure 5.3.: Adding an element from the palette. A frame contains other interface elements, such as buttons, images, text labels, and other widgets. These elements can be added to the frame in various ways: 30

31 Chapter 5. The E4CoderGUI Editor Drag & Drop: the elements can be dragged from the palette on the right and dropped into the frame in the working area, as shown in Figure 5.3. Add button: the drop-down menu activated by the Add button above the content panel allows to insert a new element of the desired kind (see Figure 5.4(a)). Insert menu: the Insert menu, shown in Figure 5.4(b), also allows to insert new elements. (a) (b) Figure 5.4.: Adding new elements by selecting them from the Add button (a) or from the Insert menu (b). Once an element is placed in the working area, it can be moved to a new position by clicking inside its bounding box and dragging it with the mouse. It can also be resized by acting on the blue triangle in its lower left corner, similarly to how described for the whole frame. Additional operations that can be performed on an element are: Deletion: an element can be removed by pressing the Delete key, clicking on the Remove button in the content panel toolbar, or by selecting Remove from the Edit menu. Reordering: the Up and Down arrows in the content panel toolbar (or the corresponding items in the Edit menu) allows to change the order of the elements. This affects the order in which overlapping elements are drawn: elements appearing later in the list will be drawn on top of previous elements. 31

32 Chapter 5. The E4CoderGUI Editor Selection and alignment: a set of items can be selected using mouse clicks (while pressing the Shift key), or by mouse selection on the Frame tab. Once selected, items can be aligned by using the buttons in the toolbar (see Figure 5.5). Figure 5.5.: You can use these buttons to align the items in E4CoderGUI 5.2. Properties The Properties panel shows a list of the properties of the currently selected object. The user can select any object in the content panel: the frame, its elements, and the input/output ports. Moreover, an element can also be selected in the working area, where it will be highlighted with a blue rectangle. The frame itself can be selected by clicking on any point of the working area outside of an element bounding box. The actual list of properties varies with each kind of object. However, the most common properties include: Name: Every object can be given a name, although it is only used to help the user identify the object in the content panel or when connecting ports. The exception is the name of the whole frame, which is displayed in the window title bar during simulation. Size: All graphical elements (frame included) have a size property which specifies the element s width and height in pixels. Position: This property specifies the x, y coordinates (in pixels) of the elements relative to the frame. Input/Output Ports: These properties are used to connect an element to a communication port (see Section 5.3). Font: Many elements allow to select the font in which text will be displayed. The font property shows the name, style, and size of the selected font and provides a dialog where the user can pick any font among those installed in the system. Please note that when a user interface is opened on a different system, the previously selected fonts may not be installed. In such cases the system default font will be used instead. Color: An element can have multiple color properties (e.g. text color, background color, etc.). The color can be set by typing the RGBA hexadecimal string representing the color, or by opening the color picker. 32

33 Chapter 5. The E4CoderGUI Editor (a) (b) (c) Figure 5.6.: An image path property. Figure 5.7.: Importing an image from outside the resource folder, i.e. the location of the user interface definition file (.xml). Images: Elements that can visualize external images have one or more imagepath properties to specify the path of the images. Allowed path must be relative either to the resource folder, i.e. the location of the user interface definition file (.xml), or to the default images location. Figure 5.6 shows the buttons that allow to browse the file-system to select the image from the resource folder (a), from the default image library (b), or to reset the property (c). If the user chooses an image file that is located outside the resource folder, an option is shown allowing to save a copy of the file inside it (see Figure 5.7). The Frame object allows to set an additional fullscreen property to control the appearance of the frame during simulation. If this property is set to true, the frame window will be shown in full-screen during simulation. When in this mode, it is always possible to close the window, and terminate the simulation, by pressing ALT-F4. Other systemwide keys combinations also work (e.g. ALT-TAB). The default value for the fullscreen property is false Managing Ports Ports enable data exchange from the Scicos block to the user interface and vice-versa. The user can manage input and output ports in the content panel, as shown in Figure 5.8. The basic operations on ports are: Adding a port: both the input and the output port lists allow to add a new port 33

34 Chapter 5. The E4CoderGUI Editor (a) (b) Figure 5.8.: Input (a) and output (b) ports in the content panel. by clicking on the Add button or by selecting the Insert menu. Available ports are listed in Table 5.1. Removing a port: input and output ports can be removed by clicking on the Remove button, by selecting Delete Selection from the Edit menu, or by pressing the Delete key. Reordering ports: the Up and Down arrow buttons allow to change the order of the ports. This affects the connections in the Scicos diagram. Renaming a port: every port can be renamed by editing its Name property in the properties panel. Additionally, input ports of kind Text have a Length property that allows to set the desired maximum text length accepted on that port. Any changes to the ports will be reflected on the Scicos block once the file is saved and the editor window is closed. 34

35 Chapter 5. The E4CoderGUI Editor Input Ports Output Ports Kind Boolean Integer Real Text Boolean Integer Real Scicos Type int32 int32 double uint8[length] int32 int32 double Table 5.1.: List of the kinds of ports available and their corresponding types in Scicos. Figure 5.9.: Connecting an input port to an element Connections All the elements have one or more properties of type either inputport or outputport which allow to connect the element to a port. Figure 5.9 shows an example of editing an inputport property by selecting one of the existing input ports. Note that if the property is left empty, the element will be disconnected from any port. During the simulation phase, an input port will send to any connected element the data received from the Scicos block. Depending on the specific element, the data will then be displayed, or at least affect the state of the element. Conversely, output ports will receive data from the element which they are connected to and forward it to the Scicos block Menus Figure 5.10.: The File menu. 35

36 Chapter 5. The E4CoderGUI Editor Figure 5.11.: The Edit menu. Figure 5.12.: About panel. The E4CoderGUI editor menu bar provides 4 menus: File: The File menu, shown in Figure 5.10, allows the user to save the user interface to disk, export a screenshot of the interface, and quit the editor application. Edit: The Edit menu, shown in Figure 5.11, provides Undo/Redo functionalities, together with the elements and ports reordering and deletion commands described in Sections 5.1 and 5.3). Insert: The Insert menu allows to add elements and ports, as described in Sections 5.1 and 5.3 (see Figure 5.4(b)). Help: The Help menu shows an About panel with information about your version of E4CoderGUI, together with access to the license installed in your system (see Figure 5.12). 36

37 Chapter 5. The E4CoderGUI Editor 5.5. Interface Elements This section contains a description of all the elements that can be added to an user interface frame. For each element, a brief description is provided together with advices on how to set it up properly. Important properties besides common ones such as Name, Size, and Position will also be discussed Button Figure 5.13.: Button element. The Button element, shown in Figure 5.13, represents a clickable widget with 2 states: Pressed and Released. The state of the button is sent to the output port connected through the OutputPort property as a boolean value, with 1 representing the Pressed state and 0 the Released state. The user can also change the caption of the button by setting the Text property Button Image Figure 5.14.: Button Image element. The Button Image element, shown in Figure 5.14, is quite similar to the Button element, with the main difference being that the user has to specify two images to represent the two states. The two properties PressedImagePath and ReleasedImagePath serve this purpose. As with the Button element, the state of the button is send to the output port connected through the OutputPort. Note that a Button Image element has no caption Button Knob Figure 5.15.: Button Knob element. The Button Knob element, shown in Figure 5.15, is a special kind of button that can be rotated by dragging with the mouse during the simulation. As with the Button 37

38 Chapter 5. The E4CoderGUI Editor Image element, the user has to specify two images to represent the two states using the two properties PressedImagePath and ReleasedImagePath. However, besides the OutputPort property with the Pressed/Release state, a Button Knob also provides a RotationOutputPort which outputs the current rotation angle θ (in degrees) of the knob. Note that the knob rotates continuously, that is, multiple turns in one direction, e.g. counter-clockwise, will lead to values of θ Button LED Figure 5.16.: Button LED element. The Button LED element, shown in Figure 5.16, represents a button with an additional Active/Inactive state. Together with the Pressed/Released state, this brings 4 state combinations, which are all matched with a different image set with the 4 properties: ActivePressedImagePath, ActiveReleasedImagePath, InactivePressedImagePath, and InactiveReleasedImagePath. As with the other buttons, the Pressed/Release state is linked to the OutputPort property, while the Active/Inactive state is linked to a boolean input port, set through the InputPort property. Moreover, the initial state of the button can be set with the IntialState property Color Bar Figure 5.17.: Color Bar element. The Color Bar element, shown in Figure 5.17, provides a graphical indicator for a level or progress value, which is linked to an integer input port through the InputPort property. In order to define the range of values, the user must set the Minimum and Maximum properties. Values outside the range will be clamped to the minimum or maximum value. The Value property can be used to set the initial level of the bar. The graphical appearance of the Color Bar can be customized by setting the following properties: Orientation: Defines the orientation of the bar and takes the 4 values, TopToBottom, BottomToTop, LeftToRight, and RightToLeft. 38

39 Chapter 5. The E4CoderGUI Editor FillColor: The color for the full portion of the bar. BackgroundColor: The color for the background. Note that if the FillColor is not completely opaque, the BackgroundColor can be seen through it in the full portion. TextOption: Selects the text mode: NoText: no text is shown; Absolute: the integer value is shown as a text label at the center of the bar; Percentage: the percentual value is calculated and shown at the center of the bar. TextFont: Sets the font for the text label, if visible. TextColor: Sets the color for the text label, if visible Image Figure 5.18.: Image element. The Image element, shown in Figure 5.18, draws an image according to its state, which can be Active/Inactive. The properties ActiveImagePath and InactiveImagePath allow to set the image shown in each state. Note that if no image is set for one of the states, the element will be effectively hidden when in that state. The Active/Inactive state is linked to a boolean input port, set through the InputPort property. Moreover, the initial state of the element can be set with the IntialState property Needle Figure 5.19.: Needle element. The Needle element, shown in Figure 5.19, represents an indicator needle. The needle rotates following the input value provided by the real input port connected through the 39

40 Chapter 5. The E4CoderGUI Editor InputPort property. The rotation assumes that the value is a counter-clockwise angle in degrees. An initial value for the angle can be set through the InitialValue property. The image representing the needle is specified with the NeedleImagePath property. Additionally, a pivot point must be defined around which the rotation will take place. The ImagePivotPoint property sets the pivot on the image, while the ElementPivotPoint sets the same point in the element coordinates Plot Figure 5.20.: Plot element. The Plot element, shown in Figure 5.20, provides basic plotting capabilities. This element plots a data series showing the simulation steps on the X axis and the value obtained from a real input port (connected through the InputPort property) on the Y axis. If the parameter yscaletype is set to Manual, then the scale is fixed to the range [yminimum... ymaximum]. If the parameter yscaletype is set to Automatic, then the scale on both axes will adjust dynamically with the range of input values as the simulation progresses. A special plotting mode can be obtained by setting a value higher than 0 for the ScrollWindow property: the value will then be used to set a fixed-sized scale on the X axis, which will scroll to the left as new input values are plotted. The color to be used to plot the data series can be set through the LineColor property. Note that a plot widget is never repainted with a frequency higher than 25Hz to avoid unwanted overhead on the graphical display routines Plotter 2D The Plotter 2D element, shown in Figure 5.21, draws a marker image on a plane taking as input two coordinates. The properties XInputPort and YInputPort are used to set the connection with two integer input ports, from which the values for the (x, y) coordinates will be read. The element will draw the image set through the MarkerImagePath property centered at the point (x, y). The couple of properties InitialX and InitialY can be used to set the initial location of the marker image. Finally, the BackgroundColor property sets the color of the element background. 40

41 Chapter 5. The E4CoderGUI Editor Figure 5.21.: Plotter 2D element Rectangle Figure 5.22.: Rectangle element. The Rectangle element, shown in Figure 5.22, draws a rectangular area of a different color according to its Active/Inactive state. The properties ActiveColor and InactiveColor allow to set the color for each state. The Active/Inactive state is linked to a boolean input port, set through the InputPort property. Moreover, the initial state of the element can be set with the IntialState property Roller and Slider Figure 5.23.: Roller element. The Roller element (Figure 5.23) and the Slider element (Figure 5.24) both allow to set an integer value inside a fixed range. The two elements are functionally equivalent and 41

42 Chapter 5. The E4CoderGUI Editor Figure 5.24.: Slider element. differ only in their appearance. The range of accepted values is set through the Minimum and Maximum properties, while the initial position depends on the Value property. The OutputPort property allows to forward the value to an integer output port. Finally, the Vertical property switch the appearance of the element between vertical (true - the default for a Roller) and horizontal (false - the default for a Slider) SpinBox Figure 5.25.: SpinBox element. The SpinBox element, shown in Figure 5.25, lets the user insert an integer value during simulation, both by editing the numerical field with the keyboard and by using the increment and decrement buttons. The setup of the element is in fact not at all different than what described for the Roller and the Slider elements (see ): the Minimum and Maximum properties define the range of acceptable values and the Value property the initial value displayed in the numerical field. The value is forwarded to the integer output port set through the OutputPort property. The appearance of a SpinBox element can be customized by setting the Font, the TextColor, and the BackgroundColor properties Switch Figure 5.26.: Switch element. The Switch element, shown in Figure 5.26, represents a toggle with 2 states: On and Off. During simulation, the user can cycle trough the states by clicking on the element. The state of the switch is forwarded to the output port connected through the OutputPort property as a boolean value, with 1 representing the On state and 0 the Off state. In each state, the element is drawn with a different image, which can be set though the OnImagePath or OffImagePath property. 42

43 Chapter 5. The E4CoderGUI Editor Figure 5.27.: Text Label element Text Label The Text Label element, shown in Figure 5.27, displays a text string on the screen. Through its InputPort property, it can be connected to any kind of input port (Text, Boolean, Integer, and Real): if needed, the input will be converted to a string before being shown. The InitialText property allows to set an initial text string. The appearance of a Text Label element can be further customized by setting the Font, the TextColor, and the BackgroundColor properties Tracker 2D Figure 5.28.: Tracker 2D element. The Tracker 2D element, shown in Figure 5.28, is functionally the opposite of the Plotter 2D element described in 5.5.9: like the Plotter 2D, it draws a marker image on a plane, but during simulation it allows the user to click on its surface to set the marker coordinates. Moreover, the (x,y) coordinates set by the user are forwarded to the integer output ports set through the properties XOutputPort and YOutputPort. The appearance of a Tracker 2D element is identical to that of a Plotter 2D: the element will draw the image set through the MarkerImagePath property centered at the point (x, y), whose initial location can be set through the couple of properties InitialX and InitialY. Finally, the BackgroundColor property sets the color of the element background. 43

44 6. Code Generation of an E4CoderGUI Block E4CoderGUI supports not only supports the simulation of a GUI block, but also its code generation. Generating code for an E4CoderGUI block means providing an implementation in C++ language using the Qt libraries which implements the same behavior which can be simulated using ScicosLab. Current target operating systems supported by the E4CoderGUI code generator are Microsoft Windows and Linux. The structure of the generated code is similar in both cases. In particular: The generated code relies on a pre-compiled library containing the E4CoderGUI widgets. The library is linked at compilation time. The generated code is a sequence of Qt function calls which creates one GUI window for each E4CoderGUI lock present in the diagram. The Qt main loop is put at the end of the initialization/background thread. The idea is that all tasks generated by the code generator are mapped to threads with their own priorities; the GUI is then handled in background with respect to those threads. The communication between the step function of the threads and the graphical interface is done in a non-blocking way to allow parallel execution of the threads and the GUI. In particular, the input values sent to the GUI block are queued for later processing by the GUI code, whereas when the block has to produce the output values only the latest value correctly written is used. This behavior allows to easily implement data plotting without loosing samples, and it allows the highfrequency execution of tasks with a frequency independent to the update of the graphical interface. 44

45 7. Examples This Chapter shortly describes a few simple examples that can be used to demonstrate the features of E4CoderGUI. All the examples are listed in the E4Coder demos window shown in Figure 7.1 (b), accessible through the E4coder Demos option of the E4coder menu in the Scicos window, as in Figure 7.1 (a). (a) (b) Figure 7.1.: The examples for E4CoderGUI are available through the E4coder Demos option of the E4coder menu in the Scicos window (a), which will show the examples list (b) Dashboard The Dashboard example simulates an automotive drivetrain in order to model an automatic transmission controller. The transmission controller is implemented in a Scicos diagram inspired by the Simulink Automated Transmission Controller demo 1. However, a GUI block is added to display the resulting data during the simulation. The whole system takes as input two curves, representing the values over time of the throttle and the brake, and simulates the speed of the vehicle, the engine RPM, and the gear. Figure 7.2 shows the DashboardGUI Superblock containing the GUI block. The whole Superblock takes as input the speed of the vehicle, the engine RPM, and the current gear. The input is then processed in order to be forwarded to the graphical elements in the interface. In particular, both the speed and the RPM value are converted into an angle to be visualized on the typical dashboard indicators. 1 See description at products/demos/shipping/simulink/sldemo autotrans.html. 45

46 Chapter 7. Examples Figure 7.2.: The E4CoderGUI block in the Dashboard Scicos diagram. Figure 7.3.: The user interface for the Dashboard example. The Dashboard GUI, shown in Figure 7.3, contains two Needle elements, one for the speed indicator (on the right) and one for the RPM indicator (on the left), and a Text Label element (at the center), visualizing the current gear2. During simulation, the Dashboard GUI shows the system response to a Throttle input function as shown in Figure 7.4 and a Brake constantly at zero. 2 The Text Label element uses the 7 Segment font, available from Please be sure to install it in your system for optimal results. 46

47 Chapter 7. Examples Figure 7.4.: Curve modeling the input function for the Throttle in the Dashboard example Plotting The Plotting example shows a graphical interface to display a sinusoid on a plot and a roller element to set the curve amplitude. Figure 7.5 shows the example diagram: the E4CoderGUI block, in yellow, takes the sinusoid data as input and the value for the amplitude as output. Figure 7.5.: The Scicos diagram for the Plotting example. 47

48 Chapter 7. Examples Figure 7.6.: The user interface shown in the Plotting example. The GUI shown during simulation (see Figure 7.6) is composed by a Plot element that displays the sinusoid in red, and a Roller element in the upper right corner that allows the user to change dynamically the amplitude of the sinusoid. In the upper left corner, the current value of the input data plotted on the graph is also updated at every simulation step Fullscreen The Fullscreen example demonstrates an user interface that is shown in full-screen. The Scicos model, shown in Figure 7.7, is a simple counter (modulo 100) which can be activated or deactivated according to the output value of the user interface block. The value of the counter is then fed to the same GUI block to be displayed, replaced by the text OFF when the counter is not active. 48

49 Chapter 7. Examples Figure 7.7.: The Scicos diagram for the Fullscreen example. Figure 7.8.: Setting the fullscreen property for a frame in the E4CoderGUI editor. Figure 7.9.: The user interface of the Fullscreen example. The user interface is composed essentially by a Text Label element to display the counter status and a Switch element connected to the output port on the block. By setting the fullscreen property on the Frame object in the GUI Editor (see Figure 7.8), 49

50 Chapter 7. Examples the interface is displayed as a full-screen window during simulation. When in this mode, it is always possible to close the window, and terminate the simulation, by pressing ALT-F4. Other system-wide keys combinations also work (e.g. ALT-TAB). Figure 7.9 shows a portion of the user interface during simulation Integers The Integers example shows a collection of elements that allows the user to insert integer values. The example user interface contains a Spinbox, a Roller, and two Sliders (with horizontal and vertical orientation). The GUI during simulation is shown in Figure Figure 7.10.: The Integers example user interface. Figure 7.11.: The Integers example Scicos model. 50