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
29class 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 */
92class KDECORE_EXPORT KTemporaryFile : public QTemporaryFile
93{
94public:
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
135private:
136 KTemporaryFilePrivate *const d;
137};
138
139#endif
140