QPushButton

Le widget QPushButton fournit un bouton de commande. Plus d'informations...

#include <QPushButton>

Voir la position dans l'arbre des classes.

Héritage

Hérite de QAbstractButton.

Hérité par QCommandLinkButton.

Description détaillée

Le widget QPushButton fournit un bouton de commande.

Le bouton, ou bouton de commande, est peut-être le widget le plus communément utilisé dans toute interface graphique : appuyer sur un bouton pour ordonner à l'ordinateur d'effectuer une action ou pour répondre à une question. Les boutons typiques sont OK, Appliquer, Annuler, Fermer, Oui, Non et Aide.

Un bouton de commande est de forme rectangulaire et affiche en général un texte décrivant son action. Un raccourci peut être spécifié en précédant le caractère privilégié avec une esperluette (&). Par exemple :

QPushButton *button = new QPushButton("&Télécharger", this);

Dans cet exemple, le raccourci est Alt+T. Voir la documentation de QShortcut pour plus de détails (pour afficher une esperluette existante, utilisez '&&').

Les boutons affichent un libellé textuel et optionnellement une petite icône. Ils peuvent être définis par l'utilisation des constructeurs et modifiés par la suite par l'utilisation de setText() et setIcon(). Si le bouton est désactivé, l'apparence du texte et de l'icône sera manipulée en conformité avec le style de d'interface graphique, de manière à donner une apparence « désactivée » au bouton.

Un bouton émet le signal clicked() quand il est activé par la souris, la barre d'espace ou par un raccourci de clavier. Connectez ce signal pour effectuer l'action du bouton. Les boutons fournissent aussi des signaux moins communément utilisés, par exemple, pressed() et released().

Les boutons de commande dans les boîtes de dialogue sont par défaut des boutons automatiques, c'est-à-dire qu'ils deviennent boutons par défaut automatiquement quand ils reçoivent le focus de l'entrée du clavier. Un bouton par défaut est un bouton qui est activé quand l'utilisateur appuie sur les touches Entrée ou Retour dans une boîte de dialogue. Vous pouvez changer cela avec setAutoDefault. Notez que les boutons automatiques par défaut réservent un petit peu plus d'espace nécessaire pour dessiner un indicateur de bouton par défaut. Si vous ne voulez pas de cet espace autour de votre bouton, appelez setAutoDefault(false).

Devenant très central, le widget bouton a été amélioré pour accueillir un grand nombre de variations au cours de la dernière décennie. Le guide du style Microsoft montre actuellement une dizaine d'états différents de boutons sous Windows et le texte implique qu'il y en ait des douzaines d'autres quand toutes les combinaisons de caractéristiques sont prises en considération.

Les modes ou états les plus importants sont :

• disponible ou non (grisé et désactivé) ;
• bouton standard, bouton réversible ou bouton de menu ;
• zctivé ou désactivé (uniquement pour les boutons réversibles) ;
• par défaut ou normal : le bouton par défaut d'une boîte de dialogue peut généralement être activé par l'utilisation des touches Entrée ou Retour ;
• répétitif automatiquement ou non ;
• enfoncé ou non.

En règle générale, utilisez un bouton d'action quand la situation le requiert : par exemple avec une boîte de dialogue lors d'un clic sur des boutons Appliquer, Annuler, Fermer et Aide). Le widget est alors représenté par un pavé rectangulaire avec un texte à l'intérieur. À l'inverse, les petits boutons, de forme carrée, sont destinés à un changement d'état de la fenêtre plutôt qu'à une action sur celle-ci (par exemple, les boutons situés dans le coin en haut à droite du QFileDialog, des boutons d'outils et non de commande) : Qt dispose dans ce cas de la classe spécifique QToolButton.

Si vous avez besoin d'un comportement réversible (voir setCheckable()) ou d'un bouton répétant automatiquement le signal d'activation lorsqu'il est enfoncé comme la flèche d'une barre de défilement (voir setAutoRepeat()), un bouton de commande n'est probablement pas ce que vous voulez. Dans le doute, utilisez un bouton d'outils.

Une variante du bouton de commande est le bouton de menu. Les boutons de menu ne fournissent pas uniquement une commande, mais plusieurs. Dès qu'ils sont appuyés, ils font surgir un menu d'options. Utilisez la méthode setMenu() pour associer un menu contextuel à un bouton.

D'autres classes de boutons sont les boutons d'options (voir QRadioButton) et les cases à cocher (voir QCheckBox).

	Un bouton affiché sous le style de widget Macintosh. Notez que lorsque la longueur devient inférieure à 50 ou que sa largeur devient inférieure à 30, les coins du bouton passent de la forme ronde à la forme carrée. Utilisez la fonction setMinimumSize() pour éviter ce comportement.
	Un bouton affiché sous le style de widget Windows XP.
	Un bouton affiché sous le style de widget Plastique.

Dans Qt, la classe de base QAbstractButton fournit la plupart des modes et d'autres API, et QPushButton fournit la logique des GUI. Voir QAbstractButton pour plus d'informations à propos de l'API.

Voir aussi QToolButton, QRadioButton, QCheckBox et Le manuel du design de GUI : Boutons.

Propriétés

autoDefault : bool

Cette propriété contrôle si le bouton est un bouton automatique par défaut.

Si cette propriété est définie à true, alors le bouton est un bouton automatique par défaut.

Dans certains styles de GUI, un bouton par défaut est dessiné avec un cadre supplémentaire l'entourant, jusqu'à 3 pixels ou plus. Qt garde automatiquement cet espace libre autour des boutons automatiques par défaut, c'est-à-dire que ces derniers peuvent avoir des dimensions conseillées légèrement plus grandes.

Cette propriété est par défaut true pour les boutons qui détiennent un parent de QDialog ; sinon par défaut false.

Voir la propriété default pour plus de détails sur la manière de définir par défaut et d'auto-interagir par défaut.

Fonctions d'accès

bool autoDefault () const
void setAutoDefault ( bool )

default : bool

Cette propriété contrôle si le bouton est le bouton par défaut.

Les boutons par défaut et les boutons automatiquement par défaut prennent la décision de ce qui ce passe quand l'utilisateur appuie sur Entrée dans une boîte de dialogue.

Un bouton avec cette propriété définie comme true (c'est-à-dire le bouton par défaut de la boîte de dialogue) sera automatiquement enfoncé quand l'utilisateur pressera la touche Entrée, avec une exception : si un bouton automatiquement par défaut détient actuellement le focus, ce bouton est pressé. Quand la boîte de dialogue possède un bouton automatiquement par défaut mais pas de bouton par défaut, l'appui sur Entrée va presser soit le bouton automatiquement par défaut qui détient actuellement le focus, soit s'il n'y a pas de bouton ayant le focus, le bouton automatiquement par défaut suivant dans l'ordre de focus.

Dans la boîte de dialogue, seulement un bouton à la fois peut être le bouton par défaut. Ce bouton est alors affiché avec un cadre additionnel (dépendant du style de GUI).

Le comportement par défaut du bouton est fourni uniquement dans les boîtes de dialogue. Le bouton qui a le focus peut toujours être cliqué depuis le clavier par une pression sur la barre d'espace.

Si la propriété par défaut est définie à false dans l'actuel bouton par défaut quand la boîte de dialogue est visible, un nouveau paramètre par défaut sera automatiquement assigné la prochaine fois qu'un bouton de la boîte de dialogue recevra le focus.

Cette propriété est par défaut false.

Fonctions d'accès

bool isDefault () const
void setDefault ( bool )

flat : bool

Cette propriété contrôle si la bordure du bouton est relevée.

Cette propriété est par défaut false. Si la propriété est définie, la plupart des styles ne va pas peindre l'arrière-plan à moins que le bouton soit en train d'être pressé. setAutoFillBackground() peut être utilisé pour faire en sorte que l'arrière-plan soit rempli en utilisant le pinceau QPalette::Button.

Fonctions d'accès

bool isFlat () const
void setFlat ( bool )

Fonctions membres

QPushButton::QPushButton ( QWidget * parent = 0 )

Construit un bouton sans texte et un parent.

QPushButton::QPushButton ( const QString & texte, QWidget * parent = 0 )

Construit un bouton avec le parent parent et le texte texte.

QPushButton::QPushButton ( const QIcon & icone, const QString & texte, QWidget * parent = 0 )

Construit un bouton avec une icone, un texte et un parent.

Notez que vous pouvez aussi passer un objet QPixmap en tant qu'icône (merci à l'implicite conversion fournie par le C++).

QPushButton::~QPushButton ()

Détruit le bouton.

bool QPushButton::event ( QEvent * e ) [virtual protected]

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

void QPushButton::focusInEvent ( QFocusEvent * e ) [virtual protected]

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

void QPushButton::focusOutEvent ( QFocusEvent * e ) [virtual protected]

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

bool QPushButton::hitButton ( const QPoint & pos ) const [virtual protected]

Réimplémentation de QAbstractButton::hitButton().

void QPushButton::initStyleOption ( QStyleOptionButton * option ) const [protected]

Initialise option avec les valeurs de ce QPushButton. Cette méthode est pratique pour les sous-classes quand elles nécessitent un QStyleOptionButton, mais ne veulent pas fournir toutes les informations elles-mêmes.

void QPushButton::keyPressEvent ( QKeyEvent * e ) [virtual protected]

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

QMenu * QPushButton::menu () const

Retourne le menu surgissant associé au bouton ou 0 s'il n'y a pas de menu surgissant ayant été défini.

Voir aussi setMenu().

QSize QPushButton::minimumSizeHint () const [virtual]

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

void QPushButton::paintEvent ( QPaintEvent * ) [virtual protected]

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

void QPushButton::setMenu ( QMenu * menu )

Associe le menu surgissant menu avec ce bouton. Cela transforme le bouton en bouton-menu qui, dans certains styles, va produire un petit triangle à droite du texte du bouton.

Le propriétaire du menu n'est pas transféré au bouton.

Boutons avec menu surgissant affichés dans le style de widget Plastique (gauche) et dans le style de widget Cleanlooks (droite).

void QPushButton::showMenu () [slot]

Affiche (fait surgir) le menu surgissant associé. S'il n'y a pas un tel menu, cette fonction ne fait rien. Cette fonction ne retourne rien jusqu'à ce que le menu ait été fermé par l'utilisateur.

QSize QPushButton::sizeHint () const [virtual]

Réimplémentation dation QWidget::sizeHint().

Remerciements

Merci à Louis du Verdier pour la traduction et à Thibaut Cuvelier, Jonathan Courtois, Jacques Thery, Philippe Beaucart et à Wachter pour leur relecture et débat !