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
30class QAction;
31class QGraphicsView;
32
33/**
34 * Namespace for everything in libplasma
35 */
36namespace Plasma
37{
38
39/**
40 * The Constraint enumeration lists the various constraints that Plasma
41 * objects have managed for them and which they may wish to react to,
42 * for instance in Applet::constraintsUpdated
43 */
44enum Constraint {
45 NoConstraint = 0, /**< No constraint; never passed in to Applet::constraintsEvent on its own */
46 FormFactorConstraint = 1, /**< The FormFactor for an object */
47 LocationConstraint = 2, /**< The Location of an object */
48 ScreenConstraint = 4, /**< Which screen an object is on */
49 SizeConstraint = 8, /**< the size of the applet was changed */
50 ImmutableConstraint = 16, /**< the immutability (locked) nature of the applet changed */
51 StartupCompletedConstraint = 32, /**< application startup has completed */
52 ContextConstraint = 64, /**< the context (e.g. activity) has changed */
53 PopupConstraint = 128, /**< the position of the popup needs to be recalculated*/
54 AllConstraints = FormFactorConstraint | LocationConstraint | ScreenConstraint |
55 SizeConstraint | ImmutableConstraint | ContextConstraint | PopupConstraint
56};
57Q_DECLARE_FLAGS(Constraints, Constraint)
58
59/**
60 * The FormFactor enumeration describes how a Plasma::Applet should arrange
61 * itself. The value is derived from the container managing the Applet
62 * (e.g. in Plasma, a Corona on the desktop or on a panel).
63 **/
64enum FormFactor {
65 Planar = 0, /**< The applet lives in a plane and has two
66 degrees of freedom to grow. Optimize for
67 desktop, laptop or tablet usage: a high
68 resolution screen 1-3 feet distant from the
69 viewer. */
70 MediaCenter, /**< As with Planar, the applet lives in a plane
71 but the interface should be optimized for
72 medium-to-high resolution screens that are
73 5-15 feet distant from the viewer. Sometimes
74 referred to as a "ten foot interface".*/
75 Horizontal, /**< The applet is constrained vertically, but
76 can expand horizontally. */
77 Vertical, /**< The applet is constrained horizontally, but
78 can expand vertically. */
79 Application /**< The Applet lives in a plane and should be optimized to look as a full application,
80 for the desktop or the particular device. */
81};
82
83/**
84 * The Direction enumeration describes in which direction, relative to the
85 * Applet (and its managing container), popup menus, expanders, balloons,
86 * message boxes, arrows and other such visually associated widgets should
87 * appear in. This is usually the oposite of the Location.
88 **/
89enum Direction {
90 Down = 0, /**< Display downards */
91 Up, /**< Display upwards */
92 Left, /**< Display to the left */
93 Right /**< Display to the right */
94};
95
96/**
97 * The direction of a zoom action.
98 */
99enum ZoomDirection {
100 ZoomIn = 0, /**< Zoom in one step */
101 ZoomOut = 1 /**< Zoom out one step */
102};
103
104/**
105 * The Location enumeration describes where on screen an element, such as an
106 * Applet or its managing container, is positioned on the screen.
107 **/
108enum Location {
109 Floating = 0, /**< Free floating. Neither geometry or z-ordering
110 is described precisely by this value. */
111 Desktop, /**< On the planar desktop layer, extending across
112 the full screen from edge to edge */
113 FullScreen, /**< Full screen */
114 TopEdge, /**< Along the top of the screen*/
115 BottomEdge, /**< Along the bottom of the screen*/
116 LeftEdge, /**< Along the left side of the screen */
117 RightEdge /**< Along the right side of the screen */
118};
119
120/**
121 * The position enumeration
122 *
123 **/
124enum Position {
125 LeftPositioned, /**< Positioned left */
126 RightPositioned, /**< Positioned right */
127 TopPositioned, /**< Positioned top */
128 BottomPositioned, /**< Positioned bottom */
129 CenterPositioned /**< Positioned in the center */
130};
131
132/**
133 * The popup position enumeration relatively to his attached widget
134 *
135 **/
136
137enum PopupPlacement {
138 FloatingPopup = 0, /**< Free floating, non attached popup */
139 TopPosedLeftAlignedPopup, /**< Popup positioned on the top, aligned
140 to the left of the wigdet */
141 TopPosedRightAlignedPopup, /**< Popup positioned on the top, aligned
142 to the right of the widget */
143 LeftPosedTopAlignedPopup, /**< Popup positioned on the left, aligned
144 to the right of the wigdet */
145 LeftPosedBottomAlignedPopup, /**< Popup positioned on the left, aligned
146 to the bottom of the widget */
147 BottomPosedLeftAlignedPopup, /**< Popup positioned on the bottom, aligned
148 to the left of the wigdet */
149 BottomPosedRightAlignedPopup, /**< Popup positioned on the bottom, aligned
150 to the right of the widget */
151 RightPosedTopAlignedPopup, /**< Popup positioned on the right, aligned
152 to the top of the wigdet */
153 RightPosedBottomAlignedPopup /**< Popup positioned on the right, aligned
154 to the bottom of the widget */
155};
156
157/**
158 * Flip enumeration
159 */
160enum FlipDirection {
161 NoFlip = 0, /**< Do not flip */
162 HorizontalFlip = 1, /**< Flip horizontally */
163 VerticalFlip = 2 /**< Flip vertically */
164};
165Q_DECLARE_FLAGS(Flip, FlipDirection)
166
167/**
168 * Zoom levels that Plasma is aware of...
169 **/
170enum ZoomLevel {
171 DesktopZoom = 0, /**< Normal desktop usage, plasmoids are painted normally
172 and have full interaction */
173 GroupZoom, /**< Plasmoids are shown as icons in visual groups; drag
174 and drop and limited context menu interaction only */
175 OverviewZoom /**< Groups become icons themselves */
176};
177
178/**
179 * Possible timing alignments
180 **/
181enum IntervalAlignment {
182 NoAlignment = 0, /**< No alignment **/
183 AlignToMinute, /**< Align to the minute **/
184 AlignToHour /**< Align to the hour **/
185};
186
187enum ItemTypes {
188 AppletType = QGraphicsItem::UserType + 1,
189 LineEditType = QGraphicsItem::UserType + 2
190};
191
192/**
193 * Defines the immutability of items like applets, corona and containments
194 * they can be free to modify, locked down by the user or locked down by the
195 * system (e.g. kiosk setups).
196 */
197enum ImmutabilityType {
198 Mutable = 1, /**< The item can be modified in any way **/
199 UserImmutable = 2, /**< The user has requested a lock down, and can undo
200 the lock down at any time **/
201 SystemImmutable = 4 /**< the item is locked down by the system, the user
202 can't unlock it **/
203};
204
205/**
206 * Defines the aspect ratio used when scaling an applet
207 */
208enum AspectRatioMode {
209 InvalidAspectRatioMode = -1, /**< Unset mode used for dev convenience
210 when there is a need to store the
211 aspectRatioMode somewhere */
212 IgnoreAspectRatio = 0, /**< The applet can be freely resized */
213 KeepAspectRatio = 1, /**< The applet keeps a fixed aspect ratio */
214 Square = 2, /**< The applet is always a square */
215 ConstrainedSquare = 3, /**< The applet is no wider (in horizontal
216 formfactors) or no higher (in vertical
217 ones) than a square */
218 FixedSize = 4 /** The applet cannot be resized */
219};
220
221/**
222 * The ComonentType enumeration refers to the various types of components,
223 * or plugins, supported by plasma.
224 */
225enum ComponentType {
226 AppletComponent = 1, /**< Plasma::Applet based plugins **/
227 DataEngineComponent = 2, /**< Plasma::DataEngine based plugins **/
228 RunnerComponent = 4, /**< Plasma::AbstractRunner based plugsin **/
229 AnimatorComponent = 8, /**< Plasma::Animator based plugins **/
230 ContainmentComponent = 16,/**< Plasma::Containment based plugins **/
231 WallpaperComponent = 32, /**< Plasma::Wallpaper based plugins **/
232 GenericComponent = 64 /** Generic repositories of files, usually they keep QML files and their assets **/
233};
234Q_DECLARE_FLAGS(ComponentTypes, ComponentType)
235
236enum MarginEdge {
237 TopMargin = 0, /**< The top margin **/
238 BottomMargin, /**< The bottom margin **/
239 LeftMargin, /**< The left margin **/
240 RightMargin /**< The right margin **/
241};
242
243enum MessageButton {
244 ButtonNone = 0, /**< None **/
245 ButtonOk = 1, /**< OK Button **/
246 ButtonYes = 2, /**< Yes Button **/
247 ButtonNo = 4, /**< No Button **/
248 ButtonCancel = 8 /**< Cancel Button **/
249};
250Q_DECLARE_FLAGS(MessageButtons, MessageButton)
251
252/**
253 * Status of an applet
254 * @since 4.3
255 */
256enum ItemStatus {
257 UnknownStatus = 0, /**< The status is unknown **/
258 PassiveStatus = 1, /**< The Item is passive **/
259 ActiveStatus = 2, /**< The Item is active **/
260 NeedsAttentionStatus = 3, /**< The Item needs attention **/
261 AcceptingInputStatus = 4 /**< The Item is accepting input **/
262};
263Q_ENUMS(ItemStatus)
264
265enum AnnouncementMethod {
266 NoAnnouncement = 0, /**< No announcements **/
267 ZeroconfAnnouncement = 1 /**< Announcements via ZeroConf **/
268};
269Q_DECLARE_FLAGS(AnnouncementMethods, AnnouncementMethod)
270
271enum TrustLevel {
272 InvalidCredentials = 0, /**< The credentials are invalid **/
273 UnknownCredentials = 1, /**< The credentials are unknown **/
274 ValidCredentials = 2, /**< The credentials are valid **/
275 TrustedCredentials = 3, /**< The credentials are trusted **/
276 UltimateCredentials = 4 /**< The ultimate trust level applies to the credentials **/
277};
278Q_ENUMS(TrustLevel)
279
280/**
281 * @return the scaling factor (0..1) for a ZoomLevel
282 **/
283PLASMA_EXPORT qreal scalingFactor(ZoomLevel level);
284
285/**
286 * Converts a location to a direction. Handy for figuring out which way to send a popup based on
287 * location or to point arrows and other directional items.
288 *
289 * @param location the location of the container the element will appear in
290 * @return the visual direction the element should be oriented in
291 **/
292PLASMA_EXPORT Direction locationToDirection(Location location);
293
294/**
295 * Converts a location to the direction facing it. Handy for figuring out which way to collapse
296 * a popup or to point arrows at the item itself.
297 *
298 * @param location the location of the container the element will appear in
299 * @return the visual direction the element should be oriented in
300 **/
301PLASMA_EXPORT Direction locationToInverseDirection(Location location);
302
303/**
304 * Returns the most appropriate QGraphicsView for the item.
305 *
306 * @param item the QGraphicsItem to locate a view for
307 * @return pointer to a view, or 0 if none was found
308 */
309PLASMA_EXPORT QGraphicsView *viewFor(const QGraphicsItem *item);
310
311/**
312 * Returns a list of all actions in the given QMenu
313 * This method flattens the hierarchy of the menu by prefixing the
314 * text of all actions in a submenu with the submenu title.
315 *
316 * @param menu the QMenu storing the actions
317 * @param prefix text to display before the text of all actions in the menu
318 * @param parent QObject to be passed as parent of all the actions in the list
319 *
320 * @since 4.4
321 */
322PLASMA_EXPORT QList<QAction*> actionsFromMenu(QMenu *menu,
323 const QString &prefix = QString(),
324 QObject *parent = 0);
325
326} // Plasma namespace
327
328Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Constraints)
329Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Flip)
330Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::ComponentTypes)
331Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::MessageButtons)
332
333
334#endif // multiple inclusion guard
335