kstandarddirs.h

来自「konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版」· C头文件 代码 · 共 730 行 · 第 1/2 页

/*
  This file is part of the KDE libraries
  Copyright (C) 1999 Sirtaj Singh Kang <[e-mail]>
  Copyright (C) 1999 Stephan Kulow <[e-mail]>
  Copyright (C) 1999 Waldo Bastian <[e-mail]>

  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., 51 Franklin Street, Fifth Floor,
  Boston, MA 02110-1301, USA.
*/

#ifndef SSK_KSTDDIRS_H
#define SSK_KSTDDIRS_H

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

class KConfig;
class KStandardDirsPrivate;

/**
 * @short Site-independent access to standard KDE directories.
 * @author Stephan Kulow <[e-mail]> and Sirtaj Singh Kang <[e-mail]>
 *
 * This is one of the most central classes in kdelibs as
 * it provides a basic service: It 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 KStandardDirs::findResource("apps", "Home.desktop")
 * to apply this knowledge to return /opt/kde/share/applnk/Home.desktop
 * or ::locate("data", "kgame/background.jpg") to return
 * /opt/kde/share/apps/kgame/background.jpg
 *
 * The main idea behind 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 resource type "html" the suffixes could be
 * share/doc/HTML and share/doc/kde/HTML.
 * So the search algorithm basically 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 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.
 *
 * <b>Standard resources that kdelibs allocates are:</b>\n
 *
 * @li apps - Applications menu (.desktop files).
 * @li cache - Cached information (e.g. favicons, web-pages)
 * @li cgi - CGIs to run from kdehelp.
 * @li config - Configuration files.
 * @li data - Where applications store data.
 * @li exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
 * @li html - HTML documentation.
 * @li icon - Icons, see KIconLoader.
 * @li lib - Libraries.
 * @li locale - Translation files for KLocale.
 * @li mime - Mime types.
 * @li module - Module (dynamically loaded library).
 * @li qtplugins - Qt plugins (dynamically loaded objects for Qt)
 * @li services - Services.
 * @li servicetypes - Service types.
 * @li scripts - Application scripting additions.
 * @li sound - Application sounds.
 * @li templates - Templates
 * @li wallpaper - Wallpapers.
 * @li tmp - Temporary files (specific for both current host and current user)
 * @li socket - UNIX Sockets (specific for both current host and current user)
 * @li emoticons - Emoticons themes  (Since KDE 3.4)
 *
 * A type that is added by the class KApplication if you use it, is
 * appdata. This one makes the use of the type data a bit easier as it
 * appends the name of the application.
 * So while you had to ::locate("data", "appname/filename") so you can
 * also write ::locate("appdata", "filename") if your KApplication instance
 * is called "appname" (as set via KApplication's constructor or KAboutData, if
 * you use the global KStandardDirs object KGlobal::dirs()).
 * Please note though that you cannot use the "appdata"
 * type if you intend to use it in an applet for Kicker because 'appname' would
 * be "Kicker" instead of the applet's name. Therefore, for applets, you've got
 * to work around this by using ::locate("data", "appletname/filename").
 *
 * <b>KStandardDirs supports the following environment variables:</b>
 *
 * @li KDEDIRS: This may set an additional number of directory prefixes to
 *          search for resources. The directories should be separated
 *          by ':'. The directories are searched in the order they are
 *          specified.
 * @li KDEDIR:  Used for backwards compatibility. As KDEDIRS but only a single
 *          directory may be specified. If KDEDIRS is set KDEDIR is
 *          ignored.
 * @li 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"
 * @li KDEROOTHOME: Like KDEHOME, but used for the root user.
 *          If KDEROOTHOME is not set it defaults to the .kde directory in the
 *          home directory of root, usually "/root/.kde".
 *          Note that the setting of $HOME is ignored in this case.
 *
 * @see KGlobalSettings
 */
class KDECORE_EXPORT KStandardDirs
{
public:
        /**
	 * KStandardDirs' constructor. It just initializes the caches.
	 **/
	KStandardDirs( );

	/**
	 * KStandardDirs' destructor.
	 */
	virtual ~KStandardDirs();

	/**
	 * Adds another search dir to front of the @p fsstnd list.
	 *
	 * @li When compiling kdelibs, the prefix is added to this.
	 * @li KDEDIRS or KDEDIR is taking into account
	 * @li Additional dirs may be loaded from kdeglobals.
	 *
	 * @param dir The directory to append relative paths to.
	 */
	void addPrefix( const QString& dir );

	/**
	 * Adds another search dir to front of the XDG_CONFIG_XXX list
	 * of prefixes.
	 * This prefix is only used for resources that start with "xdgconf-"
	 *
	 * @param dir The directory to append relative paths to.
	 */
	void addXdgConfigPrefix( const QString& dir );

	/**
	 * Adds another search dir to front of the XDG_DATA_XXX list
	 * of prefixes.
	 * This prefix is only used for resources that start with "xdgdata-"
	 *
	 * @param dir The directory to append relative paths to.
	 */
	void addXdgDataPrefix( const QString& dir );

	/**
	 * Adds 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 ( kde_default) are added by addKDEDefaults(),
	 * but for those you can add more relative paths as well.
	 *
	 * The later a suffix is added, the higher its priority. Note, that the
	 * suffix should end with / but doesn't have to start with one (as prefixes
	 * should end with one). So adding a suffix for app_pics would look
	 * like KGlobal::dirs()->addResourceType("app_pics", "share/app/pics");
	 *
	 * @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.
	 * @return true if successful, false otherwise.
	 */
	bool addResourceType( const char *type,
			      const QString& relativename );

	/**
	 * Adds 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 Points to directory where to look for this specific
	 * type. Non-existant directories may be saved but pruned.
	 * @return true if successful, false otherwise.
	 */
	bool addResourceDir( const char *type,
			     const QString& absdir);

	/**
	 * Tries to find a resource in the following order:
	 * @li All PREFIX/\<relativename> paths (most recent first).
	 * @li All absolute paths (most recent first).
	 *
	 * The filename should be a filename relative to the base dir
	 * for resources. So is a way to get the path to libkdecore.la
	 * to findResource("lib", "libkdecore.la"). KStandardDirs will
	 * then look into the subdir lib of all elements of all prefixes
	 * ($KDEDIRS) for a file libkdecore.la and return the path to
	 * the first one it finds (e.g. /opt/kde/lib/libkdecore.la)
	 *
	 * @param type The type of the wanted resource
	 * @param filename A relative filename of the resource.
	 *
	 * @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;

	/**
	 * Checks whether a resource is restricted as part of the KIOSK
	 * framework. When a resource is restricted it means that user-
	 * specific files in the resource are ignored.
	 *
	 * E.g. by restricting the "wallpaper" resource, only system-wide
	 * installed wallpapers will be found by this class. Wallpapers
	 * installed under the $KDEHOME directory will be ignored.
	 *
	 * @param type The type of the resource to check
	 * @param relPath A relative path in the resource.
	 *
	 * @return True if the resource is restricted.
	 * @since 3.1
	 */
	bool isRestrictedResource( const char *type,
			      const QString& relPath=QString::null ) const;

        /**
         * Returns a number that identifies this version of the resource.
         * When a change is made to the resource this number will change.
         *
	 * @param type The type of the wanted resource
	 * @param filename A relative filename of the resource.
	 * @param deep If true, all resources are taken into account
	 *        otherwise only the one returned by findResource().
	 *
	 * @return A number identifying the current version of the
	 *          resource.
	 */
	Q_UINT32 calcResourceHash( const char *type,
			      const QString& filename, bool deep) const;

	/**
	 * Tries to find all directories whose names consist of the
	 * specified type and a relative path. So would
	 * findDirs("apps", "Settings") return
	 * @li /opt/kde/share/applnk/Settings/
	 * @li /home/joe/.kde/share/applnk/Settings/
	 *
	 * Note that it appends / to the end of the directories,
	 * so you can use this right away as directory names.
	 *
	 * @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;

	/**
	 * Tries to find the directory the file is in.
	 * It works the same as 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.
	 *
	 * findResourceDir("lib", "libkdecore.la") would return the
	 * path of the subdir libkdecore.la is found first in
	 * (e.g. /opt/kde/lib/)
	 *
	 * @param type The type of the wanted resource
	 * @param filename A relative filename of the resource.
	 * @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;


	/**
	 * Tries 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 QRegExp
	 *        wildcard expression. E.g. "images\*.jpg". Use QString::null
	 *        if you do not want a filter.
	 * @param recursive Specifies if the function should decend
	 *        into subdirectories.
	 * @param unique If specified,  only return items which have
	 *        unique suffixes - suppressing duplicated filenames.
	 *
	 * @return List of all the files whose filename matches the
	 *         specified filter.
	 */
	QStringList findAllResources( const char *type,
				       const QString& filter = QString::null,
				       bool recursive = false,
				       bool unique = false) const;

	/**
	 * Tries 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 QRegExp
	 *        wildcard expression. E.g. "images\*.jpg". Use QString::null
	 *        if you do not want a filter.
	 * @param recursive Specifies if the function should decend
	 *        into subdirectories.
	 * @param unique If specified,  only return items which have
	 *        unique suffixes.
	 * @param relPaths The list to store the relative paths into
	 *        These can be used later to ::locate() the file
	 *
	 * @return List of all the files whose filename matches the
	 *         specified filter.
	 */
	QStringList findAllResources( const char *type,
				       const QString& filter,
				       bool recursive,
				       bool unique,
				       QStringList &relPaths) const;

	/**
	 * Returns a QStringList list of pathnames in the system path.
	 *
	 * @param pstr  The path which will be searched. If this is
	 * 		null (default), the $PATH environment variable will
	 *		be searched.
	 *
	 * @return a QStringList list of pathnames in the system path.
	 */
	static QStringList systemPaths( const QString& pstr=QString::null );