Category: Openoffice\API

Click here for more documents in the Openoffice\API category

Re: [api-dev] Re: [api-features] new/SRX645 m26 : New features / fixes in Basic / Automation bridge in cws ab02vba

This may be it!


From: Andreas Bregas <andreas.bregas@sun.com>

Hi Laurent,

 >>http://staroffice-doc.germany.sun.com:8080/Teams/Base_Technology/Groups/UNO/Docs/TaskDescription
 >> ab02vba.txt
 >>
 > the link seems to be broken :(
 > What is the correct URL ?
 >
 >  >http//.../Docs/TaskDescription
 >  >ab02vba.txt

as the text is pretty big our web frontend for feature mails
refused to accept it. So I decided to put it on a server but
forgot that this server is only accessible internally. Sorry
for this mistake. I've already replied to my own feature mail,
but the reply containing the text is either lost or it takes
very long to reach ist destination.

Anyway, you find the complete text below.

Regards

Andreas


================================================================
TaskDescription_ab02vba.txt

In cws ab02vba (integrated for srx645 m26) several changes have
been made to improve the compatibility of Star/OpenOffice Basic
to VBA and to improve the UNO-Automation bridge functionality:


****************************************************************
*** Star/OpenOffice Basic related
****************************************************************

Many of the new fixes/features are only active if a special
(also new) compiler option respectively runtime mode is set:

- Option Compatible
Refers to all compiler related features. This option has to
be used in each affected module.

- Runtime function CompatibilityMode( true/false )
Refers to all runtime related features, e.g. the behaviour of
runtime functions.

For each task in the following list the use of these option/mode
settings will be specified. In general an option is used if the
change is incompatible to the current behaviour and could break
existing Star/OpenOffice Basic programs.


//==============================================================
#108677 Allow special characters as identifiers, e.g. , , 

Relies on: Option Compatible

If option compatible is set, all characters that are defined as
letter in the Latin-1 (ISO 8859-1) character set, are accepted
as part of identifiers.

For the Latin-1 character set see "19. Table of ISO 8859-1
Characters" in:

http://www.cs.uu.nl/wais/html/na-dir/internationalization/iso-8859-1-charset.html


Example:

Option Compatible	' With this option the code works, other-
                     ' wise it will cause a compiling error
Sub Main
      = 10
     print 
End Sub

It's a known bug (#114794) that this feature only works case
sensitive.


//==============================================================
#109170 Recursion in Basic: extend limit, currently at 500

Relies on: -

The behaviour now is different for different platforms.
For Linux and Solaris the stacksize is evaluated and the
limit of recursion caculated.

For Windows the limit is set to 5800. The following exam-
ple should run on all machines. On Linux machines chan-
ging 2000 to 3000 will result in a runtime error, for
Windows and Solaris it should run.

Sub Main
	rec( 2000 )
	Print "Ready"
End Sub

Sub rec( Count as long )
	If Count > 0 Then
		rec( Count - 1 )
	Endif
End Sub


//==============================================================
#109274 Implement VBA Compatibility option in Basic

To control the compatiblity behaviour of Star/OpenOffice
Basic a new compiler option and a new runtime mode have
been implemented. Most of the other features described in
this document depend on the corresponding settings.

     Option Compatible ' Turns on Compatible compiler mode
     ' affects the module the option is used in

     CompatibilityMode( bool on/off ) ' Controls runtime mode
     ' affects all code executed after (re)setting the mode


//==============================================================
#109275 Change semantics of Option Base 1 in VBA mode

Relies on: Option Compatible

Task description:
In VBA Option Base 1 does not affect the upper index border,
in Star/OpenOffice Basic it does. This has been changed when
Option Compatible is set.

Example:

Option Base 1
Option Compatible

Sub Main
     Dim a(42)
     Print lbound( a() )		' Prints always 1
     Print ubound( a() )		' Prints 42 if Option Compatible
                             ' is set, otherwise 43
End Sub


//==============================================================
#109277 Change rmdir command in VBA mode

Relies on: CompatibilityMode( true )

In VBA only empty directories are removed by rmdir,
Star/OpenOffice Basic removes a directory recursively.

This has been changed for VBA mode.

Example:

Given a NOT empty directory /home/FooUser/Test

Sub Main
	CompatibilityMode( true )
	RmDir( "file:///home/FooUser/Test" )
End Sub

With CompatibilityMode( true ) the program results
in an error, otherwise the Test directory and all
its content is deleted.


//==============================================================
#109737 VBA compatible behaviour of Basic Dir command

Relies on: CompatibilityMode( true )

Task Description: In VBA the dir command behaves differently
to Star/OpenOffice Basic concerning the directory flags.

Unlike in VBA in Star/OpenOffice Basic the Directory flag (16)
for the Dir command means that ONLY directories are returned.
In VBA then normal files AND directories are returned. With
activated CompatibilityMode Star/OpenOffice Basic should be-
have like VBA.

Example:

Sub Main
     CompatibilityMode( true )   ' Shows also normal files
     Entry$ = Dir( "file:///home/FooUser/Tmp/*.*", 16 )
     Total$ = ""
     While Entry$ <> ""
         Total$ = Total$ + Entry$ + Chr$(13)
         Entry$ = Dir
     Wend
     MsgBox Total$
End Sub


//==============================================================
#110003 Local Variable name clashes with Module Scope Variable

Relies on: -

Task description: As title indicates, get name clash when module
scope variable has the same name as a local variable. This should
not happen any more.

Example:

Public a

Sub main
     dim a    ' Compiler error so far, but not any more
     a = 42   ' affects only the local a
     Print a
End Sub


//==============================================================
#110004 Public/Private keywords not supported for Procedures

Relies on: -

Task description: Star/OpenOffice Basic does not support the
Public/Private Keywords for Procedures. All procedures are
Public by default.

Example:

REM Module1
Sub main
	OtherSub
End Sub

REM Module2/a
Sub OtherSub
	Print "OtherSub"
End Sub

REM Module2/b
Public Sub OtherSub
	Print "OtherSub"
End Sub

REM Module2/c
Private Sub OtherSub
	Print "OtherSub"
End Sub

So far: Only Module2/a is accepted by the compiler. b/c lead
to errors.

Now: All Module2 versions are correct for the compiler.
In versions a and b OtherSub can be called from Module1/main,
version c leads to a "Property or method not found" error.


//==============================================================
#110005 Set keyword not supported fully in Star/OpenOffice Basic

Relies on: -

Example:

Sub main
	Dim Pv as new com.sun.star.beans.PropertyValue

	Dim myPv as Object	' This line is not necessary any more
	Set myPv = pv
	
	myPv.Name = "bla"
	Print myPv.Name
End Sub


//==============================================================
#110009 Control which libraries are loaded by default in
         Star/OpenOffice Basic
	
Relies on: -

Now the library xml format supports an optional boolean tag "preload"

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 
1.0//EN" "library.dtd">
<library:library xmlns:library="http://openoffice.org/2000/library" 
library:name="Library1"
  library:readonly="false" library:passwordprotected="false" 
library:preload="true">
<library:element library:name="Module1"/>
<library:element library:name="Module2"/>
</library:library>

This works both for global and for document embedded libraries.
This feature is not reflected anywhere in the UI. The preload
flag can only be edited directly in the library's .slb file.


//==============================================================
#111739 Optional Param and Default Values

Relies on: Option Compatible

With Option Compatible set Star/OpenOffice Basic now supports
optional parameters.

Example:

Option Compatible

Sub Main
	Print ReturnTwiceDefault(42), ReturnTwiceDefault()	' Prints 84    200
End Sub

Function ReturnTwiceDefault(Optional A as Integer=100) As Integer
	ReturnTwiceDefault = 2*A
end Function


//==============================================================
#111741 User Defined Types

Relies on: -

Now Star/OpenOffice Basic supports user defined types as long
as they don't contain arrays (see #111980).

Example:

Type MyType
	a as Integer
	d as Double
End Type

Sub Main
	Dim MT as MyType
	MT.a = 42
	MT.d = 111.1
	Print MT.a, MT.d	' Prints 42   111,1
End Sub


//==============================================================
#111790 Handling of nested quotes

Relies on: -

Example:

Sub main
	Msgbox "This is a pair of double quotes - """" "
End Sub

Until now the message box output was:

     This is a pair of double quotes - "

Now this is handled correctly. Inside quotes each pair of
quotes stands for one quote character in the final string.
So the message box output now is:

     This is a pair of double quotes - ""


//==============================================================
#111851 Object Reference support

Relies on: Option Compatible

This task affects several aspects of the "Dim As [New] <Type>"
and the "Set" command.


- Dim Var As <Type>

To support typical usage of these commands in VBA, especially
concerning the handling of OLE objects now "Dim MyVar As <Type>"
is accepted also for an unknown type <Type>, but only if option
compatible is set. So

     Option Compatible
     Sub Main
         Dim word1 as Word.Application
         msgbox IsNull( word1 )	' Displays True because word1
                                 ' has not been instantiated
     End Sub

is ok, but

     Sub Main
         Dim word1 as Word.Application
     End Sub

still leads to a compiling error.

This is also valid for non Windows platforms because Star/
OpenOffice Basic does not really know anything about the
type and just accepts it.


- Set Var = New <Type>

This syntax hasn't been supported at all before. Now it pos-
sible to use

     Dim Var As Type1
     ...
     Set Var = New Type1

also possible is:

     Dim Var As Object
     ...
     Set Var = New Type1

but

     Dim Var As Type1
     ...
     Set Var = New Type2

with Type1 != Type2 leads to an error.


Example 1, ok:

Option Compatible

Sub main
     Dim W As Word.Application
     Set W = New Word.Application
     W.Visible = True
End Sub

This of course only works on Window with a MS Word installed,
but it also works for UNO types:

Option Compatible

Sub main
     Dim PV As com.sun.star.beans.PropertyValue
     Set PV = New com.sun.star.beans.PropertyValue
     PV.Name = "MyName"
     Print PV.Name
End Sub


Example 2, ok:

Option Compatible

Sub main
     Dim W As Object
     Dim PV As Object

     Set W = New Word.Application
     W.Visible = True

     Set PV = New com.sun.star.beans.PropertyValue
End Sub


Example 3, Error:

Option Compatible

Sub main
     Dim W As Word.Application
     Set W = New com.sun.star.beans.PropertyValue	
		' -> Invalid use of object error because
		' of the wrong type
End Sub


- Dim Var As New <Type>

     Dim foo As New <Type>

just is a shorter form of

     Dim foo As <Type>
     Set foo = New <Type>

So for Windows - if the OleObjectFactory service is available -
this code works:

Sub main
     Dim W As New Word.Application
     W.Visible = True
End Sub

It also works without Option Compatible because it's just an
additional feature that cannot break existing programs.

As all this is mainly based on adding a new (OLE) factory to
the Star/OpenOffice Basic factory mechanism, also the
CreateObject function can be used to create OLE objects on
Windows:

Sub main
     Dim W As Object

     MyType = "Word.Application"
     W = CreateObject( MyType )
     W.Visible = True
End Sub


//==============================================================
#111884 CCurr and CVar not supported

Relies on: -

Task description: CCur - converts expresssion to Currency type:
Currency: A data type with a range of -922,337,203,685,477.5808
to 922,337,203,685,477.5807 (4 Digits fixed point format).

Example:

Sub main
	Msgbox CCur( "45345345134534.3434356356" )
End Sub

prints out 45345345134534.3434 now, before a runtime error
occured.


CVar - converts expression to Variant type

Example:

Sub main
	Msgbox CVar( "Hallo" )
End Sub

This function converts the parameter to a variant containing
the same value. This cannot be made visible in Star/OpenOffice
Basic, but before the example lead to a "Not implemented" run-
time error and now it is accepted.


//==============================================================
#111886 ReDim Type not Optional

Relies on: -

Task description: The VarType parameter is documented in the
help as being an Optional parameter for ReDim. This is not the
case if the original Dim statement has the type specified. The
following ReDim statement must have a matching Type.

[ReDim]Dim VarName [(start To end)] [As VarType]
     [, VarName2 [(start To end)] [As VarType][,...]]

This it not neccessary any more.

Example:

Sub main
     Dim sUsedStyles() As String

     ' This works now
     ReDim sUsedStyles( 1 to 5 )					

     ' This is how it had to be done before
     ' ReDim sUsedStyles( 1 to 5 ) As String
End Sub


//==============================================================
#112015 Public/ Private variables

Relies on: -

Task description: Star/OpenOffice Basic supports the Public/
Private Keywords for variables, but a private variable in one
module can be accessed from another module.

Now private module variables are not visible any more from
other modules. This does NOT relay on the Option Compatible!
So with this fix Star/OpenOffice Basic really becomes incom-
patible to a certain extend. But ignoring the private state
was a real bug and not only something slightly incompatible.
And the fix can only break existing programs that rely on a
bug and it is really strange to use private variables from
outside explicitely. So this incompatible change is accep-
table.


Example:

Module1:

' Option Explicit

Sub main
     InitVar
     Print aPrivateModule2Var	' Prints out 0 now, 42 before
                                 ' With Option Explicit -> Error
End Sub


Module2:

Private aPrivateModule2Var

Sub InitVar
	aPrivateModule2Var = 42
End Sub


//==============================================================
#112051 Optional parameters to UNO compoments require positional 
placeholders

Relies on: CompatibilityMode( true )

If Star/OpenOffice Basic calls an IDL based UNO method and end
standing parameters of type Any are considered to be optional.

So a method

     void foo( [in]double a, [in]Any b, [in]Any c );

can be called from Star/OpenOffice Basic like this:

Sub main
	CompatibilityMode( true )
	foo( 42.0, 1, 2 )
	foo( 42.0, 1 )  ' Without last parameter
	foo( 42.0 )     ' Without the last two parameters
End Sub

A method

     void foo2( [in]Any a, [in]Any b, [in]Any c );

can even be called like this:

Sub main
	CompatibilityMode( true )
	foo2            ' No parameters
End Sub

This does not mean that the call is always correct. Star/
OpenOffice Basic just passes empty Anys and it's up to the
implementation to accept this or not. But without this new
functionality the call would not even reach the implementa-
tion code because the core reflection service used for the
call would throw an exception because of the missing para-
meters before.


//==============================================================
#113063 Creation of Const String for Non Printable characters

Relies on: Option Compatible

Task description: Need support to create Const String for Non
Printable characters. Cannot create vbCr as Const String in
Star/OpenOffice Basic. In VBA vbCr is a Const String and so at
module scope you can do the following:

Const globalConstString As String = "This is a test string" & vbCr & 
"with a return"


Now Star/OpenOffice Basic supports all vbCr like constants when
option compatible is set:

vbCr Chr(13)                               Carriage return
vbCrLf Chr(13) & Chr(10)                   Carriage return/linefeed
                                            combination
vbFormFeed Chr(12)                         Form feed
vbLf Chr(10)                               Line feed
vbNewLine Chr(13) & Chr(10) or Chr(10)	   Platform-specific newline
                                            character; whatever is ap-
                                            propriate for the platform
vbNullChar Chr(0)                          Character having the value 0
vbNullString                               String having value 0 Not
                                            the same as a zero-length
                                            string ("");
vbTab Chr(9)                               Horizontal tab
vbVerticalTab Chr(11)                      Vertical tab


Example:

Option Compatible
Const globalConstString As String = "A test string" & vbCr & "with a return"

Sub main
     Msgbox globalConstString
End Sub


****************************************************************
*** Automation Bridge related
****************************************************************

The new features in the Automation bridge concern the ability to
call Automation objects from UNO and Star/OpenOffice Basic. To
call Automation objects is possible since SO 5.2. However,  due
to numerous bugs this hardly worked. The majority of tasks in the
cws ab02vba concerning the Automation bridge were bug fixes.

The new features are:

- Automation properties with additional arguments are supported
- Optional parameters
- Optional parameters with default values
- Variable argument lists
- Named Arguments

Here is an excerpt of Developer's Guide (#114009):

Accessing Automation Objects
-------------------------------
All Automation objects are accessed through [IDL:com.sun.star.script.
XInvocation] interface. The function [IDLS:com.sun.star.script.
XInvocation:getIntrospection] is not implemented. To call a method
[IDLS:com.sun.star.script.XInvocation:invoke] is used. [IDLS:com.sun.
star.script.XInvocation:invoke] is also used to access properties
with additional arguments. The methods [IDLS:com.sun.star.script.
XInvocation:setValue] and [IDLS:com.sun.star.script.XInvocation:
getValue] set or retrieve a property value. These methods can only
be used with properties which do not have additional arguments.
[IDLS:com.sun.star.script.XInvocation:hasMethod] returns true for
a name which represents a method or a property with arguments. An
last, [IDLS:com.sun.star.script.XInvocation:hasProperty] returns
true for a name that represents a property with no arguments.
Please refer to the IDL documentation for more information about
[IDLS:com.sun.star.script.XInvocation].

Properties with Arguments
----------------------------
Unlike UNO properties, Automation properties can have arguments.
Therefore [IDLS:com.sun.star.script.XInvocation:setValue] and [IDLS:
com.sun.star.script.XInvocation:getValue] method are not suitable
for those properties. Instead [IDLS:com.sun.star.script.XInvocation:
invoke] is to be used. If a property takes arguments then [IDLS:com.
sun.star.script.XInvocation:hasProperty] returns false and [IDLS:
com.sun.star.script.XInvocation:hasMethod] returns true.  [IDLS:
com.sun.star.script.XInvocation:invoke] must also be used if the
arguments of the property are optional and not provided in the call.
The bridge must recognize a write operation on a property. To achie-
ve this, the caller has to provide the actual property value (not
additional arguments) in a structure of type [IDL:com.sun.star.
bridge.oleautomation.PropertyPutArgument. Similar to IDispatch::
Invoke, the property value must be the last in the argument list.

For example:
// MIDL
[propget,...] HRESULT Item([in] VARIANT val1, [out, retval] VARIANT* pVal);
[propput,...] HRESULT Item([in] VARIANT val1, [in] VARIANT newVal);

// C++
Sequence< sal_Int16> seqIndices;
Sequence<Any> seqOut;
//Prepare arguments
Any arArgs[2];
arArgs[0] <<= makeAny((sal_Int32) 0);
arArgs[1] <<= PropertyPutArgument(makeAny((sal_Int32) 0));
Sequence<Any> seqArgs(arArgs, 2);

//obj is a XInvocation of an Automation object
obj->invoke(OUString::createFromAscii("Item"), seqArgs, seqIndices, seqOut);

//now get the property value
Any arGet[1];
arGet[0] <<= makeAny((sal_Int32) 0);
Sequence<Any> seqGet(arGet, 1);
Any retVal = obj->invoke(OUString::createFromAscii("Item"), seqGet, 
seqIndices, seqOut);


In Star/OpenOffice Basic, [IDLS:com.sun.star.bridge.oleautomation.
PropertyPutArgument] is implicitely used:

' Star/OpenOffice Basic
obj.Item(0) = 0

Dim propval As Variant
propval = obj.Item(0)

The property value which is obtained in a property get operation is
the return value of [IDLS:com.sun.star.script.XInvocation:invoke].


Optional Parameters, Default Values, Variable Argument Lists
--------------------------------------------------------------
The bridge supports all these special parameters. Optional parameters 
can be
simply left out in the argument list of 
[IDLS:com.sun.star.script.XInvocation:
invoke]. However, if a value will be omitted then all following 
arguments from
the parameter list must be omitted too. This only applies for positional 
argu-
ments and not for named arguments.
If the Automation object specifies a default value for an optional 
parameter
then the bridge supplies it, if no argument was provided by the caller.
If a method takes a variable argument list, then one can provide the respec-
tive UNO arguments as ordinary arguments to [IDLS:com.sun.star.script.XInvo-
cation:invoke]. IDispatch::Invoke would require those arguments in a 
SAFEARRAY.

Named Arguments
To provide named arguments in an 
[IDLS:com.sun.star.script.XInvocation:invoke]
call, one has to use instances of 
[IDL:com.sun.star.bridge.oleautomation.Named-
Argument] for each argument. This is the struct in UNO  IDL:

module com {  module sun {  module star {  module bridge
            {  module oleautomation { struct NamedArgument
{
     /** The name of the argument, for which
         <member>NamedArgument::Value</member> is intended.
      */
     string Name;

     /** The value of the argument whoose name is the one as contained 
in the
         member <member>Name</member>.
      */
     any Value;
};

}; }; }; }; };

In a call both, named arguments and positional arguments can be used 
together.
The order is, first  the positional arguments (the ordinary arguments), fol-
lowed by named arguments. When named arguments are used then arguments 
can be
omitted even if arguments are provided which follow the omitted parameter.
For example, say that a method takes five arguments, which are all 
optional,
then the argument lists for [IDLS:com.sun.star.script.XInvocation] could be
like this:

all provided: {A, B, C, D, E}
arguments omitted: {A,B,C,D} or {A,B} but not {A, C, D}
named arguments : {nA, nC, nB, nD}, {nC, nD}
mixed arguments: { A, B, nD}, {A, nC}

Named arguments can also be used with properties which have additional argu-
ments. However, the property value itself cannot be a named argument, since
it is already regarded as named argument. Therefore, is is always the last
argument .


****************************************************************
*** Basic IDE related
****************************************************************

#109415 Support Help URLs in Star/OpenOffice Basic comment fields

The Star/OpenOffice Basic IDE now also supports help URLs, that
means if the cursor is at a help URL, and the user presses F1,
the help system opens at the specified position, e.g.

REM For additional help move the cursor to the help URL below
REM and press F1.
REM
REM 
vnd.sun.star.help://swriter/35098?Language=en-US&System=WIN#HID_OFADLG_TREELISTBOX



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@api.openoffice.org
For additional commands, e-mail: dev-help@api.openoffice.org