kwin Library API Documentation

KDecoration Class Reference

This is the base class for a decoration object. More...

#include <kdecoration.h>

Inheritance diagram for KDecoration:

KDecorationDefines List of all members.

Public Slots

void closeWindow ()
void maximize (ButtonState button)
void maximize (MaximizeMode mode)
void minimize ()
void showContextHelp ()
void setDesktop (int desktop)
void toggleOnAllDesktops ()
void titlebarDblClickOperation ()
void setShade (bool set)
void setKeepAbove (bool set)
void setKeepBelow (bool set)
void emitKeepAboveChanged (bool above)
void emitKeepBelowChanged (bool below)

Signals

void keepAboveChanged (bool)
void keepBelowChanged (bool)

Public Member Functions

 KDecoration (KDecorationBridge *bridge, KDecorationFactory *factory)
virtual ~KDecoration ()
bool isActive () const
bool isCloseable () const
bool isMaximizable () const
MaximizeMode maximizeMode () const
bool isMinimizable () const
bool providesContextHelp () const
int desktop () const
bool isOnAllDesktops () const
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
QIconSet icon () const
QString caption () const
void showWindowMenu (const QRect &pos)
void showWindowMenu (QPoint pos)
void performWindowOperation (WindowOperation op)
void setMask (const QRegion &reg, int mode=0)
void clearMask ()
bool isPreview () const
QRect geometry () const
QRect iconGeometry () const
QRegion unobscuredRegion (const QRegion &r) const
QWidget * workspaceWidget () const
WId windowId () const
int width () const
int height () const
void processMousePressEvent (QMouseEvent *e)
virtual void init ()=0
virtual Position mousePosition (const QPoint &p) const =0
virtual void borders (int &left, int &right, int &top, int &bottom) const =0
virtual void resize (const QSize &s)=0
virtual QSize 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
virtual bool drawbound (const QRect &geom, bool clear)
virtual bool animateMinimize (bool minimize)
virtual bool windowDocked (Position side)
virtual void reset (unsigned long changed)
void setMainWidget (QWidget *)
void createMainWidget (WFlags flags=0)
QWidget * initialParentWidget () const
WFlags initialWFlags () const
void helperShowHide (bool show)
QWidget * widget ()
const QWidget * widget () const
KDecorationFactory * factory () const
void grabXServer ()
void ungrabXServer ()

Static Public Member Functions

static const KDecorationOptionsoptions ()

Friends

class KDecorationOptions

Detailed Description

This is the base class for a decoration object.

It provides functions that give various information about the decorated window, and also provides pure virtual functions for controlling the decoration that every decoration should implement.

Since:
3.2

Definition at line 309 of file kdecoration.h.


Constructor & Destructor Documentation

KDecoration::KDecoration KDecorationBridge *  bridge,
KDecorationFactory *  factory
 

Constructs a KDecoration object.

Both the arguments are passed from KDecorationFactory. Note that the initialization code of the decoration should be done in the init() method.

Definition at line 41 of file kdecoration.cpp.

References factory().

KDecoration::~KDecoration  )  [virtual]
 

Destroys the KDecoration.

Definition at line 49 of file kdecoration.cpp.

References factory().


Member Function Documentation

const KDecorationOptions * KDecoration::options  )  [static]
 

Returns the KDecorationOptions object, which is used to access configuration settings for the decoration.

Definition at line 55 of file kdecoration.cpp.

bool KDecoration::isActive  )  const
 

Returns true if the decorated window is currently active.

Definition at line 84 of file kdecoration.cpp.

bool KDecoration::isCloseable  )  const
 

Returns true if the decoration window can be closed by the user.

Definition at line 89 of file kdecoration.cpp.

bool KDecoration::isMaximizable  )  const
 

Returns true if the decorated window can be maximized.

Definition at line 94 of file kdecoration.cpp.

KDecoration::MaximizeMode KDecoration::maximizeMode  )  const
 

Returns the current maximization mode of the decorated window.

Note that only fully maximized windows should be treated as "maximized" (e.g. if the maximize button has only two states).

Definition at line 99 of file kdecoration.cpp.

bool KDecoration::isMinimizable  )  const
 

Returns true if the decorated window can be minimized by the user.

Definition at line 104 of file kdecoration.cpp.

bool KDecoration::providesContextHelp  )  const
 

Return true if the decorated window can show context help (i.e.

the decoration should provide the context help button).

Definition at line 109 of file kdecoration.cpp.

int KDecoration::desktop  )  const
 

Returns the number of the virtual desktop the decorated window is currently on (including NET::OnAllDesktops for being on all desktops).

Definition at line 114 of file kdecoration.cpp.

Referenced by isOnAllDesktops().

bool KDecoration::isOnAllDesktops  )  const [inline]
 

Convenience function that returns true if the window is on all virtual desktops.

Definition at line 864 of file kdecoration.h.

References desktop().

Referenced by toggleOnAllDesktops().

bool KDecoration::isModal  )  const
 

Returns true if the decoration window is modal (usually a modal dialog).

Definition at line 119 of file kdecoration.cpp.

bool KDecoration::isShadeable  )  const
 

Returns true if the decorated window can be shaded.

Definition at line 124 of file kdecoration.cpp.

bool KDecoration::isShade  )  const
 

Returns true if the decorated window is currently shaded.

If the window is e.g. hover unshaded, it's not considered to be shaded. This function should not be used for the shade titlebar button, use isSetShade() instead.

See also:
isSetShade

Definition at line 129 of file kdecoration.cpp.

bool KDecoration::isSetShade  )  const
 

Returns true if the decorated window was set to be shaded.

This function returns also true if the window is e.g. hover unshaded, so it doesn't always correspond to the actual window state.

See also:
isShade

Definition at line 134 of file kdecoration.cpp.

bool KDecoration::keepAbove  )  const
 

Returns true if the decorated window should be kept above other windows.

Definition at line 139 of file kdecoration.cpp.

bool KDecoration::keepBelow  )  const
 

Returns true if the decorated window should be kept below other windows.

Definition at line 144 of file kdecoration.cpp.

bool KDecoration::isMovable  )  const
 

Returns true if the decorated window can be moved by the user.

Definition at line 149 of file kdecoration.cpp.

bool KDecoration::isResizable  )  const
 

Returns true if the decorated window can be resized by the user.

Definition at line 154 of file kdecoration.cpp.

NET::WindowType KDecoration::windowType unsigned long  supported_types  )  const
 

This function returns the window type of the decorated window.

The argument to this function is a mask of all window types the decoration knows about (as the list of valid window types is extended over time, and fallback types are specified in order to support older code). For a description of all window types, see the definition of the NET::WindowType type. Note that some window types never have decorated windows.

An example of usage:

 const unsigned long supported_types = NET::NormalMask | NET::DesktopMask
    | NET::DockMask | NET::ToolbarMask | NET::MenuMask | NET::DialogMask
    | NET::OverrideMask | NET::TopMenuMask | NET::UtilityMask | NET::SplashMask;

 NET::WindowType type = windowType( supported_types );

 if( type == NET::Utility || type == NET::Menu || type == NET::Toolbar )
    // ... use smaller decorations for tool window types
 else
    // ... use normal decorations

Definition at line 159 of file kdecoration.cpp.

QIconSet KDecoration::icon  )  const
 

Returns an icon set with the decorated window's icon.

Definition at line 164 of file kdecoration.cpp.

QString KDecoration::caption  )  const
 

Returns the decorated window's caption that should be shown in the titlebar.

Definition at line 169 of file kdecoration.cpp.

void KDecoration::showWindowMenu const QRect &  pos  ) 
 

This function invokes the window operations menu.

Parameters:
pos specifies the place on the screen where the menu should show up. The menu pops up at the bottom-left corner of the specified rectangle, unless there is no space, in which case the menu is displayed above the rectangle.
Note:
Decorations that enable a double-click operation for the menu button must ensure to call showWindowMenu() with the pos rectangle set to the menu button geometry. IMPORTANT: As a result of this function, the decoration object that called it may be destroyed after the function returns. This means that the decoration object must either return immediately after calling showWindowMenu(), or it must use KDecorationFactory::exists() to check it's still valid. For example, the code handling clicks on the menu button should look similarly like this:
 KDecorationFactory* f = factory(); // needs to be saved before
 showWindowMenu( button[MenuButton]->mapToGlobal( menuPoint ));
 if( !f->exists( this )) // destroyed, return immediately
     return;
 button[MenuButton]->setDown(false);

Definition at line 179 of file kdecoration.cpp.

void KDecoration::showWindowMenu QPoint  pos  ) 
 

Overloaded version of the above.

Definition at line 184 of file kdecoration.cpp.

void KDecoration::performWindowOperation WindowOperation  op  ) 
 

This function performs the given window operation.

This function may destroy the current decoration object, just like showWindowMenu().

Definition at line 189 of file kdecoration.cpp.

void KDecoration::setMask const QRegion &  reg,
int  mode = 0
 

If the decoration is non-rectangular, this function needs to be called to set the shape of the decoration.

Parameters:
reg The shape of the decoration.
mode The X11 values Unsorted, YSorted, YXSorted and YXBanded that specify the sorting of the rectangles, default value is Unsorted.

Definition at line 194 of file kdecoration.cpp.

void KDecoration::clearMask  ) 
 

This convenience function resets the shape mask.

Definition at line 199 of file kdecoration.cpp.

bool KDecoration::isPreview  )  const
 

If this function returns true, the decorated window is used as a preview e.g.

in the configuration module. In such case, the decoration can e.g. show some information in the window area.

Definition at line 204 of file kdecoration.cpp.

QRect KDecoration::geometry  )  const
 

Returns the geometry of the decoration.

Definition at line 209 of file kdecoration.cpp.

Referenced by height(), setMainWidget(), and width().

QRect KDecoration::iconGeometry  )  const
 

Returns the icon geometry for the window, i.e.

the geometry of the taskbar entry. This is used mainly for window minimize animations. Note that the geometry may be null.

Definition at line 214 of file kdecoration.cpp.

QRegion KDecoration::unobscuredRegion const QRegion &  r  )  const
 

Returns the intersection of the given region with the region left unobscured by the windows stacked above the current one.

You can use this function to, for example, try to keep the titlebar visible if there is a hole available. The region returned is in the coordinate space of the decoration.

Parameters:
r The region you want to check for holes

Definition at line 219 of file kdecoration.cpp.

QWidget * KDecoration::workspaceWidget  )  const
 

Returns the main workspace widget.

The main purpose of this function is to allow painting the minimize animation or the transparent move bound on it.

Definition at line 224 of file kdecoration.cpp.

WId KDecoration::windowId  )  const
 

Returns the handle of the window that is being decorated.

It is possible the returned value will be 0. IMPORTANT: This function is meant for special purposes, and it usually should not be used. The main purpose is finding out additional information about the window's state. Also note that different kinds of windows are decorated: Toplevel windows managed by the window manager, test window in the window manager decoration module, and possibly also other cases. Careless abuse of this function will usually sooner or later lead to problems.

Since:
3.4

Definition at line 229 of file kdecoration.cpp.

int KDecoration::width  )  const [inline]
 

Convenience function that returns the width of the decoration.

Definition at line 869 of file kdecoration.h.

References geometry().

Referenced by KWinInternal::Client::isResizable().

int KDecoration::height  )  const [inline]
 

Convenience function that returns the height of the decoration.

Definition at line 874 of file kdecoration.h.

References geometry().

Referenced by KWinInternal::Client::isResizable().

void KDecoration::processMousePressEvent QMouseEvent *  e  ) 
 

This function is the default handler for mouse events.

All mouse events that are not handled by the decoration itself should be passed to it in order to make work operations like window resizing by dragging borders etc.

Definition at line 174 of file kdecoration.cpp.

virtual void KDecoration::init  )  [pure virtual]
 

This function is called immediately after the decoration object is created.

Due to some technical reasons, initialization should be done here instead of in the constructor.

KDecoration::Position KDecoration::mousePosition const QPoint &  p  )  const [pure virtual]
 

This function should return mouse cursor position in the decoration.

Positions at the edge will result in window resizing with mouse button pressed, center position will result in moving.

Definition at line 326 of file kdecoration.cpp.

References borders(), and widget().

virtual void KDecoration::borders int &  left,
int &  right,
int &  top,
int &  bottom
const [pure virtual]
 

This function should return the distance from each window side to the inner window.

The sizes may depend on the state of the decorated window, such as whether it's shaded. Decorations often turn off their bottom border when the window is shaded, and turn off their left/right/bottom borders when the window is maximized and moving and resizing of maximized windows is disabled. This function mustn't do any repaints or resizes. Also, if the sizes returned by this function don't match the real values, this may result in drawing errors or other problems.

See also:
KDecorationOptions::moveResizeMaximizedWindows()

Referenced by mousePosition().

virtual void KDecoration::resize const QSize &  s  )  [pure virtual]
 

This method is called by kwin when the style should resize the decoration window.

The usual implementation is to resize the main widget of the decoration to the given size.

Parameters:
s Specifies the new size of the decoration window.

virtual QSize KDecoration::minimumSize  )  const [pure virtual]
 

This function should return the minimum required size for the decoration.

Note that the returned size shouldn't be too large, because it will be used to keep the decorated window at least as large.

virtual void KDecoration::activeChange  )  [pure virtual]
 

This function is called whenever the window either becomes or stops being active.

Use isActive() to find out the current state.

Referenced by KWinInternal::Client::setActive().

virtual void KDecoration::captionChange  )  [pure virtual]
 

This function is called whenever the caption changes.

Use caption() to get it.

virtual void KDecoration::iconChange  )  [pure virtual]
 

This function is called whenever the window icon changes.

Use icon() to get it.

virtual void KDecoration::maximizeChange  )  [pure virtual]
 

This function is called whenever the maximalization state of the window changes.

Use maximizeMode() to get the current state.

virtual void KDecoration::desktopChange  )  [pure virtual]
 

This function is called whenever the desktop for the window changes.

Use desktop() or isOnAllDesktops() to find out the current desktop on which the window is.

virtual void KDecoration::shadeChange  )  [pure virtual]
 

This function is called whenever the window is shaded or unshaded.

Use isShade() to get the current state.

void KDecoration::keepAboveChanged bool   )  [signal]
 

This signal is emitted whenever the window's keep-above state changes.

Since:
3.3

void KDecoration::keepBelowChanged bool   )  [signal]
 

This signal is emitted whenever the window's keep-below state changes.

Since:
3.3

bool KDecoration::drawbound const QRect &  geom,
bool  clear
[virtual]
 

This function may be reimplemented to provide custom bound drawing for transparent moving or resizing of the window.

False should be returned if the default implementation should be used. Note that if you e.g. paint the outline using a 5 pixels wide line, you should compensate for the 2 pixels that would make the window look larger.

Parameters:
geom The geometry at this the bound should be drawn
clear true if the bound should be cleared
See also:
workspaceWidget() and geometry().

Definition at line 292 of file kdecoration.cpp.

bool KDecoration::animateMinimize bool  minimize  )  [virtual]
 

This function may be reimplemented to provide custom minimize/restore animations The reimplementation is allowed to perform X server grabs if necessary (only using the functions provided by this API, no direct Xlib calls), but no futher event processing is allowed (i.e.

no kapp->processEvents()). False should be returned if the default implementation should be used. Note that you should not use this function to force disabling of the animation.

See also:
workspaceWidget(), geometry() and helperShowHide().

Definition at line 297 of file kdecoration.cpp.

void KDecoration::reset unsigned long  changed  )  [virtual]
 

This function is called to reset the decoration on settings changes.

It is usually invoked by calling KDecorationFactory::resetDecorations().

Parameters:
changed Specifies which settings were changed, given by the SettingXXX masks

Definition at line 312 of file kdecoration.cpp.

void KDecoration::setMainWidget QWidget *   ) 
 

This should be the first function called in init() to specify the main widget of the decoration.

The widget should be created with parent specified by initialParentWidget() and flags specified by initialWFlags().

Definition at line 66 of file kdecoration.cpp.

References geometry(), and widget().

Referenced by createMainWidget().

void KDecoration::createMainWidget WFlags  flags = 0  ) 
 

Convenience functions that creates and sets a main widget as necessary.

In such case, it's usually needed to install an event filter on the main widget to receive important events on it.

Parameters:
flags Additional widget flags for the main widget. Note that only flags that affect widget drawing are allowed. Window type flags like WX11BypassWM or WStyle_NoBorder are forbidden.

Definition at line 60 of file kdecoration.cpp.

References initialParentWidget(), initialWFlags(), and setMainWidget().

QWidget * KDecoration::initialParentWidget  )  const
 

The parent widget that should be used for the main widget.

Definition at line 74 of file kdecoration.cpp.

Referenced by createMainWidget().

Qt::WFlags KDecoration::initialWFlags  )  const
 

The flags that should be used when creating the main widget.

It is possible to add more flags when creating the main widget, but only flags that affect widget drawing are allowed. Window type flags like WX11BypassWM or WStyle_NoBorder are forbidden.

Definition at line 79 of file kdecoration.cpp.

Referenced by createMainWidget().

void KDecoration::helperShowHide bool  show  ) 
 

This function is only allowed to be called once from animateMinimize().

It can be used if the window should be shown or hidden at a specific time during the animation. It is forbidden to use this function for other purposes.

Definition at line 307 of file kdecoration.cpp.

QWidget * KDecoration::widget  )  [inline]
 

Returns the main widget for the decoration.

Definition at line 849 of file kdecoration.h.

Referenced by mousePosition(), and setMainWidget().

const QWidget * KDecoration::widget  )  const [inline]
 

Returns the main widget for the decoration.

Definition at line 854 of file kdecoration.h.

KDecorationFactory * KDecoration::factory  )  const [inline]
 

Returns the factory that created this decoration.

Definition at line 859 of file kdecoration.h.

Referenced by KDecoration(), and ~KDecoration().

void KDecoration::grabXServer  ) 
 

Performs X server grab.

It is safe to call it several times in a row.

Definition at line 316 of file kdecoration.cpp.

void KDecoration::ungrabXServer  ) 
 

Ungrabs X server (if the number of ungrab attempts matches the number of grab attempts).

Definition at line 321 of file kdecoration.cpp.

void KDecoration::closeWindow  )  [slot]
 

This function can be called by the decoration to request closing of the decorated window.

Note that closing the window also involves destroying the decoration. IMPORTANT: This function may destroy the current decoration object, just like showWindowMenu().

Definition at line 234 of file kdecoration.cpp.

void KDecoration::maximize MaximizeMode  mode  )  [slot]
 

Set the maximize mode of the decorated window.

Parameters:
mode The maximization mode to be set.

Definition at line 244 of file kdecoration.cpp.

void KDecoration::minimize  )  [slot]
 

Minimize the decorated window.

Definition at line 249 of file kdecoration.cpp.

void KDecoration::showContextHelp  )  [slot]
 

Start showing context help in the window (i.e.

the mouse will enter the what's this mode).

Definition at line 254 of file kdecoration.cpp.

void KDecoration::setDesktop int  desktop  )  [slot]
 

Moves the window to the given desktop.

Use NET::OnAllDesktops for making the window appear on all desktops.

Definition at line 259 of file kdecoration.cpp.

Referenced by toggleOnAllDesktops().

void KDecoration::toggleOnAllDesktops  )  [slot]
 

This function toggles the on-all-desktops state of the decorated window.

Definition at line 264 of file kdecoration.cpp.

References isOnAllDesktops(), and setDesktop().

void KDecoration::titlebarDblClickOperation  )  [slot]
 

This function performs the operation configured as titlebar double click operation.

Definition at line 272 of file kdecoration.cpp.

void KDecoration::setShade bool  set  )  [slot]
 

Shades or unshades the decorated window.

Parameters:
set Whether the window should be shaded

Definition at line 277 of file kdecoration.cpp.

void KDecoration::setKeepAbove bool  set  )  [slot]
 

Sets or reset keeping this window above others.

Parameters:
set Whether to keep the window above others

Definition at line 282 of file kdecoration.cpp.

void KDecoration::setKeepBelow bool  set  )  [slot]
 

Sets or reset keeping this window below others.

Parameters:
set Whether to keep the window below others

Definition at line 287 of file kdecoration.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kwin Library Version 3.4.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Nov 4 00:45:29 2005 by doxygen 1.4.0 written by Dimitri van Heesch, © 1997-2003