Qt 4.2: QWSServer Class Reference

|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# QWSServer Class Reference
[QtGui module]

The QWSServer class provides server-specific functionality in Qtopia Core. More...

     #include <QWSServer>

Inherits QObject.

- List of all members, including inherited members
- Obsolete members
- Qt 3 support members

### Public Types

- class KeyboardFilter
- enum IMMouse { MousePress, MouseRelease, MouseMove, MouseOutside }
- enum WindowEvent { Create, Destroy, Hide, Show, ..., Name }

### Public Functions

- const QBrush & backgroundBrush () const
- const QList<QWSWindow *> & clientWindows ()
- void closeKeyboard ()
- void closeMouse ()
- void enablePainting ( bool enable )
- void openKeyboard ()
- void openMouse ()
- void refresh ()
- void refresh ( QRegion & region )
- void resumeMouse ()
- void sendIMEvent ( const QInputMethodEvent * event )
- void sendIMQuery ( int property )
- void suspendMouse ()
- QWSWindow * windowAt ( const QPoint & position )

- 29 public functions inherited from QObject

### Signals

- void markedText ( const QString & selection )
- void newChannel ( const QString & channel )
- void removedChannel ( const QString & channel )
- void windowEvent ( QWSWindow * window, QWSServer::WindowEvent eventType )

- 1 signal inherited from QObject

### Static Public Members

- void addKeyboardFilter ( KeyboardFilter * filter )
- QWSServer * instance ()
- bool isCursorVisible ()
- QWSKeyboardHandler * keyboardHandler ()
- QWSMouseHandler * mouseHandler ()
- void processKeyEvent ( int unicode, int keycode, Qt::KeyboardModifiers modifiers, bool isPress, bool autoRepeat )
- void removeKeyboardFilter ()
- void screenSaverActivate ( bool activate )
- bool screenSaverActive ()
- void sendKeyEvent ( int unicode, int keycode, Qt::KeyboardModifiers modifiers, bool isPress, bool autoRepeat )
- void setBackground ( const QBrush & brush )
- void setCurrentInputMethod ( QWSInputMethod * method )
- void setCursorVisible ( bool visible )
- void setDefaultKeyboard ( const char * keyboardDriver )
- void setDefaultMouse ( const char * mouseDriver )
- void setKeyboardHandler ( QWSKeyboardHandler * handler )
- void setMaxWindowRect ( const QRect & rectangle )
- void setMouseHandler ( QWSMouseHandler * handler )
- void setScreenSaver ( QWSScreenSaver * screenSaver )
- void setScreenSaverInterval ( int milliseconds )
- void setScreenSaverIntervals ( int * intervals )

- 5 static public members inherited from QObject

### Additional Inherited Members

- 1 property inherited from QObject
- 1 public slot inherited from QObject
- 7 protected functions inherited from QObject

## Detailed Description

The QWSServer class provides server-specific functionality in Qtopia Core.

When you run a Qtopia Core application, it either runs as a server or connects to an existing server. If it runs as a server, the QWSServer class provides additional functionality to handle the clients as well as the mouse, keyboard, display and input methods.

Note that this class is instantiated by QApplication for Qtopia Core server processes; you should never construct this class yourself. Access to the QWSServer instance can be obtained using the global qwsServer pointer.

- Client Administration
- Mouse and Keyboard Handling
- Display Handling
- Input Method Handling

### Client Administration

In Qtopia Core, the top-level windows are encasulated as QWSWindow objects. The collection of windows changes as applications add and remove widgets, and each window can tell which client that owns it through its QWSWindow::client() function. Use the clientWindows() function to retrieve a list of the current top-level windows. Given a particular position on the display, the window containing it can be retrieved using the windowAt() function.

QWSServer also provides the windowEvent() signal which is emitted whenever something happens to a top level window; the WindowEvent enum describes the various types of events that the signal recognizes. In addition, the server class provides the markedText() signal which is emitted whenever some text has been selected in any of the windows, passing the selection as parameter.

See the QWSWindow and QWSClient class documentation for more details.

The QCopChannel class and the QCOP communication protocol enable transfer of messages between clients. QWSServer provides the newChannel() and removedChannel() signals that is emitted whenever a new QCopChannel object is created or destroyed. See the QCopChannel class documentation for details on client communication.

### Mouse and Keyboard Handling

To open the mouse devices specified by the QWS_MOUSE_PROTO environment variable, use the openMouse() function. Alternatively, the static setDefaultMouse() function provides means of specifying the default mouse driver to use if the QWS_MOUSE_PROTO variable is not defined. Note that the default is otherwise platform dependent. The primary mouse handler can be retrieved using the static mouseHandler() function. Use the closeMouse() function to delete the mouse handlers.

Likewise, open the keyboard devices specified by the QWS_KEYBOARD environment variable by using the openKeyboard() function. Alternatively, the static setDefaultKeyboard() function provides means of specifying the default keyboard driver to use if the QWS_KEYBOARD variable is not defined. Note again tha the default is otherwise platform dependent. The primary keyboard handler can be retrieved using the static keyboardHandler() function. Use the closeKeyboard() function to delete the keyboard handlers.

In addition, the QWSServer class can control the flow of mouse input using the suspendMouse() and resumeMouse() functions (see QWSMouseHandler for more details), and handle key events from both physical and virtual keyboards using the processKeyEvent() and sendKeyEvent() functions, respectively. Use the addKeyboardFilter() function to filter the key events from physical keyboard drivers, the most recently added filter can be removed and deleted using the removeKeyboardFilter() function. See Qtopia Core Character Input and QWSKeyboardHandler for more information.

Finally, the keyMap() function returns the keyboard mapping table used to convert keyboard scancodes to Qt keycodes and Unicode values.

### Display Handling

To set the brush used as the background in the absence of obscuring windows, QWSServer provides the static setBackground() function. The backgroundBrush() function returns the currently set brush.

Use the refresh() function to refresh the entire display, or alternatively a specified region of it. The enablePainting() function can be used to control the privileges for painting on the display. QWSServer also provide the setMaxWindowRect() function restricting the area of the screen which Qtopia Core applications will consider to be the maximum area to use for windows.

The setScreenSaver() function provides the option of installing a custom screensaver derived from the QWSScreenSaver class. Once installed, the screensaver can be activated using the screenSaverActivate() function, and the screenSaverActive() function returns its current status. The screensaver's timeout intervals can be specified using the setScreenSaverInterval() and setScreenSaverIntervals() functions.

Use the isCursorVisible() function to determine if the cursor is visible on the display, use the setCursorVisible() function to alter its visibility.

### Input Method Handling

Custom input methods derived from the QWSInputMethod class, can be installed using the setCurrentInputMethod(). Use the sendIMEvent() and sendIMQuery() functions to send input method events and queries. Finally, QWSServer provides the IMMouse enum describing the various mouse events recognized by the QWSInputMethod::mouseHandler() function. The latter function allows subclasses of QWSInputMethod to handle mouse events within the preedit text.

See also QWSClient and Running Qtopia Core Applications.

## Member Type Documentation

### enum QWSServer::IMMouse

This enum describes the various types of mouse events recognized by the QWSInputMethod::mouseHandler() function which allows subclasses of QWSInputMethod to handle mouse events within the preedit text.

Constant | Value | Description
--- | --- | ---
`QWSServer::MousePress` | `0` | An event generated by pressing a mouse button.
`QWSServer::MouseRelease` | `1` | An event generated by relasing a mouse button.
`QWSServer::MouseMove` | `2` | An event generated by moving the mouse cursor.
`QWSServer::MouseOutside` | `3` | This value is only reserved, i.e. it is not used in current implementations.

See also QWSInputMethod::mouseHandler().

### enum QWSServer::WindowEvent

This enum specifies the various events that can occur in a top-level window.

Constant | Value | Description
--- | --- | ---
`QWSServer::Create` | `0x0001` | A new window has been created (by the QWidget constructor).
`QWSServer::Destroy` | `0x0002` | The window has been closed and deleted (by the QWidget destructor).
`QWSServer::Hide` | `0x0004` | The window has been hidden using the QWidget::hide() function.
`QWSServer::Show` | `0x0008` | The window has been shown using the QWidget::show() function or similar.
`QWSServer::Raise` | `0x0010` | The window has been raised to the top of the desktop.
`QWSServer::Lower` | `0x0020` | The window has been lowered.
`QWSServer::Geometry` | `0x0040` | The window has changed size or position.
`QWSServer::Active` | `0x0080` | The window has become the active window (i.e. it has keyboard focus).
`QWSServer::Name` | `0x0100` | The window has been named.

See also windowEvent().

## Member Function Documentation

### void QWSServer::addKeyboardFilter ( KeyboardFilter * filter ) `[static]`

Makes the given filter the one invoked for all key events generated by physical keyboard drivers (i.e. events sent using the processKeyEvent() function).

Note that the filter is not invoked for keys generated by virtual keyboard drivers (i.e. events sent using the sendKeyEvent() function).

See also removeKeyboardFilter().

### const QBrush & QWSServer::backgroundBrush () const

Returns the brush used as background in the absence of obscuring windows.

See also setBackground().

### const QList<QWSWindow *> & QWSServer::clientWindows ()

Returns the list of current top-level windows.

Note that the collection of top-level windows changes as applications add and remove widgets so it should not be stored for future use. The windows are sorted in stacking order from top-most to bottom-most.

See also windowAt() and QWSClient.

### void QWSServer::closeKeyboard ()

Closes all the keyboard devices (specified by the QWS_KEYBOARD environment variable) by deleting the associated keyboard handlers.

See also openKeyboard() and keyboardHandler().

### void QWSServer::closeMouse ()

Closes all pointer devices (specified by the QWS_MOUSE_PROTO environment variable) by deleting the associated mouse handlers.

See also openMouse() and mouseHandler().

### void QWSServer::enablePainting ( bool enable )

If enable is true, painting on the display is enabled; otherwise painting is disabled.

See also QDirectPainter and QScreen.

### QWSServer * QWSServer::instance () `[static]`

Returns a pointer to the application's QWSServer instance. The pointer will be 0 if the application is not the window server, e.g. QApplication::type() != QApplication::GuiServer.

This function was introduced in Qt 4.2.

### bool QWSServer::isCursorVisible () `[static]`

Returns true if the cursor is visible; otherwise returns false.

See also setCursorVisible().

### QWSKeyboardHandler * QWSServer::keyboardHandler () `[static]`

Returns the primary keyboard handler.

See also setKeyboardHandler() and openKeyboard().

### void QWSServer::markedText ( const QString & selection ) `[signal]`

This signal is emitted whenever some text is selected in any of the running applications, passing the selected text in the selection parameter.

### QWSMouseHandler * QWSServer::mouseHandler () `[static]`

Returns the primary mouse handler.

See also setMouseHandler(), closeMouse(), and openMouse().

### void QWSServer::newChannel ( const QString & channel ) `[signal]`

This signal is emitted whenever a new QCopChannel object is created, passing the channel's name in the channel parameter.

See also removedChannel().

### void QWSServer::openKeyboard ()

Opens the keyboard devices specified by the QWS_KEYBOARD environment variable.

See also closeKeyboard() and keyboardHandler().

### void QWSServer::openMouse ()

Opens the mouse devices specified by the QWS_MOUSE_PROTO environment variable.

See also closeMouse() and mouseHandler().

### void QWSServer::processKeyEvent ( int unicode, int keycode, Qt::KeyboardModifiers modifiers, bool isPress, bool autoRepeat ) `[static]`

Processes the key event characterized by the given parameters:

Parameter | Description
--- | ---
unicode | The unicode value of the key to send
keycode | The Qt keycode value as defined by the Qt::Key enum.
modifiers | An OR combination of Qt::KeyboardModifier values, indicating whether Shift/Alt/Ctrl keys are pressed.
isPress | True if this is a key down event; otherwise false.
autoRepeat | True if this event is caused by auto repeat (i.e. the user has held the key down and this is the second or subsequent key event being sent); otherwise false.

This function is typically called internally by keyboard drivers.

See also sendKeyEvent(), addKeyboardFilter(), and Qtopia Core Character Input.

### void QWSServer::refresh ()

Refreshes the entire display.

### void QWSServer::refresh ( QRegion & region )

This is an overloaded member function, provided for convenience.

Refreshes the given region of the display.

### void QWSServer::removeKeyboardFilter () `[static]`

Removes and deletes the most recently added filter.

Note that the programmer is responsible for matching each addition of a keyboard filter with a corresponding removal.

See also addKeyboardFilter().

### void QWSServer::removedChannel ( const QString & channel ) `[signal]`

This signal is emitted immediately after the QCopChannel object specified by channel, is destroyed.

Note that a channel is not destroyed until all its listeners have been unregistered.

See also newChannel().

### void QWSServer::resumeMouse ()

Resumes mouse handling by reactivating each registered mouse handler.

See also suspendMouse(), QWSMouseHandler::resume(), and QWS_MOUSE_PROTO.

### void QWSServer::screenSaverActivate ( bool activate ) `[static]`

Activates the screensaver immediately if the activate is true; otherwise it is deactivated.

See also screenSaverActive().

### bool QWSServer::screenSaverActive () `[static]`

Returns true if the screensaver is active (i.e. the screen is blanked); otherwise returns false.

See also screenSaverActivate().

### void QWSServer::sendIMEvent ( const QInputMethodEvent * event )

Sends the given input method event.

If there is a window currently in compose mode (i.e. actively composing the preedit string ), the event is sent to that window. Otherwise, the event is sent to the current focus window.

See also sendIMQuery() and QWSInputMethod::sendEvent().

### void QWSServer::sendIMQuery ( int property )

Sends an input method query for the specified property.

To receive responses to input method queries the virtual QWSInputMethod::queryResponse() function must be reimplemented in a QWSInputMethod subclass.

See also sendIMEvent() and QWSInputMethod::sendQuery().

### void QWSServer::sendKeyEvent ( int unicode, int keycode, Qt::KeyboardModifiers modifiers, bool isPress, bool autoRepeat ) `[static]`

Sends a key event. Note that this function is called by the processKeyEvent() function. Use this function to send key events generated by "virtual keyboards".

Parameter | Description
--- | ---
unicode | The unicode value of the key to send
keycode | The Qt keycode value as defined by the Qt::Key enum.
modifiers | An OR combination of Qt::KeyboardModifier values, indicating whether Shift/Alt/Ctrl keys are pressed.
isPress | True if this is a key down event; otherwise false.
autoRepeat | True if this event is caused by auto repeat (i.e. the user has held the key down and this is the second or subsequent key event being sent); otherwise false.

See also processKeyEvent() and Qtopia Core Character Input.

### void QWSServer::setBackground ( const QBrush & brush ) `[static]`

Sets the brush used as background in the absence of obscuring windows, to be the given brush.

See also backgroundBrush().

### void QWSServer::setCurrentInputMethod ( QWSInputMethod * method ) `[static]`

Sets the current input method to be the given method.

See also sendIMQuery(), sendIMEvent(), and QWSInputMethod.

### void QWSServer::setCursorVisible ( bool visible ) `[static]`

Makes the cursor visible if visible is true: otherwise the cursor is made invisible.

See also isCursorVisible().

### void QWSServer::setDefaultKeyboard ( const char * keyboardDriver ) `[static]`

Sets the keyboard driver that is used if the QWS_KEYBOARD environment variable is not defined, to be the given keyboardDriver. The default is platform-dependent.

See also Qtopia Core Character Input.

### void QWSServer::setDefaultMouse ( const char * mouseDriver ) `[static]`

Sets the mouse driver that is used if the QWS_MOUSE_PROTO environment variable is not defined, to be the given mouseDriver. The default is platform-dependent.

See also Qtopia Core Pointer Handling.

### void QWSServer::setKeyboardHandler ( QWSKeyboardHandler * handler ) `[static]`

Sets the primary keyboard handler to be the given handler.

Qtopia Core provides several ready-made keyboard drivers, and custom drivers are typically added using Qt's plugin mechanism. See the {Qtopia Core Character Input} documentation for details.

See also keyboardHandler().

### void QWSServer::setMaxWindowRect ( const QRect & rectangle ) `[static]`

Sets the area of the screen which Qtopia Core applications will consider to be the maximum area to use for windows, to the area specified by the given rectangle.

See also QWidget::showMaximized().

### void QWSServer::setMouseHandler ( QWSMouseHandler * handler ) `[static]`

Sets the mouse driver to be the given handler.

Qtopia Core provides several ready-made mouse drivers, and custom drivers are typically added using Qt's plugin mechanism. See the {Qtopia Core Pointer Handling} documentation for details.

See also mouseHandler().

### void QWSServer::setScreenSaver ( QWSScreenSaver * screenSaver ) `[static]`

Deletes the current screensaver and installs the given screenSaver instead.

See also screenSaverActivate().

### void QWSServer::setScreenSaverInterval ( int milliseconds ) `[static]`

Sets the timeout interval for the screensaver to be the specified milliseconds. To turn off the screensaver, set the timout interval to 0.

See also setScreenSaverIntervals().

### void QWSServer::setScreenSaverIntervals ( int * intervals ) `[static]`

Sets a list of timeout intervals (specified in millisecond) for the screensaver. An interval of 0 milliseconds turns off the screensaver.

Note that the array must be 0-terminated.

See also setScreenSaverInterval().

### void QWSServer::suspendMouse ()

Suspends mouse handling by suspending each registered mouse handler.

See also resumeMouse(), QWSMouseHandler::suspend(), and QWS_MOUSE_PROTO.

### QWSWindow * QWSServer::windowAt ( const QPoint & position )

Returns the window containing the given position, returns 0 if there is no window under the specified point.

See also clientWindows().

### void QWSServer::windowEvent ( QWSWindow * window, QWSServer::WindowEvent eventType ) `[signal]`

This signal is emitted whenever something happens to a top-level window (e.g. it's created or destroyed).

The window to which the event has occurred and the event's type are passed in the window and eventType parameters, respectively.

## Member Function Documentation

### QWSServer::QWSServer ( int flags, QObject * parent, const char * name )

Use the two-argument overload and call setObjectName() instead.

### void QWSServer::setDesktopBackground ( const QImage & img ) `[static]`

Sets the image img to be used as the background in the absence of obscuring windows.

### void QWSServer::setDesktopBackground ( const QColor & c ) `[static]`

This is an overloaded member function, provided for convenience.

Sets the color c to be used as the background in the absence of obscuring windows.