##################
User Documentation
##################

As ``ipyaladin`` brings the ``Aladin Lite`` software into python notebooks, some commands
are similar to the original software. When this is the case, this documentation might redirect
towards ``Aladin Lite``'s own documentation.

*************************************
Initialization options for the widget
*************************************

The widget is represented by a python class, :py:class:`ipyaladin.widget.Aladin`. This 
class has arguments that allow to chose which buttons or functionalities will be 
available in the widget. These **cannot** be edited later.

Here is a list of options that can be given to ``ipyaladin``:

.. the CSV is generated by conf.py, and grabs all traits with only_init=True don't edit it manually!

.. csv-table:: Initialization options
    :file: init_options.csv
    :header: "Argument";"Default Value";"Description"
    :delim: ;

*****************************
Setting the view's parameters
*****************************

.. nbgallery::
    ../_collections/notebooks/02_Base_Commands
    ../_collections/notebooks/03_Functions
    ../_collections/notebooks/12_Planetary_surveys

*****************************
Adding elements to the widget
*****************************

.. nbgallery::
    ../_collections/notebooks/04_Importing_Tables
    ../_collections/notebooks/05_Display_a_MOC
    ../_collections/notebooks/09_Displaying_Shapes

***************************************************
Retrieving information from the current widget view
***************************************************

.. nbgallery::
    ../_collections/notebooks/11_Extracting_information_from_the_view.ipynb

Note about the WCS
==================

To calculate the WCS, ``ipyaladin`` needs to know its ows size. However, to optimize the
speed of the rendering of notebooks, Jupyter reduces the size of the output of the cells
that are outside of the view. This causes ``ipyaladin`` to calculate WCS with the wrong 
field of view. We raise a ``WidgetReducedError`` in this case. Here are a few
workarounds for this issue:

1. Detaching the widget from the notebook and keeping it on the side of the notebook
------------------------------------------------------------------------------------

In Jupyter notebook, you can right click on the cell where ``ipyaladin`` is displayed,
then chose ``Create new view for cell output`` in the menu. This way, it is never out of
the view (we also find it very practical) and the returned WCS will correspond to the 
view on the side.

.. image:: ../_static/gifs/pop_out_widget.gif

2. Disabling the optimization in the notebook parameters
--------------------------------------------------------

To disable the option that reduces the widget when it is out of the view, you can go to
``Settings``, ``Settings Editor``, ``Notebook``, and set ``Windowing mode`` to ``none``.
This can make your notebook slower if you have a lot of cells.

************
Advanced use
************

``ipyaladin`` can be combined with widgets from the ``ipywidgets`` library to create 
interactive cell outputs.

.. nbgallery::
    ../_collections/notebooks/06_Linked-widgets
    ../_collections/notebooks/07_on-click-callback
    ../_collections/notebooks/08_Rectangular-selection
    ../_collections/notebooks/10_Advanced-GUI