Property Classes

Description

Using the specific property classes is a convenient way to work with device properties. All specific property classes are extension classes for the DeviceProperty class. When adding the specific classes to the LaRoomy Api, they will be converted to the DeviceProperty class. When retrieving the elements back from the LaRoomy Api, they come as a DeviceProperty object. They can be reconverted to a specific property class by calling the appropriate contructor of the class. Some properties use a specific syntax for the element descriptor to save the different text resources of the property element. More info regarding the property descriptor syntax is available here.

Usage

Here an OptionSelector property is created and added to the Api. 

  	
#define  MY_OPTION_SELECTOR_ID  1

void setup()
{
    // put your setup code here, to run once:
 
    /* other setup */
    
    // create the option-selector
    OptionSelector os;
    os.optionSelectorID = MY_OPTION_SELECTOR_ID;
    os.imageID = LaRoomyImages::OPTION_LIST_170;
    os.optionSelectorDescription = "Select an Option";
    os.selectedIndex = 0;

    // add the options
    os.addOption("Red");
    os.addOption("Green");
    os.addOption("Blue");

    // add the property to the api
    LaRoomyApi.addDeviceProperty(os);

	/* other setup */
    
    LaRoomyApi.run();    
}

When a propery must be retrieved and updated there are different ways: 

  	
    // Get the DeviceProperty object direct
   
    // the retrieved object is from type 'DevicePropery'. Since this class is generalized, there
    // are some convenience-functions missing (in this case: adding an option for example)
    auto optionSelector = LaRoomyApi.getProperty(MY_OPTION_SELECTOR_ID);

    // work with the property..
    // maybe change the image
    optionSelector.imageID = LaRoomyImages::AUTOMATIC_CONTROL_092;

    // update it (if the app is connected, the element will be updated)
    LaRoomyApi.updateDeviceProperty(optionSelector);
  
  	
    // Use the DeviceProperty object to construct a specific property object
    
    // call the constructor of the option selector with the DeviceProperty object as parameter
    OptionSelector os(
        LaRoomyApi.getProperty(MY_OPTION_SELECTOR_ID)
    );

    // work with it - maybe add an option
    os.addOption("White");

    // update it with the LaRoomy Api
    LaRoomyApi.updateDeviceProperty(os);
    
    // or call update on the object direct
    os.update();

The next way is the most convenient way but is not straight forward. Here a feature of the specific property classes are used. If the constructor is called with an ID of a previously added property, the property will be automatically retrieved and is used to initialize the specific property object. 

  	
    // Use the non straight forward way
    
    // calling the constructor of a specific property class with the ID of a
    // previously added property initializes the object with the existing property data
    OptionSelector optionSelector(MY_OPTION_SELECTOR_ID);

    // change the property (here another options is added)
    optionSelector.addOption("Purple");

    // if the object was initialized with the ID, 'update' can be called on the object
    optionSelector.update();

API Reference

This is a list of all available property classes:

Button

  		
class Button {
public:
    Button();
    Button(cID propertyID);
    Button(const Button& b);
    Button(const DeviceProperty& dp);

    String buttonText;
    String buttonDescriptor;
    cID buttonID = 0;
    uint8_t imageID = 0;
    bool isEnabled = true;

    String toDevicePropertyDescriptor();

    void update();
};

The Button-Property is a simple property. The element contains a button with text content (buttonText), a descriptor for the button (buttonDescriptor) and an image (imageID).

Data member:

buttonText - The text displayed inside of the button.

buttonDescriptor - The description of the button.

buttonID - The ID of the button. This value must be unique for each property and must not be zero.

imageID - The image definition for the button element. Show a list of all images...

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

Methods:

toDevicePropertyDescriptor() - Converts the text resources of the button to the required syntax for a DeviceProperty object. Read more about the descriptor syntax..

update - If the buttonID belongs to a previously added button property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

Switch

  		
class Switch {
public:
    Switch();
    Switch(cID propertyID);
    Switch(const Switch& s);
    Switch(const DeviceProperty& dp);

    String switchDescription;
    cID switchID = 0;
    uint8_t imageID = 0;
    bool switchState = false;
    bool isEnabled = true;

    void update();
};

The Switch-Property is a simple property. The element contains a switch, a descriptor for the switch (switchDescription) and an image (imageID).

Data member:

switchDescription - The description of the switch.

switchID - The ID of the switch. This value must be unique for each property and must not be zero.

imageID - The image definition for the switch element. Show a list of all images...

switchState - The state of the switch. true = on / false = off.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

Methods:

update - If the switchID belongs to a previously added switch property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

LevelSelector

  		
class LevelSelector {
public:
    LevelSelector();
    LevelSelector(cID propertyID);
    LevelSelector(const LevelSelector& ls);
    LevelSelector(const DeviceProperty& dp);

    String levelSelectorDescription;
    cID levelSelectorID = 0;
    uint8_t imageID = 0;
    uint8_t level = 0;
    bool isEnabled = true;

    void update();
};

The LevelSelector-Property is a simple property. The element contains a button, a descriptor for the element (levelSelectorDescription) and an image (imageID). The button-text is the current level as a percentage value. If the button is clicked, a popup with a slider is shown where the level can be changed by the user.

Data member:

levelSelectorDescription - The description of the LevelSelector.

levelSelectorID - The ID of the LevelSelector. This value must be unique for each property and must not be zero.

imageID - The image definition for the level selector element. Show a list of all images...

level - The value of the selector. The value can range from 0 to 255.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

Methods:

update - If the levelSelectorID belongs to a previously added LevelSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

LevelIndicator

  		
class LevelIndicator {
public:
    LevelIndicator();
    LevelIndicator(cID propertyID);
    LevelIndicator(const LevelIndicator& li);
    LevelIndicator(const DeviceProperty& dp);

    String levelIndicatorDescription;    
    uint8_t imageID = 0;
    cID levelIndicatorID = 0;
    uint8_t level = 0;
    bool isEnabled = true;
    COLOR valueColor = col_not_set;

    void update();

    String toPropertyDescriptor();
};

The LevelIndicator-Property is a simple property. The element contains a descriptor for the element (levelIndicatorDescription), an image (imageID) and a displayed level as percentage value. The LevelIndicator property is a non-executable property, the user cannot interact with it, it is only intended to show a value.

Data member:

levelIndicatorDescription - The description of the LevelIndicator.

levelIndicatorID - The ID of the LevelIndicator. This value must be unique for each property and must not be zero.

imageID - The image definition for the LevelIndicator element. Show a list of all images...

level - The value of the indicator. The value can range from 0 to 255.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

valueColor - The color of the displayed value. Type: COLOR struct

Methods:

update - If the levelIndicatorID belongs to a previously added LevelIndicator property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

toPropertyDescriptor - Converts the resources of the LevelIndicator to the required syntax for a DeviceProperty object. Read more about the descriptor syntax..

TextDisplay

  		
class TextDisplay {
public:
    TextDisplay();
    TextDisplay(cID propertyID);
    TextDisplay(const TextDisplay& td);
    TextDisplay(const DeviceProperty& dp);

    String textToDisplay;
    cID textDisplayID = 0;
    uint8_t imageID = 0;
    bool isEnabled = true;
    COLOR colorRect = col_not_set;

    void update();

    String toPropertyDescriptor();
};

The TextDisplay-Property is a simple property. The element contains an image and a textField to display a message or status string. The TextDisplay property is a non-executable property, the user cannot interact with it, it is only intended to show text.

Data member:

textToDisplay - The text displayed in the TextDisplay property.

textDisplayID - The ID of the Property. This value must be unique for each property and must not be zero.

imageID - The image definition for the TextDisplay element. Show a list of all images...

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

colorRect - The color of the trailing rect. If this value is set, a colored rectangle is shown at the end of the element. Type: COLOR struct

Methods:

update - If the textDisplayID belongs to a previously added TextDisplay property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

toPropertyDescriptor - Converts the resources of the TextDisplay property to the required syntax for a DeviceProperty object. Read more about the descriptor syntax..

OptionSelector

  		
class OptionSelector {
public:
    OptionSelector();
    OptionSelector(cID propertyID);
    OptionSelector(const OptionSelector& os);
    OptionSelector(const DeviceProperty& dp);

    String optionSelectorDescription;
    cID optionSelectorID = 0;
    uint8_t imageID = 0;
    uint8_t selectedIndex = 0;
    bool isEnabled = true;

    void addOption(String option);

    void clearAllOptions();

    void removeOption(const String& option);
    void removeOption(unsigned int index);

    unsigned int getOptionCount();

    void update();

    String toDevicePropertyDescriptor();
};

The OptionSelector-Property is a simple property. The element contains a button, a descriptor for the element (optionSelectorDescription) and an image (imageID). The button-text is the current selected option string. If the button is clicked, a popup with a string selector is shown where the option selection can be changed by the user.

Data member:

optionSelectorDescription - The description of the OptionSelector.

optionSelectorID - The ID of the OptionSelector. This value must be unique for each property and must not be zero.

imageID - The image definition for the OptionSelector element. Show a list of all images...

selectedIndex - The selected index of the OptionSelector. The value can range from 0 to 255.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

Methods:

addOption - Adds an option string to the OptionSelector property.

clearAllOptions - Removes all option strings from the OptionSelector property.

removeOption - Removes a specific option from the option stack. The desired option can be identified by string equality or index selection.

getOptionCount - Returns the current amount of option elements.

update - If the optionSelectorID belongs to a previously added OptionSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

toPropertyDescriptor - Converts the resources of the OptionSelector property to the required syntax for a DeviceProperty object. Read more about the descriptor syntax..

RGBSelector

  		
class RGBSelector {
public:
    RGBSelector();
    RGBSelector(cID propertyID);
    RGBSelector(const RGBSelector& rs);
    RGBSelector(const DeviceProperty& dp);
    
    String rgbSelectorDescription;    
    cID rgbSelectorID = 0;
    uint8_t imageID = 0;
    bool isEnabled = true;

    RGBSelectorState rgbState;

    void update();
};

The RGBSelector-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

rgbSelectorDescription - The descriptor for the RGBSelector.

rgbSelectorID - The ID of the Property. This value must be unique for each property and must not be zero.

imageID - The image definition for the RGBSelector element. Show a list of all images...

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

rgbState - The ComplexPropertyState of the RGBSelector property. Type: RGBSelectorState

Methods:

update - If the rgbSelectorID belongs to a previously added RGBSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

ExtendedLevelSelector

  		
class ExtendedLevelSelector {
public:
    ExtendedLevelSelector();
    ExtendedLevelSelector(cID propertyID);
    ExtendedLevelSelector(const ExtendedLevelSelector& els);
    ExtendedLevelSelector(const DeviceProperty& dp);

    String extendedLevelSelectorDescription;
    uint8_t imageID = 0;
    cID extendedLevelSelectorID = 0;
    bool isEnabled = true;

    ExtendedLevelSelectorState exLevelState;

    void update();
};

The ExtendedLevelSelector-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

extendedLevelSelectorDescription - The descriptor for the ExtendedLevelSelector.

imageID - The image definition for the ExtendedLevelSelector element. Show a list of all images...

extendedLevelSelectorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

exLevelState - The ComplexPropertyState of the ExtendedLevelSelector property. Type: ExtendedLevelSelectorState

Methods:

update - If the extendedLevelSelectorID belongs to a previously added ExtendedLevelSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

TimeSelector

  		
class TimeSelector {
public:
    TimeSelector();
    TimeSelector(cID propertyID);
    TimeSelector(const TimeSelector& ts);
    TimeSelector(const DeviceProperty& dp);

    String timeSelectorDescription;
    uint8_t imageID = 0;
    cID timeSelectorID = 0;
    bool isEnabled = true;

    TimeSelectorState timeSelectorState;

    void update();
};

The TimeSelector-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

timeSelectorDescription - The descriptor for the TimeSelector.

imageID - The image definition for the TimeSelector element. Show a list of all images...

timeSelectorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

timeSelectorState - The ComplexPropertyState of the TimeSelector property. Type: TimeSelectorState

Methods:

update - If the timeSelectorID belongs to a previously added TimeSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

TimeFrameSelector

  		
class TimeFrameSelector {
public:
    TimeFrameSelector();
    TimeFrameSelector(cID propertyID);
    TimeFrameSelector(const TimeFrameSelector& tfs);
    TimeFrameSelector(const DeviceProperty& dp);

    String timeFrameSelectorDescription;
    uint8_t imageID = 0;
    cID timeFrameSelectorID = 0;
    bool isEnabled = true;

    TimeFrameSelectorState timeFrameSelectorState;

    void update();
};

The TimeFrameSelector-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

timeFrameSelectorDescription - The descriptor for the TimeFrameSelector.

imageID - The image definition for the TimeFrameSelector element. Show a list of all images...

timeFrameSelectorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

timeFrameSelectorState - The ComplexPropertyState of the TimeFrameSelector property. Type: TimeFrameSelectorState

Methods:

update - If the timeFrameSelectorID belongs to a previously added TimeFrameSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

DateSelector

  		
class DateSelector {
public:
    DateSelector();
    DateSelector(cID propertyID);
    DateSelector(const DateSelector& ds);
    DateSelector(const DeviceProperty& dp);

    String dateSelectorDescription;
    uint8_t imageID = 0;
    cID dateSelectorID = 0;
    bool isEnabled = true;

    DateSelectorState dateSelectorState;

    void update();
};

The DateSelector-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

dateSelectorDescription - The descriptor for the DateSelector.

imageID - The image definition for the DateSelector element. Show a list of all images...

dateSelectorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

dateSelectorState - The ComplexPropertyState of the DateSelector property. Type: DateSelectorState

Methods:

update - If the dateSelectorID belongs to a previously added DateSelector property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

UnlockControl

  		
class UnlockControl {
public:
    UnlockControl();
    UnlockControl(cID propertyID);
    UnlockControl(const UnlockControl& uc);
    UnlockControl(const DeviceProperty& dp);

    String unlockControlDescription;
    uint8_t imageID = 0;
    cID unlockControlID = 0;
    bool isEnabled = true;

    UnlockControlState unlockControlState;

    void update();
};

The UnlockControl-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

unlockControlDescription - The descriptor for the UnlockControl.

imageID - The image definition for the UnlockControl element. Show a list of all images...

unlockControlID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

unlockControlState - The ComplexPropertyState of the UnlockControl property. Type: UnlockControlState

Methods:

update - If the unlockControlID belongs to a previously added UnlockControl property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

NavigatorControl

  		
class NavigatorControl {
public:
    NavigatorControl();
    NavigatorControl(cID propertyID);
    NavigatorControl(const NavigatorControl& nc);
    NavigatorControl(const DeviceProperty& dp);

    String navigatorDescription;
    uint8_t imageID = 0;
    cID navigatorID = 0;
    bool isEnabled = true;

    NavigatorState navigatorState;

    void update();
};

The NavigatorControl-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

navigatorDescription - The descriptor for the NavigatorControl.

imageID - The image definition for the NavigatorControl element. Show a list of all images...

navigatorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

navigatorState - The ComplexPropertyState of the NavigatorControl property. Type: NavigatorState

Methods:

update - If the navigatorID belongs to a previously added NavigatorControl property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

BarGraph

  		
class BarGraph {
public:
    BarGraph();
    BarGraph(cID propertyID);
    BarGraph(const BarGraph& bg);
    BarGraph(const DeviceProperty& dp);

    String barGraphDescription;
    uint8_t imageID = 0;
    cID barGraphID = 0;
    bool isEnabled = true;

    BarGraphState barGraphState;

    void update();
};

The BarGraph-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

barGraphDescription - The descriptor for the BarGraph.

imageID - The image definition for the BarGraph element. Show a list of all images...

barGraphID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

barGraphState - The ComplexPropertyState of the BarGraph property. Type: BarGraphState

Methods:

update - If the barGraphID belongs to a previously added BarGraph property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

LineGraph

  		
class LineGraph {
public:
    LineGraph();
    LineGraph(cID propertyID);
    LineGraph(const LineGraph& lg);
    LineGraph(const DeviceProperty& dp);

    String lineGraphDescription;
    uint8_t imageID = 0;
    cID lineGraphID = 0;
    bool isEnabled = true;

    LineGraphState lineGraphState;

    void update();
};

The LineGraph-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

lineGraphDescription - The descriptor for the LineGraph.

imageID - The image definition for the LineGraph element. Show a list of all images...

lineGraphID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

lineGraphState - The ComplexPropertyState of the LineGraph property. Type: LineGraphState

Methods:

update - If the lineGraphID belongs to a previously added LineGraph property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

StringInterrogator

  		
class StringInterrogator {
public:
    StringInterrogator();
    StringInterrogator(cID propertyID);
    StringInterrogator(const StringInterrogator& si);
    StringInterrogator(const DeviceProperty& dp);

    String stringInterrogatorDescription;
    uint8_t imageID = 0;
    cID stringInterrogatorID = 0;
    bool isEnabled = true;

    StringInterrogatorState stringInterrogatorState;

    void update();
};

The StringInterrogator-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

stringInterrogatorDescription - The descriptor for the StringInterrogator.

imageID - The image definition for the StringInterrogator element. Show a list of all images...

stringInterrogatorID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

stringInterrogatorState - The ComplexPropertyState of the StringInterrogator property. Type: StringInterrogatorState

Methods:

update - If the stringInterrogatorID belongs to a previously added StringInterrogator property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.

TextListPresenter

  		
class TextListPresenter {
public:
    TextListPresenter();
    TextListPresenter(cID propertyID);
    TextListPresenter(const TextListPresenter& tlp);
    TextListPresenter(const DeviceProperty& dp);

    String textListPresenterDescription;
    uint8_t imageID = 0;
    cID textListPresenterID = 0;
    bool isEnabled = true;

    TextListPresenterState textListPresenterState;

    void AddTextListPresenterElement(TextListPresenterElementType type, String elementText);
    void ClearTextListPresenterContent();

    void update();
};

The TextListPresenter-Property is a complex property. The element contains an image and a description text for the element. This element is navigable, that means the property has it's own page. The data for the elements on this page is provided through a Complex-Property-State object.

Data member:

textListPresenterDescription - The descriptor for the TextListPresenter.

imageID - The image definition for the TextListPresenter element. Show a list of all images...

textListPresenterID - The ID of the Property. This value must be unique for each property and must not be zero.

isEnabled - The enabled state of the property element. If disabled, the element is grayed out and does not accept user input.

textListPresenterState - The ComplexPropertyState of the TextListPresenter property. Type: TextListPresenterState

Methods:

AddTextListPresenterElement - If the textListPresenterID belongs to a previously added TextListPresenter property, this method can be used to add an element to the textListPresenter. This only makes sense if the remote device is connected to the app. The functionality of this method is equal to the addTextListPresenterElement method of the LaRoomy Api.

ClearTextListPresenterContent - If the textListPresenterID belongs to a previously added TextListPresenter property, this method can be used to clear the content of the textListPresenter. This only makes sense if the remote device is connected to the app. The functionality of this method is equal to the clearTextListPresenterContent method of the LaRoomy Api.

update - If the textListPresenterID belongs to a previously added TextListPresenter property, this method has the same effect as a call to the updateDeviceProperty() method of the LaRoomy Api with this object as an argument.