diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index c2d7500494..b1e7482581 100644 --- a/AllLangHelp_sbasic.mk +++ b/AllLangHelp_sbasic.mk @@ -91,6 +91,7 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\ helpcontent2/source/text/sbasic/shared/03/sf_filesystem \ helpcontent2/source/text/sbasic/shared/03/sf_form \ helpcontent2/source/text/sbasic/shared/03/sf_formcontrol \ + helpcontent2/source/text/sbasic/shared/03/sf_intro \ helpcontent2/source/text/sbasic/shared/03/sf_l10n \ helpcontent2/source/text/sbasic/shared/03/sf_platform \ helpcontent2/source/text/sbasic/shared/03/sf_session \ diff --git a/source/text/sbasic/python/main0000.xhp b/source/text/sbasic/python/main0000.xhp index f90781ba0d..76a4e25890 100644 --- a/source/text/sbasic/python/main0000.xhp +++ b/source/text/sbasic/python/main0000.xhp @@ -39,6 +39,7 @@ + diff --git a/source/text/sbasic/shared/03/lib_ScriptForge.xhp b/source/text/sbasic/shared/03/lib_ScriptForge.xhp index 15eb73a56a..86f12534cc 100644 --- a/source/text/sbasic/shared/03/lib_ScriptForge.xhp +++ b/source/text/sbasic/shared/03/lib_ScriptForge.xhp @@ -27,6 +27,7 @@ • Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService + To learn more about how to create and execute Python scripts using the ScriptForge library, read the help page. The described modules and classes are invoked from user scripts as "Services". A generic constructor of those services has been designed for that purpose for each language: GlobalScope.BasicLibraries.LoadLibrary("ScriptForge") diff --git a/source/text/sbasic/shared/03/sf_intro.xhp b/source/text/sbasic/shared/03/sf_intro.xhp new file mode 100644 index 0000000000..525e2680d6 --- /dev/null +++ b/source/text/sbasic/shared/03/sf_intro.xhp @@ -0,0 +1,181 @@ + + + + + + + Creating Python Scripts with ScriptForge + /text/sbasic/shared/03/sf_intro.xhp + + + + + + Python scripts with ScriptForge + +

Creating Python Scripts with ScriptForge

+

Differences between Basic and Python

+ The ScriptForge library is available both for Basic and Python. Most services, methods and properties work identically in both programming languages. However, due to differences in how each language works, ScriptForge users must be aware of some characteristics of the library when using Python: + + + Methods and Property names: In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats. + + + Arguments: All keyword arguments passed on to methods are lowercased. + + + Dates: All date objects are passed and returned as datetime.datetime native Python objects. + + + Arrays: One-dimensional arrays are passed and returned as tuples (which is an immutable object). Two-dimensional arrays are passed and returned as tuples of tuples. + + + None: Python's None keyword is equivalent to Basic's Null, Empty or Nothing. + + + UNO objects: All UNO structures are exchanged between Basic and Python without any changes. + + + Debugging: Whenever an error occurs in Python scripts that use ScriptForge, the error message provided by the Python execution stack displays the line of code that triggered the error. In Basic error messages do not display this information. + + + Visit for more information on Python scripting using %PRODUCTNAME. +

Running Python scripts on %PRODUCTNAME

+ Depending on what you intend to achieve, you may choose one of the following approaches to running Python scripts in %PRODUCTNAME: + + + Run Scripts inside the current %PRODUCTNAME process: Python scripts are executed from within the %PRODUCTNAME process by using the Tools - Macros - Run Macro menu or the APSO extension to call user scripts stored in the Python scripts folder. You can also use the APSO Python shell to interactively run Python scripts. + + + Run Scripts separately from the %PRODUCTNAME process: Python scripts are executed from an external process that connects to an ongoing %PRODUCTNAME process using a socket. + + + If you plan to run scripts from inside the %PRODUCTNAME process, it is recommended to install the APSO (Alternative Script Organizer for Python) extension. However, to develop Python scripts from outside %PRODUCTNAME, you can choose your preferred Python IDE. + +

Running Scripts from inside the %PRODUCTNAME process

+

Using the APSO extension

+ The easiest way to get started with Python scripting in %PRODUCTNAME is by installing the APSO extension. After installing it, open any %PRODUCTNAME component and go to Tools - Macros - Organize Python Scripts. + In APSO's main window go to Menu - Python Shell. + Alternativelly you can open APSO using the default shortcut Alt + Shift + F11. + Now you can start typing Python commands and the shell will print the corresponding output after each line of code is executed. + To start using the ScriptForge library, you need to import the CreateScriptService method, with which you will be able to access the services provided by the library. The example below uses the Basic service to display a message box. + + from scriptforge import CreateScriptService + bas = CreateScriptService("Basic") + bas.MsgBox("Hello!") + + To run the example above, enter each line in the Python shell, one by one, pressing the Enter key after you type each line of code. + Now you can start executing Python commands using any of the ScriptForge services. For example, the code snippet bellow uses the UI service to create a blank writer document. + + ui = CreateScriptService("UI") + doc = ui.CreateDocument("Writer") + + +

Creating Python script files

+ You can create your own Python files and edit them with your preferred text editor. Later you can call them from within any %PRODUCTNAME component. + The first step is to locate where your user scripts are stored. For that, refer to Python Scripts Organization and Location help page. + Now you can create a text file inside your Python user scripts folder, for instance sf_test.py, and start typing your scripts. + Next is a simple example that gets the numeric value from a Calc cell and increments it by 1. Simply type the following code into the sf_test.py file. + + from scriptforge import CreateScriptService + doc = CreateScriptService("Calc") + + def increment_cell(args=None): + value = doc.GetValue("A1") + value += 1 + doc.SetValue("A1", value) + + g_exportedScripts = (increment_cell, ) + + This example creates the increment_cell function. Note that g_exportedScripts is a tuple that tells which functions will be displayed in %PRODUCTNAME as user scripts. + To run this script from within a Calc document: + + + Create or open a Calc file. + + + Enter some numeric value into cell "A1" in the current sheet. + + + Go to Tools - Macros - Run Macros . + + + Choose My Macros - sf_test in the library selector. Then choose the increment_cell function under the Macro Name list. + + + Click Run. Note that the value in cell "A1" was incremented by 1. + + + You can also use APSO to run Python scripts in a similar manner: + + + First open APSO by going to Tools - Macros - Organize Python Scripts. + + + In the macro list, navigate to My Macros - sf_test - increment_cell . + + + Click Execute . + + + +

Running Scripts separately from the %PRODUCTNAME process

+
+

Determining the Installation Path

+ The first step to run scripts from a separate process is to find the folder where %PRODUCTNAME is installed. There are several ways to do that, but ScriptForge provides a quick way to identify your installation path. For that, open APSO's Python shell and type: + + from scriptforge import CreateScriptService + fs = CreateScriptService("FileSystem") + fs.FileNaming = "SYS" + inst_dir = fs.InstallFolder + print(inst_dir) + + The output from the code above is the base directory where %PRODUCTNAME is installed. Now you need to add the "program" subfolder to the resulting path. This is the base folder from which you will run Python scripts from a separate process. + For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts. +
+ +

Start %PRODUCTNAME with socket settings

+ To run Python scripts from a separate process, you need to start %PRODUCTNAME with a few additional options that specify the hostname and port through which the external process will communicate with the %PRODUCTNAME component process. + Open the your operating system's command prompt, navigate to the program folder of your %PRODUCTNAME installation directory and type: + ./soffice --accept='socket,host=localhost,port=2021;urp;' + The command above will start %PRODUCTNAME with a communication channel open so that other processes can exchange messages with it. + Note that the previous example opens %PRODUCTNAME start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows. + ./soffice --writer --accept='socket,host=localhost,port=2021;urp;' + Take note of the host and port parameters, which in this example are localhost and 2021, respectively. + +

Running an External Python Shell

+ Start the Python shell from within the program folder inside your %PRODUCTNAME installation path. Follow the steps above to learn how to find your installation path. + On Linux / Mac OS: + $ cd /usr/lib/libreoffice/program + $ python + On Windows: + $ cd C:\Program Files\LibreOffice\program\ + $ python.exe + This will open the Python shell and now you can start typing commands that will be executed by %PRODUCTNAME. But first you need to set up the socket connection. + + from scriptforge import ScriptForge, CreateScriptService + ScriptForge(hostname='localhost', port=2021) + + The second line of code above defines the host and port settings so that the Python shell can communicate with an ongoing %PRODUCTNAME process opened with the same socket settings. + Now you can run other Python commands and they will be able to communicate with the %PRODUCTNAME process. For example: + + ui = CreateScriptService("UI") + bas = CreateScriptService("Basic") + doc = ui.OpenDocument("~/Documents/myFile.ods") + bas.MsgBox(doc.DocumentType) + + +
+ + + +
+ + diff --git a/source/text/shared/guide/start_parameters.xhp b/source/text/shared/guide/start_parameters.xhp index 248aa8e51a..0e4ca26867 100644 --- a/source/text/shared/guide/start_parameters.xhp +++ b/source/text/shared/guide/start_parameters.xhp @@ -31,7 +31,7 @@ parameters;command line arguments in command line -

Starting $[officename] Software With Parameters

+

Starting $[officename] Software With Parameters

By starting $[officename] software from the command line you can assign various parameters, with which you can influence the performance. The use of command line parameters is only recommended for experienced users. For normal handling, the use of command line parameters is not necessary. A few of the parameters require a deeper knowledge of the technical background of $[officename] software technology.

Starting $[officename] Software From the Command Line