QObject

La classe QObject est la classe de base de tous les objets Qt. Plus d'informations...

#include <QObject>

Héritage

Hérité par Phonon::AudioOutput, Phonon::BackendCapabilities::Notifier, Phonon::Effect, Phonon::MediaController, Phonon::MediaObject, Q3Accel, Q3Action, Q3Canvas, Q3Dns, Q3DragObject, Q3EditorFactory, Q3FileIconProvider, Q3NetworkOperation, Q3NetworkProtocol, Q3Process, Q3ServerSocket, Q3Signal, Q3SqlForm, Q3StyleSheet, Q3UrlOperator, Q3WhatsThis, QAbstractAnimation, QAbstractEventDispatcher, QAbstractFontEngine, QAbstractItemDelegate, QAbstractItemModel, QAbstractMessageHandler, QAbstractNetworkCache, QAbstractState, QAbstractTextDocumentLayout, QAbstractTransition, QAbstractUriResolver, QAbstractVideoSurface, QAccessibleBridgePlugin, QAccessiblePlugin, QAction, QActionGroup, QAssistantClient, QAudioInput, QAudioOutput, QAxFactory, QAxObject, QAxScript, QAxScriptManager, QButtonGroup, QClipboard, QCompleter, QCopChannel, QCoreApplication, QDataWidgetMapper, QDBusAbstractAdaptor, QDBusAbstractInterface, QDBusPendingCallWatcher, QDBusServer, QDBusServiceWatcher, QDecorationPlugin, QDesignerFormEditorInterface, QDesignerFormWindowManagerInterface, QDirectPainter, QDrag, QEventLoop, QExtensionFactory, QExtensionManager, QFileSystemWatcher, QFontEnginePlugin, QFtp, QFutureWatcher, QGesture, QGLShader, QGLShaderProgram, QGraphicsAnchor, QGraphicsEffect, QGraphicsItemAnimation, QGraphicsObject, QGraphicsScene, QGraphicsTransform, QHelpEngineCore, QHelpSearchEngine, QHttp, QIconEnginePlugin, QIconEnginePluginV2, QImageIOPlugin, QInputContext, QInputContextPlugin, QIODevice, QItemSelectionModel, QKbdDriverPlugin, QLayout, QLibrary, QLocalServer, QMimeData, QMouseDriverPlugin, QMovie, QNetworkAccessManager, QNetworkCookieJar, QObjectCleanupHandler, QPictureFormatPlugin, QPluginLoader, QScreenDriverPlugin, QScriptEngine, QScriptEngineDebugger, QScriptExtensionPlugin, QSessionManager, QSettings, QSharedMemory, QShortcut, QSignalMapper, QSignalSpy, QSocketNotifier, QSound, QSqlDriver, QSqlDriverPlugin, QStyle, QStylePlugin, QSvgRenderer, QSyntaxHighlighter, QSystemTrayIcon, QTcpServer, QTextCodecPlugin, QTextDocument, QTextObject, QThread, QThreadPool, QTimeLine, QTimer, QTranslator, QUiLoader, QUndoGroup, QUndoStack, QValidator, QWebFrame, QWebHistoryInterface, QWebPage, QWebPluginFactory, QWidget, QWSClient, QWSInputMethod et QWSServer.

Note : toutes les fonctions dans cette classe sont réentrantes mais connect(), connect(), disconnect() et disconnect() sont aussi thread-safe.

Description détaillée

La classe QObject est la classe de base de tous les objets Qt.

QObject est le coeur du modèle objet de Qt. La caractéristique centrale de ce modèle est un mécanisme très puissant de communication homogène entre objets, appelé signaux et slots. Vous pouvez connecter un signal à un slot avec la fonction connect() et détruire cette connexion avec la fonction disconnect(). Pour éviter des boucles de notifications sans fin, vous pouvez les bloquer temporairement avec la fonction blockSignals(). Les fonctions protégées connectNotify() et disconnectNotify() rendent possible le suivi des connexions.

Les QObject s'organisent dans des arbres d'objets. Quand vous créez un QObject avec un autre objet comme parent, celui-ci s'ajoutera automatiquement à la liste d'enfants children() du parent. Le parent devient propriétaire de l'objet, cela signifie qu'il supprimera automatiquement ses enfants dans son destructeur. Vous pouvez chercher un objet par son nom et éventuellement son type en utilisant les fonctions findChild() et findChildren().

Chaque objet possède un objectName() (nom d'objet) et le nom de sa classe peut être trouvé grâce au metaObject() correspondant (voir QMetaObject::className()). Vous pouvez déterminer si la classe de l'objet hérite d'une autre classe dans la hiérarchie d'héritage de QObject en utilisant la fonction inherits().

Quand un objet est détruit, il émet un signal destroyed(). Vous pouvez utiliser ce signal pour éviter les références cassées à des QObject.

Les QObject peuvent recevoir des événements à travers event() et filtrer les événements d'autres objets. Voir installEventFilter() et eventFilter() pour plus de détails. Le gestionnaire childEvent() peut-être réimplémenté pour recevoir les événements des enfants.

Les événements sont délivrés dans le thread dans lequel l'objet a été créé ; voir Support des threads dans Qt et thread() pour plus de détails. Notez que le traitement des événements n'est pas du tout réalisé pour les QObject n'étant pas liés à un thread (thread() retourne zéro). Utilisez la fonction moveToThread() pour changer le thread auquel est lié un objet et ses enfants (l'objet ne peut pas être déplacé s'il a un parent).

Pour finir, QObject propose le support d'une minuterie basique dans Qt ; voir QTimer pour le support des minuteries de haut niveau.

Notez que la macro Q_OBJECT est obligatoire pour tout objet qui implémente des signaux, des slots ou des propriétés. Vous devez également exécuter le compilateur de méta objets sur le fichier source. Nous vous recommandons fortement d'utiliser cette macro dans toutes les sous-classes de QObject, qu'elles utilisent ou non des signaux, des slots ou des propriétés, car ne pas le faire peut entraîner un comportement étrange de certaines fonctions.

Tous les widgets de Qt héritent de QObject. La fonction isWidgetType() retournera si un objet est réellement un widget ou non. Elle est beaucoup plus rapide que qobject_cast<QWidget *>(obj) ou obj->inherits("QWidget").

Certaines fonctions de QObject, par exemple children(), retournent une QObjectList. QObjectList est un typedef de QList<QObject *>.

Pas de constructeur de copie ni d'opérateur d'assignation

QObject n'a ni constructeur de copie, ni opérateur d'assignation, du fait de sa conception. En réalité, ils sont définis mais dans une section private avec la macro Q_DISABLE_COPY(). En fait, toutes les classes de Qt dérivées de QObject (directement ou non) utilisent cette macro pour déclarer leur constructeur de copie et leur opérateur d'assignation comme étant private. La raison de ceci est exposée dans la discussion Identité versus valeur du modèle objet de Qt.

La principale conséquence est que vous devriez utiliser des pointeurs sur QObject (ou sur les sous-classes de QObject) là où vous auriez été tentés d'utiliser vos sous-classes comme une valeur. Par exemple, sans constructeur de copie, vous ne pouvez pas utiliser une sous-classe de QObject comme une valeur à stocker dans une des classes conteneurs. Vous devez utiliser des pointeurs.

Auto-connexion

Le système de méta-objets de Qt propose un mécanisme pour connecter automatiquement les signaux et slots entre les sous-classes de QObjet et leurs enfants. Du moment que les objets sont définis avec des noms appropriés et que les slots suivent une simple convention de nommage, cette connexion peut se faire pendant l'exécution grâce à la fonction QMetaObject::connectSlotsByName().

uic génère un code qui appelle cette fonction pour activer l'auto-connexion entre les widgets des formulaires créés avec Qt Designer. Plus d'informations sur l'utilisation de l'auto-connexion avec Qt Designer sont données dans la section Utiliser un fichier de design UI dans votre application du manuel de Qt Designer.

Propriétés dynamiques

Depuis Qt 4.2, des propriétés dynamiques peuvent être ajoutées ou supprimées sur des instances de QObject pendant l'exécution. Les propriétés dynamiques ne nécessitent pas d'être déclarées à la compilation. Cependant, elles offrent les mêmes avantages que des propriétés statiques et sont manipulées à l'aide de la même API, en utilisant property() pour les lire et setProperty() pour les écrire.

Depuis Qt 4.3, les propriétés dynamiques sont supportées par Qt Designer et des propriétés dynamiques peuvent être ajoutées à la fois aux widgets standards de Qt et aux formulaires créés par l'utilisateur.

Tous les dérivés de QObject supportent la fonctionnalité de traduction de Qt, rendant possible la traduction de l'interface utilisateur d'une application dans plusieurs langues.

Pour rendre le texte visible à l'utilisateur traducteur, il doit être entouré dans des appels à la fonction tr(). Ceci est expliqué en détail dans Écrire du code source pour la traduction.

Voir aussi QMetaObject, QPointer, QObjectCleanupHandler, Q_DISABLE_COPY() et Arbres et possession d'objets.

Propriétés

objectName : QString

Cette propriété détient le nom de cet objet.

Vous pouvez trouver un objet par son nom (et le type) à l'aide de findChild(). Vous pouvez trouver un ensemble d'objets avec findChildren().

 qDebug("MyClass::setPrecision() : (%s) précision invalide %f",
        qPrintable(objectName()), newPrecision);

Par défaut, cette propriété contient une chaîne de caractères vide.

Fonction d'accès

QString objectName () const

void setObjectName ( const QString & name )

Voir aussi metaObject() et QMetaObject::className().

Fonctions membres

Q_INVOKABLE QObject::QObject ( QObject * parent = 0 )

Construit un objet avec parent comme objet parent.

Le parent d'un objet peut être vu comme le possesseur de l'objet. Par exemple, une boîte de dialogue est le parent des boutons OK et Cancel qu'elle contient.

Le destructeur d'un objet parent détruit tous ses objets enfants.

Mettre parent à 0 construit un objet sans parent. Si cet objet est un widget, il deviendra une fenêtre.

Voir aussi parent(), findChild() et findChildren().

QObject::~QObject () [virtual]

Détruit l'objet et occasionne la suppression de tous ses objets enfants.

Tous les signaux vers et depuis l'objet sont automatiquement déconnectés et toute attente d'événements postée pour l'objet est supprimée de la file d'événements. Cependant, il est souvent recommandé d'utiliser deleteLater() plutôt que de supprimer directement une sous-classe de QObject.

Attention : tous les objets enfants sont supprimés. Si l'un de ces objets est sur la pile ou global, tôt ou tard votre programme plantera. Nous déconseillons de garder des pointeurs vers des objets enfants à l'extérieur du parent. Si vous persistez à vouloir le faire, le signal destroyed() vous donne une chance de détecter quand un objet est détruit.

Attention : la suppression d'un QObject alors que les événements en cours sont en attente d'être délivrés peut provoquer un plantage. Vous ne devez pas supprimer le QObject directement s'il existe dans un autre thread que celui où il est actuellement exécuté. Utilisez plutôt deleteLater(), qui demandera à la boucle événementielle de supprimer l'objet après que tous les événements à venir lui sont délivrés.

Voir aussi deleteLater().

bool QObject::blockSignals ( bool block )

Si block vaut true, les signaux émis par cet objet sont bloqués (c'est-à-dire que, en émettant un signal, quelque chose qui lui est connecté ne sera pas invoqué). Si block vaut false, aucun blocage ne se produira.

La valeur retournée est la valeur précédente de signalsBlocked().

Notez que le signal destroyed() sera émis même si les signaux de cet objet ont été bloqués.

Voir aussi signalsBlocked().

void QObject::childEvent ( QChildEvent * event ) [virtual protected]

Ce gestionnaire d'événements peut être réimplémenté dans un dérivé pour recevoir les événements des enfants. L'événement est passé par le paramètre event.

Les événementsQEvent::ChildAdded et QEvent::ChildRemoved sont envoyés aux objets quand les enfants sont ajoutés ou supprimés. Dans les deux cas, vous ne pouvez vous reposer que sur le fait qu'un enfant est un QObject ou, si isWidgetType() retourne true, un QWidget, parce que, dans le cas ChildAdded, l'enfant n'est pas encore complètement construit et, dans le cas ChildRemoved, il peut déjà être détruit.

Les événements QEvent::ChildPolished sont envoyés aux widgets quand les enfants sont polis ou quand des enfants polis sont ajoutés. Si vous recevez un événement de polissage d'enfant, sa construction est généralement achevée. Cependant, ceci n'est pas garanti et de multiples événements de polissage peuvent être envoyés pendant l'exécution du constructeur d'un widget.

Pour tous les widgets enfants, vous recevez un événement ChildAdded, zéro ou plusieurs événements ChildPolished et un événement ChildRemoved.

L'événement ChildPolished est omis si un enfant est supprimé immédiatement après qu'il est ajouté. Si un enfant est poli plusieurs fois durant sa construction et sa destruction, vous recevrez peut-être plusieurs événements de polissage pour les enfants, chaque fois avec une table virtuelle différente. Voir aussi event().

const QObjectList & QObject::children () const

Retourne une liste d'objets enfants. La classe QObjectList est définie dans le fichier d'en-tête <QObject> comme ceci :

 typedef QList<QObject*> QObjectList;

Le premier enfant ajouté est le premier objet dans la liste et le dernier enfant ajouté est le dernier objet dans la liste, c'est-à-dire que les nouveaux enfants sont ajoutés à la fin.

Notez que, lorsque les enfants QWidget sont élevés ou abaissés, l'ordre de la liste change. Un widget qui est élevé devient le dernier objet dans la liste et un widget qui est abaissé devient le premier objet dans la liste.

Voir aussi findChild(), findChildren(), parent() et setParent().

bool QObject::connect ( const QObject * sender, const char * signal, const QObject * receiver, const char * method, Qt::ConnectionType type = Qt::AutoConnection ) [static]

Crée une connexion du type donné entre le signal de l'objet sender et la méthode method de l'objet receiver. Retourne true si la connexion s'est faite correctement, false sinon.

Vous devez utiliser les macros SIGNAL() et SLOT() en spécifiant le signal et la méthode method, par exemple :

QLabel *label = new QLabel;
QScrollBar *scrollBar = new QScrollBar;
QObject::connect(scrollBar, SIGNAL(valueChanged(int)),
                 label,  SLOT(setNum(int)));

Cet exemple s'assure que le label affiche toujours la valeur courante de la barre de défilement. Notez que les paramètres du signal et du slot ne doivent pas contenir de nom de variable, seulement le type. Par exemple, le code suivant ne fonctionnera pas et retournera false :

// Mauvais
QObject::connect(scrollBar, SIGNAL(valueChanged(int value)),
                 label, SLOT(setNum(int value)));

Un signal peut également être connecté à un autre signal :

class MonWidget : public QWidget
{
    Q_OBJECT
 
public:
    MonWidget();
 
signals:
    void buttonClicked();
 
private:
    QPushButton *monBouton;
};
 
MonWidget::MonWidget()
{
    monBouton = new QPushButton(this);
    connect(monBouton, SIGNAL(clicked()),
            this, SIGNAL(buttonClicked()));
}

Dans cet exemple, le constructeur de MonWidget retransmet un signal depuis une variable membre privée (monBouton) et le rend disponible sous un nom relatif à MonWidget.

Un signal peut-être connecté à plusieurs slots et signaux, de même que plusieurs signaux peuvent être connectés à un même slot.

Si un signal est connecté à plusieurs slots, ceux-ci sont appelés au moment où le signal est émis, dans le même ordre que les connexions ont été établies.

Cette fonction retourne true si la connexion entre le signal et le slot a été établie avec succès. Elle retourne false si la connexion n'a pas pu être créée, par exemple si QObject est incapable de vérifier l'existence du signal ou de la méthode method ou si leur signature n'est pas compatible.

Par défaut, un signal est émis à chaque connexion que vous faites ; deux signaux sont émis pour des connexions doubles. Vous pouvez casser toutes ces connexions avec un unique appel de disconnect(). Si vous passez le type Qt::UniqueConnection, la connexion sera établie si ce n'est pas un doublon. S'il y a déjà un doublon (exactement le même signal et le même slot des mêmes objets), la connexion échouera et la fonction retournera false.

Le paramètre optionnel type décrit le type de connexion à établir. Entre autres, il détermine si un signal particulier est délivré immédiatement à un slot ou mis en file pour être délivré plus tard. Si le signal est mis en file, le type des paramètres doit être connu par le système de méta-objets de Qt, parce que Qt doit copier les arguments et les stocker dans un événement caché. Si vous tentez d'utiliser une connexion avec mise en file et que vous obtenez l'erreur suivante :

QObject::connect: Cannot queue arguments of type 'MyType'
(Make sure 'MyType' is registered using qRegisterMetaType().)

Appelez qRegisterMetaType() pour enregistrer le type de données avant d'établir la connexion.

Note : cette fonction est thread-safe.

Voir aussi disconnect(), sender() et qRegisterMetaType().

bool QObject::connect ( const QObject * sender, const char * signal, const char * method, Qt::ConnectionType type = Qt::AutoConnection ) const

Il s'agit d'une fonction surchargée de connect().

Connecte le signal de l'objet sender à sa méthode method.

Équivalent à connect(sender, signal, this, method, type).

Chaque connexion que vous faites émet un signal et, de ce fait, des connexions doubles émettent deux signaux. Vous pouvez casser une connexion grâce à disconnect().

Note : cette fonction est thread-safe.

Voir aussi disconnect().

void QObject::connectNotify ( const char * signal ) [virtual protected]

Cette fonction virtuelle est appelée quand quelque chose est connecté au signal de cet objet.

Si vous voulez comparer le signal avec un signal spécifique, utilisez QLatin1String et la macro SIGNAL() comme ceci :

if (QLatin1String(signal) == SIGNAL(valueChanged(int))) {
     // le signal est valueChanged(int)
}

Si le signal contient plusieurs paramètres ou des paramètres qui contiennent des espaces, appelez QMetaObject::normalizedSignature() sur le résultat de la macro SIGNAL().

Attention : cette fonction viole le principe orienté objet de modularité. Cependant, il peut être utile de ne faire une initialisation lourde que si quelque chose est connecté à un signal.

Voir aussi connect() et disconnectNotify().

void QObject::customEvent ( QEvent * event ) [virtual protected]

Ce gestionnaire d'événements peut être réimplémenté dans un dérivé pour recevoir des événements personnalisés, des événements définis par l'utilisateur avec une valeur de type au moins aussi grande que l'objet QEvent::User de l'énumération QEvent::Type, d'habitude un dérivé de QEvent. L'événement est passé par le paramètre event.

Voir aussi event() et QEvent.

void QObject::deleteLater () [slot]

Marque cet objet pour suppression.

L'objet sera détruit quand la boucle événementielle reprendra le contrôle. Si elle n'est pas lancée quand cette fonction est appelée (par exemple si elle est appelée sur un objet avant QCoreApplication::exec()), l'objet sera détruit dès qu'elle sera lancée.

Notez qu'entrer et sortir de la boucle (par exemple en ouvrant une boîte de dialogue modale) n'effectuera pas de suppression différée ; pour que l'objet soit supprimé, la boucle depuis laquelle deleteLater() est appelée doit reprendre le contrôle.

Note : il est sûr d'appeler cette fonction plus d'une fois ; quand la première suppression différée est arrivée, tout événement en attente concernant l'objet est supprimé de la queue des événements.

Voir aussi destroyed() et QPointer.

void QObject::destroyed ( QObject * obj = 0 ) [signal]

Ce signal est émis immédiatement avant que l'objet obj soit détruit et ne peut pas être bloqué.

Tous les enfants des objets sont détruits immédiatement après que ce signal soit émis.

Voir aussi deleteLater() et QPointer.

bool QObject::disconnect ( const QObject * sender, const char * signal, const QObject * receiver, const char * method ) [static]

Déconnecte le signal appartenant à l'objet sender de la méthode method appartenant à l'objet receiver. Retourne true si la connexion a été cassée avec succès, renvoie false sinon.

Une connexion signal-slot est supprimée quand l'un ou l'autre des objets concernés est détruit.

disconnect() est habituellement utilisée de trois façons, comme l'illustrent les exemples suivants :

• 1. Déconnecter tout ce qui est connecté aux signaux d'un objet :

 disconnect(myObject, 0, 0, 0);

Équivalent à la fonction surchargée non statique :

 myObject->disconnect();

• 2. Déconnecter tout ce qui est connecté à un signal spécifique :

 disconnect(myObject, SIGNAL(mySignal()), 0, 0);

Équivalent à la fonction surchargée non statique :

 myObject->disconnect(SIGNAL(mySignal()));

• 3. Déconnecter un objet recevant spécifique :

 disconnect(myObject, 0, myReceiver, 0);

Équivalent à la fonction surchargée non statique :

 myObject->disconnect(myReceiver);

0 peut-être utilisé en remplacement pour signifier respectivement « tous les signaux », « tous les objets recevant » ou « tous les slots dans l'objet recevant ».

Le sender ne doit jamais être 0. (Vous ne pouvez pas déconnecter des signaux pour plus d'un seul objet à la fois).

Si le signal est 0, la fonction déconnecte l'objet receiver et la méthode method de tout les signaux. Sinon, seul le signal spécifié est déconnecté.

Si receiver vaut 0, la fonction déconnecte tout ce qui est connecté au signal. Sinon, les slots appartenant à des objets différents de receiver ne sont pas déconnectés.

Si method vaut 0, la fonction déconnecte tout ce qui est connecté au receiver. Sinon, seuls les slots appelés method seront déconnectés. method doit valoir 0 si receiver est omis, vous ne pouvez donc pas déconnecter un slot ayant un nom particulier sur tous les objets.

Note : cette fonction est thread-safe.

Voir aussi connect().

bool QObject::disconnect ( const char * signal = 0, const QObject * receiver = 0, const char * method = 0 )

Cette fonction surcharge disconnect().

Déconnecte le signal de la méthode method de l'objet receiver.

Une connexion signal-slot est supprimée lorsque l'un des objets impliqués est détruit.

Note : cette fonction est thread-safe.

bool QObject::disconnect ( const QObject * receiver, const char * method = 0 )

Cette fonction surcharge disconnect().

Déconnecte tous les signaux de cet objet receiver de method

Une connexion signal-slot est supprimée lorsque l'un des objets impliqués est détruit.

void QObject::disconnectNotify ( const char * signal ) [virtual protected]

Cette fonction virtuelle est appelée quand quelque chose a été déconnecté du signal de cet objet.

Voir connectNotify() pour un exemple de comparaison entre le signal et un signal spécifique.

Attention : cette fonction viole le principe orienté objet de modularité. Cependant, elle peut être utile pour optimiser l'accès à des ressources lourdes.

Voir aussi disconnect() et connectNotify().

void QObject::dumpObjectInfo ()

Affiche des informations entre autres sur les connexions des signaux de cet objet sur la sortie de débogage.

Cette fonction est utile pour le débogage mais ne fait rien si la bibliothèque a été compilée en release (c'est-à-dire sans les informations de débogage).

Voir aussi dumpObjectTree().

void QObject::dumpObjectTree ()

Affiche un arbre des enfants sur la sortie de débogage.

Cette fonction est utile pour le débogage mais ne fait rien si la bibliothèque a été compilée en release (c'est-à-dire sans les informations de débogage).

Voir aussi dumpObjectInfo().

QList<QByteArray> QObject::dynamicPropertyNames () const

Retourne les noms de toutes les propriétés qui sont ajoutées dynamiquement à l'objet en utilisant setProperty().

Cette fonction a été introduite dans Qt 4.2.

bool QObject::event ( QEvent * e ) [virtual]

Cette fonction virtuelle reçoit des événements de l'objet et doit retourner true si l'événement e a été reconnu et traité.

La fonction event() peut être réimplémentée pour personnaliser le comportement d'un objet.

Voir aussi installEventFilter(), timerEvent(), QApplication::sendEvent(), QApplication::postEvent() et QWidget::event().

bool QObject::eventFilter ( QObject * watched, QEvent * event ) [virtual]

Filtre les événements si cet objet a été installé comme filtre d'événements pour l'objet watched.

Dans la réimplémentation de cette fonction, si vous voulez filtrer et rejeter l'événement event, c'est-à-dire faire en sorte qu'il ne soit plus traité, retournez true ; sinon, retournez false.

Exemple :

 class MainWindow : public QMainWindow
 {
 public:
     MainWindow();
 
 protected:
     bool eventFilter(QObject *obj, QEvent *ev);
 
 private:
     QTextEdit *textEdit;
 };
 
 MainWindow::MainWindow()
 {
     textEdit = new QTextEdit;
     setCentralWidget(textEdit);
 
     textEdit->installEventFilter(this);
 }
 
 bool MainWindow::eventFilter(QObject *obj, QEvent *event)
 {
     if (obj == textEdit) {
         if (event->type() == QEvent::KeyPress) {
             QKeyEvent *keyEvent = static_cast<QKeyEvent*>(event);
             qDebug() << "Ate key press" << keyEvent->key();
             return true;
         } else {
             return false;
         }
     } else {
         //passer l'événement à la classe parent
         return QMainWindow::eventFilter(obj, event);
     }
 }

Remarquez dans l'exemple ci-dessus que les événements non manipulés sont passés à la fonction eventFilter() de la classe mère, puisqu'elle pourrait avoir réimplémenté eventFilter() pour son fonctionnement interne.

Attention : si vous supprimez l'objet receveur dans cette fonction, assurez-vous de retourner true. Sinon, Qt va renvoyer l'événement à l'objet supprimé et le programme risque de planter.

Voir aussi installEventFilter().

T QObject::findChild ( const QString & name = QString() ) const

Retourne l'enfant de cet objet qui peut être casté en T et qui est appelé name ou 0 s'il n'y a pas de tel objet. Omettre l'argument name fait que tous les noms d'objets correspondent. La recherche est effectuée d'une manière récursive.

S'il y a plus d'un enfant correspondant à la recherche, l'ancêtre le plus direct est retourné. S'il y a plusieurs ancêtres aussi directs les uns que les autres, il n'est pas possible de déterminer lequel sera retourné. Dans ce cas, findChildren() devrait être utilisée.

Cet exemple retourne un enfant QPushButton du widget parent parentWidget nommé « button1 » :

QPushButton *button = parentWidget->findChild<QPushButton *>("button1");

Cet exemple retourne un enfant QListWidget du widget parent parentWidget :

QListWidget *list = parentWidget->findChild<QListWidget *>();

Attention : cette fonction n'est pas disponible dans MSVC 6. Utilisez qFindChild() si vous devez supporter cette version du compilateur.

Voir aussi findChildren() et qFindChild().

QList<T> QObject::findChildren ( const QString & name = QString() ) const

Retourne tous les enfants de cet objet avec le nom name donné et qui peuvent être castés en T ou une liste vide s'il n'y a pas de tel objet. Omettre l'argument name fait que tous les noms d'objets correspondent. La recherche est effectuée d'une manière récursive.

L'exemple suivant montre la manière de trouver une liste d'enfants de type QWidget du widget parent parentWidget nommés widgetname :

QList<QWidget *> widgets = parentWidget.findChildren<QWidget *>("widgetname");

Cet exemple retourne tous les QPushButton enfants du widget parent parentWidget :

QList<QPushButton *> allPButtons = parentWidget.findChildren<QPushButton *>();

Attention : cette fonction n'est pas disponible sur MSVC 6. Utilisez qFindChildren() si vous devez supporter cette version du compilateur.

Voir aussi findChild() and qFindChildren().

QList<T> QObject::findChildren ( const QRegExp & regExp ) const

Cette fonction surcharge findChildren().

Retourne les enfants de cet objet qui peuvent être castés en T et qui ont des noms qui correspondent à l'expression régulière regExp ou une liste vide s'il n'y a pas de tel objet. La recherche est effectuée d'une manière récursive.

Attention : cette fonction n'est pas disponible avec MSVC 6. Utilisez qFindChildren() si vous devez supporter cette version du compilateur.

bool QObject::inherits ( const char * className ) const

Retourne true si cet objet est une instance d'une classe qui hérite de className ou une sous-classe de QObject qui hérite de className ; retourne false sinon.

On considère qu'une classe hérite d'elle même.

Exemple :

 QTimer *timer = new QTimer;          // QTimer hérite de QObject
 timer->inherits("QTimer");           // retourne true
 timer->inherits("QObject");          // retourne true
 timer->inherits("QAbstractButton");  // retourne false
 
 // QVBoxLayout hinérite de QObject et QLayoutItem
 QVBoxLayout *layout = new QVBoxLayout;
 layout->inherits("QObject");         // retourne true
 layout->inherits("QLayoutItem");     // retourne true (même si QLayoutItem n'est pas un QObject

Si vous avez besoin de déterminer si un objet est une instance d'une classe particulière dans le but de la caster, pensez à utiliser qobject_cast<Type *>(object) à la place.

Voir aussi metaObject() et qobject_cast().

void QObject::installEventFilter ( QObject * filterObj )

Installe un filtre d'événement filterObj sur cet objet. Par exemple :

 monitoredObj->installEventFilter(filterObj);

Un filtre d'événement est un objet qui reçoit tous les événements envoyés à l'objet. Le filtre peut soit les arrêter soit les passer à cet objet. Le filtre d'événements filterObj reçoit les événements via sa fonction eventFilter(). La fonction eventFilter() doit retourner true si l'événement devrait être filtré (c'est-à-dire arrêté) ; sinon, elle doit retourner false.

Si de multiples filtres d'événements sont installés sur un seul objet, le filtre installé en dernier est activé en premier.

Voici une classe KeyPressEater qui dévore les appuis sur les touches du clavier des objets sur lesquels elle est enclenchée :

 class KeyPressEater : public QObject
 {
     Q_OBJECT
     ...
 
 protected:
     bool eventFilter(QObject *obj, QEvent *event);
 };
 
 bool KeyPressEater::eventFilter(QObject *obj, QEvent *event)
 {
     if (event->type() == QEvent::KeyPress) {
         QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
         qDebug("Ate key press %d", keyEvent->key());
         return true;
     } else {
         // processus standard de l'événement 
         return QObject::eventFilter(obj, event);
     }
 }

Et voici la manière de l'installer sur deux widgets :

 KeyPressEater *keyPressEater = new KeyPressEater(this);
 QPushButton *pushButton = new QPushButton(this);
 QListView *listView = new QListView(this);
 
 pushButton->installEventFilter(keyPressEater);
 listView->installEventFilter(keyPressEater);

La classe QShortcut, par exemple, utilise cette technique pour intercepter les appuis sur les touches de raccourci.

Attention : si vous supprimez l'objet receveur dans votre fonction eventFilter(), soyez bien sûr de renvoyer true. Si vous retournez false, Qt enverra l'événement à l'objet supprimé et le programme plantera.

Notez que l'objet filtrant doit être dans le même thread que cet objet. Si filterObj est dans un autre thread, cette fonction ne fait rien. Si filterObj ou cet objet sont déplacés dans un autre thread après l'appel de cette fonction, le filtre d'événements ne sera pas appelé avant que les deux objets aient la même affinité à nouveau (il n'est pas supprimé).

Voir aussi removeEventFilter(), eventFilter() et event().

bool QObject::isWidgetType () const

Retourne true si l'objet est un widget ; sinon retourne false.

Appeler cette fonction revient à appeler inherits("QWidget"), sauf qu'elle est beaucoup plus rapide.

void QObject::killTimer ( int id )

Tue la minuterie avec l'identifiant id.

L'identifiant de minuterie est retourné par startTimer() quand un événement de minuterie est lancé.

Voir aussi timerEvent() et startTimer().

const QMetaObject * QObject::metaObject () const [virtual]

Retourne un pointeur sur le méta-objet de cet objet.

Un méta-objet contient des informations sur une classe qui hérite de QObject, comme le nom de classe, le nom de la superclasse, les propriétés, les signaux et les slots. Tout dérivé de QObject qui contient la macro Q_OBJECT possédera un méta-objet.

Les informations du méta-objet sont requises par le mécanisme de connexion des signaux et slots, ainsi que par le système de propriétés. La fonction inherits() l'utilise aussi.

Si n'avez pas de pointeur sur une instance d'un objet réel mais voulez toujours accéder au méta-objet d'une classe, vous pouvez utiliser staticMetaObject.

Exemple :

 QObject *obj = new QPushButton;
 obj->metaObject()->className();              // retourne "QPushButton"
 
 QPushButton::staticMetaObject.className();   // retourne "QPushButton"

Voir aussi staticMetaObject.

void QObject::moveToThread ( QThread * targetThread )

Change l'affinité du thread pour cet objet et ses enfants. L'objet ne peut pas être bougé s'il a un parent. Le traitement des événements continuera dans le thread targetThread.

Pour déplacer un objet dans le thread principal, utilisez QApplication::instance() pour récupérer un pointeur sur l'application courante et utilisez ensuite QApplication::thread() pour récupérer le thread dans lequel vit l'application. Par exemple :

 myObject->moveToThread(QApplication::instance()->thread());

Si le thread targetThread vaut zéro, tout le traitement des événements pour cet objet et ses enfants s'arrête.

Notez que toutes les minuteries en action pour l'objet seront remises à zéro. Elles sont d'abord arrêtées dans le thread courant puis redémarrées (avec le même intervalle) dans le thread targetThread. Au final, si on déplace sans cesse un objet entre des threads, les minuteries peuvent être postposées indéfiniment.

Un événement QEvent::ThreadChange est envoyé à l'objet juste avant que l'affinité du thread ne change. Vous pouvez manipuler cet événement pour effectuer n'importe quel traitement particulier. Notez que n'importe quel nouvel événement posté sur cet objet sera traité dans le thread targetThread.

Attention : cette fonction n'est pas thread-safe ; le thread actuel doit être le même que l'affinité du thread actuel. En d'autres mots, cette fonction ne peut que « pousser » un objet du thread actuel vers un autre, elle ne peut pas en « tirer » un d'un thread arbitraire à l'actuel.

Voir aussi thread().

QObject * QObject::parent () const

Retourne un pointeur vers l'objet parent.

Voir aussi setParent() et children().

QVariant QObject::property ( const char * name ) const

Retourne la valeur de la propriété ayant pour nom name de l'objet.

S'il n'y a pas de propriété de ce nom, la variable retournée est invalide.

Les informations sur toutes les propriétés disponibles sont données par les fonctions metaObject() et dynamicPropertyNames().

Voir aussi setProperty(), QVariant::isValid(), metaObject() et dynamicPropertyNames().

int QObject::receivers ( const char * signal ) const [protected]

Retourne le nombre de receveurs connectés au signal.

Du fait que les signaux, comme les slots, peuvent être utilisés comme receveurs de signaux et que la même connexion peut être établie plusieurs fois, le nombre de receveurs est le même que le nombre de connections établies avec ce signal.

Quand vous appelez cette fonction, vous pouvez utiliser la macro SIGNAL() pour passer un signal spécifique :

 if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) {
     QByteArray data;
     get_the_value(&data);        // opérations chère en temps de calcul
     emit valueChanged(data);
 }

Comme le code ci-dessus l'illustre, vous pouvez utiliser cette fonction pour éviter d'émettre un signal si rien n'y est connecté.

Attention : cette fonction viole le principe orienté objet de modularité. Cependant, elle peut-être utile quand vous avez besoin de réaliser une initialisation complexe uniquement si quelque chose est connecté à un signal.

void QObject::removeEventFilter ( QObject * obj )

Supprime un objet de filtre événementiel obj de cet objet. La demande est ignorée si un tel filtre événementiel n'a pas été installé.

Tous les filtres événementiels pour cet objet sont automatiquement supprimés quand cet objet est détruit.

Il est toujours sûr de supprimer un filtre événementiel, même pendant son activation (c'est-à-dire depuis la fonction eventFilter()).

Voir aussi installEventFilter(), eventFilter() et event().

QObject * QObject::sender () const [protected]

Retourne un pointeur sur l'objet qui a envoyé le signal, si elle est appelée dans un slot activé par un signal ; retourne 0 sinon. Le pointeur est valide uniquement pendant l'exécution du slot qui appelle cette fonction depuis le contexte du thread de cet objet .

Le pointeur retourné par cette fonction devient invalide si l'objet envoyant le signal est détruit ou si le slot est déconnecté du signal de l'objet envoyant.

Attention : cette fonction viole le principe orienté objet de modularité. Cependant, il peut-être utile d'avoir accès à l'objet envoyant le signal quand beaucoup de signaux sont connectés au même slot.

Attention : comme décrit plus haut, la valeur de retour de cette fonction n'est pas valide quand le slot est appelé via une Qt::DirectConnection depuis un thread différent de celui de cet objet. N'utilisez pas cette fonction dans ce cas de figure.

Voir aussi QSignalMapper.

void QObject::setParent ( QObject * parent )

Fait de l'objet un enfant de parent.

Voir aussi parent() et QWidget::setParent().

bool QObject::setProperty ( const char * name, const QVariant & value )

Fait en sorte que la propriété name de l'objet prenne la valeur value.

Si la propriété est définie dans la classe en utilisant Q_PROPERTY, la fonction retourne true en cas de succès et false en cas d'échec. Si la propriété n'est pas définie par Q_PROPERTY et, par conséquent, n'est pas listée dans le méta-objet, elle est ajoutée en tant que propriété dynamique et la fonction retourne false.

Des informations sur les propriétés disponibles peuvent être obtenues par le metaObject() et la fonction dynamicPropertyNames().

Des propriétés dynamiques peuvent aussi être demandées par le biais de property() et supprimées en leur associant une valeur invalide de QVariant. Changer la valeur d'une propriété dynamique provoque l'envoi d'un événement QDynamicPropertyChangeEvent à l'objet.

Note : les propriétés dynamiques préfixées par « _q_ » sont réservées à des fins internes.

Voir aussi property(), metaObject() et dynamicPropertyNames().

bool QObject::signalsBlocked () const

Retourne true si les signaux sont bloqués ; retourne sinon false.

Les signaux ne sont pas bloqués par défaut.

Voir aussi blockSignals().

int QObject::startTimer ( int interval )

Démarre une minuterie et retourne un identifiant de minuterie ou 0 s'il est impossible d'en démarrer une.

Un événement de minuterie va se produire à chaque intervalle de interval millisecondes jusqu'à ce que killTimer() soit appelée. Si interval vaut 0, alors l'événement de minuterie se produit une fois à chaque fois qu'il n'y a plus d'événements du système de fenêtrage à traiter.

La fonction virtuelle timerEvent() est appelée avec la classe de paramètres d'événements QTimerEvent quand un événement de minuterie se produit. Réimplémentez cette fonction pour récupérer les événements de minuterie.

Si plusieurs minuteries sont en cours d'exécution, la fonction QTimerEvent::timerId() peut être utilisée pour trouver quelle minuterie a été activée.

Exemple :

 class MyObject : public QObject
 {
     Q_OBJECT
 
 public:
     MyObject(QObject *parent = 0);
 
 protected:
     void timerEvent(QTimerEvent *event);
 };
 
 MyObject::MyObject(QObject *parent)
     : QObject(parent)
 {
     startTimer(50);      // minuterie de 50 milliseconde
     startTimer(1000);    // minuterie d'une seconde
     startTimer(60000);   // minuterie d'une minute
 }
 
 void MyObject::timerEvent(QTimerEvent *event)
 {
     qDebug() << "Timer ID:" << event->timerId();
 }

Notez que la précision d'un QTimer dépend du système d'exploitation et du matériel sous-jacent. La plupart des plateformes supportent une précision de 20 millisecondes ; d'autres en permettent une meilleure. Si Qt est incapable de délivrer le nombre demandé d'événements de minuterie, il se débarrassera silencieusement de certains.

La classe QTimer fournit une interface de programmation de haut niveau avec des minuteries à coup unique et des signaux au lieu d'événements. Il y a aussi une classe QBasicTimer, plus légère que QTimer mais moins facilement maniable que les identifiants de minuterie.

Voir aussi timerEvent(), killTimer() et QTimer::singleShot().

QThread * QObject::thread () const

Retourne le thread dans lequel l'objet vit.

Voir aussi moveToThread().

void QObject::timerEvent ( QTimerEvent * event ) [virtual protected]

Ce gestionnaire événementiel peut être réimplémenté dans une sous-classe pour recevoir des événements de minuterie pour l'objet.

QTimer fournit une interface de haut niveau pour des fonctionnalité de minuterie et également des informations plus générales sur les minuteries. L'événement de minuterie est passé dans le paramètre event.

Voir aussi startTimer(), killTimer() et event().

QString QObject::tr ( const char * sourceText, const char * disambiguation = 0, int n = -1 ) [static]

Retourne une version traduite de sourceText, éventuellement basée sur une chaîne de caractères disambiguation et la valeur de n pour les chaînes contenant des pluriels, sinon retourne sourceText si aucune traduction n'est disponible.

Exemple :

 void MainWindow::createMenus()
 {
     fileMenu = menuBar()->addMenu(tr("&File"));
     ...

Si le même sourceText est utilisé dans différents rôles selon le même contexte, un identifiant supplémentaires sous la forme d'une chaîne de caractères peut être passée dans disambiguation (0 par défaut). Dans Qt 4.4 et avant, cela était la meilleure manière de transmettre des commentaires aux traducteurs.

Exemple:

 MyWindow::MyWindow()
 {
     QLabel *senderLabel = new QLabel(tr("Name:"));
     QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
     ...

Voir Écrire son code source pour la traduction pour une description détaillée du mécanisme de traduction de Qt en général et la section Désambiguïsation pour des informations sur l'homonymie.

Attention : cette méthode est réentrante seulement si tous les traducteurs sont installés avant de l'appeler. L'installation ou la suppression de traducteurs tout en effectuant des traductions n'est pas supporté. Agir ainsi pourrait faire planter l'application ou donner d'autres comportements indésirables.

Voir aussi trUtf8(), QApplication::translate(), QTextCodec::setCodecForTr() et Internationalization with Qt.

QString QObject::trUtf8 ( const char * sourceText, const char * disambiguation = 0, int n = -1 ) [static]

Retourne une version traduite de sourceText ou QString::fromUtf8(sourceText) s'il n'y a pas de traduction appropriée. Sinon, elle fonctionne de la même manière que tr(sourceText, disambiguation, n).

Notez que l'utilisation des variantes UTF-8 des fonctions de traduction ne sont pas requises si CODECFORTR est déjà réglé sur UTF-8 dans le fichier de projet qmake et que QTextCodec::setCodecForTr(« UTF-8 ») est utilisé.

Attention : cette méthode n'est réentrante que si tous les traducteurs sont installés avant son appel. Installer ou enlever des traducteurs pendant la traduction n'est pas supporté. Agir ainsi pourrait donner un crash ou d'autres comportements indésirables.

Attention : pour des raisons de portabilité, nous recommandons l'échappement des séquences de caractères non ASCII dans les chaînes littérales passées à trUtf8(). Par exemple :

 label->setText(tr("F\374r \310lise"));

Voir aussi tr(), QApplication::translate() et L'internationalisation avec Qt.

Documentation de la variable membre

const QMetaObject QObject::staticMetaObject

Cette variable stocke le méta-objet de cette classe.

Un méta-objet contient des informations sur une classe qui hérite deQObject, par exemple le nom de la classe, le nom de la super-classe, les propriétés, les signaux et les slots. Chaque classe qui contient la macro Q_OBJECT possédera également un méta-objet.

Les informations du méta-objet sont nécessaires au mécanisme de connexion signal/slot et au système de propriétés. La fonction [qobject#inherits|inherits()]] se sert également des méta-objets.

Si vous avez un pointeur sur un objet, vous pouvez utiliser la fonction metaObject() pour récupérer le méta-objet associé à cet objet.

Exemple :

 QPushButton::staticMetaObject.className();   
 
QObject *obj = new QPushButton;
obj->metaObject()->className();

Voir aussi metaObject().

En relation mais non membres de la classe

typedef QObjectList

Synonyme de QList<QObject *>.

T qFindChild ( const QObject * obj, const QString & name )

Cette fonction est équivalente à obj->findChild<T>(name). Elle est fournie comme contournement d'un problème de MSVC6 : il ne supporte pas les fonctions template membres.

Voir aussi QObject::findChild().

QList<T> qFindChildren ( const QObject * obj, const QString & name )

Cette fonction est équivalente à obj->findChildren<T>(name). Elle est fournie comme contournement d'un problème de MSVC6 : il ne supporte pas les fonctions template membres.

Voir aussi QObject::findChildren().

QList<T> qFindChildren ( const QObject * obj, const QRegExp & regExp )

Cette fonction surchage qFindChildren().

Cette fonction est équivalente à obj->findChildren<T>(regExp). Elle est fournie comme contournement d'un problème de MSVC6 : il ne supporte pas les fonctions template membres.

T qobject_cast ( QObject * object )

Retourne l'objet object donné casté dans le type T si l'objet est du type T (ou d'une sous-classe); sinon retourne 0. Si object vaut 0 alors elle retournera 0 également.

La classe T doit hériter (directement ou indirectement) de QObject et être déclarée avec la macro Q_OBJECT.

On considère qu'une classe hérite d'elle-même.

Exemple:

 QObject *obj = new QTimer;           // QTime hérite de QObject
 
 QTimer *timer = qobject_cast<QTimer *>(obj);
 // timer == (QObject *)obj
 
 QAbstractButton *button = qobject_cast<QAbstractButton *>(obj);
 // button == 0

La fonction qobject_cast() se comporte de façon semblable à la fonction standard en C++ dynamic_cast(), avec pour avantages le fait qu'elle ne nécessite pas un support du RTTI et qu'elle fonctionne au-delà des frontières dynamiques de la bibliothèque.

qobject_cast() peut également être utilisé conjointement avec des interfaces ; voir l'exemple Plug & Paint pour plus de détails.

Attention : Si T n'est pas déclaré avec la macro Q_OBJECT, la valeur de retour de cette fonction est indéfinie.

Voir aussi QObject::inherits().

Documentation des macros

Q_CLASSINFO ( Name, Value )

Cette macro associe des informations supplémentaires à la classe, disponibles avec QObject::metaObject(). À l'exception de l'extension ActiveQt, Qt n'utilise pas ces informations.

Ces informations supplémentaires prennent la forme d'une chaîne de caractères Name et d'une chaîne de caractères littérale Value.

Exemple :

 class MyClass : public QObject
 {
     Q_OBJECT
     Q_CLASSINFO("Author", "Pierre Gendron")
     Q_CLASSINFO("URL", "http://www.my-organization.qc.ca")
 
 public:
     ...
 };

Voir aussi QMetaObject::classInfo().

Q_DISABLE_COPY ( Class )

Désactive l'utilisation des constructeurs de copie et des opérateurs d'assignation pour la classe Class.

Les instances des dérivés de QObject ne devraient pas être vues comme des valeurs qui peuvent être copiées ou assignées mais bien comme des identités uniques. Ceci signifie que, quand vous créez vos dérivés de QObject (directement ou non), vous ne devriez pas lui donner un constructeur par copie ou un opérateur d'assignation. Cependant, il devrait être suffisant de simplement les omettre de votre classe parce que, si vous écrivez par erreur du code qui requiert un constructeur par copie ou un opérateur d'assignation (c'est facile à faire), votre compilateur va, plein de bonnes intentions, en créer un pour vous. Vous devez en faire plus.

L'utilisateur curieux va remarquer que les classes de Qt dérivant de QObject incluent d'habitude cette macro dans une section privée :

 class MyClass : public QObject
 {
 
   private:
     Q_DISABLE_COPY(MyClass)
 };

Elle déclare un constructeur par copie et un opérateur d'assignation dans la section privée : si vous les utilisez par erreur, le compilateur va vous renvoyer une erreur.

 class MyClass : public QObject
 {
 
   private:
      MyClass(const MyClass &);
      MyClass &operator=(const MyClass &);
 };

Cependant, ceci ne peut pas résoudre tous les cas. Vous pourriez être tenté d'écrire quelque chose du genre :

   QWidget w = QWidget();

Tout d'abord, ne le faites pas. La majorité des compilateurs va générer du code qui utilise le constructeur par copie et l'erreur de violation de private va être lancée mais votre compilateur C++ n'est pas obligé de générer du code pour cette ligne d'une manière spécifique. Il pourrait générer du code qui n'utilise ni le constructeur par copie, ni l'opérateur d'assignation que nous avons rendu privé. Dans ce cas, aucune erreur ne sera rapportée mais votre application plantera probablement quand vous appellerez une fonction membre de w.

Q_EMIT

Utilisez cette macro pour remplacer le mot-clé emit pour émettre des signaux quand vous souhaitez utiliser les signaux et slots de Qt avec un mécanisme tiers de signaux et slots.

Cette macro est normalement utilisée quand no_keywords est spécifié dans la variable CONFIG du fichier .pro mais elle peut être aussi utilisée quand no_keywords n'est pas spécifiée.

Q_ENUMS ( ... )

Cette macro enregistre un ou plusieurs types d'énumérations dans le système de méta-objets.

Par exemple :

 class MyClass : public QObject
 {
     Q_OBJECT
     Q_ENUMS(Priority)
 
 public:
     MyClass(QObject *parent = 0);
     ~MyClass();
 
     enum Priority { High, Low, VeryHigh, VeryLow };
     void setPriority(Priority priority);
     Priority priority() const;
 };

Si vous voulez enregistrer une énumération déclarée dans une autre classe, l'énumération doit être pleinement qualifiée avec le nom de la classe la définissant. En plus, la classe définissant l'énumération doit hériter de QObject et déclarer l'énumération avec Q_ENUMS().

Voir aussi Le système de propriétés de Qt.

Q_FLAGS ( ... )

Cette macro enregistre un ou plusieurs types de drapeaux (//flag//) dans le système de méta-objets. Elle est d'habitude utilisée dans la définition d'une classe pour déclarer quelles valeurs d'une énumération donnée peuvent être utilisées comme drapeaux et combinées avec l'opérateur OU.

Par exemple, dans QLibrary, le drapeau LoadHints est déclaré de cette manière :

 class QLibrary : public QObject
 {
     ...
     Q_FLAGS(LoadHint LoadHints)
     ...

La déclaration des drapeaux eux-mêmes est effectuée dans la section publique de la classe QLibrary, avec la macro Q_DECLARE_FLAGS() :

     ...
 public:
     enum LoadHint {
         ResolveAllSymbolsHint = 0x01,
         ExportExternalSymbolsHint = 0x02,
         LoadArchiveMemberHint = 0x04
     };
     Q_DECLARE_FLAGS(LoadHints, LoadHint)
     ...

Note : cette macro prend soin d'enregistrer des valeurs de drapeaux individuelles dans le système de méta-objets, il n'est donc pas utile d'utiliser Q_ENUMS() en plus de cette macro.

Voir aussi Le système de propriétés de Qt.

Q_INTERFACES ( ... )

Cette macro dit à Qt quelles interfaces la classe implémente. Ceci est utilisé lors de l'implémentation de plug-ins.

Exemple :

 class BasicToolsPlugin : public QObject,
                          public BrushInterface,
                          public ShapeInterface,
                          public FilterInterface
 {
     Q_OBJECT
     Q_INTERFACES(BrushInterface ShapeInterface FilterInterface)
 
 public:
     ...
 };

Voir l'exemple Plug & Paint Basic Tools pour plus de détails.

Voir aussi Q_DECLARE_INTERFACE(), Q_EXPORT_PLUGIN2() et Comment créer des plug-ins Qt.

Q_INVOKABLE

Appliquez cette macro aux définitions des fonctions membres pour qu'elles soient invocables par le système de méta-objets. La macro est écrite avant le type de retour, comme dans l'exemple suivant :

 class Window : public QWidget
 {
     Q_OBJECT
 
 public:
     Window();
     void normalMethod();
     Q_INVOKABLE void invokableMethod();
 };

La fonction invokableMethod() est marquée en utilisant Q_INVOKABLE, ce qui fait qu'elle est enregistrée dans le système de méta-objets et qu'elle est invocable par QMetaObject::invokeMethod(). Puisque la fonction normalMethod() n'est pas enregistrée de cette manière, elle n'est pas invocable par QMetaObject::invokeMethod().

Q_OBJECT

La macro Q_OBJECT doit apparaître dans la section privée de la définition d'une classe qui déclare ses propres signaux et slots et/ou qui utilise d'autres services fournis par le système de méta-objets de Qt.

Par exemple :

 #include <QObject>
 
 class Counter : public QObject
 {
     Q_OBJECT
 
 public:
     Counter() { m_value = 0; }
 
     int value() const { return m_value; }
 
 public slots:
     void setValeur(int value);
 
 signals:
     void valueChanged(int newValeur);
 
 private:
     int m_value;
 };

Note : cette macro requiert que la classe soit un dérivé de QObject. Utilisez Q_GADGET au lieu deQ_OBJECT pour activer le support du système de méta-objets pour les énumérations dans une classe qui ne dérive pas de QObject. Q_GADGET rend un membre de la classe disponible, staticMetaObject, du type QMetaObject et qui fournit un accès aux énumérations déclarées avec Q_ENUMS. Q_GADGET n'est disponible que pour le C++.

Voir aussi Le système de méta-objet, Les signaux et les slots et Le système de propriétés de Qt.

Q_PROPERTY ( ... )

Cette macro est utilisée pour déclarer des propriétés dans les classes qui héritent de QObject. Les propriétés se comportent comme des données membres de la classe, à l'exception du fait qu'elles possèdent des fonctionnalités additionnelles grâce au système de méta-objets.

 Q_PROPERTY(type name
            READ getFunction
            [WRITE setFunction]
            [RESET resetFunction]
            [NOTIFY notifySignal]
            [DESIGNABLE bool]
            [SCRIPTABLE bool]
            [STORED bool]
            [USER bool]
            [CONSTANT]
            [FINAL])

Le nom de la propriété et son type et la fonction READ sont requis. Le type peut être n'importe quel type supporté par QVariant ou un type défini par l'utilisateur. Les autres options sont optionnelles, même si une fonction WRITE est habituellement déclarée. Les attributs sont définis par défaut à true, à l'exception de USER à false.

Par exemple :

 Q_PROPERTY(QString title READ title WRITE setTitle USER true)

Pour plus de détails sur la manière d'utiliser cette macro et un exemple plus détaillé de son utilisation, regardez le système de propriétés de Qt.

Voir aussi Le système de propriétés de Qt.

Q_SIGNAL

C'est une macro additionnelle qui vous permet de marquer une seule fonction comme un slot. Elle peut être assez utile, spécialement quand vous utilisez un parseur de code source tiers qui ne comprend pas les groupes signals ou Q_SIGNALS.

Utilisez cette macro pour remplacer le mot-clé signal dans les déclarations de classes quand vous souhaitez utiliser les signaux et slots de Qt avec un mécanisme tiers de signaux et slots.

Cette macro est normalement utilisée quand no_keywords est spécifié dans la variable CONFIG du fichier .pro mais elle peut être aussi utilisée quand no_keywords n'est pas spécifiée.

Q_SIGNALS

Utilisez cette macro pour remplacer le mot-clé signals dans les déclarations de classes quand vous souhaitez utiliser les signaux et slots de Qt avec un mécanisme tiers de signaux et slots.

Cette macro est normalement utilisée quand no_keywords est spécifié dans la variable CONFIG du fichier .pro mais elle peut être aussi utilisée quand no_keywords n'est pas spécifiée.

Q_SLOT

C'est une macro additionnelle qui vous permet de marquer une seule fonction comme un slot. Elle peut être assez utile, spécialement quand vous utilisez un parseur de code source tiers qui ne comprend pas les groupes slots ou Q_SLOTS.

Utilisez cette macro pour remplacer le mot-clé slot dans les déclarations de classes quand vous souhaitez utiliser les signaux et slots de Qt avec un mécanisme tiers de signaux et slots.

Cette macro est normalement utilisée quand no_keywords est spécifié dans la variable CONFIG du fichier .pro mais elle peut être aussi utilisée quand no_keywords n'est pas spécifiée.

Q_SLOTS

Utilisez cette macro pour remplacer le mot-clé slots dans les déclarations de classes quand vous souhaitez utiliser les signaux et slots de Qt avec un mécanisme tiers de signaux et slots.

Cette macro est normalement utilisée quand no_keywords est spécifié dans la variable CONFIG du fichier .pro mais elle peut être aussi utilisée quand no_keywords n'est pas spécifiée.

Remerciements

Merci à Abdelhafid Hafidi et Nicolas Carion pour la traduction, à Thibaut Cuvelier pour la traduction et la relecture ainsi qu'à Jonathan Courtois et Jacques Thery pour la relecture !