I3StateCheckBox

The I3StateCheckBox class creates and manages three-state check-box control windows. A three-state check box is a square box with associated text that represents a choice. Unlike a regular check box, which has only two states (selected and deselected), a three-state check box has three states:

selected
The check box is filled to indicate that the item is selected.
indeterminate
The check box is displayed in halftone to indicate that the choice is indeterminate.
deselected
The check box is cleared to indicate that the item is deselected.

You can process the selection of a three-state check box by deriving from the ISelectHandler class and adding the handler to either the three-state check box or its owner window.

You can attach the following handlers to this control:

AIX Considerations

This control is not available on Motif.


I3StateCheckBox - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
I3StateCheckBox


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

Constructs an object from a dialog (parent) window, and the ID of a three-state check box control on that dialog window.

id
The window ID of the three-state check box.
parent
The dialog (parent) window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
I3StateCheckBox(const IWindowHandle& handle)

Constructs the object using the handle of an existing three-state check box window.

handle
The window handle of an existing three-state check box control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Constructs a three-state check box control and an object for it using the following parameters:

id
The window ID of the three-state check box.
parent
The parent window.
owner
The owner window.
initial
The initial position and size of the three-state check box you are constructing. The default is IRectangle. Optional.
style
The three-state check box'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 No


Auto Select

Use auto select members to query and modify the autoSelect style of a three-state check box object. The autoSelect style determines whether the state of the three-state check box is automatically changed when the user clicks on it.

The application determines when the user clicks on the three-state check box by attaching a handler derived from ISelectHandler to the three-state check box or its owner and overriding the ISelectHandler::selected member function. The application can then use the selection functions to change the three-state check box' state.


[view class]
disableAutoSelect
public:
virtual I3StateCheckBox& disableAutoSelect()

Removes the autoSelect style from the three-state check box control. If auto select is disabled, the application is responsible for changing the state of the three-state check box when the check box is clicked.

The application determines when the user clicks on the three-state check box by attaching a handler derived from ISelectHandler to the three-state check box or its owner and overriding the ISelectHandler::selected member function. The application can then use the selection functions to change the three-state check box' state.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
enableAutoSelect
public:
virtual I3StateCheckBox& enableAutoSelect( bool enable = true )

Sets the three-state check box control to the I3StateCheckBox::autoSelect style. If auto select is enabled, the state of the check box is automatically cycled between the selected, indeterminate, and deselected states when the check box is clicked.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

If the three-state check box control has the autoSelect style set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Layout Support

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


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

Returns the minimum size that this three-state check box control should be, based on the text string length and the current font.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Selection

Use these members to query and set the halftone selection state of a three-state check box. The halftone selection state refers to the state of the three-state check box when it is neither selected nor deselected. This state is sometimes referred to as indeterminate. 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 the ISettingButton::select, ISettingButton::deselect, and ISettingButton::isSelected functions.


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

Returns true if the three-state check box control has the halftone or indeterminate selection state.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
selectHalftone
public:
I3StateCheckBox& selectHalftone()

Sets a three-state check box control to the halftone or indeterminate selection state.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Styles

These style members provide a set of valid styles for this class. 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, those defined by the application and the Open Class Library, 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 current default style. This is the same as classDefaultStyle unless setDefaultStyle has been called. See classDefaultStyle for information about classDefaultStyle, and see setDefaultStyle for information about that function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent three-state check boxes.

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


[view class]
autoSelect
public:
static const Style autoSelect

The auto select style determines whether the state of the three-state check box is automatically changed when the user clicks on it. If auto select is enabled, the state of the check box automatically cycles between the selected, indeterminate, and deselected states. If auto select is disabled, the application must change the state of the three-state check box when the check box is clicked.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


I3StateCheckBox - Inherited Member Functions and Data

Inherited Public Functions

IButton
IControl
INotifier
ISettingButton
ITextControl
IWindow

Inherited Public Data

IWindow
INotifier
IButton
ISettingButton
ITextControl

Inherited Protected Functions

IWindow
INotifier
IButton
IControl
ITextControl
ISettingButton

Inherited Protected Data