IAnimatedButton

The IAnimatedButton class creates and manages the animated button control window. A set of bitmaps are specified for the button to use for animation. During animation, the button cycles through the bitmaps on a time interval.

The bitmap set can be specified by the application by providing the resource ID of the first bitmap and the number of bitmaps to be used. The bitmap set can also be specified by using one of the animated bitmap sets that are provided by the library for standard multimedia actions.

If the button text is not visible, the current animated bitmap is centered in the button, but it is not resized. If the button text is visible, the current animated bitmap is centered horizontally and positioned vertically along the top of the button with the text centered horizontally immediately below the bitmap. No clipping is done for the bitmap, so it can paint outside the button border if the button is too small.


IAnimatedButton - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IAnimatedButton objects because both the copy constructor and assignment operator are private functions.


[view class]
~IAnimatedButton
public:
virtual ~IAnimatedButton()

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IAnimatedButton


Overload 1
public:
IAnimatedButton(const IWindowHandle& handle)

Creates an IAnimatedButton object for the specified button control that has a user-button style.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
IAnimatedButton( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Creates an IAnimatedButton with the specified window ID, parent and owner windows, screen position and size, and window style.

Exception

IInvalidParameter The parent window pointer is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Animation

Use these members to control the animation of the button.


[view class]
animationRate
public:
unsigned long animationRate() const

Returns the current animation rate for the button. The animation rate is specified in thousandths of a second.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
disableAnimateWhenLatched
public:
virtual IAnimatedButton& disableAnimateWhenLatched()

Removes the animateWhenLatched style for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
enableAnimateWhenLatched
public:
virtual IAnimatedButton& enableAnimateWhenLatched( bool enable = true )

Sets the animateWhenLatched style for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isAnimatedWhenLatched
public:
bool isAnimatedWhenLatched() const

Returns true if the animateWhenLatched style is set.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isAnimationStarted
public:
bool isAnimationStarted() const

Returns true if the button is currently animated.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
latch
public:
virtual IAnimatedButton& latch( bool latched = true, bool refresh = true )

Puts the button in a latched or unlatched state based on the latched parameter. The value of the refresh parameter determines if the button is painted.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAnimationRate
public:
virtual IAnimatedButton& setAnimationRate( unsigned long newRate = 1000 )

Sets the animation rate for the button in thousandths of a second. The default animation rate is one second.

The animation rate represents the amount of time that each bitmap is displayed when the button is animated.
Note: This class uses the ITimer class to control animation. Refer to the ITimer class for more information.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
startAnimation
public:
virtual IAnimatedButton& startAnimation( unsigned long index = 0 )

Starts the animation of the button. If you specify an index, the bitmap at the index is the first bitmap displayed.

Exception

IInvalidParameter The specified bitmap index is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
stopAnimation
public:
virtual IAnimatedButton& stopAnimation()

Stops the animation of the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Bitmaps

Use these members to set and query the bitmaps that are displayed for a button.


[view class]
bitmap
public:
virtual IBitmapHandle bitmap(unsigned long index = 0) const

Returns the handle of the specified bitmap.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
bitmapCount
public:
virtual unsigned long bitmapCount() const

Returns the number of bitmaps specified for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
currentBitmapIndex
public:
virtual unsigned long currentBitmapIndex() const

Returns the index of the bitmap that is currently displayed for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setBitmaps

Sets the bitmaps to be used for the button. If this function is called more than once, the button uses only the bitmaps specified in the last call.


Overload 1
public:
virtual IAnimatedButton& setBitmaps( const IResourceId& firstBitmap, unsigned long count )

The bitmaps must be sequential, starting with the value specified as the first bitmap ID and continuing for the specified bitmap count.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
virtual IAnimatedButton& setBitmaps( AnimatedBitmaps bitmaps )

This function loads the specified resource bitmap set that the library provides.

Exception

IInvalidParameter The animated bitmap set identifier is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setCurrentBitmapIndex
public:
virtual IAnimatedButton& setCurrentBitmapIndex( unsigned long index = 0 )

Sets the index of the bitmap that is currently displayed for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Layout Support

These members manage the layout of an animated button.


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns the recommended minimum size of this animated button control. The size is based on the bitmap, button text, and the current font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these style members to set and query IAnimatedButton styles. You can use these styles with the styles defined by the following nested classes:


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts style bits into the style value that can be processed by the GUI. The default action is to return the base GUI style for the platform. Extended styles defined by the Open Class Library can be returned by setting the extendedOnly parameter to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is classDefaultStyle unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent animated buttons.

style
Use the styles provided by IAnimatedButton::Style to specify the default style.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
animateWhenLatched
public:
static const Style animateWhenLatched

Starts animation automatically when the button is in the latched state and stops animation when the button is in the unlatched (default) state.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IAnimatedButton - Enumerations


[view class]
AnimatedBitmaps
enum AnimatedBitmaps { rewind, 
                       stop, 
                       pause, 
                       play, 
                       fastForward, 
                       record, 
                       mute, 
                       trackAdvance, 
                       trackReverse, 
                       stepForward, 
                       stepBackward, 
                       scanForward, 
                       scanBackward, 
                       eject, 
                       volumeUp, 
                       volumeDown }

Enumeration that defines identifiers for each of the provided animated bitmap resource sets. Open Class Library provides these bitmaps for standard multimedia operations.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IAnimatedButton - Inherited Member Functions and Data

Inherited Public Functions

IButton
IControl
ICustomButton
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
ICustomButton
IButton
ITextControl

Inherited Protected Functions

ICustomButton
IWindow
INotifier
IButton
IControl
ITextControl

Inherited Protected Data