diff --git a/docs/index.md b/docs/index.md index c04534ff..d8be1181 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. diff --git a/docs/utilities/cmap.md b/docs/utilities/cmap.md new file mode 100644 index 00000000..06b571dd --- /dev/null +++ b/docs/utilities/cmap.md @@ -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 diff --git a/docs/utilities/index.md b/docs/utilities/index.md index dbe6c356..4ff6ecc5 100644 --- a/docs/utilities/index.md +++ b/docs/utilities/index.md @@ -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. | diff --git a/docs/widgets/colormap_catalog.md b/docs/widgets/colormap_catalog.md new file mode 100644 index 00000000..48da710b --- /dev/null +++ b/docs/widgets/colormap_catalog.md @@ -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') }} diff --git a/docs/widgets/index.md b/docs/widgets/index.md index 6e80a6ec..c3409e7f 100644 --- a/docs/widgets/index.md +++ b/docs/widgets/index.md @@ -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 diff --git a/docs/widgets/qcolorcombobox.md b/docs/widgets/qcolorcombobox.md new file mode 100644 index 00000000..96916651 --- /dev/null +++ b/docs/widgets/qcolorcombobox.md @@ -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') }} diff --git a/docs/widgets/qcolormap.md b/docs/widgets/qcolormap.md new file mode 100644 index 00000000..13004dc7 --- /dev/null +++ b/docs/widgets/qcolormap.md @@ -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') }} diff --git a/docs/widgets/qsearchabletreewidget.md b/docs/widgets/qsearchabletreewidget.md new file mode 100644 index 00000000..a95ebc2c --- /dev/null +++ b/docs/widgets/qsearchabletreewidget.md @@ -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') }} diff --git a/mkdocs.yml b/mkdocs.yml index 8105b863..b53619d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 @@ -44,7 +41,6 @@ markdown_extensions: plugins: - search - autorefs - - mkdocstrings - macros: module_name: docs/_macros - mkdocstrings: @@ -52,6 +48,7 @@ plugins: 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 diff --git a/pyproject.toml b/pyproject.toml index 20f44533..8e3c4a17 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"] diff --git a/src/superqt/cmap/_cmap_combo.py b/src/superqt/cmap/_cmap_combo.py index 65326e44..aa9d78c1 100644 --- a/src/superqt/cmap/_cmap_combo.py +++ b/src/superqt/cmap/_cmap_combo.py @@ -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)