Porting to TDE

From Trinity Desktop Project Wiki
Revision as of 09:08, 1 May 2023 by Blu256 (talk | contribs) (Fix typo, move TODO into Widget styles section)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This page is intended to provide generic instructions for porting old KDE3 software to the Trinity libraries.

Build system

Trinity software uses CMake with custom macros. Since R14.0.11 these macros are automatically installed as part of Trinity, so you don't need to worry about including them as a submodule anymore.

The best way to get a hang of how it all works is to take a look at how CMake is used in an existing project. For simplicity take a standalone app package as an example (e.g. Mathemagics). Note the files named CMakeLists.txt, CMakeL10n.txt, ConfigureChecks.cmake and config.h.cmake and how they configure, build and link the software.

More specific notes can be found in other Wiki articles, depending on what you are trying to port.


While porting you might want to keep the existing build system (until you figure out how everything works). To do this, remove the bundled admin directory and then clone the tde-common-admin submodule in the place of the removed directory:

$ git rm -r admin
$ git submodule add https://mirror.git.trinitydesktop.org/gitea/TDE/tde-common-admin admin

If you do this before actually porting the software, make sure the porting scripts do not overwrite anything in the admin directory where the submodule resides: you might get strange errors like configure being unable to locate TQt.

When you've got things building you should port the software to CMake.


Porting Qt3 and KDE3 software to Trinity has mostly been automated with scripts. Before porting your first application/style/... do obtain these scripts from TGW:

$ git clone https://mirror.git.trinitydesktop.org/gitea/TDE/scripts/

Then, to port a KDE3 application you would follow the following steps:

1. Switch into the directory containing the source code.

2. Create an initial commit with the original form of the source code.

3. Run the Qt3→TQt conversion script.

$ ../scripts/conversions/qt3-tqt3/convert_existing_qt3_app_to_tqt3

4. Replace all <ntq*.h> headers with <tq*.h> ones in order to use the TQt-TDE interface (simply remove the n letter from the front of the header's filename). This can be automated with a small script:

for f in $(grep -Rl "<ntq[[:alnum:]]*.h>" * --include=\*.{h,c,cpp,ui});
    sed -Ei 's!<n(tq[[:alnum:]]*.h)>!<\1>!g' $f

5. Commit your changes labeled "Qt3→TQt conversion" or similarly.

6. Run the KDE3→TDE conversion script.

$ ../scripts/conversions/kde-tde/convert_existing_kde3_app_to_tde

7. Commit your changes labeled "KDE3→TDE conversion" or similarly.

8. Try to build. If this fails take note of the errors and fix them. Don't forget to commit your changes describing what you fixed.

For Qt3-only apps follow steps 1 to 5.

Widget styles

This section has not been written/completed yet. You can contribute to Trinity by writing or finalizing this section.
Messagebox warning.png
The TQt API docs do not currently seem to reflect the API changes described here.

The TQt Style API has undergone some important changes, so porting a widget style to TDE will entail a little more than just running scripts.

Keep the following changes in mind:

  • Most functions' definitions have changed;
  • The usage of the widget argument is deprecated in favor of specifying widget parameters via ceData and elementFlags;
  • SH_UnderlineAccelerator has been extended with a new style hint, SH_HideUnderlineAcceleratorWhenAltUp.

Porting an existing style to the new API is relatively straightforward; simply update the function definitions in the existing style with the new definition prototypes and cast the passed pointer to TQWidget or TQObject where appropriate. You can see this in practice if you look into the relevant commits of already ported widget styles. See this commit of tde-style-ia-ora for example.