kstddirs.h

monqueror一个很具有参考价值的源玛

	 * 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.
	 * @param relPaths The list to store the relative paths into
	 *        These can be used later to @ref locate the file
	 *
	 * @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);

	/**
	 * This function is used internally by almost all other function as
	 * it serves and fills the directories cache.
	 *
	 * @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;

    /**
     * This function will return a list of all the types that KStandardDirs
     * supports.
     *
     * @return All types that KDE supports
     */
    QStringList allTypes() 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. 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;

	/**
	 * 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);

	/**
	 * 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 @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();

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

	/**
	 * checks for existance and accessability
	 * faster than creating a QFileInfo first
	 */
	static bool exists(const QString &fullPath);

 private:

	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;

	KStandardDirsPrivate *d;
};

/**
 * 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
 * instance->dirs()->findResource(type, filename).
 **/
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