Property Descriptor Syntax

Some properties have different elements containing text resources or other elements which are encoded through a string resource. When using specific property classes the different resources have their own representation objects. For example: A Button property has a button-text which is displayed in the button and a button-descriptor which is the text of the property element. When a specific property is added to the LaRoomy Api, it is converted to a DeviceProperty object which is a generalized representation of a device-property. This class has only one object to store text resources, so the different sources must be encoded to fit in one string. In a property response transmission from the remote device to the app this encoded string is also used to carry different resources. This article describes the pecularities of the property elements that require a special descriptor syntax.


Properties that require special descriptor syntax:

Button

The Button property has two elements that must be packed into the raw descriptor: The button-text and the element-text (button-descriptor). 

  		
/* 
    Both text resources must be separated by semicolons:
*/
    elementText;;buttonText
    
/*
    Example for a raw string:
*/
    char rawDescriptor[] = "Kitchen Light;;Toggle";
    
/*
    The Button class has a method that could be used to build the raw descriptor:
*/
    Button button;
    button.buttonText = "Toggle";
    button.buttonDescriptor = "Kitchen Light";

    auto rawDescriptor = button.toDevicePropertyDescriptor();

When the raw button descriptor does not follow this syntax, the whole string will be treated as element-text and the button will be empty (textless).

LevelIndicator

The LevelIndicator property has two elements that must be packed into the raw descriptor: The element-text and the value-color. The value color is encoded as text resource in a hexadecimal, css-like syntax. 

  		
/* 
    Both text resources must be separated by semicolons:
*/
    elementText;;#rrggbb
    
/*
    Example for a raw string:
*/
    char rawDescriptor[] = "Battery Level;;#ff0000";
/*
	Note: the value will be drawn in red (for example when the battery level is critical)
*/

/*
    The LevelIndicator class has a method that could be used to build the raw descriptor:
*/
    LevelIndicator levelIndicator;
    levelIndicator.levelIndicatorDescription = "Battery Level";
    levelIndicator.valueColor = Colors::Red;

    auto rawDescriptor = levelIndicator.toPropertyDescriptor();

When the raw descriptor for the LevelIndicator property does not follow this syntax, the whole string will be treated as element-text and the color of the value will be set to default color.

TextDisplay

The TextDisplay property has two elements that must be packed into the raw descriptor: The element-text and the value-rect. The value rect is encoded as text resource in a hexadecimal, css-like syntax. 

  		
/* 
    Both text resources must be separated by semicolons:
*/
    elementText;;#rrggbb
    
/*
    Example for a raw string:
*/
    char rawDescriptor[] = "Current Color;;#00ffff";
/*
	Note: the rect will be drawn in cyan color
*/

/*
    The TextDisplay class has a method that could be used to build the raw descriptor:
*/
    TextDisplay textDisplay;
    textDisplay.textToDisplay = "Current Color";
    textDisplay.colorRect = Colors::Cyan;

    auto rawDescriptor = textDisplay.toPropertyDescriptor();

When the raw descriptor for the TextDisplay property does not follow this syntax, the whole string will be treated as element-text and no color rect will be drawn.

OptionSelector

The OptionSelector property has two sources that must be packed into the raw descriptor: The element-text and the option-strings. 

  		
/* 
    All text resources must be separated by semicolons:
*/
    elementText;;option1;;option2;;option3 // ;; ... ;; and so on
    
/*
    Example for a raw string:
*/
    char rawDescriptor[] = "Select a speed grade:;;Slow;;Medium;;Fast";
/*
	Note: regarding the options: first index comes first
*/

/*
    The OptionSelector class has a method that could be used to build the raw descriptor:
*/
    OptionSelector optionSelector;
    optionSelector.optionSelectorDescription = "Select a speed grade:";
    optionSelector.addOption("Slow");
    optionSelector.addOption("Medium");
    optionSelector.addOption("Fast");

    auto rawDescriptor = optionSelector.toDevicePropertyDescriptor();

When the raw descriptor for the OptionSelector property does not follow this syntax, the property is invalid, since the OptionSelector cannot be used without options.