qaction.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QAction 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QAction \- Abstract user interface action that can appear both in menus and tool bars
.SH SYNOPSIS
\fC#include <qaction.h>\fR
.PP
Inherits QObject.
.PP
Inherited by QActionGroup.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQAction\fR ( QObject * parent, const char * name = 0, bool toggle = FALSE )"
.br
.ti -1c
.BI "\fBQAction\fR ( const QString & text, const QIconSet & icon, const QString & menuText, QKeySequence accel, QObject * parent, const char * name = 0, bool toggle = FALSE )"
.br
.ti -1c
.BI "\fBQAction\fR ( const QString & text, const QString & menuText, QKeySequence accel, QObject * parent, const char * name = 0, bool toggle = FALSE )"
.br
.ti -1c
.BI "\fB~QAction\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetIconSet\fR ( const QIconSet & )"
.br
.ti -1c
.BI "QIconSet \fBiconSet\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetText\fR ( const QString & )"
.br
.ti -1c
.BI "QString \fBtext\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetMenuText\fR ( const QString & )"
.br
.ti -1c
.BI "QString \fBmenuText\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetToolTip\fR ( const QString & )"
.br
.ti -1c
.BI "QString \fBtoolTip\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetStatusTip\fR ( const QString & )"
.br
.ti -1c
.BI "QString \fBstatusTip\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetWhatsThis\fR ( const QString & )"
.br
.ti -1c
.BI "QString \fBwhatsThis\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetAccel\fR ( const QKeySequence & key )"
.br
.ti -1c
.BI "QKeySequence \fBaccel\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetToggleAction\fR ( bool )"
.br
.ti -1c
.BI "bool \fBisToggleAction\fR () const"
.br
.ti -1c
.BI "bool \fBisOn\fR () const"
.br
.ti -1c
.BI "bool \fBisEnabled\fR () const"
.br
.ti -1c
.BI "bool \fBisVisible\fR () const"
.br
.ti -1c
.BI "virtual bool \fBaddTo\fR ( QWidget * w )"
.br
.ti -1c
.BI "virtual bool \fBremoveFrom\fR ( QWidget * w )"
.br
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "void \fBtoggle\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetOn\fR ( bool )"
.br
.ti -1c
.BI "virtual void \fBsetEnabled\fR ( bool )"
.br
.ti -1c
.BI "void \fBsetVisible\fR ( bool )"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBactivated\fR ()"
.br
.ti -1c
.BI "void \fBtoggled\fR ( bool on )"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "QKeySequence \fBaccel\fR - the action's accelerator key"
.br
.ti -1c
.BI "bool \fBenabled\fR - whether the action is enabled"
.br
.ti -1c
.BI "QIconSet \fBiconSet\fR - the action's icon"
.br
.ti -1c
.BI "QString \fBmenuText\fR - the action's menu text"
.br
.ti -1c
.BI "bool \fBon\fR - whether a toggle action is on"
.br
.ti -1c
.BI "QString \fBstatusTip\fR - the action's status tip"
.br
.ti -1c
.BI "QString \fBtext\fR - the action's descriptive text"
.br
.ti -1c
.BI "bool \fBtoggleAction\fR - whether the action is a toggle action"
.br
.ti -1c
.BI "QString \fBtoolTip\fR - the action's tool tip"
.br
.ti -1c
.BI "bool \fBvisible\fR - whether the action can be seen (e.g. in menus and " "toolbars" ")"
.br
.ti -1c
.BI "QString \fBwhatsThis\fR - the action's ""What's This?"" help text"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBaddedTo\fR ( QWidget * actionWidget, QWidget * container )"
.br
.ti -1c
.BI "virtual void \fBaddedTo\fR ( int index, QPopupMenu * menu )"
.br
.in -1c
.SH DESCRIPTION
The QAction class provides an abstract user interface action that can appear both in menus and tool bars.
.PP
In GUI applications many commands can be invoked via a menu option, a toolbar button and a keyboard accelerator. Since the same action must be performed regardless of how the action was invoked, and since the menu and toolbar should be kept in sync, it is useful to represent a command as an \fIaction\fR. An action can be added to a menu and a toolbar and will automatically keep them in sync. For example, if the user presses a Bold toolbar button the Bold menu item will automatically be checked.
.PP
A QAction may contain an icon, a menu text, an accelerator, a status text, a whats this text and a tool tip. Most of these can be set in the constructor. They can also be set independently with setIconSet(), setText(), setMenuText(), setToolTip(), setStatusTip(), setWhatsThis() and setAccel(), respectively.
.PP
An action may be a toggle action e.g. a Bold toolbar button, or a command action, e.g. 'Open File' to invoke an open file dialog. Toggle actions emit the toggled() signal when their state changes. Both command and toggle actions emit the activated() signal when they are invoked. Use setToggleAction() to set an action's toggled status. To see if an action is a toggle action use isToggleAction(). A toggle action may be "on", isOn() returns TRUE, or "off", isOn() returns FALSE.
.PP
Actions are added to widgets (menus or toolbars) using addTo(), and removed using removeFrom().
.PP
Once a QAction has been created it should be added to the relevant menu and toolbar and then connected to the slot which will perform the action. For example:
.PP
.nf
.br
        fileSaveAction = new QAction( "Save File", QPixmap( filesave ),
.br
                                      "&Save", CTRL+Key_S, this, "save" );
.br
        connect( fileSaveAction, SIGNAL( activated() ) , this, SLOT( save() ) );
.fi
.PP
We create a "File Save" action with a menu text of "&Save" and \fICtrl+S\fR as the keyboard accelerator. We connect the fileSaveAction's activated() signal to our own save() slot. Note that at this point there is no menu or toolbar action, we'll add them next:
.PP
.nf
.br
        QToolBar * fileTools = new QToolBar( this, "file operations" );
.fi
.PP
.nf
.br
        fileSaveAction->addTo( fileTools );
.fi
.PP
.nf
.br
        QPopupMenu * file = new QPopupMenu( this );
.br
        menuBar()->insertItem( "&File", file );
.fi
.PP
.nf
.br
        fileSaveAction->addTo( file );
.fi
.PP
We create a toolbar and add our fileSaveAction to it. Similarly we create a menu, add a top-level menu item, and add our fileSaveAction.
.PP
We recommend that actions are created as children of the window that they are used in. In most cases actions will be children of the application's main window.
.PP
To prevent recursion, don't create an action as a child of a widget that the action is later added to.
.PP
See also Main Window and Related Classes and Basic Widgets.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QAction::QAction ( QObject * parent, const char * name = 0, bool toggle = FALSE )"
Constructs an action called \fIname\fR with parent \fIparent\fR.
.PP
If \fItoggle\fR is TRUE the action will be a toggle action, otherwise it will be a command action.
.PP
If \fIparent\fR is a QActionGroup, the new action inserts itself into \fIparent\fR.
.PP
For accelerators and status tips to work, \fIparent\fR must either be a widget, or an action group whose parent is a widget.
.SH "QAction::QAction ( const QString & text, const QIconSet & icon, const QString & menuText, QKeySequence accel, QObject * parent, const char * name = 0, bool toggle = FALSE )"
This constructor creates an action with the following properties: the description \fItext\fR, the icon or iconset \fIicon\fR, the menu text \fImenuText\fR and keyboard accelerator \fIaccel\fR. It is a child of \fIparent\fR and called \fIname\fR. If \fItoggle\fR is TRUE the action will be a toggle action, otherwise it will be a command action.
.PP
If \fIparent\fR is a QActionGroup, the action automatically becomes a member of it.
.PP
For accelerators and status tips to work, \fIparent\fR must either be a widget, or an action group whose parent is a widget.
.PP
The \fItext\fR and \fIaccel\fR will be used for tool tips and status tips unless you provide specific text for these using setToolTip() and setStatusTip().
.SH "QAction::QAction ( const QString & text, const QString & menuText, QKeySequence accel, QObject * parent, const char * name = 0, bool toggle = FALSE )"
This constructor results in an icon-less action with the description \fItext\fR, the menu text \fImenuText\fR and the keyboard accelerator \fIaccel\fR. Its parent is \fIparent\fR and it is called \fIname\fR. If \fItoggle\fR is TRUE the action will be a toggle action, otherwise it will be a command action.
.PP
The action automatically becomes a member of \fIparent\fR if \fIparent\fR is a QActionGroup.