Porting Applications to KDE 3.0

This document contains the changes you have to apply to programs written for KDE 2.x when you want to port them to KDE 3.0.

As a start you should have a look at doc/porting.doc in the Qt package, or this page online.

Table of Contents

Getting started

The first step to get your KDE application to compile under KDE 3.0, is to detect KDE 3.0 and Qt 3.x at configure time. The easiest way to get a working autoconf/automake framework, is to either use KDevelop or kapptemplate (available in CVS under the module "kdesdk"), to generate a new application template. Replace the generated source files by yours and adapt Makefile.am accordingly.

Please note that we tried to be mostly source-compatible where it was possible. To accomplish that, we added commonly used but still deprecated / removed API parts in a #ifndef KDE_NO_COMPAT-block. That means you can "test" and adjust your application by #defining KDE_NO_COMPAT for compiling and see where it breaks. This is recommended, as those backward compatibility "hacks" are not kept for long.

WARNING:In some cases the names or signatures of signals or slots have changed. Check your source carefully for this since these changes will not be discovered by your compiler but will result in incorrect runtime behaviour if left uncorrected in your application.

Return to the Table of Contents

Changes in kab

AddressBook

The getStandardFilename() method has been renamed to getStandardFileName(). The old name will still work unless KDE_NO_COMPAT is defined.

Return to the Table of Contents

Changes in kdecore

KDesktopWidget

KDesktopWidget is obsolete. Include <qdesktopwidget.h> and use QDesktopWidget instead, everything else is source compatible.

Header file names

This is to help finding out header files from class names and the other way round. Compatibility headers have been created. You can use them as long as you don't compile with KDE_NO_COMPAT.

DCOP

The file with the DCOP connection information has been renamed. The new name is $HOME/.DCOPserver__. The screen part has been stripped from and the ':' character that separates host and display-number has been replaced with a '_'. If you access DCOP via DCOPClient you do not need to change anything.

It is no longer possible to make calls to an application registered as "-" with "" only. The full name can be obtained by using either KApplication::startServiceBy...() or DCOPClient::findObject() or their command line equivalents "dcopstart" and "dcopfind".

KLibFactory

KLibFactory's create method is no more virtual and the createObject method is now pure virtual. The former was marked as deprecated since KDE 2.0. All it takes in your component is to rename your existing create implementation to createObject and remove the 'emit objectCreated( yourObject );' line.

KDesktopFile

The filename() method has been renamed to fileName(). The old name will still work unless KDE_NO_COMPAT is defined.

KPixmapSplitter

KPixmapSplitter has now been moved to the new kdefx library.

KStringHandler

The matchFilename( const QString& filename, const QString& pattern ) method has been renamed to
matchFileName( const QString& filename, const QString& pattern ). The old name will still work unless KDE_NO_COMPAT is defined.

KStyle

Due to the major changes in the QStyle API in Qt3, KStyle has been completely re-written. KStyle is now a thin wrapper around QCommonStyle with a few extra primitive elements and a simple popupMenu transparency engine. All KStyles can now style Qt apps like designer and assistant automatically. KStyle is no longer present in kdecore. It is now in a new library called kdefx to allow Qt apps to use KDE's styles without having the styles linked to kdecore/kdeui.

KURL

The filename( bool _ignore_trailing_slash_in_path = true ) method has been renamed to
fileName( bool _ignore_trailing_slash_in_path = true ). The old name will still work unless KDE_NO_COMPAT is defined.

KMD5

HASHHEX and HASH has been removed to make this class namespace clean. They have been replaced by QCString and KMD5::Digest.
The API has been cleaned up, it is no longer necessary to call finalize(). Simply remove any calls to it.

KLocale

  • charset() has been removed. You might want to use encoding() instead.
  • setCharset(const QString &) has been removed. You might want to use setEncoding(int) instead.
  • formatMoney(const QString &) has been removed.
  • formatNumber(const QString &) has been removed.
  • languages() has been removed. Use languageList() instead.

    Accelerators Keys

    KAccel
    The following methods of been deprecated, and if KDE_NO_COMPAT is defined they will not be available.
    • KAccel::insertItem() and KAccel::connectItem(). 
      	- kaccel->insertItem( i18n("Scroll Up"), "Scroll Up", "Up" );
	- kaccel->connectItem( "Scroll Up", this, SLOT(scrollUp()) );
	+ kaccel->insert( "Scroll Up", i18n("Scroll Up"), QString::null,
		Key_Up, this, SLOT(scrollUp()) );
      Note that a What's This parameter is now a part of the insert function. You might replace the QString::null paramter with 
       i18n("Scroll the current document's contents up by one line.")
      for example.
    • KAccel::changeMenuAccel() has been depricated because it was never used in cvs. If you've used it in your application, the following can replace it. Note, however, that this would be handled automatically by using KAction instead. 
      	- kaccel->changeMenuAccel( menu, id, "file_open" );
	+ menu->setAccel( kaccel->shortcut( "file_open" ).keyCodeQt(), id );
    The preferred means of defining a shortcut, however, is to use KAction. 
    	new KAction( i18n("Scroll Up"), Key_Up,
		this, SLOT(scrollUp()), actionCollection(), "Scroll Up" );
    KGlobalAccel
    • Call updateConnections() after all insert() or insertItem() (depricated) calls have been made. This function then performs the actually key grabbing. In order to improve program startup speed, grabbing is no longer done automatically: usually readSettings() is called after the actions have been defined, and this may cause shortcut reassignments, which in turn used to make an expensive ungrab of the old key and second grab of the new key necessary.
    KStdAccel
    • StdAccel::WhatThis has been renamed to StdAccel::WhatsThis.
    • StdAccel::Insert and the corresponding insert() have been removed. (Nobody on the list knew what its function was supposed to be.) Calls to insert() and the equivalent key(KStdAccel::Insert) can be replaced with the former default of Qt::CTRL+Qt::Key_Insert.
    • The following functions have been depricated and will need to be changed if KDE_NO_COMPAT is defined:
      OldNew
      QString action(StdAccel id)QString name(StdAccel id)
      int defaultKey(StdAccel accel)KShortcut shortcutDefault(StdAccel id)
      QString description(StdAccel id)QString label(StdAccel id)
      bool isEqual(const QKeyEvent* pEvent, int keyQt) The best method for replacing this varies. One possibility is to use KKey(const QKeyEvent*) == KKey(int). Another is to use KShortcut::contains( const KKey&/KKeySequence& ).
      int key(StdAccel)const KShortcut& shortcut(StdAccel)

    KIconLoader, KIconTheme

    Methods now use KIcon::Group and KIcon::Context instead of int as types for group and context arguments. The change should affect only code using hardcoded numeric values instead of using the proper enum constants. This applies to classes KIconLoader, KIconTheme and (in kio and kfile) KMimeType, KService, KIconDialog, KIconButton, KURLBar and KURLBarItem.

    Return to the Table of Contents

    Changes in kdeui

    KAccelMenu

    This class has been removed, Qt offers the same functionality. Use QPopupMenu/KPopupMenu or the XML-UI method for building menus.

    KAction

    • The following methods have been depricated and will need to be replaced if KDE_NO_COMPAT is defined.
      OldNew
      int accel()const KShortcut& shortcut()
      int menuId()int itemId()
      void setAccel(int)void setShortcut(const KShortcut&)

    KActionCollection

    • When constructing a KActionCollection object, a pointer to the focus widget should be passed.
    • The insert(), remove(), and take() methods have been depricated. If you wish to keep a list of actions, use the KActionPtrList container instead. If you want to configure the shortcuts from multiple actions collections, pass each collection to KKeyChooser or KKeyDialog via their insert() methods.

    KAlphaPainter

    KAlphaPainter has been dropped, since Qt 3 has native support for hardware accelerated alpha blending.

    KAnimWidget

    This class no longer supports reading a list of images, instead it uses a single image-file that has been prepared with the kimage_concat tool. See kdelibs/pics/hicolor/kde for an example of its use.

    KContainerLayout

    This class has been removed, use Qt layouts instead.

    KCommand

    This class has been made lighter: the name isn't stored into the command anymore, but must be provided by the inherited class, as the result of the virtual name() function. This saves storing a QString into each command in memory. The former behavior is available in the class KNamedCommand, so for a quick port simply replace KCommand with KNamedCommand.

    KDialogBase

    The deprecated getMainWidget() method has been removed. Use mainWidget() instead.

    KDirectionButton

    ...is gone. Use KArrowButton instead, it offers about the same functionality.

    KDockWidget

    The WidgetList parameter has been renamed to QWidgetList. Behaviour is identical.

    KEdit

    KEdit is now deprecated. You should use use KTextEditor::Editor or QTextEdit instead.

    KImageEffect

    KImageEffect has now been moved to the new kdefx library.

    KMessageBox

    KMessageBox now does automatic line-breaking. When using plain-text, you should remove any mid-sentence linebreaks. Only use line-breaks to indicate the end of a paragraph.

    KPanelApplet

    A new protected member method 'void reportBug()' was added. It gets called by Kicker if the 'Report Bug' entry in the context menu gets selected and should be overridden by applets which support the KPanelApplet::ReportBug action. This means that you don't have to extend KPanelApplet's generic action dispatcher void KPanelApplet::action() anymore.

    KPanelMenu

    The old KPanelMenu class has been renamed to KPanelAppMenu. The KPanelMenu class now corresponds to a new Kicker menu extension that is handled by the panel in a way similar to other applets (shared library loaded at run-time). See KDE 3.0 documentation for more informations on this new extension.

    KPixmapEffect

    PixmapEffect has now been moved to the new kdefx library.

    KProgress

    KProgress is now based on QProgressBar. This has led to a few API changes. In particular the constructors have been simplified, you simply need to pass the total number of steps instead of min / max / initialvalue / orientation. See documentation of both KProgress and QProgressBar.

    KRootPixmap

    The KRootPixmap class has been extended to make it more flexible, and the checkAvailable(bool ignored) method has been renamed to isAvailable(). The old name will still work unless KDE_NO_COMPAT is defined.

    KThemeBase, KThemeStyle

    KThemeBase and KThemeStyle have been ported over to the new QStyle/KStyle API present in Qt3/KDE3. KThemeBase is no longer in kdeui, but in kstyles/kthemestyle as its use is basically limited to KThemeStyle.

    KAction, KToolBar, KToolBarButton and icons

    The prefered way for specifying icons is passing the icon names (and the icons will be loaded by KIconLoader), instead of using QIconSet or QPixmap. This results in always using the correct icon size and allows delayed on-demand icon loading.

    Method KAction::hasIconSet() has been renamed to KAction::hasIcon(), the old name will still work unless KDE_NO_COMPAT is defined. KAction::iconSet() now has an argument specifying icon group, the old KAction::iconSet() is still available unless KDE_NO_COMPAT is defined and returns KIcon::Small iconset, just like in KDE2.

    KToolBarButton methods setPixmap(), setDefaultPixmap(), setDisabledPixmap(), setDefaultIcon() and setDisabledIcon() are deprecated. Use KToolBarButton::setIcon() (prefered) or KToolBarButton::setIconSet() instead.

    KAction and derived classes

    The protected set* methods have been renamed to update* and they now take only one argument (i.e. setText(int, const QString&) is now updateText(int) ). Because the former second argument was always the value of the a corresponding data member, you can simply call the accessor method (i.e. in updateText() call text() to get the text).

    KToggleAction

    exclusiveGroup() is no more virtual. setExclusiveGroup(const QString&) is not a slot anymore.

    Return to the Table of Contents

    Changes in kio

    KPropertiesDialog

    • The header file has been renamed from kpropsdlg.h to kpropertiesdialog.h.
    • KPropertiesDialog::KPropertiesDialog(const KURL&, mode_t, QWidget*, const char*, bool, bool ) has been removed since mode_t was no longer used. Simply omit the mode_t parameter.

    KTarGz/KTarBase/KTarData

    • The KTarBase and KTarData classes have been removed.
    • KTarGz is now KTar (#define for source compatibility)
    • A base class KArchive has been written, to support other archive formats in the future
    • KTarEntry is now KArchiveEntry, KTarDirectory is now KArchiveDirectory, and KTarFile is now KArchiveFile.
    • The classes ProgressBase, StatusbarProgress and DefaultProgress have been moved to the KIO namespace.
    • The signal KDirLister::started(const QString &url) has changed to KDirLister::started(const KURL &url).
    • KServiceTypeProfile::preferredService( const QString & serviceType, bool needApp ) has been removed, use KServiceTypeProfile::preferredService( ..., "Application") if needApp was true, or KServiceTypeProfile::preferredService( ..., QString::null) if needApp was false.
    • The following functions in KProtocolManager have been replaced:
      • ftpProxy(), use proxyFor("ftp") instead.
      • httpProxy(), use proxyFor("http") instead.
      • slaveProtocol(const QString&), use slaveProtocol(const KURL &url, QString &proxy) instead.
      • defaultReadTimeout(), use DEFAULT_READ_TIMEOUT instead. (See ioslave_defaults.h)
      • defaultProxyConnectTimeout(), use DEFAULT_PROXY_CONNECT_TIMEOUT instead. (See ioslave_defaults.h)
      • defaultResponseTimeout(), use DEFAULT_RESPONSE_TIMEOUT instead. (See ioslave_defaults.h)
      • minimumTimeoutThreshold(), use MIN_TIMEOUT_VALUE instead. (See ioslave_defaults.h)
    • The following functions in KProtocolManager have been removed:
      • setUserAgentList( const QStringList& )
      • userAgentList();
      • setReadTimeout()
      • setConnectTimeout( int )
      • setProxyConnectTimeout( int )
      • setResponseTimeout( int )
      • setMarkPartial( bool )
      • setMinimumKeepSize( int )
      • setAutoResume( bool )
      • setPersistentConnections( bool )
      • setMaxCacheAge( int )
      • setUseCache( bool )
      • setMaxCacheSize( int )
      • setCacheControl( KIO::CacheControl )
      • setUseProxy( bool )
      • setUseReverseProxy( bool )
      • setProxyType( ProxyType )
      • setProxyAuthMode( ProxyAuthMode )
      • setFtpProxy( const QString& )
      • setHttpProxy( const QString& )
      • setProxyFor( const QString&, const QString& )
      • setNoProxyFor( const QString& )
      • setProxyConfigScript( const QString& )
    • In order to support files > 4Gb, the file size / file-offset argument in the signals totalSize, processedSize and canResume, which are used by the io-slaves and passed along to jobs, has been changed from unsigned long to KIO::filesize_t. Make sure to check if you use these signals since your compiler will typically not generate a compile-time error for these changes, instead you might get a run-time error when you try to connect to one of these signals using the old signature.

    KOpenWithHandler / KFileOpenWithHandler

    Those two classes are deprecated, no need to create a KFileOpenWithHandler anymore. The merging of libkio, libksycoca, libkfile and libkssl into a single libkio has allowed to fix this dependency problem: KRun can now use the OpenWith dialog directly.

    KMimeType, KService

    Methods now use KIcon::Group and KIcon::Context instead of int as types for group and context arguments. The change should affect only code using hardcoded numeric values instead of using the proper enum constants.

    KFilterDev

    The createFilterDevice method is deprecated. Use deviceForFile instead.

    KDirWatch

    • The signal fileDirty( const QString& ) has been removed
    • The signal created( const QString& ) has been added
    • The signal deleted( const QString& ) has been added
    • The signal dirty( const QString& ) may be emitted with a file name, not only a directory name. This depends on which backend is used but will probably always be the case in KDE 3.1. You should prepare to receive dirty( dirname ) or dirty( filename ) when a file has changed.

    Return to the Table of Contents

    Changes in kparts

    KParts::Factory

    The createPart method is no more virtual and the createPartObject method is now pure virtual. The former was marked as deprecated since KDE 2.0. All it takes in your component is to rename your existing createPart implementation to createPartObject and remove the 'emit objectCreated( yourObject );' line.

    KParts::Part

    The bool isSelectable() const is no more virtual. So when you want to change the behavior of the selectable property you don't need to re-implement both virtual functions, setSelectable and isSelectable, but instead just re-implementing setSelectable does the job. The very same applies for the KURL url() const and ReadWritePart's bool isReadWrite const and bool isModified() const methods.

    The void showProgressInfo(bool) method has been renamed to bool setProgressInfoEnabled(bool). The old name will still work unless KDE_NO_COMPAT is defined.

    KParts::BrowserExtension

    The URLArgs urlArgs() method is no more virtual. So when you want to change the behavior of the urlArgs property you don't need to re-implement both virtual functions, setURLArgs and urlArgs, but instead just re-implementing setURLArgs does the job.

    Return to the Table of Contents

    Changes in kspell

    KSpell

    The API has been cleaned up to be in line with the rest of kdelibs, in particular:
    • suggestions() now returns a QStringList instead of a pointer to a QStringList
    • intermediateBuffer() now returns a QString instead of a pointer to a QString
    • The signal misspelling(QString, QStringList *, unsigned) has changed to misspelling(const QString &, const QStringList &, unsigned int)
    • The signal corrected(QString, QString, unsigned) has changed to corrected(const QString &, const QString &, unsigned int)
    • The signal ignoreall(QString) has changed to ignoreall(const QString &)
    • The signal ignoreword(QString) has changed to ignoreword(const QString &)
    • The signal addword(QString) has changed to addword(const QString &)
    Make sure to check if you use the above signals since your compiler will typically not generate a compile-time error for these changes, instead you might get a run-time error when you try to connect to one of these signals using the old signature.

    Return to the Table of Contents

    API-cleanups in KHTML

    There were a few relatively minor API-adjustements in KHTMLPart. In particular:
    • enableJScript(bool) has been replaced by setJScriptEnabled(bool)
    • enableJava(bool) has been replaced by setJavaEnabled(bool)
    • enablePlugins(bool) has been replaced by setPluginsEnabled(bool)
    • autoloadImages(bool) has been replaced by setAutoloadImages(bool)
    • enableMetaRefresh(bool) has been replaced by setMetaRefreshEnabled(bool)
    • setBaseURL and setBaseTarget have been removed. baseURL(), baseTarget() and completeURL() are remained for compatibility reasons, but they're deprecated now. use the variants in DOM::HTMLDocument() instead.
    • the second parameter of KHTMLPart::completeURL is removed. it didn't have any effect before either.
    Besides that, all methods previously marked as deprecated or were internal but accidentally part of the public API are now private or removed. As they were marked as becoming private already you should not experience any problems. Backward compatibility exists for the common methods, to disable this use a #define KDE_NO_COMPAT.

    In KHTMLView, the following changes were done:

    • gotoNextLink has been replaced by gotoLink(true);
    • gotoPrevLink has been replaced by gotoLink(false);

    Return to the Table of Contents

    Changes in kfile

    The kfile-library, as used by the KFileDialog provides classes for directory browsing widgets. Those classes gained some new features, some parts were merged with other existing classes and in some cases the API was cleaned up/fixed. The library is now built as part of libkio library (there's no need to modify Makefiles which use $LIB_KFILE instead of hardcoding -lkfile).

    Even if the list of changes is long, the affected code base should be relatively small, as most parts are rarely used outside of kfile.

    The changes are:

    KFileItem

    The KFileViewItem class is completely replaced with KFileItem from kio. All its functionality has been merged with its former base class KFileItem. Additionally, some of its methods have been modified:
    Old:New:
    access()permissionsString()
    date()timeString()
    setViewItem( const KFileView *view, const void *item )setExtraData( const void *key, void *value )
    pixmap()The parameterless method has been removed, use pixmap( int size, int state = 0 ) instead.

    KFileReader

    This class has been merged with KDirLister from kio.

    KDirOperator

    Old:New:
    saveConfig()writeConfig()
    setFileReader()setDirLister()
    fileReader()dirLister()
    activatedMenu( const KFileViewItem * )activatedMenu( const KFileItem *, const QPoint& pos )

    KFileDetailView

    The protected method setSortIndicator() has been removed, it's not needed anymore.

    KFileView

    This is the baseclass for all the views. It changed in many respects to allow for greater flexibility and efficiency.

    Sorting has changed radically. Previously, KFileView had protected methods QuickSort, compareItems() and mergeLists() to sort directory entries for displaying in the views. Now, KFileView does not do any sorting anymore. Instead, the view's (i.e. KIconView, KListView) sorting is utilized by letting its view-items provide a QString key() method. Therefore, KFileView offers the two methods
    • QString sortingKey( const QString& value, bool isDir, int sortSpec )
    • QString sortingKey( KIO::filesize_t value, bool isDir, int sortSpec )
    which the view-classes can use to generate the string for the key() method. The KFile::SortMode enum has been removed, as QDir::SortSpec is used entirely.

    Further changes:
    Old:New:
    not existantvirtual void readConfig( KConfig *, const QString& group = QString::null )
    not existantvoid writeConfig( KConfig *, const QString& group = QString::null)
    virtual void setCurrentItem( const QString& filename, KFileViewItem * )Replaced with the two methods below.
     void setCurrentItem( const QString& filename );
     virtual void setCurrentItem( const KFileViewItem * ) = 0;
    setOperator( QObject * )setParentView( KFileView * )
    virtual void insertSorted( KFileViewItem *, uint count )virtual void insertItem( KFileItem * )
    virtual void addItemList( const KFileViewItemList &list )not virtual anymore. Sufficient to reimplement insertItem()


    Three more pure virtual methods have been added:
    • virtual KFileItem * firstFileItem() const = 0
    • virtual KFileItem * nextItem( const KFileItem * ) const = 0
    • virtual KFileItem * prevItem( const KFileItem * ) const = 0

    State-changes are now signaled solely via the KFileViewSignaler object, that every KFileView has a protected member of ("sig"). The methods activateMenu(), highlight() and select() have been removed. If you implemented a KFileView, change your code in the following way:
    Old:New:
    activateMenu( item )sig->activateMenu( item, pos )
    highlight( item )sig->highlightFile( item )
    select( item )sig->select( item )

    KFileViewSignaler

    The methods activateDir( const KFileViewItem * ) and activateFile( const KFileViewItem * ) have been merged into the new method activate( const KFileItem * ).

    Carsten Pfeiffer pfeiffer@kde.org

    KIconDialog, KIconButton, KURLBar, KURLBarItem

    Methods now use KIcon::Group and KIcon::Context instead of int as types for group and context arguments. The change should affect only code using hardcoded numeric values instead of using the proper enum constants.

    Return to the Table of Contents

    Changes in KControl

    Modules that require root permission

    The meaning of the X-KDE-RootOnly flag in the .desktop files has changed. In KControl 2.0 a message was shown if the user did not press the "modify" button. With the additional flag X-KDE-HasReadOnlyMode it was possible to show a disabled version of the module instead of the message. The behavior was inconsistent and has been changed:
    • X-KDE-HasReadOnlyMode is not used anymore and is ignored by KControl > 2.0.
    • X-KDE-RootOnly does now show a disabled preview of the widget and a notification box.
    • If you want the old behavior back set X-KDE-IsHiddenByDefault along with X-KDE-RootOnly. Please note that this behavior is deprecated the sake of usability.
    For more details please consult the HOWTO file in the kcontrol directory.

    Return to the Table of Contents

    Panel Applets and Extensions

    The API for Kicker panel applets and extensions has changed. Panels can now be left/top, center, or right/bottom aligned, and applets and extensions may receive notification about a change in alignment.

    KPanelApplet

    The virtual methods orientationChange() and popupDirectionChange() are deprecated. Instead you should reimplement positionChange() and alignmentChange() to be notified of changes in the position and alignment of the panel on which your applet resides. In addition, the popupDirection() method and the Direction enum are deprecated. Instead you should use the position() method and Position enum. Applets that use the deprecated methods will still work with KDE 3, but may not compile or work with a future version.

    KPanelExtension

    There is a new method alignmentChange() that your extension should reimplement if it needs to know about changes in alignment.

    Return to the Table of Contents

    Dirk Mueller mueller@kde.org