IToolBarButton

The IToolBarButton class creates and manages the toolbar button control window. IToolBarButton provides support for displaying a bitmap, text, or bitmap and text on the button.

Features of IToolBarButton include:

In addition, because IToolBarButton derives from ICustomButton, the IToolBarButton interface includes that of ICustomButton.


IToolBarButton - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IToolBarButton
public:
IToolBarButton( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )
Creates an IToolBarButton object from a control ID, parent and owner windows, rectangle, and style.

The default style for a toolbar button contains the styles IToolBarButton::useIdForText and IToolBarButton::useIdForBitmap. When you create a button with these styles, the window ID of the toolbar button is used to load the bitmap and text for the button. If the window ID is in the Open Class library reserved range, the bitmap and text are loaded from the Open Class Library's resource library. Otherwise, the bitmap and text are loaded from the default user defined resource library. If no bitmap is found in the appropriate library, a default bitmap is loaded.

An alternative method of assigning the bitmap and text to a button is through IToolBarButton::setBitmap or through the inherited setText() function. If you intend to use these functions to set the button's bitmap or text, there is no need to specify the IToolBarButton::useIdForText or IToolBarButton::useIdForBitmap styles. If you specify these styles unnecessarily, you will endure the overhead of attempts to load resources during button construction.

If the bitmap specified for a standard format button is larger than the standard bitmap size setting, the toolbar button will shrink the bitmap to the standard size. However, the button will not expand a small bitmap to the standard size. It is recommended that you specify bitmaps that match the standard bitmap size setting. The button shrinks the bitmap proportionally, which might change the look of the image depicted in your bitmap. There is also a performance overhead in shrinking the bitmap. You can change the standard bitmap size using IToolBarButton::setStandardBitmapSize. The bitmaps provided by the Open Class Library match the standard bitmap size of 22 by 22.

Toolbar buttons created with the default style are created without transparency. To specify transparency use the IToolBarButton::transparentBitmap style.

The file icconst.h includes defines for the following bitmaps and text that you can use when constructing toolbar buttons for standard operations:
IC_ID_CANCELOPERATION
IC_ID_EXIT
IC_ID_OPEN
IC_ID_NEW
IC_ID_SAVE
IC_ID_SAVE_AS
IC_ID_LOCATE
IC_ID_CUT
IC_ID_COPY
IC_ID_PASTE
IC_ID_PASTESPECIAL
IC_ID_PASTELINK
IC_ID_HELP
IC_ID_GENERALHELP
IC_ID_HELPINDEX
IC_ID_HELPTUTORIAL
IC_ID_USINGHELP
IC_ID_DESELECTALL
IC_ID_SELECTALL
IC_ID_INSERTCOLUMN
IC_ID_DELETECOLUMNS
IC_ID_INSERTROW
IC_ID_DELETEROWS
IC_ID_UNDO
IC_ID_REDO
IC_ID_CHECKSPELLING
IC_ID_NORMAL
IC_ID_ABOUT
IC_ID_UPDATE
IC_ID_MAILSEND
IC_ID_MOVEPAGES
IC_ID_PRINT
IC_ID_PRINTPREVIEW
IC_ID_PRINTSETUP
IC_ID_SORTAZ
IC_ID_SORTZA
IC_ID_SORTUP
IC_ID_SORTDOWN
IC_ID_SETTINGS
IC_ID_TOOLBAR
IC_ID_TOOLBARSETUP
IC_ID_RUNSCRIPT
IC_ID_VPAPALETTE
IC_ID_TOUR
IC_ID_LEFTALIGNOBJ
IC_ID_RIGHTALIGNOBJ
IC_ID_ZOOM
IC_ID_ZOOMIN
IC_ID_ZOOMOUT
IC_ID_LOGON
IC_ID_LOGOFF
IC_ID_BOLD
IC_ID_ITALIC
IC_ID_UNDERSCORE
IC_ID_DOUBLEUNDERSCORE
IC_ID_CENTER
IC_ID_LEFT
IC_ID_RIGHT
IC_ID_JUSTIFY
IC_ID_CLEAR
IC_ID_DELETE

The following figure shows the toolbar buttons provided.

Each of these bitmaps has a gray background. On Windows, the background gray has RGB values of Red=192, Green=192, Blue=192. On OS/2 and AIX, the background gray has RGB values of Red=204, Green=204, Blue=204.

In addition to its button text, each of these bitmaps has associated short and long help text. The help text is used to provide additional information to the user about the function of the button. You might choose to display the short text for each button in fly-over help and display the long text for each button in an information area at the bottom of the main window. Display of the short and long help text would then be triggered by the movement of the mouse over a toolbar button.

To differentiate between similar images and actions, the button text (which can be seen when the button is displayed in text or bitmap and text view) is 2 lines on some buttons. These are:
IC_ID_PASTESPECIAL
IC_ID_GENERALHELP
IC_ID_DESELECTALL
IC_ID_INSERTCOLUMN
IC_ID_DELETECOLUMNS
IC_ID_NORMAL
IC_ID_ABOUT
IC_ID_PRINTPREVIEW
IC_ID_PRINTSETUP
IC_ID_TOOLBAR
IC_ID_TOOLBARSETUP
IC_ID_RUNSCRIPT
IC_ID_VPAPALETTE
IC_ID_DOUBLEUNDERSCORE
IC_ID_CENTER
IC_ID_LEFT
IC_ID_RIGHT

The default for standard buttons (those created with the IToolBarButton::standardFormat style) is to display only one line of text on a button when the button is displayed in text or bitmap and text view. This is because the majority of the buttons have only one line of text. If you are using one of the pre-defined buttons above, and your toolbar buttons are standard format, you can set the default number of lines of text to be displayed for toolbar buttons to 2. You do this with a call to IToolBarButton::setStandardTextLines. If you do not set the standard text lines to 2, the second line of text is not displayed.

The use of these buttons and their associated short and long help text is described in more detail in the toolbar task section.

Exception

IInvalidParameter You specified mutually exclusive styles. Only one button view can be specified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Bitmaps

Use these members to set and query the bitmaps that are displayed for a button. If a latched bitmap is not supplied, the default bitmap is also used for the latched state. If the tool bar button has a style of standardFormat and the bitmap is larger than the standard bitmap size, then the bitmap is resized to the standard bitmap size when setBitmap or setLatchedBitmap is used. You can also specify a transparent color for use when drawing the bitmap.


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

Returns the handle of the primary bitmap. This is the bitmap that is displayed when the button is in unlatched (default) state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bitmapSize
public:
virtual ISize bitmapSize() const

Returns the size of the primary bitmap. This is the bitmap that is displayed when the button is in unlatched (default) state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the handle of the bitmap that is displayed when the button is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBitmap

Sets the bitmap to be used for the unlatched (default) button state.

If you intend to initially set the bitmap for a toolbar button using this function, there is no need to specify the IToolBarButton::useIdForBitmap style on toolbar button construction. If you specify this style unnecessarily, you will endure the overhead of attempts to load resources during button construction.

If the bitmap specified for a button which was created with the IToolBarButton::standardFormat style is larger than the standard bitmap size setting, the toolbar button will shrink the bitmap to the standard size. However, the button will not expand a small bitmap to the standard size. It is recommended that you specify bitmaps that match the standard bitmap size setting. The button shrinks the bitmap proportionally, which might change the look of the image depicted in your bitmap. There is also a performance overhead in shrinking the bitmap.


Overload 1
public:
virtual IToolBarButton& setBitmap(unsigned long id)

The bitmap is first loaded from the user defined resource library. If the bitmap is not found, and the resource ID is in the Open Class library reserved range, the bitmap is loaded from the Open Class Library's resource library. If no bitmap is found in the appropriate library, an exception occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IToolBarButton& setBitmap( const IBitmapHandle& handle )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IToolBarButton& setBitmap( const IResourceId& bitmapId )

The bitmap is first loaded from the IResourceId's resource library. If the bitmap is not found, and the resource ID is in the Open Class library reserved range, the bitmap is loaded from the Open Class Library's resource library. If no bitmap is found in the appropriate library, an exception occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLatchedBitmap

Sets the bitmap to be used for the latched state.

If the bitmap specified for a button which was created with the IToolBarButton::standardFormat style is larger than the standard bitmap size setting, the toolbar button will shrink the bitmap to the standard size. However, the button will not expand a small bitmap to the standard size. It is recommended that you specify bitmaps that match the standard bitmap size setting. The button shrinks the bitmap proportionally, which might change the look of the image depicted in your bitmap. There is also a performance overhead in shrinking the bitmap.


Overload 1
public:
virtual IToolBarButton& setLatchedBitmap( const IBitmapHandle& handle )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IToolBarButton& setLatchedBitmap(unsigned long id)

The bitmap is loaded from the user defined resource library. If the bitmap is not found, an exception occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual IToolBarButton& setLatchedBitmap( const IResourceId& latchedBitmapId )

The bitmap is loaded from the IResourceId's resource library. If the bitmap is not found, an exception occurs.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Canvas Layout

These members support canvas layout for tool bar buttons.


[view class]
setLayoutDistorted
public:
virtual IToolBarButton& setLayoutDistorted( unsigned long layoutAttributeOn, unsigned long layoutAttributeOff )

Called when changes have occurred in the window that will cause the layout of the window in a canvas to be updated. It is overridden by IToolBarButton to optimize minimum size calculations.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Shredder Support

Use these members to set and query whether the tool bar button can be dropped on a Workplace Shell shredder object.


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

Returns true if the dragDelete style is set for the toolbar button.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

Portability Considerations

This function returns false on Windows and AIX.


[view class]
disableDragDelete
public:
virtual IToolBarButton& disableDragDelete()

Removes the dragDelete style for the toolbar button to prevent it from being dropped on a Workplace Shell shredder object.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
enableDragDelete
public:
virtual IToolBarButton& enableDragDelete( bool enable = true )

Sets the dragDelete style for the toolbar button to enable it to be dropped on a Workplace Shell shredder object.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


Standard Format

Use these members to set and query the values used for the standard formatting of tool bar buttons. Standard formatting controls the amount of area occupied by the bitmap (when visible) and the amount of area occupied by text (when visible). Standard formatting affects all of the tool bar buttons that have a style of IToolBarButton::standardFormat so that they have a consistent appearance.


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

Returns true if the button has a style of standardFormat.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStandardBitmapSize
public:
static void setStandardBitmapSize( const ISize& newSize = ISize ( 22 , 22 ) )

Sets the size used for the bitmap of standard toolbar buttons. The default size is 22 by 22. The size of the button, which includes its borders, is larger than 22 by 22.

If the performance setting IPerformanceSettings::dynamicToolBarButtons is enabled, calling this function will immediately update all toolbar buttons. Otherwise the setting will only be used during the creation of new toolbar buttons. For better performance, the setting is not enabled by default.

If the bitmap specified for a standard format button is larger than the size you specify, the toolbar button will shrink the bitmap to this size. However, the button will not expand a small bitmap to this size. It is recommended that you specify bitmaps that match this setting. The button shrinks the bitmap proportionally, which might change the look of the image depicted in your bitmap. There is also a performance overhead in shrinking the bitmap.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStandardTextLines
public:
static void setStandardTextLines( unsigned long newLines = 1 )

Sets the number of lines to be displayed for standard toolbar buttons. The default value is 1.

If the performance setting IPerformanceSettings::dynamicToolBarButtons is enabled, calling this function will immediately update all toolbar buttons. Otherwise the setting will only be used during the creation of new toolbar buttons. For better performance, the setting is not enabled by default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setStandardTextWidth
public:
static void setStandardTextWidth( unsigned long newWidth = 50 )

Sets the width to be used for standard toolbar buttons. The default value is 50 pixels.

If the performance setting IPerformanceSettings::dynamicToolBarButtons is enabled, calling this function will immediately update all toolbar buttons. Otherwise the setting will only be used during the creation of new toolbar buttons. For better performance, the setting is not enabled by default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
standardBitmapSize
public:
static ISize standardBitmapSize()

Returns the size used for the bitmap of standard toolbar buttons. The default size is 22 by 22.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
standardTextLines
public:
static unsigned long standardTextLines()

Returns the number of lines of text displayed for a standard toolbar button. The default value is 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
standardTextWidth
public:
static unsigned long standardTextWidth()

Returns the width of a standard toolbar button. The default value is 50 pixels.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

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


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

Use this function to convert 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, those 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 toolbar buttons.

style
Use the styles provided by IToolBarButton::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]
bitmapAndTextVisible
public:
static const Style bitmapAndTextVisible

Displays the bitmap and toolbar button text.
Note: When a button is added to the toolbar, the button's view is changed to the view set for the toolbar. Subsequent queries of the view return the new view.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bitmapVisible
public:
static const Style bitmapVisible

Displays the bitmap. This style is part of IToolBarButton::classDefaultStyle.
Note: When a button is added to the toolbar, the button's view is changed to the view set for the toolbar. Subsequent queries of the view return the new view.

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 IToolBarButton::bitmapVisible, IToolBarButton::useIdForBitmap, IToolBarButton::useIdForText, IToolBarButton::standardFormat, IToolBarButton::dragDelete, IButton::noPointerFocus, and IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
dragDelete
public:
static const Style dragDelete

In OS/2, this style enables the dropping of the toolbar button on a Workplace Shell shredder object. This style has no effect on Windows and AIX.

This style is part of IToolBarButton::classDefaultStyle.
Note: Toolbar drag and drop must be enabled for toolbar button drag and drop behavior.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
standardFormat
public:
static const Style standardFormat

Displays the toolbar button in a standard format for the application. All toolbar buttons that have this style are formatted the same (based on the standard bitmap size, text width, and number of text lines). This style is part of IToolBarButton::classDefaultStyle.

If the bitmap specified for a standard format button is larger than the standard bitmap size setting, the toolbar button will shrink the bitmap to the standard size. However, the button will not expand a small bitmap to the standard size. It is recommended that you specify bitmaps that match the standard bitmap size setting. The button shrinks the bitmap proportionally, which might change the look of the image depicted in your bitmap. There is also a performance overhead in shrinking the bitmap. You can change the standard bitmap size using IToolBarButton::setStandardBitmapSize.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textVisible
public:
static const Style textVisible

Displays the toolbar button text.
Note: When a button is added to the toolbar, the button's view is changed to the view set for the toolbar. Subsequent queries of the view return the new view.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transparentBitmap
public:
static const Style transparentBitmap

Enables transparency for the button. In addition to specifying this style, a transparent color must also be defined to enable transparency on buttons. By default a transparent color is initially defined, but this style is not defined as part of IToolBarButton::classDefaultStyle. Button transparency can only be specified during button creation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useIdForBitmap
public:
static const Style useIdForBitmap

Uses the window ID of the toolbar button as the ID for the bitmap resource when the button is constructed. This style is part of IToolBarButton::classDefaultStyle.

If a bitmap resource cannot be found with the specified ID, the library tries to load a default bitmap for the toolbar button. If the default bitmap cannot be loaded, then the toolbar button does not use a bitmap.

There is no need to specify this style on toolbar button construction if you intend to set the bitmap using IToolBarButton::setBitmap. If you specify this style unnecessarily, you will endure the overhead of attempts to load resources during button construction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useIdForText
public:
static const Style useIdForText

Uses the window ID of the toolbar button as the ID for the text resource when the button is constructed. This style is part of IToolBarButton::classDefaultStyle.

If a string resource cannot be found with the specified ID, no text is set for the button.

There is no need to specify this style on toolbar button construction if you intend to set the text using setText(). If you specify this style unnecessarily, you will endure the overhead of attempts to load resources during button construction.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Transparency

Use these members to control transparency when drawing the bitmap. A transparent color is used to indicate part of the bitmap that should not be drawn for the bitmap. For example, the area under the bitmap is not overpainted for areas of the bitmap that are set to the transparent color. These members do not actually modify the bitmap and are only used when the bitmap is drawn.

Transparency allows a bitmap to display a nonrectangular image with the correct button background color. Transparency support is important for tool bar buttons because the background color used for the latched state can be different from the default background color.

The default transparent color is IColor::kPink (which has RGB values of red=255, green=0, blue=255).


[view class]
clearDefaultTransparentColor
public:
static void clearDefaultTransparentColor()

Resets the default transparent color so that no color will be treated as transparent for subsequent buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultTransparentColor
public:
static IColor defaultTransparentColor()

Returns the current default transparent color. This color is initially set to IColor::kPink (which has RGB values of Red=255, Green=0, Blue=255).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if a transparent color has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isDefaultTransparentColorSet
public:
static bool isDefaultTransparentColorSet()

Returns true if a default transparent color is set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetTransparentColor
public:
virtual IToolBarButton& resetTransparentColor()

Resets the button so that no color is made transparent when drawing the bitmap.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultTransparentColor
public:
static void setDefaultTransparentColor( const IColor& aColor = IColor ( IColor::kPink ) )

Sets the default transparent color for all subsequent toolbar buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTransparentColor
public:
virtual IToolBarButton& setTransparentColor( const IColor& color = IColor::kPink )

Sets the color to be made transparent when drawing the bitmap.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
transparentColor
public:
virtual IColor transparentColor() const

Returns the current transparent color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Views

Use these members to set and query the current view of a tool bar button.


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

Returns true if the button state is bitmapVisible or bitmapAndTextVisible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if the button state is textVisible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setView
public:
virtual IToolBarButton& setView(View buttonView)

Sets the current view of the toolbar button.
Note: The view of the toolbar button is changed to match the view of other toolbar buttons when it is added to a toolbar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
view
public:
View view() const

Returns the current view of the toolbar button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IToolBarButton - Enumerations


[view class]
View
enum View { bitmapView, 
            textView, 
            bitmapAndTextView }

Use these enumerations to specify the view of the button.

bitmapView
Only the bitmap is visible.
textView
Only the text is visible.
bitmapAndTextView
Both the bitmap and text are visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IToolBarButton - 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