ADTF CE Module

This guide explains how to enhance the functionality of the . If you need some custom dialogs to support special use cases you can wirte a UI plugin (*.adtfceplugin) which we call an ADTF CE Module. These modules consist of two parts:

  • A C++ library for the business logic and a
  • QML script for the graphical user interface.

  • Let's take properties of the type "file name" for example, as you can see when you select the ADTFDAT File Player in the Property Editor within the ADTF Configuration Editor. In previous versions of ADTF3 the user had to enter the file name into a plain text field. By writing an ADTF CE Module the handling of file name properties was improved. Now it is possible to open a file chooser and convert absolute paths to relative paths. To make the selected path work on different computers you can resolve parts like the drive name for example (the M Button in the screenshot).

    New editor for Filename and Filepath
    New editor for FilenameList

    The C++ Part

    First we need to define a C++ class that implements the functionality we want to provide inside the Configuration Editor. In this case we get the resulting class cFileListModel. In order to use the C++ class within our QML context we need to use some of Qt's predefined macros. To use functions from our C++ class within QML we have to prefix them with Q_INVOKABLE:

            
    Q_INVOKABLE void removeFile(const QString & strFilepath);
            
            

    Properties can be defined like this

            
    Q_PROPERTY(QObject* filenameHelper READ getFilenameHelper WRITE setFilenameHelper)
    
    Q_INVOKABLE QObject* getFilenameHelper();
    Q_INVOKABLE void setFilenameHelper(QObject* pFilenameHelper);
            
            

    It is possible to use any class of the ADTF SDK to extend the Configuration Editor with custom behaviour. But the code has to play nicely with the Qt meta type system. Have a look at the Qt coding guide lines here.

    A complete ADTF CE Module requires a C++ class that is derived from the Qt-Class QQmlExtensionPlugin. Inside this class we have to override the registerTypes() method in order to announce a new QML type which represents the C++ class that contains the business logic within the QML-Engine.

            
    void cCeDemoPlugin::registerTypes(const char* /*uri*/)
    {
        qmlRegisterType("FileListExample", 1, 0, "FileListModel");
    }
            
            

    This is all we have to do in C++. The complete code can be seen here.

    cFileListModel:

    cCeDemoPlugin:

    The QML part

    If we want to use a custom GUI-Extension within the ADTF Configuration Editor we need to implement it in a QML package. During start up the Configuration Editor looks for a specific file inside the QML package, the Main.qml. Within this file we register a custom property editor for a certain property type like this:

            
    import PropertyView 1.0
    Item
    {
        Component.onCompleted:
        {
            PropertyViewConfig.addEditor("cFilenameList", "qrc:/module/SimpleExample/FilenamesListEditor.qml");
        }
    }
            
            

    The PropertyViewConfig.addEditor function is a predefined function to register a new property editor.

    We can use the C++ class cFileListModel which we created and registered before inside the QML-Code like this:

            
    FileListModel
    {
        id: filelist
        filenameHelper: filenameHelper
    }
    
    TreeView
    {
        id: table
    
        Layout.fillHeight: true
        Layout.fillWidth: true
    
        model: filelist;
    
        .
        .
        .
    }
            
            

    The CMake part

    To build the *.adtfceplugin we need to create a CMakeLists.txt and open the resulting solution with Visual Studio. In order to use Qt we first need to locate the required packages. To do so we add the following lines to our script:

             
    # CMake basics
    cmake_minimum_required(VERSION 3.10.0)
    set(EXAMPLE_TARGETNAME ce_external_property_module_example)
    project(${EXAMPLE_TARGETNAME})
    
    # The ce_utils SDK package provides us the functionality to use the QML Interface of ADTF Configuration Editor 
    find_package(ADTF COMPONENTS ce_utils)
    
    # This macro will provide everything we need to create the adtfceplugin including required Qt dependencies. 
    # Important: We have to define a resource file (*.qrc) to store the logic within the binary
    # For detailed information please have a look at <ADTF_DIR>/pkg/adtfce_utils/adtfce_utils-macros.cmake
    adtf_add_ce_plugin(${EXAMPLE_TARGETNAME}
        ce_module_example_plugin.h 
        ce_module_example_plugin.cpp
        ce_module_example.h
        ce_module_example.cpp
        qml/module.qrc
    )
    
    # Qt must generate meta objects to provide signals and slots mechanism for inter-object communication
    # For more details please have a look at Qt's documentation
    adtf_enable_auto_moc(${EXAMPLE_TARGETNAME})
    
    # set our install fodler
    adtf_install_target(${EXAMPLE_TARGETNAME} src/examples/bin)
    
    # finally we have to enable Qt's Resource Compiler
    set_target_properties(${EXAMPLE_TARGETNAME} PROPERTIES
        FOLDER examples/adtf/ce_modules
        AUTORCC ON
    )
            
            

    The complete example can be found here

    Where to go next?

    You want to extract data from an .adtfdat recording ? No problem - the ADTF File Library provides a dat processing library to create own adtffileplugins. Let's have a look at ADTF DAT Tool Processer how to extract images from a video stream.