easymacro/docs/source/calc_sheets.rst

Sheets
------

Active sheet
^^^^^^^^^^^^

.. code-block:: python

    doc = app.active
    sheet = doc.active
    app.debug(sheet.name)

|

Get by index
^^^^^^^^^^^^

.. code-block:: python

    doc = app.active
    sheet = doc[0]
    app.debug(sheet.name)

|

Get by name
^^^^^^^^^^^

.. code-block:: python

    doc = app.active
    sheet = doc['Sheet1']
    app.debug(sheet.name)

|

Contains
^^^^^^^^

.. code-block:: python

    doc = app.active
    app.debug('Sheet1' in doc)

|

Get tuple with all names
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    doc = app.active
    app.debug(doc.names)

|

Count
^^^^^

.. code-block:: python

    doc = app.active
    app.debug(len(doc))

|

Iter
^^^^

.. code-block:: python

    doc = app.active
    for sheet in doc:
        app.debug(sheet)

|

New
^^^

Always validate if new name not exists.

.. warning::

    If 'NewSheet' exists, reset it to clean sheet.

.. code-block:: python

    doc = app.active

    doc['NewSheet'] = doc.new_sheet

    # ~ or

    sheet = doc.insert('NewSheet2')

|

Insert multiple, get last insert.

.. code-block:: python

    names = ('One', 'Two', 'Three')
    sheet = doc.insert(names)
    app.debug(sheet.name)

|

Move
^^^^

Move by object to last position.

.. code-block:: python

    sheet = doc[0]
    doc.move(sheet)

Move by name to last position.

.. code-block:: python

    doc.move('Sheet1')

Move to position.

.. code-block:: python

    sheet = doc[0]
    doc.move(sheet, 2)

Move from sheet

.. code-block:: python

    sheet = doc.active
    sheet.move()

Move to position.

.. code-block:: python

    sheet = doc.active
    sheet.move(2)

|

Remove
^^^^^^

Remove by object.

.. note::

    Always should be exists at least one sheet.

.. code-block:: python

    sheet = doc[0]
    doc.remove(sheet)

Remove by name.

.. code-block:: python

    doc.remove('One')

Remove from sheet.

.. code-block:: python

    sheet = doc.active
    sheet.remove()

|

Copy
^^^^

Copy inside the same spreadsheet. Always validate if new name not exists.

* By object

.. code-block:: python

    sheet = doc[0]
    doc.copy_sheet(sheet, 'OtherSheet')

* By name

.. code-block:: python

    doc.copy_sheet('Sheet1', 'Sheet2')

* From sheet

.. code-block:: python

    sheet = doc.active
    sheet.copy(f'{sheet.name}_2')

* If not set new name, automatically get next name free with `name + index`

.. code-block:: python

    sheet = doc.active
    sheet.copy()

|

Copy from
^^^^^^^^^

* Copy sheet from one spreadsheet to other.

.. code-block:: python

    doc = app.active
    doc_source = app.docs['Contacts.ods']
    name_source = 'Names'
    name_target = 'Names'
    position = 0
    doc.copy_from(doc_source, name_source, name_target, position)

* If not set `name_source` and `name_target`, copy all sheet in doc source.

.. code-block:: python

    doc_source = app.docs['Contacts.ods']
    doc.copy_from(doc_source)

|

Copy to
^^^^^^^

* Copy from sheet with the same name

.. code-block:: python

    doc = app.active
    sheet = doc.active
    doc = app.docs.new()
    sheet.copy_to(doc)

* Used new name

.. code-block:: python

    doc = app.active
    sheet = doc.active
    doc = app.docs.new()
    sheet.copy_to(doc, 'NewName')

|


Sort
^^^^

* Sort sheets by names.

.. code-block:: python

    doc = app.active
    doc.sort()

* Sort in reverse.

.. code-block:: python

    doc = app.active
    doc.sort(True)

|

Name
^^^^

Name visible by the user.

.. code-block:: python

    sheet = doc.active
    app.msgbox(sheet.name)
    sheet.name = 'NewName'
    app.msgbox(sheet.name)


Code name
^^^^^^^^^

Only accessible by code.

.. code-block:: python

    sheet = doc.active
    app.msgbox(sheet.code_name)
    sheet.code_name = 'my_name'
    app.msgbox(sheet.code_name)


Visible
^^^^^^^

Apply only with spreadsheet with two or more sheets.

.. code-block:: python

    sheet = doc.active
    app.msgbox(sheet.visible)
    sheet.visible = not sheet.visible
    app.msgbox(sheet.visible)
    sheet.visible = not sheet.visible


Is protected
^^^^^^^^^^^^

If sheet is protected with password.

.. code-block:: python

    sheet = doc.active
    app.msgbox(sheet.is_protected)


Set password
^^^^^^^^^^^^

.. code-block:: python

    sheet = doc.active
    sheet.password = 'letmein'
    app.msgbox(sheet.is_protected)


Remove password
^^^^^^^^^^^^^^^

.. code-block:: python

    sheet = doc.active
    sheet.password = 'letmein'
    app.msgbox(sheet.is_protected)

    sheet.unprotect('letmein')
    app.msgbox(sheet.is_protected)


Tab color
^^^^^^^^^

.. code-block:: python

    sheet = doc.active
    app.msgbox(sheet.color)

    sheet.color = 'red'
    app.msgbox(sheet.color)

    # RGB
    sheet.color = (125, 200, 10)
    app.msgbox(sheet.color)


Document parent
^^^^^^^^^^^^^^^

.. code-block:: python

    doc = sheet.doc
    app.msgbox(doc.title)


Activate
^^^^^^^^

.. code-block:: python

    doc = app.active

    # Get last sheet
    sheet = doc[-1]

    # Activate from sheet
    sheet.activate()

    # Activate from doc
    doc.activate(doc[1])

    # Activate by name
    doc.activate('Sheet3')

|

Events
^^^^^^

* See all the events that can be used.

.. code-block:: python

    sheet = doc.active
    event_names = sheet.events.names
    app.debug(event_names)

* Assing some macro to event.

.. code-block:: python

    def on_select(source):
        app.debug(source.AbsoluteName)
        return

    def main():
        doc = app.active
        sheet = doc.active

        events = sheet.events
        if 'OnSelect' in events:
            macro = {'library': 'test', 'name': 'on_select'}
            events['OnSelect'] = macro

        return

* Remove

.. code-block:: python

    events['OnSelect'] = {}

* Or

.. code-block:: python

    events.remove('OnSelect')