ui-documentation.md

author	copyright	license	version	min_python	min_freecad	date	geometry
Frank David Martínez Muñoz	(c) 2024 Frank David Martínez Muñoz.	LGPL 2.1	1.0.0-beta4	3.10	0.22	2024-12-04 16:48:18.686855	margin=2cm

FreeCAD GUI Modern API

META	VALUE
generated	2024-12-04 16:48:18.696733
author	Frank David Martínez Muñoz
copyright	(c) 2024 Frank David Martínez Muñoz.
license	LGPL 2.1
version	1.0.0-beta4
min_python	3.10
min_freecad	0.22

TABLE OF CONTENTS

• FreeCAD GUI Modern API
• Preliminaries
  • Disclaimer
  • Audience
  • Goals
  • Non Goals
• Features
• Widgets
  • Containers / Layouts
    • Widget: Dialog
    • Widget: Scroll
    • Widget: GroupBox
    • Widget: Container
    • Widget: TabContainer
    • Function: Tab
    • Widget: Splitter
    • Widget: Col
    • Widget: Row
  • Output
    • Widget: TextLabel
    • Widget: Html
    • Widget: ImageView
    • Widget: SvgImageView
    • Widget: Table
    • Widget: Canvas
  • Inputs
    • Widget: InputBoolean
    • Widget: InputInt
    • Widget: InputFloat
    • Widget: InputFloatList
    • Widget: InputQuantity
    • Widget: InputVector
    • Widget: InputText
    • Widget: InputOptions
    • Widget: InputSelectOne
    • Widget: InputSelectMany
    • Widget: button
  • Layout tools
    • Function: Stretch
    • Function: Spacing

Preliminaries

Disclaimer

All of the following information is the result of my own research and usage of the FreeCAD's Python APIs and Qt/PySide along several years. It reflects my very own view, coding style and limited understanding of FreeCAD internals. All the content is based on official docs, forum discussions, development of my own extensions, reading code of existing extensions and FreeCAD sources.

This document does not cover 100% of the Qt/PySide API because it is huge and not really required for common Macros in FreeCAD.

Audience

This is a technical document for developers of FreeCAD extensions using Qt/PySide as they GUI Framework.

General programming experience, some basic FreeCAD know-how and a minimalistic comprehension of Python are sufficient, as long as you can search the internet for a basic grasp of classes, functions, decorators, type hints, etc...;)

It is also expected that the readers are FreeCAD users, and have a good understanding of the basic usage of it.

Goals

• The API must be developer friendly, consistent, maintainable and compatible with FC 0.21+
• The API must be an overlay on top of the existing PySide API, so no conflicts with existing code.
• The API must be 100% documented.

Non Goals

• It is not intended to replace anything in the existing FreeCAD APIs.
• It is not intended to require any refactoring of existing python code.
• It is not intended to require any refactoring of existing C/C++ code.

Features

• Declarative Layout
  • Code layout reflects GUI Structure
• Custom input widgets
  • InputText
  • Numeric inputs: InputInt, InputFloat, InputQuantity
  • List inputs: InputFloatList
  • InputBoolean
  • InputVector
  • InputOptions
  • Selection input: InputSelectOne, InputSelectMany
  • Buttons
• Custom view widgets
  • Html
  • Image
  • Svg
  • Table
  • Canvas
• Documentation in markdown format.

Widgets

Containers / Layouts

Widget: Dialog

Signature / Dialog

def Dialog(
        title: str=None, 
        *, 
        size: Tuple[int, int]=None, 
        show: bool=True, 
        modal: bool=True, 
        parent: QWidget=None, 
        **kwargs
    ) -> Generator[QDialog, Any, Any]: ...

Gui / Dialog

Docs / Dialog

Return type	Description
QDialog	The Dialog

Argument	Type	Description
title	str	window title, defaults to None
size	Tuple[int, int]	dialog size, defaults to None
show	bool	show automatically, defaults to True
modal	bool	window modality, defaults to True
parent	QWidget	parent widget, defaults to None
**kwargs	Dict[str, Any]	Qt properties

Dialog context manager/widget.

Example:

../examples/ui/widgets.py (Dialog)

def demo_Dialog():
    with ui.Dialog("Dialog"):
        with ui.Col():
            ui.TextLabel("This a simple text", alignment=Qt.AlignCenter)

Widget: Scroll

Signature / Scroll

def Scroll(*, add: bool=True, **kwargs) -> Generator[QScrollArea, Any, Any]: ...

Gui / Scroll

Docs / Scroll

Return type	Description
QScrollArea	Scroll widget

Argument	Type	Description
add	bool	add to context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Scrollable area context manager/widget.

Example:

../examples/ui/widgets.py (Scroll)

def demo_Scroll():
    with ui.Dialog("Scroll"):
        with ui.Scroll(widgetResizable=True):
            with ui.Container():
                _v1 = ui.InputVector(label="Input vector:")
                _v2 = ui.InputVector(label="Input vector:")

Widget: GroupBox

Signature / GroupBox

def GroupBox(
        title: str=None, 
        *, 
        add: bool=True, 
        **kwargs
    ) -> Generator[QGroupBox, Any, Any]: ...

Gui / GroupBox

Docs / GroupBox

Return type	Description
QGroupBox	The group widget

Argument	Type	Description
title	str	Group title, defaults to None
add	bool	add to context, defaults to True
add	bool	add to context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

GroupBox context manager/widget.

Example:

../examples/ui/widgets.py (GroupBox)

def demo_GroupBox():
    with ui.Dialog("GroupBox"):
        with ui.GroupBox("General"):
            _quant = ui.InputInt(label="Quantity:")
            _round = ui.InputBoolean(label="Round:")
        with ui.GroupBox("Details"):
            _desc = ui.InputText(label="Description:")
            _rate = ui.InputFloat(label="Rate:")

Widget: Container

Signature / Container

def Container(*, add: bool=True, **kwargs) -> Generator[QFrame, Any, Any]: ...

Docs / Container

Return type	Description
QFrame	The container widget

Argument	Type	Description
add	bool	add to context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Simple container context/widget.

Example

../examples/ui/widgets.py (Scroll)

def demo_Scroll():
    with ui.Dialog("Scroll"):
        with ui.Scroll(widgetResizable=True):
            with ui.Container():
                _v1 = ui.InputVector(label="Input vector:")
                _v2 = ui.InputVector(label="Input vector:")

Widget: TabContainer

Signature / TabContainer

def TabContainer(
        *, 
        stretch: int=0, 
        add: bool=True, 
        **kwargs
    ) -> Generator[QTabWidget, Any, Any]: ...

Gui / TabContainer

Docs / TabContainer

Return type	Description
QTabWidget	The widget

Argument	Type	Description
stretch	int	stretch, defaults to 0
add	bool	add to the context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Tab Container context/widget

Example:

../examples/ui/widgets.py (TabContainer)

def demo_TabContainer():
    with ui.Dialog("TabContainer"):
        with ui.TabContainer():
            with ui.Tab("General"):
                _quant = ui.InputInt(label="Quantity:")
                _round = ui.InputBoolean(label="Round:")
            with ui.Tab("Details"):
                _desc = ui.InputText(label="Description:")
                _rate = ui.InputFloat(label="Rate:")

Function: Tab

Signature / Tab

def Tab(
        title: str, 
        *, 
        icon: QIcon=None, 
        add: bool=True, 
        **kwargs
    ) -> Generator[QWidget, Any, Any]: ...

Docs / Tab

Return type	Description
QWidget	the widget

Argument	Type	Description
title	str	Tab's title
icon	QIcon	Icon, defaults to None
add	bool	add to the context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Tab widget/context in a tab container

Example:

../examples/ui/widgets.py (TabContainer)

def demo_TabContainer():
    with ui.Dialog("TabContainer"):
        with ui.TabContainer():
            with ui.Tab("General"):
                _quant = ui.InputInt(label="Quantity:")
                _round = ui.InputBoolean(label="Round:")
            with ui.Tab("Details"):
                _desc = ui.InputText(label="Description:")
                _rate = ui.InputFloat(label="Rate:")

Widget: Splitter

Signature / Splitter

def Splitter(*, add=True, **kwargs) -> Generator[QSplitter, Any, Any]: ...

Gui / Splitter

Docs / Splitter

Return type	Description
QSplitter	The splitter widget

Argument	Type	Description
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Split context/container

Example:

../examples/ui/widgets.py (Splitter)

def demo_Splitter():
    with ui.Dialog("Splitter"):
        with ui.Splitter():
            with ui.Container():
                _quant = ui.InputInt(label="Quantity:")
                _round = ui.InputBoolean(label="Round:")
            with ui.Container():
                _desc = ui.InputText(label="Description:")
                _rate = ui.InputFloat(label="Rate:")

Widget: Col

Signature / Col

def Col(*, add: bool=True, **kwargs) -> Generator[QWidget, Any, Any]: ...

Gui / Col

Docs / Col

Return type	Description
QWidget	A container widget with Vertical layout

Argument	Type	Description
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Vertical context/layout

Example:

../examples/ui/widgets.py (Col)

def demo_Col():
    with ui.Dialog("Col"):
        with ui.Col():
            ui.TextLabel("Number:", alignment=Qt.AlignCenter)
            ui.InputInt(alignment=Qt.AlignCenter)
            ui.TextLabel("Boolean:", alignment=Qt.AlignCenter)
            ui.InputBoolean(alignment=Qt.AlignCenter)
            ui.TextLabel("Text:", alignment=Qt.AlignCenter)
            ui.InputText(alignment=Qt.AlignCenter)
            ui.TextLabel("Float:", alignment=Qt.AlignCenter)
            ui.InputFloat(alignment=Qt.AlignCenter)

Widget: Row

Signature / Row

def Row(*, add: bool=True, **kwargs): ...

Gui / Row

Docs / Row

Return type	Description
QWidget	A container widget with Horizontal layout

Argument	Type	Description
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Horizontal context/layout

Example:

../examples/ui/widgets.py (Row)

def demo_Row():
    with ui.Dialog("Row"):
        with ui.Row():
            ui.TextLabel("Number:")
            ui.InputInt()
            ui.TextLabel("Boolean:")
            ui.InputBoolean()
            ui.TextLabel("Text:")
            ui.InputText()
            ui.TextLabel("Float:")
            ui.InputFloat()

Output

Widget: TextLabel

Signature / TextLabel

def TextLabel(
        text: str='', 
        *, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> QLabel: ...

Gui / TextLabel

Docs / TextLabel

Return type	Description
QLabel	The widget

Argument	Type	Description
text	str	text, defaults to ""
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties of QLabel

Simple text label widget

Example:

../examples/ui/widgets.py (TextLabel)

def demo_TextLabel():
    with ui.Dialog("TextLabel"):
        with ui.Col():
            ui.TextLabel("This is a text label", alignment=Qt.AlignCenter)

Widget: Html

Signature / Html

def Html(
        *, 
        html: str=None, 
        file: str=None, 
        css: str=None, 
        css_file: str=None, 
        base_path: str=None, 
        background: str=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        variables: Dict[str, Any]=None, 
        add: bool=True, 
        **kwargs
    ) -> HtmlWidget: ...

Gui / Html

Docs / Html

Return type	Description
HtmlWidget	Html Widget

Argument	Type	Description
html	str	raw html content, defaults to None
file	str	path to html file, defaults to None
css	str	raw css code, defaults to None
css_file	str	path to css file, defaults to None
base_path	str	base dir for loading resources, defaults to None
background	str	background color code, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
variables	Dict[str, Any]	interpolation variables, defaults to None
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties of QLabel

Basic HTML Render widget

Example:

../examples/ui/widgets.py (Html)

def demo_Html():
    with ui.Dialog("Html"):
        with ui.Col():
            ui.Html(
                background="#ffffff",
                html="""
                <h1>Header</h1>
                <ul>
                    <li>Item 1</li>
                    <li>Item 1</li>
                    <li>Item 1</li>
                </ul>
                <br />
                <p>
                <strong>Be Happy!!</strong>
                </p>
                """
            )

Widget: ImageView

Signature / ImageView

def ImageView(
        uri: str, 
        *, 
        label: str=None, 
        name: str=None, 
        background: Union[str, QColor]=None, 
        add: bool=True, 
        **kwargs
    ) -> ImageViewWidget: ...

Gui / ImageView

Docs / ImageView

Return type	Description
ImageViewWidget	description

Argument	Type	Description
uri	str	path to load the image from
label	str	gui label, defaults to None
name	str	objectName, defaults to None
background	Union[str, QColor]	background color, defaults to None
add	bool	description, defaults to True

Image render widget

Example:

../examples/ui/widgets.py (ImageView)

def demo_ImageView():
    with ui.Dialog("ImageView", size=(400, 300)):
        with ui.Col():
            ui.ImageView(
                str(Path(__file__).parent / 'image.png')
            )

Widget: SvgImageView

Signature / SvgImageView

def SvgImageView(
        uri: str, 
        name: str=None, 
        label: str=None, stretch=0, alignment=Qt.Alignment(), 
        **kwargs
    ) -> SvgImageViewWidget: ...

Gui / SvgImageView

Docs / SvgImageView

Return type	Description
SvgImageViewWidget	The widget

Argument	Type	Description
uri	str	file path if the svg
name	str	Widget name, defaults to None

High resolution Svg Image box

Example:

../examples/ui/widgets.py (SvgImageView)

def demo_SvgImageView():
    with ui.Dialog("SvgImageView"):
        with ui.Col():
            ui.SvgImageView(
                str(Path(__file__).parent / 'vector.svg')
            )

Widget: Table

Signature / Table

def Table(
        headers: List[str], 
        rows: List[List[Any]], 
        *, 
        name: str=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> TableWidget: ...

Gui / Table

Docs / Table

Return type	Description
TableWidget	The table widget

Argument	Type	Description
headers	List[str]	column headers
rows	List[List[Any]]	data
name	str	objectName, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True

Simple Table output widget

Example:

../examples/ui/widgets.py (Table)

def demo_Table():
    with ui.Dialog("Table"):
        with ui.Col():
            ui.Table(
                headers=('Length', '^Width', '>Height'),
                rows=[
                    [21, 34, 56],
                    [65, 87, 98],
                    [21, 32, 54],
                    [65, 76, 87],
                ]
            )

Widget: Canvas

Signature / Canvas

def Canvas(
        paint: Callable[[QWidget, QPainter, QPaintEvent], None], 
        *, 
        setup: Callable[[QWidget, QPainter, QPaintEvent], None]=None, 
        name: str=None, 
        stretch: int=0, 
        width: int=0, 
        height: int=0, 
        **kwargs
    ) -> CanvasWidget: ...

Gui / Canvas

Docs / Canvas

Return type	Description
CanvasWidget	The widget

Argument	Type	Description
paint	Callable[[QWidget, QPainter, QPaintEvent], None]	function to paint
setup	Callable[[QWidget, QPainter, QPaintEvent], None]	function to setup canvas, defaults to None
name	str	objectName, defaults to None
stretch	int	layout stretch, defaults to 0
width	int	minimum width, defaults to 0
height	int	minimum height, defaults to 0

Canvas Widget to allow custom painting

Example:

../examples/ui/widgets.py (Canvas)

def demo_Canvas():

    def render(widget: QWidget, qp: QPainter, ch: ui.CanvasHelper):
        for i in range(10):
            with ch.pen(color=Qt.red, width=1):
                qp.drawRect(QRect(i*10, i*10, 50, 50))
            with ch.pen(color=Qt.darkBlue, width=2):
                qp.drawText(i*10+60, i*10, str(i+1))

    with ui.Dialog("Canvas"):
        ui.Canvas(render, width=300, height=200)

Inputs

Widget: InputBoolean

Signature / InputBoolean

def InputBoolean(
        value: bool=False, 
        *, 
        name: str=None, 
        label: Union[QWidget, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> QCheckBoxExt: ...

Gui / InputBoolean

Docs / InputBoolean

Return type	Description
QCheckBoxExt	The widget

Argument	Type	Description
value	bool	initial value, defaults to False
name	str	objectName, defaults to None
label	Union[QWidget, str]	ui label, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to the gui, defaults to True
**kwargs	Dict[str, Any]	settable QCheckBox properties

Input boolean widget as QCheckBox

Example:

../examples/ui/widgets.py (InputBoolean)

def demo_InputBoolean():
    with ui.Dialog("InputBoolean"):
        val = ui.InputBoolean(label="Are you ok?:", alignment=Qt.AlignCenter)

        @ui.button("Print")
        def btn_print():
            ui.print_log(val.value())

Widget: InputInt

Signature / InputInt

def InputInt(
        value: int=0, 
        *, 
        name: str=None, 
        min: int=0, 
        max: int=None, 
        step: int=1, 
        label: Union[QWidget, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> QSpinBox: ...

Gui / InputInt

Docs / InputInt

Return type	Description
QSpinBox	The input widget

Argument	Type	Description
value	int	initial value, defaults to 0
name	str	objectName, defaults to None
min	int	minimum accepted value, defaults to 0
max	int	maximum accepted value, defaults to None
step	int	spin steps, defaults to 1
label	Union[QWidget, str]	ui label, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Input int widget

Example:

../examples/ui/widgets.py (InputInt)

def demo_InputInt():
    with ui.Dialog("InputInt"):
        val = ui.InputInt(value=5, label="Enter is an int:", alignment=Qt.AlignCenter)

        @ui.button("Print")
        def print_int():
            ui.print_log(val.value())

Widget: InputFloat

Signature / InputFloat

def InputFloat(
        value: float=0.0, 
        *, 
        name: str=None, 
        min: float=0.0, 
        max: float=sys.float_info.max, 
        decimals: int=6, 
        step: float=0.01, 
        label: Union[QWidget, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> QDoubleSpinBox: ...

Gui / InputFloat

Docs / InputFloat

Return type	Description
QDoubleSpinBox	The input widget

Argument	Type	Description
value	float	initial value, defaults to 0.0
name	str	objectName, defaults to None
min	float	minimum accepted value, defaults to 0.0
max	float	maximum accepted value, defaults to sys.float_info.max
decimals	int	decimal digits, defaults to 6
step	float	spin steps, defaults to 0.01
label	Union[QWidget, str]	ui label, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Input float widget

Example:

../examples/ui/widgets.py (InputFloat)

def demo_InputFloat():
    with ui.Dialog("InputFloat"):
        val = ui.InputFloat(value=5.0, label="Enter is a float:", alignment=Qt.AlignCenter)

        @ui.button("Print")
        def print_float():
            ui.print_log(val.value())

Widget: InputFloatList

Signature / InputFloatList

def InputFloatList(
        values: List[float]=None, 
        label: Union[QWidget, str]=None, 
        name: str=None, 
        label_fn: Callable[[int], str]=None, 
        count: int=0, 
        resizable: bool=False, 
        min_count: int=0, 
        add: bool=True, 
        **kwargs
    ): ...

Gui / InputFloatList

Docs / InputFloatList

Return type	Description
InputFloatListWidget	The widget

Argument	Type	Description
values	List[float]	initial values, defaults to None
label	Union[QWidget, str]	ui label, defaults to None
name	str	objectName, defaults to None
label_fn	Callable[[int], str]	label provider (for custom row labels), defaults to None
count	int	number of autogenerated rows, defaults to 0
resizable	bool	allow resizing the list, defaults to False
min_count	int	minimum number of rows, defaults to 0
add	bool	add to the gui, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Widget to accept lists of float numbers.

Example:

../examples/ui/widgets.py (InputFloatList)

def demo_InputFloatList():
    with ui.Dialog("InputFloatList"):
        with ui.Col():
            val = ui.InputFloatList(
                values=[1.0, 2.0, 3.2, 10.5],
                label="Some floats:",
                resizable=True,
            )

            @ui.button("Print")
            def btn_print():
                ui.print_log(val.value())

Widget: InputQuantity

Signature / InputQuantity

def InputQuantity(
        value: Numeric=None, 
        *, 
        name: str=None, 
        min: Numeric=None, 
        max: Numeric=None, 
        step: Numeric=1.0, 
        label: Union[QWidget, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        unit: str=None, 
        obj: object=None, 
        property: str=None, 
        add: bool=True, 
        **kwargs
    ) -> InputQuantityWidget: ...

Gui / InputQuantity

Docs / InputQuantity

Return type	Description
InputQuantityWidget	The widget

Argument	Type	Description
value	Numeric	Initial value, defaults to None
name	str	objectName (Qt), defaults to None
min	Numeric	Minimum accepted value, defaults to None
max	Numeric	Maximum accepted value, defaults to None
step	Numeric	Spin step, defaults to 1.0
label	Union[QWidget, str]	gui label, defaults to None
stretch	int	Layout stretch, defaults to 0
alignment	Qt.Alignment	Layout alignment, defaults to Qt.Alignment()
unit	str	quantity unit (i.e. mm, in, ...), defaults to None
obj	DocumentObject	Object to bind the expression engine, defaults to None
property	str	Property name of the bounded DocumentObject if any, defaults to None
add	bool	Add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Input Quantity Widget with unit and expressions support.

Example:

../examples/ui/widgets.py (InputQuantity)

def demo_InputQuantity():
    App.activeDocument().addObject("Part::Box", "Box1")
    with ui.Dialog("InputQuantity"):
        quantity = ui.InputQuantity(
            label="Length:",
            obj=App.activeDocument().getObject("Box1"),
            property="Length",
            unit="in",
            alignment=Qt.AlignCenter,
        )

        quantity2 = ui.InputQuantity(
            value=5.0, label="Length Free:", unit="in", alignment=Qt.AlignCenter
        )

        @ui.button("Print")
        def print_q():
            ui.print_log(quantity.value(), quantity2.value())

Widget: InputVector

Signature / InputVector

def InputVector(
        label: Union[QWidget, str]=None, 
        value: Union[Tuple, Vector]=(0.0, 0.0, 0.0)
    ) -> InputVectorWrapper: ...

Gui / InputVector

Docs / InputVector

Return type	Description
InputVectorWrapper	The widget

Argument	Type	Description
label	Union[QWidget, str]	ui label, defaults to None
value	Union[Tuple, Vector]	vector value, defaults to (0.0, 0.0, 0.0)

Widget to accept a vector.

Example:

../examples/ui/widgets.py (InputVector)

def demo_InputVector():
    with ui.Dialog("InputVector"):
        with ui.Col():
            val = ui.InputVector(label="Input vector:")

            @ui.button("Print")
            def btn_print():
                ui.print_log(val.value())

Widget: InputText

Signature / InputText

def InputText(
        value: str='', 
        *, 
        name: str=None, 
        label: Union[QWidget, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> InputTextWidget: ...

Gui / InputText

Docs / InputText

Return type	Description
InputTextWidget	The widget

Argument	Type	Description
value	str	initial value, defaults to ""
name	str	objectName, defaults to None
label	Union[QWidget, str]	gui label, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True
**kwargs	Dict[str, Any]	Qt properties

Input text widget

Example:

../examples/ui/widgets.py (InputText)

def demo_InputText():
    with ui.Dialog("InputText"):
        text = ui.InputText(value="Hello World", label="Some text:", alignment=Qt.AlignCenter)

        @ui.button("Print")
        def print_text():
            ui.print_log(text.value())

Widget: InputOptions

Signature / InputOptions

def InputOptions(
        options: Dict[str, Hashable], 
        value: Hashable=None, 
        label: str=None, 
        name: str=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        **kwargs
    ) -> InputOptionsWidget: ...

Gui / InputOptions

Docs / InputOptions

Return type	Description
InputOptionsWidget	The widget

Argument	Type	Description
options	Dict[str, Hashable]	label to value mapping
value	Hashable	initial value, defaults to None
label	str	gui label, defaults to None
name	str	objectName, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
**kwargs	Dict[str, Any]	Qt properties

ComboBox widget

Example:

../examples/ui/widgets.py (InputOptions)

def demo_InputOptions():
    with ui.Dialog("InputOptions"):
        val = ui.InputOptions(
            options={
                "First": 10,
                "Second": 20,
                "Third": 30,
            },
            value=20,
            label="Select an option:",
            alignment=Qt.AlignCenter,
        )

        @ui.button("Print")
        def print_opt():
            ui.print_log(val.value())

Widget: InputSelectOne

Signature / InputSelectOne

def InputSelectOne(
        label: str=None, 
        name: str=None, 
        active: bool=False, 
        auto_deactivate: bool=True
    ): ...

Gui / InputSelectOne

Docs / InputSelectOne

Argument	Type	Description
label	str	gui label, defaults to None
name	str	objectName, defaults to None
active	bool	activated by default, defaults to False
auto_deactivate	bool	description, defaults to True

3D Selection widget. Allows to pick an object

Example:

../examples/ui/widgets.py (InputSelectOne)

def demo_InputSelectOne():
    with ui.Dialog("InputSelectOne", modal=False):
        val = ui.InputSelectOne(label="Pick one object from the 3D view:")

        @ui.button("Print")
        def print_sel():
            ui.print_log(val.value())

Widget: InputSelectMany

Signature / InputSelectMany

def InputSelectMany(label: str=None, name: str=None, active: bool=False): ...

Gui / InputSelectMany

Docs / InputSelectMany

Argument	Type	Description
label	str	gui label, defaults to None
name	str	objectName, defaults to None
active	bool	active by default or not, defaults to False

3D Multi-Selection Widget.

Example:

../examples/ui/widgets.py (InputSelectMany)

def demo_InputSelectMany():
    with ui.Dialog("InputSelectMany", modal=False):
        val = ui.InputSelectMany(label="Pick one or more objects from the 3D view:")

        @ui.button("Print")
        def print_sel():
            ui.print_log(val.value())

Widget: button

Signature / button

def button(
        label: str=None, 
        *, 
        tool: bool=False, 
        icon: Union[QIcon, str]=None, 
        stretch: int=0, 
        alignment: Qt.Alignment=Qt.Alignment(), 
        add: bool=True, 
        **kwargs
    ) -> QAbstractButton: ...

Gui / button

Docs / button

Return type	Description
QAbstractButton	The widget

Argument	Type	Description
label	str	text of the button, defaults to None
tool	bool	use tool style button, defaults to False
icon	Union[QIcon, str]	icon, defaults to None
stretch	int	layout stretch, defaults to 0
alignment	Qt.Alignment	layout alignment, defaults to Qt.Alignment()
add	bool	add to current context, defaults to True

Button Widget.

Example:

../examples/ui/widgets.py (buttons)

def demo_buttons():
    with ui.Dialog("Buttons", modal=False):

        @ui.button("Button")
        def btn1():
            ui.print_log("Hello btn1")

        @ui.button("Tool Button", tool=True)
        def btn2():
            ui.print_log("Hello btn2")

        @ui.button("Button with icon and text", icon=QIcon(":icons/Std_ViewHome.svg"))
        def btn3():
            ui.print_log("Hello btn3")

        @ui.button(icon=QIcon(":icons/zoom-in.svg"))
        def btn4():
            ui.print_log("Hello btn4")

        @ui.button(icon=QIcon(":icons/zoom-out.svg"), tool=True)
        def btn5():
            ui.print_log("Hello btn4")

Layout tools

Function: Stretch

Signature / Stretch

def Stretch(stretch: int=0) -> None: ...

Docs / Stretch

Argument	Type	Description
stretch	int	0-100 stretch factor, defaults to 0

Adds stretch factor to the current layout

Function: Spacing

Signature / Spacing

def Spacing(size: int) -> None: ...

Docs / Spacing

Argument	Type	Description
size	int	spacing

Adds spacing ro the current layout.