Skip to content

Commit

Permalink
add missing references to docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@hanjinliu
hanjinliu committed Nov 10, 2024
1 parent 2413873 commit b5c4336
Show file tree
Hide file tree
Showing 6 changed files with 68 additions and 35 deletions.
5 changes: 5 additions & 0 deletions docs/api/type_map.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
magicgui.type_map.register_type
magicgui.type_map.type_registered
magicgui.type_map.type2callback
magicgui.type_map.TypeMap

::: magicgui.type_map.get_widget_class

Expand All @@ -13,3 +14,7 @@
::: magicgui.type_map.type_registered

::: magicgui.type_map.type2callback

::: magicgui.type_map.TypeMap
options:
show_signature_annotations: false
29 changes: 24 additions & 5 deletions docs/api/widgets/bases.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,33 @@ widgets. Therefore, it is worth being aware of the type of widget you are worki
magicgui.widgets.bases.Widget
magicgui.widgets.bases.ButtonWidget
magicgui.widgets.bases.CategoricalWidget
magicgui.widgets.bases.BaseContainerWidget
magicgui.widgets.bases.ContainerWidget
magicgui.widgets.bases.ValuedContainerWidget
magicgui.widgets.bases.DialogWidget
magicgui.widgets.bases.MainWindowWidget
magicgui.widgets.bases.RangedWidget
magicgui.widgets.bases.SliderWidget
magicgui.widgets.bases.ValueWidget
magicgui.widgets.bases.BaseValueWidget

## Class Hierarchy

In visual form, the widget class hierarchy looks like this:

``` mermaid
classDiagram
Widget <|-- ValueWidget
Widget <|-- ContainerWidget
Widget <|-- BaseValueWidget
BaseValueWidget <|-- ValueWidget
Widget <|-- BaseContainerWidget
BackendWidget ..|> WidgetProtocol : implements a
ValueWidget <|-- RangedWidget
ValueWidget <|-- ButtonWidget
ValueWidget <|-- CategoricalWidget
RangedWidget <|-- SliderWidget
BaseContainerWidget <|-- ContainerWidget
BaseContainerWidget <|-- ValuedContainerWidget
BaseValueWidget <|-- ValuedContainerWidget
Widget --* WidgetProtocol : controls a
<<Interface>> WidgetProtocol
class WidgetProtocol {
Expand All @@ -53,12 +60,14 @@ classDiagram
close()
render()
}
class ValueWidget{
class BaseValueWidget{
value: Any
changed: SignalInstance
bind(value, call) Any
unbind()
}
class ValueWidget{
}
class RangedWidget{
value: float | tuple
min: float
Expand All @@ -78,7 +87,7 @@ classDiagram
class CategoricalWidget{
choices: List[Any]
}
class ContainerWidget{
class BaseContainerWidget{
widgets: List[Widget]
labels: bool
layout: str
Expand All @@ -89,12 +98,13 @@ classDiagram
}
click Widget href "#magicgui.widgets.bases.Widget"
click BaseValueWidget href "#magicgui.widgets.bases.BaseValueWidget"
click ValueWidget href "#magicgui.widgets.bases.ValueWidget"
click RangedWidget href "#magicgui.widgets.bases.RangedWidget"
click SliderWidget href "#magicgui.widgets.bases.SliderWidget"
click ButtonWidget href "#magicgui.widgets.bases.ButtonWidget"
click CategoricalWidget href "#magicgui.widgets.bases.CategoricalWidget"
click ContainerWidget href "#magicgui.widgets.bases.ContainerWidget"
click BaseContainerWidget href "#magicgui.widgets.bases.BaseContainerWidget"
```

Expand All @@ -109,9 +119,15 @@ classDiagram
::: magicgui.widgets.bases.CategoricalWidget
options:
heading_level: 3
::: magicgui.widgets.bases.BaseContainerWidget
options:
heading_level: 3
::: magicgui.widgets.bases.ContainerWidget
options:
heading_level: 3
::: magicgui.widgets.bases.ValuedContainerWidget
options:
heading_level: 3
::: magicgui.widgets.bases.DialogWidget
options:
heading_level: 3
Expand All @@ -127,3 +143,6 @@ classDiagram
::: magicgui.widgets.bases.ValueWidget
options:
heading_level: 3
::: magicgui.widgets.bases.BaseValueWidget
options:
heading_level: 3
2 changes: 2 additions & 0 deletions docs/scripts/_hooks.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ def _replace_autosummary(md: str) -> str:
if name:
module, _name = name.rsplit(".", 1)
obj = getattr(import_module(module), _name)
if obj.__doc__ is None:
raise ValueError(f"Missing docstring for {obj}")
table.append(f"| [`{_name}`][{name}] | {obj.__doc__.splitlines()[0]} |")
lines[start:last_line] = table
return "\n".join(lines)
Expand Down
2 changes: 2 additions & 0 deletions src/magicgui/type_map/_type_map.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,8 @@ class MissingWidget(RuntimeError):


class TypeMap:
"""Storage for mapping from types to widgets and callbacks."""

def __init__(
self,
*,
Expand Down
2 changes: 2 additions & 0 deletions src/magicgui/widgets/bases/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ def __init__(
from ._button_widget import ButtonWidget
from ._categorical_widget import CategoricalWidget
from ._container_widget import (
BaseContainerWidget,
ContainerWidget,
DialogWidget,
MainWindowWidget,
Expand All @@ -55,6 +56,7 @@ def __init__(
from ._widget import Widget

__all__ = [
"BaseContainerWidget",
"ButtonWidget",
"CategoricalWidget",
"ContainerWidget",
Expand Down
63 changes: 33 additions & 30 deletions src/magicgui/widgets/bases/_container_widget.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,32 @@ class ValuedContainerKwargs(ContainerKwargs[Widget], Generic[T], total=False):
nullable: bool


class _BaseContainerWidget(Widget, _OrientationMixin, Sequence[WidgetVar]):
class BaseContainerWidget(Widget, _OrientationMixin, Sequence[WidgetVar]):
"""Widget that can contain other widgets.
Wraps a widget that implements
[`ContainerProtocol`][magicgui.widgets.protocols.ContainerProtocol].
Parameters
----------
widgets : Sequence[Widget], optional
A sequence of widgets with which to initialize the container, by default
`None`.
layout : str, optional
The layout for the container. must be one of `{'horizontal',
'vertical'}`. by default "vertical"
scrollable : bool, optional
Whether to enable scroll bars or not. If enabled, scroll bars will
only appear along the layout direction, not in both directions.
labels : bool, optional
Whether each widget should be shown with a corresponding Label widget to the
left, by default `True`. Note: the text for each widget defaults to
`widget.name`, but can be overridden by setting `widget.label`.
**base_widget_kwargs : Any
All additional keyword arguments are passed to the base
[`magicgui.widgets.Widget`][magicgui.widgets.Widget] constructor.
"""

_widget: protocols.ContainerProtocol
_initialized = False
# this is janky ... it's here to allow connections during __init__ by
Expand Down Expand Up @@ -202,7 +227,7 @@ def _pop_widget(self, index: int) -> WidgetVar:


class ValuedContainerWidget(
_BaseContainerWidget[Widget], BaseValueWidget[T], Generic[T]
BaseContainerWidget[Widget], BaseValueWidget[T], Generic[T]
):
"""Container-type ValueWidget."""

Expand All @@ -226,7 +251,7 @@ def __init__(
app = use_app()
assert app.native
base_widget_kwargs["widget_type"] = app.get_obj("Container")
_BaseContainerWidget.__init__(
BaseContainerWidget.__init__(
self,
widgets=widgets,
layout=layout,
Expand All @@ -240,11 +265,8 @@ def __init__(
self.hide()


class ContainerWidget(_BaseContainerWidget[WidgetVar], MutableSequence[WidgetVar]):
"""Widget that can contain other widgets.
Wraps a widget that implements
[`ContainerProtocol`][magicgui.widgets.protocols.ContainerProtocol].
class ContainerWidget(BaseContainerWidget[WidgetVar], MutableSequence[WidgetVar]):
"""Container widget that can insert/remove child widgets.
A `ContainerWidget` behaves like a python list of [Widget][magicgui.widgets.Widget]
objects. Subwidgets can be accessed using integer or slice-based indexing
Expand All @@ -263,25 +285,6 @@ class ContainerWidget(_BaseContainerWidget[WidgetVar], MutableSequence[WidgetVar
For a `ContainerWidget` subclass that is tightly coupled to a specific function
signature (as in the "classic" magicgui decorator), see
[magicgui.widgets.FunctionGui][magicgui.widgets.FunctionGui].
Parameters
----------
widgets : Sequence[Widget], optional
A sequence of widgets with which to initialize the container, by default
`None`.
layout : str, optional
The layout for the container. must be one of `{'horizontal',
'vertical'}`. by default "vertical"
scrollable : bool, optional
Whether to enable scroll bars or not. If enabled, scroll bars will
only appear along the layout direction, not in both directions.
labels : bool, optional
Whether each widget should be shown with a corresponding Label widget to the
left, by default `True`. Note: the text for each widget defaults to
`widget.name`, but can be overridden by setting `widget.label`.
**base_widget_kwargs : Any
All additional keyword arguments are passed to the base
[`magicgui.widgets.Widget`][magicgui.widgets.Widget] constructor.
"""

_widget: protocols.ContainerProtocol
Expand All @@ -307,7 +310,7 @@ def __init__(
**base_widget_kwargs,
)
for widget in self._list:
if isinstance(widget, (BaseValueWidget, _BaseContainerWidget)):
if isinstance(widget, (BaseValueWidget, BaseContainerWidget)):
widget.changed.connect(lambda: self.changed.emit(self))

def __setattr__(self, name: str, value: Any) -> None:
Expand Down Expand Up @@ -366,7 +369,7 @@ def __dir__(self) -> list[str]:

def insert(self, key: int, widget: WidgetVar) -> None:
"""Insert widget at ``key``."""
if isinstance(widget, (BaseValueWidget, _BaseContainerWidget)):
if isinstance(widget, (BaseValueWidget, BaseContainerWidget)):
widget.changed.connect(lambda: self.changed.emit(self))
self._insert_widget(key, widget)

Expand Down Expand Up @@ -437,7 +440,7 @@ def update(
getattr(self, key).value = value
for key, value in kwargs.items():
getattr(self, key).value = value
self.changed.emit()
self.changed.emit(self)

@debounce
def _dump(self, path: str | Path) -> None:
Expand Down

0 comments on commit b5c4336

Please sign in to comment.