diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 09:06:44 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 09:06:44 +0000 |
| commit | ed5640d8b587fbcfed7dd7967f3de04b37a76f26 (patch) | |
| tree | 7a5f7c6c9d02226d7471cb3cc8fbbf631b415303 /helpcontent2/source/text/sbasic/shared/03 | |
| parent | Initial commit. (diff) | |
| download | libreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.tar.xz libreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.zip | |
Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'helpcontent2/source/text/sbasic/shared/03')
41 files changed, 20366 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/shared/03/avail_release.xhp b/helpcontent2/source/text/sbasic/shared/03/avail_release.xhp new file mode 100644 index 000000000..019363a95 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/avail_release.xhp @@ -0,0 +1,52 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + <meta> + <topic id="availablerelease" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">(Un)Available since release</title> + <filename>/text/sbasic/shared/03/avail_release.xhp</filename> + </topic> + </meta> + <body> + <section id="UnAvailBasicMethod"><note id="not_BasMeth">This method is not available in Basic.</note></section> + <section id="UnAvailBasicProperty"><note id="not_BasProp">This property is not available in Basic.</note></section> + <section id="UnAvailPythonMethod"><note id="not_PycMeth">This method is not available in Python.</note></section> + <section id="UnAvailPythonProperty"><note id="not_PycProp">This property is not available in Python.</note></section> + <comment> Tags for LibreOffice 7.3 </comment> + <section id="7.3.service"> + <note id="par_id811631775671311">This service is available from %PRODUCTNAME 7.3 onwards.</note> + </section> + <section id="7.3.method"> + <note id="par_id291613654389793">This method is available from %PRODUCTNAME 7.3 onwards.</note> + </section> + <section id="7.3.property"> + <note id="par_id201613654593537">This property is available from %PRODUCTNAME 7.3 onwards.</note> + </section> + <comment> Tags for LibreOffice 7.2 </comment> + <section id="7.2.service"> + <note id="par_id651551701041690">This service is available from %PRODUCTNAME 7.2 onwards.</note> + </section> + <section id="7.2.methods"> + <note id="par_id281613660174140">These methods are available from %PRODUCTNAME 7.2 onwards.</note> + </section> + <section id="7.2.method"> + <note id="par_id291613654389792">This method is available from %PRODUCTNAME 7.2 onwards.</note> + </section> + <section id="7.2.control"> + <note id="par_id981613655373210">This control is available from %PRODUCTNAME 7.2 onwards.</note> + </section> + <section id="7.2.events"> + <note id="par_id831613654401663">These event properties are available from %PRODUCTNAME 7.2 onwards.</note> + </section> + <section id="7.2.property"> + <note id="par_id201613654395537">This property is available from %PRODUCTNAME 7.2 onwards.</note> + </section> +</body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_ScriptForge.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_ScriptForge.xhp new file mode 100644 index 000000000..946280ba4 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_ScriptForge.xhp @@ -0,0 +1,247 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- +* This file is part of the LibreOffice project. +* +* This Source Code Form is subject to the terms of the Mozilla Public +* License, v. 2.0. If a copy of the MPL was not distributed with this +* file, You can obtain one at http://mozilla.org/MPL/2.0/. +* +--> + +<meta> + <topic id="toolsbasiclibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge Libraries</title> + <filename>/text/sbasic/shared/03/lib_ScriptForge.xhp</filename> + </topic> +</meta> +<body> + <h1 id="hd_id31529004750471" xml-lang="en-US"><variable id="ScriptForge_lib"><link href="text/sbasic/shared/03/lib_ScriptForge.xhp" name="ScriptForge library">The <literal>ScriptForge</literal> Library</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id491529070339774"> + <bookmark_value>BASIC ScriptForge library</bookmark_value> + <bookmark_value>Python scriptforge module</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph role="paragraph" id="par_id681619700336879">ScriptForge libraries build up an extensible collection of macro scripting resources for %PRODUCTNAME to be invoked from Basic macros or Python scripts.</paragraph> + <section id="importLibs"> + <note id="par_id901528999850603">• Basic macros require to load <literal>ScriptForge</literal> library using the following statement:<br/><literal>GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</literal><br/><br/>• Python scripts require an import from <literal>scriptforge</literal> module:<br/><literal>from scriptforge import CreateScriptService</literal> + </note> + </section> + <tip id="par_id1001623412767893">To learn more about how to create and execute Python scripts using the <literal>ScriptForge</literal> library, read the help page <link href="text/sbasic/shared/03/sf_intro.xhp" name="sfintro_link">Creating Python Scripts with ScriptForge</link>.</tip> + + <h2 id="hd_id781637256119733">Invoking ScriptForge services</h2> + <paragraph role="paragraph" id="par_id781606153472028">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.</paragraph> + <paragraph role="paragraph" id="par_id871637256506167">The <literal>Dispose</literal> method is available in all services and should be called to free up resources after usage:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id901619770181787">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201606153529501">Set oSvc = CreateScriptService("servicename"[, arg0, arg1, ...])</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701637256465858">' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851637256466244">oSvc.Dispose()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id701619701322002">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id531619701322249">svc = CreateScriptService('servicename'[, arg0, arg1, ...])</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271637256185236"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501637256192213">svc.Dispose()</paragraph> + </pycode> + + <h2 id="hd_id851613836643580">Services provided by the ScriptForge library</h2> + <table id="tab_id311613838858931" class="sf_table"> + <tablehead> + <tablerow> + <tablecell> + <paragraph id="par_id131613838858931" role="tablehead">Category</paragraph> + </tablecell> + <tablecell colspan="3"> + <paragraph id="par_id441613838858931" role="tablehead">Services</paragraph> + </tablecell> + </tablerow> + </tablehead> + <tablerow> + <tablecell> + <paragraph id="par_id851613847558931" role="tablecontent">%PRODUCTNAME Basic</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id581613836728425"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Array" name="Array service">Array</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Dictionary" name="Dictionary service">Dictionary</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id731613840022120"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Exception" name="Exception service">Exception</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#FileSystem" name="FileSystem service">FileSystem</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701643305576028" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#String" name="String service">String</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#TextStream" name="TextStream service">TextStream</link><br/> + </paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id131613838825831" role="tablecontent">Document Content</paragraph> + </tablecell> + <tablecell> + <paragraph role="paragraph" localize="false" id="par_id771613836902464"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Base" name="Base service">Base</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Calc" name="Calc service">Calc</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441543838858931" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Chart" name="Chart service">Chart</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Database" name="Database service">Database</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701643305576137" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Document" name="Document service">Document</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Writer" name="Writer service">Writer</link><br/> + </paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id131613947858931" role="tablecontent">User Interface</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id481613837033056"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Dialog" name="Dialog service">Dialog</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#DialogControl" name="DialogControl service">DialogControl</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Form" name="Form service">Form</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441613885558931" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#FormControl" name="FormControl service">FormControl</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Menu" name="Menu service">Menu</link><br/><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701643305576632" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#PopupMenu" name="PopupMenu service">PopupMenu</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#UI" name="UI service">UI</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id131613866258931" role="tablecontent">Utilities</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id461613837133275"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Basic" name="Basic service">Basic</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#L10N" name="L10N service">L10N</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Platform" name="Platform service">Platform</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441613723858931" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Region" name="Region service">Region</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Services" name="Services service">Services</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Session" name="Session service">Session</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701643305572058" localize="false" role="tablecontent"> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#Timer" name="Timer service">Timer</link><br/> + <link href="text/sbasic/shared/03/lib_ScriptForge.xhp#UnitTest" name="UnitTest service">UnitTest</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + <section id="Array"> + <embed href="text/sbasic/shared/03/sf_array.xhp#abstract"/> + </section> + <section id="Base"> + <embed href="text/sbasic/shared/03/sf_base.xhp#abstract"/> + </section> + <section id="Basic"> + <embed href="text/sbasic/shared/03/sf_basic.xhp#abstract"/> + </section> + <section id="Calc"> + <embed href="text/sbasic/shared/03/sf_calc.xhp#abstract"/> + </section> + <section id="Chart"> + <embed href="text/sbasic/shared/03/sf_chart.xhp#abstract"/> + </section> + <section id="Database"> + <embed href="text/sbasic/shared/03/sf_database.xhp#abstract"/> + </section> + <section id="Dialog"> + <embed href="text/sbasic/shared/03/sf_dialog.xhp#abstract"/> + </section> + <section id="DialogControl"> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#abstract"/> + </section> + <section id="Dictionary"> + <embed href="text/sbasic/shared/03/sf_dictionary.xhp#abstract"/> + </section> + <section id="Document"> + <embed href="text/sbasic/shared/03/sf_document.xhp#abstract"/> + </section> + <section id="Exception"> + <embed href="text/sbasic/shared/03/sf_exception.xhp#abstract"/> + </section> + <section id="FileSystem"> + <embed href="text/sbasic/shared/03/sf_filesystem.xhp#abstract"/> + </section> + <section id="Form"> + <embed href="text/sbasic/shared/03/sf_form.xhp#abstract"/> + </section> + <section id="FormControl"> + <embed href="text/sbasic/shared/03/sf_formcontrol.xhp#abstract"/> + </section> + <section id="L10N"> + <embed href="text/sbasic/shared/03/sf_l10n.xhp#abstract"/> + </section> + <section id="Menu"> + <embed href="text/sbasic/shared/03/sf_menu.xhp#abstract"/> + </section> + <section id="Platform"> + <embed href="text/sbasic/shared/03/sf_platform.xhp#abstract"/> + </section> + <section id="PopupMenu"> + <embed href="text/sbasic/shared/03/sf_popupmenu.xhp#abstract"/> + </section> + <section id="Region"> + <embed href="text/sbasic/shared/03/sf_region.xhp#abstract"/> + </section> + <section id="Services"> + <embed href="text/sbasic/shared/03/sf_services.xhp#abstract"/> + </section> + <section id="Session"> + <embed href="text/sbasic/shared/03/sf_session.xhp#abstract"/> + </section> + <section id="String"> + <embed href="text/sbasic/shared/03/sf_string.xhp#abstract"/> + </section> + <section id="TextStream"> + <embed href="text/sbasic/shared/03/sf_textstream.xhp#abstract"/> + </section> + <section id="Timer"> + <embed href="text/sbasic/shared/03/sf_timer.xhp#abstract"/> + </section> + <section id="UI"> + <embed href="text/sbasic/shared/03/sf_ui.xhp#abstract"/> + </section> + <section id="UnitTest"> + <embed href="text/sbasic/shared/03/sf_unittest.xhp#abstract"/> + </section> + <section id="Writer"> + <embed href="text/sbasic/shared/03/sf_writer.xhp#abstract"/> + </section> + <comment>Restricted use for SF_Root, SF_Utils modules as well as internal methods</comment> + <paragraph role="paragraph" id="par_id331608220104798"><emph>Note:</emph> Other <literal>ScriptForge</literal> undescribed modules are reserved for internal use. Their content is subject to change without notice.</paragraph> + <section id="SF_InternalUse"> + <warning id="par_id851506659675843">All <literal>ScriptForge</literal> Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.</warning> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_depot.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_depot.xhp new file mode 100644 index 000000000..2c4a01ba1 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_depot.xhp @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basicdepotlibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">DEPOT Library</title> + <filename>/text/sbasic/shared/03/lib_depot.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="depot_lib"><link href="text/sbasic/shared/03/lib_depot.xhp" name="Depot library">The <item type="literal">Depot</item> Library</link></variable></paragraph> + + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("Depot")</item></paragraph> + <embed href="text/shared/need_help.xhp#needhelp"/> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_euro.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_euro.xhp new file mode 100644 index 000000000..d975c69d4 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_euro.xhp @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basiceurolibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">EURO Library</title> + <filename>/text/sbasic/shared/03/lib_euro.xhp</filename> + </topic> + </meta> + <body> + <h1 id="hd_id31529004750471"><variable id="euro_lib"><link href="text/sbasic/shared/03/lib_euro.xhp" name="Euro library">The <item type="literal">Euro</item> Library</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id231529070133574"> + <bookmark_value>BASIC Euro library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <embed href="text/shared/need_help.xhp#needhelp"/> + <h2 id="hd_id841593518085848">Description</h2> + <paragraph role="paragraph" id="par_id921593518140986">The <emph>Euro</emph> library is used by the <emph>Euro converter…</emph> wizard.</paragraph> + <paragraph role="paragraph" id="par_id481593518247400">Its entry points are:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id961593518286855" role="listitem" localize="False">Euro.AutoPilotRun.StartAutoPilot</paragraph></listitem> + <listitem><paragraph id="par_id811593518354070" role="listitem" localize="False">Euro.ConvertRun.Main</paragraph></listitem> + </list> + <paragraph role="paragraph" id="par_id381593519742529">Selecting the <emph>Euro Converter</emph> wizard loads the following libraries in memory:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id361593520109787" role="listitem" localize="False">Euro</paragraph></listitem> + <listitem><paragraph id="par_id811593520110346" role="listitem" localize="False">ImportWizard</paragraph></listitem> + <listitem><paragraph id="par_id31593520110938" role="listitem" localize="False">Tools</paragraph></listitem> + </list> + <note id="par_id691593519646426">Basic routine name conflicts may exist when multiple Basic libraries are loaded in memory.</note> + <section id="relatedtopics"> + <paragraph role="paragraph" id="par_id1001593520257636">ImportWizard and <link href="text/sbasic/shared/03/lib_tools.xhp" name="Tools library">Tools</link> Basic libraries</paragraph> + <paragraph role="paragraph" id="par_id251593518523704"><link href="text/shared/autopi/01150000.xhp" name="Euro Converter Wizard">Euro Converter Wizard</link> describes what the <emph>Euro</emph> library does.</paragraph> + </section> + </body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_formwizard.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_formwizard.xhp new file mode 100644 index 000000000..c3ff82a11 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_formwizard.xhp @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basicdepotlibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">FORMWIZARD Library</title> + <filename>/text/sbasic/shared/03/lib_formwizard.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="formwizard_lib"><link href="text/sbasic/shared/03/lib_formwizard.xhp" name="FormWizard library">The <item type="literal">FormWizard</item> Library</link></variable></paragraph> + + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("FormWizard")</item></paragraph> + <embed href="text/shared/need_help.xhp#needhelp"/> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_gimmicks.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_gimmicks.xhp new file mode 100644 index 000000000..01c7d0171 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_gimmicks.xhp @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basicgimmickslibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">GIMMICKS Library</title> + <filename>/text/sbasic/shared/03/lib_gimmicks.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="gimmicks_lib"><link href="text/sbasic/shared/03/lib_gimmicks.xhp" name="Gimmicks library">The <item type="literal">Gimmicks</item> Library</link></variable></paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id951529070357301"> + <bookmark_value>BASIC Gimmicks library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + + <embed href="text/shared/need_help.xhp#needhelp"/> + + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("Gimmicks")</item></paragraph> + + <h2 id="hd_id841593518085848">Description</h2> + <paragraph role="paragraph" id="par_id921593518140986">The <emph>Gimmicks</emph> library is used by the <emph>AutoText</emph> wizard.</paragraph> + <paragraph role="paragraph" id="par_id481593518247400">Its entry points are:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id961593518286855" role="listitem" localize="False">Gimmicks.AutoText.Main</paragraph></listitem> + <listitem><paragraph id="par_id961593815286855" role="listitem" localize="False">Gimmicks.GetTexts.Main</paragraph></listitem> + </list> + + <paragraph role="paragraph" id="par_id381593519742529">Selecting <menuitem>Tools - AutoText</menuitem> loads the following library in memory:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id31593520110938" role="listitem" localize="False">Tools</paragraph></listitem> + </list> + <note id="par_id691593519646426">Basic routine name conflicts may exist when multiple Basic libraries are loaded in memory.</note> + + <section id="relatedtopics"> + <paragraph role="paragraph" id="par_id1001593520257636"><link href="text/sbasic/shared/03/lib_tools.xhp" name="Tools library">Tools</link> Basic library</paragraph> + <paragraph role="paragraph" id="par_id251593518523704"><link href="text/swriter/guide/autotext.xhp" name="Using AutoText">Using AutoText</link> explains what the <emph>Gimmicks</emph> library does.</paragraph> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_importwiz.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_importwiz.xhp new file mode 100644 index 000000000..20669ec99 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_importwiz.xhp @@ -0,0 +1,44 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + <meta> + <topic id="basicimportwizardlibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ImportWizard Library</title> + <filename>/text/sbasic/shared/03/lib_importwiz.xhp</filename> + </topic> + </meta> + <body> + <h1 id="hd_id31529004750471"><variable id="importwiz_lib"><link href="text/sbasic/shared/03/lib_importwiz.xhp" name="ImportWizard library">The <item type="literal">ImportWizard</item> Library</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id231529070133574"> + <bookmark_value>BASIC ImportWizard library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + <embed href="text/sbasic/shared/00000003.xhp#dialoglibhowtoget"/> + </section> + <embed href="text/shared/need_help.xhp#needhelp"/> + <h2 id="hd_id841593518085848">Description</h2> + <paragraph role="paragraph" id="par_id921593518140986">The <emph>ImportWizard</emph> library is used by the <emph>Document Converter</emph> wizard.</paragraph> + <paragraph role="paragraph" id="par_id481593518247400">Its entry point is:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id961593518286855" role="listitem" localize="False">ImportWizard.Main.Main</paragraph></listitem> + </list> + <paragraph role="paragraph" id="par_id381593519742529">Selecting the <emph>Document Converter</emph> wizard loads the following libraries in memory:</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id811593520110346" role="listitem" localize="False">ImportWizard</paragraph></listitem> + <listitem><paragraph id="par_id31593520110938" role="listitem" localize="False">Tools</paragraph></listitem> + </list> + <note id="par_id691593519646426">Basic routine name conflicts may exist when multiple Basic libraries are loaded in memory.</note> + <section id="relatedtopics"> + <paragraph role="paragraph" id="par_id1001593520257636"><link href="text/sbasic/shared/03/lib_tools.xhp" name="Tools library">Tools</link> Basic library</paragraph> + <paragraph role="paragraph" id="par_id251593518523704"><link href="text/shared/autopi/01130000.xhp" name="Document Converter">Document Converter</link> describes what the <emph>ImportWizard</emph> library does.</paragraph> + </section> + </body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_schedule.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_schedule.xhp new file mode 100644 index 000000000..00cf3dcc8 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_schedule.xhp @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basicschedulelibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SCHEDULE Library</title> + <filename>/text/sbasic/shared/03/lib_schedule.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="schedule_lib"><link href="text/sbasic/shared/03/lib_schedule.xhp" name="Schedule library">The <item type="literal">Schedule</item> Library</link></variable></paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id671529070099646"> + <bookmark_value>BASIC Schedule library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("Schedule")</item></paragraph> + <embed href="text/shared/need_help.xhp#needhelp"/> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_script.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_script.xhp new file mode 100644 index 000000000..c2ef92b9b --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_script.xhp @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basicscriptlibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SCRIPTBINDINGLIBRARY Library</title> + <filename>/text/sbasic/shared/03/lib_script.xhp</filename> + </topic> + </meta> + <body> + <h1 id="hd_id31529004750471"><variable id="script_lib"><link href="text/sbasic/shared/03/lib_script.xhp" name="ScriptBindingLibrary library">The <item type="literal">ScriptBindingLibrary</item> Library</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id851529070366056"> + <bookmark_value>BASIC ScriptBindingLibrary library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#dialoglibhowtoget"/> + </section> + <h2 id="hd_id841593518085848">Description</h2> + <paragraph role="paragraph" id="par_id921593518140986">The <emph>ScriptBindingLibrary</emph> library only contains dialogs, it is used by <emph>Highlight</emph> %PRODUCTNAME example scripts. Its dialogs are shared by Beanshell, Java and JavaScript example scripts.</paragraph> + <paragraph role="paragraph" id="par_id381593519742529">Running any <emph>Highlight</emph> example script loads the <emph>ScriptBindingLibrary</emph> library in memory.</paragraph> + <note id="par_id131593538122154">This library is not used by %PRODUCTNAME Basic.</note> + <section id="relatedtopics"> + <paragraph role="paragraph" id="par_id251593524531077"><link href="text/shared/01/06130020.xhp" name="Basic macro selector">Basic macro selector</link></paragraph> + <paragraph role="paragraph" id="par_id721593525163663">Beanshell, Java and JavaScript <link href="text/shared/01/06130030.xhp" name="Scripts">Scripts</link></paragraph> +</section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_template.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_template.xhp new file mode 100644 index 000000000..f7e093fa0 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_template.xhp @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="basictemplatelibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">TEMPLATE Library</title> + <filename>/text/sbasic/shared/03/lib_template.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="template_lib"><link href="text/sbasic/shared/03/lib_template.xhp" name="Template library">The <item type="literal">Template</item> Library</link></variable></paragraph> + + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("Template")</item></paragraph> + <embed href="text/shared/need_help.xhp#needhelp"/> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_tools.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_tools.xhp new file mode 100644 index 000000000..2ed625b5a --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_tools.xhp @@ -0,0 +1,842 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + + <meta> + <topic id="toolsbasiclibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Tools Library</title> + <filename>/text/sbasic/shared/03/lib_tools.xhp</filename> + </topic> + </meta> + <body> + <paragraph role="heading" id="hd_id31529004750471" level="1" xml-lang="en-US"><variable id="tools_lib"><link href="text/sbasic/shared/03/lib_tools.xhp" name="Tools library">The <item type="literal">Tools</item> Library</link></variable></paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id491529070339774"> + <bookmark_value>BASIC Tools library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#basiclibhowtoget"/> + </section> + <paragraph xml-lang="en-US" id="par_id901528999850603" localize="false" role="note"><embedvar href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/> + <item type="literal">GlobalScope.BasicLibraries.LoadLibrary("Tools")</item></paragraph> + <paragraph role="paragraph" id="par_id161529001339405" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#debug_module" name="debug module"><item type="literal">Debug</item> Module</link></paragraph> + <paragraph role="paragraph" id="par_id41529001348561" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#listbox_module" name="listbox module"><item type="literal">ListBox</item> Module</link></paragraph> + <paragraph role="paragraph" id="par_id341529001354451" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#misc_module" name="misc module"><item type="literal">Misc</item> Module</link></paragraph> + <paragraph role="paragraph" id="par_id311529001362049" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#modulecontrols_module" name="module controls module"><item type="literal">ModuleControls</item> Module</link></paragraph> + <paragraph role="paragraph" id="par_id701529001368064" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#strings_module" name="strings module"><item type="literal">Strings</item> Module</link></paragraph> + <paragraph role="paragraph" id="par_id251529001373426" xml-lang="en-US"><link href="text/sbasic/shared/03/lib_tools.xhp#ucb_module" name="ucb module"><item type="literal">UCB</item> Module</link></paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id271529062442803"> + <bookmark_value>BASIC Tools library;Debug module</bookmark_value> + </bookmark> + <section id="debug_module"> + <paragraph role="heading" id="hd_id371529000826947" level="2" xml-lang="en-US"><item type="literal">Debug</item> Module</paragraph> + <paragraph role="paragraph" id="par_id441529064369519" xml-lang="en-US">Functions and subroutines for debugging Basic macros.</paragraph> + <h3 id="hd_id711529001004857" xml-lang="en-US" localize="false">ActivateReadOnlyFlag</h3> + <bascode> + <paragraph id="par_id251529001003857" role="bascode" xml-lang="en-US" localize="false">Sub ActivateReadOnlyFlag()</paragraph> + </bascode> + <h3 id="hd_id71529001663903" xml-lang="en-US" localize="false">DeactivateReadOnlyFlag</h3> + <bascode> + <paragraph id="par_id951529001706210" role="bascode" xml-lang="en-US" localize="false">Sub DeactivateReadOnlyFlag()</paragraph> + </bascode> + <h3 id="hd_id421529001727178" xml-lang="en-US" localize="false">SetBasicReadOnlyFlag</h3> + <bascode> + <paragraph id="par_id771529001755355" role="bascode" xml-lang="en-US" localize="false">Sub SetBasicReadOnlyFlag(bReadOnly as Boolean)</paragraph> + </bascode> + <h3 id="hd_id651529001954868" xml-lang="en-US" localize="false">WritedbgInfo</h3> + <bascode> + <paragraph id="par_id581529001865055" role="bascode" xml-lang="en-US" localize="false">Sub WritedbgInfo(LocObject as Object)</paragraph> + </bascode> + <h3 id="hd_id841529001994821" xml-lang="en-US" localize="false">WriteDbgString</h3> + <bascode> + <paragraph id="par_id171529002013434" role="bascode" xml-lang="en-US" localize="false">Sub WriteDbgString(LocString as String)</paragraph> + </bascode> + <h3 id="hd_id741529002099962" xml-lang="en-US" localize="false">ShowArray</h3> + <bascode> + <paragraph id="par_id261529002118559" role="bascode" xml-lang="en-US" localize="false">Sub ShowArray(LocArray())</paragraph> + </bascode> + <h3 id="hd_id321529002327444" xml-lang="en-US" localize="false">ShowPropertyValues</h3> + <bascode> + <paragraph id="par_id501529002327444" role="bascode" xml-lang="en-US" localize="false">Sub ShowPropertyValues(oLocObject as Object)</paragraph> + </bascode> + <h3 id="hd_id451529002368600" xml-lang="en-US" localize="false">ShowNameValuePair</h3> + <bascode> + <paragraph id="par_id321529002368600" role="bascode" xml-lang="en-US" localize="false">Sub ShowNameValuePair(Pair())</paragraph> + </bascode> + <h3 id="hd_id551529002415495" xml-lang="en-US" localize="false">ShowElementNames</h3> + <paragraph id="par_id111529003255859" role="paragraph" xml-lang="en-US" localize="false">' Retrieves all the Elements of aSequence of an object, with the</paragraph> + <paragraph id="par_id41529003238747" role="paragraph" xml-lang="en-US" localize="false">' possibility to define a filter(sfilter <> "")</paragraph> + <bascode> + <paragraph role="bascode" id="par_id41529003225918" xml-lang="en-US" localize="false">Sub ShowElementNames(</paragraph> + <paragraph role="bascode" id="par_id321529005373289" xml-lang="en-US" localize="false">oLocElements() as Object,</paragraph> + <paragraph role="bascode" id="par_id1001529005296415" xml-lang="en-US" localize="false">Optional sFiltername as String)</paragraph> + </bascode> + <h3 id="hd_id581529003295045" xml-lang="en-US" localize="false">ShowSupportedServiceNames</h3> + <paragraph id="par_id851529003295045" role="paragraph" xml-lang="en-US" localize="false">' Retrieves all the supported servicenames of an object, with the </paragraph> + <paragraph id="par_id301529003401893" role="paragraph" xml-lang="en-US" localize="false">' possibility to define a filter(sfilter <> "")</paragraph> + <bascode> + <paragraph role="bascode" id="par_id801529003393056" xml-lang="en-US" localize="false">Sub ShowSupportedServiceNames(</paragraph> + <paragraph role="bascode" id="par_id101529005392934" xml-lang="en-US" localize="false">oLocObject as Object,</paragraph> + <paragraph role="bascode" id="par_id661529005271095" xml-lang="en-US" localize="false">Optional sFilterName as String)</paragraph> + </bascode> + <h3 id="hd_id831529003429502" xml-lang="en-US" localize="false">ShowAvailableServiceNames</h3> + <paragraph id="par_id401529003494638" role="paragraph" xml-lang="en-US" localize="false">' Retrieves all the available Servicenames of an object, with the</paragraph> + <paragraph id="par_id801529003504707" role="paragraph" xml-lang="en-US" localize="false">' possibility to define a filter(sfilter <> "")</paragraph> + <bascode> + <paragraph role="bascode" id="par_id981529005231465" xml-lang="en-US" localize="false">Sub ShowAvailableServiceNames(</paragraph> + <paragraph role="bascode" id="par_id251529005237648" xml-lang="en-US" localize="false">oLocObject as Object, </paragraph> + <paragraph role="bascode" id="par_id721529005247098" xml-lang="en-US" localize="false">Optional sFilterName as String)</paragraph> + </bascode> + <h3 id="hd_id591529003562090" xml-lang="en-US" localize="false">ShowCommands</h3> + <bascode> + <paragraph id="par_id791529003562091" role="bascode" xml-lang="en-US" localize="false">Sub ShowCommands(oLocObject as Object)</paragraph> + </bascode> + <h3 id="hd_id881529003602892" xml-lang="en-US" localize="false">ProtectCurrentSheets</h3> + <bascode> + <paragraph id="par_id531529003602892" role="bascode" xml-lang="en-US" localize="false">Sub ProtectCurrentSheets()</paragraph> + </bascode> + <h3 id="hd_id691529003635074" xml-lang="en-US" localize="false">FillDocument</h3> + <bascode> + <paragraph id="par_id371529003635074" role="bascode" xml-lang="en-US" localize="false">Sub FillDocument()</paragraph> + </bascode> + </section> + <bookmark xml-lang="en-US" branch="index" id="bm_id131529062501888"> + <bookmark_value>BASIC Tools library;ListBox module</bookmark_value> + </bookmark> + <section id="listbox_module"> + <paragraph role="heading" id="hd_id11529005753099" level="2" xml-lang="en-US"><item type="literal">ListBox</item> Module</paragraph> + <paragraph role="paragraph" id="par_id381529064415052" xml-lang="en-US">Functions and subroutines for handling ListBox elements.</paragraph> + <embed href="text/shared/need_help.xhp#needhelp"/> + </section> + <bookmark xml-lang="en-US" branch="index" id="bm_id571529062538621"> + <bookmark_value>BASIC Tools library;Misc module</bookmark_value> + </bookmark> + <section id="misc_module"> + <paragraph role="heading" id="hd_id341529005758494" level="2" xml-lang="en-US"><item type="literal">Misc</item> Module</paragraph> + <paragraph role="paragraph" id="par_id681529064596175" xml-lang="en-US">Miscellaneous functions and subroutines.</paragraph> + <h3 id="hd_id801529006604779" xml-lang="en-US" localize="false">RegisterNewDataSource</h3> + <bascode> + <paragraph role="bascode" id="par_id851529006689297" xml-lang="en-US" localize="false">Function RegisterNewDataSource(</paragraph> + <paragraph role="bascode" id="par_id471529006695330" xml-lang="en-US" localize="false">DSName as String, </paragraph> + <paragraph role="bascode" id="par_id671529006700462" xml-lang="en-US" localize="false">PropertyList(), </paragraph> + <paragraph role="bascode" id="par_id821529006705849" xml-lang="en-US" localize="false">Optional DriverProperties() </paragraph> + <paragraph role="bascode" id="par_id321529061768930" xml-lang="en-US" localize="false">as New com.sun.star.beans.PropertyValue)</paragraph> + </bascode> + <h3 id="hd_id501529006725521" xml-lang="en-US" localize="false">ConnecttoDatabase</h3> + <bascode> + <paragraph role="bascode" id="par_id771529006782954" xml-lang="en-US" localize="false">Function ConnecttoDatabase(</paragraph> + <paragraph role="bascode" id="par_id31529006789644" xml-lang="en-US" localize="false">DSName as String, </paragraph> + <paragraph role="bascode" id="par_id421529006794640" xml-lang="en-US" localize="false">UserID as String, </paragraph> + <paragraph role="bascode" id="par_id381529006799623" xml-lang="en-US" localize="false">Password as String, </paragraph> + <paragraph role="bascode" id="par_id641529006805066" xml-lang="en-US" localize="false">Optional Propertylist(), </paragraph> + <paragraph role="bascode" id="par_id201529006810077" xml-lang="en-US" localize="false">Optional DriverProperties() </paragraph> + <paragraph role="bascode" id="par_id11529061810188" xml-lang="en-US" localize="false">as New com.sun.star.beans.PropertyValue)</paragraph> + </bascode> + <h3 id="hd_id411529006832985" xml-lang="en-US" localize="false">GetStarOfficeLocale</h3> + <bascode> + <paragraph id="par_id451529006832985" role="bascode" xml-lang="en-US" localize="false">Function GetStarOfficeLocale() </paragraph> + <paragraph role="bascode" id="par_id761529061825013" xml-lang="en-US" localize="false">as New com.sun.star.lang.Locale</paragraph> + </bascode> + <h3 id="hd_id361529006902547" xml-lang="en-US" localize="false">GetRegistryKeyContent</h3> + <bascode> + <paragraph role="bascode" id="par_id391529006938605" xml-lang="en-US" localize="false">Function GetRegistryKeyContent(</paragraph> + <paragraph role="bascode" id="par_id881529006944515" xml-lang="en-US" localize="false">sKeyName as string, </paragraph> + <paragraph role="bascode" id="par_id711529006950283" xml-lang="en-US" localize="false">Optional bforUpdate as Boolean)</paragraph> + </bascode> + <h3 id="hd_id851529006965105" xml-lang="en-US" localize="false">GetProductname</h3> + <bascode> + <paragraph id="par_id451529006965105" role="bascode" xml-lang="en-US" localize="false">Function GetProductname() as String</paragraph> + </bascode> + <h3 id="hd_id771529007007439" xml-lang="en-US" localize="false">OpenDocument</h3> + <paragraph id="par_id821529007072253" role="paragraph" localize="false" xml-lang="en-US">' Opens a Document, checks beforehand, whether it has to be loaded or whether it is already on the desktop. If the parameter bDisposable is set to False then the returned document should not be disposed afterwards, because it is already opened.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id991529007104165" xml-lang="en-US" localize="false">Function OpenDocument(</paragraph> + <paragraph role="bascode" id="par_id191529007110562" xml-lang="en-US" localize="false">DocPath as String, </paragraph> + <paragraph role="bascode" id="par_id851529007118783" xml-lang="en-US" localize="false">Args(), </paragraph> + <paragraph role="bascode" id="par_id691529007123485" xml-lang="en-US" localize="false">Optional bDisposable as Boolean)</paragraph> + </bascode> + <h3 id="hd_id481529007130534" xml-lang="en-US" localize="false">TaskonDesktop</h3> + <bascode> + <paragraph id="par_id911529007130534" role="bascode" xml-lang="en-US" localize="false">Function TaskonDesktop(DocPath as String) as Boolean</paragraph> + </bascode> + <h3 id="hd_id201529007205755" xml-lang="en-US" localize="false">RetrieveFileName</h3> + <paragraph id="par_id81529007245965" role="paragraph" localize="false" xml-lang="en-US">' Retrieves a FileName out of a StarOffice-Document.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id881529007259806" xml-lang="en-US" localize="false">Function RetrieveFileName(LocDoc as Object)</paragraph> + </bascode> + <h3 id="hd_id121529007269721" xml-lang="en-US" localize="false">GetPathSettings</h3> + <paragraph id="par_id801529007338550" role="paragraph" localize="false" xml-lang="en-US">' Gets a special configured PathSetting.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id971529007353940" xml-lang="en-US" localize="false">Function GetPathSettings(</paragraph> + <paragraph role="bascode" id="par_id401529007360579" xml-lang="en-US" localize="false">sPathType as String,</paragraph> + <paragraph role="bascode" id="par_id741529007366892" xml-lang="en-US" localize="false">Optional bshowall as Boolean, </paragraph> + <paragraph role="bascode" id="par_id841529007371792" xml-lang="en-US" localize="false">Optional ListIndex as integer) as String</paragraph> + </bascode> + <h3 id="hd_id571529007381828" xml-lang="en-US" localize="false">GetOfficeSubPath</h3> + <paragraph id="par_id761529007616982" role="paragraph" localize="false" xml-lang="en-US">' Gets the fully qualified path to a subdirectory of the Template Directory, e. g. with the parameter "wizard/bitmap". The parameter must be passed over in Url-scription. The return-Value is in Urlscription.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id981529007639916" xml-lang="en-US" localize="false">Function GetOfficeSubPath(</paragraph> + <paragraph role="bascode" id="par_id21529007645780" xml-lang="en-US" localize="false">sOfficePath as String, </paragraph> + <paragraph role="bascode" id="par_id201529007651880" xml-lang="en-US" localize="false">ByVal sSubDir as String)</paragraph> + </bascode> + <h3 id="hd_id591529007658281" xml-lang="en-US" localize="false">ShowNoOfficePathError</h3> + <bascode> + <paragraph id="par_id511529007658281" role="bascode" xml-lang="en-US" localize="false">Sub ShowNoOfficePathError() </paragraph> + </bascode> + <h3 id="hd_id431529007692356" xml-lang="en-US" localize="false">InitResources</h3> + <bascode> + <paragraph id="par_id991529007692356" role="bascode" xml-lang="en-US" localize="false">Function InitResources(</paragraph> + <paragraph role="bascode" id="par_id651529007767824" xml-lang="en-US" localize="false">Description, </paragraph> + <paragraph role="bascode" id="par_id401529007773380" xml-lang="en-US" localize="false">ShortDescription as String) as boolean</paragraph> + </bascode> + <h3 id="hd_id611529007790857" xml-lang="en-US" localize="false">GetResText</h3> + <bascode> + <paragraph id="par_id331529007790857" role="bascode" xml-lang="en-US" localize="false">Function GetResText( nID as integer ) As string</paragraph> + </bascode> + <h3 id="hd_id971529007839780" xml-lang="en-US" localize="false">CutPathView</h3> + <bascode> + <paragraph role="bascode" id="par_id91529007882196" xml-lang="en-US" localize="false">Function CutPathView(</paragraph> + <paragraph role="bascode" id="par_id211529007888525" xml-lang="en-US" localize="false">sDocUrl as String, </paragraph> + <paragraph role="bascode" id="par_id361529007894202" xml-lang="en-US" localize="false">Optional PathLen as Integer)</paragraph> + </bascode> + <h3 id="hd_id51529007902118" xml-lang="en-US" localize="false">DeleteInputCells</h3> + <paragraph id="par_id311529007997114" role="paragraph" localize="false" xml-lang="en-US">' Deletes the content of all cells that are softformatted according to the 'InputStyleName'.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id111529008013953" xml-lang="en-US" localize="false">Sub DeleteInputCells(</paragraph> + <paragraph role="bascode" id="par_id731529008019208" xml-lang="en-US" localize="false">oSheet as Object, </paragraph> + <paragraph role="bascode" id="par_id881529008025944" xml-lang="en-US" localize="false">InputStyleName as String)</paragraph> + </bascode> + <h3 id="hd_id881529008035409" xml-lang="en-US" localize="false">ChangeValueofRange</h3> + <paragraph id="par_id261529008090521" role="paragraph" xml-lang="en-US" localize="false">' Inserts a certain String to all cells of a Range that is passed over either as an object or as the RangeName.</paragraph> + <bascode> + <paragraph role="bascode" id="par_id231529008110214" xml-lang="en-US" localize="false">Sub ChangeValueofRange(</paragraph> + <paragraph role="bascode" id="par_id401529008116727" xml-lang="en-US" localize="false">oSheet as Object, </paragraph> + <paragraph role="bascode" id="par_id211529008122524" xml-lang="en-US" localize="false">Range, </paragraph> + <paragraph role="bascode" id="par_id91529008128202" xml-lang="en-US" localize="false">ReplaceValue, </paragraph> + <paragraph role="bascode" id="par_id671529008133554" xml-lang="en-US" localize="false">Optional StyleName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547275154" xml-lang="en-US" localize="false">ReplaceRangeValues</h3> + <bascode> + <paragraph id="par_id061420180547275639" role="bascode" localize="false" xml-lang="en-US">Sub ReplaceRangeValues(</paragraph> + <paragraph id="par_id061420180547279527" role="bascode" localize="false" xml-lang="en-US">oRange as Object, </paragraph> + <paragraph id="par_id061420180547277" role="bascode" localize="false" xml-lang="en-US">ReplaceValue)</paragraph> + </bascode> + <h3 id="hd_id06142018054727953" xml-lang="en-US" localize="false">GetValueofCellbyName</h3> + <paragraph id="par_id061420180547271480" role="paragraph" xml-lang="en-US" localize="false">' Returns the Value of the first cell of a Range.</paragraph> + <bascode> + <paragraph id="par_id061420180547275293" role="bascode" localize="false" xml-lang="en-US">Function GetValueofCellbyName(</paragraph> + <paragraph id="par_id061420180547274365" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547272143" role="bascode" localize="false" xml-lang="en-US">sCellName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547273177" xml-lang="en-US" localize="false">DuplicateRow</h3> + <bascode> + <paragraph id="par_id061420180547278695" role="bascode" localize="false" xml-lang="en-US">Function DuplicateRow(</paragraph> + <paragraph id="par_id061420180547271430" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547271882" role="bascode" localize="false" xml-lang="en-US">RangeName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547271951" xml-lang="en-US" localize="false">GetStringofCellbyName</h3> + <paragraph id="par_id061420180547275159" role="paragraph" xml-lang="en-US" localize="false">' Returns the String of the first cell of a Range.</paragraph> + <bascode> + <paragraph id="par_id061420180547277611" role="bascode" localize="false" xml-lang="en-US">Function GetStringofCellbyName(</paragraph> + <paragraph id="par_id061420180547271853" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547277036" role="bascode" localize="false" xml-lang="en-US">sCellName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547271528" xml-lang="en-US" localize="false">GetCellByName</h3> + <paragraph id="par_id061420180547271588" role="paragraph" xml-lang="en-US" localize="false">' Returns a named Cell</paragraph> + <bascode> + <paragraph id="par_id061420180547278497" role="bascode" localize="false" xml-lang="en-US">Function GetCellByName(</paragraph> + <paragraph id="par_id061420180547284593" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547285667" role="bascode" localize="false" xml-lang="en-US">sCellName as String) as Object</paragraph> + </bascode> + <h3 id="hd_id061420180547288062" xml-lang="en-US" localize="false">ChangeCellValue</h3> + <paragraph id="par_id061420180547288384" role="paragraph" xml-lang="en-US" localize="false">' Changes the numeric Value of a cell by transmitting the String of the numeric Value.</paragraph> + <bascode> + <paragraph id="par_id061420180547287291" role="bascode" localize="false" xml-lang="en-US">Sub ChangeCellValue(</paragraph> + <paragraph id="par_id061420180547287421" role="bascode" localize="false" xml-lang="en-US">oCell as Object, </paragraph> + <paragraph id="par_id061420180547283866" role="bascode" localize="false" xml-lang="en-US">ValueString as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547283259" xml-lang="en-US" localize="false">GetDocumentType</h3> + <bascode> + <paragraph id="par_id061420180547286797" role="bascode" localize="false" xml-lang="en-US">Function GetDocumentType(oDocument)</paragraph> + </bascode> + <h3 id="hd_id061420180547288146" xml-lang="en-US" localize="false">GetNumberFormatType</h3> + <bascode> + <paragraph id="par_id061420180547285276" role="bascode" localize="false" xml-lang="en-US">Function GetNumberFormatType(</paragraph> + <paragraph id="par_id061420180547282526" role="bascode" localize="false" xml-lang="en-US">oDocFormats, </paragraph> + <paragraph id="par_id061420180547285804" role="bascode" localize="false" xml-lang="en-US">oFormatObject as Object) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180547282335" xml-lang="en-US" localize="false">ProtectSheets</h3> + <bascode> + <paragraph id="par_id061420180547283563" role="bascode" localize="false" xml-lang="en-US">Sub ProtectSheets(Optional oSheets as Object)</paragraph> + </bascode> + <h3 id="hd_id061420180547285130" xml-lang="en-US" localize="false">UnprotectSheets</h3> + <bascode> + <paragraph id="par_id061420180547289761" role="bascode" localize="false" xml-lang="en-US">Sub UnprotectSheets(Optional oSheets as Object)</paragraph> + </bascode> + <h3 id="hd_id061420180547284142" xml-lang="en-US" localize="false">GetRowIndex</h3> + <bascode> + <paragraph id="par_id061420180547284432" role="bascode" localize="false" xml-lang="en-US">Function GetRowIndex(</paragraph> + <paragraph id="par_id061420180547284492" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547288316" role="bascode" localize="false" xml-lang="en-US">RowName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547284556" xml-lang="en-US" localize="false">GetColumnIndex</h3> + <bascode> + <paragraph id="par_id061420180547285812" role="bascode" localize="false" xml-lang="en-US">Function GetColumnIndex(</paragraph> + <paragraph id="par_id061420180547287653" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061420180547285010" role="bascode" localize="false" xml-lang="en-US">ColName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547285141" xml-lang="en-US" localize="false">CopySheetbyName</h3> + <bascode> + <paragraph id="par_id061420180547284524" role="bascode" localize="false" xml-lang="en-US">Function CopySheetbyName(</paragraph> + <paragraph id="par_id061420180547286144" role="bascode" localize="false" xml-lang="en-US">oSheets as Object, </paragraph> + <paragraph id="par_id061420180547289148" role="bascode" localize="false" xml-lang="en-US">OldName as String, </paragraph> + <paragraph id="par_id061420180547287225" role="bascode" localize="false" xml-lang="en-US">NewName as String, </paragraph> + <paragraph id="par_id061420180547299943" role="bascode" localize="false" xml-lang="en-US">DestPos as Integer) as Object</paragraph> + </bascode> + <h3 id="hd_id0614201805472944" xml-lang="en-US" localize="false">ToggleWindow</h3> + <paragraph id="par_id061420180547292068" role="paragraph" xml-lang="en-US" localize="false">' Dis-or enables a Window and adjusts the mousepointer accordingly</paragraph> + <bascode> + <paragraph id="par_id061420180547296555" role="bascode" localize="false" xml-lang="en-US">Sub ToggleWindow(bDoEnable as Boolean)</paragraph> + </bascode> + <h3 id="hd_id061420180547294361" xml-lang="en-US" localize="false">CheckNewSheetname</h3> + <bascode> + <paragraph id="par_id061420180547292565" role="bascode" localize="false" xml-lang="en-US">Function CheckNewSheetname(</paragraph> + <paragraph id="par_id061420180547293242" role="bascode" localize="false" xml-lang="en-US">oSheets as Object, </paragraph> + <paragraph id="par_id061420180547297240" role="bascode" localize="false" xml-lang="en-US">Sheetname as String, </paragraph> + <paragraph id="par_id061420180547294328" role="bascode" localize="false" xml-lang="en-US">Optional oLocale) as String</paragraph> + </bascode> + <h3 id="hd_id061420180547298278" xml-lang="en-US" localize="false">AddNewSheetName</h3> + <bascode> + <paragraph id="par_id061420180547299974" role="bascode" localize="false" xml-lang="en-US">Sub AddNewSheetName(</paragraph> + <paragraph id="par_id061420180547292009" role="bascode" localize="false" xml-lang="en-US">oSheets as Object, </paragraph> + <paragraph id="par_id061420180547293223" role="bascode" localize="false" xml-lang="en-US">ByVal SheetName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547293964" xml-lang="en-US" localize="false">GetSheetIndex</h3> + <bascode> + <paragraph id="par_id06142018054729713" role="bascode" localize="false" xml-lang="en-US">Function GetSheetIndex(oSheets, sName) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180547298034" xml-lang="en-US" localize="false">GetLastUsedRow</h3> + <bascode> + <paragraph id="par_id061420180547299520" role="bascode" localize="false" xml-lang="en-US">Function GetLastUsedRow(oSheet as Object) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180547294665" xml-lang="en-US" localize="false">ModifyBorderLineWidth</h3> + <paragraph id="par_id061420180547295117" role="paragraph" xml-lang="en-US" localize="false">' Note To set a one lined frame you have to set the inner width to 0 In the API all Units that refer to pt-Heights are "1/100mm" The convert factor from 1pt to 1/100 mm is approximately 35 </paragraph> + <bascode> + <paragraph id="par_id061420180547295225" role="bascode" localize="false" xml-lang="en-US">Function ModifyBorderLineWidth(</paragraph> + <paragraph id="par_id061420180547292084" role="bascode" localize="false" xml-lang="en-US">ByVal oStyleBorder, </paragraph> + <paragraph id="par_id061420180547292560" role="bascode" localize="false" xml-lang="en-US">iInnerLineWidth as Integer, </paragraph> + <paragraph id="par_id061420180547295476" role="bascode" localize="false" xml-lang="en-US">iOuterLineWidth as Integer)</paragraph> + </bascode> + <h3 id="hd_id06142018054729303" xml-lang="en-US" localize="false">AttachBasicMacroToEvent</h3> + <bascode> + <paragraph id="par_id061420180547296417" role="bascode" localize="false" xml-lang="en-US">Sub AttachBasicMacroToEvent(</paragraph> + <paragraph id="par_id061420180547292774" role="bascode" localize="false" xml-lang="en-US">oDocument as Object, </paragraph> + <paragraph id="par_id061420180547291074" role="bascode" localize="false" xml-lang="en-US">EventName as String, </paragraph> + <paragraph id="par_id061420180547293426" role="bascode" localize="false" xml-lang="en-US">SubPath as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547308735" xml-lang="en-US" localize="false">ModifyPropertyValue</h3> + <bascode> + <paragraph id="par_id061420180547306755" role="bascode" localize="false" xml-lang="en-US">Function ModifyPropertyValue(</paragraph> + <paragraph id="par_id061420180547304617" role="bascode" localize="false" xml-lang="en-US">oContent() as New com.sun.star.beans.PropertyValue, </paragraph> + <paragraph id="par_id061420180547301558" role="bascode" localize="false" xml-lang="en-US">TargetProperties() </paragraph> + <paragraph role="bascode" id="par_id941529062083471" xml-lang="en-US" localize="false">as New com.sun.star.beans.PropertyValue)</paragraph> + </bascode> + <h3 id="hd_id06142018054730528" xml-lang="en-US" localize="false">GetPropertyValueIndex</h3> + <bascode> + <paragraph id="par_id061420180547304668" role="bascode" localize="false" xml-lang="en-US">Function GetPropertyValueIndex(</paragraph> + <paragraph id="par_id061420180547302428" role="bascode" localize="false" xml-lang="en-US">SearchName as String, </paragraph> + <paragraph id="par_id061420180547306561" role="bascode" localize="false" xml-lang="en-US">TargetProperties() </paragraph> + <paragraph role="bascode" id="par_id971529062111510" xml-lang="en-US" localize="false">as New com.sun.star.beans.PropertyValue ) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180547305379" xml-lang="en-US" localize="false">DispatchSlot</h3> + <bascode> + <paragraph id="par_id061420180547302087" role="bascode" localize="false" xml-lang="en-US">Sub DispatchSlot(SlotID as Integer)</paragraph> + </bascode> + <h3 id="hd_id061420180547308065" xml-lang="en-US" localize="false">IsFatOffice</h3> + <paragraph id="par_id061420180547306757" role="paragraph" xml-lang="en-US" localize="false">'returns the type of the office application FatOffice = 0, WebTop = 1 This routine has to be changed if the Product Name is being changed! </paragraph> + <bascode> + <paragraph id="par_id061420180547302561" role="bascode" localize="false" xml-lang="en-US">Function IsFatOffice() As Boolean</paragraph> + </bascode> + <h3 id="hd_id06142018054730408" xml-lang="en-US" localize="false">GetLocale</h3> + <bascode> + <paragraph id="par_id061420180547306751" role="bascode" localize="false" xml-lang="en-US">Function GetLocale(</paragraph> + <paragraph id="par_id061420180547302792" role="bascode" localize="false" xml-lang="en-US">sLanguage as String, </paragraph> + <paragraph id="par_id061420180547307976" role="bascode" localize="false" xml-lang="en-US">sCountry as String)</paragraph> + </bascode> + <h3 id="hd_id061420180547305357" xml-lang="en-US" localize="false">ToggleDesignMode</h3> + <bascode> + <paragraph id="par_id061420180547301559" role="bascode" localize="false" xml-lang="en-US">Sub ToggleDesignMode(oDocument as Object)</paragraph> + </bascode> + <h3 id="hd_id061420180547301521" xml-lang="en-US" localize="false">isHighContrast</h3> + <bascode> + <paragraph id="par_id061420180547302307" role="bascode" localize="false" xml-lang="en-US">Function isHighContrast(oPeer as Object)</paragraph> + </bascode> + <h3 id="hd_id061420180547302524" xml-lang="en-US" localize="false">CreateNewDocument</h3> + <bascode> + <paragraph id="par_id061420180547302408" role="bascode" localize="false" xml-lang="en-US">Function CreateNewDocument(</paragraph> + <paragraph id="par_id061420180547306406" role="bascode" localize="false" xml-lang="en-US">sType as String, </paragraph> + <paragraph id="par_id061420180547302638" role="bascode" localize="false" xml-lang="en-US">Optional sAddMsg as String) as Object</paragraph> + </bascode> + <h3 id="hd_id061420180547306821" xml-lang="en-US" localize="false">DisposeDocument</h3> + <paragraph id="par_id061420180547308844" role="paragraph" localize="false" xml-lang="en-US">' This Sub has been used in order to ensure that after disposing a document from the backing window it is returned to the backing window, so the office won't be closed</paragraph> + <bascode> + <paragraph id="par_id061420180547301077" role="bascode" localize="false" xml-lang="en-US">Sub DisposeDocument(oDocument as Object)</paragraph> + </bascode> + <h3 id="hd_id061420180547316190" xml-lang="en-US" localize="false">CalIsLeapYear</h3> + <paragraph id="par_id061420180547311590" role="paragraph" xml-lang="en-US" localize="false">'Function to calculate if the year is a leap year</paragraph> + <bascode> + <paragraph id="par_id061420180547311314" role="bascode" localize="false" xml-lang="en-US">Function CalIsLeapYear(</paragraph> + <paragraph role="bascode" id="par_id401529062200648" xml-lang="en-US" localize="false">ByVal iYear as Integer) as Boolean</paragraph> + </bascode> + </section> + <bookmark xml-lang="en-US" branch="index" id="bm_id21529062611375"> + <bookmark_value>BASIC Tools library;ModuleControl module</bookmark_value> + </bookmark> + <section id="modulecontrols_module"> + <paragraph role="heading" id="hd_id451529005764422" level="2" xml-lang="en-US"><item type="literal">ModuleControls</item> Module</paragraph> + <paragraph role="paragraph" id="par_id841529064645990" xml-lang="en-US">Functions and subroutines for module control.</paragraph> + <h3 id="hd_id061520180728405758" xml-lang="en-US" localize="false">GetControlShape</h3> + <paragraph id="par_id061520180728404186" role="paragraph" localize="false" xml-lang="en-US">' Gets the Shape of a Control( e. g. to reset the size or Position of the control</paragraph> + <paragraph id="par_id061520180728405899" role="paragraph" localize="false" xml-lang="en-US">' Parameters:</paragraph> + <paragraph id="par_id061520180728401929" role="paragraph" localize="false" xml-lang="en-US">' The 'oContainer' is the Document or a specific sheet of a Calc - Document</paragraph> + <paragraph id="par_id061520180728406561" role="paragraph" localize="false" xml-lang="en-US">' 'CName' is the Name of the Control</paragraph> + <bascode> + <paragraph id="par_id061520180728403658" role="bascode" localize="false" xml-lang="en-US">Function GetControlShape(</paragraph> + <paragraph role="bascode" id="par_id731529060754496" xml-lang="en-US" localize="false">oContainer as Object,</paragraph> + <paragraph role="bascode" id="par_id571529060764136" xml-lang="en-US" localize="false">CName as String)</paragraph> + </bascode> + <h3 id="hd_id061520180728402154" xml-lang="en-US" localize="false">getControlView</h3> + <paragraph id="par_id061520180728406447" role="paragraph" localize="false" xml-lang="en-US">' Returns the View of a Control</paragraph> + <paragraph id="par_id061520180728405250" role="paragraph" localize="false" xml-lang="en-US">' Parameters:</paragraph> + <paragraph id="par_id061520180728407354" role="paragraph" localize="false" xml-lang="en-US">' The 'oContainer' is the Document or a specific sheet of a Calc - Document</paragraph> + <paragraph id="par_id061520180728407546" role="paragraph" localize="false" xml-lang="en-US">' The 'oController' is always directly attached to the Document</paragraph> + <paragraph id="par_id061520180728401894" role="paragraph" localize="false" xml-lang="en-US">' 'CName' is the Name of the Control</paragraph> + <bascode> + <paragraph id="par_id061520180728405914" role="bascode" localize="false" xml-lang="en-US">Function getControlView(</paragraph> + <paragraph role="bascode" id="par_id431529060800677" xml-lang="en-US" localize="false">oContainer , </paragraph> + <paragraph role="bascode" id="par_id471529060805433" xml-lang="en-US" localize="false">oController as Object, </paragraph> + <paragraph role="bascode" id="par_id501529060820866" xml-lang="en-US" localize="false">CName as String) as Object</paragraph> + </bascode> + <h3 id="hd_id061520180728409398" xml-lang="en-US" localize="false">DisposeControl</h3> + <paragraph id="par_id061520180728406445" role="paragraph" localize="false" xml-lang="en-US">' Parameters:</paragraph> + <paragraph id="par_id061520180728405024" role="paragraph" localize="false" xml-lang="en-US">' The 'oContainer' is the Document or a specific sheet of a Calc - Document</paragraph> + <paragraph id="par_id061520180728403834" role="paragraph" localize="false" xml-lang="en-US">' 'CName' is the Name of the Control</paragraph> + <bascode> + <paragraph id="par_id061520180728406007" role="bascode" localize="false" xml-lang="en-US">Function DisposeControl(</paragraph> + <paragraph role="bascode" id="par_id161529060860526" xml-lang="en-US" localize="false">oContainer as Object, </paragraph> + <paragraph role="bascode" id="par_id311529060865820" xml-lang="en-US" localize="false">CName as String) as Boolean</paragraph> + </bascode> + <h3 id="hd_id061520180728401986" xml-lang="en-US" localize="false">GetControlGroupModel</h3> + <paragraph id="par_id061520180728404727" role="paragraph" localize="false" xml-lang="en-US">' Returns a sequence of a group of controls like option buttons or checkboxes</paragraph> + <paragraph id="par_id061520180728404702" role="paragraph" localize="false" xml-lang="en-US">' The 'oContainer' is the Document or a specific sheet of a Calc - Document</paragraph> + <paragraph id="par_id061520180728402498" role="paragraph" localize="false" xml-lang="en-US">' 'sGroupName' is the Name of the Controlgroup</paragraph> + <bascode> + <paragraph id="par_id061520180728405097" role="bascode" localize="false" xml-lang="en-US">Function GetControlGroupModel(</paragraph> + <paragraph role="bascode" id="par_id271529060883844" xml-lang="en-US" localize="false">oContainer as Object, </paragraph> + <paragraph role="bascode" id="par_id131529060888366" xml-lang="en-US" localize="false">sGroupName as String )</paragraph> + </bascode> + <h3 id="hd_id061520180728404995" xml-lang="en-US" localize="false">GetRefValue</h3> + <paragraph id="par_id06152018072840427" role="paragraph" localize="false" xml-lang="en-US">' Returns the Referencevalue of a group of e.g. option buttons or check boxes</paragraph> + <paragraph id="par_id061520180728401645" role="paragraph" localize="false" xml-lang="en-US">' 'oControlGroup' is a sequence of the Control objects</paragraph> + <bascode> + <paragraph id="par_id061520180728405216" role="bascode" localize="false" xml-lang="en-US">Function GetRefValue(</paragraph> + <paragraph role="bascode" id="par_id311529060906785" xml-lang="en-US" localize="false">oControlGroup() as Object)</paragraph> + </bascode> + <h3 id="hd_id06152018072841458" xml-lang="en-US" localize="false">GetRefValueOfControlGroup</h3> + <bascode> + <paragraph id="par_id061520180728415365" role="bascode" localize="false" xml-lang="en-US">Function GetRefValueOfControlGroup(</paragraph> + <paragraph id="par_id061520180728416461" role="bascode" localize="false" xml-lang="en-US">oContainer as Object, </paragraph> + <paragraph id="par_id061520180728413768" role="bascode" localize="false" xml-lang="en-US">GroupName as String)</paragraph> + </bascode> + <h3 id="hd_id061520180728416653" xml-lang="en-US" localize="false">GetOptionGroupValue</h3> + <bascode> + <paragraph id="par_id061520180728411484" role="bascode" localize="false" xml-lang="en-US">Function GetOptionGroupValue(</paragraph> + <paragraph id="par_id061520180728412653" role="bascode" localize="false" xml-lang="en-US">oContainer as Object, </paragraph> + <paragraph id="par_id061520180728413045" role="bascode" localize="false" xml-lang="en-US">OptGroupName as String) as Boolean</paragraph> + </bascode> + <h3 id="hd_id061520180728419761" xml-lang="en-US" localize="false">WriteOptValueToCell</h3> + <bascode> + <paragraph id="par_id061520180728414297" role="bascode" localize="false" xml-lang="en-US">Function WriteOptValueToCell(</paragraph> + <paragraph id="par_id061520180728414871" role="bascode" localize="false" xml-lang="en-US">oSheet as Object, </paragraph> + <paragraph id="par_id061520180728416273" role="bascode" localize="false" xml-lang="en-US">OptGroupName as String, </paragraph> + <paragraph id="par_id061520180728411892" role="bascode" localize="false" xml-lang="en-US">iCol as Integer, </paragraph> + <paragraph id="par_id061520180728411133" role="bascode" localize="false" xml-lang="en-US">iRow as Integer) as Boolean</paragraph> + </bascode> + <h3 id="hd_id061520180728411084" xml-lang="en-US" localize="false">LoadDialog</h3> + <bascode> + <paragraph id="par_id061520180728416215" role="bascode" localize="false" xml-lang="en-US">Function LoadDialog(</paragraph> + <paragraph id="par_id061520180728415374" role="bascode" localize="false" xml-lang="en-US">Libname as String, </paragraph> + <paragraph id="par_id061520180728411337" role="bascode" localize="false" xml-lang="en-US">DialogName as String, </paragraph> + <paragraph id="par_id061520180728412212" role="bascode" localize="false" xml-lang="en-US">Optional oLibContainer)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id261558858921700">Refer to <link href="text/sbasic/guide/show_dialog.xhp#show_dialog" name="Opening a Dialog with Basic">Opening a Dialog with Basic</link> for an example of LoadDialog function.</paragraph> + <h3 id="hd_id061520180728417528" xml-lang="en-US" localize="false">GetFolderName</h3> + <bascode> + <paragraph id="par_id061520180728414273" role="bascode" localize="false" xml-lang="en-US">Sub GetFolderName(oRefModel as Object)</paragraph> + </bascode> + <h3 id="hd_id061520180728412942" xml-lang="en-US" localize="false">GetFileName</h3> + <bascode> + <paragraph id="par_id061520180728416696" role="bascode" localize="false" xml-lang="en-US">Sub GetFileName(</paragraph> + <paragraph id="par_id061520180728417082" role="bascode" localize="false" xml-lang="en-US">oRefModel as Object, </paragraph> + <paragraph id="par_id061520180728418718" role="bascode" localize="false" xml-lang="en-US">Filternames())</paragraph> + </bascode> + <h3 id="hd_id061520180728414394" xml-lang="en-US" localize="false">StoreDocument</h3> + <bascode> + <paragraph id="par_id061520180728415594" role="bascode" localize="false" xml-lang="en-US">Function StoreDocument(</paragraph> + <paragraph id="par_id061520180728417685" role="bascode" localize="false" xml-lang="en-US">oDocument as Object, </paragraph> + <paragraph id="par_id061520180728416184" role="bascode" localize="false" xml-lang="en-US">FilterNames() as String, </paragraph> + <paragraph id="par_id061520180728414290" role="bascode" localize="false" xml-lang="en-US">DefaultName as String, </paragraph> + <paragraph id="par_id061520180728419279" role="bascode" localize="false" xml-lang="en-US">DisplayDirectory as String, </paragraph> + <paragraph id="par_id061520180728421914" role="bascode" localize="false" xml-lang="en-US">Optional iAddProcedure as Integer) as String</paragraph> + </bascode> + <h3 id="hd_id061520180728424363" xml-lang="en-US" localize="false">AddFiltersToDialog</h3> + <bascode> + <paragraph id="par_id061520180728429017" role="bascode" localize="false" xml-lang="en-US">Sub AddFiltersToDialog(</paragraph> + <paragraph id="par_id061520180728424454" role="bascode" localize="false" xml-lang="en-US">FilterNames() as String, </paragraph> + <paragraph id="par_id061520180728422747" role="bascode" localize="false" xml-lang="en-US">oDialog as Object)</paragraph> + </bascode> + <h3 id="hd_id061520180728422388" xml-lang="en-US" localize="false">SwitchMousePointer</h3> + <bascode> + <paragraph id="par_id0615201807284277" role="bascode" localize="false" xml-lang="en-US">Sub SwitchMousePointer(</paragraph> + <paragraph id="par_id061520180728421877" role="bascode" localize="false" xml-lang="en-US">oWindowPeer as Object, </paragraph> + <paragraph id="par_id061520180728429500" role="bascode" localize="false" xml-lang="en-US">bDoEnable as Boolean)</paragraph> + </bascode> + <h3 id="hd_id061520180728428854" xml-lang="en-US" localize="false">ShowOverwriteAllDialog</h3> + <bascode> + <paragraph id="par_id061520180728427224" role="bascode" localize="false" xml-lang="en-US">Sub ShowOverwriteAllDialog(</paragraph> + <paragraph id="par_id06152018072842792" role="bascode" localize="false" xml-lang="en-US">FilePath as String, </paragraph> + <paragraph id="par_id061520180728429393" role="bascode" localize="false" xml-lang="en-US">sTitle as String)</paragraph> + </bascode> + <h3 id="hd_id061520180728429649" xml-lang="en-US" localize="false">SetOVERWRITEToQuery</h3> + <bascode> + <paragraph id="par_id061520180728429597" role="bascode" localize="false" xml-lang="en-US">Sub SetOVERWRITEToQuery()</paragraph> + </bascode> + <h3 id="hd_id061520180728428255" xml-lang="en-US" localize="false">SetOVERWRITEToAlways</h3> + <bascode> + <paragraph id="par_id061520180728424733" role="bascode" localize="false" xml-lang="en-US">Sub SetOVERWRITEToAlways()</paragraph> + </bascode> + <h3 id="hd_id06152018072842702" xml-lang="en-US" localize="false">SetOVERWRITEToNever</h3> + <bascode> + <paragraph id="par_id061520180728429250" role="bascode" localize="false" xml-lang="en-US">Sub SetOVERWRITEToNever()</paragraph> + </bascode> + </section> + <bookmark xml-lang="en-US" branch="index" id="bm_id271529062660965"> + <bookmark_value>BASIC Tools library;Strings module</bookmark_value> + </bookmark> + <section id="strings_module"> + <paragraph role="heading" id="hd_id461529005770576" level="2" xml-lang="en-US"><item type="literal">Strings</item> Module</paragraph> + <paragraph role="paragraph" id="par_id631529064722315" xml-lang="en-US">Advanced functions and subroutines for string manipulation.</paragraph> + <h3 id="hd_id061420180708276674" xml-lang="en-US" localize="false">ElimChar</h3> + <bascode> + <paragraph id="par_id061420180708276186" role="bascode" localize="false" xml-lang="en-US">Function ElimChar(</paragraph> + <paragraph role="bascode" id="par_id551529060984480" xml-lang="en-US" localize="false">ByVal BigString as String, </paragraph> + <paragraph role="bascode" id="par_id871529060990727" xml-lang="en-US" localize="false">ElimArray() as String)</paragraph> + </bascode> + <h3 id="hd_id061420180708279224" xml-lang="en-US" localize="false">DeleteStr</h3> + <paragraph id="par_id061420180708275363" role="paragraph" localize="false" xml-lang="en-US">' Deletes out of a String 'BigString' a possible Partstring 'CompString'</paragraph> + <bascode> + <paragraph id="par_id061420180708303146" role="bascode" localize="false" xml-lang="en-US">Function DeleteStr(</paragraph> + <paragraph id="par_id061420180708306296" role="bascode" localize="false" xml-lang="en-US">ByVal BigString,</paragraph> + <paragraph id="par_id061420180708301803" role="bascode" localize="false" xml-lang="en-US">CompString as String) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708308611" xml-lang="en-US" localize="false">FindPartString</h3> + <paragraph id="par_id061420180708308479" role="paragraph" localize="false" xml-lang="en-US">' Finds a PartString, that is framed by the Strings 'Prestring' and 'PostString'</paragraph> + <bascode> + <paragraph id="par_id061420180708305815" role="bascode" localize="false" xml-lang="en-US">Function FindPartString(</paragraph> + <paragraph id="par_id061420180708307045" role="bascode" localize="false" xml-lang="en-US">BigString, </paragraph> + <paragraph id="par_id061420180708308079" role="bascode" localize="false" xml-lang="en-US">PreString, </paragraph> + <paragraph id="par_id061420180708302996" role="bascode" localize="false" xml-lang="en-US">PostString as String, </paragraph> + <paragraph id="par_id061420180708308715" role="bascode" localize="false" xml-lang="en-US">SearchPos as Integer) as String</paragraph> + </bascode> + <h3 id="hd_id06142018070830220" xml-lang="en-US" localize="false">PartStringInArray</h3> + <paragraph id="par_id061420180708302715" role="paragraph" localize="false" xml-lang="en-US">' Note iCompare = 0 (Binary comparison)</paragraph> + <paragraph id="par_id06142018070830615" role="paragraph" localize="false" xml-lang="en-US">' iCompare = 1 (Text comparison)</paragraph> + <bascode> + <paragraph id="par_id061420180708303506" role="bascode" localize="false" xml-lang="en-US">Function PartStringInArray(</paragraph> + <paragraph id="par_id06142018070830513" role="bascode" localize="false" xml-lang="en-US">BigArray(), </paragraph> + <paragraph id="par_id06142018070830983" role="bascode" localize="false" xml-lang="en-US">SearchString as String, </paragraph> + <paragraph id="par_id061420180708309182" role="bascode" localize="false" xml-lang="en-US">iCompare as Integer) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180708307208" xml-lang="en-US" localize="false">RTrimStr</h3> + <paragraph id="par_id061420180708304034" role="paragraph" localize="false" xml-lang="en-US">' Deletes the String 'SmallString' out of the String 'BigString'</paragraph> + <paragraph id="par_id06142018070830656" role="paragraph" localize="false" xml-lang="en-US">' in case SmallString's Position in BigString is right at the end</paragraph> + <bascode> + <paragraph id="par_id061420180708301129" role="bascode" localize="false" xml-lang="en-US">Function RtrimStr(</paragraph> + <paragraph id="par_id061420180708311705" role="bascode" localize="false" xml-lang="en-US">ByVal BigString, </paragraph> + <paragraph id="par_id061420180708312600" role="bascode" localize="false" xml-lang="en-US">SmallString as String) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708314304" xml-lang="en-US" localize="false">LTRimChar</h3> + <paragraph id="par_id061420180708318862" role="paragraph" localize="false" xml-lang="en-US">' Deletes the Char 'CompChar' out of the String 'BigString'</paragraph> + <paragraph id="par_id061420180708319364" role="paragraph" localize="false" xml-lang="en-US">' in case CompChar's Position in BigString is right at the beginning</paragraph> + <bascode> + <paragraph id="par_id061420180708313231" role="bascode" localize="false" xml-lang="en-US">Function LTRimChar(</paragraph> + <paragraph id="par_id061420180708311887" role="bascode" localize="false" xml-lang="en-US">ByVal BigString as String,</paragraph> + <paragraph id="par_id061420180708313838" role="bascode" localize="false" xml-lang="en-US">CompChar as String) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708314113" xml-lang="en-US" localize="false">ArrayOutOfString</h3> + <paragraph id="par_id061420180708315726" role="paragraph" localize="false" xml-lang="en-US">' Retrieves an Array out of a String.</paragraph> + <paragraph id="par_id061420180708316680" role="paragraph" localize="false" xml-lang="en-US">' The fields of the Array are separated by the parameter 'Separator', that is contained</paragraph> + <paragraph id="par_id06142018070831860" role="paragraph" localize="false" xml-lang="en-US">' in the Array</paragraph> + <paragraph id="par_id061420180708318872" role="paragraph" localize="false" xml-lang="en-US">' The Array MaxIndex delivers the highest Index of this Array</paragraph> + <bascode> + <paragraph id="par_id061420180708313417" role="bascode" localize="false" xml-lang="en-US">Function ArrayOutOfString(</paragraph> + <paragraph id="par_id061420180708317368" role="bascode" localize="false" xml-lang="en-US">BigString, </paragraph> + <paragraph id="par_id061420180708314602" role="bascode" localize="false" xml-lang="en-US">Separator as String, </paragraph> + <paragraph id="par_id061420180708311676" role="bascode" localize="false" xml-lang="en-US">Optional MaxIndex as Integer)</paragraph> + </bascode> + <h3 id="hd_id061420180708313207" xml-lang="en-US" localize="false">ClearArray</h3> + <paragraph id="par_id06142018070831823" role="paragraph" localize="false" xml-lang="en-US">' Deletes all fieldvalues in one-dimensional Array</paragraph> + <bascode> + <paragraph id="par_id061420180708315325" role="bascode" localize="false" xml-lang="en-US">Sub ClearArray(BigArray)</paragraph> + </bascode> + <h3 id="hd_id061420180708315939" xml-lang="en-US" localize="false">ClearMultiDimArray</h3> + <paragraph id="par_id061420180708319653" role="paragraph" localize="false" xml-lang="en-US">' Deletes all fieldvalues in a multidimensional Array</paragraph> + <bascode> + <paragraph id="par_id061420180708314941" role="bascode" localize="false" xml-lang="en-US">Sub ClearMultiDimArray(</paragraph> + <paragraph role="bascode" id="par_id681529061123165" xml-lang="en-US" localize="false">BigArray,</paragraph> + <paragraph role="bascode" id="par_id981529061129190" xml-lang="en-US" localize="false">DimCount as integer)</paragraph> + </bascode> + <h3 id="hd_id0614201807083186" xml-lang="en-US" localize="false">FieldinArray</h3> + <paragraph id="par_id061420180708316541" role="paragraph" localize="false" xml-lang="en-US">' Checks if a Field (LocField) is already defined in an Array</paragraph> + <paragraph id="par_id061420180708319616" role="paragraph" localize="false" xml-lang="en-US">' Returns 'True' or 'False'</paragraph> + <bascode> + <paragraph id="par_id061420180708314166" role="bascode" localize="false" xml-lang="en-US">Function FieldinArray(</paragraph> + <paragraph id="par_id061420180708312267" role="bascode" localize="false" xml-lang="en-US">LocArray(), </paragraph> + <paragraph id="par_id061420180708312072" role="bascode" localize="false" xml-lang="en-US">MaxIndex as integer, </paragraph> + <paragraph id="par_id061420180708316376" role="bascode" localize="false" xml-lang="en-US">LocField as String) As Boolean</paragraph> + </bascode> + <h3 id="hd_id061420180708311512" xml-lang="en-US" localize="false">FieldinList</h3> + <paragraph id="par_id061420180708322561" role="paragraph" localize="false" xml-lang="en-US">' Checks if a Field (LocField) is already defined in an Array</paragraph> + <paragraph id="par_id061420180708329146" role="paragraph" localize="false" xml-lang="en-US">' Returns 'True' or 'False'</paragraph> + <bascode> + <paragraph id="par_id061420180708323174" role="bascode" localize="false" xml-lang="en-US">Function FieldinList(</paragraph> + <paragraph id="par_id061420180708323053" role="bascode" localize="false" xml-lang="en-US">LocField, </paragraph> + <paragraph id="par_id06142018070832420" role="bascode" localize="false" xml-lang="en-US">BigList()) As Boolean</paragraph> + </bascode> + <h3 id="hd_id061420180708323374" xml-lang="en-US" localize="false">IndexinArray</h3> + <paragraph id="par_id061420180708321488" role="paragraph" localize="false" xml-lang="en-US">' Retrieves the Index of the delivered String 'SearchString' in</paragraph> + <paragraph id="par_id061420180708323577" role="paragraph" localize="false" xml-lang="en-US">' the Array LocList()'</paragraph> + <bascode> + <paragraph id="par_id061420180708322202" role="bascode" localize="false" xml-lang="en-US">Function IndexinArray(</paragraph> + <paragraph id="par_id061420180708321376" role="bascode" localize="false" xml-lang="en-US">SearchString as String, </paragraph> + <paragraph id="par_id061420180708321330" role="bascode" localize="false" xml-lang="en-US">LocList()) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180708324642" xml-lang="en-US" localize="false">MultiArrayInListbox</h3> + <bascode> + <paragraph id="par_id061420180708326283" role="bascode" localize="false" xml-lang="en-US">Sub MultiArrayInListbox(</paragraph> + <paragraph id="par_id061420180708323785" role="bascode" localize="false" xml-lang="en-US">oDialog as Object, </paragraph> + <paragraph id="par_id061420180708325943" role="bascode" localize="false" xml-lang="en-US">ListboxName as String, </paragraph> + <paragraph id="par_id061420180708321048" role="bascode" localize="false" xml-lang="en-US">ValList(), </paragraph> + <paragraph id="par_id061420180708326030" role="bascode" localize="false" xml-lang="en-US">iDim as Integer)</paragraph> + </bascode> + <h3 id="hd_id061420180708325766" xml-lang="en-US" localize="false">StringInMultiArray</h3> + <paragraph id="par_id061420180708328772" role="paragraph" localize="false" xml-lang="en-US">' Searches for a String in a two-dimensional Array by querying all Searchindexes of the second dimension </paragraph> + <paragraph id="par_id061420180708324136" role="paragraph" localize="false" xml-lang="en-US">' and delivers the specific String of the ReturnIndex in the second dimension of the Searchlist()</paragraph> + <bascode> + <paragraph id="par_id061420180708326799" role="bascode" localize="false" xml-lang="en-US">Function StringInMultiArray(</paragraph> + <paragraph id="par_id061420180708324098" role="bascode" localize="false" xml-lang="en-US">SearchList(), </paragraph> + <paragraph id="par_id061420180708325264" role="bascode" localize="false" xml-lang="en-US">SearchString as String, </paragraph> + <paragraph id="par_id06142018070832793" role="bascode" localize="false" xml-lang="en-US">SearchIndex as Integer, </paragraph> + <paragraph id="par_id06142018070832221" role="bascode" localize="false" xml-lang="en-US">ReturnIndex as Integer, </paragraph> + <paragraph id="par_id061420180708329795" role="bascode" localize="false" xml-lang="en-US">Optional MaxIndex as Integer) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708327934" xml-lang="en-US" localize="false">GetIndexInMultiArray</h3> + <paragraph id="par_id06142018070832514" role="paragraph" localize="false" xml-lang="en-US">' Searches for a Value in multidimensial Array by querying all Searchindices of the passed dimension </paragraph> + <paragraph id="par_id061420180708329496" role="paragraph" localize="false" xml-lang="en-US">' and delivers the Index where it is found.</paragraph> + <bascode> + <paragraph id="par_id061420180708321937" role="bascode" localize="false" xml-lang="en-US">Function GetIndexInMultiArray(</paragraph> + <paragraph id="par_id061420180708323473" role="bascode" localize="false" xml-lang="en-US">SearchList(), </paragraph> + <paragraph id="par_id061420180708329899" role="bascode" localize="false" xml-lang="en-US">SearchValue, </paragraph> + <paragraph id="par_id061420180708339789" role="bascode" localize="false" xml-lang="en-US">SearchIndex as Integer) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180708336858" xml-lang="en-US" localize="false">GetIndexForPartString_</h3> + <paragraph role="bascode" id="par_id971529015773531" xml-lang="en-US" localize="false">inMultiArray</paragraph> + <paragraph id="par_id061420180708337261" role="paragraph" localize="false" xml-lang="en-US">' Searches for a Value in multidimensial Array by querying all Searchindices of the passed dimension </paragraph> + <paragraph id="par_id061420180708334301" role="paragraph" localize="false" xml-lang="en-US">' and delivers the Index where the Searchvalue is found as a part string</paragraph> + <bascode> + <paragraph id="par_id061420180708339583" role="bascode" localize="false" xml-lang="en-US">Function GetIndexForPartStringinMultiArray(</paragraph> + <paragraph id="par_id061420180708339052" role="bascode" localize="false" xml-lang="en-US">SearchList(), </paragraph> + <paragraph id="par_id061420180708338642" role="bascode" localize="false" xml-lang="en-US">SearchValue, </paragraph> + <paragraph id="par_id061420180708335373" role="bascode" localize="false" xml-lang="en-US">SearchIndex as Integer) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180708331666" xml-lang="en-US" localize="false">ArrayfromMultiArray</h3> + <bascode> + <paragraph id="par_id061420180708331057" role="bascode" localize="false" xml-lang="en-US">Function ArrayfromMultiArray(</paragraph> + <paragraph id="par_id061420180708333679" role="bascode" localize="false" xml-lang="en-US">MultiArray as String, </paragraph> + <paragraph id="par_id061420180708337806" role="bascode" localize="false" xml-lang="en-US">iDim as Integer)</paragraph> + </bascode> + <h3 id="hd_id061420180708335847" xml-lang="en-US" localize="false">ReplaceString</h3> + <paragraph id="par_id061420180708332382" role="paragraph" localize="false" xml-lang="en-US">' Replaces the string "OldReplace" through the String "NewReplace" in the String</paragraph> + <paragraph id="par_id061420180708334998" role="paragraph" localize="false" xml-lang="en-US">' 'BigString'</paragraph> + <bascode> + <paragraph id="par_id061420180708336799" role="bascode" localize="false" xml-lang="en-US">Function ReplaceString(</paragraph> + <paragraph id="par_id061420180708337582" role="bascode" localize="false" xml-lang="en-US">ByVal Bigstring, </paragraph> + <paragraph id="par_id0614201807083370" role="bascode" localize="false" xml-lang="en-US">NewReplace, </paragraph> + <paragraph id="par_id061420180708334572" role="bascode" localize="false" xml-lang="en-US">OldReplace as String) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708336841" xml-lang="en-US" localize="false">FindSecondValue</h3> + <paragraph id="par_id061420180708337504" role="paragraph" localize="false" xml-lang="en-US">' Retrieves the second value for a next to 'SearchString' in</paragraph> + <paragraph id="par_id061420180708335341" role="paragraph" localize="false" xml-lang="en-US">' a two-dimensional string-Array</paragraph> + <bascode> + <paragraph id="par_id061420180708337932" role="bascode" localize="false" xml-lang="en-US">Function FindSecondValue(</paragraph> + <paragraph role="bascode" id="par_id771529061274912" xml-lang="en-US" localize="false">SearchString as String, </paragraph> + <paragraph role="bascode" id="par_id91529061281985" xml-lang="en-US" localize="false">TwoDimList() as String ) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708339122" xml-lang="en-US" localize="false">Power</h3> + <paragraph id="par_id061420180708332948" role="paragraph" localize="false" xml-lang="en-US">' raises a base to a certain power</paragraph> + <bascode> + <paragraph id="par_id061420180708337053" role="bascode" localize="false" xml-lang="en-US">Function Power(</paragraph> + <paragraph id="par_id061420180708337160" role="bascode" localize="false" xml-lang="en-US">Basis as Double, </paragraph> + <paragraph id="par_id061420180708335666" role="bascode" localize="false" xml-lang="en-US">Exponent as Double) as Double</paragraph> + </bascode> + <h3 id="hd_id0614201807083362" xml-lang="en-US" localize="false">Round</h3> + <paragraph id="par_id061420180708349543" role="paragraph" localize="false" xml-lang="en-US">' rounds a Real to a given Number of Decimals</paragraph> + <bascode> + <paragraph id="par_id061420180708342039" role="bascode" localize="false" xml-lang="en-US">Function Round(</paragraph> + <paragraph id="par_id061420180708348729" role="bascode" localize="false" xml-lang="en-US">BaseValue as Double, </paragraph> + <paragraph id="par_id061420180708341926" role="bascode" localize="false" xml-lang="en-US">Decimals as Integer) as Double</paragraph> + </bascode> + <h3 id="hd_id061420180708344826" xml-lang="en-US" localize="false">FileNameoutofPath</h3> + <paragraph id="par_id061420180708348505" role="paragraph" localize="false" xml-lang="en-US">'Retrieves the mere filename out of a whole path</paragraph> + <bascode> + <paragraph id="par_id061420180708348090" role="bascode" localize="false" xml-lang="en-US">Function FileNameoutofPath(</paragraph> + <paragraph id="par_id06142018070834403" role="bascode" localize="false" xml-lang="en-US">ByVal Path as String, </paragraph> + <paragraph id="par_id061420180708347244" role="bascode" localize="false" xml-lang="en-US">Optional Separator as String) as String</paragraph> + </bascode> + <h3 id="hd_id06142018070834616" xml-lang="en-US" localize="false">GetFileNameExtension</h3> + <bascode> + <paragraph id="par_id061420180708342063" role="bascode" localize="false" xml-lang="en-US">Function GetFileNameExtension(</paragraph> + <paragraph id="par_id06142018070834483" role="bascode" localize="false" xml-lang="en-US">ByVal FileName as String)</paragraph> + </bascode> + <h3 id="hd_id061420180708342472" xml-lang="en-US" localize="false">GetFileNameWithoutExtension</h3> + <bascode> + <paragraph id="par_id061420180708347863" role="bascode" localize="false" xml-lang="en-US">Function GetFileNameWithoutExtension(</paragraph> + <paragraph id="par_id061420180708347793" role="bascode" localize="false" xml-lang="en-US">ByVal FileName as String, </paragraph> + <paragraph id="par_id061420180708341627" role="bascode" localize="false" xml-lang="en-US">Optional Separator as String)</paragraph> + </bascode> + <h3 id="hd_id061420180708347642" xml-lang="en-US" localize="false">DirectoryNameoutofPath</h3> + <bascode> + <paragraph id="par_id061420180708343404" role="bascode" localize="false" xml-lang="en-US">Function DirectoryNameoutofPath(</paragraph> + <paragraph id="par_id061420180708348454" role="bascode" localize="false" xml-lang="en-US">sPath as String, </paragraph> + <paragraph id="par_id061420180708344267" role="bascode" localize="false" xml-lang="en-US">Separator as String) as String</paragraph> + </bascode> + <h3 id="hd_id061420180708348485" xml-lang="en-US" localize="false">CountCharsinString</h3> + <bascode> + <paragraph id="par_id061420180708348315" role="bascode" localize="false" xml-lang="en-US">Function CountCharsinString(</paragraph> + <paragraph id="par_id061420180708343699" role="bascode" localize="false" xml-lang="en-US">BigString, </paragraph> + <paragraph id="par_id061420180708348022" role="bascode" localize="false" xml-lang="en-US">LocChar as String, </paragraph> + <paragraph id="par_id061420180708344991" role="bascode" localize="false" xml-lang="en-US">ByVal StartPos as Integer) as Integer</paragraph> + </bascode> + <h3 id="hd_id061420180708344129" xml-lang="en-US" localize="false">BubbleSortList</h3> + <bascode> + <paragraph id="par_id061420180708343944" role="bascode" localize="false" xml-lang="en-US">Function BubbleSortList(</paragraph> + <paragraph id="par_id061420180708347334" role="bascode" localize="false" xml-lang="en-US">ByVal SortList(),</paragraph> + <paragraph id="par_id061420180708352791" role="bascode" localize="false" xml-lang="en-US">optional sort2ndValue as Boolean)</paragraph> + </bascode> + <paragraph id="par_id061420180708355329" role="paragraph" localize="false" xml-lang="en-US">'This function bubble sorts an array of maximum 2 dimensions.</paragraph> + <paragraph id="par_id061420180708351446" role="paragraph" localize="false" xml-lang="en-US">'The default sorting order is the first dimension</paragraph> + <paragraph id="par_id061420180708359513" role="paragraph" localize="false" xml-lang="en-US">'Only if sort2ndValue is True the second dimension is the relevant for the sorting order</paragraph> + <h3 id="hd_id061420180708356687" xml-lang="en-US" localize="false">GetValueoutofList</h3> + <bascode> + <paragraph id="par_id061420180708359326" role="bascode" localize="false" xml-lang="en-US">Function GetValueoutofList(</paragraph> + <paragraph id="par_id061420180708358651" role="bascode" localize="false" xml-lang="en-US">SearchValue, </paragraph> + <paragraph id="par_id061420180708355610" role="bascode" localize="false" xml-lang="en-US">BigList(), </paragraph> + <paragraph id="par_id061420180708357288" role="bascode" localize="false" xml-lang="en-US">iDim as Integer, </paragraph> + <paragraph id="par_id061420180708353372" role="bascode" localize="false" xml-lang="en-US">Optional ValueIndex)</paragraph> + </bascode> + <h3 id="hd_id06142018070835957" xml-lang="en-US" localize="false">AddListtoList</h3> + <bascode> + <paragraph id="par_id061420180708359239" role="bascode" localize="false" xml-lang="en-US">Function AddListtoList(</paragraph> + <paragraph id="par_id061420180708356836" role="bascode" localize="false" xml-lang="en-US">ByVal FirstArray(), </paragraph> + <paragraph id="par_id061420180708353284" role="bascode" localize="false" xml-lang="en-US">ByVal SecondArray(), </paragraph> + <paragraph id="par_id061420180708352829" role="bascode" localize="false" xml-lang="en-US">Optional StartIndex)</paragraph> + </bascode> + <h3 id="hd_id06142018070835769" xml-lang="en-US" localize="false">CheckDouble</h3> + <bascode> + <paragraph id="par_id061420180708359797" role="bascode" localize="false" xml-lang="en-US">Function CheckDouble(DoubleString as String)</paragraph> + </bascode> + </section> + <bookmark xml-lang="en-US" branch="index" id="bm_id731529062695476"> + <bookmark_value>BASIC Tools library;UCB module</bookmark_value> + </bookmark> + <section id="ucb_module"> + <paragraph role="heading" id="hd_id461529005780299" level="2" xml-lang="en-US"><item type="literal">UCB</item> Module</paragraph> + <paragraph role="paragraph" id="par_id131529064870824" xml-lang="en-US"><emph>Universal Content Broker</emph> functions and subroutines.</paragraph> + <h3 id="hd_id061420180727434845" xml-lang="en-US" localize="false">ReadDirectories</h3> + <bascode> + <paragraph id="par_id061420180727437288" role="bascode" localize="false" xml-lang="en-US">Function ReadDirectories(</paragraph> + <paragraph id="par_id061420180727433237" role="bascode" localize="false" xml-lang="en-US">ByVal AnchorDir As String, </paragraph> + <paragraph id="par_id061420180727439074" role="bascode" localize="false" xml-lang="en-US">bRecursive as Boolean, </paragraph> + <paragraph id="par_id061420180727435295" role="bascode" localize="false" xml-lang="en-US">bcheckFileType as Boolean, </paragraph> + <paragraph id="par_id061420180727438646" role="bascode" localize="false" xml-lang="en-US">bGetByTitle as Boolean, </paragraph> + <paragraph id="par_id061420180727432828" role="bascode" localize="false" xml-lang="en-US">Optional sFileContent(), </paragraph> + <paragraph role="bascode" id="par_id641529061341375" xml-lang="en-US" localize="false">Optional sExtension as String)</paragraph> + </bascode> + <h3 id="hd_id061420180727437838" xml-lang="en-US" localize="false">AddFoldertoList</h3> + <bascode> + <paragraph id="par_id061420180727438938" role="bascode" localize="false" xml-lang="en-US">Sub AddFoldertoList(</paragraph> + <paragraph id="par_id061420180727439505" role="bascode" localize="false" xml-lang="en-US">sDirURL as String, </paragraph> + <paragraph id="par_id061420180727431203" role="bascode" localize="false" xml-lang="en-US">iDirIndex)</paragraph> + </bascode> + <h3 id="hd_id061420180727432439" xml-lang="en-US" localize="false">AddFileNameToList</h3> + <bascode> + <paragraph id="par_id061420180727436964" role="bascode" localize="false" xml-lang="en-US">Sub AddFileNameToList(</paragraph> + <paragraph id="par_id06142018072743660" role="bascode" localize="false" xml-lang="en-US">sFileArray(), </paragraph> + <paragraph id="par_id061420180727437595" role="bascode" localize="false" xml-lang="en-US">FileName as String, </paragraph> + <paragraph id="par_id061420180727438361" role="bascode" localize="false" xml-lang="en-US">FileContent as String, </paragraph> + <paragraph id="par_id061420180727438606" role="bascode" localize="false" xml-lang="en-US">bGetByTitle as Boolean, </paragraph> + <paragraph id="par_id061420180727443630" role="bascode" localize="false" xml-lang="en-US">CurIndex)</paragraph> + </bascode> + <h3 id="hd_id061420180727448222" xml-lang="en-US" localize="false">RetrieveDocTitle</h3> + <bascode> + <paragraph id="par_id061420180727449206" role="bascode" localize="false" xml-lang="en-US">Function RetrieveDocTitle(</paragraph> + <paragraph id="par_id061420180727449481" role="bascode" localize="false" xml-lang="en-US">oDocProps as Object, </paragraph> + <paragraph id="par_id061420180727442037" role="bascode" localize="false" xml-lang="en-US">sFileName as String) As String</paragraph> + </bascode> + <h3 id="hd_id061420180727441588" xml-lang="en-US" localize="false">GetRealFileContent</h3> + <paragraph id="par_id061420180727444743" role="paragraph" localize="false" xml-lang="en-US">' Retrieves The Filecontent of a Document by extracting the content</paragraph> + <paragraph id="par_id061420180727441850" role="paragraph" localize="false" xml-lang="en-US">' from the Header of the document</paragraph> + <bascode> + <paragraph id="par_id061420180727442427" role="bascode" localize="false" xml-lang="en-US">Function GetRealFileContent(</paragraph> + <paragraph role="bascode" id="par_id31529061382662" xml-lang="en-US" localize="false">FileName as String) As String</paragraph> + </bascode> + <h3 id="hd_id061420180727441712" xml-lang="en-US" localize="false">CopyRecursively</h3> + <bascode> + <paragraph id="par_id061420180727442141" role="bascode" localize="false" xml-lang="en-US">Function CopyRecursively(</paragraph> + <paragraph id="par_id061420180727444075" role="bascode" localize="false" xml-lang="en-US">SourceFilePath as String, </paragraph> + <paragraph id="par_id061420180727447821" role="bascode" localize="false" xml-lang="en-US">SourceStemDir as String, </paragraph> + <paragraph id="par_id061420180727449128" role="bascode" localize="false" xml-lang="en-US">TargetStemDir as String)</paragraph> + </bascode> + <h3 id="hd_id061420180727445345" xml-lang="en-US" localize="false">ShowHelperDialog</h3> + <paragraph id="par_id061420180727445226" role="paragraph" localize="false" xml-lang="en-US">' Opens a help url referenced by a Help ID that is retrieved from the calling button tag</paragraph> + <bascode> + <paragraph id="par_id061420180727444009" role="bascode" localize="false" xml-lang="en-US">Sub ShowHelperDialog(aEvent)</paragraph> + </bascode> + <h3 id="hd_id061420180727442283" xml-lang="en-US" localize="false">SaveDataToFile</h3> + <bascode> + <paragraph id="par_id06142018072744822" role="bascode" localize="false" xml-lang="en-US">Sub SaveDataToFile(</paragraph> + <paragraph id="par_id061420180727446132" role="bascode" localize="false" xml-lang="en-US">FilePath as String, </paragraph> + <paragraph id="par_id0614201807274429" role="bascode" localize="false" xml-lang="en-US">DataList())</paragraph> + </bascode> + <h3 id="hd_id061420180727442501" xml-lang="en-US" localize="false">LoadDataFromFile</h3> + <bascode> + <paragraph id="par_id061420180727441903" role="bascode" localize="false" xml-lang="en-US">Function LoadDataFromFile(</paragraph> + <paragraph id="par_id061420180727448904" role="bascode" localize="false" xml-lang="en-US">FilePath as String, </paragraph> + <paragraph id="par_id061420180727448778" role="bascode" localize="false" xml-lang="en-US">DataList()) as Boolean</paragraph> + </bascode> + <h3 id="hd_id06142018072744521" xml-lang="en-US" localize="false">CreateFolder</h3> + <bascode> + <paragraph id="par_id061420180727443924" role="bascode" localize="false" xml-lang="en-US">Function CreateFolder(sNewFolder) as Boolean</paragraph> + </bascode> + </section> + <section id="relatedTopics"> + <embed href="text/sbasic/python/python_platform.xhp#pythonplatform"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/lib_wikieditor.xhp b/helpcontent2/source/text/sbasic/shared/03/lib_wikieditor.xhp new file mode 100644 index 000000000..2bf31fc1a --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/lib_wikieditor.xhp @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + <meta> + <topic id="basicwikieditorlibrary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">WikiEditor Library</title> + <filename>/text/sbasic/shared/03/lib_wikieditor.xhp</filename> + </topic> + </meta> + <body> + <h1 id="hd_id31529004750471"><variable id="wikieditor_lib"><link href="text/sbasic/shared/03/lib_wikieditor.xhp" name="WikiEditor library">The <item type="literal">WikiEditor</item> Library</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id231529070133574"> + <bookmark_value>BASIC WikiEditor library</bookmark_value> + </bookmark> + <section id="howtoget"> + <embed href="text/sbasic/shared/00000003.xhp#dialoglibhowtoget"/> + </section> + <embed href="text/shared/need_help.xhp#needhelp"/> + <h2 id="hd_id841593518085848">Description</h2> + <paragraph role="paragraph" id="par_id921593518140986">The <emph>WikiEditor</emph> library only contains dialogs, it is used by <emph>Wiki Publisher</emph> bundled Java extension.</paragraph> + <note id="par_id131593538122154">This library is not used by %PRODUCTNAME Basic.</note> + </body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_array.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_array.xhp new file mode 100644 index 000000000..241bbd408 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_array.xhp @@ -0,0 +1,968 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Array" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Array service (SF_Array)</title> + <filename>/text/sbasic/shared/03/sf_array.xhp</filename> + </topic> + </meta> +<body> + +<section id="abstract"> + <bookmark xml-lang="en-US" branch="index" id="bm_id281613039222756"> + <bookmark_value>Array service</bookmark_value> + </bookmark> + + <h1 id="bm_id781582391760253"><variable id="ArrayService"><link href="text/sbasic/shared/03/sf_array.xhp" name="ScriptForge.Array Service"><literal>ScriptForge</literal>.<literal>Array</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id991582454416549">Provides a collection of methods for manipulating and transforming arrays of one dimension (vectors) and arrays of two dimensions (matrices). This includes set operations, sorting, importing from and exporting to text files.</paragraph> + <paragraph role="paragraph" id="par_id681609955015503">Arrays with more than two dimensions cannot be used with the methods in this service, the only exception being the <literal>CountDims</literal> method that accepts Arrays with any number of dimensions.</paragraph> +</section> + + <paragraph role="paragraph" id="par_id651582454426538">Array items may contain any type of value, including (sub)arrays.</paragraph> + + <h2 id="hd_id981586595097630">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Array</literal> service the <literal>ScriptForge</literal> library needs to be loaded using:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id871608192694632">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id461609955633383">Loading the library will create the <literal>SF_Array</literal> object that can be used to call the methods in the <literal>Array</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id63158659509728">The following code snippets show the various ways to call methods in the <literal>Array</literal> service (the <literal>Append</literal> method is used as an example):</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211626911224256">Dim arr : arr = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311586595097510">arr = SF_Array.Append(arr, 4)</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211626911224167">Dim arr : arr = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811586595097328">Dim svc : svc = SF_Array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id761586595097825">arr = svc.Append(arr, 4)</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211626911224417">Dim arr : arr = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821586595097892">Dim svc : svc = CreateScriptService("Array")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81586595097173">arr = svc.Append(arr, 4)</paragraph> + </bascode> + <warning id="par_id571609956486468">Because Python has built-in list and tuple support, most of the methods in the <literal>Array</literal> service are available for Basic scripts only. The only exception is <literal>ImportFromCSVFile</literal> which is supported in both Basic and Python.</warning> + <table id="tab_id221606235233835"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Array Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id361606235233835" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_array.xhp#Append" name="Append method">Append</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#AppendColumn" name="AppendColumn method">AppendColumn</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#AppendRow" name="AppendRow method">AppendRow</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Contains" name="Contains method">Contains</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#ConvertToDictionary" name="ConvertToDictionary method">ConvertToDictionary</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Copy" name="Copy method">Copy</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#CountDims" name="CountDims method">CountDims</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Difference" name="Difference method">Difference</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#ExportToTextFile" name="ExportToTextFile method">ExportToTextFile</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#ExtractColumn" name="ExtractColumn">ExtractColumn</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#ExtractRow" name="ExtractRow method">ExtractRow</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id231606235233835" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_array.xhp#Flatten" name="Flatten method">Flatten</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#ImportFromCSVFile" name="ImportFromCSVFile method">ImportFromCSVFile</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#IndexOf" name="IndexOf method">IndexOf</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Insert" name="Insert method">Insert</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#InsertSorted" name="InsertSorted method">InsertSorted</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Intersection" name="Intersection">Intersection</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Join2D" name="Join2D method">Join2D</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Prepend" name="Prepend method">Prepend</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#PrependColumn" name="PrependColumn method">PrependColumn</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#PrependRow" name="PrependRow method">PrependRow</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#RangeInit" name="RangeInit method">RangeInit</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id831606235233835" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_array.xhp#Reverse" name="Reverse method">Reverse</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Shuffle" name="Shuffle method">Shuffle</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Slice" name="Slice method">Slice</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Sort" name="Sort method">Sort</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#SortColumns" name="SortColumns method">SortColumns</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#SortRows" name="SortRows method">SortRows</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Transpose" name="Transpose method">Transpose</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#TrimArray" name="TrimArray method">TrimArray</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Union" name="Union method">Union</link><br/> + <link href="text/sbasic/shared/03/sf_array.xhp#Unique" name="Unique method">Unique</link><br/><br/> + </paragraph></tablecell> + </tablerow> + </table> + <tip id="par_id191582454485250">The first argument of most methods is the array object to be considered. It is always passed by reference and left unchanged. Methods such as Append, Prepend, etc return a new array object after their execution.</tip> + +<section id="Append"> + <comment> Append --------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id251582548992953"> + <bookmark_value>Array service;Append</bookmark_value> + </bookmark> + <h2 id="hd_id151582548992953" localize="false">Append</h2> + <paragraph role="paragraph" id="par_id931582548992953">Appends the items listed as arguments to the end of the input array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id921626975382809"> + <input>svc.Append(array_1d: any[0..*], arg0: any, [arg1: any] ...): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id471582548992953"><emph>array_1d</emph>: The pre-existing array, may be empty.</paragraph> + <paragraph role="paragraph" id="par_id531582548992953"><emph>arg0, arg1, ...</emph>: Items that will be appended to <literal>array_1d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id101582548992954">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561582548992954">a = SF_Array.Append(Array(1, 2, 3), 4, 5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541582548992954"> ' (1, 2, 3, 4, 5)</paragraph> + </bascode> +</section> + +<section id="AppendColumn"> + <comment> AppendColumn --------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id591582549679172"> + <bookmark_value>Array service;AppendColumn</bookmark_value> + </bookmark> + <h2 id="hd_id291582549679173" localize="false">AppendColumn</h2> + <paragraph role="paragraph" id="par_id241582549679173">Appends a new column to the right side of a two dimensional array. The resulting array has the same lower bounds as the initial two dimensional array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id231626975799102"> + <input>svc.AppendColumn(array_2d: any[0..*, 0..*], column: any[0..*]): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id461582549679175"><emph>array_2d</emph>: The pre-existing array, may be empty. If that array has only one dimension, it is considered as the first column of the resulting two-dimensional array.</paragraph> + <paragraph role="paragraph" id="par_id991582549679175"><emph>column</emph>: A 1-dimensional array with as many items as there are rows in <literal>array_2d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id341582549679177">Dim a As Variant, b As variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681582549679177">a = SF_Array.AppendColumn(Array(1, 2, 3), Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151582549679177"> ' ((1, 4), (2, 5), (3, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991609959313410">b = SF_Array.AppendColumn(a, Array(7, 8, 9))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681609959354695"> ' ((1, 4, 7), (2, 5, 8), (3, 6, 9))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961582550242823">c = SF_Array.AppendColumn(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381582550413514"> ' ∀ i ∈ {0 ≤ i ≤ 2} : b(0, i) ≡ i</paragraph> + </bascode> +</section> + +<section id="AppendRow"> + <comment> AppendRow ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id451582551311490"> + <bookmark_value>Array service;AppendRow</bookmark_value> + </bookmark> + <h2 id="hd_id751582551333335" localize="false">AppendRow</h2> + <paragraph role="paragraph" id="par_id941582551396374">Append to the bottom of a two dimension array a new row. The resulting array has the same lower bounds as the initial two dimension array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id371626976443125"> + <input>svc.AppendRow(array_2d: any[0..*, 0..*], row: any[0..*]): any[0..*, 0..*])</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id631582551461984"><emph>array_2d</emph>: The pre-existing array, may be empty. If that array has 1 dimension, it is considered as the first row of the resulting 2 dimension array.</paragraph> + <paragraph role="paragraph" id="par_id101582551483685"><emph>row</emph>: A 1-dimensional array with as many items as there are columns in <literal>array_2d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id521582551530025">Dim a As Variant, b As variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951582551538465">a = SF_Array.AppendRow(Array(1, 2, 3), Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id521582551545445"> ' ((1, 2, 3), (4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431582551552206">b = SF_Array..AppendRow(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851582551572028"> ' ∀ i ∈ {0 ≤ i ≤ 2} : b(i, 0) ≡ i</paragraph> + </bascode> +</section> + +<section id="Contains"> + <comment> Contains ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id521582552517869"> + <bookmark_value>Array service;Contains</bookmark_value> + </bookmark> + <h2 id="hd_id21582552517870" localize="false">Contains</h2> + <paragraph role="paragraph" id="par_id391582552517870">Check if a one dimension array contains a certain number, text or date. Text comparison can be case-sensitive or not. + <br/>Sorted input arrays must be filled homogeneously, meaning all items must be scalars of the same type (<literal>Empty</literal> and <literal>Null</literal> items are forbidden). + <br/>The result of the method is unpredictable when the array is announced as sorted and is in reality not. + <br/>A binary search is done when the array is sorted, otherwise, it is simply scanned from top to bottom and <literal>Empty</literal> and <literal>Null</literal> items are ignored.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id641626976688897"> + <input>svc.Contains(array_1d: any[0..*], tofind: any, casesensitive: bool = False, sortorder: str = ""): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451582552517871"><emph>array_1d</emph>: The array to scan.</paragraph> + <paragraph role="paragraph" id="par_id221582552517872"><emph>tofind</emph>: A number, a date or a string to find.</paragraph> + <paragraph role="paragraph" id="par_id981582552517872"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id641582553128490"><emph>sortorder</emph>: It can be either "ASC", "DESC" or "" (not sorted). The default value is "".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id651582552517872">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id111582552517872">a = SF_Array.Contains(Array("A","B","c","D"), "C", SortOrder := "ASC") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681582552517872">SF_Array.Contains(Array("A","B","c","D"), "C", CaseSensitive := True) ' False</paragraph> + </bascode> +</section> + +<section id="ConvertToDictionary"> + <comment> ConvertToDictionary ------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id441582557214489"> + <bookmark_value>Array service;ConvertToDictionary</bookmark_value> + </bookmark> + <h2 id="hd_id541582557214489" localize="false">ConvertToDictionary</h2> + <paragraph role="paragraph" id="par_id71582557214489">Store the content of a 2-columns array into a <link href="text/sbasic/shared/03/sf_dictionary.xhp" name="dictionary">ScriptForge.Dictionary</link> object. + <br/>The key will be extracted from the first column, the item from the second.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id291626977283235"> + <input>svc.ConvertToDictionary(array_2d: any[0..*, 0..1]): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id561582557214489"><emph>array_2d</emph>: Data to be converted into a <literal>ScriptForge.Dictionary</literal> object.</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id781626977460310" role="listitem">The first column must contain exclusively strings with a length greater than zero, in any order. These values will be used as labels in the dictionary.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id511626977461127" role="listitem">The second column contains the data that will be associated to the corresponding label in the dictionary.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id921582557214490">Dim a As Variant, b As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261582557214490">a = SF_Array.AppendColumn(Array("a", "b", "c"), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931582557802907">b = SF_Array.ConvertToDictionary(a)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421582557214490">MsgBox b.Item("c") ' 3</paragraph> + </bascode> +</section> + +<section id="Copy"> + <comment> Copy --------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id251582558126024"> + <bookmark_value>Array service;Copy</bookmark_value> + </bookmark> + <h2 id="hd_id991627154151529" localize="false">Copy</h2> + <paragraph role="paragraph" id="par_id571627154604275">Creates a copy of a 1D or 2D array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id901627155659667"> + <input>svc.Copy(array_nd: any[0..*]): any[0..*]</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id901627155659568"> + <input>svc.Copy(array_nd: any[0..*, 0..*]): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id191627155816815"><emph>array_nd</emph>: The 1D or 2D array to be copied.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id451627155478940">A simple assignment of an <literal>Array</literal> object will copy its reference instead of creating a copy of the object's contents. See the example below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id881627155939064">Dim a as Variant, b as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71627155939296">a = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" id="bas_id801627155939671">' The assignment below is made by reference</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461627155939477">b = a</paragraph> + <paragraph role="bascode" id="bas_id291627156013810">' Hence changing values in "b" will also change "a"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771627155939894">b(0) = 10</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531627155940118">MsgBox a(0) ' 10</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id701627155874259">By using the <literal>Copy</literal> method, a copy of the whole <literal>Array</literal> object is made. In the example below, <literal>a</literal> and <literal>b</literal> are different objects and changing values in <literal>b</literal> will not affect values in <literal>a</literal>.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id551627156150612">Dim a as Variant, b as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781627156150904">a = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" id="bas_id141627156152196">' Creates a copy of "a" using the "Copy" method</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391627156151116">b = SF_Array.Copy(a)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661627156151494">b(0) = 10</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311627156151972">MsgBox a(0) ' 1</paragraph> + </bascode> +</section> + +<section id="CountDims"> + <comment> CountDims ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id251582558126024"> + <bookmark_value>Array service;CountDims</bookmark_value> + </bookmark> + <h2 id="hd_id761582558126025" localize="false">CountDims</h2> + <paragraph role="paragraph" id="par_id671582558126025">Count the number of dimensions of an array. The result can be greater than two. + <br/>If the argument is not an array, returns -1 + <br/>If the array is not initialized, returns 0.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591626977644227"> + <input>svc.CountDims(array_nd: any): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771582558126027"><emph>array_nd</emph>: The array to examine.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id661582558126028">Dim a(1 To 10, -3 To 12, 5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291582558126028">MsgBox SF_Array.CountDims(a) ' 3</paragraph> + </bascode> +</section> + +<section id="Difference"> + <comment> Difference --------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id941582558644286"> + <bookmark_value>Array service;Difference</bookmark_value> + </bookmark> + <h2 id="hd_id21582558644287" localize="false">Difference</h2> + <paragraph role="paragraph" id="par_id91582558644287">Build a set, as a zero-based array, by applying the difference operator on the two input arrays. Resulting items originate from the first array and not from the second. + <br/>The resulting array is sorted in ascending order. + <br/>Both input arrays must be filled homogeneously, their items must be scalars of the same type. <literal>Empty</literal> and <literal>Null</literal> items are forbidden. + <br/>Text comparison can be case sensitive or not.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id311626977822374"> + <input>svc.Difference(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id271582558644287"><emph>array1_1d</emph>: A 1-dimensional reference array, whose items are examined for removal.</paragraph> + <paragraph role="paragraph" id="par_id141582558644287"><emph>array2_1d</emph>: A 1-dimensional array, whose items are subtracted from the first input array.</paragraph> + <paragraph role="paragraph" id="par_id291582559651473"><emph>casesensitive</emph>: This argument is only applicable if the arrays are populated with strings (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id141582558644288">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id971582560754091">a = SF_Array.Difference(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281582560766794"> ' ("A", "B")</paragraph> + </bascode> +</section> + +<section id="ExportToTextFile"> + <comment> ExportToTextFile --------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_iid101582629162107"> + <bookmark_value>Array service;ExportToTextFile</bookmark_value> + </bookmark> + <h2 id="hd_id231586179707778" localize="false">ExportToTextFile</h2> + <paragraph role="paragraph" id="par_id941586179707156">Write all items of the array sequentially to a text file. If the file exists already, it will be overwritten without warning.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701626978046046"> + <input>svc.ExportToTextFile(array_1d: any[0..*], filename: str, [encoding: str]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id100158617970719"><emph>array_1d</emph>: The array to export. It must contain only strings.</paragraph> + <paragraph role="paragraph" id="par_id101586179707232"><emph>filename</emph>: The name of the text file where the data will be written to. The name must be expressed according to the current <literal>FileNaming</literal> property of the <literal>SF_FileSystem</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id70158617970791"><emph>encoding</emph>: The character set that should be used. Use one of the names listed in <link href="https://www.iana.org/assignments/character-sets/character-sets.xhtml" name="IANA character sets">IANA character sets</link>. Note that %PRODUCTNAME may not implement all existing character sets (Default is "UTF-8").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id551586179707687">SF_Array.ExportToTextFile(Array("A","B","C","D"), "C:\Temp\A short file.txt")</paragraph> + </bascode> +</section> + +<section id="ExtractColumn"> + <comment> ExtractColumn ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id891582560281081"> + <bookmark_value>Array service;ExtractColumn</bookmark_value> + </bookmark> + <h2 id="hd_id721582560281081" localize="false">ExtractColumn</h2> + <paragraph role="paragraph" id="par_id171582560281082">Extract from a two dimension array a specific column as a new array. + <br/>Its lower <literal>LBound</literal> and upper <literal>UBound</literal> boundaries are identical to that of the first dimension of the input array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id251626978426782"> + <input>svc.ExtractColumn(array_2d: any[0..*, 0..*], columnindex: int): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id301582560281083"><emph>array_2d</emph>: The array from which to extract.</paragraph> + <paragraph role="paragraph" id="par_id421582560281084"><emph>columnindex</emph>: The column number to extract - must be in the interval <literal>[LBound, UBound]</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id861609975902708">'Creates a 3x3 matrix: |1, 2, 3|</paragraph> + <paragraph role="bascode" localize="false" id="par_id921609975924606">' |4, 5, 6|</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891609975939001">' |7, 8, 9|</paragraph> + <paragraph role="bascode" localize="false" id="par_id511609975955899">Dim mat as Variant, col as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831582560741676">mat = SF_Array.AppendRow(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661582560281085">mat = SF_Array.AppendRow(mat, Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941609976001528">mat = SF_Array.AppendRow(mat, Array(7, 8, 9))</paragraph> + <paragraph role="bascode" id="bas_id431609976009994">'Extracts the third column: |3, 6, 9|</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71609976022964">col = SF_Array.ExtractColumn(mat, 2)</paragraph> + </bascode> +</section> + +<section id="ExtractRow"> + <comment> ExtractRow --------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id891582561395261"> + <bookmark_value>Array service;ExtractRow</bookmark_value> + </bookmark> + <h2 id="hd_id921582561457245" localize="false">ExtractRow</h2> + <paragraph role="paragraph" id="par_id211582561467219">Extract from a two dimension array a specific row as a new array. + <br/>Its lower <literal>LBound</literal> and upper <literal>UBound</literal> boundaries are identical to that of the second dimension of the input array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id391626978560113"> + <input>svc.ExtractRow(array_2d: any[0..*, 0..*], rowindex: int): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id911582561542889"><emph>array_2d</emph>: The array from which to extract.</paragraph> + <paragraph role="paragraph" id="par_id441582561551202"><emph>rowindex</emph>: The row number to extract - must be in the interval <literal>[LBound, UBound]</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id301582561604167">'Creates a 3x3 matrix: |1, 2, 3|</paragraph> + <paragraph role="bascode" localize="false" id="bas_id100158256161206">' |4, 5, 6|</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91609976515742">' |7, 8, 9|</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911609976539433">Dim mat as Variant, row as Variant</paragraph> + <paragraph role="bascode" localize="false" id="par_id921609976603577">mat = SF_Array.AppendRow(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="par_id281609976618980">mat = SF_Array.AppendRow(mat, Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="par_id591609976629882">mat = SF_Array.AppendRow(mat, Array(7, 8, 9))</paragraph> + <paragraph role="bascode" id="bas_id431609976648017">'Extracts the first row: |1, 2, 3|</paragraph> + <paragraph role="bascode" localize="false" id="par_id781609976663979">row = SF_Array.ExtractRow(mat, 0)</paragraph> + </bascode> +</section> + +<section id="Flatten"> + <comment> Flatten ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id261585757822682"> + <bookmark_value>Array service;Flatten</bookmark_value> + </bookmark> + <h2 id="hd_id351585757822637" localize="false">Flatten</h2> + <paragraph role="paragraph" id="par_id431585757822181">Stack all single items of an array and all items in its subarrays into one new array without subarrays. Empty subarrays are ignored and subarrays with a number of dimensions greater than one are not flattened.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id551626978750851"> + <input>svc.Flatten(array_1d: any[0..*]): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id431585757822869"><emph>array_1d</emph>: The pre-existing array, may be empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id231585757822493">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id131585757822885">a = SF_Array.Flatten(Array(Array(1, 2, 3), 4, 5))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631585757822119"> ' (1, 2, 3, 4, 5)</paragraph> + </bascode> + <tip id="par_id291610040786530">You can use the <literal>Flatten</literal> method along with other methods such as <literal>Append</literal> or <literal>Prepend</literal> to concatenate a set of 1D arrays into a single 1D array.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id941610040961148">Next is an example of how the methods <literal>Flatten</literal> and <literal>Append</literal> can be combined to concatenate three arrays.</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id841610041372527">'Creates three arrays for this example</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711610041389170">Dim a as Variant, b as Variant, c as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231610041401412">a = Array(1, 2, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281610041413482">b = Array(4, 5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651610041429583">c = Array(6, 7, 8, 9)</paragraph> + <paragraph role="bascode" id="bas_id171610041440657">'Concatenates the three arrays into a single 1D array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331610041455317">Dim arr as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121610041468254">arr = SF_Array.Flatten(SF_Array.Append(a, b, c))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981610041490008">'(1, 2, 3, 4, 5, 6, 7, 8, 9)</paragraph> + </bascode> +</section> + +<section id="ImportFromCSVFile"> + <comment> ImportFromCSVFile -------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_iid101582629162107"> + <bookmark_value>Array service;ImportFromCSVFile</bookmark_value> + </bookmark> + <h2 id="hd_id581585561482142" localize="false">ImportFromCSVFile</h2> + <paragraph role="paragraph" id="par_id611585561482373">Import the data contained in a comma-separated values (CSV) file. The comma may be replaced by any character.</paragraph> + <paragraph role="paragraph" id="par_id41585562158392">The applicable CSV format is described in <link href="https://tools.ietf.org/html/rfc4180" name="CSV formats">IETF Common Format and MIME Type for CSV Files</link>.</paragraph> + <paragraph role="paragraph" id="par_id641585562341028">Each line in the file contains a full record (line splitting is not allowed). + <br/>However sequences like <literal>\n</literal>, <literal>\t</literal>, ... are left unchanged. Use <literal>SF_String</literal>.Unescape() method to manage them.</paragraph> + <paragraph role="paragraph" id="par_id231585562475026">The method returns a two dimension array whose rows correspond to a single record read in the file and whose columns correspond to a field of the record. No check is made about the coherence of the field types across columns. A best guess will be made to identify numeric and date types.</paragraph> + <paragraph role="paragraph" id="par_id101585562548245">If a line contains less or more fields than the first line in the file, an exception will be raised. Empty lines however are simply ignored. If the size of the file exceeds the number of items limit (see inside the code), a warning is raised and the array is truncated.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id121626979017138"> + <input>svc.ImportFromCSVFile(filename: str, delimiter: str = ',', dateformat: str = ''): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441585561482121"><emph>filename</emph>: The name of the text file containing the data. The name must be expressed according to the current <literal>FileNaming</literal> property of the <literal>SF_FileSystem</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id251585561482929"><emph>delimiter</emph>: A single character, usually, a comma, a semicolon or a TAB character (Default = ",").</paragraph> + <paragraph role="paragraph" id="par_id631585563491559"><emph>dateformat</emph>: A special mechanism handles dates when <literal>dateformat</literal> is either "YYYY-MM-DD", "DD-MM-YYYY" or "MM-DD-YYYY". The dash (-) may be replaced by a dot (.), a slash (/) or a space. Other date formats will be ignored. Dates defaulting to an empty string "" are considered as normal text.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id61585564516409">Consider the CSV file "myFile.csv" with the following contents:</paragraph> + <paragraph role="paragraph" id="par_id281626980354105"><input>Name,DateOfBirth,Address,City</input></paragraph> + <paragraph role="paragraph" id="par_id301626980648833"><input>Anna,2002/03/31,"Rue de l'église, 21",Toulouse</input></paragraph> + <paragraph role="paragraph" id="par_id881626980658900"><input>Fred,1998/05/04,"Rue Albert Einstein, 113A",Carcassonne</input></paragraph> + <paragraph role="paragraph" id="par_id181626979812772">The examples below in Basic and Python read the contents of the CSV file into an <literal>Array</literal> object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id391585561482567">Dim arr As Variant</paragraph> + <paragraph role="bascode" id="bas_id531585561482408">arr = SF_Array.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "YYYY/MM/DD")</paragraph> + <paragraph role="bascode" id="bas_id621585561482783">MsgBox arr(0, 3) ' City</paragraph> + <paragraph role="bascode" id="bas_id21585564425349">MsgBox arr(1, 2) ' Rue de l'église, 21</paragraph> + <paragraph role="bascode" id="bas_id831585564433851">MsgBox arr(1, 3) ' Toulouse</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id851626979992344">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571626979992587">svc = CreateScriptService("Array")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821626979992775">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" id="pyc_id511626979992999">arr = svc.ImportFromCSVFile(r"C:\Temp\myFile.csv", dateformat = "YYYY/MM/DD")</paragraph> + <paragraph role="pycode" id="pyc_id211626979993191">bas.MsgBox(arr[0][3]) # City</paragraph> + <paragraph role="pycode" id="pyc_id671626979993408">bas.MsgBox(arr[1][2]) # Rue de l'église, 21</paragraph> + <paragraph role="pycode" id="pyc_id481626979993648">bas.MsgBox(arr[1][3]) # Toulouse</paragraph> + </pycode> +</section> + +<section id="IndexOf"> + <comment> IndexOf ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id361582562709465"> + <bookmark_value>Array service;IndexOf</bookmark_value> + </bookmark> + <h2 id="hd_id741582562715741" localize="false">IndexOf</h2> + <paragraph role="paragraph" id="par_id211582562721860">Look in a one dimension array for a number, a string or a date. Text comparison can be case-sensitive or not. + <br/>If the array is sorted it must be filled homogeneously, which means that all items must be scalars of the same type (<literal>Empty</literal> and <literal>Null</literal> items are forbidden). + <br/>The result of the method is unpredictable when the array is announced as sorted and actually is not. + <br/>A binary search is performed on sorted arrays. Otherwise, arrays are simply scanned from top to bottom and <literal>Empty</literal> and <literal>Null</literal> items are ignored. + <br/> + <br/>The method returns <literal>LBound(input array) - 1</literal> if the search was not successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id741626980743030"> + <input>svc.IndexOf(array_1d: any[0..*], tofind: any, casesensitive: bool = False, sortorder: str = ''): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id315825627687760"><emph>array_1d</emph>: The array to scan.</paragraph> + <paragraph role="paragraph" id="par_id511582562775516"><emph>tofind</emph>: A number, a date or a string to find.</paragraph> + <paragraph role="paragraph" id="par_id311582562787187"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id421582562794501"><emph>sortorder</emph>: It can be either "ASC", "DESC" or "" (not sorted). The default value is "".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id291582562917140">MsgBox SF_Array.IndexOf(Array("A","B","c","D"), "C", SortOrder := "ASC") ' 2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id100158256292397">MsgBox SF_Array.IndexOf(Array("A","B","c","D"), "C", CaseSensitive := True) ' -1</paragraph> + </bascode> +</section> + +<section id="Insert"> + <comment> Insert ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id371582626951108"> + <bookmark_value>Array service;Insert</bookmark_value> + </bookmark> + <h2 id="hd_id101582626951109" localize="false">Insert</h2> + <paragraph role="paragraph" id="par_id911582626951109">Insert before a given index of the input array the items listed as arguments. + <br/>Arguments are inserted blindly. Each of them might be either a scalar of any type or a subarray.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701626981031599"> + <input>svc.Insert(array_1d: any[0..*], before: int, arg0: any, [arg1: any] ...): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id251582626951111"><emph>array_1d</emph>: The pre-existing array, may be empty.</paragraph> + <paragraph role="paragraph" id="par_id361582626951111"><emph>before</emph>: The index before which to insert; must be in the interval <literal>[LBound, UBound + 1]</literal>.</paragraph> + <paragraph role="paragraph" id="par_id41582626951111"><emph>arg0, arg1, ...</emph>: Items that will be inserted into <literal>array_1d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id11582626951112">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231582626951113">a = SF_Array.Insert(Array(1, 2, 3), 2, "a", "b")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841582626951113"> ' (1, 2, "a", "b", 3)</paragraph> + </bascode> +</section> + +<section id="InsertSorted"> + <comment> InsertSorted ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id311582627664147"> + <bookmark_value>Array service;InsertSorted</bookmark_value> + </bookmark> + <h2 id="hd_id981582627664147" localize="false">InsertSorted</h2> + <paragraph role="paragraph" id="par_id441582627664147">Inserts into a sorted array a new item on its place. + <br/>The array must be filled homogeneously, meaning that all items must be scalars of the same type. + <br/><literal>Empty</literal> and <literal>Null</literal> items are forbidden.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561626981419647"> + <input>svc.InsertSorted(array_1d: any[0..*], item: any, sortorder: str = 'ASC', casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id121582627664147"><emph>array_1d</emph>: The array into which the value will be inserted.</paragraph> + <paragraph role="paragraph" id="par_id315826276641480"><emph>item</emph>: The scalar value to insert, of the same type as the existing array items.</paragraph> + <paragraph role="paragraph" id="par_id415826279771170"><emph>sortorder</emph>: It can be either "ASC" (default) or "DESC".</paragraph> + <paragraph role="paragraph" id="par_id701582627970037"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id91582627664148">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31582627664148">a = SF_Array.InsertSorted(Array("A", "C", "a", "b"), "B", CaseSensitive := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831582627664148"> ' ("A", "B", "C", "a", "b")</paragraph> + </bascode> +</section> + +<section id="Intersection"> + <comment> Intersection ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_iid101582629162107"> + <bookmark_value>Array service;Intersection</bookmark_value> + </bookmark> + <h2 id="hd_id841582629169550" localize="false">Intersection</h2> + <paragraph role="paragraph" id="par_id71582629177169">Build a set, as a zero-based array, by applying the intersection set operator on the two input arrays. Resulting items are contained in both arrays. + <br/>The resulting array is sorted in ascending order. + <br/>Both input arrays must be filled homogeneously, in other words all items must be scalars of the same type. <literal>Empty</literal> and <literal>Null</literal> items are forbidden. + <br/>Text comparison can be case sensitive or not.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id91626981727462"> + <input>svc.Intersection(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id881582629216169"><emph>array1_1d</emph>: The first input array.</paragraph> + <paragraph role="paragraph" id="par_id191582629223038"><emph>array2_1d</emph>: The second input array.</paragraph> + <paragraph role="paragraph" id="par_id71582629230275"><emph>casesensitive</emph>: Applies to arrays populated with text items (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id331582629257228">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811582629266094">a = SF_Array.Intersection(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171582629275916"> ' ("C", "b")</paragraph> + </bascode> +</section> + +<section id="Join2D"> + <comment> Join2D ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id231583064481294"> + <bookmark_value>Array service;Join2D</bookmark_value> + </bookmark> + <h2 id="hd_id641583064481282" localize="false">Join2D</h2> + <paragraph role="paragraph" id="par_id431583064481679">Join a two-dimensional array with two delimiters, one for the columns, one for the rows.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id421626982116561"> + <input>svc.Join2D(array_2d: any [0..*, 0..*], [columndelimiter: str], [rowdelimiter: str], [quote: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821583064481534"><emph>array_2d</emph>: Each item must be either text, a number, a date or a boolean. + <br/>Dates are transformed into the YYYY-MM-DD hh:mm:ss format. + <br/>Invalid items are replaced by a zero-length string.</paragraph> + <paragraph role="paragraph" id="par_id171583066989446"><emph>columndelimiter</emph>: Delimits each column (default = Tab/Chr(9)).</paragraph> + <paragraph role="paragraph" id="par_id431583067008842"><emph>rowdelimiter</emph>: Delimits each row (default = LineFeed/Chr(10))</paragraph> + <paragraph role="paragraph" id="par_id541583067456273"><emph>quote</emph>: If <literal>True</literal>, protect strings with double quotes. The default is <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id991583064481860">' arr = | 1, 2, "A", [2020-02-29], 51, 2, "A", [2020-02-29], 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981583064481420">' | 6, 7, "this is a string", 9, 106, 7, "this is a string", 9, 10 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881583064481455">Dim arr as Variant : arr = Array()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515830644818749">arr = SF_Array.AppendRow(arr, Array(1, 2, "A", [2020-02-29], 51, 2, "A", [2020-02-29], 5))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891583064481120">arr = SF_Array.AppendRow(arr, Array(6, 7, "this is a string", 9, 106, 7, "this is a string", 9, 10))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821626983495205">Dim arrText as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151626983442821">arrText = SF_Array.Join2D(arr, ",", "/", False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661626982983761">' 1,2,A,,51,2,A,,5/6,7,this is a string,9,106,7,this is a string,9,10</paragraph> + </bascode> +</section> + +<section id="Prepend"> + <comment> Prepend -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id701582629972724"> + <bookmark_value>Array service;Prepend</bookmark_value> + </bookmark> + <h2 id="hd_id931582629986047" localize="false">Prepend</h2> + <paragraph role="paragraph" id="par_id731582630075045">Prepend at the beginning of the input array the items listed as arguments.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id281626997292148"> + <input>svc.Prepend(array_1d: any[0..*], arg0: any, [arg1: any] ...): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id321582630107068"><emph>array_1d</emph>: The pre-existing array, may be empty.</paragraph> + <paragraph role="paragraph" id="par_id915826301138550"><emph>arg0, arg1, ...</emph>: A list of items to prepend to <literal>array_1d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id321582630131988">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851582630138380">a = SF_Array.Prepend(Array(1, 2, 3), 4, 5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681582630144971"> ' (4, 5, 1, 2, 3)</paragraph> + </bascode> +</section> + +<section id="PrependColumn"> + <comment> PrependColumn -------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id211582643223924"> + <bookmark_value>Array service;PrependColumn</bookmark_value> + </bookmark> + <h2 id="hd_id25158264322311" localize="false">PrependColumn</h2> + <paragraph role="paragraph" id="par_id91582643223166">Prepend to the left side of a two dimension array a new column. The resulting array has the same lower boundaries as the initial two dimension array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id601626997478388"> + <input>svc.PrependColumn(array_2d: any[0..*, 0..*], column: any[0..*]): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id621582643223545"><emph>array_2d</emph>: The pre-existing array, may be empty. If that array has 1 dimension, it is considered as the last column of the resulting 2 dimension array.</paragraph> + <paragraph role="paragraph" id="par_id381582643223870"><emph>column</emph>: A 1-dimensional array with as many items as there are rows in <literal>array_2d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id601582643223931">Dim a As Variant, b As variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id28158264322323">a = SF_Array.PrependColumn(Array(1, 2, 3), Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901582643223295"> ' ((4, 1), (5, 2), (6, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361582643223747">b = SF_Array.PrependColumn(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821582643223417"> ' ∀ i ∈ {0 ≤ i ≤ 2} : b(0, i) ≡ i</paragraph> + </bascode> +</section> + +<section id="PrependRow"> + <comment> PrependRow ----------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id321582643611165"> + <bookmark_value>Array service;PrependRow</bookmark_value> + </bookmark> + <h2 id="hd_id921582643611272" localize="false">PrependRow</h2> + <paragraph role="paragraph" id="par_id851582643611291">Prepend a new row at the beginning of a 2-dimensional array. The resulting array has the same lower boundaries as the initial 2-dimensional array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id791626997749524"> + <input>svc.PrependRow(array_2d: any[0..*, 0..*], row: any[0..*]): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id991582643611645"><emph>array_2d</emph>: The pre-existing array, may be empty. If that array has 1 dimension, it is considered as the last row of the resulting 2-dimensional array.</paragraph> + <paragraph role="paragraph" id="par_id321582643611415"><emph>row</emph>: A 1-dimensional array containing as many items as there are columns in <literal>array_2d</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id611582643611408">Dim a As Variant, b As variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941582643611530">a = SF_Array.PrependRow(Array(1, 2, 3), Array(4, 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621582643611876"> ' ((4, 5, 6), (1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791582643611123">b = SF_Array.PrependRow(Array(), Array(1, 2, 3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621582643611263"> ' ∀ i ∈ {0 ≤ i ≤ 2} : b(i, 0) ≡ i</paragraph> + </bascode> +</section> + +<section id="RangeInit"> + <comment> RangeInit ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id321582648204011"> + <bookmark_value>Array service;RangeInit</bookmark_value> + </bookmark> + <h2 id="hd_id61582648204011" localize="false">RangeInit</h2> + <paragraph role="paragraph" id="par_id441582648204012">Initialize a new zero-based array with numeric values.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id851626997928653"> + <input>svc.RangeInit(from: num, upto: num, [bystep: num]): num[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id591582648204013"><emph>from</emph>: Value of the first item.</paragraph> + <paragraph role="paragraph" id="par_id31582648204013"><emph>upto</emph>: The last item should not exceed <literal>UpTo</literal>.</paragraph> + <paragraph role="paragraph" id="par_id581582648204014"><emph>bystep</emph>: The difference between two successive items (Default = 1).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id341582648204015">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901582648204015">a = SF_Array.RangeInit(10, 1, -1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171582648204015"> ' (10, 9, 8, 7, 6, 5, 4, 3, 2, 1)</paragraph> + </bascode> +</section> + +<section id="Reverse"> + <comment> Reverse -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id31582648806764"> + <bookmark_value>Array service;Reverse</bookmark_value> + </bookmark> + <h2 id="hd_id111582648806764" localize="false">Reverse</h2> + <paragraph role="paragraph" id="par_id451582648806764">Return the reversed one dimension input array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id71626998176865"> + <input>svc.Reverse(array_1d: any[0..*]): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id31582648806765"><emph>array_1d</emph>: The array to reverse.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id251582648806765">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31582648806765">a = SF_Array.Reverse(Array("a", 2, 3, 4))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431582648806765"> ' (4, 3, 2, "a")</paragraph> + </bascode> +</section> + +<section id="Shuffle"> + <comment> Shuffle -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id531582649200087"> + <bookmark_value>Array service;Shuffle</bookmark_value> + </bookmark> + <h2 id="hd_id731582649200088" localize="false">Shuffle</h2> + <paragraph role="paragraph" id="par_id151582649200088">Returns a random permutation of a one-dimensional array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id191626998317797"> + <input>svc.Shuffle(array_1d: any[0..*]): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id11582649200088"><emph>array_1d</emph>: The array to shuffle.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id561582649200088">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831582649200088">a = SF_Array.Shuffle(Array(1, 2, 3, 4))</paragraph> + <paragraph role="bascode" id="bas_id611582649200089"> ' Array "a" is now in random order, f.i. (2, 3, 1, 4)</paragraph> + </bascode> +</section> + +<section id="Slice"> + <comment> Slice ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id20158618418514"> + <bookmark_value>Array service;Slice</bookmark_value> + </bookmark> + <h2 id="hd_id281586184185623" localize="false">Slice</h2> + <paragraph role="paragraph" id="par_id111586184185502">Returns a subset of a one-dimensional array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id801626998508832"> + <input>svc.Slice(array_1d: any[0..*], from: int, [upto: int]): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id201586184185438"><emph>array_1d</emph>: The array to slice.</paragraph> + <paragraph role="paragraph" id="par_id921586184482370"><emph>from</emph>: The lower index in <literal>array_1d</literal> of the subarray to extract (<literal>from</literal> included)</paragraph> + <paragraph role="paragraph" id="par_id211586184471488"><emph>upto</emph>: The upper index in <literal>array_1d</literal> of the subarray to extract (<literal>upto</literal> included). The default value is the upper bound of <literal>array_1d</literal>. If <literal>upto</literal> < <literal>from</literal> then the returned array is empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id951586184185679">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151586184185884">a = SF_Array.Slice(Array(1, 2, 3, 4, 5), 1, 3) ' (2, 3, 4)</paragraph> + </bascode> +</section> + +<section id="Sort"> + <comment> Sort ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id561582649483854"> + <bookmark_value>Array service;Sort</bookmark_value> + </bookmark> + <h2 id="hd_id65158264948384" localize="false">Sort</h2> + <paragraph role="paragraph" id="par_id171582649483675">Sort a one dimension array in ascending or descending order. Text comparisons can be case-sensitive or not. + <br/>The array must be filled homogeneously, which means that items must be scalars of the same type. + <br/><literal>Empty</literal> and <literal>Null</literal> items are allowed. Conventionally <literal>Empty</literal> < <literal>Null</literal> < any other scalar value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711626998747838"> + <input>svc.Sort(array_1d: any[0..*], sortorder: str, casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id71158264948346"><emph>array_1d</emph>: The array to sort.</paragraph> + <paragraph role="paragraph" id="par_id21582649483175"><emph>sortorder</emph>: It can be either "ASC" (default) or "DESC".</paragraph> + <paragraph role="paragraph" id="par_id301582649483187"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id661582649483468">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391582649483752">a = SF_Array.Sort(Array("a", "A", "b", "B", "C"), CaseSensitive := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711582649483987"> ' ("A", "B", "C", "a", "b")</paragraph> + </bascode> +</section> + +<section id="SortColumns"> + <comment> SortColumns ---------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id51582650186361"> + <bookmark_value>Array service;SortColumns</bookmark_value> + </bookmark> + <h2 id="hd_id20158265018616" localize="false">SortColumns</h2> + <paragraph role="paragraph" id="par_id801582650186957">Return a permutation of the columns of a two dimension array, sorted on the values of a given row. + <br/>The row must be filled homogeneously, which means that all items must be scalars of the same type. + <br/><literal>Empty</literal> and <literal>Null</literal> items are allowed. Conventionally <literal>Empty</literal> < <literal>Null</literal> < any other scalar value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301626998975171"> + <input>svc.SortColumns(array_2d: any[0..*, 0..*], rowindex: int, sortorder: str, casesensitive: bool = False): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id921582650186869"><emph>array_2d</emph>: The 2-dimensional array to sort.</paragraph> + <paragraph role="paragraph" id="par_id311582650186221"><emph>rowindex</emph>: The index of the row that will be used as reference to sort the columns.</paragraph> + <paragraph role="paragraph" id="par_id34158265018698"><emph>sortorder</emph>: It can be either "ASC" (default) or "DESC".</paragraph> + <paragraph role="paragraph" id="par_id91158265018699"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671582650186608">' arr = | 5, 7, 3 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461626999366253">' | 1, 9, 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841626999366663">' | 6, 1, 8 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561582650186620">Dim arr as Variant : arr = Array(5, 7, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81626999261871">arr = SF_Array.AppendRow(arr, Array(1, 9, 5))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81626999261909">arr = SF_Array.AppendRow(arr, Array(6, 1, 8))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251582650186630">arr = SF_Array.SortColumns(arr, 2, "ASC")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671582650186588">' arr = | 7, 5, 3 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461626999366287">' | 9, 1, 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841626999366147">' | 1, 6, 8 |</paragraph> + </bascode> +</section> + +<section id="SortRows"> + <comment> SortRows ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id301582650954674"> + <bookmark_value>Array service;SortRows</bookmark_value> + </bookmark> + <h2 id="hd_id951582650954980" localize="false">SortRows</h2> + <paragraph role="paragraph" id="par_id751582650954576">Return a permutation of the rows of a two dimension array, sorted on the values of a given column. + <br/>The column must be filled homogeneously, therefore all items must be scalars of the same type. + <br/><literal>Empty</literal> and <literal>Null</literal> items are allowed. Conventionally <literal>Empty</literal> < <literal>Null</literal> < any other scalar value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id681626999672323"> + <input>svc.SortRows(array_2d: any[0..*, 0..*], columnindex: int, sortorder: str, casesensitive: bool = False): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id621582650954370"><emph>array_2d</emph>: The array to sort.</paragraph> + <paragraph role="paragraph" id="par_id361582650954796"><emph>columnindex</emph>: The index of the column that will be used as reference to sort the rows.</paragraph> + <paragraph role="paragraph" id="par_id471582650954416"><emph>sortorder</emph>: It can be either "ASC" (default) or "DESC".</paragraph> + <paragraph role="paragraph" id="par_id111582650954690"><emph>casesensitive</emph>: Only for string comparisons (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671582650186902">' arr = | 5, 7, 3 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461626999366144">' | 1, 9, 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841626999366532">' | 6, 1, 8 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561582650186071">Dim arr as Variant : arr = Array(5, 7, 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81626999264376">arr = SF_Array.AppendRow(arr, Array(1, 9, 5))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81626999260021">arr = SF_Array.AppendRow(arr, Array(6, 1, 8))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251582650186954">arr = SF_Array.SortRows(arr, 0, "ASC")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671582650186887">' arr = | 1, 9, 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461626999366241">' | 5, 7, 3 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841626999366088">' | 6, 1, 8 |</paragraph> + </bascode> +</section> + +<section id="Transpose"> + <comment> Transpose ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id591582651575793"> + <bookmark_value>Array service;Transpose</bookmark_value> + </bookmark> + <h2 id="hd_id671582651575799" localize="false">Transpose</h2> + <paragraph role="paragraph" id="par_id611582651575637">Swaps rows and columns in a two-dimensional array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561627065272658"> + <input>svc.Transpose(array_2d: any[0..*, 0..*]): any[0..*, 0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id61582651575188"><emph>array_2d</emph>: The 2-dimensional array to transpose.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id811582651575482">' arr1 = | 1, 2 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101582651575876">' | 3, 4 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211582651575535">' | 5, 6 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id45158265157597">arr1 = Array(1, 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11627066239364">arr1 = SF_Array.AppendRow(arr1, Array(3, 4))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871627066239592">arr1 = SF_Array.AppendRow(arr1, Array(5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311627066239769">arr2 = SF_Array.Transpose(arr1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261627066239952">' arr2 = | 1, 3, 5 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661627066240113">' | 2, 4, 6 |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121627066240377">MsgBox arr2(0, 2) ' 5</paragraph> + </bascode> +</section> + +<section id="TrimArray"> + <comment> TrimArray ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id501582652996740"> + <bookmark_value>Array service;TrimArray</bookmark_value> + </bookmark> + <h2 id="hd_id27158265299667" localize="false">TrimArray</h2> + <paragraph role="paragraph" id="par_id181582652996483">Remove from a one dimension array all <literal>Null</literal>, <literal>Empty</literal> and zero-length entries. + <br/>String items are trimmed with %PRODUCTNAME Basic <literal>Trim()</literal> function.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id151627066407801"> + <input>svc.TrimArray(array_1d: any[0..*]): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id111582652996147"><emph>array_1d</emph>: The array to trim.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471582652996471">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351582652996622">a = SF_Array.TrimArray(Array("A", "B", Null, " D "))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811582652996224"> ' ("A", "B", "D")</paragraph> + </bascode> +</section> + +<section id="Union"> + <comment> Union -------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_iid101582629162107"> + <bookmark_value>Array service;Union</bookmark_value> + </bookmark> + <h2 id="hd_id341582653148202" localize="false">Union</h2> + <paragraph role="paragraph" id="par_id461582653148663">Builds a set, as a zero-based array, by applying the union operator on the two input arrays. Resulting items originate from any of both arrays. + <br/>The resulting array is sorted in ascending order. + <br/>Both input arrays must be filled homogeneously, their items must be scalars of the same type. <literal>Empty</literal> and <literal>Null</literal> items are forbidden. + <br/>Text comparison can be case sensitive or not.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id631627066696377"> + <input>svc.Union(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id4715826531488"><emph>array1_1d</emph>: The first input array.</paragraph> + <paragraph role="paragraph" id="par_id51158265314898"><emph>array2_1d</emph>: The second input array.</paragraph> + <paragraph role="paragraph" id="par_id821582653148126"><emph>casesensitive</emph>: Applicable only if the arrays are populated with strings (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id121582653148214">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id341582653148520">a = SF_Array.Union(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781582653148659"> ' ("A", "B", "C", "Z", "b")</paragraph> + </bascode> +</section> + +<section id="Unique"> + <comment> Unique ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_iid101582629162107"> + <bookmark_value>Array service;Unique</bookmark_value> + </bookmark> + <h2 id="hd_id141582653464997" localize="false">Unique</h2> + <paragraph role="paragraph" id="par_id221582653464565">Build a set of unique values derived from the input array. + <br/>The input array must be filled homogeneously, its items must be scalars of the same type. <literal>Empty</literal> and <literal>Null</literal> items are forbidden. + <br/>Text comparison can be case sensitive or not.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id781627066899997"> + <input>svc.Unique(array_1d: any[0..*], casesensitive: bool = False): any[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id521582653464553"><emph>array_1d</emph>: The input array.</paragraph> + <paragraph role="paragraph" id="par_id41158265346441"><emph>casesensitive</emph>: Applicable only if the array is populated with strings (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id991582653464938">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441582653464779">a = SF_Array.Unique(Array("A", "C", "A", "b", "B"), CaseSensitive := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881582653464236"> ' ("A", "B", "C", "b")</paragraph> + </bascode> +</section> + +<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + +<section id="relatedtopics"> + <embed href="text/scalc/01/04060107.xhp#arrayfunctit"/> + <embed href="text/sbasic/shared/calc_functions.xhp#CallingCalcFunctionsh1"/> + <embed href="text/sbasic/shared/03/sf_dictionary.xhp#SFDictionary"/> +</section> + +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_base.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_base.xhp new file mode 100644 index 000000000..ee0f5b2e8 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_base.xhp @@ -0,0 +1,372 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_FormControl" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Base service</title> + <filename>/text/sbasic/shared/03/sf_base.xhp</filename> + </topic> +</meta> + +<body> +<section id="abstract"> + <bookmark localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>Base service</bookmark_value> + </bookmark> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="ctrls_h1"><link href="text/sbasic/shared/03/sf_base.xhp" name="SFDocuments.Base service"><literal>SFDocuments</literal>.<literal>Base</literal> service</link></variable></h1> + + <paragraph role="paragraph" id="par_id901619031958273">The <literal>Base</literal> service provides a number of methods and properties to facilitate the management and handling of %PRODUCTNAME Base documents.</paragraph> + <paragraph role="paragraph" id="par_id961619032060880">This service is closely related to the <literal>Document</literal> service, which provides generic methods for handling %PRODUCTNAME documents, including Base documents. Hence, the <literal>Base</literal> service extends the <literal>Document</literal> service and provides additional methods that are specific for Base documents, enabling users to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id241619032289964" role="listitem">Get access to the database contained in a Base document.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id291619032292829" role="listitem">Open form documents stored in a Base document.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id421619032296454" role="listitem">Check if a form document from a Base document is currently loaded.</paragraph> + </listitem> +</list> +</section> + + <tip id="par_id241619032941497">Refer to the <link href="text/sbasic/shared/03/sf_document.xhp" name="Document Service"><literal>Document</literal> service</link> to learn more about methods and properties that can be used to manage %PRODUCTNAME documents.</tip> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Base</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id311619033224680">The Base service can be invoked in a variety of ways. The code snippet below uses the method <literal>CreateBaseDocument</literal> from the <literal>UI</literal> service to create a new Base file.</paragraph> + <paragraph role="paragraph" id="par_id101619033666470">Note that in all examples the object <literal>oDoc</literal> is an instance of the <literal>Base</literal> service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791619033406225">Dim ui As Object, oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321619033409042">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101619033409330">Set oDoc = ui.CreateBaseDocument("C:\Documents\MyFile.odb")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id281619033570656">The <literal>Base</literal> service can also be instantiated while opening an existing Base file, as shown below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id941619033409619">Set oDoc = ui.OpenBaseDocument("C:\Documents\MyFile.odb")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id331619033713781">If a Base document is already open, it is possible to instantiate the <literal>Base</literal> service directly:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id401619033791704">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21619033791983">Set oDoc = CreateScriptService("SFDocuments.Document", "MyFile.odb")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id871623102536956">The examples above can be translated to Python as follows:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401623102395018">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311623102395289">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id561623102422597">doc = ui.CreateBaseDocument(r"C:\Documents\MyFile.odb")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id971623102443669">doc = ui.OpenBaseDocument(r"C:\Documents\MyFile.odb")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731623102477036">doc = CreateScriptService("SFDocuments.Document", "MyFile.odb")</paragraph> + </pycode> + <note id="par_id281619619980185">The use of the <emph>"SFDocuments."</emph> substring in the previous example is optional.</note> + +<table id="tab_id101619034669263"> + <tablerow> + <tablecell colspan="3"> + <paragraph id="par_id451619034669263" role="tablehead">List of Methods in the Base Service</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id981619034669263" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_base.xhp#CloseFormDocument" name="CloseFormDocument method">CloseFormDocument</link><br/> + <link href="text/sbasic/shared/03/sf_base.xhp#FormDocuments" name="FormDocuments method">FormDocuments</link><br/> + <link href="text/sbasic/shared/03/sf_base.xhp#Forms" name="Forms method">Forms</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721619034669263" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_base.xhp#GetDatabase" name="GetDatabase method">GetDatabase</link><br/> + <link href="text/sbasic/shared/03/sf_base.xhp#IsLoaded" name="IsLoaded method">IsLoaded</link><br/> + <link href="text/sbasic/shared/03/sf_base.xhp#OpenFormDocument" name="OpenFormDocument method">OpenFormDocument</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711619034669263" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_base.xhp#PrintOut" name="PrintOut method">PrintOut</link><br/> + <link href="text/sbasic/shared/03/sf_base.xhp#SetPrinter" name="SetPrinter method">SetPrinter</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + +<section id="CloseFormDocument"> + <comment> CloseFormDocument ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id341609135528912" localize="false"> + <bookmark_value>Base service;CloseFormDocument</bookmark_value> + </bookmark> + <h2 id="hd_id61161309632927" localize="false">CloseFormDocument</h2> + <paragraph role="paragraph" id="par_id801916099743199">Closes the given form document. Returns <literal>True</literal> if closure is successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id71613205516650"> + <input>svc.CloseFormDocument(formdocument: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id941619079997810"><emph>formdocument:</emph> The name of the <literal>FormDocument</literal> to be closed, as a case-sensitive string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id351619100723505">If form documents are organized in folders, it is necessary to include the folder name to specify the form document to be opened, as illustrated in the following examples:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461619100382712">oDoc.CloseFormDocument("Folder1/myFormDocument")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361623165059717">doc.CloseFormDocument('Folder1/myFormDocument')</paragraph> + </pycode> +</section> + +<section id="FormDocuments"> + <comment> FormDocuments --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id401619035409457" localize="false"> + <bookmark_value>Base service;FormDocuments</bookmark_value> + </bookmark> + <h2 id="hd_id841619035592745" localize="false">FormDocuments</h2> + <paragraph role="paragraph" id="par_id481619036833610">Returns an array with the full names (path/name) of all form documents in the Base document as a zero-based Array of strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id401623103182304"> + <input>svc.FormDocuments(): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id431619037334440">The code snippet below prints the names of all form documents in the current Base document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id121619036825329">Dim oDoc as Object, myForms as Object, formName as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371619037281873">Set oDoc = CreateScriptService("Document", ThisDataBaseDocument)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801619037282145">Set myForms = oDoc.FormDocuments()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851619037282401">For Each formName In myForms</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531619037282633"> MsgBox formName</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851619037282890">Next formName</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id691623103639534">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101623103639206">doc = CreateScriptService("Document", bas.ThisDataBaseDocument)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901623103639390">myForms = doc.FormDocuments()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id791623103639701">for formName in myForms:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741623103639861"> bas.MsgBox(formName)</paragraph> + </pycode> + <tip id="par_id921619036922844">To learn more about form documents, refer to the <link href="text/sbasic/shared/03/sf_form.xhp" name="Form service"><literal>Form</literal> service help page</link>.</tip> +</section> + +<section id="Forms"> + <comment> Forms ---------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id861619035438484" localize="false"> + <bookmark_value>Base service;Forms</bookmark_value> + </bookmark> + <h2 id="hd_id291619035603979" localize="false">Forms</h2> + <paragraph role="paragraph" id="par_id191619037523467">Depending on the parameters provided this method will return:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id781619037575043" role="listitem">A zero-based Array with the names of all the forms contained in a form document (if the <literal>Form</literal> argument is absent)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id111619037577804" role="listitem">A <literal>SFDocuments.Form</literal> object representing the form specified in the <literal>Form</literal> argument.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id851623104561457"> + <input>svc.Forms(formdocument: str): str[0..*]</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id851623104560857"> + <input>svc.Forms(formdocument: str, form: str = ''): svc</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id851623104562213"> + <input>svc.Forms(formdocument: str, form: int): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id861619037838260"><emph>formdocument:</emph> The name of a valid form document as a case-sensitive string.</paragraph> + <paragraph role="paragraph" id="par_id281619037857187"><emph>form:</emph> The name or index number of the form stored in the form document. If this argument is absent, the method will return a list with the names of all forms available in the form document.</paragraph> + <note id="par_id921619437863617">Although it is possible to use index numbers to refer to forms, this is only recommended when there is just one form in the form document. If there are two or more forms, it is preferable to use the form name instead.</note> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id21623104676805">The first line of the example below returns a list of all forms in the form document "myFormDocument". The second line returns an instance of the Form service representing the form "myForm".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id741619200190900">Dim formsList as Object : formsList = oDoc.Forms("myFormDocument")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491619200288742">Dim oForm as Object : oForm = oDoc.Forms("myFormDocument", "myForm")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id431623104770698">formsList = doc.Forms("myFormDocument")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271623104770978">form = doc.Forms("myFormDocument", "myForm")</paragraph> + </pycode> +</section> + +<section id="GetDatabase"> + <comment> GetDatabase ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id301619035470065" localize="false"> + <bookmark_value>Base service;GetDatabase</bookmark_value> + </bookmark> + <h2 id="hd_id111619035612996" localize="false">GetDatabase</h2> + <paragraph role="paragraph" id="par_id371619098340303">Returns an instance of the <link href="text/sbasic/shared/03/sf_database.xhp" name="Database service"><literal>Database</literal> service</link> that allows the execution of SQL commands on the database defined and/or stored in the current Base document</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id431623105245851"> + <input>svc.GetDatabase(user: str = '', password: str = ''): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id731619098073221"><emph>user, password:</emph> Optional login parameters as strings. The default value for both parameters is an empty string "".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id1001599408773502">Dim myDoc As Object, myDatabase As Object, ui As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631599408779968">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801599408784337">Set myDoc = ui.OpenBaseDocument("C:\Documents\myDb.odb")</paragraph> + <paragraph role="bascode" id="bas_id631615147843278">' User and password are supplied below, if needed</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741599408788321">Set myDatabase = myDoc.GetDatabase()</paragraph> + <paragraph role="bascode" id="bas_id921599408791887">' ... Run queries, SQL statements, ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id...">myDatabase.CloseDatabase()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251599408799447">myDoc.CloseDocument()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id851623104860711">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391623104860891">myDoc = ui.OpenBaseDocument(r"C:\Documents\myDb.odb")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871623104861054">myDatabase = myDoc.GetDatabase()</paragraph> + <paragraph role="pycode" id="pyc_id351623104861223"># ... Run queries, SQL statements, ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id581623104861438">myDatabase.CloseDatabase()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id751623104861711">myDoc.CloseDocument()</paragraph> + </pycode> +</section> + +<section id="IsLoaded"> + <comment> IsLoaded -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id351619035498660" localize="false"> + <bookmark_value>Base service;IsLoaded</bookmark_value> + </bookmark> + <h2 id="hd_id621619035622085" localize="false">IsLoaded</h2> + <paragraph role="paragraph" id="par_id871619098478513">Returns <literal>True</literal> if the specified <literal>FormDocument</literal> is currently open.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id831623105309694"> + <input>svc.IsLoaded(formdocument: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id981619098545701"><emph>formdocument:</emph> The name of a <literal>FormDocument</literal> to be checked, as a case-sensitive string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id271619098642739">If Not oDoc.IsLoaded("myFormDocument") Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271619099499790"> oDoc.OpenFormDocument("myFormDocument")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id301619099500376">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id871623105432127">if not doc.IsLoaded("myFormDocument"):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id401623105432534"> doc.OpenFormDocument("myFormDocument")</paragraph> + </pycode> +</section> + +<section id="OpenFormDocument"> + <comment> OpenFormDocument ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id341619035528912" localize="false"> + <bookmark_value>Base service;OpenFormDocument</bookmark_value> + </bookmark> + <h2 id="hd_id611619035632927" localize="false">OpenFormDocument</h2> + <paragraph role="paragraph" id="par_id801619099743199">Opens the specified <literal>FormDocument</literal> either in normal or in design mode.</paragraph> + <paragraph role="paragraph" id="par_id451619100075330">If the form document is already open, it is activated without changing its mode. The method returns <literal>True</literal> if the form document could be opened.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id71623105516650"> + <input>svc.OpenFormDocument(formdocument: str, designmode: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id941619099797810"><emph>formDocument:</emph> The name of the <literal>FormDocument</literal> to be opened, as a case-sensitive string.</paragraph> + <paragraph role="paragraph" id="par_id981619099816849"><emph>designmode:</emph> If this argument is <literal>True</literal> the <literal>FormDocument</literal> will be opened in design mode.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id251619100191992">Most form documents are stored in the root of the Base document and they can be opened simply using their names, as in the example below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461619100283210">oDoc.OpenFormDocument("myFormDocument")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id351619100327505">If form documents are organized in folders, it becomes necessary to include the folder name to specify the form document to be opened, as illustrated in the following example:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461619100283712">oDoc.OpenFormDocument("myFolder/myFormDocument")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361623105659717">doc.OpenFormDocument("myFormDocument")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361623105659616">doc.OpenFormDocument("myFolder/myFormDocument")</paragraph> + </pycode> +</section> + +<section id="PrintOut"> + <comment> PrintOut ---------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721985200121249"> + <bookmark_value>Base service;PrintOut</bookmark_value> + </bookmark> + <h2 id="hd_id261589202101415" localize="false">PrintOut</h2> + <paragraph role="paragraph" id="par_id156589200121138">This method sends the content of the given form document to a default printer or a printer defined by the <literal>SetPrinter()</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id981611169416934">Returns <literal>True</literal> if the document was successfully printed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622827822169"> + <input>svc.PrintOut(opt formdocument: str, pages: str = "", copies: num = 1): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id368519200121646"><emph>formdocument</emph>: A valid document form name as a case-sensitive string. The form document must be open. It is activated by the method.</paragraph> + <paragraph role="paragraph" id="par_id211635436910093"><emph>pages</emph>: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.</paragraph> + <paragraph role="paragraph" id="par_id141635436912146"><emph>copies</emph>: The number of copies. Default is 1.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891589200121516">If oDoc.PrintOut("myForm", "1-4;10;15-18", Copies := 2) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515892500606125"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751682227903730">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622728946898">if doc.PrintOut('myForm', copies=3, pages='45-88'):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221628227947414"> # ...</paragraph> + </pycode> +</section> + +<section id="SetPrinter"> + <comment> SetPrinter ------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158921504765"> + <bookmark_value>Base service;SetPrinter</bookmark_value> + </bookmark> + <h2 id="hd_id811589502147824" localize="false">SetPrinter</h2> + <paragraph role="paragraph" id="par_id911298505147502">Define the printer options for a form document. The form document must be open.</paragraph> + <paragraph role="paragraph" id="par_id381651114800685">Returns <literal>True</literal> when successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id261652828596855"> + <input>svc.SetPrinter(opt formdocument: str, opt printer: str, opt orientation: str, paperformat: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id961635950394507"><emph>formdocument</emph>: A valid document form name as a case-sensitive string.</paragraph> + <embed href="text/sbasic/shared/03/sf_document.xhp#setPrinterArgs"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id431589204157164">oDoc.SetPrinter("myForm", Orientation := "PORTRAIT")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941628229095519">doc.SetPrinter('myForm', paperformat='TABLOID')</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_database.xhp#DatabaseService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + <embed href="text/sbasic/shared/03/sf_form.xhp#FormService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> + + </body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_basic.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_basic.xhp new file mode 100644 index 000000000..300838e7b --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_basic.xhp @@ -0,0 +1,659 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Document" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Basic service</title> + <filename>/text/sbasic/shared/03/sf_basic.xhp</filename> + </topic> +</meta> +<body> +<section id="ScriptForge-sf_basic"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Basic service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="BasicService"><link href="text/sbasic/shared/03/sf_basic.xhp" name="Basic service"><literal>ScriptForge</literal>.<literal>Basic</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id381589189355849" xml-lang="en-US">The <literal>ScriptForge.Basic</literal> service proposes a collection of %PRODUCTNAME Basic methods to be executed in a Python context. <literal>Basic</literal> service methods reproduce the exact syntax and behaviour of Basic builtin functions. +</paragraph> +</section> + <paragraph role="paragraph" id="par_id591589189364267" xml-lang="en-US">Typical example:</paragraph> + <pycode> + <paragraph role="pycode" id="pyc_id971618493778666">bas.MsgBox('Display this text in a message box from a Python script')</paragraph> + </pycode> + <warning id="par_id151618849022977"><literal>ScriptForge</literal>.<literal>Basic</literal> service is limited to Python scripts.</warning> + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <note id="par_id141610734722352">Before using the <literal>Basic</literal> service, import the <literal>CreateScriptService()</literal> method from the <literal>scriptforge</literal> module:</note> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551610734764343">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121618496552817">bas = CreateScriptService("Basic")</paragraph> + </pycode> + <h2 id="hd_id201618922972557">Properties</h2> + <table id="tab_id991618922991909"> + <tablerow> + <tablecell><paragraph id="par_id401618922991909" role="tablehead">Name</paragraph></tablecell> + <tablecell><paragraph id="par_id591618922991909" role="tablehead">ReadOnly</paragraph></tablecell> + <tablecell><paragraph id="par_id211618922991909" role="tablehead">Type</paragraph></tablecell> + <tablecell><paragraph id="par_id971618923022846" role="tablehead">Description</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id541619003984227" localize="false" role="tablecontent">MB_OK, MB_OKCANCEL, MB_RETRYCANCEL, MB_YESNO, MB_YESNOCANCEL</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21619004009875" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111619004011627" localize="false" role="tablecontent">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id791619004012484" role="tablecontent">Values: 0, 1, 5, 4, 3</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161619003998035" localize="false" role="tablecontent">MB_ICONEXCLAMATION, MB_ICONINFORMATION, MB_ICONQUESTION, MB_ICONSTOP</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201619004097755" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981619004098700" localize="false" role="tablecontent">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311619004099683" role="tablecontent">Values: 48, 64, 32, 16<br/></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831618922991909" localize="false" role="tablecontent">MB_ABORTRETRYIGNORE, MB_DEFBUTTON1, MB_DEFBUTTON2, MB_DEFBUTTON3</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581618922991909" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161618922991910" localize="false" role="tablecontent">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211618923312141" role="tablecontent">Values: 2, 128, 256, 512</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id471618924470655" localize="false" role="tablecontent">IDABORT, IDCANCEL, IDIGNORE, IDNO, IDOK, IDRETRY, IDYES</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961618924503848" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571618924505303" localize="false" role="tablecontent">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id871618924506654" role="tablecontent">Values: 3, 2, 5, 7, 1, 4, 6<br/>Constants indicating <literal>MsgBox</literal> selected button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id421619006246768" localize="false" role="tablecontent">StarDesktop</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731619006254384" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711619006255184" role="tablecontent">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541619006255653" role="tablecontent"><link href="text/sbasic/shared/stardesktop.xhp" name="StarDesktop"><literal>StarDesktop</literal></link> object represents %PRODUCTNAME Start Center.</paragraph> + </tablecell> + </tablerow> + </table> + <table id="tab_id901611086279902"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Basic Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_basic.xhp#CDate" name="CDate method">CDate</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#CDateFromUnoDateTime" name="CDateFromUnoDateTime method">CDateFromUnoDateTime</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#CDateToUnoDateTime" name="CDateToUnoDateTime method">CDateToUnoDateTime</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertFromUrl" name="ConvertFromUrl method">ConvertFromUrl</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#ConvertToUrl" name="ConvertToUrl method">ConvertToUrl</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#CreateUnoService" name="CreateUnoService method">CreateUnoService</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#DateAdd" name="DateAdd method">DateAdd</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#DateDiff" name="DateDiff method">DateDiff</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#DatePart" name="DatePart method">DatePart</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_basic.xhp#DateValue" name="DateValue method">DateValue</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#Format" name="Format method">Format</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#GetDefaultContext" name="GetDefaultContext method">GetDefaultContext</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#GetGuiType" name="GetGuiType method">GetGuiType</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#GetPathSeparator" name="GetPathSeparator method">GetPathSeparator</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#GetSystemTicks" name="GetSystemTicks method">GetSystemTicks</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#BasicLibraries" name="BasicLibraries method">GlobalScope.BasicLibraries</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#DialogLibraries" name="DialogLibraries method">GlobalScope.DialogLibraries</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#InputBox" name="InputBox method">InputBox</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611086279903" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_basic.xhp#MsgBox" name="MsgBox method">MsgBox</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#Now" name="Now method">Now</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#RGB" name="RGB method">RGB</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#ThisComponent" name="ThisComponent method">ThisComponent</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#ThisDatabaseDocument" name="ThisDatabaseDocument method">ThisDatabaseDocument</link><br/> + <link href="text/sbasic/shared/03/sf_basic.xhp#Xray" name="Xray method">Xray</link><br/><br/><br/><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + +<section id="CDate"> + <comment> CDate ------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969187"> + <bookmark_value>Basic service;CDate</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698020" localize="false">CDate</h2> + <paragraph role="paragraph" id="par_id71621894830071">Converts a numeric expression or a string to a <literal>datetime</literal>.<literal>datetime</literal> Python native object.</paragraph> + <note id="par_id431621896441258">This method exposes the Basic builtin function <link href="text/sbasic/shared/03100300.xhp" name="CDate_Basic">CDate</link> to Python scripts.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897208785"> + <input>svc.CDate(expression: any): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896675880"><emph>expression</emph>: a numeric expression or a string representing a date.</paragraph> + <embed href="text/sbasic/shared/03100300.xhp#CDate_str_date"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621898860952">d = bas.CDate(1000.25)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861621898933001">bas.MsgBox(str(d)) # 1902-09-26 06:00:00</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871621898933281">bas.MsgBox(d.year) # 1902</paragraph> + </pycode> +</section> + +<section id="CDateFromUnoDateTime"> + <comment> CDateFromUnoDateTime ------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969335"> + <bookmark_value>Basic service;CDateFromUnoDateTime</bookmark_value> + </bookmark> + <h2 id="hd_id201589199691468" localize="false">CDateFromUnoDateTime</h2> + <paragraph role="paragraph" id="par_id481621950748686">Converts a UNO date/time representation to a <literal>datetime.datetime</literal> Python native object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id691621950580345"> + <input>svc.CDateFromUnoDateTime(unodate: uno): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id41621950816227"><emph>unodate</emph>: A UNO date/time object of one of the following types: <literal>com.sun.star.util.DateTime</literal>, <literal>com.sun.star.util.Date</literal> or <literal>com.sun.star.util.Time</literal></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id281621952224847">The following example creates a <literal>com.sun.star.util.DateTime</literal> object and converts it to a <literal>datetime.datetime</literal> Python object.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id651621951946709">import uno</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931621951947749">uno_date = uno.createUnoStruct('com.sun.star.util.DateTime')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id711621951947956">uno_date.Year = 1983</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id1001621951948124">uno_date.Month = 2</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201621951948284">uno_date.Day = 23</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id911621952103058">new_date = bas.CDateFromUnoDateTime(uno_date)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951621952103813">bas.MsgBox(str(new_date)) # 1983-02-23 00:00:00</paragraph> + </pycode> +</section> + +<section id="CDateToUnoDateTime"> + <comment> CDateToUnoDateTime ------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919967133"> + <bookmark_value>Basic service;CDateToUnoDateTime</bookmark_value> + </bookmark> + <h2 id="hd_id201589199690087" localize="false">CDateToUnoDateTime</h2> + <paragraph role="paragraph" id="par_id741621952469980">Converts a date representation into a <literal>com.sun.star.util.DateTime</literal> object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id691621950580116"> + <input>svc.CDateToUnoDateTime(date: obj): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id511621952524000"><emph>date</emph>: A Python date/time object of one of the following types: <literal>datetime.datetime</literal>, <literal>datetime.date</literal>, <literal>datetime.time</literal>, <literal>float (time.time)</literal> or <literal>time.struct_time</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id131621952700723">from datetime import datetime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391621952700963">current_datetime = datetime.now()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941621952701150">uno_date = bas.CDateToUnoDateTime(current_datetime)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id191621952701458">bas.MsgBox(str(uno_date.Year) + "-" + str(uno_date.Month) + "-" + str(uno_date.Day))</paragraph> + </pycode> +</section> + +<section id="ConvertFromUrl"> + <comment> ConvertFromUrl ------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Basic service;ConvertFromUrl</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">ConvertFromUrl</h2> + <paragraph role="paragraph" id="par_id93158919969864">Returns a system path file name for the given <literal>file:</literal> URL.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id201618496409224"><input>svc.ConvertFromUrl(url: str): str</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id321618502481706"> <emph>url</emph>: An absolute <literal>file:</literal> URL.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id81618502493505">A system path file name.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id41158919969836">filename = bas.ConvertFromUrl( "file:///C:/Program%20Files%20(x86)/LibreOffice/News.txt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id881611147617212">bas.MsgBox(filename)</paragraph> + </pycode> +</section> + +<section id="ConvertToUrl"> + <comment> ConvertToUrl --------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121249"> + <bookmark_value>Basic service;ConvertToUrl</bookmark_value> + </bookmark> + <h2 id="hd_id261589210021415" localize="false">ConvertToUrl</h2> + <paragraph role="paragraph" id="par_id658519200121138">Returns a <literal>file:</literal> URL for the given system path.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id761618501052294" localize="false"><input>svc.ConvertToUrl(systempath: str): str</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401618521015903"><emph>systempath</emph>: A system file name as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id61658101307414">A <literal>file:</literal> URL as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891985200121516">url = bas.ConvertToUrl( 'C:\Program Files(x86)\LibreOffice\News.txt')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id51589200605125">bas.MsgBox(url)</paragraph> + </pycode> +</section> + +<section id="CreateUnoService"> + <comment> CreateUnoService ----------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121249"> + <bookmark_value>Basic service;CreateUnoService</bookmark_value> + </bookmark> + <h2 id="hd_id261589200121415" localize="false">CreateUnoService</h2> + <paragraph role="paragraph" id="par_id651589200121138">Instantiates a UNO service with the <literal>ProcessServiceManager</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id221618556258876" localize="false"><input>svc.CreateUnoService(servicename: str): uno</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361589200121646"><emph>servicename</emph>: A fully qualified service name such as <literal>com.sun.star.ui.dialogs.FilePicker</literal> or <literal>com.sun.star.sheet.FunctionAccess</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="bascode" localize="false" id="pyc_id891589200121516">dsk = bas.CreateUnoService('com.sun.star.frame.Desktop')</paragraph> + </pycode> +</section> + +<section id="DateAdd"> + <comment> DateAdd -------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id311599410266448"> + <bookmark_value>Basic service;DateAdd</bookmark_value> + </bookmark> + <h2 id="hd_id91599410266599" localize="false">DateAdd</h2> + <paragraph role="paragraph" id="par_id901599410483300" xml-lang="en-US">Adds a date or time interval to a given date/time a number of times and returns the resulting date.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id771618557939013" localize="false"><input>svc.DateAdd(interval: str, number: num, date: datetime): datetime</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id581618562143601"> <emph>interval</emph>: A string expression from the following table, specifying the date or time interval.</paragraph> + <embed href="text/sbasic/shared/03030110.xhp#datetable"/> + <paragraph role="paragraph" id="par_id281618562144897"><emph>number</emph>: A numerical expression specifying how often the <literal>interval</literal> value will be added when positive or subtracted when negative.</paragraph> + <paragraph role="paragraph" id="par_id811618561843272"><emph>date</emph>: A given <literal>datetime.datetime</literal> value, the <literal>interval</literal> value will be added <literal>number</literal> times to this <literal>datetime.datetime</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id181618561778320">A <literal>datetime.datetime</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id961618558341526">dt = datetime.datetime(2004, 1, 31)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891599410846998">dt = bas.DateAdd("m", 1, dt)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621599410266932">print(dt)</paragraph> + </pycode> +</section> + +<section id="DateDiff"> + <comment> DateDiff ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id601589202413561"> + <bookmark_value>Basic service;DateDiff</bookmark_value> + </bookmark> + <h2 id="hd_id611589202413141" localize="false">DateDiff</h2> + <paragraph role="paragraph" id="par_id991589202413257">Returns the number of date or time intervals between two given date/time values.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id441618562866810" localize="false"><input>svc.DateDiff(interval: str, date1: datetime, date2: datetime, firstdayofweek = 1, firstweekofyear = 1): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481618563770490"><emph>interval</emph>: A string expression specifying the date interval, as detailed in above <literal>DateAdd</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id121618563772932"><emph>date1</emph>, <emph>date2</emph>: The two <literal>datetime.datetime</literal> values to be compared.</paragraph> + <embed href="text/sbasic/shared/03030120.xhp#weekyear"/> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id121618563454738">A number.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401611153339973">date1 = datetime.datetime(2005,1, 1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121589202413630">date2 = datetime.datetime(2005,12,31)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id641618564383315">diffDays = bas.DateDiff('d', date1, date2)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151618564392035">print(diffDays)</paragraph> + </pycode> +</section> + +<section id="DatePart"> + <comment> DatePart ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id691589202925124"> + <bookmark_value>Basic service;DatePart</bookmark_value> + </bookmark> + <h2 id="hd_id3615892029256" localize="false">DatePart</h2> + <paragraph role="paragraph" id="par_id81589202925519">The <literal>DatePart</literal> function returns a specified part of a date.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id761618670376341"><input>svc.DatePart(interval: str, date: datetime, firstdayofweek = 1, firstweekofyear = 1): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id761618672192231"><emph>interval</emph>: A string expression specifying the date interval, as detailed in above <literal>DateAdd</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id61618672313838"><emph>date</emph>: The date/time from which the result is calculated.</paragraph> + <paragraph role="paragraph" id="par_id511619445271897"><emph>firstdayofweek, firstweekofyear</emph>: optional parameters that respectively specify the starting day of a week and the starting week of a year, as detailed in above <literal>DateDiff</literal> method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id791618672371743">The extracted part for the given date/time.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="bascode" localize="false" id="pyc_id31589202925376">print(bas.DatePart("ww", datetime.datetime(2005,12,31)</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id821589203188905">print(bas.DatePart('q', datetime.datetime(1999,12,30)</paragraph> + </pycode> +</section> + +<section id="DateValue"> + <comment> DateValue ------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141589203370367"> + <bookmark_value>Basic service;DateValue</bookmark_value> + </bookmark> + <h2 id="hd_id161589203370594" localize="false">DateValue</h2> + <paragraph role="paragraph" id="par_id121589203370778">Computes a date value from a date string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id721618673403017"><input>svc.DateValue(date: str): datetime</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <embed href="text/sbasic/shared/03030102.xhp#parm1"/> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id441618674018955">The computed date.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id81589203370943">dt = bas.DateValue("23-02-2011")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931618674563379">print(dt)</paragraph> + </pycode> +</section> + +<section id="Format"> + <comment> Format --------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158920514765"> + <bookmark_value>Basic service;Format</bookmark_value> + </bookmark> + <h2 id="hd_id811529844547824" localize="false">Format</h2> + <paragraph role="paragraph" id="par_id458161678389887">Converts a number to a string, and then formats it according to the format that you specify.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id901618678405855" localize="false"><input>svc.Format(expression: any, format = ''): str</input></paragraph> + <embed href="text/sbasic/shared/03120301.xhp#ValueParms"/> + <h3 id="hd_id751618825527776">Formatting Codes</h3> + <embed href="text/sbasic/shared/03120301.xhp#codes"/> + <h3 id="hd_id681618825574599">Predefined Formats</h3> + <embed href="text/sbasic/shared/03120301.xhp#formats"/> + <embed href="text/sbasic/shared/00000003.xhp#languageformat"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id431589205147164">txt = bas.Format(6328.2, '##.##0.00')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231618679147769">print(txt)</paragraph> + </pycode> +</section> + +<section id="GetDefaultContext"> + <comment> GetDefaultContext ---------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158950214765"> + <bookmark_value>Basic service;GetDefaultContext</bookmark_value> + </bookmark> + <h2 id="hd_id811589205147428" localize="false">GetDefaultContext</h2> + <paragraph role="paragraph" id="par_id451618876389887">Returns the default context of the process service factory, if existent, else returns a null reference.</paragraph> + <paragraph role="paragraph" id="par_id881618848030897"><literal>GetDefaultContext</literal> is an alternative to the <link href="text/sbasic/python/python_programming.xhp" name="getComponentContext method">getComponentContext()</link> method available from <literal>XSCRIPTCONTEXT</literal> global variable or from <link href="text/sbasic/python/python_programming.xhp" name="uno.py module">uno.py</link> module.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id901668178405855" localize="false"><input>svc.GetDefaultContext(): uno</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id381618831451271">The default component context is used, when instantiating services via <literal>XMultiServiceFactory</literal>. See the <literal>Professional UNO</literal> chapter in the Developer's Guide on <link href="https://api.libreoffice.org/" name="API Developer's Guide">api.libreoffice.org</link> for more information.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id451389205147164">ctx = bas.GetDefaultContext()</paragraph> + </pycode> +</section> + +<section id="GetGuiType"> + <comment> GetGuiType ----------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id11758950214765"> + <bookmark_value>Basic service;GetGuiType</bookmark_value> + </bookmark> + <h2 id="hd_id118589205147428" localize="false">GetGuiType</h2> + <paragraph role="paragraph" id="par_id154618876389887">Returns a numerical value that specifies the graphical user interface. This function is only provided for backward compatibility with previous versions.</paragraph> + <paragraph role="paragraph" id="par_id341618848532640">Refer to <literal>system()</literal> method from <literal>platform</literal> Python module to <link href="text/sbasic/python/python_platform.xhp" name="identify the operating system">identify the operating system</link>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id109668178405855" localize="false"><input>svc.GetGuiType(): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id154389205147164">n = bas.GetGuiType()</paragraph> + </pycode> +</section> + +<section id="GetPathSeparator"> + <comment> GetPathSeparator ---------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158950214567"> + <bookmark_value>Basic service;GetPathSeparator</bookmark_value> + </bookmark> + <h2 id="hd_id811589205147824" localize="false">GetPathSeparator</h2> + <paragraph role="paragraph" id="par_id451618876389788">Returns the operating system-dependent directory separator used to specify file paths.</paragraph> + <paragraph role="paragraph" id="par_id341618848562340">Use <literal>os.pathsep</literal> from <literal>os</literal> Python module to <link href="text/sbasic/python/python_platform.xhp" name="path delimiter">identify the path separator</link>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id901668178405558" localize="false"><input>svc.GetPathSeparator(): str</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id451389205147461">sep = bas.GetPathSeparator()</paragraph> + </pycode> +</section> + +<section id="GetSystemTicks"> + <comment> GetSystemTicks ------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71155980214765"> + <bookmark_value>Basic service;GetSystemTicks</bookmark_value> + </bookmark> + <h2 id="hd_id811589503147428" localize="false">GetSystemTicks</h2> + <paragraph role="paragraph" id="par_id451618678389887">Returns the number of system ticks provided by the operating system. You can use this function to optimize certain processes. Use this method to estimate time in milliseconds:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id901667188405855" localize="false"><input>svc.GetSystemTicks(): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id251619448108905">ticks_ini = bas.GetSystemTicks()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181619448111210">time.sleep(1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301619448111744">ticks_end = bas.GetSystemTicks()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651619448112320">bas.MsgBox("{} - {} = {}".format(ticks_end, ticks_ini,ticks_end - ticks_ini))</paragraph> + </pycode> +</section> + +<section id="BasicLibraries"> + <comment> InputBox ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id61618905161499"> + <bookmark_value>Basic service;GlobalScope.BasicLibraries</bookmark_value> + </bookmark> + <h2 id="hd_id311618905373414" localize="false">GlobalScope.BasicLibraries</h2> + <paragraph role="paragraph" id="par_id741622396277528">Returns the UNO object containing all shared Basic libraries and modules.</paragraph> + <paragraph role="paragraph" id="par_id911622396571584">This method is the Python equivalent to <literal>GlobalScope</literal>.<literal>BasicLibraries</literal> in Basic scripts.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id511622395511116"> + <input>svc.GlobalScope.BasicLibraries(): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" localize="false" id="par_id641622396435583"><link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1XLibraryContainer.html" name="LibraryContainer_API"><literal>com.sun.star.script.XLibraryContainer</literal></link></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id281622398076950">The following example loads the Gimmicks Basic library if it has not been loaded yet.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id301622397623041">libs = bas.GlobalScope.BasicLibraries()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841622397623202">if not libs.isLibraryLoaded("Gimmicks"):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621622397623352"> libs.loadLibrary("Gimmicks")</paragraph> + </pycode> +</section> + +<section id="DialogLibraries"> + <comment> InputBox ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id61618905163671"> + <bookmark_value>Basic service;GlobalScope.DialogLibraries</bookmark_value> + </bookmark> + <h2 id="hd_id311618905376155" localize="false">GlobalScope.DialogLibraries</h2> + <paragraph role="paragraph" id="par_id381622397863419">Returns the UNO object containing all shared dialog libraries.</paragraph> + <paragraph role="paragraph" id="par_id491622397863810">This method is the Python equivalent to <literal>GlobalScope</literal>.<literal>DialogLibraries</literal> in Basic scripts.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id181622395563705"> + <input>svc.GlobalScope.DialogLibraries(): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" localize="false" id="par_id641622396435133"><link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1script_1_1XLibraryContainer.html" name="LibraryContainer_API"><literal>com.sun.star.comp.sfx2.DialogLibraryContainer</literal></link></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id811622398234384">The following example shows a message box with the names of all available dialog libraries.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id561622398178727">dlg_libs = bas.GlobalScope.DialogLibraries()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181622398179079">lib_names = dlg_libs.getElementNames()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id461622398179232">bas.MsgBox("\n".join(lib_names))</paragraph> + </pycode> +</section> + +<section id="InputBox"> + <comment> InputBox ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id61618905164342"> + <bookmark_value>Basic service;InputBox</bookmark_value> + </bookmark> + <h2 id="hd_id311618905372258" localize="false">InputBox</h2> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id91619007097426" localize="false"><input>svc.InputBox(prompt: str, [title: str], [default: str], [xpostwips: int, ypostwips: int]): str</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <embed href="text/sbasic/shared/03010201.xhp#parameters"/> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" localize="false" id="par_id21619008398677">String</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <section id="ui"> + <pycode> + <paragraph role="pycode" id="pyc_id751619081201175" xml-lang="en-US">txt = s.InputBox('Please enter a phrase:', "Dear user")</paragraph> + <paragraph role="pycode" id="pyc_id261619081319555" xml-lang="en-US">s.MsgBox(txt, s.MB_ICONINFORMATION, "Confirmation of phrase")</paragraph> + </pycode> + <note id="par_id651618921455396">For in-depth information please refer to <link href="https://wiki.documentfoundation.org/Macros/General/IO_to_Screen" name="Input/Output to Screen with Python">Input/Output to Screen with Python</link> on the Wiki.</note> + </section> +</section> + +<section id="MsgBox"> + <comment> MsgBox -------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id681618905411293"> + <bookmark_value>Basic service;MsgBox</bookmark_value> + </bookmark> + <h2 id="hd_id181618br/905397758" localize="false">MsgBox</h2> + <paragraph role="paragraph" id="par_id231618922407948">Displays a dialog box containing a message and returns an optional value.<br/>MB_xx constants help specify the dialog type, the number and type of buttons to display, plus the icon type. By adding their respective values they form bit patterns, that define the <literal>MsgBox</literal> dialog appearance.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id71618922431508" localize="false"><input>bas.MsgBox(prompt: str, [buttons: int], [title: str])[: int]</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <embed href="text/sbasic/shared/03010101.xhp#parameters"/> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id711619082902143">An optional integer as detailed in above <literal>IDxx</literal> properties.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/03/sf_basic.xhp#ui"/> +</section> + +<section id="Now"> + <comment> Now ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id791618906935711"> + <bookmark_value>Basic service;Now</bookmark_value> + </bookmark> + <h2 id="hd_id231618906957248" localize="false">Now</h2> + <paragraph role="paragraph" id="par_id191619084216660">Returns the current system date and time as a <literal>datetime</literal>.<literal>datetime</literal> Python native object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id631619084685488" localize="false"><input>svc.Now(): datetime</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id411619084749448">bas.MsgBox(bas.Now(), bas.MB_OK, "Now")</paragraph> + </pycode> +</section> + +<section id="RGB"> + <comment> RGB ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id831618907521168"> + <bookmark_value>Basic service;RGB</bookmark_value> + </bookmark> + <h2 id="hd_id871618907784332" localize="false">RGB</h2> + <paragraph role="paragraph" id="par_id621619448293385">Returns an integer color value consisting of red, green, and blue components.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id201619096429785"><input>svc.RGB(red:int, green: int, blue: int): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <embed href="text/sbasic/shared/03010305.xhp#parameters"/> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" localize="false" id="par_id381619096830033">Integer</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321619096903721">YELLOW = bas.RGB(255,255,0)</paragraph> + </pycode> +</section> + +<section id="ThisComponent"> + <comment> ThisComponent -------------------------------------------------- </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id81618907850447"> + <bookmark_value>Basic service;ThisComponent</bookmark_value> + </bookmark> + <h2 id="hd_id211618907871087" localize="false">ThisComponent</h2> + <paragraph role="paragraph" id="par_id141622840830978">If the current component refers to a %PRODUCTNAME document, this method returns the UNO object representing the document.</paragraph> + <paragraph role="paragraph" id="par_id961622841287976">The method will return <literal>None</literal> when the current component does not correspond to a document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id671622840735153"> + <input>svc.ThisComponent(): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21622841338969">comp = bas.ThisComponent</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781622841643538">bas.MsgBox("\n".join(comp.getSupportedServiceNames()))</paragraph> + </pycode> +</section> + +<section id="ThisDatabaseDocument"> + <comment> ThisDatabaseDocument ------------------------------------------ </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id81618907858201"> + <bookmark_value>Basic service;ThisDatabaseDocument</bookmark_value> + </bookmark> + <h2 id="hd_id211618907879635" localize="false">ThisDatabaseDocument</h2> + <paragraph role="paragraph" id="par_id271622912644859">If the script is being executed from a Base document or any of its subcomponents this method returns the main component of the Base instance.</paragraph> + <paragraph role="paragraph" id="par_id811622912819443">This method returns <literal>None</literal> otherwise.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711622840776224"> + <input>svc.ThisDatabaseDocument(): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761622913418091">db_doc = bas.ThisDatabaseDocument</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201622913418646">table_names = db_doc.DataSource.getTables().getElementNames()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id711622913418917">bas.MsgBox("\n".join(table_names))</paragraph> + </pycode> + <tip id="par_id201623153844931">Visit the <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1sdb_1_1OfficeDatabaseDocument.html" name="OfficeDatabaseDocument">OfficeDatabaseDocument</link> API page to learn more about Base's main component structure.</tip> +</section> + +<section id="Xray"> + <comment> Xray ------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" branch="index" id="bm_id81618907851793"> + <bookmark_value>Basic service;Xray</bookmark_value> + </bookmark> + <h2 id="hd_id211618907871281" localize="false">Xray</h2> + <paragraph role="paragraph" id="par_id451619094057178">Inspect Uno objects or variables.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id301619094111856" localize="false"><input>svc.Xray(obj: any)</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id21619094660345"><emph>obj</emph>: A variable or UNO object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id751619095024401">bas.Xray(bas.StarDesktop)</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03131900.xhp#GlobalScope_h1"/> + <embed href="text/sbasic/python/python_programming.xhp#pythonprogrammingheading"/> + <paragraph role="paragraph" localize="false" id="par_id901618486941514"><link href="text/sbasic/python/python_programming.xhp" name="uno.fileUrlToSystemPath() method">uno.fileUrlToSystemPath()</link></paragraph> + <paragraph role="paragraph" localize="false" id="par_id901618496841514"><link href="text/sbasic/python/python_programming.xhp" name="uno.systemPathToFileUrl() method">uno.systemPathToFileUrl()</link></paragraph> + <paragraph role="paragraph" id="par_id951618554355538"><link href="https://wiki.documentfoundation.org/Macros/General/IO_to_Screen" name="Input/Output to Screen with Python">Input/Output to Screen with Python</link> on the wiki</paragraph> + <paragraph role="paragraph" localize="false" id="par_id610918486941514"><link href="text/sbasic/python/python_programming.xhp" name="XSCRIPTCONTEXT.getComponentContext() method">XSCRIPTCONTEXT.getComponentContext()</link></paragraph> + <paragraph role="paragraph" localize="false" id="par_id901618484961514"><link href="text/sbasic/python/python_programming.xhp" name="uno.getComponentContext() method">uno.getComponentContext()</link></paragraph> + <paragraph role="paragraph" localize="false" id="par_id901648186941514"><link href="text/sbasic/python/python_platform.xhp" name="platform.system() method">platform.system()</link></paragraph> + <paragraph role="paragraph" localize="false" id="par_id901816486941514"><link href="text/sbasic/python/python_platform.xhp" name="os.pathsep() method">os.pathsep()</link></paragraph> +</section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_calc.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_calc.xhp new file mode 100644 index 000000000..6b75f86dd --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_calc.xhp @@ -0,0 +1,2031 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="sf_calc" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Calc service</title> + <filename>/text/sbasic/shared/03/sf_calc.xhp</filename> + </topic> +</meta> + +<body> +<section id="SFDocuments-sf_calc"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Calc service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="CalcService"><link href="text/sbasic/shared/03/sf_calc.xhp" name="Calc service"><literal>SFDocuments</literal>.<literal>Calc</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id381589189355849" xml-lang="en-US">The <literal>SFDocuments</literal> shared library provides a number of methods and properties to facilitate the management and handling of %PRODUCTNAME documents.</paragraph> + <paragraph role="paragraph" id="par_id351591014177269" xml-lang="en-US">The <literal>SFDocuments.Calc</literal> service is a subclass of the <link href="text/sbasic/shared/03/sf_document.xhp" name="SF_Document_link"><literal>SFDocuments.Document</literal></link> service. All methods and properties defined for the <literal>Document</literal> service can also be accessed using a <literal>Calc</literal> service instance.</paragraph> + <paragraph role="paragraph" id="par_id591589189364267" xml-lang="en-US">The <literal>Calc</literal> service is focused on:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id891589189452545" role="listitem" xml-lang="en-US">Handling sheets within a Calc document (copy, insert, move, etc)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id811589189463041" role="listitem" xml-lang="en-US">Exchanging data between Basic data structures and Calc ranges</paragraph> + </listitem> + <listitem> + <paragraph id="par_id141599569935662" role="listitem" xml-lang="en-US">Copying and importing massive amounts of data</paragraph> + </listitem> + </list> +</section> + <note id="par_id851638217526844">This help page describes methods and properties that are applicable only to Calc documents.</note> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Calc</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id591589191059889" xml-lang="en-US">The <literal>Calc</literal> service is closely related to the <literal>UI</literal> service of the <literal>ScriptForge</literal> library. Below are a few examples of how the <literal>Calc</literal> service can be invoked.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id551621623999947">The code snippet below creates a <literal>Calc</literal> service instance that corresponds to the currently active Calc document.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id431621624078370">Set oDoc = CreateScriptService("Calc")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id341621467500466">Another way to create an instance of the <literal>Calc</literal> service is using the <literal>UI</literal> service. In the following example, a new Calc document is created and <literal>oDoc</literal> is a <literal>Calc</literal> service instance:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim ui As Object, oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201582885621287">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561589191748697">Set oDoc = ui.CreateDocument("Calc")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id921621467621019">Or using the <literal>OpenDocument</literal> method from the <literal>UI</literal> service:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671621467660766">Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id741621467697967">It is also possible to instantiate the <literal>Calc</literal> service using the <literal>CreateScriptService</literal> method:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371589191782045">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711589191788959">Set oDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id271621467810774">In the example above, "MyFile.ods" is the name of an open document window. If this argument is not provided, the active window is considered.</paragraph> + <paragraph role="paragraph" id="par_id71158288562139" xml-lang="en-US">It is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61582733781413">Set oDoc = oDoc.Dispose()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id231611610666018">However, if the document was closed using the <literal>CloseDocument</literal> method, it becomes unnecessary to free resources using the command described above.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id911621624242302">myDoc = CreateScriptService("Calc")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id201621531742824">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661621531772444">myDoc = ui.CreateDocument("Calc")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401621531828705">myDoc = ui.OpenDocument(r"C:\Documents\MyFile.ods")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id701621532481401">myDoc = CreateScriptService("SFDocuments.Calc", "MyFile.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951621532568918">myDoc.Dispose()</paragraph> + </pycode> + <tip id="par_id71611090922315">The use of the prefix "<literal>SFDocuments.</literal>" while calling the service is optional.</tip> + + <h2 id="hd_id991591016893982" xml-lang="en-US">Definitions</h2> + <paragraph role="paragraph" id="par_id511591016999246" xml-lang="en-US">Many methods require a "<emph>Sheet</emph>" or a "<emph>Range</emph>" as argument. Single cells are considered a special case of a <literal>Range</literal>.</paragraph> + <paragraph role="paragraph" id="par_id511591019278671" xml-lang="en-US">Both may be expressed either as a string or as a reference (= object) depending on the situation:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id571591019367284" role="listitem" xml-lang="en-US">Within a <emph>specific</emph> <literal>Calc</literal> <emph>instance</emph>, sheets and ranges are given as strings such as "Sheet1" and "D2:F6".</paragraph> + </listitem> + <listitem> + <paragraph id="par_id121591019432157" role="listitem" xml-lang="en-US">Additionally, the <literal>.Sheet</literal> and <literal>.Range</literal> properties return a reference that may be used as argument of a method called from <emph>another instance</emph> of the <literal>Calc</literal> service.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id421591017227464" xml-lang="en-US">The example below copies data from document A (opened as read-only and hidden) to document B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id581591017295549">Dim oDocA As Object, oDocB As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441611611293627">Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391591017309023">Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941591017325429">oDocB.CopyToRange(oDocA.Range("SheetX.D4:F8"), "D2:F6") 'CopyToRange(source, target)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id561621533543160">docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id61621533637980">docB = ui.OpenDocument(r"C:\Documents\FileB.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941621533638353">docB.CopyToRange(docA.Range("SheetX.D4:F8"), "D2:F6")</paragraph> + </pycode> + + <h3 id="hd_id941591020321580" localize="false" xml-lang="en-US">SheetName</h3> + <paragraph role="paragraph" id="par_id341591020333849" xml-lang="en-US">Either the sheet name as a <literal>string</literal> or an <literal>object</literal> produced by the <literal>.Sheet</literal> property.</paragraph> + <paragraph role="paragraph" id="par_id651591020343023" xml-lang="en-US">The shortcut "~" (tilde) represents the current sheet.</paragraph> + <h3 id="hd_id101591020737697" localize="false" xml-lang="en-US">RangeName</h3> + <paragraph role="paragraph" id="par_id291591020728110" xml-lang="en-US">Either a string designating a set of contiguous cells located in a sheet of the current instance or an <literal>object</literal> produced by the <literal>.Range</literal> property.</paragraph> + <paragraph role="paragraph" id="par_id691591020711395" xml-lang="en-US">The shortcut "~" (tilde) represents the current selection or the first selected range if multiple ranges are selected.</paragraph> + <paragraph role="paragraph" id="par_id701592230700986" xml-lang="en-US">The shortcut "*" represents all used cells.</paragraph> + <paragraph role="paragraph" id="par_id641591021597701" xml-lang="en-US">The sheet name is optional when defining a range. If no sheet name is provided, then the active sheet is used. Surrounding single quotes and $ signs are allowed but ignored.</paragraph> + <paragraph role="paragraph" id="par_id231655754032310">When specifying a <literal>SheetName</literal> as a string, the use of single quotes to enclose the sheet name are required if the name contains blank spaces " " or periods ".". </paragraph> + <paragraph role="paragraph" id="par_id931655906591984">The examples below illustrate in which cases the use of single quotes is mandatory:</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id971655754336388">' The use of single quotes is optional</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891655754336707">oDoc.clearAll("SheetA.A1:B10")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381655754337100">oDoc.clearAll("'SheetA'.A1:B10")</paragraph> + <paragraph role="bascode" id="bas_id711655754337420">' The use of single quotes is required</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311655754674294">oDoc.clearAll("'Sheet.A'.A1:B10")</paragraph> + </bascode> + <tip id="par_id371592406978640" xml-lang="en-US">Except for the <literal>CurrentSelection</literal> property, the <literal>Calc</literal> service considers only single ranges of cells.</tip> + <table id="tab_id101591024652566"> + <tablerow> + <tablecell colspan="2"> + <paragraph id="par_id91591025127496" role="tablehead" xml-lang="en-US">Examples of valid ranges</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id481591024294524" role="tablecontent" xml-lang="en-US">1) $'SheetX'.D2<br/>2) $D$2</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721591024294894" role="tablecontent" xml-lang="en-US">A single cell</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id21591024294492" role="tablecontent" xml-lang="en-US">1) $'SheetX'.D2:F6<br/>2) D2:D10</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id9159102429464" role="tablecontent" xml-lang="en-US">Single range with multiple cells</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161592230749179" role="tablecontent" xml-lang="en-US">$'SheetX'.*</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581592230749243" role="tablecontent" xml-lang="en-US">All used cells in the given sheet</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id641591024294318" role="tablecontent" xml-lang="en-US">1) $'SheetX'.A:A (column A)<br/>2) 3:5 (rows 3 to 5)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id431591024294723" role="tablecontent" xml-lang="en-US">All cells in contiguous columns or rows up to the last used cell</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id871591024294202" role="tablecontent" xml-lang="en-US">myRange</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721591024294721" role="tablecontent" xml-lang="en-US">A range named "myRange" at spreadsheet level</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181591024294534" role="tablecontent" xml-lang="en-US">1) ~.someRange<br/>2) SheetX.someRange</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911591024294816" role="tablecontent" xml-lang="en-US">A range name at sheet level</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id781591024294621" role="tablecontent" xml-lang="en-US">myDoc.Range("SheetX.D2:F6") </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id681591024294568" role="tablecontent" xml-lang="en-US">A range within the sheet SheetX in file associated with the myDoc Calc instance</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id101591024294151" role="tablecontent" xml-lang="en-US">~.~ or ~</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id22159102429479" role="tablecontent" xml-lang="en-US">The current selection in the active sheet</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2> + <paragraph role="paragraph" id="par_id151591018231905" xml-lang="en-US">All the properties generic to any document are implicitly applicable also to Calc documents. For more information, read the <link href="text/sbasic/shared/03/sf_document.xhp" name="Document service">Document service Help page</link>.</paragraph> + <paragraph role="paragraph" id="par_id911591018242565" xml-lang="en-US">The properties specifically available for Calc documents are:</paragraph> + <table id="tab_id971582885195582"> + <tablerow> + <tablecell> + <paragraph id="par_id41582885195836" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195372" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221591018408168" role="tablehead" xml-lang="en-US">Argument</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195238" role="tablehead" xml-lang="en-US">Return type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id931582885195131" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id681592407165508" role="tablecontent" xml-lang="en-US" localize="false">CurrentSelection</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301592407165942" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81592407165611" role="tablecontent" xml-lang="en-US">None</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id59159240716522" role="tablecontent" xml-lang="en-US">String or array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id85159240716560" role="tablecontent" xml-lang="en-US">The single selected range as a string or the list of selected ranges as an array.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id681592407165201" localize="false" role="tablecontent">FirstCell</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301592407165606" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81592407165545" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id59159240716378" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id85159240716828" role="tablecontent">Returns the first used cell in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id681592407166918" localize="false" role="tablecontent">FirstColumn</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301592407166642" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81592407165145" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id59159240716125" localize="false" role="tablecontent">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id85159240716225" role="tablecontent">Returns the leftmost column number in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id681592407169888" localize="false" role="tablecontent">FirstRow</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301592407167972" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81592407165695" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id59159240716663" localize="false" role="tablecontent">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id85159240716128" role="tablecontent">Returns the topmost row number in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id521593094953943" role="tablecontent" xml-lang="en-US" localize="false">Height</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id101593094953259" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741593094953790" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581593094953195" role="tablecontent" xml-lang="en-US" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311593094953330" role="tablecontent" xml-lang="en-US">The number of rows (>= 1) in the given range.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id97158288519551" localize="false" role="tablecontent">LastCell</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221582885195686" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501591018870619" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371582885195525" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881582885195976" role="tablecontent">Returns the last used cell in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id261592315106411" localize="false" role="tablecontent">LastColumn</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601592315106598" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831592315106202" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591592315106615" localize="false" role="tablecontent">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id791592315106790" role="tablecontent">The last used column in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801591025591570" localize="false" role="tablecontent">LastRow</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981591025591597" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81591025591696" role="tablecontent">SheetName or RangeName as String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id61591025591572" localize="false" role="tablecontent">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421591025591509" role="tablecontent">The last used row in a given range or sheet.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id52159102559144" role="tablecontent" xml-lang="en-US" localize="false">Range</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81591025591672" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561591025591239" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311591025591598" role="tablecontent" xml-lang="en-US" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571591025591367" role="tablecontent" xml-lang="en-US">A range reference that can be used as argument of methods like <literal>CopyToRange</literal>.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id52159102559323" role="tablecontent" xml-lang="en-US" localize="false">Region</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81591025591007" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561591025592149" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311591025591078" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571591025599937" role="tablecontent" xml-lang="en-US">Returns the address of the smallest area that contains the specified range so that the area is surrounded by empty cells or sheet edges. This is equivalent to applying the <switchinline select="sys"><caseinline select="MAC"><keycode>Command + *</keycode></caseinline><defaultinline><keycode>Ctrl + *</keycode></defaultinline></switchinline> shortcut to the given range.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id17159102559142" role="tablecontent" xml-lang="en-US" localize="false">Sheet</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541591025591511" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661591025591903" role="tablecontent" xml-lang="en-US">SheetName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id101591025591982" role="tablecontent" xml-lang="en-US" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731591025591753" role="tablecontent" xml-lang="en-US">A sheet reference that can be used as argument of methods like <literal>CopySheet</literal>.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id171591025595653" role="tablecontent" xml-lang="en-US" localize="false">SheetName</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541591025591322" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661591025591188" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id101591025591289" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731591025591006" role="tablecontent" xml-lang="en-US">Returns the sheet name of a given range address.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591591025591635" role="tablecontent" xml-lang="en-US" localize="false">Sheets</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581591025591579" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751591025591667" role="tablecontent" xml-lang="en-US">None</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861591025591250" role="tablecontent" xml-lang="en-US">Array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491591025591370" role="tablecontent" xml-lang="en-US">The list with the names of all existing sheets.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731593095062923" role="tablecontent" xml-lang="en-US" localize="false">Width</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711593095062771" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311593095062171" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761593095062827" role="tablecontent" xml-lang="en-US" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id681593095062358" role="tablecontent" xml-lang="en-US">The number of columns (>= 1) in the given range.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id691592315404547" role="tablecontent" xml-lang="en-US" localize="false">XCellRange</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391592315404944" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001592315404525" role="tablecontent" xml-lang="en-US">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id7715923154041" role="tablecontent" xml-lang="en-US" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321592315404430" role="tablecontent" xml-lang="en-US">A <literal>com.sun.star.Table.XCellRange</literal> UNO object.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961592315565332" role="tablecontent" localize="false">XSheetCellCursor</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501592315567199" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411592315560025" role="tablecontent">RangeName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521592315565365" role="tablecontent" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id41592315565185" role="tablecontent">A <literal>com.sun.star.sheet.XSheetCellCursor</literal> UNO object. After moving the cursor, the resulting range address can be accessed through the <literal>AbsoluteName</literal> UNO property of the cursor object, which returns a string value that can be used as argument for properties and methods of the Calc service.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961592315565156" role="tablecontent" xml-lang="en-US" localize="false">XSpreadsheet</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501592315565569" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411592315565235" role="tablecontent" xml-lang="en-US">SheetName As String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521592315565269" role="tablecontent" xml-lang="en-US" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id41592315560095" role="tablecontent" xml-lang="en-US">A <literal>com.sun.star.sheet.XSpreadsheet</literal> UNO object.</paragraph> + </tablecell> + </tablerow> +</table> + + <tip id="par_id321611613059105">Visit %PRODUCTNAME API Documentation's website to learn more about <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1table_1_1XCellRange.html" name="XCellRange API">XCellRange</link>, <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sheet_1_1XSheetCellCursor.html" name="XSheetCellCursor API">XSheetCellCursor</link> and <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sheet_1_1XSpreadsheet.html" name="XSpreadsheet API">XSpreadsheet</link> UNO objects.</tip> + + <h2 id="hd_id501582887473754" xml-lang="en-US">Methods</h2> + <table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Calc Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_calc.xhp#A1Style" name="A1Style method">A1Style</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#Activate" name="Activate method">Activate</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#Charts" name="Charts method">Charts</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ClearAll" name="ClearAll method">ClearAll</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ClearFormats" name="ClearFormats method">ClearFormats</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ClearValues" name="ClearValues method">ClearValues</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CompactLeft" name="CompactLeft method">CompactLeft</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CompactUp" name="CompactUp method">CompactUp</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CopySheet" name="CopySheet method">CopySheet</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CopySheetFromFile" name="CopySheetFromFile method">CopySheetFromFile</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CopyToCell" name="CopyToCell method">CopyToCell</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CopyToRange" name="CopyToRange method">CopyToRange</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CreateChart" name="CreateChart method">CreateChart</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#CreatePivotTable" name="CreatePivotTable method">CreatePivotTable</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DAvg method">DAvg</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DCount method">DCount</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DMax method">DMax</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DMin method">DMin</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DSum method">DSum</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ExportRangeToFile" name="ExportRangeToFile method">ExportRangeToFile</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#Forms" name="Forms method">Forms</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#GetColumnName" name="GetColumnName method">GetColumnName</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#GetFormula" name="GetFormula method">GetFormula</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#GetValue" name="GetValue method">GetValue</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ImportFromCSVFile" name="ImportFromCSVFile method">ImportFromCSVFile</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ImportFromDatabase" name="ImportFromDatabase method">ImportFromDatabase</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#InsertSheet" name="InsertSheet method">InsertSheet</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#MoveRange" name="MoveRange method">MoveRange</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#MoveSheet" name="MoveSheet method">MoveSheet</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#Offset" name="Offset method">Offset</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_calc.xhp#OpenRangeSelector" name="OpenRangeSelector method">OpenRangeSelector</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#PrintOut" name="PrintOut method">PrintOut</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#Printf" name="Printf method">Printf</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#RemoveSheet" name="RemoveSheet method">RemoveSheet</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#RenameSheet" name="RenameSheet method">RenameSheet</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#SetArray" name="SetArray method">SetArray</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#SetValue" name="SetValue method">SetValue</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#SetCellStyle" name="SetCellStyle method">SetCellStyle</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#SetFormula" name="SetFormula method">SetFormula</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ShiftDown" name="ShiftDown method">ShiftDown</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ShiftLeft" name="ShiftLeft method">ShiftLeft</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ShiftRight" name="ShiftRight method">ShiftRight</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#ShiftUp" name="ShiftUp method">ShiftUp</link><br/> + <link href="text/sbasic/shared/03/sf_calc.xhp#SortRange" name="SortRange method">SortRange</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + +<section id="A1Style"> + <comment> A1Style ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969104"> + <bookmark_value>Calc service;A1Style</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">A1Style</h2> + <paragraph role="paragraph" id="par_id93158919969228">Returns a range address as a string based on sheet coordinates, i.e. row and column numbers.</paragraph> + <paragraph role="paragraph" id="par_id21635434153216">If only a pair of coordinates is given, then an address to a single cell is returned. Additional arguments can specify the bottom-right cell of a rectangular range.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014334"> + <input>svc.A1Style(row1: int, column1: int, row2: int = 0; column2: int = 0; sheetname: str = "~"): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203080"><emph>row1, column1</emph>: Specify the row and column numbers of the top-left cell in the range to be considered. Row and column numbers start at 1.</paragraph> + <paragraph role="paragraph" id="par_id821591631203212"><emph>row2, column2</emph>: Specify the row and column numbers of the bottom-right cell in the range to be considered. If these arguments are not provided, or if values smaller than <literal>row1</literal> and <literal>column1</literal> are given, then the address of the single cell range represented by <literal>row1</literal> and <literal>column1</literal> is returned.</paragraph> + <paragraph role="paragraph" id="par_id821591631203336"><emph>sheetname</emph>: The name of the sheet to be appended to the returned range address. The sheet must exist. The default value is "~" corresponding to the currently active sheet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id131611616623705">The examples below in Basic and Python consider that "Sheet1" is the currently active sheet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id411589199698360">Set oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651611616531723">addr1 = oDoc.A1Style(1, 1) ' '$Sheet1'.$A$1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711611616532319">addr2 = oDoc.A1Style(2, 2, 3, 6) ' '$Sheet1'.$B$2:$F$3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181611616544988">addr3 = oDoc.A1Style(2, 2, 0, 6) ' '$Sheet1'.$B$2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181611616544911">addr4 = oDoc.A1Style(3, 4, 3, 8, "Sheet2") ' '$Sheet2'.$D$3:$H$3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181611616544104">addr5 = oDoc.A1Style(5, 1, SheetName := "Sheet3") ' '$Sheet3'.$A$5</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175228">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id971621534192369">addr1 = doc.A1Style(1, 1) # '$Sheet1'.$A$1</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id216215342375255">addr2 = doc.A1Style(2, 2, 3, 6) # '$Sheet1'.$B$2:$F$3</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281635437557107">addr3 = doc.A1Style(2, 2, 0, 6) # '$Sheet1'.$B$2</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801635437557005">addr4 = doc.A1Style(3, 4, 3, 8, "Sheet2") # '$Sheet2'.$D$3:$H$3</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501635437602129">addr5 = doc.A1Style(5, 1, sheetname="Sheet3") # '$Sheet3'.$A$5</paragraph> + </pycode> + <tip id="par_id501611617808112">The method <literal>A1Style</literal> can be combined with any of the many properties and methods of the Calc service that require a range as argument, such as <literal>GetValue</literal>, <literal>GetFormula</literal>, <literal>ClearAll</literal>, etc.</tip> +</section> + +<section id="Activate"> + <comment> Activate -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Calc service;Activate</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698099" localize="false">Activate</h2> + <paragraph role="paragraph" id="par_id93158919969864">If the argument <literal>sheetname</literal> is provided, the given sheet is activated and it becomes the currently selected sheet. If the argument is absent, then the document window is activated.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014732"> + <input>svc.Activate(sheetname: str = ""): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203996"><emph>sheetname</emph>: The name of the sheet to be activated in the document. The default value is an empty string, meaning that the document window will be activated without changing the active sheet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id131611616623714">The example below activates the sheet named "Sheet4" in the currently active document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969836">Dim ui as Variant, oDoc as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651611616531736">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711611616532302">Set oDoc = ui.GetDocument(ui.ActiveWindow)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181611616544947">oDoc.Activate("Sheet4")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175071">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id971621534192346">myDoc = ui.GetDocument(ui.ActiveWindow)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id21621534237588">myDoc.Activate("Sheet4")</paragraph> + </pycode> + <tip id="par_id501611617808220">Activating a sheet makes sense only if it is performed on a Calc document. To make sure you have a Calc document at hand you can use the <literal>isCalc</literal> property of the document object, which returns <literal>True</literal> if it is a Calc document and <literal>False</literal> otherwise.</tip> +</section> + +<section id="Charts"> + <comment> Charts ------------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158915960183"> + <bookmark_value>Calc service;Charts</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698104" localize="false">Charts</h2> + <paragraph role="paragraph" id="par_id93158919969856">Returns either the list with the names of all chart objects in a given sheet or a single <literal>Chart</literal> service instance.</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id371635438503202" role="listitem">If only <literal>sheetname</literal> is specified, a zero-based array of strings containing the names of all charts is returned.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id371635438509045" role="listitem">If a <literal>chartname</literal> is provided, then a single object corresponding to the desired chart is returned. The specified chart must exist.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534028832"> + <input>svc.Charts(sheetname: str, chartname: str = ""): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631205026"><emph>sheetname</emph>: The name of the sheet from which the list of charts is to be retrieved or where the specified chart is located.</paragraph> + <paragraph role="paragraph" id="par_id821591631203566"><emph>chartname</emph>: The user-defined name of the chart object to be returned. If the chart does not have a user-defined name, then the internal object name can be used. If this argument is absent, then the list of chart names in the specified sheet is returned.</paragraph> + <tip id="par_id431635438771588">Use the <menuitem>Navigator</menuitem> sidebar to check the names assigned to charts under the <menuitem>OLE objects</menuitem> category.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id41635439328174">The example below shows the number of chart objects in "Sheet1".</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id411589199698246">Dim arrNames as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651611616531639">arrNames = oDoc.Charts("Sheet1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711611616532310">MsgBox "There are " & UBound(arrNames) + 1 & " charts in Sheet1"</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id571635439417400">The following example accesses the chart named "MyChart" in "Sheet1" and prints its type.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461635439551325">Dim oChart as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id716354395513277">oChart = oDoc.Charts("Sheet1", "MyChart")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661635439551933">MsgBox oChart.ChartType</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id971621534192214">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321621534175387">chart_names = doc.Charts("Sheet1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id216215342375296">bas.MsgBox(f"There are {len(chart_names)} charts in Sheet1")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id421635439765634">chart = doc.Charts("Sheet1", "MyChart")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id161635439765873">bas.MsgBox(chart.ChartType)</paragraph> + </pycode> +</section> + +<section id="ClearAll"> + <comment> ClearAll -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231592919577434"> + <bookmark_value>Calc service;ClearAll</bookmark_value> + </bookmark> + <h2 id="hd_id921592919577158" localize="false">ClearAll</h2> + <paragraph role="paragraph" id="par_id31592919577984">Clears all the contents and formats of the given range.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id441621534763020"> + <input>svc.ClearAll(range: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441592919577809"><emph>range</emph>: The range to be cleared, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id521592919577626">oDoc.ClearAll("SheetX.A1:F10")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id211621536212144">myDoc.ClearAll("SheetX.A1:F10")</paragraph> + </pycode> +</section> + +<section id="ClearFormats"> + <comment> ClearFormats -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id591592919864362"> + <bookmark_value>Calc service;ClearFormats</bookmark_value> + </bookmark> + <h2 id="hd_id871592919864356" localize="false">ClearFormats</h2> + <paragraph role="paragraph" id="par_id211592919864118">Clears the formats and styles in the given range.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id381621536397094"> + <input>svc.ClearFormats(range: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id611592919864268"><emph>range</emph>: The range whose formats and styles are to be cleared, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id541592919864670">oDoc.ClearFormats("SheetX.*")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id501621536545590">myDoc.ClearFormats("SheetX.*")</paragraph> + </pycode> +</section> + +<section id="ClearValues"> + <comment> ClearValues -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781592919928644"> + <bookmark_value>Calc service;ClearValues</bookmark_value> + </bookmark> + <h2 id="hd_id111592919928265" localize="false">ClearValues</h2> + <paragraph role="paragraph" id="par_id841592919928169">Clears the values and formulas in the given range.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id951621536609302"> + <input>svc.ClearValues(range: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771592919928320"><emph>range</emph>: The range whose values and formulas are to be cleared, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371592919928100">oDoc.ClearValues("SheetX.A1:F10")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id451621536678434">myDoc.ClearValues("SheetX.A1:F10")</paragraph> + </pycode> +</section> + +<section id="CompactLeft"> + <comment> CompactLeft ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781592919922589"> + <bookmark_value>Calc service;CompactLeft</bookmark_value> + </bookmark> + <h2 id="hd_id111592919923294" localize="false">CompactLeft</h2> + <paragraph role="paragraph" id="par_id841592919903025">Deletes the columns of a specified range that match a filter expressed as a Calc formula. The filter is applied to each column to decide whether it will be deleted or not.</paragraph> + <paragraph role="paragraph" id="par_id601652269911029">The deleted column can be limited to the height of the specified range or span to the height of the entire sheet, thus deleting whole columns.</paragraph> + <paragraph role="paragraph" id="par_id701652271281106">This method returns a string with the range address of the compacted range. If all columns are deleted, then an empty string is returned.</paragraph> + <note id="par_id191652271892064">If a range of cells is selected, calling this method will not impact the selection.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id951621536600632"> + <input>svc.CompactLeft(range: str, wholecolumn: bool = False, opt filterformula: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771592919922181"><emph>range</emph>: The range from which columns will be deleted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id771592919932260"><emph>wholecolumn</emph>: If this option is set to <literal>True</literal> the entire column will be deleted from the sheet. The default value is <literal>False</literal>, which means that the deleted column will be limited to the height of the specified <literal>range</literal>.</paragraph> + <paragraph role="paragraph" id="par_id771592919915974"><emph>filterformula</emph>: The filter to be applied to each column to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first column. When the formula returns <emph>True</emph> for a column, that column will be deleted. The default filter deletes all empty columns.</paragraph> + <paragraph role="paragraph" id="par_id361652271022647">For example, suppose range <emph>A1:J200</emph> is selected (height = 200), so the default formula is <emph>=(COUNTBLANK(A1:A200)=200)</emph>. This means that if all 200 cells are empty in the first column (Column A), then the column is deleted. Note that the formula is expressed with respect to the first column only. Internally the <literal>CompactLeft</literal> method will generalize this formula for all the remaining columns.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id941652271391005">' Delete all empty columns in the range G1:L10 from Sheet1</paragraph> + <paragraph role="bascode" id="bas_id691652271390762">newrange = oDoc.CompactLeft("Sheet1.G1:L10")</paragraph> + <paragraph role="bascode" id="bas_id921652271392627">' The example below is similar, but the entire column is deleted from the sheet</paragraph> + <paragraph role="bascode" id="bas_id941652271392873">newrange = oDoc.CompactLeft("Sheet1.G1:L10", WholeColumn := True)</paragraph> + <paragraph role="bascode" id="bas_id751652271393226">' Deletes all columns where the first row is marked with an "X"</paragraph> + <paragraph role="bascode" id="bas_id761652271393514">newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")</paragraph> + <paragraph role="bascode" id="bas_id241652271725676">' Deletes all columns where the sum of values in the column is odd</paragraph> + <paragraph role="bascode" id="bas_id531652271726131">newrange = oDoc.CompactLeft("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:G10);2)=1)")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id451621536612334">newrange = myDoc.CompactLeft("Sheet1.G1:L10")</paragraph> + <paragraph role="pycode" id="pyc_id201652272121176">newrange = myDoc.CompactLeft("Sheet1.G1:L10", wholecolumn = True)</paragraph> + <paragraph role="pycode" id="pyc_id781652272122794">newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(G1="X")')</paragraph> + <paragraph role="pycode" id="pyc_id731652272123209">newrange = myDoc.CompactLeft("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:G10);2)=1)')</paragraph> + </pycode> +</section> + +<section id="CompactUp"> + <comment> CompactUp --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781592919928589"> + <bookmark_value>Calc service;CompactUp</bookmark_value> + </bookmark> + <h2 id="hd_id111592919923065" localize="false">CompactUp</h2> + <paragraph role="paragraph" id="par_id841592919903699">Deletes the rows of a specified range that match a filter expressed as a Calc formula. The filter is applied to each row to decide whether it will be deleted or not.</paragraph> + <paragraph role="paragraph" id="par_id601652269910091">The deleted rows can be limited to the width of the specified range or span to the width of the entire sheet, thus deleting whole rows.</paragraph> + <paragraph role="paragraph" id="par_id701652271283456">This method returns a string with the range address of the compacted range. If all rows are deleted, then an empty string is returned.</paragraph> + <note id="par_id191652271893913">If a range of cells is selected, calling this method will not impact the selection.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id951621536605642"> + <input>svc.CompactUp(range: str, wholerow: bool = False, opt filterformula: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771592919922080"><emph>range</emph>: The range from which rows will be deleted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id771592919921160"><emph>wholerow</emph>: If this option is set to <literal>True</literal> the entire row will be deleted from the sheet. The default value is <literal>False</literal>, which means that the deleted row will be limited to the width of the specified <literal>range</literal>.</paragraph> + <paragraph role="paragraph" id="par_id771592919926374"><emph>filterformula</emph>: The filter to be applied to each row to determine whether or not it will be deleted. The filter is expressed as a Calc formula that should be applied to the first row. When the formula returns <emph>True</emph> for a row, that row will be deleted. The default filter deletes all empty rows.</paragraph> + <paragraph role="paragraph" id="par_id361652271022681">For example, suppose range <emph>A1:J200</emph> is selected (width = 10), so the default formula is <emph>=(COUNTBLANK(A1:J1)=10)</emph>. This means that if all 10 cells are empty in the first row (Row 1), then the row is deleted. Note that the formula is expressed with respect to the first row only. Internally the <literal>CompactUp</literal> method will generalize this formula for all the remaining rows.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id941652271391554">' Delete all empty rows in the range G1:L10 from Sheet1</paragraph> + <paragraph role="bascode" id="bas_id691652271390789">newrange = oDoc.CompactUp("Sheet1.G1:L10")</paragraph> + <paragraph role="bascode" id="bas_id921652271392567">' The example below is similar, but the entire row is deleted from the sheet</paragraph> + <paragraph role="bascode" id="bas_id941652271392553">newrange = oDoc.CompactUp("Sheet1.G1:L10", WholeRow := True)</paragraph> + <paragraph role="bascode" id="bas_id751652271393117">' Deletes all rows where the first column is marked with an "X"</paragraph> + <paragraph role="bascode" id="bas_id761652271393034">newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(G1=""X"")")</paragraph> + <paragraph role="bascode" id="bas_id241652271725065">' Deletes all rows where the sum of values in the row is odd</paragraph> + <paragraph role="bascode" id="bas_id531652271726010">newrange = oDoc.CompactUp("Sheet1.G1:L10", FilterFormula := "=(MOD(SUM(G1:L1);2)=1)")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id451621536612227">newrange = myDoc.CompactUp("Sheet1.G1:L10")</paragraph> + <paragraph role="pycode" id="pyc_id201652272121288">newrange = myDoc.CompactUp("Sheet1.G1:L10", wholerow = True)</paragraph> + <paragraph role="pycode" id="pyc_id781652272122931">newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(G1="X")')</paragraph> + <paragraph role="pycode" id="pyc_id731652272123109">newrange = myDoc.CompactUp("Sheet1.G1:L10", filterformula = '=(MOD(SUM(G1:L1);2)=1)')</paragraph> + </pycode> +</section> + +<section id="CopySheet"> + <comment> CopySheet -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id901591631693213"> + <bookmark_value>Calc service;CopySheet</bookmark_value> + </bookmark> + <h2 id="hd_id51591631693461" localize="false">CopySheet</h2> + <paragraph role="paragraph" id="par_id591591631693816">Copies a specified sheet before an existing sheet or at the end of the list of sheets. The sheet to be copied may be contained inside any <emph>open</emph> Calc document. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id411621536777187"> + <input>svc.CopySheet(sheetname: any, newname: str, [beforesheet: any]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id871591631693741"><emph>sheetname</emph>: The name of the sheet to be copied as a string or its reference as an object.</paragraph> + <paragraph role="paragraph" id="par_id351591632126180" xml-lang="en-US"><emph>newname</emph>: The name of the sheet to insert. The name must not be in use in the document.</paragraph> + <paragraph role="paragraph" id="par_id211591632192379" xml-lang="en-US"><emph>beforesheet</emph>: The name (string) or index (numeric, starting from 1) of the sheet before which to insert the copied sheet. This argument is optional and the default behavior is to add the copied sheet at the last position.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id961591632309410" xml-lang="en-US">The following example makes a copy of the sheet "SheetX" and places it as the last sheet in the current document. The name of the copied sheet is "SheetY".</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id731591631693493">Dim oDoc as Object</paragraph> + <paragraph role="bascode" id="bas_id231611706034607">'Gets the Document object of the active window</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981611706030262">Set oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281611706033725">oDoc.CopySheet("SheetX", "SheetY")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id461591632297415" xml-lang="en-US">The example below copies "SheetX" from "FileA.ods" and pastes it at the last position of "FileB.ods" with the name "SheetY":</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id631591632407615">Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731591632415653">Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651591632422603">oDocB.CopySheet(oDocA.Sheet("SheetX"), "SheetY")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id741621537296168">myDoc.CopySheet("SheetX", "SheetY")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621537335378">docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801621537405452">docB = ui.OpenDocument(r"C:\Documents\FileB.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361621537425882">docB.CopySheet(docA.Sheet("SheetX"), "SheetY")</paragraph> + </pycode> + <tip id="par_id801595695285478" xml-lang="en-US">To copy sheets between <emph>open</emph> documents, use <literal>CopySheet</literal>. To copy sheets from documents that are <emph>closed</emph>, use <literal>CopySheetFromFile</literal>.</tip> +</section> + +<section id="CopySheetFromFile"> + <comment> CopySheetFromFile -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id101591714614827"> + <bookmark_value>Calc service;CopySheetFromFile</bookmark_value> + </bookmark> + <h2 id="hd_id301591714614286" localize="false">CopySheetFromFile</h2> + <paragraph role="paragraph" id="par_id931591714614755">Copies a specified sheet from a <emph>closed</emph> Calc document and pastes it before an existing sheet or at the end of the list of sheets of the file referred to by a <literal>Document</literal> object.</paragraph> + <paragraph role="paragraph" id="par_id271611706609445">If the file does not exist, an error is raised. If the file is not a valid Calc file, a blank sheet is inserted. If the source sheet does not exist in the input file, an error message is inserted at the top of the newly pasted sheet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id721621537513995"> + <input>svc.CopySheetFromFile(filename: str, sheetname: str, newname: str, [beforesheet: any]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id471591714947181" xml-lang="en-US"><emph>filename</emph>: Identifies the file to open. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation. The file must not be protected with a password.</paragraph> + <paragraph role="paragraph" id="par_id9915917146142"><emph>sheetname</emph>: The name of the sheet to be copied as a string.</paragraph> + <paragraph role="paragraph" id="par_id71591714614904" xml-lang="en-US"><emph>newname</emph>: The name of the copied sheet to be inserted in the document. The name must not be in use in the document.</paragraph> + <paragraph role="paragraph" id="par_id601591714614407" xml-lang="en-US"><emph>beforesheet</emph>: The name (string) or index (numeric, starting from 1) of the sheet before which to insert the copied sheet. This argument is optional and the default behavior is to add the copied sheet at the last position.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id981611707192039">The following example copies "SheetX" from "myFile.ods" and pastes it into the document referred to by "oDoc" as "SheetY" at the first position.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id561591714614817">oDoc.CopySheetFromFile("C:\Documents\myFile.ods", "SheetX", "SheetY", 1)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id171621537641434">myDoc.CopySheetFromFile(r"C:\Documents\myFile.ods", "SheetX", "SheetY", 1)</paragraph> + </pycode> +</section> + +<section id="CopyToCell"> + <comment> CopyToCell -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id481592558768560"> + <bookmark_value>Calc service;CopyToCell</bookmark_value> + </bookmark> + <h2 id="hd_id261592558768660" localize="false">CopyToCell</h2> + <paragraph role="paragraph" id="par_id91592558768804">Copies a specified source range (values, formulas and formats) to a destination range or cell. The method reproduces the behaviour of a Copy/Paste operation from a range to a single cell.</paragraph> + <paragraph role="paragraph" id="par_id831611707431984">It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.</paragraph> + <paragraph role="paragraph" id="par_id681592558768463" xml-lang="en-US">The source range may belong to another <emph>open</emph> document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id431621537972303"> + <input>svc.CopyToCell(sourcerange: any, destinationcell: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id761592558768578"><emph>sourcerange</emph>: The source range as a string when it belongs to the same document or as a reference when it belongs to another open Calc document.</paragraph> + <paragraph role="paragraph" id="par_id711592558768466" xml-lang="en-US"><emph>destinationcell</emph>: The destination cell where the copied range of cells will be pasted, as a string. If a range is given, only its top-left cell is considered.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id431592904964362" xml-lang="en-US">Next is an example where the source and destination are in the same file:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531592559464178">oDoc.CopyToCell("SheetX.A1:F10", "SheetY.C5")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id751592905035452" xml-lang="en-US">The example below illustrates how to copy a range from another open Calc document:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id971592558768687">Dim ui as Variant : ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401592558768991">Dim oDocSource As Object, oDocDestination As Object</paragraph> + <paragraph role="bascode" id="bas_id351592558768880">'Open the source document in the background (hidden)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751611708500322">Set oDocSource = ui.OpenDocument("C:\SourceFile.ods", Hidden := True, ReadOnly := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211611708507503">Set oDocDestination = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661611708507984">oDocDestination.CopyToCell(oDocSource.Range("Sheet1.C2:C4"), "SheetT.A5")</paragraph> + <paragraph role="bascode" id="bas_id1001611708508251">'Do not forget to close the source document because it was opened as hidden</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21611708536742">oDocSource.CloseDocument()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id531621538188012">docSource = ui.OpenDocument(r"C:\Documents\SourceFile.ods", hidden = True, readonly = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741621538288187">docDestination = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id691621538280854">docDestination.CopyToCell(docSource.Range("Sheet1.C2:C4"), "SheetT.A5")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361621538357798">docSource.CloseDocument()</paragraph> + </pycode> + <tip id="par_id61592905442071" xml-lang="en-US">To simulate a Copy/Paste from a range to a single cell, use <literal>CopyToCell</literal>. To simulate a Copy/Paste from a range to a larger range (with the same cells being replicated several times), use <literal>CopyToRange</literal>.</tip> +</section> + +<section id="CopyToRange"> + <comment> CopyToRange -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171592903121677"> + <bookmark_value>Calc service;CopyToRange</bookmark_value> + </bookmark> + <h2 id="hd_id67159290312183" localize="false">CopyToRange</h2> + <paragraph role="paragraph" id="par_id1615929031212">Copies downwards and/or rightwards a specified source range (values, formulas and formats) to a destination range. The method imitates the behaviour of a Copy/Paste operation from a source range to a larger destination range.</paragraph> + <list type="unordered"> + <listitem> + <paragraph role="paragraph" id="par_id271592904084534" xml-lang="en-US">If the height (or width) of the destination area is > 1 row (or column) then the height (or width) of the source must be <= the height (or width) of the destination. Otherwise nothing happens.</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id131592904286834" xml-lang="en-US">If the height (or width) of the destination is = 1 then the destination is expanded downwards (or rightwards) up to the height (or width) of the source range.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id661592904348877" xml-lang="en-US">The method returns a string representing the modified range of cells.</paragraph> + <paragraph role="paragraph" id="par_id41592903121807" xml-lang="en-US">The source range may belong to another <emph>open</emph> document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id981621538491567"> + <input>svc.CopyToRange(sourcerange: any, destinationrange: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id841592903121145"><emph>sourcerange</emph>: The source range as a string when it belongs to the same document or as a reference when it belongs to another open Calc document.</paragraph> + <paragraph role="paragraph" id="par_id5515929031211000" xml-lang="en-US"><emph>destinationrange</emph>: The destination of the copied range of cells, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id461592905128991" xml-lang="en-US">Copy within the same document:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81592903121951">oDoc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")</paragraph> + <paragraph role="bascode" id="bas_id601592904507182">' Returns a range string: "$SheetY.$C$5:$J$14"</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id1001592905195364" xml-lang="en-US">Copy from one file to another:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id121592903121767">Dim oDocA As Object : Set oDocA = ui.OpenDocument("C:\Documents\FileA.ods", Hidden := True, ReadOnly := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311592903121390">Dim oDocB As Object : Set oDocB = ui.OpenDocument("C:\Documents\FileB.ods")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id14159290312172">oDocB.CopyToRange(oDocA.Range("SheetX.A1:F10"), "SheetY.C5:J5")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621538667290">doc.CopyToRange("SheetX.A1:F10", "SheetY.C5:J5")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id531621538188957">docA = ui.OpenDocument(r"C:\Documents\FileA.ods", hidden = True, readonly = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741621538288785">docB = ui.OpenDocument(r"C:\Documents\FileB.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id691621538288954">docB.CopyToRange(docA.Range("SheetX.A1:F10"), "SheetY.C5:J5")</paragraph> + </pycode> +</section> + +<section id="CreateChart"> + <comment> CreateChart ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171592903123257"> + <bookmark_value>Calc service;CreateChart</bookmark_value> + </bookmark> + <h2 id="hd_id67159290312287" localize="false">CreateChart</h2> + <paragraph role="paragraph" id="par_id1615929033642">Creates a new chart object showing the data in the specified range. The returned chart object can be further manipulated using the <literal>Chart</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id981621538499667"> + <input>svc.CreateChart(chartname: str, sheetname: str, range: str, columnheader: bool = False, rowheader: bool = False): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id841592903121025"><emph>chartname:</emph> The user-defined name of the chart to be created. The name must be unique in the same sheet.</paragraph> + <paragraph role="paragraph" id="par_id5515929031213680"><emph>sheetname:</emph> The name of the sheet where the chart will be placed.</paragraph> + <paragraph role="paragraph" id="par_id5515929031211522"><emph>range:</emph> The range to be used as the data source for the chart. The range may refer to any sheet of the Calc document.</paragraph> + <paragraph role="paragraph" id="par_id5515929031216390"><emph>columnheader:</emph> When <literal>True</literal>, the topmost row of the range is used as labels for the category axis or the legend (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id5515929031211633"><emph>rowheader:</emph> When <literal>True</literal>, the leftmost column of the range is used as labels for the category axis or the legend. (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id61635441176547">The examples below in Basic and Python create a chart using the data contained in the range "A1:B5" of "Sheet1" and place the chart in "Sheet2".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81592903121217">Set oChart = oDoc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", RowHeader := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81592903121158">oChart.ChartType = "Donut"</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621538667188">chart = doc.CreateChart("MyChart", "Sheet2", "Sheet1.A1:B5", rowheader=True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id761621538664592">chart.ChartType = "Donut"</paragraph> + </pycode> + <tip id="par_id231635441342180">Refer to the help page about ScriptForge's <link href="text/sbasic/shared/03/sf_chart.xhp" name="Chart service">Chart service</link> to learn more how to further manipulate chart objects. It is possible to change properties as the chart type, chart and axes titles and chart position.</tip> +</section> + +<section id="CreatePivotTable"> + <comment> CreatePivotTable ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171592903120147"> + <bookmark_value>Calc service;CreatePivotTable</bookmark_value> + </bookmark> + <h2 id="hd_id67159290319647" localize="false">CreatePivotTable</h2> + <paragraph role="paragraph" id="par_id1615929033065">Creates a new pivot table with the properties defined by the arguments passed to the method.</paragraph> + <paragraph role="paragraph" id="par_id1001652794922144">A name must be provided for the pivot table. If a pivot table with the same name already exists in the targeted sheet, it will be replaced without warning.</paragraph> + <paragraph role="paragraph" id="par_id751652795324382">This method returns a string containing the range where the new pivot table was placed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id981621538467457"> + <input>svc.CreatePivotTable(pivottablename: str, sourcerange: str, targetcell: str, datafields: str[0..*], rowfields: str[0..*], columnfields: str[0..*], filterbutton: bool = true, rowtotals: bool = true, columntotals: bool = true): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id841592903128525"><emph>pivottablename:</emph> The user-defined name of the new pivot table.</paragraph> + <paragraph role="paragraph" id="par_id5515929031203640"><emph>sourcerange:</emph> The range containing the raw data, as a string. It is assumed that the first row contains the field names that are used by the pivot table.</paragraph> + <paragraph role="paragraph" id="par_id5515929031210400"><emph>targetcell:</emph> The top-left cell where the new pivot table will be placed. If a range is specified, only its top-left cell is considered.</paragraph> + <paragraph role="paragraph" id="par_id5515929031951290"><emph>datafields:</emph> It can be either a single string or an array containing strings that define field names and functions to be applied. When an array is specified, it must follow the syntax <input>Array("FieldName[;Function]", ...)</input>.</paragraph> + <paragraph role="paragraph" id="par_id361652795942348">The allowed functions are: <literal>Sum</literal>, <literal>Count</literal>, <literal>Average</literal>, <literal>Max</literal>, <literal>Min</literal>, <literal>Product</literal>, <literal>CountNums</literal>, <literal>StDev</literal>, <literal>StDevP</literal>, <literal>Var</literal>, <literal>VarP</literal> and <literal>Median</literal>. Function names must be provided in English. When all values are numerical, <literal>Sum</literal> is the default function, otherwise the default function is <literal>Count</literal>.</paragraph> + <paragraph role="paragraph" id="par_id5515929031211003"><emph>rowfields:</emph> A single string or an array with the field names that will be used as the pivot table rows.</paragraph> + <paragraph role="paragraph" id="par_id5515929031211114"><emph>columnfields:</emph> A single string or an array with the field names that will be used as the pivot table columns.</paragraph> + <paragraph role="paragraph" id="par_id361652796141240"><emph>filterbutton:</emph> Determines whether a filter button will be displayed above the pivot table (Default = <literal>True</literal>).</paragraph> + <paragraph role="paragraph" id="par_id661652796200051"><emph>rowtotals:</emph> Specifies if a separate column for row totals will be added to the pivot table (Default = <literal>True</literal>).</paragraph> + <paragraph role="paragraph" id="par_id671652796274304"><emph>columntotals</emph> Specifies if a separate row for column totals will be added to the pivot table (Default = <literal>True</literal>)</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211652797038002">Dim vData As Variant, oDoc As Object, ui As Object, sTable As String, sPivot As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401652797037306">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781652797037626">Set oDoc = ui.CreateDocument("Calc")</paragraph> + <paragraph role="bascode" id="bas_id201652797038370">vData = Array(Array("Item", "State", "Team", "2002", "2003", "2004"), _</paragraph> + <paragraph role="bascode" id="bas_id171652797038762"> Array("Books", "Michigan", "Jean", 14788, 30222, 23490), _</paragraph> + <paragraph role="bascode" id="bas_id331652797039146"> Array("Candy", "Michigan", "Jean", 26388, 15641, 32849), _</paragraph> + <paragraph role="bascode" id="bas_id911652797039570"> Array("Pens", "Michigan", "Jean", 16569, 32675, 25396), _</paragraph> + <paragraph role="bascode" id="bas_id471652797039963"> Array("Books", "Michigan", "Volker", 21961, 21242, 29009), _</paragraph> + <paragraph role="bascode" id="bas_id681652797040338"> Array("Candy", "Michigan", "Volker", 26142, 22407, 32841))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581652797040723">sTable = oDoc.SetArray("A1", vData)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321652797041090">sPivot = oDoc.CreatePivotTable("PT1", sTable, "H1", _</paragraph> + <paragraph role="bascode" id="bas_id851652797041450"> Array("2002", "2003;count", "2004;average"), _ ' Three data fields</paragraph> + <paragraph role="bascode" id="bas_id791652797306993"> "Item", _ ' A single row field</paragraph> + <paragraph role="bascode" id="bas_id731652797041866"> Array("State", "Team"), False) ' Two column fields</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761652797473541">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id716527974738130">doc = ui.CreateDocument("Calc")</paragraph> + <paragraph role="pycode" id="pyc_id971652797474132">vData = [["Item", "State", "Team", "2002", "2003", "2004"],</paragraph> + <paragraph role="pycode" id="pyc_id921652797555153"> ["Books", "Michigan", "Jean", 14788, 30222, 23490],</paragraph> + <paragraph role="pycode" id="pyc_id891652797555537"> ["Candy", "Michigan", "Jean", 26388, 15641, 32849],</paragraph> + <paragraph role="pycode" id="pyc_id321652797555864"> ["Pens", "Michigan", "Jean", 16569, 32675, 25396)],</paragraph> + <paragraph role="pycode" id="pyc_id121652797556264"> ["Books", "Michigan", "Volker", 21961, 21242, 29009],</paragraph> + <paragraph role="pycode" id="pyc_id881652797556680"> ["Candy", "Michigan", "Volker", 26142, 22407, 32841]]</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441652797991546">sTable = doc.SetArray("A1", vData)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id791652797991834">sPivot = doc.CreatePivotTable("PT1", sTable, "H1",</paragraph> + <paragraph role="pycode" id="pyc_id941652797992017"> ["2002", "2003;count", "2004;average"],</paragraph> + <paragraph role="pycode" id="pyc_id471652797992561"> "Item",</paragraph> + <paragraph role="pycode" id="pyc_id561652797992185"> ["State", "Team"], False)</paragraph> + </pycode> + <tip id="par_id231635441342284">To learn more about Pivot Tables in %PRODUCTNAME Calc, read the <link href="text/scalc/guide/datapilot.xhp" name="Pivot table">Pivot Table</link> help page.</tip> +</section> + + +<section id="DAvg"> + <comment> DAvg, DCount, DMax, DMin, DSum -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id791595777001863"> + <bookmark_value>Calc service;DAvg</bookmark_value> + <bookmark_value>Calc service;DCount</bookmark_value> + <bookmark_value>Calc service;DMax</bookmark_value> + <bookmark_value>Calc service;DMin</bookmark_value> + <bookmark_value>Calc service;DSum</bookmark_value> + </bookmark> + <h2 id="hd_id471595777001777" localize="false">DAvg, DCount, DMax, DMin and DSum</h2> + <paragraph role="paragraph" id="par_id601595777001498">Apply the functions Average, Count, Max, Min and Sum, respectively, to all the cells containing numeric values on a given range.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id471621539319385"> + <input>svc.DAvg(range: str): float</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="bas_id331595777279484"> + <input>svc.DCount(range: str): float</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="bas_id911595777285935"> + <input>svc.DMax(range: str): float</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="bas_id471595777292407"> + <input>svc.DMin(range: str): float</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="bas_id41595777298840"> + <input>svc.DSum(range: str): float</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id741595777001537"><emph>range</emph>: The range to which the function will be applied, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id121611752704572">The example below applies the <literal>Sum</literal> function to the range "A1:A1000" of the currently selected sheet:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id98159577700195">result = oDoc.DSum("~.A1:A1000")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id651621539472141">result = myDoc.DSum("~.A1:A1000")</paragraph> + </pycode> + <note id="par_id31611752782288">Cells in the given range that contain text will be ignored by all of these functions. For example, the <literal>DCount</literal> method will not count cells with text, only numerical cells.</note> +</section> + +<section id="ExportRangeToFile"> + <comment> ExportRangeToFile --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id271591632729478"> + <bookmark_value>Calc service;ExportRangeToFile</bookmark_value> + </bookmark> + <h2 id="hd_id331591632723258" localize="false">ExportRangeToFile</h2> + <paragraph role="paragraph" id="par_id501623063693113">Exports the specified range as an image or PDF file.</paragraph> + <paragraph role="paragraph" id="par_id401655654738754">This method returns <literal>True</literal> if the destination file was successfully saved.</paragraph> + <note id="par_id871655655302952">Hidden rows or columns in the specified range are not exported to the destination file.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id371623063577228"> + <input>svc.ExportRangeToFile(range: str, filename: str, imagetype: str = "pdf", overwrite: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441623090896470"><emph>range</emph>: A sheet name or a cell range to be exported, as a string.</paragraph> + <paragraph role="paragraph" id="par_id451623063452651"><emph>filename</emph>: The name of the file to be saved. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id441623090895310"><emph>imagetype</emph>: Identifies the destination file type. Possible values are "jpeg", "pdf" (default) and "png".</paragraph> + <paragraph role="paragraph" id="par_id441623090896317"><emph>overwrite</emph>: When set to <literal>True</literal>, the destination file may be overwritten (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id561655655121456">' Exports the entire sheet as a PDF file</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691623063398621">oDoc.ExportRangeToFile("SheetX", "C:\Temp\image.pdf")</paragraph> + <paragraph role="bascode" id="bas_id991655655060661">' Exports the range as a PNG file and overwrites the destination file if it exists</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191623063399539">oDoc.ExportRangeToFile("SheetX.A1:D10", "C:\Temp\image.png", "png", Overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id271623063215113">doc.ExportRangeToFile("SheetX", r"C:\Temp\image.pdf")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id961623063234881">doc.ExportRangeToFile("SheetX.A1:D10", r"C:\Temp\image.png", "png", overwrite = True)</paragraph> + </pycode> +</section> + +<section id="Forms"> + <comment> Forms ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id271591632726788"> + <bookmark_value>Calc service;Forms</bookmark_value> + </bookmark> + <h2 id="hd_id331591632724120" localize="false">Forms</h2> + <paragraph role="paragraph" id="par_id501623063693649">Depending on the parameters provided this method will return:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id611623063742045" role="listitem">A zero-based Array (or a tuple in Python) with the names of all the forms contained in a given sheet (if the <literal>form</literal> argument is absent)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id641623063744536" role="listitem">A <literal>SFDocuments.Form</literal> service instance representing the form specified as argument.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id371623063588128"> + <input>svc.Forms(sheetname: str): str[0..*]</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id371623063588699"> + <input>svc.Forms(sheetname: str, form: str = ''): svc</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id751623151751397"> + <input>svc.Forms(sheetname: str, form: int): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441623090893210"><emph>sheetname</emph>: The name of the sheet, as a string, from which the form will be retrieved.</paragraph> + <paragraph role="paragraph" id="par_id451623063459286"><emph>form</emph>: The name or index corresponding to a form stored in the specified sheet. If this argument is absent, the method will return a list with the names of all forms available in the sheet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id251623063305557">In the following examples, the first line gets the names of all forms stored in "Sheet1" and the second line retrieves the <literal>Form</literal> object of the form named "Form_A" which is stored in "Sheet1".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191623063399519">Set FormNames = oDoc.Forms("Sheet1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691623063399711">Set FormA = oDoc.Forms("Sheet1", "Form_A")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id271623063215023">form_names = doc.Forms("Sheet1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id961623063234990">form_A = doc.Forms("Sheet1", "Form_A")</paragraph> + </pycode> +</section> + +<section id="GetColumnName"> + <comment> GetColumnName -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id271591632726624"> + <bookmark_value>Calc service;GetColumnName</bookmark_value> + </bookmark> + <h2 id="hd_id331591632726750" localize="false">GetColumnName</h2> + <paragraph role="paragraph" id="par_id401591632726431">Converts a column number ranging between 1 and 1024 into its corresponding letter (column 'A', 'B', ..., 'AMJ'). If the given column number is outside the allowed range, a zero-length string is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id781621539718872"> + <input>svc.GetColumnName(columnnumber: int): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id83159163272628"><emph>columnnumber</emph>: The column number as an integer value in the interval 1 ... 1024.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id11621539831303">Displays a message box with the name of the third column, which by default is "C".</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id301591632726262">MsgBox oDoc.GetColumnName(3)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id661621539873908">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901621540022229">bas.MsgBox(myDoc.GetColumnName(3))</paragraph> + </pycode> + <note id="par_id451611753568778">The maximum number of columns allowed on a Calc sheet is 1024.</note> +</section> + +<section id="GetFormula"> + <comment> GetFormula -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141593880142749"> + <bookmark_value>Calc service;GetFormula</bookmark_value> + </bookmark> + <h2 id="hd_id88159388014220" localize="false">GetFormula</h2> + <paragraph role="paragraph" id="par_id921593880142573">Get the formula(s) stored in the given range of cells as a single string, a 1D or a 2D array of strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301621540291513"> + <input>svc.GetFormula(range: str): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880142588"><emph>range</emph>: The range where to get the formulas from, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id461611755257141">The following example returns a 3 by 2 array with the formulas in the range "A1:B3" (3 rows by 2 columns):</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id701593880142992">arrFormula = oDoc.GetFormula("~.A1:B3")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id191621540254086">arrFormula = myDoc.GetFormula("~.A1:B3")</paragraph> + </pycode> +</section> + +<section id="GetValue"> + <comment> GetValue -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571592231156848"> + <bookmark_value>Calc service;GetValue</bookmark_value> + </bookmark> + <h2 id="hd_id471592231156242" localize="false">GetValue</h2> + <paragraph role="paragraph" id="par_id331592231156425">Get the value(s) stored in the given range of cells as a single value, a 1D array or a 2D array. All values are either doubles or strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id51621540380926"> + <input>svc.GetValue(range: str): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id91592231156434"><emph>range</emph>: The range where to get the values from, as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id701592231156881">arrValues = oDoc.GetValue("~.B1:C100")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id931621540443237">arrValues = myDoc.GetValue("~.B1:C100")</paragraph> + </pycode> + <note id="par_id991611756492772">If a cell contains a date, the number corresponding to that date will be returned. To convert numeric values to dates in Basic scripts, use the Basic <link href="text/sbasic/shared/03100300.xhp" name="CDate Basic"><literal>CDate</literal> builtin function</link>. In Python scripts, use the <link href="text/sbasic/shared/03/sf_basic.xhp#CDate" name="CDate Python"><literal>CDate</literal> function from the <literal>Basic</literal> service.</link></note> +</section> + +<section id="ImportFromCSVFile"> + <comment> ImportFromCSVFile -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id381593685490638"> + <bookmark_value>Calc service;ImportFromCSVFile</bookmark_value> + </bookmark> + <h2 id="hd_id151593685490480" localize="false">ImportFromCSVFile</h2> + <paragraph role="paragraph" id="par_id771593685490395">Imports the contents of a CSV-formatted text file and places it on a given destination cell.</paragraph> + <paragraph role="paragraph" id="par_id751611756909199">The destination area is cleared of all contents and formats before inserting the contents of the CSV file. The size of the modified area is fully determined by the contents of the input file.</paragraph> + <paragraph role="paragraph" id="par_id911593685490873" xml-lang="en-US">The method returns a string representing the modified range of cells.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id661621540542882"> + <input>svc.ImportFromCSVFile(filename: str, destinationcell: str, [filteroptions: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id851593685490824"><emph>filename</emph>: Identifies the file to open. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id641593685490936" xml-lang="en-US"><emph>destinationcell</emph>: The destination cell to insert the imported data, as a string. If instead a range is given, only its top-left cell is considered.</paragraph> + <paragraph role="paragraph" id="par_id641593685863838" xml-lang="en-US"><emph>filteroptions</emph>: The arguments for the CSV input filter. The default filter makes following assumptions:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id661593686250471" role="listitem" xml-lang="en-US">The input file encoding is UTF8.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id161593686260876" role="listitem" xml-lang="en-US">The field separator is a comma, a semi-colon or a Tab character.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id711593686274293" role="listitem" xml-lang="en-US">The string delimiter is the double quote (").</paragraph> + </listitem> + <listitem> + <paragraph id="par_id171593686280838" role="listitem" xml-lang="en-US">All lines are included.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id881593686287161" role="listitem" xml-lang="en-US">Quoted strings are formatted as text.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id161593686293473" role="listitem" xml-lang="en-US">Special numbers are detected.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id791593686300499" role="listitem" xml-lang="en-US">All columns are presumed to be texts, except if recognized as valid numbers.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id381593686307406" role="listitem" xml-lang="en-US">The language is English/US, which implies that the decimal separator is "." and the thousands separator is ",".</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id181593685490526">oDoc.ImportFromCSVFile("C:\Temp\myCSVFile.csv", "SheetY.C5")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401621541021415">myDoc.ImportFromCSVFile(r"C:\Temp\myCSVFile.csv", "SheetY.C5")</paragraph> + </pycode> + <tip id="par_id531611757154931">To learn more about the CSV Filter Options, refer to the <link href="text/shared/guide/csv_params.xhp" name="CSV Filter Options">CSV Filter Options help page</link>.</tip> +</section> + +<section id="ImportFromDatabase"> + <comment> ImportFromDatabase -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id281599568986735"> + <bookmark_value>Calc service;ImportFromDatabase</bookmark_value> + </bookmark> + <h2 id="hd_id1001599568986535" localize="false">ImportFromDatabase</h2> + <paragraph role="paragraph" id="par_id881599568986824">Imports the contents of a database table, query or resultset, i.e. the result of a SELECT SQL command, inserting it on a destination cell.</paragraph> + <paragraph role="paragraph" id="par_id81611763957509">The destination area is cleared of all contents and formats before inserting the imported contents. The size of the modified area is fully determined by the contents in the table or query.</paragraph> + <paragraph role="paragraph" id="par_id51599568986387" xml-lang="en-US">The method returns <literal>True</literal> when the import was successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id451621542093265"> + <input>svc.ImportFromDatabase(filename: str = "", registrationname: str = "", destinationcell: str = "", sqlcommand: str = "", directsql: bool): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id311599568986784"><emph>filename</emph>: Identifies the file to open. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id711596555746281" xml-lang="en-US"><emph>registrationname</emph>: The name to use to find the database in the databases register. This argument is ignored if a <literal>filename</literal> is provided.</paragraph> + <paragraph role="paragraph" id="par_id211599568986329" xml-lang="en-US"><emph>destinationcell</emph>: The destination of the imported data, as a string. If a range is given, only its top-left cell is considered.</paragraph> + <paragraph role="paragraph" id="par_id451599489278429"><emph>sqlcommand</emph>: A table or query name (without surrounding quotes or square brackets) or a SELECT SQL statement in which table and field names may be surrounded by square brackets or quotes to improve its readability.</paragraph> + <paragraph role="paragraph" id="par_id271599489278141" xml-lang="en-US"><emph>directsql</emph>: When <literal>True</literal>, the SQL command is sent to the database engine without pre-analysis. Default is <literal>False</literal>. The argument is ignored for tables. For queries, the applied option is the one set when the query was defined.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id801599568986870">oDoc.ImportFromDatabase("C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id701621542319336">myDoc.ImportFromDatabase(r"C:\Temp\myDbFile.odb", , "SheetY.C5", "SELECT * FROM [Employees] ORDER BY [LastName]")</paragraph> + </pycode> +</section> + +<section id="InsertSheet"> + <comment> InsertSheet -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id511591698472720"> + <bookmark_value>Calc service;InsertSheet</bookmark_value> + </bookmark> + <h2 id="hd_id661591698472897" localize="false">InsertSheet</h2> + <paragraph role="paragraph" id="par_id121591698472929">Inserts a new empty sheet before an existing sheet or at the end of the list of sheets.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id531621619656738"> + <input>svc.InsertSheet(sheetname: str, [beforesheet: any]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id941591698472748"><emph>sheetname</emph>: The name of the new sheet.</paragraph> + <paragraph role="paragraph" id="par_id84159169847269" xml-lang="en-US"><emph>beforesheet</emph>: The name (string) or index (numeric, starting from 1) of the sheet before which to insert the new sheet. This argument is optional and the default behavior is to insert the sheet at the last position.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id241611764359510">The following example inserts a new empty sheet named "SheetX" and places it before "SheetY":</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851591698472747">oDoc.InsertSheet("SheetX", "SheetY")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21621619930373">myDoc.InsertSheet("SheetX", "SheetY")</paragraph> + </pycode> +</section> + +<section id="MoveRange"> + <comment> MoveRange -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id381592569476239"> + <bookmark_value>Calc service;MoveRange</bookmark_value> + </bookmark> + <h2 id="hd_id721592569476510" localize="false">MoveRange</h2> + <paragraph role="paragraph" id="par_id6415925694762">Moves a specified source range to a destination range of cells. The method returns a string representing the modified range of cells. The dimension of the modified area is fully determined by the size of the source area.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + + <paragraph role="paragraph" localize="false" id="par_id211621620062306"> + <input>svc.MoveRange(source: str, destination: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id571592569476332"><emph>source</emph>: The source range of cells, as a string.</paragraph> + <paragraph role="paragraph" id="par_id891592569476362" xml-lang="en-US"><emph>destination</emph>: The destination cell, as a string. If a range is given, its top-left cell is considered as the destination.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id651592569476254">oDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="par_id171621619974289">myDoc.MoveRange("SheetX.A1:F10", "SheetY.C5")</paragraph> + </pycode> +</section> + +<section id="MoveSheet"> + <comment> MoveSheet -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id561591698903617"> + <bookmark_value>Calc service;MoveSheet</bookmark_value> + </bookmark> + <h2 id="hd_id761591698903271" localize="false">MoveSheet</h2> + <paragraph role="paragraph" id="par_id831591698903829">Moves an existing sheet and places it before a specified sheet or at the end of the list of sheets.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001621620119732"> + <input>svc.MoveSheet(sheetname: str, [beforesheet: any]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id351591698903911"><emph>sheetname</emph>: The name of the sheet to move. The sheet must exist or an exception is raised.</paragraph> + <paragraph role="paragraph" id="par_id9159169890334" xml-lang="en-US"><emph>beforesheet</emph>: The name (string) or index (numeric, starting from 1) of the sheet before which the original sheet will be placed. This argument is optional and the default behavior is to move the sheet to the last position.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id951611766058734">The example below moves the existing sheet "SheetX" and places it before "SheetY":</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id271591698903687">oDoc.MoveSheet("SheetX", "SheetY")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id561621620208625">myDoc.MoveSheet("SheetX", "SheetY")</paragraph> + </pycode> +</section> + +<section id="Offset"> + <comment> Offset ------------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id29159223350681"> + <bookmark_value>Calc service;Offset</bookmark_value> + </bookmark> + <h2 id="hd_id61592233506228" localize="false">Offset</h2> + <paragraph role="paragraph" id="par_id51592233506371">Returns a new range (as a string) offset by a certain number of rows and columns from a given range.</paragraph> + <paragraph role="paragraph" id="par_id61611768400376">This method has the same behavior as the homonymous Calc's <link href="text/scalc/01/04060109.xhp" name="Offset function">Offset function</link>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301621620394077"> + <input>svc.Offset(reference: str, rows: int = 0, columns: int = 0, [height: int], [width: int]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id901592233506293"><emph>reference</emph>: The range, as a string, that the method will use as reference to perform the offset operation.</paragraph> + <paragraph role="paragraph" id="par_id781592234124856" xml-lang="en-US"><emph>rows</emph>: The number of rows by which the initial range is offset upwards (negative value) or downwards (positive value). Use 0 (default) to stay in the same row.</paragraph> + <paragraph role="paragraph" id="par_id971592234138769" xml-lang="en-US"><emph>columns</emph>: The number of columns by which the initial range is offset to the left (negative value) or to the right (positive value). Use 0 (default) to stay in the same column.</paragraph> + <paragraph role="paragraph" id="par_id321592234150061" xml-lang="en-US"><emph>height</emph>: The vertical height for an area that starts at the new range position. Omit this argument when no vertical resizing is needed.</paragraph> + <paragraph role="paragraph" id="par_id271592234165247" xml-lang="en-US"><emph>width</emph>: The horizontal width for an area that starts at the new range position. Omit this argument when no horizontal resizing is needed.</paragraph> + <paragraph role="paragraph" id="par_id871592234172652" xml-lang="en-US">Arguments <literal>rows</literal> and <literal>columns</literal> must not lead to zero or negative start row or column.</paragraph> + <paragraph role="paragraph" id="par_id211592234180073" xml-lang="en-US">Arguments <literal>height</literal> and <literal>width</literal> must not lead to zero or negative count of rows or columns.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id341592234459577">oDoc.Offset("A1", 2, 2)</paragraph> + <paragraph role="bascode" id="bas_id651592234465732">'SheetX.$C$3 (A1 moved by two rows and two columns down)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51592234472632">oDoc.Offset("A1", 2, 2, 5, 6)</paragraph> + <paragraph role="bascode" id="bas_id521592234478848">'SheetX.$C$3:$H$7 (A1 offset by two rows and columns with width of 5 rows and 6 columns)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id181621620341176">myDoc.Offset("A1", 2, 2)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991621620345183">myDoc.Offset("A1", 2, 2, 5, 6)</paragraph> + </pycode> +</section> + +<section id="OpenRangeSelector"> + <comment> OpenRangeSelector ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id29159223350681"> + <bookmark_value>Calc service;OpenRangeSelector</bookmark_value> + </bookmark> + <h2 id="hd_id61592233506804" localize="false">OpenRangeSelector</h2> + <paragraph role="paragraph" id="par_id51592233506021">Opens a non-modal dialog that can be used to select a range in the document and returns a string containing the selected range.</paragraph> + <note id="par_id301637936295380">This method opens the same dialog that is used by %PRODUCTNAME when the Shrink button is pressed. For example, the <menuitem>Tools - Goal Seek</menuitem> dialog has a Shrink button to the right of the <menuitem>Formula cell</menuitem> field.</note> + <paragraph role="paragraph" id="par_id551637936545121">This method does not change the current selection.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301621620394202"> + <input>svc.OpenRangeSelector(opt title: str, opt selection: str, singlecell: bool = False, closeafterselect: bool = True): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id901592233506001"><emph>title</emph>: The title of the dialog, as a string.</paragraph> + <paragraph role="paragraph" id="par_id781592234124502"><emph>selection</emph>: An optional range that is initially selected when the dialog is displayed.</paragraph> + <paragraph role="paragraph" id="par_id971592234138989"><emph>singlecell</emph>: When <literal>True</literal> (default) only single-cell selection is allowed. When <literal>False</literal> range selection is allowed.</paragraph> + <paragraph role="paragraph" id="par_id321592234150345"><emph>closeafterselect</emph>: When <literal>True</literal> (default) the dialog is closed immediately after the selection is made. When <literal>False</literal> the user can change the selection as many times as needed and then manually close the dialog.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id131637937486802">Dim sRange as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331637937487031">sRange = oDoc.OpenRangeSelector(Title := "Select a range")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id181621620341364">sRange = myDoc.OpenRangeSelector(title = "Select a range")</paragraph> + </pycode> +</section> + +<section id="Printf"> + <comment> Printf ------------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id29159223356581"> + <bookmark_value>Calc service;Printf</bookmark_value> + </bookmark> + <h2 id="hd_id61592233503364" localize="false">Printf</h2> + <paragraph role="paragraph" id="par_id51592233503441">Returns the input string after substituting its token characters by their values in a given range.</paragraph> + <paragraph role="paragraph" id="par_id551637936596521">This method does not change the current selection.</paragraph> + <tip id="par_id171637938442558">This method can be used to quickly extract specific parts of a range name, such as the sheet name or first cell column and row, and use them to compose a new range address.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301621620394154"> + <input>svc.Printf(inputstr: str, range: str, tokencharacter: str = "%"): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id901592233506232"><emph>inputstr</emph>: The string containing the tokens that will be replaced by the corresponding values in <literal>range</literal>.</paragraph> + <paragraph role="paragraph" id="par_id781592234161102"><emph>range</emph>: A <literal>RangeName</literal> from which values will be extracted. If it contains a sheet name, the sheet must exist.</paragraph> + <paragraph role="paragraph" id="par_id971592234102889"><emph>tokencharacter</emph>: Character used to identify tokens. By default "%" is the token character. The following tokens are accepted:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id261637943912156" role="listitem"><emph>%S</emph> - The sheet name containing the range, including single quotes when necessary.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id441637943912380" role="listitem"><emph>%R1</emph> - The row number of the top left cell of the range.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id521637943912620" role="listitem"><emph>%C1</emph> - The column letter of the top left cell of the range.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id371637943912860" role="listitem"><emph>%R2</emph> - The row number of the bottom right cell of the range.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id291637943913116" role="listitem"><emph>%C2</emph> - The column letter of the bottom right cell of the range.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id941637943467476">The example below extracts each element of the <literal>RangeName</literal> defined in <literal>sRange</literal> and uses them to compose a message.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id491637943243426">Dim sRange as String, sInputStr as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921637943243610">sRange = "Sheet1.A1:E10"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991637943243818">sInputStr = "Sheet name: %S" & Chr(10) & _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id516379432447042"> "First row: %R1" & Chr(10) & _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851637943244258"> "First column %C1" & Chr(10) & _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911637943244486"> "Last row %R2" & Chr(10) & _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121637943244706"> "Last column %C2"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821637943244894">MsgBox oDoc.Printf(sInputStr, sRange)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id241637944350648">The <literal>Printf</literal> method can be combined with <literal>SetFormula</literal> to create formulas over multiple cells. For instance, consider a table with numeric values in the range "A1:E10" from which formulas are to be created to sum the values in each row and place the results in the range "F1:F10":</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id631637944876589">Dim sFormula as String, sRange as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281637944876820">sRange = "A1:E10"</paragraph> + <paragraph role="bascode" id="bas_id371637944971921">' Note the use of the "$" character</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711637944876998">sFormula = "=SUM($%C1%R1:$%C2%R1)"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931637944877188">oDoc.SetFormula("F1:F10", oDoc.Printf(sFormula, sRange))</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id161637943523364">sRange = "Sheet1.A1:E10"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951637943523582">sInputStr = "Sheet name: %S\n" \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301637943523764"> "First row: %R1\n" \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631637943523987"> "First column %C1\n" \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id731637943524196"> "Last row %R2\n" \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id516379435243888"> "Last column %C2"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id511637943524613">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id216379435248836">bas.MsgBox(myDoc.Printf(sInputStr, sRange))</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id681637944943446">sRange = "A1:E10</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id851637944943797">sFormula = "=SUM($%C1%R1:$%C2%R1)"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id911637944944046">myDoc.SetFormula("F1:F10", myDoc.Printf(sFormula, sRange))</paragraph> + </pycode> +</section> + +<section id="PrintOut"> + <comment> PrintOut ---------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721985200121249"> + <bookmark_value>Calc service;PrintOut</bookmark_value> + </bookmark> + <h2 id="hd_id261589202101415" localize="false">PrintOut</h2> + <paragraph role="paragraph" id="par_id156589200121138">This method sends the contents of the given sheet to the default printer or to the printer defined by the <literal>SetPrinter</literal> method of the <literal>Document</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id981611169416934">Returns <literal>True</literal> if the sheet was successfully printed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622827822169"> + <input>svc.PrintOut(opt sheetname: str, pages: str = "", copies: num = 1): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id368519200121646"><emph>sheetname</emph>: The sheet to print, default is the active sheet.</paragraph> + <paragraph role="paragraph" id="par_id211635436910093"><emph>pages</emph>: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.</paragraph> + <paragraph role="paragraph" id="par_id141635436912146"><emph>copies</emph>: The number of copies. Default is 1.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891589200121516">If oDoc.PrintOut("SheetX", "1-4;10;15-18", Copies := 2) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515892500606125"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751682227903730">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622728946898">if doc.PrintOut('SheetX', copies=3, pages='45-88'):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221628227947414"> # ...</paragraph> + </pycode> +</section> + +<section id="RemoveSheet"> + <comment> RemoveSheet -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id821591699085559"> + <bookmark_value>Calc service;RemoveSheet</bookmark_value> + </bookmark> + <h2 id="hd_id311591699085933" localize="false">RemoveSheet</h2> + <paragraph role="paragraph" id="par_id661591699085351">Removes an existing sheet from the document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id991621620588147"> + <input>svc.RemoveSheet(sheetname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id331591699085330"><emph>sheetname</emph>: The name of the sheet to remove.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81591699085870">oDoc.RemoveSheet("SheetY")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891621620636884">myDoc.RemoveSheet("SheetY")</paragraph> + </pycode> +</section> + +<section id="RenameSheet"> + <comment> RenameSheet -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781591704316677"> + <bookmark_value>Calc service;RenameSheet</bookmark_value> + </bookmark> + <h2 id="hd_id171591704316197" localize="false">RenameSheet</h2> + <paragraph role="paragraph" id="par_id971591704316873">Renames the given sheet and returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301621620709359"> + <input>svc.RenameSheet(sheetname: str, newname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id161591704316337"><emph>sheetname</emph>: The name of the sheet to rename.</paragraph> + <paragraph role="paragraph" id="par_id931591704316998" xml-lang="en-US"><emph>newname</emph>: the new name of the sheet. It must not exist yet.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id351611775260443">This example renames the active sheet to "SheetY":</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id291591704316891">oDoc.RenameSheet("~", "SheetY")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id521621620764138">mydoc.RenameSheet("~", "SheetY")</paragraph> + </pycode> +</section> + +<section id="SetArray"> + <comment> SetArray -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id221592745582441"> + <bookmark_value>Calc service;SetArray</bookmark_value> + </bookmark> + <h2 id="hd_id831592745582224" localize="false">SetArray</h2> + <paragraph role="paragraph" id="par_id191592745582983">Stores the given value starting from a specified target cell. The updated area expands itself from the target cell or from the top-left corner of the given range to accommodate the size of the input <literal>value</literal> argument. Vectors are always expanded vertically.</paragraph> + <paragraph role="paragraph" id="par_id671592745582573" xml-lang="en-US">The method returns a string representing the modified area as a range of cells.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id401621620954121"> + <input>svc.SetArray(targetcell: str, value: any): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id801592745582116"><emph>targetcell</emph>: The cell or a range as a string from where to start to store the given value.</paragraph> + <paragraph role="paragraph" id="par_id321592745582192" xml-lang="en-US"><emph>value</emph>: A scalar, a vector or an array (in Python, one or two-dimensional lists and tuples) with the new values to be stored from the target cell or from the top-left corner of the range if <literal>targetcell</literal> is a range. The new values must be strings, numeric values or dates. Other types will cause the corresponding cells to be emptied.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id331611776151376">The following example uses the builtin <link href="text/sbasic/shared/03104300.xhp" name="DimArray function">DimArray function</link> to create an array and then store it in cell "A1":</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id691611776204011">Dim arrData as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641611776236071">arrData = DimArray(2, 1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701611776237365">arrData(0, 0) = 1 : arrData(1, 0) = 2 : arrData(2, 0) = 3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901611776237759">arrData(0, 1) = "One" : arrData(1, 1) = "Two" : arrData(2, 1) = "Three"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711611776238030">oDoc.SetArray("Sheet1.A1", arrData)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id601611775600983">This example uses the <literal>RangeInit</literal> method of the <link href="text/sbasic/shared/03/sf_array.xhp#RangeInit" name="CHANGE ME">ScriptForge Array service</link> to create an array with values that are then stored from cell "A1" and downwards.</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id251592745582536">'Fill 1st column with values from 1 to 1000</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51592745582822">oDoc.SetArray("Sheet1.A1", SF_Array.RangeInit(1, 1000))</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id611621621144146">arrData = ((1, "One"), (2, "Two"), (3, "Three"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id451621621144554">myDoc.SetArray("Sheet1.A1", arrData)</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id861621621596623">myDoc.SetArray("Sheet1.A1", tuple(i + 1 for i in range(1000)))</paragraph> + </pycode> + <tip id="par_id291592905671530" xml-lang="en-US">To dump the full contents of an array in a sheet, use <emph>SetArray</emph>. To dump the contents of an array only within the boundaries of the targeted range of cells, use <emph>SetValue</emph>.</tip> +</section> + +<section id="SetValue"> + <comment> SetValue -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id901592231799526"> + <bookmark_value>Calc service;SetValue</bookmark_value> + </bookmark> + <h2 id="hd_id681592231799943" localize="false">SetValue</h2> + <paragraph role="paragraph" id="par_id601592231799489">Stores the given value in the specified range. The size of the modified area is equal to the size of the target range.</paragraph> + <paragraph role="paragraph" id="par_id1001592233389953" xml-lang="en-US">The method returns a string representing the modified area as a range of cells.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id961621622582995"> + <input>svc.SetValue(targetrange: str, value: any): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361592231799255"><emph>targetrange</emph>: The range where to store the given value, as a string.</paragraph> + <paragraph role="paragraph" id="par_id461592232081985" xml-lang="en-US"><emph>value</emph>: A scalar, a vector or an array with the new values for each cell of the range. The new values must be strings, numeric values or dates. Other types will cause the corresponding cells to be emptied.</paragraph> + <paragraph role="paragraph" id="par_id841592745785192" xml-lang="en-US">The full range is updated and the remainder of the sheet is left unchanged. If the size of <literal>value</literal> is smaller than the size of <literal>targetrange</literal>, then the remaining cells will be emptied.</paragraph> + <paragraph role="paragraph" id="par_id191611776838396">If the size of <literal>value</literal> is larger than the size of <literal>targetrange</literal>, then <literal>value</literal> is only partially copied until it fills the size of <literal>targetrange</literal>.</paragraph> + <paragraph role="paragraph" id="par_id71611776941663">Vectors are expanded vertically, except if <literal>targetrange</literal> has a height of exactly 1 row.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id2715922317995">oDoc.SetValue("A1", 2)</paragraph> + <paragraph role="bascode" id="bas_id541592232948567">'Below the Value array is smaller than the TargetRange (remaining cells are emptied)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701592232940773">oDoc.SetValue("A1:F1", Array(1, 2, 3))</paragraph> + <paragraph role="bascode" id="bas_id541592232948825">'Below the Value and TargetRange have the same size</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981592232966698">oDoc.SetValue("A1:D2", SF_Array.AppendRow(Array(1, 2, 3, 4), Array(5, 6, 7, 8)))</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id731621689592755">If you want to fill a single row with values, you can use the <literal>Offset</literal> function. In the example below, consider that <literal>arrData</literal> is a one-dimensional array:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id21621689635263">Dim firstCell As String : firstCell = "A1"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881621689635592">Dim lenArray As Integer : lenArray = UBound(arrData) - LBound(arrData) + 1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71621689635887">Dim newRange As String : newRange = oDoc.Offset(firstCell, width = lenArray)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831621689898866">oDoc.SetValue(newRange, arrData)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id861621622679043">myDoc.SetValue("A1", 2)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id881621622724608">myDoc.SetValue("A1:F1", (1, 2, 3))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id51621622725754">myDoc.SetValue("A1:D2", ((1, 2, 3, 4), (5, 6, 7, 8)))</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891621689922925">firstCell = "A1"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id61621689923184">newRange = doc.Offset(firstCell, width = len(arrData))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771621689923430">doc.SetValue(newRange, arrData)</paragraph> + </pycode> +</section> + +<section id="SetCellStyle"> + <comment> SetCellStyle -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id21595767687885"> + <bookmark_value>Calc service;SetCellStyle</bookmark_value> + </bookmark> + <h2 id="hd_id201595767687377" localize="false">SetCellStyle</h2> + <paragraph role="paragraph" id="par_id521595767687154">Applies the specified cell style to the given target range. The full range is updated and the remainder of the sheet is left untouched. If the cell style does not exist, an error is raised.</paragraph> + <paragraph role="paragraph" id="par_id70159576768715" xml-lang="en-US">The method returns a string representing the modified area as a range of cells.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id731621622877726"> + <input>svc.SetCellStyle(targetrange: str, style: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id22159576768782"><emph>targetrange</emph>: The range to which the style will be applied, as a string.</paragraph> + <paragraph role="paragraph" id="par_id181595767687247" xml-lang="en-US"><emph>style</emph>: The name of the cell style to apply.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id661595767687880">oDoc.SetCellStyle("A1:J1", "Heading 1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541595767687904">oDoc.SetCellStyle("A2:J100", "Neutral")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731621622966995">myDoc.SetCellStyle("A1:J1", "Heading 1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931621622967434">myDoc.SetCellStyle("A2:J100", "Neutral")</paragraph> + </pycode> +</section> + +<section id="SetFormula"> + <comment> SetFormula -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231593880376363"> + <bookmark_value>Calc service;SetFormula</bookmark_value> + </bookmark> + <h2 id="hd_id191593880376344" localize="false">SetFormula</h2> + <paragraph role="paragraph" id="par_id481593880376480">Inserts the given (array of) formula(s) in the specified range. The size of the modified area is equal to the size of the range.</paragraph> + <paragraph role="paragraph" id="par_id711593880376106" xml-lang="en-US">The method returns a string representing the modified area as a range of cells.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701621623027410"> + <input>svc.SetFormula(targetrange: str, formula: any): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880376776"><emph>targetrange</emph>: The range to insert the formulas, as a string.</paragraph> + <paragraph role="paragraph" id="par_id941593880376500"><emph>formula</emph>: A string, a vector or an array of strings with the new formulas for each cell in the target range.</paragraph> + <paragraph role="paragraph" id="par_id551593880376513">The full range is updated and the remainder of the sheet is left unchanged.</paragraph> + <paragraph role="paragraph" id="par_id811593880756356">If the given formula is a string, the unique formula is pasted along the whole range with adjustment of the relative references.</paragraph> + <paragraph role="paragraph" id="par_id491593880857823">If the size of <literal>formula</literal> is smaller than the size of <literal>targetrange</literal>, then the remaining cells are emptied.</paragraph> + <paragraph role="paragraph" id="par_id701611778103306">If the size of <literal>formula</literal> is larger than the size of <literal>targetrange</literal>, then the formulas are only partially copied until it fills the size of <literal>targetrange</literal>.</paragraph> + <paragraph role="paragraph" id="par_id761611777946581">Vectors are always expanded vertically, except if <literal>targetrange</literal> has a height of exactly 1 row.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id441593880376307">oDoc.SetFormula("A1", "=A2")</paragraph> + <paragraph role="bascode" id="bas_id681593880376489">'Horizontal vector, partially empty</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951593880376376">oDoc.SetFormula("A1:F1", Array("=A2", "=B2", "=C2+10"))</paragraph> + <paragraph role="bascode" id="bas_id961593881331390">'D2 contains the formula "=H2"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951593880376571">oDoc.SetFormula("A1:D2", "=E1")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941621623159044">myDoc.SetFormula("A1", "=A2")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151621623174150">myDoc.SetFormula("A1:F1", ("=A2", "=B2", "=C2+10"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623174759">myDoc.SetFormula("A1:D2", "=E1")</paragraph> + </pycode> +</section> + +<section id="ShiftDown"> + <comment> ShiftDown --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231593880376104"> + <bookmark_value>Calc service;ShiftDown</bookmark_value> + </bookmark> + <h2 id="hd_id191593880376667" localize="false">ShiftDown</h2> + <paragraph role="paragraph" id="par_id481593880373070">Moves a given range of cells downwards by inserting empty rows. The current selection is not affected.</paragraph> + <paragraph role="paragraph" id="par_id801637929435655">Depending on the value of the <literal>wholerow</literal> argument the inserted rows can either span the width of the specified range or span all columns in the row.</paragraph> + <paragraph role="paragraph" id="par_id711593880370247" xml-lang="en-US">This method returns a string representing the new location of the initial range.</paragraph> + <note id="par_id811637929284110">If the shifted range exceeds the sheet edges, then nothing happens.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701621623022250"> + <input>svc.ShiftDown(range: str, wholerow: bool = False, opt rows: int): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880376123"><emph>range</emph>: The range above which rows will be inserted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id941593880376566"><emph>wholerow</emph>: If set to <literal>False</literal> (default), then the width of the inserted rows will be the same as the width of the specified <literal>range</literal>. Otherwise, the inserted row will span all columns in the sheet.</paragraph> + <paragraph role="paragraph" id="par_id551593880373045"><emph>rows</emph>: The number of rows to be inserted. The default value is the height of the original <literal>range</literal>. The number of rows must be a positive number.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id881637931053547">' Moves the range "A3:D3" down by one row; affects only columns A to D</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791637931053747">oDoc.ShiftDown("A3:D3")</paragraph> + <paragraph role="bascode" id="bas_id661637931232893">' The inserted row spans all columns in the sheet</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741637931233093">oDoc.ShiftDown("A3:D3", WholeRow := True)</paragraph> + <paragraph role="bascode" id="bas_id291637931053897">' Moves the range "A3:D3" down by five rows</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91637931054041">oDoc.ShiftDown("A3:D3", Rows := 5)</paragraph> + <paragraph role="bascode" id="bas_id501638218784265">' Moves the range "A3:D10" down by two rows and shows the new location of the original range</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391638218784528">Dim sNewRange as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id761638218784697">sNewRange = oDoc.ShiftDown("A3:D10", Rows := 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291638218784864">MsgBox sNewRange ' $Sheet1.$A$5:$D$12</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941621623159122">myDoc.ShiftDown("A3:D3")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623174886">myDoc.ShiftDown("A3:D3", wholerow = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151621623174257">myDoc.ShiftDown("A3:D3", rows = 5)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623174060">sNewRange = myDoc.ShiftDown("A3:D10", rows = 2)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621638218996706">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151638218996938">bas.MsgBox(sNewRange)</paragraph> + </pycode> +</section> + +<section id="ShiftLeft"> + <comment> ShiftLeft --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231593880376547"> + <bookmark_value>Calc service;ShiftLeft</bookmark_value> + </bookmark> + <h2 id="hd_id191593880373026" localize="false">ShiftLeft</h2> + <paragraph role="paragraph" id="par_id481593880376255">Deletes the leftmost columns of a given range and moves to the left all cells to the right of the affected range. The current selection is not affected.</paragraph> + <paragraph role="paragraph" id="par_id801637929460261">Depending on the value of the <literal>wholecolumn</literal> argument the deleted columns can either span the height of the specified range or span all rows in the column.</paragraph> + <paragraph role="paragraph" id="par_id711593880371259" xml-lang="en-US">This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701621623026330"> + <input>svc.ShiftLeft(range: str, wholecolumn: bool = False, opt columns: int): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880376205"><emph>range</emph>: The range from which cells will be deleted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id941593880356026"><emph>wholecolumn</emph>: If set to <literal>False</literal> (default), then the height of the deleted columns will be the same as the height of the specified <literal>range</literal>. Otherwise, the deleted columns will span all rows in the sheet.</paragraph> + <paragraph role="paragraph" id="par_id551593880373306"><emph>columns</emph>: The number of columns to be deleted from the specified <literal>range</literal>. The default value is the width of the original <literal>range</literal>, which is also the maximum value of this argument.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id881637931064919">' Deletes the range "B3:B6"; moves left all cells to the right</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791637931033877">oDoc.ShiftLeft("B3:B6")</paragraph> + <paragraph role="bascode" id="bas_id291637931056991">' Deletes the first column in the range "A3:D6"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916379310515507">oDoc.ShiftLeft("A3:D6", Columns := 1)</paragraph> + <paragraph role="bascode" id="bas_id661637931232569">' The deleted columns (A to D) spans all rows in the sheet</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741637931230274">oDoc.ShiftLeft("A3:D6", WholeColumn := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941621623156582">myDoc.ShiftLeft("B3:B6")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151621623155447">myDoc.ShiftLeft("A3:D6", Columns = 1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623172116">myDoc.ShiftLeft("A3:D6", WholeColumn = True)</paragraph> + </pycode> +</section> + +<section id="ShiftUp"> + <comment> ShiftUp ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231593880376104"> + <bookmark_value>Calc service;ShiftUp</bookmark_value> + </bookmark> + <h2 id="hd_id191593880370547" localize="false">ShiftUp</h2> + <paragraph role="paragraph" id="par_id481593880373529">Deletes the topmost rows of a given range and moves upwards all cells below the affected range. The current selection is not affected.</paragraph> + <paragraph role="paragraph" id="par_id801637929435361">Depending on the value of the <literal>wholerow</literal> argument the deleted rows can either span the width of the specified range or span all columns in the row.</paragraph> + <paragraph role="paragraph" id="par_id711593880370299" xml-lang="en-US">This method returns a string representing the location of the remaining portion of the initial range. If all cells in the original range have been deleted, then an empty string is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701621623026380"> + <input>svc.ShiftUp(range: str, wholerow: bool = False, opt rows: int): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880376583"><emph>range</emph>: The range from which cells will be deleted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id941593880300966"><emph>wholerow</emph>: If set to <literal>False</literal> (default), then the width of the deleted rows will be the same as the width of the specified <literal>range</literal>. Otherwise, the deleted row will span all columns in the sheet.</paragraph> + <paragraph role="paragraph" id="par_id551593880373265"><emph>rows</emph>: The number of rows to be deleted from the specified <literal>range</literal>. The default value is the height of the original <literal>range</literal>, which is also the maximum value of this argument.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id881637931064667">' Deletes the range "A3:D3"; moves all cells below it by one row up</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791637931056477">oDoc.ShiftUp("A3:D3")</paragraph> + <paragraph role="bascode" id="bas_id291637931056647">' Deletes the first row in the range "A3:D6"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91637931054337">oDoc.ShiftUp("A3:D6", Rows := 1)</paragraph> + <paragraph role="bascode" id="bas_id661637931232493">' The deleted rows spans all columns in the sheet</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741637931233634">oDoc.ShiftUp("A3:D6", WholeRow := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941621623150252">myDoc.ShiftUp("A3:D3")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151621623176647">myDoc.ShiftUp("A3:D6", rows = 1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623174036">myDoc.ShiftUp("A3:D6", wholerow = True)</paragraph> + </pycode> +</section> + +<section id="ShiftRight"> + <comment> ShiftRight --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231593880376025"> + <bookmark_value>Calc service;ShiftRight</bookmark_value> + </bookmark> + <h2 id="hd_id191593880376547" localize="false">ShiftRight</h2> + <paragraph role="paragraph" id="par_id481593880372568">Moves a given range of cells to the right by inserting empty columns. The current selection is not affected.</paragraph> + <paragraph role="paragraph" id="par_id801637929335255">Depending on the value of the <literal>wholecolumn</literal> argument the inserted columns can either span the height of the specified range or span all rows in the column.</paragraph> + <paragraph role="paragraph" id="par_id711593880372560" xml-lang="en-US">This method returns a string representing the new location of the initial range.</paragraph> + <note id="par_id811637929283210">If the shifted range exceeds the sheet edges, then nothing happens.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701621623022269"> + <input>svc.ShiftRight(range: str, wholecolumn: bool = False, opt columns: int): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id891593880370543"><emph>range</emph>: The range which will have empty columns inserted to its left, as a string.</paragraph> + <paragraph role="paragraph" id="par_id941593880373316"><emph>wholecolumn</emph>: If set to <literal>False</literal> (default), then the height of the inserted columns will be the same as the height of the specified <literal>range</literal>. Otherwise, the inserted columns will span all rows in the sheet.</paragraph> + <paragraph role="paragraph" id="par_id5515938803791960"><emph>columns</emph>: The number of columns to be inserted. The default value is the width of the original <literal>range</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id881637931052587">' Moves the range "A3:A6" right by one column; affects only rows 3 to 6</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791637931053646">oDoc.ShiftRight("A3:A6")</paragraph> + <paragraph role="bascode" id="bas_id291637931053225">' Moves the range "A3:A6" right by five columns</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916379310503221">oDoc.ShiftRight("A3:A6", Columns := 5)</paragraph> + <paragraph role="bascode" id="bas_id661637931232548">' The inserted column spans all rows in the sheet</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741637931330323">oDoc.ShiftRight("A3:A6", WholeColumn := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941621623155669">myDoc.ShiftRight("A3:A6")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151621623174603">myDoc.ShiftRight("A3:A6", columns = 5)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651621623174751">myDoc.ShiftRight("A3:A6", wholecolumn = True)</paragraph> + </pycode> +</section> + +<section id="SortRange"> + <comment> SortRange -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id531595692394747"> + <bookmark_value>Calc service;SortRange</bookmark_value> + </bookmark> + <h2 id="hd_id71595692394823" localize="false">SortRange</h2> + <paragraph role="paragraph" id="par_id141595692394382">Sorts the given range based on up to 3 columns/rows. The sorting order may vary by column/row. It returns a string representing the modified range of cells. The size of the modified area is fully determined by the size of the source area.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id871621623279253"> + <input>svc.SortRange(range: str, sortkeys: any, sortorder: any = "ASC", destinationcell: str = "", containsheader: bool = False, casesensitive: bool = False, sortcolumns: bool = False): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id171595692394598"><emph>range</emph>: The range to be sorted, as a string.</paragraph> + <paragraph role="paragraph" id="par_id171595692814163"><emph>sortkeys</emph>: A scalar (if 1 column/row) or an array of column/row numbers starting from 1. The maximum number of keys is 3.</paragraph> + <paragraph role="paragraph" id="par_id421595692962095"><emph>sortorder</emph>: A scalar or an array of strings containing the values "ASC" (ascending), "DESC" (descending) or "" (which defaults to ascending). Each item is paired with the corresponding item in <literal>sortkeys</literal>. If the <literal>sortorder</literal> array is shorter than <literal>sortkeys</literal>, the remaining keys are sorted in ascending order.</paragraph> + <paragraph role="paragraph" id="par_id361595692394604"><emph>destinationcell</emph>: The destination cell of the sorted range of cells, as a string. If a range is given, only its top-left cell is considered. By default the source Range is overwritten.</paragraph> + <paragraph role="paragraph" id="par_id441595693011034"><emph>containsheader</emph>: When <literal>True</literal>, the first row/column is not sorted.</paragraph> + <paragraph role="paragraph" id="par_id241595693169032"><emph>casesensitive</emph>: Only for string comparisons. Default = <literal>False</literal></paragraph> + <paragraph role="paragraph" id="par_id1001595693326226"><emph>sortcolumns</emph>: When <literal>True</literal>, the columns are sorted from left to right. Default = <literal>False</literal> : rows are sorted from top to bottom.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id641595692394484">'Sort range based on columns A (ascending) and C (descending)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id54159569239416">oDoc.SortRange("A2:J200", Array(1, 3), Array("ASC", "DESC"), CaseSensitive := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id581621623543873">myDoc.SortRange("A2:J200", (1, 3), ("ASC", "DESC"), casesensitive = True)</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_chart.xhp#ChartService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_chart.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_chart.xhp new file mode 100644 index 000000000..ca1cc338f --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_chart.xhp @@ -0,0 +1,504 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Chart" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Chart service</title> + <filename>/text/sbasic/shared/03/sf_chart.xhp</filename> + </topic> + </meta> +<body> + <section id="ScriptForge-sf_chart"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788076381"> + <bookmark_value>Chart service</bookmark_value> + </bookmark> + </section> + <section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="ChartService"><link href="text/sbasic/shared/03/sf_chart.xhp" name="Chart service"><literal>SFDocuments</literal>.<literal>Chart</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>Chart</literal> service provides a set of properties and methods to handle charts in Calc documents. With this service it is possible to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">Access chart objects in Calc documents and manipulate their properties.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Create and insert new charts into a Calc document.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id67160078807676" role="listitem">Export charts as image files.</paragraph> + </listitem> + </list> + </section> + + <h2 id="hd_id331635273472588">Chart names</h2> + <paragraph role="paragraph" id="par_id251635273489315">Charts may have two different names:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id41635273536840" role="listitem">An <emph>internal name</emph> given by %PRODUCTNAME as soon as the chart object is created (usually "Object 1", "Object 2" and so on).</paragraph> + </listitem> + <listitem> + <paragraph id="par_id641635273537122" role="listitem">A <emph>user-defined name</emph>, which can be defined by right-clicking the chart and choosing <menuitem>Name</menuitem> in the context menu.</paragraph> + </listitem> + </list> + <note id="par_id191635273980553">The <literal>Chart</literal> service primarily uses the user-defined name to access a chart object. If it does not exist, than the internal name is used.</note> + + <h2 id="hd_id281600788076359">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Chart</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id321614902851541">The <literal>Chart</literal> service is instantiated from a <literal>Calc</literal> service instance either using the <literal>Charts</literal> or <literal>CreateChart</literal> methods.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id531635274285114">The example below creates a <literal>Chart</literal> service instance from an existing chart in the current Calc document:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851600788076202">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001600788076254">Dim oDoc as Object, oChart as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721600788076288">Set oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791600788431935">Set oChart = oDoc.Charts("Sheet1", "Object 1")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id851635274721129">The following example instantiate the <literal>Chart</literal> service by creating a new chart object based on the data contained in the range "Sheet1.A1:C10".</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221635274765110">Dim oDoc as Object, oChart as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461635274776072">Set oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621635274776400">Set oChart = oDoc.CreateChart("My Chart", "Sheet1", "Sheet1.A1:C10")</paragraph> + </bascode> + <tip id="par_id881635275036852">Read the <link href="text/sbasic/shared/03/sf_calc.xhp#CreateChart" name="CreateChart_link">CreateChart</link> method description to learn more about its arguments.</tip> + + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id131635275172617">The examples above can be written in Python as follows:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710433">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311626695710851">chart = doc.Charts("Sheet1", "Object 1")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831635275439182">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381635275439396">chart = doc.CreateChart("My Chart", "Sheet1", "Sheet1.A1:C10")</paragraph> + </pycode> + + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id111614901524769"> + <bookmark_value>Chart service;ChartType</bookmark_value> + <bookmark_value>Chart service;Deep</bookmark_value> + <bookmark_value>Chart service;Dim3D</bookmark_value> + <bookmark_value>Chart service;Exploded</bookmark_value> + <bookmark_value>Chart service;Filled</bookmark_value> + <bookmark_value>Chart service;Legend</bookmark_value> + <bookmark_value>Chart service;Percent</bookmark_value> + <bookmark_value>Chart service;Stacked</bookmark_value> + <bookmark_value>Chart service;Title</bookmark_value> + <bookmark_value>Chart service;XTitle</bookmark_value> + <bookmark_value>Chart service;YTitle</bookmark_value> + <bookmark_value>Chart service;XChartObj</bookmark_value> + <bookmark_value>Chart service;XDiagram</bookmark_value> + <bookmark_value>Chart service;XShape</bookmark_value> + <bookmark_value>Chart service;XTableChart</bookmark_value> + </bookmark> + <h2 id="hd_id711600788076834">Properties</h2> + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">ChartType</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">Specifies the chart type as a string that can assume one of the following values: "Pie", "Bar", "Donut", "Column", "Area", "Line", "XY", "Bubble", "Net".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">Deep</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">When <literal>True</literal> indicates that the chart is three-dimensional and each series is arranged in the z-direction.</paragraph> + <paragraph id="par_id471635276257118" role="tablecontent">When <literal>False</literal> series are arranged considering only two dimensions.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721600788076638" role="tablecontent" localize="false">Dim3D</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711600788076534" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911600788076842" role="tablecontent" localize="false">Boolean or String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600788076645" role="tablecontent">Specifies if the chart is displayed with 3D elements. If the value is a string, it must be either "Bar", "Cylinder", "Cone" or "Pyramid".</paragraph> + <paragraph id="par_id541600788076141" role="tablecontent">If the boolean <literal>True</literal> value is specified, then the chart is displayed using 3D bars.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961600788076890" role="tablecontent" localize="false">Exploded</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891600788076190" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076562" role="tablecontent" localize="false">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91600788076674" role="tablecontent">Specifies how much pie segments are offset from the chart center as a percentage of the radius. Applicable to pie and donut charts only.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719135" localize="false" role="tablecontent">Filled</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747903" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748455" localize="false" role="tablecontent">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749007" role="tablecontent">When <literal>True</literal>, specifies a filled net chart. Applicable to net charts only.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951600788076443" role="tablecontent" localize="false">Legend</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391600788076253" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381600788076799" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076541" role="tablecontent">Specifies whether or not the chart has a legend.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id41600788076936" role="tablecontent" localize="false">Percent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211600788076138" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076518" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521600788076371" role="tablecontent">When <literal>True</literal>, chart series are stacked and each category sums up to 100%. Applicable to Area, Bar, Bubble, Column and Net charts.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161600788076362" role="tablecontent" localize="false">Stacked</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076758" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id871600788076196" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781600788076694" role="tablecontent">When <literal>True</literal>, chart series are stacked. Applicable to Area, Bar, Bubble, Column and Net charts.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id471600788076885" role="tablecontent" localize="false">Title</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261600788076841" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661600788076636" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11600788076757" role="tablecontent">Specifies the main title of the chart.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id221600789141781" role="tablecontent" localize="false">XTitle</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531600789141795" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561600789141282" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301600789141619" role="tablecontent">Specifies the title of the X axis.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id821600789286339" role="tablecontent" localize="false">YTitle</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600789286532" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181600789286889" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701600789286280" role="tablecontent">Specifies the title of the Y axis.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789752717" role="tablecontent" localize="false">XChartObj</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941608709527698" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100100678952791" role="tablecontent">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661300789527859" role="tablecontent">Returns the object representing the chart, which is an instance of the <link href="https://docs.libreoffice.org/sc/html/classScChartObj.html" name="ScChartObj"><literal>ScChartObj</literal></link> class.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789527717" role="tablecontent" localize="false">XDiagram</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941600789527698" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100160078952791" role="tablecontent">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631600789527859" role="tablecontent">Returns the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1chart_1_1XDiagram.html" name="XDiagram"><literal>com.sun.star.chart.XDiagram</literal></link> object representing the diagram of the chart.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789527123" role="tablecontent" localize="false">XShape</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941600789527099" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100160078953251" role="tablecontent">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631600789522587" role="tablecontent">Returns the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1drawing_1_1XShape.html" name="XShape"><literal>com.sun.star.drawing.XShape</literal></link> object representing the shape of the chart.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789527332" role="tablecontent" localize="false">XTableChart</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941600789527208" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100160078952007" role="tablecontent">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631600789527364" role="tablecontent">Returns the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1table_1_1XTableChart.html" name="XTableChart"><literal>com.sun.star.table.XTableChart</literal></link> object representing the data being displayed in the chart.</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id581635335807782">Creating a chart</h2> + <paragraph role="paragraph" id="par_id231635335826090">Consider the following data in the range "A1:B6" of a sheet named "Report".</paragraph> + <table id="tab_id471635335950545"> + <tablerow> + <tablecell> + <paragraph id="par_id901635335950545" localize="false" role="tablehead"></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111635335950545" localize="false" role="tablehead">A</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651635335950545" localize="false" role="tablehead">B</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591635335950822" localize="false" role="tablehead">1</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401635335950901" localize="false" role="tablecontent">Sample A</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151635335950965" localize="false" role="tablecontent">Sample B</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591635335958021" localize="false" role="tablehead">2</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401635335950888" localize="false" role="tablecontent">36</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151635335950047" localize="false" role="tablecontent">40</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591635335956841" localize="false" role="tablehead">3</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401635335950126" localize="false" role="tablecontent">39</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151635335933645" localize="false" role="tablecontent">43</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591635335959875" localize="false" role="tablehead">4</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401635335950008" localize="false" role="tablecontent">45</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151635335950367" localize="false" role="tablecontent">40</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id591635335950287" localize="false" role="tablehead">5</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401635335951225" localize="false" role="tablecontent">52</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151635335950255" localize="false" role="tablecontent">48</paragraph> + </tablecell> + </tablerow> + </table> + <paragraph role="paragraph" id="par_id911635336313498">The examples below in Basic and Python show how to create a line chart from this data with legends.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id971635337992020">oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671633022413022">oChart = oDoc.CreateChart("Samples", "Report", "Report.A1:B6")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721633022413266">oChart.ChartType = "Line"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691633022413526">oChart.Legend = True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41633022413831">oChart.Resize(1000, 1000, 25000, 15000)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id841633022704586">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281633022704771">chart = doc.CreateChart("Samples", "Report", "Report.A1:B6")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211633022704988">chart.ChartType = "Line"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id21635338077411">chart.Legend = True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941633022705212">chart.Resize(1000, 1000, 25000, 15000)</paragraph> + </pycode> + <tip id="par_id931635338174647">The chart does not need to be created in the same sheet where the data is located. It can be created in any existing sheet in the current file by specifying the sheet name in the second argument of the <literal>CreateChart</literal> method.</tip> + + <h2 id="hd_id501582887473754" xml-lang="en-US">Methods</h2> + <table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="2"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Chart Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_chart.xhp#ExportToFile" name="ExportToFile method">ExportToFile</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_chart.xhp#Resize" name="Resize method">Resize</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + + <section id="ExportToFile"> + <comment> ExportToFile ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Chart service;ExportToFile</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">ExportToFile</h2> + <paragraph role="paragraph" id="par_id93158919969864">Saves the chart as an image file in a specified location. Returns <literal>True</literal> if the image file could be successfully created.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014732"> + <input>chart.ExportToFile(filename: str, imagetype: str = "png", overwrite: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203996"><emph>filename</emph>: Identifies the path and file name where the image will be saved. It must follow the notation defined in <literal>SF_FileSystem.FileNaming</literal>.</paragraph> + <paragraph role="paragraph" id="par_id821591631203116"><emph>imagetype</emph>: The name of the image type to be created. The following values are accepted: "gif", "jpeg", "png" (default), "svg" and "tiff".</paragraph> + <paragraph role="paragraph" id="par_id821591631203133"><emph>overwrite</emph>: Specifies if the destination file can be overwritten (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969204">oChart.ExportToFile("C:\Temp\myChart.svg", ImageType := "svg", Overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175122">chart.ExportToFile(r"C:\Temp\myChart.svg", imagetype="svg", overwrite=True)</paragraph> + </pycode> + </section> + + <section id="Resize"> + <comment> Resize ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Chart service;Resize</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698887" localize="false">Resize</h2> + <paragraph role="paragraph" id="par_id93158919969165">Changes the position of the chart in the current sheet and modifies its width and height. Returns <literal>True</literal> if resizing was successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534025532"> + <input>chart.Resize([xpos: int], [ypos: int], [width: int], [height: int]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631200626"><emph>xpos, ypos:</emph> Specify the new X and Y positions of the chart. If any of these values are omitted or if negative values are provided, the corresponding positions are left unchanged.</paragraph> + <paragraph role="paragraph" id="par_id821591631204288"><emph>width:</emph> Specify the new width of the chart. If this argument is omitted or if a negative value is provided, the chart width is left unchanged.</paragraph> + <paragraph role="paragraph" id="par_id821591631203208"><emph>height:</emph> Specify the new height of the chart. If this argument is omitted or if a negative value is provided, the chart height is left unchanged.</paragraph> + <note id="par_id301635340527472">All arguments are provided as integer values that correspond to 1/100 of a millimeter.</note> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id431635340711712">' Changes only X and Y position</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41158919969836">oChart.Rezise(1000, 3000)</paragraph> + <paragraph role="bascode" id="bas_id241635340728398">' Changes only the chart width and height</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251635340748780">oChart.Resize(, , 25000, 12500)</paragraph> + <paragraph role="bascode" id="bas_id201635340749006">' Keyword arguments are supported</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991635340749181">oChart.Resize(Width := 25000, Height := 12500)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175071">chart.Rezise(1000, 3000)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391635340950666">chart.Resize(-1, -1, 20000, 20000)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id11635340951050">chart.Resize(width=25000, height=12500)</paragraph> + </pycode> + </section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_calc.xhp#CalcService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_database.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_database.xhp new file mode 100644 index 000000000..468f83b58 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_database.xhp @@ -0,0 +1,404 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Database" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDatabases.Database service</title> + <filename>/text/sbasic/shared/03/sf_database.xhp</filename> + </topic> +</meta> +<body> +<section id="ScriptForge-sf_database"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id151587913266190"> + <bookmark_value>Database service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id371587913266310" xml-lang="en-US"><variable id="DatabaseService"><link href="text/sbasic/shared/03/sf_database.xhp" name="Database service"><literal>SFDatabases</literal>.<literal>Database</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id891599407198144" xml-lang="en-US">The <literal>Database</literal> service provides access to databases either embedded or described in Base documents. This service provides methods to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id551615386924481" role="listitem">Get access to data in database tables.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id551615386924285" role="listitem">Run <literal>SELECT</literal> queries and perform aggregate functions.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id551615386924111" role="listitem">Run SQL action statements such as <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>, etc.</paragraph> + </listitem> + </list> +</section> + <paragraph role="paragraph" id="par_id811599407236602" xml-lang="en-US">Each instance of the <literal>Database</literal> service represents a single database and gives access to its tables, queries and data.</paragraph> + <paragraph role="paragraph" id="par_id111625692871642">This service does not provide access to forms or reports in the Base document that contains the database. To access forms in a Base document, refer to the method <link href="text/sbasic/shared/03/sf_base.xhp#FormDocuments" name="FormDocuments"><literal>FormDocuments</literal></link> of the <literal>Base</literal> service.</paragraph> + <note id="par_id231615386789950">All exchanges between this service and the database are done using SQL only.</note> + <paragraph role="paragraph" id="par_id121599407322804" xml-lang="en-US">SQL statements may be run in <emph>direct</emph> or <emph>indirect</emph> mode. In direct mode the statement is transferred to the database engine without any syntax checking or review.</paragraph> + <paragraph role="paragraph" id="par_id681599407189019" xml-lang="en-US">The provided interfaces include simple tables and queries lists, as well as access to database data.</paragraph> + <tip id="par_id891599407280007" xml-lang="en-US">To make SQL statements more readable, you may use square brackets "[ ]" to enclose names of tables, queries and fields instead of using other enclosing characters that may be exclusive to certain Relational Database Management Systems (RDBMS). But beware that enclosing characters are mandatory in this context.</tip> + + <h2 id="hd_id91587913266988" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Database</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id541599408159668" xml-lang="en-US">To create a instance of the <literal>Database</literal> service you can use the <literal>CreateScriptService</literal> method:</paragraph> + <paragraph role="paragraph" localize="false" id="par_id251625693098616"> + <input>CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc</input> + </paragraph> + <note id="par_id551625693442959">In the syntax described above you can use either "SFDatabases.Database" or simply "Database" as the first argument of the <literal>CreateScriptService</literal> method.</note> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id111615146818256"><emph>filename</emph>: The name of the Base file. Must be expressed using <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id771615146944307"><emph>registrationname</emph>: The name of a registered database. If <literal>filename</literal> is provided, this argument should not be used.</paragraph> + <paragraph role="paragraph" id="par_id491615147048748">Conversely, if a <literal>registrationname</literal> is specified, the <literal>filename</literal> parameter should not be defined.</paragraph> + <paragraph role="paragraph" id="par_id841615147168279"><emph>readonly</emph>: Determines if the database will be opened as readonly (Default = <literal>True</literal>).</paragraph> + <paragraph role="paragraph" id="par_id291615147236001"><emph>user, password</emph>: Additional connection parameters to the database server.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id451625698094586">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191625698094873">Dim myDatabase as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181625698095184">Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")</paragraph> + <paragraph role="bascode" id="bas_id871625698095504">' Run queries, SQL statements, ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501625698095793">myDatabase.CloseDatabase()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id291625698186091">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141625698186499">myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")</paragraph> + <paragraph role="pycode" id="pyc_id791625698186675"># Run queries, SQL statements, ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id521625698186867">myDatabase.CloseDatabase()</paragraph> + </pycode> + + <h2 id="hd_id771615147491563">Accessing Databases with the UI Service</h2> + <paragraph role="paragraph" id="par_id901599408410712" xml-lang="en-US">It is also possible to access the database associated with a Base document using the <link href="text/sbasic/shared/03/sf_ui.xhp" name="UI Service"><literal>ScriptForge.UI</literal></link> service, as shown in the examples below:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id1001599408773502">Dim myDoc As Object, myDatabase As Object, ui As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631599408779968">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801599408784337">Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")</paragraph> + <paragraph role="bascode" id="bas_id631615147843278">' User and password are supplied below, if needed</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741599408788321">Set myDatabase = myDoc.GetDatabase()</paragraph> + <paragraph role="bascode" id="bas_id921599408791887">' Run queries, SQL statements, ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id971625699354855">myDatabase.CloseDatabase()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251599408799447">myDoc.CloseDocument()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id881625699438103">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111625699438354">doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")</paragraph> + <paragraph role="pycode" id="pyc_id731625699527917"># User and password are supplied below, if needed</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741625699438527">myDatabase = doc.GetDatabase()</paragraph> + <paragraph role="pycode" id="pyc_id201625699438702"># Run queries, SQL statements, ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id171625699438887">myDatabase.CloseDatabase()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231625699570502">doc.CloseDocument()</paragraph> + </pycode> + <tip id="par_id361619188184750">The <link href="text/sbasic/shared/03/sf_base.xhp#GetDatabase" name="GetDatabase method">GetDatabase</link> method used in the example above is part of ScriptForge's <literal>Base</literal> service.</tip> + + <bookmark xml-lang="en-US" branch="index" id="bm_id771615387442357" localize="false"> + <bookmark_value>Database Service;Queries</bookmark_value> + <bookmark_value>Database Service;Tables</bookmark_value> + </bookmark> + <h2 id="hd_id841587913266618" xml-lang="en-US">Properties</h2> + <table id="tab_id291587913266435"> + <tablerow> + <tablecell> + <paragraph id="par_id521587913266568" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587913266368" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631587914939732" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951587913266220" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266162" role="tablecontent" xml-lang="en-US" localize="false">Queries</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266754" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989890" role="tablecontent" xml-lang="en-US">Array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266349" role="tablecontent" xml-lang="en-US">The list of stored queries.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id851599409717318" role="tablecontent" xml-lang="en-US" localize="false">Tables</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id931599409717463" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71599409717945" role="tablecontent" xml-lang="en-US">Array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id341599409717612" role="tablecontent" xml-lang="en-US">The list of stored tables.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id561599409777730" role="tablecontent" xml-lang="en-US" localize="false">XConnection</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741599409777967" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id101599409777906" role="tablecontent" xml-lang="en-US" localize="false"><link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sdbc_1_1XConnection.html" name="XConnection API">XConnection</link></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id551599409777759" role="tablecontent" xml-lang="en-US">The UNO object representing the current database connection.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id361599409887831" role="tablecontent" xml-lang="en-US" localize="false">XMetaData</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271599409887585" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701599409887579" role="tablecontent" xml-lang="en-US" localize="false"><link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sdbc_1_1XDatabaseMetaData.html" name="XDatabaseMetaData API">XDatabaseMetaData</link></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861599409887284" role="tablecontent" xml-lang="en-US">The UNO object representing the metadata describing the database system attributes.</paragraph> + </tablecell> + </tablerow> + </table> + +<table id="tab_id551614360519973"> + <tablerow> + <tablecell colspan="3"> + <paragraph id="par_id231614360519973" role="tablehead">List of Methods in the Database Service</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id611614360519255" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_database.xhp#CloseDatabase" name="CloseDatabase">CloseDatabase</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#DFunctions" name="DAvg">DAvg</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#DFunctions" name="DCount">DCount</link> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611614360519104" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_database.xhp#DFunctions" name="DMin">DMin</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#DFunctions" name="DMax">DMax</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#DFunctions" name="DSum">DSum</link> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611614360518452" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_database.xhp#DLookup" name="DLookup">DLookup</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#GetRows" name="GetRows">GetRows</link><br/> + <link href="text/sbasic/shared/03/sf_database.xhp#RunSql" name="RunSql">RunSql</link> + </paragraph> + </tablecell> + </tablerow> +</table> + +<section id="CloseDatabase"> + <comment> CloseDatabase ---------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id991587913266189"> + <bookmark_value>Database Service;CloseDatabase</bookmark_value> + </bookmark> + <h2 id="hd_id76158791326673" localize="false">CloseDatabase</h2> + <paragraph role="paragraph" id="par_id201587913266596">Closes the current database connection.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821625699786747"> + <input>db.CloseDatabase()</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191625699910447">myDatabase.CloseDatabase() ' Basic</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id591625699936578">myDatabase.CloseDatabase() # Python</paragraph> + </pycode> +</section> + +<section id="DFunctions"> + <comment> DFunctions ----------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id861599488343584"> + <bookmark_value>Database Service;DAvg</bookmark_value> + </bookmark> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id221599488343636"> + <bookmark_value>Database Service;DCount</bookmark_value> + </bookmark> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261599488343619"> + <bookmark_value>Database Service;DMax</bookmark_value> + </bookmark> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231599488343876"> + <bookmark_value>Database Service;DMin</bookmark_value> + </bookmark> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id831599488343138"> + <bookmark_value>Database Service;DSum</bookmark_value> + </bookmark> + <h2 id="hd_id281596554849363" localize="false">DAvg, DCount, DMin, DMax, DSum</h2> + <paragraph role="paragraph" id="par_id13159655484952">Computes the given aggregate function on a field or expression belonging to a table.</paragraph> + <paragraph role="paragraph" id="par_id101615148468548">Optionally, a SQL <literal>WHERE</literal> clause can be specified as a filter that will be applied prior to the aggregate function.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id481625700732942"> + <input>db.DAvg(expression: str, tablename: str, [criteria: str]): any</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id481625700732113"> + <input>db.DCount(expression: str, tablename: str, [criteria: str]): any</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id481625700730298"> + <input>db.DMin(expression: str, tablename: str, [criteria: str]): any</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id481625700720177"> + <input>db.DMax(expression: str, tablename: str, [criteria: str]): any</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id481625700731179"> + <input>db.DSum(expression: str, tablename: str, [criteria: str]): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441596554849949"><emph>expression</emph>: A SQL expression in which the field names are surrounded with square brackets.</paragraph> + <paragraph role="paragraph" id="par_id381596554849698" xml-lang="en-US"><emph>tablename</emph>: A table name (without square brackets).</paragraph> + <paragraph role="paragraph" id="par_id521596554849185" xml-lang="en-US"><emph>criteria</emph>: A <literal>WHERE</literal> clause without the "WHERE" keyword, in which field names are surrounded with square brackets.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id781615150306678">The example below assumes the file <literal>Employees.odb</literal> has a table named <literal>EmployeeData</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id921596554849612">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561615149909875">Dim myDB as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211615149928005">Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")</paragraph> + <paragraph role="bascode" id="bas_id871615150277916">' Counts the number of employees in the table</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31615149929509">MsgBox myDB.DCount("[ID]", "EmployeeData")</paragraph> + <paragraph role="bascode" id="bas_id291615150373387">' Returns the sum of all salaries in the table</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881615150162528">MsgBox myDB.DSum("[Salary]", "EmployeeData")</paragraph> + <paragraph role="bascode" id="bas_id931615150423062">' Below are some examples of how tables can be filtered</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241615149929870">MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241615149929145">MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311615150740276">MsgBox myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id641625700473857">myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id611625700474124">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991625700474287">bas.MsgBox(myDB.DCount("[ID]", "EmployeeData"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321625700474470">bas.MsgBox(myDB.DSum("[Salary]", "EmployeeData"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811625700474663">bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id421625700474895">bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441625700475239">bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'"))</paragraph> + </pycode> +</section> + +<section id="DLookup"> + <comment> DLookup -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id161599488113736"> + <bookmark_value>Database Service;DLookup</bookmark_value> + </bookmark> + <h2 id="hd_id151599488113565" localize="false">DLookup</h2> + <paragraph role="paragraph" id="par_id41599488113961">Computes a SQL expression on a single record returned by a <literal>WHERE</literal> clause defined by the <literal>Criteria</literal> parameter.</paragraph> + <paragraph role="paragraph" id="par_id601615381471954">If the query returns multiple records, only the first one is considered. Use the <literal>OrderClause</literal> parameter to determine how query results are sorted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id41625701240138"> + <input>db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id671599488113986"><emph>expression</emph>: A SQL expression in which the field names are surrounded with square brackets.</paragraph> + <paragraph role="paragraph" id="par_id441599488113247" xml-lang="en-US"><emph>tablename</emph>: A table name (without square brackets).</paragraph> + <paragraph role="paragraph" id="par_id40159948811316" xml-lang="en-US"><emph>criteria</emph>: A <literal>WHERE</literal> clause without the "WHERE" keyword, in which field names are surrounded with square brackets.</paragraph> + <paragraph role="paragraph" id="par_id71599488689029" xml-lang="en-US"><emph>orderclause</emph>: An <literal>ORDER BY</literal> clause without the "ORDER BY" keywords. Field names should be surrounded with square brackets.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id311599488264597">MsgBox myDB.DLookup("[FirstName]", "EmployeeData", Criteria := "[LastName] LIKE 'Smith'", OrderClause := "[FirstName] DESC")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311599488113597">MsgBox myDB.DLookup("[Salary]", "EmployeeData", Criteria := "[ID] = '3'")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21599488808504">MsgBox myDB.DLookup("[Quantity] * [Value]", "Sales", Criteria := "[SaleID] = '5014'")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id151625701420880">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181625701421328">bas.MsgBox(myDB.DLookup("[FirstName]", "EmployeeData", criteria = "[LastName] LIKE 'Smith'", orderclause = "[FirstName] DESC"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801625701421784">bas.MsgBox(myDB.DLookup("[Salary]", "EmployeeData", criteria = "[ID] = '3'"))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id551625701422176">bas.MsgBox(myDB.DLookup("[Quantity] * [Value]", "Sales", criteria = "[SaleID] = '5014'"))</paragraph> + </pycode> +</section> + +<section id="GetRows"> + <comment> GetRows ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id91599489278645"> + <bookmark_value>Database Service;GetRows</bookmark_value> + </bookmark> + <h2 id="hd_id79159948927847" localize="false">GetRows</h2> + <paragraph role="paragraph" id="par_id481599489278579">Stores the contents of a table or the results of a <literal>SELECT</literal> query or of an SQL statement in a two-dimensional array. The first index in the array corresponds to the rows and the second index refers to the columns.</paragraph> + <paragraph role="paragraph" id="par_id821615384762425">An upper limit can be specified to the number of returned rows. Optionally column names may be inserted in the first row of the array.</paragraph> + <paragraph role="paragraph" id="par_id271599490209915" xml-lang="en-US">The returned array will be empty if no rows are returned and the column headers are not required.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id121625701537873"> + <input>db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451599489278429"><emph>sqlcommand</emph>: A table or query name (without square brackets) or a <literal>SELECT</literal> SQL statement.</paragraph> + <paragraph role="paragraph" id="par_id271599489278141" xml-lang="en-US"><emph>directsql</emph>: When <literal>True</literal>, the SQL command is sent to the database engine without pre-analysis. Default is <literal>False</literal>. This argument is ignored for tables. For queries, the applied option is the one set when the query was defined.</paragraph> + <paragraph role="paragraph" id="par_id941599489278747" xml-lang="en-US"><emph>header</emph>: When <literal>True</literal>, the first row of the returned array contains the column headers.</paragraph> + <paragraph role="paragraph" id="par_id591599489278926" xml-lang="en-US"><emph>maxrows</emph>: The maximum number of rows to return. The default is zero, meaning there is no limit to the number of returned rows.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id721615385125947">Below are a few examples of how the <literal>GetRows</literal> method can be used:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id821599489278193">Dim queryResults as Variant</paragraph> + <paragraph role="bascode" id="bas_id171615385196045">' Returns all rows in the table with column headers</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261599489278488">queryResults = myDB.GetRows("EmployeeData", Header := True)</paragraph> + <paragraph role="bascode" id="bas_id371615385230721">' Returns the first 50 employee records ordered by the 'FirstName' field</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871615385264078">queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id41625701996174">queryResults = myDB.GetRows("EmployeeData", header = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871625701996504">queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)</paragraph> + </pycode> +</section> + +<section id="RunSql"> + <comment> RunSql -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781599490609499"> + <bookmark_value>Database Service;RunSql</bookmark_value> + </bookmark> + <h2 id="hd_id80159949060917" localize="false">RunSql</h2> + <paragraph role="paragraph" id="par_id31599490609759">Executes an action query of an SQL statement such as creating a table, as well as inserting, updating and deleting records.</paragraph> + <paragraph role="paragraph" id="par_id331615385491925">The method returns <literal>True</literal> when successful.</paragraph> + <tip id="par_id21599490810021" xml-lang="en-US">The <literal>RunSql</literal> method is rejected with an error message in case the database was previously opened in read-only mode.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id421625701780046"> + <input>db.RunSql(sqlcommand: str, directsql: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id701599490609473"><emph>sqlcommand</emph>: A query name (without square brackets) or a SQL statement.</paragraph> + <paragraph role="paragraph" id="par_id51599490609377" xml-lang="en-US"><emph>directsql</emph>: When <literal>True</literal>, the SQL command is sent to the database engine without pre-analysis. (Default = <literal>False</literal>). For queries, the applied option is the one set when the query was defined.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id47159949060973">myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id331625701876367">myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + <embed href="text/sbasic/shared/03/sf_form.xhp#FormService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_dialog.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_dialog.xhp new file mode 100644 index 000000000..8f9f755c1 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_dialog.xhp @@ -0,0 +1,681 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Dialog" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDialogs.Dialog service</title> + <filename>/text/sbasic/shared/03/sf_dialog.xhp</filename> + </topic> + </meta> +<body> +<section id="SFDocuments-sf_Dialog"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>Dialog service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="dlg_h1"><link href="text/sbasic/shared/03/sf_dialog.xhp" name="SFDialogs.Dialog"><literal>SFDialogs</literal>.<literal>Dialog</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id931583589764919" xml-lang="en-US">The <literal>Dialog</literal> service contributes to the management of dialogs created with the Basic <link href="text/sbasic/guide/create_dialog.xhp" name="Dialog Editor">Dialog Editor</link>. Each instance of the current class represents a single dialog box displayed to the user.</paragraph> +</section> + <tip id="par_id831598110550771" xml-lang="en-US">A dialog box can be displayed in modal or in non-modal modes.</tip> + <paragraph role="paragraph" id="par_id221598110444025" xml-lang="en-US">In modal mode, the box is displayed and the execution of the macro process is suspended until one of the OK or Cancel buttons is pressed. In the meantime, user actions executed on the box can trigger specific actions.</paragraph> + <paragraph role="paragraph" id="par_id981598110463521" xml-lang="en-US">In non-modal mode, the dialog box is "floating" on the user desktop and the execution of the macro process continues normally. A non-modal dialog closes when it is terminated with the <literal>Terminate()</literal> method or when the %PRODUCTNAME session ends. The window close button is inactive in non-modal dialogs.</paragraph> + <paragraph role="paragraph" id="par_id721598110472337" xml-lang="en-US">A dialog box disappears from memory after its explicit termination.</paragraph> + <tip id="par_id891598188164936" xml-lang="en-US">The <literal>SFDialogs.Dialog</literal> service is closely related to the <literal>SFDialogs.DialogControl</literal> service.</tip> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation and usage</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Dialog</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id361598174756160" xml-lang="en-US">The <literal>Dialog</literal> service is invoked through the <literal>CreateScriptService</literal> method. It requires three positional arguments to specify the dialog box to activate:</paragraph> + <paragraph role="paragraph" id="par_id31612271944733"><emph>Container</emph>: "<link href="text/sbasic/shared/03131900.xhp" name="GlobalScope specifier"><literal>GlobalScope</literal></link>" for preinstalled libraries or a window name as defined by <link href="text/sbasic/shared/03/sf_ui.xhp" name="ScriptForge.UI"><literal>ScriptForge.UI</literal></link> service. Empty string "" default value stands for the current document.</paragraph> + <paragraph role="paragraph" id="par_id311612271947124"><emph>Library</emph>: The case-sensitive name of a library contained in the container. Default value is "Standard".</paragraph> + <paragraph role="paragraph" id="par_id821612271946316"><emph>DialogName</emph>: A case-sensitive string designating the dialog.</paragraph> + <paragraph role="paragraph" id="par_id761620142701399">Below %PRODUCTNAME Basic and Python examples are displaying the <literal>dlgConsole</literal> dialog that belongs to <literal>ScriptForge</literal> shared library:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471598171198389">Dim oDlg As Object, lButton As Long</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611598171572062">Dim Container As String, Library As String, DialogName As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571598171205739">Set oDlg = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgConsole")</paragraph> + <paragraph role="bascode" id="bas_id321598171269873">'... controls initialization goes here...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991598171277414">lButton = oDlg.Execute()</paragraph> + <paragraph role="bascode" id="bas_id471598176518738">'Default mode = Modal</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271598171282891">If lButton = oDlg.OKBUTTON Then</paragraph> + <paragraph role="bascode" id="bas_id551598171288547">'... Process controls and do what is needed here</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741598171294507">End If</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591598171300285">oDlg.Terminate()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id601619622310089">Or using Python:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id81619619964621">dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id41619622700314"># ... controls initialization goes here...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661619619964814">rc = dlg.Execute()</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id661611699964814"># Default mode is Modal</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id711619619964997">if rc == dlg.OKBUTTON:</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id681619619965191"> # ... Process controls and do what is needed here</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821619619965373">dlg.Terminate()</paragraph> + </pycode> + + <paragraph role="paragraph" id="par_id951598174966322" xml-lang="en-US">Alternatively a <literal>Dialog</literal> instance can be retrieved via the <literal>SFDialogs.DialogEvent</literal> service, providing that the dialog was initiated with the <literal>Dialog</literal> service. <literal>DialogEvent</literal> returns the <literal>SFDialogs.Dialog</literal> service instance that triggered the event.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471620305309968">Sub SomeEvent(ByRef poEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781598175253859"> Dim oDlg As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598175248581"> Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421598175139021">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id741619625211462">with Python:</paragraph> + <pycode> + <paragraph role="pycode" id="pyc_id221620305385871" localize="false">def some_event(event: uno):</paragraph> + <paragraph role="pycode" id="pyc_id661819619965191" localize="false"> dlg = CreateScriptService("SFDialogs.DialogEvent", event)</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id251598176312571" xml-lang="en-US">Note that in previous examples, the prefix <literal>"SFDialogs."</literal> may be omitted when deemed appropriate.</paragraph> + + <h2 id="hd_id651583668365757" xml-lang="en-US">Properties</h2> + <table id="tab_id381583668386455"> + <tablerow> + <tablecell> + <paragraph id="par_id871583668386455" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491583668386455" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668474014" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401583668386455" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151583668386455" role="tablecontent" localize="false">OKBUTTON</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371583668519172" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668386455" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583668386455" role="tablecontent" xml-lang="en-US">Value = 1. An OK button was pressed.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951583839708571" role="tablecontent" localize="false">CANCELBUTTON</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541583839708548" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751583839708362" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731583839708412" role="tablecontent" xml-lang="en-US">Value = 0. A Cancel button was pressed.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511584027709311" role="tablecontent" localize="false">Caption</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761584027709516" role="tablecontent " xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491584027709825" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971584027709752" role="tablecontent" xml-lang="en-US">Specify the title of the dialog.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583839767611" role="tablecontent" localize="false">Height</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31583839767743" role="tablecontent " xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741583839767926" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839767195" role="tablecontent" xml-lang="en-US">Specify the height of the dialog box.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83158383992056" role="tablecontent" localize="false">Modal</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583839920487" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971583839920282" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451583839920858" role="tablecontent" xml-lang="en-US">Specifies if the dialog box is currently in execution in modal mode.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id751588333908795" role="tablecontent" localize="false">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571588333908716" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781588333908500" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721588333908708" role="tablecontent" xml-lang="en-US">The name of the dialog</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id251583774433989" role="tablecontent" localize="false">Page</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501583774433513" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411583774433779" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph role="paragraph" id="par_id151598177605296" xml-lang="en-US">A dialog may have several pages that can be traversed by the user step by step. The Page property of the Dialog object defines which page of the dialog is active.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731588334016220" role="tablecontent" localize="false">Visible</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271588334016191" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991588334016273" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251588334016874" role="tablecontent" xml-lang="en-US">Specify if the dialog box is visible on the desktop. By default it is not visible until the Execute() method is run and visible afterwards.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id741598177924441" role="tablecontent" localize="false">XDialogModel</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598177924437" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141598187953729"> + <bookmark_value>API;UnoControlDialogModel</bookmark_value> + </bookmark> + <paragraph id="par_id94159817792441" role="tablecontent" xml-lang="en-US" localize="true">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id191598177924897" role="tablecontent" xml-lang="en-US">The UNO object representing the dialog model. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControlModel.html" name="XControlModel interface">XControlModel</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControlDialogModel-members.html" name="css.awt.UnoControlDialogModel">UnoControlDialogModel</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801598178083859" role="tablecontent" localize="false">XDialogView</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id811598178083501" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141598187953729"> + <bookmark_value>API;UnoControlDialog</bookmark_value> + </bookmark> + <paragraph id="par_id981598178083938" role="tablecontent" xml-lang="en-US" localize="true">UNO<br />object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731598178083442" role="tablecontent" xml-lang="en-US">The UNO object representing the dialog view. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControlModel.html" name="XControl interface">XControl</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControlDialog-members.html" name="UnoControlDialog interface">UnoControlDialog</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583938767611" role="tablecontent" localize="false">Width</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31385839767743" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id147583839767926" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839717695" role="tablecontent" xml-lang="en-US">Specify the width of the dialog box.</paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="hd_id421612628828054" xml-lang="en-US">Event properties</h2> + <paragraph role="paragraph" id="par_id41612629140856" xml-lang="en-US">Returns a URI string with the reference to the script triggered by the event. Read its specification in the <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification" name="URI specification">scripting framework URI specification</link>.</paragraph> + <table id="tab_id951612628879819"> + <tablerow> + <tablecell> + <paragraph id="par_id961612628879819" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401612628879819" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id281612628879819" role="tablehead" xml-lang="en-US">Basic IDE Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id431612629836735" localize="false" role="tablecontent" xml-lang="en-US">OnFocusGained</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111612629836630" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001612629836902" role="tablecontent" xml-lang="en-US">When receiving focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id701612629836389" localize="false" role="tablecontent" xml-lang="en-US">OnFocusLost</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612629836294" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id62161262983683" role="tablecontent" xml-lang="en-US">When losing focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241612629836863" localize="false" role="tablecontent" xml-lang="en-US">OnKeyPressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81612629836634" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881612629836744" role="tablecontent" xml-lang="en-US">Key pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id201612629836996" localize="false" role="tablecontent" xml-lang="en-US">OnKeyReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591612629836830" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161612629836775" role="tablecontent" xml-lang="en-US">Key released</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id111612629836950" localize="false" role="tablecontent" xml-lang="en-US">OnMouseDragged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891612629836630" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461612629836679" role="tablecontent" xml-lang="en-US">Mouse moved while key presses</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id711612629836495" localize="false" role="tablecontent" xml-lang="en-US">OnMouseEntered</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131612629836291" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151612629836151" role="tablecontent" xml-lang="en-US">Mouse inside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id971612629836286" localize="false" role="tablecontent" xml-lang="en-US">OnMouseExited</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612629836725" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361612629836624" role="tablecontent" xml-lang="en-US">Mouse outside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721612629836537" localize="false" role="tablecontent" xml-lang="en-US">OnMouseMoved</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311612629836481" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721612629836752" role="tablecontent" xml-lang="en-US">Mouse moved</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id55161262983695" localize="false" role="tablecontent" xml-lang="en-US">OnMousePressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981612629836116" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381612629836635" role="tablecontent" xml-lang="en-US">Mouse button pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id621612629836155" localize="false" role="tablecontent" xml-lang="en-US">OnMouseReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612629836704" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id35161262983642" role="tablecontent" xml-lang="en-US">Mouse button released</paragraph> + </tablecell> + </tablerow> + </table> + <table id="tab_id891606472825856"> + <tablerow> + <tablecell><paragraph id="par_id581606472825856" role="tablehead" localize="false"></paragraph></tablecell> + <tablecell><paragraph id="par_id921606472825856" role="tablehead">Methods</paragraph></tablecell> + <tablecell><paragraph id="par_id781606472825856" role="tablehead" localize="false"></paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id381606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Activate" name="Activate method">Activate</link><br/> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Center" name="Center method">Center</link><br/> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Controls" name="Controls method">Controls</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id451606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialog.xhp#EndExecute" name="EndExecute method">EndExecute</link><br/> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Execute" name="Execute method">Execute</link><br/> + <link href="text/sbasic/shared/03/sf_dialog.xhp#GetTextsFromL10N" name="GetTextsFromL10N method">GetTextsFromL10N</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id161606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Resize" name="Resize method">Resize</link><br/> + <link href="text/sbasic/shared/03/sf_dialog.xhp#Terminate" name="Terminate method">Terminate</link><br/><br/> + </paragraph></tablecell> + </tablerow> + </table> + +<section id="Activate"> + <comment> Activate -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721583933076548"> + <bookmark_value>Dialog service;Activate</bookmark_value> + </bookmark> + <h2 id="hd_id681583933076692" localize="false">Activate</h2> + <paragraph role="paragraph" id="par_id871583933076448">Set the focus on the current <literal>Dialog</literal> instance. Return <literal>True</literal> if focusing was successful.</paragraph> + <paragraph role="paragraph" id="par_id151598178880227" xml-lang="en-US">This method is called from a dialog or control event, or when a dialog is displayed in non-modal mode.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id581619625572111"><input>svc.Activate(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221598179105596">Dim oDlg As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171598179111121">Set oDlg = CreateScriptService(,, "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681598179123436">oDlg.Execute()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371598179128761">' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361598179135096">oDlg.Activate()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id811620109056270">Python and %PRODUCTNAME Basic examples both assume that the dialog is stored in current document's <literal>Standard</literal> library.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761619626867424">dlg = CreateScriptService(,,'myDialog')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111619626868945">dlg.Execute()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781620108954143"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391619626869458">dlg.Activate()</paragraph> + </pycode> +</section> + +<section id="Center"> + <comment> Center -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584541257826"> + <bookmark_value>Dialog service;Center</bookmark_value> + </bookmark> + <h2 id="hd_id95518454125767" localize="false">Center</h2> + <paragraph role="paragraph" id="par_id391651225506119">Centers the current dialog instance in the middle of a parent window. Without arguments, the method centers the dialog in the middle of the current window.</paragraph> + <paragraph role="paragraph" id="par_id391651552206119">Returns <literal>True</literal> when successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id81619265753895"><input>svc.Center(opt Parent: obj): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001585441257789"><emph>Parent</emph>: An optional object that can be either …</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id412598177970993" role="listitem" xml-lang="en-US">a ScriptForge dialog object</paragraph> + </listitem> + <listitem> + <paragraph id="par_id81591858229301" role="listitem" xml-lang="en-US">a ScriptForge document (Calc, Base, ...) object</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id591651232045794">Sub TriggerEvent(oEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id15159958185478904"> Dim oDialog1 As Object, oDialog2 As Object, lExec As Long</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id12598185484092"> Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' The dialog that caused the event</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id641598184589492"> Set oDialog2 = CreateScriptService("Dialog", ...) ' Open a second dialog</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598185491593"> oDialog2.Center(oDialog1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981651231801683"> lExec = oDialog2.Execute()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841651231804826"> Select Case lExec</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501651231990722"> ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101651232400516">End Sub</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21651232676628">def triggerEvent(event: uno):</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id351619267575732"> dlg1 = CreateScriptService('DialogEvent.Dialog', event) # The dialog having caused the event</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id431619267576082"> dlg2 = CreateScriptService('Dialog', ...) # Open a second dialog</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141651235460258"> dlg2.Center(dlg1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131619267576307"> rc = dlg2.Execute()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991651233319117"> if rc is False:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id691651233365005"> # ...</paragraph> + </pycode> +</section> + +<section id="Controls"> + <comment> Controls -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584541257826"> + <bookmark_value>Dialog service;Controls</bookmark_value> + </bookmark> + <h2 id="hd_id95158454125767" localize="false">Controls</h2> + <paragraph role="paragraph" id="par_id161584541257982">Return either:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id421598179770993" role="listitem" xml-lang="en-US">the list of the controls contained in the dialog</paragraph> + </listitem> + <listitem> + <paragraph id="par_id81598185229301" role="listitem" xml-lang="en-US">a <literal>DialogControl</literal> class instance based on its name</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id81619625753895"><input>svc.Controls(): str[0..*]</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id61819625753598"><input>svc.Controls(controlname: str): svc</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257789"><emph>ControlName</emph> : A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id151598185478904">Dim myDialog As Object, myList As Variant, myControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21598185484092">Set myDialog = CreateScriptService("SFDialogs.Dialog", , "Standard", "Dialog1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641598185489492">myList = myDialog.Controls()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598185495193">Set myControl = myDialog.Controls("myTextBox")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id351619627575732">dlg = CreateScriptService('SFDialogs.Dialog','', 'Standard', 'Dialog1')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id431619627576082">ctrls = dlg.Controls()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131619627576307">ctrl = dlg.Controls('myTextBox')</paragraph> + </pycode> +</section> + +<section id="EndExecute"> + <comment> EndExecute -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171598185776261"> + <bookmark_value>Dialog service;EndExecute</bookmark_value> + </bookmark> + <h2 id="hd_id491598185776436" localize="false">EndExecute</h2> + <paragraph role="paragraph" id="par_id381598185776500">Ends the display of a modal dialog and gives back the argument as return value for the current <literal>Execute()</literal> running action.</paragraph> + <paragraph role="paragraph" id="par_id551598185953362"><literal>EndExecute()</literal> is usually contained in the processing of a macro triggered by a dialog or control event.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id451619627879243"><input>svc.EndExecute(returnvalue: int)</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451598185776957"><emph>returnvalue</emph>: The value passed to the running <literal>Execute()</literal> method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id411620110780170">Using %PRODUCTNAME Basic:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id521598186134426">Sub OnEvent(poEvent As com.sun.star.lang.EventObject)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631598186139835"> Dim oDlg As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251598186144483"> Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191598186150509"> oDlg.EndExecute(ReturnValue := 25)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91598186155632">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id11620110819754">Using Python:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id231619627971450">from com.sun.star.lang import EventObject</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id71619627976171">def on_event(event: EventObject):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621619627976387"> dlg = CreateScriptService("SFDialogs.DialogEvent", event)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id191619627976590"> dlg.EndExecute(25)</paragraph> + </pycode> + <tip id="par_id81620201915101">Above <link href="https://api.libreoffice.org/docs/idl/ref/structcom_1_1sun_1_1star_1_1lang_1_1EventObject.html" name="com.sun.star.lang.EventObject">com.sun.star.lang.EventObject</link> mentions are optional. Such annotations help identify %PRODUCTNAME Application Programming Interface (API).</tip> +</section> + +<section id="Execute"> + <comment> Execute -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id351598186461621"> + <bookmark_value>Dialog service;Execute</bookmark_value></bookmark> + <h2 id="hd_id531598186461915" localize="false">Execute</h2> + <paragraph role="paragraph" id="par_id29159818646178">Display the dialog box and, when modal, wait for its termination by the user. The returned value is either:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id541598186676277" role="listitem" xml-lang="en-US">0 : <literal>Cancel</literal> button pressed</paragraph> + </listitem> + <listitem> + <paragraph id="par_id821598186716345" role="listitem" xml-lang="en-US">1 : <literal>OK</literal> button pressed</paragraph> + </listitem> + <listitem> + <paragraph id="par_id951598186738346" role="listitem" xml-lang="en-US">Otherwise the dialog stopped with an <literal>EndExecute()</literal> statement issued by a dialog or control event</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id741598187335869" xml-lang="en-US">For non-modal dialog boxes the method always returns 0 and the execution of the macro continues.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id291619628195418"><input>svc.Execute(modal: bool = True): int</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id11598186461227"><emph>modal</emph>: <literal>False</literal> when non-modal dialog. Default = <literal>True</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id231620110023843">In this Basic example <literal>myDialog</literal> dialog is stored in current document's <literal>Standard</literal> library.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id591598186461923">Dim oDlg As Object, lReturn As Long</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681598186461370">Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281598186461514">lReturn = oDlg.Execute(Modal := False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291598186461410">Select Case lReturn</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741598187182079"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781612273203518">End Select</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id191620110162627">This Python code displays <literal>DlgConvert</literal> modal dialog from <literal>Euro</literal> shared Basic library.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id541619628291899">dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121619628292915">rc = dlg.Execute()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211620109965604">if rc == dlg.CANCELBUTTON:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id61620109984292"> # ...</paragraph> + </pycode> +</section> + +<section id="GetTextsFromL10N"> + <comment> GetTextsFromL10N -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141598187953209"> + <bookmark_value>Dialog service;GetTextsFromL10N</bookmark_value> + </bookmark> + <h2 id="hd_id101598187950391" localize="false">GetTextsFromL10N</h2> + <paragraph role="paragraph" id="par_id21598187900349">Replaces all fixed text strings in a dialog by their translated versions based on a <literal>L10N</literal> service instance. This method translates the following strings:</paragraph> + <embed href="text/sbasic/shared/03/sf_l10n.xhp#L10NDlgControls"/> + <paragraph role="paragraph" id="par_id641625855723650">The method returns <literal>True</literal> if successful.</paragraph> + <paragraph role="paragraph" id="par_id61637871260604">To create a list of translatable strings in a dialog use the <link href="text/sbasic/shared/03/sf_l10n.xhp#AddTextsFromDialog" name="AddTextsFromDialog">AddTextsFromDialog</link> method from the L10N service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id171619628383909"> + <input>svc.GetTextsFromL10N(l10n: svc): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451598185776205"><emph>l10n</emph>: A <literal>L10N</literal> service instance from which translated strings will be retrieved.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id951620300689850">The following example loads translated strings and applies them to the dialog "MyDialog".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id971620301083254">oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981620301085205">myPO = CreateScriptService("L10N", "/home/user/po_files/")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916203010852399">oDlg.GetTextsFromL10N(myPO)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121598187953341">oDlg.Execute()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id491620303073122">dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841620302327011">myPO = CreateScriptService("L10N", "/home/user/po_files/")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381620302328388">dlg.GetTextsFromL10N(myPO)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251620302328896">dlg.Execute()</paragraph> + </pycode> + <tip id="par_id901637872163895">Read the <link href="text/sbasic/shared/03/sf_l10n.xhp" name="L10N">L10N service</link> help page to learn more about how PO and POT files are handled.</tip> +</section> + +<section id="Resize"> + <comment> Resize -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141598187953729"> + <bookmark_value>Dialog service;Resize</bookmark_value> + </bookmark> + <h2 id="hd_id101598187953210" localize="false">Resize</h2> + <paragraph role="paragraph" id="par_id21598187953697">Moves the topleft corner of a dialog to new coordinates and/or modify its dimensions. All distances are expressed in 1/100 mm. Without arguments, the method resets the initial dimensions. Return <literal>True</literal> if the resize was successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711619628389339"><input>svc.Resize(opt Left: num, opt Top: num, opt Width: num, opt Height: num): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481651236673068"><emph>Left</emph>: the horizontal distance from the top-left corner</paragraph> + <paragraph role="paragraph" id="par_id721651236674379"><emph>Top</emph>: the vertical distance from the top-left corner</paragraph> + <paragraph role="paragraph" id="par_id991651236674995"><emph>Width</emph>: the width of the rectangle containing the dialog</paragraph> + <paragraph role="paragraph" id="par_id771651236675564"><emph>Height</emph>: the height of the rectangle containing the dialog</paragraph> + <paragraph role="paragraph" id="par_id211651236676180">Negative or missing arguments are left unchanged</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" xml-lang="en-US" id="bas_id791620301085031">oDialog.Resize(1000, 2000, Height := 6000) ' Width is not changed</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id181620112217958">With Python:</paragraph> + <pycode> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id941620303073866">oDialog.Resize(1000, 2000, Height = 6000) # Width is not changed</paragraph> + </pycode> +</section> + +<section id="Terminate"> + <comment> Terminate -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141598187953729"> + <bookmark_value>Dialog service;Terminate</bookmark_value> + </bookmark> + <h2 id="hd_id101598187953201" localize="false">Terminate</h2> + <paragraph role="paragraph" id="par_id21598187953679">Terminate the <literal>Dialog</literal> service for the current instance. Return <literal>True</literal> if the termination was successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id171619628389339"><input>svc.Terminate(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id951620300687150">Below Basic and Python examples open <literal>DlgConsole</literal> and <literal>dlgTrace</literal> non-modal dialogs. They are respectively stored in <literal>ScriptForge</literal> and <literal>Access2Base</literal> shared libraries. Dialog close buttons are disabled and explicit termination is performed at the end of a running process.</paragraph> + <paragraph role="paragraph" id="par_id301620302137482">In this example a button in <literal>DlgConsole</literal> is substituting inhibited window closing:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id971620301085031">oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981620301085983">oDlg.Execute(modal:=False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91620301085248">Wait 5000</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121598187953168">oDlg.Terminate()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id811620112217958">With Python:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> +<pycode> + <paragraph role="pycode" localize="false" id="pyc_id491620303073866">from time import sleep</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841620302327611">dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381620302328144">dlg.Execute(modal=False)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251620302328330">sleep 5</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101620302328498">dlg.Terminate()</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#ctrls_h1"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_dialogcontrol.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_dialogcontrol.xhp new file mode 100644 index 000000000..59bb03085 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_dialogcontrol.xhp @@ -0,0 +1,1273 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_DialogControl" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDialogs.DialogControl service</title> + <filename>/text/sbasic/shared/03/sf_dialogcontrol.xhp</filename> + </topic> + </meta> +<body> +<section id="abstract"> + <bookmark localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>DialogControl service</bookmark_value> + </bookmark> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="ctrls_h1"><link href="text/sbasic/shared/03/sf_dialogcontrol.xhp" name="SFDialogs.DialogControl service"><literal>SFDialogs</literal>.<literal>DialogControl</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id931583589764919" xml-lang="en-US">The <literal>DialogControl</literal> service manages the controls belonging to a dialog defined with the Basic <link href="text/sbasic/guide/create_dialog.xhp" name="Dialog Editor">Dialog Editor</link>. Each instance of the current service represents a single control within a dialog box.</paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id331612167249331" localize="false"> + <bookmark_value>API;awt.XControl</bookmark_value> + <bookmark_value>API;awt.XControlModel</bookmark_value> + </bookmark> + <paragraph role="paragraph" id="par_id701598191157426" xml-lang="en-US">The focus is set on getting and setting the values displayed by the controls of the dialog box. Formatting is accessible via the <literal>XControlModel</literal> and <literal>XControlView</literal> properties.</paragraph> + <paragraph role="paragraph" id="par_id981598191184526" xml-lang="en-US">Note that the unique <literal>DialogControl.Value</literal> property content varies according to the control type.</paragraph> + <paragraph role="paragraph" id="par_id991612698027551" xml-lang="en-US">A special attention is given to controls of type tree control. It is easy to populate a tree, either branch by branch, or with a set of branches at once. Populating a tree control can be performed statically or dynamically.</paragraph> +</section> + <tip id="par_id891598188164936" xml-lang="en-US">The <literal>SFDialogs.DialogControl</literal> service is closely related to the <link href="text/sbasic/shared/03/sf_dialog.xhp" name="Dialog service"><literal>SFDialogs.Dialog</literal></link> service.</tip> + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>DialogControl</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id361598174756160" xml-lang="en-US">The <literal>DialogControl</literal> service is invoked from an existing <literal>Dialog</literal> service instance through its <literal>Controls()</literal> method. The dialog must be initiated with the <literal>SFDialogs.Dialog</literal> service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791598453192421">Dim myDialog As Object, myControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251598453197473">Set myDialog = CreateScriptService("SFDialogs.Dialog", "GlobalScope", myLibrary, DialogName)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421598453203458">Set myControl = myDialog.Controls("myTextBox")</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id581598453210170">myControl.Value = "Dialog started at " & Now()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11598453215943">myDialog.Execute()</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id961598453222539">' ... process the controls actual values</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981598453230245">myDialog.Terminate()</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id481026225234594">from time import localtime, strftime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481620225234594">dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', lib_name, dlg_name)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811620225234785">text = dlg.Controls('myTextBox')</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id861620225235002">text.Value = "Dialog started at " + strftime("%a, %d %b %Y %H:%M:%S", localtime())</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361620225235185">dlg.Execute()</paragraph> + <paragraph role="pycode" xml-lang="en-US" id="pyc_id841620225235377"># ... process the controls actual values</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411620225235569">dlg.Terminate()</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id951598174966322" xml-lang="en-US">Alternatively a control instance can be retrieved via the <literal>SFDialogs.DialogEvent</literal> service, providing the dialog was initiated with the <literal>Dialog</literal> service. <literal>DialogEvent</literal> returns the <literal>SFDialogs.DialogControl</literal> class instance that triggered the event.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id311598175259794">Sub SomeEvent(ByRef poEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781598175253859"> Dim oControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598175248581"> Set oControl = CreateScriptService("SFDialogs.DialogEvent", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711598175146308"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421598175139021">End Sub</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id921620228762243">def some_event(event: uno):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181620228763531"> ctrl = CreateScriptService('SFDialogs.DialogEvent', event)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id731620228763715"> # ...</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id251598176312571" xml-lang="en-US">Note that in previous examples, the prefix <literal>"SFDialogs."</literal> may be omitted.</paragraph> + <h2 id="hd_id71598455687512" xml-lang="en-US">Control types</h2> + <paragraph role="paragraph" id="par_id851598455863395" xml-lang="en-US">The <literal>DialogControl</literal> service is available for these control types:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id121598455880500" localize="false" role="listitem">Button</paragraph> + </listitem> + <listitem> + <paragraph id="par_id441598455934376" localize="false" role="listitem">CheckBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id471598455940400" localize="false" role="listitem">ComboBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id181598455945642" localize="false" role="listitem">CurrencyField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id181598455949653" localize="false" role="listitem">DateField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id541598455953714" localize="false" role="listitem">FileControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id441598455957858" localize="false" role="listitem">FixedLine</paragraph> + </listitem> + <listitem> + <paragraph id="par_id971598455961404" localize="false" role="listitem">FixedText</paragraph> + </listitem> + <listitem> + <paragraph id="par_id721598455965612" localize="false" role="listitem">FormattedField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id291598455969826" localize="false" role="listitem">GroupBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id861598455974724" localize="false" role="listitem">ImageControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851598455979572" localize="false" role="listitem">ListBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id321598455984243" localize="false" role="listitem">NumericField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981598455990524" localize="false" role="listitem">PatternField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id991598455998589" localize="false" role="listitem">ProgressBar</paragraph> + </listitem> + <listitem> + <paragraph id="par_id281598456002561" localize="false" role="listitem">RadioButton</paragraph> + </listitem> + <listitem> + <paragraph id="par_id91598456007438" localize="false" role="listitem">ScrollBar</paragraph> + </listitem> + <listitem> + <paragraph id="par_id171612698897041" localize="false" role="listitem">TableControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id271598456011504" localize="false" role="listitem">TextField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id661598456015339" localize="false" role="listitem">TimeField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id171612698897514" localize="false" role="listitem">TreeControl</paragraph> + </listitem> + </list> + <h2 id="hd_id651583668365757" xml-lang="en-US">Properties</h2> + <table id="tab_id381583668386455"> + <tablerow> + <tablecell> + <paragraph id="par_id871583668386455" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491583668386455" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668474014" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291598538799794" role="tablehead" xml-lang="en-US">Applicable to</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401583668386455" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151583668386455" role="tablecontent" localize="false">Cancel</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371583668519172" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668386455" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id231598538847029" role="tablecontent" localize="false" xml-lang="en-US">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583668386455" role="tablecontent" xml-lang="en-US">Specifies if a command button has or not the behaviour of a Cancel button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951583839708571" role="tablecontent" localize="false">Caption</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541583839708548" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751583839708362" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351598538934413" role="tablecontent" localize="false">Button, CheckBox, FixedLine, FixedText, GroupBox, RadioButton</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731583839708412" role="tablecontent" xml-lang="en-US">Specifies the text associated with the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511584027709311" role="tablecontent" localize="false">ControlType</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761584027709516" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491584027709825" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261598539120502" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971584027709752" role="tablecontent" xml-lang="en-US">One of the types listed above.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id141612705482724" role="tablecontent" localize="false">CurrentNode</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67161270548283" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id341612705482566" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id51612705482172" role="tablecontent" localize="false">TreeControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001612705482919" role="tablecontent" xml-lang="en-US">The currently upmost node selected in the tree control. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1tree_1_1XMutableTreeNode.html" name="awt.tree.XMutableTreeNode">XmutableTreeNode</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583839767611" role="tablecontent" localize="false">Default</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31583839767743" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741583839767926" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71598539168348" role="tablecontent" localize="false">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839767195" role="tablecontent" xml-lang="en-US">Specifies whether a command button is the default (OK) button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83158383992056" role="tablecontent" localize="false">Enabled</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583839920487" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971583839920282" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891598539196786" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451583839920858" role="tablecontent" xml-lang="en-US">Specifies if the control is accessible with the cursor.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id751588333908795" role="tablecontent" localize="false">Format</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571588333908716" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781588333908500" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491598539231618" role="tablecontent" localize="false">DateField, TimeField, FormattedField</paragraph> + <paragraph id="par_id491598529331618" role="tablecontent" xml-lang="en-US">(read-only)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721588333908708" role="tablecontent" xml-lang="en-US">Specifies the format used to display dates and times. It must be one these strings:</paragraph> + <paragraph role="paragraph" id="par_id891598456980194" xml-lang="en-US">For dates: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD".</paragraph> + <paragraph role="paragraph" id="par_id221598456991070" xml-lang="en-US">For times: "24h short", "24h long", "12h short", "12h long".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id251583774433989" role="tablecontent" localize="false">ListCount</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501583774433513" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411583774433779" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531598539561342" role="tablecontent" localize="false">ComboBox, ListBox, TableControl</paragraph> + </tablecell> + <tablecell> + <paragraph role="paragraph" id="par_id151598177605296" xml-lang="en-US">Specifies the number of rows in a ListBox, a ComboBox or a TableControl.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731588334016220" role="tablecontent" localize="false">ListIndex</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271588334016191" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991588334016273" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598539598242" role="tablecontent" localize="false">ComboBox, ListBox, TableControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251588334016874" role="tablecontent" xml-lang="en-US">Specifies which item is selected in a ListBox, a ComboBox or a TableControl.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id451598457655392" role="tablecontent" localize="false">Locked</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961598457655506" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571598457655365" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111598539631340" role="tablecontent" localize="false">ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id2159845765568" role="tablecontent" xml-lang="en-US">Specifies if the control is read-only.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id21159845795140" role="tablecontent" localize="false">MultiSelect</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621598457951781" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311598457951281" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361598539747680" role="tablecontent" localize="false">ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821598457951782" role="tablecontent" xml-lang="en-US">Specifies whether a user can make multiple selections in a listbox.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id421598458170141" role="tablecontent" localize="false">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351598458170114" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391598458170757" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151598539764402" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621598458170392" role="tablecontent" xml-lang="en-US">The name of the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id281598458357593" role="tablecontent" localize="false">Page</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id80159845835726" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id191598458357402" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id841598539781888" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id791598458357756" role="tablecontent" xml-lang="en-US">A dialog may have several pages that can be traversed by the user step by step. The Page property of the Dialog object defines which page of the dialog is active.</paragraph> + <paragraph role="paragraph" id="par_id441598458459145" xml-lang="en-US">The Page property of a control defines the page of the dialog on which the control is visible.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id2915984585802" role="tablecontent" localize="false">Parent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161598458580581" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id921598458580608" role="tablecontent" xml-lang="en-US"><literal>Dialog</literal><br/>service</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181598539807426" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id801598458580456" role="tablecontent" xml-lang="en-US">The parent <literal>SFDialogs.Dialog</literal> class object instance.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181598458773220" role="tablecontent" localize="false">Picture</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598458773352" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471598458773993" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831598539848472" role="tablecontent" localize="false">Button, ImageControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598458773588" role="tablecontent" xml-lang="en-US">Specifies the file name containing a bitmap or other type of graphic to be displayed on the specified control. The filename must comply with the <literal>FileNaming</literal> attribute of the <literal>ScriptForge.FileSystem</literal> service.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id791612700624395" role="tablecontent" localize="false">RootNode</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831612700624650" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612700624483" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581612700624717" role="tablecontent" localize="false">TreeControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11612700624514" role="tablecontent" xml-lang="en-US">An object representing the lowest root node (usually there is only one such root node). Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1tree_1_1XMutableTreeNode.html" name="awt.tree.XMutableTreeNode">XmutableTreeNode</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id681598516577774" role="tablecontent" localize="false">RowSource</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401598516577225" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id59159851657754" role="tablecontent" localize="false">Array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131598539880024" role="tablecontent" localize="false">ComboBox, ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311598516577712" role="tablecontent" xml-lang="en-US">Specifies the data contained in a combobox or a listbox.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491598516764653" role="tablecontent" localize="false">Text</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781598516764550" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598516764696" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761598539912452" role="tablecontent" localize="false">ComboBox, FileControl, FormattedField, PatternField, TextField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11159851676440" role="tablecontent" xml-lang="en-US">Gives access to the text being displayed by the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id311598517275908" role="tablecontent" localize="false">TipText</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411598517275112" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598517275920" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id171598539985022" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651598517275384" role="tablecontent" xml-lang="en-US">Specifies the text that appears as a tooltip when you hold the mouse pointer over the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951598517418614" role="tablecontent" localize="false">TripleState</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821598517418463" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id231598517418608" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81598540007035" role="tablecontent" localize="false">CheckBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141598517418822" role="tablecontent" xml-lang="en-US">Specifies if the checkbox control may appear dimmed (grayed) or not.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31598517671415" role="tablecontent" localize="false">Value</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701598517671373" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id2159851767113" role="tablecontent" localize="false">Variant</paragraph> + </tablecell> + <tablecell></tablecell> + <tablecell> + <paragraph id="par_id1001598540024225" role="tablecontent" xml-lang="en-US">Refer to <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#hd_id81598540704978" name="Value property">Value property</link></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id571598517730264" role="tablecontent" localize="false">Visible</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661598517730941" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981598517730694" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761598540042290" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881598517730836" role="tablecontent" xml-lang="en-US">Specifies if the control is hidden or visible.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id741598177924441" role="tablecontent" localize="false">XControlModel</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598177924437" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id94159817792441" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311598540066789" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id191598177924897" role="tablecontent" xml-lang="en-US">The UNO object representing the control model. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControlModel.html" name="awt.XControlModel">XControlModel</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControlDialogModel.html)" name="awt.XControlDialogModel">UnoControlDialogModel</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801598178083859" role="tablecontent" localize="false">XControlView</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id811598178083501" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981598178083938" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id551598540079329" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731598178083442" role="tablecontent" xml-lang="en-US">The UNO object representing the control view. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControl.html" name="awt.XControl">XControl</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControlDialog.html)" name="awt.UnoControlDialog">UnoControlDialog</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id55161269944658" role="tablecontent" localize="false">XTreeDataModel</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741612699446459" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311612699446893" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id25161269944611" role="tablecontent" localize="false">TreeControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id691612699446892" role="tablecontent" xml-lang="en-US">The UNO object representing the tree control data model. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1tree_1_1XMutableTreeDataModel.html" name="awt.tree.XMutableTreeDataModel">XMutableTreeDataModel</link> in Application Programming Interface (API) documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id81598540704978" xml-lang="en-US">The <variable id="ValueProperty">Value property</variable></h2> + <table id="tab_id48159854325479"> + <tablerow> + <tablecell> + <paragraph id="par_id10159854325492" role="tablehead" xml-lang="en-US">Control type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254158" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961598543254444" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id461598543254494" role="tablecontent" localize="false">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271598543254590" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254108" role="tablecontent" xml-lang="en-US">For toggle buttons only</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id131598543254931" role="tablecontent" localize="false">CheckBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254376" role="tablecontent" xml-lang="en-US">Boolean or Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521598543254630" role="tablecontent" xml-lang="en-US">0, False: not checked<br />1, True: checked<br />2: grayed, don't know</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891598543254563" role="tablecontent" localize="false">ComboBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781598543254887" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id331598543254947" role="tablecontent" xml-lang="en-US">The selected value. The <literal>ListIndex</literal> property is an alternate option.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id58159854325446" role="tablecontent" localize="false">CurrencyField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id5159854325443" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241598543254415" role="tablecontent" localize="false">DateField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401598543254743" role="tablecontent" localize="false">Date</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id851598543254508" role="tablecontent" localize="false">FileControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731598543254544" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598543254757" role="tablecontent" xml-lang="en-US">A file name formatted in accordance with the <literal>FileNaming</literal> property of the <literal>ScriptForge.FileSystem</literal> service</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id921598543254323" role="tablecontent" localize="false">FormattedField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221598543254760" role="tablecontent" xml-lang="en-US">String or Numeric</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151598543254318" role="tablecontent" localize="false">ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id42159854325422" role="tablecontent" xml-lang="en-US">String or array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601598543254780" role="tablecontent" xml-lang="en-US">The selected row(s) as a scalar or as an array depending on the <literal>MultiSelect</literal> attribute</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771598543254973" role="tablecontent" localize="false">NumericField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461598543254909" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id38159854325480" role="tablecontent" localize="false">PatternField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81598543254625" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951598543254998" role="tablecontent" localize="false">ProgressBar</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631598543254771" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91598543254766" role="tablecontent" xml-lang="en-US">Must be within the predefined bounds</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id791598543254779" role="tablecontent" localize="false">RadioButton</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561598543254115" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id851598543254624" role="tablecontent" xml-lang="en-US">Each button has its own name. They are linked together if their TAB positions are contiguous. If a radiobutton is set to <literal>True</literal>, the other related buttons are automatically set to <literal>False</literal></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id141598543254361" role="tablecontent" localize="false">ScrollBar</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531598543254869" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21598543254994" role="tablecontent" xml-lang="en-US">Must be within the predefined bounds</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id811598543254007" role="tablecontent" localize="false">TableControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751598543254805" role="tablecontent" localize="false">Array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441598543254951" role="tablecontent" xml-lang="en-US">One-dimensional array with the data of the currently selected row.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id811598543254140" role="tablecontent" localize="false">TextField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751598543254299" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441598543254738" role="tablecontent" xml-lang="en-US">The text appearing in the field</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id89159854325478" role="tablecontent" localize="false">TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id341598543254600" role="tablecontent" localize="false">Date</paragraph> + </tablecell> + <tablecell> + </tablecell> + </tablerow> + </table> + <h2 id="hd_id421612628828054" xml-lang="en-US">Event properties</h2> + <paragraph role="paragraph" id="par_id41612629140856" xml-lang="en-US">Returns a URI string with the reference to the script triggered by the event. Read its specification in the <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification" name="URI specification">scripting framework URI specification</link>.</paragraph> + <table id="tab_id951612628879819"> + <tablerow> + <tablecell> + <paragraph id="par_id961612628879819" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401612628879819" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id281612628879819" role="tablehead" xml-lang="en-US">Description as labeled in the Basic IDE</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801612707166342" localize="false" role="tablecontent" xml-lang="en-US">OnActionPerformed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91612707166532" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612707166258" role="tablecontent" xml-lang="en-US">Execute action</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id261612707166662" localize="false" role="tablecontent" xml-lang="en-US">OnAdjustmentValueChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id79161270716675" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831612707166731" role="tablecontent" xml-lang="en-US">While adjusting</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id431612629836735" localize="false" role="tablecontent" xml-lang="en-US">OnFocusGained</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111612629836630" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001612629836902" role="tablecontent" xml-lang="en-US">When receiving focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id701612629836389" localize="false" role="tablecontent" xml-lang="en-US">OnFocusLost</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612629836294" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id62161262983683" role="tablecontent" xml-lang="en-US">When losing focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id10161270735471" localize="false" role="tablecontent" xml-lang="en-US">OnItemStateChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id51612707354544" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612707354899" role="tablecontent" xml-lang="en-US">Item status changed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241612629836863" localize="false" role="tablecontent" xml-lang="en-US">OnKeyPressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81612629836634" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881612629836744" role="tablecontent" xml-lang="en-US">Key pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id201612629836996" localize="false" role="tablecontent" xml-lang="en-US">OnKeyReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591612629836830" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161612629836775" role="tablecontent" xml-lang="en-US">Key released</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id111612629836950" localize="false" role="tablecontent" xml-lang="en-US">OnMouseDragged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891612629836630" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461612629836679" role="tablecontent" xml-lang="en-US">Mouse moved while key presses</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id711612629836495" localize="false" role="tablecontent" xml-lang="en-US">OnMouseEntered</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131612629836291" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151612629836151" role="tablecontent" xml-lang="en-US">Mouse inside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id971612629836286" localize="false" role="tablecontent" xml-lang="en-US">OnMouseExited</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612629836725" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361612629836624" role="tablecontent" xml-lang="en-US">Mouse outside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721612629836537" localize="false" role="tablecontent" xml-lang="en-US">OnMouseMoved</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311612629836481" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721612629836752" role="tablecontent" xml-lang="en-US">Mouse moved</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id55161262983695" localize="false" role="tablecontent" xml-lang="en-US">OnMousePressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981612629836116" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381612629836635" role="tablecontent" xml-lang="en-US">Mouse button pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id621612629836155" localize="false" role="tablecontent" xml-lang="en-US">OnMouseReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612629836704" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id35161262983642" role="tablecontent" xml-lang="en-US">Mouse button released</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id671612707606983" localize="false" role="tablecontent" xml-lang="en-US">OnNodeExpanded</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id851612707606863" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351612707606197" role="tablecontent" xml-lang="en-US">(Not in Basic IDE) when the expansion button is pressed on a node in a tree control</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id331612707606104" localize="false" role="tablecontent" xml-lang="en-US">OnNodeSelected</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id121612707606251" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881612707606121" role="tablecontent" xml-lang="en-US">(Not in Basic IDE) when a node in a tree control is selected</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id84161270760678" localize="false" role="tablecontent" xml-lang="en-US">OnTextChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id811612707606330" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621612707606219" role="tablecontent" xml-lang="en-US">Text modified</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id421583670049913" xml-lang="en-US">Methods</h2> + + <table id="tab_id891606472825856"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the DialogControl Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id751612709117248" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#AddSubNode" name="AddSubNode method">AddSubNode</link><br/> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#AddSubTree" name="AddSubTree method">AddSubTree</link><br/> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#CreateRoot" name="CreateRoot method">CreateRoot</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id63161270911712" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#FindNode" name="FindNode method">FindNode</link><br/> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#SetFocus" name="SetFocus method">SetFocus</link><br/><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id651612709117457" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#SetTableData" name="SetTableData method">SetTableData</link><br/> + <link href="text/sbasic/shared/03/sf_dialogcontrol.xhp#WriteLine" name="WriteLine method">WriteLine</link><br/><br/> + </paragraph></tablecell> + </tablerow> + </table> + +<section id="AddSubNode"> + <comment> AddSubNode -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id1516127118236"> + <bookmark_value>DialogControl service;AddSubNode</bookmark_value> + </bookmark> + <h2 id="hd_id791612711823914" localize="false">AddSubNode</h2> + <paragraph role="paragraph" id="par_id831612711823126">Create and return a new node of the tree control as a UNO object subordinate to a parent node. <variable id="XMutableTreeNode">Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1tree_1_1XMutableTreeNode.html" name="awt.tree.XMutableTreeNode">XMutableTreeNode</link> in Application Programming Interface (API) documentation for detailed information.</variable></paragraph> + <section id="OnNodeExpanded"> + <paragraph role="paragraph" id="par_id741612711823706" xml-lang="en-US">This method may be called before displaying the dialog box to build the initial tree. It may also be called from a dialog or control event - using the <literal>OnNodeExpanded</literal> event - to complete the tree dynamically.</paragraph> + </section> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id781620224364283"> + <input>svc.AddSubNode(parentnode: uno, displayvalue: str, opt datavalue: any): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id761612711823834"><emph>parentnode</emph>: A node UNO object, of type <literal>com.sun.star.awt.tree.XMutableTreeNode</literal>.</paragraph> + <paragraph role="paragraph" id="par_id791612711823819"><emph>displayvalue</emph>: The text appearing in the tree control box.</paragraph> + <section id="datavalue"> + <paragraph role="paragraph" id="par_id911612711823382"><emph>datavalue</emph>: Any value associated with the new node. <literal>datavalue</literal> may be a string, a number or a date. Omit the argument when not applicable.</paragraph> + </section> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id901620317110685">%PRODUCTNAME Basic and Python examples pick up current document's <literal>myDialog</literal> dialog from <literal>Standard</literal> library.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id781612711823502">Dim oDlg As Object, myTree As Object, myNode As Object, theRoot As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811612711823106">Set oDlg = CreateScriptService("Dialog",,, "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751612711823763">Set myTree = oDlg.Controls("myTreeControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31612711823423">Set theRoot = myTree.CreateRoot("Tree top")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211612712366538">Set myNode = myTree.AddSubNode(theRoot, "A branch ...")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id771620316787550">dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id511620316787792">tree = dlg.Controls('myTreeControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id291620316787950">root = tree.CreateRoot('Tree top')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201620316788142">node = tree.AddSubNode(root, 'A branch ...')</paragraph> + </pycode> +</section> + +<section id="AddSubTree"> + <comment> AddSubTree -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id481612713087784"> + <bookmark_value>DialogControl service;AddSubTree</bookmark_value> + </bookmark> + <h2 id="hd_id81161271308746" localize="false">AddSubTree</h2> + <paragraph role="paragraph" id="par_id221612713087885">Return <literal>True</literal> when a subtree, subordinate to a parent node, could be inserted successfully in a tree control. If the parent node had already child nodes before calling this method, the child nodes are erased.</paragraph> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#OnNodeExpanded"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id731620308640671"> + <input>svc.AddSubTree(parentnode: uno, flattree: any, opt withdatavalue: bool): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id781612713087722"><emph>parentnode</emph>: A node UNO object, of type <literal>com.sun.star.awt.tree.XMutableTreeNode</literal>.</paragraph> + <paragraph role="paragraph" id="par_id36161271308759"><emph>flattree</emph>: a two dimension array sorted on the columns containing the display values. Such an array can be issued by the <literal>GetRows</literal> method applied on the <literal>SFDatabases.Database</literal> service. When an array item containing the text to be displayed is <literal>Empty</literal> or <literal>Null</literal>, no new subnode is created and the remainder of the row is skipped.</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id61612716027443">Flat tree >>>> Resulting subtree</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881612716035711">A1 B1 C1 |__ A1 </paragraph> + <paragraph role="bascode" localize="false" id="bas_id221612716043100">A1 B1 C2 |__ B1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861612716050132">A1 B2 C3 |__ C1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251612716057266">A2 B3 C4 |__ C2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id316127156064145">A2 B3 C5 |__ B2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321612716075452">A3 B4 C6 |__ C3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171612716083505"> |__ A2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231612716092043"> |__ B3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id216124716100898"> |__ C4</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241612716108208"> |__ C5</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531612716115408"> |__ A3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621612716122130"> |__ B4</paragraph> + <paragraph role="bascode" localize="false" id="bas_id212612716132791"> |__ C6</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id51612713087915"><emph>withdatavalue</emph>: When <literal>False</literal> default value is used, every column of <literal>flattree</literal> contains the text to be displayed in the tree control. When <literal>True</literal>, the texts to be displayed (<literal>displayvalue</literal>) are in columns 0, 2, 4, ... while the data values (<literal>datavalue</literal>) are in columns 1, 3, 5, ...</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531612713087285">Dim myTree As Object, theRoot As Object, oDb As Object, vData As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991612713087724">Set myTree = myDialog.Controls("myTreeControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581612713087989">Set theRoot = myTree.CreateRoot("By product category")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771612713087670">Set oDb = CreateScriptService("SFDatabases.Database", "/home/.../mydatabase.odb")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731612713087683">vData = oDb.GetRows("SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] " _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id551612714130895"> & "FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] " _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id551612714139429"> & "ORDER BY [Category].[Name], [Product].[Name]")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361612714193588">myTree.AddSubTree(theRoot, vData, WithDataValue := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id671620317364456">SQL_STMT = "SELECT [Category].[Name], [Category].[ID], [Product].[Name], [Product].[ID] \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id51620317364911"> FROM [Category], [Product] WHERE [Product].[CategoryID] = [Category].[ID] \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101620318087874"> ORDER BY [Category].[Name], [Product].[Name]"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901620317363542">tree = dlg.Controls('myTreeControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361620317363735">root = tree.CreateRoot('By Product category')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361620317363903">db = CreateScriptService('SFDatabases.Database', '/home/.../mydatabase.odb')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id911620317364071">sub_tree = db.GetRows(SQL_STMT)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221620317364271">tree.AddSubTree(root, sub_tree, withdatavalue=True)</paragraph> + </pycode> +</section> + +<section id="CreateRoot"> + <comment> CreateRoot ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id791612780723864"> + <bookmark_value>DialogControl service;CreateRoot</bookmark_value> + </bookmark> + <h2 id="hd_id291612780723671" localize="false">CreateRoot</h2> + <paragraph role="paragraph" id="par_id151612780723320">Returns a new root node of the tree control, as a node UNO object of type <literal>com.sun.star.awt.tree.XMutableTreeNode</literal>. The new tree root is inserted below pre-existing root nodes. <embedvar href="text/sbasic/shared/03/sf_dialogcontrol.xhp#XMutableTreeNode"/></paragraph> + <paragraph role="paragraph" id="par_id821612780723965" xml-lang="en-US">This method may be called before displaying the dialog box to build the initial tree. It may also be called from a dialog or control event to complete the tree dynamically.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id991620309297239"> + <input>svc.CreateRoot(displayvalue: str, opt datavalue: any): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id791612117823819"><emph>displayvalue</emph>: The text appearing in the tree control box.</paragraph> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#datavalue"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id491612780723925">Dim myTree As Object, myNode As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241612780723722">Set myTree = myDialog.Controls("myTreeControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441612780723817">Set myNode = myTree.CreateRoot("Tree starts here ...")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id441620318437138">tree = dlg.Controls('myTreeControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301620318437324">node = tree.CreateRoot('Tree starts here ...')</paragraph> + </pycode> +</section> + +<section id="FindNode"> + <comment> FindNode ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id741612781589926"> + <bookmark_value>DialogControl service;FindNode</bookmark_value> + </bookmark> + <h2 id="hd_id801612781589891" localize="false">FindNode</h2> + <paragraph role="paragraph" id="par_id171612781589503">Traverses the tree and finds recursively, starting from the root, a node meeting some criteria. Either - 1 match is enough - having its display value matching <literal>displayvalue</literal> pattern or having its data value equal to <literal>datavalue</literal>. The comparisons may be or not case-sensitive. The first matching occurrence is returned as a node UNO object of type <literal>com.sun.star.awt.tree.XMutableTreeNode</literal>. <embedvar href="text/sbasic/shared/03/sf_dialogcontrol.xhp#XMutableTreeNode"/></paragraph> + <paragraph role="paragraph" id="par_id741612782475457" xml-lang="en-US">When not found, the method returns <literal>Nothing</literal>, to be tested with the <literal>IsNull()</literal> builtin function.</paragraph> + <paragraph role="paragraph" id="par_id41612781589363" xml-lang="en-US">This method may be called before displaying the dialog box to build the initial tree. It may also be called from a dialog or control event.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id61620309668544"> + <input>svc.FindNode(displayvalue: str = '', opt datavalue: any, casesensitive = False): uno</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id541613670199211">One argument out of <literal>displayvalue</literal> or <literal>datavalue</literal> must be specified. If both present, one match is sufficient to select the node.</paragraph> + <paragraph role="paragraph" id="par_id591612781589560"><emph>displayvalue</emph>: The pattern to be matched. Refer to <link href="text/sbasic/shared/03/sf_string.xhp#IsLike" name="String service IsLike() method"><literal>SF_String.IsLike()</literal></link> method for the list of possible wildcards. When equal to the zero-length string (default), this display value is not searched for.</paragraph> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#datavalue"/> + <paragraph role="paragraph" id="par_id141582384726168"><emph>casesensitive</emph>: Default value is <literal>False</literal></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61612781589464">Dim myTree As Object, myNode As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991612781589903">Set myTree = myDialog.Controls("myTreeControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461612781589942">Set myNode = myTree.FindNode("*Sophie*", CaseSensitive := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id191620318816450">tree = dlg.Controls('myTreeControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281620318817089">node = FindNode('*Sophie*', casesensitive=True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861620319785763">if node is None:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id471620319809524"> # ...</paragraph> + </pycode> +</section> + +<section id="SetFocus"> + <comment> SetFocus ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id721583933076548"> + <bookmark_value>DialogControl service;SetFocus</bookmark_value> + </bookmark> + <h2 id="hd_id681583933076692" localize="false">SetFocus</h2> + <paragraph role="paragraph" id="par_id871583933076448">Set the focus on the control. Return <literal>True</literal> if focusing was successful.</paragraph> + <paragraph role="paragraph" id="par_id151598178880227" xml-lang="en-US">This method is often called from a dialog or control event.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id11620310325234"> + <input>svc.SetFocus(): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221598179105596">Dim oControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171598179111121">Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681598179123436">Set oControl = oDlg.Controls("thisControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361598179135096">oControl.SetFocus()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id591620319169802">dlg = CreateScriptService('Dialog', None, None, 'myDialog')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201620319170298">ctrl = dlg.Controls('thisControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821620319170682">ctrl.SetFocus()</paragraph> + </pycode> +</section> + +<section id="SetTableData"> + <comment> SetTableData ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id761598619892024"> + <bookmark_value>DialogControl service;SetTableData</bookmark_value> + </bookmark> + <h2 id="hd_id961598619890364" localize="false">SetTableData</h2> + <paragraph role="paragraph" id="par_id541638553960464">Fills a <literal>TableControl</literal> with the given data. All preexisting data is cleared before inserting the new data passed as argument.</paragraph> + <paragraph role="paragraph" id="par_id551638554058131">When the <literal>TableControl</literal> is added to the dialog, it is possible to use the Basic IDE to define whether column and row headers will be shown in the table. If the <literal>TableControl</literal> has column and/or row headers, the first column and/or row in the provided data array are used as labels for the table headers.</paragraph> + <paragraph role="paragraph" id="par_id411638569396108">This method returns <literal>True</literal> when successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id841620310380255"> + <input>svc.SetTableData(dataarray: any[0..*, 0..*], widths: int[0..*], alignments: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257133"><emph>dataarray</emph>: Data to be entered into the table represented as an Array of Arrays in Basic or a tuple of tuples in Python. The data must include column and row headers if they are to be displayed by the <literal>TableControl</literal>.</paragraph> + <paragraph role="paragraph" id="par_id1001584541257025"><emph>widths</emph>: Array containing the relative widths of each column. In other words, <literal>widths = Array(1, 2)</literal> means that the second column is twice as wide as the first one. If the number of values in the array is smaller than the number of columns in the table, then the last value in the array is used to define the width of the remaining columns.</paragraph> + <paragraph role="paragraph" id="par_id1001584541257007"><emph>alignments</emph>: Defines the alignment in each column as a string in which each character can be "L" (Left), "C" (Center), "R" (Right) or " " (whitespace, default, meaning left for strings and right for numeric values). If the length of the string is shorter than the number of columns in the table, then the last character in the string is used to define the alignment of the remaining columns.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id381638569172413">The following example assumes that the dialog <literal>myDialog</literal> has a <literal>TableControl</literal> named <literal>Grid1</literal> with "Show row header" and "Show column header" properties set to "Yes".</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id901638569052132">Dim myDialog As Object, oTable As Object, tableData As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781638569039123">myDialog = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281638569051918">oTable = myDialog.Controls("Grid1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361638569052324">tableData = Array("Column A", "Column B", "Column C")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291638569052525">tableData = SF_Array.AppendRow(tableData, Array("Row 1", 1, 2))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631638569052740">tableData = SF_Array.AppendRow(tableData, Array("Row 2", 3, 4))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371638569052941">tableData = SF_Array.AppendRow(tableData, Array("Row 3", 5, 6))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781638569053179">vAlignments = "LCC"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181638569053413">vWidths = Array(2, 1, 1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191638569053613">oTable.SetTableData(tableData, vWidths, vAlignments)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981638569053837">myDialog.Execute()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id171638650502346">The <literal>Value</literal> property returns the selected row in the table. If no row is selected, an empty Array object is returned. The following code snippet shows how to test if any row is selected in the table.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891638651540245">rowValues = oTable.Value</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431638651540427">If UBound(rowValues) < 0 Then</paragraph> + <paragraph role="bascode" id="bas_id361638651540588"> MsgBox "No row selected."</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121638651540820">Else</paragraph> + <paragraph role="bascode" id="bas_id781638651541028"> MsgBox "Row " & oTable.ListIndex & " is selected."</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601638651541333">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id111638569958471">dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "myDialog")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871638569958742">table_control = dlg.Controls("Grid1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141638569958918">table_data = (("Column A", "Column B", "Column C"),</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id616385699590945"> ("Row 1", 1, 2),</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991638569959270"> ("Row 2", 3, 4),</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381638569959454"> ("Row 3", 5, 6))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251638569959654">alignments = "LCC"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id971638569959870">widths = (100, 50, 50)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571638569960094">table_control.SetTableData(table_data, widths, alignments)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id601638569960326">dlg.Execute()</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id311638651802570">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121638651802186">row_values = table_control.Value</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id216386518024106">if len(row_values) == 0:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941638651802762"> bas.MsgBox("No row selected.")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id491638651803057">else:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id261638651804210"> bas.MsgBox(f"Row {table_control.ListIndex} is selected.")</paragraph> + </pycode> +</section> + +<section id="WriteLine"> + <comment> WriteLine -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id761598619892798"> + <bookmark_value>DialogControl service;WriteLine</bookmark_value> + </bookmark> + <h2 id="hd_id961598619892816" localize="false">WriteLine</h2> + <paragraph role="paragraph" id="par_id671598619892378">Add a new line at the end of a multiline text field. A newline character will be inserted when appropriate. The method returns <literal>True</literal> when successful.</paragraph> + <paragraph role="paragraph" id="par_id941598619892915" xml-lang="en-US">An error is raised if the actual control is not of the type <literal>TextField</literal> or is not multiline.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id841620310387185"> + <input>svc.WriteLine(opt line: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257789"><emph>Line</emph>: The string to insert. Default is an empty line.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id681598619892624">Dim oDlg As Object, oControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id521598619892148">Set oDlg = CreateScriptService("SFDialogs.Dialog",,, "myDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391598619892465">Set oControl = oDlg.Controls("thisControl")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281598619892850">oControl.WriteLine("a new line")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id61620319410491">dlg = CreateScriptService('SFDialogs.Dialog', None, None, 'myDialog')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id701620319411995">ctrl = dlg.Controls('thisControl')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id591620319412507">ctr.WriteLine("a new line")</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_dialog.xhp#dlg_h1"/> + <embed href="text/sbasic/shared/03/sf_string.xhp#StringService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_dictionary.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_dictionary.xhp new file mode 100644 index 000000000..7d94a6c9f --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_dictionary.xhp @@ -0,0 +1,523 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Dictionary" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Dictionary service</title> + <filename>/text/sbasic/shared/03/sf_dictionary.xhp</filename> + </topic> +</meta> +<body> +<section id="abstract"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Dictionary service</bookmark_value> + </bookmark> + + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="SFDictionary"><link href="text/sbasic/shared/03/sf_dictionary.xhp" name="ScriptForge.Dictionary service"><literal>ScriptForge</literal>.<literal>Dictionary</literal> service</link></variable></h1> + + <paragraph role="paragraph" id="par_id891582884466217" xml-lang="en-US">A dictionary is a collection of key-item pairs</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id861582884516571" role="listitem" xml-lang="en-US">The key is a case-insensitive string</paragraph></listitem> + <listitem><paragraph id="par_id531582884549542" role="listitem" xml-lang="en-US">Items may be of any type</paragraph></listitem> + </list> +</section> + + <paragraph role="paragraph" id="par_id891582884593057" xml-lang="en-US">Keys and items can be retrieved, counted, updated, and much more.</paragraph> + <paragraph role="tip" id="par_id971582884636922" xml-lang="en-US">The Dictionary service is similar to the built-in %PRODUCTNAME Basic <literal>Collection</literal> object, however with more features. For example, <literal>Collection</literal> objects do not support the retrieval of keys. Moreover, Dictionaries provide additional capabilities as replacing keys, testing if a specific key already exists and converting the Dictionary into an Array object or JSON string.</paragraph> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id821610388789467">The following example creates <literal>myDict</literal> as an empty dictionary.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851582897798335">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim myDict As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201582885621287">myDict = CreateScriptService("Dictionary")</paragraph> + </bascode> + + <paragraph role="paragraph" id="par_id71158288562139" xml-lang="en-US">It is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id721582885621540">Set myDict = myDict.Dispose()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id551626869252987">The example below creates an empty instance of the <literal>Dictionary</literal> service and uses the Python native <literal>update</literal> method to populate it with the contents of a Python <literal>dict</literal> object.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id61626869417885">dico = dict('A' = 1, 'B' = 2, 'C' = 3)</paragraph> + <paragraph role="pycode" id="pyc_id61626869417128"># Initialize myDict as an empty dict object</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501626869418687">myDict = CreateScriptService('Dictionary')</paragraph> + <paragraph role="pycode" id="pyc_id921626869402748"># Load the values of dico into myDict</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921626869418958">myDict.update(dico)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271626869419262">myDict['D'] = 4</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681626869419637">print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801626869419846">propval = myDict.ConvertToPropertyValues()</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id981626869718081">It is possible to create an instance of the <literal>Dictionary</literal> service using a Python <literal>dict</literal> object as argument as shown in the following example.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891626869184970">dico = dict('A' = 1, 'B' = 2, 'C' = 3)</paragraph> + <paragraph role="pycode" id="pyc_id201626869185236"># Initialize myDict with the content of dico</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201626869182054">myDict = CreateScriptService('Dictionary', dico)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id831626869185400">myDict['D'] = 4</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id351626869185567">print(myDict) # {'A': 1, 'B': 2, 'C': 3, 'D': 4}</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id721626869185728">propval = myDict.ConvertToPropertyValues()</paragraph> + </pycode> + <note id="par_id211626699007613">Because Python has built-in dictionary support, most of the methods in the <literal>Dictionary</literal> service are available for Basic scripts only. Exceptions are <literal>ConvertToPropertyValues</literal> and <literal>ImportFromPropertyValues</literal> that are supported in both Basic and Python.</note> + + <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2> + <table id="tab_id971582885195582"> + <tablerow> + <tablecell> + <paragraph id="par_id41582885195836" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195372" role="tablehead" xml-lang="en-US">Read-only</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195238" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id931582885195131" role="tablehead" xml-lang="en-US" >Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id97158288519551" role="tablecontent" localize="false">Count</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221582885195686" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371582885195525" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881582885195976" role="tablecontent" xml-lang="en-US">The number of entries in the dictionary</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id841582886030384" role="tablecontent" localize="false">Items</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441582886030118" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131582886030297" role="tablecontent" xml-lang="en-US">Array of Variants</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471582886030489" role="tablecontent" xml-lang="en-US">The list of items as a one dimensional array</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id231582886791351" role="tablecontent" localize="false">Keys</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971582886791838" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582886791111" role="tablecontent" xml-lang="en-US">Array of Strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id16158288679167" role="tablecontent" xml-lang="en-US">The list of keys as a one dimensional array</paragraph> + </tablecell> + </tablerow> + </table> + + <paragraph role="tip" id="par_id461582886731495" xml-lang="en-US">The <literal>Keys</literal> and <literal>Items</literal> properties return their respective contents, using an identical ordering. The order is unrelated to the creation sequence.</paragraph> + + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id931610389113917">The following example uses the <literal>Keys</literal> property to iterate over all keys in the dictionary <literal>myDict</literal>.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211582887012398">Dim a As Variant, b As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351582887179042">a = myDict.Keys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251582887187534">For Each b In a</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121582887198799"> MsgBox(myDict.Item(b))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571606473148931">Next b</paragraph> + </bascode> + + <table id="tab_id891606472825856"> + <tablerow> + <tablecell><paragraph id="par_id581606472825856" role="tablehead" localize="false"></paragraph></tablecell> + <tablecell><paragraph id="par_id921606472825856" role="tablehead">Methods</paragraph></tablecell> + <tablecell><paragraph id="par_id781606472825856" role="tablehead" localize="false"></paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id381606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#Add" name="Add method">Add</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToArray" name="ConvertToArray method">ConvertToArray</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToJson" name="ConvertToJson method">ConvertToJson</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToPropertyValues" name="ConvertToPropertyValues method">ConvertToPropertyValues</link> + </paragraph></tablecell> + <tablecell><paragraph id="par_id451606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#Exists" name="Exists method">Exists</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromJson" name="ImportFromJson method">ImportFromJson</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromPropertyValues" name="ImportFromPropertyValues method">ImportFromPropertyValues</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#Item" name="Item method">Item</link> + </paragraph></tablecell> + <tablecell><paragraph id="par_id161606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#Remove" name="Remove method">Remove</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#RemoveAll" name="RemoveAll method">RemoveAll</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceItem" name="ReplaceItem method">ReplaceItem</link><br/> + <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceKey" name="ReplaceKey method">ReplaceKey</link> + </paragraph></tablecell> + </tablerow> + </table> + +<section id="Add"> + <comment> Add ---------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id781582887670029"> + <bookmark_value>Dictionary service;Add</bookmark_value> + </bookmark> + <h2 id="hd_id831582887670029" localize="false">Add</h2> + <paragraph role="paragraph" id="par_id831582887670029">Adds a new key-item pair into the dictionary. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id881626699610355"> + <input>dict.Add(key: str, item: any): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id341582887670030"><emph>key</emph>: String value used to identify the Item. The key is not case-sensitive.</paragraph> + <paragraph role="paragraph" id="par_id401582887670030"><emph>item</emph>: Any value, including an array, a Basic object, a UNO object, a dictionary, etc.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191582887670030">Dim NewValue As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391582887670030">myDict.Add("NewKey", NewValue)</paragraph> + </bascode> + <warning id="par_id1001610391308765">Every key must be unique in the same dictionary. If the key already exists in the dictionary, a <literal>DUPLICATEKEYERROR</literal> will be raised. Keys that are made of space characters will raise a <literal>INVALIDKEYERROR</literal> error.</warning> +</section> + +<section id="ConvertToArray"> + <comment> ConvertToArray ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id621582888424103"> + <bookmark_value>Dictionary service;ConvertToArray</bookmark_value> + </bookmark> + <h2 id="hd_id211582888424104" localize="false">ConvertToArray</h2> + <paragraph role="paragraph" id="par_id81582888424104">Stores the contents of the dictionary in a two-columns zero-based array. The keys are stored in the first column and the items are stored in the second column.</paragraph> + <paragraph role="paragraph" id="par_id341610391565678">If the dictionary is empty, this method will return an empty <literal>Array</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id71626699963594"> + <input>dict.ConvertToArray(): any[0..*, 0..1]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id651610391840491">Dim myDict as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381610391862148">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61610391873262">myDict.Add("a", 1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351610391876967">myDict.Add("b", 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491610391880959">myDict.Add("c", 3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id521610391883264">Dim arr as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361610391885584">arr = myDict.ConvertToArray()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911610391888240">'(("a", 1), ("b", 2), ("c", 3))</paragraph> + </bascode> +</section> + +<section id="ConvertToJson"> + <comment> ConvertToJson ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id631601296836318"> + <bookmark_value>Dictionary service;ConvertToJson</bookmark_value> + </bookmark> + <h2 id="hd_id851601296836224" localize="false">ConvertToJson</h2> + <paragraph role="paragraph" id="par_id831601296836981">Converts the contents of a dictionary to <link href="https://en.wikipedia.org/wiki/JSON" name="JSON text">JSON (JavaScript Object Notation)</link> text.</paragraph> + <h3 id="hd_id261601297024828" xml-lang="en-US">Limitations</h3> + <paragraph role="paragraph" id="par_id401601297178073" xml-lang="en-US">This method supports the following data types: <literal>String</literal>, <literal>Boolean</literal>, numbers, <literal>Null</literal> and <literal>Empty</literal>. Arrays containing items of those types are also allowed, whatever their dimensions. Dates are converted into strings, however they cannot be used inside Arrays. Other data types are converted to their string representation using the <literal>SF_String.Represent</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id901626700139467"> + <input>dict.ConvertToJson(indent: str = ""): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id8816012968362"><emph>indent</emph>: When <literal>indent</literal> is a positive number or a text, JSON array elements and object members are pretty-printed with that indentation level. A negative <literal>indent</literal> value will add new lines with no indentation. The default value is an empty string "" which selects the most compact representation. Using a positive integer for <literal>indent</literal> indents that many spaces per level. When <literal>indent</literal> is a string, such as <literal>Chr(9)</literal> or <literal>Tab(1)</literal>, the Tab character is used to indent each level.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671601298281962">myDict.Add("p0", 12.5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851601298288784">myDict.Add("p1", "a string àé""ê")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201601298295976">myDict.Add("p2", DateSerial(2020,9,28))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951601298323286">myDict.Add("p3", True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731601298329491">myDict.Add("p4", Array(1,2,3))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id451601298336500">MsgBox myDict.ConvertToJson() </paragraph> + <paragraph role="bascode" localize="false" id="bas_id511610392557702">'{"p0": 12.5, "p1": "a string \u00e0\u00e9\"\u00ea", "p2": "2020-09-28", "p3": true, "p4": [1, 2, 3]}</paragraph> + </bascode> +</section> + +<section id="ConvertToPropertyValues"> + <comment> ConvertToPropertyValues --------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id991582889470402"> + <bookmark_value>Dictionary service;ConvertToPropertyValues</bookmark_value> + <bookmark_value>API;PropertyValue</bookmark_value> + <bookmark_value>API;DateTime</bookmark_value> + </bookmark> + <h2 id="hd_id421582889470909" localize="false">ConvertToPropertyValues</h2> + <paragraph role="paragraph" id="par_id151582889470596">Stores the contents of the dictionary into an array of <literal>PropertyValues</literal>.</paragraph> + <paragraph role="paragraph" id="par_id231610392665049">Each entry in the array is a <literal>com.sun.star.beans.PropertyValue</literal>. The key is stored in <literal>Name</literal>, the item is stored in <literal>Value</literal>.</paragraph> + <paragraph role="paragraph" id="par_id341610392705367">If one of the items has a type <literal>Date</literal>, it is converted to a <literal>com.sun.star.util.DateTime</literal> structure. If one of the items is an empty array, it is converted to <literal>Null</literal>. The resulting array is empty when the dictionary is empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id481626700464253"> + <input>dict.ConvertToPropertyValues(): obj[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81610393124521">Dim myDict as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id971610393127816">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" id="bas_id531610393130289">'Adds some properties to the dictionary</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711610393132877">myDict.Add("Color", "Blue")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681610393135354">myDict.Add("Width", 20)</paragraph> + <paragraph role="bascode" id="bas_id571610393137959">'Converts to an Array of PropertyValue objects</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351610393140357">Dim prop as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101610393142717">prop = myDict.ConvertToPropertyValues()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id771626700938786">Note in the example below that a Python dictionary needs to be passed as the second argument of the <literal>CreateScriptService</literal> method.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id691626700585141">myDict = dict()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811626700586188">myDict["Color"] = "Blue"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id331626700586409">myDict["Width"] = 30</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id171626700586634">sfDic = CreateScriptService("Dictionary", myDict)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251626700586818">prop = sfDic.ConvertToPropertyValues()</paragraph> + </pycode> + <tip id="par_id421610393306916">Many services and methods in the UNO library take in parameters represented using the <literal>PropertyValue</literal> struct, which is part of the %PRODUCTNAME API.</tip> +</section> + +<section id="Exists"> + <comment> Exists ------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id81582889812915"> + <bookmark_value>Dictionary service;Exists</bookmark_value> + </bookmark> + <h2 id="hd_id461582889812915" localize="false">Exists</h2> + <paragraph role="paragraph" id="par_id841582889812916">Determines if a key exists in the dictionary.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id441626701103153"> + <input>dict.Exists(key: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id971582889812917"><emph>key</emph>: The key to be looked up in the dictionary.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id741582889812919">Dim myDict as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471582889812919">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" id="bas_id811606485130666">'Adds some properties to the dictionary</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391610393640781">myDict.Add("Color", "Blue")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891610393643755">myDict.Add("Width", 20)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531610393646186">'(...)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491610393648822">If Not myDict.Exists("Size") Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681610393651551"> MsgBox "You have to provide a Size value"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581610393654335">End If</paragraph> + </bascode> +</section> + +<section id="ImportFromJson"> + <comment> ImportFromJson ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id661601391980619"> + <bookmark_value>Dictionary service;ImportFromJson</bookmark_value> + </bookmark> + <h2 id="hd_id81601391980848" localize="false">ImportFromJson</h2> + <paragraph role="paragraph" id="par_id791601391980978">Adds the content of a <link href="https://en.wikipedia.org/wiki/JSON" name="JSON text">JSON (JavaScript Object Notation)</link> string into the current dictionary. Returns <literal>True</literal> if successful.</paragraph> + <h3 id="hd_id961601392113644" xml-lang="en-US">Limitations</h3> + <paragraph role="paragraph" id="par_id481601392181131" xml-lang="en-US">The JSON string may contain numbers, text, booleans, null values and arrays containing those types. It must not contain JSON objects namely sub-dictionaries.</paragraph> + <paragraph role="paragraph" id="par_id511601392205908" xml-lang="en-US">An attempt is made to convert text to date if the item matches one of these patterns: YYYY-MM-DD, HH:MM:SS or YYYY-MM-DD HH:MM:SS.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id841626701235169"> + <input>dict.ImportFromJson(inputstr: str, overwrite: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id69160139198061"><emph>inputstr</emph>: The string to import.</paragraph> + <paragraph role="paragraph" id="par_id201601391980268"><emph>overwrite</emph>: When <literal>True</literal>, entries with same name may exist in the dictionary and their values are overwritten. When <literal>False</literal> (default), repeated keys will raise an error. Beware that dictionary keys are not case-sensitive while names are case-sensitive in JSON strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id411601393205207">Dim s As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891601393212562">s = "{'firstName': 'John','lastName': 'Smith','isAlive': true,'age': 66, 'birth': '1954-09-28 20:15:00'" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id221601393220997"> & ",'address': {'streetAddress': '21 2nd Street','city': 'New York','state': 'NY','postalCode': '10021-3100'}" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931601393226582"> & ",'phoneNumbers': [{'type': 'home','number': '212 555-1234'},{'type': 'office','number': '646 555-4567'}]" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671601393233042"> & ",'children': ['Q','M','G','T'],'spouse': null}"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id131601393240390">s = Replace(s, "'", """")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351601393248554">myDict.ImportFromJson(s, OverWrite := True)</paragraph> + <paragraph role="bascode" id="bas_id521601393254694">'The (sub)-dictionaries "address" and "phoneNumbers" (0) and (1) are imported as Empty values.</paragraph> + </bascode> +</section> + +<section id="ImportFromPropertyValues"> + <comment> ImportFromPropertyValues ------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id791588941968651"> + <bookmark_value>Dictionary service;ImportFromPropertyValues</bookmark_value> + </bookmark> + <h2 id="hd_id71588941968955" localize="false">ImportFromPropertyValues</h2> + <paragraph role="paragraph" id="par_id651588941968228">Inserts the contents of an array of <literal>PropertyValue</literal> objects into the current dictionary. <literal>PropertyValue</literal> Names are used as Keys in the dictionary, whereas Values contain the corresponding values. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id431626701465848"> + <input>dict.ImportFromPropertyValues(propertyvalues: obj[0..*], overwrite: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id751588941968522"><emph>propertyvalues</emph>: A zero-based 1-dimensional array containing <literal>com.sun.star.beans.PropertyValue</literal> objects. This parameter may also be a single <literal>PropertyValue</literal> object not contained in an Array.</paragraph> + <paragraph role="paragraph" id="par_id21588941968131"><emph>overwrite</emph>: When <literal>True</literal>, entries with same name may exist in the dictionary and their values are overwritten. When <literal>False</literal> (default), repeated keys will raise an error. Note that dictionary keys are not case-sensitive in Basic, whereas names are case-sensitive in sets of property values and in Python dictionaries.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id641626703615898">The examples below first create an array with two <literal>PropertyValue</literal> objects and then convert it to a dictionary.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id951588941968987">Dim vProp As New com.sun.star.beans.PropertyValue</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771588941968883">Dim arrProp : arrProp = Array()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831588943409828">vProp.Name = "Color"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891610395011237">vProp.Value = "Blue"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371626703397791">arrProp = SF_Array.Append(arrProp, vProp)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71626703398189">vProp.Name = "Date"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001626703398431">vProp.Value = CDateToUnoDateTime(Now)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881626703398656">arrProp = SF_Array.Append(arrProp, vProp)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id761626703398879">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181626703399098">myDict.ImportFromPropertyValues(arrProp, Overwrite := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121626703516023">Dim keys : keys = myDict.Keys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id971626703516446">For Each k In keys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811626703516686"> MsgBox k & " - " & myDict.Item(k)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261626703516863">Next k</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id121626701725559">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id611626704519415">from datetime import datetime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221626701725743">import uno</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id911626701725885">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941626701726044">arrProp = list()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id911626701726205">vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id751626701726717">vProp.Name = "Color"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841626704518283">vProp.Value = "Blue"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id291626704518547">arrProp.append(vProp)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271626704518745">vProp = uno.createUnoStruct("com.sun.star.beans.PropertyValue")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id691626704518975">vProp.Name = "Date"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id691626704519192">vProp.Value = bas.CDateToUnoDateTime(datetime.now())</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631626704519647">arrProp.append(vProp)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id881626704519864">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id61626704520096">myDict.ImportFromPropertyValues(arrProp, overwrite=True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181626704520322">for k in myDict.keys():</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221626704799909"> bas.MsgBox("{} - {}".format(k, myDict[k]))</paragraph> + </pycode> +</section> + +<section id="Item"> + <comment> Item --------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id741582980366762"> + <bookmark_value>Dictionary service;Item</bookmark_value> + </bookmark> + <h2 id="hd_id301582098366573" localize="false">Item</h2> + <paragraph role="paragraph" id="par_id891582890366737">Retrieves an existing dictionary entry based on its key. Returns the value of the item if successful, otherwise returns <literal>Empty</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id501626704949678"> + <input>dict.Item(key: str): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id551582890399669"><emph>key</emph>: Not case-sensitive. If it does not exist, <literal>Empty</literal> value is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id181610395933967">The following example iterates over all keys in the dictionary and uses the <literal>Item</literal> method to access their values.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371528890366702">Dim myDict as Variant, k as Variant, allKeys as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661610395517565">myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181610395523430">myDict.Add("key1", 100)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621610395527679">myDict.Add("key2", 200)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871610395530158">myDict.Add("key3", 300)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891610395534807">allKeys = myDict.Keys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71610395537640">For Each k in allKeys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411610395540304"> MsgBox(myDict.Item(k))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931610395543522">Next k</paragraph> + </bascode> +</section> + +<section id="Remove"> + <comment> Remove ------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id741582890366762"> + <bookmark_value>Dictionary service;Remove</bookmark_value> + </bookmark> + <h2 id="hd_id301582890366573" localize="false">Remove</h2> + <paragraph role="paragraph" id="par_id891582890388737">Removes an existing dictionary entry based on its key. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id861626705083007"> + <input>dict.Remove(key: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id551582890366999"><emph>key</emph>: Not case-sensitive. Must exist in the dictionary, otherwise an <literal>UNKNOWNKEYERROR</literal> error is raised.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id56158289627581">myDict.Add("key1", 100)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651610399290742">myDict.Add("key2", 200)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741610399296091">myDict.Add("key3", 300)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591610399299316">MsgBox(myDict.Count) ' 3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661610399302807">myDict.Remove("key2")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671610399305808">MsgBox(myDict.Count) ' 2</paragraph> + </bascode> +</section> + +<section id="RemoveAll"> + <comment> RemoveAll ---------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id471582896275914"> + <bookmark_value>Dictionary service;RemoveAll</bookmark_value> + </bookmark> + <h2 id="hd_id911582896275637" localize="false">RemoveAll</h2> + <paragraph role="paragraph" id="par_id921582896275624">Removes all the entries from the dictionary. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561626705190520"> + <input>dict.RemoveAll(): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id56158289627580">myDict.Add("key1", 100)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651610399290743">myDict.Add("key2", 200)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741610399296092">myDict.Add("key3", 300)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591610399299317">MsgBox(myDict.Count) ' 3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661610399302808">myDict.RemoveAll()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671610399305809">MsgBox(myDict.Count) ' 0</paragraph> + </bascode> +</section> + +<section id="ReplaceItem"> + <comment> ReplaceItem -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id891582895615851"> + <bookmark_value>Dictionary service;ReplaceItem</bookmark_value> + </bookmark> + <h2 id="hd_id801582895615477" localize="false">ReplaceItem</h2> + <paragraph role="paragraph" id="par_id281582895615444">Replaces an existing item value based on its key. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id551626705258936"> + <input>dict.ReplaceItem(key: str, value: any): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id991582895615535"><emph>key</emph>: String value representing the key whose value will be replaced. Not case-sensitive. If the key does not exist in the dictionary, an <literal>UNKNOWNKEYERROR</literal> error is raised.</paragraph> + <paragraph role="paragraph" id="par_id721582895615186"><emph>value</emph>: The new value of the item referred to with the <literal>key</literal> parameter.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id581582895615680">myDict.Add("a", 1)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351582895615555">MsgBox(myDict.Item("a")) ' 1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361610399892402">myDict.ReplaceItem("a", 100)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411610399896001">MsgBox(myDict.Item("a")) ' 100</paragraph> + </bascode> +</section> + +<section id="ReplaceKey"> + <comment> ReplaceKey --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id411582896597981"> + <bookmark_value>Dictionary service;ReplaceKey</bookmark_value> + </bookmark> + <h2 id="hd_id231582896597839" localize="false">ReplaceKey</h2> + <paragraph role="paragraph" id="par_id571582896597766">Replaces an existing key in the dictionary by a new key. The item value is left unchanged. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id851626705393127"> + <input>dict.ReplaceKey(key: str, value: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id911582896597619"><emph>key</emph>: String value representing the key to be replaced. Not case-sensitive. If the key does not exist in the dictionary, a <literal>UNKNOWNKEYERROR</literal> error is raised.</paragraph> + <paragraph role="paragraph" id="par_id531582896597989"><emph>value</emph>: String value for the new key. Not case-sensitive. If the new key already exists in the dictionary, an <literal>DUPLICATEKEYERROR</literal> error is raised.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id521582896597313">myDict.Add("oldKey", 100)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961610400326541">MsgBox(myDict.Item("oldKey")) ' 100</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631610400329115">myDict.ReplaceKey("oldKey", "newKey")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id761610400331545">MsgBox(myDict.Item("newKey")) ' 100</paragraph> + </bascode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_array.xhp#ArrayService"/> + <embed href="text/sbasic/shared/collection.xhp#Collection_h1"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_document.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_document.xhp new file mode 100644 index 000000000..f0c0ee7c5 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_document.xhp @@ -0,0 +1,729 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Document" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Document service</title> + <filename>/text/sbasic/shared/03/sf_document.xhp</filename> + </topic> +</meta> + +<body> +<section id="SFDocuments-sf_document"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Document service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="DocumentService"><link href="text/sbasic/shared/03/sf_document.xhp" name="Exception service"><literal>SFDocuments</literal>.<literal>Document</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id381589189355849" xml-lang="en-US">The <literal>SFDocuments</literal> library provides methods and properties to facilitate the management and manipulation of %PRODUCTNAME documents.</paragraph> + <paragraph role="paragraph" id="par_id591589189364267" xml-lang="en-US">Methods that are applicable for all types of documents (Text Documents, Sheets, Presentations, etc) are provided by the <literal>SFDocuments.Document</literal> service. Some examples are:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id891589189452545" role="listitem" xml-lang="en-US">Opening, closing and saving documents</paragraph> + </listitem> + <listitem> + <paragraph id="par_id811589189463041" role="listitem" xml-lang="en-US">Accessing standard or custom properties of documents</paragraph> + </listitem> + </list> +</section> + + <warning id="par_id301611085807704">The properties, methods or arguments marked with <emph>(*)</emph> are <emph>NOT applicable to Base documents</emph>.</warning> + <paragraph role="paragraph" id="par_id241589189701274" xml-lang="en-US">Methods and properties that are specific to certain %PRODUCTNAME components are stored in separate services, such as <literal>SFDocuments.SF_Calc</literal> and <literal>SFDocuments.SF_Base</literal>.</paragraph> + <paragraph role="paragraph" id="par_id641611090052376">Although the Basic language does not offer inheritance between object classes, the latter services may be considered as subclasses of the <literal>SFDocuments.Document</literal> service. Such subclasses can invoke the properties and methods described below.</paragraph> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Document</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id581611090387382">Below are three variants of how the <literal>Document</literal> service can be invoked.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id181622816732197">Using the <literal>getDocument</literal> method from the <literal>ScriptForge</literal>.<literal>UI</literal> service:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim ui As Object, oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201582885621287">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561589191748697">Set oDoc = ui.GetDocument("Untitled 1")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id181622818236233">Alternatively you can use the methods <literal>CreateDocument</literal> and <literal>OpenDocument</literal> from the <literal>UI</literal> service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id511589191758563">Set oDocA = ui.CreateDocument("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331589191766531">Set oDocB = ui.OpenDocument("C:\Documents\MyFile.odt")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id691622816765571">Directly if the document is already open.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371589191782045">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711589191788959">Set oDoc = CreateScriptService("SFDocuments.Document", "Untitled 1") 'Default = ActiveWindow</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id821622816825012">From a macro triggered by a document event.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61598109336361">Sub RunEvent(ByRef poEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31598109342395"> Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id481598109349427"> Set oDoc = CreateScriptService("SFDocuments.DocumentEvent", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401622818141194"> ' (...)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991622818141557">End Sub</paragraph> + </bascode> + <note id="par_id831622816562430">The <literal>Document</literal> service is closely related to the <literal>UI</literal> and <literal>FileSystem</literal> services.</note> + <paragraph role="paragraph" id="par_id891582733781994" xml-lang="en-US">Except when the document was closed by program with the CloseDocument method (it is then superfluous), it is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61582733781413">Set oDoc = oDoc.Dispose()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id261622818031652">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id291622818032129">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781622818032358">doc = ui.GetDocument("Untitled 1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741622818032551"># (...)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221622818032804">doc.Dispose()</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id421622818033432">docA = ui.CreateDocument("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id451622818787113">docB = ui.OpenDocument("C:\Documents\MyFile.odt")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id931622818866918">doc = CreateScriptService("SFDocuments.Document", "Untitled 1")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551622819064247">def RunEvent(event)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311622819064554"> doc = CreateScriptService("SFDocuments.DocumentEvent", Event)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221622819064967"> # (...)</paragraph> + </pycode> + <tip id="par_id71611090922315">The use of the prefix "<literal>SFDocuments.</literal>" while calling the service is optional.</tip> + + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id81611339709014"> + <bookmark_value>API;Duration</bookmark_value> + <bookmark_value>API;XComponent</bookmark_value> + <bookmark_value>API;ODatabaseDocument</bookmark_value> + </bookmark> + <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2> + <table id="tab_id971582885195582"> + <tablerow> + <tablecell> + <paragraph id="par_id41582885195836" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195372" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31582885195238" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id931582885195131" role="tablehead" xml-lang="en-US" >Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id7715828856553" role="tablecontent" xml-lang="en-US" localize="false">CustomProperties (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582885655779" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582885655525" role="tablecontent" xml-lang="en-US" localize="false">Dictionary service</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582885655885" role="tablecontent" xml-lang="en-US" >Returns a <literal>ScriptForge.Dictionary</literal> object instance. After update, can be passed again to the property for updating the document.<br />Individual items of the dictionary may be either strings, numbers, (Basic) dates or <link href="https://api.libreoffice.org/docs/idl/ref/structcom_1_1sun_1_1star_1_1util_1_1Duration.html" name="Duration API"><literal>com.sun.star.util.Duration</literal></link> items.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id841582886030384" role="tablecontent" xml-lang="en-US" localize="false">Description (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441582886030118" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131582886030297" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471582886030489" role="tablecontent" xml-lang="en-US" >Gives access to the Description property of the document (also known as "Comments")</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id231582886791351" role="tablecontent" xml-lang="en-US" localize="false">DocumentProperties (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971582886791838" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271582886791111" role="tablecontent" xml-lang="en-US" localize="false">Dictionary service</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id16158288679167" role="tablecontent" xml-lang="en-US" >Returns a <literal>ScriptForge.Dictionary</literal> object containing all the entries. Document statistics are included. Note that they are specific to the type of document. As an example, a Calc document includes a "CellCount" entry. Other documents do not.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id881589194571813" role="tablecontent" xml-lang="en-US" localize="false">DocumentType</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201589194571955" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951589194571781" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941589194571801" role="tablecontent" xml-lang="en-US" >String value with the document type ("Base", "Calc", "Writer", etc)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id881589194572136" role="tablecontent" xml-lang="en-US" localize="false">ExportFilters</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201589194571699" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951589194571391" role="tablecontent" xml-lang="en-US" localize="false">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941589194571327" role="tablecontent" xml-lang="en-US">Returns a list with the export filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id881589194573253" role="tablecontent" xml-lang="en-US" localize="false">ImportFilters</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201589194571067" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951589194571292" role="tablecontent" xml-lang="en-US" localize="false">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941589194571922" role="tablecontent" xml-lang="en-US">Returns a list with the import filter names applicable to the current document as a zero-based array of strings. Filters used for both import/export are also returned.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241589194633142" role="tablecontent" xml-lang="en-US" localize="false">IsBase<br />IsCalc<br />IsDraw<br />IsImpress<br />IsMath<br />IsWriter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761589194633950" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741589194633956" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611589194633853" role="tablecontent" xml-lang="en-US" >Exactly one of these properties is <literal>True</literal> for a given document.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id311589194910727" role="tablecontent" xml-lang="en-US" localize="false">Keywords (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id231589194910179" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421589194910942" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311589194910190" role="tablecontent" xml-lang="en-US">Gives access to the Keywords property of the document. Represented as a comma-separated list of keywords</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id911589638614922" role="tablecontent" xml-lang="en-US" localize="false">Readonly (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id921589638614972" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501589638614132" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id801589638614518" role="tablecontent" xml-lang="en-US"><literal>True</literal> if the document is actually in read-only mode</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id921589195028191" role="tablecontent" xml-lang="en-US" localize="false">Subject (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201589195028733" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id551589195028724" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371589195028843" role="tablecontent" xml-lang="en-US">Gives access to the Subject property of the document.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id521589195028736" role="tablecontent" xml-lang="en-US" localize="false">Title (*)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451589195028910" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31589195028773" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771589195028748" role="tablecontent" xml-lang="en-US">Gives access to the Title property of the document.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id97158288519551" role="tablecontent" xml-lang="en-US" localize="false">XComponent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221582885195686" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371582885195525" role="tablecontent" xml-lang="en-US">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881582885195976" role="tablecontent" xml-lang="en-US" >The UNO object <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1lang_1_1XComponent.html" name="XComponent API"><literal>com.sun.star.lang.XComponent</literal></link> or <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1sdb_1_1OfficeDatabaseDocument.html" name="ODatabaseDocument API"><literal>com.sun.star.comp.dba.ODatabaseDocument</literal></link> representing the document</paragraph> + </tablecell> + </tablerow> +</table> + + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id861611146581334">The example below prints all the properties of a document. Note that the <literal>oDoc</literal> object returned by the <literal>UI.OpenDocument</literal> method is a <literal>SFDocuments.Document</literal> object.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id391611146834072">Dim ui as Variant : Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471611146957794">Dim oDoc as Object</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id311611146962193">Set oDoc = ui.OpenDocument("C:\Documents\MyFile.ods")</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id711611146962784">Dim propDict as Object</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id391611146963409">Set propDict = oDoc.DocumentProperties</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id621611146963920">Dim keys as Variant : propKeys = propDict.Keys</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id21611146964465">Dim k as String, strProp as String</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id681611146965001">For Each k In propKeys</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id191611146965538"> strProp = strProp & k & ": " & propDict.Item(k) & CHR$(10)</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id741611146966256">Next k</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id911611146967874">MsgBox strProp</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681611147290092">oDoc.CloseDocument()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id571622826920742">To access document properties in a Python script the user needs to directly access them using their names, as shown below:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id391622827274657">doc = ui.GetDocument(r"C:\Documents\MyFile.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id261622827328471">msg = doc.Title + '\n' + doc.Description + '\n' + doc.Keywords</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id41622827328938">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id71622827329510">bas.MsgBox(msg)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id71622827327225">doc.CloseDocument()</paragraph> + </pycode> + + <table id="tab_id901611086279902"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Document Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_document.xhp#Activate" name="Activate method">Activate</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#CloseDocument" name="CloseDocument method">CloseDocument</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#CreateMenu" name="CreateMenu method">CreateMenu</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#ExportAsPDF" name="ExportAsPDF method">ExportAsPDF</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_document.xhp#PrintOut" name="PrintOut method">PrintOut</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#RemoveMenu" name="RemoveMenu method">RemoveMenu</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#RunCommand" name="RunCommand method">RunCommand</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#Save" name="Save method">Save</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611086279903" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_document.xhp#SaveAs" name="SaveAs method">SaveAs</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#SaveCopyAs" name="SaveCopyAs method">SaveCopyAs</link><br/> + <link href="text/sbasic/shared/03/sf_document.xhp#SetPrinter" name="SetPrinter method">SetPrinter</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + +<section id="Activate"> + <comment> Activate -------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Document service;Activate</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">Activate</h2> + <paragraph role="paragraph" id="par_id93158919969864">Returns <literal>True</literal> if the document could be activated. Otherwise, there is no change in the actual user interface. It is equivalent to the <literal>Activate</literal> method of the <literal>UI</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id421611148353046">This method is useful when one needs to give focus for a document that is minimized or hidden.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id181622827609276"> + <input>svc.Activate(): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id601611148017930">The example below considers that the file "My_File.ods" is already open but not active.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969836">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881611147617212">Set oDoc = CreateScriptService("Document", "MyFile.ods")</paragraph> + <paragraph role="bascode" localize="false" id="pyc_id571611147618913">oDoc.Activate()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id411622827715523">doc = CreateScriptService("Document", "MyFile.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id171622827715836">doc.Activate()</paragraph> + </pycode> + <tip id="par_id601611148080503">Keep in mind that you can invoke the <literal>Document</literal> service by passing to <literal>CreateScriptService</literal> either "Document" or "SFDocuments.Document"</tip> +</section> + +<section id="CloseDocument"> + <comment> CloseDocument ---------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121249"> + <bookmark_value>Document service;CloseDocument</bookmark_value> + </bookmark> + <h2 id="hd_id261589200121415" localize="false">CloseDocument</h2> + <paragraph role="paragraph" id="par_id651589200121138">Closes the document. If the document is already closed, regardless of how the document was closed, this method has no effect and returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id341611149562894">The method will also return <literal>False</literal> if the user declines to close it.</paragraph> + <paragraph role="paragraph" id="par_id981611149616934">Returns <literal>True</literal> if the document was successfully closed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622887222169"> + <input>svc.CloseDocument(saveask: bool = True): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361589200121646"><emph>saveask</emph> : If <literal>True</literal> (default), the user is invited to confirm if the changes should be written on disk. This argument is ignored if the document was not modified.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891580290121516">If oDoc.CloseDocument(True) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51589200506125"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751622827903730">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622827946898">if doc.CloseDocument(True):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221622827947414"> # ...</paragraph> + </pycode> +</section> + +<section id="CreateMenu"> + <comment> CreateMenu --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200120958"> + <bookmark_value>Document service;CreateMenu</bookmark_value> + </bookmark> + <h2 id="hd_id261589200121339" localize="false">CreateMenu</h2> + <paragraph role="paragraph" id="par_id651589200121080">Creates a new menu entry in the menubar of a given document window.</paragraph> + <paragraph role="paragraph" id="par_id981611149616155">This method returns an instance of the <link href="text/sbasic/shared/03/sf_menu.xhp" name="Menu_link1"><input>SFWidgets.Menu</input></link> service.</paragraph> + <note id="par_id721643121487974">The menu created is only available during the current %PRODUCTNAME session and is not saved neither in the document nor in the global application settings. Hence closing the document window will make the menu disappear. It will only reappear when the macro that creates the menu is executed again.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622887222964"> + <input>svc.CreateMenu(menuheader: str, [before: any], submenuchar: str = ">"): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361589200120316"><emph>menuheader</emph>: The toplevel name of the new menu.</paragraph> + <paragraph role="paragraph" id="par_id361589200129686"><emph>before</emph>: The name (as a string) or position (as an integer starting at 1) of an existing menu before which the new menu will be placed. If no value is defined for this argument, the menu will be created at the last position in the menubar.</paragraph> + <paragraph role="paragraph" id="par_id361589200122507"><emph>submenuchar</emph>: The delimiter used to create menu trees when calling methods as <literal>AddItem</literal> from the <literal>Menu</literal> service. The default value is ">".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891580290121500">Dim oDoc as Object, oMenu as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515892005061251">Set oDoc = CreateScriptService("Document")</paragraph> + <paragraph role="bascode" id="bas_id751622827903865">Set oMenu = oDoc.CreateMenu("My Menu")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621643120224240">With oMenu</paragraph> + <paragraph role="bascode" id="bas_id391643120224507"> ' Add items to the menu</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411643120224708"> .AddItem("Item A")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411643120224719"> .AddItem("Item B")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461643120224936"> ' ...</paragraph> + <paragraph role="bascode" id="bas_id100164312025160"> ' After creating the menu, the service instance can be disposed of</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401643120225361"> .Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701643120225536">End With</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622827946021">doc = CreateScriptService("Document")</paragraph> + <paragraph role="pycode" id="pyc_id221622827943208">menu = doc.CreateMenu("My Menu")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381643120494454">menu.AddItem("Item A")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381643120494463">menu.AddItem("Item B")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361643120494723"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151643120494942">menu.Dispose()</paragraph> + </pycode> + <section id="menu_tip"> + <tip id="par_id271643139068194">Refer to the <link href="text/sbasic/shared/03/sf_menu.xhp" name="Menu_link2"><input>SFWidgets.Menu</input></link> help page to learn more about how to create/remove menus in %PRODUCTNAME document windows.</tip> + </section> +</section> + +<section id="ExportAsPDF"> + <comment> ExportAsPDF -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721985200121025"> + <bookmark_value>Document service;ExportAsPDF</bookmark_value> + </bookmark> + <h2 id="hd_id261589202100695" localize="false">ExportAsPDF</h2> + <paragraph role="paragraph" id="par_id156589200123048">Exports the document directly as a PDF file to the specified location. Returns <literal>True</literal> if the PDF file was successfully created.</paragraph> + <paragraph role="paragraph" id="par_id811638276067119">The export options can be set either manually using the <menuitem>File - Export As - Export as PDF</menuitem> dialog or by calling the methods <literal>GetPDFExportOptions</literal> and <literal>SetPDFExportOptions</literal> from the <link href="text/sbasic/shared/03/sf_session.xhp" name="SFSession">Session</link> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622827826679"> + <input>svc.ExportAsPDF(filename: str, overwrite: bool = False, opt pages: str, opt password: str, opt watermark: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id211635436910641"><emph>filename</emph>: The full path and file name of the PDF to be created. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id141635436912005"><emph>overwrite</emph>: Specifies if the destination file can be overwritten (Default = <literal>False</literal>). An error will occur if <literal>overwrite</literal> is set to <literal>False</literal> and the destination file already exists.</paragraph> + <paragraph role="paragraph" id="par_id141635436913587"><emph>pages</emph><emph></emph>: String specifying which pages will be exported. This argument uses the same notation as in the dialog <menuitem>File - Export As - Export as PDF</menuitem>.</paragraph> + <paragraph role="paragraph" id="par_id141635436919655"><emph>password</emph><emph></emph>: Specifies a password to open the PDF file.</paragraph> + <paragraph role="paragraph" id="par_id141635436913365"><emph>watermark</emph>: Text to be used as watermark in the PDF file, which will be drawn in every page of the resulting PDF.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id301638234284727">The following example exports the current document as a PDF file, defines a password and overwrites the destination file if it already exists.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891589200127786">oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf", Password := "1234", Overwrite := True)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id311638276257020">The code snippet below gets the current PDF export options and uses them to create the PDF file.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791638277305385">Dim exportSettings as Object, oSession as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51638277174044">oSession = CreateScriptService("Session")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291638277174233">exportSettings = oSession.GetPDFExportOptions()</paragraph> + <paragraph role="bascode" id="bas_id851638277174798">' Sets to True the option to export comments as PDF notes</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71638277174405">exportSettings.ReplaceItem("ExportNotes", True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611638277174622">oSession.SetPDFExportOptions(exportSettings)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461638277174958">oDoc.ExportAsPDF("C:\User\Documents\myFile.pdf")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622728946003">doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf", password = "1234", overwrite = True)</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id481638277330132">session = CreateScriptService("Session")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id881638277330334">exportSettings = oSession.GetPDFExportOptions()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121638277330485">exportSettings.ReplaceItem("ExportNotes", True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id401638277330637">session.SetPDFExportOptions(exportSettings)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id591638277330780">doc.ExportAsPDF(r"C:\User\Documents\myFile.pdf")</paragraph> + </pycode> +</section> + +<section id="PrintOut"> + <comment> PrintOut ---------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721985200121249"> + <bookmark_value>Document service;PrintOut</bookmark_value> + </bookmark> + <h2 id="hd_id261589202101415" localize="false">PrintOut</h2> + <paragraph role="paragraph" id="par_id156589200121138">This method sends the contents of the document to the default printer or to the printer defined by the <literal>SetPrinter</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id981611169416934">Returns <literal>True</literal> if the document was successfully printed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622827822169"> + <input>svc.PrintOut(pages: str = "", copies: num = 1): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id211635436910093"><emph>pages</emph>: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default is all pages.</paragraph> + <paragraph role="paragraph" id="par_id141635436912146"><emph>copies</emph>: The number of copies. Default is 1.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891589200121516">If oDoc.PrintOut("1-4;10;15-18", Copies := 2) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515892500606125"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751682227903730">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622728946898">if doc.PrintOut(copies=3, pages='45-88'):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221628227947414"> # ...</paragraph> + </pycode> +</section> + +<section id="RemoveMenu"> + <comment> RemoveMenu --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200129148"> + <bookmark_value>Document service;RemoveMenu</bookmark_value> + </bookmark> + <h2 id="hd_id261589200121147" localize="false">RemoveMenu</h2> + <paragraph role="paragraph" id="par_id651589200165470">Removes a toplevel menu from the menubar of a given document window.</paragraph> + <paragraph role="paragraph" id="par_id981611149610695">Returns <literal>True</literal> if the specified menu could be removed. If the specified menu does not exist, the method returns <literal>False</literal>.</paragraph> + <note id="par_id571643121106014">This method can be used to remove any menu entry from the document window, including default menus. However, none of these changes in the menubar are saved to the document or to the application settings. To restore the menubar to the default settings, simply close and reopen the document window.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001622887065864"> + <input>svc.RemoveMenu(menuheader: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361589200121156"><emph>menuheader</emph>: The toplevel name of the menu to be removed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891580290121522">Dim oDoc as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id515892005060659">Set oDoc = CreateScriptService("Document")</paragraph> + <paragraph role="bascode" id="bas_id391643120223147">oDoc.RemoveMenu("My Menu")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731622827946155">doc = CreateScriptService("Document")</paragraph> + <paragraph role="pycode" id="pyc_id221622827946338">doc.RemoveMenu("My Menu")</paragraph> + </pycode> + <embed href="text/sbasic/shared/03/sf_document.xhp#menu_tip"/> +</section> + +<section id="RunCommand"> + <comment> RunCommand --------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id601589202413561"> + <bookmark_value>Document 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 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, [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>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> + <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"> + <comment> Save ------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id691589202925124"> + <bookmark_value>Document service;Save</bookmark_value> + </bookmark> + <h2 id="hd_id3615892029256" localize="false">Save</h2> + <paragraph role="paragraph" id="par_id81589202925519">Stores the document to the file location from which it was loaded. The method is ignored if the document was not modified.</paragraph> + <paragraph role="paragraph" id="par_id731611153918907">Returns <literal>False</literal> if the document could not be saved. An error is raised if the file is open as read-only, or if it is a new file that has not been saved yet.</paragraph> + <paragraph role="paragraph" id="par_id211589203690937" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711622828457342"> + <input>svc.Save(): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id31589202925376">If Not oDoc.Save() Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821589203188905"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811622828432150">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id981622828541243">if not doc.Save():</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781622828542374"> # ...</paragraph> + </pycode> +</section> + +<section id="SaveAs"> + <comment> SaveAs --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141589203370367"> + <bookmark_value>Document service;SaveAs</bookmark_value> + </bookmark> + <h2 id="hd_id161589203370594" localize="false">SaveAs</h2> + <paragraph role="paragraph" id="par_id121589203370778">Stores the document to the given file location. The new location becomes the new file name on which simple Save method calls will be applied.</paragraph> + <paragraph role="paragraph" id="par_id31611154475602">Returns <literal>False</literal> if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.</paragraph> + <paragraph role="paragraph" id="par_id391589203370902" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561622828596238"> + <input>svc.SaveAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id331589203370950"><emph>filename</emph>: A string containing the file name to be used. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id631589204010142" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal>, the destination file may be overwritten (default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id811589204084107" xml-lang="en-US"><emph>password</emph> (*): A non-space string to protect the document.</paragraph> + <paragraph role="paragraph" id="par_id451589204163772" xml-lang="en-US"><emph>filtername</emph> (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.</paragraph> + <paragraph role="paragraph" id="par_id981589204207800" xml-lang="en-US"><emph>filteroptions</emph> (*): An optional string of options associated with the filter.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81589203370943">oDoc.SaveAs("C:\Documents\NewCopy.odt", overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id801622828865363">doc.SaveAs(r"C:\Documents\NewCopy.odt", overwrite = True)</paragraph> + </pycode> +</section> + +<section id="SaveCopyAs"> + <comment> SaveCopyAs ------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158920514765"> + <bookmark_value>Document service;SaveCopyAs</bookmark_value> + </bookmark> + <h2 id="hd_id811589205147824" localize="false">SaveCopyAs</h2> + <paragraph role="paragraph" id="par_id911589205147502">Stores a copy of or export the document to the given file location. The actual location is unchanged.</paragraph> + <paragraph role="paragraph" id="par_id381611154800685">Returns <literal>False</literal> if the document could not be saved. An error is raised when overwriting the destination is rejected or when the destination has its read-only attribute set.</paragraph> + <paragraph role="paragraph" id="par_id11589205147643" xml-lang="en-US">The document itself does not need to be active to run this method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561622828596855"> + <input>svc.SaveCopyAs(filename: str, overwrite: bool = False, password: str = '', filtername: str = '', filteroptions: str = ''): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id301589205147697"><emph>filename</emph>: A string containing the file name to be used. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id851589205147348" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal>, the destination file may be overwritten (default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id821589205147330" xml-lang="en-US"><emph>password</emph> (*): A non-space string to protect the document.</paragraph> + <paragraph role="paragraph" id="par_id67158920514729" xml-lang="en-US"><emph>filtername</emph> (*): The name of a filter that should be used for saving the document. If this argument is passed, then the filter must exist.</paragraph> + <paragraph role="paragraph" id="par_id881589205147911" xml-lang="en-US"><emph>filteroptions</emph> (*): An optional string of options associated with the filter.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id431589205147164">oDoc.SaveCopyAs("C:\Documents\Copy2.odt", Overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941622829095519">doc.SaveCopyAs(r"C:\Documents\Copy2.odt", overwrite = True)</paragraph> + </pycode> +</section> + +<section id="SetPrinter"> + <comment> SetPrinter ------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71158921504765"> + <bookmark_value>Document service;SetPrinter</bookmark_value> + </bookmark> + <h2 id="hd_id811589502147824" localize="false">SetPrinter</h2> + <paragraph role="paragraph" id="par_id911298505147502">Defines the printer options for the document.</paragraph> + <paragraph role="paragraph" id="par_id381651114800685">Returns <literal>True</literal> when successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id261652828596855"> + <input>svc.SetPrinter(opt printer: str, opt orientation: str, paperformat: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <section id="setPrinterArgs"> + <paragraph role="paragraph" id="par_id301589205741697"><emph>printer</emph>: The name of the printer queue where to print to. When absent, the default printer is set.</paragraph> + <paragraph role="paragraph" id="par_id851985205147348"><emph>orientation</emph>: Either <literal>PORTRAIT</literal> or <literal>LANDSCAPE</literal>. When absent, left unchanged with respect to the printer settings.</paragraph> + <paragraph role="paragraph" id="par_id821985205147330"><emph>paperformat</emph>: Specifies the paper format as a string value that can be either <literal>A3</literal>, <literal>A4</literal>, <literal>A5</literal>, <literal>LETTER</literal>, <literal>LEGAL</literal> or <literal>TABLOID</literal>. Left unchanged when absent.</paragraph> + </section> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id431589204157164">oDoc.SetPrinter(Orientation := "PORTRAIT")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941628229095519">doc.SetPrinter(paperformat='TABLOID')</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_dictionary.xhp#SFDictionary"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + <embed href="text/sbasic/shared/03/sf_menu.xhp#MenuService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_exception.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_exception.xhp new file mode 100644 index 000000000..416c43457 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_exception.xhp @@ -0,0 +1,459 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + +<meta> + <topic id="SF_Exception" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Exception service (SF_Exception)</title> + <filename>/text/sbasic/shared/03/sf_exception.xhp</filename> + </topic> +</meta> +<body> +<section id="abstract"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id381587139303941"> + <bookmark_value>Exception service</bookmark_value> + </bookmark> + <h1 id="hd_id521580038927003" xml-lang="en-US"><variable id="ExceptionService"><link href="text/sbasic/shared/03/sf_exception.xhp" name="Exception service"><literal>ScriptForge</literal>.<literal>Exception</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181587139648008" xml-lang="en-US">The <literal>Exception</literal> service is a collection of methods to assist in code debugging in Basic and Python scripts and in error handling in Basic scripts.</paragraph> + <paragraph role="paragraph" id="par_id141587140927573" xml-lang="en-US">In <emph>Basic scripts</emph>, when a run-time error occurs, the methods and properties of the <literal>Exception</literal> service help identify the error context and allow to handle it.</paragraph> +</section> + <list type="unordered"> + <listitem> + <paragraph id="par_id401621450898070" role="listitem">The <literal>SF_Exception</literal> service is similar to the <link href="text/sbasic/shared/ErrVBA.xhp" name="VBA Err object">VBA <literal>Err</literal> object</link>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id361621450908874" role="listitem">The <literal>Number</literal> property identifies the error.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id861621450910254" role="listitem">Use the <literal>Raise</literal> method to interrupt processing. The <literal>RaiseWarning</literal> method can be used to trap an anomaly without interrupting the macro execution.</paragraph> + </listitem> + </list> + <tip id="par_id621587225732733" xml-lang="en-US">Errors and warnings raised with the <literal>Exception</literal> service are stored in memory and can be retrieved using the <literal>Console</literal> method.</tip> + + <paragraph role="paragraph" id="par_id411587141146677" xml-lang="en-US">The <literal>Exception</literal> service console stores events, variable values and information about errors. Use the console when the Basic IDE is not easily accessible, for example in <link href="text/scalc/guide/userdefined_function.xhp" name="Calc user-defined function">Calc user defined functions (UDF)</link> or during events processing.</paragraph> + <paragraph role="paragraph" id="par_id251621034725811">Use the <literal>DebugPrint</literal> method to add any relevant information to the console. Console entries can be dumped to a text file or visualized in a dialog window.</paragraph> + <paragraph role="paragraph" id="par_id111587141158495" xml-lang="en-US">When an error occurs, an application macro may:</paragraph> + <list type="ordered"> + <listitem><paragraph role="paragraph" id="par_id451587141202844" xml-lang="en-US">Report the error in the <literal>Exception</literal> console</paragraph></listitem> + <listitem><paragraph role="paragraph" id="par_id751587141235313" xml-lang="en-US">Inform the user about the error using either a standard message or a custom message</paragraph></listitem> + <listitem><paragraph role="paragraph" id="par_id931587141260777" xml-lang="en-US">Optionally stop its execution</paragraph></listitem> + </list> + <paragraph role="paragraph" id="par_id771621035263403">In <emph>Python scripts</emph> the <literal>Exception</literal> service is mostly used for debugging purposes. Methods such as <literal>DebugPrint</literal>, <literal>Console</literal> and <literal>DebugDisplay</literal> are useful to quickly print messages, log data and open the console window from within a Python script.</paragraph> + <note id="par_id211621035276160">Not all methods and properties are available for Python scripts since the Python language already has a comprehensive exception handling system.</note> + + <h2 id="hd_id201586594659135" xml-lang="en-US">Service invocation</h2> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id161610652161795">The following examples show three different approaches to call the method <literal>Raise</literal>. All other methods can be executed in a similar fashion.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id881610652359633">SF_Exception.Raise(...)</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id441586594733346">Dim exc : exc = SF_Exception</paragraph> + <paragraph role="bascode" localize="false" id="bas_id481586594739978">exc.Raise(...)</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id431586594750461">Dim exc : exc = CreateScriptService("Exception")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471586594758689">exc.Raise(...)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id901621036227048">The code snippet below creates an instance of the <literal>Exception</literal> service, logs a message and displays the <literal>Console</literal> window.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id651621036305969">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101621036327340">exc = CreateScriptService("Exception")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id71621036480430">someVar = 100</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id291621036366532">exc.DebugPrint("Value of someVar", someVar)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411621036455976">exc.Console()</paragraph> + </pycode> + + <h2 id="hd_id651584978211886" xml-lang="en-US">Properties</h2> + <paragraph role="paragraph" id="par_id911621036526404">The properties listed below are only available for <emph>Basic</emph> scripts.</paragraph> + <table id="tab_id761584978211275"> + <tablerow> + <tablecell> + <paragraph id="par_id271584978211792" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id241584978211550" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621584978211403" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id581584978715552" role="tablecontent" localize="false">Description</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71584978715562" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581584978715701" role="tablecontent" xml-lang="en-US">The error message text.</paragraph> + <paragraph role="paragraph" id="par_id241610652688334">Default value is "" or a string containing the Basic run-time error message.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id91584978211231" role="tablecontent" localize="false">Number</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211584978211383" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id691584978211774" role="tablecontent" xml-lang="en-US">The code of the error. It can be a numeric value or text.</paragraph> + <paragraph role="paragraph" id="par_id151610652632828">Default value is 0 or the numeric value corresponding to the Basic run-time error code.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id1001584978666440" role="tablecontent" localize="false">Source</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id671584978666689" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951584978666296" role="tablecontent" xml-lang="en-US">The location in the code where the error occurred. It can be a numeric value or text.</paragraph> + <paragraph role="paragraph" id="par_id681610652723345">Default value is 0 or the code line number for a standard Basic run-time error.</paragraph> + </tablecell> + </tablerow> + </table> + <tip id="par_id461584978880380" xml-lang="en-US">Raising or clearing an <literal>Exception</literal> resets its properties.</tip> + <embed href="text/sbasic/shared/ErrVBA.xhp#RestrictedErrorCodes"/> + + <table id="tab_id441608131596153"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id881608131596153" role="tablehead">List of Methods in the Exception Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id461608131596153" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_exception.xhp#Clear" name="Clear method">Clear</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#Console" name="Console method">Console</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#ConsoleClear" name="ConsoleClear method">ConsoleClear</link> + </paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="par_id871608132025242" localize="false"> + <link href="text/sbasic/shared/03/sf_exception.xhp#ConsoleToFile" name="ConsoleToFile method">ConsoleToFile</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#DebugDisplay" name="DebugDisplay method">DebugDisplay</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#DebugPrint" name="DebugPrint method">DebugPrint</link><br/><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" id="par_id831608132069033" localize="false"> + <link href="text/sbasic/shared/03/sf_exception.xhp#PythonPrint" name="PythonPrint method">PythonPrint</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#PythonShell" name="PythonShell method">PythonShell</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#Raise" name="Raise method">Raise</link><br/> + <link href="text/sbasic/shared/03/sf_exception.xhp#RaiseWarning" name="RaiseWarning method">RaiseWarning</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + +<section id="Clear"> + <comment> Clear -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id121582203710297"> + <bookmark_value>Exception service;Clear</bookmark_value> + </bookmark> + <h2 id="hd_id791579683635979" localize="false">Clear</h2> + <paragraph role="paragraph" id="par_id271579683706571">Resets the current error status and clears the <literal>SF_Exception</literal> properties.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531579684617249">SF_Exception.Clear()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id701610654263121">The following example shows how to catch a division-by-zero exception, whose error code is 11.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id631579688532444">Sub Example_Clear()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721587215452594"> Dim a, b, c</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431587221926496"> On Local Error GoTo Catch</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541601735163562"> Try:</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441587215463149"> a = 10 : b = 0</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531587215470406"> c = a / b</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361587215477209"> '...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931587215483393"> Exit Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851587215489779"> Catch:</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771587215496761"> If SF_Exception.Number = 11 Then SF_Exception.Clear()</paragraph> + <paragraph role="bascode" id="bas_id51587215508130" xml-lang="en-US"> 'If division by zero, ignore the error</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801579688542131">End Sub</paragraph> + </bascode> + <tip id="par_id201610654368082">For a complete list of Basic run-time error codes, refer to <link href="text/sbasic/shared/01030300.xhp" name="Run-Time Error Codes">Debugging a Basic Program</link>.</tip> +</section> + +<section id="Console"> + <comment> Console -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id9159871817936"> + <bookmark_value>Exception service;Console</bookmark_value> + </bookmark> + <h2 id="hd_id971598718179751" localize="false">Console</h2> + <paragraph role="paragraph" id="par_id651598718179382">Displays the console messages in a modal or non-modal dialog. In both modes, all the past messages issued by a <literal>DebugPrint()</literal> method or resulting from an exception are displayed. In non-modal mode, subsequent entries are added automatically.</paragraph> + <paragraph role="paragraph" id="par_id161598718286205" xml-lang="en-US">If the console is already open, when non-modal, it is brought to the front.</paragraph> + <paragraph role="paragraph" id="par_id801598718629151" xml-lang="en-US">A modal console can only be closed by the user. A non-modal console can either be closed by the user or upon macro termination.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id571621040248589"> + <input>exc.Console(modal: bool = True)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id511598718179819"><emph>modal</emph>: Determine if the console window is modal (<literal>True</literal>) or non-modal (<literal>False</literal>). Default value is <literal>True</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id78159871817999"> SF_Exception.Console(Modal := False)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id621621040451660">exc.Console(modal = False)</paragraph> + </pycode> +</section> + +<section id="ConsoleClear"> + <comment> ConsoleClear -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id621587215098307"> + <bookmark_value>Exception service;ConsoleClear</bookmark_value> + </bookmark> + <h2 id="hd_id671587215098845" localize="false">ConsoleClear</h2> + <paragraph role="paragraph" id="par_id641587215098903">Clears the console keeping an optional number of recent messages. If the console is activated in non-modal mode, it is refreshed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id651621040714152"> + <input>exc.ConsoleClear(keep: int = 0)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id351587215098527"><emph>keep</emph>: The number of recent messages to be kept. Default value is 0.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id521610655023824">The following example clears the console keeping the 10 most recent messages.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id981587215098452"> SF_Exception.ConsoleClear(10)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891621040671870">exc.ConsoleClear(10)</paragraph> + </pycode> +</section> + +<section id="ConsoleToFile"> + <comment> ConsoleToFile -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id911587218077199"> + <bookmark_value>Exception service;ConsoleToFile</bookmark_value> + </bookmark> + <h2 id="hd_id691587218077803" localize="false">ConsoleToFile</h2> + <paragraph role="paragraph" id="par_id281587218077400">Exports the contents of the console to a text file. If the file already exists and the console is not empty, it will be overwritten without warning. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id171621042623495"> + <input>exc.ConsoleToFile(filename: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id851587218077862"><emph>filename</emph>: The name of the text file the console should be dumped into. The name is expressed according to the current <literal>FileNaming</literal> property of the <literal>SF_FileSystem</literal> service. By default, <link href="text/sbasic/shared/00000002.xhp" name="Url notation">URL notation</link> and the native operating system's format are both admitted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id941587218077971"> SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id901621041580099">exc.ConsoleToFile(r"C:\Documents\myFile.txt")</paragraph> + </pycode> +</section> + +<section id="DebugDisplay"> + <comment> DebugDisplay -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id591587218637462"> + <bookmark_value>Exception service;DebugDisplay</bookmark_value> + </bookmark> + <h2 id="hd_id691587218077177" localize="false">DebugDisplay</h2> + <paragraph role="paragraph" id="par_id701621043185177">Concatenates all the arguments into a single human-readable string and displays it in a <literal>MsgBox</literal> with an Information icon and an OK button.</paragraph> + <paragraph role="paragraph" id="par_id791621097689492">The final string is also added to the Console.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id461621042840877"> + <input>exc.DebugDisplay(arg0: any, [arg1: any, ...])</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481587218636884"><emph>arg0[, arg1, ...]</emph>: Any number of arguments of any type.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id871621043432964">SF_Exception.DebugDisplay("Current Value", someVar)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id501621043522869">exc.DebugDisplay("Current Value", someVar)</paragraph> + </pycode> +</section> + +<section id="DebugPrint"> + <comment> DebugPrint -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id591587218637462"> + <bookmark_value>Exception service;DebugPrint</bookmark_value> + </bookmark> + <h2 id="hd_id981587218637683" localize="false">DebugPrint</h2> + <paragraph role="paragraph" id="par_id281587218637490">Assembles all the given arguments into a single human-readable string and adds it as a new entry in the console.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id461621042840764"> + <input>exc.DebugPrint(arg0: any, [arg1: any, ...])</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481587218637988"><emph>arg0[, arg1, ...]</emph>: Any number of arguments of any type.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id58158721863732">SF_Exception.DebugPrint(Null, Array(1, 2, 3), "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151610655617295">' [NULL] [ARRAY] (0:2) (1, 2, 3) line1\nLine2 2020-04-09</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id591621043074050">exc.DebugPrint(None, [1, 2, 3], "line1\nline2")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id161621098073293"># None [1, 2, 3] line1\nline2</paragraph> + </pycode> +</section> + +<section id="PythonPrint"> + <comment> PythonPrint -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id301587219428104"> + <bookmark_value>Exception service;PythonPrint</bookmark_value> + </bookmark> + <h2 id="hd_id5515879128204789" localize="false">PythonPrint</h2> + <paragraph role="paragraph" id="par_id111621624672183">Displays the list of arguments in a readable form in the Python shell (APSO) console. Arguments are separated by a TAB character (simulated by spaces).</paragraph> + <paragraph role="paragraph" id="par_id841621426229467">The same string is added to the ScriptForge debug console.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81630591881423">exc.PythonPrint(arg0: any, [arg1: any, ...])</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#Requires_APSO"/> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id391126449167833"><emph>arg0[, arg1, ...]</emph>: Any number of arguments of any type. The maximum length of each individual argument is 1024 characters.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="pyc_id451621479450230">exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))</paragraph> + </bascode> + <note id="par_id261123015276160">In python use simply the builtin print() statement.</note> +</section> + +<section id="PythonShell"> + <comment> PythonShell -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id301587219824104"> + <bookmark_value>Exception service;PythonShell</bookmark_value> + </bookmark> + <h2 id="hd_id5515872198204789" localize="false">PythonShell</h2> + <paragraph role="paragraph" id="par_id111621426672183">Opens an APSO Python shell as a non-modal window. The Python script keeps running after the shell is opened. The output from <literal>print</literal> statements inside the script are shown in the shell.</paragraph> + <paragraph role="paragraph" id="par_id841621426922467">Only a single instance of the APSO Python shell can be opened at any time. Hence, if a Python shell is already open, then calling this method will have no effect.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#Requires_APSO"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id411621625580764"> + <input>exc.PythonShell(variables: dict)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id391621449167833"><emph>variables</emph>: a Python dictionary with variable names and values that will be passed on to the APSO Python shell. By default all local variables are passed using Python's builtin <literal>locals()</literal> function.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id991621449657850">The example below opens the APSO Python shell passing all global and local variables considering the context where the script is running.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id451621449750230">exc.PythonShell({**globals(), **locals()})</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id521621449800348">When the APSO Python shell is open, any subsequent output printed by the script will be shown in the shell. Hence, the string printed in the example below will be displayed in the Python shell.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id441621449844658">exc.PythonShell()</paragraph> + <paragraph role="pycode" id="pyc_id731621449899901">print("Hello world!")</paragraph> + </pycode> +</section> + +<section id="Raise"> + <comment> Raise -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id301587219824932"> + <bookmark_value>Exception service;Raise</bookmark_value> + </bookmark> + <h2 id="hd_id551587219824275" localize="false">Raise</h2> + <paragraph role="paragraph" id="par_id541587219824771">Generates a run-time error. An error message is displayed to the user and reported in the console. The execution is stopped. The <literal>Raise()</literal> method can be placed inside the normal script flow or in a dedicated error-handling routine.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id29158721982455">SF_Exception.Raise([Number As Variant], [Source As Variant], [Description As String])</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id921587220542454" xml-lang="en-US">The code snippets presented next are equivalent. They show alternative ways to raise an exception with code 2100.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id881587220508733">SF_Exception.Raise(2100)</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id361587220516558">SF_Exception.Number = 2100</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51587220525168">SF_Exception.Raise()</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" id="bas_id491608216264445" localize="false">SF_Exception.Raise Number := 2100</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <section id="Raise_Parameters"> + <paragraph role="paragraph" id="par_id851587219824597"><emph>Number</emph>: The error code, as a number or as a string. Default value is that of <literal>Err</literal> Basic builtin function.</paragraph> + <paragraph role="paragraph" id="par_id461587220986452" xml-lang="en-US"><emph>Source</emph>: The location of the error, as a number or as a string. Default value is that of <literal>Erl</literal> Basic builtin function.</paragraph> + <paragraph role="paragraph" id="par_id721587221018162" xml-lang="en-US"><emph>Description</emph>: The message to display to the user and to report in the console. Default value is that of <literal>Error$</literal> Basic builtin function.</paragraph> + </section> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id101587221964367">Sub Example_Raise()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681587221964375"> Dim a, b, c</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811587221964318"> On Local Error GoTo Catch</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511601735068745"> Try:</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831587221964580"> a = 10 : b = 0</paragraph> + <paragraph role="bascode" localize="false" id="bas_id4115872219641"> c = a / b</paragraph> + <paragraph role="bascode" localize="false" id="bas_id85158722196499"> '...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241587221964418"> Exit Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721587221964962"> Catch:</paragraph> + <paragraph role="bascode" id="bas_id211587222852310" xml-lang="en-US"> 'See variants below ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61587221964946">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id111587222580987" xml-lang="en-US">To raise an exception with the standard values:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id341587222627299">Catch:</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261587222635009"> SF_Exception.Raise()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id751587222598238" xml-lang="en-US">To raise an exception with a specific code:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id421587222644102">Catch:</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171587222653391"> SF_Exception.Raise(11)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id501587222607771" xml-lang="en-US">To replace the usual message:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id721587222663630">Catch:</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id431587222670849"> SF_Exception.Raise(, , "It is not a good idea to divide by zero.")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id611587222617174" xml-lang="en-US">To raise an application error:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id441587222684053">Catch:</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id71587222694657"> SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !")</paragraph> + </bascode> +</section> + +<section id="RaiseWarning"> + <comment> RaiseWarning -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id811587224839918"> + <bookmark_value>Exception service;RaiseWarning</bookmark_value> + </bookmark> + <h2 id="hd_id391587224839449" localize="false">RaiseWarning</h2> + <paragraph role="paragraph" id="par_id1001587224839900" xml-lang="en-US">This method has exactly the same syntax, arguments and behavior as the <literal>Raise()</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id761587224839624" xml-lang="en-US">However, when a warning is raised, <emph>the macro execution is not stopped</emph>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id25197821982455">SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <embed href="text/sbasic/shared/03/sf_exception.xhp#Raise_Parameters"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id71587222649657">SF_Exception.RaiseWarning(Source:="Example_Raise()", _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841608217948025"> Description:="Something wrong happened !", _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361608217956289"> Number:="MyAppError")</paragraph> + </bascode> +</section> + +<section id="relatedtopics"> + <embed href="text/sbasic/shared/03050000.xhp#ErrHandlingh1"/> +</section> + +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_filesystem.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_filesystem.xhp new file mode 100644 index 000000000..9461b7604 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_filesystem.xhp @@ -0,0 +1,1129 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_FileSystem" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.FileSystem service</title> + <filename>/text/sbasic/shared/03/sf_filesystem.xhp</filename> + </topic> +</meta> + +<body> +<section id="ScriptForge-sf_filesystem"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>FileSystem service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="FileSystemService"><link href="text/sbasic/shared/03/sf_filesystem.xhp" name="FileSystem service"><literal>ScriptForge</literal>.<literal>FileSystem</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id931583589764919" xml-lang="en-US">The <literal>FileSystem</literal> service includes routines to handle files and folders. Next are some examples of the features provided by this service:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id121612917070593" role="listitem">Verify whether a file or folder exists.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id121612917070594" role="listitem">Create and delete folders and files.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id121612917070595" role="listitem">Launch dialog boxes to open/save files.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id121612917070596" role="listitem">Access the list of files in a folder, etc.</paragraph> + </listitem> + </list> +</section> + <note id="par_id121612917368946">The methods in the FileSystem service are mostly based on the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1ucb_1_1XSimpleFileAccess.html" name="XSimpleFileAccess API"><literal>XSimpleFileAccess</literal> UNO interface.</link></note> + + <h2 id="hd_id961583589783025" xml-lang="en-US">Definitions</h2> + <paragraph role="paragraph" id="par_id821612988815351">The table below lists the main parameters used by most of the methods in the <literal>FileSystem</literal> service.</paragraph> + <table id="tab_id721612988600163"> + <tablerow> + <tablecell> + <paragraph id="par_id891612988600163" role="tablehead">Parameter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612988600163" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181612988600163" role="tablecontent" localize="false"><literal>FileName</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321612988600163" role="tablecontent">The full name of the file including the path without a path separator at the end.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181612988600164" role="tablecontent" localize="false"><literal>FolderName</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321612988600165" role="tablecontent">The full name of the folder including the path. It may or may not contain the ending path separator.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181612988600166" role="tablecontent" localize="false"><literal>Name</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321612988600167" role="tablecontent">The last component of the <emph>Folder Name</emph> or <emph>File Name</emph> including its extension. This parameter is always expressed using the native format of the operating system.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181612988600168" role="tablecontent" localize="false"><literal>BaseName</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321612988600169" role="tablecontent">The last component of the <emph>Folder Name</emph> or <emph>File Name</emph> without its extension.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181612988600171" role="tablecontent" localize="false"><literal>NamePattern</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321612988600172" role="tablecontent">Any of the above names containing wildcards in its last component. Admitted wildcards are:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id851583590809104" role="listitem" xml-lang="en-US">"?" represents any single character</paragraph> + </listitem> + <listitem> + <paragraph id="par_id161583590819320" role="listitem" xml-lang="en-US">"*" represents zero, one, or multiple characters</paragraph> + </listitem> + </list> + </tablecell> + </tablerow> + </table> + <tip id="par_id911584540527980" xml-lang="en-US">The <literal>FileSystem</literal> service allows to perform operations over multiple files at the same time. By using name patterns, user scripts can copy, move or delete multiple files. Conversely, Basic built-in methods can only handle single files.</tip> + + <h3 id="hd_id991612918109871">File Naming Notation</h3> + <paragraph role="paragraph" id="par_id791612918141083">The notation used to express file and folder names, both for arguments and returned values, is defined by the <literal>FileNaming</literal> property of the <literal>FileSystem</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id951612918220255">In short, the possible representation types are "URL" (URL file notation), "SYS" (operating system notation) and "ANY" (default). See more information <link href="text/sbasic/shared/03/sf_filesystem.xhp#properties" name="Properties Table">below</link>.</paragraph> + <tip id="par_id861583589907100" xml-lang="en-US">An example of the URL notation is <emph>file:///C:/Documents/my_file.odt</emph>. Whenever possible consider using the URL notation because it is a more portable alternative.</tip> + <warning id="par_id931626652451855">The use of the shortcut "~" (tilde), which is common in Linux-based operating systems, is not supported to express a path to a folder and file name. Instead of using <emph>"~/Documents/my_file.odt"</emph> use the full path <emph>"/home/user/Documents/my_file.odt"</emph>.</warning> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id691612990276070">The following code snippet invokes the <literal>FileSystem</literal> service. The method <literal>BuildPath</literal> was used as an example.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id551610734764343">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim FSO As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201582885621287">Set FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901612990364784">FSO.BuildPath(...)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id301626147154020">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771626147154696">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741626147154953">fs.BuildPath(...)</paragraph> + </pycode> + + <bookmark xml-lang="en-US" branch="index" id="bm_id901612991354326" localize="false"> + <bookmark_value>FileSystem service;FileNaming property</bookmark_value> + <bookmark_value>FileSystem service;ConfigFolder property</bookmark_value> + <bookmark_value>FileSystem service;ExtensionsFolder property</bookmark_value> + <bookmark_value>FileSystem service;HomeFolder property</bookmark_value> + <bookmark_value>FileSystem service;InstallFolder property</bookmark_value> + <bookmark_value>FileSystem service;TemplatesFolder property</bookmark_value> + <bookmark_value>FileSystem service;TemporaryFolder property</bookmark_value> + <bookmark_value>FileSystem service;UserTemplatesFolder property</bookmark_value> + </bookmark> + <h2 id="hd_id651583668365757" xml-lang="en-US">Properties</h2> + <section id="properties"> + <table id="tab_id381583668386455"> + <tablerow> + <tablecell> + <paragraph id="par_id871583668386455" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491583668386455" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668474014" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401583668386455" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151583668386455" role="tablecontent" xml-lang="en-US" localize="false">FileNaming</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371583668519172" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668386455" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583668386455" role="tablecontent" xml-lang="en-US">Sets or returns the current files and folders notation, either "ANY", "URL" or "SYS":</paragraph> + <list type="unordered"> + <listitem> + <paragraph role="paragraph" id="par_id881585396501844" xml-lang="en-US"><emph>"ANY"</emph>: (default) the methods of the <literal>FileSystem</literal> service accept both URL and current operating system's notation for input arguments but always return URL strings.</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id261583669091722" xml-lang="en-US"><emph>"URL"</emph>: the methods of the <literal>FileSystem</literal> service expect URL notation for input arguments and return URL strings.</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id731583669120436" xml-lang="en-US"><emph>"SYS"</emph>: the methods of the <literal>FileSystem</literal> service expect current operating system's notation for both input arguments and return strings.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id211583765169579" xml-lang="en-US">Once set, the <literal>FileNaming</literal> property remains unchanged either until the end of the %PRODUCTNAME session or until it is set again.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951583839708571" role="tablecontent" xml-lang="en-US" localize="false">ConfigFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541583839708548" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751583839708362" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731583839708412" role="tablecontent" xml-lang="en-US">Returns the configuration folder of %PRODUCTNAME.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511584027709311" role="tablecontent" xml-lang="en-US" localize="false">ExtensionsFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761584027709516" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491584027709825" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971584027709752" role="tablecontent" xml-lang="en-US">Returns the folder where extensions are installed.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583839767611" role="tablecontent" xml-lang="en-US" localize="false">HomeFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31583839767743" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741583839767926" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839767195" role="tablecontent" xml-lang="en-US">Returns the user home folder.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83158383992056" role="tablecontent" xml-lang="en-US" localize="false">InstallFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583839920487" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971583839920282" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451583839920858" role="tablecontent" xml-lang="en-US">Returns the installation folder of %PRODUCTNAME.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id751588333908795" role="tablecontent" xml-lang="en-US" localize="false">TemplatesFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571588333908716" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781588333908500" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721588333908708" role="tablecontent" xml-lang="en-US">Returns the folder containing the system templates files.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id251583774433989" role="tablecontent" xml-lang="en-US" localize="false">TemporaryFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501583774433513" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411583774433779" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71583774433459" role="tablecontent" xml-lang="en-US">Returns the temporary files folder defined in the %PRODUCTNAME path settings.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731588334016220" role="tablecontent" xml-lang="en-US" localize="false">UserTemplatesFolder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271588334016191" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991588334016273" role="tablecontent" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251588334016874" role="tablecontent" xml-lang="en-US">Returns the folder containing the user-defined template files.</paragraph> + </tablecell> + </tablerow> + </table> + </section> + +<table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead">List of Methods in the FileSystem Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#BuildPath" name="BuildPath method">BuildPath</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#CompareFiles" name="CompareFiles method">CompareFiles</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#CopyFile" name="CopyFile method">CopyFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#CopyFolder" name="CopyFolder method">CopyFolder</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#CreateFolder" name="CreateFolder method">CreateFolder</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#CreateTextFile" name="CreateTextFile method">CreateTextFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#DeleteFile" name="DeleteFile method">DeleteFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#DeleteFolder" name="DeleteFolder method">DeleteFolder</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#ExtensionFolder" name="ExtensionFolder method">ExtensionFolder</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#FileExists" name="FileExists method">FileExists</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#Files" name="Files method">Files</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#FolderExists" name="FolderExists method">FolderExists</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetBaseName" name="GetBaseName method">GetBaseName</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetExtension" name="GetExtension method">GetExtension</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetFileLen" name="GetFileLen method">GetFileLen</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetFileModified" name="GetFileModified method">GetFileModified</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetName" name="GetName method">GetName</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetParentFolderName" name="GetParentFolderName method">GetParentFolderName</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#GetTempName" name="GetTempName method">GetTempName</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#HashFile" name="HashFile method">HashFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#MoveFile" name="MoveFile method">MoveFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#MoveFolder" name="MoveFolder method">MoveFolder</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#OpenTextFile" name="OpenTextFile method">OpenTextFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#PickFile" name="PickFile method">PickFile</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#PickFolder" name="PickFolder method">PickFolder</link><br/> + <link href="text/sbasic/shared/03/sf_filesystem.xhp#SubFolders" name="SubFolders method">SubFolders</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + +<section id="BuildPath"> + <comment> BuildPath ----------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721583933076548"> + <bookmark_value>FileSystem service;BuildPath</bookmark_value> + </bookmark> + <h2 id="hd_id681583933076692" localize="false">BuildPath</h2> + <paragraph role="paragraph" id="par_id871583933076448">Joins a folder path and the name of a file and returns the full file name with a valid path separator. The path separator is added only if necessary.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id251626147640389"> + <input>svc.BuildPath(foldername: str, name: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id90158393307695"><emph>foldername</emph>: The path with which <literal>name</literal> will be combined. The specified path does not need to be an existing folder.</paragraph> + <paragraph role="paragraph" id="par_id891583933076975"><emph>name</emph>: The name of the file to be appended to <literal>foldername</literal>. This parameter uses the notation of the current operating system.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id571583933076688">Dim FSO as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891626278435709">Set FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771626215559964">Dim aFileName as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271583933076624">FSO.FileNaming = "URL"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531583933076390">aFileName = FSO.BuildPath("file:///home/user", "sample file.odt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591583933645158">' file:///home/user/sample%20file.odt</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id811626215598688">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951626215599055">fs.FileNaming = "URL"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151626215599287">aFileName = fs.BuildPath("file:///home/user", "sample file.odt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id731626215599407"># file:///home/user/sample%20file.odt</paragraph> + </pycode> +</section> + +<section id="CompareFiles"> + <comment> CompareFiles ----------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141601118910914"> + <bookmark_value>FileSystem service;CompareFiles</bookmark_value> + </bookmark> + <h2 id="hd_id441601118910655" localize="false">CompareFiles</h2> + <paragraph role="paragraph" id="par_id33160111891079">Compares two files and returns <literal>True</literal> when they seem identical.</paragraph> + <paragraph role="paragraph" id="par_id631601119001315" xml-lang="en-US">Depending on the value of the <literal>comparecontents</literal> argument, the comparison between both files can be either based only on file attributes (such as the last modified date), or based on the file contents.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id61626148854349"> + <input>svc.CompareFiles(filename1: str, filename2: str, comparecontents: bool = False): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481601118910755"><emph>filename1, filename2</emph>: The files to compare.</paragraph> + <paragraph role="paragraph" id="par_id111601118910848" xml-lang="en-US"><emph>comparecontents</emph>: When <literal>True</literal>, the contents of the files are compared (default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id231601118910666">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101601118910778">If FSO.CompareFiles("C:\myFile1.txt", "C:\myFile2.txt", CompareContents := False) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171601123413866"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271612997571657">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id341626215746128">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141626215746355">if fs.CompareFiles(r"C:\myFile1.txt", r"C:\myFile2.txt", comparecontents = False):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111626215746495"> # ...</paragraph> + </pycode> +</section> + +<section id="CopyFile"> + <comment> CopyFile ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584541257826"> + <bookmark_value>FileSystem service;CopyFile</bookmark_value> + </bookmark> + <h2 id="hd_id95158454125767" localize="false">CopyFile</h2> + <paragraph role="paragraph" id="par_id161584541257982">Copies one or more files from one location to another. Returns <literal>True</literal> if at least one file has been copied or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id401612998805699">An error will also occur if the <literal>source</literal> parameter uses wildcard characters and does not match any files.</paragraph> + <paragraph role="paragraph" id="par_id331612998814805">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id611626148998301"> + <input>svc.CopyFile(source: str, destination: str, overwrite: bool = True): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257789"><emph>source</emph>: It can be a <literal>FileName</literal> or a <literal>NamePattern</literal> indicating one or more files to be copied.</paragraph> + <paragraph role="paragraph" id="par_id111584542310166" xml-lang="en-US"><emph>destination</emph>: It can be either a <literal>FileName</literal> specifying where the single <literal>source</literal> file is to be copied, or a <literal>FolderName</literal> into which the multiple files from <literal>source</literal> are to be copied.</paragraph> + <list type="unordered"> + <listitem> + <paragraph role="paragraph" id="par_id491612999134752">If <literal>destination</literal> does not exist, it is created.</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id591612999166788">Wildcard characters are not allowed in <literal>destination</literal>.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id251584542431558" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal> (default), files may be overwritten. The method will fail if <literal>destination</literal> is readonly, regardless of the value specified in <literal>overwrite</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id691626216252568">In the examples below the first line copies a single file whereas the second line copies multiple files using wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851613000918341">FSO.CopyFile("C:\Documents\my_file.odt", "C:\Temp\copied_file.odt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501584541257221">FSO.CopyFile("C:\Documents\*.*", "C:\Temp\", Overwrite := False)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id471626216422324">fs.CopyFile(r"C:\Documents\my_file.odt", r"C:\Temp\copied_file.odt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141626216422517">fs.CopyFile(r"C:\Documents\*.*", r"C:\Temp", overwrite = False)</paragraph> + </pycode> + <note id="par_id411626216328023">Beware that subfolders and their contents are not copied when wildcards are used in the <emph>source</emph> argument.</note> +</section> + +<section id="CopyFolder"> + <comment> CopyFolder ----------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id661584544734386"> + <bookmark_value>FileSystem service;CopyFolder</bookmark_value> + </bookmark> + <h2 id="hd_id201584544734113" localize="false">CopyFolder</h2> + <paragraph role="paragraph" id="par_id731584544734412">Copies one or more folders from one location to another. Returns <literal>True</literal> if at least one folder has been copied or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id21612999775377">An error will also occur if the <literal>source</literal> parameter uses wildcard characters and does not match any folders.</paragraph> + <paragraph role="paragraph" id="par_id701612999808912">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id381626149136823"> + <input>svc.CopyFolder(source: str, destination: str, overwrite: bool = True): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id851584544734202"><emph>source</emph>: It can be a <literal>FolderName</literal> or a <literal>NamePattern</literal> indicating one or more folders to be copied.</paragraph> + <paragraph role="paragraph" id="par_id321584544734273" xml-lang="en-US"><emph>destination</emph>: Specifies the <literal>FolderName</literal> into which the single or multiple folders defined in <literal>source</literal> are to be copied.</paragraph> + <list type="unordered"> + <listitem> + <paragraph role="paragraph" id="par_id491612999134762">If <literal>destination</literal> does not exist, it is created.</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id591612999166740">Wildcard characters are not allowed in <literal>destination</literal>.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id251584542431525" xml-lang="en-US"><emph>overwrite</emph>: If <literal>True</literal> (default), files may be overwritten. The method will fail if <literal>destination</literal> is readonly, regardless of the value specified in <literal>overwrite</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id751626216627481">In the examples below all files, folders and subfolders are copied.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id761584882338442">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651584544734985">FSO.CopyFolder("C:\Documents\*", "C:\Temp\", Overwrite := False)</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id431626216707056"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771626216707454">fs.CopyFolder(r"C:\Documents\*", r"C:\Temp", overwrite = False)</paragraph> + </pycode> +</section> + +<section id="CreateFolder"> + <comment> CreateFolder -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id95158454067521"> + <bookmark_value>FileSystem service;CreateFolder</bookmark_value> + </bookmark> + <h2 id="hd_id501584540675285" localize="false">CreateFolder</h2> + <paragraph role="paragraph" id="par_id31158454067562">Creates the specified <literal>FolderName</literal>. Returns <literal>True</literal> if the folder could be successfully created.</paragraph> + <paragraph role="paragraph" id="par_id431613000475359">If the specified folder has a parent folder that does not exist, it is created.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id531626177201641"> + <input>svc.CreateFolder(foldername: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id491584540675469"><emph>foldername</emph>: A string representing the folder to be created. If the folder already exists, an exception will be raised.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id441584540675381">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491584540675179">FSO.CreateFolder("C:\NewFolder")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id971626216947436"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181626216947810">fs.CreateFolder(r"C:\NewFolder")</paragraph> + </pycode> +</section> + +<section id="CreateTextFile"> + <comment> CreateTextFile ------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id651585322689546"> + <bookmark_value>FolderSystem service;CreateTextFile</bookmark_value> + </bookmark> + <h2 id="hd_id19158532268911" localize="false">CreateTextFile</h2> + <paragraph role="paragraph" id="par_id731585322689518">Creates a specified file and returns a <literal>TextStream</literal> service instance that can be used to write to the file.</paragraph> + <paragraph role="paragraph" id="par_id821613001057759">The method returns a <literal>Null</literal> object if an error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id431626178025633"> + <input>svc.CreateTextFile(filename: str, overwrite: bool = True, encoding: str = 'UTF-8'): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id901585322689715"><emph>filename</emph>: The name of the file to be created.</paragraph> + <paragraph role="paragraph" id="par_id501585322689209"><emph>overwrite</emph>: Boolean value that determines if <literal>filename</literal> can be overwritten (default = <literal>True</literal>).</paragraph> + <paragraph role="paragraph" id="par_id551585322689192"><emph>encoding</emph>: The character set to be used. The default encoding is "UTF-8".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id291585322689770">Dim myFile As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541585322689351">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51585322689982">Set myFile = FSO.CreateTextFile("C:\Temp\ThisFile.txt", Overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id291626217084462">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251626217084848">myFile = fs.CreateTextFile(r"C:\Temp\ThisFile.txt", overwrite = True)</paragraph> + </pycode> + <note id="par_id141613001281573">To learn more about the names of character sets, visit <link href="https://www.iana.org/assignments/character-sets/character-sets.xhtml" name="Character Sets">IANA's Character Set</link> page. Beware that %PRODUCTNAME does not implement all existing character sets.</note> +</section> + +<section id="DeleteFile"> + <comment> DeleteFile -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id421584882040621"> + <bookmark_value>FileSystem service;DeleteFile</bookmark_value> + </bookmark> + <h2 id="hd_id191584882040749" localize="false">DeleteFile</h2> + <paragraph role="paragraph" id="par_id11584882040881">Deletes one or more files. Returns <literal>True</literal> if at least one file has been deleted or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id21612999775356">An error will also occur if the <literal>filename</literal> parameter uses wildcard characters and does not match any files.</paragraph> + <paragraph role="paragraph" id="par_id21613001848493">The files to be deleted must not be readonly.</paragraph> + <paragraph role="paragraph" id="par_id701612999808832">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id11626178195995"> + <input>svc.DeleteFile(filename: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441584882040860"><emph>filename</emph>: It can be a <literal>FileName</literal> or a <literal>NamePattern</literal> indicating one or more files to be deleted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id851626217167909">In the examples below only files are deleted, subfolders are not deleted.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id321584882040274">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501584882040356">FSO.DeleteFile("C:\Temp\*.docx")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id41626217239069"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id491626217239297">fs.DeleteFile(r"C:\Temp\*.docx")</paragraph> + </pycode> +</section> + +<section id="DeleteFolder"> + <comment> DeleteFolder -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id91584882542710"> + <bookmark_value>FileSystem service;DeleteFolder</bookmark_value> + </bookmark> + <h2 id="hd_id151584882542309" localize="false">DeleteFolder</h2> + <paragraph role="paragraph" id="par_id11584882015881">Deletes one or more folders. Returns <literal>True</literal> if at least one folder has been deleted or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id21612999775346">An error will also occur if the <literal>foldername</literal> parameter uses wildcard characters and does not match any folders.</paragraph> + <paragraph role="paragraph" id="par_id21613001848853">The folders to be deleted must not be readonly.</paragraph> + <paragraph role="paragraph" id="par_id701612999808842">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id61626178267917"> + <input>svc.DeleteFolder(foldername: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451584882542247"><emph>foldername</emph>: It can be a <literal>FolderName</literal> or a <literal>NamePattern</literal> indicating one or more folders to be deleted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id651626217314709">In the examples below only folders and their contents are deleted. Files in the parent folder "C:\Temp" are not deleted.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id751584882542695">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611584882542154">FSO.DeleteFolder("C:\Temp\*")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id441626217397570"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id371626217398060">fs.DeleteFolder(r"C:\Temp\*")</paragraph> + </pycode> +</section> + +<section id="ExtensionFolder"> + <comment> ExtensionFolder --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id91584882542365"> + <bookmark_value>FileSystem service;ExtensionFolder</bookmark_value> + </bookmark> + <h2 id="hd_id151584882542104" localize="false">ExtensionFolder</h2> + <paragraph role="paragraph" id="par_id11584882015025">Returns a string containing the folder where the specified extension package is installed.</paragraph> + <paragraph role="paragraph" id="par_id21612999775311">The current value of the property <literal>SF_FileSystem.FileNaming</literal> is used to determine the notation of the returned string.</paragraph> + <tip id="par_id891644442917193">Use the property <link href="text/sbasic/shared/03/sf_platform.xhp#hd_id711600788076834" name="Extensions_link"><literal>Extensions</literal></link> from the <literal>Platform</literal> service to get string array with the IDs of all installed extensions.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id61626178211365"> + <input>svc.ExtensionFolder(extension: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451584882542121"><emph>extension</emph>: A string value with the ID of the extension. If the extension is not installed, an exception is raised.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id651626217313369">The examples below in Basic and Python return the folder where the APSO extension is installed.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id116444434113410">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751584882540355">sFolder = FSO.ExtensionFolder("apso.python.script.organizer")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611584882542269">' file:///home/username/.config/libreoffice/4/user/uno_packages/cache/uno_packages/lu10833wz3u2i.tmp_/apso_1_2_7.oxt</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id441626217397588"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id371626217398166">sFolder = fs.ExtensionFolder("apso.python.script.organizer")</paragraph> + </pycode> +</section> + +<section id="FileExists"> + <comment> FileExists --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571583764426508"> + <bookmark_value>FileSystem service;FileExists</bookmark_value> + </bookmark> + <h2 id="hd_id39158376442641" localize="false">FileExists</h2> + <paragraph role="paragraph" id="par_id161583764426709">Returns <literal>True</literal> if a given file name is valid and exists, otherwise the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id91613003122613">If the <literal>filename</literal> parameter is actually an existing folder name, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id201626178344527"> + <input>svc.FileExists(filename: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id361583764426547"><emph>filename</emph>: A string representing the file to be tested.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id621583764787755">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821583764426197">If FSO.FileExists("C:\Documents\my_file.odt") Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191613003283635"> '...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891613003291580">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551626270512839">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411626270513159">if fs.FileExists(r"C:\Documents\my_file.odt"):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id591626270513425"> # ...</paragraph> + </pycode> +</section> + +<section id="Files"> + <comment> Files ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id771583944327771"> + <bookmark_value>FileSystem service;Files</bookmark_value> + </bookmark> + <h2 id="hd_id461583944327647" localize="false">Files</h2> + <paragraph role="paragraph" id="par_id11158394432779">Returns a zero-based array of the files stored in a given folder. Each entry in the array is a string containing the full path and file name.</paragraph> + <paragraph role="paragraph" id="par_id641613003790120">If the argument <literal>foldername</literal> specifies a folder that does not exist, an exception is raised.</paragraph> + <paragraph role="paragraph" id="par_id821613003779799">The resulting list may be filtered with wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id211626178396995"> + <input>svc.Files(foldername: str, filter: str = ''): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id731583944543140"><emph>foldername</emph>: A string representing a folder. The folder must exist. This argument must not designate a file.</paragraph> + <paragraph role="paragraph" id="par_id591585648450060" xml-lang="en-US"><emph>filter</emph>: A string containing wildcards ("?" and "*") that will be applied to the resulting list of files (default = "").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id381583944327923">Dim filesList As Variant, file As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581583944327968">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id451583944327508">filesList = FSO.Files("/home/user/", "*.txt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id521583944732086">For Each file In filesList</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421583944743304"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721583944748672">Next file</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id811626270625785">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id761626270626093">filesList = fs.Files("/home/user/", "*.txt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381626270626357">for file in fileList:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941626270626838"> # ...</paragraph> + </pycode> +</section> + +<section id="FolderExists"> + <comment> FolderExists -------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id11583765642643"> + <bookmark_value>FileSystem service;FolderExists</bookmark_value> + </bookmark> + <h2 id="hd_id421583765642360" localize="false">FolderExists</h2> + <paragraph role="paragraph" id="par_id51583765642590">Returns <literal>True</literal> if the specified <literal>FolderName</literal> is valid and exists, otherwise the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id151613004111990">If the <literal>foldername</literal> parameter is actually an existing file name, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id451626270785443"> + <input>svc.FolderExists(foldername: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001583765642211"><emph>foldername</emph>: A string representing the folder to be tested.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id301583765642138">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771583765642330">If FSO.FolderExists("C:\Documents\Thesis") Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21613004201438"> '...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861613004206334">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761626270831628">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id531626270831916">if fs.FolderExists(r"C:\Documents\Thesis")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801626270832082"> # ...</paragraph> + </pycode> +</section> + +<section id="GetBaseName"> + <comment> GetBaseName ---------------------------------------------------------------------------------------</comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id54158411061866"> + <bookmark_value>FileSystem service;GetBaseName</bookmark_value> + </bookmark> + <h2 id="hd_id111584110618587" localize="false">GetBaseName</h2> + <paragraph role="paragraph" id="par_id521584110618989">Returns the <literal>BaseName</literal> (equal to the last component) of a folder or file name, without its extension.</paragraph> + <paragraph role="paragraph" id="par_id731613004316790">The method does not check if the specified file or folder exists.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301626178954105"> + <input>svc.GetBaseName(filename: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id691584110618308"><emph>filename</emph>: A string representing the file name and its path.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id1001626271201609">In the examples below, the first <literal>GetBaseName</literal> method call corresponds to a folder, so the function returns the last component of the path. The second call receives a file name as input, so the name of the file is returned without its extension.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id201584110618266">MsgBox FSO.GetBaseName("/home/user/Documents") ' "Documents"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211584110618884">MsgBox FSO.GetBaseName("/home/user/Documents/my_file.ods") ' "my_file"</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id431626271314848">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411626271315092">bas.MsgBox(fs.GetBaseName("/home/user/Documents")) # "Documents"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821626271315317">bas.MsgBox(fs.GetBaseName("/home/user/Documents/my_file.ods")) # "my_file"</paragraph> + </pycode> +</section> + +<section id="GetExtension"> + <comment> GetExtension ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id271584032680645"> + <bookmark_value>FileSystem service;GetExtension</bookmark_value> + </bookmark> + <h2 id="hd_id441584032680932" localize="false">GetExtension</h2> + <paragraph role="paragraph" id="par_id831584032680866">Returns the extension part of a file or folder name without the dot "." character.</paragraph> + <paragraph role="paragraph" id="par_id941613060736524">The method does not check for the existence of the specified file or folder.</paragraph> + <paragraph role="paragraph" id="par_id561613060896361">If this method is applied to a folder name or to a file without an extension, then an empty string is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id481626179171535"> + <input>svc.GetExtension(filename: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821584032680311"><emph>filename</emph>: A string representing the file name and its path.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id241584032680600">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651584032680887">ext = FSO.GetExtension("C:\Windows\Notepad.exe") ' "exe"</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id391626271533012"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id751626271533408">ext = fs.GetExtension(r"C:\Windows\Notepad.exe") # "exe"</paragraph> + </pycode> +</section> + +<section id="GetFileLen"> + <comment> GetFileLen ----------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id511600685050691"> + <bookmark_value>FileSystem service;GetFileLen</bookmark_value> + </bookmark> + <h2 id="hd_id301600685050869" localize="false">GetFileLen</h2> + <paragraph role="paragraph" id="par_id48160068505010">The builtin <literal>FileLen</literal> Basic function returns the number of bytes contained in a file as a <literal>Long</literal> value, i.e. up to 2GB.</paragraph> + <paragraph role="paragraph" id="par_id571613061005426">The <literal>GetFileLen</literal> method can handle files with much larger sizes by returning a <literal>Currency</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id1001626179285915"> + <input>svc.GetFileLen(filename: str): num</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id161600685050367"><emph>filename</emph>: A string representing an existing file.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id901600685050677">Dim fLen As Currency</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721600685050519">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961600685050123">fLen = FSO.GetFileLen("C:\pagefile.sys")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id201626271668440">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361626271668899">fLen = fs.GetFileLen(r"C:\pagefile.sys")</paragraph> + </pycode> +</section> + +<section id="GetFileModified"> + <comment> GetFileModified -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id901584811478304"> + <bookmark_value>FileSystem service;GetFileModified</bookmark_value> + </bookmark> + <h2 id="hd_id651584811478113" localize="false">GetFileModified</h2> + <paragraph role="paragraph" id="par_id191584811478936">Returns the last modified date of a given file.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id491626179415178"> + <input>svc.GetFileModified(filename: str): datetime</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id25158481147822"><emph>filename</emph>: A string representing an existing file.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id911584811636241">Dim aDate As Date</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351584811478870">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id111584811478888">aDate = FSO.GetFileModified("C:\Documents\my_file.odt")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id531626271811921">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301626271812468">aDate = FSO.GetFileModified(r"C:\Documents\my_file.odt")</paragraph> + </pycode> +</section> + +<section id="GetName"> + <comment> GetName -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501584032366770"> + <bookmark_value>FileSystem service;GetName</bookmark_value> + </bookmark> + <h2 id="hd_id761584032366379" localize="false">GetName</h2> + <paragraph role="paragraph" id="par_id711584032366587">Returns the last component of a file or folder name in native operating system format.</paragraph> + <paragraph role="paragraph" id="par_id541613061300811">The method does not check if the specified file or folder exists.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id601626179529154"> + <input>svc.GetName(filename: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id671584032366193"><emph>filename</emph>: A string representing the file name and its path.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id731626271995119">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61158403236686">a = FSO.GetName("C:\Windows\Notepad.exe") ' Notepad.exe</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id91626272012883"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221626272013299">a = fs.GetName(r"C:\Windows\Notepad.exe") # Notepad.exe</paragraph> + </pycode> +</section> + +<section id="GetParentFolderName"> + <comment> GetParentFolderName -------------------------------------------------------------------------------</comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id211584113432829"> + <bookmark_value>FileSystem service;GetParentFolderName</bookmark_value> + </bookmark> + <h2 id="hd_id94158411343258" localize="false">GetParentFolderName</h2> + <paragraph role="paragraph" id="par_id871584113432747">Returns a string containing the name of the parent folder of a specified file or folder name.</paragraph> + <paragraph role="paragraph" id="par_id611613061603039">The method does not check if the specified file or folder exists.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id791626179605250"> + <input>svc.GetParentFolderName(filename: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id471584113432231"><emph>filename</emph>: A string with the file or folder name to be analyzed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id100158411343225">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id161584113432533">a = FSO.GetParentFolderName("C:\Windows\Notepad.exe") ' C:\Windows\</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id871626272152981"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id711626272153205">a = fs.GetParentFolderName(r"C:\Windows\Notepad.exe") # C:\Windows\</paragraph> + </pycode> +</section> + +<section id="GetTempName"> + <comment> GetTempName ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id621583851172862"> + <bookmark_value>FileSystem service;GetTempName</bookmark_value> + </bookmark> + <h2 id="hd_id981583851172348" localize="false">GetTempName</h2> + <paragraph role="paragraph" id="par_id82158385117289">Returns a randomly generated temporary file name that is useful for performing operations that require a temporary file.</paragraph> + <paragraph role="paragraph" id="par_id391613061770924">The returned file name does not have any suffix. The folder part of the returned string is the system's temporary folder.</paragraph> + <paragraph role="paragraph" id="par_id971613061774934">The method does not create the temporary file.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id81626212807031"> + <input>svc.GetTempName(): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41583851448294">Dim fName As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311583851172939">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381583851172545">fName = FSO.GetTempName() & ".txt"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381583851275546">' "/tmp/SF_574068.txt"</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id791626272322530">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121626272322966">fName = FSO.GetTempName() + ".txt"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991626272323308"># "/tmp/SF_574068.txt"</paragraph> + </pycode> +</section> + +<section id="HashFile"> + <comment> HashFile -------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id771601042514294"> + <bookmark_value>FileSystem service;HashFile</bookmark_value> + </bookmark> + <h2 id="hd_id251601042514585" localize="false">HashFile</h2> + <paragraph role="paragraph" id="par_id58160104251423">Hash functions are used by some cryptographic algorithms, in digital signatures, message authentication codes, fraud detection, fingerprints, checksums (message integrity check), hash tables, password storage and much more.</paragraph> + <paragraph role="paragraph" id="par_id301601042791356" xml-lang="en-US">The <literal>HashFile</literal> method returns the result of a hash function, applied on a given file and using a specified algorithm. The returned value is a string of lower-case hexadecimal digits.</paragraph> + <paragraph role="paragraph" id="par_id861601043268484" xml-lang="en-US">The hash algorithms supported are: <literal>MD5</literal>, <literal>SHA1</literal>, <literal>SHA224</literal>, <literal>SHA256</literal>, <literal>SHA384</literal> and <literal>SHA512</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id311626212875189"> + <input>svc.HashFile(filename: str, algorithm: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id28160104251451"><emph>filename</emph>: A string representing an existing file.</paragraph> + <paragraph role="paragraph" id="par_id71601042959846" xml-lang="en-US"><emph>algorithm</emph>: One of the supported algorithms.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id1160104251483">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391601042514664">sHash = FSO.HashFile("C:\pagefile.sys", "MD5")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id161626272480577"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id221626272480829">sHash = FSO.HashFile(r"C:\pagefile.sys", "MD5")</paragraph> + </pycode> +</section> + +<section id="MoveFile"> + <comment> MoveFile -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584791330923"> + <bookmark_value>FileSystem service;MoveFile</bookmark_value> + </bookmark> + <h2 id="hd_id321584791330580" localize="false">MoveFile</h2> + <paragraph role="paragraph" id="par_id51584791330688">Moves one or more files from one location to another. Returns <literal>True</literal> if at least one file has been moved or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id631613062890648">An error will also occur if the <literal>source</literal> parameter uses wildcard characters and does not match any files.</paragraph> + <paragraph role="paragraph" id="par_id241613062902777">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id851626214194605"> + <input>svc.MoveFile(source: str, destination: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id721584791330406"><emph>source</emph>: It can be a <literal>FileName</literal> or <literal>NamePattern</literal> to designate one or more files to be moved.</paragraph> + <paragraph role="paragraph" id="par_id291584791330181" xml-lang="en-US"><emph>destination</emph>: If <literal>source</literal> is a <literal>FileName</literal> then this parameter indicates the new path and file name of the moved file.</paragraph> + <paragraph role="paragraph" id="par_id31613063334246">If the move operation involves multiple files, then <literal>destination</literal> must be a folder name. If it does not exist, it is created.</paragraph> + <paragraph role="paragraph" id="par_id391613063494599">If <literal>source</literal> and <literal>destination</literal> have the same parent folder, the method will rename the <literal>source</literal>.</paragraph> + <paragraph role="paragraph" id="par_id941613063476533">Wildcard characters are not allowed in <literal>destination</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id91626272612758">In the following examples only files are moved, subfolders are not.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211584791330821">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881584791330102">FSO.MoveFile("C:\Temp1\*.*", "C:\Temp2")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731626272648304"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501626272649065">fs.MoveFile(r"C:\Temp1\*.*", r"C:\Temp2")</paragraph> + </pycode> +</section> + +<section id="MoveFolder"> + <comment> MoveFolder --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141584791330310"> + <bookmark_value>FolderSystem service;MoveFolder</bookmark_value> + </bookmark> + <h2 id="hd_id221584791330200" localize="false">MoveFolder</h2> + <paragraph role="paragraph" id="par_id301584791330868">Moves one or more folders from one location to another. Returns <literal>True</literal> if at least one folder has been moved or <literal>False</literal> if an error occurred.</paragraph> + <paragraph role="paragraph" id="par_id411613072570664">An error will also occur if the <literal>source</literal> parameter uses wildcard characters and does not match any folders.</paragraph> + <paragraph role="paragraph" id="par_id601613072595264">The method stops immediately after it encounters an error. The method does not roll back nor does it undo changes made before the error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id181626214342806"> + <input>svc.MoveFolder(source: str, destination: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id541584791330777"><emph>source</emph>: It can be a <literal>FolderName</literal> or <literal>NamePattern</literal> to designate one or more folders to be moved.</paragraph> + <paragraph role="paragraph" id="par_id551584791330279" xml-lang="en-US"><emph>destination</emph>: If the move operation involves a single folder, then <literal>destination</literal> is the name and path of the moved folder and it must not exist.</paragraph> + <paragraph role="paragraph" id="par_id11613072890641">If multiple folders are being moved, then <literal>destination</literal> designates where the folders in <literal>source</literal> will be moved into. If <literal>destination</literal> does not exist, it is created.</paragraph> + <paragraph role="paragraph" id="par_id301613072928159">Wildcard characters are not allowed in <literal>destination</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id1001584791330720">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201584791330500">FSO.MoveFolder("C:\Temp1\*", "C:\Temp2")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id11626275697779"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361626275698068">fs.MoveFolder(r"C:\Temp1\*", r"C:\Temp2")</paragraph> + </pycode> +</section> + +<section id="OpenTextFile"> + <comment> OpenTextFile ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id531585320922937"> + <bookmark_value>FolderSystem service;OpenTextFile</bookmark_value> + </bookmark> + <h2 id="hd_id481585320922643" localize="false">OpenTextFile</h2> + <paragraph role="paragraph" id="par_id121585320922117">Opens a file and returns a <literal>TextStream</literal> object that can be used to read from, write to, or append to the file.</paragraph> + <paragraph role="paragraph" id="par_id591613073104711">Note that the method does not check if the given file is really a text file.</paragraph> + <paragraph role="paragraph" id="par_id951613073135036">The method returns a <literal>Null</literal> object (in Basic) or <literal>None</literal> (in Python) if an error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id21626214460569"> + <input>svc.OpenTextFile(filename: str, iomode: int = 1, create: bool = False, encoding: str = 'UTF-8'): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id551585320922678"><emph>filename</emph>: Identifies the file to open.</paragraph> + <paragraph role="paragraph" id="par_id671585320922388" xml-lang="en-US"><emph>iomode</emph>: Indicates the input/output mode. It can be one of three constants: <literal>svc.ForReading</literal> (default), <literal>svc.ForWriting</literal>, or <literal>svc.ForAppending</literal>.</paragraph> + <paragraph role="paragraph" id="par_id21585321398586" xml-lang="en-US"><emph>create</emph>: Boolean value that indicates whether a new file can be created if the specified <literal>filename</literal> doesn't exist:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id721613073434797" role="listitem">If <literal>True</literal> a new file and its parent folders will be created if they do not exist;</paragraph> + </listitem> + <listitem> + <paragraph id="par_id201613073469289" role="listitem">If <literal>False</literal> then new files are not created (default).</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id771585321576210" xml-lang="en-US"><emph>encoding</emph>: The character set to be used. The default encoding is "UTF-8".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id841585320922219">Dim myFile As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id831585320922237">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141585320922524">Set myFile = FSO.OpenTextFile("C:\Temp\ThisFile.txt", FSO.ForReading)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id341585321797611">If Not IsNull(myFile) Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261585321805705"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801613073013084">End If</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id971626275941924">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271626275942194">myFile = fs.OpenTextFile(r"C:\Temp\ThisFile.txt", fs.ForReading)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141626275942434">if myFile is not None:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id721626275942719"> # ...</paragraph> + </pycode> +</section> + +<section id="PickFile"> + <comment> PickFile --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id1001583670342501"> + <bookmark_value>FileSystem service;PickFile</bookmark_value> + </bookmark> + <h2 id="hd_id421583670342501" localize="false">PickFile</h2> + <paragraph role="paragraph" id="par_id871583670342501">Opens a dialog box to open or save files.</paragraph> + <paragraph role="paragraph" id="par_id881613074436979">If the <literal>SAVE</literal> mode is set and the picked file exists, a warning message will be displayed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id751626214688263"> + <input>svc.PickFile(defaultfile: str ='', mode: str = 'OPEN', filter: str = ''): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481583670342502"><emph>defaultfile</emph>: This argument is a string composed of a folder and file name:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id511613074665951" role="listitem">The folder part indicates the folder that will be shown when the dialog opens (default = the last selected folder).</paragraph> + </listitem> + <listitem> + <paragraph id="par_id631613074685308" role="listitem">The file part designates the default file to open or save.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id981583670342502"><emph>mode</emph>: A string value that can be either "OPEN" (for input files) or "SAVE" (for output files). The default value is "OPEN".</paragraph> + <paragraph role="paragraph" id="par_id31583670342502"><emph>filter</emph>: The extension of the files displayed when the dialog is opened (default = no filter).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id881626276134300">The examples below open a file picker with the "txt" filter applied.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791626276255605">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691583670342504">aFile = FSO.PickFile("C:\Documents", "OPEN", "txt")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id681626276275531"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id701626276275757">aFile = fs.PickFile(r"C:\Documents", "OPEN", "txt")</paragraph> + </pycode> +</section> + +<section id="PickFolder"> + <comment> PickFolder ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171583671701309"> + <bookmark_value>FileSystem service;PickFolder</bookmark_value> + </bookmark> + <h2 id="hd_id581583671701385" localize="false">PickFolder</h2> + <paragraph role="paragraph" id="par_id521583671701777">Opens a dialog box to select a folder.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id671626215115555"> + <input>svc.PickFolder(defaultfolder: str = '', freetext: str = ''): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id951583671701872"><emph>defaultfolder</emph>: A string containing the folder name that will be displayed when the dialog is opened (default = the last selected folder).</paragraph> + <paragraph role="paragraph" id="par_id821583671701764"><emph>freetext</emph>: Text to display in the dialog (default = "").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id391583764844033">' Basic</paragraph> + <paragraph role="bascode" id="bas_id921583671701610">aFolder = FSO.PickFolder("C:\Documents", "Choose a folder or press Cancel")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id291626276402041"># Python</paragraph> + <paragraph role="pycode" id="pyc_id631626276402296">aFolder = fs.PickFolder(r"C:\Documents", "Choose a folder or press Cancel")</paragraph> + </pycode> +</section> + +<section id="SubFolders"> + <comment> SubFolders ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id901584016761417"> + <bookmark_value>FileSystem service;Files</bookmark_value> + </bookmark> + <h2 id="hd_id51584016761775" localize="false">SubFolders</h2> + <paragraph role="paragraph" id="par_id431584016761996">Returns a zero-based array of strings corresponding to the folders stored in a given <literal>foldername</literal>.</paragraph> + <paragraph role="paragraph" id="par_id431613075267241">The list may be filtered with wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id531626215218570"> + <input>svc.SubFolders(foldername: str, filter: str = ''): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id701584016761945"><emph>foldername</emph>: A string representing a folder. The folder must exist. <literal>foldername</literal> must not designate a file.</paragraph> + <paragraph role="paragraph" id="par_id471585648674921" xml-lang="en-US"><emph>filter</emph>: A string containing wildcards ("?" and "*") that will be applied to the resulting list of folders (default = "").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id541584016761911">Dim folderList As Variant, folder As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391584016761116">FSO.FileNaming = "SYS"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701584016761482">folderList = FSO.SubFolders("/home/user/")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631584016761643">For Each folder In folderList</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871584016761279"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881584016761778">Next folder</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891626276476767">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131626276476995">folderList = fs.SubFolders("/home/user/")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661626276477186">for folder in folderList:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891626276477415"> # ...</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_textstream.xhp#TextStreamService"/> + <embed href="text/sbasic/shared/03160000.xhp#Input_h1"/> + <embed href="text/sbasic/shared/03020103.xhp#Open_h1"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_form.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_form.xhp new file mode 100644 index 000000000..d9515a222 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_form.xhp @@ -0,0 +1,841 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Form" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Form service</title> + <filename>/text/sbasic/shared/03/sf_form.xhp</filename> + </topic> + </meta> +<body> +<section id="ScriptForge-sf_form"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>Form service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="FormService"><link href="text/sbasic/shared/03/sf_form.xhp" name="SFDocuments.Form"><literal>SFDocuments</literal>.<literal>Form</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id931583589764919" xml-lang="en-US">The <literal>Form</literal> service provides methods and properties to manage forms in %PRODUCTNAME documents. This service supports forms in Base, Calc and Writer documents and allows to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id381618172063851" role="listitem">Open and activate forms.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id261618172129782" role="listitem">Navigate through records shown by the form.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id281618172141607" role="listitem">Get access to the controls inside the form.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id371618172155483" role="listitem">Get access to subforms of a parent form.</paragraph> + </listitem> + </list> +</section> + <tip id="par_id351616768789190" xml-lang="en-US">The <literal>SFDocuments</literal>.<literal>Form</literal> service is available from %PRODUCTNAME 7.2 onwards.</tip> + <paragraph role="paragraph" id="par_id451616765867881" xml-lang="en-US">Forms are usually used in %PRODUCTNAME documents to create user interfaces connected to relational databases. Hence, the <literal>Form</literal> service provides quick access to the linked database through the <link href="text/sbasic/shared/03/sf_database.xhp" name="SFDatabases.Database"><literal>SFDatabases</literal>.<literal>Database</literal> service</link>.</paragraph> + <tip id="par_id891598188164936" xml-lang="en-US">The <literal>SFDocuments</literal>.<literal>Form</literal> service is closely related to the <link href="text/sbasic/shared/03/sf_formcontrol.xhp" name="SFDocuments.FormControl"><literal>SFDocuments</literal>.<literal>FormControl</literal> service.</link></tip> + <h2 id="hd_id161616766330804" xml-lang="en-US">Definitions</h2> + <h3 id="hd_id751616766382317" xml-lang="en-US" localize="false">FormDocument</h3> + <paragraph role="paragraph" id="par_id951618172906010">Forms are usually created in Base documents, but they can be added to Writer and Calc documents as well.</paragraph> + <paragraph role="paragraph" id="par_id671618173380680">In Base, each form you create using the <menuitem>Insert - Form</menuitem> functionality or through the <link href="text/shared/autopi/01090000.xhp" name="FormWizard">Form Wizard</link> is actually a <literal>FormDocument</literal> that can be handled with the <literal>Form</literal> service. Base documents can contain an unlimited number of form documents.</paragraph> + <paragraph role="paragraph" id="par_id841618177362626">Below is an example showing the hierarchy of all the elements involved in accessing forms and subforms in a Base document. Suppose you have a Base file named <literal>Employees.odb</literal> and inside it you created a form document to add new employees to the database. The form document contains a main form named <literal>EmployeeData</literal> that gives access to a table. There is also a subform <literal>WorksAtPlant</literal> that allows you to associate the new employee to one of the plants of the company.</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id151618176848874">Employees.odb (Base document)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381618176868013"> |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351618176868854"> |-- AddEmployee (FormDocument)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211618176869166"> |</paragraph> + <paragraph role="bascode" id="bas_id941618176869485"> |-- EmployeeData (Main Form)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571618176869726"> |</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291618176869942"> |-- WorksAtPlant (SubForm)</paragraph> + </bascode> + <note id="par_id221618173444457">A <literal>FormDocument</literal> can be seen as a set of forms that provide access to datasets such as database tables and queries from within %PRODUCTNAME documents. The names of forms and subforms inside a FormDocument can be accessed using the <link href="text/shared/02/01170600.xhp" name="FormNavigator">Form Navigator</link>.</note> + <h3 id="hd_id851616767037521" xml-lang="en-US">Forms and Subforms</h3> + <paragraph role="paragraph" id="par_id681616767265034" xml-lang="en-US">A form document is composed of one or more forms which, in turn, may also contain any number of subforms. A Form is an abstract set of controls that are linked to a specified data source, which can be a database table, a query or a SQL <literal>SELECT</literal> statement.</paragraph> + <paragraph role="paragraph" id="par_id711618178831976">In Calc and Writer documents, each form can be linked to datasets located in different databases. On the other hand, in Base documents the database contained in the document is common to all forms.</paragraph> + <tip id="par_id191616837111507" xml-lang="en-US">To invoke the <literal>SFDocuments</literal>.<literal>Form</literal> service refer to the methods <literal>Forms()</literal>, <literal>FormDocuments()</literal> and <literal>OpenFormDocument()</literal> of the <link href="text/sbasic/shared/03/sf_document.xhp" name="SFDocuments"><literal>SFDocuments</literal>.<literal>Document</literal></link> service</tip> +<section id="serviceInvocation"> + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Form</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <h3 id="hd_id991618179698545">In Writer documents</h3> + <paragraph role="paragraph" id="par_id51616767892693" xml-lang="en-US">The code snippet below shows how to access the form named <literal>Form1</literal> that is inside a Writer file:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471598171198389">Dim oDoc As Object, myForm As Object, ui as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561618179461775">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611598171572062">Set oDoc = ui.OpenDocument("/home/user/Documents/MyForm.odt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571598171205739">Set myForm = oDoc.Forms("Form1")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id241622014444493">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391622014212514">ui = CreateScriptService('UI') </paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891622014222625">doc = ui.OpenDocument('/home/user/Documents/MyForm.odt')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931622014224129">my_form = doc.Forms('Form1')</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id531618179517628">Forms can be accessed by their names or by their indices, as shown below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id991598171277414">Set myForm = oDoc.Forms(0)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id691622014677169">my_form = doc.Forms(0)</paragraph> + </pycode> + <warning id="par_id181618250546617">If you try to access a <literal>FormDocument</literal> that is currently opened in <emph>Design Mode</emph> an exception will be raised.</warning> + <h3 id="hd_id921618179792926">In Calc documents</h3> + <paragraph role="paragraph" id="par_id481618179851104">A form in a Calc file must have a unique name inside its sheet. Hence, the <literal>Forms</literal> method requires two arguments, the first indicating the sheet name and the second specifying the form name.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471598171198125">Dim oDoc As Object, myForm As Object, ui as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561618179462475">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611598170362062">Set oDoc = ui.OpenDocument("/home/user/Documents/MyForms.ods")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571598171200339">Set myForm = oDoc.Forms("Sheet1", "Form1")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id51622028165429">This is achieved identically using Python:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id871622021672708">ui = CreateScriptService('UI')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671622021672931">doc = ui.OpenDocument('/home/user/Documents/MyForms.ods')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301622021673180">my_form = doc.Forms('Sheet1', 'Form1')</paragraph> + </pycode> + <h3 id="hd_id201618180055756">In Base documents</h3> + <paragraph role="paragraph" id="par_id711616768164987" xml-lang="en-US">A <literal>FormDocument</literal> inside a Base document is accessed by its name. The following example opens the form document named <literal>thisFormDocument</literal> and accesses the form <literal>MainForm</literal>:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471598176518738">Dim oDb As Object, myForm As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271598171282891">Set oDb = CreateScriptService("SFDocuments.Document", ThisDatabaseDocument)</paragraph> + <paragraph role="bascode" id="bas_id271598171225874">' The statement below is necessary only if the form hasn't been opened yet</paragraph> + <paragraph role="bascode" localize="false" id="bas_id551598171288547">oDb.OpenFormDocument("thisFormDocument")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741598171294507">Set myForm = oDoc.Forms("thisFormDocument", "MainForm")</paragraph> + <paragraph role="bascode" id="bas_id51616768358888">' Or, alternatively, to access the form by its index ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591598171300285">Set myForm = oDb.Forms("thisFormDocument", 0)</paragraph> + </bascode> + <note id="par_id991618249636036">To perform any action on a form using the <literal>Form</literal> service, the <literal>FormDocument</literal> must have been opened either manually by the user or programmatically in a user script. The latter can be done by calling the <literal>OpenFormDocument</literal> method of the <link href="text/sbasic/shared/03/sf_base.xhp" name="ScriptForge Base Service"><literal>Base</literal> service</link>.</note> + <paragraph role="paragraph" id="par_id11618180564274">To access a given subform of a form use the <literal>SubForms</literal> method. Note that in the example below <literal>mySubForm</literal> is a new instance of the <literal>Form</literal> service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id71618182658792">Dim mySubForm As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681616768495330">Set mySubForm = myForm.SubForms("mySubForm")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id681622028653480">Previous examples translate in Python as:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id501622028742999">db = CreateScriptService('SFDocuments.Document', XSCRIPTCONTEXT.getDocument())</paragraph> + <paragraph role="pycode" id="pyc_id811622808499801"># The statement below is necessary only if the form hasn't been opened yet</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671622028743191">form_doc = db.OpenFormDocument('thisFormDocument')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id431622028743374">form = form_doc.Forms('thisFormDocument', 'MainForm')</paragraph> + <paragraph role="pycode" id="pyc_id511622808538351"># Or, alternatively, to access the form by its index ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681622028743582">form = form_doc.Forms('thisFormDocument', 0)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id611622028743782">sub_form = form.SubForms('mySubForm')</paragraph> + </pycode> + <h3 id="hd_id211618180379064">In Form events</h3> + <paragraph role="paragraph" id="par_id421616768529754" xml-lang="en-US">To invoke the <literal>Form</literal> service when a form event takes place:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id931616768628138">Sub OnEvent(ByRef poEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931616768621093"> Dim myForm As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271616768613253"> Set myForm = CreateScriptService("SFDocuments.FormEvent", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001618180405172"> '(...)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751618180415566">End sub</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551622022387877">def OnEvent(event: uno):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id081622022388165"> form = CreateScriptService('SFDocuments.FormEvent', event)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id641622022388397"> pass</paragraph> + </pycode> + <embed href="text/sbasic/shared/03/sf_formcontrol.xhp#FormEvent_Note"/> + <paragraph role="paragraph" id="par_id721623150543016">It is recommended to free resources after use of the Form service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id751681880415566">myForm.Dispose() ' Basic</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551226022387877">form.Dispose() # Python</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id221623150547406">This operation is done implicitly when a form document is closed with the <literal>CloseFormDocument()</literal> method described below.</paragraph> +</section> + <h2 id="hd_id651583668365757" xml-lang="en-US">Properties</h2> + <table id="tab_id381583668386455"> + <tablerow> + <tablecell> + <paragraph id="par_id871583668386455" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491583668386455" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668474014" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401583668386455" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151583668386455" role="tablecontent" localize="false">AllowDeletes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371583668519172" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668386455" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583668386455" role="tablecontent" xml-lang="en-US">Specifies if the form allows to delete records.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951583839708571" role="tablecontent" localize="false">AllowInserts</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541583839708548" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751583839708362" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731583839708412" role="tablecontent" xml-lang="en-US">Specifies if the form allows to add records.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511584027709311" role="tablecontent" localize="false">AllowUpdates</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761584027709516" role="tablecontent " xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491584027709825" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971584027709752" role="tablecontent" xml-lang="en-US">Specifies if the form allows to update records.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583839767611" role="tablecontent" localize="false">BaseForm</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31583839767743" role="tablecontent " xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741583839767926" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839767195" role="tablecontent" xml-lang="en-US">Specifies the hierarchical name of the Base Form containing the actual form.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83158383992056" role="tablecontent" localize="false">Bookmark</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583839920487" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971583839920282" role="tablecontent" localize="false">Variant</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451583839920858" role="tablecontent" xml-lang="en-US">Specifies uniquely the current record of the form's underlying table, query or SQL statement.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id751588333908795" role="tablecontent" localize="false">CurrentRecord</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571588333908716" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781588333908500" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721588333908708" role="tablecontent" xml-lang="en-US">Identifies the current record in the dataset being viewed on a form. If the row number is positive, the cursor moves to the given row number with respect to the beginning of the result set. Row count starts at 1. If the given row number is negative, the cursor moves to an absolute row position with respect to the end of the result set. Row -1 refers to the last row in the result set.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id251583774433989" role="tablecontent" localize="false">Filter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501583774433513" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411583774433779" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph role="paragraph" id="par_id151598177605296" xml-lang="en-US">Specifies a subset of records to be displayed as a <literal>SQL</literal> <literal>WHERE</literal>-clause without the <literal>WHERE</literal> keyword.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731588334016220" role="tablecontent" localize="false">LinkChildFields</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271588334016191" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991588334016273" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251588334016874" role="tablecontent" xml-lang="en-US">Specifies how records in a child subform are linked to records in its parent form.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id881616774153888" role="tablecontent" localize="false">LinkParentFields</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id901616774153495" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981616774153884" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981616774153723" role="tablecontent" xml-lang="en-US">Specifies how records in a child subform are linked to records in its parent form.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id561616774304843" role="tablecontent" localize="false">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501616774304840" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71616774304482" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461616774304497" role="tablecontent" xml-lang="en-US">The name of the current form.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id331616774384380" role="tablecontent" localize="false">OrderBy</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751616774384451" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id641616774384366" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321616774384489" role="tablecontent" xml-lang="en-US">Specifies in which order the records should be displayed as a <literal>SQL</literal> <literal>ORDER BY</literal> clause without the <literal>ORDER BY</literal> keywords.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id281616774918384" role="tablecontent" localize="false">Parent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261616774918923" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861616774918694" role="tablecontent" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id171616774918881" role="tablecontent" xml-lang="en-US">The parent of the current form. It can be either a <literal>SFDocuments</literal>.<literal>Form</literal> or a <literal>SFDocuments</literal>.<literal>Document</literal> object.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id581616777650809" role="tablecontent" localize="false">RecordSource</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501616777650751" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991616777650362" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91616777650933" role="tablecontent" xml-lang="en-US">Specifies the source of the data, as a table name, a query name or a SQL statement.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id741598177924441" role="tablecontent" localize="false">XForm</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598177924437" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id94159817792441" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id191598177924897" role="tablecontent" xml-lang="en-US">The UNO object representing interactions with the form. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1form_1_1XForm.html" name="XForm interface">XForm</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1form_1_1component_1_1DataForm.html" name="DataForm service">DataForm</link> in the API documentation for detailed information.</paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="hd_id421612628828054" xml-lang="en-US">Event properties</h2> + <paragraph role="paragraph" id="par_id41612629140856" xml-lang="en-US">The properties below return or set URI strings that define the script triggered by the event.</paragraph> + <table id="tab_id951612628879819"> + <tablerow> + <tablecell> + <paragraph id="par_id961612628879819" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401612628879819" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id281612628879819" role="tablehead" xml-lang="en-US">Basic IDE Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id431612629836735" localize="false" role="tablecontent" xml-lang="en-US">OnApproveCursorMove</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111612629836630" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001612629836902" role="tablecontent" xml-lang="en-US">Before record change</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id701612629836389" localize="false" role="tablecontent" xml-lang="en-US">OnApproveParameter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612629836294" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id62161262983683" role="tablecontent" xml-lang="en-US">Fill parameters</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241612629836863" localize="false" role="tablecontent" xml-lang="en-US">OnApproveReset</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81612629836634" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881612629836744" role="tablecontent" xml-lang="en-US">Prior to reset</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id201612629836996" localize="false" role="tablecontent" xml-lang="en-US">OnApproveRowChange</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591612629836830" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161612629836775" role="tablecontent" xml-lang="en-US">Before record action</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id111612629836950" localize="false" role="tablecontent" xml-lang="en-US">OnApproveSubmit</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891612629836630" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461612629836679" role="tablecontent" xml-lang="en-US">Before submitting</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id711612629836495" localize="false" role="tablecontent" xml-lang="en-US">OnConfirmDelete</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131612629836291" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151612629836151" role="tablecontent" xml-lang="en-US">Confirm deletion</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id971612629836286" localize="false" role="tablecontent" xml-lang="en-US">OnCursorMoved</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612629836725" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361612629836624" role="tablecontent" xml-lang="en-US">After record change</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721612629836537" localize="false" role="tablecontent" xml-lang="en-US">OnErrorOccurred</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311612629836481" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721612629836752" role="tablecontent" xml-lang="en-US">Error occurred</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id55161262983695" localize="false" role="tablecontent" xml-lang="en-US">OnLoaded</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981612629836116" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381612629836635" role="tablecontent" xml-lang="en-US">When loading</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id621612629836155" localize="false" role="tablecontent" xml-lang="en-US">OnReloaded</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612629836704" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id35161262983642" role="tablecontent" xml-lang="en-US">When reloading</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id541616778783953" localize="false" role="tablecontent" xml-lang="en-US">OnReloading</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id44161677878329" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661616778783899" role="tablecontent" xml-lang="en-US">Before reloading</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961616778529182" localize="false" role="tablecontent" xml-lang="en-US">OnResetted</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651616778529764" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311616778529570" role="tablecontent" xml-lang="en-US">After resetting</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id171616778529918" localize="false" role="tablecontent" xml-lang="en-US">OnRowChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601616778529481" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351616778529352" role="tablecontent" xml-lang="en-US">After record action</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id91616778529622" localize="false" role="tablecontent" xml-lang="en-US">OnUnloaded</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711616778529292" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981616778529250" role="tablecontent" xml-lang="en-US">When unloading</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id71616778529970" localize="false" role="tablecontent" xml-lang="en-US">OnUnloading</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521616778529932" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id511616778529291" role="tablecontent" xml-lang="en-US">Before unloading</paragraph> + </tablecell> + </tablerow> + </table> + <tip id="par_id961618181634322">To learn more about URI strings, refer to the <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification" name="URI specification">Scripting Framework URI Specification</link>.</tip> + <table id="tab_id891606472825856"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id921606472825856" role="tablehead">List of methods in the Form service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id381606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_form.xhp#Activate" name="Activate method">Activate</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#CloseFormDocument" name="CloseFormDocument method">CloseFormDocument</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#Controls" name="Controls method">Controls</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#GetDatabase" name="GetDatabase method">GetDatabase</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id451606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_form.xhp#MoveFirst" name="MoveFirst method">MoveFirst</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#MoveLast" name="MoveLast method">MoveLast</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#MoveNext" name="MoveNext method">MoveNext</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#MoveNew" name="MoveNew method">MoveNew</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id161606472825856" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_form.xhp#MovePrevious" name="MovePrevious method">MovePrevious</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#Requery" name="Requery method">Requery</link><br/> + <link href="text/sbasic/shared/03/sf_form.xhp#Subforms" name="Subforms method">SubForms</link><br/><br/> + </paragraph></tablecell> + </tablerow> + </table> +<section id="Activate"> + <comment> Activate -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721583933076548"> + <bookmark_value>Form service;Activate</bookmark_value> + </bookmark> + <h2 id="hd_id681583933076692" localize="false">Activate</h2> + <paragraph role="paragraph" id="par_id871583933076448">Sets the focus on the current <literal>Form</literal> instance. Returns <literal>True</literal> if focusing was successful.</paragraph> + <paragraph role="paragraph" id="par_id81616858956290" xml-lang="en-US">The behavior of the <literal>Activate</literal> method depends on the type of document where the form is located:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id761616858967361" role="listitem" xml-lang="en-US"><emph>In Writer documents:</emph> Sets the focus on that document.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id931616859010103" role="listitem" xml-lang="en-US"><emph>In Calc documents:</emph> Sets the focus on the sheet to which the form belongs.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id41616859019478" role="listitem" xml-lang="en-US"><emph>In Base documents:</emph> Sets the focus on the <literal>FormDocument</literal> the <literal>Form</literal> refers to.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id11622536171845" localize="false"><input>svc.Activate(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id921618228229529">The following example assumes you want to activate the form named <literal>FormA</literal> located in <literal>Sheet1</literal> of the currently open Calc file. It first gets access to the document using the <literal>Document</literal> service and <literal>ThisComponent</literal> and then activates the form.</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id21618228468066">'Gets hold of the form that will be activated</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421618228118346">Dim oDoc as Object, myForm as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261618228156375">Set oDoc = CreateScriptService("Document", ThisComponent)</paragraph> + <paragraph role="paragraph" localize="false" id="par_id451618228193979">Set myForm = oDoc.Forms("Sheet1", "FormA")</paragraph> + <paragraph role="bascode" id="bas_id201618228487565">'Activates the form</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361598179135096">myForm.Activate()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id211622537233877">doc = CreateScriptService('Document', XSCRIPTCONTEXT.getDocument())</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181622537234494">form = doc.Forms('Sheet1', 'FormA')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981622537234703">form.Activate()</paragraph> + </pycode> + <note id="par_id81618228720782"><literal>ThisComponent</literal> applies to Calc and Writer documents. For Base documents use <literal>ThisDataBaseDocument</literal>.</note> +</section> +<section id="CloseFormDocument"> + <comment> CloseFormDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id14161686043795"> + <bookmark_value>Form service;CloseFormDocument</bookmark_value> + </bookmark> + <h2 id="hd_id18161686043718" localize="false">CloseFormDocument</h2> + <paragraph role="paragraph" id="par_id501616860541195" xml-lang="en-US">Closes the form document containing the actual <literal>Form</literal> instance. The <literal>Form</literal> instance is disposed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id811622538068303" localize="false"><input>svc.CloseFormDocument(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id511616860437148">myForm.CloseFormDocument() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id331622538021746">form.CloseFormDocument() # Python</paragraph> + </pycode> + <note id="par_id611618229004669">This method only closes form documents located in Base documents. If the form is stored in a Writer or Calc document, calling <literal>CloseFormDocument</literal> will have no effect.</note> +</section> +<section id="Controls"> + <comment> Controls -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584541257826"> + <bookmark_value>Form service;Controls</bookmark_value> + </bookmark> + <h2 id="hd_id95158454125767" localize="false">Controls</h2> + <paragraph role="paragraph" id="par_id161584541257982">The value returned by the <literal>Controls</literal> method depends on the arguments provided:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id421598179770993" role="listitem" xml-lang="en-US">If the method is called <emph>without arguments</emph>, then it returns the list of the controls contained in the form. Beware that the returned list does not contain any subform controls.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id81598185229301" role="listitem" xml-lang="en-US">If the optional <literal>ControlName</literal> argument is provided, the method returns a <literal>FormControl</literal> class instance referring to the specified control.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id471622538274231" localize="false"><input>svc.Controls(opt controlname: str): any</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257789"><emph>controlname</emph> : A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id151598185478904">Dim myForm As Object, myList As Variant, myControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21598185484092">Set myForm = myDoc.Forms("myForm")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641598185489492">myList = myform.Controls()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598185495193">Set myControl = myform.Controls("myTextBox") ' SFDocuments.FormControl</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id711622538462214">form = doc.Forms('myForm')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631622538462782">form_names = form.Controls()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id961622538463294">form_control = form.Controls('myTextBox') # SFDocuments.FormControl</paragraph> + </pycode> +</section> +<section id="GetDatabase"> + <comment> GetDatabase -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id941616861134691"> + <bookmark_value>Form service;GetDatabase</bookmark_value> + </bookmark> + <h2 id="hd_id141616861134554" localize="false">GetDatabase</h2> + <paragraph role="paragraph" id="par_id291616861407907" xml-lang="en-US">Return a <link href="text/sbasic/shared/03/sf_database.xhp" name="DBService"><literal>SFDatabases</literal>.<literal>Database</literal></link> instance giving access to the execution of SQL commands on the database the current form is connected to and/or that is stored in the current Base document.</paragraph> + <paragraph role="paragraph" id="par_id991616861417207" xml-lang="en-US">Each form has its own database connection, except in Base documents where they all share the same connection.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id221622547947693" localize="false"><input>svc.GetDatabase(opt user: str, opt password: str): svc</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id701616861134906"><emph>user, password</emph>: The login optional parameters (Default = "").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id231616861134373">Dim myDb As Object ' SFDatabases.Database</paragraph> + <paragraph role="bascode" localize="false" id="bas_id2316168611347">Set myDb = oForm.GetDatabase()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id871622547824003">db = form.GetDatabase() # SFDatabases.Database</paragraph> + </pycode> +</section> +<section id="MoveFirst"> + <comment> MoveFirst -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id671616861787529"> + <bookmark_value>Form service;MoveFirst</bookmark_value> + </bookmark> + <h2 id="hd_id591616861787279" localize="false">MoveFirst</h2> + <paragraph role="paragraph" id="par_id771616861842867" xml-lang="en-US">The form cursor is positioned on the first record. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id101622549004980" localize="false"><input>svc.MoveFirst(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191616861787635">myForm.MoveFirst() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id421622549258920">form.MoveFirst() # Python</paragraph> + </pycode> +</section> +<section id="MoveLast"> + <comment> MoveLast -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id551616863143388"> + <bookmark_value>Form service;MoveLast</bookmark_value> + </bookmark> + <h2 id="hd_id831616863143434" localize="false">MoveLast</h2> + <paragraph role="paragraph" id="par_id331616863143187" xml-lang="en-US">The form cursor is positioned on the last record. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id931622549019307" localize="false"><input>svc.MoveLast(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id691616863143688">myForm.MoveLast() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831622549604397">form.MoveLast() # Python</paragraph> + </pycode> +</section> +<section id="MoveNew"> + <comment> MoveNew -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231616863143638"> + <bookmark_value>Form service;MoveNew</bookmark_value> + </bookmark> + <h2 id="hd_id41161686314366" localize="false">MoveNew</h2> + <paragraph role="paragraph" id="par_id361616863143954" xml-lang="en-US">The form cursor is positioned on the new record area. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id131622549039501" localize="false"><input>svc.MoveNew(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id401616863143757">myForm.MoveNew() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id381622549678558">form.MoveNew() # Python</paragraph> + </pycode> +</section> +<section id="MoveNext"> + <comment> MoveNext -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id171616863143921"> + <bookmark_value>Form service;MoveNext</bookmark_value> + </bookmark> + <h2 id="hd_id111616863143256" localize="false">MoveNext</h2> + <paragraph role="paragraph" id="par_id541616863143461" xml-lang="en-US">The form cursor is positioned on the next record. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id291622549045804" localize="false"><input>svc.MoveNext(opt offset: int): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id271616863582607"><emph>offset</emph>: The number of records to go forward (Default = 1).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id591616863143862">myForm.MoveNext() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361622549859524">form.MoveNext() # Python</paragraph> + </pycode> +</section> +<section id="MovePrevious"> + <comment> MovePrevious -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id71161686379488"> + <bookmark_value>Form service;MovePrevious</bookmark_value> + </bookmark> + <h2 id="hd_id371616863794447" localize="false">MovePrevious</h2> + <paragraph role="paragraph" id="par_id616168637945" xml-lang="en-US">The form cursor is positioned on the previous record. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id981622549054028" localize="false"><input>svc.MovePrevious(opt offset: int): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id751616863794125"><emph>offset</emph>: The number of records to go backwards (Default = 1).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id941616863794988">myForm.MovePrevious() ' Basic</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id221622549920933">form.MovePrevious() # Python</paragraph> + </pycode> +</section> +<section id="Requery"> + <comment> Requery -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id741616864216894"> + <bookmark_value>Form service;Requery</bookmark_value> + </bookmark> + <h2 id="hd_id551616864216705" localize="false">Requery</h2> + <paragraph role="paragraph" id="par_id811616864216529" xml-lang="en-US">Reloads the current data from the database and refreshes the form. The cursor is positioned on the first record. Returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id731622550132517"><input>svc.Requery(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id211616864216116">myForm.Requery() ' Basic</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401622550186725">form.Requery() # Python</paragraph> + </pycode> +</section> +<section id="Subforms"> + <comment> Subforms -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id441616864510542"> + <bookmark_value>Form service;Subforms</bookmark_value> + </bookmark> + <h2 id="hd_id241616864510145" localize="false">Subforms</h2> + <paragraph role="paragraph" id="par_id891616864510614">The value returned by the <literal>Subforms</literal> method depends on the arguments provided:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id951616864510585" role="listitem" xml-lang="en-US">If the method is called <emph>without any arguments</emph>, then it returns the list of subforms contained in the current form or subform instance.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id591616864510445" role="listitem" xml-lang="en-US">If the optional <literal>subform</literal> argument is provided, the method returns a new <literal>SFDocuments</literal>.<literal>Form</literal> instance based on the specified form/subform name or index.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id541622550497960"><input>svc.Subforms(): str[0..*]</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id161623413158150"><input>svc.Subforms(subform: str): svc</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id31623413181836"><input>svc.Subforms(subform: int): svc</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id341616864510747"><emph>subform</emph>: A subform stored in the current <literal>Form</literal> class instance given by its name or index.</paragraph> + <paragraph role="paragraph" id="par_id211618230389251">When this argument is absent, the method returns a list of available subforms as a zero-based array. If the form has a single subform, you can set <literal>subform = 0</literal> to get access to it.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id821616864510402">Dim myForm As Object, myList As Variant, mySubform As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81616864510872">myList = myform.Subforms()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951616864510420">Set mySubform = myForm.Subforms("mySubform") ' SFDocuments.Form</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id101622552303831">subform_names = form.Subforms()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781622552304561">subform = form.Subforms('mySubform') # SFDocuments.Form</paragraph> + </pycode> +</section> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_database.xhp#DatabaseService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_formcontrol.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_formcontrol.xhp new file mode 100644 index 000000000..4bcfaf687 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_formcontrol.xhp @@ -0,0 +1,1173 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_FormControl" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.FormControl service</title> + <filename>/text/sbasic/shared/03/sf_formcontrol.xhp</filename> + </topic> + </meta> +<body> +<section id="ScriptForge-sf_formcontrol"> + <bookmark localize="false" branch="index" id="bm_id41582391760252"> + <bookmark_value>FormControl service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id781582391760253" xml-lang="en-US"><variable id="FormControlService"><link href="text/sbasic/shared/03/sf_formcontrol.xhp" name="SFDocuments.FormControl service"><literal>SFDocuments</literal>.<literal>FormControl</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id931583589764919" xml-lang="en-US">The <literal>FormControl</literal> service provides access to the controls that belong to a form, a subform or a table control of a <literal>FormDocument</literal>. Each instance of the <literal>FormControl</literal> service refers to a single control in the form. This service allows users to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id451618771561326" role="listitem">Get and set the properties of the control represented by the <literal>FormControl</literal> instance.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id601618771565183" role="listitem">Access the current value displayed by the control.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981618771567951" role="listitem">Set the focus on the desired control.</paragraph> + </listitem> + </list> +</section> + <paragraph role="paragraph" id="par_id301616939922857" xml-lang="en-US">To use the <literal>FormControl</literal> service in a particular form, subform or table control, all controls must have unique names.</paragraph> + <warning id="par_id541618771629112">Radio buttons that share the same group name must also have unique control names.</warning> + <paragraph role="paragraph" id="par_id51618771641273">The main purpose of the <literal>FormControl</literal> service is setting and getting the properties and values displayed by the controls in a form.</paragraph> + <paragraph role="paragraph" id="par_id81618774023346">All controls have a <literal>Value</literal> property. However, its contents will vary according to the control type. For more information, read <link href="text/sbasic/shared/03/sf_formcontrol.xhp#hd_id81598540704978" name="Value property">The <literal>Value</literal> Property</link> below.</paragraph> + <paragraph role="paragraph" id="par_id881618771651907">It is also possible to format the controls via the <literal>XControlModel</literal> and <literal>XControlView</literal> properties.</paragraph> + <tip id="par_id891598188164936" xml-lang="en-US">The <literal>SFDocuments.FormControl</literal> service is closely related to the <link href="text/sbasic/shared/03/sf_form.xhp" name="Form service"><literal>SFDocuments.Form</literal></link> service.</tip> + <bookmark xml-lang="en-US" branch="index" id="bm_id331612167249331" localize="false"> + <bookmark_value>API;awt.XControl</bookmark_value> + <bookmark_value>API;awt.XControlModel</bookmark_value> + </bookmark> + + <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>FormControl</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id361598174756160" xml-lang="en-US">The <literal>FormControl</literal> service is invoked from an existing <literal>Form</literal> service instance through its <literal>Controls</literal> method.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791598453192421">Dim oDoc as Object, myForm As Object, myControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351618773083772">Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251598453197473">Set myForm = oDoc.Forms("formDocumentName", "formName") ' SFDocuments.Form</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421598453203458">Set myControl = myForm.Controls("myTextBox") ' SFDocuments.FormControl</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581598453210170">myControl.Value = "Current time = " & Now()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="paragraph" localize="false" id="par_id51622556288409">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301622557445074">from time import localtime, strftime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621623152215419">bas = CreateScriptService('ScriptForge.Basic')</paragraph> + <paragraph role="paragraph" localize="false" id="par_id851622556289184">doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)</paragraph> + <paragraph role="paragraph" localize="false" id="par_id981622556289672">form = doc.Forms('formDocumentName', 'formName') # SFDocuments.Form</paragraph> + <paragraph role="paragraph" localize="false" id="par_id291622556290144">control = form.Controls('myTextBox') # SFDocuments.FormControl</paragraph> + <paragraph role="pycode" id="pyc_id721622556808773">control.Value = 'Current Time = ' + strftime("%a, %d %b %Y %H:%M:%S", localtime())</paragraph> + </pycode> + <tip id="par_id781618772761258">To learn more about how to open a <literal>FormDocument</literal> and get access to its forms, refer to the <link href="text/sbasic/shared/03/sf_form.xhp" name="Form service">SFDocuments.Form</link> service help page.</tip> + <paragraph role="paragraph" id="par_id951598174966322" xml-lang="en-US">Alternatively a <literal>FormControl</literal> instance can be retrieved via the <literal>SFDocuments.FormEvent</literal> service, which returns the <literal>SFDocuments.FormControl</literal> class instance that triggered the event.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id311598175259794">Sub OnEvent(ByRef poEvent As Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781598175253859"> Dim oControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598175248581"> Set oControl = CreateScriptService("SFDocuments.FormEvent", poEvent)</paragraph> + <paragraph role="bascode" xml-lang="en-US" id="bas_id801598175242937"> ' oControl now represents the instance of the FormControl class that triggered the current event</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711598175146308"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421598175139021">End Sub</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id521622558177865">def onEvent(event: uno):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841622558178345"> control = CreateScriptService('SfDocuments.FormEvent', event)</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id251598176312571" xml-lang="en-US">Note that in previous examples, the prefix <literal>"SFDocuments."</literal> may be omitted.</paragraph> + <bookmark xml-lang="en-US" branch="index" id="bm_id541618773673421" localize="false"> + <bookmark_value>FormEvent service</bookmark_value> + </bookmark> + <section id="FormEvent_Note"> + <note id="par_id951618773412097">The <literal>FormEvent</literal> service is used exclusively to create instances of the <literal>SFDocuments.Form</literal> and <literal>SFDocuments.FormControl</literal> services when a form or control event takes place.</note> + </section> + <h2 id="hd_id71598455687512" xml-lang="en-US">Control types</h2> + <paragraph role="paragraph" id="par_id851598455863395" xml-lang="en-US">The <literal>FormControl</literal> service is available for the following control types:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id121598455880500" localize="false" role="listitem">Button</paragraph> + </listitem> + <listitem> + <paragraph id="par_id441598455934376" localize="false" role="listitem">CheckBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id471598455940400" localize="false" role="listitem">ComboBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id181598455945642" localize="false" role="listitem">CurrencyField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id181598455949653" localize="false" role="listitem">DateField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id541598455953714" localize="false" role="listitem">FileControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id971598455961404" localize="false" role="listitem">FixedText</paragraph> + </listitem> + <listitem> + <paragraph id="par_id721598455965612" localize="false" role="listitem">FormattedField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id291598455969826" localize="false" role="listitem">GroupBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id111616941115924" localize="false" role="listitem">HiddenControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id101616941115596" localize="false" role="listitem">ImageButton</paragraph> + </listitem> + <listitem> + <paragraph id="par_id861598455974724" localize="false" role="listitem">ImageControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851598455979572" localize="false" role="listitem">ListBox</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851616941210356" localize="false" role="listitem">NavigationBar</paragraph> + </listitem> + <listitem> + <paragraph id="par_id321598455984243" localize="false" role="listitem">NumericField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981598455990524" localize="false" role="listitem">PatternField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id281598456002561" localize="false" role="listitem">RadioButton</paragraph> + </listitem> + <listitem> + <paragraph id="par_id91598456007438" localize="false" role="listitem">ScrollBar</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851616941293261" localize="false" role="listitem">SpinButton</paragraph> + </listitem> + <listitem> + <paragraph id="par_id241616941333335" localize="false" role="listitem">TableControl</paragraph> + </listitem> + <listitem> + <paragraph id="par_id271598456011504" localize="false" role="listitem">TextField</paragraph> + </listitem> + <listitem> + <paragraph id="par_id661598456015339" localize="false" role="listitem">TimeField</paragraph> + </listitem> + </list> + <h2 id="hd_id651583668365757" xml-lang="en-US">Properties</h2> + <table id="tab_id381583668386455"> + <tablerow> + <tablecell> + <paragraph id="par_id871583668386455" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491583668386455" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668474014" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291598538799794" role="tablehead" xml-lang="en-US">Applicable to</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401583668386455" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151583668386455" role="tablecontent" localize="false">Action</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id371583668519172" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271583668386455" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id231598538847029" role="tablecontent" localize="false" xml-lang="en-US">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583668386455" role="tablecontent" xml-lang="en-US">Specifies the action triggered when the button is clicked. Accepted values are: <literal>none</literal>, <literal>submitForm</literal>, <literal>resetForm</literal>, <literal>refreshForm</literal>, <literal>moveToFirst</literal>, <literal>moveToLast</literal>, <literal>moveToNext</literal>, <literal>moveToPrev</literal>, <literal>saveRecord</literal>, <literal>moveToNew</literal>, <literal>deleteRecord</literal>, <literal>undoRecord</literal>.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951583839708571" role="tablecontent" localize="false">Caption</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541583839708548" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751583839708362" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351598538934413" role="tablecontent" localize="false">Button, CheckBox, FixedText, GroupBox, RadioButton</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731583839708412" role="tablecontent" xml-lang="en-US">Specifies the text displayed by the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id901616942306877" role="tablecontent" localize="false">ControlSource</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411616942306677" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id791616942306698" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861616942306914" role="tablecontent" localize="false">CheckBox, ComboBox, CurrencyField, DateField, FormattedField, ImageControl, ListBox, NumericField, PatternField, RadioButton, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461616942306745" role="tablecontent" xml-lang="en-US">Specifies the rowset field mapped onto the current control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511584027709311" role="tablecontent" localize="false">ControlType</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761584027709516" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491584027709825" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261598539120502" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971584027709752" role="tablecontent" xml-lang="en-US">One of the control types listed above.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491583839767611" role="tablecontent" localize="false">Default</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31583839767743" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741583839767926" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71598539168348" role="tablecontent" localize="false">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111583839767195" role="tablecontent" xml-lang="en-US">Specifies whether a command button is the default OK button.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id321616942739272" role="tablecontent" localize="false">DefaultValue</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id241616942739459" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771616942739341" role="tablecontent" localize="false">Variant</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861616942739836" role="tablecontent" localize="false">CheckBox, ComboBox, CurrencyField, DateField, FileControl, FormattedField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271616942739359" role="tablecontent" xml-lang="en-US">Specifies the default value used to initialize a control in a new record.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83158383992056" role="tablecontent" localize="false">Enabled</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id771583839920487" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971583839920282" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891598539196786" role="tablecontent" xml-lang="en-US">All (except HiddenControl)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451583839920858" role="tablecontent" xml-lang="en-US">Specifies if the control is accessible with the cursor.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id751588333908795" role="tablecontent" localize="false">Format</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571588333908716" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781588333908500" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491598539231618" role="tablecontent" localize="false">DateField, TimeField, FormattedField (read-only)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721588333908708" role="tablecontent" xml-lang="en-US">Specifies the format used to display dates and times. It must be one of following strings:</paragraph> + <paragraph role="paragraph" id="par_id891598456980194" xml-lang="en-US">For dates: "Standard (short)", "Standard (short YY)", "Standard (short YYYY)", "Standard (long)", "DD/MM/YY", "MM/DD/YY", "YY/MM/DD", "DD/MM/YYYY", "MM/DD/YYYY" , "YYYY/MM/DD", "YY-MM-DD", "YYYY-MM-DD".</paragraph> + <paragraph role="paragraph" id="par_id221598456991070" xml-lang="en-US">For times: "24h short", "24h long", "12h short", "12h long".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id251583774433989" role="tablecontent" localize="false">ListCount</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id501583774433513" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411583774433779" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531598539561342" role="tablecontent" localize="false">ComboBox, ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph role="paragraph" id="par_id151598177605296" xml-lang="en-US">Returns the number of rows in a ListBox or a ComboBox.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id731588334016220" role="tablecontent" localize="false">ListIndex</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271588334016191" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991588334016273" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598539598242" role="tablecontent" localize="false">ComboBox, ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251588334016874" role="tablecontent" xml-lang="en-US">Specifies which item is selected in a ListBox or ComboBox. In case of multiple selection, the index of the first item is returned or only one item is set.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id81616944120456" role="tablecontent" localize="false">ListSource</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891616944120697" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831616944120587" role="tablecontent" localize="false">Variant</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301616944120610" role="tablecontent" localize="false">ComboBox, ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id901616944120614" role="tablecontent" xml-lang="en-US">Specifies the data contained in a ComboBox or a ListBox as a zero-based array of string values.</paragraph> + <paragraph role="paragraph" id="par_id21616944586559" xml-lang="en-US">Combined with <literal>ListSourceType</literal>, may also contain the name of a table, a query or a complete <literal>SQL</literal> statement.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id331616944631911" role="tablecontent" localize="false">ListSourceType</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821616944631740" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781616944631772" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id671616944631522" role="tablecontent" localize="false">ComboBox, ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131616944631625" role="tablecontent" xml-lang="en-US">Specifies the type of data contained in a combobox or a listbox.</paragraph> + <paragraph role="paragraph" id="par_id881616944631341" xml-lang="en-US">It must be one of the <link href="https://api.libreoffice.org/docs/idl/ref/ListSourceType_8idl_source.html" name="ListSourceType"><literal>com.sun.star.form.ListSourceType.*</literal></link> constants.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id451598457655392" role="tablecontent" localize="false">Locked</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961598457655506" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id571598457655365" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111598539631340" role="tablecontent" localize="false">ComboBox, CurrencyField, DateField, FileControl, FileControl, FormattedField, ImageControl, ListBox, NumericField, PatternField, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id2159845765568" role="tablecontent" xml-lang="en-US">Specifies if the control is read-only.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id21159845795140" role="tablecontent" localize="false">MultiSelect</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621598457951781" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311598457951281" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361598539747680" role="tablecontent" localize="false">ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821598457951782" role="tablecontent" xml-lang="en-US">Specifies whether the user can select multiple items in a listbox.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id421598458170141" role="tablecontent" localize="false">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351598458170114" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391598458170757" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151598539764402" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621598458170392" role="tablecontent" xml-lang="en-US">The name of the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id2915984585802" role="tablecontent" localize="false">Parent</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161598458580581" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id921598458580608" role="tablecontent" localize="false">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181598539807426" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id801598458580456" role="tablecontent" xml-lang="en-US">Depending on the parent type, a form, a subform or a tablecontrol, returns the parent <literal>SFDocuments</literal>.<literal>Form</literal> or <literal>SFDocuments</literal>.<literal>FormControl</literal> class object instance.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181598458773220" role="tablecontent" localize="false">Picture</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598458773352" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471598458773993" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831598539848472" role="tablecontent" localize="false">Button, ImageButton, ImageControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598458773588" role="tablecontent" xml-lang="en-US">Specifies the file name containing a bitmap or other type of graphic to be displayed on the control. The filename must comply with the <literal>FileNaming</literal> attribute of the <literal>ScriptForge.FileSystem</literal> service.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id341616946015404" role="tablecontent" localize="false">Required</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id251616946015886" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461616946015486" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131616946015428" role="tablecontent" localize="false">CheckBox, ComboBox, CurrencyField, DateField, ListBox, NumericField, PatternField, RadioButton, SpinButton, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91616946015258" role="tablecontent" xml-lang="en-US">A control is said required when the underlying data must not contain a <literal>null</literal> value.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491598516764653" role="tablecontent" localize="false">Text</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781598516764550" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598516764696" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761598539912452" role="tablecontent" localize="false">ComboBox, DateField, FileControl, FormattedField, PatternField, TextField, TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11159851676440" role="tablecontent" xml-lang="en-US">Gives access to the text being displayed by the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id311598517275908" role="tablecontent" localize="false">TipText</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411598517275112" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598517275920" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id171598539985022" role="tablecontent" xml-lang="en-US">All (except HiddenControl)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651598517275384" role="tablecontent" xml-lang="en-US">Specifies the text that appears as a tooltip when you hover the mouse pointer over the control.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951598517418614" role="tablecontent" localize="false">TripleState</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821598517418463" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id231598517418608" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81598540007035" role="tablecontent" localize="false">CheckBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141598517418822" role="tablecontent" xml-lang="en-US">Specifies if the checkbox control may appear dimmed (grayed) or not.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31598517671415" role="tablecontent" localize="false">Value</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701598517671373" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id2159851767113" role="tablecontent" localize="false">Variant</paragraph> + </tablecell> + <tablecell></tablecell> + <tablecell> + <paragraph id="par_id1001598540024225" role="tablecontent" xml-lang="en-US">This property depends on the current control type. Refer to <link href="text/sbasic/shared/03/sf_formcontrol.xhp#hd_id81598540704978" name="Value property">The <literal>Value</literal> property</link> for more information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id571598517730264" role="tablecontent" localize="false">Visible</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661598517730941" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981598517730694" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761598540042290" role="tablecontent" xml-lang="en-US">All (except HiddenControl)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881598517730836" role="tablecontent" xml-lang="en-US">Specifies if the control is hidden or visible.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id741598177924441" role="tablecontent" localize="false">XControlModel</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451598177924437" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id94159817792441" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311598540066789" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id191598177924897" role="tablecontent" xml-lang="en-US">The UNO object representing the control model. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControlModel.html" name="awt.XControlModel">XControlModel</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControlModel.html" name="awt.UnoControlModel">UnoControlModel</link> in the API documentation for more information.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801598178083859" role="tablecontent" localize="false">XControlView</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id811598178083501" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981598178083938" role="tablecontent" xml-lang="en-US">UNO<br/>object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id551598540079329" role="tablecontent" xml-lang="en-US">All</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731598178083442" role="tablecontent" xml-lang="en-US">The UNO object representing the control view. Refer to <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1awt_1_1XControl.html" name="awt.XControl">XControl</link> and <link href="https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1awt_1_1UnoControl.html" name="awt.UnoControl">UnoControl</link> in the API documentation for more information.</paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="hd_id81598540704978" xml-lang="en-US">The <variable id="ValueProperty"><literal>Value</literal> property</variable></h2> + <table id="tab_id48159854325479"> + <tablerow> + <tablecell> + <paragraph id="par_id10159854325492" role="tablehead" xml-lang="en-US">Control type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254158" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961598543254444" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id461598543254494" role="tablecontent" localize="false">Button</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271598543254590" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254108" role="tablecontent" xml-lang="en-US">Applicable to toggle buttons only.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id131598543254931" role="tablecontent" localize="false">CheckBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741598543254376" role="tablecontent" xml-lang="en-US">Boolean or Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521598543254630" role="tablecontent" xml-lang="en-US">0, False: not checked<br />1, True: checked<br />2: grayed out, don't know (applicable if <literal>TripleState</literal> is <literal>True</literal>)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891598543254563" role="tablecontent" localize="false">ComboBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781598543254887" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id331598543254947" role="tablecontent" xml-lang="en-US">The selected value, as a String. The <literal>ListIndex</literal> property is an alternate option to access the index of the selected value.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id58159854325446" role="tablecontent" localize="false">CurrencyField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id5159854325443" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id90159854325450" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241598543254415" role="tablecontent" localize="false">DateField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401598543254743" role="tablecontent" localize="false">Date</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421598543254587" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id851598543254508" role="tablecontent" localize="false">FileControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731598543254544" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971598543254757" role="tablecontent" xml-lang="en-US">A file name formatted in accordance with the <literal>FileNaming</literal> property of the <literal>ScriptForge.FileSystem</literal> service</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id921598543254323" role="tablecontent" localize="false">FormattedField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221598543254760" role="tablecontent" xml-lang="en-US">String or Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651598543254212" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id581616946805539" role="tablecontent" localize="false">HiddenControl</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id37161694680551" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491616946805219" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id151598543254318" role="tablecontent" localize="false">ListBox</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id42159854325422" role="tablecontent" xml-lang="en-US">String or array of strings</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601598543254780" role="tablecontent" xml-lang="en-US">The selected row(s) as a single string or an array of strings. Only a single value can be set. If the box is linked to a database, this property gets or sets the underlying data. Otherwise it gets or sets the data being displayed.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771598543254973" role="tablecontent" localize="false">NumericField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461598543254909" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161598543254662" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id38159854325480" role="tablecontent" localize="false">PatternField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81598543254625" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911598543254335" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id791598543254779" role="tablecontent" localize="false">RadioButton</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561598543254115" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id851598543254624" role="tablecontent" xml-lang="en-US">Each button has its own name. Multiple RadioButton controls are linked together when they share the same group name. If a RadioButton is set to <literal>True</literal>, the other related buttons are automatically set to <literal>False</literal></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id141598543254361" role="tablecontent" localize="false">ScrollBar</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531598543254869" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21598543254994" role="tablecontent" xml-lang="en-US">Must be within the predefined bounds</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id91616947400762" role="tablecontent" localize="false">SpinButton</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951616947400919" role="tablecontent" xml-lang="en-US">Numeric</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id48161694740085" role="tablecontent" xml-lang="en-US">Must be within the predefined bounds</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id811598543254140" role="tablecontent" localize="false">TextField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751598543254299" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441598543254738" role="tablecontent" xml-lang="en-US">The text appearing in the field</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id89159854325478" role="tablecontent" localize="false">TimeField</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id341598543254600" role="tablecontent" localize="false">Date</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881598543254964" localize="false" role="tablecontent" xml-lang="en-US"></paragraph> + </tablecell> + </tablerow> + </table> + <h2 id="hd_id421612628828054" xml-lang="en-US">Event properties</h2> + <paragraph role="paragraph" id="par_id41612629140856" xml-lang="en-US">The properties below return or set URI strings that define the script triggered by the event.</paragraph> + <table id="tab_id951612628879819"> + <tablerow> + <tablecell> + <paragraph id="par_id961612628879819" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401612628879819" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id281612628879819" role="tablehead" xml-lang="en-US">Description as labeled in the Basic IDE</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id801612707166342" localize="false" role="tablecontent" xml-lang="en-US">OnActionPerformed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91612707166532" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612707166258" role="tablecontent" xml-lang="en-US">Execute action</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id261612707166662" localize="false" role="tablecontent" xml-lang="en-US">OnAdjustmentValueChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id79161270716675" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831612707166731" role="tablecontent" xml-lang="en-US">While adjusting</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id431616948330476" localize="false" role="tablecontent" xml-lang="en-US">OnApproveAction</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301616948330694" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id901616948330305" role="tablecontent" xml-lang="en-US">Approve action</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id391616948330165" localize="false" role="tablecontent" xml-lang="en-US">OnApproveReset</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821616948330888" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111616948330257" role="tablecontent" xml-lang="en-US">Prior to reset</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id211616948330775" localize="false" role="tablecontent" xml-lang="en-US">OnApproveUpdate</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id271616948330553" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451616948330759" role="tablecontent" xml-lang="en-US">Before updating</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id471616948330872" localize="false" role="tablecontent" xml-lang="en-US">OnChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71616948330769" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211616948330895" role="tablecontent" xml-lang="en-US">Changed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id171616948330656" localize="false" role="tablecontent" xml-lang="en-US">OnErrorOccurred</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id121616948330654" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id2216169483303" role="tablecontent" xml-lang="en-US">Error occurred</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id431612629836735" localize="false" role="tablecontent" xml-lang="en-US">OnFocusGained</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111612629836630" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id1001612629836902" role="tablecontent" xml-lang="en-US">When receiving focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id701612629836389" localize="false" role="tablecontent" xml-lang="en-US">OnFocusLost</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291612629836294" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id62161262983683" role="tablecontent" xml-lang="en-US">When losing focus</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id10161270735471" localize="false" role="tablecontent" xml-lang="en-US">OnItemStateChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id51612707354544" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612707354899" role="tablecontent" xml-lang="en-US">Item status changed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241612629836863" localize="false" role="tablecontent" xml-lang="en-US">OnKeyPressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81612629836634" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id881612629836744" role="tablecontent" xml-lang="en-US">Key pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id201612629836996" localize="false" role="tablecontent" xml-lang="en-US">OnKeyReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591612629836830" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161612629836775" role="tablecontent" xml-lang="en-US">Key released</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id111612629836950" localize="false" role="tablecontent" xml-lang="en-US">OnMouseDragged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891612629836630" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id461612629836679" role="tablecontent" xml-lang="en-US">Mouse moved while key presses</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id711612629836495" localize="false" role="tablecYesontent" xml-lang="en-US">OnMouseEntered</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131612629836291" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id151612629836151" role="tablecontent" xml-lang="en-US">Mouse inside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id971612629836286" localize="false" role="tablecontent" xml-lang="en-US">OnMouseExited</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211612629836725" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361612629836624" role="tablecontent" xml-lang="en-US">Mouse outside</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721612629836537" localize="false" role="tablecontent" xml-lang="en-US">OnMouseMoved</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311612629836481" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721612629836752" role="tablecontent" xml-lang="en-US">Mouse moved</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id55161262983695" localize="false" role="tablecontent" xml-lang="en-US">OnMousePressed</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981612629836116" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381612629836635" role="tablecontent" xml-lang="en-US">Mouse button pressed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id621612629836155" localize="false" role="tablecontent" xml-lang="en-US">OnMouseReleased</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711612629836704" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id35161262983642" role="tablecontent" xml-lang="en-US">Mouse button released</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241616948666992" localize="false" role="tablecontent" xml-lang="en-US">OnResetted</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id31616948666215" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951616948666674" role="tablecontent" xml-lang="en-US">After resetting</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id84161270760678" localize="false" role="tablecontent" xml-lang="en-US">OnTextChanged</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id811612707606330" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621612707606219" role="tablecontent" xml-lang="en-US">Text modified</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id571616948721115" localize="false" role="tablecontent" xml-lang="en-US">OnUpdated</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id41616948721642" role="tablecontent" xml-lang="en-US">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311616948721872" role="tablecontent" xml-lang="en-US">After updating</paragraph> + </tablecell> + </tablerow> + </table> + <tip id="par_id961618181634181">To learn more about URI strings, refer to the <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification" name="URI specification">Scripting Framework URI Specification</link>.</tip> + <table id="tab_id891606472825856"> + <tablerow> + <tablecell colspan="2"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the FormControl Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id751612709117248" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_formcontrol.xhp#Controls" name="Controls method">Controls</link><br/> + </paragraph></tablecell> + <tablecell><paragraph id="par_id63161270911712" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_formcontrol.xhp#SetFocus" name="SetFocus method">SetFocus</link><br/> + </paragraph></tablecell> + </tablerow> + </table> + +<section id="Controls"> + <comment> Controls -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41584541257826"> + <bookmark_value>FormControl service;Controls</bookmark_value> + </bookmark> + <h2 id="hd_id95158454125767" localize="false">Controls</h2> + <paragraph role="paragraph" id="par_id161584541257982">This method is applicable only to controls of the <literal>TableControl</literal> type. The returned value depends on the arguments provided.</paragraph> + <paragraph role="paragraph" id="par_id701618777636827">If the optional argument <literal>controlname</literal> is absent, then a zero-based Array containing the names of all controls is returned.</paragraph> + <paragraph role="paragraph" id="par_id851618777715892">On the other hand, if a <literal>controlname</literal> is provided, the method returns a <literal>FormControl</literal> class instance corresponding to the specified control.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id181622558671497"><input>svc.Controls(): str[0..*]</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id531622558833434"><input>svc.Controls(controlname: str): svc</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id1001584541257789"><emph>controlname</emph>: A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id151598185478904">Dim myGrid As Object, myList As Variant, myControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21598185484092">Set myGrid = myForm.Controls("myTableControl") ' SFDocuments.FormControl</paragraph> + <paragraph role="bascode" id="bas_id471618778075117">' Returns an Array with the names of all controls in "myTableControl"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641598185489492">myList = myGrid.Controls()</paragraph> + <paragraph role="paragraph" id="par_id931618778110273">' Returns a FormControl class instance corresponding to "myCheckBox"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921598185495193">Set myControl = myGrid.Controls("myCheckBox")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id391622559441530">Using Python:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id81622558961009">grid = form.Controls('myTableControl') # SFDocuments.FormControl</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391622558961234">control_names = form.Controls()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571622558961435">control = grid.Controls('myCheckBox') # SFDocuments.FormControl</paragraph> + </pycode> +</section> +<section id="SetFocus"> + <comment> SetFocus -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id721583933076548"> + <bookmark_value>FormControl service;SetFocus</bookmark_value> + </bookmark> + <h2 id="hd_id681583933076692" localize="false">SetFocus</h2> + <paragraph role="paragraph" id="par_id871583933076448">Sets the focus on the control. Returns <literal>True</literal> if focusing was successful.</paragraph> + <paragraph role="paragraph" id="par_id151598178880227" xml-lang="en-US">This method is often called from a form or control event.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id991622559468457"><input>svc.SetFocus(): bool</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221598179105596">Dim oDoc As Object, oForm As Object, oControl As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id171598179111121">Set oDoc = CreateScriptService("SFDocuments.Document", ThisComponent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681598179123436">Set oForm = oDoc.Forms(0)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741616950370203">Set oControl = oForm.Controls("thisControl") ' SFDocuments.FormControl</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361598179135096">oControl.SetFocus()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id51623154762285">bas = CreateScriptService('ScriptForge.Basic')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571622559687626">doc = CreateScriptService('SFDocuments.Document', bas.ThisComponent)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231622559687813">form = doc.Forms(0)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891622559687994">control = form.Controls('thisControl') # SFDocuments.FormControl</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801622560297771">control.SetFocus()</paragraph> + </pycode> +</section> +<comment> Additional examples -------------------------------------------------------------------------------------------------------------------------- </comment> + <h2 id="hd_id141618777179310">Additional examples</h2> + <paragraph role="paragraph" id="par_id331618777195723">Below are two examples that illustrate the use of the <literal>FormControl</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id371618776324489">The first example reads the current value in a ComboBox containing city names and writes it to a FixedTest control in a Form:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id591618776422887">Dim oDoc as Object, myForm as Object, myControl as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911618776450399">Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311618776466602">myForm = oDoc.Forms("formDocumentName", "formName")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741618776467585">Dim lbCity : lbCity = myForm.Controls("labelCity")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291618776467995">Dim cbCity : cbCity = myForm.Controls("comboboxCity")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611618776468297">lbCity.Caption = "Selected City: " & cbCity.Value</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id991622562833004">bas = CreateScriptService('ScriptForge.Basic') # Basic-like methods</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321622561047923">doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321622561048131">form = doc.Forms('formDocumentName', 'formName')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id1001622561048346">lbl_city = form.Controls('labelCity')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id151622561048563">combo_city = form.Controls('comboboxCity')</paragraph> + <paragraph role="pycode" id="pyc_id781622561048794">lbl_city.Caption = "Selected city: " + combo_city.Value</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id251618776614814">The following code snippet can be used to process RadioButton controls that share the same group name. In this example, suppose there are three radio buttons with names <literal>optA</literal>, <literal>optB</literal> and <literal>optC</literal> and we wish to display the caption of the selected control.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461618776931086">Dim oDoc as Object, myForm as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491618776931454">Set oDoc = CreateScriptService("SFDocuments.Document", ThisDataBaseDocument)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411618776931743">myForm = oDoc.Forms("formDocumentName", "formName")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721618776931999">Dim optNames As Object : optNames = Array("optA", "optB", "optC")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91618776932264">Dim optControl as Object, opt as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281618776932488">For Each opt In optNames</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211618776932791"> optControl = myForm.Controls(opt)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311618776933039"> If optControl.Value = True Then</paragraph> + <paragraph role="bascode" id="bas_id251618776933304"> MsgBox "Selected option: " & optControl.Caption</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581618776933600"> Exit For</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511618776933863"> End If</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31618776934159">Next opt</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id991622562822004">bas = CreateScriptService('ScriptForge.Basic') # Basic-like methods</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681622562079356">doc = CreateScriptService('SFDocuments.Document', bas.ThisDatabaseDocument)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941622562079539">form = doc.Forms('formDocumentName', 'formName')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741622562079722">radio_buttons = ['optA', 'optB', 'optC']</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901622562079883">for name in radio_buttons:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id51622562080068"> control = form.controls(name)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361622562080243"> if control.Value == True:</paragraph> + <paragraph role="pycode" id="pyc_id441622562080419"> bas.MsgBox('Selected option: ' + control.Caption)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id61622563076603"> break</paragraph> + </pycode> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_basic.xhp#BasicService"/> + <embed href="text/sbasic/shared/03/sf_form.xhp#FormService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + </section> +</body> +</helpdocument>
\ No newline at end of file diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_intro.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_intro.xhp new file mode 100644 index 000000000..98081e545 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_intro.xhp @@ -0,0 +1,181 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_FormControl" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Creating Python Scripts with ScriptForge</title> + <filename>/text/sbasic/shared/03/sf_intro.xhp</filename> + </topic> +</meta> + +<body> + <bookmark localize="false" branch="index" id="bm_id41582391760114"> + <bookmark_value>Python scripts with ScriptForge</bookmark_value> + </bookmark> + <h1 id="hd_id461623364876507"><variable id="title"><link href="text/sbasic/shared/03/sf_intro.xhp" name="SF_Intro_Page">Creating Python Scripts with <literal>ScriptForge</literal></link></variable></h1> + <h2 id="hd_id361623410405420">Differences between Basic and Python</h2> + <paragraph role="paragraph" id="par_id41623410443946">The <link href="text/sbasic/shared/03/lib_ScriptForge.xhp" name="SF_Lib">ScriptForge library</link> 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, <literal>ScriptForge</literal> users must be aware of some characteristics of the library when using Python:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id551623410718241" role="listitem"><emph>Methods and Property names:</emph> In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id741623411104297" role="listitem"><emph>Arguments:</emph> All keyword arguments passed on to methods are lowercased.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id441623411216354" role="listitem"><emph>Dates:</emph> All date objects are passed and returned as <literal>datetime.datetime</literal> native Python objects.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id891623411367669" role="listitem"><emph>Arrays:</emph> 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.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981623411507442" role="listitem"><emph>None:</emph> Python's <literal>None</literal> keyword is equivalent to Basic's <literal>Null</literal>, <literal>Empty</literal> or <literal>Nothing</literal>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id21623411611447" role="listitem"><emph>UNO objects:</emph> All UNO structures are exchanged between Basic and Python without any changes.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id651623412069496" role="listitem"><emph>Debugging:</emph> Whenever an error occurs in Python scripts that use <literal>ScriptForge</literal>, 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.</paragraph> + </listitem> + </list> + <tip id="par_id31623411828158">Visit <link href="text/sbasic/python/main0000.xhp#" name="pyscripts_link">%PRODUCTNAME Python Scripts Help</link> for more information on Python scripting using %PRODUCTNAME.</tip> + <h2 id="hd_id391623411150080">Running Python scripts on %PRODUCTNAME</h2> + <paragraph role="paragraph" id="par_id411623364895100">Depending on what you intend to achieve, you may choose one of the following approaches to running Python scripts in %PRODUCTNAME:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id681623365274024" role="listitem"><emph>Run Scripts inside the current %PRODUCTNAME process:</emph> Python scripts are executed from within the %PRODUCTNAME process by using the <menuitem>Tools - Macros - Run Macro</menuitem> 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.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id761623365278133" role="listitem"><emph>Run Scripts separately from the %PRODUCTNAME process:</emph> Python scripts are executed from an external process that connects to an ongoing %PRODUCTNAME process using a socket.</paragraph> + </listitem> + </list> + <tip id="par_id631623365667011">If you plan to run scripts from inside the %PRODUCTNAME process, it is recommended to install the <link href="https://extensions.libreoffice.org/en/extensions/show/apso-alternative-script-organizer-for-python" name="APSO">APSO (Alternative Script Organizer for Python) extension</link>. However, to develop Python scripts from outside %PRODUCTNAME, you can choose your preferred Python IDE.</tip> + + <h2 id="hd_id431623365836802">Running Scripts from inside the %PRODUCTNAME process</h2> + <h3 id="hd_id111623365861568">Using the APSO extension</h3> + <paragraph role="paragraph" id="par_id681623365892513">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 <menuitem>Tools - Macros - Organize Python Scripts</menuitem>.</paragraph> + <paragraph role="paragraph" id="par_id111623366334727">In APSO's main window go to <menuitem>Menu - Python Shell</menuitem>.</paragraph> + <tip id="par_id931623366329927">Alternatively you can open APSO using the default shortcut <keycode>Alt + Shift + F11</keycode>.</tip> + <paragraph role="paragraph" id="par_id661623366478092">Now you can start typing Python commands and the shell will print the corresponding output after each line of code is executed.</paragraph> + <paragraph role="paragraph" id="par_id581623366559478">To start using the <literal>ScriptForge</literal> library, you need to import the <literal>CreateScriptService</literal> method, with which you will be able to access the services provided by the library. The example below uses the <literal>Basic</literal> service to display a message box.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id531623366688016">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121623366689320">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id561623366689495">bas.MsgBox("Hello!")</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id701623366829587">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.</paragraph> + <paragraph role="paragraph" id="par_id471623366906045">Now you can start executing Python commands using any of the ScriptForge services. For example, the code snippet below uses the <literal>UI</literal> service to create a blank Writer document.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id331623367002488">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501623367002935">doc = ui.CreateDocument("Writer")</paragraph> + </pycode> + + <h3 id="hd_id961623367376768">Creating Python script files</h3> + <paragraph role="paragraph" id="par_id821623367433650">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.</paragraph> + <paragraph role="paragraph" id="par_id51623367560321">The first step is to locate where your user scripts are stored. For that, refer to <link href="text/sbasic/python/python_locations.xhp" name="Python_Scripts_Path">Python Scripts Organization and Location</link> help page.</paragraph> + <paragraph role="paragraph" id="par_id821623367773032">Now you can create a text file inside your Python user scripts folder, for instance <emph>sf_test.py</emph>, and start typing your scripts.</paragraph> + <paragraph role="paragraph" id="par_id271623367917630">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 <emph>sf_test.py</emph> file.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id71623367973469">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id351623367973643">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821623367973796"></paragraph> + <paragraph role="pycode" localize="false" id="pyc_id331623367973949">def increment_cell(args=None):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931623367974077"> value = doc.GetValue("A1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id741623367974212"> value += 1</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841623367974349"> doc.SetValue("A1", value)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231623368367747"></paragraph> + <paragraph role="pycode" localize="false" id="pyc_id11623368368139">g_exportedScripts = (increment_cell, )</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id171623368511426">This example creates the <literal>increment_cell</literal> function. Note that <literal>g_exportedScripts</literal> is a tuple that tells which functions will be displayed in %PRODUCTNAME as user scripts.</paragraph> + <paragraph role="paragraph" id="par_id471623368615244">To run this script from within a Calc document:</paragraph> + <list type="ordered"> + <listitem> + <paragraph id="par_id811623368677444" role="listitem">Create or open a Calc file.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id281623368679141" role="listitem">Enter some numeric value into cell "A1" in the current sheet.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id111623368679893" role="listitem">Go to <menuitem>Tools - Macros - Run Macros</menuitem> .</paragraph> + </listitem> + <listitem> + <paragraph id="par_id421623368680565" role="listitem">Choose My Macros - sf_test in the library selector. Then choose the <literal>increment_cell</literal> function under the <menuitem>Macro Name</menuitem> list.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id131623368875763" role="listitem">Click <emph>Run</emph>. Note that the value in cell "A1" was incremented by 1.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id781623368934689">You can also use APSO to run Python scripts in a similar manner:</paragraph> + <list type="ordered"> + <listitem> + <paragraph id="par_id501623369002537" role="listitem">First open APSO by going to <menuitem>Tools - Macros - Organize Python Scripts</menuitem>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id521623369004825" role="listitem">In the macro list, navigate to <menuitem>My Macros - sf_test - increment_cell</menuitem>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id101623369005929" role="listitem">Click <menuitem>Execute</menuitem>.</paragraph> + </listitem> + </list> + + <h2 id="hd_id531623369208159">Running Scripts separately from the %PRODUCTNAME process</h2> + <section id="InstallPath"> + <h3 id="hd_id261623370168228">Determining the Installation Path</h3> + <paragraph role="paragraph" id="par_id261623369722023">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 <literal>ScriptForge</literal> provides a quick way to identify your installation path. For that, open APSO's Python shell and type:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id261623369853713">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id201623369854992">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id831623370058117">fs.FileNaming = "SYS"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941623369856601">inst_dir = fs.InstallFolder</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941623369856722">print(inst_dir)</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id81623370150730">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.</paragraph> + <paragraph role="paragraph" id="par_id451623370201479">For example, suppose you get <emph>/usr/lib/libreoffice/</emph> as the result from running the Python code above. Then you need to consider <emph>/usr/lib/libreoffice/program</emph> as the path to run your Python scripts.</paragraph> + </section> + + <h3 id="hd_id231623370501084">Start %PRODUCTNAME with socket settings</h3> + <paragraph role="paragraph" id="par_id721623369245475">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.</paragraph> + <paragraph role="paragraph" id="par_id221623369584132">Open the your operating system's command prompt, navigate to the program folder of your %PRODUCTNAME installation directory and type:</paragraph> + <paragraph role="paragraph" localize="false" id="par_id381623369456352"><input>./soffice --accept='socket,host=localhost,port=2021;urp;'</input></paragraph> + <paragraph role="paragraph" id="par_id981623370706743">The command above will start %PRODUCTNAME with a communication channel open so that other processes can exchange messages with it.</paragraph> + <paragraph role="paragraph" id="par_id621623370871360">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.</paragraph> + <paragraph role="paragraph" localize="false" id="par_id371623370974348"><input>./soffice --writer --accept='socket,host=localhost,port=2021;urp;'</input></paragraph> + <paragraph role="paragraph" id="par_id431623373618951">Take note of the <literal>host</literal> and <literal>port</literal> parameters, which in this example are <emph>localhost</emph> and <emph>2021</emph>, respectively.</paragraph> + + <h3 id="hd_id861623370468356">Running an External Python Shell</h3> + <paragraph role="paragraph" id="par_id621623371253647">Start the Python shell from within the <emph>program</emph> folder inside your %PRODUCTNAME installation path. Follow the steps <link href="text/sbasic/shared/03/sf_intro.xhp#InstallPath" name="Install_Path">above</link> to learn how to find your installation path.</paragraph> + <paragraph role="paragraph" id="par_id11623373098602"><emph>On Linux / Mac OS:</emph></paragraph> + <paragraph role="paragraph" localize="false" id="par_id601623372243559"><input>$ cd /usr/lib/libreoffice/program</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id601623372243336"><input>$ python</input></paragraph> + <paragraph role="paragraph" id="par_id311623373151552"><emph>On Windows:</emph></paragraph> + <paragraph role="paragraph" localize="false" id="par_id601623372243204"><input>$ cd C:\Program Files\LibreOffice\program\</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id601623372243399"><input>$ python.exe</input></paragraph> + <paragraph role="paragraph" id="par_id791623373520018">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.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id281623373588570">from scriptforge import ScriptForge, CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121623373589306">ScriptForge(hostname='localhost', port=2021)</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id351623373686414">The second line of code above defines the <literal>host</literal> and <literal>port</literal> settings so that the Python shell can communicate with an ongoing %PRODUCTNAME process opened with the same socket settings.</paragraph> + <paragraph role="paragraph" id="par_id721623373769471">Now you can run other Python commands and they will be able to communicate with the %PRODUCTNAME process. For example:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731623373850131">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id731623373850255">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671623373851588">doc = ui.OpenDocument("~/Documents/myFile.ods")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631623373909828">bas.MsgBox(doc.DocumentType)</paragraph> + </pycode> + + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#ScriptForge_lib"/> + <embed href="text/sbasic/python/main0000.xhp#pythonscriptshelp"/> + <embed href="text/shared/guide/start_parameters.xhp#Title_h1"/> + </section> + </body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_l10n.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_l10n.xhp new file mode 100644 index 000000000..453fe345a --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_l10n.xhp @@ -0,0 +1,375 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_L10N" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.L10N service</title> + <filename>/text/sbasic/shared/03/sf_l10n.xhp</filename> + </topic> +</meta> +<body> +<section id="ScriptForge-sf_l10n"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571585843652319"> + <bookmark_value>L10N service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id521585843652750" xml-lang="en-US"><variable id="L10NService"><link href="text/sbasic/shared/03/sf_l10n.xhp" name="L10N service"><literal>ScriptForge</literal>.<literal>L10N</literal> service</link></variable></h1> + <paragraph role="paragraph" xml-lang="en-US" id="par_id411585843652556">This service provides a number of methods related to the translation of strings with minimal impact on the program's source code. The methods provided by the <literal>L10N</literal> service can be used mainly to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id601614351922212" role="listitem">Create POT files that can be used as templates for translation of all strings in the program.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id131614352196513" role="listitem">Get translated strings at runtime for the language defined in the <literal>Locale</literal> property.</paragraph> + </listitem> + </list> +</section> + + <note id="par_id971614966420419">The acronym <literal>L10N</literal> stands for Localization and refers to a set of procedures for translating software to a specific country or region.</note> + <paragraph role="paragraph" id="par_id291585843652438" xml-lang="en-US">PO files have long been promoted in the free software community as a means to providing multilingual user interfaces. This is accomplished through the use of human-readable text files with a well defined structure that specifies, for any given language, the source language string and the localized string.</paragraph> + <paragraph role="paragraph" id="par_id181585843652814" xml-lang="en-US">The main advantage of the PO format is dissociation of the programmer and the translator. PO files are independent text files, so the programmer can send POT template files to translators, who will then translate their contents and return the translated PO files for each supported language.</paragraph> + <tip id="par_id811614352321187">The <literal>L10N</literal> service is based on the GNU implementation of PO (portable object) files. To learn more about this file format, visit <link href="https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html" name="GetText">GNU gettext Utilities: PO Files</link>.</tip> + <paragraph role="paragraph" id="par_id91585843652832" xml-lang="en-US">This service implements the methods listed below:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id1158584365237" role="listitem" xml-lang="en-US"><emph>AddText</emph>: Used by the programmer to build a set of strings that will be translated later.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id81637866601151" role="listitem"><emph>AddTextsFromDialog</emph>: Extracts all strings from a <literal>Dialog</literal> service instance.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id681585843652331" role="listitem" xml-lang="en-US"><emph>ExportToPOTFile</emph>: Exports the strings added by the <literal>AddText</literal> method to a POT file.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id531585843652697" role="listitem" xml-lang="en-US"><emph>GetText</emph>: Gets the translated strings at runtime.</paragraph> + </listitem> + </list> + <note id="par_id361614361362393">Note that the first two methods are used to build a set of translatable strings and export them to a POT file. However, it is not mandatory to create POT files using these methods. Since they are text files, the programmer could have created them using any text editor.</note> + + <h2 id="hd_id351585843652312" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>L10N</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id421614353247163">There are several ways to invoke the <literal>L10N</literal> service using up to five optional arguments that specify the folder where PO files are stored, the locale and encoding to be used, as well as a fallback PO file and its encoding.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id481625854402332"> + <input>CreateScriptService("L10N", opt foldername: str, opt locale: str, encoding: str = "UTF-8", opt locale2: str, encoding2: str = "UTF-8"): svc</input> + </paragraph> + <paragraph role="paragraph" id="par_id331585843652877"><emph>foldername</emph>: The folder containing the PO files. It must be expressed in the <literal>FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id581585843652789"><emph>locale</emph>: A string in the form "la-CO" (language-COUNTRY) or in the form "la" (language) only.</paragraph> + <paragraph role="paragraph" id="par_id591646219881864"><emph>encoding</emph>: The character set to be used. The default encoding is "UTF-8".</paragraph> + <paragraph role="paragraph" id="par_id281646219882464"><emph>locale2</emph>: A string specifying the fallback locale to be used in case the PO file corresponding to the locale defined the <literal>locale</literal> parameter does not exist. This parameter is expressed in the form "la-CO" (language-COUNTRY) or "la" (language) only.</paragraph> + <paragraph role="paragraph" id="par_id881646219882951"><emph>encoding2</emph>: The character set of the fallback PO file corresponding to the <literal>locale2</literal> argument. The default encoding is "UTF-8".</paragraph> + <note id="par_id141613001281573">To learn more about the names of character sets, visit <link href="https://www.iana.org/assignments/character-sets/character-sets.xhtml" name="Character Sets">IANA's Character Set</link> page. Beware that %PRODUCTNAME does not implement all existing character sets.</note> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id891614358528334">The following example instantiates the <literal>L10N</literal> service without any optional arguments. This will only enable the <literal>AddText</literal> and <literal>ExportToPOTFile</literal> methods, which is useful for creating POT files.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891585843652669">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821585843652135">Dim myPO As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151585843652269">Set myPO = CreateScriptService("L10N")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id611614358672609">The example below specifies the folder containing the PO files. Because the locale is not defined, the service instance will use the locale defined for the %PRODUCTNAME user interface, which is the same locale defined in the <literal>OfficeLocale</literal> property of the <link href="text/sbasic/shared/03/sf_platform.xhp" name="OfficeLocale_link">Platform</link> service.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id451614358683971">Set myPO = CreateScriptService("L10N", "C:\myPOFiles")</paragraph> + </bascode> + <warning id="par_id391625855630975">The example above will result in an runtime error if the PO file corresponding to the <literal>OfficeLocale</literal> locale does not exist in the specified folder.</warning> + <paragraph role="paragraph" id="par_id321614358809763">In the example below, the locale is explicitly defined to be Belgian French ("fr-BE"), hence the service will load the file "fr-BE.po" from the folder "C:\myPOFiles". If the file does not exist, an error will occur.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id661614358846464">Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id271646220649616">To avoid errors, it is possible to specify a preferred and a fallback locale and encoding. The following example will first try to load the file "fr-BE.po" from the specified folder and if it does not exist, the file "en-US.po" will be loaded.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id551646220782634">Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8", "en-US", "UTF-8")</paragraph> + </bascode> + <paragraph role="tip" id="par_id411585843652496" xml-lang="en-US">PO files must be named in the form "la-CO.po" or "la.po", where "la" refers to the language and "CO" is the country. Some examples are: "en-US.po", "fr-BE.po" or "fr.po".</paragraph> + <paragraph role="paragraph" id="par_id171585843652545" xml-lang="en-US">It is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891585843652617">Set myPO = myPO.Dispose()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id281625854773330">The examples above can be translated to Python as follows:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941625854656863">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id51625854657247">myPO = CreateScriptService('L10N')</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761625854846211">myPO = CreateScriptService('L10N', r'C:\myPOFiles')</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id311625854879209">myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id981646221720301">myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id11625855490095">myPO = myPO.Dispose()</paragraph> + </pycode> + <note id="par_id301614358956087">Several instances of the <literal>L10N</literal> service may coexist. However, each instance must use a separate directory for its PO files.</note> + +<bookmark localize="false" branch="index" id="bm_id871614359551930"> + <bookmark_value>L10N service;Folder</bookmark_value> + <bookmark_value>L10N service;Languages</bookmark_value> + <bookmark_value>L10N service;Locale</bookmark_value> +</bookmark> +<h2 id="hd_id561585843652465" xml-lang="en-US">Properties</h2> + <table id="tab_id711585843652120"> + <tablerow> + <tablecell> + <paragraph id="par_id181585843652958" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741585843652162" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291585843652823" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351585843652638" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id781585843652397" role="tablecontent" xml-lang="en-US" localize="false">Folder</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451585843652928" role="tablecontents" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351585843652874" role="tablecontents" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751585843652642" role="tablecontent" xml-lang="en-US">The folder containing the PO files (see the <link href="text/sbasic/shared/03/sf_filesystem.xhp#bm_id901612991354326" name="FileNaming property"><literal>FileSystem.FileNaming</literal></link> property to learn about the notation used).</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161585843652104" role="tablecontent" xml-lang="en-US" localize="false">Languages</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id96158584365279" role="tablecontents" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611585843652345" role="tablecontents" xml-lang="en-US" localize="false">Array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id331585843652912" role="tablecontent" xml-lang="en-US">A zero-based array listing all the base names (without the ".po" extension) of the PO-files found in the specified <literal>Folder</literal>.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721585843652496" role="tablecontent" xml-lang="en-US" localize="false">Locale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961585843652589" role="tablecontents" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611585843652290" role="tablecontents" xml-lang="en-US" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561585843652947" role="tablecontent" xml-lang="en-US">The currently active language-COUNTRY combination. This property will be initially empty if the service was instantiated without any of the optional arguments.</paragraph> + </tablecell> + </tablerow> + </table> + +<table id="tab_id551614360519973"> + <tablerow> + <tablecell colspan="3"> + <paragraph id="par_id231614360519973" role="tablehead">List of Methods in the L10N Service</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id611614360519255" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_l10n.xhp#AddText" name="AddText">AddText</link><br/> + <link href="text/sbasic/shared/03/sf_l10n.xhp#AddTextsFromDialog" name="AddTextsFromDialog">AddTextsFromDialog</link> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611614360519104" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_l10n.xhp#ExportToPOTFile" name="ExportToPOTFile">ExportToPOTFile</link><br/><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611614360518452" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_l10n.xhp#GetText" name="GetText">GetText</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + + +<section id="AddText"> + <comment> AddText ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id951585843652555"> + <bookmark_value>L10N service;AddText</bookmark_value> + </bookmark> + <h2 id="hd_id191585843652902" localize="false">AddText</h2> + <paragraph role="paragraph" id="par_id1001585843652271">Adds a new entry in the list of localizable strings. It must not exist yet.</paragraph> + <paragraph role="paragraph" id="par_id641625855725050">The method returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id241625855910866"> + <input>svc.AddText(context: str = '', msgid: str = '', comment: str = ''): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id391585843652753"><emph>context</emph>: The key to retrieve the translated string with the <literal>GetText</literal> method. This parameter has a default value of "".</paragraph> + <paragraph role="paragraph" id="par_id581585844419114" xml-lang="en-US"><emph>msgid</emph>: The untranslated string, which is the text appearing in the program code. It must not be empty. The <literal>msgid</literal> becomes the key to retrieve the translated string via <literal>GetText</literal> method when <literal>context</literal> is empty.</paragraph> + <paragraph role="paragraph" id="par_id311614361926844">The <literal>msgid</literal> string may contain any number of placeholders (%1 %2 %3 ...) for dynamically modifying the string at runtime.</paragraph> + <paragraph role="paragraph" id="par_id541585844475331" xml-lang="en-US"><emph>comment</emph>: Optional comment to be added alongside the string to help translators.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id461614364298440">The example below creates a set of strings in English:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61585843652630">myPO.AddText(, "This is a string to be included in a POT file")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61585843652141">myPO.AddText("CTX1", "A string with a context")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61585843653298">myPO.AddText(, "Provide a String value", Comment := "Do not translate the word String")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821625856085258">myPO.AddText(msgid = 'This is a string to be included in a POT file')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821625856440025">myPO.AddText('CTX1', 'A string with a context')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id521625856443322">myPO.AddText(msgid = 'Provide a String value', comment = 'Do not translate the word String')</paragraph> + </pycode> +</section> + +<section id="AddTextsFromDialog"> + <comment> AddTextsFromDialog ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id951585843650024"> + <bookmark_value>L10N service;AddTextsFromDialog</bookmark_value> + </bookmark> + <h2 id="hd_id191585843652058" localize="false">AddTextsFromDialog</h2> + <paragraph role="paragraph" id="par_id1001585843659821">Automatically extracts strings from a dialog and adds them to the list of localizable text strings. The following strings are extracted:</paragraph> + <section id="L10NDlgControls"> + <list type="unordered"> + <listitem> + <paragraph id="par_id621637863440015" role="listitem">The title of the dialog.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id61637863440399" role="listitem">The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id251637863440626" role="listitem">Static strings in ListBoxes and ComboBoxes.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id811637863596791" role="listitem">The tooltip or help text displayed when the mouse hovers over the control.</paragraph> + </listitem> + </list> + </section> + <paragraph role="paragraph" id="par_id641625855723650">The method returns <literal>True</literal> if successful.</paragraph> + <note id="par_id731637863894577">The dialog from which strings will be extracted must not be open when the method is called.</note> + <paragraph role="paragraph" id="par_id911637864050221">When a <literal>L10N</literal> service instance is created from an existing PO file, use the <link href="text/sbasic/shared/03/sf_dialog.xhp#GetTextsFromL10N" name="GetTextsFromL10N">GetTextsFromL10N</link> method from the <literal>Dialog</literal> service to automatically load all translated strings into the dialog.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id241625855910158"> + <input>svc.AddTextsFromDialog(dialog: svc): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id391585843652113"><emph>dialog</emph>: a Dialog service instance corresponding to the dialog from which strings will be extracted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id461614364298983">The following example extracts all strings from the dialog "MyDialog" stored in the "Standard" library and exports them to a POT file:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61585843652225">oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61585843652012">myPO = CreateScriptService("L10N")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61585843653117">myPO.AddTextsFromDialog(oDlg)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id68163786595435">myPO.ExportToPOTFile("en-US.pot")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821625856085583">dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id821625856440596">myPO = CreateScriptService("L10N")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id521625856443065">myPO.AddTextsFromDialog(dlg)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id401637866328706">myPO.ExportToPOTFile("en-US.pot")</paragraph> + </pycode> +</section> + +<section id="ExportToPOTFile"> + <comment> ExportToPOTFile --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id471586102707389"> + <bookmark_value>L10N service;ExportToPOTFile</bookmark_value> + </bookmark> + <h2 id="hd_id231586102707125" localize="false">ExportToPOTFile</h2> + <paragraph role="paragraph" id="par_id281586102707242">Exports a set of untranslated strings as a POT file.</paragraph> + <paragraph role="paragraph" id="par_id711586102939257" xml-lang="en-US">To build a set of strings you can use either a succession of <literal>AddText</literal> method calls, or by a successful invocation of the <literal>L10N</literal> service with the <literal>foldername</literal> argument present. It is also possible to use a combination of both techniques.</paragraph> + <paragraph role="paragraph" id="par_id641625855725141">The method returns <literal>True</literal> if successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id161625856621303"> + <input>svc.ExportToPOTFile(filename: str, header: str = '', encoding:str = 'UTF-8'): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id31586102707537"><emph>filename</emph>: The output file in <literal>FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id851586102707579" xml-lang="en-US"><emph>header</emph>: Comments that will be added on top of the generated POT file.</paragraph> + <paragraph role="paragraph" id="par_id111614364686973">Do not include any leading "#" characters. If you want the header to be broken into multiple lines, insert escape sequences (\n) where relevant. A standard header will be added alongside the text specified in the <literal>header</literal> argument.</paragraph> + <paragraph role="paragraph" id="par_id5158610270728" xml-lang="en-US"><emph>encoding</emph>: The character set to be used (Default = "UTF-8").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id761625856867301">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891586102707992">myPO.ExportToPOTFile("myFile.pot", Header := "First line of the header\nSecond line of the header")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id141625856892715"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131625856893020">myPO.ExportToPOTFile('myFile.pot', header = 'First line of the header\nSecond line of the header')</paragraph> + </pycode> + <note id="par_id581614364494235">The generated file should successfully pass the <literal>msgfmt --check</literal> GNU command.</note> +</section> + +<section id="GetText"> + <comment> GetText ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id131586165768747"> + <bookmark_value>L10N service;GetText</bookmark_value> + </bookmark> + <h2 id="hd_id56158616576884" localize="false">GetText</h2> + <paragraph role="paragraph" id="par_id891586165768715">Gets the translated string corresponding to the given <literal>msgid</literal> argument.</paragraph> + <paragraph role="paragraph" id="par_id291614365296959">A list of arguments may be specified to replace the placeholders (%1, %2, ...) in the string.</paragraph> + <paragraph role="paragraph" id="par_id231586166181909">If no translated string is found, the method returns the untranslated string after replacing the placeholders with the specified arguments.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" id="par_id871586352505927" xml-lang="en-US">This method can be called either by the full name <literal>GetText</literal> or by the shortcut <literal>_</literal> (a single underscore):</paragraph> + <paragraph role="paragraph" localize="false" id="par_id661625857165908"> + <input>svc.GetText(msgid: str, args: any[0..*]): str</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id661625857165119"> + <input>svc._(msgid: str, args: any[0..*]): str</input> + </paragraph> + <note id="par_id421614967136502">In the ScriptForge library, all methods starting with the "_" character are reserved for internal use only. However, the shortcut <literal>_</literal> used for <literal>GetText</literal> is the only exception to this rule, hence it can be safely used in Basic and Python scripts.</note> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id51586165768525" xml-lang="en-US"><emph>msgid</emph>: The untranslated string, which is the text appearing in the program code. It must not be empty. It may contain any number of placeholders (%1 %2 %3 ...) that can be used to dynamically insert text at runtime.</paragraph> + <paragraph role="paragraph" id="par_id11614365537450">Besides using a single <literal>msgid</literal> string, this method also accepts the following formats:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id961614365557277" role="listitem">The <literal>context</literal> string with which the method will retrieve the <literal>msgid</literal> in the PO file, or;</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981614365589866" role="listitem">A combination <literal>context|msgid</literal>, instructing the method to retrieve the <literal>msgid</literal> using specified <literal>context</literal> value. The second part of the argument is used to improve code readability.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id571586165768106" xml-lang="en-US"><emph>args</emph>: Values to be inserted into the placeholders. Any variable type is allowed, however only strings, numbers and dates will be considered.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id701614365961454">Consider the following code is running on a %PRODUCTNAME installation with locale set to "es-ES". Additionally, there is a file "es-ES.po" inside the specified folder that translates the string passed to the <literal>GetText</literal> method:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id171614366110835">myPO = CreateScriptService("L10N", "C:\myPOFiles\")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861586165768104">myPO.GetText("Welcome %1! Hope you enjoy this program", "John")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001586166834936">' "¡Bienvenido John! Espero que disfrutes de este programa"</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821625858120620">myPO = CreateScriptService('L10N', r"C:\myPOFiles")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231625858122952">myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id831625858123194"># "¡Bienvenido John! Espero que disfrutes de este programa"</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_filesystem.xhp#FileSystemService"/> + <embed href="text/sbasic/guide/translation.xhp#translation"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_menu.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_menu.xhp new file mode 100644 index 000000000..162c63083 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_menu.xhp @@ -0,0 +1,324 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Menu" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFWidgets.Menu service</title> + <filename>/text/sbasic/shared/03/sf_menu.xhp</filename> + </topic> +</meta> +<body> + <section id="ScriptForge-sf_pmenu"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788076877"> + <bookmark_value>Menu service</bookmark_value> + </bookmark> + </section> + <section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="MenuService"><link href="text/sbasic/shared/03/sf_menu.xhp" name="Menu service"><literal>SFWidgets</literal>.<literal>Menu</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>Menu</literal> service can be used to create and remove menus from the menubar of a %PRODUCTNAME document window. Each menu entry can be associated with a script or with a UNO command. This service provides the following capabilities:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">Creation of menus with custom entries, checkboxes, radio buttons and separators.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Decoration of menu items with icons and tooltips.</paragraph> + </listitem> + </list> + </section> + <note id="par_id581643133675012">Menus created with this service are available only for a specified document window. They are not saved into the document or as application settings. Closing and opening the document will restore the default menubar settings.</note> + <warning id="par_id291643224925643">When OLE objects such as Math formulas or Calc charts are edited from within a document, %PRODUCTNAME reconfigures the menubar according to the object. When this happens, the menus created with the <literal>Menu</literal> service are removed and are not be restored after editing the OLE object.</warning> + + <h2 id="hd_id281600788076359">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Menu</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id321614902851541">The <literal>Menu</literal> service is instantiated by calling the <link href="text/sbasic/shared/03/sf_document.xhp#CreateMenu" name="CreateMenu_link"><literal>CreateMenu</literal></link> method from the <literal>Document</literal> service. The code snippet below creates a menu named <emph>My Menu</emph> in the current document window with two entries <emph>Item A</emph> and <emph>Item B</emph>.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791643134557838">Sub CreateMenu()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891643134322054"> GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141643134322438"> Dim oDoc as Object, oMenu as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151643134322614"> Set oDoc = CreateScriptService("Document")</paragraph> + <paragraph role="bascode" id="bas_id261643134374056"> Set oMenu = oDoc.CreateMenu("My Menu")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261643134581928"> With oMenu</paragraph> + <paragraph role="bascode" id="bas_id431643134582213"> .AddItem("Item A", Command := "About")</paragraph> + <paragraph role="bascode" id="bas_id571643134582396"> .AddItem("Item B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531643134582588"> .Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981643134582741"> End With</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791643134722777">End Sub</paragraph> + </bascode> + <note id="par_id371643135157996">After creating the menu, it is recommended to call the <literal>Dispose</literal> method to free the resources used by the <literal>Menu</literal> service instance.</note> + <paragraph role="paragraph" id="par_id341636718182262">In the example above, <emph>Item A</emph> is associated with the UNO command <literal>.uno:About</literal> whereas <emph>Item B</emph> is associated with the script <literal>ItemB_Listener</literal> defined in <literal>Module1</literal> of the <literal>Standard</literal> library of the <literal>My Macros</literal> container.</paragraph> + <paragraph role="paragraph" id="par_id851635274721129">The following example defines <literal>ItemB_Listener</literal> that will be called when <emph>Item B</emph> is clicked. This listener simply splits the argument string passed to the <literal>Sub</literal> and shows them in a message box.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id311643135422309">Sub ItemB_Listener(args As String)</paragraph> + <paragraph role="bascode" id="bas_id716431354225603"> ' Process the argument string passed to the listener</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211643135422708"> Dim sArgs as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461643135422860"> sArgs = Split(args, ",")</paragraph> + <paragraph role="bascode" id="bas_id901643135423012"> MsgBox "Menu name: " & sArgs(0) & Chr(13) & _</paragraph> + <paragraph role="bascode" id="bas_id301643136028263"> "Menu item: " & sArgs(1) & Chr(13) & _</paragraph> + <paragraph role="bascode" id="bas_id181643136028557"> "Item ID: " & sArgs(2) & Chr(13) & _</paragraph> + <paragraph role="bascode" id="bas_id561643136028710"> "Item status: " & sArgs(3)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241643136028871">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id531636493797707">As shown in the example above, menu entries associated with a script receive a comma-separated string argument with the following values:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id921643136489994" role="listitem">The toplevel name of the menu.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id611643136491059" role="listitem">The string ID of the selected menu entry.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id961643136491491" role="listitem">The numeric ID of the selected menu entry.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id381643136494580" role="listitem">The current state of the menu item. This is useful for checkboxes and radio buttons. If the item is checked, the value "1" is returned, otherwise "0" is returned.</paragraph> + </listitem> + </list> + + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id131635275172617">The examples above can be written in Python as follows:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441636718456158"></paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441636718456844">def create_menu(args=None):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710433"> oDoc = CreateScriptService("Document")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710122"> oMenu = oDoc.CreateMenu("My Menu")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311626695710851"> oMenu.AddItem("Item A", command="About")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211636717609237"> oMenu.AddItem("Item B", script="vnd.sun.star.script:my_macros.py$item_b_listener?language=Python&location=user")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id616367176100230"> oMenu.Dispose()</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831635275439182">def item_b_listener(args):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481643137165239"> bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381635275439396"> s_args = args.split(",")</paragraph> + <paragraph role="pycode" id="pyc_id981636717957632"> msg = f"Menu name: {s_args[0]}\n"</paragraph> + <paragraph role="pycode" id="pyc_id851636718008427"> msg += f"Menu item: {s_args[1]}\n"</paragraph> + <paragraph role="pycode" id="pyc_id331636727047102"> msg += f"Item ID: {s_args[2]}\n"</paragraph> + <paragraph role="pycode" id="pyc_id71643137333404"> msg += f"Item status: {s_args[3]}"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111643137333564"> bas.MsgBox(msg)</paragraph> + </pycode> + + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id111614901520029"> + <bookmark_value>PopupService service;ShortcutCharacter</bookmark_value> + <bookmark_value>PopupService service;SubmenuCharacter</bookmark_value> + </bookmark> + <h2 id="hd_id711600788076834">Properties</h2> + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">ShortcutCharacter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">Character used to define the access key of a menu item. The default character is "~".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">SubmenuCharacter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">Character or string that defines how menu items are nested. The default character is ">".</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id181636719707892">Menu and Submenus</h2> + <paragraph role="paragraph" id="par_id741636719725402">To create a menu with submenus, use the character defined in the <literal>SubmenuCharacter</literal> property while creating the menu entry to define where it will be placed. For instance, consider the following menu/submenu hierarchy.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id991636719842353">' Item A</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231636719842719">' Item B > Item B.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421636719842904">' Item B.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916367201523640">' ------ (line separator)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541636719843240">' Item C > Item C.1 > Item C.1.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701636719843447">' Item C.1.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601636719843672">' Item C > Item C.2 > Item C.2.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843864">' Item C.2.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843567">' ------ (line separator)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843154">' Item C.2.3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843965">' Item C.2.4</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id211636720111489">The code below uses the default submenu character ">" to create the menu/submenu hierarchy defined above:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="par_id961636720555061">oMenu.AddItem("Item A")</paragraph> + <paragraph role="bascode" localize="false" id="par_id371636720556397">oMenu.AddItem("Item B>Item B.1")</paragraph> + <paragraph role="bascode" localize="false" id="par_id941636720556623">oMenu.AddItem("Item B>Item B.2")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261636720973178">oMenu.AddItem("---")</paragraph> + <paragraph role="bascode" localize="false" id="par_id431636720556822">oMenu.AddItem("Item C>Item C.1>Item C.1.1")</paragraph> + <paragraph role="bascode" localize="false" id="par_id651636720557021">oMenu.AddItem("Item C>Item C.1>Item C.1.2")</paragraph> + <paragraph role="bascode" localize="false" id="par_id861636720557222">oMenu.AddItem("Item C>Item C.2>Item C.2.1")</paragraph> + <paragraph role="bascode" localize="false" id="par_id21636720557437">oMenu.AddItem("Item C>Item C.2>Item C.2.2")</paragraph> + <paragraph role="bascode" localize="false" id="par_id21636720557103">oMenu.AddItem("Item C>Item C.2>---")</paragraph> + <paragraph role="bascode" localize="false" id="par_id21636720557256">oMenu.AddItem("Item C>Item C.2>Item C.2.3")</paragraph> + <paragraph role="bascode" localize="false" id="par_id21636720557941">oMenu.AddItem("Item C>Item C.2>Item C.2.4")</paragraph> + </bascode> + <note id="par_id121636721243578">The string "---" is used to define line separators in menus or submenus.</note> + <embed href="text/sbasic/shared/03/sf_popupmenu.xhp#using_icons"/> + + <h2 id="hd_id501582887473754" xml-lang="en-US">Methods</h2> + <table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Menu Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_menu.xhp#AddCheckBox" name="AddCheckBox method">AddCheckBox</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_menu.xhp#AddItem" name="AddItem method">AddItem</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613625804" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_menu.xhp#AddRadioButton" name="AddRadioButton method">AddRadioButton</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + + <section id="AddCheckBox"> + <comment> AddCheckBox ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>Menu service;AddCheckBox</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">AddCheckBox</h2> + <paragraph role="paragraph" id="par_id93158919969864">Inserts a check box in the menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014732"> + <input>svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203996"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631203116"><emph>name:</emph> String value used to identify the menu item. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id821591631203133"><emph>status:</emph> Defines whether the item is selected when the menu is created (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id11636721653313"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653208"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <paragraph role="paragraph" id="par_id11636721653328"><emph>command:</emph> The name of a UNO command without the <literal>.uno:</literal> prefix. If the command name does not exist, nothing happens.</paragraph> + <paragraph role="paragraph" id="par_id11636721653107"><emph>script:</emph> The URI for a Basic or Python script that will be executed when the item is clicked.</paragraph> + <section id="menu_note"> + <note id="par_id31643198954204">The arguments <literal>command</literal> and <literal>script</literal> are mutually exclusive, hence only one of them can be set for each menu item.</note> + <tip id="par_id31643148484084">Read <link href="https://wiki.documentfoundation.org/Documentation/DevGuide/Scripting_Framework#Scripting_Framework_URI_Specification" name="URI_Notation">Scripting Framework URI Specification</link> to learn more about the URI syntax used in the <literal>script</literal> argument.</tip> + </section> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id191643306748853">' Menu entry associated with the .uno:Paste command</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41158919969204">oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")</paragraph> + <paragraph role="bascode" id="bas_id271643147793320">' Runs the Basic script Standard.Module1.MyListener stored in the document</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41158919969114">oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")</paragraph> + <paragraph role="bascode" id="bas_id801643306742620">' Runs the Python script MyListener located in file myScripts.py in the user scripts folder</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41158919969324">oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175122">oMenu.AddCheckBox("Item A", status=True, tooltip="Paste values", command="Paste")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321621534175344">oMenu.AddCheckBox("Item B", status=False, script="vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id591643307035249">oMenu.AddCheckBox("Item C", Status=True, Script="vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")</paragraph> + </pycode> + </section> + + <section id="AddItem"> + <comment> AddItem ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919960353"> + <bookmark_value>Menu service;AddItem</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698158" localize="false">AddItem</h2> + <paragraph role="paragraph" id="par_id93158919963364">Inserts a label entry in the menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534012185"> + <input>svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203021"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631203026"><emph>name:</emph> String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id11636721652886"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653118"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <paragraph role="paragraph" id="par_id11636721653314"><emph>command:</emph> The name of a UNO command without the <literal>.uno:</literal> prefix. If the command name does not exist, nothing happens.</paragraph> + <paragraph role="paragraph" id="par_id11636721652057"><emph>script:</emph> The URI for a Basic or Python script that will be executed when the item is clicked.</paragraph> + <embed href="text/sbasic/shared/03/sf_menu.xhp#menu_note"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id41158919969106">oMenu.AddItem("Item A", Tooltip := "A descriptive message")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id321621534170554">oMenu.AddItem("Item A", tooltip = "A descriptive message")</paragraph> + </pycode> + </section> + + <section id="AddRadioButton"> + <comment> AddRadioButton --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969447"> + <bookmark_value>Menu service;AddRadioButton</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693022" localize="false">AddRadioButton</h2> + <paragraph role="paragraph" id="par_id93158919969399">Inserts a radio button entry in the menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534013775"> + <input>svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203501"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631228716"><emph>name:</emph> String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id821591631203643"><emph>status:</emph> Defines whether the item is selected when the menu is created (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id11636721653228"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653114"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <paragraph role="paragraph" id="par_id11636721653447"><emph>command:</emph> The name of a UNO command without the <literal>.uno:</literal> prefix. If the command name does not exist, nothing happens.</paragraph> + <paragraph role="paragraph" id="par_id11636721652598"><emph>script:</emph> The URI for a Basic or Python script that will be executed when the item is clicked.</paragraph> + <embed href="text/sbasic/shared/03/sf_menu.xhp#menu_note"/> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969658">oMenu.AddRadioButton("Item A", Name := "A", Status := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175471">oMenu.AddRadioButton("Item A", name="A", status=True)</paragraph> + </pycode> + </section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_popupmenu.xhp#PopupMenuService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_methods.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_methods.xhp new file mode 100644 index 000000000..219669b9f --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_methods.xhp @@ -0,0 +1,211 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> + <!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + --> + <meta> + <topic id="scriptforgemethods" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge Method Signatures</title> + <filename>/text/sbasic/shared/03/sf_methods.xhp</filename> + </topic> + </meta> + <body> + <h1 id="hd_id31529004750471" xml-lang="en-US"><variable id="SF_Signatures"><link href="text/sbasic/shared/03/sf_methods.xhp" name="ScriptForge Method Signatures"><literal>ScriptForge</literal> Method Signatures</link></variable></h1> + <bookmark xml-lang="en-US" branch="index" id="bm_id491529070339774"> + <bookmark_value>ScriptForge; Method signatures</bookmark_value> + </bookmark> + <paragraph role="paragraph" id="par_id681619700336879">ScriptForge libraries aggregate macro scripting resources for %PRODUCTNAME to be invoked from Basic macros or Python scripts. Its modules and classes are invoked from user scripts as "Services" that expose properties, methods and events.</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id681623415196030" role="listitem">Whenever service methods are proposed solely for %PRODUCTNAME Basic, their syntax presentation matches that of Basic subroutines, functions or properties. </paragraph> + </listitem> + <listitem> + <paragraph id="par_id401623415235965" role="listitem">Whenever service methods are proposed for Python and Basic, or solely for Python, their syntax and arguments use a specific textual layout.</paragraph> + </listitem> + </list> + + <h2 id="hd_id1001623415980365">Basic only service method</h2> + <paragraph role="paragraph" id="par_id791623418737799">Typographical characters such as brackets, ellipsis or curly braces denote optional, repetitive or compulsory arguments:</paragraph> + <embed href="text/sbasic/shared/conventions.xhp#Typography"/> + <h3 id="hd_id511616863794613" localize="false"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id241623422100136">FSO.HashFile(FileName As String, _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101623423263928"> Algorithm As String = {MD5|SHA1|SHA224|SHA256|SHA384|SHA512}) As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851623422099952">SF_Array.ImportFromCSVFile(FileName As String, _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741623423196368"> [Delimiter = ","], [DateFormat As String]) As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691623422100368">SF_String.SplitNotQuoted(InputStr As String, _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881623423667888"> [Delimiter As String], [Occurrences As Long], [QuoteChar As String]) As Variant</paragraph> + </bascode> + + <h2 id="hd_id711623416000470">Python or Basic service methods</h2> + <paragraph role="paragraph" id="par_id221623415475781">The following typographical rules are mixing the UML notation, the API documentation layout and the UNO object inspector user interface:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id661623417427142" role="listitem">Optional parameters are indicated with either opt, '=' accompanying a default value, or '[ ]' brackets.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id351623417430814" role="listitem">arguments are lowercased, in order to comply with Python PEP 8 while Basic is case-agnostic.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id781623417432494" role="listitem">Collections arguments or API sequences are denoted using UML multiplicity. That applies also to return values.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id741623417433319" role="listitem">Basic data types and Python annotations are syntactically transposed as:</paragraph> + </listitem> + </list> + <table id="tab_Datatypes"> + <tablerow> + <tablecell> + <paragraph id="par_id131613838858931" localize="false" role="tablehead">%PRODUCTNAME<br/>Basic</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441613838858931" role="tablehead">Syntax</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441613839128931" localize="false" role="tablehead">Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id851613847558931" role="tablecontent">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id581613836728425">bool</paragraph> + </tablecell> + <tablecell> + <paragraph role="tablecontent" localize="false" id="par_id731613840022120">bool</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id241623419591966" localize="false" role="tablecontent">Date</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541623420256687" localize="false" role="tablecontent">datetime</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421623420257224" localize="false" role="tablecontent">datetime</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id651623419593960" localize="false" role="tablecontent">Double</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id321623420281678" localize="false" role="tablecontent">float</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471623420282320" localize="false" role="tablecontent">float</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id421623419594151" localize="false" role="tablecontent">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971623420314751" localize="false" role="tablecontent">int</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561623420315278" localize="false" role="tablecontent">int</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511623419594366" localize="false" role="tablecontent">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451623420342159" localize="false" role="tablecontent">int</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591623420343208" localize="false" role="tablecontent">int</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id541623419594576" localize="false" role="tablecontent">Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601623420375543" localize="false" role="tablecontent">obj</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601628420375147" localize="false" role="tablecontent"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id931623419594783" localize="false" role="tablecontent">Single</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821623420532337" localize="false" role="tablecontent">float</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351623420532936" localize="false" role="tablecontent">float</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id391623419595010" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211623420546503" localize="false" role="tablecontent">str</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id681623420559167" localize="false" role="tablecontent">str</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id61623419595200" localize="false" role="tablecontent">Variant</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81623420571390" localize="false" role="tablecontent">any</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601628420044847" localize="false" role="tablecontent"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id931623419595424" role="tablecontent">UNO Object</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821623420607671" localize="false" role="tablecontent">uno</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601628420332587" localize="false" role="tablecontent"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951623419595631" role="tablecontent">User Defined<br/>Type (UDT)</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491623420626262" localize="false" role="tablecontent">obj</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601628420215874" localize="false" role="tablecontent"></paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id451623419793734" role="tablecontent"><literal>ScriptForge</literal><br/>service</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761623420648335" localize="false" role="tablecontent">svc</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601628420373974" localize="false" role="tablecontent"></paragraph> + </tablecell> + </tablerow> + </table> + <h3 id="hd_id622616863794724" localize="false"><embedvar href="text/sbasic/shared/00000003.xhp#functexample"/></h3> + <paragraph role="paragraph" localize="false" id="par_id261623421276448"><input>svc.Forms( opt form: any ): svc[0..*]</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id921623420866535"><input>svc.MsgBox( prompt: str, buttons = svc.MB_OK , opt title: str ): opt str</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id641623420867288"><input>svc.InputBox( prompt: str, default = "", [ title: str ], [ xpostwips: int, ypostwips: int ] ): str</input></paragraph> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_platform.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_platform.xhp new file mode 100644 index 000000000..c9283925b --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_platform.xhp @@ -0,0 +1,412 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Platform" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Platform service</title> + <filename>/text/sbasic/shared/03/sf_platform.xhp</filename> + </topic> + </meta> +<body> +<section id="ScriptForge-sf_platform"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788076381"> + <bookmark_value>Platform service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="PlatformService"><link href="text/sbasic/shared/03/sf_platform.xhp" name="Platform service"><literal>ScriptForge</literal>.<literal>Platform</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>Platform</literal> service provides a collection of properties about the current execution environment and context, such as:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">The hardware platform (architecture, CPU count, machine type, etc)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Operating system information (OS type, release, version, etc)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id67160078807676" role="listitem">The %PRODUCTNAME version</paragraph> + </listitem> + <listitem> + <paragraph id="par_id671600788076855" role="listitem">The current user name</paragraph> + </listitem> + </list> +</section> + <note id="par_id951614903258253">All properties of the <literal>Platform</literal> service are read-only.</note> + <h2 id="hd_id281600788076359">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Platform</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id321614902851541">The examples below in Basic and Python instantiate the <literal>Platform</literal> service and access the <literal>Architecture</literal> property.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851600788076202">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001600788076254">Dim platform As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721600788076288">platform = CreateScriptService("Platform")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791600788431935">MsgBox platform.Architecture</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710433">svc = CreateScriptService("Platform")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311626695710851">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391626695711082">bas.MsgBox(svc.Architecture)</paragraph> + </pycode> + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id111614901524769"> + <bookmark_value>Platform service;Architecture</bookmark_value> + <bookmark_value>Platform service;ComputerName</bookmark_value> + <bookmark_value>Platform service;CPUCount</bookmark_value> + <bookmark_value>Platform service;CurrentUser</bookmark_value> + <bookmark_value>Platform service;Extensions</bookmark_value> + <bookmark_value>Platform service;Fonts</bookmark_value> + <bookmark_value>Platform service;FormatLocale</bookmark_value> + <bookmark_value>Platform service;Locale</bookmark_value> + <bookmark_value>Platform service;Machine</bookmark_value> + <bookmark_value>Platform service;OfficeLocale</bookmark_value> + <bookmark_value>Platform service;OfficeVersion</bookmark_value> + <bookmark_value>Platform service;OSName</bookmark_value> + <bookmark_value>Platform service;OSPlatform</bookmark_value> + <bookmark_value>Platform service;OSRelease</bookmark_value> + <bookmark_value>Platform service;OSVersion</bookmark_value> + <bookmark_value>Platform service;Printers</bookmark_value> + <bookmark_value>Platform service;Processor</bookmark_value> + <bookmark_value>Platform service;PythonVersion</bookmark_value> + <bookmark_value>Platform service;SystemLocale</bookmark_value> + </bookmark> + <h2 id="hd_id711600788076834">Properties</h2> + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">Architecture</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">The hardware bit architecture. Example: '<literal>32bit</literal>' or '<literal>64bit</literal>'</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">ComputerName</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">The computer's network name.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721600788076638" role="tablecontent" localize="false">CPUCount</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711600788076534" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911600788076842" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600788076645" role="tablecontent">The number of central processing units.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961600788076890" role="tablecontent" localize="false">CurrentUser</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891600788076190" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076562" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91600788076674" role="tablecontent">The name of the currently logged user.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719246" localize="false" role="tablecontent">Extensions</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747014" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748566" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749125" role="tablecontent">Returns a zero-based array of strings containing the internal IDs of all installed extensions.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021716585" localize="false" role="tablecontent">FilterNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747209" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748322" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749118" role="tablecontent">Returns a zero-based unsorted array of strings containing the available document import and export filter names.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719135" localize="false" role="tablecontent">Fonts</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747903" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748455" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749007" role="tablecontent">Returns a zero-based array of strings containing the names of all available fonts.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021710186" localize="false" role="tablecontent">FormatLocale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021748013" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021749655" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749297" role="tablecontent">Returns the locale used for numbers and dates as a string in the format "la-CO" (language-COUNTRY).</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719022" localize="false" role="tablecontent">Locale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021743188" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021743058" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749018" role="tablecontent">Returns the locale of the operating system as a string in the format "la-CO" (language-COUNTRY). This is equivalent to the <literal>SystemLocale</literal> property.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951600788076443" role="tablecontent" localize="false">Machine</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391600788076253" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381600788076799" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076541" role="tablecontent">The machine type. Examples are: '<literal>i386</literal>' or '<literal>x86_64</literal>'.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021710156" localize="false" role="tablecontent">OfficeLocale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021706513" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021746335" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021741117" role="tablecontent">Returns the locale of the user interface as a string in the format "la-CO" (language-COUNTRY).</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id41600788076936" role="tablecontent" localize="false">OfficeVersion</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211600788076138" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076518" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521600788076371" role="tablecontent">The actual %PRODUCTNAME version expressed as<br />' <literal>%PRODUCTNAME w.x.y.z (The Document Foundation)</literal>'.</paragraph> + <paragraph role="paragraph" id="par_id621614902220807">Example: '<literal>LibreOffice 7.4.1.2 (The Document Foundation, Debian and Ubuntu)</literal>'</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161600788076362" role="tablecontent" localize="false">OSName</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076758" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id871600788076196" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781600788076694" role="tablecontent">The operating system type. Example: '<literal>Darwin</literal>, <literal>Linux</literal>' or '<literal>Windows</literal>'.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id471600788076885" role="tablecontent" localize="false">OSPlatform</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261600788076841" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661600788076636" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11600788076757" role="tablecontent">A single string identifying the underlying platform with as much useful and human-readable information as possible.</paragraph> + <paragraph role="paragraph" id="par_id501614902381381">Example: '<literal>Linux-5.8.0-44-generic-x86_64-with-glibc2.32</literal>'</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id221600789141781" role="tablecontent" localize="false">OSRelease</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531600789141795" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561600789141282" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301600789141619" role="tablecontent">The operating system's release. Example: '<literal>5.8.0-44-generic</literal>'</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id821600789286339" role="tablecontent" localize="false">OSVersion</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600789286532" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181600789286889" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701600789286280" role="tablecontent">The operating system's build or version.</paragraph> + <paragraph role="paragraph" id="par_id351614902520555">Example: '<literal>#50-Ubuntu SMP Tue Feb 9 06:29:41 UTC 2021</literal>'</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789752717" role="tablecontent" localize="false">Printers</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941608709527698" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100100678952791" role="tablecontent" localize="false">String<br/>array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661300789527859" role="tablecontent">The list of available printers as a zero-based array.</paragraph> + <paragraph role="paragraph" id="par_id111614952098396">The default printer is put in the first position of the list (index = 0).</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789527717" role="tablecontent" localize="false">Processor</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941600789527698" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100160078952791" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631600789527859" role="tablecontent">The real processor name. Example: '<literal>amdk6</literal>'.</paragraph> + <paragraph role="paragraph" id="par_id111614902598396">This property may return the same value as the <literal>Machine</literal> property.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31600789752228" role="tablecontent" localize="false">PythonVersion</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id941608709527036" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id100100678952208" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661300789527994" role="tablecontent">Returns the version of the Python interpreter being used as a string in the format "Python major.minor.patchlevel" (ex: "Python 3.9.7").</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id83163302112358" localize="false" role="tablecontent">SystemLocale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021708547" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021746229" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021741336" role="tablecontent">Returns the locale of the operating system as a string in the format "la-CO" (language-COUNTRY). This is equivalent to the <literal>Locale</literal> property.</paragraph> + </tablecell> + </tablerow> + </table> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id311633022159446">The following examples in Basic and Python illustrate how to use the <literal>Fonts</literal> property to write the names of all available fonts to the current Calc sheet starting at cell "A1":</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671633022413022">Dim oDoc as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721633022413266">Dim allFonts as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691633022413526">Dim svcPlatform as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41633022413831">Set oDoc = CreateScriptService("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541633022414069">Set svcPlatform = CreateScriptService("Platform")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641633022414366">allFonts = svcPlatform.Fonts</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651633022414637">oDoc.setArray("~.A1", allFonts)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id701633022704347">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841633022704586">svc_platform = CreateScriptService("Platform")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281633022704771">doc = CreateScriptService("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211633022704988">all_fonts = svc_platform.Fonts</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941633022705212">doc.setArray("~.A1", all_fonts)</paragraph> + </pycode> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/python/python_platform.xhp#pythonplatform"/> + <paragraph role="paragraph" id="par_id301613065794148"><link href="text/scalc/01/04060104.xhp#bm_id3691824" name="Calc_Info">Platform information with INFO("system") Calc formula</link></paragraph> + <embed href="text/sbasic/shared/03132100.xhp#getguitype2"/> + <embed href="text/sbasic/shared/03/lib_tools.xhp#tools_lib"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_popupmenu.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_popupmenu.xhp new file mode 100644 index 000000000..b36ebbda3 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_popupmenu.xhp @@ -0,0 +1,348 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_PopupMenu" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFWidgets.PopupMenu service</title> + <filename>/text/sbasic/shared/03/sf_popupmenu.xhp</filename> + </topic> +</meta> +<body> + <section id="ScriptForge-sf_popupmenu"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788076877"> + <bookmark_value>PopupMenu service</bookmark_value> + </bookmark> + </section> + <section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="PopupMenuService"><link href="text/sbasic/shared/03/sf_popupmenu.xhp" name="PopupMenu service"><literal>SFWidgets</literal>.<literal>PopupMenu</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>PopupMenu</literal> service can be used to create popup menus that can be associated with events or executed by scripts. This service provides the following capabilities:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">Creation of popup menus with custom entries, checkboxes and radio buttons.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Decoration of menu items with icons and tooltips.</paragraph> + </listitem> + </list> + </section> + + <h2 id="hd_id281600788076359">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>PopupMenu</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id321614902851541">The <literal>PopupMenu</literal> service can be instantiated in multiple ways. The example below creates a popup menu without associating it with a mouse or application event.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id701636718117715">Sub ShowPopup</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851600788076202"> GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id100160078076254"> Dim myPopup As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721600788076288"> Set myPopup = CreateScriptService("SFWidgets.PopupMenu", , 300, 300)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791600788431935"> myPopup.AddItem("Item ~A")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791600788431755"> myPopup.AddItem("Item ~B")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791600788431206"> vResponse = myPopup.Execute()</paragraph> + <paragraph role="bascode" id="bas_id841636717357955"> MsgBox("Selected item ID: " & vResponse)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801636717387904"> myPopup.Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721636718154385">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id341636718182262">Running the <literal>Sub</literal> defined above will create a popup menu with two entries in the position X=300 and Y=300 on the screen.</paragraph> + <tip id="par_id711636493696169">The prefix <literal>SFWidgets</literal> can be suppressed while invoking the <literal>PopupMenu</literal> service.</tip> + <paragraph role="paragraph" id="par_id851635274721129">The following example defines a <literal>Sub</literal> that can be associated with a mouse event:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221635274765110">Sub MyPopupClick(Optional poMouseEvent as Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461635274776072"> Dim myPopup As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621635274776400"> Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)</paragraph> + <paragraph role="bascode" id="bas_id721636488722999"> ' Populate popupmenu with items</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201636488724356"> Dim vResponse As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371636488724573"> vResponse = myPopup.Execute(False)</paragraph> + <paragraph role="bascode" id="bas_id311636488724795"> ' Do something based on vResponse</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501636493549364"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721636718367863"> myPopup.Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941636493510454">End Sub</paragraph> + </bascode> + <tip id="par_id991636718278125">Use the <literal>Dispose</literal> method to free resources after executing the popup menu.</tip> + <paragraph role="paragraph" id="par_id531636493797707">It is also possible to associate a popup menu with events triggered by %PRODUCTNAME applications, form and dialog controls. Events such as "Mouse button pressed" and "Mouse button released" are commonly associated with popup menus.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id221635274762410">Sub MyPopupClick(Optional poEvent as Object)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461635274776234"> Dim myPopup As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621635274776299"> Set myPopup = CreateScriptService("PopupMenu", poEvent)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id501636493549964"> ' ...</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941636493510712">End Sub</paragraph> + </bascode> + + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id131635275172617">The examples above can be written in Python as follows:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441636718456158"></paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441636718456844">def show_popup(args=None):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710433"> my_popup = CreateScriptService("SFWidgets.PopupMenu", None, 300, 300)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710122"> bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311626695710851"> my_popup.AddItem("Item ~A")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211636717609237"> my_popup.AddItem("Item ~B")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id616367176100230"> response = my_popup.Execute()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901636718500313"> bas.MsgBox(f"Selected item ID: {response}")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id416367185012216"> my_popup.Dispose()</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831635275439182">def my_popup_click(poEvent=None):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381635275439396"> my_popup = CreateScriptService("SFWidgets.PopupMenu", poEvent)</paragraph> + <paragraph role="pycode" id="pyc_id916367179574588"> # Populate popupmenu with items</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981636717957632"> response = my_popup.Execute()</paragraph> + <paragraph role="pycode" id="pyc_id851636718008427"> # Do something based on response</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id331636727047102"> my_popup.Dispose()</paragraph> + </pycode> + + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id111614901520029"> + <bookmark_value>PopupService service;ShortcutCharacter</bookmark_value> + <bookmark_value>PopupService service;SubmenuCharacter</bookmark_value> + </bookmark> + <h2 id="hd_id711600788076834">Properties</h2> + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">ShortcutCharacter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">Character used to define the access key of a menu item. The default character is "~".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">SubmenuCharacter</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">Character or string that defines how menu items are nested. The default character is ">".</paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id181636719707892">Menu and Submenus</h2> + <paragraph role="paragraph" id="par_id741636719725402">To create a popup menu with submenus, use the character defined in the <literal>SubmenuCharacter</literal> property while creating the menu entry to define where it will be placed. For instance, consider the following menu/submenu hierarchy.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id991636719842353">' Item A</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231636719842719">' Item B > Item B.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421636719842904">' Item B.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916367201523640">' ------ (line separator)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541636719843240">' Item C > Item C.1 > Item C.1.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701636719843447">' Item C.1.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601636719843672">' Item C > Item C.2 > Item C.2.1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843864">' Item C.2.2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843567">' ------ (line separator)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843154">' Item C.2.3</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921636719843965">' Item C.2.4</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id211636720111489">The code below uses the default submenu character ">" to create the menu/submenu hierarchy defined above:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id961636720555061">myPopup.AddItem("Item A")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371636720556397">myPopup.AddItem("Item B>Item B.1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941636720556623">myPopup.AddItem("Item B>Item B.2")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261636720973178">myPopup.AddItem("---")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431636720556822">myPopup.AddItem("Item C>Item C.1>Item C.1.1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651636720557021">myPopup.AddItem("Item C>Item C.1>Item C.1.2")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861636720557222">myPopup.AddItem("Item C>Item C.2>Item C.2.1")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21636720557437">myPopup.AddItem("Item C>Item C.2>Item C.2.2")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21636720557103">myPopup.AddItem("Item C>Item C.2>---")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21636720557256">myPopup.AddItem("Item C>Item C.2>Item C.2.3")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21636720557941">myPopup.AddItem("Item C>Item C.2>Item C.2.4")</paragraph> + </bascode> + <note id="par_id121636721243578">The string "---" is used to define line separators in menus or submenus..</note> + <section id="using_icons"> + <h2 id="hd_id211636723438558">Using icons</h2> + <paragraph role="paragraph" id="par_id981636723485402">Items in the menu can have icons, which are specified as arguments in the <literal>AddCheckBox</literal>, <literal>AddItem</literal> and <literal>AddRadioButton</literal> methods.</paragraph> + <paragraph role="paragraph" id="par_id881636724112434">All icons available in %PRODUCTNAME can be used by specifying their path relative to the folder where icon files are located in the installation folder. Icons are located in the following folder:</paragraph> + <paragraph role="paragraph" localize="false" id="par_id991636724479899"><input>INSTALLDIR/share/config</input></paragraph> + <tip id="par_id941636724808906">Use the <literal>InstallFolder</literal> property of the <literal>FileSystem</literal> service to determine where %PRODUCTNAME is installed in your system.</tip> + <paragraph role="paragraph" id="par_id201636724575911">This folder contains a series of ZIP files containing the image files of each available icon set. The images inside these ZIP files are organized into folders. To use an icon, specify the icon file with the path to its location inside the ZIP file.</paragraph> + <paragraph role="paragraph" id="par_id641636724972071">The example below uses the icon "sc_newdoc.svg" that is located inside the "cmd" folder. The forward slash "/" character is used as the path separator regardless of the operating system.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id121636725026678">myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361643307394680">myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")</paragraph> + </pycode> + <note id="par_id691636725233961">All icon sets have the same internal structure. The actual icon displayed depends on the icon set currently in use.</note> + </section> + + <h2 id="hd_id501582887473754" xml-lang="en-US">Methods</h2> + <table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the PopupMenu Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_popupmenu.xhp#AddCheckBox" name="AddCheckBox method">AddCheckBox</link><br/> + <link href="text/sbasic/shared/03/sf_popupmenu.xhp#AddItem" name="AddItem method">AddItem</link> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_popupmenu.xhp#AddRadioButton" name="AddRadioButton method">AddRadioButton</link><br/><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613625804" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_popupmenu.xhp#Execute" name="Execute method">Execute</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + + <section id="AddCheckBox"> + <comment> AddCheckBox ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969883"> + <bookmark_value>PopupMenu service;AddCheckBox</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698251" localize="false">AddCheckBox</h2> + <paragraph role="paragraph" id="par_id93158919969864">Inserts a check box in the popup menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014732"> + <input>svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203996"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631203116"><emph>name:</emph> String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id821591631203133"><emph>status:</emph> Defines whether the item is selected when the menu is created (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id11636721653313"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653208"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969204">myPopup.AddCheckBox("Option A", Status := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175122">my_popup.AddCheckBox("Option A", status=True)</paragraph> + </pycode> + </section> + + <section id="AddItem"> + <comment> AddItem ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919960353"> + <bookmark_value>PopupMenu service;AddItem</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698158" localize="false">AddItem</h2> + <paragraph role="paragraph" id="par_id93158919963364">Inserts a menu entry in the popup menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534012185"> + <input>svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203021"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631203026"><emph>name:</emph> String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id11636721652886"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653118"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id41158919969106">myPopup.AddItem("Item A", Tooltip := "A descriptive message")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id321621534170554">my_popup.AddItem("Item A", tooltip = "A descriptive message")</paragraph> + </pycode> + </section> + + <section id="AddRadioButton"> + <comment> AddRadioButton --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969447"> + <bookmark_value>PopupMenu service;AddRadioButton</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693022" localize="false">AddRadioButton</h2> + <paragraph role="paragraph" id="par_id93158919969399">Inserts a radio button entry in the popup menu. Returns an integer value that identifies the inserted item.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534013775"> + <input>svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631203501"><emph>menuitem:</emph> Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.</paragraph> + <paragraph role="paragraph" id="par_id821591631228716"><emph>name:</emph> String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.</paragraph> + <paragraph role="paragraph" id="par_id821591631203643"><emph>status:</emph> Defines whether the item is selected when the menu is created (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id11636721653228"><emph>icon:</emph> Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.</paragraph> + <paragraph role="paragraph" id="par_id11636721653114"><emph>tooltip:</emph> Text to be displayed as tooltip.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919969658">myPopup.AddRadioButton("Option A", Name := "A", Status := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534175471">my_popup.AddRadioButton("Option A", name="A", status=True)</paragraph> + </pycode> + </section> + + <section id="Execute"> + <comment> Execute --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919962887"> + <bookmark_value>PopupMenu service;Execute</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693201" localize="false">Execute</h2> + <paragraph role="paragraph" id="par_id93158919963279">Displays the popup menu and waits for a user action. Returns the item clicked by the user.</paragraph> + <paragraph role="paragraph" id="par_id101636726249788">If the user clicks outside the popup menu or presses the <keycode>Esc</keycode> key, then no item is selected. In such cases, the returned value depends on the <literal>returnid</literal> parameter. If <literal>returnid = True</literal> and no item is selected, then the value 0 (zero) is returned. Otherwise an empty string "" is returned.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821621534014414"> + <input>svc.Execute(opt returnid: bool = True): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id821591631202088"><emph>returnid:</emph> If <literal>True</literal> the selected item ID is returned. If <literal>False</literal> the method returns the item's name (Default = <literal>True</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id51636726671698">In the examples below, a popup menu is created and the item's name is returned because the <literal>returnid</literal> argument is set to <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41158919963328">myPopup.AddItem("Item A", Name := "A")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91636726598754">myPopup.AddItem("Item B", Name := "B")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871636726599326">Dim vResponse as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351636726599500">vResponse = myPopup.Execute(False)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id321621534173001">my_popup.AddItem("Item A", name="A")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id271636726772842">my_popup.AddItem("Item B", name="B")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621636726773015">response = my_popup.Execute(False)</paragraph> + </pycode> + </section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_dialog.xhp#dlg_h1"/> + <embed href="text/sbasic/shared/03/sf_dialogcontrol.xhp#ctrls_h1"/> + <embed href="text/sbasic/shared/03/sf_menu.xhp#MenuService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_region.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_region.xhp new file mode 100644 index 000000000..2fee97f17 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_region.xhp @@ -0,0 +1,605 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_Region" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Region service</title> + <filename>/text/sbasic/shared/03/sf_region.xhp</filename> + </topic> + </meta> +<body> +<section id="ScriptForge-sf_region"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788079651"> + <bookmark_value>Region service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="RegionService"><link href="text/sbasic/shared/03/sf_region.xhp" name="Region service"><literal>ScriptForge</literal>.<literal>Region</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>Region</literal> service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">Accessing locale and region-dependent settings such as number formatting, currency and timezones.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Converting timezones and calculate Daylight Saving Time (DST) offsets.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id67160078807676" role="listitem">Transforming numbers into text in any supported language.</paragraph> + </listitem> + </list> +</section> + + <h2 id="hd_id851656012844548">Definitions</h2> + <h3 id="hd_id421656012886648">Locale or Region</h3> + <paragraph role="paragraph" id="par_id191656012908838">A string combining a language and a country in the format "la-CO". The language part is expressed with 2 or 3 lowercase characters followed by a dash and 2 uppercase characters representing the country.</paragraph> + <paragraph role="paragraph" id="par_id431656013368415">For instance, "en-US" corresponds to the English language in the United States; "fr-BE" corresponds to the French language in Belgium, and so forth.</paragraph> + <paragraph role="paragraph" id="par_id981656013623018">On some situations the full locale is not required and only the language or country may be specified.</paragraph> + <note id="par_id261656013132204">Most properties and methods accept a locale as argument. If no locale is specified, then the user-interface locale is used, which is defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</note> + <h3 id="hd_id51656013825718">Timezone</h3> + <paragraph role="paragraph" id="par_id541656013854150">A string in the format "Region/City" such as "Europe/Berlin", or a timezone ID such as "UTC" or "GMT-8:00". Refer to the wiki page <link href="https://wikipedia.org/wiki/List_of_tz_database_time_zones" name="TimeZones_List">List of tz database and timezones</link> for a list of possible timezone names and IDs.</paragraph> + <warning id="par_id981656078937577">Providing an invalid timezone string to any of the methods in the <literal>Region</literal> service will not result in a runtime error. Instead, methods as <literal>UTCDateTime</literal> and <literal>UTCNow</literal> will return the current operating system date and time.</warning> + <paragraph role="paragraph" id="par_id611656014040098">The time offset between the timezone and the Greenwich Meridian Time (GMT) is expressed in minutes.</paragraph> + <paragraph role="paragraph" id="par_id121656014053670">The Daylight Saving Time (DST) is an additional offset.</paragraph> + <note id="par_id591656014140929">The timezone and DST offsets may be positive or negative.</note> + + <h2 id="hd_id281600788076359">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Region</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + <paragraph role="paragraph" id="par_id321614902851541">The examples below in Basic and Python instantiate the <literal>Region</literal> service and access the <literal>Country</literal> property.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851600788076202">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001600788076254">Dim oRegion As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721600788076288">oRegion = CreateScriptService("Region")</paragraph> + <paragraph role="bascode" id="bas_id791600788431935">MsgBox oRegion.Country("en-US") ' United States</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626695710433">oRregion = CreateScriptService("Region")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id311626695710851">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391626695711082">bas.MsgBox(oRegion.Country("en-US"))</paragraph> + </pycode> + + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id11161490152686"> + <bookmark_value>Region service;Country</bookmark_value> + <bookmark_value>Region service;Currency</bookmark_value> + <bookmark_value>Region service;DatePatterns</bookmark_value> + <bookmark_value>Region service;DateSeparator</bookmark_value> + <bookmark_value>Region service;DayAbbrevNames</bookmark_value> + <bookmark_value>Region service;DayNames</bookmark_value> + <bookmark_value>Region service;DayNarrowNames</bookmark_value> + <bookmark_value>Region service;DecimalPoint</bookmark_value> + <bookmark_value>Region service;Language</bookmark_value> + <bookmark_value>Region service;ListSeparator</bookmark_value> + <bookmark_value>Region service;MonthAbbrevNames</bookmark_value> + <bookmark_value>Region service;MonthNames</bookmark_value> + <bookmark_value>Region service;MonthNarrowNames</bookmark_value> + <bookmark_value>Region service;ThousandSeparator</bookmark_value> + <bookmark_value>Region service;TimeSeparator</bookmark_value> + </bookmark> + + <h2 id="hd_id711600788076834">Properties</h2> + <paragraph role="paragraph" id="par_id601656018689690">All properties listed below accept a <literal>locale</literal> argument, provided as a string. Some properties require this argument to be in the format "la-CO", whereas others may receive "la" or "CO" as input.</paragraph> + + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330679679" role="tablehead">Locale</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">Country</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411656330757666" role="tablecontent" localize="false">"la‑CO"<br/>"CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">Returns the country name in English corresponding to a given region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">Currency</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330815396" role="tablecontent" localize="false">"la-CO"<br/>"CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">Returns the ISO 4217 currency code of the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721600788076638" role="tablecontent" localize="false">DatePatterns</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711600788076534" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911600788076842" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330815199" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600788076645" role="tablecontent">Returns a zero-based array of strings containing the date acceptance patterns for the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961600788076890" role="tablecontent" localize="false">DateSeparator</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891600788076190" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076562" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330809635" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91600788076674" role="tablecontent">Returns the date separator used in the given region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719246" localize="false" role="tablecontent">DayAbbrevNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747014" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748566" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330815320" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021745014" role="tablecontent">Returns a zero-based array of strings containing the list of abbreviated weekday names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021716585" localize="false" role="tablecontent">DayNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747209" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748322" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330815767" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021748865" role="tablecontent">Returns a zero-based array of strings containing the list of weekday names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719135" localize="false" role="tablecontent">DayNarrowNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021747903" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021748455" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330819641" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021747711" role="tablecontent">Returns a zero-based array of strings containing the list of the initials of weekday names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021710186" localize="false" role="tablecontent">DecimalPoint</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021748013" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021749655" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330816830" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749297" role="tablecontent">Returns the decimal separator used in numbers in the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021719022" localize="false" role="tablecontent">Language</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021743188" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021743058" localize="false" role="tablecontent">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330816697" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021749018" role="tablecontent">Returns the name of the language, in English, of the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id951600788076443" role="tablecontent" localize="false">ListSeparator</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391600788076253" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381600788076799" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330816642" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076541" role="tablecontent">Returns the list separator used in the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id831633021710156" localize="false" role="tablecontent">MonthAbbrevNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561633021706513" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id201633021746335" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330814533" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831633021741117" role="tablecontent">Returns a zero-based array of strings containing the list of abbreviated month names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id41600788076936" role="tablecontent" localize="false">MonthNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211600788076138" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076518" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330817644" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521600788076371" role="tablecontent">Returns a zero-based array of strings containing the list of month names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161600788076362" role="tablecontent" localize="false">MonthNarrowNames</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21600788076758" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id871600788076196" role="tablecontent">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330812262" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id781600788076694" role="tablecontent">Returns a zero-based array of strings containing the list of the initials of month names in the specified language.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id471600788076885" role="tablecontent" localize="false">ThousandSeparator</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id261600788076841" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661600788076636" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330844830" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id116007880767507" role="tablecontent">Returns the thousands separator used in numbers in the specified region.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id221600789141781" role="tablecontent" localize="false">TimeSeparator</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531600789141795" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561600789141282" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id131656330817766" role="tablecontent" localize="false">"la-CO"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301600789141619" role="tablecontent">Returns the separator used to format times in the specified region.</paragraph> + </tablecell> + </tablerow> + </table> + + <table id="tab_id901611086279902"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Region Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_region.xhp#DSTOffset" name="DSTOffset method">DSTOffset</link><br/> + <link href="text/sbasic/shared/03/sf_region.xhp#LocalDateTime" name="LocalDateTime method">LocalDateTime</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_region.xhp#Number2Text" name="Number2Text method">Number2Text</link><br/> + <link href="text/sbasic/shared/03/sf_region.xhp#TimeZoneOffset" name="TimeZoneOffset method">TimeZoneOffset</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611086279903" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_region.xhp#UTCDateTime" name="UTCDateTime method">UTCDateTime</link><br/> + <link href="text/sbasic/shared/03/sf_region.xhp#UTCNow" name="UTCNow method">UTCNow</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + + <section id="DSTOffset"> + <comment> DSTOffset ---------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969187"> + <bookmark_value>Region service;DSTOffset</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698020" localize="false">DSTOffset</h2> + <paragraph role="paragraph" id="par_id71621894830071">Computes the additional Daylight Saving Time (DST) offset, in minutes, that is applicable to a given region and timezone.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897208117"> + <input>svc.DSTOffset(localdatetime: date, timezone: str, opt locale: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896675880"><emph>localdatetime</emph>: the local date and time expressed as a date.</paragraph> + <paragraph role="paragraph" id="par_id401621896675125"><emph>timezone</emph>: the timezone for which the offset will be calculated.</paragraph> + <paragraph role="paragraph" id="par_id401621896675963"><emph>locale</emph>: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id531656022497519">' Calculates the offset applicable in the "America/Los_Angeles" timezone</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201656782497415">Dim aDateTime As Date, offset As Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201656022497919">aDateTime = DateSerial(2022, 7, 1) + TimeSerial(16, 0, 0)</paragraph> + <paragraph role="bascode" id="bas_id801656022498143">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601656022498128">aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)</paragraph> + <paragraph role="bascode" id="bas_id831656022498543">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621898860952">import datetime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861621898933001">aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)</paragraph> + <paragraph role="pycode" id="pyc_id871621898933281">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861621898934287">aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)</paragraph> + <paragraph role="pycode" id="pyc_id871621898934141">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)</paragraph> + </pycode> + </section> + + <section id="LocalDateTime"> + <comment> LocalDateTime ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969630"> + <bookmark_value>Region service;LocalDateTime</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698124" localize="false">LocalDateTime</h2> + <paragraph role="paragraph" id="par_id71621894832058">Computes the local date and time from a UTC date and time.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897208785"> + <input>svc.LocalDateTime(utcdatetime: date, timezone: str, opt locale: str): date</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896674716"><emph>utcdatetime</emph>: the UTC date and time, expressed using a date object.</paragraph> + <paragraph role="paragraph" id="par_id401621896675449"><emph>timezone</emph>: the timezone for which the local time will be calculated.</paragraph> + <paragraph role="paragraph" id="par_id401621896675193"><emph>locale</emph>: the locale specifying the country for which the local time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id201656022497017">' June 6th, 2022 at 10:30:45 (used here as UTC time)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711656454548454">Dim UTCTime As Date, localTime As Date</paragraph> + <paragraph role="bascode" localize="false" id="bas_id803696022498143">UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)</paragraph> + <paragraph role="bascode" id="bas_id531656022497121">' Calculates local time in Sao Paulo, Brazil</paragraph> + <paragraph role="bascode" id="bas_id601656022498318">' June 6th, 2022 at 07:30:45</paragraph> + <paragraph role="bascode" localize="false" id="bas_id830696022498543">localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id761621898833352">import datetime</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861621898933128">utcTime = datetime.datetime(2022, 6, 23, 10, 30, 45)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871621898933337">localTime = oRegion.LocalDateTime(utcTime, "America/Sao_Paulo", "BR")</paragraph> + </pycode> + </section> + + <section id="Number2Text"> + <comment> Number2Text ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919966650"> + <bookmark_value>Region service;Number2Text</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698374" localize="false">Number2Text</h2> + <paragraph role="paragraph" id="par_id71621894832089">Converts numbers and monetary values into written text for any of the currently supported languages.</paragraph> + <tip id="par_id971656026551328">For a list of all supported languages visit the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1linguistic2_1_1XNumberText.html" name="XNumberText">XNumberText Interface</link> API reference.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897208441"> + <input>svc.Number2Text(number: any, opt locale: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896675306"><emph>number</emph>: the number to be converted into written text. It can be provided either as a numeric type or as a string. When a string is provided, it can be preceded by a prefix informing how the numbers should be written. It is also possible to include ISO 4217 currency codes. See examples below for more information.</paragraph> + <paragraph role="paragraph" id="par_id401621896675412"><emph>locale</emph>: the locale defining the language into which the number will be converted to, given either in "la-CO" or "la" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id301656027173020">' Returns "one hundred five"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851656454602974">Dim numText As String</paragraph> + <paragraph role="bascode" id="bas_id531656022496631">numText = oRegion.Number2Text(105, "en-US")</paragraph> + <paragraph role="bascode" id="bas_id771656027217144">' Returns: "two point four two"</paragraph> + <paragraph role="bascode" id="bas_id201656022493367">numText = oRegion.Number2Text(2.42, "en-US")</paragraph> + <paragraph role="bascode" id="bas_id281656027262234">' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol</paragraph> + <paragraph role="bascode" id="bas_id201656022497171">numText = oRegion.Number2Text("EUR 25.10", "en-US")</paragraph> + <paragraph role="bascode" id="bas_id981656027330132">' Returns: "fifteenth"; Notice the "ordinal" prefix</paragraph> + <paragraph role="bascode" id="bas_id841656027330394">numText = oRegion.Number2Text("ordinal 15", "en-US")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id401656027481473">numText = oRegion.Number2Text(105, "en-US")</paragraph> + <paragraph role="pycode" id="pyc_id781656027481769">numText = oRegion.Number2Text(2.42, "en-US")</paragraph> + <paragraph role="pycode" id="pyc_id951656027482096">numText = oRegion.Number2Text("EUR 25.10", "en-US")</paragraph> + <paragraph role="pycode" id="pyc_id231656027482425">numText = oRegion.Number2Text("ordinal 15", "en-US")</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id801656027524051">To get a list of all supported prefixes in a given language, call <literal>Number2Text</literal> with the special "help" argument, as shown in the example below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id851656027713735">prefixes = oRegion.Number2Text("help")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id716560277139601">MsgBox prefixes</paragraph> + <paragraph role="bascode" id="bas_id181656027807107">' Considering the "en-US" locale the message box will show the following text</paragraph> + <paragraph role="bascode" id="bas_id216560277123601">' one, two, three</paragraph> + <paragraph role="bascode" id="bas_id361656027712711">' ordinal: first, second, third</paragraph> + <paragraph role="bascode" id="bas_id891656027712920">' ordinal-number: 1st, 2nd, 3rd</paragraph> + <paragraph role="bascode" id="bas_id611656027713104">' year: nineteen ninety-nine, two thousand, two thousand one</paragraph> + <paragraph role="bascode" id="bas_id861656027713288">' currency (for example, USD): two U.S. dollars and fifty cents</paragraph> + <paragraph role="bascode" id="bas_id841656027713503">' money USD: two and 50/100 U.S. dollars</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id781656027840633">The first line in the message box does not have a prefix, which means that it is the standard format. The subsequent lines include the prefix and some examples of numbers using its format.</paragraph> + <note id="par_id781656028528520">Each language has its own set of supported prefixes.</note> + </section> + + <section id="TimeZoneOffset"> + <comment> TimeZoneOffset ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919966017"> + <bookmark_value>Region service;TimeZoneOffset</bookmark_value> + </bookmark> + <h2 id="hd_id201589199691085" localize="false">TimeZoneOffset</h2> + <paragraph role="paragraph" id="par_id71621894832117">Returns the offset between GMT and the given timezone and locale, in minutes.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897203066"> + <input>svc.TimeZoneOffset(timezone: str, opt locale: str): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896675018"><emph>timezone</emph>: the timezone for which the offset to the GMT will be calculated.</paragraph> + <paragraph role="paragraph" id="par_id401621896675691"><emph>locale</emph>: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id101656454730797">Dim offset As Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id916560675890495">offset = oRegion.TimeZoneOffset("America/New_York", "US") ' -300</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211656075890806">offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") ' 60</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id1001656076044293">offset = oRegion.TimeZoneOffset("America/New_York", "US") # -300</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id5015656076044605">offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") # 60</paragraph> + </pycode> + </section> + + <section id="UTCDateTime"> + <comment> UTCDateTime ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919943207"> + <bookmark_value>Region service;UTCDateTime</bookmark_value> + </bookmark> + <h2 id="hd_id201589199691808" localize="false">UTCDateTime</h2> + <paragraph role="paragraph" id="par_id71621894864217">Returns the UTC date and time considering a given local date and time in a timezone.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897202644"> + <input>svc.UTCDateTime(localdatetime: date, timezone: str, opt locale: str): date</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896674748"><emph>localdatetime</emph>: the local date and time in a specific timezone expressed as a date.</paragraph> + <paragraph role="paragraph" id="par_id401621896675739"><emph>timezone</emph>: the timezone for which the <literal>localdatetime</literal> argument was given.</paragraph> + <paragraph role="paragraph" id="par_id401621896675550"><emph>locale</emph>: the locale specifying the country for which the <literal>localdatetime</literal> argument was given, expressed either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id861656077547861">' Date/Time in Berlin, June 23, 2022 at 14:30:00</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771656454767976">Dim localDT As Date, utcTime As Date</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911656077521797">localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)</paragraph> + <paragraph role="bascode" id="bas_id731656077523173">' The UTC date/time is June 23, 2022 at 12:30:00</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001656077527477">utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id361656077667354">import datetime</paragraph> + <paragraph role="pycode" id="pyc_id901656077667666">localDT = datetime.datetime(2022, 6, 23, 14, 30, 0)</paragraph> + <paragraph role="pycode" id="pyc_id521656077682826">utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")</paragraph> + </pycode> + </section> + + <section id="UTCNow"> + <comment> UTCNow ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919939587"> + <bookmark_value>Region service;UTCNow</bookmark_value> + </bookmark> + <h2 id="hd_id201589199694336" localize="false">UTCNow</h2> + <paragraph role="paragraph" id="par_id71621894835287">Returns the current UTC date and time, given a timezone and locale.</paragraph> + <paragraph role="paragraph" id="par_id491656078254442">This method uses the current date and time of your operating system to calculate the UTC time.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897201935"> + <input>svc.UTCNow(timezone: str, opt locale: str): date</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id401621896673318"><emph>timezone</emph>: the timezone for which the current UTC time will be calculated.</paragraph> + <paragraph role="paragraph" id="par_id401621896674831"><emph>locale</emph>: the locale specifying the country for which the current UTC time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769" name="OfficeLocale_link"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id861656078128374">' Suppose the operating system time is June 23rd, 2022 at 10:42:00</paragraph> + <paragraph role="bascode" id="bas_id691656078180784">' If the computer is in Europe/Berlin, then UTC time is June 23rd, 2022 at 08:42:00</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351656454814865">Dim utcTime As Date</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881656078243397">utcTime = oRegion.UTCNow("Europe/Berlin", "DE")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" id="pyc_id821656078645252">utcTime = oRegion.UTCNow("Europe/Berlin", "DE")</paragraph> + </pycode> + </section> + + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_platform.xhp#PlatformService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_services.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_services.xhp new file mode 100644 index 000000000..e8462b426 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_services.xhp @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Services" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Services service</title> + <filename>/text/sbasic/shared/03/sf_services.xhp</filename> + </topic> +</meta> +<body> +<section id="abstract"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id751582710853363"> + <bookmark_value>Services service</bookmark_value> + </bookmark> + <h1 id="hd_id471582710868716"><variable id="ScriptForgeServices"><link href="text/sbasic/shared/03/sf_services.xhp" name="Services service"><literal>ScriptForge</literal>.<literal>Services</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id241627513489594">The main purpose of the <literal>Services</literal> module is to provide access to the <literal>CreateScriptService</literal> method, which can be called in user scripts to instantiate services that are implemented using the ScriptForge framework.</paragraph> +</section> +<paragraph role="paragraph" id="par_id351582710868545">In ScriptForge terminology a service is a collection of methods and properties that can be used for a common purpose. For example, the <literal>String</literal> service provides methods for manipulating strings whereas the <literal>FileSystem</literal> service allows for the manipulation of files and folders.</paragraph> +<tip id="par_id541627513771828">The <literal>Services</literal> module of the ScriptForge library provides additional methods that are used either internally to register available services or by developers who are interested in extending ScriptForge by creating new services. The only method that is relevant for user scripts is <literal>CreateScriptService</literal>.</tip> + +<section id="CreateScriptService"> + <comment> CreateScriptService ----------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id861582714020042"> + <bookmark_value>Services service;CreateScriptService</bookmark_value> + </bookmark> + <h2 id="hd_id751582714020043" localize="false">CreateScriptService</h2> + <paragraph role="paragraph" id="par_id871582714020043">This method is used to instantiate a ScriptForge service so it can be called in user scripts.</paragraph> + <paragraph role="paragraph" id="par_id711627514310039">The returned value is a Basic object or <literal>Nothing</literal> if an error occurred.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id961627475353964"> + <input>svc.CreateScriptService(service: str, [arg0: any] ...): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id971582714020045"><emph>service</emph>: The name of the service identified as a string in the format "library.service":</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id11627475954271" role="listitem">The <emph>library</emph> is a Basic library that must exist in the <link href="text/sbasic/shared/03131900.xhp" name="GlobalScope">GlobalScope</link>. The default value is "ScriptForge".</paragraph> + </listitem> + <listitem> + <paragraph id="par_id811627475954641" role="listitem">The <emph>service</emph> is one of the services registered by the ScriptForge library.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id391582714020045"><emph>arg0, ...</emph>: A list of arguments required by the invoked service.</paragraph> + <paragraph role="paragraph" id="par_id841627475900817">If the first argument refers to an event manager, then <literal>arg0</literal> is mandatory and must be the UNO object representing the event provided as argument to the user macro.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id581582898149266">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" id="bas_id981582898174133">' To be done once</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281582898567582">Dim svc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571582714020046">Set svc = CreateScriptService("Array")</paragraph> + <paragraph role="bascode" id="bas_id311582715700844">' Refers to the "ScriptForge.Array" service or SF_Array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671582715735064">Set svc = CreateScriptService("ScriptForge.Dictionary")</paragraph> + <paragraph role="bascode" id="bas_id61582715759468">' Returns a new empty dictionary class instance; "ScriptForge." is optional</paragraph> + <paragraph role="bascode" localize="false" id="bas_id231582715781789">Set svc = CreateScriptService("SFDocuments.Calc")</paragraph> + <paragraph role="bascode" id="bas_id901582715797722">' Refers to the Calc service, implemented in the associated SFDocuments library</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841582715829454">Set svc = CreateScriptService("Timer", True)</paragraph> + <paragraph role="bascode" id="bas_id361582715845747">' Returns a Timer class instance starting immediately</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11596298688112">Set svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)</paragraph> + <paragraph role="bascode" id="bas_id571596298708062">' Refers to the DocumentEvent service implemented in the associated SFDocuments library</paragraph> + <paragraph role="bascode" id="bas_id121613492254532">' Returns the instance of the Document class that fired the event</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id881627426495369">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id431627426495747">svc = CreateScriptService("Array")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681627426496018">svc = CreateScriptService("ScriptForge.Dictionary")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811627426496299">svc = CreateScriptService("SFDocuments.Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811627426496564">svc = CreateScriptService("Timer", True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921627426496940">svc = CreateScriptService("SFDocuments.DocumentEvent", oEvent)</paragraph> + </pycode> + <paragraph role="paragraph" id="par_id321627570607194">Python scripts support keyword arguments when calling <literal>CreateScriptService</literal>. The following example illustrates this concept by instantiating the <literal>Timer</literal> and <literal>Document</literal> services using keyword arguments.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id771627570744091">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id351627570744359"># Timer</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181627570744511">my_timer = CreateScriptService("Timer", start = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321627570744655"># Document</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id591627570744815">my_doc = CreateScriptService("Document", windowname = "some_file.ods")</paragraph> + </pycode> + <tip id="par_id901627576693156">To make writing Python scripts more fluid, ScriptForge provides the <literal>Basic</literal> service which allows Python scripts to call a collection of methods with the same syntax and meaning as their homonymous native Basic functions.</tip> + <paragraph role="paragraph" id="par_id41627644806288">The following example instantiates the <literal>Basic</literal> service and calls the <literal>MsgBox</literal> method, which is equivalent to the <literal>MsgBox</literal> function available in Basic:</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id521627644939451">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id241627644939717">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id841627644939897">bas.MsgBox("Hello World!")</paragraph> + </pycode> + <note id="par_id581627645023307">Beware that the <literal>Basic</literal> service has to be instantiated in Python scripts using the <literal>CreateScriptService</literal> method.</note> +</section> + +<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + +<section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_basic.xhp#BasicService"/> + <embed href="text/sbasic/shared/03103700.xhp#Set_h1"/> + <embed href="text/sbasic/shared/03131900.xhp#GlobalScope_h1"/> +</section> + +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_session.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_session.xhp new file mode 100644 index 000000000..ff4124323 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_session.xhp @@ -0,0 +1,693 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Session" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Session service</title> + <filename>/text/sbasic/shared/03/sf_session.xhp</filename> + </topic> +</meta> +<body> + <section id="abstract"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id661582814720399"> + <bookmark_value>Session service</bookmark_value> + </bookmark> + <h1 id="hd_id901582814720985" xml-lang="en-US"><variable id="SessionService"><link href="text/sbasic/shared/03/sf_session.xhp" name="Session service"><literal>ScriptForge.Session</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id861582814720987" xml-lang="en-US">The <literal>Session</literal> service gathers various general-purpose methods about:</paragraph> + <list type = "unordered"> + <listitem> + <paragraph id="par_id34158281472051" role="listitem" xml-lang="en-US">the installation or execution environment</paragraph> + </listitem> + <listitem> + <paragraph id="par_id411582814720361" role="listitem" xml-lang="en-US">UNO introspection</paragraph> + </listitem> + <listitem> + <paragraph id="par_id321582814720863" role="listitem" xml-lang="en-US">the invocation of external scripts or programs</paragraph> + </listitem> + </list> + </section> + + <h2 id="hd_id91582814720116" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Session</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id931582897922121">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961582814720760">Dim session As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651582814720203">session = CreateScriptService("Session")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891626808716096">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id261626808717344">session = CreateScriptService("Session")</paragraph> + </pycode> + <h2 id="hd_id291582814720762" xml-lang="en-US">Constants</h2> + <paragraph role="paragraph" id="par_id82158281472034" xml-lang="en-US">Below is a list of constants available to ease the designation of the library containing a Basic or Python script to invoke. Use them as <literal>session.CONSTANT</literal>.</paragraph> + <section id="constants"> + <table id="tab_id291582814720160"> + <tablerow> + <tablecell> + <paragraph id="par_id381582814720870" role="tablehead" xml-lang="en-US" localize="false">CONSTANT</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id9158281472045" role="tablehead" xml-lang="en-US">Value</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id241582814720636" role="tablehead" xml-lang="en-US">Where to find the library?</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id361582814720116" role="tablehead" xml-lang="en-US">Applicable</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id821582814720218" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISEMBEDDED</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401582814720597" role="tablecontent" xml-lang="en-US" localize="false">"document"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451582814720105" role="tablecontent" xml-lang="en-US">in the document</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421582814720733" role="tablecontent" xml-lang="en-US" localize="false">Basic + Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id191582814720876" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISAPPLICATION</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601582814720388" role="tablecontent" xml-lang="en-US" localize="false">"application"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id73158281472032" role="tablecontent" xml-lang="en-US">in any shared library</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id291582814720233" role="tablecontent" xml-lang="en-US" localize="false">Basic</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id571582814720667" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISPERSONAL</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id4158281472033" role="tablecontent" xml-lang="en-US" localize="false">"user"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id391582814720487" role="tablecontent" xml-lang="en-US">in My Macros</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701582814720517" role="tablecontent" xml-lang="en-US" localize="false">Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id691582814720670" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISPERSOXT</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401582814720356" role="tablecontent" xml-lang="en-US" localize="false">"user:uno_packages"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id56158281472073" role="tablecontent" xml-lang="en-US">in an extension installed for the current user</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id611582814720723" role="tablecontent" xml-lang="en-US" localize="false">Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id781582814720282" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISSHARED</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id991582814720953" role="tablecontent" xml-lang="en-US" localize="false">"share"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id21582814720997" role="tablecontent" xml-lang="en-US">in %PRODUCTNAME macros</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id491582814720794" role="tablecontent" xml-lang="en-US" localize="false">Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id371582814720280" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISSHAROXT</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id51582814720754" role="tablecontent" xml-lang="en-US" localize="false">"share:uno_packages"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981582814720125" role="tablecontent" xml-lang="en-US">in an extension installed for all users</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id66158281472037" role="tablecontent" xml-lang="en-US" localize="false">Python</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id71582814720886" role="tablecontent" xml-lang="en-US" localize="false">SCRIPTISOXT</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id51582814720584" role="tablecontent" xml-lang="en-US" localize="false">"uno_packages"</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id93158281472047" role="tablecontent" xml-lang="en-US">in an extension but the installation parameters are unknown</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601582814720689" role="tablecontent" xml-lang="en-US" localize="false">Python</paragraph> + </tablecell> + </tablerow> + </table> + </section> + +<table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Session Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_session.xhp#ExecuteBasicScript" name="ExecuteBasicScript method">ExecuteBasicScript</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#ExecuteCalcFunction" name="ExecuteCalcFunction method">ExecuteCalcFunction</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#ExecutePythonScript" name="ExecutePythonScript method">ExecutePythonScript</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#GetPDFExportOptions" name="GetPDFExportOptions method">GetPDFExportOptions</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#HasUnoMethod" name="HasUnoMethod method">HasUnoMethod</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_session.xhp#HasUnoProperty" name="HasUnoProperty method">HasUnoProperty</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#OpenURLInBrowser" name="OpenURLInBrowser method">OpenURLInBrowser</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#RunApplication" name="RunApplication method">RunApplication</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#SendMail" name="SendMail method">SendMail</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#SetPDFExportOptions" name="SetPDFExportOptions method">SetPDFExportOptions</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_session.xhp#UnoMethods" name="UnoMethods method">UnoMethods</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#UnoProperties" name="UnoProperties method">UnoProperties</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#UnoObjectType" name="UnoObjectType method">UnoObjectType</link><br/> + <link href="text/sbasic/shared/03/sf_session.xhp#WebService" name="WebService method">WebService</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + + <tip id="par_id491613061572993"><literal>Execute...</literal> methods in <literal>Session</literal> service behave as follows: + <br/>Arguments are passed by value. Changes made by the called function to the arguments do not update their values in the calling script. + <br/>A single value or an array of values is returned to the calling script. + </tip> + +<section id="ExecuteBasicScript"> + <comment> ExecuteBasicScript ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id41582815407230"> + <bookmark_value>Session service;ExecuteBasicScript</bookmark_value> + </bookmark> + <h2 id="hd_id281582815407230" localize="false">ExecuteBasicScript</h2> + <paragraph role="paragraph" id="par_id451582815407230">Execute the Basic script given its name and location and fetch its result if any.</paragraph> + <paragraph role="paragraph" id="par_id921600856780901" xml-lang="en-US">If the script returns nothing, which is the case of procedures defined with <literal>Sub</literal>, the returned value is <literal>Empty</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id131626808989444"> + <input>session.ExecuteBasicScript(scope: str, script: str, args: any[0..*]): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id631582815407231"><emph>scope</emph>: String specifying where the script is stored. It can be either "document" (constant <literal>session.SCRIPTISEMBEDDED</literal>) or "application" (constant <literal>session.SCRIPTISAPPLICATION</literal>).</paragraph> + <paragraph role="paragraph" id="par_id691582815407231"><emph>script</emph>: String specifying the script to be called in the format "library.module.method" as a case-sensitive string.</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id741626828862265" role="listitem">The library is loaded in memory if necessary.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id981626828863001" role="listitem">The module must not be a class module.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id721626828863257" role="listitem">The method may be a <literal>Sub</literal> or a <literal>Function</literal>.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id881582815407231"><emph>args</emph>: The arguments to be passed to the called script.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id21626809513802">Consider the following Basic function named <literal>DummyFunction</literal> that is stored in "My Macros" in the "Standard" library inside a module named "Module1".</paragraph> + <paragraph role="paragraph" id="par_id551626810319766">The function simply takes in two integer values <literal>v1</literal> and <literal>v2</literal> and return the sum of all values starting in <literal>v1</literal> and ending in <literal>v2</literal>.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id21626810243092">Function DummyFunction(v1 as Integer, v2 as Integer) As Long</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571626810243635"> Dim result as Long, i as Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321626810243876"> For i = v1 To v2</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631626810244299"> result = result + i</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321626810244676"> Next i</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641626810245084"> DummyFunction = result</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381626810245324">End Function</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id461626810470057">The examples below show how to call <literal>DummyFunction</literal> from within Basic and Python scripts.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id251626810696112">Dim session : session = CreateScriptService("Session")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321626810696366">Dim b_script as String, result as Long</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291626810696576">b_script = "Standard.Module1.DummyFunction"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751626810696799">result = session.ExecuteBasicScript("application", b_script, 1, 10)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991626810697024">MsgBox result ' 55</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id291626810829019">session = CreateScriptService("Session")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231626810829279">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id261626810829451">b_script = 'Standard.Module1.DummyFunction'</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111626810829725">result = session.ExecuteBasicScript('application', b_script, 1, 10)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id111626810838070">bas.MsgBox(result) # 55</paragraph> + </pycode> +</section> + +<section id="ExecuteCalcFunction"> + <comment> ExecuteCalcFunction ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571582816585180"> + <bookmark_value>Session service;ExecuteCalcFunction</bookmark_value> + </bookmark> + <h2 id="hd_id551582816585181" localize="false">ExecuteCalcFunction</h2> + <paragraph role="paragraph" id="par_id111582816585181">Execute a Calc function using its English name and based on the given arguments. + <br />If the arguments are arrays, the function is executed as an <link href="text/scalc/01/04060107.xhp" name="array formula">array formula</link>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701626811351722"> + <input>session.ExecuteCalcFunction(calcfunction: str, args: any[0..*]): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771582816585183"><emph>calcfunction</emph>: The name of the Calc function to be called, in English.</paragraph> + <paragraph role="paragraph" id="par_id371582816585183"><emph>args</emph>: The arguments to be passed to the called Calc function. Each argument must be either a string, a numeric value or an array of arrays combining those types.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461582816585184">session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) ' 4</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641582816585185">session.ExecuteCalcFunction("ABS", Array(Array(-1, 2, 3), Array(4, -5, 6), Array(7, 8, -9)))(2)(2) ' 9</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241582817051111">session.ExecuteCalcFunction("LN", -3)</paragraph> + <paragraph role="bascode" id="bas_id881582816585185" xml-lang="en-US">' Generates an error.</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id781626816579430">session.ExecuteCalcFunction("AVERAGE", 1, 5, 3, 7) # 4</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id721626816579849">session.ExecuteCalcFunction("ABS", ((-1, 2, 3), (4, -5, 6), (7, 8, -9)))[2][2] # 9</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id191626816580053">session.ExecuteCalcFunction("LN", -3)</paragraph> + </pycode> +</section> + +<section id="ExecutePythonScript"> + <comment> ExecutePythonScript ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id671582818023244"> + <bookmark_value>Session service;ExecutePythonScript</bookmark_value> + </bookmark> + <h2 id="hd_id741582818023244" localize="false">ExecutePythonScript</h2> + <paragraph role="paragraph" id="par_id571582818023245">Execute the Python script given its location and name, fetch its result if any. Result can be a single value or an array of values.</paragraph> + <paragraph role="paragraph" id="par_id71600856817410" xml-lang="en-US">If the script is not found, or if it returns nothing, the returned value is <literal>Empty</literal>.</paragraph> + <embed href="text/sbasic/python/python_2_basic.xhp#APIScriptingFramework" /> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id421626816736635"> + <input>session.ExecutePythonScript(scope: str, script: str, args: any[0..*]): any</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id791582818023246"><emph>scope</emph>: One of the applicable constants listed <link href="text/sbasic/shared/03/sf_session.xhp#constants" name="Session constants">above</link>. The default value is <literal>session.SCRIPTISSHARED</literal>.</paragraph> + <paragraph role="paragraph" id="par_id71582818023247"><emph>script</emph>: Either "library/module.py$method" or "module.py$method" or "myExtension.oxt|myScript|module.py$method" as a case-sensitive string.</paragraph> + <list type="unordered"> + <listitem><paragraph id="par_id501613061041313" role="listitem">library: The folder path to the Python module.</paragraph></listitem> + <listitem><paragraph id="par_id771613061043097" role="listitem">myScript: The folder containing the Python module.</paragraph></listitem> + <listitem><paragraph id="par_id301613061123849" role="listitem">module.py: The Python module.</paragraph></listitem> + <listitem><paragraph id="par_id241613061044560" role="listitem">method: The Python function.</paragraph></listitem> + </list> + <paragraph role="paragraph" id="par_id711582818023247"><emph>args</emph>: The arguments to be passed to the called script.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id701626817164878">Consider the Python function <literal>odd_integers</literal> defined below that creates a list with odd integer values between <literal>v1</literal> and <literal>v2</literal>. Suppose this function is stored in a file named <emph>my_macros.py</emph> in your user scripts folder.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21626817636630">def odd_integers(v1, v2):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231626817636935"> odd_list = [v for v in range(v1, v2 + 1) if v % 2 != 0]</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901626817637127"> return odd_list</paragraph> + </pycode> + <tip id="par_id751626817335715">Read the help page <link href="text/sbasic/python/python_locations.xhp" name="pylocation_link">Python Scripts Organization and Location</link> to learn more about where Python scripts can be stored.</tip> + <paragraph role="paragraph" id="par_id121626817725471">The following examples show how to call the function <literal>odd_integers</literal> from within Basic and Python scripts.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id481626817835712">Dim script as String, session as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141626817836000">script = "my_macros.py$odd_integers"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371626817836256">session = CreateScriptService("Session")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711626817836519">Dim result as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id221626817836809">result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91626817837112">MsgBox SF_String.Represent(result)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id231626818075452">session = CreateScriptService("Session")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id481626818075720">script = "my_macros.py$odd_integers"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661626818075938">result = session.ExecutePythonScript(session.SCRIPTISPERSONAL, script, 1, 9)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id811626818076162">bas.MsgBox(repr(result))</paragraph> + </pycode> +</section> + +<section id="GetPDFExportOptions"> + <comment> GetPDFExportOptions ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571582816536250"> + <bookmark_value>Session service;GetPDFExportOptions</bookmark_value> + </bookmark> + <h2 id="hd_id551582816589871" localize="false">GetPDFExportOptions</h2> + <paragraph role="paragraph" id="par_id111582816585087">Returns the current PDF export settings defined in the <menuitem>PDF Options</menuitem> dialog, which can be accessed by choosing <menuitem>File - Export as - Export as PDF</menuitem>.</paragraph> + <paragraph role="paragraph" id="par_id931638383270026">Export options set with the <menuitem>PDF Options</menuitem> dialog are kept for future use. Hence <literal>GetPDFExportOptions</literal> returns the settings currently defined. In addition, use <literal>SetPDFExportOptions</literal> to change current PDF export options.</paragraph> + <paragraph role="paragraph" id="par_id801638383659558">This method returns a <literal>Dictionary</literal> object wherein each key represent export options and the corresponding values are the current PDF export settings.</paragraph> + <tip id="par_id751638383457198">Read the <link href="https://wiki.openoffice.org/wiki/API/Tutorials/PDF_export" name="PDFExport_Wiki">PDF Export wiki page</link> to learn more about all available options.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701626811351883"> + <input>session.GetPDFExportOptions(): obj</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id361638384343807">Dim expSettings As Object, msg As String, key As String, optLabels As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721638384344196">expSettings = session.GetPDFExportOptions()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181638384344396">optLabels = expSettings.Keys</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271638384344575">For Each key in optLabels</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711638384344810"> msg = msg + key & ": " & expSettings.Item(key) & Chr(10)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651638384345031">Next key</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101638384345303">MsgBox msg</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431638384345510">' Zoom: 100</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001638384345677">' Changes: 4</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11638384345891">' Quality: 90</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471638384346131">' ...</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> +</section> + +<section id="HasUnoMethod"> + <comment> HasUnoMethod ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id901587477335292"> + <bookmark_value>Session service;HasUnoMethod</bookmark_value> + </bookmark> + <h2 id="hd_id58158747733586" localize="false">HasUnoMethod</h2> + <paragraph role="paragraph" id="par_id111587477335982">Returns <literal>True</literal> if an UNO object contains the given method. Returns <literal>False</literal> when the method is not found or when an argument is invalid.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id761626818201301"> + <input>session.HasUnoMethod(unoobject: uno, methodname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id921587477335673"><emph>unoobject</emph>: The object to inspect.</paragraph> + <paragraph role="paragraph" id="par_id631587477566016" xml-lang="en-US"><emph>methodname</emph>: the method as a case-sensitive string</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471587477335112">Dim a As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71587477335350">a = CreateUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671587477335639">MsgBox session.HasUnoMethod(a, "callFunction") ' True</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id201626818671015">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id781626818671422">a = bas.createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441626818671679">result = session.HasUnoMethod(a, "callFunction")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626818671871">bas.MsgBox(result) # True</paragraph> + </pycode> +</section> + +<section id="HasUnoProperty"> + <comment> HasUnoProperty ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id511587477832348"> + <bookmark_value>Session service;HasUnoProperty</bookmark_value> + </bookmark> + <h2 id="hd_id521587477832241" localize="false">HasUnoProperty</h2> + <paragraph role="paragraph" id="par_id191587477832959">Returns <literal>True</literal> if a UNO object has the given property. Returns <literal>False</literal> when the property is not found or when an argument is invalid.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821626818816336"> + <input>session.HasUnoProperty(unoobject: uno, propertyname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id121587477832805"><emph>unoobject</emph>: The object to inspect.</paragraph> + <paragraph role="paragraph" id="par_id701587477832750" xml-lang="en-US"><emph>propertyname</emph>: the property as a case-sensitive string</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61587477832241">Dim svc As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281587477832114">svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id90158747783219">MsgBox session.HasUnoProperty(svc, "Wildcards")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id331626818906928">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id191626818907607">a = bas.createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951626818907799">result = session.HasUnoProperty(a, "Wildcards")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441626818907959">bas.MsgBox(result) # True</paragraph> + </pycode> +</section> + +<section id="OpenURLInBrowser"> + <comment> OpenURLInBrowser --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id321601129640799"> + <bookmark_value>Session service;OpenURLInBrowser</bookmark_value> + </bookmark> + <h2 id="hd_id971601129640909" localize="false">OpenURLInBrowser</h2> + <paragraph role="paragraph" id="par_id97160112964017">Open a Uniform Resource Locator (<link href="text/shared/00/00000002.xhp#URL" name="URL">URL</link>) in the default browser.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id831626819024511"> + <input>session.OpenURLInBrowser(url: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id241601129640549"><emph>url</emph>: The URL to open.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531626819105690">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781601129640527">session.OpenURLInBrowser("help.libreoffice.org/")</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id551626819119460"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121626819119605">session.OpenURLInBrowser("help.libreoffice.org/")</paragraph> + </pycode> +</section> + +<section id="RunApplication"> + <comment> RunApplication ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id121582819697896"> + <bookmark_value>Session service;RunApplication</bookmark_value> + </bookmark> + <h2 id="hd_id511582819697896" localize="false">RunApplication</h2> + <paragraph role="paragraph" id="par_id311582819697897">Executes an arbitrary system command and returns <literal>True</literal> if it was launched successfully.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id691626819239862"> + <input>session.RunApplication(command: str, parameters: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id461582819697898"><emph>command</emph>: The command to execute. This may be an executable file or a document which is registered with an application so that the system knows what application to launch for that document. The command must be expressed in the current <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id611582819697899"><emph>parameters</emph>: A list of space separated parameters as a single string. The method does not validate the given parameters, but only passes them to the specified command.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id111582819697900">session.RunApplication("Notepad.exe")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851582819697900">session.RunApplication("C:\myFolder\myDocument.odt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641582819697901">session.RunApplication("kate", "/home/user/install.txt") ' GNU/Linux</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id381626819384936">session.RunApplication("Notepad.exe")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id601626819385217">session.RunApplication(r"C:\myFolder\myDocument.odt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211626819385376">session.RunApplication("kate", "/home/user/install.txt") # GNU/Linux</paragraph> + </pycode> +</section> + +<section id="SendMail"> + <comment> SendMail ------------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id601601030349204"> + <bookmark_value>Session service;SendMail</bookmark_value> + </bookmark> + <h2 id="hd_id561601030349199" localize="false">SendMail</h2> + <paragraph role="paragraph" id="par_id131601030349755">Send a message - with optional attachments - to recipients from the user's mail client. The message may be edited by the user before sending or, alternatively, be sent immediately.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id691626819545788"> + <input>session.SendMail(recipient: str, cc: str = '', bcc: str = '', subject: str = '', body: str = '', filenames: str = '', editmessage: bool = True)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id701601030349896"><emph>recipient</emph>: An email address (the "To" recipient).</paragraph> + <paragraph role="paragraph" id="par_id571601030349904"><emph>cc</emph>: A comma-separated list of email addresses (the "carbon copy" recipients).</paragraph> + <paragraph role="paragraph" id="par_id961601031043346"><emph>bcc</emph>: A comma-separated list of email addresses (the "blind carbon copy" recipients).</paragraph> + <paragraph role="paragraph" id="par_id891601031050814"><emph>subject</emph>: the header of the message.</paragraph> + <paragraph role="paragraph" id="par_id191601031056673"><emph>body</emph>: The contents of the message as an unformatted text.</paragraph> + <paragraph role="paragraph" id="par_id511601031063269"><emph>filenames</emph>: a comma-separated list of file names. Each file name must respect the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id161601032784063"><emph>editmessage</emph>: When <literal>True</literal> (default), the message is edited before being sent.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id481601030349950">session.SendMail("someone@example.com" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901601032999905"> , Cc := "b@other.fr, c@other.be" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651601033006799"> , FileNames := "C:\myFile1.txt, C:\myFile2.txt")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821626819725867">session.SendMail("someone@example.com",</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391626819726171"> cc="john@other.fr, mary@other.be"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771626819726363"> filenames=r"C:\myFile1.txt, C:\myFile2.txt")</paragraph> + </pycode> +</section> + +<section id="SetPDFExportOptions"> + <comment> SetPDFExportOptions ------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id571582816563070"> + <bookmark_value>Session service;SetPDFExportOptions</bookmark_value> + </bookmark> + <h2 id="hd_id551582816583371" localize="false">SetPDFExportOptions</h2> + <paragraph role="paragraph" id="par_id111582816583005">Modifies the PDF export settings defined in the <menuitem>PDF Options</menuitem> dialog, which can be accessed by choosing <menuitem>File - Export as - Export as PDF</menuitem>.</paragraph> + <paragraph role="paragraph" id="par_id181638385131806">Calling this method changes the actual values set in the <menuitem>PDF Options</menuitem> dialog, which are used by the <literal>ExportAsPDF</literal> method from the <literal>Document</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id391638385313847">This method returns <literal>True</literal> when successful.</paragraph> + <tip id="par_id751638383457321">Read the <link href="https://wiki.openoffice.org/wiki/API/Tutorials/PDF_export" name="PDFExport_Wiki">PDF Export wiki page</link> to learn more about all available options.</tip> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id701626811351011"> + <input>session.SetPDFExportOptions(pdfoptions: obj): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771582816585233"><emph>pdfoptions</emph>: <literal>Dictionary</literal> object that defines the PDF export settings to be changed. Each key-value pair represents an export option and the value that will be set in the dialog.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id141638386087986">The following example changes the maximum image resolution to 150 dpi and exports the current document as a PDF file.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id501638385904841">Dim newSettings As Object, oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681638465060402">Set oDoc = CreateScriptService("Document")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411638385905025">Set newSettings = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421638386212072">newSettings.Add("ReduceImageResolution", True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801638385905201">newSettings.Add("MaxImageResolution", 150)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141638385905345">session.SetPDFExportOptions(newSettings)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id381638465110336">oDoc.ExportAsPDF("C:\Documents\myFile.pdf", Overwrite := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#Basic_Only"/> +</section> + +<section id="UnoMethods"> + <comment> UnoMethods --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id701587478024358"> + <bookmark_value>Session service;UnoMethods</bookmark_value> + </bookmark> + <h2 id="hd_id861587478024365" localize="false">UnoMethods</h2> + <paragraph role="paragraph" id="par_id321587478024997">Returns a list of the methods callable from an UNO object. The list is a zero-based array of strings and may be empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id341626819941177"> + <input>session.UnoMethods(unoobject: uno): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id251587478024311"><emph>unoobject</emph>: The object to inspect.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531587478024129">Dim svc : svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931587478024509">Dim methods : methods = session.UnoMethods(svc)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211587478024770">Dim msg as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631626820375428">For Each m in methods</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101626820375677"> msg = msg & m & Chr(13)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151626820375931">Next m</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741626820376195">MsgBox msg</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id501626820431003">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991626820431395">a = bas.createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id81626820431651">methods = session.UnoMethods(a)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281626820432068">msg = "\n".join(methods)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id281626820432763">bas.MsgBox(msg)</paragraph> + </pycode> +</section> + +<section id="UnoProperties"> + <comment> UnoProperties ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id57158747834361"> + <bookmark_value>Session service;UnoProperties</bookmark_value> + </bookmark> + <h2 id="hd_id101587478343870" localize="false">UnoProperties</h2> + <paragraph role="paragraph" id="par_id141587478343306">Returns a list of the properties of an UNO object. The list is a zero-based array of strings and may be empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="bas_id91626820631150"> + <input>session.UnoProperties(unoobject: uno): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id241587478343323"><emph>unoobject</emph>: The object to inspect.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id281587478343944">Dim svc As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581587478343738">svc = CreateUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101587478343422">MsgBox SF_Array.Contains(session.UnoProperties(svc), "Wildcards") ' True</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821626820748621">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id861626820749053">svc = bas.createUnoService("com.sun.star.sheet.FunctionAccess")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671626821449697">properties = session.UnoProperties(a)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id991626821450160">b = "Wildcards" in properties</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id371626820749214">bas.MsgBox(str(b)) # True</paragraph> + </pycode> +</section> + +<section id="UnoObjectType"> + <comment> UnoObjectType ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id221582820251346"> + <bookmark_value>Session service;UnoObjectType</bookmark_value> + </bookmark> + <h2 id="hd_id751582820251347" localize="false">UnoObjectType</h2> + <paragraph role="paragraph" id="par_id371582820251347">Identify the type of a UNO object as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id121626821532107"> + <input>session.UnoObjectType(unoobject: uno): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id921582820251349"><emph>unoobject</emph>: The object to identify.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id771582820251350">Dim svc As Variant, txt As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id721582820680948">svc = CreateUnoService("com.sun.star.system.SystemShellExecute")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571582820689968">txt = session.UnoObjectType(svc) ' "com.sun.star.comp.system.SystemShellExecute"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821582820696697">svc = CreateUnoStruct("com.sun.star.beans.Property")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id315828202513519">txt = session.UnoObjectType(svc) ' "com.sun.star.beans.Property"</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id501626821620216">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id501626821626352">svc = bas.createUnoService("com.sun.star.system.SystemShellExecute")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131626821626637">txt = session.UnoObjectType(svc) # "com.sun.star.comp.system.SystemShellExecute"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771626821626792">svc = bas.createUnoService("com.sun.star.beans.Property")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251626821626944">txt = session.UnoObjectType(svc) # "com.sun.star.beans.Property"</paragraph> + </pycode> +</section> + +<section id="WebService"> + <comment> WebService ---------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id561582821057372"> + <bookmark_value>Session service;WebService</bookmark_value> + </bookmark> + <h2 id="hd_id101582821057372" localize="false">WebService</h2> + <paragraph role="paragraph" id="par_id341582821057373">Get some web content from a URI.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id941626821793360"> + <input>session.WebService(uri: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id771582821057374"><emph>uri</emph>: URI address of the web service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id901582821057375">session.WebService("wiki.documentfoundation.org/api.php?" _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id421582821057375"> & "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id691626821991398">session.WebService(("wiki.documentfoundation.org/api.php?" </paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671626821991593"> "hidebots=1&days=7&limit=50&action=feedrecentchanges&feedformat=rss"))</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + +<section id="relatedtopics"> + <embed href="text/sbasic/shared/03104200.xhp#Array_h1"/> + <embed href="text/sbasic/shared/calc_functions.xhp#CallingCalcFunctionsh1"/> + <embed href="text/sbasic/guide/basic_2_python.xhp#basic2python"/> + <embed href="text/sbasic/shared/03/sf_basic.xhp#BasicService"/> + <embed href="text/sbasic/shared/03/sf_filesystem.xhp#FileSystemService"/> +</section> + +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_string.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_string.xhp new file mode 100644 index 000000000..2ca692c21 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_string.xhp @@ -0,0 +1,1501 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_String" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.String service (SF_String)</title> + <filename>/text/sbasic/shared/03/sf_string.xhp</filename> + </topic> +</meta> + +<body> +<section id="ScriptForge-sf_string"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id151579602147056"> + <bookmark_value>String service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id521580038927003"><variable id="StringService"><link href="text/sbasic/shared/03/sf_string.xhp" name="String service"><literal>ScriptForge</literal>.<literal>String</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id351579602570526">The <literal>String</literal> service provides a collection of methods for string processing. These methods can be used to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id611611952070366" role="listitem">Validate the contents of strings</paragraph> + </listitem> + <listitem> + <paragraph id="par_id611611952070376" role="listitem">Format strings by trimming, justifying or wrapping their contents</paragraph> + </listitem> + <listitem> + <paragraph id="par_id611611952070367" role="listitem">Use regular expressions to search and replace substrings</paragraph> + </listitem> + <listitem> + <paragraph id="par_id611611952070368" role="listitem">Apply hash algorithms on strings, etc.</paragraph> + </listitem> + </list> +</section> + + <h2 id="hd_id961579603699855">Definitions</h2> + + <h3 id="hd_id441579603838777">Line breaks</h3> + <paragraph role="paragraph" id="par_id791611946942340">The <literal>String</literal> service recognizes the following line breaks:</paragraph> + <table id="tab_id411611947117831"> + <tablerow> + <tablecell> + <paragraph id="par_id151611947117831" role="tablehead">Symbolic name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721611947117831" role="tablehead">ASCII number</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611947117831" role="tablecontent"> + Line feed<br/> + Vertical tab<br/> + Carriage return<br/> + Line feed + Carriage return<br/> + File separator<br/> + Group separator<br/> + Record separator<br/> + Next line<br/> + Line separator<br/> + Paragraph separator + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211611947117831" role="tablecontent" localize="false"> + 10 <br/> 12 <br/> 13 <br/> 10 + 13 <br/> 28 <br/> 29 <br/> 30 <br/> 133 <br/> 8232 <br/> 8233 + </paragraph> + </tablecell> + </tablerow> + </table> + + <h3 id="hd_id161579604225813">Whitespaces</h3> + <paragraph role="paragraph" id="par_id401611948279056">The <literal>String</literal> service recognizes the following whitespaces:</paragraph> + <table id="tab_id411611947117831"> + <tablerow> + <tablecell> + <paragraph id="par_id151611947117893" role="tablehead">Symbolic name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721611947117855" role="tablehead">ASCII number</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611947117835" role="tablecontent"> + Space<br/> + Horizontal tab<br/> + Line feed<br/> + Vertical tab<br/> + Form feed<br/> + Carriage return<br/> + Next line<br/> + No-break space<br/> + Line separator<br/> + Paragraph separator + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211611947117832" role="tablecontent" localize="false"> + 32 <br/> 9 <br/> 10 <br/> 11 <br/> 12 <br/> 13 <br/> 133 <br/> 160 <br/> 8232 <br/> 8233 + </paragraph> + </tablecell> + </tablerow> + </table> + + <h3 id="hd_id191580480825160">Escape sequences</h3> + <paragraph role="paragraph" id="par_id971611949145057">Below is a list of escape sequences that can be used in strings.</paragraph> + <table id="tab_id411611947117834"> + <tablerow> + <tablecell> + <paragraph id="par_id151611947117287" role="tablehead">Escape Sequence</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721611947117732" role="tablehead">Symbolic name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id721611947117144" role="tablehead">ASCII number</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771611948706049" role="tablecontent" localize="false"> + \n <br/> \r <br/> \t + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611947119834" role="tablecontent"> + Line feed<br/> + Carriage return<br/> + Horizontal tab + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211611947117163" role="tablecontent" localize="false"> + 10 <br/> 13 <br/> 9 + </paragraph> + </tablecell> + </tablerow> + </table> + <tip id="par_id251611949474763">To have the escape sequence "\n" interpreted as an actual string, simply use "\\n" instead of <literal>"\" & Chr(10).</literal></tip> + + <h3 id="hd_id771579606799550">Non-printable characters:</h3> + <paragraph role="paragraph" id="par_id531579606877342">Characters defined in the Unicode Character Database as “Other” or “Separator” are considered as non-printable characters.</paragraph> + <paragraph role="paragraph" id="par_id221611949584320">Control characters (ascii code <= 0x1F) are also considered as non-printable.</paragraph> + + <h3 id="hd_id661579604944268">Quotes inside strings:</h3> + <paragraph role="paragraph" id="par_id551579605035332">To add quotes in strings use \' (single quote) or \" (double quote). For example:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id201611949691285" role="listitem">The string <literal>[str\'i\'ng]</literal> is interpreted as <literal>[str'i'ng]</literal></paragraph> + </listitem> + <listitem> + <paragraph id="par_id201611949691323" role="listitem">The string <literal>[str\"i\"ng]</literal> is interpreted as <literal>[str"i"ng]</literal></paragraph> + </listitem> + </list> + + <h2 id="hd_id201586594659135">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>ScriptForge.String</literal> service the <literal>ScriptForge</literal> library needs to be loaded using:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id871608192694632">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id271627158844922">Loading the library will create the <literal>SF_String</literal> object that can be used to call the methods in the <literal>String</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id63158659509728">The following code snippets show the three ways to call methods from the <literal>String</literal> service (the <literal>Capitalize</literal> method is used as an example):</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id641627157912899">Dim s as String : s = "abc def"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181586594723543">s = SF_String.Capitalize(s) ' Abc Def</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id641627157912017">Dim s as String : s = "abc def"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441586594733346">Dim svc : svc = SF_String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id481586594739978">s = svc.Capitalize(s) ' Abc Def</paragraph> + </bascode> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id641627157912647">Dim s as String : s = "abc def"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431586594750461">Dim svc : svc = CreateScriptService("String")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471586594758689">s = svc.Capitalize(s) ' Abc Def</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <paragraph role="paragraph" id="par_id761627158463235">The code snippet below illustrates how to invoke methods from the <literal>String</literal> service in Python scripts. The <literal>IsIPv4</literal> method is used as an example.</paragraph> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id171627158604379">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101627158604648">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id171627158604858">ip_address = '192.168.0.14'</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id551627158605138">svc.IsIPv4(ip_address) # True</paragraph> + </pycode> + + <h2 id="hd_id651584978211886">Properties</h2> + <paragraph role="paragraph" id="par_id241611950267068">The <literal>SF_String</literal> object provides the following properties for Basic scripts:</paragraph> + <table id="tab_id761584978211275"> + <tablerow> + <tablecell> + <paragraph id="par_id271584978211792" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id241584978211550" role="tablehead">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621584978211403" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id581584978715552" role="tablecontent" localize="false">sfCR</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id71584978715562" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581584978715701" role="tablecontent">Carriage return: Chr(13)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id91584978211231" role="tablecontent" localize="false">sfCRLF</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id211584978211383" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id691584978211774" role="tablecontent">Carriage return + Linefeed: Chr(13) & Chr(10)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id1001584978666440" role="tablecontent" localize="false">sfLF</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id671584978666689" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951584978666296" role="tablecontent">Linefeed: Chr(10)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id311584978666162" role="tablecontent" localize="false">sfNEWLINE</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421584978666327" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id901584978666158" role="tablecontent">Carriage return + Linefeed, which can be<br/>1) Chr(13) & Chr(10) or + <br/>2) Linefeed: Chr(10) + <br/>depending on the operating system.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id371584978666469" role="tablecontent" localize="false">sfTAB</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541584978666991" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741584978666508" role="tablecontent">Horizontal tabulation: Chr(9)</paragraph> + </tablecell> + </tablerow> + </table> + <tip id="par_id461584978880380">You can use the properties above to identify or insert the corresponding characters inside strings. For example, the Linefeed can be replaced by <literal>SF_String.sfLF</literal>.</tip> + +<table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the String Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_string.xhp#Capitalize" name="Capitalize method">Capitalize</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Count" name="Count method">Count</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#EndsWith" name="EndsWith method">EndsWith</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Escape" name="Escape method">Escape</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#ExpandTabs" name="ExpandTabs method">ExpandTabs</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#FilterNotPrintable" name="FilterNotPrintable method">FilterNotPrintable</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#FindRegex" name="FindRegex method">FindRegex</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#HashStr" name="HashStr method">HashStr</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#HtmlEncode" name="HtmlEncode method">HtmlEncode</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsADate" name="IsADate method">IsADate</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsAlpha" name="IsAlpha method">IsAlpha</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsAlphaNum" name="IsAlphaNum method">IsAlphaNum</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsAscii" name="IsAscii method">IsAscii</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsDigit" name="IsDigit method">IsDigit</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsEmail" name="IsEmail method">IsEmail</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_string.xhp#IsFileName" name="IsFileName method">IsFileName</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsHexDigit" name="IsHexDigit method">IsHexDigit</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsIBAN" name="IsIBAN method">IsIBAN</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsIPv4" name="IsIPv4 method">IsIPv4</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsLike" name="IsLike method">IsLike</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsLower" name="IsLower method">IsLower</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsPrintable" name="IsPrintable method">IsPrintable</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsRegex" name="IsRegex method">IsRegex</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsSheetName" name="IsSheetName method">IsSheetName</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsTitle" name="IsTitle method">IsTitle</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsUpper" name="IsUpper method">IsUpper</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsUrl" name="IsUrl method">IsUrl</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#IsWhitespace" name="IsWhitespace method">IsWhitespace</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#JustifyCenter" name="JustifyCenter method">JustifyCenter</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#JustifyLeft" name="JustifyLeft method">JustifyLeft</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_string.xhp#JustifyRight" name="JustifyRight method">JustifyRight</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Quote" name="Quote method">Quote</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#ReplaceChar" name="ReplaceChar method">ReplaceChar</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#ReplaceRegex" name="ReplaceRegex method">ReplaceRegex</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#ReplaceStr" name="ReplaceStr method">ReplaceStr</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Represent" name="Represent method">Represent</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Reverse" name="Reverse method">Reverse</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#SplitLines" name="SplitLines method">SplitLines</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#SplitNotQuoted" name="SplitNotQuoted method">SplitNotQuoted</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#StartsWith" name="StartsWith method">StartsWith</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#TrimExt" name="TrimExt method">TrimExt</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Unescape" name="Unescape method">Unescape</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Unquote" name="Unquote method">Unquote</link><br/> + <link href="text/sbasic/shared/03/sf_string.xhp#Wrap" name="Wrap method">Wrap</link><br/><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + <note id="par_id151611951803163">The first argument of most methods is the string to be considered. It is always passed by reference and left unchanged. Methods such as <literal>Capitalize</literal>, <literal>Escape</literal>, etc return a new string after their execution.</note> + <warning id="par_id371627158142730">Because Python has comprehensive built-in string support, most of the methods in the <literal>String</literal> service are available for Basic scripts only. The methods available for Basic and Python are: <literal>HashStr</literal>, <literal>IsADate</literal>, <literal>IsEmail</literal>, <literal>IsFileName</literal>, <literal>IsIBAN</literal>, <literal>IsIPv4</literal>, <literal>IsLike</literal>, <literal>IsSheetName</literal>, <literal>IsUrl</literal>, <literal>SplitNotQuoted</literal> and <literal>Wrap</literal>.</warning> + +<section id="Capitalize"> + <comment> Capitalize -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id121582203710297"> + <bookmark_value>String service;Capitalize</bookmark_value> + </bookmark> + <h2 id="hd_id791579683635979" localize="false">Capitalize</h2> + <paragraph role="paragraph" id="par_id271579683706571">Capitalizes the first character from each word in the input string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id121627158901416"> + <input>svc.Capitalize(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id941582304592013"><emph>inputstr</emph>: The string to be capitalized.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id631579688532444">Dim sName as String : sName = "john smith"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id451579686015963">Dim sCapitalizedName as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41579785318230">sCapitalizedName = SF_String.Capitalize(sName)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801579688542131">MsgBox sCapitalizedName 'John Smith</paragraph> + </bascode> +</section> + +<section id="Count"> + <comment> Count ------------------------------------------------------------------------------------------------- </comment> + <bookmark branch="index" id="bm_id421582384432626" localize="false"> + <bookmark_value>String service;Count</bookmark_value> + </bookmark> + <h2 id="hd_id1001582384527265" localize="false">Count</h2> + <paragraph role="paragraph" id="par_id891582384556756">Counts the number of occurrences of a substring or a regular expression within a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id421627159083108"> + <input>svc.Count(inputstr: str, substring: str, [isregex: bool], [casesensitive: bool]): int</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id571582384689863"><emph>inputstr</emph>: The input string to be examined</paragraph> + <paragraph role="paragraph" id="par_id601582384696486"><emph>substring</emph>: The substring or the regular expression to be used during search</paragraph> + <paragraph role="paragraph" id="par_id451582384703719"><emph>isregex</emph>: Use <literal>True</literal> if the substring is a regular expression (Default = <literal>False</literal>)</paragraph> + <paragraph role="paragraph" id="par_id141582384726168"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id371582384749769">'Counts the occurrences of the substring "or" inside the input string (returns 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281582384809689">MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)</paragraph> + <paragraph role="bascode" id="bas_id561582384801586">'Counts the number of words with only lowercase letters (returns 7)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631582384780777">MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)</paragraph> + </bascode> + <tip id="par_id131612223767126">To learn more about regular expressions, refer to the Python's documentation on <link href="https://docs.python.org/3/library/re.html" name="Regular expressions">Regular Expression Operations</link>.</tip> +</section> + +<section id="EndsWith"> + <comment> EndsWith ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id771582203795803"> + <bookmark_value>String service;EndsWith</bookmark_value> + </bookmark> + <h2 id="hd_id801579687630238" localize="false">EndsWith</h2> + <paragraph role="paragraph" id="par_id581579687739629">Returns <literal>True</literal> if a string ends with a specified substring.</paragraph> + <paragraph role="paragraph" id="par_id21612306392239">The function returns <literal>False</literal> when either the string or the substring have a length = 0 or when the substring is longer than the string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id551627159333520"> + <input>svc.EndsWith(inputstr: str, substring: str, [casesensitive: bool]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id191579861552201"><emph>inputstr</emph>: The string to be tested.</paragraph> + <paragraph role="paragraph" id="par_id211579861561473"><emph>substring</emph>: The substring to be searched at the end of <literal>inputstr</literal>.</paragraph> + <paragraph role="paragraph" id="par_id801579861574009"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id811579862998452">'Returns True because the method was called with the default CaseSensitive = False</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581579863063364">MsgBox SF_String.EndsWith("abcdefg", "EFG")</paragraph> + <paragraph role="bascode" id="bas_id231579863168747">'Returns False due to the CaseSensitive parameter</paragraph> + <paragraph role="bascode" localize="false" id="bas_id221579863071644">MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)</paragraph> + </bascode> +</section> + +<section id="Escape"> + <comment> Escape ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id731585921441446"> + <bookmark_value>String service;Escape</bookmark_value> + </bookmark> + <h2 id="hd_id821585921441213" localize="false">Escape</h2> + <paragraph role="paragraph" id="par_id921585921441429">Converts linebreaks and tabs contained in the input string to their equivalent escaped sequence (\\, \n, \r, \t).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id151627159520587"> + <input>svc.Escape(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id9158592144110"><emph>inputstr</emph>: The string to be converted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id901585921441483">'Returns the string "abc\n\tdef\\n"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741585921441977">MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")</paragraph> + </bascode> +</section> + +<section id="ExpandTabs"> + <comment> ExpandTabs -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id161582203880251"> + <bookmark_value>String service;ExpandTabs</bookmark_value> + </bookmark> + <h2 id="hd_id761579868039113" localize="false">ExpandTabs</h2> + <paragraph role="paragraph" id="par_id271579868053137">Replaces Tab characters <literal>Chr(9)</literal> by space characters to replicate the behavior of tab stops.</paragraph> + <paragraph role="paragraph" id="par_id951579868064344">If a line break is found, a new line is started and the character counter is reset.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id821627159598950"> + <input>svc.ExpandTabs(inputstr: str, [tabsize: int]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id231579868290408"><emph>inputstr</emph>: The string to be expanded</paragraph> + <paragraph role="paragraph" id="par_id281579868299807"><emph>tabsize</emph>: This parameter is used to determine the Tab stops using the formula: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Default = 8)</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id611579868690878">Dim myText as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931585922081615">myText = "100" & SF_String.sfTAB & "200" & SF_String.sfTAB & "300" & SF_String.sfNEWLINE & _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311579868703742"> "X" & SF_String.sfTAB & "Y" & SF_String.sfTAB & "Z"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841585921966229">MsgBox SF_String.ExpandTabs(myText)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461579868714135">'100 200 300</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461579868714136">'X Y Z</paragraph> + </bascode> +</section> + +<section id="FilterNotPrintable"> + <comment> FilterNotPrintable ------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id231582204001536"> + <bookmark_value>String service;FilterNotPrintable</bookmark_value> + </bookmark> + <h2 id="hd_id581579874537114" localize="false">FilterNotPrintable</h2> + <paragraph role="paragraph" id="par_id161579874552729">Replaces all non-printable characters in the input string by a given character.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id271627159754299"> + <input>svc.FilterNotPrintable(inputstr: str, [replacedby: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id431579874633865"><emph>inputstr</emph>: The string to be searched</paragraph> + <paragraph role="paragraph" id="par_id31579874656437"><emph>replacedby</emph>: Zero, one or more characters that will replace all non-printable characters in <literal>inputstr</literal> (Default = "")</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id481579874686887">Dim LF : LF = Chr(10)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id41579874696422">Dim myText as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611579874737551">myText = "àén ΣlPµ" & LF & " Русский" & "\n"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271579874750894">MsgBox SF_String.FilterNotPrintable(myText)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81612308364024">' "àén ΣlPµ Русский\n"</paragraph> + </bascode> +</section> + +<section id="FindRegex"> + <comment> FindRegex --------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id491582204303825"> + <bookmark_value>String service;FindRegex</bookmark_value> + </bookmark> + <h2 id="hd_id471579876212449" localize="false">FindRegex</h2> + <paragraph role="paragraph" id="par_id1001579876228707">Finds in a string a substring matching a given regular expression.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591627159907982"> + <input>svc.FindRegex(inputstr: str, regex: str, [start: int], [casesensitive: bool], [forward: bool]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id131579876314120"><emph>inputstr</emph>: The string to be searched</paragraph> + <paragraph role="paragraph" id="par_id751579876371545"><emph>regex</emph>: The regular expression</paragraph> + <paragraph role="paragraph" id="par_id881579876394584"><emph>start</emph>: The position in the string where the search will begin. This parameter is passed by reference, so after execution the value of <literal>start</literal> will point to the first character of the found substring. If no matching substring is found, <literal>start</literal> will be set to 0.</paragraph> + <paragraph role="paragraph" id="par_id251579876403831"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <paragraph role="paragraph" id="par_id841579876412287"><emph>forward</emph>: Determines the direction of the search. If <literal>True</literal>, search moves forward. If <literal>False</literal> search moves backwards (Default = <literal>True</literal>)</paragraph> + <paragraph role="paragraph" id="par_id451612309155653">At the first iteration, if <literal>forward = True</literal>, then <literal>start</literal> should be equal to 1, whereas if <literal>forward = False</literal> then <literal>start</literal> should be equal to <literal>Len(inputstr)</literal></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id621579876463377">Dim lStart As Long : lStart = 1</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001579876429088">Dim result as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571579876474344">result = SF_String.FindRegex("abCcdefghHij", "C.*H", lStart, CaseSensitive := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671579876511592">MsgBox lStart & ": " & result</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51579876497768">'3: CcdefghH</paragraph> + </bascode> + <tip id="par_id221612309579001">In the example above, the new value of <literal>lStart</literal> can be used to keep searching the same input string by setting the <literal>Start</literal> parameter to <literal>lStart + Len(result)</literal> at the next iteration.</tip> +</section> + +<section id="HashStr"> + <comment> HashStr ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id24160104898372"> + <bookmark_value>String service;HashStr</bookmark_value> + </bookmark> + <h2 id="hd_id871601048983883" localize="false">HashStr</h2> + <paragraph role="paragraph" id="par_id471601048983628">Hash functions are used inside some cryptographic algorithms, in digital signatures, message authentication codes, manipulation detection, fingerprints, checksums (message integrity check), hash tables, password storage and much more.</paragraph> + <paragraph role="paragraph" id="par_id301601048983765">The <literal>HashStr</literal> method returns the result of a hash function applied on a given string and using a specified algorithm, as a string of lowercase hexadecimal digits.</paragraph> + <paragraph role="paragraph" id="par_id631601048983149">The hash algorithms supported are: <literal>MD5</literal>, <literal>SHA1</literal>, <literal>SHA224</literal>, <literal>SHA256</literal>, <literal>SHA384</literal> and <literal>SHA512</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id741627160211210"> + <input>svc.HashStr(inputstr: str, algorithm: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id621601048983210"><emph>inputstr</emph>: The string to hash. It is presumed to be encoded in UTF-8. The hashing algorithm will consider the string as a stream of bytes.</paragraph> + <paragraph role="paragraph" id="par_id941601048983822"><emph>algorithm</emph>: One of the supported algorithms listed above, passed as a string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id721601048983555">MsgBox SF_String.HashStr("œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬", "MD5")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891612351766467">' c740ccc2e201df4b2e2b4aa086f35d8a</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id201627248048720">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101627248049176">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id401627248049343">a_string = "œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id611627248049495">hash_value = svc.HashStr(a_string, "MD5")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id471627248049687">bas.MsgBox(hash_value)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121627248049991"># c740ccc2e201df4b2e2b4aa086f35d8a</paragraph> + </pycode> +</section> + +<section id="HtmlEncode"> + <comment> HtmlEncode -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id561582204334292"> + <bookmark_value>String service;HtmlEncode</bookmark_value> + </bookmark> + <h2 id="hd_id771579879504956" localize="false">HtmlEncode</h2> + <paragraph role="paragraph" id="par_id221579879516929">Encodes the input string into the HTML character codes, replacing special characters by their <literal>&</literal> counterparts.</paragraph> + <paragraph role="paragraph" id="par_id341612351999692">For example, the character <literal>é</literal> would be replaced by <literal>&eacute;</literal> or an equivalent numerical HTML code.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id601627160353326"> + <input>svc.HtmlEncode(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="bas_id501579879570781"><emph>inputstr</emph>: The string to encode.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671579879597547">MsgBox SF_String.HtmlEncode("<a href=""https://a.b.com"">From α to ω</a>")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461579879607044">' "&lt;a href=&quot;https://a.b.com&quot;&gt;From &#945; to &#969;&lt;/a&gt;"</paragraph> + </bascode> +</section> + +<section id="IsADate"> + <comment> IsADate ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id11582204732653"> + <bookmark_value>String service;IsADate</bookmark_value> + </bookmark> + <h2 id="hd_id141579880967392" localize="false">IsADate</h2> + <paragraph role="paragraph" id="par_id171579880990533">Returns <literal>True</literal> if the input string is a valid date according to a specified date format.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id191627160586821"> + <input>svc.IsADate(inputstr: str, [dateformat: str]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id151579881091821"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal></paragraph> + <paragraph role="paragraph" id="par_id991579881107670"><emph>dateformat</emph>: The date format, as a string. It can be either "YYYY-MM-DD" (default), "DD-MM-YYYY" or "MM-DD-YYYY"</paragraph> + <paragraph role="paragraph" id="par_id291579881117126">The dash (-) may be replaced by a dot (.), a slash (/) or a space.</paragraph> + <paragraph role="paragraph" id="par_id51579881125801"> If the format is invalid, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id811579881155015">MsgBox SF_String.IsADate("2020-12-31", "YYYY-MM-DD") ' True</paragraph> + </bascode> + <note id="par_id211612370427721">This method checks the format of the input string without performing any calendar-specific checks. Hence it does not test the input string for leap years or months with 30 or 31 days. For that, refer to the <link href="text/sbasic/shared/03102300.xhp" name="IsDate function"><literal>IsDate</literal> built-in function</link>.</note> + <paragraph role="paragraph" id="par_id181612371147364">The example below shows the difference between the methods <literal>IsADate</literal> (ScriptForge) and the <literal>IsDate</literal> (built-in) function.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id531612371248704">Dim myDate as String : myDate = "2020-02-30"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731612371253577">MsgBox SF_String.IsADate(myDate, "YYYY-MM-DD") 'True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821612371254969">MsgBox IsDate(myDate) ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627248497889">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id121627248498619">s_date = "2020-12-31"</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id621627248498786">result = svc.IsADate(s_date) # True</paragraph> + </pycode> +</section> + +<section id="IsAlpha"> + <comment> IsAlpha ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id491582204781995"> + <bookmark_value>String service;IsAlpha</bookmark_value> + </bookmark> + <h2 id="hd_id231579881589037" localize="false">IsAlpha</h2> + <paragraph role="paragraph" id="par_id161579881600317">Returns <literal>True</literal> if all characters in the string are alphabetic.</paragraph> + <paragraph role="paragraph" id="par_id251579881615469">Alphabetic characters are those characters defined in the <link href="https://unicode.org/reports/tr44/" name="Unicode documentation">Unicode Character Database</link> as <literal>Letter</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711627160772668"> + <input>svc.IsAlpha(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id11579881691826"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="par_id381579881735058">MsgBox SF_String.IsAlpha("àénΣlPµ") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331579881743363">MsgBox SF_String.IsAlpha("myVar3") ' False</paragraph> + </bascode> +</section> + +<section id="IsAlphaNum"> + <comment> IsAlphaNum -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id581582204814414"> + <bookmark_value>String service;IsAlphanum</bookmark_value> + </bookmark> + <h2 id="hd_id711579883155335" localize="false">IsAlphaNum</h2> + <paragraph role="paragraph" id="par_id421579883181382">Returns <literal>True</literal> if all characters in the string are alphabetic, digits or "_" (underscore). The first character must not be a digit.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id981627160850954"> + <input>svc.IsAlphaNum(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id31579884464101"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id611579884379482">MsgBox SF_String.IsAlphaNum("_ABC_123456_abcàénΣlPµ") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id551612445915119">MsgBox SF_String.IsAlphaNum("123ABC") ' False</paragraph> + </bascode> +</section> + +<section id="IsAscii"> + <comment> IsAscii ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id991582204833033"> + <bookmark_value>String service;IsAscii</bookmark_value> + </bookmark> + <h2 id="hd_id891580039448798" localize="false">IsAscii</h2> + <paragraph role="paragraph" id="par_id671580039484786">Returns <literal>True</literal> if all characters in the string are Ascii characters.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id931627160994922"> + <input>svc.IsAscii(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id791580039528838"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41580039556401">MsgBox SF_String.IsAscii("a%?,25") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841580039565265">MsgBox SF_String.IsAscii("abcàénΣlPµ") ' False</paragraph> + </bascode> +</section> + +<section id="IsDigit"> + <comment> IsDigit ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id741582204858557"> + <bookmark_value>String service;IsDigit</bookmark_value> + </bookmark> + <h2 id="hd_id321580044756464" localize="false">IsDigit</h2> + <paragraph role="paragraph" id="par_id861580044805749">Returns <literal>True</literal> if all characters in the string are digits.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id491627161075258"> + <input>svc.IsDigit(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id41580044873043"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id821580044929100">MsgBox SF_String.IsDigit("123456") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601580044939971">MsgBox SF_String.IsDigit("_12a") ' False</paragraph> + </bascode> +</section> + +<section id="IsEmail"> + <comment> IsEmail ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id721582204903245"> + <bookmark_value>String service;IsEmail</bookmark_value> + </bookmark> + <h2 id="hd_id601580045208963" localize="false">IsEmail</h2> + <paragraph role="paragraph" id="par_id521580045221758">Returns <literal>True</literal> if the string is a valid email address.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id561627161153727"> + <input>svc.IsEmail(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id841580045280071"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id351580045300802">MsgBox SF_String.IsEmail("first.last@something.org") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511580045308668">MsgBox SF_String.IsEmail("first.last@something.com.br") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621580045319466">MsgBox SF_String.IsEmail("first.last@something.123") ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id921627248625925">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671627248629820">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651627248630083">bas.MsgBox(svc.IsEmail("first.last@something.org")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id451627248630275">bas.MsgBox(svc.IsEmail("first.last@something.com.br")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id491627248630514">bas.MsgBox(svc.IsEmail("first.last@something.123")) # False</paragraph> + </pycode> +</section> + +<section id="IsFileName"> + <comment> IsFileName -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id601582204928759"> + <bookmark_value>String service;IsFileName</bookmark_value> + </bookmark> + <h2 id="hd_id941580047025136" localize="false">IsFileName</h2> + <paragraph role="paragraph" id="par_id41580047039666">Returns <literal>True</literal> if the string is a valid filename in a given operating system.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id521627161235397"> + <input>svc.IsFileName(inputstr: str, [osname: str]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id801580047079938"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id781580047088954"><emph>osname</emph>: The operating system name, as a string. It can be "WINDOWS", "LINUX", "MACOSX" or "SOLARIS".</paragraph> + <paragraph role="paragraph" id="par_id991612372824234">The default value is the current operating system on which the script is running.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id291580047101783">MsgBox SF_String.IsFileName("/home/user/Documents/a file name.odt", "LINUX") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id761580047111201">MsgBox SF_String.IsFileName("C:\home\a file name.odt", "LINUX") ' False</paragraph> + <paragraph role="bascode" localize="false" id="bas_id901580047128532">MsgBox SF_String.IsFileName("C:\home\a file name.odt", "WINDOWS") ' True</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id921627248625144">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id671627248629099">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id651627248630165">bas.MsgBox(svc.IsFileName("/home/user/Documents/a file name.odt", "LINUX")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id451627248630094">bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "LINUX")) # False</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id491627248630255">bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "WINDOWS")) # True</paragraph> + </pycode> +</section> + +<section id="IsHexDigit"> + <comment> IsHexDigit ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id1001582204955266"> + <bookmark_value>String service;IsHexDigit</bookmark_value> + </bookmark> + <h2 id="hd_id441580047541078" localize="false">IsHexDigit</h2> + <paragraph role="paragraph" id="par_id911580047551929">Returns <literal>True</literal> if all characters in the string are hexadecimal digits.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id141627161371952"> + <input>svc.IsHexDigit(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id331580047594144"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id521612377109554">The hexadecimal digits may be prefixed with "0x" or "&H".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id51580047615488">MsgBox SF_String.IsHexDigit("&H00FF") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id251580047624832">MsgBox SF_String.IsHexDigit("08AAFF10") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281580047636521">MsgBox SF_String.IsHexDigit("0x18LA22") ' False</paragraph> + </bascode> +</section> + +<section id="IsIBAN"> + <comment> IsIBAN ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id931582204907784"> + <bookmark_value>String service;IsIBAN</bookmark_value> + </bookmark> + <h2 id="hd_id431580840408317" localize="false">IsIBAN</h2> + <paragraph role="paragraph" id="par_id791584008420941">Returns <literal>True</literal> if the string is a valid International Bank Account Number (IBAN). The comparison is not case-sensitive.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id291627161741207"> + <input>svc.IsIBAN(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id951880048466565"> <emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functvalue"/> + <paragraph role="paragraph" id="par_id631619526542367"><literal>True</literal> if the string contains a valid IBAN number.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id71627249022958">' Basic</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571500848484444">MsgBox SF_String.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") ' True</paragraph> + </bascode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id121627249045568"># Python</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id901627249045753">result = svc.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") # True</paragraph> + </pycode> +</section> + +<section id="IsIPv4"> + <comment> IsIPv4 ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id931582204977084"> + <bookmark_value>String service;IsIPv4</bookmark_value> + </bookmark> + <h2 id="hd_id431580048408317" localize="false">IsIPv4</h2> + <paragraph role="paragraph" id="par_id791580048420941">Returns <literal>True</literal> if the string is a valid IP(v4) address.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id861627161817305"> + <input>svc.IsIPv4(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id981580048466565"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id571580048484444">MsgBox SF_String.IsIPv4("192.168.1.50") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871580048493061">MsgBox SF_String.IsIPv4("192.168.50") ' False</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201580048501038">MsgBox SF_String.IsIPv4("255.255.255.256") ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627249268171">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981627249268449">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871627249268596">bas.MsgBox(svc.IsIPv4("192.168.1.50")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211627249268763">bas.MsgBox(svc.IsIPv4("192.168.50")) # False</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571627249268932">bas.MsgBox(svc.IsIPv4("255.255.255.256")) # False</paragraph> + </pycode> +</section> + +<section id="IsLike"> + <comment> IsLike ------------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id721582205008767"> + <bookmark_value>String service;IsLike</bookmark_value> + </bookmark> + <h2 id="hd_id791580049073672" localize="false">IsLike</h2> + <paragraph role="paragraph" id="par_id831580049093038">Returns <literal>True</literal> if the whole input string matches a given pattern containing wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id951627161917563"> + <input>svc.IsLike(inputstr: str, pattern: str, [casesensitive: bool]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id141580049142548"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id31580049154551"><emph>pattern</emph>: The pattern as a string. Wildcards are:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id181612441703306" role="listitem">"?" represents any single character;</paragraph> + </listitem> + <listitem> + <paragraph role="paragraph" id="par_id861612377611438">"*" represents zero, one, or multiple characters.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id991580049206617"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id541580049238484">MsgBox SF_String.IsLike("aAbB", "?A*") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821580049249434">MsgBox SF_String.IsLike("C:\a\b\c\f.odb", "?:*.*") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981580049258743">MsgBox SF_String.IsLike("name:host", "?*@?*") ' False</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821612378053774">MsgBox SF_String.IsLike("@host", "?*@?*") ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627249268227">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981627249268238">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871627249268903">bas.MsgBox(svc.IsLike("aAbB", "?A*")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211627249268144">bas.MsgBox(svc.IsLike(r"C:\a\b\c\f.odb", "?:*.*")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id571627249268752">bas.MsgBox(svc.IsLike("name:host", "?*@?*")) # False</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661627249433231">bas.MsgBox(svc.IsLike("@host", "?*@?*")) # False</paragraph> + </pycode> +</section> + +<section id="IsLower"> + <comment> IsLower ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id91582205043650"> + <bookmark_value>String service;IsLower</bookmark_value> + </bookmark> + <h2 id="hd_id621580050021403" localize="false">IsLower</h2> + <paragraph role="paragraph" id="par_id581580050048679">Returns <literal>True</literal> if all characters in the string are in lowercase. Non-alphabetic characters are ignored.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id901627162072714"> + <input>svc.IsLower(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id751580050122938"><emph>InputStr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id731580050158022">MsgBox SF_String.IsLower("abc'(-xy4z") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881580050187982">MsgBox SF_String.IsLower("1234") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id741580050198046">MsgBox SF_String.IsLower("abcDefg") ' False</paragraph> + </bascode> +</section> + +<section id="IsPrintable"> + <comment> IsPrintable ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id71582205064134"> + <bookmark_value>String service;IsPrintable</bookmark_value> + </bookmark> + <h2 id="hd_id51580051636185" localize="false">IsPrintable</h2> + <paragraph role="paragraph" id="par_id231580051650488">Returns <literal>True</literal> if all characters in the string are printable.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id581627162139952"> + <input>svc.IsPrintable(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id721580051706431"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id341580051737598">MsgBox SF_String.IsPrintable("àén ΣlPµ Русский") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791580051747813">MsgBox SF_String.IsPrintable("First line." & Chr(10) & "Second Line.") ' False</paragraph> + </bascode> +</section> + +<section id="IsRegex"> + <comment> IsRegex ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id561582205088656"> + <bookmark_value>String service;IsRegex</bookmark_value> + </bookmark> + <h2 id="hd_id11580052383614" localize="false">IsRegex</h2> + <paragraph role="paragraph" id="par_id281580052400960">Returns <literal>True</literal> if the whole input string matches a given regular expression.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id581627162222687"> + <input>svc.IsRegex(inputstr: str, regex: str, [casesensitive: bool]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id161580052454770"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id581580052467973"><emph>regex</emph>: The regular expression. If empty, the method returns <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id621580052654341"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id711580052523722">MsgBox SF_String.IsRegex("aAbB", "[A-Za-z]+") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431580052508625">MsgBox SF_String.IsRegex("John;100", "[A-Za-z]+;[0-9]+") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71580052534405">MsgBox SF_String.IsRegex("John;100;150", "[A-Za-z]+;[0-9]+") ' False</paragraph> + </bascode> +</section> + +<section id="IsSheetName"> + <comment> IsSheetName ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id901589460240654"> + <bookmark_value>String service;IsSheetName</bookmark_value> + </bookmark> + <h2 id="hd_id791589460240472" localize="false">IsSheetName</h2> + <paragraph role="paragraph" id="par_id1001589460240467">Returns <literal>True</literal> if the input string is a valid Calc sheet name.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id171627162339798"> + <input>svc.IsSheetName(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id671589460240552"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id391589460240928">MsgBox SF_String.IsSheetName("1àbc + ""déf""") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681589460240214">MsgBox SF_String.IsSheetName("[MySheet]") ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627249268323">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981627249268455">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871627249268018">bas.MsgBox(svc.IsSheetName("1àbc + ""déf""")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211627249268278">bas.MsgBox(svc.IsSheetName("[MySheet]")) # False</paragraph> + </pycode> + <note id="par_id551612442002823">A sheet name must not contain the characters [ ] * ? : / \ or the character ' (apostrophe) as first or last character.</note> +</section> + +<section id="IsTitle"> + <comment> IsTitle ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id461582205108468"> + <bookmark_value>String service;IsTitle</bookmark_value> + </bookmark> + <h2 id="hd_id571580293080317" localize="false">IsTitle</h2> + <paragraph role="paragraph" id="par_id371580293093655">Returns <literal>True</literal> if the first character of every word is in uppercase and the other characters are in lowercase.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id741627162408971"> + <input>svc.IsTitle(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id471580293142283"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id701580293163557">MsgBox SF_String.IsTitle("This Is The Title Of My Book") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371580293175037">MsgBox SF_String.IsTitle("This is the Title of my Book") ' False</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001580293184622">MsgBox SF_String.IsTitle("Result Number 100") ' True</paragraph> + </bascode> +</section> + +<section id="IsUpper"> + <comment> IsUpper ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id31582205124227"> + <bookmark_value>String service;IsUpper</bookmark_value> + </bookmark> + <h2 id="hd_id341580128661190" localize="false">IsUpper</h2> + <paragraph role="paragraph" id="par_id801580128672004">Returns <literal>True</literal> if all characters in the string are in uppercase. Non alphabetic characters are ignored.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id271627162484974"> + <input>svc.IsUpper(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id391580128736809"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id81580128769670">MsgBox SF_String.IsUpper("ABC'(-XYZ") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951580128785698">MsgBox SF_String.IsUpper("A Title") ' False</paragraph> + </bascode> +</section> + +<section id="IsUrl"> + <comment> IsUrl ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id431582205169135"> + <bookmark_value>String service;IsUrl</bookmark_value> + </bookmark> + <h2 id="hd_id211580132006615" localize="false">IsUrl</h2> + <paragraph role="paragraph" id="par_id531580132067813">Returns <literal>True</literal> if the string is a valid absolute URL (Uniform Resource Locator) address. Only the http, https and ftp protocols are supported.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id301627162561225"> + <input>svc.IsUrl(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id321580132113593"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id41580132143630">MsgBox SF_String.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811580132160302">MsgBox SF_String.IsUrl("www.somesite.org") ' False</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627249268852">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981627249268254">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871627249268007">bas.MsgBox(svc.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff")) # True</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211627249268997">bas.MsgBox(svc.IsUrl("www.somesite.org")) # False</paragraph> + </pycode> +</section> + +<section id="IsWhitespace"> + <comment> IsWhitespace ----------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id551582205196046"> + <bookmark_value>String service;IsWhitespace</bookmark_value> + </bookmark> + <h2 id="hd_id401580132462319" localize="false">IsWhitespace</h2> + <paragraph role="paragraph" id="par_id41580132491698">Returns <literal>True</literal> if all characters in the string are whitespaces</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id981627162624424"> + <input>svc.IsWhitespace(inputstr: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id801580132535511"><emph>inputstr</emph>: The string to be checked. If empty, the method returns <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id71580132555742">MsgBox SF_String.IsWhitespace(" ") ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191580132564154">MsgBox SF_String.IsWhitespace(" " & Chr(9) & Chr(10)) ' True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531580132571745">MsgBox SF_String.IsWhitespace("") ' False</paragraph> + </bascode> +</section> + +<section id="JustifyCenter"> + <comment> JustifyCenter ----------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id421582205214600"> + <bookmark_value>String service;JustifyCenter</bookmark_value> + </bookmark> + <h2 id="hd_id291580133287288" localize="false">JustifyCenter</h2> + <paragraph role="paragraph" id="par_id891580133307100">Returns the input string center-justified.</paragraph> + <paragraph role="paragraph" id="par_id571612380829021">The leading and trailing white spaces are stripped and the remaining characters are completed left and right up to a specified total <literal>length</literal> with the character <literal>padding</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id911627162696565"> + <input>svc.JustifyCenter(inputstr: str, [length: int], [padding: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id911580133391827"><emph>inputstr</emph>: The string to be center-justified. If empty, the method returns an empty string.</paragraph> + <paragraph role="paragraph" id="par_id671580133694946"><emph>length</emph>: The length of the resulting string (default = the length of the input string).</paragraph> + <paragraph role="paragraph" id="par_id511612381090109">If the specified length is shorter than the center-justified input string, then the returned string is truncated.</paragraph> + <paragraph role="paragraph" id="par_id101580133705268"><emph>padding</emph>: The single character to be used as padding (default = the Ascii space " ").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id121580133437963">MsgBox SF_String.JustifyCenter("Title", Length := 11) ' " Title "</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701580133452083">MsgBox SF_String.JustifyCenter(" ABCDEF", Padding := "_") ' "__ABCDEF__"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841580133480737">MsgBox SF_String.JustifyCenter("A Long Title", Length := 5) ' "ong T"</paragraph> + </bascode> +</section> + +<section id="JustifyLeft"> + <comment> JustifyLeft ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id351582205243403"> + <bookmark_value>String service;JustifyLeft</bookmark_value> + </bookmark> + <h2 id="hd_id51580135447561" localize="false">JustifyLeft</h2> + <paragraph role="paragraph" id="par_id911580135466348">Returns the input string left-justified.</paragraph> + <paragraph role="paragraph" id="par_id431612381917641">The leading white spaces are stripped and the remaining characters are completed to the right up to a specified total <literal>length</literal> with the character <literal>padding</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id551627162821330"> + <input>svc.JustifyLeft(inputstr: str, [length: int], [padding: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id281580135523448"><emph>inputstr</emph>: The string to be left-justified. If empty, the method returns an empty string.</paragraph> + <paragraph role="paragraph" id="par_id431580135534910"><emph>length</emph>: The length of the resulting string (default = the length of the input string).</paragraph> + <paragraph role="paragraph" id="par_id161612381664182">If the specified length is shorter than the left-justified input string, then the returned string is truncated.</paragraph> + <paragraph role="paragraph" id="par_id221580135568475"><emph>padding</emph>: The single character to be used as padding (default = the Ascii space " ").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id611580135592267">MsgBox SF_String.JustifyLeft("Title", Length := 10) ' "Title "</paragraph> + <paragraph role="bascode" localize="false" id="bas_id131580135610150">MsgBox SF_String.JustifyLeft(" ABCDEF", Padding := "_") ' "ABCDEF____"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441580135619176">MsgBox SF_String.JustifyLeft("A Long Title", Length := 5) ' "A Lon"</paragraph> + </bascode> +</section> + +<section id="JustifyRight"> + <comment> JustifyRight ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id401582205265380"> + <bookmark_value>String service;JustifyRight</bookmark_value> + </bookmark> + <h2 id="hd_id651580136079149" localize="false">JustifyRight</h2> + <paragraph role="paragraph" id="par_id821580136091225">Returns the input string right-justified.</paragraph> + <paragraph role="paragraph" id="par_id771612382000293">The leading white spaces are stripped and the remaining characters are completed to the left up to a specified total <literal>length</literal> with the character <literal>padding</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id161627162950390"> + <input>svc.JustifyRight(inputstr: str, [length: int], [padding: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id201580136154170"><emph>inputstr</emph>: The string to be right-justified. If empty, the method returns an empty string.</paragraph> + <paragraph role="paragraph" id="par_id71580136164632"><emph>length</emph>: The length of the resulting string (default = the length of the input string).</paragraph> + <paragraph role="paragraph" id="par_id191612381732163">If the specified length is shorter than the right-justified input string, then the returned string is truncated.</paragraph> + <paragraph role="paragraph" id="par_id751580136200680"><emph>padding</emph>: The single character to be used as padding (default = the Ascii space " ").</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id791580136219992">MsgBox SF_String.JustifyRight("Title", Length := 10) ' " Title"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id751580136242414">MsgBox SF_String.JustifyRight(" ABCDEF ", Padding := "_") ' "____ABCDEF"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861580136253164">MsgBox SF_String.JustifyRight("A Long Title", Length := 5) ' "Title"</paragraph> + </bascode> +</section> + +<section id="Quote"> + <comment> Quote ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id241582205281048"> + <bookmark_value>String service;Quote</bookmark_value> + </bookmark> + <h2 id="hd_id741580136875363" localize="false">Quote</h2> + <paragraph role="paragraph" id="par_id251580136888958">Returns the input string enclosed in single or double quotes. Existing quotes are left unchanged, including leading and/or trailing quotes.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id321627163052678"> + <input>svc.Quote(inputstr: str, [quotechar: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id811580136944674"><emph>inputstr</emph>: The string to quote.</paragraph> + <paragraph role="paragraph" id="par_id581599129397412"><emph>quotechar</emph>: Either the single (') or double (") quote (default).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id171580136967087">MsgBox SF_String.Quote("Text Value")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331612442671018">' "Text Value"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291580136977341">MsgBox SF_String.Quote("Book Title: ""The Arabian Nights""", "'")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id111612442632444">' 'Book Title: "The Arabian Nights"'</paragraph> + </bascode> + <tip id="par_id911612382537087">This method can be useful while preparing a string field to be stored in a csv-like file, which requires that text values be enclosed with single or double quotes.</tip> +</section> + +<section id="ReplaceChar"> + <comment> ReplaceChar ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id971582205313633"> + <bookmark_value>String service;ReplaceChar</bookmark_value> + </bookmark> + <h2 id="hd_id171580139110167" localize="false">ReplaceChar</h2> + <paragraph role="paragraph" id="par_id951580139124650">Replaces all occurrences of the characters specified in the <literal>Before</literal> parameter by the corresponding characters specified in <literal>After</literal>.</paragraph> + <paragraph role="paragraph" id="par_id1001612384040018">If the length of <literal>Before</literal> is greater than the length of <literal>After</literal>, the residual characters in <literal>Before</literal> are replaced by the last character in <literal>After</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id191627163199236"> + <input>svc.ReplaceChar(inputstr: str, before: str, after: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id11580139160633"><emph>inputstr</emph>: The input string on which replacements will occur.</paragraph> + <paragraph role="paragraph" id="par_id111580139169795"><emph>before</emph>: A string with the characters that will be searched in the input string for replacement.</paragraph> + <paragraph role="paragraph" id="par_id851580139182113"><emph>after</emph>: A string with the new characters that will replace those defined in <literal>before</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" id="bas_id921580139218457">' Replaces accented characters</paragraph> + <paragraph role="bascode" localize="false" id="bas_id281580139228929">MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361612384219658">' "Protegez votre vie privee"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201580139288120">MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401612443219105">' "Protgez votre vie prive"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661580139301417">MsgBox SF_String.ReplaceChar("àâãçèéêëîïôöûüýÿ", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621612443248643">' "aaaceeeeiioouuyy"</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id151612442904499">The <literal>SF_String</literal> service provides useful public constants for the Latin character sets, as shown in the example below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id621580139272513">MsgBox SF_String.ReplaceChar("Protégez votre vie privée", SF_String.CHARSWITHACCENT, SF_String.CHARSWITHOUTACCENT)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id551612443170894">' "Protegez votre vie privee"</paragraph> + </bascode> +</section> + +<section id="ReplaceRegex"> + <comment> ReplaceRegex ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id541582205335970"> + <bookmark_value>String service;ReplaceRegex</bookmark_value> + </bookmark> + <h2 id="hd_id491580140260181" localize="false">ReplaceRegex</h2> + <paragraph role="paragraph" id="par_id671580140272818">Replaces all occurrences of a given regular expression by a new string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id21627163307092"> + <input>svc.ReplaceRegex(inputstr: str, regex: str, newstr: str, [casesensitive: bool]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id471580140311626"><emph>inputstr</emph>: The input string on which replacements will occur.</paragraph> + <paragraph role="paragraph" id="par_id651580140322666"><emph>regex</emph>: The regular expression.</paragraph> + <paragraph role="paragraph" id="par_id891580140334754"><emph>newstr</emph>: The replacing string.</paragraph> + <paragraph role="paragraph" id="par_id581580140345221"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id151580140386767">MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "[a-z]", "x", CaseSensitive := True)</paragraph> + <paragraph role="bascode" id="bas_id961612384647003">' "Lxxxx xxxxx xxxxx xxx xxxx, xxxxxxxxxxx xxxxxxxxxx xxxx." (each lowercase letter is replaced by "x")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11580140400163">MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", "x", CaseSensitive := False)</paragraph> + <paragraph role="bascode" id="bas_id751612384623936">' "x x x x x, x x x." (each word is replaced by "x")</paragraph> + </bascode> +</section> + +<section id="ReplaceStr"> + <comment> ReplaceStr -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id751582205356816"> + <bookmark_value>String service;ReplaceStr</bookmark_value> + </bookmark> + <h2 id="hd_id701580146458127" localize="false">ReplaceStr</h2> + <paragraph role="paragraph" id="par_id51580146471894">Replaces in a string some or all occurrences of an array of strings by an array of new strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id521627163432097"> + <input>svc.ReplaceStr(inputstr: str, oldstr: str, newstr: str, [occurrences: int], [casesensitive: bool]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id831580146504326"><emph>inputstr</emph>: The input string on which replacements will occur.</paragraph> + <paragraph role="paragraph" id="par_id411580146514927"><emph>oldstr</emph>: A single string or an array of strings. Zero-length strings are ignored.</paragraph> + <paragraph role="paragraph" id="par_id591580146532966"><emph>newstr</emph>: The replacing string or the array of replacing strings.</paragraph> + <paragraph role="paragraph" id="par_id611612384873347">If <literal>oldstr</literal> is an array, each occurrence of any of the items in <literal>oldstr</literal> is replaced by <literal>newstr</literal>.</paragraph> + <paragraph role="paragraph" id="par_id611612384880820">If <literal>oldstr</literal> and <literal>newstr</literal> are arrays, replacements occur one by one up to the <literal>UBound(newstr)</literal>.</paragraph> + <paragraph role="paragraph" id="par_id241612385058264">If <literal>oldstr</literal> has more entries than <literal>newstr</literal>, then the residual elements in <literal>oldstr</literal> are replaced by the last element in <literal>newstr</literal>.</paragraph> + <paragraph role="paragraph" id="par_id701580146547619"><emph>occurrences</emph>: The maximum number of replacements. The default value is 0, meaning that all occurrences will be replaced.</paragraph> + <paragraph role="paragraph" id="par_id741612385380533">When <literal>oldstr</literal> is an array, the <literal>occurrence</literal> parameter is computed separately for each item in the array.</paragraph> + <paragraph role="paragraph" id="par_id301580146556599"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id481580146574037">MsgBox SF_String.ReplaceStr("100 xxx 200 yyy", Array("xxx", "yyy"), Array("(1)", "(2)"), CaseSensitive := False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511612385563994">' "100 (1) 200 (2)"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151580146611738">MsgBox SF_String.ReplaceStr("abCcdefghHij", Array("c", "h"), Array("Y", "Z"), CaseSensitive := False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491612385543543">' "abYYdefgZZij"</paragraph> + </bascode> +</section> + +<section id="Represent"> + <comment> Represent --------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id151582205374090"> + <bookmark_value>String service;Represent</bookmark_value> + </bookmark> + <h2 id="hd_id581580147543150" localize="false">Represent</h2> + <paragraph role="paragraph" id="par_id901580147558931">Returns a string with a readable representation of the argument, truncated at a given length. This is useful mainly for debugging or logging purposes.</paragraph> + <paragraph role="paragraph" id="par_id11612386054691">If the <literal>anyvalue</literal> parameter is an object, it will be enclosed with square brackets "[" and "]".</paragraph> + <paragraph role="paragraph" id="par_id491612386081802">In strings, tabs and line breaks are replaced by \t, \n or \r.</paragraph> + <paragraph role="paragraph" id="par_id921612386089103">If the final length exceeds the <literal>maxlength</literal> parameter, the latter part of the string is replaced by " ... (N)" where N is the total length of the original string before truncation.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id711627163695452"> + <input>svc.Represent(anyvalue: any, [maxlength: int]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id91580147593626"><emph>anyvalue</emph>: The input value to be represented. It can be any value, such as a string, an array, a Basic object, a UNO object, etc.</paragraph> + <paragraph role="paragraph" id="par_id811580147609322"><emph>maxlength</emph>: The maximum length of the resulting string. The default value is 0, meaning there is no limit to the length of the resulting representation.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id931580147637178">MsgBox SF_String.Represent("this is a usual string") ' "this is a usual string"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701580147646290">MsgBox SF_String.Represent("this is a usual string", 15) ' "this i ... (22)"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001580147656762">MsgBox SF_String.Represent("this is a" & Chr(10) & " 2-lines string") ' "this is a\n 2-lines string"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661580147668170">MsgBox SF_String.Represent(Empty) ' "[EMPTY]"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id941580147685721">MsgBox SF_String.Represent(Null) ' "[NULL]"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531580147702074">MsgBox SF_String.Represent(Pi) ' "3.142"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461580147719545">MsgBox SF_String.Represent(CreateUnoService("com.sun.star.util.PathSettings")) ' "[com.sun.star.comp.framework.PathSettings]"</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id641612386659292">Note that the representation of data types such as Arrays and <literal>ScriptForge.Dictionary</literal> object instances include both the data type and their values:</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id971612386906463">' An example with a Basic built-in Array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401580147734722">MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id311612386778843">' "[ARRAY] (0:2) (1, 2, Text\there)"</paragraph> + <paragraph role="bascode" id="bas_id401612386876329">' An example with a ScriptForge Array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621612386824731">Dim aValues as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id771612386825586">aValues = SF_Array.RangeInit(1, 5)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841612386825825">MsgBox SF_String.Represent(aValues)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121612386864144">' "[ARRAY] (0:4) (1.0, 2.0, 3.0, 4.0, 5.0)"</paragraph> + <paragraph role="bascode" id="bas_id551612386931680">' An example with a ScriptForge Dictionary</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951580147750109">Dim myDict As Variant : myDict = CreateScriptService("Dictionary")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701580147765158">myDict.Add("A", 1) : myDict.Add("B", 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921580147782281">MsgBox SF_String.Represent(myDict)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911612386800415">' "[Dictionary] ("A":1, "B":2)"</paragraph> + </bascode> +</section> + +<section id="Reverse"> + <comment> Reverse ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id111582205394632"> + <bookmark_value>String service;Reverse</bookmark_value> + </bookmark> + <h2 id="hd_id781580312915849" localize="false">Reverse</h2> + <paragraph role="paragraph" id="par_id411580312925741">Returns the input string in reversed order.</paragraph> + <paragraph role="paragraph" id="par_id141612387177873">This method is equivalent to the built-in <link href="text/sbasic/shared/03120412.xhp" name="StrReverse function"><literal>StrReverse</literal> Basic function</link>.</paragraph> + <note id="par_id961612387463144">To use the <literal>StrReverse</literal> function, the statement <literal>Option VBASupport 1</literal> must be present in the module.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id951627163820097"> + <input>svc.Reverse(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id241580312964497"><emph>inputstr</emph>: The string to be reversed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671580313005541">MsgBox SF_String.Reverse("abcdefghij") ' "jihgfedcba"</paragraph> + </bascode> +</section> + +<section id="SplitLines"> + <comment> SplitLines -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id681582205412371"> + <bookmark_value>String service;SplitLines</bookmark_value> + </bookmark> + <h2 id="hd_id111580210751549" localize="false">SplitLines</h2> + <paragraph role="paragraph" id="par_id721580210762286">Returns a zero-based array of strings with the lines in the input string. Each item in the array is obtained by splitting the input string at newline characters.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id491627163897526"> + <input>svc.SplitLines(inputstr: str, [keepbreaks: int]): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481580210806878"><emph>inputstr</emph>: The string to be split.</paragraph> + <paragraph role="paragraph" id="par_id231580210820309"><emph>keepbreaks</emph>: When <literal>True</literal>, line breaks are preserved in the output array (default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id301580210850100">Dim a as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561580210860646">a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661612387860556">' a = Array("Line1", "Line2", "Line3")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791580210888116">a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10))</paragraph> + <paragraph role="bascode" localize="false" id="bas_id701612387837745">' a = Array("Line1", "Line2", "Line3", "")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id451580210958405">a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10), KeepBreaks := True)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591612387824058">' a = Array("Line1\n", "Line2\r", "Line3\n", "")</paragraph> + </bascode> +</section> + +<section id="SplitNotQuoted"> + <comment> SplitNotQuoted ---------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id531582205451718"> + <bookmark_value>String service;SplitNotQuoted</bookmark_value> + </bookmark> + <h2 id="hd_id131580211748939" localize="false">SplitNotQuoted</h2> + <paragraph role="paragraph" id="par_id471580211762739">Splits a string into an array of elements using a specified delimiter.</paragraph> + <paragraph role="paragraph" id="par_id281612388034501">If a quoted substring contains a delimiter, it is ignored. This is useful when parsing CSV-like records that contain quoted strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id261627164043199"> + <input>svc.SplitNotQuoted(inputstr: str, [delimiter: str], [occurrences: int], [quotechar: str]): str[0..*]</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id881580211809490"><emph>inputstr</emph>: The string to be split.</paragraph> + <paragraph role="paragraph" id="par_id811580211821162"><emph>delimiter</emph>: A string of one or more characters that will be used as delimiter. The default delimiter is the Ascii space " " character.</paragraph> + <paragraph role="paragraph" id="par_id181580211833778"><emph>occurrences</emph>: The maximum number of substrings to return. The default value is 0, meaning that there is no limit to the number of returned strings.</paragraph> + <paragraph role="paragraph" id="par_id421599123777334"><emph>quotechar</emph>: Either the single (') or double (") quote.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id511580211876156">arr1 = SF_String.SplitNotQuoted("abc def ghi")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581580211857403">' arr1 = Array("abc", "def", "ghi")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711580211886107">arr2 = SF_String.SplitNotQuoted("abc,""def,ghi""", ",")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id111580211865432">' arr2 = Array("abc", """def,ghi""")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101580211896350">arr3 = SF_String.SplitNotQuoted("abc,""def\"",ghi""", ",")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id351612388312049"> ' arr3 = Array("abc", """def\"",ghi""")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591580211905379">arr4 = SF_String.SplitNotQuoted("abc,""def\"",ghi"""",", ",")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691580211914228">' arr4 = Array("abc", """def\"",ghi""", "")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id831627249262582">svc = CreateScriptService("String")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981627249260364">arr1 = svc.SplitNotQuoted('abc def ghi')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871627249262177"># arr1 = ('abc', 'def', 'ghi')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id211627249269827">arr2 = svc.SplitNotQuoted('abc,"def,ghi"', ",")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id11627251280871"># arr2 = ('abc', '"def,ghi"')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681627251281232">arr3 = svc.SplitNotQuoted(r'abc,"def\",ghi"', ",")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id291627251281439"># arr3 = ('abc', '"def\\",ghi"')</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id81627251281671">arr4 = svc.SplitNotQuoted(r'abc,"def\",ghi"",', ",")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id601627251281871"># arr4 = ('abc', '"def\\",ghi""', '')</paragraph> + </pycode> + <note id="par_id661627251379676">Beware of the differences between Basic and Python when representing strings. For example, in Basic two "" characters inside a string are interpreted as a single " character. In Python, strings enclosed with single quotes can contain " characters without having to double them.</note> +</section> + +<section id="StartsWith"> + <comment> StartsWith -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id521582205468821"> + <bookmark_value>String service;StartsWith</bookmark_value> + </bookmark> + <h2 id="hd_id121580212826111" localize="false">StartsWith</h2> + <paragraph role="paragraph" id="par_id771580212837884">Returns <literal>True</literal> if the first characters of a string are identical to a given substring.</paragraph> + <paragraph role="paragraph" id="par_id781612393174350">This method returns <literal>False</literal> if either the input string or the substring have a length = 0 or when the substring is longer than the input string.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id211627164196721"> + <input>svc.StartsWith(inputstr: str, substring: str, [casesensitive: bool]): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id271580212876135"><emph>inputstr</emph>: The string to be tested.</paragraph> + <paragraph role="paragraph" id="par_id571580212889462"><emph>substring</emph>: The substring to be searched at the start of <literal>inputstr</literal>.</paragraph> + <paragraph role="paragraph" id="par_id811580212900799"><emph>casesensitive</emph>: The search can be case sensitive or not (Default = <literal>False</literal>).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id581580212931342">MsgBox SF_String.StartsWith("abcdefg", "ABC") 'True</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491580212940539">MsgBox SF_String.StartsWith("abcdefg", "ABC", CaseSensitive := True) 'False</paragraph> + </bascode> +</section> + +<section id="TrimExt"> + <comment> TrimExt ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id461582205488207"> + <bookmark_value>String service;TrimExt</bookmark_value> + </bookmark> + <h2 id="hd_id191580295988498" localize="false">TrimExt</h2> + <paragraph role="paragraph" id="par_id911580295999690">Returns the input string without its leading and trailing whitespaces.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id241627164299510"> + <input>svc.TrimExt(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id541580296044377"><emph>inputstr</emph>: The string to trim.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id231580296079929">MsgBox SF_String.TrimExt(" Some text. ") ' "Some text."</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871580296091857">MsgBox SF_String.TrimExt(" ABCDEF" & Chr(9) & Chr(10) & Chr(13) & " ") ' "ABCDEF"</paragraph> + </bascode> +</section> + +<section id="Unescape"> + <comment> Unescape ---------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id651582205521725"> + <bookmark_value>String service;Unescape</bookmark_value> + </bookmark> + <h2 id="hd_id831580483080098" localize="false">Unescape</h2> + <paragraph role="paragraph" id="par_id61580483096936">Converts any escaped sequence (\\, \n, \r, \t) in the input string to their corresponding Ascii character.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id51627164365699"> + <input>svc.Unescape(inputstr: str): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id971580483124743"><emph>inputstr</emph>: The string to be converted.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id601580483196328">MsgBox SF_String.Unescape("abc\n\tdef\\n")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261580483205906">' "abc" & Chr(10) & Chr(9) & "def\n"</paragraph> + </bascode> +</section> + +<section id="Unquote"> + <comment> Unquote ----------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id471582205541341"> + <bookmark_value>String service;Unquote</bookmark_value> + </bookmark> + <h2 id="hd_id481580213622428" localize="false">Unquote</h2> + <paragraph role="paragraph" id="par_id831580213634029">Removes the single or double quotes enclosing the input string.</paragraph> + <paragraph role="paragraph" id="par_id811612393585600">This is useful when parsing CSV-like records that contain quoted strings.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id391627164432930"> + <input>svc.Unquote(inputstr: str, [quotechar: str]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id761580213677493"><emph>inputstr</emph>: The string to unquote.</paragraph> + <paragraph role="paragraph" id="par_id211599129509890"><emph>quotechar</emph>: Either the single (') or double (") quote (default).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371580213703732">Dim s as String</paragraph> + <paragraph role="bascode" id="bas_id371580213702598">' s = "Some text" (without enclosing quotes)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981580213799125">s = SF_String.Unquote("""Some text""")</paragraph> + <paragraph role="bascode" id="bas_id51580213693694">' The string below does not have enclosing quotes, so it remains unchanged</paragraph> + <paragraph role="bascode" id="bas_id961612393917830">' s = "Some text" (unchanged)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961612393917927">s = SF_String.Unquote("Some text")</paragraph> + <paragraph role="bascode" id="bas_id461612394182689">' Quotes inside the string are not removed</paragraph> + <paragraph role="bascode" id="bas_id961612394171208">' s = "The ""true"" meaning" (unchanged)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961612394171186">s = SF_String.Unquote("The ""true"" meaning")</paragraph> + </bascode> +</section> + +<section id="Wrap"> + <comment> Wrap ------------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id321585834468367"> + <bookmark_value>String service;Wrap</bookmark_value> + </bookmark> + <h2 id="hd_id911585834468456" localize="false">Wrap</h2> + <paragraph role="paragraph" id="par_id871585834468102">Converts the input string into an array of substrings so that each item in the array has at most a given number of characters.</paragraph> + <paragraph role="paragraph" id="par_id21612394465120">In practice, this method returns a zero-based array of output lines, without newlines at the end, except for the pre-existing line-breaks.</paragraph> + <paragraph role="paragraph" id="par_id601612395193333">Tabs are expanded using the same procedure performed by the <link href="text/sbasic/shared/03/sf_string.xhp#ExpandTabs" name="ExpandTabs method">ExpandTabs</link> method.</paragraph> + <paragraph role="paragraph" id="par_id641612394826616"> Symbolic line breaks are replaced by their equivalent Ascii characters.</paragraph> + <paragraph role="paragraph" id="par_id361612394859733">If the wrapped output has no content, the returned array is empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id41627164529595"> + <input>svc.Wrap(inputstr: str, [width: int], [tabsize: int]): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id251585834468498"><emph>inputstr</emph>: The string to wrap.</paragraph> + <paragraph role="paragraph" id="par_id351585834773177"><emph>width</emph>: The maximum number of characters in each line (Default = 70).</paragraph> + <paragraph role="paragraph" id="par_id741585834874500"><emph>tabsize</emph>: Before wrapping the text, the existing TAB <literal>Chr(9)</literal> characters are replaced with spaces. The argument <literal>tabsize</literal> defines the TAB stops at TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Default = 8).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id461585835162853">a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891585835170534">b = SF_String.Wrap(a, 20)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191585835179883">' Array("Neque porro ", "quisquam est qui ", "dolorem ipsum quia ", "dolor sit amet, ", "consectetur, ", "adipisci velit...")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id221627251731306">a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411627251731572">b = svc.Wrap(a, 20)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921627251731739"># ('Neque porro ', 'quisquam est qui ', 'dolorem ipsum quia ', 'dolor sit amet, ', 'consectetur, ', 'adipisci velit...')</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_array.xhp#ArrayService"/> + <embed href="text/sbasic/shared/03120202.xhp#String_h1"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_textstream.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_textstream.xhp new file mode 100644 index 000000000..7505f09c2 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_textstream.xhp @@ -0,0 +1,376 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_TextStream" indexer="include" status="PUBLISH"> + <title id="tit">ScriptForge.TextStream service</title> + <filename>/text/sbasic/shared/03/sf_textstream.xhp</filename> + </topic> + </meta> + +<body> + +<section id="ScriptForge-SF_TextStream"> + <bookmark localize="false" branch="index" id="bm_id50158533078781"> + <bookmark_value>TextStream service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="bm_id351585330787295"><variable id="TextStreamService"><link href="text/sbasic/shared/03/sf_textstream.xhp" name="TextStream service"><literal>ScriptForge</literal>.<literal>TextStream</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id511585330787205">The <literal>TextStream</literal> service is used to sequentially read from and write to files opened or created using the <literal>ScriptForge.FileSystem</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id41613596903894">The methods <literal>OpenTextFile</literal> and <literal>CreateTextFile</literal> from the <literal>FileSystem</literal> service return an instance of the <literal>TextStream</literal> service.</paragraph> +</section> + <paragraph role="paragraph" id="par_id161585330787262">Line delimiters may be specified by the user. In input operations CR, LF or CR+LF are supported. In output operations, the default line delimiter is the one used by the operating system.</paragraph> + <paragraph role="paragraph" id="par_id831613598137669">The line delimiter for the operating system where the macro is being executed can be accessed using the <literal>SF_String.sfNEWLINE</literal> property.</paragraph> + <note id="par_id851613597445432">All operations needed to read from or write to a file (open, read/write and close) are presumed to happen during the same macro run.</note> + + <h2 id="hd_id83158533078741">Service invocation</h2> + <paragraph role="paragraph" id="par_id351613598192725">The examples below in Basic and Python use the <literal>OpenTextFile</literal> method to create an instance of the <literal>TextStream</literal> Service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id77158533078783">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id971585330787275">Dim FSO As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11585330787585">FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891585330787374">Set myFile = FSO.OpenTextFile("C:\Temp\ThisFile.txt", FSO.ForReading)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id371585330787197">The file must be closed with the <literal>CloseFile</literal> method after all read or write operations have been executed:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id91613599192241">myFile.CloseFile()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id891582733781994">Optionally, the resources used by the <literal>TextStream</literal> instance can be released using the <literal>Dispose</literal> method:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id761613599333614">Set myFile = myFile.Dispose()</paragraph> + </bascode> + <note id="par_id121612917368946">The methods in the <literal>TextStream</literal> service are mostly based on the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1io_1_1XTextInputStream.html" name="XTextInputStream API"><literal>XTextInputStream</literal></link> and <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1io_1_1XTextOutputStream.html" name="XTextOutputStream API"><literal>XTextOutputStream</literal></link> UNO interfaces.</note> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id841626893320674">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id981626893320923">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id851626893321150">myFile = fs.OpenTextFile(r"C:\Temp\ThisFile.txt", fs.ForReading)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id131626893321309"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id231626893321491">myFile.CloseFile()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id871626893321683">myFile = myFile.Dispose()</paragraph> + </pycode> + + <h2 id="hd_id941585330787948">Properties</h2> + <bookmark branch="index" id="bm_id1001613600572485" localize="false"> + <bookmark_value>TextStream service;AtEndOfStream</bookmark_value> + <bookmark_value>TextStream service;Encoding</bookmark_value> + <bookmark_value>TextStream service;FileName</bookmark_value> + <bookmark_value>TextStream service;IOMode</bookmark_value> + <bookmark_value>TextStream service;Line</bookmark_value> + <bookmark_value>TextStream service;NewLine</bookmark_value> + </bookmark> + <table id="tab_id81585330787547"> + <tablerow> + <tablecell> + <paragraph id="par_id631585330787267" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401585330787370" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581585330787700" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id551585330787608" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941585330787832" role="tablecontent" localize="false">AtEndOfStream</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181585330787752" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id471585330787948" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id901585330787680" role="tablecontent">Used in read mode. A <literal>True</literal> value indicates that the end of the file has been reached. A test using this property should precede calls to the <literal>ReadLine</literal> method.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id501585330787895" role="tablecontent" localize="false">Encoding</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561585330787568" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731585330787673" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id741585330787777" role="tablecontent">The character set to be used. The default encoding is "UTF-8".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id361585330787241" role="tablecontent" localize="false">FileName</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id641585330787207" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id9158533078741" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id281585330787614" role="tablecontent">Returns the name of the current file either in URL format or in the native operating system's format, depending on the current value of the <literal>FileNaming</literal> property of the <literal>FileSystem</literal> service.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id451585330787745" role="tablecontent" localize="false">IOMode</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id111585330787410" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id981585330787716" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861585330787417" role="tablecontent">Indicates the input/output mode. Possible values are "READ", "WRITE" or "APPEND".</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721585330787688" role="tablecontent" localize="false">Line</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id87158533078795" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id601585330787171" role="tablecontent" localize="false">Long</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id561585330787741" role="tablecontent">Returns the number of lines read or written so far.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id12158533078767" role="tablecontent" localize="false">NewLine</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id531585330787157" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id9415853307876" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id691585330787279" role="tablecontent">Sets or returns the current delimiter to be inserted between two successive written lines. The default value is the native line delimiter in the current operating system.</paragraph> + </tablecell> + </tablerow> + </table> + <note id="par_id141613001281573">To learn more about the names of character sets, visit <link href="https://www.iana.org/assignments/character-sets/character-sets.xhtml" name="Character Sets">IANA's Character Set</link> page. Beware that %PRODUCTNAME does not implement all existing character sets.</note> +<table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead">List of Methods in the TextStream Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_textstream.xhp#CloseFile" name="CloseFile method">CloseFile</link><br/> + <link href="text/sbasic/shared/03/sf_textstream.xhp#ReadAll" name="ReadAll method">ReadAll</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_textstream.xhp#ReadLine" name="ReadLine method">ReadLine</link><br/> + <link href="text/sbasic/shared/03/sf_textstream.xhp#SkipLine" name="SkipLine method">SkipLine</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_textstream.xhp#WriteBlankLines" name="WriteBlankLines method">WriteBlankLines</link><br/> + <link href="text/sbasic/shared/03/sf_textstream.xhp#WriteLine" name="WriteLine method">WriteLine</link><br/> + </paragraph> + </tablecell> + </tablerow> +</table> + +<section id="CloseFile"> + <comment> CloseFile ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id21585330787288"> + <bookmark_value>TextStream service;CloseFile</bookmark_value> + </bookmark> + <h2 id="hd_id901585330787252" localize="false">CloseFile</h2> + <paragraph role="paragraph" id="par_id421585330787675">Closes the current input or output stream and empties the output buffer if relevant. Returns <literal>True</literal> if the file was successfully closed.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id971626891612501"> + <input>myFile.CloseFile(): bool</input> + </paragraph> +</section> + +<section id="ReadAll"> + <comment> ReadAll -------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id311585330787690"> + <bookmark_value>TextStream service;ReadAll</bookmark_value> + </bookmark> + <h2 id="hd_id311585330787335" localize="false">ReadAll</h2> + <paragraph role="paragraph" id="par_id65158533078799">Returns all the remaining lines in the text stream as a single string. Line breaks are not removed.</paragraph> + <paragraph role="paragraph" id="par_id71613600347125">The resulting string can be split in lines either by using the <literal>Split</literal> built-in Basic function if the line delimiter is known, or with the <literal>SF_String.SplitLines</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id91585330787373">For large files, using the <literal>ReadAll</literal> method wastes memory resources. In such cases it is recommended to read the file line by line using the <literal>ReadLine</literal> method.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id501626891694491"> + <input>myFile.ReadAll(): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id921613595637851">Consider the text file "Students.txt" with the following contents (a name in each line):</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id921613595638140">Herbie Peggy</paragraph> + <paragraph role="bascode" localize="false" id="bas_id61613595639028">Hardy Jarrett</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711613595639379">Edith Lorelle</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331613595639605">Roderick Rosamund</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641613595639909">Placid Everette</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id391613596019750">The examples below in Basic and Python use the <literal>ReadAll</literal> and <literal>SplitLines</literal> methods to read the contents of the file into an array of strings:</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" id="bas_id251613595640550">'Loads the FileSystem service</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931613595640789">Dim FSO : FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" id="bas_id181613595641087">'Opens the text file with the names to be read</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291613595641480">Dim inputFile as Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651613595641754">Set inputFile = FSO.OpenTextFile("/home/user/Documents/Students.txt")</paragraph> + <paragraph role="bascode" id="bas_id711613595642109">'Reads all the contents in the input file as a single string</paragraph> + <paragraph role="bascode" localize="false" id="bas_id81613595642474">Dim allData as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191613595642766">allData = inputFile.ReadAll()</paragraph> + <paragraph role="bascode" id="bas_id961613595643093">'Splits the string into an array</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51613595643398">Dim arrNames as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151613595643675">arrNames = SF_String.SplitLines(allData)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211613595928948">' (...)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31613600104976">inputFile.CloseFile()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id641626893916915">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id751626893917578">inputFile = fs.OpenTextFile("/home/user/Documents/Students.txt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id771626893917826">allData = inputFile.ReadAll()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951626893918067">arrNames = allData.split(inputFile.NewLine)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id391626893918273"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id241626893918515">inputFile.CloseFile()</paragraph> + </pycode> +</section> + +<section id="ReadLine"> + <comment> ReadLine ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id161585330787462"> + <bookmark_value>TextStream service;ReadLine</bookmark_value> + </bookmark> + <h2 id="hd_id111585330787998" localize="false">ReadLine</h2> + <paragraph role="paragraph" id="par_id871585330787885">Returns the next line in the text stream as a string. Line breaks are removed from the returned string.</paragraph> + <paragraph role="paragraph" id="par_id431613600221626">The <literal>AtEndOfStream</literal> test should precede the <literal>ReadLine</literal> method like in the example below.</paragraph> + <paragraph role="paragraph" id="par_id171585330787774">An error will be raised if the <literal>AtEndOfStream</literal> was reached during the previous <literal>ReadLine</literal> or <literal>SkipLine</literal> method call.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id431626892013564"> + <input>myFile.ReadLine(): str</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id321585330787499">Dim sLine As String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791585330787376">Do While Not myFile.AtEndOfStream</paragraph> + <paragraph role="bascode" localize="false" id="bas_id461585330787206"> sLine = myFile.ReadLine()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id521585330787673"> ' (...)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id715853307876">Loop</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21626894253022">while not myFile.AtEndOfStream:</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381626894253384"> sLine = myFile.ReadLine()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id931626894253567"> # ...</paragraph> + </pycode> +</section> + +<section id="SkipLine"> + <comment> SkipLine ------------------------------------------------------------------------------------------- </comment> + <bookmark localize="false" branch="index" id="bm_id381585330787551"> + <bookmark_value>TextStream service;SkipLine</bookmark_value> + </bookmark> + <h2 id="hd_id241585330787168" localize="false">SkipLine</h2> + <paragraph role="paragraph" id="par_id11585330787847">Skips the next line in the input stream when reading a <literal>TextStream</literal> file.</paragraph> + <paragraph role="paragraph" id="par_id441613600704766">This method can result in <literal>AtEndOfStream</literal> being set to <literal>True</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id41626892171105"> + <input>myFile.SkipLine()</input> + </paragraph> +</section> + +<section id="WriteBlankLines"> + <comment> WriteBlankLines ------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id61585330787548"> + <bookmark_value>TextStream service;WriteBlankLines</bookmark_value> + </bookmark> + <h2 id="hd_id241585330787109" localize="false">WriteBlankLines</h2> + <paragraph role="paragraph" id="par_id141585330787657">Writes a specified number of empty lines to the output stream.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id531626892281078"> + <input>myFile.WriteBlankLines(lines: int)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id291585330787357"><emph>lines</emph>: The number of empty lines to write to the file.</paragraph> +</section> + +<section id="WriteLine"> + <comment> WriteLine ------------------------------------------------------------------------------------------ </comment> + <bookmark localize="false" branch="index" id="bm_id371585330787255"> + <bookmark_value>TextStream service;WriteLine</bookmark_value> + </bookmark> + <h2 id="hd_id611585330787877" localize="false">WriteLine</h2> + <paragraph role="paragraph" id="par_id101585330787215">Writes the given string to the output stream as a single line.</paragraph> + <paragraph role="paragraph" id="par_id421613601002074">The character defined in the <literal>NewLine</literal> property is used as the line delimiter.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id791626892414752"> + <input>myFile.WriteLine(line: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id491585330787650"><emph>line</emph>: The line to write, may be empty.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id821626894480105">The examples below in Basic and Python create a text file in CSV format in which each line contains a value and its square until <literal>lastValue</literal> is reached.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id171613321461620">Sub SquaredValuesFile(lastValue as Integer)</paragraph> + <paragraph role="bascode" id="bas_id21613321528612"> 'Instantiates the FileSystem Service</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711613321529004"> Dim FSO as Variant : FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" id="bas_id191613321529277"> 'Creates a text file</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861613321529684"> Dim myFile as Variant : myFile = FSO.CreateTextFile("/home/user/Documents/squares.csv")</paragraph> + <paragraph role="bascode" id="bas_id641613321530181"> 'Writes the Value and Value squared, separated by ";"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331613321530548"> Dim value as Integer</paragraph> + <paragraph role="bascode" id="bas_id141613321530960"> myFile.WriteLine("Value;Value Squared")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id891613321531342"> For value = 1 To lastValue</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951613321531798"> myFile.WriteLine(value & ";" & value ^ 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621613321532215"> Next value</paragraph> + <paragraph role="bascode" id="bas_id881613321532598"> 'Closes the file and free resources</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671613321532919"> myFile.CloseFile()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51613321533150"> Set myFile = myFile.Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id861613321645821">End Sub</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id191626894577635">def squared_values_file(lastValue):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id71626894577912"> fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id681626894578108"> myFile = fs.CreateTextFile("/home/user/Documents/squares.csv")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411626894578332"> myFile.WriteLine("Value;Value Squared")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id541626894578572"> for value in range(1, lastValue + 1):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id551626894578859"> myFile.WriteLine("{};{}".format(value, value ** 2))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id711626894579141"> myFile.CloseFile()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251626894579421"> myFile = myFile.Dispose()</paragraph> + </pycode> +</section> + +<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> +<section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_filesystem.xhp#FileSystemService"/> + <embed href="text/sbasic/shared/03160000.xhp#Input_h1"/> + <embed href="text/sbasic/shared/03020103.xhp#Open_h1"/> +</section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_timer.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_timer.xhp new file mode 100644 index 000000000..b3c2ea2dd --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_timer.xhp @@ -0,0 +1,315 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_Timer" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.Timer service</title> + <filename>/text/sbasic/shared/03/sf_timer.xhp</filename> + </topic> +</meta> +<body> + +<section id="ScriptForge-sf_timer"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Timer service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="TimerService"><link href="text/sbasic/shared/03/sf_timer.xhp" name="ScriptForge.Timer service"><literal>ScriptForge</literal>.<literal>Timer</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id961582733781662" xml-lang="en-US">The <literal>Timer</literal> service measures the amount of time it takes to run user scripts.</paragraph> + <paragraph role="paragraph" id="par_id181582733781323" xml-lang="en-US">A <literal>Timer</literal> measures <emph>durations</emph>. It can be:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id711582733781252" role="listitem" xml-lang="en-US">Started, to indicate when to start measuring time.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id631582733781431" role="listitem" xml-lang="en-US">Suspended, to pause measuring running time.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id691582733781498" role="listitem" xml-lang="en-US">Resumed, to continue tracking running time after the Timer has been suspended.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id31582733781344" role="listitem" xml-lang="en-US">Restarted, which will cancel previous measurements and start the <literal>Timer</literal> at zero.</paragraph> + </listitem> + </list> +</section> + <paragraph role="tip" id="par_id991582733781280" xml-lang="en-US">Durations are expressed in seconds with a precision of 3 decimal digits (milliseconds). A duration value of 12.345 means 12 seconds and 345 milliseconds</paragraph> + + <h2 id="hd_id201582733781265" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Timer</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id891610734806133">The example below creates a <literal>Timer</literal> object named <literal>myTimer</literal> and starts it immediately.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id551610734764343">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11582733781672">Dim myTimer As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id31582733781292">myTimer = CreateScriptService("Timer", True)</paragraph> + <paragraph role="bascode" id="bas_id681582733781715">'The timer starts immediately when the second argument = True, default = False</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id891582733781994" xml-lang="en-US">It is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61582733781413">Set myTimer = myTimer.Dispose()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id351626871397672">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id851626871397921">myTimer = CreateScriptService("Timer", start = True)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id301626871398065"># ...</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661626871405884">myTimer = myTimer.Dispose()</paragraph> + </pycode> + + <h2 id="hd_id521582733781450" xml-lang="en-US">Properties</h2> + <table id="tab_id761582733781447"> + <tablerow> + <tablecell> + <paragraph id="par_id71582733781260" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711582733781103" role="tablehead" xml-lang="en-US">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id76158273378122" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id751582733781926" role="tablehead" xml-lang="en-US" >Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id561582733781781" role="tablecontent" xml-lang="en-US" localize="false">Duration</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id621582733781588" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id521582733781943" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id731582733781476" role="tablecontents" xml-lang="en-US" >The actual running time elapsed since start or between start and stop (does not consider suspended time)</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id181582733781163" role="tablecontent" xml-lang="en-US" localize="false">IsStarted</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301582733781498" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591582733781696" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id401582733781608" role="tablecontents" xml-lang="en-US" ><literal>True</literal> when timer is started or suspended</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id371582733781716" role="tablecontent" xml-lang="en-US" localize="false">IsSuspended</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id181582733781551" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411582733781116" role="tablecontent" xml-lang="en-US" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id161582733781328" role="tablecontents" xml-lang="en-US" ><literal>True</literal> when timer is started and suspended</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id691582733781260" role="tablecontent" xml-lang="en-US" localize="false">SuspendDuration</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651582733781874" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id581582733781213" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id171582733781456" role="tablecontents" xml-lang="en-US" >The actual time elapsed while suspended since start or between start and stop</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id411582733781943" role="tablecontent" xml-lang="en-US" localize="false">TotalDuration</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141582733781303" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id451582733781978" role="tablecontent" xml-lang="en-US" localize="false">Double</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id411582733781932" role="tablecontents" xml-lang="en-US" >The actual time elapsed since start or between start and stop (including suspensions and running time)</paragraph> + </tablecell> + </tablerow> + </table> + <paragraph role="tip" id="par_id9158273378151" xml-lang="en-US">Note that the <literal>TotalDuration</literal> property is equivalent to summing the <literal>Duration</literal> and <literal>SuspendDuration</literal> properties.</paragraph> + + <h2 id="hd_id141582734141895" xml-lang="en-US">Methods</h2> + <paragraph role="paragraph" id="par_id291582734377752" xml-lang="en-US">All methods do not require arguments and return a <literal>Boolean</literal> value.</paragraph> + <paragraph role="paragraph" id="par_id311582734894257" xml-lang="en-US">If the returned value is <literal>False</literal>, then nothing happened.</paragraph> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id911610740799006"> + <bookmark_value>Timer service;Continue</bookmark_value> + <bookmark_value>Timer service;Restart</bookmark_value> + <bookmark_value>Timer service;Start</bookmark_value> + <bookmark_value>Timer service;Suspend</bookmark_value> + <bookmark_value>Timer service;Terminate</bookmark_value> + </bookmark> + <table id="tab_id231582734180676"> + <tablerow> + <tablecell> + <paragraph id="par_id871582734180676" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id971582734180676" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911582734180676" role="tablehead" xml-lang="en-US">Returned value</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id31582734180676" localize="False" role="tablecontent" xml-lang="en-US">Continue</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id301582734180676" role="tablecontent" xml-lang="en-US">Resumes the <literal>Timer</literal> if it has been suspended</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661582734180676" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is not suspended</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id881582734649304" localize="False" role="tablecontent" xml-lang="en-US">Restart</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id821582734649305" role="tablecontent" xml-lang="en-US">Terminates the <literal>Timer</literal> and discards its current property values, restarting as a new clean <literal>Timer</literal></paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761582734649305" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is inactive</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id201582734802443" localize="False" role="tablecontent" xml-lang="en-US">Start</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id641582734802443" role="tablecontent" xml-lang="en-US">Starts a new clean timer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id921582734802443" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is already started</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id781582734905507" localize="False" role="tablecontent" xml-lang="en-US">Suspend</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81582734905507" role="tablecontent" xml-lang="en-US">Suspends a running timer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661582734905507" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is not started or already suspended</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id771582734996722" localize="False" role="tablecontent" xml-lang="en-US">Terminate</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id861582734996722" role="tablecontent" xml-lang="en-US">Stops a running timer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id381582734996722" role="tablecontent" xml-lang="en-US"><literal>False</literal> if the timer is neither started nor suspended</paragraph> + </tablecell> + </tablerow> + </table> + + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id731626871820490">The examples below in Basic and Python illustrate the use of the methods and properties in the <literal>Timer</literal> service.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id711582735902164">myTimer.Start()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id371582735909094">Wait 500</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691582735916493">myTimer.Suspend()</paragraph> + <paragraph role="bascode" id="bas_id141582735926821">'The time elapsed while the Dialog box is open will be counted as suspended time</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001582735936992">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph> + <paragraph role="bascode" localize="false" id="bas_id361582735943749">myTimer.Continue()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id71582735950518">Wait 500</paragraph> + <paragraph role="bascode" id="bas_id901582735961725">'The time elapsed while the Dialog box is open will be counted as running time</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621610739916646">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51610739919950">myTimer.Terminate()</paragraph> + <paragraph role="bascode" id="bas_id941610739926687">'Shows the final time measurements</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291610739929200">MsgBox myTimer.Duration & " " & myTimer.SuspendDuration & " " & myTimer.TotalDuration</paragraph> + </bascode> + <note id="par_id281610740093006">If you call the <literal>Terminate</literal> method, subsequent calls for the <literal>Continue</literal> method will not resume time measurement. Similarly, after a Timer has been terminated, calling the <literal>Start</literal> method will restart it as if it were a clean new Timer.</note> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id731626871933079">from time import sleep</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921626871933367">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id101626871933551">myTimer.Start()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id961626871933734">sleep(0.5)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id351626871933894">myTimer.Suspend()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id761626871934072">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id411626871934239">myTimer.Continue()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id941626871934407">sleep(0.5)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id521626871934590">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id921626871934776">myTimer.Terminate()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id531626872457511">bas.MsgBox("{} {} {}".format(myTimer.Duration, myTimer.SuspendDuration, myTimer.TotalDuration))</paragraph> + </pycode> + <note id="par_id391626872019832">Beware that the <literal>Wait</literal> function in Basic takes in a duration argument in milliseconds whereas the <literal>sleep</literal> function in Python uses seconds in its argument.</note> + + <h2 id="hd_id431610989623086">Working with Multiple Timers</h2> + <paragraph role="paragraph" id="par_id741610989639201">It is possible to instantiate multiple <literal>Timer</literal> services in parallel, which gives flexibility in measuring time in different parts of the code.</paragraph> + <paragraph role="paragraph" id="par_id921610989722908">The following example illustrates how to create two <literal>Timer</literal> objects and start them separately.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id771610989793244">Dim myTimerA as Variant, myTimerB as Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261610989825466">myTimerA = CreateScriptService("Timer")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931610989829730">myTimerB = CreateScriptService("Timer")</paragraph> + <paragraph role="bascode" id="bas_id481610989853679">'Starts myTimerA</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911610989839892">myTimerA.Start()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871610989842236">Wait 1000 'Wait 1 second (1,000 milliseconds)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571610989855742">MsgBox myTimerA.Duration & " " & myTimerB.Duration</paragraph> + <paragraph role="bascode" id="bas_id331610989849501">'Starts myTimerB</paragraph> + <paragraph role="bascode" localize="false" id="bas_id341610989847112">myTimerB.Start()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id571610989851550">Wait 1000</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51610989832354">MsgBox myTimerA.Duration & " " & myTimerB.Duration</paragraph> + <paragraph role="bascode" id="bas_id931610989837747">'Terminate both timers</paragraph> + <paragraph role="bascode" localize="false" id="bas_id631610989844852">myTimerA.Terminate()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id411610989835115">myTimerB.Terminate()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id711626872551380">from time import sleep</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id541626872551709">myTimerA = CreateScriptService("Timer")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id581626872551876">myTimerB = CreateScriptService("Timer")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441626872552076">myTimerA.Start()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631626872552268">sleep(1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id41626872552468">bas.MsgBox("{} {}".format(myTimerA.Duration, myTimerB.Duration))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id891626872552670">myTimerB.Start()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id321626872552868">sleep(1)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id11626872553077">bas.MsgBox("{} {}".format(myTimerA.Duration, myTimerB.Duration))</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id441626872553324">myTimerA.Terminate()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id161626872553821">myTimerB.Terminate()</paragraph> + </pycode> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03030203.xhp#Now_H1"/> + <embed href="text/sbasic/shared/03030303.xhp#Timer_H1"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_ui.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_ui.xhp new file mode 100644 index 000000000..313577f48 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_ui.xhp @@ -0,0 +1,704 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="SF_UI" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">ScriptForge.UI service</title> + <filename>/text/sbasic/shared/03/sf_ui.xhp</filename> + </topic> +</meta> +<body> +<section id="abstract"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id151587913266190"> + <bookmark_value>UI service</bookmark_value> + </bookmark> + +<h1 id="hd_id371587913266310" xml-lang="en-US"><variable id="UIService"><link href="text/sbasic/shared/03/sf_ui.xhp" name="ScriptForge.UI service"><literal>ScriptForge</literal>.<literal>UI</literal> service</link></variable></h1> + +<paragraph role="paragraph" xml-lang="en-US" id="par_id31587913266153">The UI (User Interface) service simplifies the identification and the manipulation of the different windows composing the whole %PRODUCTNAME application:</paragraph> +<list type="unordered"> + <listitem> + <paragraph role="listitem" id="par_id591587913266547" xml-lang="en-US">Windows selection</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id511587913266292" xml-lang="en-US">Windows moving and resizing</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id51587913266596" xml-lang="en-US">Statusbar settings</paragraph> + </listitem> + <listitem> + <paragraph id="par_id401599404339702" role="listitem" xml-lang="en-US">Display of a floating progress bar</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id761587913266388" xml-lang="en-US">Creation of new windows</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id591587913266489" xml-lang="en-US">Access to the underlying "documents"</paragraph> + </listitem> +</list> +</section> + +<tip id="par_id181620312953395">The UI service is the starting point to open, create or access to the content of new or existing documents from a user script.</tip> + +<h2 id="hd_id881587913266307">Definitions</h2> + +<section id="WindowName"> + <h3 id="hd_id761587913266887" localize="false">WindowName</h3> + <paragraph role="paragraph" id="par_id741587913266919">A window can be designated using various ways:</paragraph> + <list type="unordered"> + <listitem> + <paragraph role="listitem" id="par_id291587913946648" xml-lang="en-US">a full path and file name</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id991587914045862" xml-lang="en-US">the last component of the full file name or even only the last component without its suffix</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id541587914079744" xml-lang="en-US">the title of the window</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id191587914134221" xml-lang="en-US">for new documents, something like "Untitled 1"</paragraph> + </listitem> + <listitem> + <paragraph role="listitem" id="par_id911587914185746" xml-lang="en-US">one of the special windows "<literal>BASICIDE</literal>" and "<literal>WELCOMESCREEN</literal>"</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id181587914255236" xml-lang="en-US">The window name is case-sensitive.</paragraph> + <h3 id="hd_id541588520711430" xml-lang="en-US">Document object</h3> +</section> + <paragraph role="paragraph" id="par_id841588521238711" xml-lang="en-US">The methods <literal>CreateDocument</literal>, <literal>CreateBaseDocument</literal>, <literal>GetDocument</literal>, <literal>OpenBaseDocument</literal> and <literal>OpenDocument</literal>, described below, generate document objects. When a window contains a document, an instance of the <literal>Document</literal> class represents that document. A counterexample the Basic IDE is not a document but is a window in our terminology. Additionally a document has a type: <literal>Calc</literal>, <literal>Impress</literal>, <literal>Writer</literal>, ...</paragraph> + <paragraph role="paragraph" id="par_id331588521254916" xml-lang="en-US">The specific properties and methods applicable on documents are implemented in a document class.</paragraph> + <tip id="par_id971588521292976" xml-lang="en-US">The implementation of the document objects class is done in the <literal>SFDocuments</literal> associated library. See its "<literal>Document</literal>" service.</tip> + +<h2 id="hd_id91587913266988" xml-lang="en-US">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>UI</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id391587913266269">Dim ui As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id851582897798335">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id1001587913266355">Set ui = CreateScriptService("UI")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id61620310677393">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id601620310674922">ui = CreateScriptService("UI")</paragraph> + </pycode> + +<h2 id="hd_id841587913266618" xml-lang="en-US">Properties</h2> + <table id="tab_id291587913266435"> + <tablerow> + <tablecell> + <paragraph id="par_id521587913266568" role="tablehead" xml-lang="en-US">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587913266368" role="tablehead" xml-lang="en-US">ReadOnly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id631587914939732" role="tablehead" xml-lang="en-US">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951587913266220" role="tablehead" xml-lang="en-US">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266162" role="tablecontent" localize="false">ActiveWindow</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266754" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989890" role="tablecontent" localize="false">String</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266349" role="tablecontent" xml-lang="en-US">a valid and unique <literal>WindowName</literal> for the currently active window. When the window cannot be identified, a zero-length string is returned.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161597813266162" role="tablecontent" localize="false">Documents</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id658517913266754" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587994189890" role="tablecontent" localize="false">String array</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id153587913266349" role="tablecontent" xml-lang="en-US">The list of the currently open documents. Special windows are ignored. This list consists of a zero-based one dimensional array either of filenames (in SF_FileSystem.FileNaming notation) or of window titles for unsaved documents.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266563" role="tablecontent" localize="false">Height</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266945" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989732" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266211" role="tablecontent" xml-lang="en-US">Returns the height of the active window in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266574" role="tablecontent" localize="false">Width</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266645" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989935" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266036" role="tablecontent" xml-lang="en-US">Returns the width of the active window in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266096" role="tablecontent" localize="false">X</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266312" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989789" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266296" role="tablecontent" xml-lang="en-US">Returns the X coordinate of the active window, which is the distance to the left edge of the screen in pixels.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id161587913266323" role="tablecontent" localize="false">Y</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id651587913266670" role="tablecontent" xml-lang="en-US">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id421587914989902" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id351587913266216" role="tablecontent" xml-lang="en-US">Returns the Y coordinate of the active window, which is the distance to the top edge of the screen in pixels. This value does not consider window decorations added by your operating system, so even when the window is maximized this value may not be zero.</paragraph> + </tablecell> + </tablerow> + </table> + +<section id="Constants"> +<h2 id="hd_id511620762163390">Constants</h2> +<table id="tab_id51620761856238"> + <tablerow> + <tablecell> + <paragraph id="par_id761620761856238" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id591620761856238" role="tablehead">Value</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711620761856238" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id511620761856238" localize="false" role="tablecontent">MACROEXECALWAYS</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761620761856107" localize="false" role="tablecontent">2</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id341620761856238" role="tablecontent">Macros are always executed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id661620761881513" localize="false" role="tablecontent">MACROEXECNEVER</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id661620761891082" localize="false" role="tablecontent">1</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id101620761893011" role="tablecontent">Macros are never executed</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id311620761888379" localize="false" role="tablecontent">MACROEXECNORMAL</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id951620761899067" localize="false" role="tablecontent">0</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id11620761899780" role="tablecontent">Macro execution depends on user settings</paragraph> + </tablecell> + </tablerow> +</table> +</section> + + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id311620312548992">The examples below show a <literal>MsgBox</literal> with the names of all currently open documents.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id201587985861232">Dim openDocs as Object, strDocs as String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id261587985839734">Set openDocs = ui.Documents()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id621587985950181">strDocs = openDocs(0)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id11587985956383">For i = 1 to UBound(openDocs)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981620312219531"> strDocs = strDocs & Chr(10) & openDocs(i)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id341587985962974">Next i</paragraph> + <paragraph role="bascode" localize="false" id="bas_id191620312244070">MsgBox strDocs</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id21620312350189">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id631620312351013">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id141620312351286">openDocs = ui.Documents()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661620312351500">strDocs = "\n".join(openDocs)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801620312351676">bas.MsgBox(strDocs)</paragraph> + </pycode> + + <table id="tab_id891606472825856"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id881608131596153" role="tablehead">List of Methods in the UI Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell><paragraph id="par_id381606472825856" role="tablecontent" localize="false"> + <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><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#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> (*)<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#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><br/><br/> + </paragraph></tablecell> + </tablerow> + </table> +<warning id="par_id431620322170443">Note, as an exception, that the methods marked <emph>(*)</emph> are <emph>not applicable to Base documents</emph>.</warning> + +<section id="Activate"> + <comment> Activate -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id991587913266189"> + <bookmark_value>UI service;Activate</bookmark_value> + </bookmark> + <h2 id="hd_id76158791326673" localize="false">Activate</h2> + <paragraph role="paragraph" id="par_id201587913266596">Make the specified window active. The method returns <literal>True</literal> if the given window is found and can be activated. There is no change in the actual user interface if no window matches the selection.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id331620319796672"> + <input>svc.Activate(windowname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id381587913266946"><emph>windowname</emph>: see the definitions above.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id201587913266745">ui.Activate("C:\Documents\My file.odt")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id941620322846267">ui.Activate(r"C:\Documents\My file.odt")</paragraph> + </pycode> +</section> + +<section id="CreateBaseDocument"> + <comment> CreateBaseDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id871596554849122"> + <bookmark_value>UI service;CreateBaseDocument</bookmark_value> + </bookmark> + <h2 id="hd_id281596554849363" localize="false">CreateBaseDocument</h2> + <paragraph role="paragraph" id="par_id13159655484952">Creates and stores a new %PRODUCTNAME Base document embedding an empty database of the given type. The method returns a <literal>Document</literal> service instance.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id461620320014911"> + <input>svc.CreateBaseDocument(filename: str, embeddeddatabase: str = 'HSQLDB', registrationname: str = '', opt calcfilename: str): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441596554849949"><emph>filename</emph> : Identifies the file to create. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation. If the file already exists, it is overwritten without warning</paragraph> + <paragraph role="paragraph" id="par_id381596554849698" xml-lang="en-US"><emph>embeddeddatabase</emph> : Either "HSQLDB" (default), "FIREBIRD" or "CALC".</paragraph> + <paragraph role="paragraph" id="par_id521596554849185" xml-lang="en-US"><emph>registrationname</emph> : The name used to store the new database in the databases register. When = "" (default), no registration takes place. If the name already exists it is overwritten without warning.</paragraph> + <paragraph role="paragraph" id="par_id181629364905056" xml-lang="en-US"><emph>calcfilename</emph> : Only when <literal>embeddeddatabase</literal> = "CALC", <literal>calcfilename</literal> represents the file containing the tables as Calc sheets. The file must exist or an error is raised.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id631596554849994">Dim myBase As Object, myCalcBase As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id921596554849612">Set myBase = ui.CreateBaseDocument("C:\Databases\MyBaseFile.odb", "FIREBIRD")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id51629365306345">Set myCalcBase = ui.CreateBaseDocument("C:\Databases\MyCalcBaseFile.odb", _</paragraph> + <paragraph role="bascode" localize="false" id="bas_id911629365353801"> "CALC", , "C:\Databases\MyCalcFile.ods")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id361620323808010">myBase = ui.CreateBaseDocument(r"C:\Databases\MyBaseFile.odb", "FIREBIRD")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id251629365641121">myCalcBase = ui.CreateBaseDocument(r"C:\Databases\MyCalcBaseFile.odb", \</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id431629366045258"> "CALC", calcfilename = r"C:\Databases\MyCalcFile.ods")</paragraph> + </pycode> +</section> + +<section id="CreateDocument"> + <comment> CreateDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id461588521753429"> + <bookmark_value>UI service;CreateDocument</bookmark_value> + </bookmark> + <h2 id="hd_id45158852175376" localize="false">CreateDocument (*)</h2> + <paragraph role="paragraph" id="par_id651588521753997">Create a new %PRODUCTNAME document of a given type or based on a given template. The method returns a document object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id401620320696126"> + <input>svc.CreateDocument(documenttype: str = '', templatefile: str = '', hidden: bool = False): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id51588521753302"><emph>documenttype</emph> : "Calc", "Writer", etc. If absent, the <literal>templatefile</literal> argument must be present.</paragraph> + <paragraph role="paragraph" id="par_id401588522663325" xml-lang="en-US"><emph>templatefile</emph> : The full <literal>FileName</literal> of the template to build the new document on. If the file does not exist, the argument is ignored. The <literal>FileSystem</literal> service provides the <literal>TemplatesFolder</literal> and <literal>UserTemplatesFolder</literal> properties to help to build the argument.</paragraph> + <paragraph role="paragraph" id="par_id131588522824366" xml-lang="en-US"><emph>hidden</emph>: if <literal>True</literal>, open the new document in the background (default = <literal>False</literal>). To use with caution: activation or closure afterwards can only happen programmatically.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id701620762417802">In both examples below, the first call to <literal>CreateDocument</literal> method creates a blank Calc document, whereas the second creates a document from a template file.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id201588522371030">Dim myDoc1 As Object, myDoc2 As Object, FSO As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id931588522377598">Set myDoc1 = ui.CreateDocument("Calc")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821588522387111">Set FSO = CreateScriptService("FileSystem")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id661588522393007">Set myDoc2 = ui.CreateDocument(, FSO.BuildPath(FSO.TemplatesFolder, "personal/CV.ott"))</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id901620324433095">myDoc1 = ui.CreateDocument("Calc")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id361620324544381">fs = CreateScriptService("FileSystem")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id161620324434583">myDoc2 = ui.CreateDocument(templatefile = fs.BuildPath(fs.TemplatesFolder, "personal/CV.ott"))</paragraph> + </pycode> +</section> + +<section id="GetDocument"> + <comment> GetDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id351588520551838"> + <bookmark_value>UI service;GetDocument</bookmark_value> + </bookmark> + <h2 id="hd_id171588520551515" localize="false">GetDocument</h2> + <paragraph role="paragraph" id="par_id201588520551463">Returns an open document object referring to either the active window, a given window or the active document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id811620320778478"> <input>svc.GetDocument(windowname: str = ''): svc</input></paragraph> + <paragraph role="paragraph" localize="false" id="par_id251624026292796"><input>svc.GetDocument(windowname: uno): svc</input></paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id851588520551368"><emph>windowname</emph>: See the definitions <link href="text/sbasic/shared/03/sf_ui.xhp#WindowName" name="WindowName section">above</link>. If this argument is absent, the active window is used. UNO objects of types <literal>com.sun.star.lang.XComponent</literal> or <literal>com.sun.star.comp.dba.ODatabaseDocument</literal> are also accepted. Thus passing <literal>ThisComponent</literal> or <literal>ThisDatabaseDocument</literal> as argument creates a new <link href="text/sbasic/shared/03/sf_document.xhp" name="Document service">SFDocuments.Document</link>, <link href="text/sbasic/shared/03/sf_base.xhp" name="Base service">Base</link> or <link href="text/sbasic/shared/03/sf_calc.xhp" name="Calc service">Calc</link> service. +</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191588522924110">Dim myDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591588520551682">Set myDoc = ui.GetDocument("C:\Documents\My file.odt")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id651624025734467">Set myBase = ui.GetDocument(ThisDatabaseDocument)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id931624025986035">from scriptforge import CreateScriptService</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id641624026031595">bas = CreateScriptService("Basic")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id831620330074037">myDoc = ui.GetDocument(r"C:\Documents\My file.odt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id601624025839840">myDoc = ui.GetDocument(bas.ThisComponent)</paragraph> + </pycode> + <tip id="par_id521620330287071">To access the name of the currently active window, refer to the <literal>ActiveWindow</literal> property.</tip> +</section> + +<section id="Maximize"> + <comment> Maximize -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id441587986441397"> + <bookmark_value>UI service;Maximize</bookmark_value> + </bookmark> + <h2 id="hd_id261587986441738" localize="false">Maximize</h2> + <paragraph role="paragraph" id="par_id24158798644169">Maximizes the active window or the given window.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id631620320925633"> + <input>svc.Maximize(windowname: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id951587986441954"><emph>windowname</emph>: see the definitions <link href="text/sbasic/shared/03/sf_ui.xhp#WindowName" name="WindowName section">above</link>. If this argument is absent, the active window is maximized.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id891587986441319">ui.Maximize("Untitled 1")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id181620330373220">ui.Maximize("Untitled 1")</paragraph> + </pycode> +</section> + +<section id="Minimize"> + <comment> Minimize -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id2315879865929"> + <bookmark_value>UI service;Minimize</bookmark_value> + </bookmark> + <h2 id="hd_id21158798659210" localize="false">Minimize</h2> + <paragraph role="paragraph" id="par_id871587986592696">Minimizes the active window or the given window.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id201620321224368"> + <input>svc.Minimize(windowname: str)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id751587986592626"><emph>windowname</emph>: see the definitions <link href="text/sbasic/shared/03/sf_ui.xhp#WindowName" name="WindowName section">above</link>. If this argument is absent, the active window is minimized.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671587986592107">ui.Minimize()</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id481620330501644">ui.Minimize()</paragraph> + </pycode> +</section> + +<section id="OpenBaseDocument"> + <comment> OpenBaseDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id291596555746452"> + <bookmark_value>UI service;OpenBaseDocument</bookmark_value> + </bookmark> + <h2 id="hd_id671596555746148" localize="false">OpenBaseDocument</h2> + <paragraph role="paragraph" id="par_id691596555746539">Open an existing %PRODUCTNAME Base document. The method returns a document object.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id21620321395150"> + <input>svc.OpenBaseDocument(filename: str = '', registrationname: str = '', macroexecution: int = 0): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id231596555746385"><emph>filename</emph>: Identifies the file to open. It must follow the <literal>SF_FileSystem.FileNaming</literal> notation.</paragraph> + <paragraph role="paragraph" id="par_id711596555746281" xml-lang="en-US"><emph>registrationname</emph>: The name to use to find the database in the databases register. It is ignored if <literal>FileName</literal> <> "".</paragraph> + <paragraph role="paragraph" id="id721596556313545" xml-lang="en-US"><emph>macroexecution</emph>: 0 = behaviour is defined by the user configuration, 1 = macros are not executable, 2 = macros are executable.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id761596555746795">Dim myBase As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91596555746449">Set myBase = ui.OpenBaseDocument("C:\Documents\myDB.odb", MacroExecution := ui.MACROEXECALWAYS)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id431620331254271">ui.OpenBaseDocument(r"C:\Documents\myDB.odb", macroexecution = ui.MACROEXECALWAYS)</paragraph> + </pycode> + <tip id="par_id941620762989833">To improve code readability you can use <link href="text/sbasic/shared/03/sf_ui.xhp#Constants" name="CHANGE ME">predefined constants</link> for the <literal>macroexecution</literal> argument, as in the examples above.</tip> +</section> + +<section id="OpenDocument"> + <comment> OpenDocument -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id141588523635836"> + <bookmark_value>UI service;OpenDocument</bookmark_value> + </bookmark> + <h2 id="hd_id451588523635719" localize="false">OpenDocument (*)</h2> + <paragraph role="paragraph" id="par_id541588523635283">Opens an existing %PRODUCTNAME document with the given options. Returns a document object or one of its subclasses. The method returns <literal>Nothing</literal> (in Basic) / <literal>None</literal> (in Python) if the opening failed, even when the failure is caused by a user decision.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id271620321692960"> + <input>svc.Opendocument(filename: str, password: str = '', readonly: bool = False, hidden: bool = False, macroexecution: int = 0, filtername: str = '', filteroptions: str = ''): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id481588523635890"><emph>filename</emph>: Identifies the file to open. It must follow the <literal>FileNaming</literal> notation of the <literal>FileSystem</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id451588523635507" xml-lang="en-US"><emph>password</emph>: To use when the document is protected. If wrong or absent while the document is protected, the user will be prompted to enter a password.</paragraph> + <paragraph role="paragraph" id="par_id611588524329781" xml-lang="en-US"><emph>readonly</emph>: Default = <literal>False</literal>.</paragraph> + <paragraph role="paragraph" id="par_id641588523635497" xml-lang="en-US"><emph>hidden</emph>: if <literal>True</literal>, open the new document in the background (default = <literal>False</literal>). To use with caution: activation or closure afterwards can only happen programmatically.</paragraph> + <paragraph role="paragraph" id="par_id981588524474719" xml-lang="en-US"><emph>macroexecution</emph>: 0 = behaviour is defined by the user configuration, 1 = macros are not executable, 2 = macros are executable.</paragraph> + <paragraph role="paragraph" id="par_id611588524584693" xml-lang="en-US"><emph>filtername</emph>: The name of a filter that should be used for loading the document. If present, the filter must exist.</paragraph> + <paragraph role="paragraph" id="par_id191588524634348" xml-lang="en-US"><emph>filteroptions</emph>: An optional string of options associated with the filter.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id811588523635720">Dim myDoc As Object, FSO As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391588523635826">Set myDoc = ui.OpenDocument("C:\Documents\myFile.odt", ReadOnly := True)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id891620331804571">ui.OpenDocument(r"C:\Documents\myFile.odt", readonly = True)</paragraph> + </pycode> +</section> + +<section id="Resize"> + <comment> Resize -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id951587986945259"> + <bookmark_value>UI service;Resize</bookmark_value> + </bookmark> + <h2 id="hd_id551587986945514" localize="false">Resize</h2> + <paragraph role="paragraph" id="par_id751587986945965">Resizes and/or moves the active window. Absent and negative arguments are ignored. If the window is minimized or maximized, calling <literal>Resize</literal> without arguments restores it.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id411620321819387"> + <input>svc.Resize(left: int = -1, top: int = -1, width: int = -1, height: int = -1)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441587986945696"><emph>left, top</emph>: Distances of the top-left corner from top and left edges of the screen, in pixels.</paragraph> + <paragraph role="paragraph" id="par_id601587987453825" xml-lang="en-US"><emph>width, height</emph>: New dimensions of the window, in pixels.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id801587987507028">In the following examples, the <literal>width</literal> and <literal>height</literal> of the window are changed while <literal>top</literal> and <literal>left</literal> are left unchanged.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id171587986945392">ui.Resize(, ,500, 500)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id971620331945744">ui.Resize(width = 500, height = 500)</paragraph> + </pycode> + <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"> + <bookmark_value>UI service;SetStatusbar</bookmark_value> + </bookmark> + <h2 id="hd_id171587996421550" localize="false">SetStatusbar (*)</h2> + <paragraph role="paragraph" id="par_id281587996421580">Display a text and a progressbar in the status bar of the active window. Any subsequent calls in the same macro run refer to the same status bar of the same window, even if the window is not visible anymore. A call without arguments resets the status bar to its normal state.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id461620321923929"> + <input>svc.SetStatusbar(text: str = '', percentage: int = -1)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id71587996421829"><emph>text</emph>: An optional text to be displayed in front of the progress bar.</paragraph> + <paragraph role="paragraph" id="par_id881587996421777" xml-lang="en-US"><emph>percentage</emph>: an optional degree of progress between 0 and 100.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61587996791867">Dim i As Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id291587996799353">For i = 0 To 100</paragraph> + <paragraph role="bascode" localize="false" id="bas_id331587996806267"> ui.SetStatusbar("Progress ...", i)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id491587996813628"> Wait 50</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841587996820714">Next i</paragraph> + <paragraph role="bascode" id="bas_id651620332601083">' Resets the statusbar</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141587996829242">ui.SetStatusbar</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id631620332653004">from time import sleep</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id351620332422330">for i in range(101):</paragraph> + <paragraph role="pycode" localize="false" id="bas_id261620332627647"> ui.SetStatusbar("Test:", i)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id181620332715974"> sleep(0.05)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id381620332733373">ui.SetStatusbar()</paragraph> + </pycode> +</section> + +<section id="ShowProgressBar"> + <comment> ShowProgressBar -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id91159886425573"> + <bookmark_value>UI service;ShowProgressBar</bookmark_value> + </bookmark> + <h2 id="hd_id31598864255380" localize="false">ShowProgressBar</h2> + <paragraph role="paragraph" id="par_id571598864255776">Displays a non-modal dialog box. Specify its title, an explicatory text and a percentage of progress to be represented on a progressbar. The dialog will remain visible until a call to the method without arguments or until the user manually closes the dialog.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id41620322016943"> + <input>svc.ShowProgressBar(title: str = '', text: str = '', percentage: str = -1)</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441598864535695" xml-lang="en-US"><emph>title</emph> : The title appearing on top of the dialog box. Default = "ScriptForge".</paragraph> + <paragraph role="paragraph" id="par_id311598864255297"><emph>text</emph>: An optional text to be displayed above the progress bar.</paragraph> + <paragraph role="paragraph" id="par_id881598864255424" xml-lang="en-US"><emph>percentage</emph>: an optional degree of progress between 0 and 100.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id931598864255666">Dim i As Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211598864255731">For i = 0 To 100</paragraph> + <paragraph role="bascode" localize="false" id="bas_id341598864255351"> ui.ShowProgressBar("Window Title", "Progress ..." & i & "/100", i)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id34159886425576"> Wait 50</paragraph> + <paragraph role="bascode" localize="false" id="bas_id541598864255593">Next i</paragraph> + <paragraph role="bascode" id="bas_id651620333289753">' Closes the Progress Bar window</paragraph> + <paragraph role="bascode" localize="false" id="bas_id21598864255428">ui.ShowProgressBar</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id821620333264948">from time import sleep</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id611620333268146">for i in range(101):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id331620333268525"> ui.ShowProgressBar("Window Title", "Progress ... " + str(i) + "/100", i)</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id451620333268900"> sleep(0.05)</paragraph> + <paragraph role="pycode" id="pyc_id761620333269236"># Closes the Progress Bar window</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id81620333269484">ui.ShowProgressBar()</paragraph> + </pycode> +</section> + +<section id="WindowExists"> + <comment> WindowExists -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id431588587119136"> + <bookmark_value>UI service;WindowExists</bookmark_value> + </bookmark> + <h2 id="hd_id21588587119344" localize="false">WindowExists</h2> + <paragraph role="paragraph" id="par_id431588587119925">Returns <literal>True</literal> if the given window could be identified.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id521620322090015"> + <input>svc.WindowExists(windowname: str): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id45158858711917"><emph>windowname</emph>: see the definitions above.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id941588587119772">If ui.WindowExists("C:\Document\My file.odt") Then</paragraph> + <paragraph role="bascode" localize="false" id="bas_id871588587295216"> ' ...</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id441620333481074">if ui.WindowExists(r"C:\Document\My file.odt"):</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id801620333495532"> # ...</paragraph> + </pycode> +</section> + +<section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_basic.xhp#BasicService"/> + <embed href="text/sbasic/shared/03/sf_calc.xhp#CalcService"/> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> +</section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_unittest.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_unittest.xhp new file mode 100644 index 000000000..80ce5c834 --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_unittest.xhp @@ -0,0 +1,818 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> +<meta> + <topic id="SF_UnitTest" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFUnitTests.UnitTest service</title> + <filename>/text/sbasic/shared/03/sf_unittest.xhp</filename> + </topic> + </meta> +<body> +<section id="ScriptForge-sf_unittest"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788079507"> + <bookmark_value>UnitTest service</bookmark_value> + </bookmark> +</section> +<section id="abstract"> + <h1 id="bm_id681600788076499"><variable id="UnitTestService"><link href="text/sbasic/shared/03/sf_unittest.xhp" name="UnitTest service"><literal>SFUnitTests</literal>.<literal>UnitTest</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id181600788076612">The <literal>UnitTest</literal> service provides a framework for automating unit tests using the Basic language, including the ability to:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id301600788076785" role="listitem">Aggregate test cases into test suites and unit tests.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id1001600788076848" role="listitem">Share setup and shutdown code among test cases.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id67160078807676" role="listitem">Report test results using the <literal>Console</literal>.</paragraph> + </listitem> + </list> +</section> + <note id="par_id411656351918942">Both the unit tests and the code to be tested must be written in Basic. The code being tested may call functions written in other languages.</note> + <warning id="par_id601656621416963">The <literal>UnitTest</literal> service is not available for Python scripts.</warning> + + <h2 id="hd_id491656351958796">Definitions</h2> + <h3 id="hd_id31656351967453">Test Case</h3> + <paragraph role="paragraph" id="par_id571656351977812">A test case is the individual unit of testing. It checks for a specific response to a particular set of inputs.</paragraph> + <paragraph role="paragraph" id="par_id391656352078166">In the <literal>UnitTest</literal> service, a test case is represented by a single Basic <literal>Sub</literal> whose name starts with a common prefix (the default is "Test_").</paragraph> + <paragraph role="paragraph" id="par_id701656352338645">The test case fails if one of the <literal>AssertX</literal> methods returns <literal>False</literal>.</paragraph> + <h3 id="hd_id431656352497598">Test Suite</h3> + <paragraph role="paragraph" id="par_id771656352513789">A test suite is a collection of test cases that should be executed together.</paragraph> + <paragraph role="paragraph" id="par_id941656352597973">All test cases of a test suite are stored in a single Basic module.</paragraph> + <paragraph role="paragraph" id="par_id51656352696989">A test suite may implement the <literal>SetUp</literal> and <literal>TearDown</literal> methods to prepare for test cases in its module.</paragraph> + <h3 id="hd_id351656352884283">Unit Test</h3> + <paragraph role="paragraph" id="par_id461656352894003">A full unit test consists of a set of test suites in the same Basic library.</paragraph> + + <h2 id="hd_id991656353328287">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>UnitTest</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + <h3 id="hd_id941656357981021">Simple mode</h3> + <paragraph role="paragraph" id="par_id381656357996613">Invoke the service in <emph>simple mode</emph> to call <literal>AssertX</literal> functions without having to build the full hierarchy of test suites and test cases.</paragraph> + <paragraph role="paragraph" id="par_id331656358092318">In simple mode, the service is invoked inside the test case, as shown in the example below:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id561656358185215">Sub SimpleTest</paragraph> + <paragraph role="bascode" localize="false" id="bas_id116563581854320"> On Local Error GoTo CatchError</paragraph> + <paragraph role="bascode" localize="false" id="bas_id221656358185634"> Dim myTest As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id801656358185805"> myTest = CreateScriptService("UnitTest")</paragraph> + <paragraph role="bascode" id="bas_id501656358186053"> ' A few dummy tests</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791656421185689"> myTest.AssertEqual(1 + 1, 2)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id961656421186032"> myTest.AssertEqual(1 - 1, 0)</paragraph> + <paragraph role="bascode" id="bas_id981656421186233"> MsgBox("All tests passed")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691656421186433"> Exit Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id591656421186681">CatchError:</paragraph> + <paragraph role="bascode" id="bas_id971656421186872"> myTest.ReportError("A test failed")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id391656421284881">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id321656421319505">In this example, if any of the <literal>AssertEqual</literal> calls fail, the interpreter will go to the <literal>CatchError</literal> label and report the error by calling the <literal>ReportError</literal> method.</paragraph> + <h3 id="hd_id341656353807950">Full mode</h3> + <paragraph role="paragraph" id="par_id881656353390116">When invoked in <emph>full mode</emph>, the service creation is external to the test code and all tests are organized into test cases and test suites inside a single library.</paragraph> + <paragraph role="paragraph" id="par_id41656354017140">The following example creates a <literal>UnitTest</literal> instance whose tests are located inside the current document (<literal>ThisComponent</literal>) in the "Tests" library.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id171656354156234">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id641656354156652">Dim myUnitTest As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611656354156951">myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests")</paragraph> + </bascode> + <h3 id="hd_id731656421609300">A minimalist example in full mode</h3> + <paragraph role="paragraph" id="par_id721656421629357">Consider that a ODS file has a module named "MathUtils" in its "Standard" library with the following code:</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id821656421926586">' Code in module Standard.MathUtils</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791656421927279">Function Sum(a, b) As Double</paragraph> + <paragraph role="bascode" localize="false" id="bas_id791656421927530"> Sum = a + b</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321656421927738">End Function</paragraph> + <paragraph role="bascode" localize="false" id="bas_id141656421927930"></paragraph> + <paragraph role="bascode" localize="false" id="bas_id611656421928122">Function Multiply(a, b) As Double</paragraph> + <paragraph role="bascode" localize="false" id="bas_id581656421928322"> Multiply = a * b</paragraph> + <paragraph role="bascode" localize="false" id="bas_id101656421928786">End Function</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id871656422027581">To create a full test suite, consider that a new library named "Tests" is created in the file with a single module "AllTests" containing the code below:</paragraph> + <bascode> + <paragraph role="bascode" id="bas_id731656422341011">' Code in module Tests.AllTests</paragraph> + <paragraph role="bascode" localize="false" id="bas_id241656422341227">Sub Main()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id121656422341403"> GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id401656422341627"> Dim test As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id841656422341836"> test = CreateScriptService("UnitTest", ThisComponent, "Tests")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id616564223542052"> test.RunTest("AllTests")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id821656422342284"> test.Dispose()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id681656422342516">End Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781656422342732"></paragraph> + <paragraph role="bascode" localize="false" id="bas_id451656422342948">Sub Setup(test)</paragraph> + <paragraph role="bascode" id="bas_id671656422476689"> ' Preparation code ran prior to the first test case</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151656422476955"> Dim exc As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981656422477190"> exc = CreateScriptService("Exception")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991656422477719"> exc.Console(Modal := False)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151656422477959">End Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id611656422478230"></paragraph> + <paragraph role="bascode" localize="false" id="bas_id316564223478487">Sub TearDown(test)</paragraph> + <paragraph role="bascode" id="bas_id621656422479007"> ' Optional cleanup code called after the last test case</paragraph> + <paragraph role="bascode" localize="false" id="bas_id991656422479239">End Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id811656422683092"></paragraph> + <paragraph role="bascode" localize="false" id="bas_id711656422683636">Sub Test_Sum(test)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id816564522683844"> On Local Error GoTo CatchError</paragraph> + <paragraph role="bascode" id="bas_id141656422684085"> test.AssertEqual(Sum(1, 1), 2, "Sum two positive integers")</paragraph> + <paragraph role="bascode" id="bas_id491656422684324"> test.AssertEqual(Sum(-10, 20), 10, "Sum of negative and positive integers")</paragraph> + <paragraph role="bascode" id="bas_id201656422684556"> test.AssertEqual(Sum(1.5, 1), 2.5, "Sum of float and integer values")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211656422684772"> Exit Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601656422684988">CatchError:</paragraph> + <paragraph role="bascode" id="bas_id716356422685228"> test.ReportError("Sum method is broken")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id181656422685436">End Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id951656422832165"></paragraph> + <paragraph role="bascode" localize="false" id="bas_id271656422832448">Sub Test_Multiply(test)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id531656422832728"> On Local Error GoTo CatchError</paragraph> + <paragraph role="bascode" id="bas_id416564228330400"> test.AssertEqual(Multiply(2, 2), 4, "Multiply two positive integers")</paragraph> + <paragraph role="bascode" id="bas_id231656422833240"> test.AssertEqual(Multiply(-4, 2), -8, "Multiply negative and positive integers")</paragraph> + <paragraph role="bascode" id="bas_id931656422833480"> test.AssertEqual(Multiply(1.5, 3), 4.5, "Multiply of float and integer values")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id471656422833729"> Exit Sub</paragraph> + <paragraph role="bascode" localize="false" id="bas_id616564228334928">CatchError:</paragraph> + <paragraph role="bascode" id="bas_id151656422834184"> test.ReportError("Multiply method is broken")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id271656422834376">End Sub</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id681656423030706">The test suite above consists of two test cases <literal>Test_Sum</literal> and <literal>Test_Multiply</literal>. To run all tests simply run the <literal>Main</literal> method from the "AllTests" module.</paragraph> + <paragraph role="paragraph" id="par_id681656423146183">The <link href="text/sbasic/shared/03/sf_exception.xhp#Console" name="Console"><literal>Console</literal></link> from the <literal>Exception</literal> service is used as the default output to print test results. After running the example above, the following output will be displayed in the console:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id471656424558171">' RUNTEST ENTER testsuite='Tests.AllTests', pattern='Test_*'</paragraph> + <paragraph role="bascode" localize="false" id="bas_id881656424560234">' SETUP Tests.AllTests.Setup() ENTER</paragraph> + <paragraph role="bascode" localize="false" id="bas_id816565423395738">' SETUP Tests.AllTests.Setup() EXIT</paragraph> + <paragraph role="bascode" localize="false" id="bas_id981656423396035">' TESTCASE Tests.AllTests.Test_Multiply() ENTER</paragraph> + <paragraph role="bascode" localize="false" id="bas_id416564233956290">' TESTCASE Tests.AllTests.Test_Multiply() EXIT (0,017 sec)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731656423396546">' TESTCASE Tests.AllTests.Test_Sum() ENTER</paragraph> + <paragraph role="bascode" localize="false" id="bas_id781656423396778">' TESTCASE Tests.AllTests.Test_Sum() EXIT (0,016 sec)</paragraph> + <paragraph role="bascode" localize="false" id="bas_id321656423397506">' TEARDOWN Tests.AllTests.TearDown() ENTER</paragraph> + <paragraph role="bascode" localize="false" id="bas_id441656423397714">' TEARDOWN Tests.AllTests.TearDown() EXIT</paragraph> + <paragraph role="bascode" localize="false" id="bas_id151656423492374">' RUNTEST EXIT testsuite='Tests.AllTests' (0,223 sec)</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id161656423510879">If any of the <literal>AssertEqual</literal> methods fails during these tests, an error message is added to the console.</paragraph> + + <bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id11161490151416"> + <bookmark_value>Region service;LongMessage</bookmark_value> + <bookmark_value>Region service;ReturnCode</bookmark_value> + <bookmark_value>Region service;Verbose</bookmark_value> + <bookmark_value>Region service;WhenAssertionFails</bookmark_value> + </bookmark> + + <h2 id="hd_id711600788076834">Properties</h2> + <table id="tab_id701600788076583"> + <tablerow> + <tablecell> + <paragraph id="par_id461600788076917" role="tablehead">Name</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076328" role="tablehead">Type</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id67160078807636" role="tablehead">Description</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id491600788076621" role="tablecontent" localize="false">LongMessage</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id311600788076756" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id831600788076785" role="tablecontent" localize="false">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id441600788076826" role="tablecontent">When set to <literal>True</literal> (default) the console shows the standard message appended to the message provided by the tester. When <literal>False</literal>, only the message defined by the tester is used.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id941600788076595" role="tablecontent" localize="false">ReturnCode</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id49160078807654" role="tablecontent">Yes</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id961600788076376" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id81600788076419" role="tablecontent">Value returned by <literal>RunTest</literal> after the unit test is finished. Next is a list of possible values:</paragraph> + <paragraph role="paragraph" id="par_id141656425588260">0 - Test finished without errors or test not started<br/> + 1 - An assertion within a test case returned <literal>False</literal><br/> + 2 - A <literal>SkipTest</literal> was issued by the <literal>Setup</literal> method or by one of the test cases.<br/> + 3 - Abnormal end of test</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id721600788076638" role="tablecontent" localize="false">Verbose</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id711600788076534" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id911600788076842" localize="false" role="tablecontent">Boolean</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541600788076645" role="tablecontent">When set to <literal>True</literal>, all assertions are reported in the console (failing or not). When <literal>False</literal> (default), only failing assertions are reported.</paragraph> + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id961600788076890" role="tablecontent" localize="false">WhenAssertionFails</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id891600788076190" role="tablecontent">No</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761600788076562" role="tablecontent" localize="false">Integer</paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id91600788076674" role="tablecontent">Defines what is done when an assertion fails. Next is a list of possible values:</paragraph> + <paragraph role="paragraph" id="par_id671656425606077">0 - Ignore the failure and continue running the test<br/> + 1 - The <literal>TearDown</literal> method in the module is executed in the current test suite and the next suite is started (default in full mode).<br/> + 2 - Stop immediately (default in simple mode)</paragraph> + </tablecell> + </tablerow> + </table> + + <table id="tab_id901611086279902"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the UnitTest Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id761611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertAlmostEqual" name="AssertAlmostEqual method">AssertAlmostEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertEqual" name="AssertEqual method">AssertEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertFalse" name="AssertFalse method">AssertFalse</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertGreater" name="AssertGreater method">AssertGreater</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertGreaterEqual" name="AssertGreaterEqual method">AssertGreaterEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIn" name="AssertIn method">AssertIn</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIsInstance" name="AssertIsInstance method">AssertIsInstance</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIsNothing" name="AssertIsNothing method">AssertIsNothing</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertLike" name="AssertLike method">AssertLike</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id141611086279902" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotRegex" name="AssertNotRegex method">AssertNotRegex</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIsNull" name="AssertIsNull method">AssertIsNull</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertLess" name="AssertLess method">AssertLess</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertLessEqual" name="AssertLessEqual method">AssertLessEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotAlmostEqual" name="AssertNotAlmostEqual method">AssertNotAlmostEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotEqual" name="AssertNotEqual method">AssertNotEqual</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotIn" name="AssertNotIn method">AssertNotIn</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotInstance" name="AssertNotInstance method">AssertNotInstance</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotLike" name="AssertNotLike method">AssertNotLike</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id761611086279903" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotNothing" name="AssertNotNothing method">AssertNotNothing</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertNotNull" name="AssertNotNull method">AssertNotNull</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertRegex" name="AssertRegex method">AssertRegex</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertTrue" name="AssertTrue method">AssertTrue</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#Fail" name="Fail method">Fail</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#Log" name="Log method">Log</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#ReportError" name="ReportError method">ReportError</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#RunTest" name="RunTest method">RunTest</link><br/> + <link href="text/sbasic/shared/03/sf_unittest.xhp#SkipTest" name="SkipTest method">SkipTest</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + + <h2 id="hd_id201656428230690">Arguments of the AssertX methods</h2> + <paragraph role="paragraph" id="par_id591656428251124">All assertions test one or two expressions, referred in the remainder of this help page as <emph>A</emph> and <emph>B</emph>. They are always the first one or two arguments in the <literal>AssertX</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id231656428367462">All <literal>AssertX</literal> methods accept a <literal>message</literal> argument specifying a custom message to be reported in the console regarding the assertion. By default an empty string is used. This argument is always in the last position of the assertion.</paragraph> + <paragraph role="paragraph" id="par_id91656451227291">Some <literal>AssertX</literal> methods also accept additional arguments, as described by their syntaxes below.</paragraph> + + <section id="AssertAlmostEqual"> + <comment> AssertAlmostEqual -------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919665187"> + <bookmark_value>UnitTest service;AssertAlmostEqual</bookmark_value> + </bookmark> + <h2 id="hd_id201589199698020" localize="false">AssertAlmostEqual</h2> + <paragraph role="paragraph" id="par_id71621894833351">Returns <literal>True</literal> when <emph>A</emph> and <emph>B</emph> are numerical values and are considered to be close to each other, given a relative tolerance.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897232817"> + <input>svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id241656426318310">This assertion returns <literal>True</literal> if the two conditions below are met:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id861656426361793" role="listitem">A and B can be converted to the <literal>Double</literal> type.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851656426362072" role="listitem">The absolute difference between A and B divided by the largest absolute value of A or B is <emph>lower</emph> than the value specified in <literal>tolerance</literal>.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertEqual"> + <comment> AssertEqual -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919960367"> + <bookmark_value>UnitTest service;AssertEqual</bookmark_value> + </bookmark> + <h2 id="hd_id2015891996965210" localize="false">AssertEqual</h2> + <paragraph role="paragraph" id="par_id71621894830182">Returns <literal>True</literal> when <emph>A</emph> and <emph>B</emph> are considered to be equal.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897208117"> + <input>svc.AssertEqual(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id241656426317440">When A and B are scalars, <literal>True</literal> is returned if:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id861656426361808" role="listitem">Both expressions have the same <literal>VarType</literal> or are both numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851656426362362" role="listitem">Booleans and numeric values are compared with the = operator.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id201656427500186" role="listitem">Strings are compared with the builtin <literal>StrComp</literal> function. The comparison is case-sensitive.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id861656427531067" role="listitem">Dates and times are compared up to the second.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id361656427557940" role="listitem"><literal>Null</literal>, <literal>Empty</literal> and <literal>Nothing</literal> are not equal, but <literal>AssertEqual(Nothing, Nothing)</literal> returns <literal>True</literal>.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id31656427624016" role="listitem">UNO objects are compared with the builtin <literal>EqualUnoObjects</literal> method.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id301656427695507" role="listitem">Note that Basic objects are never equal.</paragraph> + </listitem> + </list> + <paragraph role="paragraph" id="par_id691656427837518">When A and B are arrays, <literal>True</literal> is returned if:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id831656427894608" role="listitem">Both arrays have the same number of dimensions (up to 2 dimensions) and their lower and upper bounds are identical for all dimensions.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851656427895040" role="listitem">All items in both arrays are equal, one by one.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id571656427895400" role="listitem">Two empty arrays are considered to be equal.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertFalse"> + <comment> AssertFalse -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969204"> + <bookmark_value>UnitTest service;AssertFalse</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693690" localize="false">AssertFalse</h2> + <paragraph role="paragraph" id="par_id71621894830071">Returns <literal>True</literal> when the type of A is <literal>Boolean</literal> and its value is <literal>False</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897203045"> + <input>svc.AssertFalse(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="AssertGreater"> + <comment> AssertGreater ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969108"> + <bookmark_value>UnitTest service;AssertGreater</bookmark_value> + </bookmark> + <h2 id="hd_id201589199665410" localize="false">AssertGreater</h2> + <paragraph role="paragraph" id="par_id71621894830337">Returns <literal>True</literal> when A is greater than B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897207037"> + <input>svc.AssertGreater(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428670110">The comparison between A and B assumes the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428689390" role="listitem">Eligible data types are <literal>String</literal>, <literal>Date</literal> or numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286489629" role="listitem">Both expressions must have the same <literal>VarType</literal> or both must be numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428689774" role="listitem">String comparisons are case-sensitive.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertGreaterEqual"> + <comment> AssertGreaterEqual ------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919963398"> + <bookmark_value>UnitTest service;AssertGreaterEqual</bookmark_value> + </bookmark> + <h2 id="hd_id201589199666322" localize="false">AssertGreaterEqual</h2> + <paragraph role="paragraph" id="par_id71621894838548">Returns <literal>True</literal> when A is greater than or equal to B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897203210"> + <input>svc.AssertGreaterEqual(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428670202">The comparison between A and B assumes the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428689207" role="listitem">Eligible data types are <literal>String</literal>, <literal>Date</literal> or numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286455529" role="listitem">Both expressions must have the same <literal>VarType</literal> or both must be numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428663284" role="listitem">String comparisons are case-sensitive.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertIn"> + <comment> AssertIn ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919964658"> + <bookmark_value>UnitTest service;AssertIn</bookmark_value> + </bookmark> + <h2 id="hd_id201589199666309" localize="false">AssertIn</h2> + <paragraph role="paragraph" id="par_id71621894831448">Returns <literal>True</literal> when A is found in B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897203344"> + <input>svc.AssertIn(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428677632">This assertion assumes the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428688858" role="listitem">Expression B may be a 1D array, a ScriptForge <literal>Dictionary</literal> object or a string.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286454219" role="listitem">When expression B is a 1D array, expression A may be a date or a numeric value.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id51656678140228" role="listitem">When expression B is a ScriptForge <literal>Dictionary</literal> object, then string A is searched for among the keys in B.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428663299" role="listitem">String comparisons are case-sensitive.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertIsInstance"> + <comment> AssertIsInstance --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919963087"> + <bookmark_value>UnitTest service;AssertIsInstance</bookmark_value> + </bookmark> + <h2 id="hd_id201589199666212" localize="false">AssertIsInstance</h2> + <paragraph role="paragraph" id="par_id71621894831399">Returns <literal>True</literal> when A is an instance of a specified object type, specified as a string containing the type name.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897201284"> + <input>svc.AssertIsInstance(a: any, objecttype: str, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428676302">Expression A may be one of the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428676428" role="listitem">A ScriptForge object. In this case, the <literal>objecttype</literal> argument is a string such as "DICTIONARY", "calc", "Dialog", etc.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286456619" role="listitem">A UNO object. In this case, the <literal>objecttype</literal> argument must be a string identical to the value returned by the <literal>SF_Session.UnoObjectType()</literal> method.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428680559" role="listitem">An Array. In this case, the <literal>objecttype</literal> argument is expected to be "array".</paragraph> + </listitem> + <listitem> + <paragraph id="par_id891656439858783" role="listitem">Any other variable (neither an <literal>Object</literal> nor an <literal>Array</literal>). In this case, <literal>objecttype</literal> is a string matching the value returned by the builtin <literal>TypeName</literal> function.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertIsNothing"> + <comment> AssertIsNothing ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919936404"> + <bookmark_value>UnitTest service;AssertIsNothing</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693766" localize="false">AssertIsNothing</h2> + <paragraph role="paragraph" id="par_id71621894830197">Returns <literal>True</literal> when A is an object that has the <literal>Nothing</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897221145"> + <input>svc.AssertIsNothing(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="AssertIsNull"> + <comment> AssertIsNull ------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969366"> + <bookmark_value>UnitTest service;AssertIsNull</bookmark_value> + </bookmark> + <h2 id="hd_id201589199693825" localize="false">AssertIsNull</h2> + <paragraph role="paragraph" id="par_id71621894863251">Returns <literal>True</literal> when A has the <literal>Null</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897202545"> + <input>svc.AssertIsNull(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="AssertLess"> + <comment> AssertLess --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919964338"> + <bookmark_value>UnitTest service;AssertLess</bookmark_value> + </bookmark> + <h2 id="hd_id201589199663022" localize="false">AssertLess</h2> + <paragraph role="paragraph" id="par_id71621894838018">Returns <literal>True</literal> when A is less than B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id59162189726574"> + <input>svc.AssertLess(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428672332">The comparison between A and B assumes the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428689311" role="listitem">Eligible data types are <literal>String</literal>, <literal>Date</literal> or numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286265809" role="listitem">Both expressions must have the same <literal>VarType</literal> or both must be numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428660996" role="listitem">String comparisons are case-sensitive.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertLessEqual"> + <comment> AssertLessEqual ---------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919964174"> + <bookmark_value>UnitTest service;AssertLessEqual</bookmark_value> + </bookmark> + <h2 id="hd_id201589199661992" localize="false">AssertLessEqual</h2> + <paragraph role="paragraph" id="par_id71621894208818">Returns <literal>True</literal> when A is less than or equal to B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id59162189720864"> + <input>svc.AssertLessEqual(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id991656428606322">The comparison between A and B assumes the following:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id591656428682251" role="listitem">Eligible data types are <literal>String</literal>, <literal>Date</literal> or numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id516564286265711" role="listitem">Both expressions must have the same <literal>VarType</literal> or both must be numeric.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id211656428660176" role="listitem">String comparisons are case-sensitive.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertLike"> + <comment> AssertLike --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919968226"> + <bookmark_value>UnitTest service;AssertLike</bookmark_value> + </bookmark> + <h2 id="hd_id201589199611825" localize="false">AssertLike</h2> + <paragraph role="paragraph" id="par_id71621894862651">Returns <literal>True</literal> if string A matches a given pattern containing wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897207315"> + <input>svc.AssertLike(a: any, pattern: str = "", message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id51656446203238">The following wildcards are accepted:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id661656446233484" role="listitem">? - Represents any single character.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id681656446233831" role="listitem">* - Represents zero, one, or multiple characters.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertNotAlmostEqual"> + <comment> AssertNotAlmostEqual ----------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919665187"> + <bookmark_value>UnitTest service;AssertNotAlmostEqual</bookmark_value> + </bookmark> + <h2 id="hd_id2015891996638414" localize="false">AssertNotAlmostEqual</h2> + <paragraph role="paragraph" id="par_id71621894832641">Returns <literal>True</literal> when <emph>A</emph> and <emph>B</emph> are numerical values and are <emph>not</emph> considered to be close to each other, given a relative tolerance.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id5916218972331205"> + <input>svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id241656426317970">This assertion returns <literal>True</literal> if the two conditions below are met:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id861656426361686" role="listitem">A and B can be converted to the <literal>Double</literal> type.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id851656426332052" role="listitem">The absolute difference between A and B divided by the largest absolute value of A or B is <emph>greater</emph> than the value specified in <literal>tolerance</literal>.</paragraph> + </listitem> + </list> + </section> + + <section id="AssertNotEqual"> + <comment> AssertNotEqual ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919961047"> + <bookmark_value>UnitTest service;AssertNotEqual</bookmark_value> + </bookmark> + <h2 id="hd_id2015891996963410" localize="false">AssertNotEqual</h2> + <paragraph role="paragraph" id="par_id71621894862842">Returns <literal>True</literal> when <emph>A</emph> and <emph>B</emph> are <emph>not</emph> considered to be equal.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897227497"> + <input>svc.AssertNotEqual(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id581656446598206">This method works both for scalars and arrays. Read the instructions in <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertEqual" name="AssertEqual"><literal>AssertEqual</literal></link> for more information on what equality means in this assertion.</paragraph> + </section> + + <section id="AssertNotIn"> + <comment> AssertNotIn -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919932358"> + <bookmark_value>UnitTest service;AssertNotIn</bookmark_value> + </bookmark> + <h2 id="hd_id201589199617409" localize="false">AssertNotIn</h2> + <paragraph role="paragraph" id="par_id71621894832638">Returns <literal>True</literal> when A (a string) is <emph>not</emph> found in B.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897212544"> + <input>svc.AssertNotIn(a: any, b: any, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id271656446302516">Read the instructions in <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIn" name="AssertIn"><literal>AssertIn</literal></link> for more information on the assumptions of this method.</paragraph> + </section> + + <section id="AssertNotInstance"> + <comment> AssertNotInstance -------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919963186"> + <bookmark_value>UnitTest service;AssertNotInstance</bookmark_value> + </bookmark> + <h2 id="hd_id201589199676312" localize="false">AssertNotInstance</h2> + <paragraph role="paragraph" id="par_id71621894831403">Returns <literal>True</literal> when A is <emph>not</emph> an instance of a specified object type.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897136284"> + <input>svc.AssertNotInstance(a: any, objecttype: str, message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id271656446949396">Read the instructions in <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertIsInstance" name="AssertIsInstance"><literal>AssertIsInstance</literal></link> for more information on the assumptions of this method.</paragraph> + </section> + + <section id="AssertNotLike"> + <comment> AssertNotLike ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919967256"> + <bookmark_value>UnitTest service;AssertNotLike</bookmark_value> + </bookmark> + <h2 id="hd_id201589199612225" localize="false">AssertNotLike</h2> + <paragraph role="paragraph" id="par_id71621894863961">Returns <literal>True</literal> if string A <emph>does not</emph> match a given pattern containing wildcards.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897237415"> + <input>svc.AssertNotLike(a: any, pattern: str = "", message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id271656446258396">Read the instructions in <link href="text/sbasic/shared/03/sf_unittest.xhp#AssertLike" name="AssertLike"><literal>AssertLike</literal></link> for more information on the assumptions of this method.</paragraph> + </section> + + <section id="AssertNotNothing"> + <comment> AssertNotNothing --------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158914467256"> + <bookmark_value>UnitTest service;AssertNotNothing</bookmark_value> + </bookmark> + <h2 id="hd_id201589199743855" localize="false">AssertNotNothing</h2> + <paragraph role="paragraph" id="par_id71621894420261">Returns <literal>True</literal> except when A is an object that has the <literal>Nothing</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621843337415"> + <input>svc.AssertNotNothing(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="AssertNotNull"> + <comment> AssertNotNull ------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919966555"> + <bookmark_value>UnitTest service;AssertNotNull</bookmark_value> + </bookmark> + <h2 id="hd_id201589199602825" localize="false">AssertNotNull</h2> + <paragraph role="paragraph" id="par_id71621894876551">Returns <literal>True</literal> except when A has the <literal>Null</literal> value.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621897223945"> + <input>svc.AssertNotNull(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="AssertNotRegex"> + <comment> AssertNotRegex ----------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919964125"> + <bookmark_value>UnitTest service;AssertNotRegex</bookmark_value> + </bookmark> + <h2 id="hd_id201589199602432" localize="false">AssertNotRegex</h2> + <paragraph role="paragraph" id="par_id71621894860331">Returns <literal>True</literal> when A is <emph>not</emph> a string or <emph>does not</emph> match the given regular expression.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621898163945"> + <input>svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id931656448163772">The comparison is case-sensitive.</paragraph> + </section> + + <section id="AssertRegex"> + <comment> AssertRegex -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919933525"> + <bookmark_value>UnitTest service;AssertRegex</bookmark_value> + </bookmark> + <h2 id="hd_id201589199601132" localize="false">AssertRegex</h2> + <paragraph role="paragraph" id="par_id71621894836031">Returns <literal>True</literal> when string A matches the given regular expression.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621898142945"> + <input>svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool</input> + </paragraph> + <paragraph role="paragraph" id="par_id931656448163625">The comparison is case-sensitive.</paragraph> + </section> + + <section id="AssertTrue"> + <comment> AssertTrue --------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919986595"> + <bookmark_value>UnitTest service;AssertTrue</bookmark_value> + </bookmark> + <h2 id="hd_id20158919962312" localize="false">AssertTrue</h2> + <paragraph role="paragraph" id="par_id71621894063449">Returns <literal>True</literal> when expression A is a <literal>Boolean</literal> and its value is <literal>True</literal>.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621898125645"> + <input>svc.AssertTrue(a: any, message: str = ""): bool</input> + </paragraph> + </section> + + <section id="Fail"> + <comment> Fail --------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919986595"> + <bookmark_value>UnitTest service;Fail</bookmark_value> + </bookmark> + <h2 id="hd_id20158919736312" localize="false">Fail</h2> + <paragraph role="paragraph" id="par_id71621894086431">Forces a test case to fail.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621890114545"> + <input>svc.Fail(message: str = "")</input> + </paragraph> + <paragraph role="paragraph" id="par_id751656448550854">A message can be provided to be reported in the console.</paragraph> + </section> + + <section id="Log"> + <comment> Log ---------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919986595"> + <bookmark_value>UnitTest service;Log</bookmark_value> + </bookmark> + <h2 id="hd_id20158919909612" localize="false">Log</h2> + <paragraph role="paragraph" id="par_id71621894063631">Writes the specified <literal>message</literal> in the console.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621898149545"> + <input>svc.Log(message: str = "")</input> + </paragraph> + <paragraph role="paragraph" id="par_id751656448510894">A message can be provided to be reported in the console.</paragraph> + </section> + + <section id="ReportError"> + <comment> ReportError -------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919949695"> + <bookmark_value>UnitTest service;ReportError</bookmark_value> + </bookmark> + <h2 id="hd_id20158919658972" localize="false">ReportError</h2> + <paragraph role="paragraph" id="par_id71621894199311">Displays a message box with a message and the current property values of the <literal>Exception</literal> service.</paragraph> + <paragraph role="paragraph" id="par_id851656622819891">This method is commonly used in the exception handling section of the <literal>Sub</literal> containing the test case, which is reached when an assertion fails or when the <literal>Fail</literal> method is called.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591639698323545"> + <input>svc.ReportError(message: str = "")</input> + </paragraph> + <paragraph role="paragraph" id="par_id291656448892783">Depending on the value of the property <literal>WhenAssertionFails</literal>, the test execution may continue or be interrupted.</paragraph> + <paragraph role="paragraph" id="par_id551656448951538">When writing test cases it is recommended to include a call to the <literal>ReportError</literal> method in the exception handling section of the <literal>Sub</literal>.</paragraph> + <paragraph role="paragraph" id="par_id711656449128572">If the property <literal>LongMessage</literal> is equal to <literal>True</literal>, the specified <literal>message</literal> is followed by the standard error message description. Otherwise only the <literal>message</literal> is displayed.</paragraph> + </section> + + <section id="RunTest"> + <comment> RunTest ------------------------------------------------------------------------------------------------ </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919984145"> + <bookmark_value>UnitTest service;RunTest</bookmark_value> + </bookmark> + <h2 id="hd_id20158919960992" localize="false">RunTest</h2> + <paragraph role="paragraph" id="par_id71621894063361">Executes the complete test suite implemented in the specified module. Each test case is run independently from each other.</paragraph> + <paragraph role="paragraph" id="par_id201656449688023">Running a test suite consists of:</paragraph> + <list type="ordered"> + <listitem> + <paragraph id="par_id751656449718279" role="listitem">Executing the optional <literal>Setup</literal> method present in the module.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id611656449718505" role="listitem">Executing once each test case, in no specific order.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id461656449718687" role="listitem">Executing the optional <literal>TearDown</literal> method present in the module.</paragraph> + </listitem> + </list> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591621898140525"> + <input>svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int</input> + </paragraph> + <paragraph role="paragraph" id="par_id751656448521144">The argument <literal>testcasepattern</literal> specifies a pattern composed of "?" and "*" wildcards to select which test cases will be run. The comparison is not case-sensitive.</paragraph> + <paragraph role="paragraph" id="par_id81656448858455">If a <literal>message</literal> is provided, it is written to the console when the test starts.</paragraph> + </section> + + <section id="SkipTest"> + <comment> SkipTest ----------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919949695"> + <bookmark_value>UnitTest service;SkipTest</bookmark_value> + </bookmark> + <h2 id="hd_id20158919952512" localize="false">SkipTest</h2> + <paragraph role="paragraph" id="par_id71621894064311">Interrupts the running test suite without calling the <literal>TearDown</literal> method.</paragraph> + <paragraph role="paragraph" id="par_id781656450313544">Skipping a test is usually meaningful during the <literal>Setup</literal> method when not all conditions to run the test are met.</paragraph> + <paragraph role="paragraph" id="par_id531656450405799">It is up to the <literal>Setup</literal> method to exit the <literal>Sub</literal> shortly after the <literal>SkipTest</literal> call.</paragraph> + <paragraph role="paragraph" id="par_id581656450504005">If <literal>SkipTest</literal> is called from within a test case, the execution of the test suite is interrupted and the remaining test cases are not run. Keep in mind that the order in which test cases are run is arbitrary within a test suite.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id591639698149545"> + <input>svc.SkipTest(message: str = "")</input> + </paragraph> + <paragraph role="paragraph" id="par_id81656449618455">If a <literal>message</literal> is provided, it is written to the console.</paragraph> + </section> + + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_exception.xhp#ExceptionService"/> + </section> +</body> +</helpdocument> diff --git a/helpcontent2/source/text/sbasic/shared/03/sf_writer.xhp b/helpcontent2/source/text/sbasic/shared/03/sf_writer.xhp new file mode 100644 index 000000000..d4ea1bdfc --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/03/sf_writer.xhp @@ -0,0 +1,189 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * +--> + +<meta> + <topic id="sf_writer" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">SFDocuments.Writer service</title> + <filename>/text/sbasic/shared/03/sf_writer.xhp</filename> + </topic> +</meta> + +<body> +<section id="SFDocuments-sf_writer"> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id261582733781987"> + <bookmark_value>Writer service</bookmark_value> + </bookmark> +</section> + +<section id="abstract"> + <h1 id="hd_id731582733781114" xml-lang="en-US"><variable id="WriterService"><link href="text/sbasic/shared/03/sf_writer.xhp" name="Writer service"><literal>SFDocuments</literal>.<literal>Writer</literal> service</link></variable></h1> + <paragraph role="paragraph" id="par_id381589189355849" xml-lang="en-US">The <literal>SFDocuments</literal> shared library provides a number of methods and properties to facilitate the management and handling of %PRODUCTNAME documents.</paragraph> + <paragraph role="paragraph" id="par_id351591014177269" xml-lang="en-US">Some methods are generic for all types of documents and are inherited from the <literal>SF_Document</literal> module, whereas other methods that are specific for Writer documents are defined in the <literal>SF_Writer</literal> module.</paragraph> + <comment>To be done: list with the main features of the Writer service.</comment> +</section> + + <h2 id="hd_id581582885621841">Service invocation</h2> + <paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Writer</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph> + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/> + + <paragraph role="paragraph" id="par_id591589191059889" xml-lang="en-US">The <literal>Writer</literal> service is closely related to the <literal>UI</literal> service of the <literal>ScriptForge</literal> library. Below are a few examples of how the <literal>Writer</literal> service can be invoked.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <paragraph role="paragraph" id="par_id551621623999947">The code snippet below creates a <literal>Writer</literal> service instance that corresponds to the currently active Writer document.</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id651631197152830">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id431621624078370">Set oDoc = CreateScriptService("SFDocuments.Writer", "Untitled 1") ' Default = ActiveWindow</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id341621467500466">Another way to create an instance of the <literal>Writer</literal> service is using the <literal>UI</literal> service. In the following example, a new Writer document is created and <literal>oDoc</literal> is a <literal>Writer</literal> service instance:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim ui As Object, oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id201582885621287">Set ui = CreateScriptService("UI")</paragraph> + <paragraph role="bascode" localize="false" id="bas_id561589191748697">Set oDoc = ui.CreateDocument("Writer")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id921621467621019">Or using the <literal>OpenDocument</literal> method from the <literal>UI</literal> service:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id671621467660766">Set oDoc = ui.OpenDocument("C:\Me\MyFile.odt")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id741621467697967">It is also possible to instantiate the <literal>Writer</literal> service using the <literal>CreateScriptService</literal> method:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id371589191782045">Dim oDoc As Object</paragraph> + <paragraph role="bascode" localize="false" id="bas_id711589191788959">Set oDoc = CreateScriptService("SFDocuments.Writer", "MyFile.odt")</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id271621467810774">In the example above, "MyFile.odt" is the name of an open document window. If this argument is not provided, the active window is considered.</paragraph> + <paragraph role="paragraph" id="par_id71158288562139" xml-lang="en-US">It is recommended to free resources after use:</paragraph> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id61582733781413">Set oDoc = oDoc.Dispose()</paragraph> + </bascode> + <paragraph role="paragraph" id="par_id231611610666018">However, if the document was closed using the <literal>CloseDocument</literal> method, it becomes unnecessary to free resources using the command described above.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id911621624242302">myDoc = CreateScriptService("Writer") ' Default = ActiveWindow</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id201621531742824">ui = CreateScriptService("UI")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id661621531772444">myDoc = ui.CreateDocument("Writer")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id401621531828705">myDoc = ui.OpenDocument(r"C:\Documents\MyFile.odt")</paragraph> + </pycode> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id701621532481401">myDoc = CreateScriptService("SFDocuments.Writer", "MyFile.odt")</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id951621532568918">myDoc.Dispose()</paragraph> + </pycode> + <tip id="par_id71611090922315">The use of the prefix "<literal>SFDocuments.</literal>" while calling the service is optional.</tip> + + <h2 id="hd_id291631196803182">Definitions</h2> + <comment>TBD</comment> + + <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2> + + <h2 id="hd_id501582887473754" xml-lang="en-US">Methods</h2> + <table id="tab_id501611613601554"> + <tablerow> + <tablecell colspan="3"><paragraph id="par_id891611613601554" role="tablehead" xml-lang="en-US">List of Methods in the Writer Service</paragraph></tablecell> + </tablerow> + <tablerow> + <tablecell> + <paragraph id="par_id891611613601556" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_writer.xhp#Forms" name="Forms method">Forms</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id541611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_writer.xhp#PrintOut" name="PrintOut method">PrintOut</link><br/> + </paragraph> + </tablecell> + <tablecell> + <paragraph id="par_id701611613601554" role="tablecontent" localize="false"> + <link href="text/sbasic/shared/03/sf_writer.xhp#MoveRange" name="MoveRange method">…</link><br/> + </paragraph> + </tablecell> + </tablerow> + </table> + +<section id="Forms"> + <comment> Forms --------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id721589200121336"> + <bookmark_value>Document service;Forms</bookmark_value> + </bookmark> + <h2 id="hd_id261589200120884" localize="false">Forms</h2> + <paragraph role="paragraph" id="par_id501623063693649">Depending on the parameters provided this method will return:</paragraph> + <list type="unordered"> + <listitem> + <paragraph id="par_id611623063742045" role="listitem">A zero-based Array (or a tuple in Python) with the names of all the forms contained in the document (if the <literal>form</literal> argument is absent)</paragraph> + </listitem> + <listitem> + <paragraph id="par_id641623063744536" role="listitem">A <literal>SFDocuments.Form</literal> service instance representing the form specified as argument.</paragraph> + </listitem> + </list> + <note id="par_id821623076570573">This method is applicable only for Writer documents. Calc and Base documents have their own <literal>Forms</literal> method in the <link href="text/sbasic/shared/03/sf_calc.xhp#Forms" name="Calc_Forms">Calc</link> and <link href="text/sbasic/shared/03/sf_base.xhp#Forms" name="Base_Forms">Base</link> services, respectively.</note> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id371623063588699"> + <input>svc.Forms(): str[0..*]</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id471623151738791"> + <input>svc.Forms(form: str = ''): svc</input> + </paragraph> + <paragraph role="paragraph" localize="false" id="par_id751623151751397"> + <input>svc.Forms(form: int): svc</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id451623063459286"><emph>form</emph>: The name or index corresponding to a form stored in the document. If this argument is absent, the method will return a list with the names of all forms available in the document.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <paragraph role="paragraph" id="par_id251623063305557">In the following examples, the first line gets the names of all forms in the document and the second line retrieves the <literal>Form</literal> object of the form named "Form_A".</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id191623063399519">Set FormNames = oDoc.Forms()</paragraph> + <paragraph role="bascode" localize="false" id="bas_id691623063399711">Set FormA = oDoc.Forms("Form_A")</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id271623063215023">form_names = doc.Forms()</paragraph> + <paragraph role="pycode" localize="false" id="pyc_id961623063234990">form_A = doc.Forms("Form_A")</paragraph> + </pycode> +</section> + +<section id="PrintOut"> + <comment> PrintOut -------------------------------------------------------------------------------------------------------------------------- </comment> + <bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id231592919577434"> + <bookmark_value>Writer service;PrintOut</bookmark_value> + </bookmark> + <h2 id="hd_id921592919577158" localize="false">PrintOut</h2> + <paragraph role="paragraph" id="par_id31592919577984">Send the contents of the document to the printer. The printer may be previously defined by default, by the user or by the <link href="text/sbasic/03/sf_document.xhp#SetPrinter" name="SetPrinter method"><literal>SetPrinter</literal></link> method of the <link href="text/sbasic/03/sf_document.xhp" name="Document service">Document</link> service. Returns <literal>True</literal> when successful.</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/> + <paragraph role="paragraph" localize="false" id="par_id441621534763020"> + <input>svc.PrintOut(opt pages: str = "", opt copies: num = 1, opt printbackground: bool = True, opt printblankpages: bool = False, opt printevenpages: bool = True, opt printoddpages: bool = True, opt printimages: bool = True): bool</input> + </paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functparameters"/> + <paragraph role="paragraph" id="par_id441592919577809"><emph>pages</emph>: The pages to print as a string, like in the user interface. Example: "1-4;10;15-18". Default = all pages</paragraph> + <paragraph role="paragraph" id="par_id221636020923278"><emph>copies</emph>: The number of copies, default is 1.</paragraph> + <paragraph role="paragraph" id="par_id121636020926764"><emph>printbackground</emph>: Prints the background image when <literal>True</literal> (default).</paragraph> + <paragraph role="paragraph" id="par_id261636020927276"><emph>printblankpages</emph>: When <literal>False</literal> (default), omits empty pages.</paragraph> + <paragraph role="paragraph" id="par_id021636020927484"><emph>printevenpages</emph>: Prints even pages when <literal>True</literal> (default).</paragraph> + <paragraph role="paragraph" id="par_id391636020927676"><emph>printoddpages</emph>: Print odd pages when <literal>True</literal> (default).</paragraph> + <paragraph role="paragraph" id="par_id121636021103996"><emph>printimages</emph>: Print graphic objects when <literal>True</literal> (default).</paragraph> + <embed href="text/sbasic/shared/00000003.xhp#functexample"/> + <embed href="text/sbasic/shared/00000003.xhp#In_Basic"/> + <bascode> + <paragraph role="bascode" localize="false" id="bas_id521592919577626">oDoc.PrintOut("1-4;10;15-18", Copies := 2, PrintImages := False)</paragraph> + </bascode> + <embed href="text/sbasic/shared/00000003.xhp#In_Python"/> + <pycode> + <paragraph role="pycode" localize="false" id="pyc_id211621536212144">doc.PrintOut(printblankpages = True, copies = 3)</paragraph> + </pycode> +</section> + + <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/> + <section id="relatedtopics"> + <embed href="text/sbasic/shared/03/sf_document.xhp#DocumentService"/> + <embed href="text/sbasic/shared/03/sf_ui.xhp#UIService"/> + </section> +</body> +</helpdocument> |