PMGuide - Cursors

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

A cursor is a rectangle that can be shown at any location in a window, indicating where the user's next interaction with items on the screen will happen. This chapter describes how to create and use cursors in your PM applications.

About Cursors

Only one cursor appears on the screen at a time-either marking the text-insertion point (a text cursor) or indicating which items the user can interact with from the keyboard (a selection cursor). For example, when an entry field has the keyboard focus, it displays a blinking vertical bar to show the text-insertion point; however, when a button has the keyboard focus, the cursor appears as a halftone rectangle the size of the button. The operating system draws and blinks the cursor, freeing the application from handling these details. Notice that the cursor has no direct relationship with the mouse pointer.

Cursor Creation and Destruction

The system can use only one cursor at a time, so windows must create and destroy cursors as each windows gains and loses the keyboard focus. If an application attempts to use more than one cursor at a time, the results can be unpredictable and might affect other applications.

An application creates a cursor by calling WinCreateCursor. Generally, this is done when a window gains the keyboard focus. The application specifies the window in which to display the cursor, whether it be the desktop window, an application window, or a control window. An application destroys a cursor by calling WinDestroyCursor- when the specified window loses the keyboard focus, for example.

Position and Size

An application can set the position (in window coordinates) of an existing cursor by calling WinCreateCursor, specifying the CURSOR_SETPOS flag. The cursor width is usually 0 (nominal border width is used) for text-insertion cursors. This is preferable to a value of 1, since such a fine width is almost invisible on a high-resolution monitor. The cursor width also can be related to the window size-for example, when a button control uses a dotted-line cursor around the button text to indicate focus. To change the cursor size, the application must destroy the current cursor and create a new one of the desired size.

Other Cursor Characteristics

An application uses the WinCreateCursor function to specify information about the cursor rectangle and the clipping rectangle. WinCreateCursor specifies whether the cursor rectangle should be filled, framed, blinking, or halftone. In addition, the function specifies the clipping rectangle, in window coordinates, that controls the cursor clipping region. Probably the most efficient strategy is for the application to specify NULL, which causes the rectangle to clip the cursor to the window rectangle.

Cursor Visibility

An application can use the WinShowCursor function to show or hide a cursor. The operating system maintains a show level for the cursor: when the cursor is visible, the its show level is zero; each time the cursor is hidden, its show level is incremented; each time the cursor is shown, its show level is decremented. The show:hide relationship is 1:1, so the show level cannot drop below zero. When first creating a cursor, an application should show the cursor because the application creates the cursor with a show level of 1.

The operating system automatically hides the cursor when the application calls WinBeginPaint; it shows the cursor when the application calls WinEndPaint. Therefore, there is no conflict with the cursor during WM_PAINT processing.

Using Cursors

This section explains how to perform the following tasks:

• Create and destroy a cursor
• Respond to a WM_SETFOCUS message

Creating and Destroying a Cursor

The following code fragment shows how an application should respond to a WM_SETFOCUS message when using a cursor in a particular window:

    LONG   curXPos,curYPos,curWidth,curHeight;

    case WM_SETFOCUS:
        if (SHORT1FROMMP(mp2)) {

            /* Gain the focus. */
            WinCreateCursor(hwnd, curXPos, curYPos, curWidth, curHeight,
                CURSOR_SOLID | CURSOR_FLASH, (PRECTL) NULL);
            WinShowCursor(hwnd, TRUE);
        }
        else {

            /* Lose the focus. */
            WinDestroyCursor(hwnd);
        }

        return 0;