Property-State Classes

Description

Property State Classes are used to carry the data and logic for the states of Complex Properties. Every complex type property class has a respective Complex-State class as member defining the state of the property. Simple Property-States are carried within an Property-Transmission, but Complex-Property-States have their own transmission to send the state from device to app and vice versa. Complex States are retrieved from the app in a Complex-Property-State-Loop. Some member of Complex-Property-State classes are only used in one direction. For example: member affecting the visual appearance of the page in the app are only used when the state is transmitted from device to app. Otherwise they are not set or will be ignored. Remember to always keep the Property-States up to date even if the device is not connected.

Usage

Here a RGBSelector property is created and it's initial RGBSelectorState is defined. 

  	
    #define MY_RGB_SELECTOR_ID  1
    
    // create a rgb selector property
    RGBSelector rgbSelector;
    rgbSelector.imageID = LaRoomyImages::RGB_CIRCLES_019;
    rgbSelector.rgbSelectorID = MY_RGB_SELECTOR_ID;
    rgbSelector.rgbSelectorDescription = "Select a Color";

    // define the initial state for the property
    rgbSelector.rgbState.isOn = false; // state initally off (this is the default)
    rgbSelector.rgbState.colorTransitionProgram =
        RGBColorTransitionProgram::RCTP_NO_TRANSITION; // no transition (default)

    // set color to green
    rgbSelector.rgbState.redValue = 0;
    rgbSelector.rgbState.greenValue = 255;
    rgbSelector.rgbState.blueValue = 0;

    // with the flags some elements on the rgb page can be hidden
    // here the intensity slider is hidden
    rgbSelector.rgbState.flags = RGBSelectorFlags::RSF_HIDE_INTENSITY_SLIDER;

    // add the property
    LaRoomyApi.addDeviceProperty(rgbSelector);

If the state must be modified later, it can be retrieved, changed and updated 

  	
   // retrieve the RGBSelectorState for the previously added RGBSelector
    auto rgbState = LaRoomyApi.getRGBSelectorState(MY_RGB_SELECTOR_ID);

    // change color to blue
    rgbState.blueValue = 255;
    rgbState.greenValue = 0;
    rgbState.redValue = 0;

    // show the intensity slider (clear the flag)
    rgbState.flags &= ~RGBSelectorFlags::RSF_HIDE_INTENSITY_SLIDER;

    // set state to ON
    rgbState.isOn = true;

    // finally update the state (if the app is connected an update transmission will be sent)
    LaRoomyApi.updateRGBState(MY_RGB_SELECTOR_ID, rgbState);

API Reference

This is a list of all available Complex-Property-State-Classes

RGBSelectorState

  		
class RGBSelectorState {
public:
    RGBSelectorState();
    RGBSelectorState(const RGBSelectorState& state);

    bool isOn = false;
    unsigned int flags = 0;
    
    RGBColorTransitionProgram colorTransitionProgram =
    	RGBColorTransitionProgram::RCTP_NO_TRANSITION;
        
    unsigned int redValue = 255;
    unsigned int greenValue = 255;
    unsigned int blueValue = 255;
    
    RGBTransitionType transitionType = RGBTransitionType::SOFT_TRANSITION;
};

The RGBSelectorState is the complex state of a RGBSelector property. It carries all data that could be modified within a RGBSelector page.

Data member:

isOn - Determines whether the property is switched on or off.

flags - Flags can be used to adapt the UI. Unused elements can be hidden. Use the RGBSelectorFlags enum to set one ore more flags.

colorTransitionProgram - If a color-transition-program is set up, this is the transition-program. Type: RGBColorTransitionProgram

redValue - The red part of the color. Can take values from 0 to 255.

greenValue - The green part of the color. Can take values from 0 to 255.

blueValue - The blue part of the color. Can take values from 0 to 255.

transitionType - The transition type. This determins how colors should be changed. Type: RGBTransitionType

ExtendedLevelSelectorState

  		
class ExtendedLevelSelectorState {
public:
    ExtendedLevelSelectorState();
    ExtendedLevelSelectorState(const ExtendedLevelSelectorState& state);

    bool isOn = false;
    
    int16_t levelValue = 0;
    int16_t maxValue = 100;
    int16_t minValue = 0;
    
    bool showOnOffSwitch = true;
    bool transmitOnlyStartAndEndOfTracking = false;
    
    ExLevelTrackingType trackingType = ExLevelTrackingType::ELTT_UNUSED;
};

The ExtendedLevelSelectorState is the complex state of a ExtendedLevelSelector property. It carries all data to define the range of the selector, control visibility, transmission behaviour and the level itself.

Data member:

isOn - Determines whether the property is switched on or off.

levelValue - The current position of the level slider. The value must be in a valid scope regarding to the min and max values.

maxValue - The maximum position value of the level slider.

minValue - The minimum position value of the level slider.

showOnOffSwitch - Determins whether the on/off switch should be shown or not.

transmitOnlyStartAndEndOfTracking - Controls the transmission behaviour of the element. If this is true and a slider tracking occurs, the app sends only position updates at the start and the end of tracking of the slider. If this is false, updates will be sent also while the user is tracking the slider.

trackingType - The tracking type (start/end/intertrack). Only used in a transmission from app to device. Type: ExLevelTrackingType

TimeSelectorState

  		
class TimeSelectorState {
public:
    TimeSelectorState();
    TimeSelectorState(const TimeSelectorState& state);

    unsigned int hour = 0;
    unsigned int minute = 0;

    STATETIME toStateTime();
};

The TimeSelectorState is the complex state of a TimeSelector property. It carries the selected time.

Data member:

hour - The hour of the selector.

minute - The minute of the selector.

Methods:

toStateTime - Returns the time data as a STATETIME object.

TimeFrameSelectorState

  		
class TimeFrameSelectorState {
public:
    TimeFrameSelectorState();
    TimeFrameSelectorState(const TimeFrameSelectorState& state);

    STATETIME startTime = {0,0};
    STATETIME endTime = {0,0};

    bool checkIfTimeIsInFrame(const STATETIME& pTime);
};

The TimeFrameSelectorState is the complex state of a TimeFrameSelector property. It carries a time frame.

Data member:

startTime - The start-time of the frame selector. Type: STATETIME

endTime - The end-time of the selector. Type: STATETIME

Methods:

checkIfTimeIsInFrame - Returns true if the pTime parameter is inside the time-frame, false otherwise.

DateSelectorState

  		
class DateSelectorState {
public:
    DateSelectorState();
    DateSelectorState(const DateSelectorState& state);
    
    unsigned int day = 1;
    unsigned int month = 1;
    unsigned int year = 2023;
};

The DateSelectorState is the complex state of a DateSelector property. It carries a date definition.

Data member:

day - The day of the selector.

month - The month of the selector.

year - The year of the selector.

UnlockControlState

  		
class UnlockControlState {
public:
    UnlockControlState();
    UnlockControlState(const UnlockControlState& state);
    
    bool unlocked = false;
    unsigned int mode = 0;
    String pin = "not set";
};

The UnlockControlState is the complex state of an UnlockControl property. It carries the locked state, the current mode and the used pin.

Data member:

unlocked - The current unlocked state: true if unlocked, false if locked.

mode - The current mode of the tranmission. This parameter is only used in a transmission from app to device. The UnlockControlModes can be used to determine the tranmission mode.

pin - The pin to unlock or pin-change. Is not used in some transmissions, for example a lock command.

NavigatorState

  		
class NavigatorState {
public:
    NavigatorState();
    NavigatorState(const NavigatorState& state);

    unsigned int buttonType = NavigatorButtonTypes::NO_BUTTON;
    unsigned int actionType = NavigatorActionTypes::NAT_UNUSED;

    void setButtonVisibility(bool up, bool right, bool down, bool left, bool mid);
};

The NavigatorState is the complex state of a NavigatorControl property. It carries button states for execution commands.

Data member:

buttonType - This parameter is only used in an execution command from app to device. It determins the type of button that is pressed. Type NavigatorButtonTypes

actionType - This parameter is only used in an execution command from app to device. It determins the action that is executed on the button defined in buttonType. Type NavigatorActionTypes

Methods:

setButtonVisibility - Can be used to set the visibility of the buttons in a Navigator property.

BarGraphState

  		
class BarGraphState {
public:
    BarGraphState();
    BarGraphState(const BarGraphState& state);

    void addBar(const BarData& bData);
    void addBar(const char* barName, float barValue);
    
    void removeBarAt(unsigned int index);
    
    void changeBarValueAt(unsigned int index, float newValue);
    void changeBarDataAt(unsigned int index, const BarData& bd);
    
    BarData getBarDataAt(unsigned int index);

    bool useValueAsBarDescriptor = false;
    bool useFixedMaximumValue = false;
    float fixedMaximumValue = 0;
};

The BarGraphState is the complex state of a BarGraph property. It carries the bar data and configuration values for the appearance and the behaviour of the BarGraph. An example on how to add data for a bar in the BarGraph is provided on the BarData docu site.

Data member:

useValueAsBarDescriptor - If the value is true, the current value of the bar is displayed beneath the bar. In this case no bar-descriptors should be defined, since they would be overwritten.

useFixedMaximumValue - If this value is true, the grid of the BarGraph is fixed. If not, the grid will be adapted to the bar data, everytime the bar-data is set.

fixedMaximumValue - If the useFixedMaximumValue parameter is true, this is the value to define the upper limit of the grid. If the useFixedMaximumValue parameter is false, this value is ignored.

Methods:

addBar - Add a bar to the BarGraph. A bar is defined with the BarData class

removeBarAt - Remove a bar from the BarGraph at the specified index.

changeBarValueAt - Changes a bar value at the specified index.

changeBarDataAt - Changes a bar-data set at the specified index.

getBarDataAt - Returns a bar definition from the BarGraph at the specified index.

LineGraphState

  		
class LineGraphState {
public:
    LineGraphState();
    LineGraphState(const LineGraphState& state);

    bool drawGridLines = false;
    bool drawAxisValues = false;
    float xMinValue = -10;
    float xMaxValue = 10;
    float yMinValue = -10;
    float yMaxValue = 10;
    float xIntersection = 2;
    float yIntersection = 2;

    LineGraphDataPoints lineGraphPoints;
};

The LineGraphState is the complex state of a LineGraph property. It carries the line data and configuration values for the appearance and the behaviour of the LineGraph.

Data member:

drawGridLines - If this value is true, grid-lines will be drawn in the background based on the specified intersection.

drawAxisValues - If this value is true, the intersection values will be drawn at the axis.

xMinValue - The lower limit of the grid on the X axis.

xMaxValue - The upper limit of the grid on the X axis.

yMinValue - The lower limit of the grid on the Y axis.

yMaxValue - The upper limit of the grid on the Y axis.

xIntersection - The grid intersection on the X axis.

yIntersection - The grid intersection on the Y axis.

lineGraphPoints - The line-data of the LineGraph. Type: LineGraphDataPoints

StringInterrogatorState

  		
class StringInterrogatorState {
public:
    StringInterrogatorState();
    StringInterrogatorState(const StringInterrogatorState& state);
    
    bool fieldOneVisible = true;
    bool fieldTwoVisible = true;
    bool navigateBackOnButtonPress = true;
    bool acceptNonAsciiCharacters = false;
    
    StringInterrogatorFieldInputType fieldOneInputType =
    			StringInterrogatorFieldInputType::SI_INPUT_TEXT;
                
    StringInterrogatorFieldInputType fieldTwoInputType =
    			StringInterrogatorFieldInputType::SI_INPUT_TEXT;

    String buttonText;

    String fieldOneDescriptor;
    String fieldTwoDescriptor;
    String fieldOneHint;
    String fieldTwoHint;
    String fieldOneContent;
    String fieldTwoContent;
};

The StringInterrogatorState is the complex state of a StringInterrogator property. It carries data for the input fields and their properties.

Data member:

fieldOneVisible - Controls the visibility of the first input field.

fieldTwoVisible - Controls the visibility of the second input field.

navigateBackOnButtonPress - Determins if an automatic back navigation occurs when the user has pressed the confirm button. Default value is 'true'.

acceptNonAsciiCharacters - Determins if the input field should accept non-ascii characters. If this is true, the entered non-ascii characters are escaped with a unicode escape sequence when the content is transmitted to the device. If this is false, an invalid input warning will be displayed to the user and the confirm button will not work as long as the input is invalid.

fieldOneInputType - The type of data the user can enter in field one. Type: StringInterrogatorFieldInputType

fieldTwoInputType - The type of data the user can enter in field two. Type: StringInterrogatorFieldInputType

buttonText - The text of the confirm button.

fieldOneDescriptor - The descriptor for the first input field, this is the purpose of the entered data.

fieldTwoDescriptor - The descriptor for the second input field, this is the purpose of the entered data.

fieldOneHint - The hint that is displayed in the first input field if there is no content in it.

fieldTwoHint - The hint that is displayed in the second input field if there is no content in it.

fieldOneContent - The content that is set in the first input field.

fieldTwoContent - The content that is set in the second input field.

TextListPresenterState

  		
class TextListPresenterState {
public:
    TextListPresenterState();
    TextListPresenterState(const TextListPresenterState& state);
    
    bool useBackgroundStack = true;
};

The TextListPresenterState is the complex state of a TextListPresenter property. It carries control parameter.

Data member:

useBackgroundStack - If this is true, the transmitted elements for the TextListPresenter are saved in a background-stack even if the respective property page is not open.