ICustomButton

The ICustomButton class creates and manages the custom button window. Custom buttons allow the application to customize the button appearance by providing an ICustomButtonDrawHandler to draw the button while retaining the behavior of a push button.

Custom buttons support the following features:


ICustomButton - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ICustomButton


Overload 1
public:
ICustomButton(const IWindowHandle& handle)

Creates an ICustomButton object for the specified button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

This constructor is to be used to create an ICustomButton object from a Motif XmPushButton widget. The default ICustomButtonDrawHandler draws the button image and sets this image as the XmNlabelPixmap, XmNlabelInsenstivePixmap, or the XmNarmPixmap as appropriate.

OS/2 Considerations

This constructor is to be used to create an ICustomButton object from a Presentation Manager button control created with the user button style.

Windows Considerations

This constructor is to be used to create an ICustomButton object from a Windows button control created with the owner draw style.


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

Creates an ICustomButton 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 Yes


Overload 3
protected:
ICustomButton()

This constructor does not create the button control window. When using this constructor, you must create the window. You can create the window using IWindow::create in the body of the constructor of your ICustomButton derived class. You can then begin event handling by calling IWindow::startHandlingEventsFor.

This constructor does not attach an ICustomButtonDrawHandler to the button being created. You can attach and detach the default draw handler using ICustomButton::addDefaultDrawHandler and ICustomButton::removeDefaultDrawHandler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Attributes

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


[view class]
disable
public:
virtual ICustomButton& disable()

Prevents keyboard and mouse input from being sent to the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Enables the window to accept keyboard and mouse input.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to set or query the color attributes of a custom button.


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

Returns the color used to paint the background of the custom button when it is in the default state. If you have not specifically set the background color, this function returns the system color in effect for middle of buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if the color used to paint the background of the button has halftone emphasis when the custom button is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the color used to paint the background of the custom button when it is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the color used to paint the foreground of the custom button when it is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetBackgroundColor
public:
virtual ICustomButton& resetBackgroundColor()

Resets the color used to paint the background by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

ICustomButton only overrides this function on Windows. On other platforms, the function is provided by a base class.


[view class]
resetLatchedBackgroundColor
public:
virtual ICustomButton& resetLatchedBackgroundColor()

Resets the latched background color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetLatchedForegroundColor
public:
virtual ICustomButton& resetLatchedForegroundColor()

Resets the latched foreground color by undoing a previous set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBackgroundColor
public:
virtual ICustomButton& setBackgroundColor( const IColor& color )

Sets the background color to the indicated color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

ICustomButton only overrides this function on Windows. On other platforms, the function is provided by a base class


[view class]
setLatchedBackgroundColor
public:
virtual ICustomButton& setLatchedBackgroundColor( const IColor& color, bool halftone = true )

Sets the color used to paint the background of the button when it is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLatchedForegroundColor
public:
virtual ICustomButton& setLatchedForegroundColor( const IColor& color )

Sets the color used to paint the foreground of the button when it is in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setColor
protected:
virtual ICustomButton& setColor( unsigned long colorArea, const IColor& color )

Sets the colorArea to the indicated color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

ICustomButton only overrides this function on Windows. On other platforms, the function is provided by a base class


Default Draw Handler

Use these members to manage the default draw handler of a custom button.


[view class]
addDefaultDrawHandler
protected:
ICustomButton& addDefaultDrawHandler()

Attaches the default ICustomButtonDrawHandler to the window. A call to this function will not attach the default handler if it is already attached.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeDefaultDrawHandler
protected:
ICustomButton& removeDefaultDrawHandler()

Removes the default ICustomButtonDrawHandler from the window. A call to this function will not remove the default hander if it is not attached.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

Event-handling implementation members perform processing needed to allow event handlers to properly receive and route events.


[view class]
passEventToOwner
protected:
virtual bool passEventToOwner(IEvent& event)

Determines if the event is passed on to the owner.

Supported Platforms

Windows OS/2 AIX
Yes No Yes

Portability Considerations

ICustomButton overrides this function in AIX to prevent mouse button click messages from being passed to the owner.


Fonts

Use these members to set, reset, and query fonts.


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

Calculates and returns the average character width and maximum character height for the currently set font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
font
public:
virtual IFont font() const

Returns the font used by the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetFont
public:
virtual ICustomButton& resetFont()

Causes the window to disregard a font set by a call to setFont. Following a call to this function, the window uses a default font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setFont
public:
virtual ICustomButton& setFont(const IFont& font)

Sets a new font to be used by the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Latch Support

Use these members to manage the latched state of a custom button.


[view class]
disableAutoLatch
public:
virtual ICustomButton& disableAutoLatch()

Disables the autoLatch style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
disableLatching
public:
virtual ICustomButton& disableLatching()

Sets the style of the button so that the user cannot latch or unlatch it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableAutoLatch
public:
virtual ICustomButton& enableAutoLatch(bool enable = true)

Sets the style of the button so that other custom buttons in the same group that have the autoLatch style are automatically unlatched when the user latches the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableLatching
public:
virtual ICustomButton& enableLatching(bool enable = true)

Sets the style of the button so that the user can latch or unlatch it.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if the autoLatch style is set for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if the button is in a latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns true if the latchable style is set for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Puts the button in a latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
unlatch
public:
virtual ICustomButton& unlatch()

Puts the button in the unlatched (default) state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

These members provide layout support for custom buttons.


[view class]
setLayoutDistorted
public:
virtual ICustomButton& 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 ICustomButton to optimize drawing and 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 the custom button. The size is based on the button text and the current font. This function examines the text for newline characters to accurately determine the button's size with multiple lines of text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

These INotificationId strings are used for all notifications that ICustomButton provides to its observers.


[view class]
latchId
public:
static INotificationId const latchId

This notification identifier is provided to observers when the user latches or unlatches the button. A boolean value is provided in the INotificationEvent::eventData field of the INotificationEvent. This value is true if the button is currently in the latched state.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

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

If the latchable style is set for the button but not the autoLatch style, then the user can latch and unlatch the button directly. If the autoLatch style is set for the button but not the latchable style, then the user can latch the button but cannot unlatch it directly. The user must latch another custom button that has the autoLatch style to unlatch the previous button. If both the latchable and autoLatch styles are set for the button, then the user can latch and unlatch the button directly. Also, the button automatically unlatches itself when the user latches another custom button that has the autoLatch style.


[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 custom buttons.

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

Unlatches automatically other custom buttons in the same group when the user latches button. This style also allows the user to latch the button when clicking on the button with mouse button 1.

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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
latchable
public:
static const Style latchable

Allows the user to latch or unlatch the custom button when clicking on the button with mouse button 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text Processing

Use these members to manage the text. You can query and set the text as well as query the length of the text for objects of this class.


[view class]
setText

Sets the custom button's text.


Overload 1
public:
virtual ICustomButton& setText(const char* text)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ICustomButton& setText(const IResourceId& text)

Sets the custom button's text from a resource file.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
virtual IString text() const

Returns the custom button's text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


User Data

Use these members to set or query user data for custom button objects.


[view class]
setUserData
public:
ICustomButton& setUserData(unsigned long data)

Stores an unsigned long value that represents special data to be associated with the button object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns an unsigned long value that represents special data associated with the button object. This data can be used to store information about special drawing for the button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICustomButton - Inherited Member Functions and Data

Inherited Public Functions

IButton
IControl
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
IButton
ITextControl

Inherited Protected Functions

IWindow
INotifier
IButton
IControl
ITextControl

Inherited Protected Data