Functional UA runtime API

The Client API allows to create a generic UA application and use it to send Buffers to a CDS. The Client API won't show any Client Interface but will allow to manage the communication with the Server, including receiving Server widget or exception events.

This allows to send Buffers and receive events to the Server programmatically.

Overview

The methods which are explained in this article are provided in the A661RuntimeAPI interface, which the runtimeAPIHelper field in the AbstractFunctionalUA implements.

Contrary to the ARINC 661 client API, the methods are called with the runtimeAPIHelper instance rather then api (the api is called by the runtimeAPIHelper internally).

For example:

      runtimeAPIHelper.setA661WidgetParameter("MyWidgetName", "A661_VISIBLE", true);
      runtimeAPIHelper.sendAllA661BufferContent();

Layers declaration

The UA configuration allows to declare the Layers which will be used by one FunctionalUA.

For example, if you have the following Definition File:

      <a661_df name="Default" library_version="0" supp_version="6">
         <model>
            <prop name="ApplicationId" value="1" />
         </model>
         <a661_layer name="TheLayer1" >
            <model>
               <prop name="LayerId" value="1" />
               <prop name="ContextNumber" value="0" />
               <prop name="Height" value="3000" />
               <prop name="Width" value="8000" />
            </model>
            <a661_widget name="label" type="A661_LABEL">
               <model>
                  <prop name="WidgetIdent" value="2" />
      ...
               </model>
            </a661_widget>
         </a661_layer>
         <a661_layer name="TheLayer2" >
            <model>
               <prop name="LayerId" value="2" />
               <prop name="ContextNumber" value="0" />
               <prop name="Height" value="3000" />
               <prop name="Width" value="8000" />
            </model>
            <a661_widget name="label" type="A661_LABEL">
               <model>
                  <prop name="WidgetIdent" value="2" />
      ...
               </model>
            </a661_widget>
         </a661_layer>
      </a661_df>

In the following example, we have two declared Layers, and the second will be used as the default Layer:

      <uas>
         <ua url="MyUA.jar" path="my.uaappli.UA1" defaultSubscribeService="published">
            <layers>
               <layer appliID="1" layerID="1" />
            </layers>
            <subscribe service="published" >
               <entryPoint method="subscribe" />
            </subscribe>
         </ua>
         <ua url="MyUA.jar" path="my.uaappli.UA2" defaultSubscribeService="published">
            <layers>
               <layer appliID="1" layerID="2" defaultLayer="true" />
            </layers>
            <subscribe service="published" >
               <entryPoint method="subscribe" />
            </subscribe>
         </ua>
      </uas>

In that case the Functional UA runtime API will only be configured for:

• The Layer of AppliID 1 and LayerID 1, with the name "TheLayer1"
• The Layer of AppliID 1 and LayerID 2, with the name "TheLayer2", declared as the default Layer

Default Layer

The UA configuration allows to specify the Layer which will be used by default if no layer name is specified in the A661RuntimeAPI method:

• If there is only one Layer in the uas declarations, then it will be used as the default Layer
• Else it is possible to explicitly declare a layer as the default

In the following example, there is only one Layer for the UA, which means it is the default Layer:

      <uas>
         <ua url="MyUA.jar" path="my.uaappli.UA1" defaultSubscribeService="published">
            <layers>
               <layer appliID="1" layerID="1" />
            </layers>
            <subscribe service="published" >
               <entryPoint method="subscribe" />
            </subscribe>
         </ua>
      </uas>

In the next example, the first Layer is explictly declared as the default Layer:

      <uas>
         <ua url="MyUA.jar" path="my.uaappli.UA1" defaultSubscribeService="published">
            <layers>
               <layer appliID="1" layerID="1" defaultLayer="true"/>
               <layer appliID="1" layerID="2" />
            </layers>
            <subscribe service="published" >
               <entryPoint method="subscribe" />
            </subscribe>
         </ua>
      </uas>

In the last example, no default Layer is declared, so the last one will be used as the default:

      <uas>
         <ua url="MyUA.jar" path="my.uaappli.UA1" defaultSubscribeService="published">
            <layers>
               <layer appliID="1" layerID="1" />
               <layer appliID="1" layerID="2" />
            </layers>
            <subscribe service="published" >
               <entryPoint method="subscribe" />
            </subscribe>
         </ua>
      </uas>

API runtime

Overview

You must note that the communication will only be possible after the API has been connected. The runtime sequence is the following:

• For each parameter, the UA sets parameter values to the runtimeAPIHelper instance, then the runtimeAPIHelper calls the underlying api to effectively perform the sets parameter value
• The UA calls the runtimeAPIHelper to send the content of the Buffer
• Then the content of the Buffer is effectively sent by the underlying api

For example:

      runtimeAPIHelper.setA661WidgetParameter("MyWidgetName", "A661_VISIBLE", true);
      runtimeAPIHelper.sendAllA661BufferContent();

Set values for widgets parameters

For the default Layer, you can use either:

• The A661RuntimeAPI.setA661WidgetParameter(String, String, Object) with the widget name, and the parameter ID
• The A661RuntimeAPI.setA661WidgetParameterFromName(String, String, Object) with the widget name, and the parameter name

For example:

      runtimeAPIHelper.setA661WidgetParameter("MyLabel", "A661_VISIBLE", true);
      runtimeAPIHelper.setA661WidgetParameterFromName("MyLabel", "PosX", 5000);
      runtimeAPIHelper.setA661WidgetParameterFromName("MyLabel", "LabelString", "CANNIBAL CORPSE");
      runtimeAPIHelper.setA661WidgetParameter("MyLabel", "A661_STYLE_SET", 12);
      runtimeAPIHelper.sendAllA661BufferContent();

For any declared Layer, you can use either:

• The A661RuntimeAPI.setA661WidgetParameter(String, String, String, Object) with the Layer name, the widget name, and the parameter ARINC ID
• The A661RuntimeAPI.setA661WidgetParameter(int, String, String, String, Object) with the application ID, the Layer name, the widget name, and the parameter ARINC ID
• The A661RuntimeAPI.setA661WidgetParameterFromName(String, String, String, Object) with the Layer name, the widget name, and the parameter name
• The A661RuntimeAPI.setA661WidgetParameterFromName(int, String, String, String, Object) with the application ID, the Layer name, the widget name, and the parameter name

For example:

      runtimeAPIHelper.setA661WidgetParameter("TheLayer1", "MyLabel", "A661_VISIBLE", true);
      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyLabel", "PosX", 5000);
      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyLabel", "LabelString", "CANNIBAL CORPSE");
      runtimeAPIHelper.setA661WidgetParameter("TheLayer1", "MyLabel", "A661_STYLE_SET", 12);
      runtimeAPIHelper.sendAllA661BufferContent();

With the application ID:

      runtimeAPIHelper.setA661WidgetParameter(10, "TheLayer1", "MyLabel", "A661_VISIBLE", true);
      runtimeAPIHelper.setA661WidgetParameterFromName(10, "TheLayer1", "MyLabel", "PosX", 5000);
      runtimeAPIHelper.setA661WidgetParameterFromName(10, "TheLayer1", "MyLabel", "LabelString", "CANNIBAL CORPSE");
      runtimeAPIHelper.setA661WidgetParameter(10, "TheLayer1", "MyLabel", "A661_STYLE_SET", 12);
      runtimeAPIHelper.sendAllA661BufferContent();

Constraints on the parameter value

The API allows to specify the parameter value with its ARINC 661 type, but you can also use Strings for Colors, Pictures, Fonts, Clippings, Blinkings, or Widget IDs. For example:

      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyLabel", "ColorIndex", "Red");
      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyPicture", "PictureReference", "Ball");
      runtimeAPIHelper.sendAllA661BufferContent();

The API also allows to use Strings for enumerative values. For example:

      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyLabel", "Alignment", "A661_CENTER");
      runtimeAPIHelper.sendAllA661BufferContent();

The API also allows to use the names of widgets instead of widget IDs. For example:

      runtimeAPIHelper.setA661WidgetParameterFromName("TheLayer1", "MyMutually", "VisibleChild", "TheWidget");
      runtimeAPIHelper.sendAllA661BufferContent();

Listen to layers or widget events

You can use either:

• The A661RuntimeAPI.addA661WidgetEventListener(String, ARINCEventListener) on the default Layer
• The A661RuntimeAPI.addA661WidgetEventListener(String, String, ARINCEventListener) on a declared Layer
• The A661RuntimeAPI.addA661WidgetEventListener(int, String, String, ARINCEventListener) on a declared Layer, specifying the application ID and the Layer name

Example when listening for a A661_EVT_SELECTION event on a PushButton on the default Layer:

      runtimeAPIHelper.addA661WidgetEventListener("MyPushButton", new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          System.out.println("Button Pressed");
        }
      });

Example when listening for a A661_EVT_SELECTION event on a PushButton on a declared Layer:

      runtimeAPIHelper.addA661WidgetEventListener("TheLayer1", "MyPushButton", new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          System.out.println("Button Pressed");
        }
      });

To check the event ID, check the associated event ID. For example, to check if the cursor enters or exits the area of an A661_CURSOR_OVER widget:

      runtimeAPIHelper.addA661WidgetEventListener("MyCursorOver", new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
            System.out.println("Cursor Enter");
          } else if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_EXIT) {
            System.out.println("Cursor Exit");
          }
        });
      });

If the event has associated values, you can retrieve these values with the getFirstValue() or getValues() methods on the WidgetEvent class. For example, to get the PosX and PosY coordinates of the cursor relative to the A661_CURSOR_OVER widget:

      runtimeAPIHelper.addA661WidgetEventListener("MyCursorOver", new ARINCEventListener() {
        public void eventReceived(ARINCEvent evt) {
          WidgetEvent widgetEvt = (WidgetEvent) evt;
          if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
            long posX = (long)widgetEvt.getValues.get(0);
            long posY = (long)widgetEvt.getValues.get(1);
            System.out.println("Cursor Enter at " + posY + " and " + posY);
          }
        });

Sending a BufferOfMapItems

The A661RuntimeAPI has helper methods which simplify the sending of BufferOfMapItems to the CDS.

Creation of a representation for a MapItemList

The MapItemListRep is a representation of a MapItemList widget which can be used to send Buffer of MapItems to the CDS.

To create a MapItemListRep helper, you can use one of the following methods:

• The A661RuntimeAPI.addMapItemListRep(String) will create a MapItemListRep on the default Layer
• The A661RuntimeAPI.addMapItemListRep(String, String) will create a MapItemListRep on the specified Layer

For example:

      MapItemListRep rep = runtimeAPIHelper.addMapItemListRep("MyMapItemList");
      or:
      MapItemListRep rep2 = runtimeAPIHelper.addMapItemListRep("TheLayer1", "MyMapItemList2");

Adding a MapItem

The MapItemListRep.addItem(int, String) allows to add a MapItem for the MapItemList managed by the MapItemListRep helper.

It therefore possible to set properties for this MapItem. For example:

      ItemMap mapItem = rep.addItem(1, "A661_SYMBOL_GENERIC");
      mapItem.addProperty("X", 0.1);
      mapItem.addProperty("Y", 0.1);
      mapItem.addProperty("SymbolType", 1);

Sending the Buffer to the API

The content of the Buffer is sent to the API by MapItemListRep.setBufferContent().