Descriptor Callback

Description

The purpose of the Descriptor-Callback is to provide dynamic, language dependent text resources for properties and groups. When a descriptor for a specific element is required it is requested through the callback.

Usage

To use the callback, create a class which inherits from the IElementDescriptionCallback interface. 

  	
// define the callback for the descriptor resources
class DescriptionCallback : public IElementDescriptionCallback
{
    // ...
};

In this class the desired methods can be overwritten to implement an interface that provides the text resources for the requested elements. The override keyword should be used to make sure the syntax is correct and the respective method is overwritten. 

  	
// define the callback for the descriptor resources
class DescriptionCallback : public IElementDescriptionCallback
{
public:
    // this callback method is called every time when a description for a specific property is required
    void onPropertyDescriptionRequired(cID propertyID, const String &langID, String &description) override
    {
    	// check the langID for a specific language
        if (langID == "en")
        {
            if (propertyID == MY_PROPERTY_ONE)
            {
            	description = // provide english text for property 1
            }
            else if(propertyID == MY_PROPERTY_TWO)
            {
            	description = // provide english text for property 2
            }
			/* TODO: handle all properties */            
        }
        else if (langID == "de")
        {
            if (propertyID == MY_PROPERTY_ONE)
            {
            	description = // provide german text for property 1
            }
            else if(propertyID == MY_PROPERTY_TWO)
            {
            	description = // provide german text for property 2
            }
			/* TODO: handle all properties */            
        }
        /* TODO: implement more languages*/
        else
        {
            if (propertyID == MY_PROPERTY_ONE)
            {
            	description = // provide a default fallback language if the requested is not supported
            }
            else if(propertyID == MY_PROPERTY_TWO)
            {
            	description = // provide a default fallback language if the requested is not supported
            }
			/* TODO: handle all properties */                    
        }
    }

    // this callback method is called when a description for a specific group is required
    void onGroupDescriptionRequired(cID groupID, const String &langID, String &description) override
    {
        if (langID == "de")
        {
            if (groupID == MY_GROUP_ONE)
            {
                description = // provide german header text for group 1
            }
            else if(groupID == MY_GROUP_TWO)
            {
            	description = // provide german header text for group 2
            }
            /* TODO: handle all groups */
        }
        else // provide a default language if the requested is not supported
        {
            if (groupID == MY_GROUP_ONE)
            {
                description = // provide default language header text for group 1
            }
            else if(groupID == MY_GROUP_TWO)
            {
            	description = // provide default language header text for group 2
            }
            /* TODO: handle all groups */
        }
    }
};

Please note that when a property description is requested, the RAW descriptor is required. Some properties require special syntax for descriptors. More Info..

Finally, an instance of this class must be added to the LaRoomy Api to get notified of events. 

  	
void setup()
{
    // put your setup code here, to run once:
    
    /* other setup */
    
    // set the callback for description resources
    LaRoomyApi.setDescriptionCallback(
        dynamic_cast<IElementDescriptionCallback *>(
            new DescriptionCallback()));
    
    /* other setup */    
}

API Reference

This is a list of all available callback methods.

onPropertyDescriptionRequired

  		
virtual void onPropertyDescriptionRequired(
    cID propertyID,
    const String& langID, 
    String& description
);

When a descriptor for a property element is required, this method is called. This is the case when the app sends a property-request to the remote device. The 'description' parameter must be set depending on the language that is given in the 'langID' parameter for the property element that is identified through the 'propertyID' parameter.

Arguments:

propertyID - The ID for the property element for which a description was requested.

langID - The language identifier indicating the language the app is running in. This is a 2-letter code in ISO 639-1 format. More Info..

description - This is an out parameter, at the call of the method it is empty. When processing the method, this parameter must be filled with the correct descriptor for the requested element. Please note that here the raw descriptor is required. Some properties require special syntax. More Info..

onGroupDescriptionRequired

  		
virtual void onGroupDescriptionRequired(
    cID groupID, 
    const String& langID, 
    String& description
);

When a descriptor for a group is required, this method is called. This is the case when the app sends a group-request to the remote device. The 'description' parameter must be set depending on the language that is given in the 'langID' parameter for the group element that is identified through the 'groupID' parameter.

Arguments:

groupID - The ID for the group element for which a description was requested.

langID - The language identifier indicating the language the app is running in. This is a 2-letter code in ISO 639-1 format. More Info..

description - This is an out parameter, at the call of the method it is empty. When processing the method, this parameter must be filled with the correct descriptor for the requested element.