The cc_tools_qt::property::field namespace contains definition of multiple classes that are expected to be used to define fields properties. For example, let's take a look at definition of field1 of EnumValues message of the demo protocol. The properties for such field can be defined as:

QVariantMap props = 
    cc_tools_qt::property::field::EnumValue()
        .name("field1")
        .add("Value1")
        .add("Value2")
        .add("Value3")
        .asMap();    

NOTE the final call to asMap() member function to retrieved the set properties as QVariantMap.

In general, the name of the properties setting class is the same as the field's class name from the COMMS library. What differs is their respective namespaces.

Use cc_tools_qt::property::field::IntValue to define properties for comms::field::IntValue field.
Use cc_tools_qt::property::field::EnumValue to define properties for comms::field::EnumValue field.
Use cc_tools_qt::property::field::BitmaskValue to define properties for comms::field::BitmaskValue field.
Use cc_tools_qt::property::field::Bitfield to define properties for comms::field::Bitfield field.
Use cc_tools_qt::property::field::Bundle to define properties for comms::field::Bundle field.
Use cc_tools_qt::property::field::String to define properties for comms::field::String field.
Use cc_tools_qt::property::field::ArrayList to define properties for comms::field::ArrayList field.
Use cc_tools_qt::property::field::Optional to define properties for comms::field::Optional field.
Use cc_tools_qt::property::field::FloatValue to define properties for comms::field::FloatValue field.
Use cc_tools_qt::property::field::Variant to define properties for comms::field::Variant field.

The cc_tools_qt library also provides the alias type (cc_tools_qt::property::field::ForField) which can be used to retrieve the right properties definition type, based on the type of the field. For example, the cc_plugin/message/EnumValues.cpp file contains the following code that defines properties for earlier mentioned field1 field of the EnumValues message of the demo protocol.

namespace cc = cc_tools_qt;
...
cc::property::field::ForField<EnumValuesFields::field1>()
    .name("field1")
    .add("Value1")
    .add("Value2")
    .add("Value3")
    .asMap();

Please note, that every "setter" function in every properties definition class returns reference to itself (return *this). It allows the application of settings "one on top of another", just like in the example above.

Common Properties

All the mentioned earlier properties definition classes inherit from cc_tools_qt::property::field::CommonBase, which in turn inherits from cc_tools_qt::property::field::Common. These classes provide set/get functionality of all the properties common to all the fields. They are:

name (see cc_tools_qt::property::field::CommonBase::name())
hidden (see cc_tools_qt::property::field::CommonBase::hidden())
readOnly (see cc_tools_qt::property::field::CommonBase::readOnly())
serialisedHidden (see cc_tools_qt::property::field::CommonBase::serialisedHidden())

"Name" Property

Every field has a name. The cc_view (main GUI application of the CommsChampion Tools) uses the provided "name" property value to display the name of the field in the generated widget:

"Hidden" Property

The cc_view application generated widget for every defined field of the message and every contained member field for such complex fields as comms::field::Bitfield or comms::field::Bundle. The "hidden" property will hide the generated widget. It can be useful when defining some reserved fields, which don't need to be displayed.

"Read Only" Property

The values of some fields may depend on values of some other fields. It may be useful to disallow manual update of such fields. Good example would be having a field that shows number of elements in some other "list" field that appears later in the message. The contents of the former should not be allowed to be updated manually. When "readOnly" property is set, the cc_view application will disallow update of the relevant GUI elements.

"Serialised Hidden" Property.

The cc_view application generated a widget for every field containing two parts. The left one contains value in human readable form, while right part contains raw byte(s) of the same value but serialised. The "serialisedHidden" property can be used to hide the right (serialised) part of the widget. It can be useful when displaying complex fields. For example, field2 of the Lists message. It is defined to be a fixed size list (3 elements) of int16_t values (comms::field::IntValue<...> fields). If the "serialisedHidden" property is NOT set neither on the list, nor on the int fields, the generated widget will contain duplicate information on serialised values. It will look like this:

It is up to developer to decide what "serialised" part to hide, whether it is of the list itself, or of the integer fields it contains.

Properties for comms::field::IntValue

In addition to Common Properties, the cc_tools_qt::property::field::IntValue object has several of its own.

"Display Offset" Property

The COMMS library provides and ability to add a numeric offset to the value of comms::field::IntValue field when the latter is serialised. By default, the left-hand side of the field's widget displays the real value the field contains. Sometimes it is required to display such value with additional offset added to it. For example, the demo protocol defines is transport wrapping data as:

SYNC | LENGTH | ID | PAYLOAD | CHECKSUM

The LENGTH value is defined to contain the remaining length including size of the CHECKSUM. However, the protocol stack is defined to have CHECKSUM layer wrapping the LENGTH one. As the result the real value of the "length" field doesn't include length of the CHECKSUM value (see Stack.h).

using LengthField =
    comms::field::IntValue<
        FieldBase,
        std::uint16_t,
        comms::option::NumValueSerOffset<sizeof(std::uint16_t)>
    >;

When displaying such field, the latter should also add "2" to its displayed value (see cc_plugin/TransportMessage.cpp).

QVariantList createFieldsProperties()
{
    ...
    props.append(
        cc::property::field::ForField<LengthField>()
            .name("LENGTH")
            .displayOffset(2)
            .asMap());
    ...
}

See definition of cc_tools_qt::property::field::IntValue::displayOffset() for more details.

"Scaled Decimals" Property

Many communcation protocols avoid serialisation of the floating point values. Instead they introduce scaling factor and use multiplication / division operations to convert such floating point values to integral one prior to serialisation. Such fields may be defined using comms::field::IntValue classes (see field3 in FloatValues message definition).

// Floating point value serialised as integer with (1e-2) scaling ratio.
using field3 =
    comms::field::IntValue<
        FieldBase,
        std::uint8_t,
        comms::option::ScalingRatio<1, 100>
    >;

However, sometimes it is desired to present it as floating point field to the user. In this case there is a need to provide information about how many digits need to be displayed after the decimal point (see cc_plugin/message/FloatValues.cpp ).

QVariantList createFieldsProperties()
{
    ...
    props.append(
        cc::property::field::ForField<FloatValuesFields::field3>()
            .name("field3")
            .scaledDecimals(2)
            .asMap());
    ...
}

See definition of cc_tools_qt::property::field::IntValue::scaledDecimals() for more details.

Properties for comms::field::EnumValue

In addition to Common Properties, the cc_tools_qt::property::field::EnumValue object is expected to provide names to the enum values the comms::field::EnumValue field may contain. To add such information cc_tools_qt::property::field::EnumValue::add() functions may be used. As an example let's take a look at field1 of the EnumValues message. Its enum type is defined to be

enum class ValuesField1 : std::uint8_t
{
    Value1, 
    Value2, 
    Value3, 
    NumOfValues
};

The first value starts at 0 and every next value is greater by 1 than the previous one. The properties of such field are defined in the following way (see cc_plugin/message/EnumValues.cpp ).

QVariantList createFieldsProperties()
{
    QVariantList props;
    props.append(
        cc::property::field::ForField<EnumValuesFields::field1>()
            .name("field1")
            .add("Value1")
            .add("Value2")
            .add("Value3")
            .asMap());
    ...
}

As a second example let's take a look at field2 of the EnumValues message. Its enum type is defined to be

enum class ValuesField2 : std::int16_t
{
    Value1 = -5, 
    Value2 = 100,
    Value3 = 130,
    Value4 = 1028
};

The properties of such enum field are defined in the following way (see cc_plugin/message/EnumValues.cpp ).

QVariantList createFieldsProperties()
{
    ...
    props.append(
        cc::property::field::ForField<EnumValuesFields::field2>()
            .name("field2")
            .add("Value1", (int)EnumValuesFields::ValuesField2::Value1)
            .add("Value2", (int)EnumValuesFields::ValuesField2::Value2)
            .add("Value3", (int)EnumValuesFields::ValuesField2::Value3)
            .add("Value4", (int)EnumValuesFields::ValuesField2::Value4)
            .asMap());
    ...
}

Please note the availability of two cc_tools_qt::property::field::EnumValue::add() member functions. One of them receives numeric value of enumerator, the other doesn't. The latter just takes the latest inserted value, adds 1 to it and inserts the result as new one.

Properties for comms::field::BitmaskValue

In addition to Common Properties, the cc_tools_qt::property::field::BitmaskValue object is expected to provide names to the bits of the comms::field::BitmaskValue field. To add such information cc_tools_qt::property::field::BitmaskValue::add() functions may be used. The usage is very similar to Properties for comms::field::EnumValue. For examples please take a look at the BitmaskValues message fields definition and definition of the properties inside cc_plugin/message/BitmaskValues.cpp.

Properties for comms::field::Bitfield

In addition to Common Properties, the cc_tools_qt::property::field::Bitfield object is expected to provide also properties of the contained member fields. The properties are added using cc_tools_qt::property::field::Bitfield::add() member function. Note, that created properties are passed already converted to QVariantMap. For example, take a look at fields definitions of the Bitfields message and their properties assignment inside the cc_plugin/message/Bitfields.cpp.

Properties for comms::field::Bundle

Setting properties for comms::field::Bundle field is very similar to setting properties to comms::field::Bitfield (see Properties for comms::field::Bitfield). The properties of the member fields are assigned using cc_tools_qt::property::field::Bundle::add() member function. For example take a look at definition of field4 of the Lists message. The properties for the bundle field are assigned using the following code (see cc_plugin/message/Lists.cpp).

QVariantMap createField4Properties()
{
    ...
    cc::property::field::ForField<ListsFields::field4::ValueType::value_type>()
        .name("element")
        .add(cc::property::field::IntValue().name("memeber1").asMap())
        .add(cc::property::field::IntValue().name("memeber2").asMap())
        .serialisedHidden()
        .asMap()
    ...
}

Properties for comms::field::String

The cc_tools_qt::property::field::String properties definition class doesn't have any extra properties in addition to Common Properties . For usage example, please take a look at For example, take a look at fields definitions of the Strings message definition and defining properties to its field inside cc_plugin/message/Strings.cpp.

Properties for comms::field::ArrayList

The comms::field::ArrayList is a variable length field. It may contain either raw bytes or variable number of fields of the same type. To set the properties for comms::field::ArrayList fields, the cc_tools_qt::property::field::ArrayList can be used. In case of storing raw bytes, there is no need for any extra properties except ones listed in Common Properties. Let's take a look at definition of field1 of Lists message.

// Raw data list that uses 2 bytes size prefix
using field1 =
    comms::field::ArrayList<
        FieldBase,
        std::uint8_t,
        comms::option::SequenceSizeFieldPrefix<
            comms::field::IntValue<
                FieldBase,
                std::uint16_t
            >
        >
    >;

The properties for it are defined in cc_plugin/message/Lists.cpp.

QVariantList createFieldsProperties()
{
    QVariantList props;
    props.append(cc::property::field::ForField<ListsFields::field1>().name("field1").asMap());
    ...
}

When comms::field::ArrayList field contains other fields, there is a need to provide properties for the latter as well. The properties for contained fields are added using cc_tools_qt::property::field::ArrayList::add() member function. Let's take a look at definition of field2 of the same Lists message.

// List of 2 bytes integer value fields, with fixed size of 3 elements
using field2 =
    comms::field::ArrayList<
        FieldBase,
        comms::field::IntValue<
            FieldBase,
            std::int16_t
        >,
        comms::option::SequenceFixedSize<3>
    >;

The maximum number of the elements the list is going to store is known. It is 3. Then, it is possible to assign different properties for each and every one of them. The same cc_plugin/message/Lists.cpp. file contains the following code:

QVariantMap createField2Properties()
{
    typedef ListsFields::field2 Field2;
    static const auto ElemCount =
        Field2::fixedSize();
 
    cc::property::field::ForField<ListsFields::field2> props;
    props.name("field2");
 
    for (auto idx = 0U; idx < ElemCount; ++idx) {
        props.add(
            cc::property::field::IntValue()
                .name(QString("element %1").arg(idx))
                .serialisedHidden()
                .asMap());
    }
    return props.asMap();
}

Note, that cc_tools_qt::property::field::ArrayList::add() member functions was invoked multiple times providing different name for every contained field.

Quite often the maximum number of fields the comms::field::ArrayList field may contain is not known up front. In this case only one set of properties should be added to cc_tools_qt::property::field::ArrayList object, which is going to be used for every displayed field that the list contains. As an example, let's take a look at field3 of the same Lists message.

// List of 2 bytes integer value fields, prefixed with 2 bytes serialisation length
using field3 =
    comms::field::ArrayList<
        FieldBase,
        comms::field::IntValue<
            FieldBase,
            std::uint16_t
        >,
        comms::option::SequenceSerLengthFieldPrefix<
            comms::field::IntValue<
                FieldBase,
                std::uint16_t
            >
        >
    >;

The same cc_plugin/message/Lists.cpp. file contains the following properties setting code:

QVariantMap createField3Properties()
{
    return
        cc::property::field::ForField<ListsFields::field3>()
            .name("field3")
            .add(cc::property::field::IntValue().name("element").serialisedHidden().asMap())
            .asMap();
}

Quite often the comms::field::ArrayList fields are prefixed with number of elements to follow or serialisation length, just like field3 of the
Lists message mentioned earlier. Sometimes it would be convenient to hide the "serialised" information of the list itself ( on the right-hand side of the generated widget), but show one of the contained fields. In this case the information about the list's "prefix" part won't be displayed. To rectify this situation the cc_tools_qt::property::field::ArrayList class provides an ability to show and name such prefix. Please use the following functions to provide such information:

Properties for comms::field::Optional

The properties for comms::field::Optional field are set using cc_tools_qt::property::field::Optional object. In addition to Common Properties it must also contain properties of the wrapped (contained) field. The properties of the latter are set using cc_tools_qt::property::field::Optional::field() member function.

"Uncheckable" Property

By default, the widget generated for the comms::field::Optional field will have small check box which can be used to mark the field as "existing" or "missing". However, most of the time the existence of the comms::field::Optional field is determined by the value of some other field (such as bit in some bitmask). In this case, the user is not supposed to be able to use the described checkbox. Adding the "uncheckable" property will hide it.

As an example, let's take a look at Optionals message. The existance of its field2 and field3 fields is determined by the value of the field1. The properties of the mentioned field are set in cc_plugin/message/Optionals.cpp. file.

QVariantMap createField2Properties()
{
    static const char* Name = "field2";
    return
        cc::property::field::ForField<OptionalsFields::field2>()
            .name(Name)
            .field(
                cc::property::field::ForField<OptionalsFields::field2::Field>()
                    .name(Name)
                    .asMap())
            .uncheckable()
            .asMap();
}

Please note, that the example above sets the same name for the comms::field::Optional field and the wrapped comms::field::IntValue field. The name assigned to the the comms::field::Optional field will be displayed when the field is "missing", but when it's marked as "existing", the widget of the wrapped comms::field::IntValue field is displayed, showing the name of the latter.

Properties for comms::field::FloatValue

The properties for comms::field::FloatValue are defined using cc_tools_qt::property::field::FloatValue. Just like any other field it has all the properties described in Common Properties. It also has one more.

"Decimals" Properties

When displaying value of the comms::field::FloatValue field there is a need to know how many digits to display after the decimal point. The information is provided using cc_tools_qt::property::field::FloatValue::decimals() member function. The cc_plugin/message/FloatValues.cpp file contains code setting properties for such fields used by FloatValues message.

Properties for comms::field::Variant

The process of assigning properties for comms::field::Variant field is very similar to setting properties to comms::field::Bundle (see Properties for comms::field::Bundle). The properties for all possible fields the comms::field::Variant may contain are added using cc_tools_qt::property::field::Variant::add() member function in the order of their definition inside the provided std::tuple.

"IndexHidden" Property.

When setting value of the comms::field::Variant field, the cc_view (main GUI application) allows choice of the actual field type using spin box with type index. However, when the widget has been created and displayed in "read only" mode such index may be hidden using described property. Use cc_tools_qt::property::field::Variant::indexHidden() member function to set it. For example please take a look at definition of the Variants message and the properties setting code inside cc_plugin/message/Variants.cpp file.

Table of Contents