diff options
Diffstat (limited to 'KDE3PORTING.html')
| -rw-r--r-- | KDE3PORTING.html | 672 |
1 files changed, 672 insertions, 0 deletions
diff --git a/KDE3PORTING.html b/KDE3PORTING.html new file mode 100644 index 000000000..416b6024b --- /dev/null +++ b/KDE3PORTING.html @@ -0,0 +1,672 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Level 2//EN//2.0"> +<HTML> +<HEAD> + <TITLE>Guide to Porting Applications to KDE 3.0</TITLE> +</HEAD> +<BODY> + +<H2>Porting Applications to KDE 3.0</H2> +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.<P> + +As a start you should have a look at doc/porting.doc in the Qt package, +or <a href="http://doc.trolltech.com/3.0/porting.html">this page online</a>.<P> + +<H3><A NAME="TOC">Table of Contents</A></H3> + +<UL> +<LI><A HREF="#gettingstarted">Getting Started</A></LI> +<LI><A HREF="#kab">Changes in kab</A></LI> +<LI><A HREF="#kdecore">Changes in kdecore</A></LI> +<LI><A HREF="#kdeui">Changes in kdeui</A></LI> +<LI><A HREF="#kio">Changes in kio</A></LI> +<LI><A HREF="#kparts">Changes in kparts</A></LI> +<LI><A HREF="#kspell">Changes in kspell</A></LI> +<LI><A HREF="#khtmlpart">API-cleanup in KHTML</A></LI> +<LI><A HREF="#kfile">Changes in kfile</A></LI> +<LI><A HREF="#kcontrol">KDE Control Center</A></LI> +<LI><A HREF="#kicker">Panel Applets and Extensions</A></LI> +</UL> + +<H3><A NAME="gettingstarted">Getting started</A></H3> + + 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 + <a href="http://www.kdevelop.org">KDevelop</a> or + <a href="http://home.earthlink.net/~granroth/kapptemplate/index.html">kapptemplate</a> + (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. +<p> + 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. +</p> +<p> + <b>WARNING:</b>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 + behavior if left uncorrected in your application. +</p> + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kab">Changes in kab</A></H3> + +<H4>AddressBook</H4> +The <i>getStandardFilename()</i> method has been renamed to <i>getStandardFileName()</i>. +The old name will still work unless KDE_NO_COMPAT is defined. + + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kdecore">Changes in kdecore</A></H3> + +<H4>KDesktopWidget</H4> +KDesktopWidget is obsolete. Include <qdesktopwidget.h> and use QDesktopWidget +instead, everything else is source compatible. + +<H4>Header file names</H4> +<UL> +<LI>kapp.h is now kapplication.h</LI> +<LI>kuniqueapp.h is now kuniqueapplication.h</LI> +<LI>kstddirs.h is now kstandarddirs.h</LI> +<LI>kcolorbtn.h is now kcolorbutton.h</LI> +<LI>kxmlgui.h is now kxmlguifactory.h</LI> +<LI>kdatepik.h is now kdatepicker.h</LI> +<LI>kdualcolorbtn.h is now kdualcolorbutton.h</LI> + +</UL> +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. + +<H4>DCOP</H4> +The file with the DCOP connection information has been renamed. The new +name is $HOME/.DCOPserver_<hostname>_<display>. The screen part has been +stripped from <display> 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. +<p> +It is no longer possible to make calls to an application registered as +"<appid>-<pid>" with "<appid>" only. The full name can be obtained by using +either KApplication::startServiceBy...() or DCOPClient::findObject() or +their command line equivalents "dcopstart" and "dcopfind". + +<H4>KLibFactory</H4> +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. + +<H4>KDesktopFile</H4> +The <i>filename()</i> method has been renamed to <i>fileName()</i>. +The old name will still work unless KDE_NO_COMPAT is defined. + +<H4>KPixmapSplitter</H4> +KPixmapSplitter has now been moved to the new kdefx library. + +<H4>KStringHandler</H4> +The <i>matchFilename( const QString& filename, const QString& pattern )</i> method has been +renamed to <br><i>matchFileName( const QString& filename, const QString& pattern )</i>. +The old name will still work unless KDE_NO_COMPAT is defined. + +<H4>KStyle</H4> +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. + +<H4>KURL</H4> +The <i>filename( bool _ignore_trailing_slash_in_path = true )</i> method has been +renamed to <br><i>fileName( bool _ignore_trailing_slash_in_path = true )</i>. +The old name will still work unless KDE_NO_COMPAT is defined. + +<H4>KMD5</H4> +HASHHEX and HASH has been removed to make this class namespace clean. +They have been replaced by QCString and KMD5::Digest. <br> +The API has been cleaned up, it is no longer necessary to call finalize(). +Simply remove any calls to it. + +<H4>KLocale</H4> +<li>charset() has been removed. You might want to use encoding() instead. +<li>setCharset(const QString &) has been removed. You might want to use +setEncoding(int) instead. +<li>formatMoney(const QString &) has been removed. +<li>formatNumber(const QString &) has been removed. +<li>languages() has been removed. Use languageList() instead. +<li>All references to monthName(), monthNamePossessive(), and weekDayName() +should be replaced with methods from KLocale::calendar(). +<li>Hard coded date handling or date handling with QDate should in most +cases be replaced by methods in KLocale::calendar(). + +<H4>Accelerators Keys</H4> +<h5>KAccel</h5> +The following methods of been deprecated, and if KDE_NO_COMPAT is defined they will +not be available. +<ul> + <li> KAccel::insertItem() and KAccel::connectItem(). +<pre> + - 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()) ); +</pre> + Note that a What's This parameter is now a part of the insert function. + You might replace the QString::null parameter with + <pre> i18n("Scroll the current document's contents up by one line.") </pre> + for example.</li> + <li> KAccel::changeMenuAccel() has been deprecated 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. +<pre> + - kaccel->changeMenuAccel( menu, id, "file_open" ); + + menu->setAccel( kaccel->shortcut( "file_open" ).keyCodeQt(), id ); +</pre> + </li> +</ul> +The preferred means of defining a shortcut, however, is to use <b>KAction</b>. +<pre> + new KAction( i18n("Scroll Up"), Key_Up, + this, SLOT(scrollUp()), actionCollection(), "Scroll Up" ); +</pre> + +<h5>KGlobalAccel</h5> +<ul> + <li>Call <i>updateConnections()</i> after all <i>insert()</i> or + <i>insertItem()</i> (deprecated) 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 <i>readSettings()</i> + 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.</li> +</ul> +<h5>KStdAccel</h5> +<ul> + <li><i>StdAccel::WhatThis</i> has been renamed to <i>StdAccel::WhatsThis</i>. + <li><i>StdAccel::Insert</i> and the corresponding <i>insert()</i> + have been removed. (Nobody on the list knew what its function was + supposed to be.) Calls to <i>insert()</i> and the equivalent + <i>key(KStdAccel::Insert)</i> can be replaced with the former default + of <i>Qt::CTRL+Qt::Key_Insert</i>.</li> + <li>The following functions have been deprecated and will need to be changed if KDE_NO_COMPAT is defined: + <table border=1> + <tr><th>Old</th><th>New</th></tr> + <tr><td>QString action(StdAccel id)</td><td>QString name(StdAccel id)</td></tr> + <tr><td>int defaultKey(StdAccel accel)</td><td>KShortcut shortcutDefault(StdAccel id)</td></tr> + <tr><td>QString description(StdAccel id)</td><td>QString label(StdAccel id)</td></tr> + <tr><td>bool isEqual(const QKeyEvent* pEvent, int keyQt)</td> + <td>The best method for replacing this varies. One possibility is to use + <i>KKey(const QKeyEvent*) == KKey(int)</i>. Another is to use + <i>KShortcut::contains( const KKey&/KKeySequence& )</i>.</td></tr> + <tr><td>int key(StdAccel)</td><td>const KShortcut& shortcut(StdAccel)</td></tr> + </table></li--> +</ul> + +<H4>KIconLoader, KIconTheme</H4> +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. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kdeui">Changes in kdeui</A></H3> + +<H4>KAccelMenu</H4> +This class has been removed, Qt offers the same functionality. +Use QPopupMenu/KPopupMenu or the XML-UI method for building menus. + +<H4>KAction</H4> +<ul> + <li>The following methods have been deprecated and will need to be + replaced if KDE_NO_COMPAT is defined. + <table border=1> + <tr><th>Old</th><th>New</th></tr> + <tr><td>int accel()</td><td>const KShortcut& shortcut()</td></tr> + <tr><td>int menuId()</td><td>int itemId()</td></tr> + <tr><td>void setAccel(int)</td><td>void setShortcut(const KShortcut&)</td></tr> + </table></li> +</ul> + +<h4>KActionCollection</h4> +<ul> + <li>When constructing a KActionCollection object, a pointer to the focus widget should be passed.</li> + <li>The insert(), remove(), and take() methods have been deprecated. + 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.</li> +</ul> + +<H4>KAlphaPainter</H4> +KAlphaPainter has been dropped, since Qt 3 has native support for +hardware accelerated alpha blending. + +<H4>KAnimWidget</H4> +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. + +<H4>KContainerLayout</H4> +This class has been removed, use Qt layouts instead. + +<H4>KCommand</H4> +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. + +<H4>KDialogBase</H4> +The deprecated getMainWidget() method has been removed. Use mainWidget() instead. + +<H4>KDirectionButton</H4> +...is gone. Use KArrowButton instead, it offers about the same +functionality. + +<H4>KDockWidget</H4> +The WidgetList parameter has been renamed to QWidgetList. Behaviour +is identical. + +<H4>KEdit</H4> +KEdit is now deprecated. You should use use KTextEditor::Editor or +KTextEdit instead. + +<H4>KImageEffect</H4> +KImageEffect has now been moved to the new kdefx library. + +<H4>KMessageBox</H4> +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. + +<H4>KPanelApplet</H4> +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. + +<H4>KPanelMenu</H4> +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. + +<H4>KPixmapEffect</H4> +PixmapEffect has now been moved to the new kdefx library. + +<H4>KProgress</H4> +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. + +<H4>KRootPixmap</H4> +The KRootPixmap class has been extended to make it more flexible, and the +<i>checkAvailable(bool ignored)</i> method has been renamed to <i>isAvailable()</i>. +The old name will still work unless KDE_NO_COMPAT is defined. + +<H4>KThemeBase, KThemeStyle</H4> +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. + +<H4>KAction, KToolBar, KToolBarButton and icons</H4> +The preferred 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. +<p> +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. +<p> +KToolBarButton methods setPixmap(), setDefaultPixmap(), setDisabledPixmap(), setDefaultIcon() and setDisabledIcon() are deprecated. +Use KToolBarButton::setIcon() (preferred) or KToolBarButton::setIconSet() instead. + +<H4>KAction and derived classes</H4> +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). + +<H4>KToggleAction</H4> +exclusiveGroup() is no more virtual. setExclusiveGroup(const +QString&) is not a slot anymore. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kio">Changes in kio</A></H3> + +<H4>KPropertiesDialog</H4> +<ul> + <li>The header file has been renamed from kpropsdlg.h to kpropertiesdialog.h.</li> + <li>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.</li> +</ul> + +<H4>KTarGz/KTarBase/KTarData</H4> +<ul> + <li>The KTarBase and KTarData classes have been removed.</li> + <li>KTarGz is now KTar (#define for source compatibility)</li> + <li>A base class KArchive has been written, to support other archive formats in the future</li> + <li>KTarEntry is now KArchiveEntry, KTarDirectory is now KArchiveDirectory, and KTarFile is now KArchiveFile.</li> + <li>The classes ProgressBase, StatusbarProgress and DefaultProgress have been moved to the KIO namespace.</li> + <li>The signal KDirLister::started(const QString &url) has changed to KDirLister::started(const KURL &url).<li> + <li>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. + <li>The following functions in KProtocolManager have been replaced: + <ul> +<li>ftpProxy(), use proxyFor("ftp") instead. +<li>httpProxy(), use proxyFor("http") instead. +<li>slaveProtocol(const QString&), use slaveProtocol(const KURL &url, QString &proxy) instead. +<li>defaultReadTimeout(), use DEFAULT_READ_TIMEOUT instead. (See ioslave_defaults.h) +<li>defaultProxyConnectTimeout(), use DEFAULT_PROXY_CONNECT_TIMEOUT instead. (See ioslave_defaults.h) +<li>defaultResponseTimeout(), use DEFAULT_RESPONSE_TIMEOUT instead. (See ioslave_defaults.h) +<li>minimumTimeoutThreshold(), use MIN_TIMEOUT_VALUE instead. (See ioslave_defaults.h) + </ul> + <li>The following functions in KProtocolManager have been removed: + <ul> +<li>setUserAgentList( const QStringList& ) +<li>userAgentList(); +<li>setReadTimeout() +<li>setConnectTimeout( int ) +<li>setProxyConnectTimeout( int ) +<li>setResponseTimeout( int ) +<li>setMarkPartial( bool ) +<li>setMinimumKeepSize( int ) +<li>setAutoResume( bool ) +<li>setPersistentConnections( bool ) +<li>setMaxCacheAge( int ) +<li>setUseCache( bool ) +<li>setMaxCacheSize( int ) +<li>setCacheControl( KIO::CacheControl ) +<li>setUseProxy( bool ) +<li>setUseReverseProxy( bool ) +<li>setProxyType( ProxyType ) +<li>setProxyAuthMode( ProxyAuthMode ) +<li>setFtpProxy( const QString& ) +<li>setHttpProxy( const QString& ) +<li>setProxyFor( const QString&, const QString& ) +<li>setNoProxyFor( const QString& ) +<li>setProxyConfigScript( const QString& ) + </ul> + </li> + <li>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 + <b>unsigned long</b> to <b>KIO::filesize_t</b>. + 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. + </li> +</ul> + +<H4>KOpenWithHandler / KFileOpenWithHandler</H4> +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. + +<H4>KMimeType, KService</H4> +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. + +<H4>KFilterDev</H4> +The createFilterDevice method is deprecated. Use deviceForFile instead. + +<H4>KDirWatch</H4> +<ul> + <li>The signal fileDirty( const QString& ) has been removed</li> + <li>The signal created( const QString& ) has been added</li> + <li>The signal deleted( const QString& ) has been added</li> + <li>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. + </li> +</ul> + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kparts">Changes in kparts</A></H3> + +<H4>KParts::Factory</H4> +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. + +<H4>KParts::Part</H4> +The <code>bool isSelectable() const</code> 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 <code>KURL url() const</code> and ReadWritePart's <code>bool isReadWrite const</code> +and <code>bool isModified() const</code> methods. +<p> +The <code>void showProgressInfo(bool)</code> +method has been renamed to <code>bool setProgressInfoEnabled(bool)</code>. The old name will +still work unless KDE_NO_COMPAT is defined. + +<H4>KParts::BrowserExtension</H4> +The <code>URLArgs urlArgs()</code> 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. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kspell">Changes in kspell</A></H3> + +<H4>KSpell</H4> +The API has been cleaned up to be in line with the rest of kdelibs, in particular: +<ul> +<li>suggestions() now returns a QStringList instead of a pointer to a QStringList +<li>intermediateBuffer() now returns a QString instead of a pointer to a QString +<li>The signal <b>misspelling(QString, QStringList *, unsigned)</b> has changed to + misspelling(const QString &, const QStringList &, unsigned int) +<li>The signal <b>corrected(QString, QString, unsigned)</b> has changed to + corrected(const QString &, const QString &, unsigned int) +<li>The signal <b>ignoreall(QString)</b> has changed to + ignoreall(const QString &) +<li>The signal <b>ignoreword(QString)</b> has changed to + ignoreword(const QString &) +<li>The signal <b>addword(QString)</b> has changed to + addword(const QString &) +</ul> + + 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. + + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="khtmlpart">API-cleanups in KHTML</A></H3> + +There were a few relatively minor API-adjustements in KHTMLPart. In particular: +<ul><li>enableJScript(bool) has been replaced by setJScriptEnabled(bool) +<li>enableJava(bool) has been replaced by setJavaEnabled(bool) +<li>enablePlugins(bool) has been replaced by setPluginsEnabled(bool) +<li>autoloadImages(bool) has been replaced by setAutoloadImages(bool) +<li>enableMetaRefresh(bool) has been replaced by setMetaRefreshEnabled(bool) +<li>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. +<li>the second parameter of KHTMLPart::completeURL is removed. it didn't have + any effect before either. +</ul> +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. +<p>In KHTMLView, the following changes were done: +<ul> +<li>gotoNextLink has been replaced by gotoLink(true); +<li>gotoPrevLink has been replaced by gotoLink(false); +</ul> +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> + +<H3><A NAME="kfile">Changes in kfile</A></H3> +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). +<p> +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. +<p> +The changes are: +<H4>KFileItem</H4> +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: +<table> +<tr><th>Old:</th><th>New:</th></tr> +<tr><td>access()</td><td>permissionsString()</td></tr> +<tr><td>date()</td><td>timeString()</td></tr> +<tr><td>setViewItem( const KFileView *view, const void *item )</td><td>setExtraData( const void *key, void *value )</td></tr> +<tr><td>pixmap()</td><td>The parameterless method has been removed, use pixmap( int size, int state = 0 ) instead.</td></tr> +</table> + +<H4>KFileReader</H4> +This class has been merged with KDirLister from kio. + +<H4>KDirOperator</H4> +<table> +<tr><th>Old:</th><th>New:</th></tr> +<tr><td>saveConfig()</td><td>writeConfig()</td></tr> +<tr><td>setFileReader()</td><td>setDirLister()</td></tr> +<tr><td>fileReader()</td><td>dirLister()</td></tr> +<tr><td>activatedMenu( const KFileViewItem * )</td><td>activatedMenu( const KFileItem *, const QPoint& pos )</td></tr> +</table> + +<H4>KFileDetailView</H4> +The protected method setSortIndicator() has been removed, it's not needed anymore. + +<H4>KFileView</H4> +This is the baseclass for all the views. It changed in many respects to allow for greater +flexibility and efficiency. +<br><br> +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 +<ul> +<li>QString sortingKey( const QString& value, bool isDir, int sortSpec )</li> +<li>QString sortingKey( KIO::filesize_t value, bool isDir, int sortSpec )</li> +</ul> +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. + +<br><br> +Further changes: +<table> +<tr><th>Old:</th><th>New:</th></tr> +<tr><td>not existant</td><td>virtual void readConfig( KConfig *, const QString& group = QString::null )</td></tr> +<tr><td>not existant</td><td>void writeConfig( KConfig *, const QString& group = QString::null)</td></tr> +<tr><td>virtual void setCurrentItem( const QString& filename, KFileViewItem * )</td><td>Replaced with the two methods below.</td></tr> +<tr><td> </td><td>void setCurrentItem( const QString& filename );</td></tr> +<tr><td> </td><td>virtual void setCurrentItem( const KFileViewItem * ) = 0;</td></tr> +<tr><td>setOperator( QObject * )</td><td>setParentView( KFileView * )</td></tr> +<tr><td>virtual void insertSorted( KFileViewItem *, uint count )</td><td>virtual void insertItem( KFileItem * )</td></tr> +<tr><td>virtual void addItemList( const KFileViewItemList &list )</td><td>not virtual anymore. Sufficient to reimplement insertItem()</td></tr> +</table> +<br><br> +Three more pure virtual methods have been added: +<ul> +<li>virtual KFileItem * firstFileItem() const = 0</li> +<li>virtual KFileItem * nextItem( const KFileItem * ) const = 0</li> +<li>virtual KFileItem * prevItem( const KFileItem * ) const = 0</li> +</ul> + +<p> +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: +<table> +<tr><th>Old:</th><th>New:</th></tr> +<tr><td>activateMenu( item )</td><td>sig->activateMenu( item, pos )</td></tr> +<tr><td>highlight( item )</td><td>sig->highlightFile( item )</td></tr> +<tr><td>select( item )</td><td>sig->select( item )</td></tr> +</table> + + +<H4>KFileViewSignaler</H4> +The methods activateDir( const KFileViewItem * ) and activateFile( const KFileViewItem * ) +have been merged into the new method activate( const KFileItem * ). + +<br><br> +Carsten Pfeiffer <A HREF="mailto:pfeiffer@kde.org">pfeiffer@kde.org</A> + +<H4>KIconDialog, KIconButton, KURLBar, KURLBarItem</H4> +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. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> +<p> + + +<H3><A NAME="kcontrol">Changes in KControl</A></H3> + +<H4>Modules that require root permission</H4> +The meaning of the <i>X-KDE-RootOnly</i> 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 <i>X-KDE-HasReadOnlyMode</i> it was possible to show +a disabled version of the module instead of the message. The behavior was inconsistent +and has been changed: + +<ul> +<li><i>X-KDE-HasReadOnlyMode</i> is not used anymore and is ignored by KControl > 2.0. +<li><i>X-KDE-RootOnly</i> does now show a disabled preview of the widget and a notification box. +<li>If you want the old behavior back set <i>X-KDE-IsHiddenByDefault</i> along with +<i>X-KDE-RootOnly</i>. Please note that this behavior is deprecated the sake of +usability. +</ul> + +For more details please consult the HOWTO file in the kcontrol directory. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> +<p> + +<H3><A NAME="kicker">Panel Applets and Extensions</A></H3> + +<p>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. + +<H4>KPanelApplet</H4> + +<p>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. + +<H4>KPanelExtension</H4> + +<p>There is a new method alignmentChange() that your extension should reimplement if +it needs to know about changes in alignment. + +<H4><P ALIGN="RIGHT"><A HREF="#TOC">Return to the Table of Contents</A></P></H4> +<p> + +Dirk Mueller <A HREF="mailto:mueller@kde.org">mueller@kde.org</A> +</BODY> +</HTML> |