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 !