Qt Protobuf QML types

With the generator plugin, you can register protobuf messages in the QML. To register the type, use the QML and QML_URI generation keys. See API details in qt_add_protobuf command and API usage example QML extended protobuf.

Registered protobuf messages are available in the QML, like built-in Q_GADGET types. The registration is done via the QML module.

Protobuf message duplicates

You should avoid declaration of protobuf message duplicates in your *.proto files or do it wisely. If your application uses several identical protobuf message names declared inside different protobuf packages, they might contradict each other in auto-generated code. In the example below, two different proto packages, qtprotobufnamespace and qtprotobufnamespace1.nested, use the same proto message NestedFieldMessage. The file nested.proto:

syntax = "proto3";

package qtprotobufnamespace;
import "externalpackage.proto";

message NestedFieldMessage {
    sint32 testFieldInt = 1;
}

The file nestedspace1.proto:

syntax = "proto3";

package qtprotobufnamespace1.nested;

message NestedFieldMessage {
    message NestedMessage {
        sint32 field = 1;
    }
    NestedMessage nested = 1;
}

In case there is no possibility to avoid name duplicates among packages, then put duplicated messages in different QML modules and use a <Qualifier> for each QML module import, see Module (Namespace) Imports. Below the example how to add protobuf packages into different QML modules:

# qtprotobufnamespace QML module
qt_add_protobuf(nestedtypes_qtprotobuf_qml
    PROTO_FILES
        nested.proto
    QML
    QML_URI
        qtprotobufnamespace
    OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen1"
)

...

# qtprotobufnamespace1.nested QML module
qt_add_protobuf(nestedspace_qml
    PROTO_FILES
        nestedspace1.proto
    QML
    QML_URI
        qtprotobufnamespace1.nested
    OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/qt_protobuf_gen2"
)

The <Qualifier> usage example:

import qtprotobufnamespace as NestedFieldMessages
import qtprotobufnamespace1.nested as FieldMessages_Nested1

...

property NestedFieldMessages.nestedFieldMessage fieldMsg1;
property FieldMessages_Nested1.nestedFieldMessage fieldMsg2;

QML keywords handling

Pay attention to the keywords that are reserved in QML or JavaScript context, but not reserved in *.proto context. Fields with names that are reserved by QML will be silently extended by _proto suffix by the generator plugin. For example, id, property, and import are reserved keywords. They will be replaced by id_proto, property_proto, import_proto:

message MessageUpperCaseReserved {
    sint32 Import = 1;
    sint32 Property = 2;
    sint32 Id = 3;
}

Generated code output:

Q_PROPERTY(QtProtobuf::sint32 import_proto READ import_proto ...)
Q_PROPERTY(QtProtobuf::sint32 property_proto READ property_proto ...)
Q_PROPERTY(QtProtobuf::sint32 id_proto READ id_proto ...)

Also, enum values cannot begin with a lower case letter. The generator plugin will capitalize the first letter in code output. See the *.proto example below:

enum LowerCaseEnum {
    enumValue0 = 0;
    enumValue1 = 1;
    enumValue2 = 2;
}

Generated code output:

enum LowerCaseEnum {
    EnumValue0 = 0,
    EnumValue1 = 1,
    EnumValue2 = 2,
};
Q_ENUM(LowerCaseEnum)

Also, enum fields cannot begin with an underscore symbol. Such fields will be generated as is, but will be undefined in the QML, unless the QML engine will allow registering them in the future. See the *.proto example below:

enum UnderScoreEnum {
    _enumUnderscoreValue0 = 0;
    _EnumUnderscoreValue1 = 1;
}

Generated output:

enum UnderScoreEnum {
    _enumUnderscoreValue0 = 0,
    _EnumUnderscoreValue1 = 1,
};
Q_ENUM(UnderScoreEnum)

For more information about the QML properties syntax, check Defining Property Attributes.