This is a multi-part message in MIME format.
--------------7264A2CCEF7A800ABD8FD003
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

OK, now I know that coolo@kde.org's mails won't
reach kde-devel, I'll forward the rest.

Greetings, Stephan

-- 
Und sie nannten ihn, wie er selbst unterschrieb -
Den Trojanischen Pferdedieb
--------------7264A2CCEF7A800ABD8FD003
Content-Type: message/rfc822
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

X-Mozilla-Status2: 00000000
Message-ID: <376970C6.A777172@kde.org>
Date: Fri, 18 Jun 1999 00:03:50 +0200
From: Stephan Kulow <coolo@kde.org>
X-Mailer: Mozilla 4.6 [en] (X11; U; Linux 2.0.36 i586)
X-Accept-Language: en
MIME-Version: 1.0
To: KDE Developer <kde-devel@kde.org>
Subject: HOWTO: locate
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hi!

It seems, it was a mistake from my side to think
that the introduction of KStandardDirs would be
easy. Well, actually I relied on the promise of
Kurt and Waldo, who said that no rewrite is 
necessary and implied they would do so if 
necessary.

Ok, to make it short: locate("icon", "") will
_not_ give the same as kde_icondir(). Instead
if will just return null. The propose of locate
is to find files, not directories. You have to
get this in your head before you should change
your code :)

The second parameter is the filename locate should
look into and the first gives the set of directories
to look into. kde_icondir() is just one of them.

So, you can replace code like kde_icondir() + filename
with locate("icon", filename) if you just need one
file with that name.

But if you need the directories for some misc stuff,
you have to go the hard way and rethink your code.
The new concept, that there is no kde_icondir, but
a whole set of directories where it can be. The
main idea behind it, is that the user can give extra
directories for each type _and_ that every application
may reside in a different directory independent from
where kdelibs is.
That has been a very big limitation of KDE 1.1.x, you
couldn't install klyx outside of /opt/kde for example.

But if we want to allow that, we have to take away the
concept of path names from the developers and give him
functions to find and access files. And if you look into
KStandardDirs, there is a whole bunch of them, thanks to
the ideas of Taj and some hours of coding of me ;)

addResourceType lets you add a complete new set of directories
for some internal stuff of your application. For example
I added addResourceType("kwm_pics") to kwm or "themes" to
kthememgr. you get a KIconLoader::loadIcon for free ;)
BTW: KIconLoader->setIconType("kwm_pics") will let
loadIcon look into your defined set of paths.

findResource is the long form for locate. It looks around
in the set for the given type and looks for a _file_ named
like the second parameter.

findDirs is something like findResource for directories. 
But this one returns a list of possible hits and you 
have to find the one you really need yourself. Don't 
assume anything about which is the right one, but look into 
everyone of them. It also has a second parameter to add a 
relative suffix to decrease  the number of possible hits.

findResourceDir is the function used internally by find-
Resource, but you can use it too if you for example load
a bunch of files that you can be sure are in the same
directory (kmoon's pictures would be a good example). 
But the argument for findResourceDir is still a filename
and it won't return something guessed, but only directory
names for the filename you give it. But code like this is
cool (reference to Warwick :)

 dir = findResourceDir("moons", "moon1.png");
 moon2 = load(dir + "moon2.png");

And finally there is findAllResources.
This function returns all filenames in all directories 
registred for the type. This are most often way too many
and I think, the next addition will be findAllFiltered :)

And there are also findExe for finding executables taking
$PATH in account and some more.

So please: look into kstddirs.cpp before you change your
code. I've seen too many wrong usages already.

Greetings, Stephan

-- 
Und sie nannten ihn, wie er selbst unterschrieb -
Den Trojanischen Pferdedieb

--------------7264A2CCEF7A800ABD8FD003--