libs/flake

KoShapeFactory Class Reference

A factory for KoShape objects. More...

#include <KoShapeFactory.h>

Inheritance diagram for KoShapeFactory:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 KoShapeFactory (QObject *parent, const QString &id, const QString &name)
virtual ~KoShapeFactory ()
KoShape * createDefaultShapeAndInit (const QMap< QString, KoDataCenter * > &dataCenterMap) const
KoShape * createShapeAndInit (const KoProperties *params, const QMap< QString, KoDataCenter * > &dataCenterMap) const
virtual QList
< KoShapeConfigWidgetBase * > 		createShapeOptionPanels ()
QString family () const
virtual bool hidden () const
QString icon () const
QString id () const
quint32 loadingPriority () const
QString name () const
QStringList odfElementNames () const
const QString & odfNameSpace () const
const QList
< KoShapeConfigFactory * > & 		panelFactories ()
virtual void populateDataCenterMap (QMap< QString, KoDataCenter * > &dataCenterMap)
void setOptionPanels (QList< KoShapeConfigFactory * > &panelFactories)
virtual bool supports (const KoXmlElement &e) const
const QList< KoShapeTemplate > templates () const
QString toolTip () const

Protected Member Functions

void addTemplate (KoShapeTemplate &params)
virtual KoShape * createDefaultShape () const =0
virtual KoShape * createShape (const KoProperties *params) const =0
void setFamily (const QString &family)
void setIcon (const QString &iconName)
void setLoadingPriority (quint32 priority)
void setOdfElementNames (const QString &nameSpace, const QStringList &elementNames)
void setToolTip (const QString &tooltip)

Detailed Description

A factory for KoShape objects.

The baseclass for all shape plugins. Each plugin that ships a KoShape should also ship a factory. That factory will extend this class and set variable data like a toolTip and icon in the constructor of that extending class.

An example usage would be: 

class MyShapeFactory : public KoShapeFactory {
public:
    MyShapeFactory(QObject *parent)
        : KoShapeFactory(parent, "MyShape", i18n("My Shape")) {
        setToolTip(i18n("A nice shape"));
    }
    ~MyShapeFactory() {}
    // more methods here
};

After you created the factory you should create a plugin that can announce the factory to the KoShapeRegistry. See the KoPluginLoader as well.

Definition at line 88 of file KoShapeFactory.h.

Constructor & Destructor Documentation

KoShapeFactory::KoShapeFactory ( QObject *  parent,
const QString &  id,
const QString &  name 
)

Create the new factory.

Parameters:
parent the parent QObject for memory management usage.
id a string that will be used internally for referencing the shape, for example for use by the KoTool::activateTemporary.
name the user visible name of the shape this factory creates.

Definition at line 57 of file KoShapeFactory.cpp.

KoShapeFactory::~KoShapeFactory (  )  [virtual]

Definition at line 63 of file KoShapeFactory.cpp.

Member Function Documentation

void KoShapeFactory::addTemplate ( KoShapeTemplate &  params  )  [protected]

Add a template with the properties of a speficic type of shape this factory can generate using the createShape() method.

Parameters:
params the new template this factory knows to produce

Definition at line 127 of file KoShapeFactory.cpp.

virtual KoShape* KoShapeFactory::createDefaultShape (  )  const [protected, pure virtual]

This method should be implemented by factories to create a shape that the user gets when doing a base insert.

For example from a script. The created shape should have its values set to good defaults that the user can then adjust further if needed. Including the KoShape:setShapeId(), with the Id from this factory The default shape position is not relevant, it will be moved by the caller.

Returns:
a new shape

Implemented in KoConnectionShapeFactory, and KoPathShapeFactory.

KoShape * KoShapeFactory::createDefaultShapeAndInit ( const QMap< QString, KoDataCenter * > &  dataCenterMap  )  const

This method should be called to create a shape that the user gets when doing a base insert.

For example from a script or during loading.

This function will call init on the shape with the dataCenterMap that was given. You should make sure to pass the dataCenterMap so that all works as expected. However in some cases it is ok to not pass the shapeController e.g. when it is only a temporary shape that will not be inserted in the document. The shape can then set things that e.g. need to be available during loading of the shape. This method internally calls createShape( params );

Parameters:
dataCenterMap The dataCenterMap of the document.
Returns:
a new shape
See also:
KoShapeFactory::createDefaultShape
KoShape::init

Definition at line 68 of file KoShapeFactory.cpp.

virtual KoShape* KoShapeFactory::createShape ( const KoProperties *  params  )  const [protected, pure virtual]

This method should be implemented by factories to create a shape based on a set of properties that are specifically made for this shape-type.

This method should also set this factories shapeId on the shape using KoShape::setShapeId()

Returns:
a new shape
See also:
KoShapeTemplate::properties

Implemented in KoConnectionShapeFactory, and KoPathShapeFactory.

KoShape * KoShapeFactory::createShapeAndInit ( const KoProperties *  params,
const QMap< QString, KoDataCenter * > &  dataCenterMap 
) const

This method should be called to create a shape based on a set of properties that are specifically made for this shape-type.

This function will call init on the shape with the dataCenterMap that was given. You should make sure to pass the dataCenterMap so that all works as expected. However in some cases it is ok to not pass the shapeController e.g. when it is only a temporary shape that will not be inserted in the document. The shape can then set things that e.g. need to be available during loading of the shape. This method internally calls createShape( params );

Parameters:
params The properties to used to create the shape
dataCenterMap The dataCenterMap of the document.
Returns:
a new shape
See also:
KoShapeFactory::createShape
KoShapeTemplate::properties
KoShape::init

Definition at line 76 of file KoShapeFactory.cpp.

virtual QList<KoShapeConfigWidgetBase*> KoShapeFactory::createShapeOptionPanels (  )  [inline, virtual]

Create a list of option panels to show on creating a new shape.

The shape type this factory creates may have general or specific setting panels that will be shown after inserting a new shape. The first item in the list will be shown as the first tab in the list of panels, behind all app specific panels. This is a separate list as set by setOptionPanels() and fetched by panelFactories()

Reimplemented in KoConnectionShapeFactory.

Definition at line 153 of file KoShapeFactory.h.

QString KoShapeFactory::family (  )  const

return the non-visible name of the family the default shape belongs to.

Returns:
the family name.

Definition at line 99 of file KoShapeFactory.cpp.

bool KoShapeFactory::hidden (  )  const [virtual]

This functions decides if the shape should be shown in the shape selector or not.

The default implementation returns false.

Definition at line 179 of file KoShapeFactory.cpp.

QString KoShapeFactory::icon (  )  const

return the basename of the icon for a selector of shapes

Returns:
the basename of the icon for a selector of shapes

Definition at line 89 of file KoShapeFactory.cpp.

QString KoShapeFactory::id (  )  const

return the id for the shape this factory creates.

Returns:
the id for the shape this factory creates.

Definition at line 148 of file KoShapeFactory.cpp.

quint32 KoShapeFactory::loadingPriority (  )  const

lower prio means the shape is more generic and will be checked later

Definition at line 104 of file KoShapeFactory.cpp.

QString KoShapeFactory::name (  )  const

return the user visible (and translated) name to be seen by the user.

Returns:
the user visible (and translated) name to be seen by the user.

Definition at line 94 of file KoShapeFactory.cpp.

QStringList KoShapeFactory::odfElementNames (  )  const

the name used for quick checking if this shapeFactory is able to load Odf data identified by the element name.

Definition at line 109 of file KoShapeFactory.cpp.

const QString & KoShapeFactory::odfNameSpace (  )  const

The namespace that the elements supported by the shape created by this factory should be in.

Definition at line 114 of file KoShapeFactory.cpp.

const QList< KoShapeConfigFactory * > & KoShapeFactory::panelFactories (  ) 

Return the app-specific panels.

See also:
setOptionPanels()

Definition at line 158 of file KoShapeFactory.cpp.

virtual void KoShapeFactory::populateDataCenterMap ( QMap< QString, KoDataCenter * > &  dataCenterMap  )  [inline, virtual]

pouplates the dataCenterMap with any datacenters the shapes might need.

The default implementation does nothing

Parameters:
dataCenterMap The map which the shapeControllerBase owns.

Reimplemented in KoPathShapeFactory.

Definition at line 185 of file KoShapeFactory.h.

void KoShapeFactory::setFamily ( const QString &  family  )  [protected]

Set the family name of the default shape.

Parameters:
family the family name of the default shape this factory creates. for example "funny", "arrows", "geometrics". Use "" for default

Definition at line 143 of file KoShapeFactory.cpp.

void KoShapeFactory::setIcon ( const QString &  iconName  )  [protected]

Set an icon to be used in a selector of shapes.

Parameters:
iconName the basename (without extension) of the icon
See also:
KIconLoader

Definition at line 138 of file KoShapeFactory.cpp.

void KoShapeFactory::setLoadingPriority ( quint32  priority  )  [protected]

Set the loading priority for this icon; higher priority means the shape is more specific which means it will be earlier in the queue to try loading a particular odf element.

Definition at line 168 of file KoShapeFactory.cpp.

void KoShapeFactory::setOdfElementNames ( const QString &  nameSpace,
const QStringList &  elementNames 
) [protected]

Set the name used for quick checking whether this shapefactory is able to create a shape from xml identified by this element name.

Parameters:
nameSpace the ODF name space (like urn:oasis:names:tc:opendocument:xmlns:text:1.0, take it from KoXmlNS.h)
elementNames the name of the element itself, like "draw"

Definition at line 173 of file KoShapeFactory.cpp.

void KoShapeFactory::setOptionPanels ( QList< KoShapeConfigFactory * > &  panelFactories  ) 

Set app specific panel factories to show config options after creating a new shape.

The application that lets the user create shapes is able to set option widgets that will be shown after the user inserted a new shape of the type that this factory presents. Example: 

  // Init shape Factories with our frame based configuration panels.
  QList<KoShapeConfigFactory *> panels;
  panels.append(new AppConfigFactory()); // insert some factory
  foreach(QString id, KoShapeRegistry::instance()->keys())
      KoShapeRegistry::instance()->value(id)->setOptionPanels(panels);
See also:
panelFactories()

Definition at line 153 of file KoShapeFactory.cpp.

void KoShapeFactory::setToolTip ( const QString &  tooltip  )  [protected]

Set the tooltip to be used for a selector of shapes.

Parameters:
tooltip the tooltip

Definition at line 133 of file KoShapeFactory.cpp.

bool KoShapeFactory::supports ( const KoXmlElement &  e  )  const [virtual]

returns true if this shapeFactory is able to load the ODF type started at argument element.

('draw:line' / 'draw:frame' / etc)

Reimplemented in KoConnectionShapeFactory, and KoPathShapeFactory.

Definition at line 119 of file KoShapeFactory.cpp.

const QList< KoShapeTemplate > KoShapeFactory::templates (  )  const

Return all the templates this factory knows about.

Each template shows a different way to create a shape this factory is specialized in.

Definition at line 163 of file KoShapeFactory.cpp.

QString KoShapeFactory::toolTip (  )  const

return a translated tooltip Text for a selector of shapes

Returns:
a translated tooltip Text

Definition at line 84 of file KoShapeFactory.cpp.

The documentation for this class was generated from the following files: