Google Git
Sign in
eclipse / titan / titan.Libraries.CLL / a1c7f90f93ac5396c409fa3d980eaed3881d89f9 / . / doc / UIHandler / FD / EPTF_CLL_UIHandler_FD.adoc
blob: 4558837bc9d5f7721f154ee0f2fff31fafa7c1fb [file] [log] [blame]
---
Author: József Gyürüsi
Version: 2/155 16-CNL 113 512, Rev. S
Date: 2009-02-09
---
= EPTF CLL UIHandler, Function Description
:author: József Gyürüsi
:revnumber: 2/155 16-CNL 113 512, Rev. S
:revdate: 2009-02-09
:toc:
== How to Read This Document
This is the Function Description for the `UIHandler` of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). EPTF Core Library is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.
== Scope
This document is to specify the content and functionality of the `UIHandler` feature of the EPTF Core Library.
== Recommended Way of Reading
The readers are supposed to get familiar with the concept and functionalities of EPTF Core Library <<_3, [3]>>. They should get familiar with the list of acronyms and the glossary in the Terminology section.
= General Description
This document specifies the UIHandler feature of the EPTF Core Library. The main goal of the UIHandler feature is to hide the details of handling the Graphical User Interface (or shortly GUI), including both the communication with, and the layout-configuration of the GUI. Furthermore, it provides TELNET access <<_7, [7]>> to TitanSim, which can be used as a Command Line Interface (CLI) substitute of the GUI.
[[overview]]
== Overview
Users can display EPTF Variables <<_5, [5]>>, or can change the value of these variables using either the TitanSim Runtime GUI <<_6, [6]>>, a standard HTML web browser or a TELNET-client. These use-cases are collectively called as "data-manipulation" in this document and are shown in the figure below:
image:images/Data_manipulation_use_cases.png[alt]
Users can change layout of the GUI via adding, removing, enabling or disabling GUI elements. These use-cases are collectively called as "widget manipulation" in this document and are shown as in the figure below:
image:images/GUI_manipulation_use_cases.png[alt]
There are five logical roles realized as dedicated component types in the UIHandler CLL feature:
1. The components extending `EPTF_UIHandlerClient_CT` manage EPTF Variables, describe how to handle them (in which widget they have to be displayed), and how to interpret their values. Their logical role is the "client(s)" of the UIHandler, they request the UIHandler to display their EPTF Variable data that they own. For this relationship the UIHandler clients act as EPTF Variable "providers" <<_5, [5]>>.
2. The component extending `EPTF_UIHandler_CT` connect EPTF Variables of its client components (i.e., those extending `EPTF_UIHandlerClient_CT`) to the GUI. The logical role of the UIHandler is a "server" that deals with the presentation of the EPTF Variable data of its clients. For this relationship the UIHandler acts as an EPTF Variable "subscriber" <<_5, [5]>>.
3. The component extending `EPTF_UIHandler_CLI_CT` is a special UIHandler that provides TELNET terminal access to remotely control those EPTF Variables that are subscribed by the UIHandler.
4. The component extending `EPTF_UIHandler_VariableUI_CT` is basically a `EPTF_UIHandlerClient_CT` (it also extends that) but has some functions, that can manage massive widget – variable subscriptions and putting them to the GUI.
5. It contains UIs to selected CLL features. You may be able to use the feature without or with UI support. When the former is used, the feature will add his own widgets, variables to the GUI.
At any given time only one UIHandler component can connect to the same GUI. There can be more than one UIHandlerClient components sharing EPTF Variables with the same UIHandler component. The figure below describes a typical TTCN-3 run-time configuration using UIHandler. Run-time components (PTC objects) are visualized as rectangles. If the component-type of such a PTC defined via (possibly recursive) extension of another component type(s), then it is depicted as embedded boxes according to the extension hierarchy.
See a common configuration of the components of the UIHandler feature below:
image:images/Components_of_the_UIHandler_feature.png[alt]
If the users want to display their data on different UIs, there can be more UIHandler components connected to different UIs.
The same variable can be shared with more than one UIHandler components.
The figure below describes a more complicated configuration, where there are two UIHandlers (with their associated GUI).
See a more complicated configuration of the components of the UIHandler feature below:
image:images/Components_of_the_UIHandler_feature_complicated.png[alt]
In any actual run-time test configuration any component can extend the `EPTF_UIHandler_CT`, `EPTF_UIHandlerClient_CT` or the `EPTF_UIHandler_CLI_CT` component, even all of them at the same time. It is quite possible to deploy all these logical roles on the same PTC.
== Sharing EPTF Variables
To share EPTF Variables UIHandler uses the subscription functionalities of the `EPTF_Var_CT` component.
The component (PTC#2) that extends the `EPTF_UIHandlerClient_CT` component and wants to allow its EPTF Variable to be changed/displayed via the GUI/CLI, must send a subscription note to the component that extends the `EPTF_UIHandler_CT` component (PTC#1). This subscription note describes:
* the name of the EPTF Variable that the component wants to use with the GUI/CLI,
* the name of the EPTF Variable that the UIHandler will create as a subscriber of the above variable,
* the ID of the widget in which the subscriber variable will be displayed
* the subscription mode and
* the refresh rate which specifies the rate of refresh for this subscription. The refresh period is calculated as the `refreshRate` multiplied by the `minSyncInterval`.
`PTC#1` subscribes to the specified variable via the functionalities of the `EPTF_Var_CT` component. After a successful subscription it sends back an acknowledgment and if there was a widget ID in the message, refreshes the content of the given widget.
See sequence of the variable sharing below:
image:images/Sequence_of_the_variable_sharing.png[alt]
=== Sharing variables with `VariableUI`
When extending `EPTF_UIHandler_VariableUI_CT`, it is a bit easier to manage variable subscriptions. Only widgetId (or widget) – variable name pairs, called a connection have to be provided, and they should automatically be added to the GUI, and connected with the variables.
There are three forms to use the feature:
1. In the simplest form, it is assumed, that all the widgets are on the GUI, so only their widgetIDs should be provided with the variable that connects to.
2. If the widgets that would subscribe to a variable are not present or it is not know that is present on the GUI, the whole widget should be provided with its parent’s ID with the appropriate function.
3. In some cases, the first two possibilities are not enough, also an other widget should be provided upon, called the holding widget. Furthermore, one holding widget could be used for many widgets – variable pairs, so there is a reference with the widget to a holding widget too, that could be provided with the appropriate function.
After providing all the pairs, it is possible to add the widgets and subscribe all of them in a single step.
== UI Handling
=== Runtime GUI
The UIHandler component communicates with the Runtime GUI through XTDP messages.
After the UIhandler and Runtime GUI is connected via TCP, the XTDP session will be initiated. It is established after a successful XTDP handshake and authentication. The authentication is optional and can be switched off by setting the `tsp_EPTF_UIHandler_Authmsg` or the `tsp_EPTF_UIHandler_Authresp` module parameter to empty string. The password that has to be entered on the Runtime GUI can be set in the `tsp_EPTF_UIHandler_Authresp` parameter. The maximal time of authentication can be adjusted by the module parameter `tsp_EPTF_UIHandler_authMaxTimer`. By default the UIHandler authentication is switched off.
==== GUI Layout Manipulation
Users can _add_, _remove_, _enable_ or _disable_ components of the runtime GUI. Both the UIHandler and the UIHandlerClient components provide means for GUI layout manipulation.
To initiate GUI layout changes from the UIHandlerClient component, the UIHandlerClient component sends messages to the UIHandler component via its `EPTF_adminPort_PT` port. The UIHandler component books the changes and sends the appropriate XTDP messages to the runtime GUI via TCP (using the CLL IPL4 Transport).
[[data_manipulation_using_the_runtime_GUI]]
==== Data Manipulation Using the Runtime GUI
Users can connect EPTF Variables to widgets by their names.
When the content of such a provider variable in one of the UIHandlerClients has been changed, then the EPTF Variable feature automatically updates the content of the related subscriber variable in the UIHandler component. Upon the detection of this change the UIHandler component sends an XTDP message to the runtime GUI and changes the content of the associated widget, as shown in figure below:
See displaying the content of a variable after its change below:
image:images/Content_of_variable_after_its_change.png[alt]
When a user changes the content of a widget – for example, types into a tree cell, or presses a button – the runtime GUI sends a message to the UIHandler component. If there is an associated variable, the UIHandler component initiates a change of its content via the "adjust" method of the `EPTF_Variable` <<_5, [5]>> feature. The figure below describes this synchronization mechanism.
See the synchronization mechanism below:
image:images/Synchronization_mechanism.png[alt]
=== CLI
After an UIHandler component creates EPTF Variables by a subscription, the created EPTF Variables can be accessed via a TELNET terminal application. Users can connect their TELNET terminal to the UIHandler component and change or display the values of the variables. The UIHandler component interprets the commands received on TELNET port and sends back the answers on the same port.
Figure below describes the collaboration of the components using the CLI functionality.
image:images/Collaboration_when_user_sets_content_of_variable.png[alt]
Users can monitor the content of the variables handled by UIHandler by ordering a periodic printout of their content. Such periodic printout will be directed to another TELNET terminal. The former is called the "command" TELNET terminal, the later is called the "display" TELNET terminal, respectively. The UIHandler component interprets the commands received on the command TELNET terminal and periodically sends the content of the required variables to the display TELNET terminal.
See collaboration when the user monitors the content of a variable below:
image:images/Collaboration_when_user_monitors_content_of_variable.png[alt]
=== Web Browser GUI
The UIHandler can behave like a web server, if the module parameter `tsp_EPTF_UIHandler_enableBrowserGUI` is set to `_true_` (by default it is). The UIHandler is waiting for requests on a hostname and port given by the module parameters:
* `tsp_EPTF_UIHandler_Browser_RemoteAddress` (default: `_"127.0.0.1"_`)
* `tsp_EPTF_UIHandler_Browser_RemotePort` (default: `_"4000"_`).
When a web browser (currently Mozilla/Chrome/Internet Explorer 7+ are supported) connects to the UIHandler, the content of the GUI is sent to the browser via an XML message, which looks similar to an XTDP message. The difference is mainly an xml-stylesheet tag. The module parameter `tsp_EPTF_UIHandler_Browser_xsl2send` (default: `_"EPTF_LoadMain.xsl"_`) is used to convert the given XML message to a HTML compatible format.
When the browser gets the xml, it downloads the xsl, it makes the transformation into html. The browser downloads the images and the javascript files. The _favicon.ico_ is determined by the module parameter: `tsp_EPTF_UIHandler_Browser_favicon2send` (default: _favicon.ico_)
There is an opportunity to show a welcome screen, while the application is not ready. To show/hide this screen, the following functions can be used:
* `f_EPTF_UIHandler_Browser_enableWelcomeScreen()`
* `f_EPTF_UIHandler_Browser_disableWelcomeScreen()`
The welcome screen is defined in the `tsp_EPTF_UIHandler_Browser_welcomeScreen` module parameter.
All of the files requested by the browser has to be placed in the directory determined by the module parameter `tsp_EPTF_UIHandler_Browser_directory` (default: `_"../BrowserGUI/"_`). If the directory does not exist, the UIhandler tries to find the files in the current directory. The default files ( _.js_, _.png_, _.jpg_, _.xsl_, _.css_) are located in the src/UIHandler/BrowserGUI directory. This directory should be linked to the correct place defined by the parameter above.
When the page is loaded, the values of the widgets are refreshed using JavaScript sending and receiving JSON strings (widgetId:value pairs).
The Browser GUI can be configured with the following functions:
* `f_EPTF_UIHandler_Browser_getRemoteHosts` - This function returns the Host names and ports on which the BrowserGUI is activated.
* `f_EPTF_UIHandler_Browser_addRemoteHosts` - This function adds the given Host name and port pairs to the list on which the BrowserGUI is activated and activates them as well.
* `f_EPTF_UIHandler_Browser_setRemoteHosts` - This function sets and activates the given Host name and port pairs on which the BrowserGUI is listening.
* `f_EPTF_UIHandler_Browser_clearRemoteHosts` - This function clears the host name and ports on which the BrowserGUI is listening.
* `f_EPTF_UIHandler_Browser_removeRemoteHosts` - This function removes and deactivates the given Host name and port pairs on which the BrowserGUI is listening.
* `f_EPTF_UIHandler_Browser_setBrowserDirectory` - This function sets the BrowserGUI directory, where the _.png_, _.css_, _.js_ and several other files are, needed by the BrowserGUI feature.
* `f_EPTF_UIHandler_Browser_getBrowserDirectory` - This function returns with the BrowserGUI directory string, where the _.png_, _.css_, _.js_ and several other files should be, needed by the BrowserGUI feature.
Custom CSS styles can be setup using the following functions:
* `f_EPTF_UIHandler_Browser_getCustomStyle` - This function returns the active custom CSS style of the BrowserGUI.
* `f_EPTF_UIHandler_Browser_addCustomStyle` - This function adds the given CSS Style to the main.css from file.
* `f_EPTF_UIHandler_Browser_setCustomStyle` - This function sets the custom style (CSS) from file.
* `f_EPTF_UIHandler_Browser_clearCustomStyle` - This function clears the custom style CSS elements.
* `f_EPTF_UIHandler_Browser_removeCustomStyle` - This function removes the custom style (CSS) based on filename.
* `f_EPTF_UIHandler_Browser_addCustomStyleStr` - This function adds the given CSS Style to the main.css from string.
* `f_EPTF_UIHandler_Browser_setCustomStyleStr` - This function sets the custom style (CSS) from string.
* `f_EPTF_UIHandler_Browser_removeCustomStyleStr` - This function removes the custom style string (CSS) based in string.
= General Functions
== Naming Conventions
All functions of the `EPTF_UIHandler_CT` component have the prefix `f_EPTF_UIHandler_`.
All functions of the `EPTF_UIHandlerClient_CT` component have the prefix `f_EPTF_UIHandlerClient_`.
Functions of the `EPTF_UIHandler_CLI_CT` component have the prefix `f_EPTF_UIHandler_CLI_`.
== Using Default UIHandler Component
Although the UIHandlerClient components can use many UIHandler components in the executable, usually there is only one GUI; and consequently only one UIHandler. Therefore, the users can declare a default UIHandler component for a given UIHandlerClient and implicitly use it with all the UIHandler management functions.
To support this, all of the UIHandlerClient component API functions have two forms: one with an explicit UIHandler component reference parameter and one without it. Functions having an explicit UIHandler component parameter manage the specified UIHandler component, the functions without this parameter manage the default UIHandler component.
Users can specify the default UIHandler component in the `f_EPTF_UIHandlerClient_init_CT` initializer function.
== Initialization
Before using the functions of the UIHandler component, the
[source]
----
function f_EPTF_UIHandler_init_CT(
in charstring pl_selfName,
in boolean pl_connectGUI := true,
in charstring pl_windowLayout := "" ,
in EPTF_CLI_CT pl_CLI_compRef := null,
in charstring pl_prefix := tsp_EPTF_UIHandler_CLIPrefix,
in boolean pl_simulationMode := false,
in charstring pl_simulation_buildDB_file := ")
----
function should be called. The `pl_selfName` parameter specifies the name of the component. The `pl_connecGUI` parameter can be used to force the UIHandler to connect to the Runtime GUI during its initialization in XTDP-client mode. This connection means not only the establishment of the TCP connection, but the successful XTDP handshake and authentication as well. The maximal wait time for connection establishment can be controlled by the module parameter `tsp_EPTF_UIHandler_maxGUIWaitTime`. If the TCP connection fails, but headless mode is enabled, this function will not wait for the XTDP session to be established and will exit before the maximal waiting time entering into headless mode.
A predefined initial layout can be specified in the `pl_windowLayout` parameter. If this argument is given, the layout on the Runtime GUI will be replaced by the layout specified. The layout has to be given in a charstring value that can be decoded by the decode function `f_EPTF_UIHandler_XSD_decodeXUL` which is a wrapper for the decode function of the XTDP Protocol Module <<_8, [8]>>.
Before using the functions of UIHandlerClient component, the
[source]
----
function f_EPTF_UIHandlerClient_init_CT(
in charstring pl_selfName,
in EPTF_UIHandler_CT pl_DefaultUIHandler)
----
function should be called.
Before using the functions of `UIHandler_CLI` component, the
[source]
----
function f_EPTF_UIHandler_CLI_init_CT(
in charstring pl_selfName,
in boolean pl_connectGUI := true)
----
function should be called.
The `pl_simulationMode` parameter can be used to initialize UIHandler in simulation mode. The `pl_simulation_buildDB_file` parameter defines the file, what will be used to save the database or load the database in simulation mode. More information about using these 2 parameters can be found in the UIHandler User Guide document.
= Variable Handling
Since the UIHandler component subscribes to EPTF Variables of the UIHandlerClients, therefore both the UIHandlerClient and the UIHandler components use EPTF Variable API <<_5, [5]>> functions to initiate such subscriptions and connect such variables to GUI widgets.
[[order_the_UIHandler_component_to_subscibe_to_an_EPTF_variable]]
== Order the UIHandler Component to Subscribe to an EPTF Variable
Using the
[source]
----
function f_EPTF_UIHandlerClient_subscribeVariableTo(
in EPTF_UIHandler_CT pl_subscriber,
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeline,
in integer pl_refreshRate := -1)
----
function the UIHandlerClient component can order the UIHandler component to subscribe to its EPTF Variable.
The `pl_providedParamName` specifies the name of the EPTF Variable. The UIHandler component will subscribe to this variable, and the created EPTF Variable will have the name specified in the `pl_destParamName` parameter.
The `pl_refreshRate` parameter specifies the rate of refresh for this subscription. The refresh period is calculated as the `refreshRate` multiplied by the `minSyncInterval`. If this argument is not specified (or `_<=0_` value is given) the default refresh rate is used with period defined by the `syncInterval` parameter. The `minSyncInterval` and `syncInterval` parameters can be set by the functions:
* `f_EPTF_Var_setSyncInterval`
* `f_EPTF_Var_setMinSyncInterval`
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_subscribeVariable(
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeline,
in integer pl_refreshRate := -1)
----
== Order the UIHandler Component to Subscribe to an EPTF Variable and Connect it to a Widget
Using the
[source]
----
function f_EPTF_UIHandlerClient_subscribeMeTo (
in EPTF_UIHandler_CT pl_subscriber,
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_UIHandler_WidgetIdString pl_widgetId := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeline,
in integer pl_refreshRate := -1)
----
function the UIHandlerClient component can order the UIHandler component to subscribe to its EPTF Variable and eventually connect it to a widget on the runtime GUI.
The `pl_providedParamName` specifies the name of the EPTF Variable. The UIHandler component will subscribe to this variable, and the created EPTF Variable will have the name specified in the `pl_destParamName` parameter.
If the `pl_widgetId` parameter is not an empty string, the UIHandler component will connect the variable to the specified widget. That means that when the content of the EPTF Variable changes, the UIHandler component changes the content of the associated widget. Similarly, when the content of the specified widget changes, the UIHandler component changes the content of the variable.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_subscribeMe (
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_UIHandler_WidgetIdString pl_widgetId := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeline,
in integer pl_refreshRate := -1)
----
It is possible to connect a GUI widget to a variable which is defined in an other component. This can be done by using the function
[source]
----
function f_EPTF_UIHandlerClient_subscribeTo (
in EPTF_UIHandler_CT pl_subscriber,
in EPTF_Var_CT pl_remoteCompRef,
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_UIHandler_WidgetIdString pl_widgetId := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeline,
in integer pl_refreshRate := -1)
----
Here the parameter `remoteCompRef` is that component that the EPTF variable created. The pair of this function is
[source]
----
function f_EPTF_UIHandlerClient_subscribe (
in EPTF_Var_CT pl_remoteCompRef,
in charstring pl_providedParamName,
in charstring pl_destParamName := "",
in EPTF_UIHandler_WidgetIdString pl_widgetId := "",
in EPTF_Var_SubscriptionMode pl_subsMode := timeLine)
----
== Using the `VariableUI`
Initializing the component can be done with
[source]
----
f_EPTF_UIHandler_VariableUI_init_CT(in charstring pl_selfName,
in EPTF_UIHandler_CT pl_UIHandler)
----
Put means add the widget to the GUI and subscribe it to the variable. The following function put a variable given by a name from the database.
[source]
f_EPTF_UIHandler_VariableUI_putVarbyName(in charstring pl_var)
Using the functions
[source]
----
f_EPTF_UIHandler_VariableUI_putconnections()
f_EPTF_UIHandler_VariableUI_putlastconnections()
----
it is possible to put all the variable given already, or just the last few, that are not processed since the last put.
With the function
[source]
f_EPTF_UIHandler_VariableUI_addsimpleconnection(in charstring pl_varname, in charstring pl_widgetid)
it is possible to fill the database with an existing widgetID and a variable name. It returns an index in the database.
The function
[source]
----
f_EPTF_UIHandler_VariableUI_addwidgetconnection(in charstring pl_varname,
in charstring pl_widgetid,
in XTDP_XML_Tag pl_widget,
in charstring pl_parentid)
----
can be used, to put a widget - variable par into the database, with the widget given in XUL format. This widget will be added to `pl_parentid`, and variable will be connected to the widget with `pl_widgetid`. It returns an index in the database.
A holder widget can be specified with the following function:
[source]
f_EPTF_UIHandler_VariableUI_addholdingwidget(in charstring pl_name, in XTDP_XML_Tag pl_widget, in charstring pl_parentid)
It returns an index in the database.
Assigning a holder widget to a widget – variable pair can be done with the following functions:
[source]
----
f_EPTF_UIHandler_VariableUI_assignholdingwidget(in charstring pl_varname, in charstring pl_holdingname)
f_EPTF_UIHandler_VariableUI_assignholding(in integer pl_connidx, in integer pl_holdingidx)
----
A variable – widget pair can be removed from the database with the following functions:
[source]
f_EPTF_UIHandler_VariableUI_removeconnection(in charstring pl_varname)
= UI Handling
== User Interactions
All the user interactions using the runtime GUI is mapped to EPTF Variable management. User input widgets can be connected to variables, and when the user changes them – for example, types into a tree cell, or presses a button – the runtime GUI sends a message to the UIHandler component. Then the UIHandler component changes the content of the associated variable as described in <<data_manipulation_using_the_runtime_GUI, Data Manipulation Using the Runtime GUI>>.
Table below describes the permitted mapping of widgets to of EPTF Variable types.
See Widget types and EPTF Variable types that can be assigned to
[cols=",",options="header",]
|==========================================
|Widget type |EPTF Variable type
|Button |intVal
|Toolbarbutton |intVal
|TreeCell of checkbox |boolVal
|TreeCell of floatField |floatVal
|TreeCell of pushButton |intVal
|TreeCell of integerField |intVal
|TreeCell of string |charstringVal
|TreeCell of statusLEDOfText |charstringVal
|TreeCell of statusLED |charstringVal
|Chart |floatVal
|==========================================
== GUI Handling
=== Layout Manipulation
As described in Section <<overview, Overview>> the UIHandlerClient components own their EPTF Variables and they might choose to associate them to widgets of the GUI. Therefore, they may have to change the GUI layout: add or remove, enable or disable those widgets, or set the focus to a particular widget. To support this, the UIHandler and UIHandlerClient components have widget adding, removing, enabling, disabling and set focus functions.
In order to prepare an initial GUI layout `EPTF_UIHandler_CT` component type has widget adding and removing functions. The widget enabling and disabling functionalities are related to handling the particular EPTF Variables, therefore such functions are provided by the UIHandlerClient components. The `set focus' functionality is available by the UIHandlerClient components as well.
When adding, removing, manipulating elements on the GUI as described in this section, all widget IDs must conform to the restrictions in the XTDP protocol module XSD <<_8, [8]>>.
UIHandlerClient provides a group of convenience functions as well. Using them makes it easy to create specific widgets on the GUI, as button, text label, spacer, chart, tabbed box and horizontal box.
==== Add Widgets
Using the
[source]
----
function f_EPTF_UIHandlerClient_XSD_addElementToGUITo(
in Widgets pl_xul,
in EPTF_UIHandler_WidgetIdString pl_parentWidgetId,
in EPTF_UIHandler_CT pl_UIHandler)
----
function users can add a widget or a tree of widgets under the parent widget `pl_parentWidgetId` on the GUI connected to the specified UIHandler component.
The `pl_xul` parameter describes the hierarchy of widgets to add to the GUI. See <<_6, [6]>>.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_XSD_addElementToGUI(
in Widgets pl_xul,
in EPTF_UIHandler_WidgetIdString pl_parentWidgetId)
----
In the UIHandler component the corresponding function is:
[source]
----
function f_EPTF_UIHandler_XSD_addElementToGui(
in Widgets pl_xul,
in EPTF_UIHandler_WidgetIdString pl_parentWidgetID := "",
inout boolean pl_widgetExists,
in boolean pl_updateDb := true)
----
The `pl_updateDb` parameter can be used to disable the internal database update in UIhandler.
==== Remove Widgets
Using the
[source]
----
function f_EPTF_UIHandlerClient_removeElementFromGUITo(
in EPTF_UIHandler_WidgetIdString pl_Widget2Remove,
in EPTF_UIHandler_CT pl_UIHandler)
----
function users can remove a widget and its children from the GUI connected to the specified UIHandler component.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_removeElementFromGUI(
in EPTF_UIHandler_WidgetIdString pl_Widget2Remove)
----
In the UIHandler component the similar function is:
[source]
----
function f_EPTF_UIHandler_removeElementFromGui(
in EPTF_UIHandler_WidgetIdString pl_widgetId)
----
==== Enable Widgets
Using the
[source]
----
function f_EPTF_UIHandlerClient_enableGUIElementTo(
in EPTF_UIHandler_WidgetIdString pl_WidgetID,
in EPTF_UIHandler_CT pl_UIHandler)
----
function users can enable a widget on the GUI connected to the specified UIHandler component.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_enableGUIElement(
in EPTF_UIHandler_WidgetIdString pl_WidgetID)
----
==== Disable Widgets
Using the
[source]
----
function f_EPTF_UIHandlerClient_disableGUIElementTo (
in EPTF_UIHandler_WidgetIdString pl_WidgetID,
in EPTF_UIHandler_CT pl_UIHandler)
----
function users can disable a widget on the GUI connected to the specified UIHandler component.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_disableGUIElement(
in EPTF_UIHandler_WidgetIdString pl_WidgetID)
----
==== Setting the Focused Widget
Using the
[source]
----
function f_EPTF_UIHandlerClient_setFocusToGUIElementTo (
in EPTF_UIHandler_WidgetIdString pl_WidgetID,
in EPTF_UIHandler_CT pl_UIHandler)
----
function users can set the focus to a widget on the GUI connected to the specified UIHandler component.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_disableGUIElement(
in EPTF_UIHandler_WidgetIdString pl_WidgetID)
----
There is another function specialized for Tabboxes. The
[source]
----
function f_EPTF_UIHandlerClient_setFocusToTabTo (
in EPTF_UIHandler_WidgetIdString pl_TabboxID,
in integer pl_TabIndex,
in EPTF_UIHandler_CT pl_UIHandler)
----
function allows the user to select a particular tab of tabbox on the GUI connected to the specified UIHandler component.
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_setFocusTo Tab(
in EPTF_UIHandler_WidgetIdString pl_TabboxID,
in integer pl_TabIndex)
----
==== Checking Existence of Widgets
[source]
----
function f_EPTF_UIHandlerClient_widgetExistsOn(
in EPTF_UIHandler_WidgetIdString pl_WidgetID,
in EPTF_UIHandler_CT pl_UIHandler)
----
The pair of this function without UIHandler component parameter is
[source]
----
function f_EPTF_UIHandlerClient_widgetExists(
in EPTF_UIHandler_WidgetIdString pl_WidgetID)
----
==== Clear the GUI and Create a New Window
Function `f_EPTF_UIHandler_clearGUI(`) removes all the widgets from the GUI, even the window widget.
The `f_EPTF_UIHandler_addWindow()` function creates a new window widget on an empty GUI. The id, the height, width and the title of the new window widget can be defined with the `tsp_EPTF_GUI_Main_Window_WidgetId`, `tsp_EPTF_GUI_Main_Window_Height`, `tsp_EPTF_GUI_Main_Window_Width` and `tsp_EPTF_GUI_Main_Window_Title` module parameters.
==== Get the Description of the Current GUI, and Save It into a File
The `f_EPTF_UIHandler_snapshot()` function returns the XUL representation of the current GUI in a charstring. This description can be stored into a file with the `f_EPTF_UIHandler_saveLayout` function.
==== Create Custom GUI from XML
It is possible to load widgets from XML to the GUI. The XML is decoded into the Widgets type defined in the XTDP Protocol Module. The following function puts the widgets in XML under the given parent widget id:
[source]
----
public function f_EPTF_UIHandler_createGUI (
in charstring pl_xul,
in charstring pl_parentWidgetId := "" )
runs on EPTF_UIHandler_Private_CT
return boolean
----
The XML has to be in a format that can be decoded by `f_EPTF_UIHandler_XSD_decodeXUL` function. If the XML contains iterators, external values, external data and conditions, they are processed by the UIHandler which uses the DataSource feature to determine the value of the external data. This means that it is possible to put content to the GUI for which the value is determined dynamically. For example without knowing how many traffic cases are defined, it is possible to define an XML that puts the CPS value for all traffic cases to the GUI.
The enabled/disabled state of the widget is determined automatically from the `subsCanAdjust` flag of the EPTF Variable containing the data for the data source element. See the relevant section of <<_5, [5]>>.
Here is a simple XML that puts some variables to the GUI:
[source,xml]
----
<window xmlns='http://ttcn.ericsson.se/protocolModules/xtdp/xtdl' height='386.000000' id='EPTF_Main_Window' orientation='vertical' title='TTCN constructed window' width='820.000000'>
<hbox id='EPTF_Main_hbox' orientation='vertical'>
<hbox id='Params' orientation='vertical'>
<label disabled='false' flex='0.000000' value='Available variables' />
<textbox id='Var.AllVars.value' readonly='true' value=''>
<externaldata element='VarValue' source='VarProvider'>
<params>
<dataparam name='VarValue' value='allVar'></dataparam>
</params>
</externaldata>
</textbox>
<iterator element='VarList' id='VarList' source='VarProvider'>
<label disabled='false' flex='0.000000' value='Value of %VarList% :'/>
<textbox id='Var.%VarList%.value' readonly='true' value=''>
<externaldata element='VarValue' source='VarProvider'>
<params>
<dataparam name='VarValue' value='%VarList%'></dataparam>
</params>
</externaldata>
</textbox>
</iterator>
</hbox>
</hbox>
</window>
----
In the example above there is a data source registered with the dataSource name `"VarProvider"`. This data source supports the following elements: `"VarValue"` and `"VarList"`. The `"VarValue"` element returns the value of a given variable of which the name is given in the parameters. The name of the parameter is also called `"VarValue"`. In this XML in the first hbox the value of the `"allVar"` variable is shown. Then there is a `"VarList"` iterator (element is `"VarList"`) with id `"VarList"`. This iterator iterates through all the variables in `"VarProvider"`. The value of the iterator is accessible by the iterator id written between `"%"`s like `%VarList%`. In the example this is given to the external data `"VarValue"` as the parameter. So the example creates textboxes for all variables in `"VarProvider"` and puts their values into them. A label is placed before the textbox with the name of the variable. The value shown in the textbox will change dynamically if the value of the variable changes.
There is also the possibility to access the index of the iterator by writing `"::idx"` added to the iterator id between `"%"`s like `%VarList::idx%`. It can be used for example in widget ids where the value of the iterator cannot be used (because of illegal characters or any other reason). Writing `"::count"` added to the iterator id between `"%"s` like `%VarList::count%` means the number of iterated elements in the iterator. This can be used for example in conditions where if this number is lower than a specific number then put some widget onto the GUI, else do something else.
The `externalvalue` element works as an iterator on a single value. The attributes and parameters are the same as in case of the iterators. The %ID% reference returns the given variable value in charstring format. The %ID::ref% returns the variable name. Can be used in all places, where the iterators can.
The values of iterators and `externalvalues` can change during running. If this happens, the gui is re-organized according to the change, so widgets can appear or disappear.
There is a special widget type called "htmlcode". This widget will not appear in RuntimeGUI, only in the browser. It is possible to insert any html code to this value of this widget. The written html code has to be escaped, because the supported TITAN version does not allow the unescaped characters. Here is an example of using the html code widget:
[source,xml]
----
<window xmlns='http://ttcn.ericsson.se/protocolModules/xtdp/xtdl' height='386.000000' id='EPTF_Main_Window' orientation='vertical' title='TTCN constructed window' width='820.000000'>
<hbox id='EPTF_Main_hbox' orientation='vertical'>
<htmlcode>
<value>&lt;a href=”http://ttcn.ericsson.se”&gt;LINK&lt;/a&gt;</value>
</htmlcode>
</hbox>
</window>
----
It is possible to use externaldata in "htmlcode" widget. The value of the html code will be replaced by the value of the externaldata.
[[converting-widgets-to-from-charstring-in-xml-format]]
==== Converting Widgets to/from charstring in XML format
The Widget type defined in the XTDP protocol module can be converted to charstring in XML format by the function:
[source]
----
public function f_EPTF_UIHandler_XSD_encodeXUL(in Widgets pl_widgets)
return charstring{
var octetstring vl_ret := enc_Widgets(pl_widgets);
return oct2char(vl_ret)
}
To decode the XML into the TTCN-3 Widgets type the following function can be used:
public function f_EPTF_UIHandler_XSD_decodeXUL(in charstring pl_widgets)
return Widgets{
var Widgets vl_ret;
var integer vl_dummy;
vl_dummy := dec_Widgets(char2oct(pl_widgets), vl_ret);
return vl_ret;
}
----
=== Progress Information During Startup
UIHandler provides dataSources to display progress information during startup. The `"progressBar"` dataSource can be changed from any component in case of a new progress information should be displayed.
On the UIHandler component the function
[source]
----
public function f_EPTF_UIHandler_updateProgress(in charstring pl_progressInfo, in float vl_progressPercent := -1.0) runs on EPTF_UIHandler_Private_CT
----
can be used to update the progress information.
All changes to the `"progressBar"` dataSource are accumulated into the `"progressBarHistory"` dataSource, with each value is written into a separate line. This is done automatically by the UIHandler. The `"progressBarHistory"` dataSource is read-only.
It is possible to switch on/off the UIHandler’s own progress information by calling the function
[source]
public function f_EPTF_UIHandler_enableOwnProgress(in boolean pl_enableOwnProgress) runs on EPTF_UIHandler_Private_CT
after the UIHandler is initialized. If own progress is disabled, progress information of UIHandler will not show up in the `"progressBar"` history, whereas changes set by other components will.
=== Convenience Functions in UIHandlerClient
These functions allow an easy way to create instances of the most commonly used widget types on the GUI. The following functions are provided by UIHandlerClient component:
The `f_EPTF_UIHandlerClient_XUL_addButton()` function allows to put a new button to the GUI.
`f_EPTF_UIHandlerClient_XUL_addSpacer()` function adds a new spacer to a parent widget on the GUI.
`f_EPTF_UIHandlerClient_XUL_addLabel()` function creates a new text label.
`f_EPTF_UIHandlerClient_XUL_addEmptyHbox()` function creates a new horizontal box.
`f_EPTF_UIHandlerClient_XUL_addEmptyTabbox()` function creates a new tabbed box.
`f_EPTF_UIHandlerClient_XUL_addTabpanel()` function creates a new tab panel.
`f_EPTF_UIHandlerClient_XUL_addTab()` function creates a new tab on a tabbed box.
`f_EPTF_UIHandlerClient_XUL_addEmptyChart()` function creates a new chart.
`f_EPTF_UIHandlerClient_XUL_addTrace2Chart()` function adds a new trace to a chart.
== `HostAdminUI` Functions
The HostAdminUI component named `EPTF_HostAdminUI_CT` can be used as the original HostAdmin component, but it provides an extra function, that can be used to start the component with
Starting the HostAdminUI component with the function
[source]
f_EPTF_HostAdminUI_behavior(in charstring pl_selfname, in charstring pl_hostname, in EPTF_UIHandler_CT pl_UIHandler)
will result variables put by the component and measure the CPU load.
== `LoadRegulator` UI Functions
The LoadRegulatorUI component named `EPTF_LoadRegulatorUI_CT` can be used as the original LoadRegulator component, but it provides an extra function, that can be used to put the Regulator to the GUI.
The function `f_EPTF_LoadRegulatorUI_putUI(in charstring pl_parentid)` can be used to put its own widgets to the GUI. This widget is a simple box, it could be placed anywhere. Therefore a parent Id should be specified.
== `StatCaptureUI` Functions
The StatCaptureUI component named `EPTF_StatCaptureUI_CT` can be used as the original StatCapture component, but it provides an extra function, that can be used to put the Capturer to the GUI. It is only capable to display its configuration.
The function `f_EPTF_StatCaptureUI_putUI(inEPTF_StatCapture_CaptureGroupsConfig pl_groups)` can be used to put its own widgets to the GUI. This widget is a tab with a tabpanel. The parent widget’s Id could be configured thru a module parameter, also the configuration parameter to the function should be the proper module parameter of the `StatCapture` feature.
== XTDP Operation Modes of UIHandler
While the XTDP protocol <<_6, [6]>> is symmetrical protocol between the GUI and its handler component, the user shall decide the mode for the XTDP connection initialization. The party who opens the XTDP-listener port and awaits for incoming connections is called the XTDP server. The party who connects to this XTDP-listener port is called the XTDP-client.
The UIHandler component can act as either an XTDP-server, or as an XTDP-client. The two modes are different from the point of view of handling XTDP-authentication on one hand and XTDP-connection loss from the other hand.
After the XTDP ports are connected, the XTDP session is always started from the Runtime GUI. Runtime GUI sends the XTDP-HandshakeRequest which is then answered by the UIHandler. After that if enabled, the XTDP-authentication takes place. UIHandler sends the XTDP-Authentication Request to the Runtime GUI with a challenge question configured in `tsp_EPTF_UIHandler_Authmsg`. The response can be entered on the Runtime GUI and is sent back to the UIHandler which checks if it matches with the configured value given in `tsp_EPTF_UIHandler_Authresp`. After successful authentication the XTDP session is up. The authentication can be switched off in the configuration file by setting `tsp_EPTF_UIHandler_Authresp` to empty string.
=== XTDP-Client Mode
The XTDP-client mode is the default behavior. In this mode the Runtime GUI opens the XTDP-listen port and waits for incoming connection.
The TitanSim executable initiates the connection (via the UIHandler). Upon XTDP connection-loss — which can happen if the GUI has been shut-down by the user, for example — it enters _headless mode_, see Section <<headless_mode, Headless Mode>>. During the headless mode it periodically attempts to reconnect.
In order to avoid long timeouts in XTDP connection attempts, UIHandler first "pings" the server via UDP. It attempts to initiate an XTDP-connect only after the GUI starts to answer to these "pings".
On incoming XTDP connection XTDP handshake and if enabled, authentication is performed: the UIHandler will prompt (challenge string) the user for a password (response string) via the GUI.
Both the challenge and the response strings are read from modules parameters, given in the configuration file.
By default the XTDP authentication is turned off.
=== XTDP-Server Mode
In server mode of the UIHandler, the XTDP port will be configured to act like a server, so it will listen on the specified port and wait for a Runtime GUI to connect. Since it might be quite possible that several TitanSim application is running on the same network concurrently, it might happen that a user connects its GUI to a wrong TitanSim application.
To minimize the impact of such misconfiguration problems, an authentication is possible: the UIHandler will prompt (challenge string) the user for a password (response string) via the GUI.
Both the challenge and the response strings are read from modules parameters, given in the configuration file.
By default XTDP-server mode is turned off.
== Shadow GUI
In server mode, it is possible to connect multiple Runtime GUIs to the TTCN application. The first connected GUI will be a Master GUI, which can control the execution. UIHandler will accept XTDP massages only from the Master GUI, but will send out its messages to every GUI connected. This way, the "shadowed" GUIs are only able to monitor the execution. In case the Master GUI disappears, the next connected GUI becomes the Master GUI for UIHandler.
[[headless_mode]]
== Headless Mode
Headless mode is a feature of the UIHandler functionality, what allows the user to continue work or tests even when the Runtime GUI disconnected from the test executable. If headless mode is disabled, the UHandler will start up only if it can establish connection and XTDP authentication with the Runtime GUI during initialization. If the Runtime GUI is closed during test execution UIhandler will enter into headless mode automatically regardless of the headless mode setting (`tsp_EPTF_UIHandler_headlessmode`). In headless mode when the GUI is not present, the UIHandler will not perform any XTDP message passing, but will keep track of the changes that are supposed to affect the GUI. Thus, when the GUI (re-)connected to the running test executable again, it will show the actual layout and data on the GUI.
If the UIHandler is configured to be an XTDP-client to the GUI, auto reconnection will be performed if the GUI is present again. By default it is turned on.
== CLI Handling
Users can handle the values of the shared EPTF Variables of the UIHandlerClient components via TELNET terminal. The names of the EPTF Variables in these commands are the names with which the UIHandler component created its subscribing EPTF Variables. (see `pl_destParamName` parameter of the subscription ordering functions in Section <<order_the_UIHandler_component_to_subscibe_to_an_EPTF_variable, Order the UIHandler Component to Subscribe to an EPTF Variable>>.
The commands are case independent.
=== Data Manipulation
==== Set the Value of a Variable
*Command:* SET
*Syntax:* `SET variable_name := value`
*Purpose:* sets the value of a variable.
==== Get the Value of a Variable
*Command:* GET
*Syntax:* `GET variable_name`
*Purpose:* gets the value of a variable and displays it on the command TELNET terminal, to which the user typed the command in.
==== List all Variables and Their Values
*Command:* LS
*Syntax:* `LS`
*Purpose:* lists all GUI variables and their current values.
==== List Read-Only Variables
*Command:* LSREADONLY
*Syntax:* `LSREADONLY`
*Purpose:* lists read-only GUI variables and their current values.
==== List Writable Variables
*Command:* LSWRITABLE
*Syntax:* `LSWRITABLE`
*Purpose:* lists GUI variables that can be set using the SET command and their current values.
=== Monitor the Values of Variables
UIHandler CLI component periodically sends the value of the selected EPTF Variables to the display TELNET terminal in the form of:
`variable_name := value`
Users can add EPTF Variables to the list of EPTF Variables to display, and remove from it.
==== Display Periodically
*Command:* DISPLAY
*Syntax:* `DISPLAY variable_name`
*Purpose:* Periodically displays the value of the variable on the display TELNET terminal.
==== Stop Displaying
*Command:* HIDE
*Syntax:* `HIDE variable_name`
*Purpose:* Stops periodical display the value of the variable on the display TELNET terminal.
*Command:* HIDE
*Syntax:* `HIDE`
*Purpose:* Stops displaying the values of all the EPTF Variables.
=== Other Commands
==== Help
*Command:* HELP
*Syntax:* `HELP`
*Purpose:* Displays a short help sting on the command TELNET terminal.
==== Quit
*Command:* QUIT
*Syntax:* `QUIT`
*Purpose:* Disconnects the command TELNET terminal.
==== Stop
*Command:* STOP
*Syntax:* `STOP`
*Purpose:* Stops the test execution and disconnects the command TELNET terminal.
= Feature GUIs
== `HostAdminUI`
It is possible, to use HostAdmin CLL feature with GUI support. When building the test executable with `EPTF_HostAdmin_CT` it acts exactly like the HostAdmin feature, but an extra parameter should be added at the usage: the UIHandler component reference. It will automatically put it’s own tab under the given parent, that can be specified via a tsp. On that tab, it will put out a table, and each HostAdmin in the system, will put out his own row to the table, that shows the name of the host, it is executed on and the average CPU load on that host.
See the documentation of the HostAdmin feature, and the reference in this document.
= Summary Table of All Public Functions for UIHandler
See summary of UIHandler functions in the table below:
[width="100%",cols="50%,50%",options="header",]
|======================================================================================================================================================================================================================================================
|Function name |Description
|`f_EPTF_UIHandler_init_CT` |Initialises the `EPTF_UIHandler_CT`
|`f_EPTF_UIHandlerClient_init_CT` |Initialises the `EPTF_UIHandlerClient_CT` component
|`f_EPTF_UIHandler_CLI_init_CT` |The initialization function of the `EPTF_UIHandler_CLI_CT` component..
|`f_EPTF_UIHandler_clearGUI` |Sends a message to user interface via XTDP port to remove all the elements.
|`f_EPTF_UIHandler_addWindow` |Adds a new window widget to the RuntimeGUI
|`f_EPTF_UIHandler_addMainTabbox` |Tries to add the main tabbox to the RuntimeGUI
|`f_EPTF_UIHandler_addMainTabpages` |Tries to add the TabPages to the RuntimeGUI
|`f_EPTF_UIHandler_XSD_addElementToGui` |if the element to add to the Runtime Gui proves to be valid (will not destroy consistency), function sends out singleAddElementToGUI XTDP addRequest to the Gui and also adds this new element to GUI item list.
|`f_EPTF_UIHandler_XSD_encodeXUL` |Encodes XTDP widgets the string
|`f_EPTF_UIHandler_XSD_decodeXUL` |Decodes XTDP widgets from string
|`f_EPTF_UIHandler_removeElementFromGui` |Removes an element from the GUI.
|`f_EPTF_UIHandler_snapshot` |Makes a snapshot of the GUI as a charstring.
|`f_EPTF_UIHandler_snapshotWindow` |Makes a snapshot of the GUI's root widget (windowelem) as a charstring.
|`f_EPTF_UIHandler_XSD_encodeWindowXUL` |Encodes a XUL Window record to its charstring representation
|`f_EPTF_UIHandler_XSD_encodeXULEm` |Encodes an Embedded XUL record to its charstring representation
|`f_EPTF_UIHandler_preprocessAliasXUL` |Preprocess alias items in XUL charstring
|`f_EPTF_UIHandler_XSD_decodeXULEm` |Decodes a XUL record to its charstring representation
|`f_EPTF_UIHandler_saveLayout` |Saves the parameter charstring as a window layout.
|`f_EPTF_UIHandler_convertLayout` |Converts the charstring retreived by the `f_EPTF_UIHandler_snapshot` function to a storeable format.
|`f_EPTF_UIHandler_revertLayout` |Restores the charstring converted by the `f_EPTF_UIHandler_convertLayout` to a charstring that can be given to
|`f_EPTF_UIHandler_requestLayout` |Sends a layoutRequest message to the RuntimeGUI and builds the database of the widgets by the response
|`f_EPTF_UIHandler_getGUIAddrPorts` |function to get address, port and reconnect port of the GUI to connect.
|`f_EPTF_UIHandler_setGUIAddrPorts` |function to set address , port and reconnect port of the GUI to connect.
|`f_EPTF_UIHandler_setGuiReconnectPort` |function to set the port of the GUI to reconnect.
|`f_EPTF_UIHandler_setGuiHostPort` |function to set address of the GUI to connect.
|`f_EPTF_UIHandler_logAll` |Logs all internal variables in `EPTF_UIHandler_CT`.
|`f_EPTF_UIHandler_logWidgetDB` |Logs all widgets database in `EPTF_UIHandler_CT`.
|`f_EPTF_UIHandler_log2strWidgetRec` |Logs Widget Record
|`f_EPTF_UIHandler_GUIConnected` |Returns whether the GUI is connected (authenticated)
|`f_EPTF_UIHandler_initialized` |Returns whether the GUI is initialized
|`f_EPTF_UIHandler_exitButtonPressed` |Handles the pressing of the exit button. Only for TESTING purposes!
|`f_EPTF_UIHandler_str2Integer` |Converts a string containing non-digit char separated numbers into a record of integer
|`f_EPTF_UIHandler_str2IntegerList` |Converts a string containing non-digit char separated numbers into a record of integer
|`f_EPTF_UIHandler_str2FloatList` |Converts a string containing non-digit char separated numbers into a record of floats
|`f_EPTF_UIHandler_str2bool` |function to convert a string value to a boolean value
|`f_UIHandler_setHandshakeMaxTime` |Sets the max time for the XTDP handshake
|`f_UIHandler_setByeMaxTime` |Sets max time for XTDP bye
|`f_UIHandler_setAuthMaxTime` |Sets max time for XTDP authentication
|`f_EPTF_UIHandler_enableOwnProgress` |Enable/disable UIHandler’s own progress updates to the `"progressBar"` dataSource
|`f_EPTF_UIHandler_updateOwnProgress` |Update the value of the dataSource containing the progress information with the UIHandler's own progress info
|`f_EPTF_UIHandler_updateProgress` |Update the `"progressBar"` dataSource on the UIHandler component
|`f_EPTF_UIHandlerClient_subscribeMe` |Orders the default UIHandler to subscribe to a specified variable and optionally connect to a widget
|`f_EPTF_UIHandlerClient_subscribeMeTo` |Orders an UIHandler to subscribe to a specified variable and optionally connect to a widget
|`f_EPTF_UIHandlerClient_subscribe` |Orders the default UIHandler to subscribe to a specified variable on an other component and optionally connect it to a widget
|`f_EPTF_UIHandlerClient_subscribeTo` |Orders an UIHandler to subscribe to a specified variable on an other component and optionally connect it to a widget
|`f_EPTF_UIHandlerClient_subscribeVariable` |Orders the default UIHandler to subscribe to a specified variable
|`f_EPTF_UIHandlerClient_subscribeVariableTo` |Orders an UIHandler to subscribe to a specified variable
|`f_EPTF_UIHandlerClient_removeElementFromGUI` |Orders the default UIHandler to remove a widget from the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_removeElementFromGUITo` |Orders an UIHandler to remove a widget from the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_enableGUIElement` |Orders the default UIHandler to enable a widget on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_enableGUIElementTo` |Orders an UIHandler to enable a widget on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_disableGUIElement` |Orders the defalut UIHandler to disable a widget on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_disableGUIElementTo` |Orders an UIHandler to disable a widget on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_setFocusToGUIElement` |Orders the defalut UIHandler to set a widget being focused on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_setFocusToGUIElementTo` |Orders an UIHandler to set a widget being focused on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_setFocusToTab` |Orders the defalut UIHandler to select a particular tab of a tabbox on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_setFocusToTabTo` |Orders an UIHandler to select a particular tab of a tabbox on the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_widgetExists` |Checks whether the widget exists on the runtime GUI connected to the default UIHandler
|`f_EPTF_UIHandlerClient_widgetExistsOn` |Checks whether the widget exists on the runtime GUI connected to the specified UIHandler
|`f_EPTF_UIHandlerClient_defaultUIHandler` |Returns the default UIHandler component
|`f_EPTF_UIHandlerClient_logAll` |Logs all internal variable in `EPTF_UIHandlerClient_CT`
|`f_EPTF_CLI_Client_split` |Splits a string using a given separator
|`f_EPTF_UIHandlerClient_XSD_addElementToGUI` |Orders the default UIHandler to add a widget to the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_XSD_addElementToGUITo` |Orders an UIHandler to add a widget to the runtime GUI connected to the UIHandler
|`f_EPTF_UIHandlerClient_XUL_addWidget` |Adds a widget to the GUI
|`f_EPTF_UIHandlerClient_XUL_XSD_addEmptyTabbox` |Adds a new TabBox to the GUI
|`f_EPTF_UIHandlerClient_XUL_XSD_addEmptyTabpages` |Adds a new TabPage to the GUI
|`f_EPTF_UIHandlerClient_XUL_XSD_addWidget` |Adds a widget to the GUI
|`f_EPTF_UIHandlerClient_XUL_addButton` |Puts a new button to the GUI
|`f_EPTF_UIHandlerClient_XUL_addSpacer` |Adds a new spacer to a parent widget on the GUI
|`f_EPTF_UIHandlerClient_XUL_addLabel` |Creates a new text label
|`f_EPTF_UIHandlerClient_XUL_addEmptyHbox` |Creates a new horizontal box
|`f_EPTF_UIHandlerClient_XUL_addEmptyTabbox` |Creates a new tabbed box
|`f_EPTF_UIHandlerClient_XUL_addTabpanel` |Creates a new tab on a tabbed box
|`f_EPTF_UIHandlerClient_XUL_addTab` |Creates a new tab on a tabbed box
|`f_EPTF_UIHandlerClient_XUL_addEmptyChart` |Creates a new chart on the GUI
|`f_EPTF_UIHandlerClient_XUL_addTrace2Chart` |Adds a new trace to a chart
|`f_EPTF_UIHandler_VariableUI_init_CT` |Initializes the `VariableUI` component
|`f_EPTF_UIHandler_VariableUI_putVarbyName` |Puts a variable to the GUI given by name
|`f_EPTF_UIHandler_VariableUI_putconnections` |Puts all the variables to the GUI
|`f_EPTF_UIHandler_VariableUI_putlastconnections` |Put the last given variables to the GUI.
|`f_EPTF_UIHandler_VariableUI_addsimpleconnection` |Adds a simple connection(variable – widget pair)
|`f_EPTF_UIHandler_VariableUI_addwidgetconnection` |Adds a connection with a widget
|`f_EPTF_UIHandler_VariableUI_addholdingwidget` |Adds a holding widget to the database
|`f_EPTF_UIHandler_VariableUI_assignholdingwidget` |Assigns a holding widget to a connection
|`f_EPTF_UIHandler_VariableUI_assignholding` |Assigns a holding widget to a connection
|`f_EPTF_UIHandler_VariableUI_removeconnection` |Removes a connection from the database
|`f_EPTF_UIHandlerXUL_init_CT` |Initialises the `EPTF_UIHandler_CT`
|`f_EPTF_UIHandler_Browser_init_CT` |Initialize the host information to browser GUI
|`f_EPTF_UIHandler_Browser_enableWelcomeScreen` |Enable welcome screen, when the application starts by setting the v_EPTF_UIHandler_Browser_enableWelcomeScreen component variable to true.
|`f_EPTF_UIHandler_Browser_disableWelcomeScreen` |Disable welcome screen, when the application starts by setting the v_EPTF_UIHandler_Browser_enableWelcomeScreen component variable to false.
|`f_EPTF_UIHandler_Browser_getRemoteHosts` |This function returns the Host names and ports on which the BrowserGUI is activated.
|`f_EPTF_UIHandler_Browser_addRemoteHosts` |This function adds the given Host name and port pairs to the list on which the BrowserGUI is activated and activates them as well.
|`f_EPTF_UIHandler_Browser_setRemoteHosts` |This function sets and activates the given Host name and port pairs on which the BrowserGUI is listening.
|`f_EPTF_UIHandler_Browser_clearRemoteHosts` |This function clears the host name and ports on which the BrowserGUI is listening.
|`f_EPTF_UIHandler_Browser_removeRemoteHosts` |This function removes and deactivates the given Host name and port pairs on which the BrowserGUI is listening.
|`f_EPTF_UIHandler_Browser_getCustomStyle` |This function returns the active custom CSS style of the BrowserGUI.
|`f_EPTF_UIHandler_Browser_addCustomStyle` |This function adds the given CSS Style to the main.css from file.
|`f_EPTF_UIHandler_Browser_setCustomStyle` |This function sets the custom style (CSS) from file.
|`f_EPTF_UIHandler_Browser_clearCustomStyle` |This function clears the custom style CSS elements.
|`f_EPTF_UIHandler_Browser_removeCustomStyle` |This function removes the custom style (CSS) based on filename.
|`f_EPTF_UIHandler_Browser_addCustomStyleStr` |This function adds the given CSS Style to the main.css from string.
|`f_EPTF_UIHandler_Browser_setCustomStyleStr` |This function sets the custom style (CSS) from string.
|`f_EPTF_UIHandler_Browser_removeCustomStyleStr` |This function removes the custom style string (CSS) based in string.
|`f_EPTF_UIHandler_Browser_setBrowserDirectory` |This function sets the BrowserGUI directory, where the _.png_, _.css_, _.js_ and several other files are, needed by the BrowserGUI feature.
|`f_EPTF_UIHandler_Browser_getBrowserDirectory` |This function returns with the BrowserGUI directory string, where the _.png_, _.css_, _.js_ and several other files should be, needed by the BrowserGUI feature.
|`f_EPTF_UIHandler_ChartDataType_RB_init` |Function to initialise an empty `<EPTF_BASE_TYPE##RingBuffer>`.
|`f_EPTF_UIHandler_ChartDataType_RB_size` |Function to ask the size of the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_capacity` |Function to ask the capacity of the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_empty` |Checks whether the buffer is empty.
|`f_EPTF_UIHandler_ChartDataType_RB_front` |Function to get the first (eldest) element from the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_back` |Function to get the last (latest) element from the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_push_back` |Function to store a new data item at end of buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_push_front` |Function to store a new data item at beginning of the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_pop_front` |Function to drop the first data item.
|`f_EPTF_UIHandler_ChartDataType_RB_pop_back` |Function to drop the last data item.
|`f_EPTF_UIHandler_ChartDataType_RB_clear` |Function to remove all data from the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_get` |Function to perform an unchecked random access to the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_at` |Function to perform a secure access to the buffer.
|`f_EPTF_UIHandler_ChartDataType_RB_dump` |Function to dump the content of the buffer into a list.
|`f_EPTF_UIHandler_CLI_init_CT` |The initialization function.
|`f_EPTF_UIHandler_CLI_sendUserMessage` |Send a custom message to be displayed to the user.
|`f_EPTF_UIHandler_CLI_logAll` |Log all internal variables in `EPTF_UIHandler_CLI_CT` component.
|`f_EPTF_UIHandler_simulation_createDBFromFile` |
|`f_EPTF_UIHandler_simulation_encode_directContentDB` |Encodes a `EPTF_UIHandler_simulation_directContentDB` to its charstring representation
|`f_EPTF_UIHandler_simulation_decode_directContentDB` |Decode a charstring to EPTF_UIHandler_simulation_directContentDB
|`f_EPTF_UIHandler_XULWidgetId2charstr` |Converts a widget ID to a charstring
|`f_EPTF_UIHandler_CLIClient_init_CT` |The initialization function.
|`f_EPTF_UIHandler_CLIClient_logAll` |Log all internal variables in `EPTF_UIHandler_Private_CT` component.
|`f_EPTF_UIHandler_CLIClient_sendUserMessage` |Sends a custom message to the display terminal
|`f_EPTF_UIHandler_readFileToCharstring` |Loads a XUL describing a window layout and creates the described GUI.
|`f_EPTF_HostAdminUI_behavior` |Puts out a statistic row to its table and starts measuring
|`f_EPTF_LoadRegulatorUI_putUI` |Puts out the widgets of the LoadRegulatorUI
|`f_EPTF_StatCaptureUI_putUI` |Puts out the widgets of the StatCaptureUI
|======================================================================================================================================================================================================================================================
= Terminology
*TitanSim Core (Load) Library(CLL):* +
It is that part of the TitanSim software that is totally project independent. (I.e., which is not protocol-, or application-dependent). The EPTF Core Library is to be supplied and supported by the TCC organization. Any EPTF Core Library development is to be funded centrally by Ericsson
*UIHandler:* +
It is a main feature or an abstract layer of the TitanSim Core Library that is supposed to communicate with a User Interface, for example, Runtime GUI, or CLI.
*UIHandler component:* +
It means a component that extends the `EPTF_UIHandler_CT` component.
*UIHandlerClient or UIHandlerClient component:* +
It is a component that extends the `EPTF_UIHandlerClient_CT`.
*UIHandler CLI:* +
It means a component that extends the `EPTF_UIHandler_CLI_CT` component.
*Headless mode:* +
It is a feature of the `UIHandler` that is useful, when the runtime GUI goes away. When running TitanSim applications with headless mode turned on, the `UIHandler` will be able to reconnect to the GUI.
*EPTF Variable:* +
It is a variable of `EPTF_Var_CT` component.
*Widget:* +
It is a screen element of the runtime GUI.
*Command TELNET terminal:* +
It is the terminal that connects to the `v_UIHandler_CLI_TELNETaspIf` port of the `EPTF_UIHandler_CLI_CT` component.
*Display TELNET terminal:* +
It is the terminal that connects to the `v_UIHandler_CLI_displayTELNETaspIf` port of the `EPTF_UIHandler_CLI_CT` component.
*VariableUI:* +
It is a feature of the `UIHandler`, that allows easier widget – variable connections and subscriptions.
= Abbreviations
CLI:: Command Line Interface
CLL:: Core Load Library
EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
GUI:: Graphical User Interface
PTC:: Parallel Test Component
TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
TTCN-3:: Testing and Test Control Notation version 3 [1]
UDP:: User Datagram Protocol
UI:: User Interface
XTDP:: eXtensible Titan Display Protocol
XTDL:: eXtensible Titan Display Language, a derivative of XUL
XUL:: eXtensible User-interface Language
= References
[[_1]]
[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
The Testing and Test Control Notation version 3. Part 1: Core Language
[[_2]]
[2] User Guide for the TITAN TTCN-3 Test Executor
[[_3]]
[3] EPTF Core Library for TTCN-3 toolset with TITAN, Function Specification
[[_4]]
[4] EPTF Core Library for TTCN-3 toolset with TITAN +
http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]
[[_5]]
[5] EPTF Core Library Variable, Function Description
[[_6]]
[6] Runtime GUI for TTCN-3 Toolset with TITAN, User's Guide
[[_7]]
[7] Telnet Test Port for TTCN-3 Toolset with TITAN, Function Specification
[[_8]]
[8] XTDP Protocol Module User Guide