TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

730 lines
26 KiB

  1. /*
  2. This file is part of the KDE libraries
  3. Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org>
  4. Copyright (C) 1999 Stephan Kulow <coolo@kde.org>
  5. Copyright (C) 1999 Waldo Bastian <bastian@kde.org>
  6. This library is free software; you can redistribute it and/or
  7. modify it under the terms of the GNU Library General Public
  8. License as published by the Free Software Foundation; either
  9. version 2 of the License, or (at your option) any later version.
  10. This library is distributed in the hope that it will be useful,
  11. but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  13. Library General Public License for more details.
  14. You should have received a copy of the GNU Library General Public License
  15. along with this library; see the file COPYING.LIB. If not, write to
  16. the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17. Boston, MA 02110-1301, USA.
  18. */
  19. #ifndef SSK_KSTDDIRS_H
  20. #define SSK_KSTDDIRS_H
  21. #include <tqstring.h>
  22. #include <tqdict.h>
  23. #include <tqstringlist.h>
  24. #include <kglobal.h>
  25. class KConfig;
  26. class KStandardDirsPrivate;
  27. /**
  28. * @short Site-independent access to standard KDE directories.
  29. * @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org>
  30. *
  31. * This is one of the most central classes in tdelibs as
  32. * it provides a basic service: It knows where the files
  33. * reside on the user's hard disk. And it's meant to be the
  34. * only one that knows -- to make the real location as
  35. * transparent as possible to both the user and the applications.
  36. *
  37. * To this end it insulates the application from all information
  38. * and applications always refer to a file with a resource type
  39. * (e.g. icon) and a filename (e.g. khexdit.xpm). In an ideal world
  40. * the application would make no assumption where this file is and
  41. * leave it up to KStandardDirs::findResource("apps", "Home.desktop")
  42. * to apply this knowledge to return /opt/kde/share/applnk/Home.desktop
  43. * or ::locate("data", "kgame/background.jpg") to return
  44. * /opt/kde/share/apps/kgame/background.jpg
  45. *
  46. * The main idea behind KStandardDirs is that there are several
  47. * toplevel prefixes below which the files lie. One of these prefixes is
  48. * the one where the user installed tdelibs, one is where the
  49. * application was installed, and one is $HOME/.trinity, but there
  50. * may be even more. Under these prefixes there are several well
  51. * defined suffixes where specific resource types are to be found.
  52. * For example, for the resource type "html" the suffixes could be
  53. * share/doc/HTML and share/doc/tde/HTML.
  54. * So the search algorithm basically appends to each prefix each registered
  55. * suffix and tries to locate the file there.
  56. * To make the thing even more complex, it's also possible to register
  57. * absolute paths that KStandardDirs looks up after not finding anything
  58. * in the former steps. They can be useful if the user wants to provide
  59. * specific directories that aren't in his $HOME/.trinity directory for,
  60. * for example, icons.
  61. *
  62. * <b>Standard resources that tdelibs allocates are:</b>\n
  63. *
  64. * @li apps - Applications menu (.desktop files).
  65. * @li cache - Cached information (e.g. favicons, web-pages)
  66. * @li cgi - CGIs to run from kdehelp.
  67. * @li config - Configuration files.
  68. * @li data - Where applications store data.
  69. * @li exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
  70. * @li html - HTML documentation.
  71. * @li icon - Icons, see KIconLoader.
  72. * @li lib - Libraries.
  73. * @li locale - Translation files for KLocale.
  74. * @li mime - Mime types.
  75. * @li module - Module (dynamically loaded library).
  76. * @li qtplugins - Qt plugins (dynamically loaded objects for Qt)
  77. * @li services - Services.
  78. * @li servicetypes - Service types.
  79. * @li scripts - Application scripting additions.
  80. * @li sound - Application sounds.
  81. * @li templates - Templates
  82. * @li wallpaper - Wallpapers.
  83. * @li tmp - Temporary files (specific for both current host and current user)
  84. * @li socket - UNIX Sockets (specific for both current host and current user)
  85. * @li emoticons - Emoticons themes (Since KDE 3.4)
  86. *
  87. * A type that is added by the class KApplication if you use it, is
  88. * appdata. This one makes the use of the type data a bit easier as it
  89. * appends the name of the application.
  90. * So while you had to ::locate("data", "appname/filename") so you can
  91. * also write ::locate("appdata", "filename") if your KApplication instance
  92. * is called "appname" (as set via KApplication's constructor or KAboutData, if
  93. * you use the global KStandardDirs object KGlobal::dirs()).
  94. * Please note though that you cannot use the "appdata"
  95. * type if you intend to use it in an applet for Kicker because 'appname' would
  96. * be "Kicker" instead of the applet's name. Therefore, for applets, you've got
  97. * to work around this by using ::locate("data", "appletname/filename").
  98. *
  99. * <b>KStandardDirs supports the following environment variables:</b>
  100. *
  101. * @li TDEDIRS: This may set an additional number of directory prefixes to
  102. * search for resources. The directories should be separated
  103. * by ':'. The directories are searched in the order they are
  104. * specified.
  105. * @li TDEDIR: Used for backwards compatibility. As TDEDIRS but only a single
  106. * directory may be specified. If TDEDIRS is set TDEDIR is
  107. * ignored.
  108. * @li TDEHOME: The directory where changes are saved to. This directory is
  109. * used to search for resources first. If TDEHOME is not
  110. * specified it defaults to "$HOME/.trinity"
  111. * @li TDEROOTHOME: Like TDEHOME, but used for the root user.
  112. * If TDEROOTHOME is not set it defaults to the .kde directory in the
  113. * home directory of root, usually "/root/.trinity".
  114. * Note that the setting of $HOME is ignored in this case.
  115. *
  116. * @see KGlobalSettings
  117. */
  118. class TDECORE_EXPORT KStandardDirs
  119. {
  120. public:
  121. /**
  122. * KStandardDirs' constructor. It just initializes the caches.
  123. **/
  124. KStandardDirs( );
  125. /**
  126. * KStandardDirs' destructor.
  127. */
  128. virtual ~KStandardDirs();
  129. /**
  130. * Adds another search dir to front of the @p fsstnd list.
  131. *
  132. * @li When compiling tdelibs, the prefix is added to this.
  133. * @li TDEDIRS or TDEDIR is taking into account
  134. * @li Additional dirs may be loaded from kdeglobals.
  135. *
  136. * @param dir The directory to append relative paths to.
  137. */
  138. void addPrefix( const TQString& dir );
  139. /**
  140. * Adds another search dir to front of the XDG_CONFIG_XXX list
  141. * of prefixes.
  142. * This prefix is only used for resources that start with "xdgconf-"
  143. *
  144. * @param dir The directory to append relative paths to.
  145. */
  146. void addXdgConfigPrefix( const TQString& dir );
  147. /**
  148. * Adds another search dir to front of the XDG_DATA_XXX list
  149. * of prefixes.
  150. * This prefix is only used for resources that start with "xdgdata-"
  151. *
  152. * @param dir The directory to append relative paths to.
  153. */
  154. void addXdgDataPrefix( const TQString& dir );
  155. /**
  156. * Adds suffixes for types.
  157. *
  158. * You may add as many as you need, but it is advised that there
  159. * is exactly one to make writing definite.
  160. * All basic types ( kde_default) are added by addKDEDefaults(),
  161. * but for those you can add more relative paths as well.
  162. *
  163. * The later a suffix is added, the higher its priority. Note, that the
  164. * suffix should end with / but doesn't have to start with one (as prefixes
  165. * should end with one). So adding a suffix for app_pics would look
  166. * like KGlobal::dirs()->addResourceType("app_pics", "share/app/pics");
  167. *
  168. * @param type Specifies a short descriptive string to access
  169. * files of this type.
  170. * @param relativename Specifies a directory relative to the root
  171. * of the KFSSTND.
  172. * @return true if successful, false otherwise.
  173. */
  174. bool addResourceType( const char *type,
  175. const TQString& relativename );
  176. /**
  177. * Adds absolute path at the end of the search path for
  178. * particular types (for example in case of icons where
  179. * the user specifies extra paths).
  180. *
  181. * You shouldn't need this
  182. * function in 99% of all cases besides adding user-given
  183. * paths.
  184. *
  185. * @param type Specifies a short descriptive string to access files
  186. * of this type.
  187. * @param absdir Points to directory where to look for this specific
  188. * type. Non-existant directories may be saved but pruned.
  189. * @return true if successful, false otherwise.
  190. */
  191. bool addResourceDir( const char *type,
  192. const TQString& absdir);
  193. /**
  194. * Tries to find a resource in the following order:
  195. * @li All PREFIX/\<relativename> paths (most recent first).
  196. * @li All absolute paths (most recent first).
  197. *
  198. * The filename should be a filename relative to the base dir
  199. * for resources. So is a way to get the path to libtdecore.la
  200. * to findResource("lib", "libtdecore.la"). KStandardDirs will
  201. * then look into the subdir lib of all elements of all prefixes
  202. * ($TDEDIRS) for a file libtdecore.la and return the path to
  203. * the first one it finds (e.g. /opt/kde/lib/libtdecore.la)
  204. *
  205. * @param type The type of the wanted resource
  206. * @param filename A relative filename of the resource.
  207. *
  208. * @return A full path to the filename specified in the second
  209. * argument, or TQString::null if not found.
  210. */
  211. TQString findResource( const char *type,
  212. const TQString& filename ) const;
  213. /**
  214. * Checks whether a resource is restricted as part of the KIOSK
  215. * framework. When a resource is restricted it means that user-
  216. * specific files in the resource are ignored.
  217. *
  218. * E.g. by restricting the "wallpaper" resource, only system-wide
  219. * installed wallpapers will be found by this class. Wallpapers
  220. * installed under the $TDEHOME directory will be ignored.
  221. *
  222. * @param type The type of the resource to check
  223. * @param relPath A relative path in the resource.
  224. *
  225. * @return True if the resource is restricted.
  226. * @since 3.1
  227. */
  228. bool isRestrictedResource( const char *type,
  229. const TQString& relPath=TQString::null ) const;
  230. /**
  231. * Returns a number that identifies this version of the resource.
  232. * When a change is made to the resource this number will change.
  233. *
  234. * @param type The type of the wanted resource
  235. * @param filename A relative filename of the resource.
  236. * @param deep If true, all resources are taken into account
  237. * otherwise only the one returned by findResource().
  238. *
  239. * @return A number identifying the current version of the
  240. * resource.
  241. */
  242. TQ_UINT32 calcResourceHash( const char *type,
  243. const TQString& filename, bool deep) const;
  244. /**
  245. * Tries to find all directories whose names consist of the
  246. * specified type and a relative path. So would
  247. * findDirs("apps", "Settings") return
  248. * @li /opt/kde/share/applnk/Settings/
  249. * @li /home/joe/.trinity/share/applnk/Settings/
  250. *
  251. * Note that it appends / to the end of the directories,
  252. * so you can use this right away as directory names.
  253. *
  254. * @param type The type of the base directory.
  255. * @param reldir Relative directory.
  256. *
  257. * @return A list of matching directories, or an empty
  258. * list if the resource specified is not found.
  259. */
  260. TQStringList findDirs( const char *type,
  261. const TQString& reldir ) const;
  262. /**
  263. * Tries to find the directory the file is in.
  264. * It works the same as findResource(), but it doesn't
  265. * return the filename but the name of the directory.
  266. *
  267. * This way the application can access a couple of files
  268. * that have been installed into the same directory without
  269. * having to look for each file.
  270. *
  271. * findResourceDir("lib", "libtdecore.la") would return the
  272. * path of the subdir libtdecore.la is found first in
  273. * (e.g. /opt/kde/lib/)
  274. *
  275. * @param type The type of the wanted resource
  276. * @param filename A relative filename of the resource.
  277. * @return The directory where the file specified in the second
  278. * argument is located, or TQString::null if the type
  279. * of resource specified is unknown or the resource
  280. * cannot be found.
  281. */
  282. TQString findResourceDir( const char *type,
  283. const TQString& filename) const;
  284. /**
  285. * Tries to find all resources with the specified type.
  286. *
  287. * The function will look into all specified directories
  288. * and return all filenames in these directories.
  289. *
  290. * @param type The type of resource to locate directories for.
  291. * @param filter Only accept filenames that fit to filter. The filter
  292. * may consist of an optional directory and a QRegExp
  293. * wildcard expression. E.g. "images\*.jpg". Use TQString::null
  294. * if you do not want a filter.
  295. * @param recursive Specifies if the function should decend
  296. * into subdirectories.
  297. * @param unique If specified, only return items which have
  298. * unique suffixes - suppressing duplicated filenames.
  299. *
  300. * @return List of all the files whose filename matches the
  301. * specified filter.
  302. */
  303. TQStringList findAllResources( const char *type,
  304. const TQString& filter = TQString::null,
  305. bool recursive = false,
  306. bool unique = false) const;
  307. /**
  308. * Tries to find all resources with the specified type.
  309. *
  310. * The function will look into all specified directories
  311. * and return all filenames (full and relative paths) in
  312. * these directories.
  313. *
  314. * @param type The type of resource to locate directories for.
  315. * @param filter Only accept filenames that fit to filter. The filter
  316. * may consist of an optional directory and a QRegExp
  317. * wildcard expression. E.g. "images\*.jpg". Use TQString::null
  318. * if you do not want a filter.
  319. * @param recursive Specifies if the function should decend
  320. * into subdirectories.
  321. * @param unique If specified, only return items which have
  322. * unique suffixes.
  323. * @param relPaths The list to store the relative paths into
  324. * These can be used later to ::locate() the file
  325. *
  326. * @return List of all the files whose filename matches the
  327. * specified filter.
  328. */
  329. TQStringList findAllResources( const char *type,
  330. const TQString& filter,
  331. bool recursive,
  332. bool unique,
  333. TQStringList &relPaths) const;
  334. /**
  335. * Returns a TQStringList list of pathnames in the system path.
  336. *
  337. * @param pstr The path which will be searched. If this is
  338. * null (default), the $PATH environment variable will
  339. * be searched.
  340. *
  341. * @return a TQStringList list of pathnames in the system path.
  342. */
  343. static TQStringList systemPaths( const TQString& pstr=TQString::null );
  344. /**
  345. * Finds the executable in the system path.
  346. *
  347. * A valid executable must
  348. * be a file and have its executable bit set.
  349. *
  350. * @param appname The name of the executable file for which to search.
  351. * @param pathstr The path which will be searched. If this is
  352. * null (default), the $PATH environment variable will
  353. * be searched.
  354. * @param ignoreExecBit If true, an existing file will be returned
  355. * even if its executable bit is not set.
  356. *
  357. * @return The path of the executable. If it was not found,
  358. * it will return TQString::null.
  359. * @see findAllExe()
  360. */
  361. static TQString findExe( const TQString& appname,
  362. const TQString& pathstr=TQString::null,
  363. bool ignoreExecBit=false );
  364. /**
  365. * Finds all occurrences of an executable in the system path.
  366. *
  367. * @param list Will be filled with the pathnames of all the
  368. * executables found. Will be empty if the executable
  369. * was not found.
  370. * @param appname The name of the executable for which to
  371. * search.
  372. * @param pathstr The path list which will be searched. If this
  373. * is 0 (default), the $PATH environment variable will
  374. * be searched.
  375. * @param ignoreExecBit If true, an existing file will be returned
  376. * even if its executable bit is not set.
  377. *
  378. * @return The number of executables found, 0 if none were found.
  379. *
  380. * @see findExe()
  381. */
  382. static int findAllExe( TQStringList& list, const TQString& appname,
  383. const TQString& pathstr=TQString::null,
  384. bool ignoreExecBit=false );
  385. /**
  386. * This function adds the defaults that are used by the current
  387. * KDE version.
  388. *
  389. * It's a series of addResourceTypes()
  390. * and addPrefix() calls.
  391. * You normally wouldn't call this function because it's called
  392. * for you from KGlobal.
  393. */
  394. void addKDEDefaults();
  395. /**
  396. * Reads customized entries out of the given config object and add
  397. * them via addResourceDirs().
  398. *
  399. * @param config The object the entries are read from. This should
  400. * contain global config files
  401. * @return true if new config paths have been added
  402. * from @p config.
  403. **/
  404. bool addCustomized(KConfig *config);
  405. /**
  406. * This function is used internally by almost all other function as
  407. * it serves and fills the directories cache.
  408. *
  409. * @param type The type of resource
  410. * @return The list of possible directories for the specified @p type.
  411. * The function updates the cache if possible. If the resource
  412. * type specified is unknown, it will return an empty list.
  413. * Note, that the directories are assured to exist beside the save
  414. * location, which may not exist, but is returned anyway.
  415. */
  416. TQStringList resourceDirs(const char *type) const;
  417. /**
  418. * This function will return a list of all the types that KStandardDirs
  419. * supports.
  420. *
  421. * @return All types that KDE supports
  422. */
  423. TQStringList allTypes() const;
  424. /**
  425. * Finds a location to save files into for the given type
  426. * in the user's home directory.
  427. *
  428. * @param type The type of location to return.
  429. * @param suffix A subdirectory name.
  430. * Makes it easier for you to create subdirectories.
  431. * You can't pass filenames here, you _have_ to pass
  432. * directory names only and add possible filename in
  433. * that directory yourself. A directory name always has a
  434. * trailing slash ('/').
  435. * @param create If set, saveLocation() will create the directories
  436. * needed (including those given by @p suffix).
  437. *
  438. * @return A path where resources of the specified type should be
  439. * saved, or TQString::null if the resource type is unknown.
  440. */
  441. TQString saveLocation(const char *type,
  442. const TQString& suffix = TQString::null,
  443. bool create = true) const;
  444. /**
  445. * Converts an absolute path to a path relative to a certain
  446. * resource.
  447. *
  448. * If "abs = ::locate(resource, rel)"
  449. * then "rel = relativeLocation(resource, abs)" and vice versa.
  450. *
  451. * @param type The type of resource.
  452. *
  453. * @param absPath An absolute path to make relative.
  454. *
  455. * @return A relative path relative to resource @p type that
  456. * will find @p absPath. If no such relative path exists, absPath
  457. * will be returned unchanged.
  458. */
  459. TQString relativeLocation(const char *type, const TQString &absPath);
  460. /**
  461. * Recursively creates still-missing directories in the given path.
  462. *
  463. * The resulting permissions will depend on the current umask setting.
  464. * permission = mode & ~umask.
  465. *
  466. * @param dir Absolute path of the directory to be made.
  467. * @param mode Directory permissions.
  468. * @return true if successful, false otherwise
  469. */
  470. static bool makeDir(const TQString& dir, int mode = 0755);
  471. /**
  472. * This returns a default relative path for the standard KDE
  473. * resource types. Below is a list of them so you get an idea
  474. * of what this is all about.
  475. *
  476. * @li data - share/apps
  477. * @li html - share/doc/tde/HTML
  478. * @li icon - share/icon
  479. * @li config - share/config
  480. * @li pixmap - share/pixmaps
  481. * @li apps - share/applnk
  482. * @li sound - share/sounds
  483. * @li locale - share/locale
  484. * @li services - share/services
  485. * @li servicetypes - share/servicetypes
  486. * @li mime - share/mimelnk
  487. * @li wallpaper - share/wallpapers
  488. * @li templates - share/templates
  489. * @li exe - bin
  490. * @li lib - lib
  491. *
  492. * @returns Static default for the specified resource. You
  493. * should probably be using locate() or locateLocal()
  494. * instead.
  495. * @see locate()
  496. * @see locateLocal()
  497. */
  498. static TQString kde_default(const char *type);
  499. /**
  500. * @internal (for use by sycoca only)
  501. */
  502. TQString kfsstnd_prefixes();
  503. /**
  504. * @internal (for use by sycoca only)
  505. */
  506. TQString kfsstnd_xdg_conf_prefixes();
  507. /**
  508. * @internal (for use by sycoca only)
  509. */
  510. TQString kfsstnd_xdg_data_prefixes();
  511. /**
  512. * Returns the toplevel directory in which KStandardDirs
  513. * will store things. Most likely $HOME/.trinity
  514. * Don't use this function if you can use locateLocal
  515. * @return the toplevel directory
  516. */
  517. TQString localtdedir() const;
  518. /**
  519. * @internal
  520. * Returns the default toplevel directory where KDE is installed.
  521. */
  522. static TQString kfsstnd_defaultprefix();
  523. /**
  524. * @internal
  525. * Returns the default bin directory in which KDE executables are stored.
  526. */
  527. static TQString kfsstnd_defaultbindir();
  528. /**
  529. * @return $XDG_DATA_HOME
  530. * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
  531. */
  532. TQString localxdgdatadir() const;
  533. /**
  534. * @return $XDG_CONFIG_HOME
  535. * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
  536. */
  537. TQString localxdgconfdir() const;
  538. /**
  539. * Checks for existence and accessability of a file or directory.
  540. * Faster than creating a TQFileInfo first.
  541. * @param fullPath the path to check. IMPORTANT: must end with a slash if expected to be a directory
  542. * (and no slash for a file, obviously).
  543. * @return true if the directory exists
  544. */
  545. static bool exists(const TQString &fullPath);
  546. /**
  547. * Expands all symbolic links and resolves references to
  548. * '/./', '/../' and extra '/' characters in @p dirname
  549. * and returns the canonicalized absolute pathname.
  550. * The resulting path will have no symbolic link, '/./'
  551. * or '/../' components.
  552. * @since 3.1
  553. */
  554. static TQString realPath(const TQString &dirname);
  555. /**
  556. * Expands all symbolic links and resolves references to
  557. * '/./', '/../' and extra '/' characters in @p filename
  558. * and returns the canonicalized absolute pathname.
  559. * The resulting path will have no symbolic link, '/./'
  560. * or '/../' components.
  561. * @since 3.4
  562. */
  563. static TQString realFilePath(const TQString &filename);
  564. private:
  565. TQStringList prefixes;
  566. // Directory dictionaries
  567. TQDict<TQStringList> absolutes;
  568. TQDict<TQStringList> relatives;
  569. mutable TQDict<TQStringList> dircache;
  570. mutable TQDict<TQString> savelocations;
  571. // Disallow assignment and copy-construction
  572. KStandardDirs( const KStandardDirs& );
  573. KStandardDirs& operator= ( const KStandardDirs& );
  574. bool addedCustoms;
  575. class KStandardDirsPrivate;
  576. KStandardDirsPrivate *d;
  577. void checkConfig() const;
  578. void applyDataRestrictions(const TQString &) const;
  579. void createSpecialResource(const char*);
  580. // Like their public counter parts but with an extra priority argument
  581. // If priority is true, the directory is added directly after
  582. // $TDEHOME/$XDG_DATA_HOME/$XDG_CONFIG_HOME
  583. void addPrefix( const TQString& dir, bool priority );
  584. void addXdgConfigPrefix( const TQString& dir, bool priority );
  585. void addXdgDataPrefix( const TQString& dir, bool priority );
  586. // If priority is true, the directory is added before any other,
  587. // otherwise after
  588. bool addResourceType( const char *type,
  589. const TQString& relativename, bool priority );
  590. bool addResourceDir( const char *type,
  591. const TQString& absdir, bool priority);
  592. };
  593. /**
  594. * \addtogroup locates Locate Functions
  595. * @{
  596. * On The Usage Of 'locate' and 'locateLocal'
  597. *
  598. * Typical KDE applications use resource files in one out of
  599. * three ways:
  600. *
  601. * 1) A resource file is read but is never written. A system
  602. * default is supplied but the user can override this
  603. * default in his local .kde directory:
  604. *
  605. * \code
  606. * // Code example
  607. * myFile = locate("appdata", "groups.lst");
  608. * myData = myReadGroups(myFile); // myFile may be null
  609. * \endcode
  610. *
  611. * 2) A resource file is read and written. If the user has no
  612. * local version of the file the system default is used.
  613. * The resource file is always written to the users local
  614. * .kde directory.
  615. *
  616. * \code
  617. * // Code example
  618. * myFile = locate("appdata", "groups.lst")
  619. * myData = myReadGroups(myFile);
  620. * ...
  621. * doSomething(myData);
  622. * ...
  623. * myFile = locateLocal("appdata", "groups.lst");
  624. * myWriteGroups(myFile, myData);
  625. * \endcode
  626. *
  627. * 3) A resource file is read and written. No system default
  628. * is used if the user has no local version of the file.
  629. * The resource file is always written to the users local
  630. * .kde directory.
  631. *
  632. * \code
  633. * // Code example
  634. * myFile = locateLocal("appdata", "groups.lst");
  635. * myData = myReadGroups(myFile);
  636. * ...
  637. * doSomething(myData);
  638. * ...
  639. * myFile = locateLocal("appdata", "groups.lst");
  640. * myWriteGroups(myFile, myData);
  641. * \endcode
  642. **/
  643. /*!
  644. * \relates KStandardDirs
  645. * This function is just for convenience. It simply calls
  646. *instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename).
  647. **/
  648. TDECORE_EXPORT TQString locate( const char *type, const TQString& filename, const KInstance* instance = KGlobal::instance() );
  649. /*!
  650. * \relates KStandardDirs
  651. * This function is much like locate. However it returns a
  652. * filename suitable for writing to. No check is made if the
  653. * specified filename actually exists. Missing directories
  654. * are created. If filename is only a directory, without a
  655. * specific file, filename must have a trailing slash.
  656. *
  657. **/
  658. TDECORE_EXPORT TQString locateLocal( const char *type, const TQString& filename, const KInstance* instance = KGlobal::instance() );
  659. /*!
  660. * \relates KStandardDirs
  661. * This function is much like locate. No check is made if the
  662. * specified filename actually exists. Missing directories
  663. * are created if @p createDir is true. If filename is only
  664. * a directory, without a specific file,
  665. * filename must have a trailing slash.
  666. *
  667. **/
  668. TDECORE_EXPORT TQString locateLocal( const char *type, const TQString& filename, bool createDir, const KInstance* instance = KGlobal::instance() );
  669. /*! @} */
  670. #endif // SSK_KSTDDIRS_H