KWM Class Reference

[kdecore Index] [kdecore Hierarchy] [Headers]


class for interaction with the window- and sessionmanager More...

#include <kwm.h>

Public Members


Detailed Description

The class KWM allows usual X11 clients to get or modify window properties and to interact with the windowmanager. It also offers some high level functions to support the easy implementation of session managment.


QString getProperties(Window w) [public static]

Return all window properties needed to restore a window in a string. The string can be used as a command line argument

QRect setProperties(Window w, const QString &props) [public static]

Apply properties from a property string to a window. This will have an immediate effect if the window is already managed by the window manager (that means it is either in Normal- or in IconicState). If the window is still WithDrawn, the windowmanager will apply the properties when the window is mapped (This happens for example with a QWidget::show() ). If setProperties is used for session management, you should call it first and map the window later, since this avoids unnecessary flickering.

setProperties returns the geometry of the property string.

Note: Some window managers may not understand all kwm properties, but all common properties such as geometry or IconicState should nevertheless work anyway.

void enableSessionManagement(Window w) [public static]

This will tell the windowmanager that your client is able to do session management. If you do this, your client MUST react on WM_SAVE_YOURSELF client messages by setting the XA_WM_COMMAND property. This can be easily done with a call to setWmCommand (see below). If your application has several top level windows which are not transient, you can enable session management only for the main toplevel window, but call setWmCommand for the others with an empty (not null) string as argument. You should/can do that already when you create these windows. It will prevent the session manager from believing that this window does not support session management at all. Whenever you react on WM_SAVE_YOURSELF, you will have to call setWmCommand. Passing an empty (not null) string is legal: The session manager will understand this as an indicator that everything is ok and that your application window may be restored by somebody else ;-)

Note: If you enable session management although your client does not react correctly on WM_SAVE_YOURSELF client messages, the window manager cannot perform the logout process, that means the GUI will hang!

Note 2: Session management needs a session manager. In KDE this is also done by the windowmanager kwm. Other windowmangers might not support this, so you may have to run a standalone session manager instead. Anyway, enabling session management does not harm in the case a user does not run a session manager. He/she simply will not have session management, but all other functionality.

Note 3: PSEUDO SESSION MANAGEMENT There is also another way to do pseudo session management: 1) do NOT enable session management 2) call setWmCommand (see below) anyway and set the command which was used to start your application.

This is exactly what old X11 applications like xterm, xedit or xv do. BTW setWmCommand will also set the WM_CLIENT_MACHINE property, which allows the session manager to restart the application on the correct machine.

kwm will act similar to smproxy: the window properties will be stored and applied again when the window will be mapped after the restart. To avoid unnecessary flickering or jumping of windows it is important to call setWmCommand BEFORE your window is mapped!

Anyway your application will appear in a warning box in kwm, which indicates that the user might have some data loss. If you do not want that (because your application does not contain any data to be lost, for example a clock), you may simply call setUnsavedDataHint with FALSE as value. Note that this hint is read only when the user logs out, so the last value will be used. You can also set it to TRUE to indicate that the user will certainly have some data loss. All these things may of course have no effect with other window- or session managers.

Note 4: kwm also supports session management for toplevel windows that are not mapped (and never have been mapped). This is very usefull for programms with n windows, where n can be 0 (like kfm, for example), which want to recieve a WM_SAVE_YOURSELF message nevertheless. The same as usual: If you do not want the session manager to restart your application, since it is already started by the usual startup script (True for kfm), set the command to an empty string (setWmCommand(, "");)

void setWmCommand(Window w, const QString &command) [public static]

Store a shell command that can be used to restore the client. This should be done as reaction on a WM_SAVE_YOURSELF client message. setWmCommand also sets the WM_CLIENT_MACHINE property to allow a session management to restart your application even on the correct machine.

void setMiniIcon(Window w, const QPixmap &pm) [public static]

Set a mini icon for your application window. This icon may appear in the window decoration as well as on taskbar buttons. Therefore it should be very small (kwm for example will scale it to 14x14, so 14x14 may be the size of choice).

setMiniIcon will _not_ change the icon_pixmap property of the standard XWMHints, but define a special KWM_WIN_ICON property. This has the advantage, that your application can support standard X11 icons (which are usually _very_ large) if it runs with mwm for example, as well as modern KDE-like miniicons.

Note: kwm will even detect changes of this property when your window is mapped.

void setIcon(Window w, const QPixmap &pm) [public static]

Set a standard (large) icon for the application window. If you are using Qt this should be almost aequivalent to a call to QWidget::setIcon(..)

void setDockWindow(Window w) [public static]

This declares a toplevel window to be a docking window. If a KWMDockModule is running (for example kpanel), it will swallow the window on its docking area when it is mapped.

For docking call setDockWindow() on a new _unmapped_ toplevel window. If this window will be mapped (show), it will appear on the docking area, if you unmap it again (hide) it will disappear from the docking area again. Docking windows MUST be toplevel windows. If you create them with Qt (new QWidget()->winId()) be sure not to pass any parent.

Note: May have no effect with other window mangers

void setDecoration(Window w, long value) [public static]

Some windows do not want to be decorated at all but should not be override_redirect (for example toolbars which are dragged out of their main window). This can be achieved with a simple call to setDecoration() even if the window is already mapped.

KWM understands the following values at present: noDecoration : Not decorated at all normalDecoration : Normal decoration (transient windows with dialog decoration, shaped windows not decorated at all)

tinyDecoration : Tiny decoration (just a little frame)

If your window does not want the focus, you can OR the decoration property with noFocus, for example kpager: KWM::setDecoration(winId(), KWM::tinyDecoration | KWM::noFocus);

Last not least, you can tell the window manager to keep the window always on top of other windows by combing a decoration with the KWM::staysOnTop flag, for example KWM::setDecoration(winId(), KWM::normalDecoration | KWM::staysOnTop);

Note: X11R6 does not offer a standard property or protocoll for this purpose. So kwm uses a KDE specific property which may have no effect with other window managers.

void logout() [public static]

Invokes the logout process (session management, logout dialog, ...)

Note: May have no effect with other window mangers

void refreshScreen() [public static]

Clients who draw over other windows should call refreshScreen() afterwards to force an ExposureEvent on all visible windows. Also necessary after darkenScreen();

Note: May have no effect with other window mangers

void darkenScreen() [public static]

Draw a black matrix over the entire screen to make it look darker. Clients who use this should grab the X server afterwards and also call refreshScreen() after releasing the X server.

Note: May have no effect with other window mangers

void configureWm() [public static]

Clients who manipulated the config file of the windowmanager should call this afterwards

Note: May have no effect with other window mangers

int currentDesktop() [public static]

The current virtual desktop. This is usefull if your program behaves different on different desktops (for example a background drawing program) but does not itself need to be a window manager module (which recieve a message when the current desktop changes)

void raiseSoundEvent(const QString &event) [public static]

Raise/register/unregister sound events. The number of character in the event name is limited to 20.

Note: May have no effect with other window mangers

void setKWMModule(Window w) [public static]

Declare a toplevel window to be used for module communication. This window does not need to be mapped, although it can be mapped of course. Module windows MUST be toplevel windows. If you create them with Qt (new QWidget()->winId()) be sure not to pass any parent. Modules get the following client messages from kwm. Argument is either a window ((Window) XClientMessageEvent.data.l[0]), a (long) number or nothing.

KWM_MODULE_INIT - initialization starts KWM_MODULE_INITIALIZED - initialization is complete KWM_MODULE_DESKTOP_CHANGE - new current virtual desktop KWM_MODULE_DESKTOP_NAME_CHANGE - a desktop got a new name KWM_MODULE_DESKTOP_NUMBER_CHANGE - the number of desktop changed KWM_MODULE_WIN_ADD - new window KWM_MODULE_DIALOG_WIN_ADD - new dialog window. The signal comes _before_ the WIN_ADD signal to allow clients to exclude dialog windows. KWM_MODULE_WIN_REMOVE - remove window KWM_MODULE_WIN_CHANGE - size, properties, map state etc. KWM_MODULE_WIN_RAISE - raise and lower allow a module (for example KWM_MODULE_WIN_LOWER a pager) to keep the stacking order KWM_MODULE_WIN_ACTIVATE - new active (focus) window KWM_MODULE_WIN_ICON_CHANGE - window got a (new) icon

KDE_SOUND_EVENT - a sound event KDE_REGISTER_SOUND_EVENT - registration of a new sound event KDE_UNREGISTER_SOUND_EVENT - remove a registration

Please check out the KWMModuleApplication class which gives you easy access to all these messages via Qt signals and slots. It also keeps automatically a list of windows in both stacking and creation order.

bool isKWMModule(Window w) [public static]

Is the window a kwm module?

void setKWMDockModule(Window w) [public static]

Note that there can only be one single KWMDockModule at the same time. The first one to come wins. The later can check the result with isKWMDockModule.

The KWMDockModule recieves two additional client messages: KWM_MODULE_DOCKWIN_ADD KWM_MODULE_DOCKWIN_REMOVE

bool isKWMDockModule(Window w) [public static]

Is the window a kwm dock module?

bool isKWMInitialized() [public static]

This is usefull for modules which depend on a running windowmanager for the correct settings of the number of desktops or the desktop names (for example kpanel). Just insert while (!KWM::isKWMInitialized()) sleep(1); in the main function of your application to wait for kwm being ready. As an alternative you can also wait for the init-signal of KWMModuleApplication.

Window activeWindow() [public static]

Returns the window which has the focus

void switchToDesktop(int desk) [public static]

Switches to the specified virtual desktop

void setWindowRegion(int desk, const QRect &region) [public static]

Window region define the rectangle where windows can appear. A window which can be fully maximized will exactly fill this region. The regions are settable withing kwm to allow desktop panels like kpanel to stay visible even if a window becomes maximized. kwm will store the regions in the kwmrc when exiting.

QRect getWindowRegion(int desk) [public static]

Returns the window region of the specified virtual desktop.

int numberOfDesktops() [public static]

Returns the number of virtual desktops.

void setNumberOfDesktops(int num) [public static]

Sets the number of virtual desktops. Modules like kpanel are informed.

void setDesktopName(int desk, const QString &name) [public static]

Changes a name of a virtual desktop. Modules like kpanel are informed.

QString getDesktopName(int desk) [public static]

Returns the name of the specified virtual desktop.

void sendKWMCommand(const QString &command) [public static]

low level kwm communication. This can also be used for a one-way communication with modules, since kwm sends messages, which it does not understand, to all modules. You module should declare a short unque praefix for this task.

Note: the length of a command is limited to 20 character. This stems from the limitations of an ordinary X11 client messages.

QString title(Window w) [public static]

The standard window title. If kwm runs, title() will return the title kwm uses. These titles are always unique.

QString titleWithState(Window w) [public static]

titleWithState is aequivalent to title(), but inside round brackets for iconified window

QPixmap miniIcon(Window w, int width=0, int height=0) [public static]

if no miniicon is set, miniIcon() will return the standard icon. The result will be scaled to (width, height) if it is larger. Otherwise it will not be modified. If you do not specify width or height, the result will be returned in its native size. Returns a null pixmap in the case no icon is defined.

QPixmap icon(Window w, int width=0, int height=0) [public static]

Same as miniIcon() above, but for the full icon.

int desktop(Window w) [public static]

Returns the virtual desktop on which the window is located.

QRect geometry(Window w, bool including_frame = FALSE) [public static]

Returns the geometry of a window. If including_frame is set, then the geometry of kwm's decoration frame is returned. This functions tries to work even for non-KDE-compliant window managers. Anyway, since this is a bit weird in X the result cannot be guaranteed to be correct then.

QRect geometryRestore(Window w) [public static]

geometry restore is only defined for maximized window. It is the geometry a window will get when it is unmaximized.

QRect iconGeometry(Window w) [public static]

Returns the icon geometry of a window. This is either the defined icon geometry from a setIconGeometry() call, or the center of the window in case there was no geometry or an empty geometry defined.

bool isIconified(Window w) [public static]

Is the window iconified?

bool isMaximized(Window w) [public static]

Is the window maximized?

bool isDoMaximize(Window w) [public static]

Shall the window be maximized?

int maximizeMode(Window w) [public static]

The maximize mode, either horizontal, vertical or fullscreen

int doMaximizeMode(Window w) [public static]

The doMaximize mode, either horizontal, vertical or fullscreen

bool isSticky(Window w) [public static]

Is the window sticky?

long getDecoration(Window w) [public static]

Returns the KDE decoration hints of the window.

bool fixedSize(Window w) [public static]

Is the window sticky?

bool containsUnsavedData(Window w) [public static]

Does the window contain unsaved data? (KDE hint)

bool unsavedDataHintDefined(Window w) [public static]

Does the window define the KDE unsaved data hint at all?

bool isActive(Window w) [public static]

Does the window have the focus?

void moveToDesktop(Window w, int desk) [public static]

Move the window to another virutal desktop

void setGeometry(Window w, const QRect &geom) [public static]

Set the geometry of a window

void setGeometryRestore(Window w, const QRect &geom) [public static]

Set the restore geometry (before maximize) of a window

void setIconGeometry(Window w, const QRect &geom) [public static]

Set the icon geometry of a window.

void move(Window w, const QPoint &pos) [public static]

Move a window to another geometric position

void setMaximize(Window w, bool value, int mode ) [public static]

Maximize/Unmaximize a window according to value. If the window is not mapped yet, this function only sets the _state_ of the maximize button, it does _not_ change the geometry. See doMaximize below.

The mode can either be horizontal or vertical or ( the default) fullscreen

void setMaximize(Window w, bool value) [public static]

for binary compatibility, the above with default argument mode = horitzonal|vertical

void doMaximize(Window w, bool value, int mode) [public static]

Maximize a window (changing the geometry to fill the entire screen).

void doMaximize(Window w, bool value) [public static]

for binary compatibility, the above with default argument mode = horitzonal|vertical

void setIconify(Window w, bool value) [public static]

Iconify/UnIconify a window according to value

void setSticky(Window w, bool value) [public static]

Sticky/UnSticky a window according to value

void close(Window w) [public static]

close will send a WM_DELETE_WINDOW message to the window, if this window requested for this protocol. Otherwise it will simply be destroyed.

void activate(Window w) [public static]

activate will deiconify the window, if is is iconified, or switch to another desktop, if the window is there. Then the window is raised and activated with activateInteral (see below)

void activateInternal(Window w) [public static]

activateInternal will simply activate the window. Be carefull: you might run into trouble if the window is iconified or on another desktop! You probably prefer activate (see above).

void raise(Window w) [public static]

raise the specified window. Should work with any windowmanager

void lower(Window w) [public static]

lower the specified window. Should work with any windowmanager

void prepareForSwallowing(Window w) [public static]

if you like to swallow a mapped window ( == XReparentWindow) you should call prepareForSwallowing before. This will set the window to WithDrawnState (and also wait until the window achieved this state), what usually let the windowmanager remove all its decorations and re-reparent the window to the root window.

You do not need to call prepareForSwallowing if you are sure that the window is already in withdrawn state and unmanaged (i.e. still a child of the root window). This is usually the case if the window was never shown, but not always. Some windowmanagers may even manage newly created unmapped windows, although this is not a good idea to do. If the window is not in withdrawn state but managed by the windowmanager, then the windowmanager may react on the synthetic unmapNotify event created from XReparentWindow by reparenting the window back to the root window. Since this happen after your XReparentWindow, you did not swallow it but put it onto the desktop without any decoration frame instead! prepareForSwallowing helps to avoid this case.

Note: You _never_ need to call prepareForSwallowing if you are using kwm, since kwm is very clever regarding unmapNotify events. If you like to ensure that your software works with other windowmanager though, you should better do it. Please keep in mind that taking windows away from windowmanagers is a sensitive topic. That means: Even prepareForSwallowing may fail with certain non-standard windowmanagers.

Also note that all this stuff only affects toplevel windows. Reparenting subwindows is no problem at all, since a

void doNotManage(const QString&) [public static]

doNotManage(...) allows to define the first 20 character of a window title (or a regular expression) that should not be managed by the windowmanager. This is useful to avoid flickering when a panel swallows legacy applications. doNotManage(...) applies only for the first window which meets the criteria.

Note: May have no effect with other windowmanagers.

QString getMaximizeString() [public static]

An i18n'ed string for maximize.

QString getUnMaximizeString() [public static]

An i18n'ed string for unmaximize

QString getIconifyString() [public static]

An i18n'ed string for iconify

QString getUnIconifyString() [public static]

An i18n'ed string for uniconify

QString getStickyString() [public static]

An i18n'ed string for sticky

QString getUnStickyString() [public static]

An i18n'ed string for unsticky.

QString getMoveString() [public static]

An i18n'ed string for move.

QString getResizeString() [public static]

An i18n'ed string for resize.

QString getCloseString() [public static]

An i18n'ed string for close.

QString getToDesktopString() [public static]

An i18n'ed string for "toDesktop".

QString getOntoCurrentDesktopString() [public static]

An i18n'ed string for "ontoCurrentDesktop".

bool isDockWindow(Window w) [public static]

Is the window a docking window?

int getWindowState(Window w) [public static]

Returns the X window state of the specified winodw


  • Author: Matthias Ettrich (ettrich@kde.org)
  • Documentation generated by tasin@cd1 on Die Nov 30 17:31:35 CET 1999
Kdoc