kdecoration.h

/*****************************************************************
This file is part of the KDE project.
 
Copyright (C) 2003 Lubos Lunak <l.lunak@kde.org>
 
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
******************************************************************/
 
#ifndef KDECORATION_H
#define KDECORATION_H
 
#include <tqcolor.h>
#include <tqfont.h>
#include <tqobject.h>
#include <tqiconset.h>
#include <netwm_def.h>
#include <tdeversion.h>
 
class KDecorationOptionsPrivate;
class KDecorationBridge;
class KDecorationPrivate;
class KDecorationFactory;
 
#define KWIN_EXPORT TDE_EXPORT

class KWIN_EXPORT KDecorationDefines
{
public:
    enum Position
        { // without prefix, they'd conflict with TQt::TopLeft etc. :(
        PositionCenter         = 0x00,
        PositionLeft           = 0x01,
        PositionRight          = 0x02,
        PositionTop            = 0x04,
        PositionBottom         = 0x08,
        PositionTopLeft        = PositionLeft | PositionTop,
        PositionTopRight       = PositionRight | PositionTop,
        PositionBottomLeft     = PositionLeft | PositionBottom,
        PositionBottomRight    = PositionRight | PositionBottom
        };

    // these values are written to session files, don't change the order
    enum MaximizeMode
        {
    MaximizeRestore    = 0, 
    MaximizeVertical   = 1, 
    MaximizeHorizontal = 2, 
    MaximizeFull = MaximizeVertical | MaximizeHorizontal 
        };
 
    enum WindowOperation
        {
        MaximizeOp = 5000,
        RestoreOp,
        MinimizeOp,
        MoveOp,
        UnrestrictedMoveOp,
        ResizeOp,
        UnrestrictedResizeOp,
        CloseOp,
        OnAllDesktopsOp,
        ShadeOp,
        KeepAboveOp,
        KeepBelowOp,
        OperationsOp,
        WindowRulesOp,
        ToggleStoreSettingsOp = WindowRulesOp, 
        HMaximizeOp,
        VMaximizeOp,
        LowerOp,
        FullScreenOp,
        NoBorderOp,
        NoOp,
        SetupWindowShortcutOp,
        ApplicationRulesOp,    
        ShadowOp,              
        SuspendWindowOp,       
        ResumeWindowOp         
        };

    enum ColorType
    {
    ColorTitleBar,   
    ColorTitleBlend, 
    ColorFont,       
    ColorButtonBg,   
    ColorFrame,      
    ColorHandle,     
    NUM_COLORS
    };

    enum
        {
        SettingDecoration = 1 << 0, 
        SettingColors     = 1 << 1, 
        SettingFont       = 1 << 2, 
        SettingButtons    = 1 << 3, 
        SettingTooltips   = 1 << 4, 
        SettingBorder     = 1 << 5  
        };

    enum BorderSize
        {
        BorderTiny,      
        BorderNormal,    
        BorderLarge,     
        BorderVeryLarge, 
        BorderHuge,      
        BorderVeryHuge,  
        BorderOversized, 
        BordersCount     
        };

    enum Ability
        {
        AbilityAnnounceButtons = 0, 
        AbilityButtonMenu = 1000,   
        AbilityButtonOnAllDesktops = 1001, 
        AbilityButtonSpacer = 1002, 
        AbilityButtonHelp = 1003,   
        AbilityButtonMinimize = 1004,  
        AbilityButtonMaximize = 1005, 
        AbilityButtonClose = 1006, 
        AbilityButtonAboveOthers = 1007, 
        AbilityButtonBelowOthers = 1008, 
        AbilityButtonShade = 1009, 
        AbilityButtonResize = 1010, 
        ABILITY_DUMMY = 10000000
        };
 
    enum Requirement { REQUIREMENT_DUMMY = 1000000 };
};    
 
class KDecorationProvides
    : public KDecorationDefines
    {
    public:
        virtual bool provides( Requirement req ) = 0;
    };

class KWIN_EXPORT KDecorationOptions : public KDecorationDefines
    {
public:
    KDecorationOptions();
    virtual ~KDecorationOptions();
    const TQColor& color(ColorType type, bool active=true) const;
    const TQColorGroup& colorGroup(ColorType type, bool active=true) const;
    const TQFont& font(bool active=true, bool small = false) const;
    bool customButtonPositions() const;
    TQString titleButtonsLeft() const;
    TQString titleButtonsRight() const;

    bool showTooltips() const;

    BorderSize preferredBorderSize( KDecorationFactory* factory ) const;
 
    /*
     * When this functions returns false, moving and resizing of maximized windows
     * is not allowed, and therefore the decoration is allowed to turn off (some of)
     * its borders.
     * The changed flags for this setting is SettingButtons.
     */
    bool moveResizeMaximizedWindows() const;

    WindowOperation operationMaxButtonClick( TQt::ButtonState button ) const;

    virtual unsigned long updateSettings() = 0; // returns SettingXYZ mask
 
protected:
    KDecorationOptionsPrivate* d;
    };
 

class KWIN_EXPORT KDecoration
    : public TQObject, public KDecorationDefines
    {
    TQ_OBJECT
    public:
    KDecoration( KDecorationBridge* bridge, KDecorationFactory* factory );
    virtual ~KDecoration();
 
    // requests from decoration

        static const KDecorationOptions* options();
    bool isActive() const;
    bool isCloseable() const;
    bool isMaximizable() const;
    MaximizeMode maximizeMode() const;
    bool isMinimizable() const;
        bool providesContextHelp() const;
        int desktop() const;
        bool isOnAllDesktops() const; // convenience
        bool isModal() const;
        bool isShadeable() const;
        bool isShade() const;
        bool isSetShade() const;
        bool keepAbove() const;
        bool keepBelow() const;
        bool isMovable() const;
        bool isResizable() const;
        NET::WindowType windowType( unsigned long supported_types ) const;
    TQIconSet icon() const;
    TQString caption() const;
    void showWindowMenu( const TQRect &pos );

    void showWindowMenu( TQPoint pos );
    void performWindowOperation( WindowOperation op );
        void setMask( const TQRegion& reg, int mode = 0 );
        void clearMask(); // convenience
        bool isPreview() const;
        TQRect geometry() const;
        TQRect iconGeometry() const;
        TQRegion unobscuredRegion( const TQRegion& r ) const;
        TQWidget* workspaceWidget() const;
        WId windowId() const;
        int width() const; // convenience
        int height() const;  // convenience
    void processMousePressEvent( TQMouseEvent* e );
 
    // requests to decoration

        virtual void init() = 0; // called once right after created
    
    virtual Position mousePosition( const TQPoint& p ) const = 0;

        // mustn't do any repaints, resizes or anything like that
    virtual void borders( int& left, int& right, int& top, int& bottom ) const = 0;
    virtual void resize( const TQSize& s ) = 0;
    virtual TQSize minimumSize() const = 0;
        virtual void activeChange() = 0;
        virtual void captionChange() = 0;
        virtual void iconChange() = 0;
        virtual void maximizeChange() = 0;
        virtual void desktopChange() = 0;
        virtual void shadeChange() = 0;
#if KDE_IS_VERSION( 3, 90, 0 )
#warning Redo all the XYZChange() virtuals as signals.
#endif
    signals:
        void keepAboveChanged( bool );
        void keepBelowChanged( bool );
    public:
        virtual bool drawbound( const TQRect& geom, bool clear );
        virtual bool animateMinimize( bool minimize );
        // TODO position will need also values for top+left+bottom etc. docking ?
        virtual bool windowDocked( Position side );
        virtual void reset( unsigned long changed );
 
    // special
 
        void setMainWidget( TQWidget* );
        void createMainWidget( TQt::WFlags flags = 0 );
        TQWidget* initialParentWidget() const;
        TQt::WFlags initialWFlags() const;
        void helperShowHide( bool show );
    TQWidget* widget();
    const TQWidget* widget() const;
        KDecorationFactory* factory() const;
        void grabXServer();
        void ungrabXServer();
    public slots:
    // requests from decoration

    void closeWindow();
        /*
         * Changes the maximize mode of the decorated window. This function should
         * be preferred to the other maximize() overload for reacting on clicks
         * on the maximize titlebar button.
         * NOTE: This function is new in KDE3.3. In order to support also KDE3.2,
         * it is recommended to use code like this:
         * \code
         * ButtonState button = ... ;
         * #if KDE_IS_VERSION( 3, 3, 0 )
         * maximize( button );
         * #else
         * if( button == MidButton )
     *     maximize( maximizeMode() ^ MaximizeVertical );
         * else if( button == RightButton )
         *     maximize( maximizeMode() ^ MaximizeHorizontal );
         * else
         *     maximize( maximizeMode() == MaximizeFull ? MaximizeRestore : MaximizeFull );
         * #endif
         * \endcode
         * @since 3.3
         */
#if KDE_IS_VERSION( 3, 90, 0 )
#warning Update the docs.
#endif
        void maximize( ButtonState button );
    void maximize( MaximizeMode mode );
    void minimize();
        void showContextHelp();
        void setDesktop( int desktop );
        void toggleOnAllDesktops(); // convenience
        void titlebarDblClickOperation();
        void titlebarMouseWheelOperation( int delta );
        void setShade( bool set );
        void setKeepAbove( bool set );
        void setKeepBelow( bool set );
        void emitKeepAboveChanged( bool above ) { emit keepAboveChanged( above ); }
        void emitKeepBelowChanged( bool below ) { emit keepBelowChanged( below ); }
    private:
    KDecorationBridge* bridge_;
    TQWidget* w_;
        KDecorationFactory* factory_;
        friend class KDecorationOptions; // for options_
        static KDecorationOptions* options_;
        KDecorationPrivate* d;
    };
 
inline
KDecorationDefines::MaximizeMode operator^( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
    {
    return KDecorationDefines::MaximizeMode( int(m1) ^ int(m2) );
    }
 
inline
KDecorationDefines::MaximizeMode operator&( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
    {
    return KDecorationDefines::MaximizeMode( int(m1) & int(m2) );
    }
 
inline
KDecorationDefines::MaximizeMode operator|( KDecorationDefines::MaximizeMode m1, KDecorationDefines::MaximizeMode m2 )
    {
    return KDecorationDefines::MaximizeMode( int(m1) | int(m2) );
    }
 
inline TQWidget* KDecoration::widget()
    {
    return w_;
    }
 
inline const TQWidget* KDecoration::widget() const
    {
    return w_;
    }
 
inline KDecorationFactory* KDecoration::factory() const
    {
    return factory_;
    }
 
inline bool KDecoration::isOnAllDesktops() const
    {
    return desktop() == NET::OnAllDesktops;
    }
 
inline int KDecoration::width() const
    {
    return geometry().width();
    }
    
inline int KDecoration::height() const
    {
    return geometry().height();
    }
    
#endif