class KWM

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

Definition#include <kwm.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Static Methods


Detailed Description

WARNING! THIS CLASS WILL DISSAPPEAR IN KDE-2.0

With the raise of a common wm-spec standard and KDE-2.0 supporting X11R6 session management, this class becomes obsolete.

Instead, there will a class KWin to deal with the common window operations (will work with all window managers then) and another class to raise desktop sound events (likely KDESound). The communication protocol ( sendKWMCommand() ) will dissappear completely. Hacks based on that shall be replaced with real IPC based on DCOP.

END OF WARNING

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  properties (Window w)

[static]

Return all window properties needed to restore a window in a string. The string can be used as a command line argument for the session management (See setWmCommand below).

QRect  setProperties (Window w, const QString &props)

[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)

[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(<your window>, "");)

void  setWmCommand (Window w, const QString &command)

[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)

[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.

Note 2: May have no effect with other windowmanagers

void  setIcon (Window w, const QPixmap &pm)

[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)

[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)

[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 ()

[static]

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

Note: May have no effect with other window mangers

void  refreshScreen ()

[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 ()

[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 ()

[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 ()

[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)

[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)

[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)

[static]

Is the window a kwm module?

void  setKWMDockModule (Window w)

[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)

[static]

Is the window a kwm dock module?

bool  isKWMInitialized ()

[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 ()

[static]

Returns the window which has the focus

void  switchToDesktop (int desk)

[static]

Switches to the specified virtual desktop

void  setWindowRegion (int desk, const QRect &region)

[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  windowRegion (int desk)

[static]

Returns the window region of the specified virtual desktop.

int  numberOfDesktops ()

[static]

Returns the number of virtual desktops.

void  setNumberOfDesktops (int num)

[static]

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

void  setDesktopName (int desk, const QString &name)

[static]

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

QString  desktopName (int desk)

[static]

Returns the name of the specified virtual desktop.

void  sendKWMCommand (const QString &command)

[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)

[static]

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

QString  titleWithState (Window w)

[static]

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

QPixmap  miniIcon (Window w, int width=0, int height=0)

[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)

[static]

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

int  desktop (Window w)

[static]

Returns the virtual desktop on which the window is located.

QRect  geometry (Window w, bool including_frame = false)

[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)

[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)

[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)

[static]

Is the window iconified?

bool  isMaximized (Window w)

[static]

Is the window maximized?

bool  isDoMaximize (Window w)

[static]

Shall the window be maximized?

int  maximizeMode (Window w)

[static]

The maximize mode, either horizontal, vertical or fullscreen

int  doMaximizeMode (Window w)

[static]

The doMaximize mode, either horizontal, vertical or fullscreen

bool  isSticky (Window w)

[static]

Is the window sticky?

long  decoration (Window w)

[static]

Returns the KDE decoration hints of the window.

bool  fixedSize (Window w)

[static]

Is the window sticky?

bool  containsUnsavedData (Window w)

[static]

Does the window contain unsaved data? (KDE hint)

bool  unsavedDataHintDefined (Window w)

[static]

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

bool  isActive (Window w)

[static]

Does the window have the focus?

void  moveToDesktop (Window w, int desk)

[static]

Move the window to another virutal desktop

void  setGeometry (Window w, const QRect &geom)

[static]

Set the geometry of a window

void  setGeometryRestore (Window w, const QRect &geom)

[static]

Set the restore geometry (before maximize) of a window

void  setIconGeometry (Window w, const QRect &geom)

[static]

Set the icon geometry of a window.

void  move (Window w, const QPoint &pos)

[static]

Move a window to another geometric position

void  setMaximize (Window w, bool value, int mode )

[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)

[static]

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

void  doMaximize (Window w, bool value, int mode)

[static]

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

void  doMaximize (Window w, bool value)

[static]

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

void  setIconify (Window w, bool value)

[static]

Iconify/UnIconify a window according to value

void  setSticky (Window w, bool value)

[static]

Sticky/UnSticky a window according to value

void  close (Window w)

[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)

[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)

[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)

[static]

raise the specified window. Should work with any windowmanager

void  lower (Window w)

[static]

lower the specified window. Should work with any windowmanager

void  prepareForSwallowing (Window w)

[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 windowmanager does not care about them.

void  doNotManage (const QString&)

[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.

void  keepOnTop (Window w)

[static]

Tell the window manager that you like to have this window on top of all other windows. The last window to call keepOnTop() has the highest priority. KDE's desktop panel and taskbar are two example windows that make use of this functionality.

Note: May have no effect with other windowmanagers.

QString  maximizeString ()

[static]

An i18n'ed string for maximize.

QString  unMaximizeString ()

[static]

An i18n'ed string for unmaximize

QString  iconifyString ()

[static]

An i18n'ed string for iconify

QString  unIconifyString ()

[static]

An i18n'ed string for uniconify

QString  stickyString ()

[static]

An i18n'ed string for sticky

QString  unStickyString ()

[static]

An i18n'ed string for unsticky.

QString  moveString ()

[static]

An i18n'ed string for move.

QString  resizeString ()

[static]

An i18n'ed string for resize.

QString  closeString ()

[static]

An i18n'ed string for close.

QString  toDesktopString ()

[static]

An i18n'ed string for "toDesktop".

QString  ontoCurrentDesktopString ()

[static]

An i18n'ed string for "ontoCurrentDesktop".

bool  isDockWindow (Window w)

[static]

Is the window a docking window?

int  windowState (Window w)

[static]

Returns the X window state of the specified winodw