UIFactory Class Reference
[QtBaseModule]

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.