kwin Library API Documentation

kdecoration.h

00001 /*****************************************************************
00002 This file is part of the KDE project.
00003 
00004 Copyright (C) 2003 Lubos Lunak <l.lunak@kde.org>
00005 
00006 Permission is hereby granted, free of charge, to any person obtaining a
00007 copy of this software and associated documentation files (the "Software"),
00008 to deal in the Software without restriction, including without limitation
00009 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00010 and/or sell copies of the Software, and to permit persons to whom the
00011 Software is furnished to do so, subject to the following conditions:
00012 
00013 The above copyright notice and this permission notice shall be included in
00014 all copies or substantial portions of the Software.
00015 
00016 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00017 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00018 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
00019 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00020 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00021 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00022 DEALINGS IN THE SOFTWARE.
00023 ******************************************************************/
00024 
00025 #ifndef KDECORATION_H
00026 #define KDECORATION_H
00027 
00028 #include <qcolor.h>
00029 #include <qfont.h>
00030 #include <qobject.h>
00031 #include <qiconset.h>
00032 #include <netwm_def.h>
00033 #include <kdeversion.h>
00034 
00035 class KDecorationOptionsPrivate;
00036 class KDecorationBridge;
00037 class KDecorationPrivate;
00038 class KDecorationFactory;
00039 
00040 #define KWIN_EXPORT KDE_EXPORT
00041 
00047 class KWIN_EXPORT KDecorationDefines
00048 {
00049 public:
00053     enum Position
00054         { // without prefix, they'd conflict with Qt::TopLeft etc. :(
00055         PositionCenter         = 0x00,
00056         PositionLeft           = 0x01,
00057         PositionRight          = 0x02,
00058         PositionTop            = 0x04,
00059         PositionBottom         = 0x08,
00060         PositionTopLeft        = PositionLeft | PositionTop,
00061         PositionTopRight       = PositionRight | PositionTop,
00062         PositionBottomLeft     = PositionLeft | PositionBottom,
00063         PositionBottomRight    = PositionRight | PositionBottom
00064         };
00068     // these values are written to session files, don't change the order
00069     enum MaximizeMode
00070         {
00071     MaximizeRestore    = 0, 
00072     MaximizeVertical   = 1, 
00073     MaximizeHorizontal = 2, 
00074 
00075     MaximizeFull = MaximizeVertical | MaximizeHorizontal 
00076         };
00077 
00078     enum WindowOperation
00079         {
00080         MaximizeOp = 5000,
00081         RestoreOp,
00082         MinimizeOp,
00083         MoveOp,
00084         UnrestrictedMoveOp,
00085         ResizeOp,
00086         UnrestrictedResizeOp,
00087         CloseOp,
00088         OnAllDesktopsOp,
00089         ShadeOp,
00090         KeepAboveOp,
00091         KeepBelowOp,
00092         OperationsOp,
00093         WindowRulesOp,
00094         ToggleStoreSettingsOp = WindowRulesOp, 
00095         HMaximizeOp,
00096         VMaximizeOp,
00097         LowerOp,
00098         FullScreenOp,
00099         NoBorderOp,
00100         NoOp,
00101         SetupWindowShortcutOp
00102         };
00108     enum ColorType
00109     {
00110     ColorTitleBar,   
00111     ColorTitleBlend, 
00112     ColorFont,       
00113     ColorButtonBg,   
00114     ColorFrame,      
00115     ColorHandle,     
00116     NUM_COLORS
00117     };
00118     
00123     enum
00124         {
00125         SettingDecoration = 1 << 0, 
00126         SettingColors     = 1 << 1, 
00127         SettingFont       = 1 << 2, 
00128         SettingButtons    = 1 << 3, 
00129         SettingTooltips   = 1 << 4, 
00130         SettingBorder     = 1 << 5  
00131         };
00132         
00137     enum BorderSize
00138         {
00139         BorderTiny,      
00140         BorderNormal,    
00141         BorderLarge,     
00142         BorderVeryLarge, 
00143         BorderHuge,      
00144         BorderVeryHuge,  
00145         BorderOversized, 
00146         BordersCount     
00147         };
00148 
00153     enum Ability
00154         {
00155         AbilityAnnounceButtons = 0, 
00156         AbilityButtonMenu = 1000,   
00157         AbilityButtonOnAllDesktops = 1001, 
00158         AbilityButtonSpacer = 1002, 
00159         AbilityButtonHelp = 1003,   
00160         AbilityButtonMinimize = 1004,  
00161         AbilityButtonMaximize = 1005, 
00162         AbilityButtonClose = 1006, 
00163         AbilityButtonAboveOthers = 1007, 
00164         AbilityButtonBelowOthers = 1008, 
00165         AbilityButtonShade = 1009, 
00166         AbilityButtonResize = 1010, 
00167         ABILITY_DUMMY = 10000000
00168         };
00169 
00170     enum Requirement { REQUIREMENT_DUMMY = 1000000 };
00171 };    
00172 
00173 class KDecorationProvides
00174     : public KDecorationDefines
00175     {
00176     public:
00177         virtual bool provides( Requirement req ) = 0;
00178     };
00179 
00186 class KWIN_EXPORT KDecorationOptions : public KDecorationDefines
00187     {
00188 public:
00189     KDecorationOptions();
00190     virtual ~KDecorationOptions();
00198     const QColor& color(ColorType type, bool active=true) const;
00206     const QColorGroup& colorGroup(ColorType type, bool active=true) const;
00214     const QFont& font(bool active=true, bool small = false) const;
00222     bool customButtonPositions() const;
00244     QString titleButtonsLeft() const;
00256     QString titleButtonsRight() const;
00257 
00262     bool showTooltips() const;
00263     
00274     BorderSize preferredBorderSize( KDecorationFactory* factory ) const;
00275 
00276     /*
00277      * When this functions returns false, moving and resizing of maximized windows
00278      * is not allowed, and therefore the decoration is allowed to turn off (some of)
00279      * its borders.
00280      * The changed flags for this setting is SettingButtons.
00281      */
00282     bool moveResizeMaximizedWindows() const;
00283 
00287     WindowOperation operationMaxButtonClick( Qt::ButtonState button ) const;
00288 
00292     virtual unsigned long updateSettings() = 0; // returns SettingXYZ mask
00293 
00294 protected:
00298     KDecorationOptionsPrivate* d;
00299     };
00300 
00301 
00309 class KWIN_EXPORT KDecoration
00310     : public QObject, public KDecorationDefines
00311     {
00312     Q_OBJECT
00313     public:
00319     KDecoration( KDecorationBridge* bridge, KDecorationFactory* factory );
00323     virtual ~KDecoration();
00324     
00325     // requests from decoration
00326     
00331         static const KDecorationOptions* options();
00335     bool isActive() const;
00339     bool isCloseable() const;
00343     bool isMaximizable() const;
00349     MaximizeMode maximizeMode() const;
00353     bool isMinimizable() const;
00358         bool providesContextHelp() const;
00364         int desktop() const;
00369         bool isOnAllDesktops() const; // convenience
00373         bool isModal() const;
00377         bool isShadeable() const;
00386         bool isShade() const;
00394         bool isSetShade() const;
00398         bool keepAbove() const;
00402         bool keepBelow() const;
00406         bool isMovable() const;
00410         bool isResizable() const;
00434         NET::WindowType windowType( unsigned long supported_types ) const;
00438     QIconSet icon() const;
00442     QString caption() const;
00469     void showWindowMenu( const QRect &pos );
00470 
00474     void showWindowMenu( QPoint pos );
00479     void performWindowOperation( WindowOperation op );
00488         void setMask( const QRegion& reg, int mode = 0 );
00492         void clearMask(); // convenience
00498         bool isPreview() const;
00502         QRect geometry() const;
00508         QRect iconGeometry() const;
00517         QRegion unobscuredRegion( const QRegion& r ) const;
00522         QWidget* workspaceWidget() const;
00536         WId windowId() const;
00540         int width() const; // convenience
00544         int height() const;  // convenience
00550     void processMousePressEvent( QMouseEvent* e );
00551 
00552     // requests to decoration
00553 
00559         virtual void init() = 0; // called once right after created
00560     
00566     virtual Position mousePosition( const QPoint& p ) const = 0;
00567 
00580         // mustn't do any repaints, resizes or anything like that
00581     virtual void borders( int& left, int& right, int& top, int& bottom ) const = 0;
00589     virtual void resize( const QSize& s ) = 0;
00595     virtual QSize minimumSize() const = 0;
00600         virtual void activeChange() = 0;
00604         virtual void captionChange() = 0;
00608         virtual void iconChange() = 0;
00613         virtual void maximizeChange() = 0;
00619         virtual void desktopChange() = 0;
00624         virtual void shadeChange() = 0;
00625 #if KDE_IS_VERSION( 3, 90, 0 )
00626 #warning Redo all the XYZChange() virtuals as signals.
00627 #endif
00628     signals:
00633         void keepAboveChanged( bool );
00638         void keepBelowChanged( bool );
00639     public:
00653         virtual bool drawbound( const QRect& geom, bool clear );
00664         virtual bool animateMinimize( bool minimize );
00668         // TODO position will need also values for top+left+bottom etc. docking ?
00669         virtual bool windowDocked( Position side );
00676         virtual void reset( unsigned long changed );
00677 
00678     // special
00679 
00686         void setMainWidget( QWidget* );
00696         void createMainWidget( WFlags flags = 0 );
00700         QWidget* initialParentWidget() const;
00707         WFlags initialWFlags() const;
00714         void helperShowHide( bool show );
00718     QWidget* widget();
00722     const QWidget* widget() const;
00726         KDecorationFactory* factory() const;
00730         void grabXServer();
00734         void ungrabXServer();
00735     public slots:
00736     // requests from decoration
00737 
00745     void closeWindow();
00746         /*
00747          * Changes the maximize mode of the decorated window. This function should
00748          * be preferred to the other maximize() overload for reacting on clicks
00749          * on the maximize titlebar button.
00750          * NOTE: This function is new in KDE3.3. In order to support also KDE3.2,
00751          * it is recommended to use code like this:
00752          * \code
00753          * ButtonState button = ... ;
00754          * #if KDE_IS_VERSION( 3, 3, 0 )
00755          * maximize( button );
00756          * #else
00757          * if( button == MidButton )
00758      *     maximize( maximizeMode() ^ MaximizeVertical );
00759          * else if( button == RightButton )
00760          *     maximize( maximizeMode() ^ MaximizeHorizontal );
00761          * else
00762          *     maximize( maximizeMode() == MaximizeFull ? MaximizeRestore : MaximizeFull );
00763          * #endif
00764          * \endcode
00765          * @since 3.3
00766          */
00767 #if KDE_IS_VERSION( 3, 90, 0 )
00768 #warning Update the docs.
00769 #endif
00770         void maximize( ButtonState button );
00775     void maximize( MaximizeMode mode );
00779     void minimize();
00784         void showContextHelp();
00789         void setDesktop( int desktop );
00793         void toggleOnAllDesktops(); // convenience
00798         void titlebarDblClickOperation();
00803         void setShade( bool set );
00808         void setKeepAbove( bool set );
00813         void setKeepBelow( bool set );
00817         void emitKeepAboveChanged( bool above ) { emit keepAboveChanged( above ); }
00821         void emitKeepBelowChanged( bool below ) { emit keepBelowChanged( below ); }
00822     private:
00823     KDecorationBridge* bridge_;
00824     QWidget* w_;
00825         KDecorationFactory* factory_;
00826         friend class KDecorationOptions; // for options_
00827         static KDecorationOptions* options_;
00828         KDecorationPrivate* d;
00829     };
00830 
00831 inline
00832 KDecorationDefines::MaximizeMode operator^( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
00833     {
00834     return KDecorationDefines::MaximizeMode( int(m1) ^ int(m2) );
00835     }
00836 
00837 inline
00838 KDecorationDefines::MaximizeMode operator&( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
00839     {
00840     return KDecorationDefines::MaximizeMode( int(m1) & int(m2) );
00841     }
00842 
00843 inline
00844 KDecorationDefines::MaximizeMode operator|( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
00845     {
00846     return KDecorationDefines::MaximizeMode( int(m1) | int(m2) );
00847     }
00848 
00849 inline QWidget* KDecoration::widget()
00850     {
00851     return w_;
00852     }
00853 
00854 inline const QWidget* KDecoration::widget() const
00855     {
00856     return w_;
00857     }
00858 
00859 inline KDecorationFactory* KDecoration::factory() const
00860     {
00861     return factory_;
00862     }
00863 
00864 inline bool KDecoration::isOnAllDesktops() const
00865     {
00866     return desktop() == NET::OnAllDesktops;
00867     }
00868 
00869 inline int KDecoration::width() const
00870     {
00871     return geometry().width();
00872     }
00873     
00874 inline int KDecoration::height() const
00875     {
00876     return geometry().height();
00877     }
00878     
00879 #endif
KDE Logo
This file is part of the documentation for kwin Library Version 3.4.3.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Jun 14 01:54:12 2006 by doxygen 1.4.4 written by Dimitri van Heesch, © 1997-2003