IPushButton

The IPushButton class creates and manages push button control windows.

The standard push button generates an ICommandEvent. However, the application can change the window style value to generate a help request or system command event.

To change the push button event (message) processing, call either of the following:

The preceding functions add or remove the following styles:

When the user selects a push button, the push button generates an ICommandEvent that is routed to its owner window, or it generates a help request. You can process an ICommandEvent with an ICommandHandler.

You can derive classes from the following handlers and attach them to a push button control:

Portability Considerations

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

Windows Considerations

The inherited functions which set colors have no effect on push button controls. Push buttons are always drawn with the system default colors set in the Control Panel.


IPushButton - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IPushButton


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

Creates an object for a push button control that exists in a dialog window.

id
The identifier of the existing push button control.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IPushButton(const IWindowHandle& handle)

Creates an object for an existing push button control.

handle
The window handle of an existing push button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Creates a push button control and an object for it.

id
A push button control ID.
parent
The parent window.
owner
The owner window.
initial
The initial position and size of the control you are constructing. Optional.
style
The control's characteristics. Optional.

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
protected:
IPushButton()

Creates an IPushButton object. This protected constructor is used by derived classes to create objects of this class. Derived classes that use this constructor must create the underlying GUI object.

Supported Platforms

Windows OS/2 AIX
No No Yes

AIX Considerations

Creates an IPushButton object without an associated XmPushButton widget. This allows derived classes to create their own widgets.


Borders

Use these members to query and modify the noBorder style of a push button object. By default, the push button is displayed with a border drawn around it.


[view class]
addBorder
public:
virtual IPushButton& addBorder(bool add = true)

Adds or removes the push button border.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

The border style is not supported in the Windows environment. This function has no effect in that environment.


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

If the push button has a border, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

The border style is not supported in the Windows environment. This functionalways retunrs false in that environment.


[view class]
removeBorder
public:
virtual IPushButton& removeBorder()

Removes the border from the push button. This also prevents the background of the push button from being drawn with the color that is currently set for background drawing.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes

Windows Considerations

The border style is not supported in the Windows environment. This function has no effect in that environment.


Default Buttons

Use these members to query and modify the defaultButton style of a push button object. A default push button is the push button pressed when the user presses the Enter key.

OS/2 Considerations

A default push button is displayed with a thick border box.


[view class]
disableDefault
public:
virtual IPushButton& disableDefault()

Removes the style defaultButton from the push button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableDefault
public:
virtual IPushButton& enableDefault(bool enable = true)

Adds or removes the style defaultButton.

IWindow::setDefaultPushButton is called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

  • IWindow::setDefaultPushButton is called.

  • [view class]
    isDefault
    public:
    bool isDefault() const

    If the style defaultButton is set, true is returned. Otherwise, false is returned.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    Event-Handling Implementation

    Event-handling implementation members perform processing needed to allow handlers to properly receive GUI events and to route these 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


    Help Buttons

    Use these members to query and modify the help style of a push button object. A button with the help style enabled generates help events instead of command events when selected.


    [view class]
    disableHelp
    public:
    virtual IPushButton& disableHelp()

    Removes the style help from the push button.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    enableHelp
    public:
    virtual IPushButton& enableHelp(bool enable = true)

    Adds or removes the style help.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


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

    If the style help is set, true is returned. Otherwise, false is returned.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    Layout Support

    Layout support members are overrides that supply information used by the canvas classes to provide dialog-like behavior.


    [view class]
    addEmphasis
    public:
    virtual IPushButton& addEmphasis(bool enable = true)

    Adds or removes the push button focus emphasis.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes

    AIX Considerations

    IWindow::setDefaultEmphasisButton is called.

    OS/2 Considerations

    IWindow::setDefaultEmphasisButton is called.

    Windows Considerations

    IWindow::setDefaultEmphasisButton is called.


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

    If the push button has focus emphasis, true is returned. Otherwise, false is returned.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    removeEmphasis
    public:
    virtual IPushButton& removeEmphasis()

    Removes the focus emphasis from the push button.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


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

    Returns the minimum size this push button control can be, based on the text string length and the current font.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    Styles

    These style members provide a set of valid styles for this class. Use these members to query and set the push button styles. You can use these styles with the styles in the following classes:


    [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 defined by the application 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 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 push buttons.

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

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

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    defaultButton
    public:
    static const Style defaultButton

    Specifies that this is a default push button. If the parent or owner window is a canvas or frame window, the Enter key can be used to select the push button without having the cursor on the push button. Visually, a default push button has a darker and thicker border.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    help
    public:
    static const Style help

    Generates a help request, instead of a command event, when the push button is selected.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes

    AIX Considerations

    The general help window for the owner window is displayed when the user selects a Help push button. This is in accordance with the Motif Style Guide for dialogs.


    [view class]
    noBorder
    public:
    static const Style noBorder

    Displays the push button without a border.

    Supported Platforms

    Windows OS/2 AIX
    Ignored Yes Yes

    Windows Considerations

    This style has no effect in the Windows environment.


    [view class]
    systemCommand
    public:
    static const Style systemCommand

    Generates a system command event, instead of a command event, when the user selects a push button. The only portable system command is ISystemMenu::idClose. This is the system command for closing a window. You can override the ICommandHandler::systemCommand function to process system command events.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    System Command Buttons

    Use these members to query and modify the systemCommand style of a push button object. A button with the systemCommand style enabled generates events that can be used by overriding ICommandHandler::systemCommand instead of ICommandHandler::command.


    [view class]
    disableSystemCommand
    public:
    virtual IPushButton& disableSystemCommand()

    Removes the style systemCommand from the push button.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


    [view class]
    enableSystemCommand
    public:
    virtual IPushButton& enableSystemCommand( bool enable = true )

    Adds or removes the style systemCommand.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


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

    If the style systemCommand is set, true is returned. Otherwise, false is returned.

    Supported Platforms

    Windows OS/2 AIX
    Yes Yes Yes


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