source/text/sbasic/shared/03/sf_document.xhp | 30 ++++++++++---
source/text/sbasic/shared/03/sf_ui.xhp | 62 ++++++++++++++++++++++++---
2 files changed, 80 insertions(+), 12 deletions(-)
New commits:
commit c82b7b47513c4fee5357365b7bd67003a22d86e0
Author: Rafael Lima <rafael.palma.l...@gmail.com>
AuthorDate: Sun Feb 6 23:04:26 2022 +0100
Commit: Alain Romedenne <libreoffici...@gerrit.libreoffice.org>
CommitDate: Wed Feb 9 17:52:38 2022 +0100
Document method RunCommand in ScriptForge
Change-Id: Iebbf6c521c426d55ffebb48265485c5fa8015390
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/129560
Tested-by: Jenkins
Reviewed-by: Alain Romedenne
diff --git a/source/text/sbasic/shared/03/sf_document.xhp
b/source/text/sbasic/shared/03/sf_document.xhp
index 7bef27181..ea735c8be 100644
--- a/source/text/sbasic/shared/03/sf_document.xhp
+++ b/source/text/sbasic/shared/03/sf_document.xhp
@@ -531,29 +531,45 @@
<bookmark_value>Document service;RunCommand</bookmark_value>
</bookmark>
<h2 id="hd_id611589202413141" localize="false">RunCommand</h2>
- <paragraph role="paragraph" id="par_id991589202413257">Runs a command on a
document. The command is executed without arguments.</paragraph>
- <paragraph role="paragraph" id="par_id921611152932311">A few typical
commands are: Save, SaveAs, ExportToPDF, SetDocumentProperties, Undo, Copy,
Paste, etc.</paragraph>
+ <paragraph role="paragraph" id="par_id991589202413257">Runs a UNO command on
the document window associated with the service instance. A few typical
commands are: Save, SaveAs, ExportToPDF, Undo, Copy, Paste, etc.</paragraph>
<paragraph role="paragraph" id="par_id261589202778896" xml-lang="en-US">The
document itself does not need to be active to be able to run
commands.</paragraph>
+ <paragraph role="paragraph" id="par_id921611152932311">Commands can be run
with or without arguments. Arguments are not validated before running the
command. If the command or its arguments are invalid, then nothing will
happen.</paragraph>
+ <tip id="par_id31644182402479">For a complete list of UNO commands that can
be run in %PRODUCTNAME, refer to the Wiki page <link
href="https://wiki.documentfoundation.org/Development/DispatchCommands";
name="Commands_Wiki">Development/DispatchCommands</link>.</tip>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id521622828226683">
- <input>svc.RunCommand(command: str)</input>
+ <input>svc.RunCommand(command: str, [args: any])</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
- <paragraph role="paragraph" id="par_id401589202413575"><emph>command</emph>:
Case-sensitive string containing the command in English. The command itself is
not checked for correctness. If nothing happens after the command call, then
the command is probably wrong.</paragraph>
+ <paragraph role="paragraph" id="par_id401589202413575"><emph>command</emph>:
Case-sensitive string containing the UNO command name. The inclusion of the
prefix ".uno:" in the command is optional. The command itself is not checked
for correctness. If nothing happens after the command call, then the command is
probably wrong.</paragraph>
+ <paragraph role="paragraph" id="par_id521644182774710"><emph>args</emph>:
For each argument to be passed to the command, specify a pair containing the
argument name and value.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
- <paragraph role="paragraph" id="par_id721611153068137">The following example
runs the "SelectData" command in a Calc sheet named "MyFile.ods", which will
result in the selection of the data area based on the currently selected
cell.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
+ <paragraph role="paragraph" id="par_id721611153068137">The following example
runs the <literal>SelectData</literal> command in a Calc file named
"MyFile.ods", which will result in the selection of the data area based on the
currently selected cell. Note that this command does not require any
arguments.</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id401611153339973">Set
oDoc = CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="bascode" localize="false"
id="bas_id121589202413630">oDoc.RunCommand("SelectData")</paragraph>
</bascode>
+ <paragraph role="paragraph" id="par_id371644184276886">Below is an example
that runs the UNO command <literal>ReplaceAll</literal> and passes values for
its arguments <literal>SearchString</literal> and
<literal>ReplaceString</literal>. Running this command will replace all
occurrence of the string "abc" by "ABC" in the current sheet.</paragraph>
+ <bascode>
+ <paragraph role="bascode" id="bas_id631644184414955">' Arguments passed to
the command:</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id621644184336024">'
SearchString = "abc"</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id516441843364240">'
ReplaceString = "ABC"</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id391644184337449">oDoc.RunCommand(".uno:ReplaceAll", "SearchString",
"abc", "ReplaceString", "ABC")</paragraph>
+ </bascode>
+ <paragraph role="paragraph" id="par_id41644184549167">Note that calling the
command <literal>ReplaceAll</literal> without arguments will open the
<menuitem>Find and Replace</menuitem> dialog.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id821622828361025">doc =
CreateScriptService("Document", "MyFile.ods")</paragraph>
<paragraph role="pycode" localize="false"
id="pyc_id211622828361293">doc.RunCommand("SelectData")</paragraph>
</pycode>
- <paragraph role="paragraph" id="par_id751611153375195">The example above
actually runs the UNO command <literal>.uno:SelectData</literal>. Hence, to use
the <literal>RunCommand</literal> method it is necessary to remove the ".uno:"
substring.</paragraph>
- <tip id="par_id191611153511038">Each LibreOffice component has its own set
of commands available. One easy way to learn commands is going to <emph>Tools >
Customize > Keyboard</emph>. When you position your mouse over a function in
the <emph>Function</emph> list, a tooltip will appear with the corresponding
UNO command.</tip>
+ <pycode>
+ <paragraph role="pycode" localize="false"
id="pyc_id661644184648102">doc.RunCommand(".uno:ReplaceAll", "SearchString",
"abc", "ReplaceString", "ABC")</paragraph>
+ </pycode>
+ <paragraph role="paragraph" id="par_id811644243228448">In Python it is also
possible to call <literal>RunCommand</literal> using keyword
arguments:</paragraph>
+ <pycode>
+ <paragraph role="pycode" localize="false"
id="pyc_id301644243318500">doc.RunCommand(".uno:ReplaceAll", SearchString =
"abc", ReplaceString = "ABC")</paragraph>
+ </pycode>
+ <tip id="par_id191611153511038">Each %PRODUCTNAME component has its own set
of commands available. One easy way to learn commands is going to <emph>Tools >
Customize > Keyboard</emph>. When you position your mouse over a function in
the <emph>Function</emph> list, a tooltip will appear with the corresponding
UNO command.</tip>
</section>
<section id="Save">
diff --git a/source/text/sbasic/shared/03/sf_ui.xhp
b/source/text/sbasic/shared/03/sf_ui.xhp
index 03593c7f5..dadd8a3a8 100644
--- a/source/text/sbasic/shared/03/sf_ui.xhp
+++ b/source/text/sbasic/shared/03/sf_ui.xhp
@@ -216,19 +216,20 @@
<link href="text/sbasic/shared/03/sf_ui.xhp#Activate"
name="Activate method">Activate</link><br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#CreateBaseDocument"
name="CreateBaseDocument method">CreateBaseDocument</link><br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#CreateDocument"
name="CreateDocument method">CreateDocument</link> (*)<br/>
- <link href="text/sbasic/shared/03/sf_ui.xhp#GetDocument"
name="GetDocument method">GetDocument</link>
+ <link href="text/sbasic/shared/03/sf_ui.xhp#GetDocument"
name="GetDocument method">GetDocument</link><br/>
+ <link href="text/sbasic/shared/03/sf_ui.xhp#Maximize"
name="Maximize method">Maximize</link>
</paragraph></tablecell>
<tablecell><paragraph id="par_id451606472825856" role="tablecontent"
localize="false">
- <link href="text/sbasic/shared/03/sf_ui.xhp#Maximize"
name="Maximize method">Maximize</link><br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#Minimize"
name="Minimize method">Minimize</link><br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#OpenBaseDocument"
name="OpenBaseDocument method">OpenBaseDocument</link><br/>
- <link href="text/sbasic/shared/03/sf_ui.xhp#OpenDocument"
name="OpenDocument method">OpenDocument</link> (*)
+ <link href="text/sbasic/shared/03/sf_ui.xhp#OpenDocument"
name="OpenDocument method">OpenDocument</link> (*)<br/>
+ <link href="text/sbasic/shared/03/sf_ui.xhp#Resize" name="Resize
method">Resize</link><br/><br/>
</paragraph></tablecell>
<tablecell><paragraph id="par_id161606472825856" role="tablecontent"
localize="false">
- <link href="text/sbasic/shared/03/sf_ui.xhp#Resize" name="Resize
method">Resize</link><br/>
+ <link href="text/sbasic/shared/03/sf_ui.xhp#RunCommand"
name="RunCommand method">RunCommand</link><br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#SetStatusBar"
name="SetStatusBar method">SetStatusBar</link> (*)<br/>
<link href="text/sbasic/shared/03/sf_ui.xhp#ShowProgressBar"
name="ShowProgressBar method">ShowProgressBar</link><br/>
- <link href="text/sbasic/shared/03/sf_ui.xhp#WindowExists"
name="WindowExists method">WindowExists</link>
+ <link href="text/sbasic/shared/03/sf_ui.xhp#WindowExists"
name="WindowExists method">WindowExists</link><br/><br/>
</paragraph></tablecell>
</tablerow>
</table>
@@ -486,6 +487,57 @@
<tip id="par_id21620332301809">To resize a window that is not active, first
activate it using the <literal>Activate</literal> method.</tip>
</section>
+<section id="RunCommand">
+ <comment> RunCommand
---------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id601589202413561">
+ <bookmark_value>UI service;RunCommand</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id611589202413141" localize="false">RunCommand</h2>
+ <paragraph role="paragraph" id="par_id991589202413257">Runs a UNO command on
the current window. A few typical commands are: Save, SaveAs, ExportToPDF,
Undo, Copy, Paste, etc.</paragraph>
+ <paragraph role="paragraph" id="par_id921611152932311">Commands can be run
with or without arguments. Arguments are not validated before running the
command. If the command or its arguments are invalid, then nothing will
happen.</paragraph>
+ <tip id="par_id31644182402479">For a complete list of UNO commands that can
be run in %PRODUCTNAME, refer to the Wiki page <link
href="https://wiki.documentfoundation.org/Development/DispatchCommands";
name="Commands_Wiki">Development/DispatchCommands</link>.</tip>
+ <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
+ <paragraph role="paragraph" localize="false" id="par_id521622828226683">
+ <input>svc.RunCommand(command: str, [args: any])</input>
+ </paragraph>
+ <embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
+ <paragraph role="paragraph" id="par_id401589202413575"><emph>command</emph>:
Case-sensitive string containing the UNO command name. The inclusion of the
prefix ".uno:" in the command is optional. The command itself is not checked
for correctness. If nothing happens after the command call, then the command is
probably wrong.</paragraph>
+ <paragraph role="paragraph" id="par_id521644182774710"><emph>args</emph>:
For each argument to be passed to the command, specify a pair containing the
argument name and value.</paragraph>
+ <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
+ <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
+ <paragraph role="paragraph" id="par_id721611153068137">The following example
runs the <literal>.uno:About</literal> command in the current
window.</paragraph>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id401611153339973">Set
ui = CreateScriptService("UI")</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id121589202413630">ui.RunCommand("About")</paragraph>
+ </bascode>
+ <paragraph role="paragraph" id="par_id371644184276886">Below is an example
that runs the UNO command <literal>.uno:BasicIDEAppear</literal> and passes the
arguments required to open the Basic IDE at a specific line of a
module.</paragraph>
+ <bascode>
+ <paragraph role="bascode" id="bas_id631644184414955">' Arguments passed to
the command:</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id621644184336024">'
Document = "LibreOffice Macros & Dialogs"</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id516441843364240">'
LibName = "ScriptForge"</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id721644186851722">'
Name = "SF_Session"</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id231644186851949">'
Line = 600</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id391644184337449">ui.RunCommand(".uno:BasicIDEAppear", "Document",
"LibreOffice Macros & Dialogs", _ </paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id971644186963686">
"LibName", "ScriptForge", "Name", "SF_Session", "Line",
600)</paragraph>
+ </bascode>
+ <paragraph role="paragraph" id="par_id41644184549167">Note that calling the
command <literal>BasicIDEAppear</literal> without arguments will simply open
the <menuitem>Basic IDE</menuitem>.</paragraph>
+ <embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
+ <pycode>
+ <paragraph role="pycode" localize="false" id="pyc_id821622828361025">ui =
CreateScriptService("UI")</paragraph>
+ <paragraph role="pycode" localize="false"
id="pyc_id211622828361293">ui.RunCommand("About")</paragraph>
+ </pycode>
+ <pycode>
+ <paragraph role="pycode" localize="false"
id="pyc_id661644184648102">ui.RunCommand(".uno:BasicIDEAppear", "Document",
"LibreOffice Macros & Dialogs", \</paragraph>
+ <paragraph role="pycode" localize="false" id="pyc_id981644187044060">
"LibName", "ScriptForge", "Name", "SF_Session", "Line", 600)</paragraph>
+ </pycode>
+ <paragraph role="paragraph" id="par_id311644243516674">In Python it is also
possible to call <literal>RunCommand</literal> using keyword
arguments:</paragraph>
+ <pycode>
+ <paragraph role="pycode" localize="false"
id="pyc_id821644243549887">ui.RunCommand(".uno:BasicIDEAppear", Document =
"LibreOffice Macros & Dialogs", \</paragraph>
+ <paragraph role="pycode" localize="false" id="pyc_id681644243592324">
LibName = "ScriptForge", Name = "SF_Session", Line = 600)</paragraph>
+ </pycode>
+ <tip id="par_id191611153511038">Each %PRODUCTNAME component has its own set
of commands available. One easy way to learn commands is going to <emph>Tools >
Customize > Keyboard</emph>. When you position your mouse over a function in
the <emph>Function</emph> list, a tooltip will appear with the corresponding
UNO command.</tip>
+</section>
+
<section id="SetStatusBar">
<comment> SetStatusbar
--------------------------------------------------------------------------------------------------------------------------
</comment>
<bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id25158799642119">
