IButton

The IButton class is the base class for the button control classes. This class contains the common functions for all button controls. You can construct button objects by using classes derived from IButton.

IButton - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of the IButton class from derived classes. You cannot copy or assign IButton objects because both the copy constructor and assignment operator are private functions.

~IButton

public:
virtual ~IButton()

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

IButton

protected:
IButton()

Derived classes use this protected constructor to create objects of this class.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Colors

Use these members to query or set the color used for various areas of a window.

backgroundColor

public:
virtual IColor backgroundColor() const

Returns the background color value of the window area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

disabledForegroundColor

public:
virtual IColor disabledForegroundColor() const

Returns the disabled foreground color value of the window area. If you have not set the color for the area, the default color is returned.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

AIX Considerations

Returns the default disabled foreground color value of the window area.

Windows Considerations

Returns the default disabled foreground color value of the window area.

foregroundColor

public:
virtual IColor foregroundColor() const

Returns the foreground color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

hiliteBackgroundColor

public:
virtual IColor hiliteBackgroundColor() const

Returns the highlight background color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

AIX Considerations

Returns the default highlight background color value of the window area.

Windows Considerations

Returns the default highlight background color value of the window area.

hiliteForegroundColor

public:
virtual IColor hiliteForegroundColor() const

Returns the highlight foreground color value of the window area or the default if no color for the area has been set.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

AIX Considerations

Returns the default highlight foreground color value of the window area.

Windows Considerations

Returns the default highlight foreground color value of the window area.

Highlighting

Use these members to query and modify the highlight state of the button. A button in the highlighted state has the same appearance as if the mouse selection button (mouse button 1) was pressed while the mouse pointer was over the button control.

highlight

public:
virtual IButton& highlight(bool highlight = true)

Sets the button's highlight state.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Ignored

AIX Considerations

Setting a button's highlight state is not supported in the AIX environment. This function has no effect in that environment.

isHighlighted

public:
bool isHighlighted() const

If the button's highlight state is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Ignored

AIX Considerations

Setting a button's highlight state is not supported in the AIX environment. This function always returns false.

unhighlight

public:
virtual IButton& unhighlight()

Turns off the button's highlight state.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Ignored

AIX Considerations

Setting a button's highlight state is not supported in the AIX environment. This function has no effect in that environment.

Mouse Focus

Mouse focus describes a button's capability to receive the input focus when the mouse is clicked with the pointer over the button. Use these members to query and modify this capability of a button object.

allowsMouseClickFocus

public:
bool allowsMouseClickFocus() const

If the button can receive the focus when clicked with the mouse, true is returned. Otherwise, false is returned.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

disableMouseClickFocus

public:
virtual IButton& disableMouseClickFocus()

Prevents the button from receiving the focus when the user selects it using the mouse.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

enableMouseClickFocus

public:
virtual IButton& enableMouseClickFocus(bool enable = true)

Enables or disables the button to receive the focus when the user selects it using the mouse.

enable: Flag indicating whether the mouse can have focus.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Notification Members

Use these members to identify and enable notifications sent to observer objects.

enableNotification

public:
virtual IButton& enableNotification(bool enable = true)

Enables or disables the button to send notifications to any observer objects.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

buttonClickId

public:
static INotificationId const buttonClickId

Notification identifier provided to observers when the button control is clicked by the user.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Selection

These members change the selection state of the button. The selection state of a button is typically changed by the user clicking on it using the mouse or pressing a key to select it. You can also change or query the state using other Open Class Library functions.

click

public:
virtual IButton& click()

Simulates the user clicking on the button control using the mouse selection button. The click function calls ISelectHandler. You might use this function instead of ISettingButton::select, which does not call ISelectHandler.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Styles

These style members provide a set of valid styles for use in classes derived from IButton. Use these members to query and set button styles. You can use these styles with the styles in the IWindow Styles class.

noPointerFocus

public:
static const Style noPointerFocus

Enables the cursor to stay on a control for which information is required, rather than moving to the button clicked on by the user. A typical usage is for a help push button that shows contextual help.
Note: This has no effect on keyboard interaction except on AIX, where the button cannot be accessed with the keyboard.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Text

Use these functions to set the button text. Button text is the label string placed on or beside the button.

setText

Sets the text for the button. If appropriate, this function notifies a parent canvas to update the layout for its children.

text: Reference to the text object or text for the button. The function is overloaded so the text can be set from a char* or from a string table ID.

Overload 1

public:
virtual IButton& setText(const IResourceId& text)

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Overload 2

public:
virtual IButton& setText(const char* text)

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

IButton - Inherited Member Functions and Data

Inherited Public Functions

IControl

```
virtual ~IControl()
```

INotifier

```
virtual ~INotifier()
```

virtual INotifier& disableNotification() = 0

virtual INotifier&
  enableNotification( bool enable = true ) = 0

```
INotifier()
```

virtual bool isEnabledForNotification() const = 0

virtual INotifier&
  notifyObservers( const INotificationEvent& event ) = 0

virtual INotifier&
  notifyObserversAsync( const INotificationEvent& event )

```
const IThreadId& threadId() const
```

ITextControl

```
virtual ~ITextControl()
```
```
static bool clipboardHasTextFormat()
```

virtual ISize displaySize(const char* text = 0) const

virtual ITextControl&
  setLayoutDistorted( unsigned long layoutAttributeOn,
                      unsigned long layoutAttributeOff )

virtual ITextControl& setText(const char* text)

virtual ITextControl& setText(const IResourceId& text)

```
virtual IString text() const
```

virtual unsigned long textLength() const

IWindow

```
virtual ~IWindow()
```

IAccelTblHandle acceleratorHandle() const

IAcceleratorTable acceleratorTable() const

```
virtual IColor activeColor() const
```

IWindow&
  addOrReplaceAttribute( const IAttributeName& name,
                         const IAttribute& attribute )

IWindow&
  adoptWindowData( const DataHandle& typeToken,
                   IWindowData* windowData )

```
virtual IString asDebugInfo() const
```
```
virtual IString asString() const
```

IAttributeName
  attributeNameAt( const AttributeCursor& cursor ) const

const IAttribute*
  attributeWithName( const IAttributeName& name,
                     ESearchType search = kWindowOnly ) const

virtual IWindow& capturePointer(bool capture = true)

```
ISize characterSize() const
```

IWindowHandle childAt(const ChildCursor& cursor) const

IWindow* childWindowAt(const ChildCursor& cursor) const

virtual IArgList
  convertToArgList( const IBitFlag& style ) const

virtual unsigned long
  convertToGUIStyle( const IBitFlag& style,
                     bool extendedOnly = false ) const

static DataHandle
  dataHandleWithKey( const char* dataKeyName )

virtual IWindowHandle defaultEmphasisButton() const

```
static SiblingOrder defaultOrdering()
```

virtual IWindowHandle defaultPushButton() const

```
static IWindow* desktopWindow()
```
```
virtual IWindow& disable()
```

virtual IColor disabledBackgroundColor() const

```
virtual IWindow& disableGroup()
```
```
IWindow& disableMinimumSizeCaching()
```
```
virtual IWindow& disableNotification()
```
```
virtual IWindow& disableTabStop()
```
```
virtual IWindow& disableUpdate()
```

bool
  dispatchRemainingHandlers( IEvent& event,
                             bool callDefProc = true )

virtual IWindow& enable(bool enableWindow = true)

virtual IWindow& enableGroup(bool enable = true)

IWindow&
  enableMinimumSizeCaching( bool enableCaching = true )

virtual IWindow& enableNotification(bool enable = true)

virtual IWindow& enableTabStop(bool enable = true)

virtual IWindow& enableUpdate(bool enableWindow = true)

static IWindow::ExceptionFn* exceptionFunction()

```
virtual IFont font() const
```
```
virtual IWindowHandle handle() const
```

virtual bool
  handleException( IException& dispatcherException,
                   IEvent& exceptionEvent )

virtual IWindowHandle handleForChildCreation() const

static IWindowHandle
  handleWithParent( unsigned long identifier,
                    const IWindowHandle& parent )

static IWindowHandle handleWithPointerCaptured()

```
virtual bool hasFocus() const
```

virtual bool hasPointerCaptured() const

```
unsigned long helpId() const
```
```
virtual IWindow& hide()
```
```
virtual IWindow& hideSourceEmphasis()
```
```
virtual unsigned long id() const
```
```
virtual IColor inactiveColor() const
```

virtual IRectangle invalidatedRect() const

virtual IRegionHandle invalidatedRegion() const

```
bool isAutoDeleteObject() const
```
```
bool isAutoDestroyWindow() const
```
```
bool isEnabled() const
```

virtual bool isEnabledForNotification() const

```
virtual bool isFrameWindow() const
```
```
virtual bool isGroup() const
```

bool isHandling(const EventMask& events) const

virtual bool
  isLayoutDistorted( unsigned long layoutAttribute ) const

bool isMinimumSizeCachingEnabled() const

```
bool isShowing() const
```
```
virtual bool isTabStop() const
```
```
virtual bool isValid() const
```
```
bool isVisible() const
```

static bool isWindowValid(const IWindow* window)

```
IDMItemProvider* itemProvider() const
```

IWindow(unsigned long identifier, IWindow* parent)

```
IWindow(const IWindowHandle& handle)
```

virtual IRectangle layoutAdjustment() const

static IPoint
  mapPoint( const IPoint& point,
            const IWindowHandle& from,
            const IWindowHandle& to )

virtual IWindowHandle
  matchForMnemonic( unsigned short character ) const

IMessageQueueHandle messageQueue() const

ISize minimumSize(bool windowCalculatedSize = false) const

virtual IPointerHandle mousePointer() const

static void movePointerTo(const IPoint& position)

virtual IWindow&
  moveSizeTo( const IRectangle& newSizeAndPosition )

virtual IWindow& moveTo(const IPoint& newPosition)

```
virtual IRectangle nativeRect() const
```

virtual INotifierAddress notifierAddress() const

virtual IWindow&
  notifyObservers( const INotificationEvent& event )

virtual IWindow&
  notifyObserversAsync( const INotificationEvent& event )

```
static IWindow* objectWindow()
```
```
virtual IWindow* owner() const
```
```
IWindow* parent() const
```
```
virtual ISize parentSize() const
```

static ISize parentSize(const IWindowHandle& windowHandle)

```
static IPoint pointerPosition()
```
```
virtual IPoint position() const
```

virtual IWindow&
  positionBehindSibling( const IWindowHandle& siblingWindow )

virtual IWindow& positionBehindSiblings()

```
virtual IWindow& positionOnSiblings()
```

virtual const IWindow& postEvent(const IEvent& event) const

virtual const IWindow&
  postEvent( EventType eventType,
             const IEventParameter1& parm1 = 0,
             const IEventParameter2& parm2 = 0 ) const

virtual const IWindow&
  postEvent( unsigned long eventId,
             const IEventParameter1& parm1 = 0,
             const IEventParameter2& parm2 = 0 ) const

virtual IPresSpaceHandle presSpace() const

```
virtual IRectangle rect() const
```

virtual IWindow&
  refresh( const IRectangle& invalidRectangle,
           bool immediate = false )

virtual IWindow& refresh(RefreshType type = paintAll)

```
virtual IWindow& releasePointer()
```

virtual void
  releasePresSpace( const IPresSpaceHandle& presentationSpaceHandle ) const

```
IWindow& removeAllAttributes()
```

IWindow& removeAttribute(const IAttributeName& name)

```
virtual IWindow& resetActiveColor()
```

virtual IWindow& resetBackgroundColor()

virtual IWindow& resetDisabledBackgroundColor()

virtual IWindow& resetDisabledForegroundColor()

```
virtual IWindow& resetFont()
```

virtual IWindow& resetForegroundColor()

virtual IWindow& resetHiliteBackgroundColor()

virtual IWindow& resetHiliteForegroundColor()

```
virtual IWindow& resetInactiveColor()
```
```
IWindow& resetMinimumSize()
```
```
virtual IWindow& resetShadowColor()
```

virtual IEventResult
  sendEvent( unsigned long eventId,
             const IEventParameter1& parm1 = 0,
             const IEventParameter2& parm2 = 0 ) const

virtual IEventResult
  sendEvent( EventType eventType,
             const IEventParameter1& parm1 = 0,
             const IEventParameter2& parm2 = 0 ) const

virtual IEventResult sendEvent(const IEvent& event) const

IWindow&
  setAcceleratorHandle( const IAccelTblHandle& handle )

IWindow&
  setAcceleratorTable( const IAcceleratorTable* acceleratorTable )

virtual IWindow& setActiveColor(const IColor& color)

IWindow& setAutoDeleteObject(bool autoDelete = true)

IWindow& setAutoDestroyWindow(bool autoDestroy = false)

virtual IWindow& setBackgroundColor(const IColor& color)

static void setDefaultOrdering(SiblingOrder order)

virtual IWindow&
  setDisabledBackgroundColor( const IColor& color )

virtual IWindow&
  setDisabledForegroundColor( const IColor& color )

static IWindow::ExceptionFn*
  setExceptionFunction( IWindow::ExceptionFn* exceptionFunction )

```
virtual IWindow& setFocus()
```

virtual IWindow& setFont(const IFont& font)

virtual IWindow& setForegroundColor(const IColor& color)

IWindow& setHelpId(unsigned long helpTopicId)

virtual IWindow&
  setHiliteBackgroundColor( const IColor& color )

virtual IWindow&
  setHiliteForegroundColor( const IColor& color )

virtual IWindow& setId(unsigned long newIdentifier)

virtual IWindow& setInactiveColor(const IColor& color)

IWindow& setItemProvider(IDMItemProvider* dragProvider)

virtual IWindow&
  setLayoutDistorted( unsigned long layoutAttributesOn,
                      unsigned long layoutAttributesOff )

IWindow& setMinimumSize(const ISize& size)

virtual IWindow&
  setMousePointer( const IPointerHandle& mousePointer )

virtual IWindow& setOwner(const IWindow* newOwner)

virtual IWindow& setParent(const IWindow* newParent)

virtual IWindow& setShadowColor(const IColor& color)

```
virtual IColor shadowColor() const
```

virtual IWindow& show(bool showWindow = true)

virtual IWindow& showSourceEmphasis(bool show = true)

```
virtual ISize size() const
```

virtual IWindow& sizeTo(const ISize& newSize)

IWindow& startHandling(const EventMask& events)

IWindow& stopHandling(const EventMask& events)

virtual IWindow&
  validateRect( const IRectangle& validatedRectangle )

virtual IWindow&
  validateRegion( const IRegionHandle& validatedRegion )

virtual IRectangle visibleRectangle() const

IWindowData* windowData(const DataHandle& typeToken) const

static IWindow*
  windowWithHandle( const IWindowHandle& windowHandle,
                    bool allThreads = true )

static IWindow*
  windowWithOwner( unsigned long identifier,
                   const IWindow* owner,
                   bool allThreads = true )

static IWindow*
  windowWithParent( unsigned long identifier,
                    const IWindow* parent,
                    bool allThreads = true )

Inherited Public Data

IWindow

static INotificationId const activeColorId

```
static const EventMask allMouseMoves
```

static INotificationId const
  attributeAddReplaceId

static INotificationId const attributeRemoveId

static INotificationId const backgroundColorId

static INotificationId const borderColorId

```
static const Style clipChildren
```
```
static const Style clipSiblings
```
```
static const Style clipToParent
```
```
static INotificationId const commandId
```
```
static const Style disabled
```

static INotificationId const
  disabledBackgroundColorId

static INotificationId const
  disabledForegroundColorId

```
static INotificationId const enableId
```
```
static INotificationId const focusId
```
```
static INotificationId const fontId
```

static INotificationId const foregroundColorId

```
static const Style group
```

static INotificationId const
  hiliteBackgroundColorId

static INotificationId const
  hiliteForegroundColorId

static INotificationId const inactiveColorId

```
static const Style leftToRight
```

static const EventMask mouseEntersLeaves

```
static const Style noStyle
```

static INotificationId const positionId

```
static const Style rightToLeft
```
```
static const Style saveBits
```

static INotificationId const shadowColorId

```
static INotificationId const sizeId
```
```
static const EventMask someMouseMoves
```
```
static const Style synchPaint
```

static INotificationId const systemCommandId

```
static const Style tabStop
```
```
static const Style visible
```
```
static INotificationId const visibleId
```

INotifier

static INotificationId const allChangesId

```
static INotificationId const deleteId
```

ITextControl

```
static INotificationId const textId
```

Inherited Protected Functions

IWindow

IWindow& addHandler(IHandler* newHandler)

virtual IWindow&
  addObserver( IObserver& observer,
               const IInterest& interest )

static void
  addToWindowSet( IWindow* window,
                  const IWindowHandle& windowHandle )

IWindow& bindMessageQueue(bool bindToMessageQueue = true)

```
virtual ISize calcMinimumSize() const
```

IColor
  color( unsigned long colorArea,
         const IColor& defaultColor ) const

IColor color(unsigned long colorArea) const

virtual IWindowHandle
  create( unsigned long id,
          const char* text,
          const IBitFlag& style,
          const char* windowClass,
          const IWindow* parent,
          const IWindow* owner,
          const IRectangle& initRect,
          const void* ctlData,
          const void* presParams,
          IWindow::SiblingOrder ordering = defaultOrdering ( ) )

virtual IWindowHandle
  create( unsigned long id,
          const char* text,
          const IBitFlag& style,
          IXmCreateFunction createFunction,
          const IWindow* parent,
          const IWindow* owner,
          const IRectangle& initRect,
          IWindow::SiblingOrder ordering = defaultOrdering ( ) )

virtual IWindowHandle
  create( unsigned long id,
          const char* text,
          unsigned long style,
          IXmCreateFunction createFunction,
          const IWindowHandle& parent,
          const IWindowHandle& owner,
          const IRectangle& initRect,
          const void* callerArgList,
          unsigned int callerNumberArguments,
          IWindow::SiblingOrder ordering = defaultOrdering ( ),
          unsigned long extendedStyle = 0 )

virtual IWindowHandle
  create( unsigned long id,
          const char* text,
          unsigned long style,
          const char* windowClass,
          const IWindowHandle& parent,
          const IWindowHandle& owner,
          const IRectangle& initRect,
          const void* ctlData,
          const void* presParams,
          IWindow::SiblingOrder ordering = defaultOrdering ( ),
          unsigned long extendedStyle = 0 )

IWindow& defaultProcedure(IEvent& event)

```
bool deleteIsInProcess() const
```
```
bool dispatch(IEvent& event)
```

virtual unsigned long extendedStyle() const

```
bool isBoundToMessageQueue() const
```

virtual bool isDragStarting(IEvent& event)

```
bool isPrimaryWindow() const
```
```
bool isUserWindowWordReserved() const
```
```
IWindow()
```

IWindowNotifyHandler* notificationHandler() const

virtual IWindow&
  notifyObservers( const INotificationId& notification )

IObserverList&
  observerList( const IInterest* interest = 0 ) const

virtual bool passEventToOwner(IEvent& event)

virtual IWindow&
  prepareForUse( const IWindowHandle& windowHandle )

```
virtual IWindow& removeAllObservers()
```

static void removeFromWindowSet(IWindow* window)

IWindow& removeHandler(IHandler* oldHandler)

virtual IWindow&
  removeObserver( IObserver& observer,
                  const IInterest& interest )

virtual IWindow& removeObserver(IObserver& observer)

IWindow& reserveUserWindowWord(bool reserve = true)

virtual IWindow& resetColor(unsigned long colorArea)

```
ISize savedMinimumSize() const
```

IWindow& saveMinimumSize(const ISize& size)

virtual IWindow&
  setBidiSettings( const IBidiSettings& bidiSettings,
                   bool childInherit,
                   bool refresh )

virtual IWindow&
  setColor( unsigned long colorArea,
            const IColor& color )

virtual IWindow&
  setDefaultEmphasisButton( const IWindowHandle& defaultEmphasisButton,
                            bool enable )

virtual IWindow&
  setDefaultPushButton( const IWindowHandle& defaultPushButton )

virtual IWindow&
  setExtendedStyle( unsigned long extendedStyle )

IWindow&
  setNotificationHandler( IWindowNotifyHandler* notifyHandler )

virtual IWindow& setStyle(unsigned long style)

IWindow& setWindowData(long index, unsigned long dataValue)

IWindow&
  setWindowData( long index,
                 unsigned short dataValue )

IWindow&
  startHandlingEventsFor( unsigned long identifier,
                          IWindow* parent )

IWindow&
  startHandlingEventsFor( const IWindowHandle& windowHandle )

```
virtual unsigned long style() const
```
```
IWindow& unbindMessageQueue()
```

unsigned long windowULong(long index) const

unsigned short windowUShort(long index) const

INotifier

virtual INotifier&
  addObserver( IObserver& observer,
               const IInterest& interest )

virtual INotifier&
  notifyObservers( const INotificationId& id ) = 0

virtual IObserverList&
  observerList( const IInterest* anInterest = 0 ) const = 0

virtual INotifier& removeAllObservers() = 0

virtual INotifier& removeObserver(IObserver& observer) = 0

virtual INotifier&
  removeObserver( IObserver& observer,
                  const IInterest& interest )

IControl

```
IControl()
```

ITextControl

```
ITextControl()
```

Inherited Protected Data

None