diff --git a/KDE2PORTING.html b/KDE2PORTING.html deleted file mode 100644 index 181a5bccb..000000000 --- a/KDE2PORTING.html +++ /dev/null @@ -1,925 +0,0 @@ - - - - Guide to Porting Applications to KDE 2.0 - - - -

Porting Applications to KDE 2.0

-

Last Modified on November 28, 2000

-This document contains the changes you have to apply to programs written for -KDE1.1 when you want to port them to KDE2.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 2.0, - is to detect KDE 2.0 and Qt 2.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 "tdesdk"), to generate a new - application template. Replace the generated source files by yours - and adapt Makefile.am accordingly. - -

Return to the Table of Contents

- -

Global changes

- - We did our best to clean up the header files of tdelibs, so they do - not include unnecessary bloat for your application. As a consequence, you - may notice that some header files are missing from your source files as - they have been included before by kapp.h for example. There is a script - in tdesdk/scripts called "fixheaders" that takes care of most of these - cases. Just call "make -k 2>&1 | perl .../fixheaders" and it will try - to look after the error messages and add includes as it recognize the - errors.

- - Also, if your code does not compile and complains about missing member - functions, you should check for methods that started with get...(). - These methods have been renamed to xy*() for consistency.

- -

Return to the Table of Contents

- -

automoc/am_edit, Makefile.am tags

- - On the subject of the compilation framework, automoc has been removed from - the admin directory. It has been replaced by am_edit which provides a lot of - additional features.

- METASOURCES=AUTO still does the job of generating the appropriate moc files, - but in addition, you should use KDE_ICON for the icons representing the application - (and naming those icons conforming to lo16-app-<appname>.png), and install - the application-specific icons under $(kde_datadir)/<appname>/pics. - -

Return to the Table of Contents

- -

TDEApplication

- - doesn't hold any longer a TDELocale instance. With this getLocale() - and isLocaleInstantiated are now replaced by TDEGlobal::locale()

- - it also doesn't hold a KiconLoader instance. As this also getIconLoader() - has been removed. Replace kapp->getIconLoader()->loadIcon() with - BarIcon() or use TDEGlobal::iconLoader() instead of getIconLoader()

- - kde_*dir() have been removed as they require a unique top level directory - for all applications (TDEDIR). This concept doesn't exist in KDE 2.0 - any more, it has been replaced with "multiple levels of directories", - set in TDEDIRS, so that it's possible to have global settings and - group settings, applied before user settings.

- - Replace code that uses kde_*dir() + filename with calls to - locate(filetype, filename) where filetype is what * used to be - in kde_*dir(). locate is defined as function in kstddirs.h to call - TDEGlobal::dirs()->findResource.

- - Use locateLocal to get the path of a writable file. For instance, - TDEApplication::localconfigdir()+filename is now locateLocal( "config", filename ), - but for most cases, simply using TDEGlobal::config() is enough, if you're happy - with saving the application's configuration into appnamerc, or - KSimpleConfig cfg("anothercfgfile") to create a config file with another name.

- - generalFont() and fixedFont() are deprecated and will be removed soon. - Please use TDEGlobalSettings::generalFont() and TDEGlobalSettings::fixedFont() instead.

- - appName() is deprecated. Please use TQApplication::name() or instanceName - instead.

- - The methods tempSaveName() and checkRecoverFile() return QString - now. The returned values must _not_ be free()d.

- - helpMenu() has been moved to TDEMainWindow. aboutKDE(), aboutApp() and - appHelpActivated() have all been removed See section for TDEMainWindow - for more info.

- - The TDEApplication constructor has changed. Command line arguments and - program name should no longer be passed to TDEApplication but to - TDECmdLineArgs. TDECmdLineArgs performs command line parsing and a command - line help. See below for more info.

- -

Return to the Table of Contents

- -

TDECmdLineArgs

- - TDECmdLineArgs is a new class that handles command line parsing and - command line help. It is now required that your application - specifies at least:

-

- - TDECmdLineArgs itself will add the command line options supported by Qt - and TDEApplication.

- - You can also use the TDEAboutData class to specify name, description and - version.

- - In return for this information you can query TDECmdLineArgs whether an - certain option was specified on the command line and your application - now automatically supports --help and --version. It aborts with a - useful error message when the command line contains a syntax error. - See tdelibs/tdecore/tdecmdlineargs.h for more info.

- -

Return to the Table of Contents

- -

TDELocale

- - i18n is no longer a macro

- - TDEApplication::getApplication()->getLocale()->translate

- - but a function on its own. klocale is obsolete and replace every call - to klocale->translate with i18n.

- - The return value of i18n is also no longer a const char*, - but a unicode TQString.

- -

Return to the Table of Contents

- -

TDEGlobal: access to KDE global objects.

- -TDEGlobal allows centralized access to KDE global objects without including -extraneous headers. object creation is deferred if possible.

- -All methods are static and headers for returned types are not included. You -must have created a TDEApplication object before the methods can be used.

- - - - - - - -
- 
-      #include <tdeglobal.h>
-      #include <tdeconfig.h>      // Needed to use TDEConfig
-      #include <tdelocale.h>      // Needed to use TDELocale
-      #include <kiconloader.h>  // Needed to use TDEIconLoader
-
-
- 
-    ...
-        	TDEConfig *appcfg = TDEGlobal::config();
-	        TQString mystr	 = i18n( "This is a string" );
-
-
-		TDEIconLoader *loader = TDEGlobal::iconLoader();
-
-
- -

Return to the Table of Contents

- -

TDEIconLoader

- -TDEIconLoader in 1.1 used to mix icons for applications and for toolbars. -This has changed, so you may notice that your application doesn't find -the right icons. loadIcon (used by BarIcon) returns only toolbar icons.

-If you need icons for applications, use loadApplicationIcon.

-loadMiniIcon and loadApplicationMiniIcon have been removed, instead -loadApplicationIcon now takes a "size" argument where you can specify the -size of the icon (small, medium, large).

-The other big change you may notice, is that ICON and Icon have been -removed as they caused big confusion for not loading application icons -(see above). For this we added BarIcon which does the same as ICON before. -The third change in this row is that loadIcon doesn't need the extension -anymore, but looks for standard extensions (png, xpm) itself. If you hard- -coded .xpm, loadIcon will issue a warning at runtime, but will still work -in stripping off the .xpm part

- -

Return to the Table of Contents

- -

KTMainWindow

- -KTMainWindow has been replaced with TDEMainWindow.

- -The TDEMainWindow constructor needs a parent widget as first argument. -You can use 0 for this.

-setView() has been replaced with setCentralWidget().

-view() has been replaced with centralWidget().

-addToolBar() has been removed, it is not needed any more.

-setMenu(...) has been removed, it is not needed any more.

-setStatusBar(...) has been removed, it is not needed any more.

-updateRects() has been removed, it is not needed any more.

-enableStatusBar(...) has been removed, use statusBar()->show() and/or -statusBar()->hide() instead.

-enableToolBar(...) has been removed, use toolBar()->show() and/or -toolBar()->hide() instead.

- -view_* public variables do no longer exist. There is really no reason -for an app to use this information. If you do need it anyway, use -mainViewGeometry() instead.

- -

Return to the Table of Contents

- -

KHelpMenu

- -helpMenu() has been moved to TDEMainWindow from TDEApplication (kapp).

- -Both the "About KDE" and the "About <Application>" dialog boxes -are now modeless. "About KDE" is a completely new widget.

- -If you used in the toplevel window (that is derived from TDEMainWindow) -"kapp->helpMenu( bool, TQString )" to get the help menu -you must now change this to "helpMenu( TQString )". The TQString defaults -to TQString::null so it is sufficient to write helpMenu().

- -The old aboutKDE(), aboutApp() and appHelpActivated() of TDEApplication -have all been removed. If you need direct access to these or need -access to a help menu in a class that is not derived from -TDEMainWindow then allocate an instance of the new class KHelpMenu. -See KDE 2.0 API reference or khelpmenu.h (tdeui) for additional info.

-Espen Sand <espen@kde.org>

- -

Return to the Table of Contents

- -

TDEToolBar

- -enable(...) is depreciated, use show()/hide() instead.

-enableFloating(...) has been removed, use enableMoving() instead.

-setMaxHeight() is depreciated, use setMaximumHeight() instead.

-maxHeight() is depreciated, use maximumHeight() instead.

-setMaxWidth() is depreciated, use setMaximumWidth() instead.

-maxWidth() is depreciated, use maximumWidth() instead.

- -

Return to the Table of Contents

- -

Starting other programs

- -In KDE 2.0 there are several ways to start other programs from within -your application. Here is a short summary of your options with reasons why -you should or should not use them. -

1. fork + exec

-

-You never want to use this unless you have a very good reason why it is -impossible to use TDEProcess. -

-

2. TDEProcess

-

-You want to use this if you need to start a new process which needs to be a -child of your process, e.g. because you want to catch stdout/stderr or need -to send it data via stdin. You should never use this to start other KDE -applications unless your application is called kgdb :-) If you need to -send/receive text like data to/from the process, you are probably better -off with KProcIO -

- -

3. KProcIO

-

-Like TDEProcess. Unlike TDEProcess, this class actually makes it easy to -send data to and receive data from the process. - -

-

4. startServiceByDesktopPath

-

-Preferred way to launch desktop (KDE/Gnome/X) applications or KDE services. -The application/service must have a .desktop file. It will make use of -KDEinit for increased startup performance and lower memory usage. These -benefits only apply to applications available as KDEinit loadable module (KLM) -

-

5. KRun

-

-Generic way to open documents/applications/shell commands. Uses -startServiceBy.... where applicable. Offers the additional -benefit of startup-notification.
-KRun can start any application, from the binary or the desktop file, -it will determine the mimetype of a file before running the -preferred handler for it, and it can also start shell commands. -This makes KRun the recommended way to run another program in KDE 2. -

- -

Return to the Table of Contents

- -

tdehtmlw

- -tdehtmlw has been replaced with tdehtml.
- - -

Return to the Table of Contents

- -

KIntegerLine, KIntLineEdit

- - KIntegerLine and KIntLineEdit have been replaced by KIntNumInput. - The new header file is called knuminput.h.

- - The new KIntNumInput can have an optional slider attached, ensures - that the entered value is in a given range (use MAX_INT or similar - if you don't care about the range) and can maintain a descriptive - label and also a unit for the edited value.

- - The API is almost the same and it simplifies existing code a bit, - so give it a try. If you need more functionality, please contact - me, Dirk A. Mueller <mueller@kde.org>.

- - The additional class KDoubleNumInput gives you the same look & feel, - but allows you to edit floating point numbers.

- -

Return to the Table of Contents

- -

KDNDIcon, KDNDDropZone, KDNDWidget, tdecore/drag.h

- -KDE Drag and Drop is Dead. Long live Qt Xdnd.

- -Xdnd is better anyway, because it has been adopted by all the other -major GUI toolkits still under active development (this precludes -Motif, but maybe we can convince the lesstif guys!). Some changes -are necessary to convert your old KDND-based stuff to Qt DND.

-

- -

Return to the Table of Contents

- -

TDEConfigBase, TDEConfig, KSimpleConfig

- - These classes have been largely re-implemented. The external API - remains mostly the same, with the single notable change that - the groupIterator and entryIterator methods have been removed and - instead replaced by groupList (which returns a TQStringList of groups) - and entryMap(const TQString &group) (which returns a TQMap of entries - in the specified group). This is due to internal changes in TDEConfig - which would make providing iterators possibly rather difficult.

- - Much more extensive documentation on the TDEConfig and friends API can - be found in the kdoc generated documentation from the header files, - and in tdecore/KCONFIG_DESIGN.

- - To use the new iterator, you will probably want to do something like - this:

- 

-
-  TQMap<TQString, TQString> tmpMap = config-<entryMap(myGroup);
-  TQMap<TQString, TQString>::Iterator aIt(tmpMap.begin());
-
-  for (; aIt != tmpMap.end(); ++aIt) {
-   // body here.  Access iterator key as aIt.key(),
-   // data as *aIt.
-  }
-
- -

Return to the Table of Contents

- -

libkfm has disappeared

- - Lots of other functionalities have been taken out of kfm, some being - now in libtdeio, some in libkonq.

- Replacement table :

- - - - - - - - - - - - -
KFM::download -> TDEIO::NetAccess::download (tdelibs/tdeio/netaccess.h)
KFM::removeTempFile -> TDEIO::NetAccess::removeTempFile
refreshDesktop, sortDesktop, selectRootIcons : removed; kdesktop handles it
KFM::configure -> see konqueror DCOP interface
KFM::openURL -> "(void) new KRun (url)" (tdelibs/tdeio/krun.h)
KFM::refreshDirectory -> not needed anymore since konqy/kdesktop use KDirWatch
KFM::openProperties -> "(void) new KPropertiesDialog (url)" (tdelibs/tdefile/kpropsdlg.h)
KFM::exec -> "(void) new KRun (url)" (tdelibs/tdeio/krun.h)
KFM::copy, KFM::move -> TDEIO::Job (async, see tdeio/job.h)
- or TDEIO::NetAccess (sync, see tdeio/netaccess.h)
DlgLocation -> Use KLineEditDlg (tdeui/klineeditdlg.h) instead
- -

Return to the Table of Contents

- -

KDialog

- -KDialog is no longer defined in kwizard.h. Include kdialog.h instead.

-Note that the best way to write new dialogs is to use KDialogBase (see kdialogbase.h)

- -

Return to the Table of Contents

- - -

kcharsets

- -The kcharsets class has been completely rewritten, and most of it has -vanished, since support for it moved to Qt.

- -Most applications will only need to replace kapp->getKCharsets() with -TDEGlobal::charsets().

- -For conversion of various input formats to QStrings, please have a -look at TQTextCodec and classes derived from it.

- -Character entities are now converted from and to QChars. The name has -changed from convertTag to fromEntity and toEntity.

- -To get a font, which can display a certain charset (if such a font -exists), you can use the KCharsets::setQFont methods. Input is a font and -a charset. Kcharsets tries to find an output font, which matches the -input font most closely, but can display the given charset.

- -

Return to the Table of Contents

- -

KWizard, KNoteBook

- -KWizard is based on TQWizard now. The API has changed. Consult Qt's -documentation and tdelibs/kdetest/kwizardtest.cpp for an example use.

-KNoteBook (deeply entwined with the former KWizard) has been removed until -someone is willing to port it to work with the new wizard. If you want to -use it you'll find the necessary files in tdegraphics/tdeiconedit.

- -

Return to the Table of Contents

- -

KSpinBox, KNumericSpinBox

- -These classes have been replaced by TQSpinBox. API is almost the same -HINTS:

-

- -

Return to the Table of Contents

- -

TDEClipboard

- -TDEClipboard has been removed. In case you've been using TDEClipboard, -QClipboard is the way to go now, as it has all the functionality the K -version had, and more.

- -

Return to the Table of Contents

- -

KPanner, KNewPanner

- -KPanner and KNewPanner have been removed. TQSplitter does everything -KPanner did and more. The api is similar, but not compatible. -Basically to set it up so that you have a vertical splitter between a -listbox, a listview and multi line editor, you would do something like -this:

-
- TQSplitter *split = new TQSplitter( parent );
- TQListBox *lb = new TQListBox( split );
- TDEListView *lv = new TDEListView( split );
- TQMultiLineEdit *ed = new TQMultiLineEdit( split ); -
- -As you can see you are not limited to two children. Additionally, you -do not have to call activate when you are done, and opaque resizing is -possible if you call setOpaqueResize(true).

- -

Return to the Table of Contents

- -

KTreeList, KTreeListItem

- -Use TDEListView, TQListViewItem instead. API is almost the same, you only -need to add a Column (TDEListView::addColum) before TDEListView is useable.

- -TDEListView has no addChild(), insertItem() and removeItem() calls. Inserting -a root item is done by constructing a TQListViewItem with the TDEListView -passed as the parent widget. adding a child item is done by constructing -a TQListViewItem with the parent item as parameter. removeItem() should -be replaced by delete <pointer to item>.

- -The root items are not shown in a tree fashion by default. to get this, -use TDEListView::setDecorativeRoot(true).

- -Expanding and collapsing can by done by using TQListViewItem::setOpen(bool).

- - -

Return to the Table of Contents

- -

KMsgBox

- -KMsgBox has been superseded by TQMessageBox. Which has been superseded -by KMessageBox.

-

- -

Return to the Table of Contents

- -

KCombo

- -KCombo has been removed. Use KComboBox instead, it is completely -compatible with the old KCombo API. The method that you may have problems -with is the old KCombo::setText. This has been renamed to -KComboBox::setEditText.

- -

Return to the Table of Contents

- -

KQuickHelp

- -KQuickHelp, the "super-tooltip" widget, has been replaced by TQWhatsThis. -It provides a compatible API and almost the same look and feel, in addition -to some new functionality.

- -

Return to the Table of Contents

- -

KPixmap::gradientFill

- -Instead of old KPixmap::gradientFill, use:

- -KPixmapEffect::gradient(KPixmap&, TQColor, TQColor, enum KPixmapEffect::GradientType, int)

- - Hence:

- -pix.gradientFill(ca, cb, direction, ncols)

- -becomes, for direction == true :

- -KPixmapEffect::gradient(pix, ca, cb, KPixmapEffect::VerticalGradient, ncols)

- -There are now:

- -
-KPixmapEffect::
 [Vertical,
- Horizontal,
- Diagonal,
- CrossDiagonal,
- Rectangle,
- Pyramid,
- PipeCross,
- Elliptic]
- -Gradients. See tdelibs/kdetest/kgradienttest & kunbalancedgradienttest for -information on how they actually look.

- -Look further in this document for other info about pixmap effect code -reorganization (essentially, all effects are now in libtdeui.so: gradient(), -unbalancedGradient(), hash(), desaturate(), pattern(), fade(), blend() etc.

- -

Return to the Table of Contents

- -

KTabListBox

- -This widget has been replaced by the almighty TDEListView. Everything said -about KTreeList could be repeated here. The good thing is, that you now -can combine TreeView's and normal Tablists without problems.

- -

Return to the Table of Contents

- -

TDEToolBarButton & TDERadioGroup

- -If you need to do anything with TDEToolBarButton you now need to include -<tdetoolbarbutton.h> TDERadioGroup has been renamed to TDEToolBarRadioGroup and -requires you to include <tdetoolbarradiogroup.h>

- -

Return to the Table of Contents

- -

TDEAccel

- -The functions keyToString() and stringToKey() which were previously -declared globally in tdeaccel.h are now static methods in TDEAccel.

- -

Return to the Table of Contents

- -

kstring.h / KString

- -The KString class is obsolete and is not defined in -kstring.h anymore. The header file only existed for compatibility reasons. -The file has been removed completely, use TQString instead. (mirko@kde.org)

- -

Return to the Table of Contents

- -

ktopwidget.h / KTopWidget

- -TDEMainWindow replaces this class completely. ktopwidget.h does not -exist in KDE 2. (mirko@kde.org)

- -

Return to the Table of Contents

- -

kbutton.h / KButton

- -Since Qt 2.0, the class TQToolButton provides the functionality of -buttons that raise when the mouse is moved over them, so there is no -reason to have a class providing the same feature in KDE libs. All -occurrences of KButton in the KDE CVS have been replaced by QToolButtons, -but for applications not in the CVS it has to be done by the respective -developer. (mirko@kde.org)

- -

kbuttonbox.h / KButtonBox

- -KButtonBox::Orientation has been removed in favor of Qt::Orientation. - -

Return to the Table of Contents

- -

kcolorgroup.h / KColorGroup

- -KColorGroup was not used in sources in the KDE CVS, and its -functionality is provided by Qt. It has been removed. (mirko@kde.org)

- -

Return to the Table of Contents

- -

kled.h, kledlamp.h / KLed, KLedLamp

- -There where two different classes for showing an LED lamp. Both are -merged to the KLed class, but THE USER INTERFACE IS DIFFERENT, as both -where more or less broken.

-Please adjust your code accordingly.

- -

Return to the Table of Contents

- -

KDockWidget

- -KDockWidget inherits form TDEMainWindow instead of KTMainWindow now. -See KTMainWindow for more details. - -

Return to the Table of Contents

- -

KPixmap, KPixmapEffect

- -KPixmap::gradientFill, KPixmap::patternFill, KPixmap::tile and -KPixmap::mapFill have been moved to KPixmapEffect, which is now part -of libtdeui.

- -KPixmap::tile() has been renamed to KPixmapEffects::createTile().

- -Dirk A. Mueller <mueller@kde.org>

- - -

Return to the Table of Contents

- -

Trinity Control Center

- -The format for modules for the Trinity Control Center has changed quite -a bit. If you want to port your module to the new schema, please -consult

- -tdebase/kcontrol/README

- -which explains what needs to be done.

- -Matthias Hoelzer-Kluepfel <hoelzer@kde.org>

- -

Return to the Table of Contents

- - -

KWMModuleApplication libtdeui/kwmmapp.h

- -The KWMModuleApplication has been removed. Instead, use the class -KWinModule in libtdecore. The API is a bit cleaner but very similar, -so you will feel comfortable immediately. One of the advantages of -KWinModule is that it doesn't require a special TDEApplication -subclass. This lead to many problems and misunderstandings in the -past. KWinModule is now just an object that emits fancy signals (and -provides some useful lists, like the list of all managed windows). -(ettrich@kde.org)

- - -

Return to the Table of Contents

- -

kDebug

- -Use kdDebug, kdWarning, kdError, kdFatal to log debug output, warnings and -errors in a very flexible way. kdebug has been improved, and the API simplified. -tdesdk/scripts/kDebug2kdDebug.sh provides a script for automating the conversion. -Note that enabling/disabling debug output can now be done with tdedebugdialog, -which can be found in tdebase. The hidden dialog on C+S+F12 no longer exists. -

-Also, note that tqDebug and fprintf aren't disabled by -DNDEBUG, whereas kdDebug is. -One more reason to use kdDebug ! -(faure@kde.org)

- -

Return to the Table of Contents

- -

KFileDialog - General Stuff

- -The new (rewritten) KFileDialog (KFD) is a lot more like the new QFileDialog -but still looks quite different. Normally you may want to use the static -methods provided for convenience (getOpenFileName and getSaveFileName). -If you need special features you can configure the dialog extensively. Just -create an object and use the different methods.

-Werner Trobin <wtrobin@carinthia.com>

- - -

Return to the Table of Contents

- -

KFileDialog - Preview Mode

-There is also a new preview mode which is quite different to the one we had in -the KDE 1.x KFD. There are no preview modules you have to register but there -is a single method you can use to set a preview widget. This widget has to -inherit TQWidget and you have to implement a slot (showPreview(const KURL &)) -in this class. This slot is called each time the selected file/dir changes. -In this slot you have to react appropriate (i.e. show the preview :). The -easiest way this can be done is to derive your class from TQWidgetStack and -add a Object (derived from TQWidget) for each file type. In the showPreview -method you just raise the matching widget. If you can't find an appropriate -widget just hide() the widget stack.

-If you need some "inspiration" on how that could be done, please have a look -at koffice/lib/kofficecore/koFilterManager.cc (PreviewStack).

-Werner Trobin <wtrobin@carinthia.com>

- -

Return to the Table of Contents

- -

Image effects

- -The kFSDither class is now gone. Its functionality was moved to -KImageEffect::dither(). Whereas before, you would done:

- - - - -
- 
-  kFSDither dither(palette, ncols);
-  image = dither.dither(image);
-
-
-

-Now do:
- - - - -
- 
-  KImageEffect::dither(image, palette, ncols);
-
-
-

- -Kurt Granroth <granroth@kde.org> - -

Return to the Table of Contents

- -

KAudio (kaudio.h)

-The KAudio class no longer exists. Here are your options for porting. -

-

-Stefan Westerfeld stefan@space.twc.de - -

Return to the Table of Contents

- -

KImageIO (kimgio.h)

-

-KImageIO has moved from 'kimgio.h' to 'kimageio.h'. LIB_KIMGIO does no longer -exists, you need to link against LIB_TDESYCOCA instead. -

-

-kimgioRegister() has been replaced by KImageIO::registerFormats(). -

- -

-Waldo Bastian bastian@kde.org - -

Return to the Table of Contents

- - -