Revision as of 09:12, 2 June 2023 by Sascha
Spectrum Analyzer Demo
This demo shows how to create and use a Guiliani "custom extension" (a.k.a. custom control). We use a bargraph as an example. Up to 50 segments can be defined in the Guiliani Streaming Editor (GSE). The active/inactive color for each one can be set, as well as the distance between the segments. The demo also uses a number of standard Guiliani features and controls such as data pools, skins, buttons, carousel, clock and calendar. You can easily expand the functionality by adding dialogs or by adding images and text on the "Information" dialog, for example. We hope it is useful and enjoyable.
Target audience: the demo assumes full proficiency in embedded software languages/environments such as C++, embedded IDE and so on. We also highly recommend our detailed Guiliani documentation for learning more about Guiliani and the Guiliani Streaming Editor (GSE).
Windows Desktop (800x480 and 1280x720)
M13-RZA2M-EK (Based on Renesas RZ/A2M) (800x480)
Renesas Starter Kit+ for RZ/A1H (RZ/A1H) (800x480)
Renesas RZ/A3UL (1280x720)
Renesas RZ/G2L (1280x720)
Renesas RZ/G2UL (1280x720)
1. View the project
In order to examine the project in more detail you will need to open it in the GSE as well as the corresponding source-files in your text-editor or IDE.
The Spectrum Analyzer Demo has multiple screens (screen-filling dialogs) where each will demonstrate examples of Guiliani’s feature-rich portfolio of controls (widgets).
The screens are:
- SpectrumAnalyzer: The main screen of the demo with the 11 bargraphs is a virtual display of an audio equalizer that visualizes the individual frequencies present in an audio signal. This screen also has 5 buttons to start and stop the simulation of the bar graph values, as well as to switch to the other screens.
- Information: This screen contains general information, as well as a button to return to the main screen. It can also be used to add your own functionality quickly and easily. Think of it as a dialog you can use to start playing with your own graphic assets and try controls…
- MusicSelector: This screen contains a carousel with different cover images to swipe through, as well as a button to return to the main screen.
- Settings: This screen contains a calendar, a clock, a button to switch between the colorful and the black design of the demo, and a button to return to the main screen.
3. General Explanations
Parts of a Guiliani-Application
Every application using Guiliani will consist of the visual description (properties, dialogs and resources) created in the GSE and the code using the Guiliani-API to communicate with the GUI and create dynamic behaviour. The code will include the pre-built libraries and some start up-code additionally to your business logic. The starting point for your application-code will be the file MyGUI_SR.cpp located in <APP>/Source-folder.
4. The screens explained
The bar graphs were created as a custom control and are not a standard control of Guiliani. The other parts of the screen are common controls that are available in Guiliani.
The headline is a combination of GUIText and GUIImage. In the case of the colorful design, the DUMMY_IMAGE is used here and thus the white line is only displayed in the dark design.
We have created a new CustomControl called "Bargraph". This simulates a LED bar display as known from mixing consoles or other audio devices that are supposed to display a volume level. The number of segments can be from 1 to a maximum of 50. For each of them, the color for the active as well as the inactive state can be determined individually. The distance between the segments can be set. The assignment of whether a segment is active or not is done as with sliders via a defined value range (from..to) and the currently set value. The alignment from active to inactive is set from the bottom to the top and cannot be changed.
The number of elements is limited by the control to 50 and could be increased if necessary. To have a control that does not contain a fixed number of elements, the "WriteToStream" and the "ReadFromStream" must be designed accordingly. An additional index variable is necessary, in this case called "SegmentColors" which manages the number of elements and determines the loop for reading or writing the individual elements from or to the stream. A write protection that no more than 50 elements are written should always exist.
The “CALLAPI” command is attached to the first two buttons to start and stop the generation of random values for the bargraphs. The "DIALOG_TRANSITION" command is attached to the last three buttons to switch to other dialogs in this demo. These are the Music Selection dialog, the Setting dialog and the Information dialog. This command triggers a change from one dialog to another when the button is pressed. This command requires the following five attributes to perform a dialog transition:
- DestDialogFileName: The dialog to switch to.
- SourceObjectID: The current dialog to switch from and close at the end.
- TransitionType: The way the transition is made (here: Simple transition to the new dialog).
- EasingType: The time course of the transition.
- TransitionTime: The duration of the transition.
This custom control has some areas that are particularly important for its function.
XML Streaming The reading or writing of the bar graph specific attributes of the control take place in the ReadFromStream and WrtiteToStream functions. These are:
- DatapoolXIndex: This defines with which X index of the DataPool the control should be linked.
- MinValue: Initial value for value range.
- MaxValue: End value for value range.
- Value: Current start value.
- Spacing: Distance between the segments.
- SegmentColors: number of segments.
- ActiveColor: The color when the segment is active.
- InactiveColor: The color when the segment is inactive.
A particularly important attribute in this case is the "SegmentColors" attribute. This specifies how many segments the control has and thus controls the loop passes for reading out "ActiveColor" and "InactiveColor". This area is summarized with an additional tag.
In order to use the dynamic part of the control in the GSE, the control or not the control but the attribute, in this case "SegmentColors" needs an entry in the "CustomsExtensionsFunc.cpp" in the function "GetCustomRepetitions". This ensures that elements are added and removed cleanly.
Drawing the Bargraph The drawing of the segments of the control is done in the function DoDraw. After the current dimensions of the control have been queried, the segment dimensions are calculated taking into account the distance between the segments. Depending on whether a segment is marked as active or inactive, it is then drawn in the corresponding color. The FilledRect function of the GFX wrapper is used as the drawing function for the segments.
DataPool connection The connection to the DataPool takes place via the SetValue function. If an instance of the control is monitored by the DataPool Manager, this function is automatically called when the data in the DataPool changes and the current value is transferred to the control via the X and Y index (in our case only the X index is used and Y always remains at 0). To simplify the evaluation of how many segments are active we use the class CGUIRange which takes over the evaluation.
Property Sets The colors of the individual elements can be managed via properties. This makes it possible to switch between different color sets. For this the control class must be derived from the "CGUIColoPropertyObserver".
CALLAPI Command The evaluation of the keyword passed with the CALLAPI command happens in the My_GUI and starts or stops there the generation of the random numbers and its transmission to the DataPool.
Information This dialog was created entirely in the GSE and does not require any additional handling by additional source code. It consists of several GUIText for the different texts and a GUIButton to return to the main dialog.
MusicSelector This dialog was created entirely in the GSE and does not require any additional handling in the by additional source code. It consists of the controls GUICarousel for the cover carousel, a GUIText for the headline above it and a GUIButton to return to the main dialog.
Change Skin The GUIButton is used as the control and has been assigned the appropriate graphics for its various states. All graphics used in the demo are stored in both the respective version for one or the other design in the image sets. Texts that change color when switching are also stored as property sets for the respective skin and used in the GSE instead of absolute values. The "CALLAPI" command is attached to the button which is triggered when pressed and is passed the keyword "ToggleSkin" as an ApplicationAPI. This will be evaluated later in the code of the MyGUI.
Calendar The GUICalender is used as control for the calendar. The start date was set in its attributes.
Clock The GUIClock is used as a control for the clock. The start time were Set in its attributes, as well as the “autostart” attribute.
Back button GUIButton to return to the main dialog.
Code The evaluation of the keyword passed with the CALLAPI command happens in the My_GUI and switches there between sets using the ChangeSkin function added as a help function to perform the actual switching of the set there.