Display devices, touchscreens, and mouse events

Note: differences between versions of WhiskerServer

If you have the Basic Edition version of Whisker, all display/touchscreen/mouse commands generate the following error from the server:

Error: command not supported by this version of WhiskerServer

and return Failure on the immediate socket.

How the display system works internally

When the server runs, it detects physical display devices (monitors), including the primary display.

If a physical display device is to be used, the server creates a full-screen frame window for that device — that is, it takes full control of a monitor and places a window on that monitor to obscure any others. The server attaches a default document to this window; this default document consists of a black screen. If you choose to display a test pattern on a particular monitor, the server switches the window's view to a document containing a test pattern.

Clients may create one or more display documents and place text, shapes and bitmaps on them. They may assign the display documents to display devices (once they have claimed ownership of the display device in question); only one document may be placed on a display device at a single moment. When no client-owned display documents are attached to a device, the device displays the default (black) document.

Clients may display the same document on several displays simultaneously; each copy will respond to mouse and touchscreen events identically.

On the server console program, you can view a copy of every display device the server is controlling.

Optionally, clients may create new, temporary display devices, known as virtual displays, which do not take full-screen control of an entire monitor, but appear as windows on the desktop. You may move these windows around normally; otherwise, they are treated as the other display devices. (This feature is to aid clients in creating windows, displaying graphics in them, and responding to mouse and touchscreen events. Clients can of course accomplish this by programming Windows directly, unless they are running on a different computer to the server.)

Documents and devices must have unique names. (Display devices may have more than one alias refer to them, but each alias must be unique.)

To communicate with the display system, the server uses DirectX (DirectDraw) with multimonitor extensions (available under Windows 2000, but not Windows NT 4).

The number of colours and display resolution used on a monitor is determined by Windows (Control Panel → Display).

Display and document sizes

The size of a physical display is obviously predetermined. You can query its size in pixels using the DisplayGetSize command.

The size of a virtual display may also be queried with DisplayGetSize. However, at the moment you create a virtual display (using DisplayCreateDevice) you may specify its size in pixels. You may also choose whether the user should be allowed to resize the window, and you can request a starting position on the desktop; however, you cannot prevent the user moving the window.

Physical and virtual displays may show documents unchanged (showing a scroll bar if the document is larger than the display), or scale their document to fit the device's window size. Choose this using the DisplayScaleDocuments command. Scaling is off by default.

You may specify the logical size of a document using the DisplaySetDocumentSize command. Until you do this, the document will expand to surround all the objects you place in it. The size that you set in this way affects only one thing – the size to which the document is scaled/scrolled.

This enables you to scale documents for different monitors with ease. Suppose you have created a document and laid out objects on it on the assumption that it will be viewed on a 1024 × 768 display. If you have to use it on an 800 × 600 display, the right and bottom edges will not be seen. But you can scale it instead:

               DisplaySetDocumentSize mydoc 1024 768

               DisplayScaleDocuments smallscreen on

               DisplayShowDocument smallscreen mydoc

This facility means you can choose your coordinate space freely. However, you should note that shrinking very detailed pictures to fit onto a smaller monitor may result in loss of detail.

Mouse and touchscreen events

If you can move the mouse cursor onto a display (and the display is enabled for mouse input, see User Guide), clicking the mouse will have the same effects as touching the touchscreen, and vice versa.

Keyboard events

Whisker supports keyboard events. This facility is intended primarily for human testing.

One Windows PC can only have one keyboard attached to it. It is therefore unlikely to be useful to run several clients that require keyboard input simultaneously, as only one can receive keyboard events at one time. This is exactly the same as other programs under Windows: you can't type into your wordprocessor and your Telnet session at the same time (you can of course switch between them) because only one window has what is termed the focus at one moment. The same is true of Whisker: only when a display has the focus will keyboard events work.

In practice, then, single clients for testing humans may find keyboard events useful. Keyboard events are associated with display documents. They are slightly different to other kinds of events, as you do not specify which keys you are interested in; simply that you want to be notified when keys are pressed (or released, or both). Whisker then sends a KeyEvent: message telling the client which key has been pressed. See DisplayKeyboardEvents for details.

Display system commands

Displays and associated devices are controlled using the following commands: