Miscellaneous Routines


The miscellaneous routines described in this section are general-purpose routines that aren't necessarily related to each other (see Table 11 ).

Table 11: Miscellaneous functions in OOo Basic.

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 ).

Listing 18: Create an object using CreateObject or Dim As New.
start example
 Dim oProp As New com.sun.star.beans.PropertyValue Dim o As Object o = CreateObject("com.sun.star.beans.PropertyValue") 
end example
 
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.

Listing 19: Dim a PropertyValue and use CreateObject to create a new one.
start example
 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") 
end example
 

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 ).

Listing 20: ExampleReDimPreserveProp is found in the Misc module in this chapter's source code files as SC08.sxw.
start example
 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 
end example
 
Listing 21: You can add PropertyValue variables to a declared array.
start example
 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 
end example
 

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 .

Listing 22: ExampleCopyAsValue is found in the Misc module in this chapter's source code files as SC08.sxw.
start example
 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 
end example
 
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 



OpenOffice.org Macros Explained
OpenOffice.org Macros Explained
ISBN: 1930919514
EAN: 2147483647
Year: 2004
Pages: 203

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net