source/text/sbasic/shared/01020300.xhp | 164 ++++++++++++++++++--------------- source/text/sbasic/shared/property.xhp | 2 2 files changed, 92 insertions(+), 74 deletions(-)
New commits: commit 74fc09527478fff86496efdac55f3d6d339b8537 Author: LibreOfficiant <libreoffici...@sfr.fr> AuthorDate: Mon Feb 24 14:36:11 2020 +0100 Commit: Olivier Hallot <olivier.hal...@libreoffice.org> CommitDate: Wed Mar 18 12:57:56 2020 +0100 o Property statement added in Procedures & Functions help o Multiple layout changes Note: Optional keyword to be referenced later in above help o ByVal/ByRef added to Property help page Change-Id: I30e84c1e7464b4bc101727d2d088a35173f74b34 Reviewed-on: https://gerrit.libreoffice.org/c/help/+/89282 Tested-by: Jenkins Reviewed-by: Olivier Hallot <olivier.hal...@libreoffice.org> diff --git a/source/text/sbasic/shared/01020300.xhp b/source/text/sbasic/shared/01020300.xhp index d3d1dd08e..5db47968d 100644 --- a/source/text/sbasic/shared/01020300.xhp +++ b/source/text/sbasic/shared/01020300.xhp @@ -17,23 +17,18 @@ * except in compliance with the License. You may obtain a copy of * the License at http://www.apache.org/licenses/LICENSE-2.0 . --> - <meta> <topic id="textsbasicshared01020300xml" indexer="include" status="PUBLISH"> - <title id="tit" xml-lang="en-US">Using Procedures and Functions</title> + <title id="tit" xml-lang="en-US">Using Procedures, Functions or Properties</title> <filename>/text/sbasic/shared/01020300.xhp</filename> </topic> </meta> - <body> - - -<section id="prozedur"> <bookmark xml-lang="en-US" branch="index" id="bm_id3149456"> <bookmark_value>procedures</bookmark_value> <bookmark_value>functions;using</bookmark_value> - <bookmark_value>variables;passing to procedures and functions</bookmark_value> - <bookmark_value>parameters;for procedures and functions</bookmark_value> + <bookmark_value>variables;passing to procedures, functions, properties</bookmark_value> + <bookmark_value>parameters;for procedures, functions or properties</bookmark_value> <bookmark_value>parameters;passing by reference or value</bookmark_value> <bookmark_value>variables;scope</bookmark_value> <bookmark_value>scope of variables</bookmark_value> @@ -43,57 +38,77 @@ <bookmark_value>functions;return value type</bookmark_value> <bookmark_value>return value type of functions</bookmark_value> </bookmark> - - -<paragraph id="hd_id3149456" role="heading" level="1" xml-lang="en-US"><link href="text/sbasic/shared/01020300.xhp">Using Procedures and Functions</link></paragraph> -<paragraph id="par_id3150767" role="paragraph" xml-lang="en-US">The following describes the basic use of procedures and functions in $[officename] Basic.</paragraph> +<section id="prozedur"> +<h1 id="hd_id3149456"><link href="text/sbasic/shared/01020300.xhp">Using Procedures, Functions and Properties</link></h1> +<paragraph id="par_id3150767" role="paragraph">The following describes the basic use of procedures, functions and properties in %PRODUCTNAME Basic.</paragraph> </section> -<paragraph id="par_id3151215" role="note" xml-lang="en-US">When you create a new module, $[officename] Basic automatically inserts a SUB called "Main". This default name has nothing to do with the order or the starting point of a $[officename] Basic project. You can also safely rename this SUB.</paragraph> -<paragraph id="par_id314756320" role="note" xml-lang="en-US">Some restrictions apply for the names of your public variables, subs, and functions. You must not use the same name as one of the modules of the same library.</paragraph> -<paragraph id="par_id3154124" role="paragraph" xml-lang="en-US">Procedures (SUBS) and functions (FUNCTIONS) help you maintaining a structured overview by separating a program into logical pieces.</paragraph> -<paragraph id="par_id3153193" role="paragraph" xml-lang="en-US">One benefit of procedures and functions is that, once you have developed a program code containing task components, you can use this code in another project.</paragraph> - -<paragraph id="hd_id3153770" role="heading" level="2" xml-lang="en-US">Passing Variables to Procedures (SUB) and Functions (FUNCTION)</paragraph> -<paragraph id="par_id3155414" role="paragraph" xml-lang="en-US">Variables can be passed to both procedures and functions. The SUB or FUNCTION must be declared to expect parameters:</paragraph> +<note id="par_id3151215">When you create a new module, %PRODUCTNAME Basic automatically inserts a <literal>Sub</literal> called "<literal>Main</literal>". This default name has nothing to do with the order or the starting point of a %PRODUCTNAME Basic project. You can also safely rename this <literal>Sub</literal>routine.</note> +<note id="par_id314756320">Some restrictions apply for the names of your public variables, subroutines, functions and properties. You must not use the same name as one of the modules of the same library.</note> +<paragraph id="par_id3154124" role="paragraph" xml-lang="en-US">Procedures (<literal>Sub</literal>routines) functions (<literal>Function</literal>) and properties (<literal>Property</literal>) help you maintaining a structured overview by separating a program into logical pieces.</paragraph> +<paragraph id="par_id3153193" role="paragraph" xml-lang="en-US">One benefit of procedures, functions and properties is that, once you have developed a program code containing task components, you can use this code in another project.</paragraph> +<h2 id="hd_id3153770">Passing Variables to Procedures, Functions or Properties</h2> +<paragraph id="par_id3155414" role="paragraph" xml-lang="en-US">Variables can be passed to both procedures, functions or properties. The <literal>Sub</literal> <literal>Function</literal> or <literal>Property</literal> must be declared to expect parameters:</paragraph> <bascode> -<paragraph id="par_idm1340846688" role="bascode" localize="false" xml-lang="en-US">Sub SubName(Parameter1 As Type, Parameter2 As Type,...)</paragraph> -<paragraph id="par_id3151114" role="bascode" xml-lang="en-US">Program code</paragraph> -<paragraph id="par_idm1340843712" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph> + <paragraph id="par_idm1340846688" role="bascode" localize="false">Sub SubName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...)</paragraph> + <paragraph id="par_id3151114" role="bascode" xml-lang="en-US"> ' your code goes here</paragraph> + <paragraph id="par_idm1340843712" role="bascode" localize="false">End Sub</paragraph> </bascode> -<paragraph id="par_id3152577" role="paragraph" xml-lang="en-US">The SUB is called using the following syntax:</paragraph> +<paragraph id="par_id3152577" role="paragraph" xml-lang="en-US">The <literal>Sub</literal> is called using the following syntax:</paragraph> <bascode> -<paragraph id="par_idm1341029952" role="bascode" localize="false" xml-lang="en-US">SubName(Value1, Value2,...)</paragraph> + <paragraph id="par_idm1341029952" role="bascode" localize="false" xml-lang="en-US">SubName(Value1, Value2,...)</paragraph> </bascode> -<paragraph id="par_id3147124" role="paragraph" xml-lang="en-US">The parameters passed to a SUB must fit to those specified in the SUB declaration.</paragraph> -<paragraph id="par_id3147397" role="paragraph" xml-lang="en-US">The same process applies to FUNCTIONS. In addition, functions always return a function result. The result of a function is defined by assigning the return value to the function name:</paragraph> +<paragraph id="par_id3147124" role="paragraph" xml-lang="en-US">The parameters passed to a <literal>Sub</literal> must fit to those specified in the <literal>Sub</literal> declaration.</paragraph> +<paragraph id="par_id3147397" role="paragraph" xml-lang="en-US">The same process applies to a <literal>Function</literal>. In addition, functions always return a function result. The result of a function is defined by assigning the return value to the function name:</paragraph> <bascode> -<paragraph id="par_idm1341024672" role="bascode" localize="false" xml-lang="en-US">Function FunctionName(Parameter1 As Type, Parameter2 As Type,...) As Type</paragraph> -<paragraph id="par_id3156284" role="bascode" xml-lang="en-US">Program code</paragraph> -<paragraph id="par_id3145799" role="bascode" xml-lang="en-US">FunctionName=Result</paragraph> -<paragraph id="par_idm1341019952" role="bascode" localize="false" xml-lang="en-US">End Function</paragraph> + <paragraph id="par_idm1341024672" role="bascode" localize="false">Function FunctionName(Parameter1 As TYPENAME, Parameter2 As TYPENAME,...) As TYPENAME</paragraph> + <paragraph id="par_id3156284" role="bascode" xml-lang="en-US"> ' your code goes here</paragraph> + <paragraph id="par_id3145799" role="bascode" localize="false"> FunctionName=Result</paragraph> + <paragraph id="par_idm1341019952" role="bascode" localize="false">End Function</paragraph> </bascode> -<paragraph id="par_id3153839" role="paragraph" xml-lang="en-US">The FUNCTION is called using the following syntax:</paragraph> +<paragraph id="par_id3153839" role="paragraph" xml-lang="en-US">The <literal>Function</literal> is called using the following syntax:</paragraph> <bascode> -<paragraph id="par_id3146914" role="bascode" xml-lang="en-US">Variable=FunctionName(Parameter1, Parameter2,...)</paragraph> + <paragraph id="par_id3146914" role="bascode" xml-lang="en-US">Variable=FunctionName(Parameter1, Parameter2,...)</paragraph> </bascode> -<paragraph id="par_idN107B3" role="tip" xml-lang="en-US">You can also use the fully qualified name to call a procedure or function:<br/> <item type="literal">Library.Module.Macro()</item> <br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> <item type="literal">Gimmicks.AutoText.Main()</item> </paragraph> - -<paragraph id="hd_id3156276" role="heading" level="2" xml-lang="en-US">Passing Variables by Value or Reference</paragraph> -<paragraph id="par_id3155765" role="paragraph" xml-lang="en-US">Parameters can be passed to a SUB or a FUNCTION either by reference or by value. Unless otherwise specified, a parameter is always passed by reference. That means that a SUB or a FUNCTION gets the parameter and can read and modify its value.</paragraph> -<paragraph id="par_id3145640" role="paragraph" xml-lang="en-US">If you want to pass a parameter by value insert the key word "ByVal" in front of the parameter when you call a SUB or FUNCTION, for example:</paragraph> +<paragraph role="paragraph" id="par_id981584288549909">Properties combine the syntax of procedures and functions. A property usually requires up to one parameter.</paragraph> <bascode> -<paragraph id="par_id3150042" role="bascode" xml-lang="en-US">Result = Function(ByVal Parameter)</paragraph> + <paragraph role="bascode" id="bas_id471584288905523" localize="false">Property Get IsApproved As TYPENAME</paragraph> + <paragraph role="bascode" id="bas_id961584288948497" xml-lang="en-US"> ' your code goes here</paragraph> + <paragraph role="bascode" id="bas_id631584288950491" localize="false">End Property</paragraph> + <paragraph role="bascode" id="bas_id271584288951107" localize="false">Property Let IsApproved(value As TYPENAME)</paragraph> + <paragraph role="bascode" id="bas_id921584288951588" xml-lang="en-US"> ' your code goes here</paragraph> + <paragraph role="bascode" id="bas_id721584289581705" localize="false"> IsApproved = computed_value</paragraph> + <paragraph role="bascode" id="bas_id491584288952356" localize="false">End Property</paragraph> </bascode> -<paragraph id="par_id3149258" role="paragraph" xml-lang="en-US">In this case, the original content of the parameter will not be modified by the FUNCTION since it only gets the value and not the parameter itself.</paragraph> - -<paragraph id="hd_id3150982" role="heading" level="2" xml-lang="en-US">Scope of Variables</paragraph> -<paragraph id="par_id3149814" role="paragraph" xml-lang="en-US">A variable defined within a SUB or FUNCTION, only remains valid until the procedure is exited. This is known as a "local" variable. In many cases, you need a variable to be valid in all procedures, in every module of all libraries, or after a SUB or FUNCTION is exited.</paragraph> - -<paragraph id="hd_id3154186" role="heading" level="3" xml-lang="en-US">Declaring Variables Outside a SUB or FUNCTION</paragraph> +<paragraph id="par_id3153389" role="paragraph" xml-lang="en-US">The <literal>Property</literal> is called using the following syntax:</paragraph> +<bascode> + <paragraph role="bascode" id="bas_id511584289696025" localize="false">var = IsApproved</paragraph> + <paragraph role="bascode" id="bas_id551584289696697" localize="false">IsApproved = True</paragraph> +</bascode> +<tip id="par_idN107B3">You can also use the fully qualified name to call a procedure, function or property:<br/> <literal>Library.Module.Macro()</literal> <br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> <item type="literal">Gimmicks.AutoText.Main()</item> </tip> +<h2 id="hd_id3156276">Passing Variables by Value or Reference</h2> +<paragraph id="par_id3155765" role="paragraph" xml-lang="en-US">Parameters can be passed to a procedure, a function or a property either by reference or by value. Unless otherwise specified, a parameter is always passed by reference. That means that a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal> gets the parameter and can read and modify its value.</paragraph> +<paragraph id="par_id3145640" role="paragraph" xml-lang="en-US">If you want to pass a parameter by value insert the key word <literal>ByVal</literal> in front of the parameter when you call a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal>, for example:</paragraph> +<bascode> + <paragraph id="par_id3150042" role="bascode" xml-lang="en-US">Function ReadOnlyParms(ByVal p2, ByVal p2)</paragraph> + <paragraph role="bascode" id="bas_id81584367761978"> ' your code goes here</paragraph> + <paragraph role="bascode" id="bas_id131584367516784">End Function</paragraph> + <paragraph role="bascode" id="bas_id801584367475787">result = ReadOnlyParms(parm1, parm2)</paragraph> +</bascode> +<paragraph id="par_id3149258" role="paragraph" xml-lang="en-US">In this case, the original content of the parameter will not be modified by the <literal>Function</literal> since it only gets the value and not the parameter itself.</paragraph> +<h2 id="hd_id161584366585035">Defining Optional Parameters</h2> +<paragraph role="paragraph" id="par_id31584367006971">Functions, procedures or properties can be defined with optional parameters, for example:</paragraph> +<bascode> + <paragraph role="bascode" id="bas_id761584366669997">Sub Rounding(number, Optional decimals, Optional format)</paragraph> + <paragraph role="bascode" id="bas_id111584366809406"> ' your code goes here</paragraph> + <paragraph role="bascode" id="bas_id251584366745722">End Sub</paragraph> +</bascode> +<h2 id="hd_id3150982">Scope of Variables</h2> +<paragraph id="par_id3149814" role="paragraph" xml-lang="en-US">A variable defined within a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal>, only remains valid until the procedure is exited. This is known as a "local" variable. In many cases, you need a variable to be valid in all procedures, in every module of all libraries, or after a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal> is exited.</paragraph> +<h3 id="hd_id3154186">Declaring Variables Outside a <literal>Sub</literal> a <literal>Function</literal> or a <literal>Property</literal></h3> <bascode> <paragraph id="par_id3150208" role="bascode" xml-lang="en-US">Global VarName As TYPENAME</paragraph> </bascode> -<paragraph id="par_id3145258" role="paragraph" xml-lang="en-US">The variable is valid as long as the $[officename] session lasts.</paragraph> +<paragraph id="par_id3145258" role="paragraph" xml-lang="en-US">The variable is valid as long as the %PRODUCTNAME session lasts.</paragraph> <bascode> <paragraph id="par_id3153198" role="bascode" xml-lang="en-US">Public VarName As TYPENAME</paragraph> </bascode> @@ -106,39 +121,42 @@ <paragraph id="par_id3150886" role="bascode" xml-lang="en-US">Dim VarName As TYPENAME</paragraph> </bascode> <paragraph id="par_id3150368" role="paragraph" xml-lang="en-US">The variable is only valid in this module.</paragraph> - -<paragraph id="hd_id5097506" role="heading" level="3" xml-lang="en-US">Example for private variables</paragraph> -<paragraph id="par_id8738975" role="paragraph" xml-lang="en-US">Enforce private variables to be private across modules by setting CompatibilityMode(true).</paragraph><comment>from i17948, see i54894</comment> +<h3 id="hd_id5097506">Example for private variables</h3> + <paragraph id="par_id8738975" role="paragraph" xml-lang="en-US">Enforce private variables to be private across modules by setting <literal>CompatibilityMode(True)</literal>.</paragraph><comment>from i17948, see i54894</comment> <bascode> -<paragraph id="par_idm1340976400" role="bascode" localize="false" xml-lang="en-US">' ***** Module1 *****</paragraph> -<paragraph id="par_idm1340975168" role="bascode" localize="false" xml-lang="en-US">Private myText As String</paragraph> -<paragraph id="par_idm1340973920" role="bascode" localize="false" xml-lang="en-US">Sub initMyText</paragraph> -<paragraph id="par_id9475997" role="bascode" xml-lang="en-US"> myText = "Hello"</paragraph> -<paragraph id="par_id6933500" role="bascode" xml-lang="en-US"> Print "In module1 : ", myText</paragraph> -<paragraph id="par_idm1340970208" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph> -<paragraph id="par_idm1340968976" role="bascode" localize="false" xml-lang="en-US"> </paragraph> -<paragraph id="par_idm1340967728" role="bascode" localize="false" xml-lang="en-US">' ***** Module2 *****</paragraph> -<paragraph id="par_idm1340966496" role="bascode" localize="false" xml-lang="en-US">'Option Explicit</paragraph> -<paragraph id="par_idm1340965264" role="bascode" localize="false" xml-lang="en-US">Sub demoBug</paragraph> -<paragraph id="par_idm1340964032" role="bascode" localize="false" xml-lang="en-US"> CompatibilityMode( true )</paragraph> -<paragraph id="par_idm1340962784" role="bascode" localize="false" xml-lang="en-US"> initMyText</paragraph> -<paragraph id="par_id4104129" role="bascode" xml-lang="en-US"> ' Now returns empty string</paragraph> -<paragraph id="par_id7906125" role="bascode" xml-lang="en-US"> ' (or raises error for Option Explicit)</paragraph> -<paragraph id="par_id8055970" role="bascode" xml-lang="en-US"> Print "Now in module2 : ", myText</paragraph> -<paragraph id="par_idm1340957792" role="bascode" localize="false" xml-lang="en-US">End Sub</paragraph> + <paragraph id="par_idm1340976400" role="bascode" localize="false">' ***** Module1 *****</paragraph> + <paragraph id="par_idm1340975168" role="bascode" localize="false">Private myText As String</paragraph> + <paragraph id="par_idm1340973920" role="bascode" localize="false">Sub initMyText</paragraph> + <paragraph id="par_id9475997" role="bascode" xml-lang="en-US"> myText = "Hello"</paragraph> + <paragraph id="par_id6933500" role="bascode" xml-lang="en-US"> Print "In module1 : ", myText</paragraph> + <paragraph id="par_idm1340970208" role="bascode" localize="false">End Sub</paragraph> + <paragraph id="par_idm1340968976" role="bascode" localize="false"> </paragraph> + <paragraph id="par_idm1340967728" role="bascode" localize="false">' ***** Module2 *****</paragraph> + <paragraph id="par_idm1340966496" role="bascode" localize="false">'Option Explicit</paragraph> + <paragraph id="par_idm1340965264" role="bascode" localize="false">Sub demoBug</paragraph> + <paragraph id="par_idm1340964032" role="bascode" localize="false"> CompatibilityMode( True )</paragraph> + <paragraph id="par_idm1340962784" role="bascode" localize="false"> initMyText</paragraph> + <paragraph id="par_id4104129" role="bascode" xml-lang="en-US"> ' Now returns empty string</paragraph> + <paragraph id="par_id7906125" role="bascode" xml-lang="en-US"> ' (or raises error for Option Explicit)</paragraph> + <paragraph id="par_id8055970" role="bascode" xml-lang="en-US"> Print "Now in module2 : ", myText</paragraph> + <paragraph id="par_idm1340957792" role="bascode" localize="false">End Sub</paragraph> </bascode> - -<paragraph id="hd_id3154368" role="heading" level="3" xml-lang="en-US">Saving Variable Content after Exiting a SUB or FUNCTION</paragraph> +<h3 id="hd_id3154368">Saving Variable Content after Exiting a <literal>Sub</literal> a <literal>Function</literal> or a <literal>Property</literal></h3> <bascode> -<paragraph id="par_id3156288" role="bascode" xml-lang="en-US">Static VarName As TYPENAME</paragraph> + <paragraph id="par_id3156288" role="bascode" xml-lang="en-US">Static VarName As TYPENAME</paragraph> </bascode> -<paragraph id="par_id3154486" role="paragraph" xml-lang="en-US">The variable retains its value until the next time the FUNCTION or SUB is entered. The declaration must exist inside a SUB or a FUNCTION.</paragraph> - -<paragraph id="hd_id3155809" role="heading" level="2" xml-lang="en-US">Specifying the Return Value Type of a FUNCTION</paragraph> -<paragraph id="par_id3149404" role="paragraph" xml-lang="en-US">As with variables, include a type-declaration character after the function name, or the type indicated by "As" and the corresponding key word at the end of the parameter list to define the type of the function's return value, for example:</paragraph> +<paragraph id="par_id3154486" role="paragraph" xml-lang="en-US">The variable retains its value until the next time the a <literal>Function</literal>, <literal>Sub</literal> or <literal>Property</literal> is entered. The declaration must exist inside a <literal>Sub</literal>, a <literal>Function</literal> or a <literal>Property</literal>.</paragraph> +<h2 id="hd_id3155809">Specifying the Return Value Type of a <literal>Function</literal> or a <literal>Property</literal></h2> +<paragraph id="par_id3149404" role="paragraph" xml-lang="en-US">As with variables, include a type-declaration character after the function name, or the type indicated by <literal>As</literal> and the corresponding data type at the end of the parameter list to define the type of the function or property's return value, for example:</paragraph> <bascode> -<paragraph id="par_idm1340946176" role="bascode" localize="false" xml-lang="en-US">Function WordCount(WordText As String) As Integer</paragraph> + <paragraph id="par_idm1340946176" role="bascode" localize="false" xml-lang="en-US">Function WordCount(WordText As String) As Integer</paragraph> </bascode> +<section id="relatedtopics"> + <embed href="text/sbasic/shared/compatibilitymode.xhp#compatibilitymodeh1"/> + <embed href="text/sbasic/shared/03103300.xhp#explicitstatement"/> + <paragraph role="paragraph" id="N0237"><link href="text/sbasic/shared/03104100.xhp" name ="Optional keyword">Optional keyword</link></paragraph> + <paragraph role="paragraph" id="N0238"><link href="text/sbasic/shared/property.xhp" name ="Property Statement">Property Statement</link></paragraph> + <paragraph role="paragraph" id="N0239"><link href="text/sbasic/shared/03103500.xhp" name ="Static Statement">Static Statement</link></paragraph> +</section> </body> - </helpdocument> \ No newline at end of file diff --git a/source/text/sbasic/shared/property.xhp b/source/text/sbasic/shared/property.xhp index b2a4c1b3b..1138716fd 100644 --- a/source/text/sbasic/shared/property.xhp +++ b/source/text/sbasic/shared/property.xhp @@ -32,7 +32,7 @@ <warning id="N0184">This statement requires <link href="text/sbasic/shared/compatible.xhp" name ="Option Compatible">Option Compatible</link> to be placed before the executable program code in a module. </warning> <h2 id="N0185">Syntax</h2> <bascode> - <paragraph role="bascode" localize="false" id="N0186">[Global | Private | Public] Property [Get | Let | Set] propName[(value As VarType)] [As VarType]</paragraph> + <paragraph role="bascode" localize="false" id="N0186">[Global | Private | Public] Property [Get | Let | Set] propName[([Optional [ByRef | ByVal]]value As Typename)] [As Typename]</paragraph> <paragraph role="bascode" localize="false" id="N0187">End Property</paragraph> </bascode> <h2 id="N0188">Examples</h2> _______________________________________________ Libreoffice-commits mailing list libreoffice-comm...@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/libreoffice-commits