Exemple de curseurs

Qt propose trois types de widgets de type curseur : QSlider, QScrollBar et QDial. Ils héritent tous la plupart de leurs fonctionnalités de QAbstractSlider et peuvent en théorie se substituer les uns aux autres dans une application, car les différences ne concernent que leur apparence et leur comportement. Cet exemple montre à quoi ils ressemblent, comment ils fonctionnent et comment leur comportement et leur apparence peuvent être modifiés à l'aide de leurs propriétés.

L'exemple montre également comment les signaux et les slots peuvent être utilisés pour synchroniser le comportement de deux ou plusieurs widgets, et comment redéfinir la méthode ` resizeEvent()` pour mettre en place une mise en page adaptative.

Capture d'écran de l'exemple « Sliders »

L’exemple « Sliders » se compose de deux classes :

• SlidersGroup est un widget personnalisé. Il combine un ` QSlider`, un ` QScrollBar ` et un ` QDial`.
• Window est le widget principal combinant un QGroupBox et un SlidersGroup. Le QGroupBox contient plusieurs widgets qui contrôlent le comportement des widgets de type curseur.

Nous allons d'abord passer en revue la classe ` Window `, puis nous examinerons la classe ` SlidersGroup `.

Définition de la classe Window

class Window : public QWidget
{
    Q_OBJECT

public:
    Window(QWidget *parent = nullptr);

private:
    void createControls(const QString &title);
    void resizeEvent(QResizeEvent *e);

    SlidersGroup *slidersGroup;

    QGroupBox *controlsGroup;
    QLabel *minimumLabel;
    QLabel *maximumLabel;
    QLabel *valueLabel;
    QCheckBox *invertedAppearance;
    QCheckBox *invertedKeyBindings;
    QSpinBox *minimumSpinBox;
    QSpinBox *maximumSpinBox;
    QSpinBox *valueSpinBox;
    QBoxLayout *layout;
};

La classe ` Window ` hérite de la classe ` QWidget`. Elle affiche les widgets de type curseur et permet à l’utilisateur de définir leurs valeurs minimale, maximale et actuelle, ainsi que de personnaliser leur apparence, leurs raccourcis clavier et leur orientation. Nous utilisons une fonction privée ` createControls() ` pour créer les widgets qui fournissent ces mécanismes de contrôle et pour les relier aux widgets de type curseur.

Implémentation de la classe `Window`

Window::Window(QWidget *parent)
    : QWidget(parent)
{
    slidersGroup = new SlidersGroup(tr("Sliders"));

    createControls(tr("Controls"));

Dans le constructeur, nous créons d’abord le widget ` SlidersGroup ` qui affiche les widgets de curseur. À l’aide de ` createControls() `, nous créons les widgets de contrôle et les connectons aux curseurs.

    layout = new QBoxLayout(QBoxLayout::LeftToRight);
    layout->addWidget(controlsGroup);
    layout->addWidget(slidersGroup);
    setLayout(layout);

    minimumSpinBox->setValue(0);
    maximumSpinBox->setValue(20);
    valueSpinBox->setValue(5);

    setWindowTitle(tr("Sliders"));
}

Nous plaçons les groupes de widgets de contrôle et les curseurs dans une disposition horizontale avant d’initialiser les valeurs minimale, maximale et actuelle. L’initialisation de la valeur actuelle se répercutera sur les widgets curseurs grâce à la connexion que nous avons établie entre les widgets « valueSpinBox » et « SlidersGroup ». Les valeurs minimale et maximale se répercutent quant à elles via les connexions que nous avons créées avec « createControls() ».

void Window::createControls(const QString &title)
{
    controlsGroup = new QGroupBox(title);

    minimumLabel = new QLabel(tr("Minimum value:"));
    maximumLabel = new QLabel(tr("Maximum value:"));
    valueLabel = new QLabel(tr("Current value:"));

    invertedAppearance = new QCheckBox(tr("Inverted appearance"));
    invertedKeyBindings = new QCheckBox(tr("Inverted key bindings"));

Dans la fonction privée ` createControls() `, nous utilisons un ` QGroupBox ` (`controlsGroup`) pour afficher les widgets de contrôle. Une zone de groupe peut fournir un cadre, un titre et un raccourci clavier, et affiche divers autres widgets en son sein. Le groupe de widgets de contrôle est composé de deux cases à cocher et de trois champs de sélection avec des libellés.

Après avoir créé les étiquettes, nous créons les deux cases à cocher. Les cases à cocher sont généralement utilisées pour représenter des fonctionnalités d’une application pouvant être activées ou désactivées. Lorsque l’option « invertedAppearance » est activée, les valeurs des curseurs sont inversées. Le tableau ci-dessous présente l’apparence des différents widgets de type curseur :

QSliderIl est courant d’inverser le sens de déplacement d’un curseur vertical. Un curseur vertical qui contrôle le volume, par exemple, se déplace généralement de bas en haut (sens non inversé), tandis qu’un curseur vertical qui contrôle la position d’un objet à l’écran peut se déplacer de haut en bas, car les coordonnées de l’écran vont de haut en bas.

Lorsque l’option d’ invertedKeyBindings est activée (correspondant à la propriété « QAbstractSlider::invertedControls »), les événements liés à la molette et aux touches du curseur sont inversés. Avec les raccourcis clavier normaux, faire défiler la molette de la souris « vers le haut » ou utiliser des touches telles que « Page précédente » augmente la valeur actuelle du curseur vers son maximum. Une fois inversés, ces mêmes événements de molette et de touches feront évoluer la valeur vers le minimum du curseur. Cela peut s’avérer utile si l’apparence d’un curseur est inversée : certains utilisateurs pourraient s’attendre à ce que les touches agissent toujours de la même manière sur la valeur, tandis que d’autres pourraient s’attendre à ce que « PageUp » signifie « vers le haut » à l’écran.

Notez que pour les barres de défilement horizontales et verticales, les raccourcis clavier sont inversés par défaut : PageDown augmente la valeur actuelle, et PageUp la diminue.

    minimumSpinBox = new QSpinBox;
    minimumSpinBox->setRange(-100, 100);
    minimumSpinBox->setSingleStep(1);

    maximumSpinBox = new QSpinBox;
    maximumSpinBox->setRange(-100, 100);
    maximumSpinBox->setSingleStep(1);

    valueSpinBox = new QSpinBox;
    valueSpinBox->setRange(-100, 100);
    valueSpinBox->setSingleStep(1);

Nous créons ensuite les zones de saisie. QSpinBox permet à l'utilisateur de choisir une valeur en cliquant sur les boutons haut et bas ou en appuyant sur les touches Up et Down du clavier pour modifier la valeur actuellement affichée. L'utilisateur peut également saisir la valeur manuellement. Les zones de saisie contrôlent les valeurs minimale, maximale et actuelle des widgets QSlider, QScrollBar et QDial.

    connect(slidersGroup, &SlidersGroup::valueChanged,
            valueSpinBox, &QSpinBox::setValue);
    connect(valueSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setValue);
    connect(minimumSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setMinimum);
    connect(maximumSpinBox, &QSpinBox::valueChanged,
            slidersGroup, &SlidersGroup::setMaximum);
    connect(invertedAppearance, &QCheckBox::toggled,
            slidersGroup, &SlidersGroup::invertAppearance);
    connect(invertedKeyBindings, &QCheckBox::toggled,
            slidersGroup, &SlidersGroup::invertKeyBindings);

    QGridLayout *controlsLayout = new QGridLayout;
    controlsLayout->addWidget(minimumLabel, 0, 0);
    controlsLayout->addWidget(maximumLabel, 1, 0);
    controlsLayout->addWidget(valueLabel, 2, 0);
    controlsLayout->addWidget(minimumSpinBox, 0, 1);
    controlsLayout->addWidget(maximumSpinBox, 1, 1);
    controlsLayout->addWidget(valueSpinBox, 2, 1);
    controlsLayout->addWidget(invertedAppearance, 0, 2);
    controlsLayout->addWidget(invertedKeyBindings, 1, 2);
    controlsGroup->setLayout(controlsLayout);

}

Nous connectons ensuite le ` slidersGroup ` et le ` valueSpinBox ` entre eux, de sorte que les widgets de curseur et le widget de contrôle se comportent de manière synchronisée lorsque la valeur actuelle de l’un d’entre eux change. Le signal ` valueChanged() ` est émis avec la nouvelle valeur comme argument. Le slot ` setValue() ` définit la valeur actuelle du widget sur la nouvelle valeur et émet ` valueChanged() ` si la nouvelle valeur est différente de l’ancienne.

Nous synchronisons le comportement des widgets de contrôle et des widgets curseurs via leurs signaux et slots. Nous connectons chaque widget de contrôle aux groupes de widgets curseurs horizontaux et verticaux. Nous connectons également orientationCombo à QStackedWidget, afin que la « page » correcte s’affiche. Enfin, nous disposons les widgets de contrôle dans un QGridLayout au sein de la boîte de groupe controlsGroup.

void Window::resizeEvent(QResizeEvent *)
{
    if (width() == 0 || height() == 0)
        return;

    const double aspectRatio = double(width()) / double(height());

    if (aspectRatio < 1.0) {
        layout->setDirection(QBoxLayout::TopToBottom);
        slidersGroup->setOrientation(Qt::Horizontal);
    } else if (aspectRatio > 1.0) {
        layout->setDirection(QBoxLayout::LeftToRight);
        slidersGroup->setOrientation(Qt::Vertical);
    }
}

Enfin, nous redéfinissons la méthode resizeEvent() de QWidget. Nous nous protégeons contre la division par zéro, puis nous calculons le rapport d’aspect du widget. Si la fenêtre est au format portrait, nous configurons la mise en page pour organiser verticalement les groupes de widgets de contrôle et de curseurs, et nous donnons aux curseurs une orientation horizontale. Si la fenêtre est au format paysage, nous modifions la mise en page pour afficher les curseurs et les widgets de contrôle côte à côte, et nous donnons aux curseurs une orientation verticale.

Définition de la classe `SlidersGroup`

class SlidersGroup : public QGroupBox
{
    Q_OBJECT

public:
    SlidersGroup(const QString &title, QWidget *parent = nullptr);

signals:
    void valueChanged(int value);

public slots:
    void setValue(int value);
    void setMinimum(int value);
    void setMaximum(int value);
    void invertAppearance(bool invert);
    void invertKeyBindings(bool invert);
    void setOrientation(Qt::Orientation orientation);

private:
    QSlider *slider;
    QScrollBar *scrollBar;
    QDial *dial;
    QBoxLayout *slidersLayout;
};

La classe ` SlidersGroup ` hérite de ` QGroupBox`. Elle fournit un cadre et un titre, et contient un ` QSlider`, un ` QScrollBar ` et un ` QDial`.

Nous fournissons un signal « valueChanged() » et un slot public « setValue() » dont les fonctionnalités sont équivalentes à celles de « QAbstractSlider » et « QSpinBox ». De plus, nous implémentons plusieurs autres slots publics permettant de définir les valeurs minimale et maximale, d’inverser l’apparence des widgets de curseur ainsi que les raccourcis clavier, et de définir l’orientation.

Implémentation de la classe `SlidersGroup`

SlidersGroup::SlidersGroup(const QString &title, QWidget *parent)
    : QGroupBox(title, parent)
{
    slider = new QSlider;
    slider->setFocusPolicy(Qt::StrongFocus);
    slider->setTickPosition(QSlider::TicksBothSides);
    slider->setTickInterval(10);
    slider->setSingleStep(1);

    scrollBar = new QScrollBar;
    scrollBar->setFocusPolicy(Qt::StrongFocus);

    dial = new QDial;
    dial->setFocusPolicy(Qt::StrongFocus);

Nous commençons par créer les widgets de type curseur avec les propriétés appropriées. Nous définissons notamment la politique de focus pour chaque widget. ` Qt::FocusPolicy ` est un type énuméré qui définit les différentes politiques qu’un widget peut adopter concernant l’acquisition du focus clavier. La politique ` Qt::StrongFocus ` signifie que le widget accepte le focus aussi bien via la touche Tab que par un clic.

    connect(slider, &QSlider::valueChanged, scrollBar, &QScrollBar::setValue);
    connect(scrollBar, &QScrollBar::valueChanged, dial, &QDial::setValue);
    connect(dial, &QDial::valueChanged, slider, &QSlider::setValue);
    connect(dial, &QDial::valueChanged, this, &SlidersGroup::valueChanged);

Ensuite, nous connectons les widgets entre eux, afin qu’ils restent synchronisés lorsque la valeur actuelle de l’un d’entre eux change.

Nous relions le signal ` valueChanged() ` de ` dial` au signal ` valueChanged() ` de ` SlidersGroup`, afin d’informer les autres widgets de l’application (c’est-à-dire les widgets de contrôle) de la modification de la valeur.

    slidersLayout = new QBoxLayout(QBoxLayout::LeftToRight);
    slidersLayout->addWidget(slider);
    slidersLayout->addWidget(scrollBar);
    slidersLayout->addWidget(dial);
    setLayout(slidersLayout);
}

Enfin, nous créons la disposition des widgets curseurs à l’intérieur de la zone de groupe. Nous commençons par une disposition horizontale des curseurs.

void SlidersGroup::setValue(int value)
{
    slider->setValue(value);
}

Le slot « setValue() » définit la valeur de « QSlider ». Il n’est pas nécessaire d’appeler explicitement la méthode « setValue() » sur les widgets « QScrollBar » et « QDial », car « QSlider » émettra le signal « valueChanged() » lorsque sa valeur changera, déclenchant ainsi un effet domino.

void SlidersGroup::setMinimum(int value)
{
    slider->setMinimum(value);
    scrollBar->setMinimum(value);
    dial->setMinimum(value);
}

void SlidersGroup::setMaximum(int value)
{
    slider->setMaximum(value);
    scrollBar->setMaximum(value);
    dial->setMaximum(value);
}

Les slots « setMinimum() » et « setMaximum() » sont utilisés par la classe « Window » pour définir la plage des widgets « QSlider », « QScrollBar » et « QDial ».

void SlidersGroup::invertAppearance(bool invert)
{
    slider->setInvertedAppearance(invert);
    scrollBar->setInvertedAppearance(invert);
    dial->setInvertedAppearance(invert);
}

void SlidersGroup::invertKeyBindings(bool invert)
{
    slider->setInvertedControls(invert);
    scrollBar->setInvertedControls(invert);
    dial->setInvertedControls(invert);
}

Les slots invertAppearance() et invertKeyBindings() contrôlent les propriétés invertedAppearance et invertedControls des widgets enfants.

void SlidersGroup::setOrientation(Qt::Orientation orientation)
{
    slidersLayout->setDirection(orientation == Qt::Horizontal
                                ? QBoxLayout::TopToBottom
                                : QBoxLayout::LeftToRight);
    scrollBar->setOrientation(orientation);
    slider->setOrientation(orientation);
}

Le slot setOrientation() contrôle la direction de la disposition et l'orientation des curseurs. Dans un groupe horizontal, les curseurs ont une orientation horizontale et sont disposés les uns au-dessus des autres. Dans un groupe vertical, les curseurs ont une orientation verticale et sont disposés les uns à côté des autres.

Exemple de projet sur code.qt.io