|
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QObject
com.trolltech.qt.gui.QWidget
com.trolltech.qt.gui.QAbstractButton
public abstract class QAbstractButton
The QAbstractButton class is the abstract base class of button widgets, providing functionality common to buttons.
This class implements an abstract button. Subclasses of this class handle user actions, and specify how the button is drawn.
QAbstractButton provides support for both push buttons and checkable (toggle) buttons. Checkable buttons are implemented in the QRadioButton and QCheckBox classes. Push buttons are implemented in the QPushButton and QToolButton classes; these also provide toggle behavior if required.
Any button can display a label containing text and an icon. setText sets the text; setIcon sets the icon. If a button is disabled, its label is changed to give the button a "disabled" appearance.
If the button is a text button with a string containing an ampersand ('&'), QAbstractButton automatically creates a shortcut key. For example:
QPushButton *button = new QPushButton(tr("Ro&ck && Roll"), this);
The Alt+C shortcut is assigned to the button, i.e., when the user presses Alt+C the button will call animateClick. See the QShortcut documentation for details (to display an actual ampersand, use '&&').
You can also set a custom shortcut key using the setShortcut function. This is useful mostly for buttons that do not have any text, because they have no automatic shortcut.
button->setIcon(QIcon(":/images/print.png")); button->setShortcut(tr("Alt+F7"));
All of the buttons provided by Qt (QPushButton, QToolButton, QCheckBox, and QRadioButton) can display both text and icons.
A button can be made the default button in a dialog are provided by QPushButton::setDefault() and QPushButton::setAutoDefault().
QAbstractButton provides most of the states used for buttons:
The difference between isDown and isChecked is as follows. When the user clicks a toggle button to check it, the button is first pressed then released into the checked state. When the user clicks it again (to uncheck it), the button moves first to the pressed state, then to the unchecked state (isChecked and isDown are both false).
QAbstractButton provides four signals:
To subclass QAbstractButton, you must reimplement at least paintEvent to draw the button's outline and its text or pixmap. It is generally advisable to reimplement sizeHint as well, and sometimes hitButton (to determine whether a button press is within the button). For buttons with more than two states (like tri-state buttons), you will also have to reimplement checkStateSet and nextCheckState.
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.Boolean> |
clicked
This signal is emitted when the button is activated (i.e. pressed down then released while the mouse cursor is inside the button), when the shortcut key is typed, or when click or animateClick is called. |
QSignalEmitter.Signal0 |
pressed
This signal is emitted when the button is pressed down. |
QSignalEmitter.Signal0 |
released
This signal is emitted when the button is released. |
QSignalEmitter.Signal1<java.lang.Boolean> |
toggled
This signal is emitted whenever a checkable button changes its state. |
Fields inherited from class com.trolltech.qt.gui.QWidget |
---|
customContextMenuRequested |
Constructor Summary | |
---|---|
QAbstractButton()
Equivalent to QAbstractButton(0). |
|
QAbstractButton(QWidget parent)
Constructs an abstract button with a parent. |
Method Summary | |
---|---|
void |
animateClick()
Equivalent to animateClick(100). |
void |
animateClick(int msec)
Performs an animated click: the button is pressed immediately, and released msec milliseconds later (the default is 100 ms). |
boolean |
autoExclusive()
Returns whether auto-exclusivity is enabled. |
boolean |
autoRepeat()
Returns whether autoRepeat is enabled. |
int |
autoRepeatDelay()
Returns the initial delay of auto-repetition. |
int |
autoRepeatInterval()
Returns the interval of auto-repetition. |
protected void |
changeEvent(QEvent e)
This event handler can be reimplemented to handle state changes. |
protected void |
checkStateSet()
This virtual handler is called when setChecked was called, unless it was called from within nextCheckState. |
void |
click()
Performs a click. |
boolean |
event(QEvent e)
This is the main event handler; it handles event arg__1. |
protected void |
focusInEvent(QFocusEvent e)
This event handler can be reimplemented in a subclass to receive keyboard focus events (focus received) for the widget. |
protected void |
focusOutEvent(QFocusEvent e)
This event handler can be reimplemented in a subclass to receive keyboard focus events (focus lost) for the widget. |
static QAbstractButton |
fromNativePointer(QNativePointer nativePointer)
This function returns the QAbstractButton instance pointed to by nativePointer |
QButtonGroup |
group()
Returns the group that this button belongs to. |
protected boolean |
hitButton(QPoint pos)
Returns true if pos is inside the clickable button rectangle; otherwise returns false. |
QIcon |
icon()
Returns the icon shown on the button. |
QSize |
iconSize()
Returns the icon size used for this button.. |
boolean |
isCheckable()
Returns whether the button is checkable. |
boolean |
isChecked()
Returns whether the button is checked. |
boolean |
isDown()
Returns whether the button is pressed down. |
protected void |
keyPressEvent(QKeyEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive key press events for the widget. |
protected void |
keyReleaseEvent(QKeyEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive key release events for the widget. |
protected void |
mouseMoveEvent(QMouseEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse move events for the widget. |
protected void |
mousePressEvent(QMouseEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse press events for the widget. |
protected void |
mouseReleaseEvent(QMouseEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse release events for the widget. |
protected void |
nextCheckState()
This virtual handler is called when a button is clicked. |
protected abstract void |
paintEvent(QPaintEvent e)
This event handler can be reimplemented in a subclass to receive paint events which are passed in the arg__1 parameter. |
void |
setAutoExclusive(boolean arg__1)
Sets whether auto-exclusivity is enabled to arg__1. |
void |
setAutoRepeat(boolean arg__1)
Sets whether autoRepeat is enabled to arg__1. |
void |
setAutoRepeatDelay(int arg__1)
Sets the initial delay of auto-repetition to arg__1. |
void |
setAutoRepeatInterval(int arg__1)
Sets the interval of auto-repetition to arg__1. |
void |
setCheckable(boolean arg__1)
Sets whether the button is checkable to arg__1. |
void |
setChecked(boolean arg__1)
Sets whether the button is checked to arg__1. |
void |
setDown(boolean arg__1)
Sets whether the button is pressed down to arg__1. |
void |
setIcon(QIcon icon)
Sets the icon shown on the button to icon. |
void |
setIconSize(QSize size)
Sets the icon size used for this button. |
void |
setShortcut(QKeySequence.StandardKey key)
Sets the shortcut to the key sequence for the given key. |
void |
setShortcut(QKeySequence key)
Sets the mnemonic associated with the button to key. |
void |
setShortcut(java.lang.String key)
Sets the shortcut to the key sequence for the given key string. |
void |
setText(java.lang.String text)
Sets the text shown on the button to text. |
QKeySequence |
shortcut()
Returns the mnemonic associated with the button. |
java.lang.String |
text()
Returns the text shown on the button. |
protected void |
timerEvent(QTimerEvent e)
This event handler can be reimplemented in a subclass to receive timer events for the object. |
void |
toggle()
Toggles the state of a checkable button. |
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 |
---|
public final QSignalEmitter.Signal1<java.lang.Boolean> clicked
This signal is emitted when the button is activated (i.e. pressed down then released while the mouse cursor is inside the button), when the shortcut key is typed, or when click or animateClick is called. Notably, this signal is not emitted if you call setDown, setChecked or toggle.
If the button is checkable, checked is true if the button is checked, or false if the button is unchecked.
public final QSignalEmitter.Signal0 pressed
This signal is emitted when the button is pressed down.
public final QSignalEmitter.Signal0 released
This signal is emitted when the button is released.
public final QSignalEmitter.Signal1<java.lang.Boolean> toggled
This signal is emitted whenever a checkable button changes its state. checked is true if the button is checked, or false if the button is unchecked.
This may be the result of a user action, click slot activation, or because setChecked was called.
The states of buttons in exclusive button groups are updated before this signal is emitted. This means that slots can act on either the "off" signal or the "on" signal emitted by the buttons in the group whose states have changed.
For example, a slot that reacts to signals emitted by newly checked buttons but which ignores signals from buttons that have been unchecked can be implemented using the following pattern:
void MyWidget::reactToToggle(bool checked)
{
if (checked) {
// Examine the new button states.
...
}
}
Button groups can be created using the QButtonGroup class, and updates to the button states monitored with the QButtonGroup::buttonClicked signal.
Constructor Detail |
---|
public QAbstractButton()
Equivalent to QAbstractButton(0).
public QAbstractButton(QWidget parent)
Constructs an abstract button with a parent.
Method Detail |
---|
public final void animateClick()
Equivalent to animateClick(100).
public final void animateClick(int msec)
Performs an animated click: the button is pressed immediately, and released msec milliseconds later (the default is 100 ms).
Calling this function again before the button was released will reset the release timer.
All signals associated with a click are emitted as appropriate.
This function does nothing if the button is disabled.
public final boolean autoExclusive()
Returns whether auto-exclusivity is enabled.
If auto-exclusivity is enabled, checkable buttons that belong to the same parent widget behave as if they were part of the same exclusive button group. In an exclusive button group, only one button can be checked at any time; checking another button automatically unchecks the previously checked one.
The property has no effect on buttons that belong to a button group.
autoExclusive is off by default, except for radio buttons.
public final boolean autoRepeat()
Returns whether autoRepeat is enabled.
If autoRepeat is enabled, then the pressed, released, and clicked signals are emitted at regular intervals when the button is down. autoRepeat is off by default. The initial delay and the repetition interval are defined in milliseconds by autoRepeatDelay and autoRepeatInterval.
Note: If a button is pressed down by a shortcut key, then auto-repeat is enabled and timed by the system and not by this class. The pressed, released, and clicked signals will be emitted like in the normal case.
public final int autoRepeatDelay()
Returns the initial delay of auto-repetition.
If autoRepeat is enabled, then autoRepeatDelay defines the initial delay in milliseconds before auto-repetition kicks in.
public final int autoRepeatInterval()
Returns the interval of auto-repetition.
If autoRepeat is enabled, then autoRepeatInterval defines the length of the auto-repetition interval in millisecons.
public final void click()
Performs a click.
All the usual signals associated with a click are emitted as appropriate. If the button is checkable, the state of the button is toggled.
This function does nothing if the button is disabled.
public final QButtonGroup group()
Returns the group that this button belongs to.
If the button is not a member of any QButtonGroup, this function returns 0.
public final QIcon icon()
Returns the icon shown on the button.
The icon's default size is defined by the GUI style, but can be adjusted by setting the iconSize property.
public final QSize iconSize()
Returns the icon size used for this button..
The default size is defined by the GUI style. This is a maximum size for the icons. Smaller icons will not be scaled up.
public final boolean isCheckable()
Returns whether the button is checkable.
By default, the button is not checkable.
checked
public final boolean isChecked()
Returns whether the button is checked.
Only checkable buttons can be checked. By default, the button is unchecked.
checkable
public final boolean isDown()
Returns whether the button is pressed down.
If this property is true, the button is pressed down. The signals pressed and clicked are not emitted if you set this property to true. The default is false.
public final void setAutoExclusive(boolean arg__1)
Sets whether auto-exclusivity is enabled to arg__1.
If auto-exclusivity is enabled, checkable buttons that belong to the same parent widget behave as if they were part of the same exclusive button group. In an exclusive button group, only one button can be checked at any time; checking another button automatically unchecks the previously checked one.
The property has no effect on buttons that belong to a button group.
autoExclusive is off by default, except for radio buttons.
public final void setAutoRepeat(boolean arg__1)
Sets whether autoRepeat is enabled to arg__1.
If autoRepeat is enabled, then the pressed, released, and clicked signals are emitted at regular intervals when the button is down. autoRepeat is off by default. The initial delay and the repetition interval are defined in milliseconds by autoRepeatDelay and autoRepeatInterval.
Note: If a button is pressed down by a shortcut key, then auto-repeat is enabled and timed by the system and not by this class. The pressed, released, and clicked signals will be emitted like in the normal case.
public final void setAutoRepeatDelay(int arg__1)
Sets the initial delay of auto-repetition to arg__1.
If autoRepeat is enabled, then autoRepeatDelay defines the initial delay in milliseconds before auto-repetition kicks in.
public final void setAutoRepeatInterval(int arg__1)
Sets the interval of auto-repetition to arg__1.
If autoRepeat is enabled, then autoRepeatInterval defines the length of the auto-repetition interval in millisecons.
public final void setCheckable(boolean arg__1)
Sets whether the button is checkable to arg__1.
By default, the button is not checkable.
checked
public final void setChecked(boolean arg__1)
Sets whether the button is checked to arg__1.
Only checkable buttons can be checked. By default, the button is unchecked.
checkable
public final void setDown(boolean arg__1)
Sets whether the button is pressed down to arg__1.
If this property is true, the button is pressed down. The signals pressed and clicked are not emitted if you set this property to true. The default is false.
public final void setIcon(QIcon icon)
Sets the icon shown on the button to icon.
The icon's default size is defined by the GUI style, but can be adjusted by setting the iconSize property.
public final void setIconSize(QSize size)
Sets the icon size used for this button. to size.
The default size is defined by the GUI style. This is a maximum size for the icons. Smaller icons will not be scaled up.
public final void setShortcut(QKeySequence key)
Sets the mnemonic associated with the button to key.
public final void setText(java.lang.String text)
Sets the text shown on the button to text.
If the button has no text, the text function will return a an empty string.
If the text contains an ampersand character ('&'), a shortcut is automatically created for it. The character that follows the '&' will be used as the shortcut key. Any previous shortcut will be overwritten, or cleared if no shortcut is defined by the text. See the QShortcut documentation for details (to display an actual ampersand, use '&&').
There is no default text.
public final QKeySequence shortcut()
Returns the mnemonic associated with the button.
public final java.lang.String text()
Returns the text shown on the button.
If the button has no text, the text function will return a an empty string.
If the text contains an ampersand character ('&'), a shortcut is automatically created for it. The character that follows the '&' will be used as the shortcut key. Any previous shortcut will be overwritten, or cleared if no shortcut is defined by the text. See the QShortcut documentation for details (to display an actual ampersand, use '&&').
There is no default text.
public final void toggle()
Toggles the state of a checkable button.
checked
protected void changeEvent(QEvent e)
This event handler can be reimplemented to handle state changes.
The state being changed in this event can be retrieved through event arg__1.
Change events include: QEvent::ToolBarChange, QEvent::ActivationChange, QEvent::EnabledChange, QEvent::FontChange, QEvent::StyleChange, QEvent::PaletteChange, QEvent::WindowTitleChange, QEvent::IconTextChange, QEvent::ModifiedChange, QEvent::MouseTrackingChange, QEvent::ParentChange, QEvent::WindowStateChange, QEvent::LanguageChange, QEvent::LocaleChange, QEvent::LayoutDirectionChange.
changeEvent
in class QWidget
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.
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.
event
in class QWidget
protected void focusInEvent(QFocusEvent e)
This event handler can be reimplemented in a subclass to receive keyboard focus events (focus received) for the widget. The event is passed in the arg__1 parameter
A widget normally must setFocusPolicy to something other than Qt::NoFocus in order to receive focus events. (Note that the application programmer can call setFocus on any widget, even those that do not normally accept focus.)
The default implementation updates the widget (except for windows that do not specify a focusPolicy).
focusInEvent
in class QWidget
protected void focusOutEvent(QFocusEvent e)
This event handler can be reimplemented in a subclass to receive keyboard focus events (focus lost) for the widget. The events is passed in the arg__1 parameter.
A widget normally must setFocusPolicy to something other than Qt::NoFocus in order to receive focus events. (Note that the application programmer can call setFocus on any widget, even those that do not normally accept focus.)
The default implementation updates the widget (except for windows that do not specify a focusPolicy).
focusOutEvent
in class QWidget
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.
protected void keyPressEvent(QKeyEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive key press events for the widget.
A widget must call setFocusPolicy to accept focus initially and have focus in order to receive a key press event.
If you reimplement this handler, it is very important that you ignore() the event if you do not understand it, so that the widget's parent can interpret it.
The default implementation closes popup widgets if the user presses Esc. Otherwise the event is ignored.
keyPressEvent
in class QWidget
protected void keyReleaseEvent(QKeyEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive key release events for the widget.
A widget must accept focus initially and have focus in order to receive a key release event.
If you reimplement this handler, it is very important that you ignore() the release if you do not understand it, so that the widget's parent can interpret it.
The default implementation ignores the event.
keyReleaseEvent
in class QWidget
protected void mouseMoveEvent(QMouseEvent e)
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.
mouseMoveEvent
in class QWidget
Example
protected void mousePressEvent(QMouseEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse press events for the widget.
If you create new widgets in the mousePressEvent the mouseReleaseEvent may not end up where you expect, depending on the underlying window system (or X11 window manager), the widgets' location and maybe more.
The default implementation implements the closing of popup widgets when you click outside the window. For other widget types it does nothing.
mousePressEvent
in class QWidget
Example
protected void mouseReleaseEvent(QMouseEvent e)
This event handler, for event arg__1, can be reimplemented in a subclass to receive mouse release events for the widget.
mouseReleaseEvent
in class QWidget
Example
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.
protected abstract void paintEvent(QPaintEvent e)
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.
paintEvent
in class QWidget
protected void timerEvent(QTimerEvent e)
This event handler can be reimplemented in a subclass to receive timer events for the object.
QTimer provides a higher-level interface to the timer functionality, and also more general information about timers. The timer event is passed in the arg__1 parameter.
timerEvent
in class QObject
public static QAbstractButton fromNativePointer(QNativePointer nativePointer)
nativePointer
- the QNativePointer of which object should be returned.public void setShortcut(java.lang.String key)
key
- The description of the key sequence. Typically used with tr() so key sequences can be locale aware.public void setShortcut(QKeySequence.StandardKey key)
key
- The key for which to select a key sequence
|
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |