Doc for sheet methods

docs/source/calc_sheets.rst

@@ -0,0 +1,377 @@
+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))
+
+|
+
+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 = app.active_sheet
+    app.msgbox(sheet.name)
+    sheet.name = 'NewName'
+    app.msgbox(sheet.name)
+
+
+Code name
+^^^^^^^^^
+
+* Name only accessible by code.
+
+.. code-block:: python
+
+    sheet = app.active_sheet
+    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 = app.active_sheet
+    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 = app.active_sheet
+    app.msgbox(sheet.is_protected)
+
+
+Set password
+^^^^^^^^^^^^
+
+.. code-block:: python
+
+    sheet = app.active_sheet
+    sheet.password = 'letmein'
+    app.msgbox(sheet.is_protected)
+
+
+Remove password
+^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    sheet = app.active_sheet
+    sheet.password = 'letmein'
+    app.msgbox(sheet.is_protected)
+
+    sheet.unprotect('letmein')
+    app.msgbox(sheet.is_protected)
+
+
+Tab color
+^^^^^^^^^
+
+.. code-block:: python
+
+    sheet = app.active_sheet
+    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
+
+
+Activate
+^^^^^^^^
+
+.. code-block:: python
+
+    doc = app.active
+    # Get last sheet
+    sheet = doc[-1]
+
+    # Activate from doc
+    doc.activate(sheet)
+
+    # Activate from sheet
+    sheet.activate()

docs/source/index.rst

@@ -8,7 +8,7 @@ Welcome to easymacro's documentation!
 
 **easymacro** it's a library for easily develop macros en LibreOffice con Python. It is an abstraction layer between the extensive and complex LibreOffice API UNO and your code.
 
-Probably, your will be more happy if used it. :)
+Probably, you will be more happy if used it. :)
 
 You can used **easymacro** with any extension or directly in your macros.
 

source/easymacro.py

@@ -3370,7 +3370,9 @@ class LODocCalc(LODocument):
 
         `See Api RangeSelectionArguments <https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1sheet_1_1RangeSelectionArguments.html>`_
         """
-        if not args:
+        if args:
+            args['CloseOnMouseRelease'] = args.get('CloseOnMouseRelease', True)
+        else:
             args = dict(
                 Title = 'Please select a range',
                 CloseOnMouseRelease = True)
@@ -3408,6 +3410,10 @@ class LOCalcSheet(object):
     def obj(self):
         return self._obj
 
+    @property
+    def doc(self):
+        return LODocCalc(self.obj.DrawPage.Forms.Parent)
+
     @property
     def name(self):
         return self._obj.Name
@@ -3433,6 +3439,33 @@ class LOCalcSheet(object):
     def is_protected(self):
         return self._obj.isProtected()
 
+    def move(self, pos: int=-1):
+        index = pos
+        if pos < 0:
+            index = len(self.doc)
+        self.doc.move(self.name, index)
+        return
+
+    def remove(self):
+        self.doc.remove(self.name)
+        return
+
+    def copy(self, new_name: str='', pos: int=-1):
+        index = pos
+        if pos < 0:
+            index = len(self.doc)
+        new_sheet = self.doc.copy_sheet(self.name, new_name, index)
+        return new_sheet
+
+    def copy_to(self, doc: Any, target: str='', pos: int=-1):
+        index = pos
+        if pos < 0:
+            index = len(doc)
+
+        new_name = target or self.name
+        sheet = doc.copy_from(self.doc, self.name, new_name, index)
+        return sheet
+
 
 class LOCalcRange(object):
     CELL = 'ScCellObj'