Tools
=====

Remember,  always import library first.

.. code-block:: python

    import easymacro as app


Info from PC
------------

Operate system
^^^^^^^^^^^^^^

.. code-block:: python

    app.msgbox(app.OS)

.. image:: _static/images/tools_01.png


Desktop
^^^^^^^

Name desktop, only GNU/Linux

.. code-block:: python

    app.msgbox(app.DESKTOP)

.. image:: _static/images/tools_02.png


Name PC
^^^^^^^

.. code-block:: python

    app.msgbox(app.PC)

.. image:: _static/images/tools_03.png


Current user
^^^^^^^^^^^^

.. code-block:: python

    app.msgbox(app.USER)

.. image:: _static/images/tools_04.png


Is Windows
^^^^^^^^^^

.. code-block:: python

    app.msgbox(app.IS_WIN)

.. image:: _static/images/tools_05.png


Is Mac
^^^^^^

.. code-block:: python

    app.msgbox(app.IS_MAC)

.. image:: _static/images/tools_05.png


Info from LibO
--------------

Application name
^^^^^^^^^^^^^^^^

.. code-block:: python

    app.msgbox(app.NAME)

.. image:: _static/images/tools_06.png


Version
^^^^^^^

.. code-block:: python

    app.msgbox(app.VERSION)

.. image:: _static/images/tools_07.png


Language
^^^^^^^^

.. code-block:: python

    app.msgbox(app.LANG)

.. image:: _static/images/tools_08.png


Language with variant
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    app.msgbox(app.LANGUAGE)

.. image:: _static/images/tools_09.png


Message Box
-----------

.. code-block:: python

    app.msgbox('Damed World', 'My Macro')

.. image:: _static/images/tools_10.png


Show warning box
----------------

.. code-block:: python

    message = 'Caution, this action is dangerous'
    title = 'My App'
    app.warning(message, title)

.. image:: _static/images/tools_11.png


Show error box
--------------

.. code-block:: python

    message = 'ERROR: Contact technical support'
    title = 'My App'
    app.errorbox(message, title)

.. image:: _static/images/tools_12.png


Make question
-------------

.. code-block:: python

    message = 'Is easy Python?'
    title = 'My App'
    result = app.question(message, title)
    app.msgbox(result)

.. image:: _static/images/tools_13.png


InputBox
^^^^^^^^

* Normal data

.. code-block:: python

    message = 'Type your name'
    default = ''
    title = 'My App'

    result = app.inputbox(message, default, title)
    app.msgbox(result)

* Private data

.. code-block:: python

    message = 'Type your password'
    default = ''
    title = 'My App'
    echochar = "*"

    result = app.inputbox(message, default, title, echochar)
    app.msgbox(result)


Date and times
--------------

Get today
^^^^^^^^^

.. code-block:: python

    d = app.dates
    app.msgbox(d.today)

.. image:: _static/images/tools_14.png


Get now
^^^^^^^

.. code-block:: python

    d = app.dates
    app.msgbox(d.now)

.. image:: _static/images/tools_15.png


Get `Unix Time`_
^^^^^^^^^^^^^^^^

.. code-block:: python

    d = app.dates
    app.msgbox(app.d.epoch)

.. image:: _static/images/tools_16.png


Simple measure time
^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    d = app.dates
    d.start()
    app.sleep(5)
    seconds = d.end()
    app.msgbox(seconds)

.. image:: _static/images/tools_17.png

.. image:: _static/images/tools_18.png


Make date
^^^^^^^^^

.. code-block:: python

    d = app.dates
    date = d.date(1974, 1, 15)
    app.msgbox(date)

.. image:: _static/images/tools_19.png

.. note::

   Start date in Python and Calc is diferent.


String to date
^^^^^^^^^^^^^^

See `Python strftime cheatsheet <https://strftime.org/>`_

.. code-block:: python

    d = app.dates
    str_date = '1974-01-15'
    template = '%Y-%m-%d'
    date = d.str_to_date(str_date, template)
    app.msgbox(type(date))

.. image:: _static/images/tools_20.png

|

For correct date for Calc.

.. code-block:: python

    d = app.dates
    str_date = '1974-01-15'
    template = '%Y-%m-%d'
    date = d.str_to_date(str_date, template, True)
    app.msgbox(type(date))

.. image:: _static/images/tools_21.png


Calc to date
^^^^^^^^^^^^

Get star date in Calc configuration.

.. code-block:: python

    d = app.dates
    cell_value = 1
    date = d.calc_to_date(cell_value)
    app.msgbox(date)

.. image:: _static/images/tools_22.png


Thread
------

You can execute any macro in thread

Normal execution
^^^^^^^^^^^^^^^^

.. code-block:: python

    def show_time(seconds):
        app.sleep(seconds)
        app.msgbox(app.NAME)
        return

    def main(args=None):
        show_time(5)
        app.msgbox('Finish...')
        return

Run in thread
^^^^^^^^^^^^^

.. code-block:: python

    @app.run_in_thread
    def show_time(seconds):
        app.sleep(seconds)
        app.msgbox(app.NAME)
        return

    def main(args=None):
        show_time(5)
        app.msgbox('Finish...')
        return


Dictionary to/from Properties
-----------------------------

.. code-block:: python

    args = {
        'Hidden': True,
        'Password': 'letmein',
    }
    properties = app.dict_to_property(args)

    app.msgbox(properties)

    data = app.data_to_dict(properties)

    app.msgbox(data)


Tuples or lists to dictionary
-----------------------------

.. code-block:: python

    tuple_of_tuples = (
        ('Hidden', True),
        ('Password', 'letmein'),
    )
    data = app.data_to_dict(tuple_of_tuples)
    app.msgbox(data)

    list_of_lists = [
        ['Hidden', True],
        ['Password', 'letmein'],
    ]
    data = app.data_to_dict(list_of_lists)
    app.msgbox(data)


Json
----

Dumps data
^^^^^^^^^^

.. code-block:: python

    data = {
        'Hidden': True,
        'Password': 'letmein',
    }

    json = app.json.dumps(data)

    app.msgbox(json)


Loads data
^^^^^^^^^^

.. code-block:: python

    data = app.json.loads(json)

    app.msgbox(data)


Call Macros
-----------

You can execute any macro, for default call macros Python.

.. code-block:: python

    def show_message():
        app.msgbox(app.INFO_DEBUG)
        return

    def main(args=None):
        args = {
            'library': 'test',
            'name': 'show_message',
        }
        app.macro.call(args)
        return

Of course is better call directly if both macros are the same languaje, but, you can call macro in Basic too.

.. code-block:: vbnet

    Sub show_message()
        MsgBox "Basic from Python"
    End Sub

Call from Python with.

.. code-block:: python

    args = {
        'language': 'Basic',
        'library': 'Standard',
        'module': 'Module1',
        'name': 'show_message',
    }
    app.call_macro(args)

Execute macro in other thread

.. code-block:: python

    app.call_macro(args, True)


Call external program
---------------------

.. code-block:: python

    app_name = 'gnome-calculator'
    app.shell.run(app_name)
    app.debug(app_name)

Call command line and capture output

.. code-block:: python

    args = 'ls -lh ~'
    result = app.shell.run(args, True)
    app.debug(result)

.. code-block:: bash

    21/06/2021 22:27:22 - DEBUG - total 1.3M
    drwxr-xr-x  5 mau mau 4.0K Jun 17 13:09 Desktop
    drwxr-xr-x  6 mau mau 4.0K Jun 15 12:35 Documents
    drwxr-xr-x  2 mau mau 4.0K Jun 21 20:26 Downloads
    drwxr-xr-x  2 mau mau 4.0K Jun 21 16:18 Pictures
    drwxr-xr-x 13 mau mau 4.0K Jun 21 15:34 Projects
    drwxr-xr-x  2 mau mau 4.0K May 11 18:48 Templates
    drwxr-xr-x  2 mau mau 4.0K Jun 20 23:27 Videos

Call command line and capture output line by line.

.. code-block:: python

    args = 'ls -lh /home/mau'
    for line in app.popen(args):
        app.debug(line)

.. code-block:: bash

    21/06/2021 22:34:42 - DEBUG - total 1.3M
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  5 mau mau 4.0K Jun 17 13:09 Desktop
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  6 mau mau 4.0K Jun 15 12:35 Documents
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  2 mau mau 4.0K Jun 21 20:26 Downloads
    21/06/2021 22:34:42 - DEBUG - -rw-r-----  1 mau mau 1.3M Jun 14 11:53 out.png
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  2 mau mau 4.0K Jun 21 16:18 Pictures
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x 13 mau mau 4.0K Jun 21 15:34 Projects
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  2 mau mau 4.0K May 11 18:48 Templates
    21/06/2021 22:34:42 - DEBUG - drwxr-xr-x  2 mau mau 4.0K Jun 20 23:27 Videos


Timer
-----

Only once
^^^^^^^^^

Execute any macro only once in N seconds.

.. code-block:: python

    TIMER_NAME = 'clock'

    def show_time():
        app.debug(app.dates.time)
        return

    def start_clock():
        seconds = 5
        macro = {
            'library': 'test',
            'name': 'show_time',
        }
        app.timer.once(TIMER_NAME, seconds, macro)
        return


    def main(args=None):
        start_clock()
        return


Cancel execution, before start.

.. code-block:: python

    TIMER_NAME = 'clock'

    def show_time():
        app.debug(app.dates.time)
        return

    def start_clock():
        seconds = 60
        macro = {
            'library': 'test',
            'name': 'show_time',
        }
        app.timer.once(TIMER_NAME, seconds, macro)
        return

    def stop_clock():
        app.timer.cancel(TIMER_NAME)
        return


.. code-block:: bash

    26/02/2022 12:23:09 - INFO - Event: "clock", started... execute in 60 seconds
    26/02/2022 12:23:16 - INFO - Cancel event: "clock", ok...


Every seconds
^^^^^^^^^^^^^

Execute any macro every seconds.

.. code-block:: python

    TIMER_NAME = 'clock'

    def show_time():
        app.debug(app.dates.time)
        return

    def start_clock():
        seconds = 1
        macro = {
            'library': 'test',
            'name': 'show_time',
        }
        app.timer.start(TIMER_NAME, seconds, macro)
        return

    def stop_clock():
        app.timer.stop(TIMER_NAME)
        return

    def main(args=None):
        start_clock()
        return

Execute **stop_clock** for stop timer.

.. code-block:: bash

    26/02/2022 11:28:01 - INFO - Timer 'clock' started, execute macro: 'show_time'
    26/02/2022 11:28:02 - DEBUG - 11:28:02
    26/02/2022 11:28:03 - DEBUG - 11:28:03
    ...
    26/02/2022 11:28:08 - DEBUG - 11:28:08
    26/02/2022 11:28:09 - DEBUG - 11:28:09
    26/02/2022 11:28:10 - INFO -    Timer stopped...

.. note::

   Be sure to use a unique name for each timer.

.. warning::

   Be sure to macro for execute not block UI LibO


Get digest
----------

For default get digest in hex

.. code-block:: python

    data = 'LibreOffice with Python'

    digest = app.hash.digest('md5', data)
    app.debug('MD5 = ', digest)

    digest = app.hash.digest('sha1', data)
    app.debug('SHA1 = ', digest)

    digest = app.hash.digest('sha256', data)
    app.debug('SHA256 = ', digest)

    digest = app.hash.digest('sha512', data)
    app.debug('SHA512 = ', digest)

    # Get bytes
    digest = app.hash.digest('md5', data, False)
    app.debug('MD5 = ', digest)

.. code-block:: bash

    26/02/2022 15:57:53 - DEBUG - MD5 =     e0cb96d2c04b26db79dbd30c4d56b555
    26/02/2022 15:57:53 - DEBUG - SHA1 =    7006fb17b7a235245cfc986710a11f10543ae10d
    26/02/2022 15:57:53 - DEBUG - SHA256 =  3fe4586d51fa3e352ec28c05b7e71eaee2e41d5ee78f372c44eeb2f433f7e002
    26/02/2022 15:57:53 - DEBUG - SHA512 =  b6eaea6bc11956eae7f990034ff950eba4b0fe51a577d301272cc8b4c1c603abd36ce852311766e5af2f603d1d96741797b62d4b405459348bacae7ec54e2982
    26/02/2022 15:57:53 - DEBUG - MD5 =     b'\xe0\xcb\x96\xd2\xc0K&\xdby\xdb\xd3\x0cMV\xb5U'


Save and get configurations
---------------------------

You can save any data.

.. code-block:: python

    my_app = 'my_extension'
    data = {
        'path': '/home/mau/work',
        'save_data': True,
    }

    if app.config.set(my_app, data):
        app.msgbox('Save config')

    path = app.config.get(my_app)

    app.msgbox(data)


You can get any key

.. code-block:: python

    path = app.config.get(my_app, 'path')
    app.msgbox(path)


Render string
-------------

.. code-block:: python

    template = """Hello $name

    I send you this $file_name

    Best regards
    """

    data = {'name': 'Ingrid Bergman', 'file_name': 'letter_love.odt'}

    render = app.render(template, data)

    app.msgbox(render)


Simple url open
---------------

Get text data
^^^^^^^^^^^^^

.. code-block:: python

    url = 'https://api.ipify.org'
    result, headers, err = app.url.get(url)
    if err:
        app.error(err)
    else:
        app.debug(type(result), result)
        app.debug(headers)

.. image:: _static/images/tools_23.png

|

Get json data
^^^^^^^^^^^^^

.. code-block:: python

    url = 'https://api.ipify.org?format=json'
    result, headers, err = app.url.get(url, json=True)
    if err:
        app.error(err)
    else:
        app.debug(type(result), result)
        app.debug(headers)

.. image:: _static/images/tools_24.png

|


Color
-----

Look colors that you can used in `web colors`_

.. code-block:: python

    color_name = 'darkblue'
    color = app.color(color_name)
    app.debug(color)

    color_rgb = (125, 200, 10)
    color = app.color(color_rgb)
    app.debug(color)

    color_html = '#008080'
    color = app.color(color_html)
    app.debug(color)


.. _Unix Time: https://en.wikipedia.org/wiki/Unix_time
.. _web colors: https://en.wikipedia.org/wiki/Web_colors