AMLibO no8

LibreOffice RefCard

Using The “Macro” (String) Expander Singleton
 Such “macros” have nothing to see with the BASIC macros we’re dealing with in otherparts of this refcard.

LibreOfice BASIC"/singletons/com.sun.star.util.theMacroExpander"and call its ExpandMacros() method:

Runtime Parameters
v. 1.03 – 12/02/2018

Advanficed

Writen using LibreOffice v. 5.3.3 – Platform : All

Knowing LibreOffice Paths
User Files Paths
These paths can be modified in the UI menu Tools > Options > LibreOffice > Paths
Use the PathSettings service:Dim oPaths As Object
Dim Dirs As Variant'directories arrayoPaths = CreateUnoService("com.sun.star.util.PathSettings")
Dirs = Split(oPaths.Xxx, ";")

where Xxx is the property associated to the wanted directory, among:
The property…
… points toAddin
The directory with the old add-ins.
The autocorrection dialog parameters.
AutoCorrect
The autotexts storage directory name.
AutoText
The backup directory name.
BackupHere are the BASIC files used for autopilots.
BasicToolbar icons.
BitmapFichiers de configuration.
ConfigStorage for the provided dictionaries.
Dictionary
Path for storing files bookmarks.
Favorite
Filters storage.
FilterMultimedia and Gallery storage.
Gallery
The directory displayed when a graphic is opened or saved.
Graphic
Path to help files.
Help
Language checking files storage.
Linguistic
Paths to the modules.
ModulePaths to the palettes (.sob to .sof).
PalettePlugins storage paths.
PluginMail or newsgroup files storage (ex : FTP server).
Storage
Base URL to temporary files.
Temp
Template storage directories.
Template
Global directories for configuration files storage.
UIConfig
The user’s configuration parameters directory.
UserConfig
Path to the work directory. Can be modified to follow the user’sWorkneeds.
?
BasePathShareLayer?
BasePathUserLayer

Extension Installation Path
Use the “package provider” singleton:

Dim oContext as Object
Dim oMacroExpand as Object
Dim Result As StringoContext = getProcessServiceManager().DefaultContext
oMacroExpand =oContext.getValueByName("/singletons/com.sun.star.util.theMacroExp
ander")
Result = oMacroExpand.ExpandMacros("$UNO_USER_PACKAGES_CACHE") A “macro” string must start with the $ symbol.
☞ Directory and file names are returned in URL form.

“Macros”
There’re plenty of them. For a full list, see:https://wiki.documentfoundation.org/Development/Environment_variables
and, for the bootstrap file:
ORIGIN
LibreOffice installation directory.
SYSUSERCONFIG
The user’s parameters directory (profile) in his session.
UNO_USER_PACKAGES_CACHE
The extensions directory.
USERNAME
The user’s account name.

Knowing LibreOffice Command-Line Parameters
Here, we only describe the parameters that are useful in macro development mode. A fulllist may be found here (checked 2018/06):
https://dnimruoynepo.blogspot.fr/2016/12/command-line-arguments-in-libreoffice.html
From which these are extracted:Help And Information--version--nstemporarydirectory

where ExtID is the unique identifier for the given extension (ex : "com.company.AName")☞ Path either holds the directory (in URL form) or a zero-length string if not found.
☞ You may also use the strings expander with the UNO_USER_PACKAGES_CACHE macro.

Knowing LibreOffice Execution Parameters
Two complementary services are available: PathSubstitution and MacroExpander.

Using The PathSubstitution Service
Dim oSubst As Object, Result As StringoSubst = CreateUnoService("com.sun.star.util.PathSubstitution")
Result = oSubst.getSubstituteVariableValue("$(var_name)")☞ The substituted variable is a string which format is $(var_name)☞ The result is in URL form.
The variable…
… is a substitute for$(inst)
The LibreOffice installation path.
$(prog)
The soffice program path.
$(user)
The user’s installation path.
$(work)The user’s work directory.
Under Windows, it is My Documents. Under Unix, it is the “home” dir.
$(home)
The user’s directory.
Under Unix, it is the “home” dir.
Under Windows, it is the directory that CSIDL_PERSONAL point to, for
ex : "Documents and Settings\<username>\Documents".
$(temp)
The current temporary directory.
$(path)The contents of the environment PATH variable.
$(username)
The user name for the current session (without domain name under(since LibO 5.2)
Windows).
$(langid)
Then language code LibreOffice uses. Ex : 1036 for French (France).
$(vlang)
The language code LibreOffice uses, in text form. Ex : "fr" for French.

Displays the version number.
(only for MacOS X sandbox)
Returns the temporary directory path for the current user.
Overrides all other arguments.

General Parameters--quickstart[=no]--nolockcheck--infilter={filter}

Disables/Enables the quick starter.
Only one value at the right of “=”:no which disables the quickstart.
Disables check for remote instances using one installation.
Force an input filter type if possible. If it isn’t possible,
LibreOffice uses the available filter for the document.
Example :--infilter="Calc Office Open XML"--infilter="Text (encoded):UTF8,LF,,,"--pidfile={file}--display {display}"/singletons/com.sun.star.deployment.PackageInformationProvider"
Dim oInfo As Object, Path As StringoInfo =GetDefaultContext.getByName("/singletons/com.sun.star.deployment.P
ackageInformationProvider")If Not IsNull(oInfo) Then
Path = oInfo.getPackageLocation(ExtID)
End IfIf (Path <> "") Then Path = Path & "/"'context object'macro expander

Note that filter names may change, these examples show theuse of the argument. Unfortunately, there is no easy way toknow all the available filters.
Store soffice.bin pid in {file}.
Sets the DISPLAY environment variable on UNIX-likeplatforms to the value {display} (only supported by a start
script for the LibreOffice).

UI Control--nologo--minimized--nodefault

Disables the splash screen at program start.
Starts minimized. The splash screen is not displayed.
Starts without displaying anything except the splash screen(do not display initial window).
--invisible
Starts in invisible mode. Neither the start-up logo nor the initialprogram window will be visible. LibreOffice can be controlled,and documents and dialogs can be controlled and opened via
the API. Using the parameter, LibreOffice can only be ended
using the taskmanager (Windows) or the kill command(UNIX-like systems).
--invisible cannot be used with --quickstart.
--headlessStarts in “headless mode” which allows using the application
without GUI. This special mode can be used when theapplication is controlled by external clients via the API.
☞ invisible vs headless.
--invisible does not disable the GUI: documents and dialogs are displayed.
--headless calls a “silent mode” everytime a GUI is not needed.
--norestore
Disables restart and file recovery after a system crash.
--safe-mode
Starts in a safe mode, i.e. starts temporarily with a fresh user
profile and helps to restore a broken configuration.
--accept={UNO-URL}
Specifies an UNO-URL connect-string to create an UNO
acceptor through which other programs can connect to accessthe API.
{UNO-URL} is a string like
uno:connection-type,params;protocolname,params;ObjectName.

--unaccept={UNO-URL}

At the same time, according to the LibreOffice code, theObjectName is ignored.
Closes an acceptor that was created with --accept.
Use --unaccept=all to close all open acceptors.

Developer Parameters--terminate_after_init--eventtesting

Exit after initialization complete (no documents loaded).
Exit after loading documents.

Creating Documents
These arguments create an empty document of the specified kind. Only one of them may
be used in one command line. If filenames are specified after an argument, then it tries toopen those files in the specified component. If it is impossible to open in the selectedcomponent, LibreOffice loads the document.
The options below create empty documents of the specified type:--writer--calc

LibOBasic_08_Params_Flat_A4_EN_v103.odt--draw--impress--base--global--math--web

Opening Files
The arguments define how following filenames are treated. New treatment begins after theargument and ends at the next argument. The default treatment is to open documents forediting, and create new documents from document templates.
-nTreats following files as templates for creation of newdocuments.
-oOpens following files for editing, regardless whether they aretemplates or not.
--pt {Printer}
Prints following files to the printer {Printername}, after whichthose files are closed. The splash screen does not appear. If
used multiple times, only last {Printername} is effective forall documents of all --pt runs.
Also, --printer-name argument of --print-to-file switch
interferes with {Printername}.
-pPrints following files to the default printer, after which thosefiles are closed.
The splash screen does not appear. If the file name contains
spaces, then it must be enclosed in quotation marks.
--viewOpens following files in viewer mode (read-only).
--showOpens and starts the following presentation documents ofeach immediately. Files are closed after the showing.
Files other than Impress documents are opened in default
mode, regardless of previous mode.
--convert-toBatch convert files (implies --headless).
OutExt[:OutFilterName] OutExt : target extension.
[--outdir output_dir] OutFilterName : the conversion filter.
If --outdir isn't specified, then current working directory isused as output_dir.
If --convert-to is used more than once, last value of
OutputFileExtension[:OutputFilterName] is effective.
If --outdir is used more than once, only its last value iseffective.
Examples :-- convert-to pdf *.doc-- convert-to pdf:writer_pdf_Export --outdir/home/user *.doc-- convert-to "html:XHTML Writer File:UTF8" *.doc-- convert-to "txt:Text (encoded):UTF8" *.doc

Unfortunately, now there is no easy way to know all thepossible filter values. Thus, the use of this argument isdifficult, in spite of its potential usefulness.
https://ask.libreoffice.org/en/question/2641/convert-to-command-line-parameter/
points to:https://cgit.freedesktop.org/libreoffice/core/tree/filter/source/config/fragments/filters(checked 2018/06)--print-to-file [-Batch print files to file.
printer-name
If --outdir is not specified, then current working directory is
printer_name] [-used as output_dir.
outdir output_dir]
If --printer-name or --outdir used multiple times, only lastvalue of each is effective.
Also, {Printername} of --pt switch interferes with--printer-name.
--cat
Dump text content of the following files to console (implies--headless).
Cannot be used with --convert-to.
-env:var[=value]
Set a bootstrap variable.
For example: to set a non-default user profile path:

Installing A Macro… By Macro We don’t install a macro, we install a library that contains it.

In A Nutshell
A container file (Writer, Calc, etc.) holds both the macro to install and an installer macro:• The installer macro is stored in the document Standard library,• The macro to install is separated from the installer and stored within its own library.
We’ll install the latter.
☞ Generally, the container file type (Writer, Calc, etc.) is not connected to the macro to install capabilities. Writer is a good container as we may use it to document the process.

The Macro To Install
Store it in its own library in the container document. We’ll install that library.

The Installer Macro
Its purpose is to copy the contained library to the global container My Macros. Here’s an
example of a typical installation process for a code library:
Dim oSrcLib As Object'source library (container document)
Dim oDestLib As Object'target library (in 'My Macros')
Dim i As IntegerDim SrcModules() As String'we create the target library if it doesn' exist yet
If Not GlobalScope.BasicLibraries.hasByName("MyTargetLib") Then
GlobalScope.BasicLibraries.createLibrary("MyTargetLib")
End If'we copy the modules
If BasicLibraries.hasByName("MySourceLib") Then
BasicLibraries.loadLibrary("MySourceLib")
oSrcLib = BasicLibraries.getByName("MySourceLib")oDestLib = GlobalScope.BasicLibraries.getByName("MyTargetLib")
SrcModules = oSrcLib.getElementNames()'installation des modules 1 par 1i = LBound(SrcModules())
Do While (i <= uBound(SrcModules()))
If Not oDestLib.hasByName(SrcModules(i)) ThenoDestLib.insertByName(SrcModules(i), _oSrcLib.getByName(SrcModules(i)))
End Ifi = i + 1Loop
End If☞ To install a dialog library, replace
BasicLibraries with DialogLibraries
and GlobalScope.BasicLibraries with GlobalScope.DialogLibraries.

Beyond Macros: Extensions
The next step would be to turn our macro into an extension for ease of distribution or use.
 This is a difficult task. Bernard Marcelly’s ExtensionCompiler brings much help in that
area: http://berma.pagesperso-orange.fr/Files_en/ExtensionCompiler.ott.

-env:UserInstallation=file:///tmp/test

Unfortunately, now there is no easy way to get all the possible
variables for this flag.

Calling A Macro Through The Command-LineSyntax☞ The --headless option triggers a silent execution (see above).

Calling A Global Macro{soffice} "macro:///library/module/macro[(params)]"

Calling A Macro Stored In An ODF Document{soffice} path/to/doc.odf "macro://./library/module/macro[(params)]"
The {soffice} FormWindows
GNU/Linux%programfiles%\libreoffice 5\program\soffice.exe/opt/LibreOffice 5/program/soffice

Credits
Author: Jean-François Nifenecker – jean-francois.nifenecker@laposte.net
We are like dwarves perched on the shoulders of giants, and thus we are able to see more and farther than thelatter. And this is not at all because of the acuteness of our sight or the stature of our body, but because we arecarried aloft and elevated by the magnitude of the giants. (Bernard of Chartres [attr.])HistoryVersionDate

1.02

23/06/2018

First EN versionComments

1.03

02/12/2018

Minor corrections.

LicenseThis RefCard is distributed under theCreativeCommons BY-SA v3 license
Informations
https://creativecommons.org/licenses/by-sa/3.0/fr/