Configuration ============= * Create new extension: ``./zaz.py -new -t ~/projects -n MyGreatExtension`` * Move to new folder: ``cd ~/projects/MyGreatExtension`` * Edit file ``conf.py`` ``vim conf.py`` Parameters ---------- **Configure correctly this options, before you start code your extension.** Only modify this options. Type extension ^^^^^^^^^^^^^^ **TYPE_EXTENSION** The type extension that you want develop. * Integer * 1 = Normal extension * 2 = New components * 3 = Calc addin Example: .. code-block:: python TYPE_EXTENSION = 1 Version ^^^^^^^ **VERSION** * String * The current version of extension, look: `Semantic Versioning`_ Example: .. code-block:: python VERSION = '0.1.0' Name ^^^^ **NAME** * String * Your extension name, not used spaces. Example: .. code-block:: python NAME = 'MyGreatExtension' ID extension ^^^^^^^^^^^^ The internal name for extension. **ID** * String * Should be unique, used URL inverse Example: .. code-block:: python ID = 'org.yourname.extensionname' Locales ^^^^^^^ If your extension will be multi-language (recommended) **USE_LOCALES** * Bool Example: .. code-block:: python USE_LOCALES = True Domain for locales ^^^^^^^^^^^^^^^^^^ The base name for generate files POT **DOMAIN** * String Example: .. code-block:: python DOMAIN = 'base' Path pyGetText ^^^^^^^^^^^^^^ Absolute path for tool `pygettext.py` for generate POT. **PATH_PYGETTEXT** * String Example: .. code-block:: python PATH_PYGETTEXT = '/usr/lib/python3.9/Tools/i18n/pygettext.py' Author ^^^^^^ Your information like author, one or more languages. This information is displayed in the extension manager. **PUBLISHER** * Dictionary Example: .. code-block:: python PUBLISHER = { 'en': {'text': 'Your name', 'link': 'https://your.page'}, 'es': {'text': 'Tu nombre', 'link': 'https://elmau.net'}, } Extension icon ^^^^^^^^^^^^^^ Path relative or absolute to extension logo. Show in extension manager. **ICON** * String Example: .. code-block:: python ICON='images/logo.png' License ^^^^^^^ The license for your extension, please, used free license. **LICENSE** * String Example: .. code-block:: python LICENSE_EN = f"""This file is part of {NAME}. {NAME} is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. {NAME} is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with {NAME}. If not, see . """ LICENSE_ES = LICENSE_EN Information ^^^^^^^^^^^ Information of extension: Display name, description and license to displayed when install. **INFO** * Dictionary Example: .. code-block:: python INFO = { 'en': { 'display_name': 'Test Macro', 'description': 'My great extension', 'license': LICENSE_EN, }, 'es': { 'display_name': 'Macro de Prueba', 'description': 'Mi gran extensión', 'license': LICENSE_ES, }, } Parent menu ^^^^^^^^^^^ Only for normal extension (`TYPE_EXTENSION = 1`), where add extension menu, only two possible values: **AddonMenu** or **OfficeMenuBar** **PARENT** * String * **AddonMenu**: Show in menu Tools->Add-Ons * **OfficeMenuBar**: Show in LibreOffice menu Example: .. code-block:: python PARENT = 'OfficeMenuBar' Main menu ^^^^^^^^^ Only for normal extension (`TYPE_EXTENSION = 1`) and only if parent menu is `OfficeMenuBar`. Can be multi language. **MENU_MAIN** * Dictionary Example: .. code-block:: python MENU_MAIN = { 'en': 'My Extension', 'es': 'Mi Extensión', } Menus ^^^^^ Each menu for show in parent menu. **MENUS** * Tuple of dictionaries * **title** = Label showed, can be multi language. * **argument** = Argument to pass to extension, not use spaces. * **context** = In what applications show, if is blank, show in all. * **icon** = Icon to add, the icon should be in format BMP. The name should be NAME_16.bmp or NAME_26.bmp. Set only NAME in this property. * **toolbar** = It is True, add to new toolbar too, used same icon. * **shortcut** = Shortcut keyboard for this menu. For `Shift+Ctrl+Alt+T` used: `T_SHIFT_MOD1_MOD2` Example: .. code-block:: python MENUS = ( { 'title': {'en': 'Option 1', 'es': 'Opción 1'}, 'argument': 'option1', 'context': 'calc,writer', 'icon': 'icon', 'toolbar': True, 'shortcut': 'T_SHIFT_MOD1_MOD2', }, ) Functions ^^^^^^^^^ Only for Add-in extension (`TYPE_EXTENSION = 2`). Can be multi language. The key of dictionary, is the same name of your function. Used exactly you used in your code. **FUNCTIONS** * Dictionary of dictionaries * **displayname** = Show in function wizard, multi language. * **description** = Show in function wizard, multi language. * **parameters** = Each parameters in your function. * **key** = Is the exactly name for parameter in your code function. * **displayname** = Show in function wizard, multi language. * **description** = Show in function wizard, multi language. Example: .. code-block:: python FUNCTIONS = { 'test': { 'displayname': {'en': 'test', 'es': 'prueba'}, 'description': {'en': 'My test', 'es': 'Mi prueba'}, 'parameters': { 'value': { 'displayname': {'en': 'value', 'es': 'valor'}, 'description': {'en': 'The value', 'es': 'El valor'}, }, }, }, } Default program ^^^^^^^^^^^^^^^ Optional. Open automatically when install and test. **PROGRAM** * String * --calc * --writer * --draw * --impress Example: .. code-block:: python PROGRAM = '--calc' File test ^^^^^^^^^ Optional. Open automatically when install and test. * String Example: .. code-block:: python FILE_TEST = '/home/mau/example.ods' Paths ^^^^^ Paths for install and test. `idlc`, `include` and `remerge` only used en `TYPE_EXTENSION` 2 or 3. `idlc` and path `include` is installed with LibreOffice SDK. **PATHS** * Dictionary * **idlc** for generate files urd. * **include** path with files idl. * **remerge** for generate files rdb. * **soffice** for open LibreOffice. * **install** for install extension. Example: .. code-block:: python PATHS = { 'idlc': '/usr/lib/libreoffice/sdk/bin/idlc', 'include': '/usr/share/idl/libreoffice', 'regmerge': '/usr/lib/libreoffice/program/regmerge', 'soffice': ('soffice', PROGRAM, FILE_TEST), 'install': ('unopkg', 'add', '-v', '-f', '-s'), } .. _Semantic Versioning: https://semver.org/