This topic explains how to use the QFace IDL. A complete description of the library is available at https://pelagicore.github.io/qface/.

QFace (Qt Interface Language) is an Interface Description Languge (IDL). While it's primarily designed to define an interface between Qt, QML, and C++, it is flexible enough to be used in other contexts.

The IDL

The IDL uses common API concepts such as modules, interfaces, properties, structs, enums, or flags. Additionally, the IDL knows about lists and models:

• list - an array of primitive or complex types
• model - an container for large data sets, typically used via a defined API

module org.example 1.0

interface Echo {
    string message;
    void echo(string message);
    signal broadcast(string message);
    Status status;
}

enum Status {
    Null, Loading, Ready, Error
}

The data types provided by QFace can be divided into primitive and complex types:

Primitive Types

• bool
• int
• real
• string
• var

Complex Types

• Interface
• Struct
• Enum
• Flag
• Array
• Model

The language as such does not provide any support for maps or dictionaries. QFace doesn't provide a map container type because keys in dictionaries require a hash, which isn't always available in complex types.

Grammar

The grammar of QFace is well-defined and is based on the concepts of modules as a larger collection of information.

A module can have several interfaces, structs, enums, or flags.

module <module> <version>
import <module> <version>

interface <Identifier> {
    [readonly] <type> <identifier>
    <type> <operation>(<parameter>*)
    signal <signal>(<parameter>*)
}

struct <Identifier> {
    <type> <identifier>;
}

enum <Identifier> {
    <name> = <value>,
}

flag <Identifier> {
    <name> = <value>,
}

A QFace document always describes one module. Each document can contain one or more interfaces, structs, enums, or flags. Each document can import other modules using the import statement.

Note: There are some limitations with the Qt Ivi generator that parses the QFace IDL file. For more information, see Known Limitations.

Module

A module consists of one or more interfaces, structs, enums, or flags; in any combination. A module is identified by its name. This name should be a URI, such as, entertainment.tuner.

Interface

An interface is a collection of properties, operations, and signals. Properties carry data, while operations modify data. Signals are used to notify the user about changes that have taken place. The interface is the only type that can contain operations and signals.

interface WeatherStation {
    real temperature;
    void reset();
    signal error(string message);
}

The QFace library does not allow for interfaces to be extended; this is by design.

Struct

The struct serves as a container to transport structured data. Unlike an interface, a struct doesn't support operations and signals.

Property

Properties carry data about interfaces and structures: syntax elements allow you to describe some attributes of the data. A property can be of any type known to the IDL. It can be marked as readonly, in which case this attribute of the interface is not supposed to be written to from code outside. But it's up to the generator to enforce this constraint.

Enum or Flag

Enum and flags allows you to encode information used inside the struct or interface as data types. Enums and flags are common concepts in many popular programming languages. But in the IDL, enums are allowed to take single value only, whereas flags can take a combination of multiple values that are combined with the bitwise OR operator.

Type

A type can be an interface, struct, enum, or flag. Types are either local or external. Local types can be referenced by their name. External types are from an external module, and they need to be referenced with their fully qualified name, module.<name>.

Below is an example of a QFace file.

module entertainment.tuner 1.0;

import common 1.0

interface Tuner {
    // property currentStation
    readonly Station currentStation;
    // operation nextStation
    void nextStation();
    // operation previousStation
    void previousStation();
    // operation updateCurrentStation
    void updateCurrentStation(int stationId);

    list<int> primitiveList;
    list<Station> complexList;
    model<int> primitiveModel;
    model<Station> complexModel;
}

Note: There are some limitations with the Qt Ivi generator that parses the QFace IDL file. For more information, see Known Limitations.

Annotation

Annotations are a way to add meta information to your interface definition, such as tags. They are available to each symbol in the interface.

A module, interface, struct, or enum, can be preceded by one or several annotations. You can also use annotations before an operation, property, or signal. Ultimately, you can use annotations anywhere documentation comments are allowed.

An annotation is written as follows:

@service: {port: 12345}
interface Tuner {
}

An in-code annotation precedes a symbol and starts with the @ sign. A symbol can have more than one annotation line, with each line having one individual annotation. The content is in YAML format. All @ signs preceding a symbol are collected and then evaluated using a YAML parser.

For larger annotations, you can use the external annotation document feature.

@singleton: yes
@data: [1,2,3]
@config: { values: [LEFT, RIGHT, TOP] }

This results in the following YAML content:

singleton: yes
data: [1,2,3]
config: { values: [LEFT, RIGHT, TOP] }

The result, as a Python object, would be:

{
  "data": [ 1, 2, 3 ],
  "singleton": true,
  "config": {
    "values": [ "LEFT", "RIGHT", "TOP" ]
  }
}

Annotation Documents

QFace allows you to also specify these annotations in external documents using the YAML syntax. For this you need to create a document with the same name as the QFace document, but wth a .yaml extension.

Your document should resemble the following:

com.pelagicore.ivi.Tuner:
    service:
      port: 12345

The root level should contain a symbol's fully qualified name. This symbol is looked up and the accompanying annotation information is then merged with any existing annotations from the QFace document.

Merge Annotations

The external annotations are merged on top of the embedded annotations, per symbol; dictionaries are also merged. If a merge can't be done, then the external document based annotations will always override the embedded annotations.

When you navigate the domain model, the external annotations are placed in a later portion.

{% if "service" in interface.tags %}
interface {{interface}} is served on port: {{interface.tags.service.port}}
{% else %}
interface {{interface}} is not served
{% endif %}

Note: QFace does not specify specific annotations, but defines the annotation format only. It is the generator that defines and documents the set of supported annotations.

Domain Model

A domain model object is created, as a result of parsing the IDL document. The domain model defines the structure of our system as objects. It is built by the parser and serves as the input into the generator.

The IDL is converted into an in-memory domain model (see qface/idl/domain.py).

- System
    - Module
        - Import
        - Interface
              - Property
              - Operation
              - Event
        - Enum
        - Flag
        - Struct
              - Property

The domain model is the base for any code generation. You traverse the domain tree and then trigger your own code generation.