PMGuide - Mouse Pointers and Icons

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 mouse pointer is a special bit map the operating system uses to show a user the current location of the mouse on the screen. When the user moves the mouse, the mouse pointer moves on the screen. This chapter describes how to create and use mouse pointers and icons in PM applications.

About Mouse Pointers and Icons

Mouse pointers and icons are made up of bit maps that the operating system uses to paint images of the pointers or icons on the screen. A monochrome bit map is a series of bytes. Each bit corresponds to a single pel in the image. (The bit map representing the display typically has four bits for each pel.)

A mouse pointer or icon bit map always is twice as tall as it is wide. The top half of the bit map is an AND mask, in which the bits are combined, using the AND operator, with the screen bits where the pointer is being drawn. The lower half of the bit map is an XOR mask, in which the bits are combined, using the XOR operator, with the destination screen bits.

The combination of the AND and XOR masks results in four possible colors in the bit map. The pels of an icon or pointer can be black, white, transparent (the screen color beneath the pel), or inverted (inverting the screen color beneath the pel). The following figure shows the relationship of the bit values in the AND and XOR masks:

AND mask	0	0	1	1
XOR mask	0	1	0	1
Result	Black	White	Transparent	Inverted

Mouse-Pointer Hot Spot

Each mouse pointer has its own hot spot, which is the point that represents the exact location of the mouse pointer. This location is defined as an x and y offset from the lower-left corner of the mouse-pointer bit map. For the arrow-shaped pointer, the hot spot is at the tip of the arrow. For the I-beam pointer, the hot spot is at the middle of the vertical line.

Predefined Mouse Pointers

Before an application can use a mouse pointer, it first must receive a handle to the pointer. Most applications load mouse pointers from the system or from their own resource file. The operating system maintains many predefined mouse pointers that an application can use by calling WinQuerySysPointer. System mouse pointers include all the standard mouse-pointer shapes and message-box icons. The following predefined mouse pointers are available:

Mouse Pointer	Description
SPTR_APPICON	Square icon; used to represent a minimized application window.
SPTR_ARROW	Arrow that points to the upper-left corner of the screen.
SPTR_ICONERROR	Icon containing an exclamation point; used in a warning message box.
SPTR_ICONINFORMATION	Octagon-shaped icon containing the image of a human hand; used in a warning message box.
SPTR_ICONQUESTION	Icon containing a question mark; used in a query message box.
SPTR_ICONWARNING	Icon containing an asterisk; used in a warning message box.
SPTR_MOVE	Four-headed arrow; used when dragging an object or window around the screen.
SPTR_SIZE	Small box within a box; used when resizing a window by dragging.
SPTR_SIZENS	Two-headed arrow that points up and down (north and south); used when sizing a window.
SPTR_SIZENESW	Two-headed diagonal arrow that points to the upper-right (northeast) and lower-left (southwest) window borders; used when sizing a window.
SPTR_SIZENWSE	Two-headed diagonal arrow that points to the upper-left (northwest) and lower-right (southeast) window borders; used when sizing a window.
SPTR_SIZEWE	Two-headed arrow that points left and right (west to east); used when sizing a window.
SPTR_TEXT	Text-insertion and selection pointer, often called the I-beam pointer.
SPTR_WAIT	Hourglass; used to indicate that a time-consuming operation is in progress.

The operating system contains a second set of predefined mouse pointers that are used as icons in PM applications. An application can use one of these icons by supplying one of the following constants in WinQuerySysPointer. If a copy of the system pointer is made using WinQuerySysPointer, the pointer copy must be destroyed using WinDestroyPointer before termination of the application.

Icon	Description
SPTR_FILE	Represents a file (in the shape of a single sheet of paper).
SPTR_FOLDER	Represents a file folder.
SPTR_ILLEGAL	Circular icon containing a slash; represents an illegal operation.
SPTR_MULTFILE	Represents multiple files.
SPTR_PROGRAM	Represents an executable file.

Applications can use mouse-pointer resources to draw icons. WinDrawPointer draws a specified mouse pointer in a specified presentation space. Many of the predefined system mouse pointers are standard icons displayed in message boxes.

In addition to using the predefined pointer shapes, an application also can use pointers that have been defined in a resource file. Once the pointer or icon has been created (by Icon Editor or a similar application), the application includes it in the resource file, using the POINTER statement, a resource identifier, and a file name for the Icon Editor data. After including the mouse-pointer resource, the application can use the pointer or icon by calling WinLoadPointer, specifying the resource identifier and module handle. Typically, the resource is in the executable file of the application, so the application simply can specify NULL for the module handle to indicate the current application resource file.

An application can create mouse pointers at run time by constructing a bit map for the pointer and calling WinCreatePointer. This function, if successful, returns the new pointer handle, which the application then can use to set or draw the pointer. The bit map must be twice as tall as it is wide, with the first half defining the AND mask and the second half defining the XOR mask. The application also must specify the hot spot when creating the mouse pointer.

System Bit Maps

In addition to using the mouse pointers and icons defined by the system, applications can use standard system bit maps by calling WinGetSysBitmap. This function returns a bit map handle that is passed to WinDrawBitmap or to one of the GPI bit-map functions. The system uses standard bit maps to draw portions of control windows, such as the system menu, minimize/maximize box, and scroll-bar arrows. The following standard system bit maps are available:

Bit Map	Description
SBMP_BTNCORNERS	Specifies the bit map for push button corners.
SBMP_CHECKBOXES	Specifies the bit map for the check-box or radio-button check mark.
SBMP_CHILDSYSMENU	Specifies the bit map for the smaller version of the system-menu bit map; used in child windows.
SBMP_CHILDSYSMENUDEP	Same as SBMP_CHILDSYSMENU but indicates that the system menu is selected.
SBMP_COMBODOWN	Specifies the bit map for the downward pointing arrow in a drop-down combination box.
SBMP_MAXBUTTON	Specifies the bit map for the maximize button.
SBMP_MENUATTACHED	Specifies the bit map for the symbol used to indicate that a menu item has an attached, hierarchical menu.
SBMP_MENUCHECK	Specifies the bit map for the menu check mark.
SBMP_MINBUTTON	Specifies the bit map for the minimize button.
SBMP_OLD_CHILDSYSMENU	Same as SBMP_CHILDSYSMENU. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_MAXBUTTON	Same as SBMP_MAXBUTTON. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_MINBUTTON	Same as SBMP_MINBUTTON. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_RESTOREBUTTON	Same as SBMP_RESTOREBUTTON. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_SBDNARROW	Same as SBMP_SBDNARROW. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_SBLFARROW	Same as SBMP_SBLFARROW. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_SBRGARROW	Same as SBMP_SBRGARROW. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_OLD_SBUPARROW	Same as SBMP_SBUPARROW. (For compatibility with previous versions of the OS/2 operating system.)
SBMP_PROGRAM	Specifies the bit map for the symbol that File Manager uses to indicate that a file is an executable program.
SBMP_RESTOREBUTTON	Specifies the bit map for the restore button.
SBMP_RESTOREBUTTONDEP	Same as SBMP_RESTOREBUTTON but indicates that the restore button is pressed.
SBMP_SBDNARROW	Specifies the bit map for the scroll-bar down arrow.
SBMP_SBDNARROWDEP	Same as SBMP_SBDNARROW but indicates that the scroll-bar down arrow is pressed.
SBMP_SBDNARROWDIS	Same as SBMP_SBDNARROW but indicates that the scroll-bar down arrow is disabled.
SBMP_SBLFARROW	Specifies the bit map for the scroll-bar left arrow.
SBMP_SBLFARROWDEP	Same as SBMP_SBLFARROW but indicates that the scroll-bar left arrow is pressed.
SBMP_SBMFARROWDIS	Same as SBMP_SBLFARROW but indicates that the scroll-bar left arrow is disabled.
SBMP_SBRGARROW	Specifies the bit map for the scroll-bar right arrow.
SBMP_SBRGARROWDEP	Same as SBMP_SBRGARROW but indicates that the scroll-bar right arrow is pressed.
SBMP_SBRGARROWDIS	Same as SBMP_SBRGARROW but indicates that the scroll-bar right arrow is disabled.
SBMP_SBUPARROW	Specifies the bit map for the scroll-bar up arrow.
SBMP_SBUPARROWDEP	Same as SBMP_SBUPARROW but indicates that the scroll-bar up arrow is pressed.
SBMP_SBUPARROWDIS	Same as SBMP_SBUPARROW but indicates that the scroll-bar up arrow is disabled.
SBMP_SIZEBOX	Specifies the bit map for the symbol that indicates an area of a window in which the user can click to resize the window.
SBMP_SYSMENU	Specifies the bit map for the system menu.
SBMP_TREEMINUS	Specifies the bit map for the symbol that File Manager uses to indicate an empty entry in the directory tree.
SBMP_TREEPLUS	Specifies the bit map for the symbol that File Manager uses to indicate that an entry in the directory tree contains more files.

Using Mouse Pointers and Icons

This section explains how to perform the following tasks:

• Save the current mouse pointer
• Change the mouse pointer
• Restore the original mouse pointer

Changing the Mouse Pointer

Once you create or load a mouse pointer, you can change its shape by calling WinSetPointer. Following are three typical situations in which an application changes the shape of the mouse pointer:

• When an application receives a WM_MOUSEMOVE message, there is an opportunity to change the mouse pointer based on its location in the window. If you want the standard arrow pointer, pass this message on to WinDefWindowProc. If you want to change the mouse pointer on a standard dialog window, you need to capture the WM_CONTROLPOINTER message and return a pointing-device pointer handle.

• When an application is about to start a time-consuming process during which it will not accept user input, the application displays the system-wait mouse pointer (SPTR_WAIT). Upon finishing the process, the application resets the mouse pointer to its former shape.

The following code fragment shows how to save the current mouse pointer, set the hourglass pointer, and restore the original mouse pointer. Notice that the hourglass pointer also is saved in a global variable so that the application can return it when responding to a WM_MOUSEMOVE message during a time-consuming process.

   HPOINTER hptrOld, hptrWait, hptrCurrent;

        /* Get the current pointer.                   */
        hptrOld = WinQueryPointer(HWND_DESKTOP);

        /* Get the wait mouse pointer.                */
        hptrWait = WinQuerySysPointer(HWND_DESKTOP,
            SPTR_WAIT, FALSE);

        /* Save the wait pointer to use in WM_MOUSEMOVE processing.*/
        hptrCurrent = hptrWait;

        /* Set the mouse pointer to the wait pointer. */
        WinSetPointer(HWND_DESKTOP, hptrWait);

        /*
         * Do a time-consuming operation, then restore the
         * original mouse pointer.
         */
        WinSetPointer(HWND_DESKTOP, hptrOld);

• When an application needs to indicate its current operational mode, it changes the pointer shape. For example, a paint program with a palette of drawing tools should change the pointer shape to indicate which drawing tool is in use currently.