Source: kstddirs.h


Annotated List
Files
Globals
Hierarchy
Index
/*
  This file is part of the KDE libraries
  Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org>
                     Stephan Kulow <coolo@kde.org>
		     Waldo Bastian <bastian@kde.org>

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Library General Public
  License as published by the Free Software Foundation; either
  version 2 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Library General Public License for more details.

  You should have received a copy of the GNU Library General Public License
  along with this library; see the file COPYING.LIB.  If not, write to
  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA 02111-1307, USA.
*/

#ifndef SSK_KSTDDIRS_H
#define SSK_KSTDDIRS_H

#include <qstring.h>
#include <qdict.h>
#include <qlist.h>
#include <qstringlist.h>
#include <kglobal.h>

class KConfig;

/**
* @short Site-independent access to standard KDE directories.
* @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org>
* @version $Id: kstddirs.h,v 1.56 2000/02/05 20:38:44 waba Exp $
*
* This is one of the most central classes in kdelibs as
* it provides a basic service: Tt knows where the files
* reside on the user's hard disk. And it's meant to be the
* only one that knows -- to make the real location as
* transparent as possible to both the user and the applications.
*
* To this end it insulates the application from all information
* and applications always refer to a file with a resource type
* (e.g. icon) and a filename (e.g. khexdit.xpm). In an ideal world
* the application would make no assumption where this file is and
* leave it up to @ref KStandardDirs::findResource("apps", "Home.desktop")
* to apply this knowledge.
*
* The main idea behind @ref KStandardDirs is that there are several
* toplevel prefixes below which the files lie. One of these prefixes is
* the one where the user installed kdelibs, one is where the
* application was installed, and one is $HOME/.kde, but there
* may be even more. Under these prefixes there are several well
* defined suffixes where specific resource types are to be found.
* For example, for the resourcet type "icon" the suffixes are be share/icons
* and share/apps/<appname>/icons,
* but also share/icons/large if the user prefers large icons.
* So the search algorithm basicly appends to each prefix each registered
* suffix and tries to locate the file there.
* To make the thing even more complex, it's also possible to register
* absolute paths that @ref KStandardDirs looks up after not finding anything
* in the former steps. They can be useful if the user wants to provide
* specific directories that aren't in his $HOME/.kde directory for,
* for example, icons.
*
* @sect Standard resources that kdelibs allocates are:
*
* @li appdata - Application specific data dir (if created after KApplication).
* @li apps - Applications menu (.desktop files).
* @li cgi - CGIs to run from kdehelp.
* @li config - Configuration files.
* @li data - Where applications store data.
* @li exe - Executables in $prefix/bin. @ref #findExe for a function that takes $PATH into account.
* @li html - HTML documentation.
* @li icon - Icons.
* @li lib - Libraries.
* @li locale - Translation files for @ref KLocale.
* @li mime - Mime types.
* @li services - Services.
* @li servicetypes - Service types.
* @li sound - Application sounds.
* @li toolbar - Toolbar pictures.
* @li wallpaper - Wallpapers.
*
* KStandardDirs supports the following environment variables:
*
* KDEDIRS: This may set an additional number of directories to 
*          search for resources. The directories should be seperated
*          by ':'. The directories are searched in the order they are 
*          specified.
* KDEDIR:  Used for backwards compatibility. As KDEDIRS but only a single
*          directory may be specified. If KDEDIRS is set KDEDIR is 
*          ignored.
* KDEHOME: The directory where changes are saved to. This directory is
*          used to search for resources first. If KDEHOME is not 
*          specified it defaults to "$HOME/.kde"
*
**/
class KStandardDirs
{
public:
        /**
	 * @ref KStandardDirs constructor. It just initializes the cache.
	 **/
	KStandardDirs( );

	/**
	 * @ref KStandardDirs destructor.
	 */
	virtual ~KStandardDirs();

	/**
	 * Add another search dir to front of the @p fsstnd list.
	 *
	 * @li When compiling kdelibs, the prefix is added to this.
	 * @li When compiling a separate app, kapp adds the new prefix
	 * @li Additional dirs may be loaded from kdeglobals.
	 *
	 * @param dir The directory to append relative paths to.
	 */
	void addPrefix( QString dir );


	/**
	 * Add suffixes for types.
	 *
	 *  You may add as many as
	 * you need, but it is advised that there is exactly one to make
	 * writing definite.
	 * All basic types (@ref kde_default) are added by @ref addKDEDefaults(),
	 * but for those you can add more relative paths as well.
	 *
	 * The later a suffix is added, the higher its priority.
	 *
	 * @param type Specifies a short descriptive string to access
	 * files of this type.
	 * @param relativename Specifies a directory relative to the root
	 * of the KFSSTND.
	 */
	bool addResourceType( const char *type,
			      const QString& relativename );


	/**
	 * Add absolute path at the end of the search path for
	 * particular types (for example in case of icons where
	 * the user specifies extra paths).
	 *
	 * You shouldn't need this
	 * function in 99% of all cases besides adding user-given
	 * paths.
	 *
	 * @param type Specifies a short descriptive string to access files
	 * of this type.
	 * @param absdir Soints to directory where to look for this specific
	 * type. Non-existant directories may be saved but pruned.
	 *
	 */
	bool addResourceDir( const char *type,
			     const QString& absdir);

	/**
	 * Try to find resource in the following order:
	 * @li All PREFIX/<relativename> paths (most recent first).
	 * @li All hard paths (most recent first).
	 *
	 * @return A full path to the filename specified in the second
	 *         argument, or QString::null if not found.
	 */
	QString findResource( const char *type,
			      const QString& filename ) const;

	/**
	 * Try to find all directories whose names consist of the
	 * specified type and a relative path.
	 *
	 * @param type The type of the base directory.
	 * @param reldir Relative directory.
	 *
	 * @return A list of matching directories, or an empty
	 *         list if the resource specified is not found.
	 */
	QStringList findDirs( const char *type,
                              const QString& reldir ) const;

	/**
	 * Try to find the directory the file is in.
	 * It works the same as @ref findResource(), but it doesn't
	 * return the filename but the name of the directory.
	 *
	 * This way the application can access a couple of files
	 * that have been installed into the same directory without
	 * having to look for each file.
	 *
	 * @return The directory where the file specified in the second
	 *         argument is located, or QString::null if the type
	 *         of resource specified is unknown or the resource
	 *         cannot be found.
	 */
	QString findResourceDir( const char *type,
				 const QString& filename) const;


	/**
	 * Try to find all resources with the specified type.
	 *
	 * The function will look into all specified directories
	 * and return all filenames in these directories.
	 *
	 * @param type The type of resource to locate directories for.
	 * @param filter Only accept filenames that fit to filter. The filter
	 *        may consist of an optional directory and a @ref QRexExp
	 *        wildcard expression. E.g. "images\*.jpg"
	 * @param recursive Specifies if the function should decend
	 *        into subdirectories.
	 * @param uniq If specified,  only return items which have
	 *        unique suffixes.
	 *
	 * @return A list of directories matching the resource specified,
	 *         or an empty list if the resource type is unknown.
	 */
	QStringList findAllResources( const char *type,
				       const QString& filter = QString::null,
				       bool recursive = false,
				       bool uniq = false) const;

	/**
	 * Try to find all resources with the specified type.
	 *
	 * The function will look into all specified directories
	 * and return all filenames (full and relative paths) in
	 * these directories.
	 *
	 * @param type The type of resource to locate directories for.
	 * @param filter Only accept filenames that fit to filter. The filter
	 *        may consist of an optional directory and a @ref QRexExp
	 *        wildcard expression. E.g. "images\*.jpg"
	 * @param recursive Specifies if the function should decend
	 *        into subdirectories.
	 * @param uniq If specified,  only return items which have
	 *        unique suffixes.
	 * @param list Of relative paths for the given type.
	 *
	 * @return A list of directories matching the resource specified,
	 *         or an empty list if the resource type is unknown.
	 */
	QStringList findAllResources( const char *type,
				       const QString& filter,
				       bool recursive,
				       bool uniq,
				       QStringList &relPaths) const;

	/**
	 * Find the executable in the system path.
	 *
	 * A valid executable must
	 * be a file and have its executable bit set.
	 *
	 * @see findAllExe()
	 * @param appname The name of the executable file for which to search.
	 * @param pathstr The path which will be searched. If this is
	 * 		0 (default), the $PATH environment variable will
	 *		be searched.
	 * @param ignoreExecBit	If true, an existing file will be returned
	 *			even if its executable bit is not set.
	 *
	 * @return The path of the executable. If it was not found,
	 *         it will return @ref QString::null.
	 */
	static QString findExe( const QString& appname,
				const QString& pathstr=QString::null,
				bool ignoreExecBit=false );

	/**
	 * Find all occurences of an executable in the system path.
	 *
	 * @see	findExe()
	 *
	 * @param list	Will be filled with the pathnames of all the
	 *		executables found. Will be empty if the executable
	 *		was not found.
	 * @param appname	The name of the executable for which to
	 *	 		search.
	 * @param pathstr	The path list which will be searched. If this
	 *		is 0 (default), the $PATH environment variable will
	 *		be searched.
	 * @param ignoreExecBit If true, an existing file will be returned
	 *			even if its executable bit is not set.
	 *
	 * @return The number of executables found, 0 if none were found.
	 */
	static int findAllExe( QStringList& list, const QString& appname,
			       const QString& pathstr=QString::null,
			       bool ignoreExecBit=false );

	/**
	 * This function adds the defaults that are used by the current
	 * KDE version.
	 *
	 * It's a series of @ref addResourceTypes()
	 * and @ref addPrefix() calls.
	 * You normally wouldn't call this function because it's called
	 * for you from @ref KGlobal.
	 */
	void addKDEDefaults();

	/**
	 * Read customized entries out of the given config object and add
	 * them via @ref addResourceDirs().
	 *
	 * @param config The object the entries are read from. This should
	 *        contain global config files
	 * @return @true if new config paths have been added 
	 * from @p config.
	 **/
	bool addCustomized(KConfig *config);

	/**
	 * @return The list of possible directories for the specified @p type.
	 * The function updates the cache if possible.  If the resource
	 * type specified is unknown, it will return an empty list.
	 */
	QStringList resourceDirs(const char *type) const;

	/**
	 * Find a location to save files into for the given type
	 * in the user's home directory.
	 *
	 * @param suffix A subdirectory name. 
	 *             Makes it easier for you to create subdirectories.
	 *   You can't pass filenames here, you _have_ to pass
	 *       directory names only and add possible filename in
	 *       that directory yourself.
	 * @param create If set, saveLocation() will create the directories
	 *        needed (including those given by @p suffix).
	 *
	 * @return A path where resources of the specified type should be
	 *         saved, or QString::null if the resource type is unknown.
	 */
	 QString saveLocation(const char *type,
			      const QString& suffix = QString::null,
			      bool create = true) const;

	/**
	 * Recursively create still-missing directories in the given path.
	 *
	 * The resulting permissions will depend on the current umask setting.
	 * permission = mode & ~umask.
	 *
	 * @param dir Absolute path of the directory to be made.
	 * @param mode Directory permissions.
	 */
	static bool makeDir(const QString& dir, int mode = 0755);

	/**
	 * @returns Static default for the specified resource.  You
	 *          should probably be using @ref locate() or @ref locateLocal()
	 *          instead.
	 * @see locate()
	 * @see locateLocal()
	 */
	static QString kde_default(const char *type);

        /**
         * @internal (for use by sycoca only)
         */
        QString kfsstnd_prefixes();         

 private:

	QString localkdedir() const;

	QStringList prefixes;

	// Directory dictionaries
	QDict<QStringList> absolutes;
	QDict<QStringList> relatives;
	
	mutable QDict<QStringList> dircache;

	// Disallow assignment and copy-construction
	KStandardDirs( const KStandardDirs& );
	KStandardDirs& operator= ( const KStandardDirs& );

	bool addedCustoms;

	// checks for existance and accessability
	static bool exists(const QString &fullPath);
};

/**
 * On The Usage Of 'locate' and 'locateLocal'
 *
 * Typical KDE applications use resource files in one out of
 * three ways:
 *
 * 1) A resource file is read but is never written. A system
 *    default is supplied but the user can override this
 *    default in his local .kde directory:
 *
 *    // Code example
 *    myFile = locate("appdata", "groups.lst");
 *    myData =  myReadGroups(myFile); // myFile may be null
 *
 * 2) A resource file is read and written. If the user has no
 *    local version of the file the system default is used.
 *    The resource file is always written to the users local
 *    .kde directory.
 *
 *    // Code example
 *    myFile = locate("appdata", "groups.lst")
 *    myData =  myReadGroups(myFile);
 *    ...
 *    doSomething(myData);
 *    ...
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myWriteGroups(myFile, myData);
 *
 * 3) A resource file is read and written. No system default
 *    is used if the user has no local version of the file.
 *    The resource file is always written to the users local
 *    .kde directory.
 *
 *    // Code example
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myData =  myReadGroups(myFile);
 *    ...
 *    doSomething(myData);
 *    ...
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myWriteGroups(myFile, myData);
 **/

/**
 * This function is just for convience. It simply calls
 * KGlobal::dirs()->findResource(type, filename).
 * But if you pass a KLibGlobal, then library->dirs() is
 * queried for the desired resource.
 **/
QString locate( const char *type, const QString& filename, const KInstance* instance = KGlobal::instance() );

/**
 * This function is much like locate. However it returns a
 * filename suitable for writing to. No check is made if the
 * specified filename actually exists. Missing directories
 * are created. If filename is only a directory, without a
 * specific file, filename must have a trailing slash.
 *
 **/
QString locateLocal( const char *type, const QString& filename, const KInstance* instance = KGlobal::instance() );

#endif // SSK_KSTDDIRS_H

Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:19 2000, using kdoc 2.0a33.