qobject.3qt

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

'\" t
.TH QObject 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
QObject \- The base class of all Qt objects
.SH SYNOPSIS
\fC#include <qobject.h>\fR
.PP
Inherits Qt.
.PP
Inherited by QAccel, QAccessibleObject, QAction, QApplication, QAssistantClient, QDataPump, QWidget, QCanvas, QStyle, QClipboard, QCopChannel, QDns, QLayout, QDragObject, QEditorFactory, QEventLoop, QFileIconProvider, QNetworkProtocol, QWSKeyboardHandler, QNetworkOperation, QObjectCleanupHandler, QProcess, QServerSocket, QSessionManager, QSignal, QSignalMapper, QSocket, QSocketNotifier, QSound, QSqlDatabase, QSqlDriver, QSqlForm, QStyleSheet, QTimer, QToolTipGroup, QTranslator, QUrlOperator, QValidator, and QAssistantClient.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQObject\fR ( QObject * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "virtual \fB~QObject\fR ()"
.br
.ti -1c
.BI "virtual const char * \fBclassName\fR () const"
.br
.ti -1c
.BI "virtual QMetaObject * \fBmetaObject\fR () const"
.br
.ti -1c
.BI "virtual bool \fBevent\fR ( QEvent * e )"
.br
.ti -1c
.BI "virtual bool \fBeventFilter\fR ( QObject * watched, QEvent * e )"
.br
.ti -1c
.BI "bool \fBisA\fR ( const char * clname ) const"
.br
.ti -1c
.BI "bool \fBinherits\fR ( const char * clname ) const"
.br
.ti -1c
.BI "const char * \fBname\fR () const"
.br
.ti -1c
.BI "const char * \fBname\fR ( const char * defaultName ) const"
.br
.ti -1c
.BI "virtual void \fBsetName\fR ( const char * name )"
.br
.ti -1c
.BI "bool \fBisWidgetType\fR () const"
.br
.ti -1c
.BI "bool \fBhighPriority\fR () const"
.br
.ti -1c
.BI "bool \fBsignalsBlocked\fR () const"
.br
.ti -1c
.BI "void \fBblockSignals\fR ( bool block )"
.br
.ti -1c
.BI "int \fBstartTimer\fR ( int interval )"
.br
.ti -1c
.BI "void \fBkillTimer\fR ( int id )"
.br
.ti -1c
.BI "void \fBkillTimers\fR ()"
.br
.ti -1c
.BI "QObject * \fBchild\fR ( const char * objName, const char * inheritsClass = 0, bool recursiveSearch = TRUE )"
.br
.ti -1c
.BI "const QObjectList * \fBchildren\fR () const"
.br
.ti -1c
.BI "QObjectList * \fBqueryList\fR ( const char * inheritsClass = 0, const char * objName = 0, bool regexpMatch = TRUE, bool recursiveSearch = TRUE ) const"
.br
.ti -1c
.BI "virtual void \fBinsertChild\fR ( QObject * obj )"
.br
.ti -1c
.BI "virtual void \fBremoveChild\fR ( QObject * obj )"
.br
.ti -1c
.BI "void \fBinstallEventFilter\fR ( const QObject * filterObj )"
.br
.ti -1c
.BI "void \fBremoveEventFilter\fR ( const QObject * obj )"
.br
.ti -1c
.BI "bool \fBconnect\fR ( const QObject * sender, const char * signal, const char * member ) const"
.br
.ti -1c
.BI "bool \fBdisconnect\fR ( const char * signal = 0, const QObject * receiver = 0, const char * member = 0 )"
.br
.ti -1c
.BI "bool \fBdisconnect\fR ( const QObject * receiver, const char * member = 0 )"
.br
.ti -1c
.BI "void \fBdumpObjectTree\fR ()"
.br
.ti -1c
.BI "void \fBdumpObjectInfo\fR ()"
.br
.ti -1c
.BI "virtual bool \fBsetProperty\fR ( const char * name, const QVariant & value )"
.br
.ti -1c
.BI "virtual QVariant \fBproperty\fR ( const char * name ) const"
.br
.ti -1c
.BI "QObject * \fBparent\fR () const"
.br
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "void \fBdeleteLater\fR ()"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBdestroyed\fR ()"
.br
.ti -1c
.BI "void \fBdestroyed\fR ( QObject * obj )"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QString \fBtr\fR ( const char * sourceText, const char * comment )"
.br
.ti -1c
.BI "QString \fBtrUtf8\fR ( const char * sourceText, const char * comment )"
.br
.ti -1c
.BI "const QObjectList * \fBobjectTrees\fR ()"
.br
.ti -1c
.BI "bool \fBconnect\fR ( const QObject * sender, const char * signal, const QObject * receiver, const char * member )"
.br
.ti -1c
.BI "bool \fBdisconnect\fR ( const QObject * sender, const char * signal, const QObject * receiver, const char * member )"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "QCString \fBname\fR - the name of this object"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "const QObject * \fBsender\fR ()"
.br
.ti -1c
.BI "virtual void \fBtimerEvent\fR ( QTimerEvent * )"
.br
.ti -1c
.BI "virtual void \fBchildEvent\fR ( QChildEvent * )"
.br
.ti -1c
.BI "virtual void \fBcustomEvent\fR ( QCustomEvent * )"
.br
.ti -1c
.BI "virtual void \fBconnectNotify\fR ( const char * signal )"
.br
.ti -1c
.BI "virtual void \fBdisconnectNotify\fR ( const char * signal )"
.br
.ti -1c
.BI "virtual bool \fBcheckConnectArgs\fR ( const char * signal, const QObject * receiver, const char * member )"
.br
.in -1c
.SS "Static Protected Members"
.in +1c
.ti -1c
.BI "QCString \fBnormalizeSignalSlot\fR ( const char * signalSlot )"
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
.in +1c
.ti -1c
.BI "void * \fBqt_find_obj_child\fR ( QObject * parent, const char * type, const char * name )"
.br
.in -1c
.SH DESCRIPTION
The QObject class is the base class of all Qt objects.
.PP
QObject is the heart of the Qt object model. The central feature in this model is a very powerful mechanism for seamless object communication called signals and slots. You can connect a signal to a slot with connect() and destroy the connection with disconnect(). To avoid never ending notification loops you can temporarily block signals with blockSignals(). The protected functions connectNotify() and disconnectNotify() make it possible to track connections.
.PP
QObjects organize themselves in object trees. When you create a QObject with another object as parent, the object will automatically do an insertChild() on the parent and thus show up in the parent's children() list. The parent takes ownership of the object i.e. it will automatically delete its children in its destructor. You can look for an object by name and optionally type using child() or queryList(), and get the list of tree roots using objectTrees().
.PP
Every object has an object name() and can report its className() and whether it inherits() another class in the QObject inheritance hierarchy.
.PP
When an object is deleted, it emits a destroyed() signal. You can catch this signal to avoid dangling references to QObjects. The QGuardedPtr class provides an elegant way to use this feature.
.PP
QObjects can receive events through event() and filter the events of other objects. See installEventFilter() and eventFilter() for details. A convenience handler, childEvent(), can be reimplemented to catch child events.
.PP
Last but not least, QObject provides the basic timer support in Qt; see QTimer for high-level support for timers.
.PP
Notice that the Q_OBJECT macro is mandatory for any object that implements signals, slots or properties. You also need to run the moc program (Meta Object Compiler) on the source file. We strongly recommend the use of this macro in \fIall\fR subclasses of QObject regardless of whether or not they actually use signals, slots and properties, since failure to do so may lead certain functions to exhibit undefined behaviour.
.PP
All Qt widgets inherit QObject. The convenience function isWidgetType() returns whether an object is actually a widget. It is much faster than inherits( "QWidget" ).
.PP
Some QObject functions, e.g. children(), objectTrees() and queryList() return a QObjectList. A QObjectList is a QPtrList of QObjects. QObjectLists support the same operations as QPtrLists and have an iterator class, QObjectListIt.
.PP
See also Object Model.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QObject::QObject ( QObject * parent = 0, const char * name = 0 )"
Constructs an object called \fIname\fR with parent object, \fIparent\fR.
.PP
The parent of an object may be viewed as the object's owner. For instance, a dialog box is the parent of the" OK" and "Cancel" buttons it contains.
.PP
The destructor of a parent object destroys all child objects.
.PP
Setting \fIparent\fR to 0 constructs an object with no parent. If the object is a widget, it will become a top-level window.
.PP
The object name is some text that can be used to identify a QObject. It's particularly useful in conjunction with \fIQt Designer\fR. You can find an object by name (and type) using child(). To find several objects use queryList().
.PP
See also parent(), name, child(), and queryList().
.SH "QObject::~QObject ()\fC [virtual]\fR"
Destroys the object, deleting all its child objects.
.PP
All signals to and from the object are automatically disconnected.
.PP
\fBWarning:\fR All child objects are deleted. If any of these objects are on the stack or global, sooner or later your program will crash. We do not recommend holding pointers to child objects from outside the parent. If you still do, the QObject::destroyed() signal gives you an opportunity to detect when an object is destroyed.
.SH "void QObject::blockSignals ( bool block )"
Blocks signals if \fIblock\fR is TRUE, or unblocks signals if \fIblock\fR is FALSE.
.PP
Emitted signals disappear into hyperspace if signals are blocked.
.PP
Example: rot13/rot13.cpp.
.SH "bool QObject::checkConnectArgs ( const char * signal, const QObject * receiver, const char * member )\fC [virtual protected]\fR"
Returns TRUE if the \fIsignal\fR and the \fImember\fR arguments are compatible; otherwise returns FALSE. (The \fIreceiver\fR argument is currently ignored.)
.PP
\fBWarning:\fR We recommend that you use the default implementation and do not reimplement this function.
.SH "QObject * QObject::child ( const char * objName, const char * inheritsClass = 0, bool recursiveSearch = TRUE )"
Searches the children and optionally grandchildren of this object, and returns a child that is called \fIobjName\fR that inherits \fIinheritsClass\fR. If \fIinheritsClass\fR is 0 (the default), any class matches.
.PP
If \fIrecursiveSearch\fR is TRUE (the default), child() performs a depth-first search of the object's children.
.PP
If there is no such object, this function returns 0. If there are more than one, the first one found is retured; if you need all of them, use queryList().
.SH "void QObject::childEvent ( QChildEvent * )\fC [virtual protected]\fR"
This event handler can be reimplemented in a subclass to receive child events.
.PP
Child events are sent to objects when children are inserted or removed.
.PP
Note that events with QEvent::type() QEvent::ChildInserted are posted (with QApplication::postEvent()) to make sure that the child's construction is completed before this function is called.
.PP
If a child is removed immediately after it is inserted, the \fCChildInserted\fR event may be suppressed, but the \fCChildRemoved\fR event will always be sent. In such cases it is possible that there will be a \fCChildRemoved\fR event without a corresponding \fCChildInserted\fR event.
.PP
If you change state based on \fCChildInserted\fR events, call QWidget::constPolish(), or do
.PP
.nf
.br
        QApplication::sendPostedEvents( this, QEvent::ChildInserted );
.br
.fi
in functions that depend on the state. One notable example is QWidget::sizeHint().
.PP
See also event() and QChildEvent.
.PP
Reimplemented in QMainWindow and QSplitter.
.SH "const QObjectList * QObject::children () const"
Returns a list of child objects, or 0 if this object has no children.
.PP
The QObjectList class is defined in the qobjectlist.h header file.
.PP
The first child added is the first object in the list and the last child added is the last object in the list, i.e. new children are appended at the end.
.PP
Note that the list order changes when QWidget children are raised or lowered. A widget that is raised becomes the last object in the list, and a widget that is lowered becomes the first object in the list.
.PP
See also child(), queryList(), parent(), insertChild(), and removeChild().
.SH "const char * QObject::className () const\fC [virtual]\fR"
Returns the class name of this object.
.PP
This function is generated by the Meta Object Compiler.
.PP
\fBWarning:\fR This function will return the wrong name if the class definition lacks the Q_OBJECT macro.
.PP
See also name, inherits(), isA(), and isWidgetType().
.PP
Example: sql/overview/custom1/main.cpp.
.SH "bool QObject::connect ( const QObject * sender, const char * signal, const QObject * receiver, const char * member )\fC [static]\fR"
Connects \fIsignal\fR from the \fIsender\fR object to \fImember\fR in object \fIreceiver\fR, and returns TRUE if the connection succeeds; otherwise returns FALSE.
.PP
You must use the SIGNAL() and SLOT() macros when specifying the \fIsignal\fR and the \fImember\fR, for example:
.PP
.nf
.br
    QLabel     *label  = new QLabel;
.br
    QScrollBar *scroll = new QScrollBar;
.br
    QObject::connect( scroll, SIGNAL(valueChanged(int)),
.br
                      label,  SLOT(setNum(int)) );
.br
.fi
.PP
This example ensures that the label always displays the current scroll bar value. Note that the signal and slots parameters must not contain any variable names, only the type. E.g. the following would not work and return FALSE: QObject::connect( scroll, SIGNAL(valueChanged(int v)), label, SLOT(setNum(int v)) );
.PP
A signal can also be connected to another signal:
.PP
.nf
.br
    class MyWidget : public QWidget
.br
    {
.br
        Q_OBJECT
.br
    public:
.br
        MyWidget();
.br
.br
    signals:
.br
        void myUsefulSignal();
.br
.br