IGroupBox

The IGroupBox class creates and manages group box control windows. Group boxes are drawn around one or more associated controls. For example, you can group a set of related radio buttons within a group box in order to confine their mutually exclusive behavior. This allows the user to select a radio button outside the group box without deselecting one that is inside it.

A group box neither modifies the behavior of any of the grouped controls nor does it accept input.
Note: To have a group box appear around the contents of a set canvas, use ISetCanvas::setText instead of creating an IGroupBox object.

Portability Considerations

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

AIX Considerations

In AIX, you cannot nest an outline box within a group box and vice versa if they are sibling controls. If you want that look, you should nest canvasses and put the controls in their own canvas or use the border style on the canvas itself.


IGroupBox - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IGroupBox


Overload 1
public:
IGroupBox(unsigned long id, IWindow* parentDialog)

Use this constructor to create an object for the specified group box control from the ID of the group box control on a dialog window and the parent window.

id
Identifier of the group box control you construct.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IGroupBox(const IWindowHandle& handle)

Use this constructor to create an IGroupBox object from the window handle of an existing group box control.

handle
The window handle of an existing group box control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Use this constructor to construct a group box control and object from a control ID, parent and owner windows, a rectangle, and a style.

id
Identifier of the group box control you construct.
parent
The parent window of the group box control you construct. You must specify a parent window.
owner
Owner window of the group box control you construct.
initial
The initial position and size of the group box control you construct. Optional.
style
Group box 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


Colors

Use these members to query colors for IGroupBox objects.


[view class]
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
Ignored Yes Yes

Windows Considerations

Returns the default foreground color value of the window area.


[view class]
setForegroundColor
public:
virtual IGroupBox& setForegroundColor(const IColor& color)

Sets the foreground color to the indicated color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Sets the color area to the specified color.

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]
setText

Sets the text for the group box and overrides the inherited setText. If the control's parent is a canvas, it is notified to update the layout for its children, if appropriate.


Overload 1
public:
virtual IGroupBox& setText(const IResourceId& text)

Use this function to set the text by specifying an IResourceId to identify the string table ID and specific resource library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IGroupBox& setText(const char* text)

Use this function to set the group box text with a char *.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
visibleRectangle
public:
virtual IRectangle visibleRectangle() const

Returns a rectangle that represents the area of the window that is actually painted by the control, not the actual rectangle of the control. This will actually return a size of 0, since the control does not actually paint anything except the line and it's text if present.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the minimum size of the group box control based on the current font and the text string.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid group box styles for this class. Use these members to query and set the group box styles. You can use these styles with the styles in the IWindow Styles 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, will be 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 group boxes.

style
Use the styles provided by IGroupBox 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


Miscellaneous Members

AIX Considerations

In AIX, you cannot nest an outline box within a group box and vice versa if they are sibling controls. If you want that look, you should nest canvasses and put the controls in their own canvas or use the border style on the canvas itself.

[view class]
displaySize
public:
virtual ISize displaySize(const char* text = 0) const

This function returns the display size of the text associated with the group box. This function is overridden in Motif and inherited in OS/2 and Windows, so it is portable.

Supported Platforms

Windows OS/2 AIX
No No Yes


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

Sets the background color to the indicated color.

Supported Platforms

Windows OS/2 AIX
No No Yes


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

This function returns the text associated with the group box. This function is overridden in Motif and inherited in OS/2 and Windows, so it is portable.

Supported Platforms

Windows OS/2 AIX
No No Yes


IGroupBox - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
ITextControl

Inherited Protected Functions

IWindow
INotifier
IControl
ITextControl

Inherited Protected Data