You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
koffice/kexi/plugins/macros/lib/manager.h

220 lines
6.3 KiB

/***************************************************************************
* This file is part of the KDE project
* copyright (C) 2005 by Sebastian Sauer (mail@dipe.org)
* copyright (C) 2005 by Tobi Krebs (tobi.krebs@gmail.com)
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
* You should have received a copy of the GNU Library General Public License
* along with this program; see the file COPYING. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
***************************************************************************/
#ifndef KOMACRO_MANAGER_H
#define KOMACRO_MANAGER_H
#include <tqmap.h>
#include <tqguardedptr.h>
#include <ksharedptr.h>
#include <kxmlguiclient.h>
#include <kstaticdeleter.h>
#include "komacro_export.h"
class TQObject;
class TQDomElement;
namespace KoMacro {
// Forward declarations.
class Action;
class Macro;
/**
* The Manager class acts as window-wide manager for macros.
*
* Example how KoMacro could be used.
* @code
* // We have a class that inheritates from TQObject and
* // implements some public signals and slots that will
* // be accessible by Macros once a class-instance
* // got published.
* class PublishedObject : public TQObject {};
*
* // Somewhere we have our KMainWindow.
* KMainWindow* mainwindow = new KMainWindow();
*
* // Create a new KoMacro::Manager instance to access the
* // Macro-framework.
* KoMacro::Manager* manager = new KoMacro::Manager( mainwindow );
*
* // Now we like to publish a TQObject
* PublishedObject* publishedobject = new PublishedObject();
* manager->publishObject(publishedobject);
*
* // ... here we are able to use manager->createAction() to
* // create Action instances on the fly and work with them.
*
* // Finally free the publishedobject instance we created. We
* // need to free it manualy cause PublishedObject doesn't
* // got a TQObject parent as argument.
* delete publishedobject;
*
* // Finally free the manager-instance. It's always needed
* // to free the instance by yourself!
* delete manager;
* @endcode
*/
class KOMACRO_EXPORT Manager
{
friend class KStaticDeleter< ::KoMacro::Manager >;
private:
/**
* Constructor.
*
* @param xmlguiclient The KXMLGUIClient instance this
* @a Manager is associated with.
*/
explicit Manager(KXMLGUIClient* const xmlguiclient);
/**
* Destructor.
*/
virtual ~Manager();
public:
/**
* Initialize this \a Manager singleton. This function
* needs to be called exactly once to initialize the
* \a Manager singleton before \a self() got used.
*/
static void init(KXMLGUIClient* xmlguiclient);
/**
* @return a pointer to a Manager singleton-instance. The
* static method \a init() needs to be called exactly once
* before calling this method else we may return NULL .
*/
static Manager* self();
/**
* @return the KXMLGUIClient instance this @a Manager is
* associated with.
*/
KXMLGUIClient* guiClient() const;
/**
* \return true if we carry a \a Macro with the
* defined \p macroname .
*/
bool hasMacro(const TQString& macroname);
/**
* \return the \a Macro defined with \p macroname
* or NULL if we don't have such a \a Macro.
*/
KSharedPtr<Macro> getMacro(const TQString& macroname);
/**
* Add a new \a Macro to the list of known macros. If
* there exists already a \a Macro instance with the
* defined \p macroname then the already existing one
* will be replace.
*
* \param macroname The name the \a Macro will be
* accessible as.
* \param macro The \a Macro instance.
*/
void addMacro(const TQString& macroname, KSharedPtr<Macro> macro);
/**
* Remove the \a Macro defined with \p macroname . If
* we don't know about a \a Macro with that \p macroname
* nothing happens.
*/
void removeMacro(const TQString& macroname);
/**
* Factory function to create a new \a Macro instances.
* The returned new \a Macro instance will not be added
* to the list of known macros. Use \a addMacro if you
* like to attach the returned new \a Macro to this
* \a Manager instance.
*/
KSharedPtr<Macro> createMacro(const TQString& macroname);
#if 0
/**
* Factory method to create @a Action instances from the
* defined @p element .
*
* @param element The serialized TQDomElement that should
* be used to create the @a Action instance.
* @return A new @a Action instance or NULL if the
* defined @p element is not valid.
*
* @deprecated Moved to common XMLReader/XMLWriter classes. Use Macro::xmlHandler() !
*/
KSharedPtr<Action> createAction(const TQDomElement& element);
#endif
/**
* @return the @a Action which was published under the
* name @p name or returns an empty @a KSharedPtr<Action> object
* if there was no such @a Action published.
*/
KSharedPtr<Action> action(const TQString& name) const;
/**
* @return a map of all published actions.
*/
TQMap<TQString, KSharedPtr<Action> > actions() const;
/**
* @return a list of all published actions.
*/
TQStringList actionNames() const;
/**
* Publish the @a Action @p action . The published @a Action
* will be accessible via it's unique name.
*/
void publishAction(KSharedPtr<Action> action);
/**
* Publish the passed TQObject @p object. Those object will
* provide it's slots as callable functions.
*/
void publishObject(const TQString& name, TQObject* object);
/**
* @return the publish TQObject defined with name @p name
* or NULL if there exists no such object.
*/
TQGuardedPtr<TQObject> object(const TQString& name) const;
/**
* @return a map of the published TQObject instances.
*/
TQMap<TQString, TQGuardedPtr<TQObject> > objects() const;
private:
/// @internal d-pointer class.
class Private;
/// @internal d-pointer instance.
Private* const d;
};
}
#endif