QDockWidget

La classe QDockWidget fournit un widget qui peut être parqué (docked) à l'intérieur d'une QMainWindow ou flotter en tant que fenêtre de premier niveau sur le bureau. Plus d'informations...

#include <QDockWidget>

Voir la position dans l'arbre des classes.

Héritage

Hérite de QWidget.

Description détaillée

La classe QDockWidget fournit un widget qui peut être parqué (docked) à l'intérieur d'une QMainWindow ou flotter en tant que fenêtre de premier niveau sur le bureau.

QDockWidget fournit le concept de widgets de dock, aussi connu sous le nom de palettes d'outils ou fenêtres utilitaires. Les docks sont des fenêtres secondaires placées dans la zone de widget de dock située autour du widget central d'une QMainWindow.

Les docks peuvent être déplacés à l'intérieur de leur zone actuelle, déplacés dans de nouvelles zones ou rendus flottants (c'est-à-dire détachés) par l'utilisateur final. L'API de QDockWidget permet au programmeur de restreindre la capacité du widget de dock de se déplacer, d'être détaché et de se fermer, aussi bien que de restreindre les zones dans lesquelles ils peuvent être placés.

Apparence

Un QDockWidget consiste en une barre de titre et une zone de contenu. La barre de titre affiche le titre de fenêtre du widget de dock, un bouton de détachement et un bouton de fermeture. Selon l'état du QDockWidget, les boutons de détachement et de fermeture peuvent être désactivés ou complètement invisibles.

L'apparence visuelle de la barre de titre et des boutons dépend du style utilisé.

Un QDockWidget agit en tant qu'entourage pour son widget enfant, défini avec setWidget(). Les indications de taille, les tailles maximales et minimales ainsi que la politique de taille doivent être implémentées sur le widget enfant. QDockWidget les respectera, ajustant ses propres contraintes pour inclure le cadre et le titre. Les contraintes de taille ne doivent pas être définies sur le QDockWidget lui-même puisqu'elles changent suivant qu'il soit parqué ou non, sachant qu'un QDockWidget parqué n'a pas de cadre et possède une barre de titre plus petite.

Voir aussi QMainWindow et les exemples de widgets de dock.

Type

enum QDockWidget::DockWidgetFeatureflags QDockWidget::DockWidgetFeatures

Le type DockWidgetFeatures est un typedef de QFlags<DockWidgetFeature>. Il stocke des combinaisons OU des valeurs de DockWidgetFeature.

Propriétés

allowedAreas : Qt::DockWidgetAreas

Cette propriété définit les zones dans lesquelles le widget de dock peut être placé.

La valeur par défaut est Qt::AllDockWidgetAreas.

Fonctions d'accès

Qt::DockWidgetAreas allowedAreas () const

void setAllowedAreas ( Qt::DockWidgetAreas areas )

Signal de notification :

void allowedAreasChanged ( Qt::DockWidgetAreas allowedAreas )

Voir aussi Qt::DockWidgetArea.

features : DockWidgetFeatures

Cette propriété définit si le widget de dock peut être déplacé, fermé et détaché.

Par défaut, cette propriété est égale à la combinaison de DockWidgetClosable, DockWidgetMovable et DockWidgetFloatable.

Fonctions d'accès

DockWidgetFeatures features () const

void setFeatures ( DockWidgetFeatures features )

Signal de notification :

void featuresChanged ( QDockWidget::DockWidgetFeatures features )

Voir aussi DockWidgetFeature.

floating : bool

Cette propriété définit si le widget de dock est détaché.

Un widget de dock détaché est présenté à l'utilisateur en tant que fenêtre indépendante « au-dessus » de sa QMainWindow mère, à la place d'être parqué à l'intérieur.

Par défaut, cette propriété est à true.

Fonctions d'accès

bool isFloating () const

void setFloating ( bool floating )

Voir aussi isWindow().

windowTitle : QString

Cette propriété définit le titre (légende) du widget de dock.

Par défaut, cette propriété contient une chaine vide.

Fonctions d'accès

QString windowTitle () const

void setWindowTitle ( const QString & )

Fonctions membres

QDockWidget::QDockWidget ( const QString & title, QWidget * parent = 0, Qt::WindowFlags flags = 0 )

Construit un QDockWidget avec le parent parent et les drapeaux de fenêtre flags. Le widget de dock sera placé dans la zone de widget de dock de gauche.

Le titre de la fenêtre est défini à title. Ce titre est utilisé lorsque le QDockWidget est parqué et lorsqu'il est détaché. Il est aussi utilisé dans le menu contextuel fourni par QMainWindow.

Voir aussi setWindowTitle().

QDockWidget::QDockWidget ( QWidget * parent = 0, Qt::WindowFlags flags = 0 )

Construit un QDockWidget avec le parent parent et les drapeaux de fenêtre flags. Le widget de dock sera placé dans la zone de widget de dock de gauche.

QDockWidget::~QDockWidget ()

Détruit le widget de dock.

void QDockWidget::allowedAreasChanged ( Qt::DockWidgetAreas allowedAreas ) [signal]

Ce signal est émis lorsque la propriété allowedAreas est modifiée. Le paramètre allowedAreas fournit la nouvelle valeur de la propriété.

void QDockWidget::changeEvent ( QEvent * event ) [virtual protected]

Réimplémentation de QWidget::changeEvent().

void QDockWidget::closeEvent ( QCloseEvent * event ) [virtual protected]

Réimplémentation de QWidget::closeEvent().

void QDockWidget::dockLocationChanged ( Qt::DockWidgetArea area ) [signal]

Ce signal est émis quand le widget de dock est déplacé dans une autre zone de dock ou déplacé dans un autre emplacement de sa zone de dock actuelle. Cela se produit lorsque le widget de dock est déplacé par programmation ou glissé dans un nouvel emplacement par l'utilisateur.

Cette fonction a été introduite dans Qt 4.3.

bool QDockWidget::event ( QEvent * event ) [virtual protected]

Réimplémentation de QObject::event().

void QDockWidget::featuresChanged ( QDockWidget::DockWidgetFeatures features ) [signal]

Ce signal est émis quand la propriété features est modifiée. Le paramètre features fournit la nouvelle valeur de la propriété.

void QDockWidget::initStyleOption ( QStyleOptionDockWidget * option ) const [protected]

Initialise option avec les valeurs provenant de ce QDockWidget. Cette méthode est pratique pour les sous-classes lorsque celles-ci ont besoin d'un QStyleOptionDockWidget mais ne souhaitent pas remplir toutes les informations elles-mêmes.

Voir aussi QStyleOption::initFrom().

bool QDockWidget::isAreaAllowed ( Qt::DockWidgetArea area ) const

Retourne true si ce widget de dock peut être placé dans la zone area donnée ; sinon retourne false.

void QDockWidget::paintEvent ( QPaintEvent * event ) [virtual protected]

Réimplémentation de QWidget::paintEvent().

void QDockWidget::setTitleBarWidget ( QWidget * widget )

Définit un widget arbitraire en tant que barre de titre du widget de dock. Si le widget est 0, tout widget de barre de titre défini précédemment sur le widget de dock est retiré mais pas détruit et la barre de titre par défaut est utilisée à la place.

Si un widget de barre de titre est défini, QDockWidget n'utilisera pas les décorations de fenêtre natives quand il sera détaché.

Voici quelques conseils pour l'implémentation de barres de titre personnalisées :

• les événements de souris qui ne sont pas explicitement gérés par le widget de barre de titre doivent être ignorés en appelant QMouseEvent::ignore(). Ces événements se propagent alors au QDockWidget parent qui les gère de la manière habituelle, se déplaçant lorsque la barre de titre est glissée, se parquant et se détachant lorsqu'on double-clique dessus, etc. ;
• lorsque DockWidgetVerticalTitleBar est défini sur le QDockWidget, la barre de titre est repositionnée en conséquence. Dans resizeEvent(), la barre de titre doit vérifier l'orientation qu'elle doit prendre :

 QDockWidget *dockWidget = qobject_cast<QDockWidget*>(parentWidget());
 if (dockWidget->features() & QDockWidget::DockWidgetVerticalTitleBar) {
     // je dois m'orienter verticalement
 } else {
     // je dois m'orienter horizontalement
 }

• la barre de titre doit avoir une QWidget::sizeHint() et une QWidget::minimumSizeHint() valides. Ces fonctions doivent tenir compte de l'orientation actuelle de la barre de titre ;
• il n'est pas possible de retirer une barre de titre d'un widget de dock. Cependant, un effet similaire peut être réalisé en définissant un QWidget construit par défaut en tant que widget de barre de titre.

Par l'utilisation de qobject_cast() tel que montré ci-dessus, la barre de titre a un accès complet à son QDockWidget parent. De ce fait il peut effectuer des opérations telles que se parquer et se cacher en réponse aux actions de l'utilisateur.

Cette fonction a été introduite dans Qt 4.3.

Voir aussi titleBarWidget() et DockWidgetVerticalTitleBar.

void QDockWidget::setWidget ( QWidget * widget )

Définit le widget du widget de dock à widget;

Si le widget de dock est visible lorsque widget est ajouté, il est nécessaire de l'afficher explicitement avec show().

Notez que l'on doit ajouter le layout du widget avant d'appeler cette fonction ; dans le cas contraire, le widget ne sera pas visible.

Voir aussi widget().

QWidget * QDockWidget::titleBarWidget () const

Retourne le widget de barre de titre personnalisée défini sur le QDockWidget ou 0 si aucune barre de titre personnalisée n'a été définie.

Cette fonction a été introduite dans Qt 4.3.

Voir aussi setTitleBarWidget().

QAction * QDockWidget::toggleViewAction () const

Retourne une action cochable qui peut être utilisée pour afficher ou masquer ce widget de dock.

Le texte de l'action est le titre de la fenêtre du widget de dock.

Voir aussi QAction::text et QWidget::windowTitle.

void QDockWidget::topLevelChanged ( bool topLevel ) [signal]

Ce signal lorsque la propriété floating est modifiée. Le paramètre topLevel est à true si le widget de dock est dès lors en train de flotter ; sinon à false.

Voir aussi isWindow().

void QDockWidget::visibilityChanged ( bool visible ) [signal]

Ce signal est émis lorsque le widget de dock devient visible (ou invisible). Cela se produit lorsque le widget est masqué ou affiché, ainsi que lorsqu'il est parqué dans une zone de dock à onglets et que son onglet devient sélectionné ou désélectionné.

Cette fonction a été introduite dans Qt 4.3.

QWidget * QDockWidget::widget () const

Retourne le widget du widget de dock. Cette fonction retourne zéro si le widget n'a pas été défini.

Voir aussi setWidget().

Remerciements

Merci à Louis du Verdier pour la traduction et Ilya Diallo, Dimitry Ernot ainsi que Claude Leloup pour leur relecture !