IGraphicPushButton

The IGraphicPushButton class creates and manages a push button window with a graphical image as its label. The standard push button generates an ICommandEvent. However, the application can change the window style value to generate a help event or system command event. To change the push button event (that is, message) processing, call IPushButton::enableHelp and IPushButton::enableSystemCommand. These functions add or remove the styles IPushButton::help and IPushButton::systemCommand, respectively. For example:

IGraphicPushButton pbCancel(ID_CANCEL, this, this, ID_SOMEBMP,
                           IRectangle(10,10,80,22));

Portability Considerations

AIX does not support dialog templates.

Color

There are restrictions for specifying the color of controls based on the platform and which style of control you use.


IGraphicPushButton - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IGraphicPushButton


Overload 1
public:
IGraphicPushButton(unsigned long id, IWindow* parent)

Creates a graphic push button object for the specified push button in a dialog template that has the icon or bitmap style.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.
IAccessError Control information could not be obtained from the system for the specified window. Verify that the specified ID and parentDialog combination refer to a valid push button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Creates a graphic push button with the specified window ID, parent and owner windows, screen position and size, icon, and window style. If you already have an icon handle, use this constructor to put the icon on a graphic push button.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Creates a graphic push button with the specified window ID, parent and owner windows, screen position and size, default resource library with its specified icon or bitmap ID, and window style. If you have not already loaded the bitmap or icon and you want to load it from the default resource library, use this constructor.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IGraphicPushButton(const IWindowHandle& handle)

Creates a graphic push button object for an existing bitmap or icon push button control with the specified window handle.

Exception

IAccessError Control information could not be obtained from the system for the specified window. Verify that the specified handle refers to a valid push button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IGraphicPushButton( unsigned long id, IWindow* parent, IWindow* owner, const IBitmapHandle& bitmap = IBitmapHandle ( ), const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Creates a graphic push button with the specified window ID, parent and owner windows, screen position and size, bitmap, and window style. If you already have a bitmap handle, use this constructor to put the bitmap on the graphic push button.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 6
public:
IGraphicPushButton( unsigned long id, IWindow* parent, IWindow* owner, const IResourceId& bitmapOrIconId, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Creates a graphic push button using the specified window ID, parent and owner windows, screen position and size, resource library with its specified icon or bitmap ID, and window style. If you have not already loaded the bitmap or icon and you want to load it from the resource library of your choice, use this constructor.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

Use this member to query and set the accessible attributes of objects of this class.


[view class]
enable
public:
virtual IWindow& enable(bool enableWindow = true)

Enables the window to accept keyboard and mouse input.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Graphic

A graphic is an icon or bitmap that is displayed on a graphic push button. You can query the type, handle, or window of the current graphic and set a new graphic.


[view class]
bitmap
public:
IBitmapHandle bitmap() const

Returns the handle of the currently set bitmap. If no bitmap is set into the graphic push button, the return value is an IBitmapHandle object with a 0 handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
currentGraphicType
public:
GraphicType currentGraphicType() const

Returns the current type of graphic set onto the graphic push button. The returned value is an enumerator provided by IGraphicPushButton::GraphicType.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
graphicWindow
public:
IIconControl& graphicWindow() const

Returns the IIconControl used for drawing the graphic.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

AIX does not support this function because there is no IIconControl associated with the graphic push button.


[view class]
icon
public:
IPointerHandle icon() const

Returns the handle of the currently set icon. If no icon is set into the graphic push button, the return value is an IPointerHandle object with a 0 handle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setGraphic

Changes the stored graphic to the specified value.


Overload 1
public:
virtual IGraphicPushButton& setGraphic( const IResourceId& bitmapOrIconId )

Use this overload if you have not already loaded the bitmap or icon and you want to load it from the resource library of your choice.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IGraphicPushButton& setGraphic( const IPointerHandle& handle )

Use this overload if you already have an icon handle for the icon you want to place on the graphic push button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IGraphicPushButton& setGraphic( unsigned long bitmapOrIconId )

Use this overload if you have not already loaded the bitmap or icon and you want to load it from the default resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual IGraphicPushButton& setGraphic( const IBitmapHandle& handle )

Use this overload if you already have a bitmap handle for the bitmap you want to place on the graphic push button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Graphic Size

Use these members to query and modify the way the graphic image is displayed in a graphic push button object.


[view class]
disableSizeImageToWindow
public:
virtual IGraphicPushButton& disableSizeImageToWindow()

Clears the sizeImageToWindow style flag.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disableSizeWindowToImage
public:
virtual IGraphicPushButton& disableSizeWindowToImage()

Clears the sizeWindowToImage style flag.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableSizeImageToWindow
public:
virtual IGraphicPushButton& enableSizeImageToWindow( bool enable = true )

Sets or clears the sizeImageToWindow style flag.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableSizeWindowToImage
public:
virtual IGraphicPushButton& enableSizeWindowToImage( bool enable = true )

Sets or clears the sizeWindowToImage style flag.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSizeImageToWindowEnabled
public:
virtual bool isSizeImageToWindowEnabled() const

Returns true if the sizeImageToWindow style flag is currently set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isSizeWindowToImageEnabled
public:
virtual bool isSizeWindowToImageEnabled() const

Returns true if the sizeWindowToImage style flag is currently set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

Layout is information used by the canvas classes to provide dialog-like behavior.


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

Returns the recommended minimum size of this graphic push button control. The size is based on the actual size of the stored graphic.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Margins

The margin is the area between the graphic and the outside border of the push button. If you have not set the sizeToGraphic style, you can change the size of this area.


[view class]
marginSize
public:
ISize marginSize() const

Returns the currently set margin size.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMarginSize
public:
IGraphicPushButton& setMarginSize(const ISize& size)

Changes the size of the margin between the button outline and the graphic. The height of the ISize will be used for both the top and bottom of the button, and the width value of the ISize will be used for the left and right sides. The default value for the margin is a system dependent value that leaves no margin. Because of this, you should use the value marginSize added to the margin you desire as the argument to this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide valid styles for IGraphicPushButton::setDefaultStyle and for the constructor of the IGraphicPushButton class.


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

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly 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 it 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 graphic push buttons. Use the styles provided by IGraphicPushButton 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]
classDefaultStyle
public:
static const Style classDefaultStyle

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeImageToWindow
public:
static const Style sizeImageToWindow

Use this style to control the automatic stretching or shrinking of the graphical image to fit the window. If you set this style, the image is resized to cover the face of the window. If you do not set this style, the image is rendered in the center of the window without resizing. If the image is larger that the window, it is clipped at the boundaries of the window label area.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeWindowToImage
public:
static const Style sizeWindowToImage

Use this style to cause the window to be automatically resized to fit the image when you set a new image. The automatic resizing only occurs when a new image is set, such as during construction of the window or with the setGraphic function. Note that if there is text set in the window, the window is sized to accommodate the larger of the text and the image.

This style does not affect the behavior of the window if you use the sizeTo function after setting the image. You can use the sizeImageToWindow style to control automatic stretching or shrinking of the image. You can also set an IAlignmentAttribute for the window to control automatic resizing of the window by canvas classes such as IMultiCellCanvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IGraphicPushButton - Enumerations


[view class]
GraphicType
enum GraphicType { bitmapType, 
                   iconType }

These enumerators specify the current type of graphic set onto the graphic push button:

bitmapType
Specifies that a bitmap is set onto the graphic push button. If you do not specify a handle or resource ID when constructing the graphic push button object, an IBitmapHandle is the default graphic. This is the default style.
iconType
Specifies an icon is set onto the graphic push button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IGraphicPushButton - Inherited Member Functions and Data

Inherited Public Functions

IButton
IControl
INotifier
IPushButton
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
IButton
IPushButton
ITextControl

Inherited Protected Functions

IWindow
INotifier
IButton
IControl
IPushButton
ITextControl

Inherited Protected Data