PySide

This page is a translated version of the page PySide and the translation is 100% complete.

Introdução

A biblioteca PySide é um *wrapper* em Python para o Qt, um *toolkit* de interface gráfica do usuário (GUI) multiplataforma. O FreeCAD utiliza o Qt como seu principal *toolkit* de GUI. O Qt, por si só, é mais do que apenas um *toolkit* de GUI; trata-se de uma coleção de bibliotecas C++ voltadas para diversas finalidades — é possível, por exemplo, realizar operações de rede utilizando componentes da biblioteca Qt —, tudo isso acessível em Python por meio do PySide. Qualquer interface gráfica que possa ser criada em C++ também pode ser criada e modificada em Python. Uma vantagem de utilizar Python é que as interfaces Qt podem ser desenvolvidas e testadas em tempo real, uma vez que não há necessidade de compilar os arquivos de código-fonte.

A maneira recomendada de importar o PySide (de qualquer versão) no FreeCAD é:

from PySide import QtCore, QtGui, QtWidgets

Versões do Qt e PySide

A versão 1.0 do Qt foi lançada em meados da década de 1990
A versão 4.0 do Qt foi lançada em 2005, e a série 4.x foi oficialmente descontinuada em 2015
- O wrapper Python para o Qt4.x chama-se PySide
A versão 5.0 do Qt foi lançada em 2012, e a série 5.x foi oficialmente descontinuada em 2020.
- O wrapper Python para o Qt5.x chama-se PySide2
A versão 6.0 do Qt foi lançada em 2020; é a série de versão atual
- O wrapper Python para o Qt6.x chama-se PySide6

Exemplos criados com PySide. À esquerda: uma caixa de diálogo simples. À direita: uma caixa de diálogo mais complexa com gráficos.

Top

FreeCAD e PySide

A ideia original por trás do FreeCAD era reunir o Cas.CADE (núcleo geométrico), o Qt (toolkit de GUI) e o Python para criar um programa de CAD paramétrico 3D gratuito com um mecanismo de script integrado. Isso ocorreu no início dos anos 2000 — ou seja, antes da existência do PySide; por isso, utilizou-se um wrapper diferente, o PyQt, durante a primeira década de existência do FreeCAD. O PySide surgiu para resolver questões de licenciamento relacionadas ao PyQt, e a migração do FreeCAD para o PySide foi realizada em 2013 (commit 1dc122dc9a).

Se você quiser saber qual versão do Qt sua instalação utiliza, a caixa de diálogo "Sobre" contém listas de versões que incluem o Qt.

Para mais informações, consulte:

Ao instalar o FreeCAD, você obtém tanto o Qt quanto a versão correspondente do PySide como parte do pacote. Se você mesmo estiver realizando a compilação, deve verificar se versões compatíveis dessas duas bibliotecas estão instaladas para que o FreeCAD funcione corretamente. Naturalmente, o PySide só funcionará se o Qt estiver presente.

Top

Compatibilidade entre múltiplas versões

A principal diferença entre o PySide e as bibliotecas subsequentes PySide2 e PySide6 reside nos namespaces. O PySide (Qt4) possui os namespaces principais QtGui e QtCore, enquanto o PySide2 (Qt5) e o PySide6 (Qt6) introduziram o namespace adicional QtWidgets, onde todos os widgets estão agora localizados — anteriormente, eles ficavam no namespace QtGui.

A abordagem do FreeCAD para lidar com as diferentes versões do Qt/PySide consiste em chamá-las todas de PySide — algo que, na verdade, deveria ser encarado como PySideX. Não importa qual versão do Qt/PySide esteja instalada; todas são importadas como PySide.

Um shim lida com as diferenças entre as versões. Este shim do PySide está localizado no diretório Ext/ de uma instalação do FreeCAD compilada para Qt5/Qt6.

/usr/share/freecad/Ext/PySide

Este módulo apenas importa as classes necessárias de PySide2/6 e as coloca no namespace PySide. Essa abordagem foi escolhida por sua capacidade de oferecer compatibilidade retroativa sob a perspectiva do Qt4.

PySide2.QtCore -> PySide.QtCore
PySide2.QtGui -> PySide.QtGui
PySide2.QtWidgets -> PySide.QtWidgets
PySide2.QtSvg -> PySide.QtSvg
PySide2.QtUiTools -> PySide.QtUiTools

Por esse motivo, as classes do PySide2.QtWidgets também são colocadas no namespace PySide.QtGui.

PySide2.QtWidgets.QCheckBox -> PySide.QtGui.QCheckBox

Mas a maneira recomendada atualmente é usar o sistema moderno de namespaces.

from PySide import QtCore, QtGui, QtWidgets

my_check_box = QtWidgets.QCheckBox()

Top

Exemplos de uso do PySide

Exemplos de PySide para Iniciantes, "Hello World", anúncios, entrada de texto, entrada de número.
Exemplos de PySide de Nível Intermediário, redimensionamento de janelas, ocultação de widgets, menus pop-up, posição do mouse, eventos de mouse.
Exemplos de PySide Avançados, múltiplos widgets.

Os exemplos do PySide estão divididos em três partes, diferenciadas pelo nível de exposição ao PySide, ao Python e aos componentes internos do FreeCAD. A primeira página apresenta uma visão geral do PySide; a segunda e a terceira páginas consistem principalmente em exemplos de código em diferentes níveis.

Espera-se que estes exemplos sejam úteis para começar e que, posteriormente, o usuário possa consultar outros recursos online ou a documentação oficial.

Top

Documentação

Existem algumas diferenças no tratamento de widgets entre as diferentes versões. Os programadores devem estar cientes dessas incompatibilidades e consultar a documentação oficial caso algo não funcione como esperado em uma determinada plataforma. Embora raro, às vezes pode ser necessário realizar chamadas específicas para cada versão utilizando estruturas condicionais (*if-clauses*).

A documentação do PySide refere-se às classes no estilo Python; entretanto, como Qt é originalmente uma biblioteca C++, a mesma informação deve estar disponível na referência C++ correspondente.