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