[KDE/Mac] Thoughts on standard directories in Qt5 - QStandardPaths

[Ian Wadham]

Hi Marko,

I have been reading around the topic of standard directories and I may be
able to help you at long last… :-)  SDs are certainly a balancing act… :-)

KStandardDirs
--------------------

First of all, the ancestor of QStandardPaths [1] is KStandardDirs [2].  The
Detailed Description section(scroll down that page) is quite good and may
give you some useful background on how KDE apps find their files and
plugins.  As an example, consider the following log, from dear old
KGoldrunner:

    System games: /opt/local/share/apps/kgoldrunner/system/
    User data:          /Users/ianw/Library/Preferences/KDE/share/apps/kgoldrunner/user/

As well as code, KGoldrunner comes with many data files of different types.

The first line shows where the basic games and levels come from.  A great
feature of KGoldrunner, since its ancestor Loderunner (™) on Apple II and
Commodore 64, is that the game has a Game Editor and users can compose
their own games and levels.  The second line shows where the users' games
and levels go.  The user can select and play levels from either area.  The use
of the "system" and "user" subdirs is peculiar to KGoldrunner.  Most KDE apps
would use /<some_prefix>/<appname> and ~/<some_other_prefix>/<appname>
for their data files, the idea being that if there are files of the same name in each
area, the one in ~ ($HOME) overrides the one in /<some_prefix>/<appname>.
This makes it easy for a user to create personalised or test versions of files.

KGoldrunner also has files for sounds, graphics themes, menu configuration,
keystroke settings and application prefs.  Other games, such as Palapeli, have
files to describe plugins and KSudoku has XML files to describe puzzle layouts.
In general, menu config, keystroke settings and application prefs can be overidden
by files in the user area (e.g. the famous case of <appname>ui.rc files).

In KDE 4, all these files must be installed in known locations and found by
KStandardDirs when the application runs.  For any given *type* of file, there is
a list of such locations covering installed (read-only) locations and zero or one
user location (usually writable), which can override the installed locations.

The simplest (static) methods to use in KStandardDirs are KStandardDirs::locate()
and KStandardDirs::locateLocal() [3].  These correspond roughly to Qt5's methods
QStandardPaths::locate() and QStandardPaths::writableLocation(), see [1].

KF5 is using QStandardPaths (QSP).  KStandardDirs has many more options and
bells and whistles than QSP, so much so that there is a special page on KStandardDirs
in the KF5 Porting Notes [4].  This is worth a read, to get an idea of how KDE apps in
KF5 are likely to be using QSP.  A key point is that KStandardDirs and QSP file types
do not always coincide and the KDE application programmer (in KF5) must do something
special about types like "emoticons", "html" and "sound".  OTOH QSP has location-types
for music, movies and pictures, which are not found in KStandardDirs.  One might say
that QSP is more user-oriented whereas KStandardDirs is more developer-oriented.

QStandardPaths (QSP) on Apple OS X
----------------------------------------------------

QStringList QStandardPaths::standardLocations(StandardLocation type) is a key method
of QSP.  It returns a list of all directories where files of a particular type may be found.  The
first directory in the list is provided by calling QStandardPaths::writableLocation(), i.e. it can
be a directory in the user's home area whose files can override default files in installed areas.
This is mimicing the behaviour of KStandardDirs in KDE 5.  To see what file-types are defined
in QSP and where those directories might be, on different platforms, see [5].

The list of locations for Apple OS X files in KF5 or Qt5 applications is provided by source
code qt5/qtbase/src/corelib/io/qstandardpaths_mac.cpp.  This file contains the implementation
of the key methods QStandardPaths::standardLocations() and QStandardPaths::writableLocation()
on which other methods depend (e.g. QStandardPaths::locate()).  Marko has been patching
this file.  See [6].







[1] http://qt-project.org/doc/qt-5/qstandardpaths.html
[2] http://api.kde.org/4.14-api/kdelibs-apidocs/kdecore/html/classKStandardDirs.html
[3] http://api.kde.org/4.14-api/kdelibs-apidocs/kdecore/html/classKStandardDirs.html#ac3dc86ce3c70df963e56c898d75ec201
[4] https://community.kde.org/Frameworks/Porting_Notes/KStandardDirs
[5] http://qt-project.org/doc/qt-5/qstandardpaths.html#StandardLocation-enum
[6] http://quickgit.kde.org/?p=clones%2Fwebsites%2Fbuild-kde-org%2Fkaning%2Fmp-osx-ci.git&a=blob&h=e0b488e55a279023c1750543cb1daf8b40980321&hb=4c2bfb1d764e18b9ee12851c991ef5126e4d30f1&f=patches%2Fqt5%2Fkf5-qt5%2Fpatch-qstandardpaths_mac.cpp.diff