1 | /* kate: tab-indents off; replace-tabs on; tab-width 4; remove-trailing-space on; encoding utf-8;*/ |
2 | /* This file is part of the KDE libraries |
3 | * Copyright 2006 Jaison Lee <lee.jaison@gmail.com> |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Library General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2 of the License, or (at your option) any later version. |
9 | * |
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 | * |
15 | * You should have received a copy of the GNU Library General Public License |
16 | * along with this library; see the file COPYING.LIB. If not, write to |
17 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | * Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef ktemporaryfile_h |
22 | #define ktemporaryfile_h |
23 | |
24 | #include <kdecore_export.h> |
25 | #include <kglobal.h> |
26 | |
27 | #include <QtCore/QTemporaryFile> |
28 | |
29 | class KTemporaryFilePrivate; |
30 | |
31 | /** |
32 | * \class KTemporaryFile ktemporaryfile.h <KTemporaryFile> |
33 | * |
34 | * @brief A QTemporaryFile that will save in the KDE temp directory. |
35 | * |
36 | * This class derives from QTemporaryFile and makes sure that your temporary |
37 | * files go in the temporary directory defined by KDE. (This is retrieved by |
38 | * using KStandardDirs to locate the "tmp" resource.) In general, whenever you |
39 | * would use a QTemporaryFile() use a KTemporaryFile() instead. |
40 | * |
41 | * By default the filename will start with your application's instance name, |
42 | * followed by six random characters and an extension of ".tmp". You can use |
43 | * setPrefix() and setSuffix() to change the beginning and ending of the random |
44 | * name, as well as change the directory if you wish (read the descriptions of |
45 | * these functions for more information). For complex specifications, you may |
46 | * be better off calling QTemporaryFile::setFileTemplate() directly. |
47 | * |
48 | * For example, let's make a new temporary file: |
49 | * |
50 | * @code |
51 | * KTemporaryFile temp; |
52 | * @endcode |
53 | * |
54 | * This temporary file will currently be stored in the default KDE temporary |
55 | * directory and have an extension of ".tmp". Now, let's change the directory: |
56 | * |
57 | * @code |
58 | * temp.setPrefix("/var/lib/foodata/"); |
59 | * @endcode |
60 | * |
61 | * Now the temporary file will be stored in "/var/lib/foodata" instead of the |
62 | * default KDE temporary directory, with an extension of ".tmp". It's important |
63 | * to remember the leading and trailing slashes to properly define the path! |
64 | * Next, let's change the suffix to a particular extension: |
65 | * |
66 | * @code |
67 | * temp.setSuffix(".pdf"); |
68 | * @endcode |
69 | * |
70 | * Now the temporary file will be stored in "/var/lib/foodata" and have an |
71 | * extension of ".pdf" instead of ".tmp". |
72 | * |
73 | * Once you are done determining the name of the file, call open() to |
74 | * create the file. |
75 | * |
76 | * @code |
77 | * if ( !temp.open() ) { |
78 | * // handle error... |
79 | * } |
80 | * @endcode |
81 | * |
82 | * If open() is unable to create the file it will return false. If the call to |
83 | * open() returns true you are ready to use your temporary file. If you don't |
84 | * want the file removed automatically when the KTemporaryFile object is |
85 | * destroyed, you need to call setAutoRemove(false), but make sure you have a |
86 | * good reason for leaving your temp files around. |
87 | * |
88 | * @see QTemporaryFile |
89 | * |
90 | * @author Jaison Lee <lee.jaison@gmail.com> |
91 | */ |
92 | class KDECORE_EXPORT KTemporaryFile : public QTemporaryFile |
93 | { |
94 | public: |
95 | /** |
96 | * Construct a new KTemporaryFile. The file will be stored in the temporary |
97 | * directory configured in KDE. The default prefix is the value of the |
98 | * default KDE temporary directory, plus your application's instance name. |
99 | * The default suffix is ".tmp". |
100 | * |
101 | * \param componentData The KComponentData to use for the name of the file and to look up the |
102 | * directory. |
103 | */ |
104 | explicit KTemporaryFile(const KComponentData &componentData = KGlobal::mainComponent()); |
105 | |
106 | /** |
107 | * Destructor. |
108 | */ |
109 | virtual ~KTemporaryFile(); |
110 | |
111 | /** |
112 | * @brief Sets a prefix to use when creating the file. |
113 | * |
114 | * This function sets a prefix to use when creating the file. The random |
115 | * part of the filename will come after this prefix. The prefix can also |
116 | * change or modify the target directory. If @p prefix is an absolute |
117 | * path it will override the default temporary directory. If @p prefix is |
118 | * a relative directory it will be relative to the default temporary |
119 | * location. To set a relative directory for the current working directory |
120 | * you should use QTemporaryFile::setFileTemplate() directly. |
121 | * @param prefix The prefix to use when creating the file. Remember to |
122 | * end the prefix with a '/' if you are designating a directory. |
123 | */ |
124 | void setPrefix(const QString &prefix); |
125 | |
126 | /** |
127 | * @brief Sets a suffix to use when creating the file. |
128 | * |
129 | * Sets a suffix to use when creating the file. The random part of the |
130 | * filename will come before this suffix. |
131 | * @param suffix The suffix to use when creating the file. |
132 | */ |
133 | void setSuffix(const QString &suffix); |
134 | |
135 | private: |
136 | KTemporaryFilePrivate *const d; |
137 | }; |
138 | |
139 | #endif |
140 | |