Properties of ADTF Components

This guide teaches you how to:

Property Variables

Property Variables are members of your Filter class and are linked to a Property. These members will always reflect the value of the assigned Property. Use the adtf::base::property_variable template to create Property Variables of the required type.

Implement a Filter that has Properties

Edit Properties in the ADTF Configuration Editor

After you have built this Filter you can add it by drag and drop from the Component View to a Filter Graph within the ADTF Configuration Editor. Select/click on the Filter let's you edit the Properties in the Property Editor:

Properties of our Filter in the Property Editor

React to Property Changes

If you need to react to Property changes within your ADTF Component, you can implement the IPropertyObserver interface or use property_variable<T>::SetPropertyChangedCallback(const std::function & fnCallback).

If you are interested in observing all property changes in one callback use IPropertyObserver:

If you are interested in observing a single property change you can use property_variable<T>::SetPropertyChangedCallback(...) since ADTF 3.7.0:

Adapt macro resolving

By default the ADTF Session Manager will resolve Macros in Property values before it sets them at the specific Service or Filter instances during session initialization. If you do not want that to happen (i.e. for resolving $(TIME) and friends while the session is running) you can use the adtf::base::property_variable::SetResolveMacros() function to disable automatic marco resolving. See property_variable_macros_filter.cpp:
        
#include <adtffiltersdk/adtf_filtersdk.h>

class cMacroFilter: public adtf::filter::cFilter
{
public:
    ADTF_CLASS_ID_NAME(cMacroFilter,
                       "property_variable_macros.filter.adtf_guides.cid",
                       "Property Variable Macro Filter");
public:
    cMacroFilter()
    {
        // mark this property such that marcos are not resolved during initialization.
        m_strLogString.SetResolveMacros(false);
        m_strLogString.SetDescription("Property which will be resolved manually.");
        RegisterPropertyVariable("log_string", m_strLogString);
        
        // provide a runner to trigger resolving
        CreateRunner("log_message");
        SetDescription("log_message", "Runner pin to trigger manual resolving.");

        // common description for the component
        SetDescription("This filter shows the usage of manual macro resolving for a given property.");
    }

    tResult Process(adtf::base::tNanoSeconds, adtf::streaming::IRunner*) override
    {
        // resolve macros manually each time.
        const auto strResolved = adtf::services::adtf_resolve_macros(m_strLogString->c_str());
        LOG_INFO("%s", strResolved.GetPtr());
        RETURN_NOERROR;
    }

private:
    adtf::base::property_variable<std::string> m_strLogString;
};

// The code behind the macro creates a plugin and the main entries to the plugin DLL or shared object.
// The cPropertyFilter will be available through the plugins class factory.
ADTF_PLUGIN("Property Variable Macro Filter Plugin",
            cMacroFilter);

        
      

Change Properties of ADTF Components while a Session is running

To change properties at runtime (after session has been launched), there exist several possibilities to adapt them:

  • ADTF Configuration Editor: If you are connected to the Launcher, the Properties view provides a remote view
  • ADTF Property Editor Tool: As connectable GUI tool using RPC to show and edit properties
  • Qt5 Property Editor UI Service: As embedded runtime widget within ADTF Qt5 XSystem Service with direct access
  • ADTF Control: As connectable CLI tool using RPC to get and set properties
  • Here is an short example how it works using our ADTF Control:

    Use and link graph properties

    Since ADTF 3.7.0 it is possible to create dynamic properties by implementing a Filter Editor and accessing the QML API from ADTF Configuration Editor, please have a look at ADTF Configuration Editor - Filter Editor. This is very useful by creating them based on some scripting metric, e.g. other property values, conditions, external files and more.

    Another possibility is adding them manually to an ADTF Component, which is possible within the Property Editor of ADTF Configuration Editor since ADTF 3.8.0. This works also for a whole ADTF Filter Graph and its graph properties are accessable when included as Subgraph. You can link those graph properties to existing properties of ADTF Components to let them parameterized from "outside" when including the ADTF Filter Graph as Subgraph (especially when we talk about ADTF Include Mechanism, see Session Editor).

    Let's have a look at a short example which includes a Subgraph that makes the display title property of the containing Qt5 Media Description Display accessable in the parent graph:

    Using graph properties

    Where to go next?

    Have a look at Generate Plugin Description to learn how to describe ADTF Components and generate this meta files.