XGCONF Module Writers Guide

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 19-Apr-2014 04:04 UTC

XGCONF Module Writers Guide

Adding modules to the XGCONF view



This guide is written for RTSC content producers who already have experience with developing RTSC modules and now want to enable their modules to be configured in XGCONF, the RTSC graphical configuration tool. It is important to mention that, even without any additional work on part of a module producer, any RTSC module can be configured in XGCONF. In the next section, there is an example of XGCONF configuration of a RTSC module that does not implement any XGCONF code. However, there are some functional and visual drawbacks to the default module representation in XGCONF. With a little additional effort, a content producer can create an XGCONF layer on top of a RTSC module.

Quick Start Guide

This example demonstrates how to create a minimal XML file that adds a module to the XGCONF view. First, we show the default XGCONF view for the modules that do not implement any XML files, and then we improve the module consumer's configuration experience by adding a small XML file.

For the purposes of this and following examples, let us assume there is a RTSC repository in the directory C:\newProd\packages. The repository is added to a CCS project through Project Properties->CCS General->RTSC->Add...->Select repository from file-system. The repository contains a package ti.demo, and the package contains a module Mod. The module has four configuration parameters, some with and some without default values:

module Mod {
    config int num = 3;
    config String msg;
    config Bool flag = true;
    enum E {E0, E1, E2};
    config E enumV;

The following picture displays the Available Products view, which contains all products and repositories found on the package path for the CCS project. To use Mod, a user has to expand the package tree for the repository, right-click on the module's name and click on "Use Mod". After that, the module's configuration parameters are displayed in a grid in the XGCONF view, on the left. The first problem with this view is that the configuration parameters are listed in the same order as in the XDC file and cannot be organized into logically connected groups. Furthermore, widgets selected for various parameters are not under the module producer's control. And finally, the parameter names are used as labels instead of possibly more descriptive labels that do not have to conform to the syntax of XDCscript and C.


In the next step, we add one more module named ModView to the package ti.demo. The module ModView is identical to Mod, but in addition to the specification file ModView.xdc, ModView comes with a small XML file ModView.xml. By adding an XML file, a content producer can control how the configuration of his module is presented to users. The file that represents the module in XGCONF is an XML file with the same base name as the module. The file contains an HTML table that contains the configuration parameters from ModView, surrounded by some minimal XGCONF specific XML tags:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<gep name="ModView" title="Xgconf XML example">
<page title="Basic Page">
<tr><td><h1>Parameters with defaults</h1></td></tr>
<td><control type="label" label="ModView.num (Integer)"/></td>
<td><control type="editbox" value="value:this.num"/></td>
<td><control type="label" label="ModView.flag (Boolean)"/></td>
<td><control type="checkbox" value="value:this.flag"/></td>
<tr><td><h1>Parameters without defaults</h1></td></tr>
<td><control type="label" label="ModView.msg (String)"/></td>
<td><control type="editbox" value="value:this.msg"/></td>
<td><control type="label" label="ModView.enum (Enum E)"/></td>
<td><control type="droplist" value="value:this.enumV"/></td>


The controls and their properties that can be used within XGCONF XML files are documented in XML Controls Reference.

Creating a RTSC Product

In the previous examples, we added an XML file that overlays a logical organization on top of a module's configuration parameters. In this section, we introduce a next level of logical organization of content presented in XGCONF - a RTSC product. RTSC products can separate its modules and packages into logical units and can consist of multiple package repositories.

The first step in creating a RTSC product is to define a RTSC module that inherits from the interface xdc.tools.product.IProduct. That module defines some elementary properties of a product: its name, a version, an array of package repositories, and the name of the module that defines a GUI representation of the product. Here is an example of a module that defines a RTSC product:

metaonly module Product inherits xdc.tools.product.IProduct {
    override config String name = "Demo";
    override config String version = "";
    override config String productViewModule = "ti.demo.product.DemoProdView";
    override config String id = "com.ti.demo.xgconf";
    override config String bundleName = "demo";
    override config String copyRightNotice = "Empty";
    override config String repositoryArr[] = ["packages"];

This module and its package are not delivered with the product. Modules that inherit IProduct are meant to expose a RTSC product to various IDEs, which do not process RTSC files. Therefore, such modules must be processed by an additional tool that would convert the module to a format than an IDE understands. The particular IDE we use in this guide, Eclipse-based Code Composer Studio is extended through plugins. Consequently, we need to use a tool that will convert a RTSC module that inherits IProduct into an Eclipse plugin. Such a tool is delivered with an XDCtools installation and can be found in the package xdc.tools.product.plugingen. After plugingen processes the module the resulting Eclipse plugin is added to the RTSC product while the original package containing the module inheriting IProduct is not needed in the product itself. In this example, we keep the module Product in a separate package ti.demo.productdef. Here is the command line that creates a plugin:

C:\newProd\packages\ti\demo\productdef>xs xdc.tools.product.plugingen -p C:\newProd -m

If the plugin generation succeeds, the following output is displayed:

Generated eclipse extension in folder: C:\newProd\eclipse

It is assumed that the packages ti.demo.productdef and the package ti.demo.product referenced by the parameter productViewModule are already built before plugingen runs.

After the package is built, and xdc.tools.product.plugingen runs, the result is an eclipse plugin which is added to the product as a subdirectory eclipse in the top directory of the product. The directory where the plugin is generated is specified by the option -p on the plugingen command line. After we add the path to the product (C:\newProd) in Windows->Preferences->Code Composer Studio->RTSC->Products->Add..., and restart Code Composer Studio, we can add the new product to our CCS project, as shown in the following picture:


The name of the product and its version are defined by the parameters name and version specified in the module Product on lines 1 and 2. The line 4 defines repository directories that are added to the package path whenever the product is used in a CCS project.

Home Module

The module Product defines general properties of a RTSC product that introduce the product to Code Composer Studio. The only parameter relevant to XGCONF, productViewModule, is shown on line 3. The parameter points to a module DemoProdView located in the package ti.demo.product. This module defines various properties of the graphical view of the product, such as the grouping of the modules into logical groups, and the name of the module that is presented as the initial view of a product in XGCONF, whenever a product is used in a configuration.

metaonly module DemoProdView inherits xdc.tools.product.IProductView {
    override config String homeModule = "ti.demo.Home";

The XML page for Home contains only one button, which when clicked on, opens the configuration page for ModView. Image:Home.png

The code that generates the page has only one control element for the button:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<gep name="Home" title="Xgconf XML example">
<page title="Welcome Page">
<control type="pushbutton" label="ModView" link="ref:ti.demo.ModView" align="center" width="100" height="30"/>

The XDCscript file for DemoProdView is very simple. It only points to the module Home, which we need to add to the package ti.demo, as the product's home module. A module denoted as a home module of a RTSC product must have an XML file, and it is usually a module that is loaded in each configuration that uses its product. The home module's XML file will be displayed as a home page of a project that includes this module's product.

Let us review now the content of DemoProdView.xs. The file contains only one function getProductDescriptor(). This function generates the content of the product's navigation tree in the view Available Products.


The navigation tree consists of instances of the structure ProductElemDesc defined in xdc.tools.product.IProductView. We first create a structure for modules Mod and ModView and define the properties of these nodes as they appear in Available Products. These properties are a reference to an actual module that the node represents, the name that appears in Available Products, and an icon file. Then, we create a top node, which is not connected to any particular module, but contains two module nodes in its elemArray property. We do not need to list all modules from the product in the value returned from getProductDescriptor(). We intentionally omitted the module Home because its only purpose is to bring in the product's home page, and there is no need for users to configure usage of that module.

function getProductDescriptor() 
    var ProdMod = xdc.module("xdc.tools.product.IProductView");
    var prod = new ProdMod.ProductElemDesc();
    var Mod = new ProdMod.ProductElemDesc();
    Mod.elemName = "Mod";
    Mod.moduleName = "ti.demo.Mod";
    Mod.iconFileName = "icons/xdc.gif";
    var ModView = new ProdMod.ProductElemDesc();
    ModView.elemName = "ModView";
    ModView.moduleName = "ti.demo.ModView";
    ModView.iconFileName = "icons/xdc.gif";
    prod.elemName = "XGConf Demo";
    prod.moduleName = null;
    prod.iconFileName = "icons/xdc.gif";
    prod.elemArray = [Mod, ModView];
    return prod;

XML Controls Reference

The syntax for the XML element control is:

<control type="controlType" value="value:RTSCParameter" [ attributeName="attributeValue"]*/>
checkbox | droplist | editbox | hyperlink |  infobox | jumper | label | listbox | popupmenu |
pushbutton | radiobutton | radiogroup | togglebutton

The attributes type and value are listed separately in the definition of the syntax for control because they are not optional in most cases. RTSCParameter is a reference to a module parameter or an instance parameter of a RTSC module. Although an XML file always belong to a specific module, any RTSC module can be referenced in that file.

The attributes available for a specific control type slightly differ, as well as the valid attribute values. However, many of them are used in the same way for all types. The list of attributes and their values is given in Table 1.

Table 1 Supported Attributes
atributeName attributeValue
label text to display alongside the control
enabled if true the initial value can be changed
visible if false the control is not displayed
bold true or false
fontHeight size in points (1/72th of an inch)
[printable version]  [offline version]offline version generated on 19-Apr-2014 04:04 UTC
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference