# The Interface Kit: BCheckBox

Derived from: public BControl

Declared in: be/interface/CheckBox.h

Library: libbe.so

## Overview

A BCheckBox object draws a labeled check box on-screen and responds to a keyboard action or a click by changing the state of the device. A check box has two states: An "X" is displayed in the box when the object's value is 1 (`B_CONTROL_ON`), and is absent when the value is 0 (`B_CONTROL_OFF`). The BCheckBox is invoked (it posts a message to the target receiver) whenever its value changes in either direction--when it's turned on and when it's turned off.

A check box is an appropriate control device for setting a state--turning a value on and off. Use menu items or buttons to initiate actions within the application.

## Constructor and Destructor

### BCheckBox()

          BCheckBox(BRect frame, const char *name,
             const char *label,
             BMessage *message,
             uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
             uint32 flags = B_WILL_DRAW | B_NAVIGABLE)
          BCheckBox(BMessage *archive)

Initializes the BCheckBox by passing all arguments to the BControl constructor. BControl initializes the label of the check box and assigns it a message that encapsulates the action that should be taken when the state of the check box changes.

The frame, name, resizingMode, and flags arguments are the same as those declared for the BView class and are passed unchanged to the BView constructor.

When the BCheckBox is attached to a window, the height of its frame rectangle will be adjusted so that it has exactly the right amount of room to display the check box icon and the label, given its current font. The object draws at the vertical center of its frame rectangle beginning at the left side.

See also: the BControl and BView constructors, `AttachedToWindow()`

### ~BCheckBox()

          virtual ~BCheckBox()

Does nothing; a BCheckBox doesn't require any cleanup when it's deleted.

## Static Functions

### Instantiate()

          static BCheckBox *Instantiate(BMessage *archive)

Returns a new BCheckBox object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the archive doesn't contain data for a BCheckBox object, this function returns `NULL`.

See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

## Member Functions

### Archive()

          virtual status_t Archive(BMessage *archive, bool deep = true) const

Calls the inherited version of `Archive()`, then adds the BCheckBox class name to the archive BMessage.

See also: `BArchivable::Archive()`, `Instantiate()` static function

### AttachedToWindow()

          virtual void AttachedToWindow(void)

Augments the BControl version of `AttachedToWindow()` to set the view and low colors of the BCheckbox to the match its parent's view color, and to resize the view vertically to fit the height of the label it displays. The height of the label depends on the BCheckBox's font, which the BControl constructor sets to system plain font (`be_plain_font`).

See also: `BControl::AttachedToWindow()`

### Draw()

          virtual void Draw(BRect updateRect)

Draws the check box and its label. If the current value of the BCheckBox is 1 (`B_CONTROL_ON`), it's marked with an "X". If the value is 0 (`B_CONTROL_OFF`), it's empty.

See also: `BView::Draw()`

### GetPreferredSize()

          virtual  void GetPreferredSize(float *width, float *height)

Calculates the most optimal size for the check box to display the icon and the label in the current font; and reports the results in the variables that the width and height arguments refer to. `ResizeToPreferred()`, defined in the BView class, resizes a view's frame rectangle to the preferred size, keeping its left and top sides constant. `AttachedToWindow()` automatically resizes a check box to its preferred height, but doesn't modify its width.

See also: `BView::GetPreferredSize()`, `AttachedToWindow()`

### MouseDown()

          virtual void MouseDown(BPoint point)

Responds to a mouse-down event within the check box by tracking the cursor while the user holds the mouse button down. If the cursor is inside the bounds rectangle when the user releases the mouse button, this function toggles the value of the BCheckBox and calls `Draw()` to redisplay it.

When the value of the BCheckBox changes, a copy of the model BMessage is delivered to the object's target handler. See BInvoker's `Invoke()` and `SetTarget()` functions for more information. The message is dispatched by calling the target's `MessageReceived()` virtual function.

The target object can get a pointer to the source BCheckBox from the message, and use it to discover the object's new value. For example:

       void MyHandler::MessageReceived(BMessage *message)
       {
           BHandler *handler;
           if ( message->FindPointer("source", &handler) ) {
               BCheckBox *box = cast_as(handler, BCheckBox);
               if ( box ) {
                   . . .
               }
           }
           . . .
       }

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.