kstandarddirs.h

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

	/**
	 * Finds the executable in the system path.
	 *
	 * A valid executable must
	 * be a file and have its executable bit set.
	 *
	 * @param appname The name of the executable file for which to search.
	 * @param pathstr The path which will be searched. If this is
	 * 		null (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 QString::null.
	 * @see findAllExe()
	 */
	static QString findExe( const QString& appname,
				const QString& pathstr=QString::null,
				bool ignoreExecBit=false );

	/**
	 * Finds all occurrences of an executable in the system path.
	 *
	 * @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.
	 *
	 * @see	findExe()
	 */
	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 addResourceTypes()
	 * and addPrefix() calls.
	 * You normally wouldn't call this function because it's called
	 * for you from KGlobal.
	 */
	void addKDEDefaults();

	/**
	 * Reads customized entries out of the given config object and add
	 * them via 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);

	/**
	 * This function is used internally by almost all other function as
	 * it serves and fills the directories cache.
         *
	 * @param type The type of resource
	 * @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.
         * Note, that the directories are assured to exist beside the save
         * location, which may not exist, but is returned anyway.
	 */
	QStringList resourceDirs(const char *type) const;

	/**
	 * This function will return a list of all the types that KStandardDirs
	 * supports.
	 *
	 * @return All types that KDE supports
	 */
	QStringList allTypes() const;

	/**
	 * Finds a location to save files into for the given type
	 * in the user's home directory.
	 *
	 * @param type The type of location to return.
	 * @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. A directory name always has a
 	 *       trailing slash ('/').
	 * @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;

        /**
         * Converts an absolute path to a path relative to a certain
         * resource.
         *
         * If "abs = ::locate(resource, rel)"
         * then "rel = relativeLocation(resource, abs)" and vice versa.
         *
         * @param type The type of resource.
         *
         * @param absPath An absolute path to make relative.
         *
         * @return A relative path relative to resource @p type that
         * will find @p absPath. If no such relative path exists, absPath
         * will be returned unchanged.
         */
         QString relativeLocation(const char *type, const QString &absPath);

	/**
	 * Recursively creates 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.
	 * @return true if successful, false otherwise
	 */
	static bool makeDir(const QString& dir, int mode = 0755);

	/**
	 * This returns a default relative path for the standard KDE
	 * resource types. Below is a list of them so you get an idea
	 * of what this is all about.
	 *
	 * @li data - share/apps
	 * @li html - share/doc/HTML
	 * @li icon - share/icon
	 * @li config - share/config
	 * @li pixmap - share/pixmaps
	 * @li apps - share/applnk
	 * @li sound - share/sounds
	 * @li locale - share/locale
	 * @li services - share/services
	 * @li servicetypes - share/servicetypes
	 * @li mime - share/mimelnk
	 * @li wallpaper - share/wallpapers
	 * @li templates - share/templates
	 * @li exe - bin
	 * @li lib - lib
	 *
	 * @returns Static default for the specified resource.  You
	 *          should probably be using locate() or locateLocal()
	 *          instead.
	 * @see locate()
	 * @see locateLocal()
	 */
	static QString kde_default(const char *type);

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

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

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

	/**
	 * Returns the toplevel directory in which KStandardDirs
	 * will store things. Most likely $HOME/.kde
	 * Don't use this function if you can use locateLocal
	 * @return the toplevel directory
	 */
	QString localkdedir() const;

	/**
	 * @internal
	 * Returns the default toplevel directory where KDE is installed.
	 */
	static QString kfsstnd_defaultprefix();

	/**
	 * @internal
	 * Returns the default bin directory in which KDE executables are stored.
	 */
	static QString kfsstnd_defaultbindir();

	/**
	 * @return $XDG_DATA_HOME
	 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
	 */
	QString localxdgdatadir() const;

	/**
	 * @return $XDG_CONFIG_HOME
	 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
	 */
	QString localxdgconfdir() const;

	/**
	 * Checks for existence and accessability of a file or directory.
	 * Faster than creating a QFileInfo first.
	 * @param fullPath the path to check. IMPORTANT: must end with a slash if expected to be a directory
	 *                 (and no slash for a file, obviously).
	 * @return true if the directory exists
	 */
	static bool exists(const QString &fullPath);

	/**
	 * Expands all symbolic links and resolves references to
	 * '/./', '/../' and extra  '/' characters in @p dirname
	 * and returns the canonicalized absolute pathname.
	 * The resulting path will have no symbolic link, '/./'
	 * or '/../' components.
	 * @since 3.1
	 */
	static QString realPath(const QString &dirname);

	/**
	 * Expands all symbolic links and resolves references to
	 * '/./', '/../' and extra  '/' characters in @p filename
	 * and returns the canonicalized absolute pathname.
	 * The resulting path will have no symbolic link, '/./'
	 * or '/../' components.
	 * @since 3.4
	 */
	static QString realFilePath(const QString &filename);

 private:

	QStringList prefixes;

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

	mutable QDict<QStringList> dircache;
	mutable QDict<QString> savelocations;

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

	bool addedCustoms;

	class KStandardDirsPrivate;
	KStandardDirsPrivate *d;

	void checkConfig() const;
	void applyDataRestrictions(const QString &) const;
	void createSpecialResource(const char*);

        // Like their public counter parts but with an extra priority argument
        // If priority is true, the directory is added directly after
        // $KDEHOME/$XDG_DATA_HOME/$XDG_CONFIG_HOME
	void addPrefix( const QString& dir, bool priority );
	void addXdgConfigPrefix( const QString& dir, bool priority );
	void addXdgDataPrefix( const QString& dir, bool priority );

	// If priority is true, the directory is added before any other,
	// otherwise after
	bool addResourceType( const char *type,
			      const QString& relativename, bool priority );
	bool addResourceDir( const char *type,
			     const QString& absdir, bool priority);
};

/**
 * \addtogroup locates Locate Functions
 *  @{
 * 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
 *    // Code example
 *    myFile = locate("appdata", "groups.lst");
 *    myData =  myReadGroups(myFile); // myFile may be null
 *    \endcode
 *
 * 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
 *    // Code example
 *    myFile = locate("appdata", "groups.lst")
 *    myData =  myReadGroups(myFile);
 *    ...
 *    doSomething(myData);
 *    ...
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myWriteGroups(myFile, myData);
 *    \endcode
 *
 * 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
 *    // Code example
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myData =  myReadGroups(myFile);
 *    ...
 *    doSomething(myData);
 *    ...
 *    myFile = locateLocal("appdata", "groups.lst");
 *    myWriteGroups(myFile, myData);
 *    \endcode
 **/

/*!
 * \relates KStandardDirs
 * This function is just for convenience. It simply calls
 *instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename).
 **/
KDECORE_EXPORT QString locate( const char *type, const QString& filename, const KInstance* instance = KGlobal::instance() );

/*!
 * \relates KStandardDirs
 * 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.
 *
 **/
KDECORE_EXPORT QString locateLocal( const char *type, const QString& filename, const KInstance* instance = KGlobal::instance() );

/*!
 * \relates KStandardDirs
 * This function is much like locate. No check is made if the
 * specified filename actually exists. Missing directories
 * are created if @p createDir is true. If filename is only
 * a directory, without a specific file,
 * filename must have a trailing slash.
 *
 **/
KDECORE_EXPORT QString locateLocal( const char *type, const QString& filename, bool createDir, const KInstance* instance = KGlobal::instance() );

/*! @} */

#endif // SSK_KSTDDIRS_H