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

Porting to Qtopia 4

This page suplements the more general information for Porting Between Qtopia/Qt Extended Versions.

• Basic Conversions
• Qtopia 4 Headers
• Designer and UIC
• QProcess
• QMenu and QActionGroup
• QAction for Regular Menu Items
• QImage/QPixmap::smoothScale
• QStyle
• QCanvas
• QUuid
• Plug-ins
• Resource
• Config
• VScrollView
• grabKeyboard() and ungrabKeyboard()

Basic Conversions

If a previously used Qt function is not available and is not listed below or in the above documents, check if it is declared in the relevant header file, but within #ifdef QT3_SUPPORT bracketing.

If it is, check the in-line code for the function for the corresponding Qt 4 code.

For example:

QComboBox::setCurrentItem(int) is in Qt3_SUPPORT, but it is an in-line function that simply calls the renamed function, QComboBox::setCurrentIndex(int).

The table below lists the function conversions for porting to Qtopia 4.

Qtopia 4 Headers

Qtopia 4 has both classic (2.2-style) and Qt-style headers. The classic headers are provided to ease porting but you should consider switching to Qt-style headers to avoid dependency problems and because they will eventually be removed.

There are 2 ways to include Qt-style headers. You can use the class name (for public classes in public headers) or the header file name.

    #include <QAppointment>
    #include <qappointment.h>
    #include <private/vobject_p.h>

Note that the classic versions of these headers are.

    #include <qtopia/pim/qappointment.h>
    #include <qtopia/pim/private/vobject_p.h>

In cases where a header with the same name exists in 2 libraries you may need to prefix the library name.

    #include <qtopiapim/QAppointment>
    #include <qtopiapim/qappointment.h>
    #include <qtopiapim/private/vobject_p.h>

However, this should be avoided where possible because it can lead to dependency problems. If you include <QAppointment> but you have not declared your dependency on libqtopiapim (depends(libraries/qtopiapim)) you will get a compile error that will clearly identify the header <QAppointment> is unavailable. If you include <qtopiapim/QAppointment> you will get a linker or runtime error that may not indicate the problem in a clear way.

Designer and UIC

UIC can convert Qt 2/3 UI files to Qt 4, however, it generates code that uses Qt 3 support classes if the .ui file specifies either a class or a property on a class which is in the Qt 3 Support module.

For example, if QButtonGroup is used, it will generally convert trivially to QButtonGroup which is also in Qt 4, however, QButtonGroup in Qt 3 inherited QGroupBox which in turn inherited QFrame. So if the .ui file specifies QFrame properties on a QButtonGroup, then Qt 3 Support code will be generated.

To port .ui files:

• Run: uic3 -convert oldfile.ui >newfile.ui
• Edit/check newfile.ui - for example class names may have been lowercased MyDialog -> mydialog
• Remove use of Qt 3 support classes (look for "Q3"), and use Qt 4 classes as described above.

Note: converted .ui files contain an objectName property that matches the widget's name. While there may be a few cases where an objectName should be set, most cases are redundant and just take up space. You may choose to remove this property (in Designer or by editing the .ui file).

QProcess

QProcess is now subclassed from QIODevice, so instead of readStderr() and read|writeStdin() you access output as follows:

       myproc.setInputChannel( QProcess::StandardOutput );
       QTextStream procstream( myproc );
       procStream >> theResults;  // get into a string
       myproc.setInputChannel( QProcess::StandardError );
       procStream >> someError;

There is also readAllStandardError(), and to write to stdin, there are the QIODevice methods, such as myproc.write(<some text>).

The signal wroteToStdin() should be replaced by usage of QIODevice::bytesWritten(int).

QMenu and QActionGroup

Mutually exclusive checkable menu items are implemented with QActionGroup.

Note: addAction() is now a method of QWidget:

        QMenu* menu = new QMenu;
        menu->setCheckable( TRUE );
        QActionGroup *grp = new QActionGroup;
        for (int i = 0; i <= myLastItem; ++i )
        {
            items[i] = new QAction( QString( "option %1" ).arg( i ), grp );
            items[i]->setCheckable( TRUE );
        }
        items[myDefault]->setChecked( TRUE );
        menu->addActions( grp->actions() );

QAction for Regular Menu Items

In the past, you may have used something like the following to create regular menu items:

    a_settings = new QAction( tr("Settings..."),
                              theicon,
                              QString::null, 0, this, 0 );
    connect( a_settings, SIGNAL( activated() ),
             this, SLOT( doSettings() ) );
    a_settings->addTo( menu );

The new sequence looks like this:

    a_settings = new QAction( theicon,
                              tr("Settings..."), this );
    connect( a_settings, SIGNAL( triggered() ),
             this, SLOT( doSettings() ) );
    menu->addAction( a_settings );

Note: the transposition of the first two arguments to the QAction constructor, and the use of the triggered() slot rather than activated().

QImage/QPixmap::smoothScale

Qt 2 code:

        img = img.smoothScale( 5, 5 );

becomes:

        img.scale( 5, 5, Qt::KeepAspectRatio, Qt::SmoothTransformation );

QStyle

In tune with other parts of Qt, query and paint methods are now parameterized by enums instead of having specific names. Search the QStyle documentation for the name you want to query or paint, to find the enum and the method you need.

Qt 2 code:

    QRect r = style().pushButtonContentsRect( this );
    int sx, sy;
    style().getButtonShift(sx, sy);
    int dx = style().menuButtonIndicatorWidth( height() );
    style().drawArrow( p, DownArrow, FALSE, x+w-dx, y+2, dx-4, h-4,
             colorGroup(), isEnabled() );

becomes:

    QStyleOptionButton sob;
    sob.init( this );  // copies this->rect() and this->state, this's StyleFlags
    QRect r = style()->subRect( QStyle::SR_PushButtonContents, &sob );
    int sx = style()->pixelMetric( QStyle::PM_ButtonShiftHorizontal, &sob );
    int sy = style()->pixelMetric( QStyle::PM_ButtonShiftVertical, &sob );
    int dx = style()->pixelMetric( QStyle::PM_MenuButtonIndicator, &sob );
    QStyleOptionButton arrowStyle = sob;
    arrowStyle.rect.setLeft( sob.rect.right() - h) );  // a small square at RHS
    style()->drawPrimitive( QStyle::PE_IndicatorArrowDown, &arrowStyle, p );

QCanvas

There is no QCanvas in Qt 4 (it is in the unavailable Qt 3 Support module), but it is available in Qtopia 4 - instead of including qcanvas.h or Qt/qcanvas.h, use qtopia/canvas/qcanvas.h.

However, note that this class is intended to be obsoleted in Qtopia 4.2 by a new Qt class.

QUuid

QUuid is in Qt 4, so include Qt/quuid.h, not qtopia/quuid.h.

Plug-ins

Qtopia 4 uses the standard Qt 4 mechanisms for plug-ins.

The code below shows the pattern used for Qtopia plug-ins. Replace MyPlugin with the name of the type of plug-in you are writing,such as InputMethod. The pure virtual functions are those functions you want your plug-in to provide and the keys function should return the name of the plug-in implementation. For example, keys() would return Handwriting for the handwriting plug-in, or Handwriting, Fullscreen Handwriting if both plug-ins are provided).

    #include <qplugin.h>
    #include <qfactoryinterface.h>
    #include <qobject.h>

    struct QMyPluginFactoryInterface : public QFactoryInterface
    {
        // pure virtual functions
    };

    Q_DECLARE_INTERFACE(QMyPluginFactoryInterface, "http://trolltech.com/Qtopia/QMyPluginFactoryInterface")

    class QMyPluginPlugin : public QObject, public QMyPluginFactoryInterface
    {
        Q_OBJECT
        Q_INTERFACES(QMyPluginFactoryInterface:QFactoryInterface)
    public:
        QMyPluginPlugin(QObject *parent=0);
        ~QMyPluginPlugin();

        virtual QStringList keys() const = 0;
        // pure virtual functions
    };

Resource

Resources are now found using the Qt 4 QFileEngine mechanism, where in all places where a filename may be used, a special name starting with a colon (":") is used instead to refer to a resource. In Qt this is only used to refer to compiled-in resources, but in Qtopia, they may be actual files in predetermined places in the filesystem, that is, as Resource provided in Qtopia 2.

You can use scripts/porting-resources to automate the changes.

Config

Use QSettings instead.

Where Config files include translations (i.e. keys with []) and you need to read those keys, use QTranslatableSettings instead.

Rather than Config::setGroup(), you should use QSettings::beginGroup()..endGroup() spans.

Note:

• Config only used end-of-line for string termination.
• QSettings has different quoting rules. Where Config contains quotes ("), this should be considered.
• Config::isValid() was FALSE if the file did not yet exist, whereas QSettings::status() is TRUE.

You can use scripts/porting-config to automate the changes, however:

Note: clever use of Config::setGroup() can confuse that script.

The settings files are now stored in ~/Settings/Trolltech/ or $QPEDIR/etc/default/Trolltech/.

VScrollView

Use QScrollArea instead.

Keypad mode will work correctly provided you set the focus policy of QScrollArea to Qt::NoFocus.

For example:

        QScrollArea *sa = new QScrollArea(...);
        sa->setFocusPolicy(Qt::NoFocus);
        QWidget *view = new QWidget;
        sa->setWidget(view);
        sa->setWidgetResizable(true);
        // add children to view.

grabKeyboard() and ungrabKeyboard()

QtopiaApplication::grabKeyboard() and QtopiaApplication::ungrabKeyboard()

The documentation use to say:

    Grabs the physical keyboard keys, e.g. the application's launching
    keys. Instead of launching applications when these keys are pressed
    the signals emitted are sent to this application instead. Some games
    programs take over the launch keys in this way to make interaction
    easier.

    Under Qtopia Phone Edition this function does nothing. It is not
    possible to grab the keyboard under Qtopia Phone Edition.

Any calls to these methods can be safely removed. They did nothing since the PDA edition code was taken away when #ifdef QTOPIA_PHONE was removed.