1 /* This file is part of the KDE project
2    Copyright (C) 2003 Lucijan Busch <lucijan@gmx.at>
3    Copyright (C) 2004 Cedric Pasteur <cedric.pasteur@free.fr>
4    Copyright (C) 2004-2017 Jarosław Staniek <staniek@kde.org>
5 
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 
11    This library is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Library General Public License for more details.
15 
16    You should have received a copy of the GNU Library General Public License
17    along with this library; see the file COPYING.LIB.  If not, write to
18    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20 */
21 
22 #ifndef KFORMDESIGNERWIDGETINFO_H
23 #define KFORMDESIGNERWIDGETINFO_H
24 
25 #include "kformdesigner_export.h"
26 
27 #include <KDbTristate>
28 
29 #include <QHash>
30 
31 namespace KFormDesigner
32 {
33 
34 class WidgetFactory;
35 class WidgetLibrary;
36 
37 //! A class providing properties of a single widget class offered by a factory
38 class KFORMDESIGNER_EXPORT WidgetInfo
39 {
40 public:
41     explicit WidgetInfo(WidgetFactory *f);
42 
43     virtual ~WidgetInfo();
44 
45     //! \return the name of the icon associated with the widget
46     QString iconName() const;
47 
48     void setIconName(const QString &iconName);
49 
50     //! @return the class name of a widget e.g. "LineEdit"
51     QByteArray className() const;
52 
53     void setClassName(const QByteArray& className);
54 
55     QByteArray inheritedClassName() const;
56 
57     void setInheritedClassName(const QByteArray& inheritedClassName);
58 
59     /**
60      * @return Untranslated name prefix used to generate unique names for widget instances
61      *
62      * Widget names appear in the property editor or in scripts and can be references there.
63      * Names and prefixes must be valid identifiers, as defined by KDb::isIdentifier().
64      *
65      * @see translatedNamePrefix()
66      */
67     QString namePrefix() const;
68 
69     /**
70      * Sets untranslated name prefix used to generate unique names for widget instances
71      *
72      * @a prefix must be a valid identifier, as defined by KDb::isIdentifier(). If it is not then
73      * real name prefix will be reset to "widget".
74      * Parameters of setNamePrefix() should be enclosed with I18N_NOOP2() to enable translation
75      * text extraction without actual translation of the argument. @a context parameter is unused;
76      * it's provided only to make I18N_NOOP2() work.
77      *
78      * Example use for a label class:
79      * @code
80      * setNamePrefix(
81      *      I18N_NOOP2("A prefix for identifiers of label widgets. Based on that, identifiers such as "
82      *          "label1, label2 are generated. "
83      *          "This string can be used to refer the widget object as variables in programming "
84      *          "languages or macros so it must _not_ contain white spaces and non latin1 characters, "
85      *          "should start with lower case letter and if there are subsequent words, these should "
86      *          "start with upper case letter. Example: smallCamelCase. "
87      *          "Moreover, try to make this prefix as short as possible.",
88      *          "label"));
89      * @endcode
90      *
91      * If translation of @a prefix for given locale is not a valid identifier, as defined by
92      * KDb::isIdentifier() then a warning is issued to the error channel and untranslated prefix is
93      * used, e.g. "label".
94      */
95     void setNamePrefix(const char *context, const char *prefix);
96 
97     /**
98      * @return Translated name prefix used to generate unique names for widget instances
99      *
100      * This string is created using i18n(namePrefix()). See setNamePrefix() for exceptional cases
101      * of invalid translations.
102      */
103     QString translatedNamePrefix() const;
104 
105     //! \return the real name e.g. 'Line Edit', showed eg in ObjectTreeView
106     QString name() const;
107 
108     void setName(const QString &n);
109 
110     QString description() const;
111 
112     void setDescription(const QString &desc);
113 
114     QString includeFileName() const;
115 
116     /*! Sets the C++ include file corresponding to this class,
117      that uic will need to add when creating the file. You don't have to set this for Qt std widgets.*/
118     void setIncludeFileName(const QString &name);
119 
120     QList<QByteArray> alternateClassNames() const;
121 
122     QByteArray savingName() const;
123 
124     WidgetFactory *factory() const;
125 
126     /*! Sets alternate names for this class.
127      If this name is found when loading a .ui file, the className() will be used instead.
128      It allows to support both KDE and Qt versions of widget, without duplicating code.
129      As a rule, className() should always return a class name which is inherited from
130      alternate class. For exampleQPushButton class has alternate KexiPushButton class.
131 
132      \a override parameter overrides class name of a widget,
133      even if it was implemented in other factory.
134      By default it's set to false, what means that no other class is overridden
135      by this widget class if there is already a class implementing it
136      (no matter in which factory).
137      By forced overriding existing class with other - custom, user
138      will be able to see more or less properties and experience different behaviour.
139      For example, in Kexi application, KexiDBPushButton class contains additional
140      properties.
141     */
142     void addAlternateClassName(const QByteArray& alternateName, bool override = false);
143 
144     /*! \return true if a class \a alternateName is defined as alternate name with
145      'override' flag set to true, using addAlternateClassName().
146      If this flag is set to false (the default) or there's no such alternate class
147      name defined. */
148     bool isOverriddenClassName(const QByteArray& alternateName) const;
149 
150     /*! Sets the name that will be written in the .ui file when saving.
151      This name must be one of alternate names (or loading will be impossible).
152 
153      On form data saving to XML .ui format, saveName is used instead,
154      so .ui format is not broken and still usable with other software as Qt Designer.
155      Custom properties are saved as well with 'stdset' attribute set to 0. */
156     void setSavingName(const QByteArray &saveName);
157 
158     /*! Sets autoSync flag for property \a propertyName.
159      This allows to override autoSync flag for certain widget's property, because
160      e.g. KPropertyEditorView can have autoSync flag set to false or true, but
161      not all properties have to comply with that.
162      \a flag equal to cancelled value means there is no overriding (the default). */
163     void setAutoSyncForProperty(const QByteArray& propertyName, tristate flag);
164 
165     /*! \return autoSync override value (true or false) for \a propertyName.
166      If cancelled value is returned, there is no overriding (the default). */
167     tristate autoSyncForProperty(const QByteArray& propertyName) const;
168 
169     QByteArray parentFactoryName() const;
170 
171     void setParentFactoryName(const QByteArray& factoryName);
172 
173     WidgetInfo* inheritedClass() const;
174 
175     /*! Sets custom type \a type for property \a propertyName.
176      This allows to override default type, especially when custom property
177      and custom property editor item has to be used. */
178     void setCustomTypeForProperty(const QByteArray& propertyName, int type);
179 
180     /*! \return custom type for property \a propertyName. If no specific custom type has been assigned,
181      KProperty::Auto is returned.
182      @see setCustomTypeForProperty() */
183     int customTypeForProperty(const QByteArray& propertyName) const;
184 
185     /*! @return list of the properties that should automatically be saved
186     for a widget of @a classname class.
187     Examples are: custom properties "text" for label or button, "contents" for combobox...
188     If there is inherited class (see @ref inheritedClass()), autosave properties
189     from that class are prepended to the list. */
190     QList<QByteArray> autoSaveProperties() const;
191 
192     /*! Sets list of the properties that should automatically be saved for a widget of @a classname class. */
193     void setAutoSaveProperties(const QList<QByteArray>& properties);
194 
195     /*! @return internal property @a property.
196      Internal properties are not stored within objects, but can be just provided
197      to describe class' details. */
198     QVariant internalProperty(const QByteArray& property) const;
199 
200     /*! Assigns @a value for internal property @a property.
201      Internal properties are not stored within objects, but can be provided
202      to describe class' details. */
203     void setInternalProperty(const QByteArray& property, const QVariant& value);
204 
205     /**
206      * @brief Returns @c alignment flags supports by the widget
207      *
208      * By default returns all possible flags minus Qt::AlignAbsolute.
209      * @see setSupportedAlignmentFlags
210      */
211     Qt::Alignment supportedAlignmentFlags() const;
212 
213     /**
214      * @brief Sets alignment flags supported by the widget
215      *
216      * Used for example by an image box that does not support justified, absolute and baseline
217      * alignment.
218      * @see supportedAlignmentFlags
219      */
220     void setSupportedAlignmentFlags(Qt::Alignment flags);
221 
222 protected:
223     void setInheritedClass(WidgetInfo *inheritedClass);
224 
225 private:
226     class Private;
227     Private * const d;
228 
229     friend class WidgetLibrary;
230 };
231 
232 } // namespace KFormDesigner
233 
234 #endif
235