Tutorial Abrangente de PyQt5: Construa GUIs Profissionais em Python

O que é PyQt?

PyQt é um binding Python para o framework Qt, uma biblioteca C++ multiplataforma usada para criar aplicações GUI nativas no Windows, macOS, Linux, Android, iOS, Raspberry Pi e mais. O binding é mantido pela Riverbank Computing (UK), enquanto o Qt em si é desenvolvido pela The Qt Company (Finlândia). PyQt dá desenvolvedores Python acesso ao rico conjunto de widgets, rede, banco de dados, 3D e capacidades multimídia do Qt.

Neste tutorial você aprenderá:

• Principais recursos do PyQt5
• Versões disponíveis do PyQt
• Como instalar PyQt5 no Windows, macOS e Linux
• Conceitos fundamentais do PyQt e programas de exemplo
• Componentes e widgets centrais
• Estratégias de layout e personalização de temas

Principais Recursos do PyQt5

PyQt5 expõe mais de 600 classes que cobrem:

• Interfaces Gráficas de Usuário
• Integração com bancos de dados SQL (SQLite, MySQL, PostgreSQL, Oracle, ODBC)
• Renderização web via QtWebEngine
• Parsing e manipulação XML
• Rede robusta (TCP/UDP, SSL, DNS)
• Multimídia e gráficos 3D (QtMultimedia, Qt3D)

Essas capacidades permitem desenvolvedores construir aplicações desktop e embarcadas complexas e de alta performance. Grandes corporações como LG, Mercedes-Benz, AMD, Panasonic e Harman confiam no Qt para suas stacks de UI.

Versões do PyQt

Riverbank Computing oferece dois bindings principais:

• PyQt4 — suporta módulos Qt 4.x e Qt 5.x (não compatível com versões anteriores)
• PyQt5 — bindings exclusivamente para Qt 5.x

Adicionalmente, PyQt3D fornece bindings Python para o framework Qt3D, útil para renderização 3D em tempo real e simulação.

Instalando PyQt5

Dois métodos comuns de instalação são descritos abaixo. Recomendamos usar pacotes wheel porque incluem binários C++ compilados e evitam processos de build longos.

Método 1: Instalação via Wheels (Recomendado)

1. Abra seu terminal ou prompt de comando preferido.
2. Execute pip install PyQt5 para baixar o wheel (≈ 50 MB).
3. Verifique se a instalação completa com sucesso.

Exemplo no Windows:

pip install PyQt5

Uma vez instalado, você pode importar PyQt5.QtWidgets e começar a construir aplicações.

Método 2: Build from Source

Build from source é mais complexo porque compila código C++. É apenas necessário se você precisar de modificações customizadas ou o wheel para sua plataforma estiver indisponível.

Fundamentos da Programação PyQt5

Abaixo está um exemplo mínimo que abre uma janela 300x300 titulada "Guru99". Cada linha é anotada para clareza.

import sys
from PyQt5.QtWidgets import QApplication, QWidget
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    w.show()
    sys.exit(app.exec_())

Explicação:

• QApplication — o loop de eventos central.
• QWidget — classe base para todos componentes UI.
• resize() — define dimensões da janela.
• setWindowTitle() — define texto da barra de título.
• show() — exibe o widget.
• app.exec_() — inicia o loop de eventos e bloqueia até a janela fechar.

Adicionando Interatividade

O exemplo a seguir adiciona um label, um botão e uma message box que aparece quando o botão é clicado. Demonstra signals e slots, o núcleo do sistema de eventos do Qt.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QPushButton, QMessageBox
def dialog():
    mbox = QMessageBox()
    mbox.setText("Your allegiance has been noted")
    mbox.setDetailedText("You are now a disciple and subject of the all-knowing Guru")
    mbox.setStandardButtons(QMessageBox.Ok | QMessageBox.Cancel)
    mbox.exec_()
if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = QWidget()
    w.resize(300, 300)
    w.setWindowTitle("Guru99")
    label = QLabel("Behold the Guru, Guru99", w)
    label.move(100, 130)
    btn = QPushButton("Beheld", w)
    btn.move(110, 150)
    btn.clicked.connect(dialog)
    w.show()
    sys.exit(app.exec_())

Clicar no botão dispara dialog(), que cria um QMessageBox modal.

Componentes Centrais e Widgets

A arquitetura do PyQt5 é organizada em vários módulos. Entender esta hierarquia ajuda você a importar apenas o que precisa.

Visão Geral dos Módulos

• Qt — agrega todos sub-módulos; conveniente para scripts pequenos.
• QtCore — classes core non-GUI (signals, slots, timers).
• QtWidgets — widgets GUI padrão (botões, labels, etc.).
• QtGui — primitivas gráficas e pintura avançada.
• QtNetwork — sockets TCP/UDP, SSL, DNS.
• QtMultimedia — suporte a áudio/vídeo.
• QtSql — integração com banco de dados.

Widgets Comuns

• QLineEdit — input de texto de linha única.
• QRadioButton — botão de rádio selecionável.
• QComboBox — seletor drop-down.
• QCheckBox — caixa de toggle.
• QMenuBar — barra de menu horizontal.
• QToolBar — toolbar com botões.
• QTabWidget — interface com abas.
• QScrollBar — widget de scroll bar.
• QSplitter — split view redimensionável.
• QDockWidget — painel dock destacável.

Gerenciamento de Layout

Em vez de posicionar widgets manualmente com move() e resize(), o Qt oferece gerenciadores de layout que organizam widgets automaticamente baseados no tamanho da janela.

Box Layouts (HBox & VBox)

QHBoxLayout organiza widgets horizontalmente; QVBoxLayout verticalmente.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QHBoxLayout, QVBoxLayout
app = QApplication([])
win = QWidget()
win.setWindowTitle("Musketeers")
btn1 = QPushButton("Athos")
btn2 = QPushButton("Porthos")
btn3 = QPushButton("Aramis")
hbox = QHBoxLayout(win)
hbox.addWidget(btn1)
hbox.addWidget(btn2)
hbox.addWidget(btn3)
win.show()
app.exec_()

Substitua QHBoxLayout por QVBoxLayout para empilhar botões verticalmente.

Grid Layout

Organize widgets em grade 2D. O método addWidget() aceita índices de linha e coluna mais argumentos opcionais de row-span e column-span.

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QPushButton, QGridLayout
app = QApplication([])
win = QWidget()
layout = QGridLayout(win)
for i in range(3):
    for j in range(3):
        layout.addWidget(QPushButton(f"Button {i},{j}"), i, j)
win.show()
app.exec_()

Temas e Estilos Customizados

PyQt5 suporta temas nativos e stylesheets customizados.

Temas Embutidos

Defina o estilo da aplicação com app.setStyle("Fusion") ou qualquer outro estilo disponível.

app = QApplication([])
app.setStyle("Fusion")

Personalização de Paleta

Use QPalette para modificar cores de widgets programaticamente.

from PyQt5.QtGui import QPalette
from PyQt5.QtCore import Qt
palette = QPalette()
palette.setColor(QPalette.ButtonText, Qt.black)
palette.setColor(QPalette.Window, Qt.black)
palette.setColor(QPalette.Button, Qt.gray)
app.setPalette(palette)

Qt Style Sheets (CSS-like)

Para estilização avançada, aplique stylesheets diretamente em widgets ou na aplicação inteira.

btn.setStyleSheet("background-color: #4CAF50; color: white; padding: 5px;")

Principais Conclusões

• PyQt5 é um poderoso binding Python para o framework Qt, adequado para apps desktop, embarcados e móveis multiplataforma.
• Instalação é melhor realizada via wheels; builds from source são opcionais.
• Módulos core: QtCore, QtGui, QtWidgets, QtNetwork, QtMultimedia, QtSql.
• Widgets incluem botões, labels, campos de texto, radio buttons, checkboxes, menus, toolbars, tabs, splitters e docks.
• Interatividade depende do mecanismo de signals e slots do Qt.
• Layouts — Box e Grid — automatizam posicionamento de widgets, melhorando responsividade.
• Temas podem ser alcançados com estilos embutidos, paletas ou Qt Style Sheets.
• Qt Designer e Qt Creator agilizam design de UI e empacotamento de aplicações.