Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

UIFactory Class Reference
[QtBaseModule]

The UIFactory class provides a factory for various types of widgets used within the Qt Extended server. More...

    #include <UIFactory>

• List of all members, including inherited members

Static Public Members

• QDialog * createDialog ( const QByteArray & dialogClassName, QWidget * parent = 0, Qt::WFlags f = 0 )
• QWidget * createWidget ( const QByteArray & widgetClassName, QWidget * parent = 0, Qt::WFlags fl = 0 )
• bool isAvailable ( const QByteArray & widgetClassName )

Macros

• UIFACTORY_REGISTER_WIDGET ( ClassName )

Detailed Description

The UIFactory class provides a factory for various types of widgets used within the Qt Extended server.

If a widget registers itself via UIFACTORY_REGISTER_WIDGET() an instance of that widget can be obtained via the UIFactory. The caller only refers to the class via its name without having to include the actual class definition for that widget. Thus by using this factory dependencies between various widget components within the server are reduced.

UIFactory vs. Qt Extended Server Widgets

The decision whether to use the UIFactory or the Qt Extended Server Widget mechanism depends on the use case. In general if UI components require extensive interfaces Qt Extended Server Widgets should be used. The following table gives a brief overview of the advantages and disadvantages of each concept:

How to use UIFactory

The subsequent example defines and registers the new ExampleLabel widget.

    //in examplelabel.cpp
    class ExampleLabel : public QWidget
    {
        Q_OBJECT
    public:
        ExampleLabel( QWidget *parent = 0, Qt::WFlags fl = 0) {}
    };

    UIFACTORY_REGISTER_WIDGET( ExampleLabel );

Note that a widget must use the Q_OBJECT macro in order to be accessable via the UIFactory.

    //in exampleuser.cpp
    void ExampleUser::showExampleLabel()
    {
        QWidget *label = UIFactory::createWidget( "ExampleLabel", this, 0 );
        if ( label ) {
            label->show();
        }
    }

The caller accesses ExampleLabel via the interface provided by QWidget. Widgets such as ExampleLabel are usually delivered as part of a server component. If the component that provides ExampleLabel is not deployed as part of the server widget() returns a NULL pointer. Therefore it is always required to check the returned widget pointer for validity and it is the callers responsibility to handle the case of a non-existing ExampleLabel component.

Advanced usage

In some circumstances it may be required to access some additional methods or properties provided by a widget. A typical example would be a dialog that returns a more sophisticated error code than the integer value returned by QDialog::exec(). Nevertheless the caller would like to avoid having to include the dialog declaration.

The following SampleDialog demonstrates such an example. Usually SampleDialog::errorCode() would not be accessable via the QDialog interface.

    //in sampledialog.cpp
    class SampleDialog : public QDialog
    {
        Q_OBJECT
    public:
        SampleDialog( QWidget *parent = 0, Qt::WFlags fl = 0) {}

        QString notCallableMethod;
        Q_INVOKABLE QString errorCode();

    public slots:
        void setParamter( bool param1, int param2 );
    };
    //class definition for SampleDialog
    ...
    UIFACTORY_REGISTER_WIDGET( SampleDialog );

The following code demonstrates how other code can access SampleDialog methods via Qt's Meta-Object System.

    //in dialoguser.cpp
    void DialogUser::showSampleDialog()
    {
        QDialog *dlg = UIFactory::createDialog( "SampleDialog" );
        if ( dlg ) {
            QMetaObject::invokeMethod( dlg, "setParameter",
                    Qt::DirectConnection, Q_ARG(bool,true), Q_ARG(int,10) )
            QtopiaApplication::execDialog( dlg );

            QSlotInvoker returnCode( dlg, SLOT(errorCode()), 0 );
            QList<QVariant> args;
            QString returnString = returnCode->invoke( args ).toString();
            ...
        } else {
            qWarning("SampleDialog not available");
        }
    }

The meta system allows the invocation of slots or invokable methods via QMetaObject::invokeMethod(). QSlotInvoker is a convenience class with the same purpose. Its main difference is that the user doesn't need to know the exact type of the arguments. In general QMetaObject::invokeMethod() should be prefered over QSlotInvoker.

The only limitation of using Qt's meta system is that only slots and methods marked with the Q_INVOKABLE macros can be invoked via the meta system. In the case of the above SampleDialog only SampleDialog::errorCode() and SampleDialog::setParameter() can be invoked but not SampleDialog::notCallableMethod().

Note that accessing of slots and methods via Qt's Meta-Object System should only be used in limited cases. This approach is very error prone because programming error may only be discovered at runtime (and not at compile time). As soon as widgets are required that expose more sophisticated interfaces abstract server widgets should be considered.

See also QSlotInvoker and QtopiaApplication.

Member Function Documentation

QDialog * UIFactory::createDialog ( const QByteArray & dialogClassName, QWidget * parent = 0, Qt::WFlags f = 0 )   [static]

Returns a pointer to a new instance of dialogClassName. If no dialog with that name has been registered this function returns 0. The returned dialog is a child of parent, with widget flags set to f.

Each call to this function will create a new instance of dialogClassName. It is the callers responsibility to manage the life cycle of the returned dialog.

QWidget * UIFactory::createWidget ( const QByteArray & widgetClassName, QWidget * parent = 0, Qt::WFlags fl = 0 )   [static]

Returns a pointer to a new instance of widgetClassName. If no widget with that name has been registered this function returns 0. The returned widget is a child of parent, with widget flags set to fl.

Each call to this function will create a new instance of widgetClassName. It is the callers responsibility to manage the life cycle of the returned widget.

bool UIFactory::isAvailable ( const QByteArray & widgetClassName )   [static]

Returns true if widgetClassName is registered/available as a component that can be created via the UIFactory; otherwise false.

This function may be used to discover available widgets components at runtime and implement fall-back strategies if a particular widget is not available. Note that the list of widgets/components is created at static construction time. Therefore this function does not return reliable data before main() has been entered.

Macro Documentation

UIFACTORY_REGISTER_WIDGET ( ClassName )

Registers the widget ClassName so that other parts of the server can utilize the widget. The advantage of this macro is the fact that the user of ClassName must not include the class declaration for ClassName.