plasma-framework/corona.h
Aaron J. Seigo 92390049ed * bring back a publicly available scheduleConfigSync, but as requestConfigSync; the host app may need to trigger this
* signal when the config is sync'd, so the host app (or whomever else cares to) can hook into these syncs as well.

svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=820383
2008-06-14 01:31:53 +00:00

197 lines
5.8 KiB
C++

/*
* Copyright 2007 Aaron Seigo <aseigo@kde.org>
* Copyright 2007 Matt Broadstone <mbroadst@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, 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 General Public License for more details
*
* You should have received a copy of the GNU Library General Public
* License along with this program; if not, write to the
* Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef CORONA_H
#define CORONA_H
#include <QtGui/QGraphicsScene>
#include <plasma/applet.h>
#include <plasma/plasma.h>
#include <plasma/plasma_export.h>
namespace Plasma
{
class Containment;
/**
* @short A QGraphicsScene for Plasma::Applets
*/
class PLASMA_EXPORT Corona : public QGraphicsScene
{
Q_OBJECT
//typedef QHash<QString, QList<Plasma::Applet*> > layouts;
public:
explicit Corona(QObject * parent = 0);
~Corona();
/**
* Sets the mimetype of Drag/Drop items. Default is
* text/x-plasmoidservicename
*/
void setAppletMimeType(const QString &mimetype);
/**
* The current mime type of Drag/Drop items.
*/
QString appletMimeType();
/**
* @return all containments on this Corona
*/
QList<Containment*> containments() const;
/**
* Clear the Corona from all applets.
*/
void clearContainments();
/**
* Returns the the config file used to store the configuration for this Corona
*/
KSharedConfig::Ptr config() const;
/**
* Adds a Containment to the Corona
*
* @param name the plugin name for the containment, as given by
* KPluginInfo::pluginName(). If an empty string is passed in, the defalt
* containment plugin will be used (usually DesktopContainment). If the
* string literal "null" is passed in, then no plugin will be loaded and
* a simple Containment object will be created instead.
* @param args argument list to pass to the containment
*
* @return a pointer to the containment on success, or 0 on failure
*/
Containment* addContainment(const QString& name, const QVariantList& args = QVariantList());
/**
* Returns the Containment, if any, for a given physical screen
*
* @param screen number of the physical screen to locate
*/
Containment* containmentForScreen(int screen) const;
public Q_SLOTS:
/**
* Initializes the layout from a config file. This will first clear any existing
* Containments, load a layout from the requested configuration file, request the
* default layout if needed and update immutability.
*
* @param config the name of the config file to load from,
* or the default config file if QString()
*/
void initializeLayout(const QString &config = QString());
/**
* Load applet layout from a config file. The results will be added to the
* current set of Containments.
*
* @param config the name of the config file to load from,
* or the default config file if QString()
*/
void loadLayout(const QString &config = QString());
/**
* Save applets layout to file
* @arg config the file to save to, or the default config file if QString()
*/
void saveLayout(const QString &config = QString()) const;
/**
* Removes a given containment from the corona
*/
void destroyContainment(Containment *containment);
/**
* @return The type of immutability of this Corona
*/
ImmutabilityType immutability() const;
/**
* Sets the immutability type for this Corona (not immutable, user immutable or system immutable)
* @arg immutable the new immutability type of this applet
*/
void setImmutability(const ImmutabilityType immutable);
/**
* Schedules a flush-to-disk synchronization of the configuration state
* at the next convenient moment.
*/
void requestConfigSync();
Q_SIGNALS:
/**
* This signal indicates a new containment has been added to
* the Corona
*/
void containmentAdded(Plasma::Containment *containment);
/**
* This signal indicates that a containment has been newly
* associated (or dissociated) with a physical screen.
*
* @param wasScreen the screen it was associated with
* @param isScreen the screen it is now associated with
* @param containment the containment switching screens
*/
void screenOwnerChanged(int wasScreen, int isScreen, Plasma::Containment *containment);
/**
* This signal indicates that an application launch, window
* creation or window focus event was triggered. This is used, for instance,
* to ensure that the Dashboard view in Plasma hides when such an event is
* triggered by an item it is displaying.
*/
void releaseVisualFocus();
/**
* This signal indicates that the configuration file was flushed to disc.
*/
void configSynced();
protected:
/**
* Loads the default (system wide) layout for this user
**/
virtual void loadDefaultLayout();
//Reimplemented from QGraphicsScene
void dragEnterEvent(QGraphicsSceneDragDropEvent* event);
void dragLeaveEvent(QGraphicsSceneDragDropEvent* event);
void dragMoveEvent(QGraphicsSceneDragDropEvent* event);
private:
class Private;
Private * const d;
Q_PRIVATE_SLOT(d, void containmentDestroyed(QObject*))
Q_PRIVATE_SLOT(d, void syncConfig())
};
} // namespace Plasma
#endif