mirror of
https://github.com/pyapp-kit/superqt.git
synced 2026-01-04 19:31:24 +01:00
Docs (#124)
* wip * wip * more wip * progress * more docs * more changes * add link * more examples and improvements * fix check-manifest * sort members * remove autogen images * remove _images * add font docs * add link to utils
This commit is contained in:
Talley Lambert
GitHub
144
docs/_macros.py
Normal file
144
docs/_macros.py
Normal file
@@ -0,0 +1,144 @@
|
||||
import sys
|
||||
from enum import EnumMeta
|
||||
from importlib import import_module
|
||||
from pathlib import Path
|
||||
from textwrap import dedent
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from jinja2 import pass_context
|
||||
from qtpy.QtCore import QObject, Signal
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from mkdocs_macros.plugin import MacrosPlugin
|
||||
|
||||
EXAMPLES = Path(__file__).parent.parent / "examples"
|
||||
IMAGES = Path(__file__).parent / "_auto_images"
|
||||
IMAGES.mkdir(exist_ok=True, parents=True)
|
||||
|
||||
|
||||
def define_env(env: "MacrosPlugin"):
|
||||
@env.macro
|
||||
@pass_context
|
||||
def show_widget(context, width: int = 500) -> list[Path]:
|
||||
# extract all fenced code blocks starting with "python"
|
||||
page = context["page"]
|
||||
dest = IMAGES / f"{page.title}.png"
|
||||
if "build" in sys.argv:
|
||||
dest.unlink(missing_ok=True)
|
||||
|
||||
codeblocks = [
|
||||
b[6:].strip()
|
||||
for b in page.markdown.split("```")
|
||||
if b.startswith("python")
|
||||
]
|
||||
src = codeblocks[0].strip()
|
||||
src = src.replace(
|
||||
"QApplication([])", "QApplication.instance() or QApplication([])"
|
||||
)
|
||||
src = src.replace("app.exec_()", "")
|
||||
|
||||
exec(src)
|
||||
_grab(dest, width)
|
||||
return f"{{ loading=lazy; width={width} }}\n\n"
|
||||
|
||||
@env.macro
|
||||
def show_members(cls: str):
|
||||
# import class
|
||||
module, name = cls.rsplit(".", 1)
|
||||
_cls = getattr(import_module(module), name)
|
||||
|
||||
first_q = next(
|
||||
(
|
||||
b.__name__
|
||||
for b in _cls.__mro__
|
||||
if issubclass(b, QObject) and ".Qt" in b.__module__
|
||||
),
|
||||
None,
|
||||
)
|
||||
|
||||
inherited_members = set()
|
||||
for base in _cls.__mro__:
|
||||
if issubclass(base, QObject) and ".Qt" in base.__module__:
|
||||
inherited_members.update(
|
||||
{k for k in dir(base) if not k.startswith("_")}
|
||||
)
|
||||
|
||||
new_signals = {
|
||||
k
|
||||
for k, v in vars(_cls).items()
|
||||
if not k.startswith("_") and isinstance(v, Signal)
|
||||
}
|
||||
|
||||
self_members = {
|
||||
k
|
||||
for k in dir(_cls)
|
||||
if not k.startswith("_") and k not in inherited_members | new_signals
|
||||
}
|
||||
|
||||
enums = []
|
||||
for m in list(self_members):
|
||||
if isinstance(getattr(_cls, m), EnumMeta):
|
||||
self_members.remove(m)
|
||||
enums.append(m)
|
||||
|
||||
out = ""
|
||||
if first_q:
|
||||
url = f"https://doc.qt.io/qt-6/{first_q.lower()}.html"
|
||||
out += f"## Qt Class\n\n<a href='{url}'>`{first_q}`</a>\n\n"
|
||||
|
||||
out += ""
|
||||
|
||||
if new_signals:
|
||||
out += "## Signals\n\n"
|
||||
for sig in new_signals:
|
||||
out += f"### `{sig}`\n\n"
|
||||
|
||||
if enums:
|
||||
out += "## Enums\n\n"
|
||||
for e in enums:
|
||||
out += f"### `{_cls.__name__}.{e}`\n\n"
|
||||
for m in getattr(_cls, e):
|
||||
out += f"- `{m.name}`\n\n"
|
||||
|
||||
if self_members:
|
||||
|
||||
out += dedent(
|
||||
f"""
|
||||
## Methods
|
||||
|
||||
::: {cls}
|
||||
options:
|
||||
heading_level: 3
|
||||
show_source: False
|
||||
show_inherited_members: false
|
||||
show_signature_annotations: True
|
||||
members: {sorted(self_members)}
|
||||
docstring_style: numpy
|
||||
show_bases: False
|
||||
show_root_toc_entry: False
|
||||
show_root_heading: False
|
||||
"""
|
||||
)
|
||||
|
||||
return out
|
||||
|
||||
|
||||
def _grab(dest: str | Path, width) -> list[Path]:
|
||||
"""Grab the top widgets of the application."""
|
||||
from qtpy.QtCore import QTimer
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
w = QApplication.topLevelWidgets()[-1]
|
||||
w.setFixedWidth(width)
|
||||
w.activateWindow()
|
||||
w.setMinimumHeight(40)
|
||||
w.grab().save(str(dest))
|
||||
|
||||
# hack to make sure the object is truly closed and deleted
|
||||
while True:
|
||||
QTimer.singleShot(10, w.deleteLater)
|
||||
QApplication.processEvents()
|
||||
try:
|
||||
w.parent()
|
||||
except RuntimeError:
|
||||
return
|
||||
@@ -1,68 +0,0 @@
|
||||
# ComboBox
|
||||
|
||||
|
||||
## Enum Combo Box
|
||||
|
||||
`QEnumComboBox` is a variant of [`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html)
|
||||
that populates the items in the combobox based on a python `Enum` class. In addition to all
|
||||
the methods provided by `QComboBox`, this subclass adds the methods
|
||||
`enumClass`/`setEnumClass` to get/set the current `Enum` class represented by the combobox,
|
||||
and `currentEnum`/`setCurrentEnum` to get/set the current `Enum` member in the combobox.
|
||||
There is also a new signal `currentEnumChanged(enum)` analogous to `currentIndexChanged` and `currentTextChanged`.
|
||||
|
||||
Method like `insertItem` and `addItem` are blocked and try of its usage will end with `RuntimeError`
|
||||
|
||||
```python
|
||||
from enum import Enum
|
||||
|
||||
from superqt import QEnumComboBox
|
||||
|
||||
class SampleEnum(Enum):
|
||||
first = 1
|
||||
second = 2
|
||||
third = 3
|
||||
|
||||
# as usual:
|
||||
# you must create a QApplication before create a widget.
|
||||
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum)
|
||||
```
|
||||
|
||||
other option is to use optional `enum_class` argument of constructor and change
|
||||
```python
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum)
|
||||
```
|
||||
to
|
||||
```python
|
||||
combo = QEnumComboBox(enum_class=SampleEnum)
|
||||
```
|
||||
|
||||
|
||||
### Allow `None`
|
||||
`QEnumComboBox` allow using Optional type annotation:
|
||||
|
||||
```python
|
||||
from enum import Enum
|
||||
|
||||
from superqt import QEnumComboBox
|
||||
|
||||
class SampleEnum(Enum):
|
||||
first = 1
|
||||
second = 2
|
||||
third = 3
|
||||
|
||||
# as usual:
|
||||
# you must create a QApplication before create a widget.
|
||||
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum, allow_none=True)
|
||||
```
|
||||
|
||||
In this case there is added option `----` and `currentEnum` will return `None` for it.
|
||||
|
||||
## QSearchableComboBox
|
||||
|
||||
`QSearchableComboBox` is a variant of [`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that
|
||||
allow to filter list of options by enter part of text. It could be drop in replacement for `QComboBox`.
|
||||
26
docs/faq.md
Normal file
26
docs/faq.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# FAQ
|
||||
|
||||
## Sliders not dragging properly on MacOS 12+
|
||||
|
||||
??? details
|
||||
On MacOS Monterey, with Qt5, there is a bug that causes all sliders
|
||||
(including native Qt sliders) to not respond properly to drag events. See:
|
||||
|
||||
- [https://bugreports.qt.io/browse/QTBUG-98093](https://bugreports.qt.io/browse/QTBUG-98093)
|
||||
- [https://github.com/napari/superqt/issues/74](https://github.com/napari/superqt/issues/74)
|
||||
|
||||
Superqt includes a workaround for this issue, but it is not perfect, and it requires using a custom stylesheet (which may interfere with your own styles). Note that you
|
||||
may not see this issue if you're already using custom stylesheets.
|
||||
|
||||
To opt in to the workaround, do any of the following:
|
||||
|
||||
- set the environment variable `USE_MAC_SLIDER_PATCH=1` before importing superqt
|
||||
(note: this is safe to use even if you're targeting more than just MacOS 12, it will only be applied when needed)
|
||||
- call the `applyMacStylePatch()` method on any of the superqt slider subclasses (note, this will override your slider styles)
|
||||
- apply the stylesheet manually:
|
||||
|
||||
```python
|
||||
from superqt.sliders import MONTEREY_SLIDER_STYLES_FIX
|
||||
|
||||
slider.setStyleSheet(MONTEREY_SLIDER_STYLES_FIX)
|
||||
```
|
||||
29
docs/index.md
Normal file
29
docs/index.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# superqt
|
||||
|
||||
##  "missing" widgets and components for PyQt/PySide
|
||||
|
||||
This repository aims to provide high-quality community-contributed Qt widgets
|
||||
and components for [PyQt](https://riverbankcomputing.com/software/pyqt/) &
|
||||
[PySide](https://www.qt.io/qt-for-python) that are not provided in the native
|
||||
QtWidgets module.
|
||||
|
||||
Components are tested on:
|
||||
|
||||
- macOS, Windows, & Linux
|
||||
- Python 3.7 and above
|
||||
- PyQt5 (5.11 and above) & PyQt6
|
||||
- PySide2 (5.11 and above) & PySide6
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install superqt
|
||||
```
|
||||
|
||||
```bash
|
||||
conda install -c conda-forge superqt
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
See the [Widgets](./widgets/) and [Utilities](./utilities/) pages for features offered by superqt.
|
||||
@@ -1,8 +0,0 @@
|
||||
# ListWidget
|
||||
|
||||
## QSearchableListWidget
|
||||
|
||||
`QSearchableListWidget` is a variant of [`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) that add text entry above list widget that allow to filter list
|
||||
of available options.
|
||||
|
||||
Because of implementation it does not inherit directly from `QListWidget` but satisfy it all api. The only limitation is that it cannot be used as argument of `QListWidgetItem` constructor.
|
||||
257
docs/sliders.md
257
docs/sliders.md
@@ -1,257 +0,0 @@
|
||||
# Sliders
|
||||
|
||||
|
||||
|
||||
|
||||
- `QRangeSlider` inherits from [`QSlider`](https://doc.qt.io/qt-5/qslider.html)
|
||||
and attempts to match the Qt API as closely as possible
|
||||
- Uses platform-specific styles (for handle, groove, & ticks) but also supports
|
||||
QSS style sheets.
|
||||
- Supports mouse wheel and keypress (soon) events
|
||||
- Supports more than 2 handles (e.g. `slider.setValue([0, 10, 60, 80])`)
|
||||
|
||||
*Note: There is a Qt5 Bug that affects sliders in MacOS 12+, see fix at bottom of page.*
|
||||
|
||||
## Range Slider
|
||||
|
||||
```python
|
||||
from superqt import QRangeSlider
|
||||
|
||||
# as usual:
|
||||
# you must create a QApplication before create a widget.
|
||||
range_slider = QRangeSlider()
|
||||
```
|
||||
|
||||
As `QRangeSlider` inherits from `QtWidgets.QSlider`, you can use all of the
|
||||
same methods available in the [QSlider API](https://doc.qt.io/qt-5/qslider.html). The major difference is that `value` and `sliderPosition` are reimplemented as `tuples` of `int` (where the length of the tuple is equal to the number of handles in the slider.)
|
||||
|
||||
### `value: Tuple[int, ...]`
|
||||
|
||||
This property holds the current value of all handles in the slider.
|
||||
|
||||
The slider forces all values to be within the legal range:
|
||||
`minimum <= value <= maximum`.
|
||||
|
||||
Changing the value also changes the sliderPosition.
|
||||
|
||||
##### Access Functions:
|
||||
|
||||
```python
|
||||
range_slider.value() -> Tuple[int, ...]
|
||||
```
|
||||
|
||||
```python
|
||||
range_slider.setValue(val: Sequence[int]) -> None
|
||||
```
|
||||
|
||||
##### Notifier Signal:
|
||||
|
||||
```python
|
||||
valueChanged(Tuple[int, ...])
|
||||
```
|
||||
|
||||
### `sliderPosition: Tuple[int, ...]`
|
||||
|
||||
This property holds the current slider positions. It is a `tuple` with length equal to the number of handles.
|
||||
|
||||
If [tracking](https://doc.qt.io/qt-5/qabstractslider.html#tracking-prop) is enabled (the default), this is identical to [`value`](#value--tupleint-).
|
||||
|
||||
##### Access Functions:
|
||||
|
||||
```python
|
||||
range_slider.sliderPosition() -> Tuple[int, ...]
|
||||
```
|
||||
|
||||
```python
|
||||
range_slider.setSliderPosition(val: Sequence[int]) -> None
|
||||
```
|
||||
|
||||
##### Notifier Signal:
|
||||
|
||||
```python
|
||||
sliderMoved(Tuple[int, ...])
|
||||
```
|
||||
|
||||
### Additional properties
|
||||
|
||||
These options are in addition to the Qt QSlider API, and control the behavior of the bar between handles.
|
||||
|
||||
| getter | setter | type | default | description |
|
||||
| -------------------- | ------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `barIsVisible` | `setBarIsVisible` <br>`hideBar` / `showBar` | `bool` | `True` | <small>Whether the bar between handles is visible.</small> |
|
||||
| `barMovesAllHandles` | `setBarMovesAllHandles` | `bool` | `True` | <small>Whether clicking on the bar moves all handles or just the nearest</small> |
|
||||
| `barIsRigid` | `setBarIsRigid` | `bool` | `True` | <small>Whether bar length is constant or "elastic" when dragging the bar beyond min/max.</small> |
|
||||
------
|
||||
|
||||
### Examples
|
||||
|
||||
These screenshots show `QRangeSlider` (multiple handles) next to the native `QSlider`
|
||||
(single handle). With no styles applied, `QRangeSlider` will match the native OS
|
||||
style of `QSlider` – with or without tick marks. When styles have been applied
|
||||
using [Qt Style Sheets](https://doc.qt.io/qt-5/stylesheet-reference.html), then
|
||||
`QRangeSlider` will inherit any styles applied to `QSlider` (since it inherits
|
||||
from QSlider). If you'd like to style `QRangeSlider` differently than `QSlider`,
|
||||
then you can also target it directly in your style sheet. The one "special"
|
||||
property for QRangeSlider is `qproperty-barColor`, which sets the color of the
|
||||
bar between the handles.
|
||||
|
||||
> The code for these example widgets is [here](../examples/demo_widget.py)
|
||||
<details>
|
||||
|
||||
<summary><em>See style sheet used for this example</em></summary>
|
||||
|
||||
```css
|
||||
/*
|
||||
Because QRangeSlider inherits from QSlider, it will also inherit styles
|
||||
*/
|
||||
QSlider {
|
||||
min-height: 20px;
|
||||
}
|
||||
|
||||
QSlider::groove:horizontal {
|
||||
border: 0px;
|
||||
background: qlineargradient(x1:0, y1:0, x2:1, y2:1,
|
||||
stop:0 #777, stop:1 #aaa);
|
||||
height: 20px;
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
QSlider::handle {
|
||||
background: qradialgradient(cx:0, cy:0, radius: 1.2, fx:0.5,
|
||||
fy:0.5, stop:0 #eef, stop:1 #000);
|
||||
height: 20px;
|
||||
width: 20px;
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
/*
|
||||
"QSlider::sub-page" is the one exception ...
|
||||
(it styles the area to the left of the QSlider handle)
|
||||
*/
|
||||
QSlider::sub-page:horizontal {
|
||||
background: #447;
|
||||
border-top-left-radius: 10px;
|
||||
border-bottom-left-radius: 10px;
|
||||
}
|
||||
|
||||
/*
|
||||
for QRangeSlider: use "qproperty-barColor". "sub-page" will not work.
|
||||
*/
|
||||
QRangeSlider {
|
||||
qproperty-barColor: #447;
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
#### macOS
|
||||
|
||||
##### Catalina
|
||||
|
||||
|
||||
|
||||
##### Big Sur
|
||||
|
||||
|
||||
|
||||
#### Windows
|
||||
|
||||
|
||||
|
||||
#### Linux
|
||||
|
||||
|
||||
|
||||
## Labeled Sliders
|
||||
|
||||
This package also includes two "labeled" slider variants. One for `QRangeSlider`, and one for the native `QSlider`:
|
||||
|
||||
### `QLabeledRangeSlider`
|
||||
|
||||
|
||||
|
||||
```python
|
||||
from superqt import QLabeledRangeSlider
|
||||
```
|
||||
|
||||
This has the same API as `QRangeSlider` with the following additional options:
|
||||
|
||||
#### `handleLabelPosition`/`setHandleLabelPosition`
|
||||
|
||||
Where/whether labels are shown adjacent to slider handles.
|
||||
|
||||
**type:** `QLabeledRangeSlider.LabelPosition`
|
||||
|
||||
**default:** `LabelPosition.LabelsAbove`
|
||||
|
||||
*options:*
|
||||
|
||||
- `LabelPosition.NoLabel` (no labels shown adjacent to handles)
|
||||
- `LabelPosition.LabelsAbove`
|
||||
- `LabelPosition.LabelsBelow`
|
||||
- `LabelPosition.LabelsRight` (alias for `LabelPosition.LabelsAbove`)
|
||||
- `LabelPosition.LabelsLeft` (alias for `LabelPosition.LabelsBelow`)
|
||||
|
||||
#### `edgeLabelMode`/`setEdgeLabelMode`
|
||||
|
||||
**type:** `QLabeledRangeSlider.EdgeLabelMode`
|
||||
|
||||
**default:** `EdgeLabelMode.LabelIsRange`
|
||||
|
||||
*options:*
|
||||
|
||||
- `EdgeLabelMode.NoLabel`: no labels shown at slider extremes
|
||||
- `EdgeLabelMode.LabelIsRange`: edge labels shown the min/max values
|
||||
- `EdgeLabelMode.LabelIsValue`: edge labels shown the slider range
|
||||
|
||||
#### fine tuning position of labels:
|
||||
|
||||
If you find that you need to fine tune the position of the handle labels:
|
||||
|
||||
- `QLabeledRangeSlider.label_shift_x`: adjust horizontal label position
|
||||
- `QLabeledRangeSlider.label_shift_y`: adjust vertical label position
|
||||
|
||||
### `QLabeledSlider`
|
||||
|
||||
|
||||
|
||||
```python
|
||||
from superqt import QLabeledSlider
|
||||
```
|
||||
|
||||
(no additional options at this point)
|
||||
|
||||
|
||||
## Float Slider
|
||||
|
||||
just like QSlider, but supports float values
|
||||
|
||||
```python
|
||||
from superqt import QDoubleSlider
|
||||
```
|
||||
|
||||
## Issues
|
||||
|
||||
### MacOS Monterey Slider issue
|
||||
|
||||
On MacOS Monterey, with Qt5, there is a bug that causes all sliders
|
||||
(including native Qt sliders) to not respond properly to drag events. See:
|
||||
|
||||
- https://bugreports.qt.io/browse/QTBUG-98093
|
||||
- https://github.com/napari/superqt/issues/74
|
||||
|
||||
Superqt includes a workaround for this issue, but it is not perfect, and it requires using a custom stylesheet (which may interfere with your own styles). Note that you
|
||||
may not see this issue if you're already using custom stylesheets.
|
||||
|
||||
To opt in to the workaround, do any of the following:
|
||||
|
||||
- set the environment variable `USE_MAC_SLIDER_PATCH=1` before importing superqt
|
||||
(note: this is safe to use even if you're targeting more than just MacOS 12, it will only be applied when needed)
|
||||
- call the `applyMacStylePatch()` method on any of the superqt slider subclasses (note, this will override your slider styles)
|
||||
- apply the stylesheet manually:
|
||||
|
||||
```python
|
||||
from superqt.sliders import MONTEREY_SLIDER_STYLES_FIX
|
||||
|
||||
slider.setStyleSheet(MONTEREY_SLIDER_STYLES_FIX)
|
||||
```
|
||||
52
docs/utilities/code_syntax_highlight.md
Normal file
52
docs/utilities/code_syntax_highlight.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# CodeSyntaxHighlight
|
||||
|
||||
A code highlighter subclass of `QSyntaxHighlighter`
|
||||
that can be used to highlight code in a QTextEdit.
|
||||
|
||||
Code lexer and available styles are from [`pygments`](https://pygments.org/) python library
|
||||
|
||||
List of available languages are available [here](https://pygments.org/languages/).
|
||||
|
||||
List of available styles are available [here](https://pygments.org/styles/).
|
||||
|
||||
## Example
|
||||
|
||||
```python
|
||||
from qtpy.QtGui import QColor, QPalette
|
||||
from qtpy.QtWidgets import QApplication, QTextEdit
|
||||
|
||||
from superqt.utils import CodeSyntaxHighlight
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
text_area = QTextEdit()
|
||||
|
||||
highlight = CodeSyntaxHighlight(text_area.document(), "python", "monokai")
|
||||
|
||||
palette = text_area.palette()
|
||||
palette.setColor(QPalette.Base, QColor(highlight.background_color))
|
||||
text_area.setPalette(palette)
|
||||
text_area.setText(
|
||||
"""from argparse import ArgumentParser
|
||||
|
||||
def main():
|
||||
parser = ArgumentParser()
|
||||
parser.add_argument("name", help="Your name")
|
||||
args = parser.parse_args()
|
||||
print(f"Hello {args.name}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
"""
|
||||
)
|
||||
|
||||
text_area.show()
|
||||
text_area.resize(400, 200)
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.utils.CodeSyntaxHighlight') }}
|
||||
101
docs/utilities/fonticon.md
Normal file
101
docs/utilities/fonticon.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Font icons
|
||||
|
||||
The `superqt.fonticon` module provides a set of utilities for working with font
|
||||
icons such as [Font Awesome](https://fontawesome.com/) or [Material Design
|
||||
Icons](https://materialdesignicons.com/).
|
||||
|
||||
## Basic Example
|
||||
|
||||
```python
|
||||
from fonticon_fa5 import FA5S
|
||||
|
||||
from qtpy.QtCore import QSize
|
||||
from qtpy.QtWidgets import QApplication, QPushButton
|
||||
|
||||
from superqt.fonticon import icon, pulse
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
btn2 = QPushButton()
|
||||
btn2.setIcon(icon(FA5S.smile, color="blue"))
|
||||
btn2.setIconSize(QSize(225, 225))
|
||||
btn2.show()
|
||||
|
||||
app.exec()
|
||||
```
|
||||
|
||||
{{ show_widget(225) }}
|
||||
|
||||
## Font Icon plugins
|
||||
|
||||
Ready-made fonticon packs are available as plugins:
|
||||
|
||||
### [Font Awesome 5](https://fontawesome.com/v5/search)
|
||||
|
||||
```bash
|
||||
pip install fonticon-fontawesome5
|
||||
```
|
||||
|
||||
### [Font Awesome 6](https://fontawesome.com/v6/search)
|
||||
|
||||
```bash
|
||||
pip install fonticon-fontawesome6
|
||||
```
|
||||
|
||||
### [Material Design Icons](https://materialdesignicons.com/)
|
||||
|
||||
```bash
|
||||
pip install fonticon-materialdesignicons6
|
||||
```
|
||||
|
||||
### See also
|
||||
|
||||
- <https://github.com/tlambert03/fonticon-bootstrapicons>
|
||||
- <https://github.com/tlambert03/fonticon-linearicons>
|
||||
- <https://github.com/tlambert03/fonticon-feather>
|
||||
|
||||
`superqt.fonticon` is a pluggable system, and font icon packs may use the `"superqt.fonticon"`
|
||||
entry point to register themselves with superqt. See [`fonticon-cookiecutter`](https://github.com/tlambert03/fonticon-cookiecutter) for a template, or look through the following repos for examples:
|
||||
|
||||
- <https://github.com/tlambert03/fonticon-fontawesome6>
|
||||
- <https://github.com/tlambert03/fonticon-fontawesome5>
|
||||
- <https://github.com/tlambert03/fonticon-materialdesignicons6>
|
||||
|
||||
## API
|
||||
|
||||
::: superqt.fonticon.icon
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.setTextIcon
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.font
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.IconOpts
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.addFont
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
## Animations
|
||||
|
||||
the `animation` parameter to `icon()` accepts a subclass of
|
||||
`Animation` that will be
|
||||
|
||||
::: superqt.fonticon.Animation
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.pulse
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.fonticon.spin
|
||||
options:
|
||||
heading_level: 3
|
||||
31
docs/utilities/index.md
Normal file
31
docs/utilities/index.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Utilities
|
||||
|
||||
## Font Icons
|
||||
|
||||
| Object | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`addFont`](./fonticon.md#superqt.fonticon.addFont) | Add an `OTF/TTF` file at to the font registry. |
|
||||
| [`font`](./fonticon.md#superqt.fonticon.font) | Create `QFont` for a given font-icon font family key |
|
||||
| [`icon`](./fonticon.md#superqt.fonticon.icon) | Create a `QIcon` for font-con glyph key |
|
||||
| [`setTextIcon`](./fonticon.md#superqt.fonticon.setTextIcon) | Set text on a `QWidget` to a specific font & glyph. |
|
||||
| [`IconFont`](./fonticon.md#superqt.fonticon.IconFont) | Helper class that provides a standard way to create an `IconFont`. |
|
||||
| [`IconOpts`](./fonticon.md#superqt.fonticon.IconOpts) | Options for rendering an icon |
|
||||
| [`Animation`](./fonticon.md#superqt.fonticon.Animation) | Base class for adding animations to a font-icon. |
|
||||
|
||||
## Threading tools
|
||||
|
||||
| Object | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`ensure_main_thread`](./thread_decorators.md#ensure_main_thread) | Decorator that ensures a function is called in the main `QApplication` thread. |
|
||||
| [`ensure_object_thread`](./thread_decorators.md#ensure_object_thread) | Decorator that ensures a `QObject` method is called in the object's thread. |
|
||||
| [`FunctionWorker`](./threading.md#superqt.utils.FunctionWorker) | `QRunnable` with signals that wraps a simple long-running function. |
|
||||
| [`GeneratorWorker`](./threading.md#superqt.utils.GeneratorWorker) | `QRunnable` with signals that wraps a long-running generator. |
|
||||
| [`create_worker`](./threading.md#superqt.utils.create_worker) | Create a worker to run a target function in another thread. |
|
||||
| [`thread_worker`](./threading.md#superqt.utils.thread_worker) | Decorator for `create_worker`, turn a function into a worker. |
|
||||
|
||||
## Miscellaneous
|
||||
|
||||
| Object | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`QMessageHandler`](./qmessagehandler.md) | A context manager to intercept messages from Qt. |
|
||||
| [`CodeSyntaxHighlight`](./code_syntax_highlight.md) | A `QSyntaxHighlighter` for code syntax highlighting. |
|
||||
8
docs/utilities/qmessagehandler.md
Normal file
8
docs/utilities/qmessagehandler.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# QMessageHandler
|
||||
|
||||
::: superqt.utils.QMessageHandler
|
||||
options:
|
||||
heading_level: 3
|
||||
show_signature_annotations: True
|
||||
docstring_style: numpy
|
||||
show_bases: False
|
||||
@@ -1,18 +1,24 @@
|
||||
# Decorators
|
||||
|
||||
## Move to thread decorators
|
||||
# Threading decorators
|
||||
|
||||
`superqt` provides two decorators that help to ensure that given function is
|
||||
running in the desired thread:
|
||||
|
||||
* `ensure_main_thread` - ensures that the decorated function/method runs in the main thread
|
||||
* `ensure_object_thread` - ensures that a decorated bound method of a `QObject` runs in the
|
||||
thread in which the instance lives ([qt
|
||||
documentation](https://doc.qt.io/qt-5/threads-qobject.html#accessing-qobject-subclasses-from-other-threads)).
|
||||
## `ensure_main_thread`
|
||||
|
||||
`ensure_main_thread` ensures that the decorated function/method runs in the main thread
|
||||
|
||||
## `ensure_object_thread`
|
||||
|
||||
`ensure_object_thread` ensures that a decorated bound method of a `QObject` runs
|
||||
in the thread in which the instance lives ([see qt documentation for
|
||||
details](https://doc.qt.io/qt-5/threads-qobject.html#accessing-qobject-subclasses-from-other-threads)).
|
||||
|
||||
## Usage
|
||||
|
||||
By default, functions are executed asynchronously (they return immediately with
|
||||
an instance of
|
||||
[`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future)).
|
||||
|
||||
To block and wait for the result, see [Synchronous mode](#synchronous-mode)
|
||||
|
||||
```python
|
||||
@@ -57,12 +63,14 @@ As can be seen in this example these decorators can also be used for setters.
|
||||
These decorators should not be used as replacement of Qt Signals but rather to
|
||||
interact with Qt objects from non Qt code.
|
||||
|
||||
### Synchronous mode
|
||||
## Synchronous mode
|
||||
|
||||
If you'd like for the program to block and wait for the result of your function
|
||||
call, use the `await_return=True` parameter, and optionally specify a timeout.
|
||||
|
||||
> *Note: Using synchronous mode may significantly impact performance.*
|
||||
!!! important
|
||||
|
||||
Using synchronous mode may significantly impact performance.
|
||||
|
||||
```python
|
||||
from superqt import ensure_main_thread
|
||||
36
docs/utilities/threading.md
Normal file
36
docs/utilities/threading.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Thread workers
|
||||
|
||||
The objects in this module provide utilities for running tasks in a separate
|
||||
thread. In general (with the exception of `new_worker_qthread`), everything
|
||||
here wraps Qt's [QRunnable API](https://doc.qt.io/qt-6/qrunnable.html).
|
||||
|
||||
The highest level object is the
|
||||
[`@thread_worker`][superqt.utils.thread_worker] decorator. It was originally
|
||||
written for `napari`, and was later extracted into `superqt`. You may also be
|
||||
interested in reading the [napari
|
||||
documentation](https://napari.org/stable/guides/threading.html#threading-in-napari-with-thread-worker) on this feature,
|
||||
which provides a more in-depth/introductory usage guide.
|
||||
|
||||
For additional control, you can create your own
|
||||
[`FunctionWorker`][superqt.utils.FunctionWorker] or
|
||||
[`GeneratorWorker`][superqt.utils.GeneratorWorker] objects.
|
||||
|
||||
::: superqt.utils.WorkerBase
|
||||
|
||||
::: superqt.utils.FunctionWorker
|
||||
|
||||
::: superqt.utils.GeneratorWorker
|
||||
|
||||
## Convenience functions
|
||||
|
||||
::: superqt.utils.thread_worker
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.utils.create_worker
|
||||
options:
|
||||
heading_level: 3
|
||||
|
||||
::: superqt.utils.new_worker_qthread
|
||||
options:
|
||||
heading_level: 3
|
||||
46
docs/utilities/throttling.md
Normal file
46
docs/utilities/throttling.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Throttling & Debouncing
|
||||
|
||||
These utilities allow you to throttle or debounce a function. This is useful
|
||||
when you have a function that is called multiple times in a short period of
|
||||
time, and you want to make sure it is only "actually" called once (or at least
|
||||
no more than a certain frequency).
|
||||
|
||||
For background on throttling and debouncing, see:
|
||||
|
||||
- <https://blog.openreplay.com/forever-functional-debouncing-and-throttling-for-performance>
|
||||
- <https://css-tricks.com/debouncing-throttling-explained-examples/>
|
||||
|
||||
::: superqt.utils.qdebounced
|
||||
options:
|
||||
show_source: false
|
||||
docstring_style: numpy
|
||||
show_root_toc_entry: True
|
||||
show_root_heading: True
|
||||
|
||||
::: superqt.utils.qthrottled
|
||||
options:
|
||||
show_source: false
|
||||
docstring_style: numpy
|
||||
show_root_toc_entry: True
|
||||
show_root_heading: True
|
||||
|
||||
::: superqt.utils.QSignalDebouncer
|
||||
options:
|
||||
show_source: false
|
||||
docstring_style: numpy
|
||||
show_root_toc_entry: True
|
||||
show_root_heading: True
|
||||
|
||||
::: superqt.utils.QSignalThrottler
|
||||
options:
|
||||
show_source: false
|
||||
docstring_style: numpy
|
||||
show_root_toc_entry: True
|
||||
show_root_heading: True
|
||||
|
||||
::: superqt.utils._throttler.GenericSignalThrottler
|
||||
options:
|
||||
show_source: false
|
||||
docstring_style: numpy
|
||||
show_root_toc_entry: True
|
||||
show_root_heading: True
|
||||
@@ -1,10 +0,0 @@
|
||||
# Utils
|
||||
|
||||
## Code highlighting
|
||||
|
||||
`superqt` provides a code highlighter subclass of `QSyntaxHighlighter`
|
||||
that can be used to highlight code in a QTextEdit.
|
||||
|
||||
Code lexer and available styles are from [`pygments`](https://pygments.org/) python library
|
||||
List of available languages are available [here](https://pygments.org/languages/).
|
||||
List of available styles are available [here](https://pygments.org/styles/).
|
||||
31
docs/widgets/index.md
Normal file
31
docs/widgets/index.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Widgets
|
||||
|
||||
The following are QWidget subclasses:
|
||||
|
||||
## Sliders and Numerical Inputs
|
||||
|
||||
| Widget | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`QDoubleRangeSlider`](./qdoublerangeslider.md) | Multi-handle slider for float values |
|
||||
| [`QDoubleSlider`](./qdoubleslider.md) | Slider for float values |
|
||||
| [`QLabeledDoubleRangeSlider`](./qlabeleddoublerangeslider.md) | `QDoubleRangeSlider` variant with editable labels for each handle |
|
||||
| [`QLabeledDoubleSlider`](./qlabeleddoubleslider.md) | `QSlider` for float values with editable `QSpinBox` with the current value |
|
||||
| [`QLabeledRangeSlider`](./qlabeledrangeslider.md) | `QRangeSlider` variant, with editable labels for each handle |
|
||||
| [`QLabeledSlider`](./qlabeledslider.md) | `QSlider` with editable `QSpinBox` that shows the current value |
|
||||
| [`QLargeIntSpinBox`](./qlargeintspinbox.md) | `QSpinbox` that accepts arbitrarily large integers |
|
||||
| [`QRangeSlider`](./qrangeslider.md) | Multi-handle slider |
|
||||
|
||||
## Labels and categorical inputs
|
||||
|
||||
| Widget | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`QElidingLabel`](./qelidinglabel.md) | A `QLabel` variant that will elide text (add `…`) to fit width. |
|
||||
| [`QEnumComboBox`](./qenumcombobox.md) | `QComboBox` that populates the combobox from a python `Enum` |
|
||||
| [`QSearchableComboBox`](./qsearchablecombobox.md) | `QComboBox` variant that filters available options based on text input |
|
||||
| [`QSearchableListWidget`](./qsearchablelistwidget.md) | `QListWidget` variant with search field that filters available options |
|
||||
|
||||
## Frames and containers
|
||||
|
||||
| Widget | Description |
|
||||
| ----------- | --------------------- |
|
||||
| [`QCollapsible`](./qcollapsible.md) | A collapsible widget to hide and unhide child widgets. |
|
||||
24
docs/widgets/qcollapsible.md
Normal file
24
docs/widgets/qcollapsible.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# QCollapsible
|
||||
|
||||
Collapsible `QFrame` that can be expanded or collapsed by clicking on the header.
|
||||
|
||||
```python
|
||||
from qtpy.QtWidgets import QApplication, QLabel, QPushButton
|
||||
|
||||
from superqt import QCollapsible
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
collapsible = QCollapsible("Advanced analysis")
|
||||
collapsible.addWidget(QLabel("This is the inside of the collapsible frame"))
|
||||
for i in range(10):
|
||||
collapsible.addWidget(QPushButton(f"Content button {i + 1}"))
|
||||
|
||||
collapsible.expand(animate=False)
|
||||
collapsible.show()
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget(350) }}
|
||||
|
||||
{{ show_members('superqt.QCollapsible') }}
|
||||
23
docs/widgets/qdoublerangeslider.md
Normal file
23
docs/widgets/qdoublerangeslider.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# QDoubleRangeSlider
|
||||
|
||||
Float variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QDoubleRangeSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QDoubleRangeSlider(Qt.Orientation.Horizontal)
|
||||
slider.setRange(0, 1)
|
||||
slider.setValue((0.2, 0.8))
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QDoubleRangeSlider') }}
|
||||
23
docs/widgets/qdoubleslider.md
Normal file
23
docs/widgets/qdoubleslider.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# QDoubleSlider
|
||||
|
||||
`QSlider` variant that accepts floating point values.
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QDoubleSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QDoubleSlider(Qt.Orientation.Horizontal)
|
||||
slider.setRange(0, 1)
|
||||
slider.setValue(0.5)
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QDoubleSlider') }}
|
||||
26
docs/widgets/qelidinglabel.md
Normal file
26
docs/widgets/qelidinglabel.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# QElidingLabel
|
||||
|
||||
`QLabel` variant that will elide text (i.e. add an ellipsis)
|
||||
if it is too long to fit in the available space.
|
||||
|
||||
```python
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QElidingLabel
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
widget = QElidingLabel(
|
||||
"a skj skjfskfj sdlf sdfl sdlfk jsdf sdlkf jdsf dslfksdl sdlfk sdf sdl "
|
||||
"fjsdlf kjsdlfk laskdfsal as lsdfjdsl kfjdslf asfd dslkjfldskf sdlkfj"
|
||||
)
|
||||
widget.setWordWrap(True)
|
||||
widget.resize(300, 20)
|
||||
widget.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget(300) }}
|
||||
|
||||
{{ show_members('superqt.QElidingLabel') }}
|
||||
72
docs/widgets/qenumcombobox.md
Normal file
72
docs/widgets/qenumcombobox.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# QEnumComboBox
|
||||
|
||||
`QEnumComboBox` is a variant of
|
||||
[`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that populates the items in
|
||||
the combobox based on a python `Enum` class. In addition to all the methods
|
||||
provided by `QComboBox`, this subclass adds the methods
|
||||
`enumClass`/`setEnumClass` to get/set the current `Enum` class represented by
|
||||
the combobox, and `currentEnum`/`setCurrentEnum` to get/set the current `Enum`
|
||||
member in the combobox. There is also a new signal `currentEnumChanged(enum)`
|
||||
analogous to `currentIndexChanged` and `currentTextChanged`.
|
||||
|
||||
Method like `insertItem` and `addItem` are blocked and try of its usage will end
|
||||
with `RuntimeError`
|
||||
|
||||
```python
|
||||
from enum import Enum
|
||||
|
||||
from qtpy.QtWidgets import QApplication
|
||||
from superqt import QEnumComboBox
|
||||
|
||||
|
||||
class SampleEnum(Enum):
|
||||
first = 1
|
||||
second = 2
|
||||
third = 3
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum)
|
||||
combo.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
Another option is to use optional `enum_class` argument of constructor and change
|
||||
|
||||
```python
|
||||
# option A:
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum)
|
||||
# option B:
|
||||
combo = QEnumComboBox(enum_class=SampleEnum)
|
||||
```
|
||||
|
||||
## Allow `None`
|
||||
|
||||
`QEnumComboBox` also allows using `Optional` type annotation:
|
||||
|
||||
```python
|
||||
from enum import Enum
|
||||
|
||||
from superqt import QEnumComboBox
|
||||
|
||||
class SampleEnum(Enum):
|
||||
first = 1
|
||||
second = 2
|
||||
third = 3
|
||||
|
||||
# as usual:
|
||||
# you must create a QApplication before create a widget.
|
||||
|
||||
combo = QEnumComboBox()
|
||||
combo.setEnumClass(SampleEnum, allow_none=True)
|
||||
```
|
||||
|
||||
In this case there is added option `----` and the `currentEnum()` method will
|
||||
return `None` when it is selected.
|
||||
|
||||
{{ show_members('superqt.QEnumComboBox') }}
|
||||
23
docs/widgets/qlabeleddoublerangeslider.md
Normal file
23
docs/widgets/qlabeleddoublerangeslider.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# QLabeledDoubleRangeSlider
|
||||
|
||||
Labeled Float variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QLabeledDoubleRangeSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QLabeledDoubleRangeSlider(Qt.Orientation.Horizontal)
|
||||
slider.setRange(0, 1)
|
||||
slider.setValue((0.2, 0.8))
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QLabeledDoubleRangeSlider') }}
|
||||
24
docs/widgets/qlabeleddoubleslider.md
Normal file
24
docs/widgets/qlabeleddoubleslider.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# QLabeledDoubleSlider
|
||||
|
||||
[`QDoubleSlider`](./qdoubleslider.md) variant that shows an editable (SpinBox) label next to the slider.
|
||||
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QLabeledDoubleSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QLabeledDoubleSlider(Qt.Orientation.Horizontal)
|
||||
slider.setRange(0, 2.5)
|
||||
slider.setValue(1.3)
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QLabeledDoubleSlider') }}
|
||||
29
docs/widgets/qlabeledrangeslider.md
Normal file
29
docs/widgets/qlabeledrangeslider.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# QLabeledRangeSlider
|
||||
|
||||
Labeled variant of [`QRangeSlider`](qrangeslider.md). (see that page for more details).
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QLabeledRangeSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QLabeledRangeSlider(Qt.Orientation.Horizontal)
|
||||
slider.setValue((20, 80))
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QLabeledRangeSlider') }}
|
||||
|
||||
----
|
||||
|
||||
If you find that you need to fine tune the position of the handle labels:
|
||||
|
||||
- `QLabeledRangeSlider.label_shift_x`: adjust horizontal label position
|
||||
- `QLabeledRangeSlider.label_shift_y`: adjust vertical label position
|
||||
22
docs/widgets/qlabeledslider.md
Normal file
22
docs/widgets/qlabeledslider.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# QLabeledSlider
|
||||
|
||||
`QSlider` variant that shows an editable (SpinBox) label next to the slider.
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QLabeledSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QLabeledSlider(Qt.Orientation.Horizontal)
|
||||
slider.setValue(42)
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QLabeledSlider') }}
|
||||
23
docs/widgets/qlargeintspinbox.md
Normal file
23
docs/widgets/qlargeintspinbox.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# QLargeIntSpinBox
|
||||
|
||||
`QSpinBox` variant that allows to enter large integers, without overflow.
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QLargeIntSpinBox
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QLargeIntSpinBox()
|
||||
slider.setRange(0, 4.53e8)
|
||||
slider.setValue(4.53e8)
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget(150) }}
|
||||
|
||||
{{ show_members('superqt.QLargeIntSpinBox') }}
|
||||
229
docs/widgets/qrangeslider.md
Normal file
229
docs/widgets/qrangeslider.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# QRangeSlider
|
||||
|
||||
A multi-handle slider widget than can be used to
|
||||
select a range of values.
|
||||
|
||||
```python
|
||||
from qtpy.QtCore import Qt
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QRangeSlider
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QRangeSlider(Qt.Orientation.Horizontal)
|
||||
slider.setValue((20, 80))
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
- `QRangeSlider` inherits from [`QSlider`](https://doc.qt.io/qt-5/qslider.html)
|
||||
and attempts to match the Qt API as closely as possible
|
||||
- It uses platform-specific styles (for handle, groove, & ticks) but also supports
|
||||
QSS style sheets.
|
||||
- Supports mouse wheel events
|
||||
- Supports more than 2 handles (e.g. `slider.setValue([0, 10, 60, 80])`)
|
||||
|
||||
As `QRangeSlider` inherits from
|
||||
[`QtWidgets.QSlider`](https://doc.qt.io/qt-5/qslider.html), you can use all of
|
||||
the same methods available in the [QSlider
|
||||
API](https://doc.qt.io/qt-5/qslider.html). The major difference is that `value()`
|
||||
and `sliderPosition()` are reimplemented as `tuples` of `int` (where the length of
|
||||
the tuple is equal to the number of handles in the slider.)
|
||||
|
||||
These options are in addition to the Qt QSlider API, and control the behavior of the bar between handles.
|
||||
|
||||
| getter | setter | type | default | description |
|
||||
| -------------------- | ------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `barIsVisible` | `setBarIsVisible` <br>`hideBar` / `showBar` | `bool` | `True` | <small>Whether the bar between handles is visible.</small> |
|
||||
| `barMovesAllHandles` | `setBarMovesAllHandles` | `bool` | `True` | <small>Whether clicking on the bar moves all handles or just the nearest</small> |
|
||||
| `barIsRigid` | `setBarIsRigid` | `bool` | `True` | <small>Whether bar length is constant or "elastic" when dragging the bar beyond min/max.</small> |
|
||||
|
||||
### Screenshots
|
||||
|
||||
??? title "code that generates the images below"
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
from qtpy import QtCore
|
||||
from qtpy import QtWidgets as QtW
|
||||
|
||||
# patch for Qt 5.15 on macos >= 12
|
||||
os.environ["USE_MAC_SLIDER_PATCH"] = "1"
|
||||
|
||||
from superqt import QRangeSlider # noqa
|
||||
|
||||
QSS = """
|
||||
QSlider {
|
||||
min-height: 20px;
|
||||
}
|
||||
|
||||
QSlider::groove:horizontal {
|
||||
border: 0px;
|
||||
background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #888, stop:1 #ddd);
|
||||
height: 20px;
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
QSlider::handle {
|
||||
background: qradialgradient(cx:0, cy:0, radius: 1.2, fx:0.35,
|
||||
fy:0.3, stop:0 #eef, stop:1 #002);
|
||||
height: 20px;
|
||||
width: 20px;
|
||||
border-radius: 10px;
|
||||
}
|
||||
|
||||
QSlider::sub-page:horizontal {
|
||||
background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #227, stop:1 #77a);
|
||||
border-top-left-radius: 10px;
|
||||
border-bottom-left-radius: 10px;
|
||||
}
|
||||
|
||||
QRangeSlider {
|
||||
qproperty-barColor: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #227, stop:1 #77a);
|
||||
}
|
||||
"""
|
||||
|
||||
Horizontal = QtCore.Qt.Orientation.Horizontal
|
||||
|
||||
|
||||
class DemoWidget(QtW.QWidget):
|
||||
def __init__(self) -> None:
|
||||
super().__init__()
|
||||
|
||||
reg_hslider = QtW.QSlider(Horizontal)
|
||||
reg_hslider.setValue(50)
|
||||
range_hslider = QRangeSlider(Horizontal)
|
||||
range_hslider.setValue((20, 80))
|
||||
multi_range_hslider = QRangeSlider(Horizontal)
|
||||
multi_range_hslider.setValue((11, 33, 66, 88))
|
||||
multi_range_hslider.setTickPosition(QtW.QSlider.TickPosition.TicksAbove)
|
||||
|
||||
styled_reg_hslider = QtW.QSlider(Horizontal)
|
||||
styled_reg_hslider.setValue(50)
|
||||
styled_reg_hslider.setStyleSheet(QSS)
|
||||
styled_range_hslider = QRangeSlider(Horizontal)
|
||||
styled_range_hslider.setValue((20, 80))
|
||||
styled_range_hslider.setStyleSheet(QSS)
|
||||
|
||||
reg_vslider = QtW.QSlider(QtCore.Qt.Orientation.Vertical)
|
||||
reg_vslider.setValue(50)
|
||||
range_vslider = QRangeSlider(QtCore.Qt.Orientation.Vertical)
|
||||
range_vslider.setValue((22, 77))
|
||||
|
||||
tick_vslider = QtW.QSlider(QtCore.Qt.Orientation.Vertical)
|
||||
tick_vslider.setValue(55)
|
||||
tick_vslider.setTickPosition(QtW.QSlider.TicksRight)
|
||||
range_tick_vslider = QRangeSlider(QtCore.Qt.Orientation.Vertical)
|
||||
range_tick_vslider.setValue((22, 77))
|
||||
range_tick_vslider.setTickPosition(QtW.QSlider.TicksLeft)
|
||||
|
||||
szp = QtW.QSizePolicy.Maximum
|
||||
left = QtW.QWidget()
|
||||
left.setLayout(QtW.QVBoxLayout())
|
||||
left.setContentsMargins(2, 2, 2, 2)
|
||||
label1 = QtW.QLabel("Regular QSlider Unstyled")
|
||||
label2 = QtW.QLabel("QRangeSliders Unstyled")
|
||||
label3 = QtW.QLabel("Styled Sliders (using same stylesheet)")
|
||||
label1.setSizePolicy(szp, szp)
|
||||
label2.setSizePolicy(szp, szp)
|
||||
label3.setSizePolicy(szp, szp)
|
||||
left.layout().addWidget(label1)
|
||||
left.layout().addWidget(reg_hslider)
|
||||
left.layout().addWidget(label2)
|
||||
left.layout().addWidget(range_hslider)
|
||||
left.layout().addWidget(multi_range_hslider)
|
||||
left.layout().addWidget(label3)
|
||||
left.layout().addWidget(styled_reg_hslider)
|
||||
left.layout().addWidget(styled_range_hslider)
|
||||
|
||||
right = QtW.QWidget()
|
||||
right.setLayout(QtW.QHBoxLayout())
|
||||
right.setContentsMargins(15, 5, 5, 0)
|
||||
right.layout().setSpacing(30)
|
||||
right.layout().addWidget(reg_vslider)
|
||||
right.layout().addWidget(range_vslider)
|
||||
right.layout().addWidget(tick_vslider)
|
||||
right.layout().addWidget(range_tick_vslider)
|
||||
|
||||
self.setLayout(QtW.QHBoxLayout())
|
||||
self.layout().addWidget(left)
|
||||
self.layout().addWidget(right)
|
||||
self.setGeometry(600, 300, 580, 300)
|
||||
self.activateWindow()
|
||||
self.show()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
dest = Path("screenshots")
|
||||
dest.mkdir(exist_ok=True)
|
||||
|
||||
app = QtW.QApplication([])
|
||||
demo = DemoWidget()
|
||||
|
||||
if "-snap" in sys.argv:
|
||||
import platform
|
||||
|
||||
QtW.QApplication.processEvents()
|
||||
demo.grab().save(str(dest / f"demo_{platform.system().lower()}.png"))
|
||||
else:
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
#### macOS
|
||||
|
||||
##### Catalina
|
||||
|
||||
{ width=580; }
|
||||
|
||||
##### Big Sur
|
||||
|
||||
{ width=580; }
|
||||
|
||||
#### Windows
|
||||
|
||||
|
||||
|
||||
#### Linux
|
||||
|
||||
|
||||
|
||||
|
||||
{{ show_members('superqt.sliders._sliders._GenericRangeSlider') }}
|
||||
|
||||
## Type changes
|
||||
|
||||
Note the following changes in types compared to the `QSlider` API:
|
||||
|
||||
```python
|
||||
value() -> Tuple[int, ...]
|
||||
```
|
||||
|
||||
```python
|
||||
setValue(val: Sequence[int]) -> None
|
||||
```
|
||||
|
||||
```python
|
||||
# Signal
|
||||
valueChanged(Tuple[int, ...])
|
||||
```
|
||||
|
||||
```python
|
||||
sliderPosition() -> Tuple[int, ...]
|
||||
```
|
||||
|
||||
```python
|
||||
setSliderPosition(val: Sequence[int]) -> None
|
||||
```
|
||||
|
||||
```python
|
||||
sliderMoved(Tuple[int, ...])
|
||||
```
|
||||
25
docs/widgets/qsearchablecombobox.md
Normal file
25
docs/widgets/qsearchablecombobox.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# QSearchableComboBox
|
||||
|
||||
`QSearchableComboBox` is a variant of
|
||||
[`QComboBox`](https://doc.qt.io/qt-5/qcombobox.html) that allow to filter list
|
||||
of options by enter part of text. It could be drop in replacement for
|
||||
`QComboBox`.
|
||||
|
||||
|
||||
```python
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QSearchableComboBox
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
combo = QSearchableComboBox()
|
||||
combo.addItems(["foo", "bar", "baz", "foobar", "foobaz", "barbaz"])
|
||||
combo.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QSearchableComboBox') }}
|
||||
28
docs/widgets/qsearchablelistwidget.md
Normal file
28
docs/widgets/qsearchablelistwidget.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# QSearchableListWidget
|
||||
|
||||
`QSearchableListWidget` is a variant of
|
||||
[`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) that add text entry
|
||||
above list widget that allow to filter list of available options.
|
||||
|
||||
Due to implementation details, this widget it does not inherit directly from
|
||||
[`QListWidget`](https://doc.qt.io/qt-5/qlistwidget.html) but it does fully
|
||||
satisfy its api. The only limitation is that it cannot be used as argument of
|
||||
[`QListWidgetItem`](https://doc.qt.io/qt-5/qlistwidgetitem.html) constructor.
|
||||
|
||||
```python
|
||||
from qtpy.QtWidgets import QApplication
|
||||
|
||||
from superqt import QSearchableListWidget
|
||||
|
||||
app = QApplication([])
|
||||
|
||||
slider = QSearchableListWidget()
|
||||
slider.addItems(["foo", "bar", "baz", "foobar", "foobaz", "barbaz"])
|
||||
slider.show()
|
||||
|
||||
app.exec_()
|
||||
```
|
||||
|
||||
{{ show_widget() }}
|
||||
|
||||
{{ show_members('superqt.QSearchableListWidget') }}
|
||||
Reference in New Issue
Block a user