Skip to main content
Ir para o conteúdo
Editar esta página See source code Criar um bug sobre a documentação Formatting guidelines Style guidelines

Controles e elementos interativos

Torne seus aplicativos mais interativos usando botões, controles de seleção, controles deslizantes e campos de texto.

O Kirigami utiliza uma ampla seleção de diferentes elementos interativos do Qt que você pode usar em seus aplicativos. Cada tipo diferente possui estilos de interação, estilos visuais e funcionalidades ligeiramente diferentes. Usar o tipo certo de controle em seu aplicativo pode ajudar a tornar sua interface de usuário mais responsiva e intuitiva.

Botões

Em aplicativos Kirigami, usamos o Button do QtQuick Controls. Usá-los é bastante simples: definimos a propriedade text e qualquer ação que queremos que ele execute é definida como a propriedade onClicked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.Button"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.Button {
                Layout.alignment: Qt.AlignCenter
                text: "Beep!"
                onClicked: showPassiveNotification("Boop!")
            }
        }
    }
}

Uma janela contendo um botão "Beep" no centro, que, quando clicado, mostra uma notificação passiva "Boop" na parte inferior da janela

Botões alternáveis

O comportamento dos botões pode ser alterado para torná-los alternáveis: neste modo, eles permanecerão pressionados até serem clicados novamente. Este modo pode ser ativado definindo a propriedade checkable como true; também podemos definir que os botões sejam alternados por padrão definindo checked como true.

Podemos aproveitar ao máximo os botões alternáveis ​​usando o manipulador de sinal onCheckedChanged, que é gerado automaticamente a partir do sinal checked. Ele funciona de forma semelhante ao onClicked, exceto que aqui a ação atribuída será executada quando o estado do botão mudar. É uma propriedade booleana, que pode ser útil para casos de uso específicos.

Neste exemplo, definimos a visibilidade de uma gaveta embutida de acordo com o status de um botão alternável:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.Button (toggleable version)"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.Button {
                Layout.alignment: Qt.AlignCenter
                text: "Hide inline drawer"
                checkable: true
                checked: true
                onCheckedChanged: myDrawer.visible = checked
            }

            Kirigami.OverlayDrawer {
                id: myDrawer
                edge: Qt.BottomEdge
                modal: false

                contentItem: Controls.Label {
                    text: "Peekaboo!"
                }
            }
        }
    }
}

Uma janela contendo um botão alternável "Ocultar gaveta embutida" no centro que, quando alternado, oculta a gaveta embutida "Peekaboo"

Botões da barra de ferramentas

Existe um tipo específico de botão destinado ao uso em barras de ferramentas, Controls.ToolButton. A diferença mais óbvia entre ele e um Button convencional é o estilo, com os botões de ferramentas sendo planos (embora isso seja alterável com a propriedade booleana flat).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.ToolButton"
    width: 600
    height: 600

    header: Controls.ToolBar {
        RowLayout {
            anchors.fill: parent
            Controls.ToolButton {
                icon.name: "application-menu-symbolic"
                onClicked: showPassiveNotification("Kirigami Pages and Actions are better!")
            }
            Controls.Label {
                text: "Global ToolBar"
                horizontalAlignment: Qt.AlignHCenter
                verticalAlignment: Qt.AlignVCenter
                Layout.fillWidth: true
            }
            Controls.ToolButton {
                text: "Beep!"
                onClicked: showPassiveNotification("ToolButton boop!")
            }
        }
    }
}

Uma janela mostrando uma barra de ferramentas personalizada no cabeçalho da janela, simulando uma Kirigami.globalToolBar, com um ícone de menu à esquerda que exibe uma notificação passiva "Páginas e Ações do Kirigami estão melhores!" e um botão de ferramenta à direita "Bip", completamente plano, simulando uma Kirigami.Action

Controles de seleção

Os controles de seleção permitem que os usuários façam uma escolha ou escolham uma opção. Existem diferentes tipos que são mais adequados para diferentes situações.

Caixas de seleção

Uma Controls.CheckBox é destinada a opções em que as escolhas não são exclusivas e onde cada opção tem uma alternativa clara.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.CheckBox"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.left: parent.left
            anchors.right: parent.right
            Controls.CheckBox {
                Layout.alignment: Qt.AlignHCenter
                text: "This checkbox is checked!"
                checked: true
            }
            Controls.CheckBox {
                Layout.alignment: Qt.AlignHCenter
                text: "This checkbox is not checked!"
                checked: false
            }
        }
    }
}

Uma janela mostrando duas caixas de seleção onde mais de uma caixa de seleção pode ser marcada ao mesmo tempo

Como você pode ver, eles são simples de usar. A propriedade checked contém um valor booleano que determina se eles foram verificados ou não.

Botões de opção

Um Controls.RadioButton foi projetado para situações em que o usuário deve escolher uma opção de um conjunto de várias opções.

Os botões de opção são exclusivos por padrão: apenas um botão pode ser marcado no mesmo item pai.

Assim como as caixas de seleção, eles podem ser definidos para serem marcadas ou desmarcadas por padrão com a propriedade checked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.RadioButton"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {

        ColumnLayout {
            anchors.left: parent.left
            anchors.right: parent.right
            Controls.RadioButton {
                Layout.alignment: Qt.AlignCenter
                text: "Tick!"
                checked: true
            }
            Controls.RadioButton {
                Layout.alignment: Qt.AlignCenter
                text: "Tock!"
                checked: false
            }
        }
    }
}

Uma janela mostrando dois botões de opção onde apenas um botão de opção pode ser marcado ao mesmo tempo

Interruptores

No desktop, alterar as configurações geralmente envolve alterar a configuração e aplicá-la clicando no botão "Aplicar" ou "OK". No celular, podemos usar Controls.Switch em vez disso.

Os interruptores podem ser alternados entre os estados ligado e desligado. Eles podem ser alternados clicando ou tocando neles, ou podem ser arrastados para a posição ligado ou desligado. Mais uma vez, os interruptores podem ser definidos como ligados ou desligados por padrão com a propriedade checked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.Switch"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.Switch {
                Layout.alignment: Qt.AlignCenter
                text: "Switchy"
                checked: true
            }
            Controls.Switch {
                Layout.alignment: Qt.AlignCenter
                text: "Swootchy"
                checked: false
            }
        }
    }
}

Uma janela mostrando dois interruptores igualmente espaçados que funcionam como alternadores

Controles deslizantes

Os controles deslizantes permitem que os usuários selecionem determinados valores deslizando uma alça ao longo de uma trilha. Existem vários tipos que você pode escolher, dependendo dos valores que deseja que seus usuários escolham em seu aplicativo.

Controles deslizantes padrão e marcados

Um Controls.Slider padrão fornece ao usuário um controle muito preciso sobre a seleção que deseja fazer.

No modo da esquerda para a direita, os controles deslizantes vão da esquerda para a direita para aumentar quando na orientação horizontal, enquanto no modo da direita para a esquerda, eles vão na direção inversa. Em ambos os modos, os controles deslizantes na orientação vertical vão de baixo para cima.

A coloração fornece um indicador visual de quão grande é o valor que você está selecionando.

Os controles deslizantes têm algumas propriedades importantes às quais devemos prestar atenção:

  • value: contém o valor no qual o identificador é colocado e também pode ser definido manualmente para fornecer um valor inicial padrão
  • to: define o intervalo do controle deslizante especificando o valor máximo que ele pode atingir
  • orientation: permite que o controle deslizante seja definido para uma orientação vertical com Qt.Vertical
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.Slider"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.Slider {
                id: normalSlider
                Layout.alignment: Qt.AlignHCenter
                Layout.fillHeight: true
                orientation: Qt.Vertical
                value: 60
                to: 100
            }
            Controls.Label {
                Layout.alignment: Qt.AlignHCenter
                text: Math.round(normalSlider.value)
            }
        }
    }
}

Uma janela mostrando um controle deslizante vertical com seu valor atual abaixo dele

Outra propriedade útil que podemos usar é stepSize. Defini-la como um valor numérico nos permite criar um controle deslizante que se encaixa em valores múltiplos do stepSize especificado, com esses múltiplos sendo indicados por marcas de seleção. Portanto, se definirmos essa propriedade como 2,0, quando o usuário arrastar a alça do controle deslizante, ele só poderá selecionar 0,0, 2,0, 4,0, etc. até o valor especificado na propriedade to.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.Slider (with steps)"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.Slider {
                id: tickmarkedSlider
                Layout.alignment: Qt.AlignHCenter
                Layout.fillWidth: true
                orientation: Qt.Horizontal
                snapMode: Controls.Slider.SnapAlways
                value: 6.0
                to: 10.0
                stepSize: 2.0
            }
            Controls.Label {
                Layout.alignment: Qt.AlignHCenter
                text: tickmarkedSlider.value
            }
        }
    }
}

Uma janela mostrando um conjunto de controles deslizantes marcados que são divididos simetricamente e cada divisão é chamada de etapa

Controles deslizantes de intervalo

O QtQuick Controls também fornece Controls.RangeSliders. Eles possuem duas alças, permitindo que você defina um intervalo de números entre as duas alças.

Duas novas propriedades são importantes de se ter em mente: first.value e second.value, que contêm os valores dos dois identificadores. Assim como a propriedade value dos controladores deslizantes padrão, elas podem ser predefinidas.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Controls.RangeSlider"
    width: 400
    height: 400
    pageStack.initialPage: Kirigami.Page {
        ColumnLayout {
            anchors.fill: parent
            Controls.RangeSlider {
                id: rangeSlider
                Layout.alignment: Qt.AlignHCenter
                to: 10.0
                first.value: 2.0
                second.value: 8.0
                stepSize: 1.0
                snapMode: Controls.Slider.SnapAlways
            }
            RowLayout {
                Layout.alignment: Qt.AlignHCenter
                Layout.fillWidth: true
                Controls.Label {
                    Layout.fillWidth: true
                    text: "The slider's first value is: " + Math.round(rangeSlider.first.value)
                }
                Controls.Label {
                    Layout.fillWidth: true
                    text: "The slider's second value is: " + Math.round(rangeSlider.second.value)
                }
            }
            Controls.Label {
                Layout.alignment: Qt.AlignHCenter
                font.bold: true
                text: "Is the selected range between 2 and 8?"
            }
            Controls.Button {
                Layout.alignment: Qt.AlignHCenter
                icon.name: {
                    if (rangeSlider.first.value >= 2 && rangeSlider.second.value <= 8)
                        return "emblem-checked"
                    else
                        return "emblem-error"
                }
            }
        }
    }
}

![Uma janela mostrando um controle deslizante de intervalo, seguido por alguns rótulos abaixo e um botão com um ícone de marca de seleção](/pt-br/docs/getting-started/kirigami/components-controls /controls-rangeslider.webp)

Previous
Tipos de diálogos
Next
Layouts de formulário