plasma/plasma.h

   1 /*
   2  *   Copyright 2005 by Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_DEFS_H
  21 #define PLASMA_DEFS_H
  22
  23 /** @header plasma/plasma.h <Plasma/Plasma> */
  24
  25 #include <QtGui/QGraphicsItem>
  26 #include <QtGui/QPainterPath>
  27
  28 #include <plasma/plasma_export.h>
  29
  30 class QGraphicsView;
  31
  32 /**
  33  * Namespace for everything in libplasma
  34  */
  35 namespace Plasma
  36 {
  37
  38 /**
  39  * The Constraint enumeration lists the various constraints that Plasma
  40  * objects have managed for them and which they may wish to react to,
  41  * for instance in Applet::constraintsUpdated
  42  */
  43 enum Constraint {
  44     NoConstraint = 0,
  45     /** The FormFactor for an object */
  46     FormFactorConstraint = 1,
  47     /** The Location of an object */
  48     LocationConstraint = 2,
  49     /** Which screen an object is on */
  50     ScreenConstraint = 4,
  51     /** the size of the applet was changed */
  52     SizeConstraint = 8,
  53     /** the immutability (locked) nature of the applet changed  */
  54     ImmutableConstraint = 16,
  55     /** application startup has completed */
  56     StartupCompletedConstraint = 32,
  57     /** the desktop context has changed */
  58     ContextConstraint = 64,
  59     AllConstraints = FormFactorConstraint | LocationConstraint | ScreenConstraint |
  60     SizeConstraint | ImmutableConstraint | ContextConstraint
  61 };
  62 Q_DECLARE_FLAGS(Constraints, Constraint)
  63
  64 /**
  65  * The FormFactor enumeration describes how a Plasma::Applet should arrange
  66  * itself. The value is derived from the container managing the Applet
  67  * (e.g. in Plasma, a Corona on the desktop or on a panel).
  68  **/
  69 enum FormFactor {
  70     Planar = 0,  /**< The applet lives in a plane and has two
  71                     degrees of freedom to grow. Optimize for
  72                     desktop, laptop or tablet usage: a high
  73                     resolution screen 1-3 feet distant from the
  74                     viewer. */
  75     MediaCenter, /**< As with Planar, the applet lives in a plane
  76                     but the interface should be optimized for
  77                     medium-to-high resolution screens that are
  78                     5-15 feet distant from the viewer. Sometimes
  79                     referred to as a "ten foot interface".*/
  80     Horizontal,  /**< The applet is constrained vertically, but
  81                     can expand horizontally. */
  82     Vertical     /**< The applet is constrained horizontally, but
  83                     can expand vertically. */
  84 };
  85
  86 /**
  87  * The Direction enumeration describes in which direction, relative to the
  88  * Applet (and its managing container), popup menus, expanders, balloons,
  89  * message boxes, arrows and other such visually associated widgets should
  90  * appear in. This is usually the oposite of the Location.
  91  **/
  92 enum Direction {
  93     Down = 0, /**< Display downards */
  94     Up,       /**< Display upwards */
  95     Left,     /**< Display to the left */
  96     Right     /**< Display to the right */
  97 };
  98
  99 /**
 100  * The direction of a zoom action.
 101  */
 102 enum ZoomDirection {
 103     ZoomIn = 0, /**< Zoom in one step */
 104     ZoomOut = 1 /**< Zoom out one step */
 105 };
 106
 107 /**
 108  * The Location enumeration describes where on screen an element, such as an
 109  * Applet or its managing container, is positioned on the screen.
 110  **/
 111 enum Location {
 112     Floating = 0, /**< Free floating. Neither geometry or z-ordering
 113                      is described precisely by this value. */
 114     Desktop,      /**< On the planar desktop layer, extending across
 115                      the full screen from edge to edge */
 116     FullScreen,   /**< Full screen */
 117     TopEdge,      /**< Along the top of the screen*/
 118     BottomEdge,   /**< Along the bottom of the screen*/
 119     LeftEdge,     /**< Along the left side of the screen */
 120     RightEdge     /**< Along the right side of the screen */
 121 };
 122
 123 /**
 124  * The position enumeration
 125  *
 126  **/
 127 enum Position {
 128     LeftPositioned,    /**< Positioned left */
 129     RightPositioned,   /**< Positioned right */
 130     TopPositioned,     /**< Positioned top */
 131     BottomPositioned,  /**< Positioned bottom */
 132     CenterPositioned   /**< Positioned in the center */
 133 };
 134
 135 /**
 136  * The popup position enumeration relatively to his attached widget
 137  *
 138  **/
 139
 140 enum PopupPlacement {
 141     FloatingPopup = 0,            /**< Free floating, non attached popup */
 142     TopPosedLeftAlignedPopup,     /**< Popup positioned on the top, aligned
 143                                      to the left of the wigdet */
 144     TopPosedRightAlignedPopup,    /**< Popup positioned on the top, aligned
 145                                      to the right of the widget */
 146     LeftPosedTopAlignedPopup,     /**< Popup positioned on the left, aligned
 147                                      to the right of the wigdet */
 148     LeftPosedBottomAlignedPopup,  /**< Popup positioned on the left, aligned
 149                                      to the bottom of the widget */
 150     BottomPosedLeftAlignedPopup,  /**< Popup positioned on the bottom, aligned
 151                                      to the left of the wigdet */
 152     BottomPosedRightAlignedPopup, /**< Popup positioned on the bottom, aligned
 153                                      to the right of the widget */
 154     RightPosedTopAlignedPopup,    /**< Popup positioned on the right, aligned
 155                                      to the top of the wigdet */
 156     RightPosedBottomAlignedPopup  /**< Popup positioned on the right, aligned
 157                                      to the bottom of the widget */
 158 };
 159
 160 /**
 161  * Flip enumeration
 162  */
 163 enum FlipDirection {
 164     NoFlip = 0,          /**< Do not flip */
 165     HorizontalFlip = 1,  /**< Flip horizontally */
 166     VerticalFlip = 2     /**< Flip vertically */
 167 };
 168 Q_DECLARE_FLAGS(Flip, FlipDirection)
 169
 170 /**
 171  * Zoom levels that Plasma is aware of...
 172  **/
 173 enum ZoomLevel {
 174     DesktopZoom = 0, /**< Normal desktop usage, plasmoids are painted normally
 175                         and have full interaction */
 176     GroupZoom,       /**< Plasmoids are shown as icons in visual groups; drag
 177                         and drop and limited context menu interaction only */
 178     OverviewZoom     /**< Groups become icons themselves */
 179 };
 180
 181 /**
 182  * Possible timing alignments
 183  **/
 184 enum IntervalAlignment {
 185     NoAlignment = 0,
 186     AlignToMinute,
 187     AlignToHour
 188 };
 189
 190 enum ItemTypes {
 191     AppletType = QGraphicsItem::UserType + 1,
 192     LineEditType = QGraphicsItem::UserType + 2
 193 };
 194
 195 /**
 196  * Defines the immutability of items like applets, corona and containments
 197  * they can be free to modify, locked down by the user or locked down by the
 198  * system (e.g. kiosk setups).
 199  */
 200 enum ImmutabilityType {
 201     Mutable = 1,        /**< The item can be modified in any way **/
 202     UserImmutable = 2,  /**< The user has requested a lock down, and can undo
 203                            the lock down at any time **/
 204     SystemImmutable = 4 /**<  the item is locked down by the system, the user
 205                            can't unlock it **/
 206 };
 207
 208 /**
 209  * Defines the aspect ratio used when scaling an applet
 210  */
 211 enum AspectRatioMode {
 212     InvalidAspectRatioMode = -1, /**< Unsetted mode used for dev convenience
 213                                     when there is a need to store the
 214                                     aspectRatioMode somewhere */
 215     IgnoreAspectRatio = 0,       /**< The applet can be freely resized */
 216     KeepAspectRatio = 1,         /**< The applet keeps a fixed aspect ratio */
 217     Square = 2,                  /**< The applet is always a square */
 218     ConstrainedSquare = 3,       /**< The applet is no wider (in horizontal
 219                                     formfactors) or no higher (in vertical
 220                                     ones) than a square */
 221     FixedSize = 4                /** The applet cannot be resized */
 222 };
 223
 224 /**
 225  * The ComonentType enumeration refers to the various types of components,
 226  * or plugins, supported by plasma.
 227  */
 228 enum ComponentType {
 229     AppletComponent = 1,      /**< Plasma::Applet based plugins **/
 230     DataEngineComponent = 2,  /**< Plasma::DataEngine based plugins **/
 231     RunnerComponent = 4,      /**< Plasma::AbstractRunner based plugsin **/
 232     AnimatorComponent = 8,    /**< Plasma::Animator based plugins **/
 233     ContainmentComponent = 16 /**< Plasma::Containment based plugins **/
 234 };
 235 Q_DECLARE_FLAGS(ComponentTypes, ComponentType)
 236
 237 enum MarginEdge {
 238     TopMargin = 0,
 239     BottomMargin,
 240     LeftMargin,
 241     RightMargin
 242 };
 243
 244 enum MessageButton {
 245     ButtonNone = 0,
 246     ButtonOk = 1,
 247     ButtonYes = 2,
 248     ButtonNo = 4,
 249     ButtonCancel = 8
 250 };
 251 Q_DECLARE_FLAGS(MessageButtons, MessageButton)
 252
 253
 254 /**
 255  * @return the scaling factor (0..1) for a ZoomLevel
 256  **/
 257 PLASMA_EXPORT qreal scalingFactor(ZoomLevel level);
 258
 259 /**
 260  * Converts a location to a direction. Handy for figuring out which way to send a popup based on
 261  * location or to point arrows and other directional items.
 262  *
 263  * @param location the location of the container the element will appear in
 264  * @return the visual direction of the element should be oriented in
 265  **/
 266 PLASMA_EXPORT Direction locationToDirection(Location location);
 267
 268 /**
 269  * Returns the most appropriate QGraphicsView for the item.
 270  *
 271  * @arg item the QGraphicsItem to locate a view for
 272  * @return pointer to a view, or 0 if none was found
 273  */
 274 PLASMA_EXPORT QGraphicsView *viewFor(const QGraphicsItem *item);
 275
 276 } // Plasma namespace
 277
 278 Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Constraints)
 279 Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Flip)
 280 Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::ComponentTypes)
 281
 282 #endif // multiple inclusion guard