Qt Jambi Home

com.trolltech.qt.gui
Class QCheckBox

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.core.QObject
              extended by com.trolltech.qt.gui.QWidget
                  extended by com.trolltech.qt.gui.QAbstractButton
                      extended by com.trolltech.qt.gui.QCheckBox
All Implemented Interfaces:
QPaintDeviceInterface, QtJambiInterface

public class QCheckBox
extends QAbstractButton

The QCheckBox widget provides a checkbox with a text label.

A QCheckBox is an option button that can be switched on (checked) or off (unchecked). Checkboxes are typically used to represent features in an application that can be enabled or disabled without affecting others, but different types of behavior can be implemented.

A QButtonGroup can be used to group check buttons visually.

Whenever a checkbox is checked or cleared it emits the signal stateChanged. Connect to this signal if you want to trigger an action each time the checkbox changes state. You can use isChecked to query whether or not a checkbox is checked.

In addition to the usual checked and unchecked states, QCheckBox optionally provides a third state to indicate "no change". This is useful whenever you need to give the user the option of neither checking nor unchecking a checkbox. If you need this third state, enable it with setTristate, and use checkState to query the current toggle state.

Just like QPushButton, a checkbox displays text, and optionally a small icon. The icon is set with setIcon. The text can be set in the constructor or with setText. A shortcut key can be specified by preceding the preferred character with an ampersand. For example:

    QCheckBox *checkbox = new QCheckBox("C&ase sensitive", this);

In this example the shortcut is Alt+A. See the QShortcut documentation for details (to display an actual ampersand, use '&&').

Important inherited functions: text, setText, text, pixmap, setPixmap(), accel(), setAccel(), isToggleButton(), setDown, isDown, isOn(), checkState, autoRepeat, isExclusiveToggle(), group, setAutoRepeat, toggle, pressed, released, clicked, toggled, checkState, and stateChanged.

Screenshot of a Macintosh style checkboxA checkbox shown in the Macintosh widget style.
Screenshot of a Windows XP style checkboxA checkbox shown in the Windows XP widget style.
Screenshot of a Plastique style checkboxA checkbox shown in the Plastique widget style.

See Also:
QAbstractButton, QRadioButton, GUI Design Handbook: Check Box

Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QWidget
QWidget.RenderFlag, QWidget.RenderFlags
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.Signal0, QSignalEmitter.Signal1<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Field Summary
 QSignalEmitter.Signal1<java.lang.Integer> stateChanged
          This signal is emitted whenever the check box's state changes, i.e. whenever the user checks or unchecks it.
 
Fields inherited from class com.trolltech.qt.gui.QAbstractButton
clicked, pressed, released, toggled
 
Fields inherited from class com.trolltech.qt.gui.QWidget
customContextMenuRequested
 
Constructor Summary
QCheckBox()
          Equivalent to QCheckBox(0).
QCheckBox(QWidget parent)
          Constructs a checkbox with the given parent, but with no text.
QCheckBox(java.lang.String text)
          Equivalent to QCheckBox(text, 0).
QCheckBox(java.lang.String text, QWidget parent)
          Constructs a checkbox with the given parent and text.
 
Method Summary
 Qt.CheckState checkState()
          Returns the check box's check state.
protected  void checkStateSet()
          

This virtual handler is called when setChecked was called, unless it was called from within nextCheckState.

 boolean event(QEvent e)
          

This is the main event handler; it handles event arg__1. You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.

Key press and release events are treated differently from other events. event checks for Tab and Shift+Tab and tries to move the focus appropriately. If there is no widget to move the focus to (or the key press is not Tab or Shift+Tab), event calls keyPressEvent.

Mouse and tablet event handling is also slightly special: only when the widget is enabled, event will call the specialized handlers such as mousePressEvent; otherwise it will discard the event.

This function returns true if the event was recognized, otherwise it returns false. If the recognized event was accepted (see QEvent::accepted), any further processing such as event propagation to the parent widget stops.

static QCheckBox fromNativePointer(QNativePointer nativePointer)
          This function returns the QCheckBox instance pointed to by nativePointer
protected  boolean hitButton(QPoint pos)
          

Returns true if pos is inside the clickable button rectangle; otherwise returns false.

protected  void initStyleOption(QStyleOptionButton option)
          Initialize option with the values from this QCheckBox.
 boolean isTristate()
          Returns whether the checkbox is a tri-state checkbox.
protected  void mouseMoveEvent(QMouseEvent arg__1)
          

This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse move events for the widget.

If mouse tracking is switched off, mouse move events only occur if a mouse button is pressed while the mouse is being moved. If mouse tracking is switched on, mouse move events occur even if no mouse button is pressed.

QMouseEvent::pos() reports the position of the mouse cursor, relative to this widget. For press and release events, the position is usually the same as the position of the last mouse move event, but it might be different if the user's hand shakes. This is a feature of the underlying window system, not Qt.

protected  void nextCheckState()
          

This virtual handler is called when a button is clicked.

protected  void paintEvent(QPaintEvent arg__1)
          

This event handler can be reimplemented in a subclass to receive paint events which are passed in the arg__1 parameter.

A paint event is a request to repaint all or part of the widget. It can happen as a result of repaint or update, or because the widget was obscured and has now been uncovered, or for many other reasons.

Many widgets can simply repaint their entire surface when asked to, but some slow widgets need to optimize by painting only the requested region: QPaintEvent::region(). This speed optimization does not change the result, as painting is clipped to that region during event processing. QListView and QTableView do this, for example.

Qt also tries to speed up painting by merging multiple paint events into one. When update is called several times or the window system sends several paint events, Qt merges these events into one event with a larger region (see QRegion::united()). repaint does not permit this optimization, so we suggest using update whenever possible.

When the paint event occurs, the update region has normally been erased, so that you're painting on the widget's background.

The background can be set using setBackgroundRole and setPalette.

From Qt 4.0, QWidget automatically double-buffers its painting, so there's no need to write double-buffering code in paintEvent to avoid flicker.

Note: Under X11 it is possible to toggle the global double buffering by calling qt_x11_set_global_double_buffer(). Example usage:

    ...
    extern void qt_x11_set_global_double_buffer(bool);
    qt_x11_set_global_double_buffer(false);
    ...

Note: In general, one should refrain from calling update or repaint inside of paintEvent. For example, calling update or repaint on children inside a paintEvent results in undefined behavior; the child may or may not get a paint event.

 void setCheckState(Qt.CheckState state)
          Sets the check box's check state to state.
 void setTristate()
          Equivalent to setTristate(true).
 void setTristate(boolean y)
          Sets whether the checkbox is a tri-state checkbox to y.
 QSize sizeHint()
          

Returns the recommended size for the widget.

 
Methods inherited from class com.trolltech.qt.gui.QAbstractButton
animateClick, animateClick, autoExclusive, autoRepeat, autoRepeatDelay, autoRepeatInterval, changeEvent, click, focusInEvent, focusOutEvent, group, icon, iconSize, isCheckable, isChecked, isDown, keyPressEvent, keyReleaseEvent, mousePressEvent, mouseReleaseEvent, setAutoExclusive, setAutoRepeat, setAutoRepeatDelay, setAutoRepeatInterval, setCheckable, setChecked, setDown, setIcon, setIconSize, setShortcut, setShortcut, setShortcut, setText, shortcut, text, timerEvent, toggle
 
Methods inherited from class com.trolltech.qt.gui.QWidget
acceptDrops, accessibleDescription, accessibleName, actionEvent, actions, activateWindow, addAction, addActions, adjustSize, autoFillBackground, backgroundRole, baseSize, childAt, childAt, childrenRect, childrenRegion, clearFocus, clearMask, close, closeEvent, contentsRect, contextMenuEvent, contextMenuPolicy, createWinId, cursor, depth, destroy, destroy, destroy, devType, dragEnterEvent, dragLeaveEvent, dragMoveEvent, dropEvent, ensurePolished, enterEvent, focusNextChild, focusNextPrevChild, focusPolicy, focusPreviousChild, focusProxy, focusWidget, font, fontInfo, fontMetrics, foregroundRole, frameGeometry, frameSize, geometry, getContentsMargins, grabKeyboard, grabMouse, grabMouse, grabShortcut, grabShortcut, hasFocus, hasMouseTracking, height, heightForWidth, heightMM, hide, hideEvent, inputContext, inputMethodEvent, inputMethodQuery, insertAction, insertActions, isActiveWindow, isAncestorOf, isEnabled, isEnabledTo, isFullScreen, isHidden, isLeftToRight, isMaximized, isMinimized, isModal, isRightToLeft, isVisible, isVisibleTo, isWindow, isWindowModified, keyboardGrabber, layout, layoutDirection, leaveEvent, locale, logicalDpiX, logicalDpiY, lower, mapFrom, mapFromGlobal, mapFromParent, mapTo, mapToGlobal, mapToParent, mask, maximumHeight, maximumSize, maximumWidth, metric, minimumHeight, minimumSize, minimumSizeHint, minimumWidth, mouseDoubleClickEvent, mouseGrabber, move, move, moveEvent, nextInFocusChain, normalGeometry, numColors, overrideWindowFlags, overrideWindowFlags, overrideWindowState, overrideWindowState, paintEngine, paintingActive, palette, parentWidget, physicalDpiX, physicalDpiY, pos, raise, rect, releaseKeyboard, releaseMouse, releaseShortcut, removeAction, render, render, render, render, render, repaint, repaint, repaint, repaint, resetInputContext, resize, resize, resizeEvent, restoreGeometry, saveGeometry, scroll, scroll, setAcceptDrops, setAccessibleDescription, setAccessibleName, setAttribute, setAttribute, setAutoFillBackground, setBackgroundRole, setBaseSize, setBaseSize, setContentsMargins, setContentsMargins, setContextMenuPolicy, setCursor, setDisabled, setEnabled, setFixedHeight, setFixedSize, setFixedSize, setFixedWidth, setFocus, setFocus, setFocusPolicy, setFocusProxy, setFont, setForegroundRole, setGeometry, setGeometry, setHidden, setInputContext, setLayout, setLayoutDirection, setLocale, setMask, setMask, setMaximumHeight, setMaximumSize, setMaximumSize, setMaximumWidth, setMinimumHeight, setMinimumSize, setMinimumSize, setMinimumWidth, setMouseTracking, setPalette, setParent, setParent, setParent, setShortcutAutoRepeat, setShortcutAutoRepeat, setShortcutEnabled, setShortcutEnabled, setSizeIncrement, setSizeIncrement, setSizePolicy, setSizePolicy, setStatusTip, setStyle, setStyleSheet, setTabOrder, setToolTip, setUpdatesEnabled, setVisible, setWhatsThis, setWindowFlags, setWindowFlags, setWindowIcon, setWindowIconText, setWindowModality, setWindowModified, setWindowOpacity, setWindowRole, setWindowState, setWindowState, setWindowTitle, show, showEvent, showFullScreen, showMaximized, showMinimized, showNormal, size, sizeIncrement, sizePolicy, stackUnder, statusTip, style, styleSheet, tabletEvent, testAttribute, toolTip, underMouse, unsetCursor, unsetLayoutDirection, unsetLocale, update, update, update, update, updateGeometry, updateMicroFocus, updatesEnabled, visibleRegion, whatsThis, wheelEvent, width, widthMM, window, windowFlags, windowIcon, windowIconText, windowModality, windowOpacity, windowRole, windowState, windowTitle, windowType, winId, x, y
 
Methods inherited from class com.trolltech.qt.core.QObject
blockSignals, childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, property, removeEventFilter, setObjectName, setParent, setProperty, signalsBlocked, startTimer, thread
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
disconnect, disconnect, signalSender
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

stateChanged

public final QSignalEmitter.Signal1<java.lang.Integer> stateChanged

This signal is emitted whenever the check box's state changes, i.e. whenever the user checks or unchecks it.

arg__1 contains the check box's new ToggleState.

Compatible Slot Signatures:
void mySlot(int arg__1)
void mySlot()

Constructor Detail

QCheckBox

public QCheckBox()

Equivalent to QCheckBox(0).


QCheckBox

public QCheckBox(QWidget parent)

Constructs a checkbox with the given parent, but with no text.

The parent argument is passed on to the QAbstractButton constructor.


QCheckBox

public QCheckBox(java.lang.String text)

Equivalent to QCheckBox(text, 0).


QCheckBox

public QCheckBox(java.lang.String text,
                 QWidget parent)

Constructs a checkbox with the given parent and text.

The parent argument is passed on to the QAbstractButton constructor.

Method Detail

checkState

public final Qt.CheckState checkState()

Returns the check box's check state.

See Also:
setCheckState, Qt::CheckState

isTristate

public final boolean isTristate()

Returns whether the checkbox is a tri-state checkbox.

The default is false; i.e. the checkbox has only two states.


setCheckState

public final void setCheckState(Qt.CheckState state)

Sets the check box's check state to state.

See Also:
checkState, Qt::CheckState

setTristate

public final void setTristate()

Equivalent to setTristate(true).


setTristate

public final void setTristate(boolean y)

Sets whether the checkbox is a tri-state checkbox to y.

The default is false; i.e. the checkbox has only two states.

See Also:
isTristate

checkStateSet

protected void checkStateSet()

This virtual handler is called when setChecked was called, unless it was called from within nextCheckState. It allows subclasses to reset their intermediate button states.

Overrides:
checkStateSet in class QAbstractButton
See Also:
nextCheckState

event

public boolean event(QEvent e)

This is the main event handler; it handles event arg__1. You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.

Key press and release events are treated differently from other events. event checks for Tab and Shift+Tab and tries to move the focus appropriately. If there is no widget to move the focus to (or the key press is not Tab or Shift+Tab), event calls keyPressEvent.

Mouse and tablet event handling is also slightly special: only when the widget is enabled, event will call the specialized handlers such as mousePressEvent; otherwise it will discard the event.

This function returns true if the event was recognized, otherwise it returns false. If the recognized event was accepted (see QEvent::accepted), any further processing such as event propagation to the parent widget stops.

Overrides:
event in class QAbstractButton
See Also:
closeEvent, focusInEvent, focusOutEvent, enterEvent, keyPressEvent, keyReleaseEvent, leaveEvent, mouseDoubleClickEvent, mouseMoveEvent, mousePressEvent, mouseReleaseEvent, moveEvent, paintEvent, resizeEvent, QObject::event, QObject::timerEvent

hitButton

protected boolean hitButton(QPoint pos)

Returns true if pos is inside the clickable button rectangle; otherwise returns false.

By default, the clickable area is the entire widget. Subclasses may reimplement this function to provide support for clickable areas of different shapes and sizes.

Overrides:
hitButton in class QAbstractButton

mouseMoveEvent

protected void mouseMoveEvent(QMouseEvent arg__1)

This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse move events for the widget.

If mouse tracking is switched off, mouse move events only occur if a mouse button is pressed while the mouse is being moved. If mouse tracking is switched on, mouse move events occur even if no mouse button is pressed.

QMouseEvent::pos() reports the position of the mouse cursor, relative to this widget. For press and release events, the position is usually the same as the position of the last mouse move event, but it might be different if the user's hand shakes. This is a feature of the underlying window system, not Qt.

Overrides:
mouseMoveEvent in class QAbstractButton
See Also:
setMouseTracking, mousePressEvent, mouseReleaseEvent, mouseDoubleClickEvent, event, QMouseEvent, Example

nextCheckState

protected void nextCheckState()

This virtual handler is called when a button is clicked. The default implementation calls setChecked(!isChecked) if the button isCheckable. It allows subclasses to implement intermediate button states.

Overrides:
nextCheckState in class QAbstractButton
See Also:
checkStateSet

paintEvent

protected void paintEvent(QPaintEvent arg__1)

This event handler can be reimplemented in a subclass to receive paint events which are passed in the arg__1 parameter.

A paint event is a request to repaint all or part of the widget. It can happen as a result of repaint or update, or because the widget was obscured and has now been uncovered, or for many other reasons.

Many widgets can simply repaint their entire surface when asked to, but some slow widgets need to optimize by painting only the requested region: QPaintEvent::region(). This speed optimization does not change the result, as painting is clipped to that region during event processing. QListView and QTableView do this, for example.

Qt also tries to speed up painting by merging multiple paint events into one. When update is called several times or the window system sends several paint events, Qt merges these events into one event with a larger region (see QRegion::united()). repaint does not permit this optimization, so we suggest using update whenever possible.

When the paint event occurs, the update region has normally been erased, so that you're painting on the widget's background.

The background can be set using setBackgroundRole and setPalette.

From Qt 4.0, QWidget automatically double-buffers its painting, so there's no need to write double-buffering code in paintEvent to avoid flicker.

Note: Under X11 it is possible to toggle the global double buffering by calling qt_x11_set_global_double_buffer(). Example usage:

    ...
    extern void qt_x11_set_global_double_buffer(bool);
    qt_x11_set_global_double_buffer(false);
    ...

Note: In general, one should refrain from calling update or repaint inside of paintEvent. For example, calling update or repaint on children inside a paintEvent results in undefined behavior; the child may or may not get a paint event.

Specified by:
paintEvent in class QAbstractButton
See Also:
event, repaint, update, QPainter, QPixmap, QPaintEvent, Analog Clock Example

sizeHint

public QSize sizeHint()

Returns the recommended size for the widget.

If the value of this property is an invalid size, no size is recommended.

The default implementation of sizeHint returns an invalid size if there is no layout for this widget, and returns the layout's preferred size otherwise.

Overrides:
sizeHint in class QWidget
See Also:
QSize::isValid, minimumSizeHint, sizePolicy, setMinimumSize, updateGeometry

fromNativePointer

public static QCheckBox fromNativePointer(QNativePointer nativePointer)
This function returns the QCheckBox instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

initStyleOption

protected final void initStyleOption(QStyleOptionButton option)
Initialize option with the values from this QCheckBox. This method is useful for subclasses when they need a QStyleOptionButton, but don't want to fill in all the information themselves.


Qt Jambi Home