MMProgRef - Graphic Button Control

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

Multimedia Programming Reference

Introduction What's New... MCI Functions High-Level Macro Service Functions Subsystem Messages Notification Messages MCI Command Messages String Commands Memory Playlist Commands Graphic Button Control Secondary Window Functions MMIO Functions MMIO Messages CODEC Messages DIVE Functions Real-Time MIDI Functions SPI Functions Data Stream State Table SMH Messages DDCMD Messages VSD Commands SHD Messages SHC Messages Data Types Types of MIDI Messages Multimedia Specification Overview Resource Interchange File Format Multimedia File Formats RIFF Compound Files and Elements - Sharing and Access Return Codes Notices Glossary

This section describes graphic button styles and control messages. Graphic buttons are different from other types of push buttons in that they have graphic, two-state, and animation capabilities. Using graphic buttons, an application programmer can do the following:

• Display both text and bit maps on the same button.
• Animate a series of bit maps.
• Give the user a two-state button.
• Change bit maps.

Graphic buttons permit a more intuitive interaction between a user and an application than standard push buttons do. For example, graphic buttons can mimic and enhance the look and feel of the physical controls found on stereo equipment. They can emulate the two-state behavior of the Pause button found on cassette decks; scan play buttons on CD players and VCRs; and change or animate bit maps when control buttons are pressed.

The graphic button class is registered by calling WinRegisterGraphicButton.

Control Data

The GBTNCDATA data structure contains the information used as the graphic button control data.

Styles

The base graphic button provides the ability to display bitmaps and text; it defaults to the Up state. Additional styles can be used to increase its function.

Graphic button controls have the following window styles:

GBS_TWOSTATE

A two-state graphic button has two states-Up and Down. If the button is in the Up state, the button is drawn with the Z-order above the owner. If the button is in the Down state, the button is drawn with the Z-order below the owner. Typically, the Up state expresses to the user that the button's action is selectable; while the Down state expresses that the action is being processed currently. Related messages are GBM_SETSTATE, GBM_QUERYSTATE, GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX.

GBS_AUTOTWOSTATE

An automatic two-state graphic button automatically toggles its state from Up to Down and from Down to Up whenever the user clicks on it. No message from the owner is required for the button to toggle its state. Related messages are GBM_SETSTATE, GBM_QUERYSTATE, GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX.

If both GBS_TWOSTATE and GBS_AUTOTWOSTATE are set, GBS_AUTOTWOSTATE takes precedence.

GBS_ANIMATION

An animation graphic button can animate a series of bitmaps. The bitmaps are displayed in ascending sequential order. The series is treated as a circular list: when the last bitmap of the series is reached, the next bitmap displayed is the first in the series. Related messages are GBM_ANIMATE, GBM_QUERYANIMATIONACTIVE, GBM_SETANIMATIONRATE, GBM_QUERYANIMATIONRATE, GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX. GBS_AUTOANIMATION

An automatic animation graphic button automatically toggles the animation from On to Off and from Off to On whenever the user clicks on it. Related messages are GBM_ANIMATE, GBM_QUERYANIMATIONACTIVE, GBM_SETANIMATIONRATE, GBM_QUERYANIMATIONRATE, GBM_SETBITMAPINDEX, and GBM_QUERYBITMAPINDEX.

If both GBS_ANIMATION and GBS_AUTOANIMATION are set, GBS_AUTOANIMATION takes precedence.

GBS_HILITEBITMAP

This style permits display of a different bitmap when the graphic button is in the highlighted paint state. The highlighted paint state occurs when the user presses the pointer button while over the graphic button or holds the spacebar down when the graphic button has the focus. This bitmap is set by the GBM_SETBITMAPINDEX message with GB_HILITE as the specified index to change. Related messages are GBM_SETBITMAPINDEX and GBM_QUERYBITMAPINDEX.

GBS_DISABLEBITMAP

This style permits display of a different bitmap when the graphic button is in the disabled paint state. This bitmap is set by the GBM_SETBITMAPINDEX message with GB_DISABLE as the specified index to change. Related messages are GBM_SETBITMAPINDEX and GBM_QUERYBITMAPINDEX.

GBS_3D_TEXTRECESSED

The text on the graphic button is displayed three-dimensionally. The Z-order of the text is below the face of the graphic button. The text is drawn with its main body black, and the bottom and right edges white.

GBS_3D_TEXTRAISED

The text on the graphic button is displayed three-dimensionally. The Z-order of the text is above the face of the graphic button. The text is drawn with its main body white, and the bottom and right edges black.

If both GBS_3D_TEXTRECESSED and GBS_3D_TEXTRAISED are set, GBS_3D_TEXTRAISED takes precedence.

Control Messages

Graphic buttons use the following messages:

Message	Description
**GBM_ANIMATE**	Sets the animation of an animate-able graphic button On or Off.
**GBM_QUERYANIMATIONACTIVE**	Returns the animation state of the graphic button.
**GBM_QUERYANIMATIONRATE**	Returns the animation rate of a graphic button in milliseconds.
**GBM_QUERYBITMAPINDEX**	Returns the bitmap index of the queried button parameter.
**GBM_QUERYSTATE**	Returns the current state of the graphic button.
**GBM_QUERYTEXTPOSITION**	Returns the text positioning relative to the bitmap.
**GBM_SETANIMATIONRATE**	Sets the animation rate of an animate-able graphic button.
**GBM_SETBITMAPINDEX**	Sets the bitmap index to use during various states of the graphic button.
**GBM_SETGRAPHICDATA**	An application sends this message to change the graphical data of the graphic button.
**GBM_SETSTATE**	Sets the state of a two-state graphic button.
**GBM_SETTEXTPOSITION**	Sets the text positioning relative to the bitmap.