1 /* 2 SPDX-FileCopyrightText: 2005 Aaron Seigo <aseigo@kde.org> 3 4 SPDX-License-Identifier: LGPL-2.0-or-later 5 */ 6 7 #ifndef PLASMA_DEFS_H 8 #define PLASMA_DEFS_H 9 10 /** @header plasma/plasma.h <Plasma/Plasma> */ 11 12 #include <QObject> 13 14 #include <plasma/plasma_export.h> 15 16 class QAction; 17 18 /** 19 * Namespace for everything in libplasma 20 */ 21 namespace Plasma 22 { 23 /** 24 * @class Types plasma/plasma.h <Plasma/Plasma> 25 * @short Enums and constants used in Plasma 26 * 27 */ 28 class PLASMA_EXPORT Types : public QObject 29 { 30 Q_OBJECT 31 32 public: 33 ~Types() override; 34 /** 35 * The Constraint enumeration lists the various constraints that Plasma 36 * objects have managed for them and which they may wish to react to, 37 * for instance in Applet::constraintsUpdated 38 */ 39 enum Constraint { 40 NoConstraint = 0, /**< No constraint; never passed in to Applet::constraintsEvent on its own */ 41 FormFactorConstraint = 1, /**< The FormFactor for an object */ 42 LocationConstraint = 2, /**< The Location of an object */ 43 ScreenConstraint = 4, /**< Which screen an object is on */ 44 ImmutableConstraint = 8, /**< the immutability (locked) nature of the applet changed */ 45 StartupCompletedConstraint = 16, /**< application startup has completed */ 46 ContextConstraint = 32, /**< the context (e.g. activity) has changed */ 47 UiReadyConstraint = 64, 48 /**< The ui has been completely loaded */ // (FIXME: merged with StartupCompletedConstraint?) 49 AllConstraints = FormFactorConstraint | LocationConstraint | ScreenConstraint | ImmutableConstraint, 50 }; 51 Q_ENUM(Constraint) 52 Q_DECLARE_FLAGS(Constraints, Constraint) 53 54 /** 55 * This enumeration lists the various hints that an applet can pass to its 56 * constraint regarding the way that it is represented 57 */ 58 enum ConstraintHints { // TODO KF6 ConstraintHints -> ConstraintHint 59 NoHint = 0, 60 CanFillArea = 1, 61 /**< The CompactRepresentation can fill the area and ignore constraint margins*/ // (TODO: KF6 CanFillArea -> CompactRepresentationFillArea) 62 MarginAreasSeparator = CanFillArea | 2, /**< The applet acts as a separator between the standard and slim panel margin areas*/ 63 }; 64 Q_DECLARE_FLAGS(ConstraintFlags, ConstraintHints) 65 Q_FLAG(ConstraintFlags) 66 67 /** 68 * The FormFactor enumeration describes how a Plasma::Applet should arrange 69 * itself. The value is derived from the container managing the Applet 70 * (e.g. in Plasma, a Corona on the desktop or on a panel). 71 **/ 72 enum FormFactor { 73 Planar = 0, /**< The applet lives in a plane and has two 74 degrees of freedom to grow. Optimize for 75 desktop, laptop or tablet usage: a high 76 resolution screen 1-3 feet distant from the 77 viewer. */ 78 MediaCenter, /**< As with Planar, the applet lives in a plane 79 but the interface should be optimized for 80 medium-to-high resolution screens that are 81 5-15 feet distant from the viewer. Sometimes 82 referred to as a "ten foot interface".*/ 83 Horizontal, /**< The applet is constrained vertically, but 84 can expand horizontally. */ 85 Vertical, /**< The applet is constrained horizontally, but 86 can expand vertically. */ 87 Application, /**< The Applet lives in a plane and should be optimized to look as a full application, 88 for the desktop or the particular device. */ 89 }; 90 Q_ENUM(FormFactor) 91 92 /** 93 * Display hints that come from the containment that suggest the applet how to look and behave. 94 * @since 5.77 95 */ 96 enum ContainmentDisplayHint { 97 NoContainmentDisplayHint = 0, 98 ContainmentDrawsPlasmoidHeading = 99 1, /**< The containment will draw an titlebar-looking header for the applets, so the applets shouldn't attempt to paint a similar thing **/ 100 ContainmentForcesSquarePlasmoids = 101 2, /**< The containment will force every plasmoid to be constrained in a square icon (An example is the System Tray)**/ 102 DesktopFullyCovered = 103 4, /**< The desktop area for the contaiment's screen is not visible at all, for instance a window has been maximized on top of it */ 104 }; 105 Q_ENUM(ContainmentDisplayHint) 106 Q_DECLARE_FLAGS(ContainmentDisplayHints, ContainmentDisplayHint) 107 Q_FLAG(ContainmentDisplayHints) 108 109 /** 110 * This enumeration describes the type of the Containment. 111 * DesktopContainments represent main containments that will own a screen in a mutually exclusive fashion, 112 * while PanelContainments are accessories which can be present multiple per screen. 113 */ 114 enum ContainmentType { 115 NoContainmentType = -1, /**< @internal */ 116 DesktopContainment = 0, /**< A desktop containment */ 117 PanelContainment, /**< A desktop panel */ 118 119 CustomContainment = 127, /**< A containment that is neither a desktop nor a panel 120 but something application specific */ 121 CustomPanelContainment = 128, /**< A customized desktop panel */ 122 CustomEmbeddedContainment = 129, /**< A customized containment embedded in another applet */ 123 }; 124 Q_ENUM(ContainmentType) 125 126 /** 127 * A descriptive type for QActions, to help categorizing them when presented to the user 128 */ 129 enum ActionType { 130 AddAction = 0, /**< The action will cause something new being created*/ 131 ConfigureAction = 100, /**< The Action will make some kind of configuration ui to appear */ 132 ControlAction = 200, /**< Generic control, similar to ConfigureAction TODO: better doc */ 133 MiscAction = 300, /**< A type of action that doesn't fit in the other categories */ 134 DestructiveAction = 135 400, /**< A dangerous action, such as deletion of objects, plasmoids and files. They are intended to be shown separated from other actions */ 136 UserAction = DestructiveAction + 1000, /**< If new types are needed in a C++ implementation, define them as ids more than UserAction*/ 137 }; 138 Q_ENUM(ActionType) 139 140 /** 141 * The Direction enumeration describes in which direction, relative to the 142 * Applet (and its managing container), popup menus, expanders, balloons, 143 * message boxes, arrows and other such visually associated widgets should 144 * appear in. This is usually the opposite of the Location. 145 **/ 146 enum Direction { 147 Down = 0, /**< Display downards */ 148 Up, /**< Display upwards */ 149 Left, /**< Display to the left */ 150 Right, /**< Display to the right */ 151 }; 152 Q_ENUM(Direction) 153 154 /** 155 * The Location enumeration describes where on screen an element, such as an 156 * Applet or its managing container, is positioned on the screen. 157 **/ 158 enum Location { 159 Floating = 0, /**< Free floating. Neither geometry or z-ordering 160 is described precisely by this value. */ 161 Desktop, /**< On the planar desktop layer, extending across 162 the full screen from edge to edge */ 163 FullScreen, /**< Full screen */ 164 TopEdge, /**< Along the top of the screen*/ 165 BottomEdge, /**< Along the bottom of the screen*/ 166 LeftEdge, /**< Along the left side of the screen */ 167 RightEdge, /**< Along the right side of the screen */ 168 }; 169 Q_ENUM(Location) 170 171 /** 172 * The position enumeration 173 * 174 **/ 175 enum Position { 176 LeftPositioned, /**< Positioned left */ 177 RightPositioned, /**< Positioned right */ 178 TopPositioned, /**< Positioned top */ 179 BottomPositioned, /**< Positioned bottom */ 180 CenterPositioned, /**< Positioned in the center */ 181 }; 182 Q_ENUM(Position) 183 184 /** 185 * The popup position enumeration relatively to his attached widget 186 * 187 **/ 188 enum PopupPlacement { 189 FloatingPopup = 0, /**< Free floating, non attached popup */ 190 TopPosedLeftAlignedPopup, /**< Popup positioned on the top, aligned 191 to the left of the widget */ 192 TopPosedRightAlignedPopup, /**< Popup positioned on the top, aligned 193 to the right of the widget */ 194 LeftPosedTopAlignedPopup, /**< Popup positioned on the left, aligned 195 to the top of the widget */ 196 LeftPosedBottomAlignedPopup, /**< Popup positioned on the left, aligned 197 to the bottom of the widget */ 198 BottomPosedLeftAlignedPopup, /**< Popup positioned on the bottom, aligned 199 to the left of the widget */ 200 BottomPosedRightAlignedPopup, /**< Popup positioned on the bottom, aligned 201 to the right of the widget */ 202 RightPosedTopAlignedPopup, /**< Popup positioned on the right, aligned 203 to the top of the widget */ 204 RightPosedBottomAlignedPopup, /**< Popup positioned on the right, aligned 205 to the bottom of the widget */ 206 }; 207 Q_ENUM(PopupPlacement) 208 209 /** 210 * Flip enumeration 211 */ 212 enum FlipDirection { 213 NoFlip = 0, /**< Do not flip */ 214 HorizontalFlip = 1, /**< Flip horizontally */ 215 VerticalFlip = 2, /**< Flip vertically */ 216 }; 217 Q_ENUM(FlipDirection) 218 Q_DECLARE_FLAGS(Flip, FlipDirection) 219 220 /** 221 * Possible timing alignments 222 **/ 223 enum IntervalAlignment { 224 NoAlignment = 0, /**< No alignment **/ 225 AlignToMinute, /**< Align to the minute **/ 226 AlignToHour, /**< Align to the hour **/ 227 }; 228 Q_ENUM(IntervalAlignment) 229 230 /** 231 * Defines the immutability of items like applets, corona and containments 232 * they can be free to modify, locked down by the user or locked down by the 233 * system (e.g. kiosk setups). 234 */ 235 enum ImmutabilityType { 236 Mutable = 1, /**< The item can be modified in any way **/ 237 UserImmutable = 2, /**< The user has requested a lock down, and can undo 238 the lock down at any time **/ 239 SystemImmutable = 4, /**< the item is locked down by the system, the user 240 can't unlock it **/ 241 }; 242 Q_ENUM(ImmutabilityType) 243 244 /** 245 * The ComonentType enumeration refers to the various types of components, 246 * or plugins, supported by plasma. 247 */ 248 enum ComponentType { 249 AppletComponent = 1, /**< Plasma::Applet based plugins **/ 250 DataEngineComponent = 2, /**< Plasma::DataEngine based plugins **/ 251 ContainmentComponent = 4, /**< Plasma::Containment based plugins **/ 252 WallpaperComponent = 8, /**< Plasma::Wallpaper based plugins **/ 253 GenericComponent = 16, /** Generic repositories of files, usually they keep QML files and their assets **/ 254 }; 255 Q_ENUM(ComponentType) 256 Q_DECLARE_FLAGS(ComponentTypes, ComponentType) 257 258 enum MarginEdge { 259 TopMargin = 0, /**< The top margin **/ 260 BottomMargin, /**< The bottom margin **/ 261 LeftMargin, /**< The left margin **/ 262 RightMargin, /**< The right margin **/ 263 }; 264 Q_ENUM(MarginEdge) 265 266 /** 267 * Status of an applet 268 * @since 4.3 269 */ 270 enum ItemStatus { 271 UnknownStatus = 0, /**< The status is unknown **/ 272 PassiveStatus = 1, /**< The Item is passive **/ 273 ActiveStatus = 2, /**< The Item is active **/ 274 NeedsAttentionStatus = 3, /**< The Item needs attention **/ 275 RequiresAttentionStatus = 4, /**< The Item needs persistent attention **/ 276 AcceptingInputStatus = 5, /**< The Item is accepting input **/ 277 // FIXME KF6: this should be the smallest status 278 HiddenStatus = 6, /**< The Item will be hidden totally **/ 279 }; 280 Q_ENUM(ItemStatus) 281 282 enum TrustLevel { 283 UnverifiableTrust = 0, /**< The trust of the object can not be verified, usually because no 284 trust information (e.g. a cryptographic signature) was provided */ 285 CompletelyUntrusted, /**< The signature is broken/expired/false */ 286 UnknownTrusted, /**< The signature is valid, but the key is unknown */ 287 UserTrusted, /**< The signature is valid and made with a key signed by one of the 288 user's own keys*/ 289 SelfTrusted, /**< The signature is valid and made with one of the user's own keys*/ 290 FullyTrusted, /**< The signature is valid and made with a key signed by the vendor's key*/ 291 UltimatelyTrusted, /**< The signature is valid and made with the vendor's key*/ 292 }; 293 Q_ENUM(TrustLevel) 294 295 /** 296 * Description on how draw a background for the applet 297 */ 298 enum BackgroundHints { 299 NoBackground = 0, /**< Not drawing a background under the applet, the applet has its own implementation */ 300 StandardBackground = 1, /**< The standard background from the theme is drawn */ 301 TranslucentBackground = 2, /**< An alternate version of the background is drawn, usually more translucent */ 302 ShadowBackground = 4, /**< The applet won't have a svg background but a drop shadow of its content done via a shader */ 303 ConfigurableBackground = 8, /** If the hint has this flag, the user is able to configure this background */ 304 DefaultBackground = StandardBackground, /**< Default settings: both standard background */ 305 }; 306 Q_ENUM(BackgroundHints) 307 // TODO KF6: BackgroundHint and BackgroundHints 308 Q_DECLARE_FLAGS(BackgroundFlags, BackgroundHints) 309 310 private: 311 Types(QObject *parent = nullptr); 312 }; 313 314 /** 315 * Converts a location to a direction. Handy for figuring out which way to send a popup based on 316 * location or to point arrows and other directional items. 317 * 318 * @param location the location of the container the element will appear in 319 * @return the visual direction the element should be oriented in 320 **/ 321 PLASMA_EXPORT Types::Direction locationToDirection(Types::Location location); 322 323 /** 324 * Converts a location to the direction facing it. Handy for figuring out which way to collapse 325 * a popup or to point arrows at the item itself. 326 * 327 * @param location the location of the container the element will appear in 328 * @return the visual direction the element should be oriented in 329 **/ 330 PLASMA_EXPORT Types::Direction locationToInverseDirection(Types::Location location); 331 332 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::ContainmentDisplayHints) 333 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::Constraints) 334 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::ConstraintFlags) 335 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::Flip) 336 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::ComponentTypes) 337 Q_DECLARE_OPERATORS_FOR_FLAGS(Types::BackgroundFlags) 338 339 } // Plasma namespace 340 341 #endif // multiple inclusion guard 342