← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/kdebase-workspace/gutsy

« back to all changes in this revision

Viewing changes to libs/plasma/packagestructure.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2007-09-05 20:45:14 UTC
  • Revision ID: james.westby@ubuntu.com-20070905204514-632hhspl0nvrc84i
Tags: upstream-3.93.0
Import upstream version 3.93.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/plasma/packagestructure.h
 
1
/******************************************************************************
 
2
*   Copyright 2007 by Aaron Seigo <aseigo@kde.org>                        *
 
3
*                                                                             *
 
4
*   This library is free software; you can redistribute it and/or             *
 
5
*   modify it under the terms of the GNU Library General Public               *
 
6
*   License as published by the Free Software Foundation; either              *
 
7
*   version 2 of the License, or (at your option) any later version.          *
 
8
*                                                                             *
 
9
*   This library is distributed in the hope that it will be useful,           *
 
10
*   but WITHOUT ANY WARRANTY; without even the implied warranty of            *
 
11
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU          *
 
12
*   Library General Public License for more details.                          *
 
13
*                                                                             *
 
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
 
 
20
#ifndef PACKAGESTRUCTURE_H
 
21
#define PACKAGESTRUCTURE_H
 
22
 
 
23
#include <QtCore/QStringList>
 
24
 
 
25
#include <plasma/plasma_export.h>
 
26
 
 
27
namespace Plasma
 
28
{
 
29
 
 
30
/**
 
31
 * @brief A description of the expected file structure of a given package type
 
32
 *
 
33
 * PackageStructure defines what is in a package. This information is used
 
34
 * to create packages and provides a way to programatically refer to contents.
 
35
 *
 
36
 * An example usage of this class might be:
 
37
 *
 
38
 @code
 
39
    PackageStructure structure;
 
40
 
 
41
    structure.addDirectoryDefinition("images", "pics/", i18n("Images"));
 
42
    QStringList mimetypes;
 
43
    mimetypes << "image/svg" << "image/png" << "image/jpeg";
 
44
    structure.setMimetypes("images", mimetypes);
 
45
 
 
46
    structure.addDirectoryDefinition("scripts", "code/", i18n("Executable Scripts"));
 
47
    mimetypes.clear();
 
48
    mimetypes << "text/\*";
 
49
    structure.setMimetypes("scripts", mimetypes);
 
50
 
 
51
    structure.addFileDefinition("mainscript", "code/main.js", i18n("Main Script File"));
 
52
    structure.setRequired("mainscript", true);
 
53
 @endcode
 
54
 * One may also choose to create a subclass of PackageStructure and include the setup
 
55
 * in the constructor.
 
56
 *
 
57
 * Either way, PackageStructure creates a sort of "contract" between the packager and
 
58
 * the application which is also self-documenting.
 
59
 **/
 
60
class PLASMA_EXPORT PackageStructure
 
61
{
 
62
public:
 
63
    /**
 
64
     * Default constructor for a package structure definition
 
65
     *
 
66
     * @arg type the type of package. This is often application specific.
 
67
     **/
 
68
    PackageStructure(const QString &type);
 
69
 
 
70
    /**
 
71
     * Type of package this structure describes
 
72
     **/
 
73
    QString type();
 
74
 
 
75
    /**
 
76
     * The directories defined for this package
 
77
     **/
 
78
    QStringList directories();
 
79
 
 
80
    /**
 
81
     * The required directories defined for this package
 
82
     **/
 
83
    QStringList requiredDirectories();
 
84
 
 
85
    /**
 
86
     * The individual files defined for this package
 
87
     **/
 
88
    QStringList files();
 
89
 
 
90
    /**
 
91
     * The individual required files defined for this package
 
92
     **/
 
93
    QStringList requiredFiles();
 
94
 
 
95
    /**
 
96
     * Adds a directory to the structure of the package. It is added as
 
97
     * a not-required element with no associated mimetypes.
 
98
     *
 
99
     * @param key  used as an internal label for this directory
 
100
     * @param path the path within the the package for this directory
 
101
     * @param name the user visible (translated) name for the directory
 
102
     **/
 
103
    void addDirectoryDefinition(const char* key, const QString& path, const QString& name);
 
104
 
 
105
    /**
 
106
     * Adds a file to the structure of the package. It is added as
 
107
     * a not-required element with no associated mimetypes.
 
108
     *
 
109
     * @param key  used as an internal label for this file
 
110
     * @param path the path within the the package for this file
 
111
     * @param name the user visible (translated) name for the file
 
112
     **/
 
113
    void addFileDefinition(const char* key, const QString& path, const QString& name);
 
114
 
 
115
    /**
 
116
     * @return path relative to the package root for the given entry
 
117
     **/
 
118
    QString path(const char* key);
 
119
 
 
120
    /**
 
121
     * @return user visible name for the given entry
 
122
     **/
 
123
    QString name(const char* key);
 
124
 
 
125
    /**
 
126
     * Sets whether or not a given part of the structure is required or not.
 
127
     * The path must already have been added using addDirectoryDefinition
 
128
     * or addFileDefinition.
 
129
     *
 
130
     * @param path the path of the entry within the package
 
131
     * @param required true if this entry is required, false if not
 
132
     */
 
133
    void setRequired(const char* key, bool required);
 
134
 
 
135
    /**
 
136
     * @return true if the item at path exists and is required
 
137
     **/
 
138
    bool required(const char* key);
 
139
 
 
140
    /**
 
141
     * Defines the default mimetypes for any definitions that do not have
 
142
     * associated mimetypes. Handy for packages with only one or predominantly
 
143
     * one file type.
 
144
     *
 
145
     * @param mimetypes a list of mimetypes
 
146
     **/
 
147
    void setDefaultMimetypes(QStringList mimetypes);
 
148
 
 
149
    /**
 
150
     * Define mimetypes for a given part of the structure
 
151
     * The path must already have been added using addDirectoryDefinition
 
152
     * or addFileDefinition.
 
153
     * 
 
154
     * @param path the path of the entry within the package
 
155
     * @param mimetypes a list of mimetypes
 
156
     **/
 
157
    void setMimetypes(const char* key, QStringList mimetypes);
 
158
 
 
159
    /**
 
160
     * @return the mimetypes associated with the path, if any
 
161
     **/
 
162
    QStringList mimetypes(const char* key);
 
163
 
 
164
    /**
 
165
     * Copy constructor
 
166
     **/
 
167
    PackageStructure(const PackageStructure& rhs);
 
168
 
 
169
    /**
 
170
     * Destructor
 
171
     **/
 
172
    virtual ~PackageStructure();
 
173
 
 
174
    /**
 
175
     * Assignment operator
 
176
     **/
 
177
    PackageStructure& operator=(const PackageStructure& rhs);
 
178
 
 
179
private:
 
180
     class Private;
 
181
     Private * const d;
 
182
};
 
183
 
 
184
} // Plasma namespace
 
185
#endif