|
|
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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[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 |
[static]
Invokes the logout process (session management, logout dialog, ...)
Note: May have no effect with other window mangers
void |
[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 |
[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 |
[static]
Clients who manipulated the config file of the windowmanager should call this afterwards
Note: May have no effect with other window mangers
int |
[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 |
[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 |
[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 |
[static]
Is the window a kwm module?
void |
[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 |
[static]
Is the window a kwm dock module?
bool |
[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 |
[static]
Returns the window which has the focus
void |
[static]
Switches to the specified virtual desktop
void |
[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 |
[static]
Returns the window region of the specified virtual desktop.
int |
[static]
Returns the number of virtual desktops.
void |
[static]
Sets the number of virtual desktops. Modules like kpanel are informed.
void |
[static]
Changes a name of a virtual desktop. Modules like kpanel are informed.
QString |
[static]
Returns the name of the specified virtual desktop.
void |
[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 |
[static]
The standard window title. If kwm runs, title() will return the title kwm uses. These titles are always unique.
QString |
[static]
titleWithState is aequivalent to title(), but inside round brackets for iconified window
QPixmap |
[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 |
[static]
Same as miniIcon() above, but for the full icon.
int |
[static]
Returns the virtual desktop on which the window is located.
QRect |
[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 |
[static]
geometry restore is only defined for maximized window. It is the geometry a window will get when it is unmaximized.
QRect |
[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 |
[static]
Is the window iconified?
bool |
[static]
Is the window maximized?
bool |
[static]
Shall the window be maximized?
int |
[static]
The maximize mode, either horizontal, vertical or fullscreen
int |
[static]
The doMaximize mode, either horizontal, vertical or fullscreen
bool |
[static]
Is the window sticky?
long |
[static]
Returns the KDE decoration hints of the window.
bool |
[static]
Is the window sticky?
bool |
[static]
Does the window contain unsaved data? (KDE hint)
bool |
[static]
Does the window define the KDE unsaved data hint at all?
bool |
[static]
Does the window have the focus?
void |
[static]
Move the window to another virutal desktop
void |
[static]
Set the geometry of a window
void |
[static]
Set the restore geometry (before maximize) of a window
void |
[static]
Set the icon geometry of a window.
void |
[static]
Move a window to another geometric position
void |
[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 |
[static]
for binary compatibility, the above with default argument mode = horitzonal|vertical
void |
[static]
Maximize a window (changing the geometry to fill the entire screen).
void |
[static]
for binary compatibility, the above with default argument mode = horitzonal|vertical
void |
[static]
Iconify/UnIconify a window according to value
void |
[static]
Sticky/UnSticky a window according to value
void |
[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 |
[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 |
[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 |
[static]
raise the specified window. Should work with any windowmanager
void |
[static]
lower the specified window. Should work with any windowmanager
void |
[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 |
[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 |
[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 |
[static]
An i18n'ed string for maximize.
QString |
[static]
An i18n'ed string for unmaximize
QString |
[static]
An i18n'ed string for iconify
QString |
[static]
An i18n'ed string for uniconify
QString |
[static]
An i18n'ed string for sticky
QString |
[static]
An i18n'ed string for unsticky.
QString |
[static]
An i18n'ed string for move.
QString |
[static]
An i18n'ed string for resize.
QString |
[static]
An i18n'ed string for close.
QString |
[static]
An i18n'ed string for "toDesktop".
QString |
[static]
An i18n'ed string for "ontoCurrentDesktop".
bool |
[static]
Is the window a docking window?
int |
[static]
Returns the X window state of the specified winodw