The miscellaneous routines described in this section are general-purpose routines that aren't necessarily related to each other (see Table 11 ).
Function | Description |
---|---|
Beep | Make a system-dependent beep. |
CBool(expression) | Convert an integer or string to Boolean. |
Environ(string) | Return an environment variable. |
GetSolarVersion | Internal running version. |
CreateObject(obj_type) | Dynamic version of "Dim As New". |
The Beep statement generates a system-dependent beep. You can't change the pitch or the length of the generated beep. On some systems, this plays a configurable sound file through the built-in speaker, and on others it generates a system event that plays a system-defined sound through low-level internal hardware.
Beep 'Generate a noise Wait(500) 'Wait 1/2 second Beep 'Generate a noise
Use the CBool function to convert a string or a number to a Boolean value. Any numeric expression that evaluates to 0 returns False. Numeric expressions that are not 0 return True. String expressions that evaluate to "True" or "False" return True or False respectively; case does not matter. A string that does not evaluate exactly to True or False is evaluated as a number. If the string doesn't contain a number or the text "true" or "false", a run-time error occurs.
Print CBool(False) 'False Print CBool(13) 'True Print CBool("13") 'True Print CBool("trUe") 'True Print CBool("&h1") 'True Print CBool("13xx") 'run-time error Print Cbool("Truee") 'run-time error
Use the Environ function to retrieve environment variables. If the environment variable does not exist, an empty string is returned. No method is provided to set or change environment variables .
Print Environ("PATH") Print Environ("TEMP")
Use getSolarVersion to obtain the integer internal build number of OOo. You can write your macro to work around known issues, based on release documentation or discovered bugs for different versions of OOo.
Print GetSolarVersion
The CreateObject function allows objects to be created dynamically. If an object can be created using "Dim v As New", it can be created with the CreateObject function. In other words, if an object can be created as a user -defined type, CreateObject can create one. The OOo underlying special data objects, which are covered in depth later, are called Universal Network Objects (UNO). These objects cannot be created using CreateObject. OOo does define structures that are not UNO objects that can be created using Dim As New and CreateObject (see Listing 18 ).
Dim oProp As New com.sun.star.beans.PropertyValue Dim o As Object o = CreateObject("com.sun.star.beans.PropertyValue")
Tip | Prior to OOo version 1.1.1, you could declare a structure without the New keyword shown in Listing 18. You will undoubtedly find old macros that fail because of the new requirement. |
Listing 18 demonstrates creating a variable type defined by OOo that is like a user-defined type. The actual type name of the object is "com.sun.star.beans.PropertyValue". Many of the objects in OOo have similarly long and cumbersome names . While writing about or discussing variable types such as this, it's common to abbreviate the type name as the last portion of the name. For example, set the Name property of the PropertyValue variable (see Listing 19 ). Objects of type PropertyValue have two properties: Name as a String and Value as a Variant.
Dim aProp As New com.sun.star.beans.PropertyValue aProp.Name = "FirstName" 'Set the Name property aProp.Value = "Paterton" 'Set the Value property REM Create a new one! aPropr = CreateObject("com.sun.star.beans.PropertyValue")
Use the CreateObject function to create an object dynamically-in other words, when you don't want to create the object when it's declared. You can use CreateObject to create only one object at a time. Use the Dim As New construction to create an array of a particular type (see Listing 20 ). You can even change the dimension of the array and preserve the data. It is more cumbersome to declare an array and then fill it with the appropriate values individually (see Listing 21 ).
Sub ExampleReDimPreserveProp REM this is easy to create this way Dim oProps(2) As New com.sun.star.beans.PropertyValue oProps(0).Name = "FirstName" : oProps(0).Value = "Joe" oProps(1).Name = "LastName" : oProps(1).Value = "Blather" oProps(2).Name = "Age" : oProps(1).Value = 53 ReDim Preserve oProps(3) As New com.sun.star.beans.PropertyValue oProps(3).Name = "Weight" : oProps(3).value = 97 Print oProps(2).Name 'Age End Sub
REM This is more cumbersome, but you can still do it... Dim oProps(2) oProps(0) = CreateObject("com.sun.star.beans.PropertyValue") oProps(1) = CreateObject("com.sun.star.beans.PropertyValue") oProps(2) = CreateObject("com.sun.star.beans.PropertyValue") oProps(0).Name = "FirstName" : oProps(0).Value = "Joe" oProps(1).Name = "LastName" : oProps(1).Value = "Blather" oProps(2).Name = "Age" : oProps(1).Value = 53
Assigning one array to another assigns a reference so that both arrays reference the same array object. With variable types such as Integer and PropertyValue, assignment makes a copy. Failure to understand which types copy by value and which types copy by reference is a common source of errors. Structures and integral types (such as Integer and String) copy as a value, but arrays and UNO variables, as will be discussed later, copy as a reference. Copying by reference is demonstrated in an obvious way in Listing 22 .
Sub ExampleCopyAsValue Dim aProp1 Dim aProp2 aProp1 = CreateObject("com.sun.star.beans.PropertyValue") aProp1.Name = "Age" 'Set Name Property on one aProp1.Value = 27 'Set Value Property on one aProp2 = aProp1 'Make a copy aProp2.Name = "Weight"'Set Name Property on two aProp2.Value = 97 'Set Value Property on two Print aProp1.Name, aProp2.Name 'Age Weight End Sub
Warning | Standard object variables copy by value, and UNO variables copy by reference. |
When one integer variable is assigned to another, it is understood that the value was copied and nothing more. The two variables are still independent of each other. This is also true for structures. Text cursors , discussed later, contain a property called CharLocale, which specifies the country and language for the text selected by the text cursor. The common, incorrect method to set the locale is to access the variable directly. This sets the language and country on a copy of the CharLocale property rather than on the copy used by the text cursor. I see this type of error often.
oCursor.CharLocale.Language = "fr" 'set language to French on a copy oCursor.CharLocale.Country = "CH" 'set country to Switzerland on a copy
One correct method to set the locale is to create a new Locale structure, modify the new structure, and copy the new structure to the text cursor.
Dim aLocale As New com.sun.star.lang.Locale aLocale.Language = "fr" 'Set Locale to use the French language aLocale.Country = "CH" 'Set Locale to use Switzerland as the country oCursor.CharLocale = aLocale 'Assign the value back
You can also obtain a copy of the structure, modify the copied structure, and copy the modified structure to the text cursor.
Dim aLocale aLocale = oCursor.CharLocale 'Or use a copy aLocale.Language = "fr" 'Set Locale to use the French language aLocale.Country = "CH" 'Set Locale to use Switzerland as the country oCursor.CharLocale = aLocale 'Assign the value back