source/text/sbasic/shared/03/sf_calc.xhp | 382 ++++++++++++++++++++++++++++---
1 file changed, 346 insertions(+), 36 deletions(-)
New commits:
commit b838d04091f125a13302519807040ce43652d5ba
Author: Rafael Lima <rafael.palma.l...@gmail.com>
AuthorDate: Fri Nov 26 18:46:46 2021 +0200
Commit: Rafael Lima <rafael.palma.l...@gmail.com>
CommitDate: Tue Nov 30 19:38:43 2021 +0100
Document new SF_Calc methods
This patch documents the following new methods:
- OpenRangeSelector, Printf, ShiftDown, ShiftLeft, ShiftRight, ShiftUp
The following new properties were added:
- FirstCell, FirstColumn, FirstRow
Change-Id: I9803252ec0594bd202fc689dd16ca57541e94e62
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/125890
Tested-by: Jenkins
Reviewed-by: Rafael Lima <rafael.palma.l...@gmail.com>
diff --git a/source/text/sbasic/shared/03/sf_calc.xhp
b/source/text/sbasic/shared/03/sf_calc.xhp
index 7c7148cb4..fa3004bc4 100644
--- a/source/text/sbasic/shared/03/sf_calc.xhp
+++ b/source/text/sbasic/shared/03/sf_calc.xhp
@@ -26,8 +26,8 @@
<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">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 Calc documents are defined in the
<literal>SF_Calc</literal> module.</paragraph>
- <paragraph role="paragraph" id="par_id591589189364267"
xml-lang="en-US">The <literal>SF_Calc</literal> module is focused
on:</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>
@@ -40,6 +40,7 @@
</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_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>
@@ -209,7 +210,7 @@
<paragraph id="par_id221591018408168" role="tablehead"
xml-lang="en-US">Argument</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id31582885195238" role="tablehead"
xml-lang="en-US">Type</paragraph>
+ <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>
@@ -229,7 +230,58 @@
<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>
+ <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>
@@ -246,58 +298,58 @@
<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>
+ <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" role="tablecontent"
xml-lang="en-US" localize="false">LastCell</paragraph>
+ <paragraph id="par_id97158288519551" localize="false"
role="tablecontent">LastCell</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id221582885195686" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ <paragraph id="par_id221582885195686"
role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id501591018870619" role="tablecontent"
xml-lang="en-US">SheetName As String</paragraph>
+ <paragraph id="par_id501591018870619"
role="tablecontent">SheetName or RangeName as String</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id371582885195525" role="tablecontent"
xml-lang="en-US" localize="false">String</paragraph>
+ <paragraph id="par_id371582885195525" localize="false"
role="tablecontent">String</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id881582885195976" role="tablecontent"
xml-lang="en-US">The last used cell in 'A1' format in the given
sheet</paragraph>
+ <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" role="tablecontent"
xml-lang="en-US" localize="false">LastColumn</paragraph>
+ <paragraph id="par_id261592315106411" localize="false"
role="tablecontent">LastColumn</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id601592315106598" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ <paragraph id="par_id601592315106598"
role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id831592315106202" role="tablecontent"
xml-lang="en-US">SheetName As String</paragraph>
+ <paragraph id="par_id831592315106202"
role="tablecontent">SheetName or RangeName as String</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id591592315106615" role="tablecontent"
xml-lang="en-US" localize="false">Long</paragraph>
+ <paragraph id="par_id591592315106615" localize="false"
role="tablecontent">Long</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id791592315106790" role="tablecontent"
xml-lang="en-US">The last used column in the given sheet</paragraph>
+ <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" role="tablecontent"
xml-lang="en-US" localize="false">LastRow</paragraph>
+ <paragraph id="par_id801591025591570" localize="false"
role="tablecontent">LastRow</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id981591025591597" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ <paragraph id="par_id981591025591597"
role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id81591025591696" role="tablecontent"
xml-lang="en-US">SheetName As String</paragraph>
+ <paragraph id="par_id81591025591696" role="tablecontent">SheetName
or RangeName as String</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id61591025591572" role="tablecontent"
xml-lang="en-US" localize="false">Long</paragraph>
+ <paragraph id="par_id61591025591572" localize="false"
role="tablecontent">Long</paragraph>
</tablecell>
<tablecell>
- <paragraph id="par_id421591025591509" role="tablecontent"
xml-lang="en-US">The last used row in the given sheet</paragraph>
+ <paragraph id="par_id421591025591509" role="tablecontent">The last
used row in a given range or sheet.</paragraph>
</tablecell>
</tablerow>
<tablerow>
@@ -314,7 +366,7 @@
<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>
+ <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>
@@ -331,7 +383,7 @@
<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 <keycode>Ctrl + *</keycode> shortcut to the
given range.</paragraph>
+ <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>
@@ -348,7 +400,7 @@
<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>
+ <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>
@@ -365,7 +417,7 @@
<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>
+ <paragraph id="par_id491591025591370" role="tablecontent"
xml-lang="en-US">The list with the names of all existing sheets.</paragraph>
</tablecell>
</tablerow>
<tablerow>
@@ -382,7 +434,7 @@
<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>
+ <paragraph id="par_id681593095062358" role="tablecontent"
xml-lang="en-US">The number of columns (>= 1) in the given range.</paragraph>
</tablecell>
</tablerow>
<tablerow>
@@ -399,7 +451,7 @@
<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>
+ <paragraph id="par_id321592315404430" role="tablecontent"
xml-lang="en-US">A <literal>com.sun.star.Table.XCellRange</literal> UNO
object.</paragraph>
</tablecell>
</tablerow>
<tablerow>
@@ -433,7 +485,7 @@
<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>
+ <paragraph id="par_id41592315560095" role="tablecontent"
xml-lang="en-US">A <literal>com.sun.star.sheet.XSpreadsheet</literal> UNO
object.</paragraph>
</tablecell>
</tablerow>
</table>
@@ -459,13 +511,13 @@
<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#DAvg" name="DAvg
method">DAvg</link><br/>
+ <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/>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id541611613601554" role="tablecontent"
localize="false">
- <link href="text/sbasic/shared/03/sf_calc.xhp#DAvg" name="DAvg
method">DAvg</link><br/>
- <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#Forms" name="Forms
method">Forms</link><br/>
@@ -474,22 +526,28 @@
<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/>
- </paragraph>
- </tablecell>
- <tablecell>
- <paragraph id="par_id701611613601554" role="tablecontent"
localize="false">
<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/>
+ <link href="text/sbasic/shared/03/sf_calc.xhp#OpenRangeSelector"
name="OpenRangeSelector method">OpenRangeSelector</link><br/><br/>
+ </paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id701611613601554" role="tablecontent"
localize="false">
<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#SortRange"
name="SortRange method">SortRange</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>
@@ -1205,7 +1263,7 @@
</section>
<section id="Offset">
- <comment> Offset
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <comment> Offset
------------------------------------------------------------------------------------------------
</comment>
<bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id29159223350681">
<bookmark_value>Calc service;Offset</bookmark_value>
</bookmark>
@@ -1239,6 +1297,109 @@
</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">
@@ -1472,6 +1633,155 @@
</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>wholerows</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>wholecolumns</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>wholerows</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>wholecolumns</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">
