Skip to content

Commit

Permalink
docs: add cmap and QSearchableTreeWidget to docs (#199)
Browse files Browse the repository at this point in the history
  • Loading branch information
tlambert03 authored Sep 12, 2023
1 parent bace50f commit df2034d
Show file tree
Hide file tree
Showing 11 changed files with 193 additions and 8 deletions.
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,4 @@ conda install -c conda-forge superqt

## Usage

See the [Widgets](./widgets/) and [Utilities](./utilities/) pages for features offered by superqt.
See the [Widgets](./widgets/index.md) and [Utilities](./utilities/index.md) pages for features offered by superqt.
12 changes: 12 additions & 0 deletions docs/utilities/cmap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Colormap utilities

See also:

- [`superqt.QColormapComboBox`](../widgets/qcolormap.md)
- [`superqt.cmap.CmapCatalogComboBox`](../widgets/colormap_catalog.md)

::: superqt.cmap.draw_colormap

::: superqt.cmap.QColormapLineEdit

::: superqt.cmap.QColormapItemDelegate
1 change: 1 addition & 0 deletions docs/utilities/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@
| ----------- | --------------------- |
| [`QMessageHandler`](./qmessagehandler.md) | A context manager to intercept messages from Qt. |
| [`CodeSyntaxHighlight`](./code_syntax_highlight.md) | A `QSyntaxHighlighter` for code syntax highlighting. |
| [`draw_colormap`](./cmap.md) | Function that draws a colormap into any QPaintDevice. |
35 changes: 35 additions & 0 deletions docs/widgets/colormap_catalog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# CmapCatalogComboBox

Searchable `QComboBox` variant that contains the
[entire cmap colormap catalog](https://cmap-docs.readthedocs.io/en/latest/catalog/)

!!! note "requires cmap"

This widget uses the [cmap](https://cmap-docs.readthedocs.io/) library
to provide colormaps. You can install it with:

```shell
# use the `cmap` extra to include colormap support
pip install superqt[cmap]
```

You can limit the colormaps shown by setting the `categories` or
`interpolation` keyword arguments.

```python
from qtpy.QtWidgets import QApplication

from superqt.cmap import CmapCatalogComboBox

app = QApplication([])

catalog_combo = CmapCatalogComboBox(interpolation="linear")
catalog_combo.setCurrentText("viridis")
catalog_combo.show()

app.exec()
```

{{ show_widget(130) }}

{{ show_members('superqt.cmap.CmapCatalogComboBox') }}
3 changes: 3 additions & 0 deletions docs/widgets/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ The following are QWidget subclasses:
| [`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 |
| [`QSearchableTreeWidget`](./qsearchabletreewidget.md) | `QTreeWidget` variant with search field that filters available options |
| [`QColorComboBox`](./qcolorcombobox.md) | `QComboBox` to select from a specified set of colors |
| [`QColormapComboBox`](./qcolormap.md) | `QComboBox` to select from a specified set of colormaps. |

## Frames and containers

Expand Down
27 changes: 27 additions & 0 deletions docs/widgets/qcolorcombobox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# QColorComboBox

`QComboBox` designed to select from a specific set of colors.

```python
from qtpy.QtWidgets import QApplication

from superqt import QColorComboBox

app = QApplication([])

colors = QColorComboBox()
colors.addColors(['red', 'green', 'blue'])

# show an "Add Color" item that opens a QColorDialog when clicked
colors.setUserColorsAllowed(True)

# emits a QColor when changed
colors.currentColorChanged.connect(print)
colors.show()

app.exec_()
```

{{ show_widget(100) }}

{{ show_members('superqt.QColorComboBox') }}
67 changes: 67 additions & 0 deletions docs/widgets/qcolormap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# QColormapComboBox

`QComboBox` variant to select from a specific set of colormaps.

!!! note "requires cmap"

This widget uses the [cmap](https://cmap-docs.readthedocs.io/) library
to provide colormaps. You can install it with:

```shell
# use the `cmap` extra to include colormap support
pip install superqt[cmap]
```

### ColorMapLike objects

Colormaps may be specified in a variety of ways, such as by name (string), an iterable of a color/color-like objects, or as
a [`cmap.Colormap`][] instance. See [cmap documentation for details on
all ColormapLike types](https://cmap-docs.readthedocs.io/en/latest/colormaps/#colormaplike-objects)

### Example

```python
from cmap import Colormap
from qtpy.QtWidgets import QApplication

from superqt import QColormapComboBox

app = QApplication([])

cmap_combo = QColormapComboBox()
# see note above about colormap-like objects
# as names from the cmap catalog
cmap_combo.addColormaps(["viridis", "plasma", "magma", "gray"])
# as a sequence of colors, linearly interpolated
cmap_combo.addColormap(("#0f0", "slateblue", "#F3A003A0"))
# as a `cmap.Colormap` instance with custom name:
cmap_combo.addColormap(Colormap(("green", "white", "orange"), name="MyMap"))

cmap_combo.show()
app.exec()
```

{{ show_widget(200) }}

### Style Customization

Note that both the LineEdit and the dropdown can be styled to have the colormap
on the left, or fill the entire width of the widget.

To make the CombBox label colormap fill the entire width of the widget:

```python
from superqt.cmap import QColormapLineEdit
cmap_combo.setLineEdit(QColormapLineEdit())
```

To make the CombBox dropdown colormaps fill
less than the entire width of the widget:

```python
from superqt.cmap import QColormapItemDelegate
delegate = QColormapItemDelegate(fractional_colormap_width=0.33)
cmap_combo.setItemDelegate(delegate)
```

{{ show_members('superqt.QColormapComboBox') }}
37 changes: 37 additions & 0 deletions docs/widgets/qsearchabletreewidget.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# QSearchableTreeWidget

`QSearchableTreeWidget` combines a
[`QTreeWidget`](https://doc.qt.io/qt-6/qtreewidget.html) and a `QLineEdit` for showing a mapping that can be searched by key.

This is intended to be used with a read-only mapping and be conveniently created
using `QSearchableTreeWidget.fromData(data)`. If the mapping changes, the
easiest way to update this is by calling `setData`.


```python
from qtpy.QtWidgets import QApplication

from superqt import QSearchableTreeWidget

app = QApplication([])

data = {
"none": None,
"str": "test",
"int": 42,
"list": [2, 3, 5],
"dict": {
"float": 0.5,
"tuple": (22, 99),
"bool": False,
},
}
tree = QSearchableTreeWidget.fromData(data)
tree.show()

app.exec_()
```

{{ show_widget() }}

{{ show_members('superqt.QSearchableTreeWidget') }}
7 changes: 2 additions & 5 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,7 @@ repo_name: pyapp-kit/superqt
repo_url: https://github.com/pyapp-kit/superqt

# Copyright
copyright: Copyright © 2021 - 2022 Talley Lambert

extra_css:
- stylesheets/extra.css
copyright: Copyright © 2021 - 2022

watch:
- src
Expand Down Expand Up @@ -44,14 +41,14 @@ markdown_extensions:
plugins:
- search
- autorefs
- mkdocstrings
- macros:
module_name: docs/_macros
- mkdocstrings:
handlers:
python:
import:
- https://docs.python.org/3/objects.inv
- https://cmap-docs.readthedocs.io/en/latest/objects.inv
options:
show_source: false
docstring_style: numpy
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ dev = [
"rich",
"types-Pygments",
]
docs = ["mkdocs-macros-plugin", "mkdocs-material", "mkdocstrings[python]"]
docs = ["mkdocs-macros-plugin", "mkdocs-material", "mkdocstrings[python]", "pint", "cmap"]
quantity = ["pint"]
cmap = ["cmap >=0.1.1"]
pyside2 = ["pyside2"]
Expand Down
8 changes: 7 additions & 1 deletion src/superqt/cmap/_cmap_combo.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,13 @@ def userAdditionsAllowed(self) -> bool:
return self._allow_user_colors

def setUserAdditionsAllowed(self, allow: bool) -> None:
"""Sets whether the user can add custom colors."""
"""Sets whether the user can add custom colors.
If enabled, an "Add Colormap..." item will be added to the end of the
list. When clicked, a dialog will be shown to allow the user to select
a colormap from the
[cmap catalog](https://cmap-docs.readthedocs.io/en/latest/catalog/).
"""
self._allow_user_colors = bool(allow)

idx = self.findData(self._add_color_text, Qt.ItemDataRole.DisplayRole)
Expand Down

0 comments on commit df2034d

Please sign in to comment.