← Back to branch summary

~ubuntu-branches/ubuntu/precise/koffice/precise

« back to all changes in this revision

Viewing changes to lib/koproperty/factory.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2006-04-20 21:38:53 UTC
  • mfrom: (1.1.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20060420213853-j5lxluqvymxt2zny
Tags: 1:1.5.0-0ubuntu2
Ubuntu upload 

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/koproperty/factory.h
 
1
/* This file is part of the KDE project
 
2
   Copyright (C) 2004 Cedric Pasteur <cedric.pasteur@free.fr>
 
3
   Copyright (C) 2004 Alexander Dymo <cloudtemple@mskat.net>
 
4
   Copyright (C) 2005 Jaroslaw Staniek <js@iidea.pl>
 
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 KPROPERTY_FACTORY_H
 
23
#define KPROPERTY_FACTORY_H
 
24
 
 
25
#include "koproperty_global.h"
 
26
#include <kstaticdeleter.h> 
 
27
#include <qobject.h> 
 
28
 
 
29
template<class U> class QValueList;
 
30
 
 
31
namespace KoProperty {
 
32
 
 
33
class Widget;
 
34
class CustomProperty;
 
35
class Property;
 
36
class FactoryManagerPrivate;
 
37
 
 
38
///*! A pointer to factory function which creates and returns widget for a given property type.*/
 
39
//typedef Widget *(*createWidget) (Property*);
 
40
//typedef CustomProperty *(*createCustomProperty) (Property*);
 
41
 
 
42
//! \brief A prototype for custom property factory
 
43
class KOPROPERTY_EXPORT CustomPropertyFactory : public QObject
 
44
{
 
45
        public:
 
46
                CustomPropertyFactory(QObject *parent);
 
47
                virtual ~CustomPropertyFactory();
 
48
 
 
49
                /*! \return a new instance of custom property for \a parent. 
 
50
                 Implement this for property types you want to support. 
 
51
                 Use parent->type() to get type of the property. */
 
52
                virtual CustomProperty* createCustomProperty(Property *parent) = 0;
 
53
 
 
54
                /*! \return a new instance of custom property for \a property. 
 
55
                 Implement this for property editor types you want to support. 
 
56
                 Use parent->type() to get type of the property. */
 
57
                virtual Widget* createCustomWidget(Property *property) = 0;
 
58
};
 
59
 
 
60
//! \brief Manages factories providing custom editors and properties.
 
61
/*! This class is static, you don't need to create an instance of it. It's used to enable the
 
62
     custom property/editors system.
 
63
     You may want to create your own property types and/or editors to:
 
64
 
 
65
     - Create your own editors for some special kind of properties, not included in
 
66
       KProperty basic editors;
 
67
 
 
68
     - Create composed properties, which contain more than one value. Child
 
69
       items will then be created in the Editor (that's how rect, size properties are created).
 
70
 
 
71
     \section custom_prop Using Custom Properties
 
72
     To create a custom property, create a subclass of \ref CustomProperty class. You need to implement
 
73
     some virtual functions, to customise the behaviour of your property 
 
74
     (see \ref CustomProperty api doc).
 
75
     If you create a composed property, both parent and children properties must have custom 
 
76
     (different) types. \n
 
77
     Then, you need to register the new created type, using \ref registerFactoryForProperty(). 
 
78
     The second parameter is an instance of CustomPropertyFactory-derived class 
 
79
     implementing createCustomProperty() method.\n
 
80
     To create a property of this type, just use the normal constructor, overriding 
 
81
     the type parameter with the type you registered.
 
82
 
 
83
     \section custom_editor Using Custom Editors
 
84
     First, create a subclass of Widget, and implement all the virtuals you need to tweak
 
85
     the property editor. You can find examples of editors in the src/editors/ directory.\n
 
86
     Then, register it using \ref registerFactoryForEditor(), as for properties (see test/ dir 
 
87
     for an example of custom editor). You can also register a new editor for a basic type, 
 
88
     if the basic editor doesn't fit your needs (if you have created a better editor, 
 
89
     send us the code, and it may get included in KProperty library).\n
 
90
     Every time a property of this type is created, createCustomWidget() method for 
 
91
     the custom CustomPropertyFactory-derived factory object you registered will be called 
 
92
     to create the custom editor widget item.
 
93
 
 
94
   \author Cedric Pasteur <cedric.pasteur@free.fr>
 
95
   \author Alexander Dymo <cloudtemple@mskat.net>
 
96
 */
 
97
class KOPROPERTY_EXPORT FactoryManager : public QObject
 
98
{
 
99
        public:
 
100
                /*! Registers a custom factory \a factory for handling property editor for \a editorType.
 
101
                This custom factory will be used before defaults when widgetForProperty() is called. 
 
102
                \a creator is not owned by this Factory object, but it's good idea 
 
103
                to instantiate CustomPropertyFactory object itself as a child of Factory parent. For example:
 
104
                \code
 
105
                        MyCustomPropertyFactory *f = new MyCustomPropertyFactory(KoProperty::Factory::self());
 
106
                        KoProperty::Factory::self()->registerEditor( MyCustomType, f );
 
107
                \endcode */
 
108
                void registerFactoryForEditor(int editorType, CustomPropertyFactory *factory);
 
109
 
 
110
                /*! Registers custom factory \a factory for handling property editors for \a editorTypes.
 
111
                 @see registerFactoryForEditor(). */
 
112
                void registerFactoryForEditors(const QValueList<int> &editorTypes, CustomPropertyFactory *factory);
 
113
 
 
114
                /*! \return custom factory for type \a type or NULL if there 
 
115
                 is no such property type registered. 
 
116
                 To create a custom widget createWidgetForProperty() should be rather used. */
 
117
                CustomPropertyFactory *factoryForEditorType(int type);
 
118
 
 
119
                /*! Creates and returns the editor for given property type.
 
120
                Warning: editor and viewer widgets won't have parent widget. Property editor
 
121
                cares about reparenting and deletion of returned widgets in machines.
 
122
                If \a createWidget is false, just create child properties, not widget.*/
 
123
                Widget* createWidgetForProperty(Property *property);
 
124
 
 
125
                /*! Registers a custom factory that handles a CustomProperty of a type \a type.
 
126
                 This function will be called every time a property of \a type is created. */
 
127
                void registerFactoryForProperty(int propertyType, CustomPropertyFactory *factory);
 
128
 
 
129
                /*! Registers a custom property factory that handles a CustomProperty for \a types.
 
130
                 @see registerFactoryForProperty() */
 
131
                void registerFactoryForProperties(const QValueList<int> &propertyTypes, 
 
132
                        CustomPropertyFactory *factory);
 
133
 
 
134
                /*! This function is called in Property::Property() to create (optional)
 
135
                  custom property. It creates the custom property for built-in types, or
 
136
                  calls one of createCustomProperty function previously registered for other types. */
 
137
                CustomProperty* createCustomProperty(Property *parent);
 
138
 
 
139
                /*! \return a pointer to a property factory instance.*/
 
140
                static FactoryManager* self();
 
141
 
 
142
        private:
 
143
                FactoryManager();
 
144
                ~FactoryManager();
 
145
 
 
146
                FactoryManagerPrivate *d;
 
147
                friend class KStaticDeleter<KoProperty::FactoryManager>;
 
148
};
 
149
 
 
150
}
 
151
 
 
152
#endif