Материал из Wiki.crossplatform.ru

Текущая версия на 09:56, 29 января 2009

Внимание: Актуальная версия перевода документации находится здесь

__NOTOC__

[править] QWSServer Class Reference
^{[модуль QtGui ]}

The QWSServer class encapsulates a server process in Qtopia Core. Далее...

 #include <QWSServer>

Inherits QObject.

• Список всех членов, включая унаследованные
• Obsolete members
• Поддерживаемые члены Qt 3

[править] Открытые типы

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

[править] Открытые функции

• 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 открытых функций, унаследованных от QObject

[править] Сигналы

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

• 1 сигнал, унаследованный от QObject

[править] Статические открытые члены

• 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 * driver )
• void setMaxWindowRect ( const QRect & rectangle )
• void setMouseHandler ( QWSMouseHandler * driver )
• void setScreenSaver ( QWSScreenSaver * screenSaver )
• void setScreenSaverBlockLevel ( int eventBlockLevel )
• void setScreenSaverInterval ( int milliseconds )
• void setScreenSaverIntervals ( int * intervals )

• 5 статических открытых членов, унаследованных от QObject

[править] Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 7 защищенных функций, унаследованных от QObject

[править] Подробное описание

The QWSServer class encapsulates a server process in Qtopia Core.

When you run a Qtopia Core application, it either runs as a server or connects to an existing server. The server and client processes have different responsibilities: The client process performs all application specific operations. The server process is responsible for managing the clients as well as taking care of the pointer handling, character input, and screen output. In addition, the server provides functionality to handle input methods.

In Qtopia Core, all system generated events are passed to the server application which then propagates the event to the appropriate client. See the Qtopia Core Architecture documentation for details.

Note that this class is instantiated by QApplication for Qtopia Core server processes; you should never construct this class yourself. Use the instance() function to retrieve a pointer to the server object.

Note that the static functions of the QWSServer class can only be used in the server process.

• Client Administration
• Mouse Handling
• Keyboard Handling
• Display Handling
• Input Method Handling

[править] Client Administration

As applications add and remove windows, the server process maintains information about each window. In Qtopia Core, top-level windows are encapsulated as QWSWindow objects. 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.

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, respectively.

See also: QWSWindow, QWSClient and QCopChannel.

[править] Mouse Handling

The mouse driver (represented by an instance of the QWSMouseHandler class) is loaded by the server application when it starts running, using Qt's plugin system. A mouse driver receives mouse events from the device and encapsulates each event with an instance of the QWSEvent class which it then passes to the server.

The openMouse() function opens the mouse devices specified by the QWS_MOUSE_PROTO environment variable, and the setMouseHandler() functions sets the primary mouse driver. Alternatively, the static setDefaultMouse() function provides means of specifying the mouse driver to use if the QWS_MOUSE_PROTO variable is not defined (note that the default is otherwise platform dependent). The primary mouse driver can be retrieved using the static mouseHandler() function. Use the closeMouse() function to delete the mouse drivers.

In addition, the QWSServer class can control the flow of mouse input using the suspendMouse() and resumeMouse() functions.

See also: QWSMouseHandler and Qtopia Core Pointer Handling.

[править] Keyboard Handling

The keyboard driver (represented by an instance of the QWSKeyboardHandler class) is loaded by the server application when it starts running, using Qt's plugin system. A keyboard driver receives keyboard events from the device and encapsulates each event with an instance of the QWSEvent class which it then passes to the server.

The openKeyboard() function opens the keyboard devices specified by the QWS_KEYBOARD environment variable, and the setKeyboardHandler() functions sets the primary keyboard driver. Alternatively, the static setDefaultKeyboard() function provides means of specifying the keyboard driver to use if the QWS_KEYBOARD variable is not defined (note again that the default is otherwise platform dependent). The primary keyboard driver can be retrieved using the static keyboardHandler() function. Use the closeKeyboard() function to delete the keyboard drivers.

In addition, the QWSServer class can 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 also: QWSKeyboardHandler and Qtopia Core Character Input.

[править] Display Handling

When a screen update is required, the server runs through all the top-level windows that intersect with the region that is about to be updated, and ensures that the associated clients have updated their memory buffer. Then the server uses the screen driver (represented by an instance of the QScreen class) to copy the content of the memory to the screen.

In addition, the QWSServer class provides some means of managing the screen output: Use the refresh() function to refresh the entire display, or alternatively a specified region of it. The enablePainting() function can be used to disable (and enable) painting onto the screen. 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. To set the brush used as the background in the absence of obscuring windows, QWSServer provides the static setBackground() function. The corresponding backgroundBrush() function returns the currently set brush.

QWSServer also controls the screen saver: Use the setScreenSaver() to install a custom screen saver derived from the QWSScreenSaver class. Once installed, the screensaver can be activated using the screenSaverActivate() function, and the screenSaverActive() function returns its current status. Use the setScreenSaverInterval() function to specify the timeout interval. Qtopia Core also supports multilevel screen saving, use the setScreenSaverIntervals() function to specify the various levels and their timeout intervals.

Finally, the QWSServer class controls the cursor's appearance, i.e., use the setCursorVisible() function to hide or show the cursor, and the isCursorVisible() function to determine whether the cursor is visible on the display or not.

See also: QScreen and Qtopia Core Display Management.

[править] Input Method Handling

Whenever the server receives an event, it queries its stack of top-level windows to find the window containing the event's position (each window can identify the client application that created it). Then the server forwards the event to the appropriate client. If an input method is installed, it is used as a filter between the server and the client application.

Derive from the QWSInputMethod class to create custom input methods, and use the server's setCurrentInputMethod() function to install it. Use the sendIMEvent() and sendIMQuery() functions to send input method events and queries.

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: QWSInputMethod

[править] Описание типов

[править]

enum QWSServer::IMMouse

This enum describes the various types of mouse events recognized by the QWSInputMethod::mouseHandler() function.

See also QWSInputMethod and setCurrentInputMethod().

[править]

enum QWSServer::WindowEvent

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

See also windowEvent().

[править] Описание функций-членов

[править]

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

Activates the given keyboard filter 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).

Note that this function can only be used in the server process.

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.

Use the QWSWindow::client() function to retrieve the client application that owns a given window.

See also windowAt() and instance().

[править]

void QWSServer::closeKeyboard ()

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

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

See also openMouse() and mouseHandler().

[править]

void QWSServer::enablePainting ( bool enable )

Enables painting onto the screen if enable is true; otherwise painting is disabled.

See also Qtopia Core Architecture.

[править]

QWSServer * QWSServer::instance () [static]

Returns a pointer to the server instance.

Note that the pointer will be 0 if the application is not the server, i.e., if the QApplication::type() function doesn't return QApplication::GuiServer.

Эта функция была введена в Qt 4.2.

See also clientWindows() and windowAt().

[править]

bool QWSServer::isCursorVisible () [static]

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

Note that this function can only be used in the server process.

See also setCursorVisible().

[править]

QWSKeyboardHandler * QWSServer::keyboardHandler () [static]

Returns the primary keyboard driver.

Note that this function can only be used in the server process.

See also setKeyboardHandler(), openKeyboard(), and closeKeyboard().

[править]

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.

See also windowEvent().

[править]

QWSMouseHandler * QWSServer::mouseHandler () [static]

Returns the primary mouse driver.

Note that this function can only be used in the server process.

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

[править]

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. Be advised that closeMouse() is called first to delete all the existing mouse handlers. This behaviour could be the cause of problems if you were not expecting it.

See also closeMouse() and mouseHandler().

[править]

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

Processes the given key event. The key is identified by its unicode value and the given keycode, modifiers, isPress and autoRepeat parameters.

The keycode parameter is the Qt keycode value as defined by the Qt::Key enum. The modifiers is an OR combination of Qt::KeyboardModifier values, indicating whether Shift/Alt/Ctrl keys are pressed. The isPress parameter is true if the event is a key press event and autoRepeat is true if the event is caused by an auto-repeat mechanism and not an actual key press.

This function is typically called internally by keyboard drivers. Note that this function can only be used in the server process.

See also sendKeyEvent() and Qtopia Core Character Input.

[править]

void QWSServer::refresh ()

Refreshes the display by making the screen driver update the entire display.

See also QScreen::exposeRegion().

[править]

void QWSServer::refresh ( QRegion & region )

Эта перегруженная функция предоставлена для удобства.

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 removing each added keyboard filter.

Note that this function can only be used in the server process.

See also addKeyboardFilter().

[править]

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

This signal is emitted immediately after the given 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 pointer handling by reactivating all the mouse drivers registered by the QWS_MOUSE_PROTO environment variable.

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

[править]

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

Activates the screen saver if activate is true; otherwise it is deactivated.

Note that this function can only be used in the server process.

See also screenSaverActive() and setScreenSaver().

[править]

bool QWSServer::screenSaverActive () [static]

Returns true if the screen saver is active; otherwise returns false.

Note that this function can only be used in the server process.

See also screenSaverActivate().

[править]

void QWSServer::sendIMEvent ( const QInputMethodEvent * event )

Sends the given input method event.

The QInputMethodEvent class is derived from QWSEvent, i.e., it is a QWSEvent object of the QWSEvent::IMEvent type.

If there is a window actively composing the preedit string, the event is sent to that window. Otherwise, the event is sent to the window currently in focus.

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

[править]

void QWSServer::sendIMQuery ( int property )

Sends an input method query for the given property.

To receive responses to input method queries, the virtual QWSInputMethod::queryResponse() function must be reimplemented in a QWSInputMethod subclass that is activated using the setCurrentInputMethod() function.

See also sendIMEvent() and setCurrentInputMethod().

[править]

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

Sends the given key event. The key is identified by its unicode value and the given keycode, modifiers, isPress and autoRepeat parameters.

Use this function to send key events generated by "virtual keyboards" (note that the processKeyEvent() function is impelemented using this function).

The keycode parameter is the Qt keycode value as defined by the Qt::Key enum. The modifiers is an OR combination of Qt::KeyboardModifier values, indicating whether Shift/Alt/Ctrl keys are pressed. The isPress parameter is true if the event is a key press event and autoRepeat is true if the event is caused by an auto-repeat mechanism and not an actual key press.

Note that this function can only be used in the server process.

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.

Note that this function can only be used in the server process.

See also backgroundBrush().

[править]

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

Sets the current input method to be the given method.

Note that this function can only be used in the server process.

See also sendIMQuery() and sendIMEvent().

[править]

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

Shows the cursor if visible is true: otherwise the cursor is hidden.

Note that this function can only be used in the server process.

See also isCursorVisible().

[править]

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

Sets the keyboard driver that will be used if the QWS_KEYBOARD environment variable is not defined, to be the given keyboardDriver.

Note that the default is platform-dependent. This function can only be used in the server process.

See also setKeyboardHandler() and Qtopia Core Character Input.

[править]

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

Sets the mouse driver that will be used if the QWS_MOUSE_PROTO environment variable is not defined, to be the given mouseDriver.

Note that the default is platform-dependent. This function can only be used in the server process.

See also setMouseHandler() and Qtopia Core Pointer Handling.

[править]

void QWSServer::setKeyboardHandler ( QWSKeyboardHandler * driver ) [static]

Sets the primary keyboard driver to be the given driver.

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.

Note that this function can only be used in the server process.

See also keyboardHandler() and setDefaultKeyboard().

[править]

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

Sets the maximum area of the screen that Qtopia Core applications can use, to be the given rectangle.

Note that this function can only be used in the server process.

See also QWidget::showMaximized().

[править]

void QWSServer::setMouseHandler ( QWSMouseHandler * driver ) [static]

Sets the primary mouse driver to be the given driver.

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.

Note that this function can only be used in the server process.

See also mouseHandler() and setDefaultMouse().

[править]

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

Installs the given screenSaver, deleting the current screen saver.

Note that this function can only be used in the server process.

See also screenSaverActivate(), setScreenSaverInterval(), setScreenSaverIntervals(), and setScreenSaverBlockLevel().

[править]

void QWSServer::setScreenSaverBlockLevel ( int eventBlockLevel ) [static]

Block the key or mouse event that wakes the system from level eventBlockLevel or higher. To completely disable event blocking (the default behavior), set eventBlockLevel to -1.

The algorithm blocks the "down", "up" as well as any "repeat" events for the same key but will not block other key events after the initial "down" event. For mouse events, the algorithm blocks all mouse events until an event with no buttons pressed is received.

There are 2 keys that are never blocked, Qt::Key_F34 (POWER) and Qt::Key_F35 (LIGHT).

Example usage:

 bool MyScreenSaver::save( int level )
 {
     switch ( level ) {
         case 0:
             if ( dim_enabled ) {
                 // dim the screen
             }
             return true;
         case 1:
             if ( screenoff_enabled ) {
                 // turn off the screen
             }
             return true;
         case 2:
             if ( suspend_enabled ) {
                 // suspend
             }
             return true;
         default:
             return false;
     }
 }
 
 ...
 
 int timings[4];
 timings[0] = 5000;  // dim after 5 seconds
 timings[1] = 10000; // light off after 15 seconds
 timings[2] = 45000; // suspend after 60 seconds
 timings[3] = 0;
 QWSServer::setScreenSaverIntervals( timings );
 
 // ignore the key/mouse event that turns on the screen
 int blocklevel = 1;
 if ( !screenoff_enabled ) {
     // screenoff is disabled, ignore the key/mouse event that wakes from suspend
     blocklevel = 2;
     if ( !suspend_enabled ) {
         // suspend is disabled, never ignore events
         blocklevel = -1;
     }
 }
 QWSServer::setScreenSaverBlockLevel( blocklevel );

Note that this function can only be used in the server process.

See also setScreenSaverIntervals() and setScreenSaverInterval().

[править]

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

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

Note that this function can only be used in the server process.

See also setScreenSaverIntervals() and setScreenSaverBlockLevel().

[править]

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

Specifies the time intervals (in milliseconds) between the different levels of screen responsiveness.

Qtopia Core supports multilevel screen saving, i.e., it is possible to specify several different levels of screen responsiveness by implementing the QWSScreenSaver::save() function. For example, you can choose to first turn off the light before you fully activate the screensaver. See the QWSScreenSaver documentation for details.

Note that an interval of 0 milliseconds will turn off the screensaver, and that the intervals array must be 0-terminated. This function can only be used in the server process.

See also setScreenSaverInterval() and setScreenSaverBlockLevel().

[править]

void QWSServer::suspendMouse ()

Suspends pointer handling by deactivating all the mouse drivers registered by the QWS_MOUSE_PROTO environment variable.

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

[править]

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

Returns the window containing the given position.

Note that if there is no window under the specified point this function returns 0.

See also clientWindows() and instance().

[править]

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), passing a pointer to the window and the event's type in the window and eventType parameters, respectively.

See also markedText().