Metadata-Version: 2.4
Name: auto-options-python
Version: 1.1.2
Summary: Manage command options in Python and create QWidgets for them.
Author-email: Volker Baecker <volker.baecker@mri.cnrs.fr>, Clément Benedetti <clement.benedetti@mri.cnrs.fr>
License: MIT License
        
        Copyright (c) 2025 Montpellier Ressources Imagerie
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Bug Tracker, https://github.com/MontpellierRessourcesImagerie/auto-options-python/issues
Project-URL: Documentation, https://montpellierressourcesimagerie.github.io/auto-options-python/
Project-URL: Source Code, https://github.com/MontpellierRessourcesImagerie/auto-options-python
Project-URL: User Support, https://github.com/MontpellierRessourcesImagerie/auto-options-python/issues
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: appdirs
Requires-Dist: qtpy
Requires-Dist: napari
Requires-Dist: pyperclip
Requires-Dist: matplotlib
Dynamic: license-file

# auto-options-python

Mange command options in python and create QWidgets for them.

## Introduction

<figure>
  <img src="https://github.com/user-attachments/assets/ea23f8a5-81d7-4524-90d0-9d5a4daaea63" alt="A simple options dialog" style="width:250", align='center'>
  <figcaption>Fig. 1.1 - A simple dialog created with autooptions</figcaption>
</figure>

Autooptions allows to create options for operations in napari, in a simple way. Autooptions automatically saves and
loads non transient options. It can create a dialog from the options, in which the user can change the values of the
options. It updates combo-boxes containing layers of a given type when layers of that type are added or removed in
napari. The user can provide callbacks that are called when the value of an option changes.

The option types currently supported are:

- Image
- FFT (specific to 3D-toolbox)
- Labels
- Points
- Int
- Float
- Choice
- String
- Boolean

The layer types (FFT, Labels, Points and Image) and Choice will be represented via combo-boxes in the dialog. Boolean
is using a checkbox and the others are using input fields.

The code to create the options-dialog in .1.1 is:

```python
 import napari
 from autooptions.options import Options
 from autooptions.widget import OptionsWidget

 viewer = napari.Viewer()
 options = Options("3D Toolbox", "Convolution")
 options.addImage()
 options.addImage(name="kernel")
 options.addChoice("mode", choices=["same", "valid", "full"])
 options.addChoice("method", choices=["auto", "direct", "fft"])
 options.load()
 widget = OptionsWidget(viewer, options, layout_type="vertical")
 widget.addApplyButton(None)
 viewer.window.add_dock_widget(widget, name=options.optionsName)
```

## Accessing the values of options

You can access the user input of the widgets via the options name:

```python
    print(options.value("image"))
    print(options.value("method"))
```
The shortcut ``getImageLayer``, allows to directly retrieve the layer selected in the widget, without retrieving the name first and then the layer.

```python
kernelLayer = widget.getImageLayer("kernel")
```

## Callbacks

You can register callbacks for options and for buttons. The callback of an option is called when the user input for the option changed. For the predifined buttons ``apply`` and ``ok`` the values are automatically copied from the widget into the option, before the user registered callback is called.

```python
 options = Options("3D Toolbox", "Convolution")
 options.addImage(callback, callback=self.onInputImageChanged)
 self.widget = OptionsWidget(self.viewer, self.options, client=self)
 widget.addApplyButton(self.handleApplyButtonPressed)
```

## Accessing widgets

You can access a widget, for example to check that only valid values can be entered:

```python
    def onInputChanged(self, value):
        if not value.isnumeric():
            self.widget.widgets["size xy"][1].setText(str(self.options.value("size xy")))
```

## Optional options

You can create optional options :) These are displayed with a checkbox to activate/deactivate them. When deactivated the option will be ignored. This allows to avoid the usage of special values in options that indicate for example that the user doesn't want to enter a value for the option in which case a default or on the fly calculated value is used. 

```python
options = Options("Filament Toolbox", "measure_labels")
options.addLabels()
options.addImage(optional=[True, False])
```
``[True, False]`` indicates that the option is optional and by default deactivated. The value of a deactivated option will be ``None``. 

<figure>
  <img src="https://github.com/user-attachments/assets/cd4cdbf3-a626-4c37-b1b5-76481c21cf61" alt="An optional option" style="width:250", align='center'>
  <figcaption>Fig. 1.2 - The image option is optional</figcaption>
</figure>

## Layouts

Currently the ``vertical`` and the ``grid`` layout are supportet. If no layout is specified the grid layout is used. See Fig.1.1 for a vertical layout. 

<figure>
  <img src="https://github.com/user-attachments/assets/7abfa93c-0d02-4bdf-a0fa-ae975bfcbb81" alt="grid layout style="width:250", align='center'>
  <figcaption>Fig. 1.3 - The same option's dialog as in Fig. 1.1, but with a grid layout.</figcaption>
</figure>

```python
import napari
from autooptions.options import Options
from autooptions.widget import OptionsWidget

viewer = napari.Viewer()
options = Options("3D Toolbox", "Convolution")
options.addImage()
options.addImage(name="kernel")
options.addChoice("mode", choices=["same", "valid", "full"])
options.addChoice("method", choices=["auto", "direct", "fft"])
options.load()
widget = OptionsWidget(viewer, options, layout_type="grid")
widget.addApplyButton(None)
viewer.window.add_dock_widget(widget, name=options.optionsName)
```
