Apache OpenOffice Wiki - User contributions [en]

Python/Transfer from Basic to Python

2015-11-15T15:18:24Z

Hanya: /* Input Box */ Set label to no label on the input box

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==
In Basic, you can call subroutines defined in other modules or other libraries that has been loaded.
<source lang="Python">
BasicLibraries.loadLibrary("Library1")
Library1.Foo()
</source>
In Python, you can import some modules that can be found in sys.path list. If you want to import your own module placed inside Scripts/python directory, put your module in pythonpath directory nearby your script file.
<pre>
- Scripts/
- python/
- macro.py
- pythonpath/ # this directory is added automatically before your macro executed
- your_module.py # this module can be found
</pre>
When you execute the macro from your script file, the internal executor adds the pythonpath/ directory to sys.path list to be used as one of lookup location.

Please keep in mind, the name of module conflict each other if you have the same named module in the some location, this is the standard python mechanism of importing modules, put your each modules in differently named library to avoid the name conflict.

== Dialog ==
In Basic, there is CreateUnoDialog runtime function to instantiate the dialog.
<source lang="Python">
DialogLibraries.loadLibrary("Standard")
dialog = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
dialog.execute()
dialog.dispose()
</source>
In Python, such shortcut function is not provided but you can easily instantiate your dialog using <idl>com.sun.star.awt.DialogProvider</idl> service.
<source lang="Python">
def dialog_example():
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)
dialog = dp.createDialog("vnd.sun.star.script:Standard.Dialog1?location=user")
dialog.execute()
dialog.dispose()
</source>

== Message Box ==
In Basic, you can use MsgBox runtime function to show some message to the users.
<source lang="Python">
Msgbox "Hello."
</source>
In Python, no shortcut function is provided but you can use <idl>com.sun.star.awt.XMessageBoxFactory</idl> interface through the toolkit.

<source lang="Python">
def messagebox(ctx, parent, message, title, message_type, buttons):
""" Show message in message box. """
toolkit = parent.getToolkit()
older_imple = check_method_parameter(
ctx, "com.sun.star.awt.XMessageBoxFactory", "createMessageBox",
1, "com.sun.star.awt.Rectangle")
if older_imple:
msgbox = toolkit.createMessageBox(
parent, Rectangle(), message_type, buttons, title, message)
else:
message_type = uno.getConstantByName("com.sun.star.awt.MessageBoxType." + {
"messbox": "MESSAGEBOX", "infobox": "INFOBOX",
"warningbox": "WARNINGBOX", "errorbox": "ERRORBOX",
"querybox": "QUERYBOX"}[message_type])
msgbox = toolkit.createMessageBox(
parent, message_type, buttons, title, message)
n = msgbox.execute()
msgbox.dispose()
return n

def check_method_parameter(ctx, interface_name, method_name, param_index, param_type):
""" Check the method has specific type parameter at the specific position. """
cr = create_service(ctx, "com.sun.star.reflection.CoreReflection")
try:
idl = cr.forName(interface_name)
m = idl.getMethod(method_name)
if m:
info = m.getParameterInfos()[param_index]
return info.aType.getName() == param_type
except:
pass
return False
</source>

== Input Box ==

No function provided for Python, you have to make your own one. Here is an example:

<source lang="Python">def inputbox(message, title="", default="", x=None, y=None):
""" Shows dialog with input box.
@param message message to show on the dialog
@param title window title
@param default default value
@param x dialog positio in twips, pass y also
@param y dialog position in twips, pass y also
@return string if OK button pushed, otherwise zero length string
"""
WIDTH = 600
HORI_MARGIN = VERT_MARGIN = 8
BUTTON_WIDTH = 100
BUTTON_HEIGHT = 26
HORI_SEP = VERT_SEP = 8
LABEL_HEIGHT = BUTTON_HEIGHT * 2 + 5
EDIT_HEIGHT = 24
HEIGHT = VERT_MARGIN * 2 + LABEL_HEIGHT + VERT_SEP + EDIT_HEIGHT
import uno
from com.sun.star.awt.PosSize import POS, SIZE, POSSIZE
from com.sun.star.awt.PushButtonType import OK, CANCEL
from com.sun.star.util.MeasureUnit import TWIP
ctx = uno.getComponentContext()
def create(name):
return ctx.getServiceManager().createInstanceWithContext(name, ctx)
dialog = create("com.sun.star.awt.UnoControlDialog")
dialog_model = create("com.sun.star.awt.UnoControlDialogModel")
dialog.setModel(dialog_model)
dialog.setVisible(False)
dialog.setTitle(title)
dialog.setPosSize(0, 0, WIDTH, HEIGHT, SIZE)
def add(name, type, x_, y_, width_, height_, props):
model = dialog_model.createInstance("com.sun.star.awt.UnoControl" + type + "Model")
dialog_model.insertByName(name, model)
control = dialog.getControl(name)
control.setPosSize(x_, y_, width_, height_, POSSIZE)
for key, value in props.items():
setattr(model, key, value)
label_width = WIDTH - BUTTON_WIDTH - HORI_SEP - HORI_MARGIN * 2
add("label", "FixedText", HORI_MARGIN, VERT_MARGIN, label_width, LABEL_HEIGHT,
{"Label": str(message), "NoLabel": True})
add("btn_ok", "Button", HORI_MARGIN + label_width + HORI_SEP, VERT_MARGIN,
BUTTON_WIDTH, BUTTON_HEIGHT, {"PushButtonType": OK, "DefaultButton": True})
add("btn_cancel", "Button", HORI_MARGIN + label_width + HORI_SEP, VERT_MARGIN + BUTTON_HEIGHT + 5,
BUTTON_WIDTH, BUTTON_HEIGHT, {"PushButtonType": CANCEL})
add("edit", "Edit", HORI_MARGIN, LABEL_HEIGHT + VERT_MARGIN + VERT_SEP,
WIDTH - HORI_MARGIN * 2, EDIT_HEIGHT, {"Text": str(default)})
frame = create("com.sun.star.frame.Desktop").getCurrentFrame()
window = frame.getContainerWindow() if frame else None
dialog.createPeer(create("com.sun.star.awt.Toolkit"), window)
if not x is None and not y is None:
ps = dialog.convertSizeToPixel(uno.createUnoStruct("com.sun.star.awt.Size", x, y), TWIP)
_x, _y = ps.Width, ps.Height
elif window:
ps = window.getPosSize()
_x = ps.Width / 2 - WIDTH / 2
_y = ps.Height / 2 - HEIGHT / 2
dialog.setPosSize(_x, _y, 0, 0, POS)
edit = dialog.getControl("edit")
edit.setSelection(uno.createUnoStruct("com.sun.star.awt.Selection", 0, len(str(default))))
edit.setFocus()
ret = edit.getModel().Text if dialog.execute() else ""
dialog.dispose()
return ret
</source>

This function can be called as follows:
<source lang="Python">
inputbox("Please input some value", "Input", "Default value")
</source>

== Executing Macros from Toolbar Buttons ==
In Basic, you can call any subroutines or functions through toolbar buttons.
<source lang="Python">
Sub WriteHello()
ThisComponent.getText().getEnd().setString("Hello!")
End Sub
</source>

In Python, you have to define your Python function with an argument (or variable length arguments) to take an argument passed when the function executed through assigned toolbar button.
<source lang="Python">
def writeHello(*args):
# writeHello(arg): is also ok but if you want to call this function
# by some ways, define your function takes variable arguments.
XSCRIPTCONTEXT.getDocument().getText().getEnd().setString("Hello!")
</source>

[[Category:Python]]

Python/Transfer from Basic to Python

2015-11-15T15:08:53Z

Hanya: /* Input Box */ Add example about input box

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==
In Basic, you can call subroutines defined in other modules or other libraries that has been loaded.
<source lang="Python">
BasicLibraries.loadLibrary("Library1")
Library1.Foo()
</source>
In Python, you can import some modules that can be found in sys.path list. If you want to import your own module placed inside Scripts/python directory, put your module in pythonpath directory nearby your script file.
<pre>
- Scripts/
- python/
- macro.py
- pythonpath/ # this directory is added automatically before your macro executed
- your_module.py # this module can be found
</pre>
When you execute the macro from your script file, the internal executor adds the pythonpath/ directory to sys.path list to be used as one of lookup location.

Please keep in mind, the name of module conflict each other if you have the same named module in the some location, this is the standard python mechanism of importing modules, put your each modules in differently named library to avoid the name conflict.

== Dialog ==
In Basic, there is CreateUnoDialog runtime function to instantiate the dialog.
<source lang="Python">
DialogLibraries.loadLibrary("Standard")
dialog = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
dialog.execute()
dialog.dispose()
</source>
In Python, such shortcut function is not provided but you can easily instantiate your dialog using <idl>com.sun.star.awt.DialogProvider</idl> service.
<source lang="Python">
def dialog_example():
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)
dialog = dp.createDialog("vnd.sun.star.script:Standard.Dialog1?location=user")
dialog.execute()
dialog.dispose()
</source>

== Message Box ==
In Basic, you can use MsgBox runtime function to show some message to the users.
<source lang="Python">
Msgbox "Hello."
</source>
In Python, no shortcut function is provided but you can use <idl>com.sun.star.awt.XMessageBoxFactory</idl> interface through the toolkit.

<source lang="Python">
def messagebox(ctx, parent, message, title, message_type, buttons):
""" Show message in message box. """
toolkit = parent.getToolkit()
older_imple = check_method_parameter(
ctx, "com.sun.star.awt.XMessageBoxFactory", "createMessageBox",
1, "com.sun.star.awt.Rectangle")
if older_imple:
msgbox = toolkit.createMessageBox(
parent, Rectangle(), message_type, buttons, title, message)
else:
message_type = uno.getConstantByName("com.sun.star.awt.MessageBoxType." + {
"messbox": "MESSAGEBOX", "infobox": "INFOBOX",
"warningbox": "WARNINGBOX", "errorbox": "ERRORBOX",
"querybox": "QUERYBOX"}[message_type])
msgbox = toolkit.createMessageBox(
parent, message_type, buttons, title, message)
n = msgbox.execute()
msgbox.dispose()
return n

def check_method_parameter(ctx, interface_name, method_name, param_index, param_type):
""" Check the method has specific type parameter at the specific position. """
cr = create_service(ctx, "com.sun.star.reflection.CoreReflection")
try:
idl = cr.forName(interface_name)
m = idl.getMethod(method_name)
if m:
info = m.getParameterInfos()[param_index]
return info.aType.getName() == param_type
except:
pass
return False
</source>

== Input Box ==

No function provided for Python, you have to make your own one. Here is an example:

<source lang="Python">def inputbox(message, title="", default="", x=None, y=None):
""" Shows dialog with input box.
@param message message to show on the dialog
@param title window title
@param default default value
@param x dialog positio in twips, pass y also
@param y dialog position in twips, pass y also
@return string if OK button pushed, otherwise zero length string
"""
WIDTH = 600
HORI_MARGIN = VERT_MARGIN = 8
BUTTON_WIDTH = 100
BUTTON_HEIGHT = 26
HORI_SEP = VERT_SEP = 8
LABEL_HEIGHT = BUTTON_HEIGHT * 2 + 5
EDIT_HEIGHT = 24
HEIGHT = VERT_MARGIN * 2 + LABEL_HEIGHT + VERT_SEP + EDIT_HEIGHT
import uno
from com.sun.star.awt.PosSize import POS, SIZE, POSSIZE
from com.sun.star.awt.PushButtonType import OK, CANCEL
from com.sun.star.util.MeasureUnit import TWIP
ctx = uno.getComponentContext()
def create(name):
return ctx.getServiceManager().createInstanceWithContext(name, ctx)
dialog = create("com.sun.star.awt.UnoControlDialog")
dialog_model = create("com.sun.star.awt.UnoControlDialogModel")
dialog.setModel(dialog_model)
dialog.setVisible(False)
dialog.setTitle(title)
dialog.setPosSize(0, 0, WIDTH, HEIGHT, SIZE)
def add(name, type, x_, y_, width_, height_, props):
model = dialog_model.createInstance("com.sun.star.awt.UnoControl" + type + "Model")
dialog_model.insertByName(name, model)
control = dialog.getControl(name)
control.setPosSize(x_, y_, width_, height_, POSSIZE)
for key, value in props.items():
setattr(model, key, value)
label_width = WIDTH - BUTTON_WIDTH - HORI_SEP - HORI_MARGIN * 2
add("label", "FixedText", HORI_MARGIN, VERT_MARGIN, label_width, LABEL_HEIGHT, {"Label": str(message)})
add("btn_ok", "Button", HORI_MARGIN + label_width + HORI_SEP, VERT_MARGIN,
BUTTON_WIDTH, BUTTON_HEIGHT, {"PushButtonType": OK, "DefaultButton": True})
add("btn_cancel", "Button", HORI_MARGIN + label_width + HORI_SEP, VERT_MARGIN + BUTTON_HEIGHT + 5,
BUTTON_WIDTH, BUTTON_HEIGHT, {"PushButtonType": CANCEL})
add("edit", "Edit", HORI_MARGIN, LABEL_HEIGHT + VERT_MARGIN + VERT_SEP,
WIDTH - HORI_MARGIN * 2, EDIT_HEIGHT, {"Text": str(default)})
frame = create("com.sun.star.frame.Desktop").getCurrentFrame()
window = frame.getContainerWindow() if frame else None
dialog.createPeer(create("com.sun.star.awt.Toolkit"), window)
if not x is None and not y is None:
ps = dialog.convertSizeToPixel(uno.createUnoStruct("com.sun.star.awt.Size", x, y), TWIP)
_x, _y = ps.Width, ps.Height
elif window:
ps = window.getPosSize()
_x = ps.Width / 2 - WIDTH / 2
_y = ps.Height / 2 - HEIGHT / 2
dialog.setPosSize(_x, _y, 0, 0, POS)
edit = dialog.getControl("edit")
edit.setSelection(uno.createUnoStruct("com.sun.star.awt.Selection", 0, len(str(default))))
edit.setFocus()
ret = edit.getModel().Text if dialog.execute() else ""
dialog.dispose()
return ret
</source>

This function can be called as follows:
<source lang="Python">
inputbox("Please input some value", "Input", "Default value")
</source>

== Executing Macros from Toolbar Buttons ==
In Basic, you can call any subroutines or functions through toolbar buttons.
<source lang="Python">
Sub WriteHello()
ThisComponent.getText().getEnd().setString("Hello!")
End Sub
</source>

In Python, you have to define your Python function with an argument (or variable length arguments) to take an argument passed when the function executed through assigned toolbar button.
<source lang="Python">
def writeHello(*args):
# writeHello(arg): is also ok but if you want to call this function
# by some ways, define your function takes variable arguments.
XSCRIPTCONTEXT.getDocument().getText().getEnd().setString("Hello!")
</source>

[[Category:Python]]

User:Hanya/Part of Build Tools

2015-01-05T09:41:27Z

Hanya: /* Other */ Fix about rsc

There are some executable and scripts used while building the office. Here is the part of them that I wanted to know.

== Localization ==
For localization. See [[Localization_AOO]].

{|
|-
! Name
! Module
! Description
|-
| cfgex
| l10ntools
|
|-
| gsicheck
| l10ntools
| Checks SDF file
|-
| helpex
| l10ntools
| Generates SDF file from help files
|-
| HelpLinker
| l10ntools
| Generates ht, db and key files
|-
| tralay
| l10ntools
| Merge XML file into SDF file
|-
| transex3
| l10ntools
| translation frontend
|-
| ulfex
| l10ntools
|
|-
| xrmex
| l10ntools
| For xrm files
|}

== Other ==
It seems some tools are not used.

{|
|-
! Name
! Module
! Description
|-
| bmp
| svtools/bmpmaker
|
|-
| bmpsum
| svtools/bmpmaker
|
|-
| g2g
| svtools/bmpmaker
| graphic to graphic conversion
|-
| rsc
| rsc
| Compiles resource files into srs file
|-
| rsc2
| rsc
| Called from rsc
|-
| rscdep
| tools/bootstrp
|
|-
| rscpp
| rsc
| Called from rsc
|-
| sp2bv
| cpputools/source/sp2bv
| Convert system path to URL
|-
| srvdepy
| xml2cmp
| Find dependencies for XML files of component descriptions
|-
| sspretty
| tools/bootstrp
|
|-
| svidl
| idl/source/prj
| StarView IDL compiler
|-
| ulfconv
| setup_native/source/ulfconv
| Convert ulf file according to passed encoding table
|-
| xml2cmp
| xml2cmp
|
|}

User:Hanya/Part of Build Tools

2015-01-05T09:27:44Z

Hanya: Add initial content

There are some executable and scripts used while building the office. Here is the part of them that I wanted to know.

== Localization ==
For localization. See [[Localization_AOO]].

{|
|-
! Name
! Module
! Description
|-
| cfgex
| l10ntools
|
|-
| gsicheck
| l10ntools
| Checks SDF file
|-
| helpex
| l10ntools
| Generates SDF file from help files
|-
| HelpLinker
| l10ntools
| Generates ht, db and key files
|-
| tralay
| l10ntools
| Merge XML file into SDF file
|-
| transex3
| l10ntools
| translation frontend
|-
| ulfex
| l10ntools
|
|-
| xrmex
| l10ntools
| For xrm files
|}

== Other ==
It seems some tools are not used.

{|
|-
! Name
! Module
! Description
|-
| bmp
| svtools/bmpmaker
|
|-
| bmpsum
| svtools/bmpmaker
|
|-
| g2g
| svtools/bmpmaker
| graphic to graphic conversion
|-
| rsc
| rsc
| Compiles rsc file to res file
|-
| rsc2
| rsc
|
|-
| rscdep
| tools/bootstrp
|
|-
| rscpp
| rsc
|
|-
| sp2bv
| cpputools/source/sp2bv
| Convert system path to URL
|-
| srvdepy
| xml2cmp
| Find dependencies for XML files of component descriptions
|-
| sspretty
| tools/bootstrp
|
|-
| svidl
| idl/source/prj
| StarView IDL compiler
|-
| ulfconv
| setup_native/source/ulfconv
| Convert ulf file according to passed encoding table
|-
| xml2cmp
| xml2cmp
|
|}

User:Hanya

2015-01-05T08:20:15Z

Hanya: /* Notes */ Add link to new page about build tool

ICLA submitted.

== Notes ==
* [[/Tracked_API_Changes]]
* [[/Hyperlink_Control_on_Dialog_Editor]]
* [[/Distribute_SymbolStyles_by_Extension]]
* [[/External_Libraries]]
* [[/API Changes on 4.0 since 3.4]]
* [[/Translation_Review]]
* [[/New_Field_on_Writer]]
* [[/Iif_Problem]]
* [[/Python_Test_Executor]]
* [[/Part_of_Build_Tools]]

User:Hanya/Python Test Executor

2014-12-27T16:09:09Z

Hanya: Add description about how to execute bundled test cases of Python standard libraries from Python macro

If new version of Python is introduced as shipped Python, bundled test cases should be executed to check standard libraries work well.
There are a few problems to execute these test cases from Python macro. Here is Python script having some settings that avoids errors.

Store the following content into $(user)/Scripts/python/test.py and execute test_all or test_ function.
<pre>
import uno
import sys
import os.path
import platform
import locale
import builtins

STORE_IN_LOGFILE = False
LOG_PATH = None
LOGGER = None

# some tests have problem with the uno importer function,
# so use default import function in regression test
_default_importer = uno._g_delegatee
_uno_importer = uno._uno_import

def _set_default_importer():
builtins.__dict__["__import__"] = _default_importer

def _set_uno_importer():
builtins.__dict__["__import__"] = _uno_importer

class LogWriter:
def write(self, s):
if LOG_PATH:
with open(LOG_PATH, "a") as f:
f.seek(0, whence=2)
f.write(s)

def create(script_context, name):
ctx = script_context.getComponentContext()
return ctx.getServiceManager().createInstanceWithContext(name, ctx)

def _set_io():
if STORE_IN_LOGFILE:
global LOG_PATH
if LOG_PATH is None:
LOG_PATH = uno.fileUrlToSystemPath(
create(XSCRIPTCONTEXT, "com.sun.star.util.PathSubstitution").substituteVariables(
"$(user)/Scripts/python/test.log"))
global LOGGER = LogWriter()
sys.stdout = LOGGER
sys.stderr = LOGGER

def _reset_io():
sys.stdout = sys.__stdout__
sys.stderr = sys.__stderr__

def _set_vars():
python_name = "python.exe" if platform.system() == "Windows" else "python"

office_dir = create(XSCRIPTCONTEXT, "com.sun.star.util.OfficeInstallationDirectories").getOfficeInstallationDirectoryURL()
python_path = os.path.join(uno.fileUrlToSystemPath(office_dir), "program", python_name)

# set parameters for test through command line arguments
sys.argv = ["-r", "-w", "-n", "-u" "all"]#"all,-largefile,-audio,-gui"]
# set executable path because not executable path has been set
sys.executable = python_path

# for some modules such as datetime
locale.setlocale(locale.LC_ALL, "C")

def test_all():
""" Execute all regression test. """
if STORE_IN_LOGFILE:
_set_io()
_set_vars()
_set_default_importer()
try:
import test.__main__
except:
pass
finally:
_set_uno_importer()
if STORE_IN_LOGFILE:
_reset_io()

class TestEnv:
def __init__(self, module):
self.module = module

def __enter__(self):
_set_vars()
_set_default_importer()
return self

def __exit__(self, *args):
_set_uno_importer()
return False

def start(self):
_exec_test(self.module)

def _exec_test(module):
module.test_main()

def test_():
""" Execute selected test. """
import test.test_ssl as module
with TestEnv(module) as t:
t.start()

g_exportedScripts = test_all, test_,
</pre>

User:Hanya

2014-12-27T16:02:51Z

Hanya: /* Notes */ Add link to new page about the way to execute test cases of Python

User:Hanya/Iif Problem

2014-12-22T08:48:05Z

Hanya: Add the way to obtain disassembled code

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

== How to Obtain Disassembled Code ==
The compile for Basic contains the code to write disassembled code into a file. Change some part like the following and recompile it.
Change aFile variable to match with your desired location to store the result. If this code is enabled, you get disassembled code every compilation.

<pre>
Index: basic/source/comp/sbcomp.cxx
===================================================================
--- basic/source/comp/sbcomp.cxx (Revision 1634275)
+++ basic/source/comp/sbcomp.cxx (Working Copy)
@@ -908,7 +908,7 @@

//==========================================================================
// For debugging only
-//#define DBG_SAVE_DISASSEMBLY
+#define DBG_SAVE_DISASSEMBLY

#ifdef DBG_SAVE_DISASSEMBLY
static bool dbg_bDisassemble = true;
@@ -920,7 +920,7 @@
#include <com/sun/star/io/XActiveDataSource.hpp>

using namespace comphelper;
-using namespace rtl;
+//using namespace rtl;
using namespace com::sun::star::uno;
using namespace com::sun::star::lang;
using namespace com::sun::star::ucb;
@@ -931,7 +931,7 @@
bool bDisassemble = dbg_bDisassemble;
if( bDisassemble )
{
- Reference< XSimpleFileAccess3 > xSFI;
+ //Reference< XSimpleFileAccess3 > xSFI;
Reference< XTextOutputStream > xTextOut;
Reference< XOutputStream > xOut;
Reference< XMultiServiceFactory > xSMgr = getProcessServiceFactory();
@@ -938,10 +938,10 @@
if( xSMgr.is() )
{
Reference< XSimpleFileAccess3 > xSFI = Reference< XSimpleFileAccess3 >( xSMgr->createInstance
- ( OUString::createFromAscii( "com.sun.star.ucb.SimpleFileAccess" ) ), UNO_QUERY );
+ ( ::rtl::OUString::createFromAscii( "com.sun.star.ucb.SimpleFileAccess" ) ), UNO_QUERY );
if( xSFI.is() )
{
- String aFile( RTL_CONSTASCII_USTRINGPARAM("file:///d:/zBasic.Asm/Asm_") );
+ String aFile( RTL_CONSTASCII_USTRINGPARAM("file:///home/foo/a") );
StarBASIC* pBasic = (StarBASIC*)pModule->GetParent();
if( pBasic )
{
@@ -955,7 +955,7 @@
if( xSFI->exists( aFile ) )
xSFI->kill( aFile );
xOut = xSFI->openFileWrite( aFile );
- Reference< XInterface > x = xSMgr->createInstance( OUString::createFromAscii( "com.sun.star.io.TextOutputStream" ) );
+ Reference< XInterface > x = xSMgr->createInstance( ::rtl::OUString::createFromAscii( "com.sun.star.io.TextOutputStream" ) );
Reference< XActiveDataSource > xADS( x, UNO_QUERY );
xADS->setOutputStream( xOut );
xTextOut = Reference< XTextOutputStream >( x, UNO_QUERY );
</pre>

== Disassembled Original ==
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled with Problem ==
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled without Problem after Restarting ==
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Differences ==
With the same code, different operation codes are generated for IIf function.

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>
Op2 is type for this OpCode:
<pre>// SbiDisas::TypeOp
pTypes[][13] = {
"Empty","Null","Integer","Long","Single","Double",
"Currency","Date","String","Object","Error","Boolean",
"Variant" };
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

== Code ==
<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
// SbiExprList::Gen in exprgen.cxx
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
// SbiExprList::Gen in exprgen.cxx
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
// SbiExprNode::GenElement in exprgen.cxx
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
// SbiParser::Symbol in parser.cxx
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
// SbiParser::DefProc in dim.cxx
</pre>

In SbiParser::CheckRTLForSym method, pVar->GetType() call should return SbxEMPTY for rSym == "IIf". But SbxINTEGER is returned when the problem was happen. The return value of the function, instance of SbiSymDef gets wrong type. The return type depends on the arguments of the Iif function that called first time.
Then the wrong type is passed to new SbiExprNode instance in SbiExpression::Term method.
When I change the second argument from "" to false, I got SbxSTRING for the type.

While first compilation, SbxObject::Find( rName, t ) returns NULL in SbiStdObject::Find method for rName = "IIf".
IIf function was found in pMethods in SbxObject::Find at second compilation. When the function is registerd in SbxObject::pMethods variable of runtime. The method instance is registerd by SbxObject::Make method called in SbiStdObject::Find method after searching the runtime function in the table.

The type of return value is set at first execution of the runtime function. Iif is defined as RTLFUNC(Iif) (SbRtl_Iif function is generated by the macro) in basic/source/runtime/methods1.cxx file.
If Iif is called like: Iif(true, 1, ""), the return type is going to be SbxINTEGER from the second argument in *rPar.Get(0) = *rPar.Get(2); line. In SbxValue::operator= function called at assignment of the return value, last Put method call set the type of return value of the function.

After the first execution of the code that contains Iif function call, the method instance having return type is used to obtain the return type while the second compilation. The type of return value of Iif function depends on each function call and cause type miss match.

User:Hanya/Iif Problem

2014-12-21T10:12:06Z

Hanya: /* Code */ Add description about the cause of the wrong type

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

== Disassembled Original ==
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled with Problem ==
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled without Problem after Restarting ==
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Differences ==
With the same code, different operation codes are generated for IIf function.

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>
Op2 is type for this OpCode:
<pre>// SbiDisas::TypeOp
pTypes[][13] = {
"Empty","Null","Integer","Long","Single","Double",
"Currency","Date","String","Object","Error","Boolean",
"Variant" };
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

== Code ==
<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
// SbiExprList::Gen in exprgen.cxx
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
// SbiExprList::Gen in exprgen.cxx
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
// SbiExprNode::GenElement in exprgen.cxx
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
// SbiParser::Symbol in parser.cxx
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
// SbiParser::DefProc in dim.cxx
</pre>

In SbiParser::CheckRTLForSym method, pVar->GetType() call should return SbxEMPTY for rSym == "IIf". But SbxINTEGER is returned when the problem was happen. The return value of the function, instance of SbiSymDef gets wrong type. The return type depends on the arguments of the Iif function that called first time.
Then the wrong type is passed to new SbiExprNode instance in SbiExpression::Term method.
When I change the second argument from "" to false, I got SbxSTRING for the type.

While first compilation, SbxObject::Find( rName, t ) returns NULL in SbiStdObject::Find method for rName = "IIf".
IIf function was found in pMethods in SbxObject::Find at second compilation. When the function is registerd in SbxObject::pMethods variable of runtime. The method instance is registerd by SbxObject::Make method called in SbiStdObject::Find method after searching the runtime function in the table.

The type of return value is set at first execution of the runtime function. Iif is defined as RTLFUNC(Iif) (SbRtl_Iif function is generated by the macro) in basic/source/runtime/methods1.cxx file.
If Iif is called like: Iif(true, 1, ""), the return type is going to be SbxINTEGER from the second argument in *rPar.Get(0) = *rPar.Get(2); line. In SbxValue::operator= function called at assignment of the return value, last Put method call set the type of return value of the function.

After the first execution of the code that contains Iif function call, the method instance having return type is used to obtain the return type while the second compilation. The type of return value of Iif function depends on each function call and cause type miss match.

User:Hanya/Iif Problem

2014-12-20T17:53:06Z

Hanya: /* Code */ IIf is found in list of methods hold by the runtime

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

== Disassembled Original ==
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled with Problem ==
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled without Problem after Restarting ==
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Differences ==
With the same code, different operation codes are generated for IIf function.

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>
Op2 is type for this OpCode:
<pre>// SbiDisas::TypeOp
pTypes[][13] = {
"Empty","Null","Integer","Long","Single","Double",
"Currency","Date","String","Object","Error","Boolean",
"Variant" };
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

== Code ==
<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
// SbiExprList::Gen in exprgen.cxx
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
// SbiExprList::Gen in exprgen.cxx
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
// SbiExprNode::GenElement in exprgen.cxx
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
// SbiParser::Symbol in parser.cxx
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
// SbiParser::DefProc in dim.cxx
</pre>

In SbiParser::CheckRTLForSym method, pVar->GetType() call should return SbxEMPTY for rSym == "IIf". But SbxINTEGER is returned when the problem was happen. The return value of the function, instance of SbiSymDef gets wrong type.
Then the wrong type is passed to new SbiExprNode instance in SbiExpression::Term method.
When I change the second argument from "" to false, I got SbxSTRING for the type.

While first compilation, SbxObject::Find( rName, t ) returns NULL in SbiStdObject::Find method for rName = "IIf".
But the second compilation, the call returns something. Who does define IIf as something in the runtime?

IIf function was found in pMethods in SbxObject::Find at second compilation. The function is defined as user defined function with just calling as runtime function, it seems. When the function is registerd in SbxObject::pMethods variable of runtime.

User:Hanya/Iif Problem

2014-12-20T17:43:04Z

Hanya: /* Code */ Add description about wrong findings of the function information

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

== Disassembled Original ==
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled with Problem ==
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled without Problem after Restarting ==
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Differences ==
With the same code, different operation codes are generated for IIf function.

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>
Op2 is type for this OpCode:
<pre>// SbiDisas::TypeOp
pTypes[][13] = {
"Empty","Null","Integer","Long","Single","Double",
"Currency","Date","String","Object","Error","Boolean",
"Variant" };
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

== Code ==
<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
// SbiExprList::Gen in exprgen.cxx
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
// SbiExprList::Gen in exprgen.cxx
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
// SbiExprNode::GenElement in exprgen.cxx
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
// SbiParser::Symbol in parser.cxx
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
// SbiParser::DefProc in dim.cxx
</pre>

In SbiParser::CheckRTLForSym method, pVar->GetType() call should return SbxEMPTY for rSym == "IIf". But SbxINTEGER is returned when the problem was happen. The return value of the function, instance of SbiSymDef gets wrong type.
Then the wrong type is passed to new SbiExprNode instance in SbiExpression::Term method.
When I change the second argument from "" to false, I got SbxSTRING for the type.

While first compilation, SbxObject::Find( rName, t ) returns NULL in SbiStdObject::Find method for rName = "IIf".
But the second compilation, the call returns something. Who does define IIf as something in the runtime?

User:Hanya/Iif Problem

2014-12-20T17:19:11Z

Hanya: /* Differences */ Add some description with code location

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

== Disassembled Original ==
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled with Problem ==
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Disassembled without Problem after Restarting ==
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

== Differences ==
With the same code, different operation codes are generated for IIf function.

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>
Op2 is type for this OpCode:
<pre>// SbiDisas::TypeOp
pTypes[][13] = {
"Empty","Null","Integer","Long","Single","Double",
"Currency","Date","String","Object","Error","Boolean",
"Variant" };
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

== Code ==
<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
// SbiExprList::Gen in exprgen.cxx
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
// SbiExprList::Gen in exprgen.cxx
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
// SbiExprNode::GenElement in exprgen.cxx
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
// SbiParser::Symbol in parser.cxx
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
// SbiParser::DefProc in dim.cxx
</pre>

In SbiParser::CheckRTLForSym method, pVar->GetType() call should return SbxEMPTY for rSym == "IIf". But SbxINTEGER is returned when the problem was happen. The return value of the function, instance of SbiSymDef gets wrong type.
Then the wrong type is passed to new SbiExprNode instance in SbiExpression::Term method.

User:Hanya/Iif Problem

2014-12-20T09:30:16Z

Hanya: /* Differences */ Add about Op2 code

User:Hanya/Iif Problem

2014-12-20T09:27:03Z

Hanya: Fix section tags

User:Hanya/Iif Problem

2014-12-20T09:25:33Z

Hanya: Add initial content of this page

Issue: https://issues.apache.org/ooo/show_bug.cgi?id=63614

Error code 87302 is produced when some code is modified contains Iif runtime function.

** Disassembled Original
<pre>
Sub Main
IIf(true, 1.0, "")
End Sub
</pre>

<pre>
Position Op Op1 Op2 OpStr
-----------------------------------------
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000 // Label
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, 1.0, "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC // new argv
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 40 00000004 NUMBER "1"
00000027 19 ARGV
00000028 41 00000005 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

** Disassembled with Problem
Second argument for IIf function is changed from 1.0 to "".
Execute the code after the change -> strange error.
<pre>
Sub Main
IIf(true, "", "")
End Sub
</pre>

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

** Disassembled without Problem after Restarting
After the modification and error mentioned above, restart the office.
And then execute the code, no error.

<pre>
00000000 Lbl00000000:
00000000 45 00000000 JUMP Lbl0000
; Sub Main
00000005 Main:
00000005 87 00000003 00000000 STMNT 3,0 (For-Level: 0)
; IIf(true, "", "")
0000000E 87 00000004 00000000 STMNT 4,0 (For-Level: 0)
00000017 18 ARGC
00000018 80 00000002 0000000C RTL true ; Variant
00000021 19 ARGV
00000022 41 00000004 STRING ""
00000027 19 ARGV
00000028 41 00000004 STRING ""
0000002D 19 ARGV
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
00000037 1C GET
; End Sub
00000038 87 00000005 00000000 STMNT 5,0 (For-Level: 0)
00000041 2B LEAVE
</pre>

** Differences
With the same code, different operation codes are generated for IIf function.

<pre>
// with problem
0000002E 80 00008003 00000002 RTL IIf ; Integer, Args
// restarted
0000002E 80 00008003 00000000 RTL IIf ; Empty, Args
</pre>

The error code 87302 is set in SbxValue::SetType (t is not equal to aData.eType) method.
Therefore the problem is caused by the wrong compilation when the code is modified.

User:Hanya

2014-12-20T07:43:35Z

Hanya: Add link to Iif problem page

User:Hanya/New Field on Writer

2014-05-16T12:06:13Z

Hanya: Add note when adding new field on Writer

On Fields dialog of Writer document, the order of sub types for ExtUser fields should be match with SwExtUserSubType enum values. If not match with them, illegal value would be taken.

User:Hanya

2014-05-16T12:03:43Z

Hanya: /* Notes */

Documentation/DevGuide/OfficeDev/XML Filter Detection

2014-02-11T15:06:09Z

Hanya: i21766 Data property can not contain new line

{{Documentation/DevGuide/OfficeDevTOC
|OfficeDev2b=block
|OfficeDevInteg=block
|OfficeDevXMLFilter=block
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/OfficeDev/The Exporter
|NextPage=Documentation/DevGuide/OfficeDev/Number Formats
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/OfficeDev/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:XML Filter Detection}}
__NOTOC__

The number of XML files that conform to differing DTD specifications means that a single filter and file type definition is insufficient to handle all of the possible formats available. In order to allow {{PRODUCTNAME}} to handle multiple filter definitions and implementations, it is necessary to implement an additional filter detection module that is capable of determining the type of XML file being read, based on its <code>DocType</code> declaration.

To accomplish this, a filter detection service <idl>com.sun.star.document.ExtendedTypeDetection</idl> can be implemented, which is capable of handling and distinguishing between many different XML based file formats. This type of service supersedes the basic ''flat'' detection, which uses the file's suffix to determine the Type, and instead, carries out a ''deep'' detection which uses the file's internal structure and content to detect its true type.

=== Requirements for Deep Detection ===

There are three requirements for implementing a deep detection module that is capable of identifying one or more unique XML types. These include:

* An extended type definition for describing the format in more detail (''TypeDetection.xcu'').
* A <code>DetectService</code> implementation.
* A <code>DetectService</code> definition (''TypeDetection.xcu'').

=== Extending the File Type Definition ===

Since many different XML files can conform to different DTDs, the type definition of a particular XML file needs to be extended. To do this, some or all of the <code>DocType</code> information can be contained as part of the file type definition. This information is held as part of the <code>ClipboardFormat</code> property of the type node. A unique namespace or preface identifies the string at this point in the sequence as being a <code>DocType</code> declaration.

==== Sample Type definition: ====
<source lang="xml">
<node oor:name="writer_DocBook_File" oor:op="replace">
<prop oor:name="UIName">
<value XML:lang="en-US">DocBook</value>
</prop>
<prop oor:name="Data">
<value>0,,doctype:-//OASIS//DTD DocBook XML V4.1.2//EN,,XML,20002,</value>
</prop>
</node>
</source>
=== The ExtendedTypeDetection Service Implementation ===

In order for the type detection code to function as an <code>ExtendedTypeDetection</code> service, you must implement the <code>detect()</code> method as defined by the <idl>com.sun.star.document.XExtendedFilterDetection</idl> interface definition:
<source lang="cpp">
string detect( [inout]sequence<com::sun::star::beans::PropertyValue > Descriptor );
</source>
This method supplies you with a sequence of <code>PropertyValue</code>s from which you can use to extract the current <code>TypeName</code> and the <code>URL</code> of the file being loaded:
<source lang="cpp">
::rtl::OUString SAL_CALL FilterDetect::detect(com::sun::star::uno::Sequence< com::sun::star::beans::PropertyValue >& aArguments ) throw (com::sun::star::uno::RuntimeException)
{
const PropertyValue * pValue = aArguments.getConstArray();
sal_Int32 nLength;
::rtl::OString resultString;
nLength = aArguments.getLength();
for (sal_Int32 i = 0; i < nLength; i++) {
if (pValue[i].Name.equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("TypeName"))) {
}
else if (pValue[i].Name.equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("URL"))) {
pValue[i].Value >>= sUrl;
}
}
</source>
Once you have the URL of the file, you can then use it to create a <code>::ucb::Content</code> from which you can open an <code>XInputStream</code> to the file:
<source lang="cpp">
Reference< com::sun::star::ucb::XCommandEnvironment > xEnv;
::ucb::Content aContent(sUrl,xEnv);
xInStream = aContent.openStream();
</source>
You can now use this <code>XInputStream</code> to read the header of the file being loaded. Because the exact location of the <code>DocType</code> information within the file is not known, the first 1000 bytes of information will be read:
<source lang="cpp">
::rtl::OString resultString;
com::sun::star::uno::Sequence< sal_Int8 > aData;
long bytestRead = xInStream->readBytes (aData, 1000);
resultString = ::rtl::OString( (const sal_Char *)aData.getConstArray(), bytestRead);
</source>
Once you have this information, you can start looking for a type that describes the file being loaded. In order to do this, you need to get a list of the types currently supported:
<source lang="cpp">
Reference <XNameAccess> xTypeCont(mxMSF->createInstance(OUString::createFromAscii(
"com.sun.star.document.TypeDetection" )),UNO_QUERY);
Sequence <::rtl::OUString> myTypes= xTypeCont->getElementNames();
nLength = myTypes.getLength();
</source>
For each of these types, you must first determine whether the <code>ClipboardFormat</code> property contains a DocType:
<source lang="cpp">
Loc_of_ClipboardFormat=...;
Sequence<::rtl::OUString> ClipboardFormatSeq;
Type_Props[Loc_of_ClipboardFormat].Value >>=ClipboardFormatSeq ;
while() {
if(ClipboardFormatSeq.match(OUString::createFromAscii("doctype:") {
//if it contains a DocType, start to compare to header
}
}
</source>
All of the possible <code>DocType</code> declarations of the file types can be checked to determine a match. If a match is found, the type corresponding to the match is returned. If no match is found, an empty string is returned. This will force {{PRODUCTNAME}} into flat detection mode.

=== TypeDetection.xcu DetectServices Entry ===

Now that you have created the <code>ExtendedTypeDetection</code> service implementation, you need to tell {{PRODUCTNAME}} when to use this service.

First create a <code>DetectServices</code> node, unless one already exists, and then add the information specific to the detection service that has been implemented, that is, the name of the service and the file types that use it.
<source lang="xml">
<node oor:name="DetectServices">
<node oor:name="com.sun.star.comp.filters.XMLDetect" oor:op="replace">
<prop oor:name="ServiceName">
<value XML:lang="en-US">com.sun.star.comp.filters.XMLDetect</value>
</prop>
<prop oor:name="Types">
<value>writer_DocBook_File</value>
<value>writer_Flat_XML_File</value>
</prop>
</node>
</node>
</source>
{{PDL1}}

[[Category:Documentation/Developer's Guide/Office Development]]

Documentation/DevGuide/Scripting/Writing Macros

2014-02-03T06:36:07Z

Hanya: Add description about manifest entries when Java macro embedded in document

{{Documentation/DevGuide/ScriptingTOC
|ShowPrevNext=block
|PrevPage=Documentation/DevGuide/Scripting/Macro Recording
|NextPage=Documentation/DevGuide/Scripting/How the Scripting Framework Works
}}
{{Documentation/DevGuideLanguages|Documentation/DevGuide/Scripting/{{SUBPAGENAME}}}}
{{DISPLAYTITLE:Writing Macros}}
__NOTOC__
=== The HelloWorld macro ===
Here is a comparison of HelloWorld macros in the different script languages available in {{PRODUCTNAME}}.

==== Basic ====
<source lang="oobas">
Sub writeHelloWorld()
Dim oDoc As Object, xText As Object, xTextRange As Object

oDoc = ThisComponent
xText = oDoc.getText()
xTextRange = xText.getEnd()
xTextRange.CharBackColor = 1234567
xTextRange.CharHeight = 16.0
' CharUnderline receives a group constant
xTextRange.CharUnderline = com.sun.star.awt.FontUnderline.WAVE
' CharPosture receives an enum
xTextRange.CharPosture = com.sun.star.awt.FontSlant.ITALIC
xTextRange.setString( "Hello World (in Basic)" )
End Sub
</source>
Basic interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

SomeType getSomeProperty()
void setSomeProperty(SomeType aValue)

Using these facilities some lines can be simplified:
<source lang="oobas">
xText = oDoc.Text
xTextRange = xText.End
xTextRange.String = "Hello World (in Basic)"
</source>

Service properties can be directly accessed in Basic, it is not necessary to use <code>getPropertyValue</code> or <code>setPropertyValue</code> methods.

==== BeanShell ====
As BeanShell accepts typeless variables, the code is simplified compared to Java.
<source lang="java">
import com.sun.star.uno.UnoRuntime;
import com.sun.star.text.XTextDocument;
import com.sun.star.text.XText;
import com.sun.star.text.XTextRange;
import com.sun.star.beans.XPropertySet;
import com.sun.star.awt.FontSlant;
import com.sun.star.awt.FontUnderline;

oDoc = XSCRIPTCONTEXT.getDocument();

xTextDoc = UnoRuntime.queryInterface(XTextDocument.class,oDoc);
xText = xTextDoc.getText();
xTextRange = xText.getEnd();
pv = UnoRuntime.queryInterface(XPropertySet.class, xTextRange);

pv.setPropertyValue("CharBackColor", 1234567);
pv.setPropertyValue("CharHeight", 16.0);
// CharUnderline receives a group constant
pv.setPropertyValue("CharUnderline", com.sun.star.awt.FontUnderline.WAVE);
// CharPosture receives an enum
pv.setPropertyValue("CharPosture", com.sun.star.awt.FontSlant.ITALIC) ;

xTextRange.setString( "Hello World (in BeanShell)" );
return 0;
</source>

BeanShell interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

SomeType getSomeProperty()
void setSomeProperty(SomeType aValue)

Using these facilities some lines can be simplified:

<source lang="java">
xText = xTextDoc.Text;
xTextRange = xText.End;
xTextRange.String = "Hello World (in BeanShell)";
</source>

Service properties are only accessed with <code>getPropertyValue</code> or <code>setPropertyValue</code>.

==== JavaScript ====
As JavaScript accepts typeless variables, the code is simplified compared to Java.
<source lang="javascript">
importClass(Packages.com.sun.star.uno.UnoRuntime)
importClass(Packages.com.sun.star.text.XTextDocument)
importClass(Packages.com.sun.star.text.XText)
importClass(Packages.com.sun.star.text.XTextRange)
importClass(Packages.com.sun.star.beans.XPropertySet)
importClass(Packages.com.sun.star.awt.FontSlant)
importClass(Packages.com.sun.star.awt.FontUnderline)

oDoc = XSCRIPTCONTEXT.getDocument()
xTextDoc = UnoRuntime.queryInterface(XTextDocument,oDoc)
xText = xTextDoc.getText()
xTextRange = xText.getEnd()
pv = UnoRuntime.queryInterface(XPropertySet, xTextRange)

pv.setPropertyValue("CharHeight", 16.0) // Double
// CharBackColor receives an Integer
pv.setPropertyValue("CharBackColor", new java.lang.Integer(1234567))
// CharUnderline receives a group constant
pv.setPropertyValue("CharUnderline",
new java.lang.Short(Packages.com.sun.star.awt.FontUnderline.WAVE))
// CharPosture receives an enum
pv.setPropertyValue("CharPosture", Packages.com.sun.star.awt.FontSlant.ITALIC)
xTextRange.setString( "Hello World (in JavaScript)" )
</source>

JavaScript does not accept the simplifications seen in Basic and BeanShell.

Setting an integer value to a property requires to use a java class.

==== Java ====
Other sections of this document provide numerous Java examples. Here is the HelloWorld provided in {{PRODUCTNAME}}
<source lang="java">
import com.sun.star.uno.UnoRuntime;
import com.sun.star.frame.XModel;
import com.sun.star.text.XTextDocument;
import com.sun.star.text.XTextRange;
import com.sun.star.text.XText;
import com.sun.star.script.provider.XScriptContext;

public class HelloWorld {
public static void printHW(XScriptContext xScriptContext)
{
XModel xDocModel = xScriptContext.getDocument();

// getting the text document object
XTextDocument xtextdocument = (XTextDocument) UnoRuntime.queryInterface(
XTextDocument.class, xDocModel);

XText xText = xtextdocument.getText();
XTextRange xTextRange = xText.getEnd();
xTextRange.setString( "Hello World (in Java)" );
}
}
</source>

===== Compiling and Deploying Java macros =====

Because Java is a compiled language it is not possible to execute Java source code as a macro directly from within {{PRODUCTNAME}}. The code must first be compiled and then deployed within a {{PRODUCTNAME}} installation or document. The following steps show how to create a Java macro using the HelloWorld example code:

* Create a ''HelloWorld'' directory for your macro
* Create a ''HelloWorld.java'' file using the HelloWorld source code
* Compile the ''HelloWorld.java'' file. The following jar files from the ''program/classes'' directory of a {{PRODUCTNAME}} installation must be in the classpath: ''ridl.jar'', ''unoil.jar'', ''jurt.jar''
* Create a ''HelloWorld.jar'' file containing the ''HelloWorld.class'' file
* Create a ''parcel-descriptor.xml'' file for your macro
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<parcel language="Java" xmlns:parcel="scripting.dtd">
<script language="Java">
<locale lang="en">
<displayname value="HelloWorld"/>
<description>
Prints "Hello World".
</description>
</locale>
<functionname value="HelloWorld.printHW"/>
<logicalname value="HelloWorld.printHW"/>
<languagedepprops>
<prop name="classpath" value="HelloWorld.jar"/>
</languagedepprops>
</script>
</parcel>
</source>
The ''parcel-descriptor.xml'' file is used by the Scripting Framework to find macros. The functionname element indicates the name of the Java method which should be executed as a macro. The classpath element can be used to indicate any jar or class files which are used by the macro. If the classpath element is not included, then the directory in which the ''parcel-desciptor.xml'' file is found and any jar files in that directory will be used as the classpath. The necessary Java UNO classes are available automatically.

* Copy the HelloWorld directory into the ''share/Scripts/java'' (or ''basis/share/Scripts/java'') directory of a {{PRODUCTNAME}} installation or into the ''user/Scripts/java'' directory of a user installation. If you want to deploy the macro to a document you need to place it in a ''Scripts/java'' directory within the document zip file.
* If {{PRODUCTNAME}} is running, you will need to restart it in order for the macro to appear in the Macro Selector dialog.

{{Documentation/Note|The ''parcel-descriptor.xml'' file is also used to detect BeanShell and JavaScript macros. It is created automatically when creating macros using the Organizer dialogs for BeanShell and JavaScript.}}

If these files are embedded in document file, they have to be registered in META-INF/manifest.xml:
<source lang="xml">
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="Scripts/java/Test/parcel-descriptor.xml"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/java/Test/test.jar"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/java/Test/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/java/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/"/>
</source>

==== Python ====

A Python module may contain several scripts.
<source lang="python">
def HelloPython( ):
import uno

def HelloPython( ):
oDoc = XSCRIPTCONTEXT.getDocument()
xText = oDoc.getText()
xTextRange = xText.getEnd()

xTextRange.CharHeight = 16.0
xTextRange.CharBackColor = 1234567
# CharUnderline receives a group constant
xTextRange.CharUnderline = uno.getConstantByName("com.sun.star.awt.FontUnderline.WAVE")
# CharPosture receives an enum
xTextRange.CharPosture = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")

xTextRange.setString( "Hello World (in Python)" )
return None
</source>
Python interprets pairs of get and set methods at UNO objects as object properties if they follow this pattern:

SomeType getSomeProperty()
void setSomeProperty(SomeType aValue)

Using these facilities some lines can be simplified:
<source lang="python">
xText = oDoc.Text
xTextRange = xText.End
xTextRange.String = "Hello World (in Python)"
</source>
Service properties can be directly accessed in Python, no need to use <code>getPropertyValue</code> or <code>setPropertyValue</code>.

=== Features of script languages supported by {{PRODUCTNAME}} ===

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!Language feature
!Basic
!BeanShell
!JavaScript
!Java macro
!Python
|-
|Interpreted
|Yes
|Yes
|Yes
|No
|Yes
|-
|Integrated editor
|Yes, colored
|Yes
|Yes
|No
|No
|-
|Integrated debugger
|Yes
|No
|Yes
|No
|No
|-
|Script organizer
|Yes
|Yes
|Yes
|No
|No
|-
|Script encryption
|Possible
|No
|No
|No
|No
|-
|Typeless variables
|Yes: Variant
|Yes
|Yes
|No
|Yes
|-
|Getter/Setter
|Yes
|Yes
|No
|No
|Yes
|-
|Direct property access
|Yes
|No
|No
|No
|Yes
|-
|Function for Calc formula
|Yes
|No
|No
|No
|No
|-
|UNO component creation
|No
|No
|No
|Yes
|Yes
|}

=== Using the {{PRODUCTNAME}} API from macros ===

BeanShell, JavaScript, Java, Python macros are supplied with a variable of type <idl>com.sun.star.script.provider.XScriptContext</idl> which can be used to access the {{PRODUCTNAME}} API. This interface has three methods:

* <idl>com.sun.star.frame.XModel</idl> <code>getDocument( )</code>
:Returns the <code>XModel</code> interface of the document for which the macro was invoked (see [[Documentation/DevGuide/OfficeDev/Using the Component Framework|Using the Component Framework]])
* <idl>com.sun.star.frame.XDesktop</idl> <code>getDesktop( )</code>
:Returns the <code>XDesktop</code> interface for the application which can be used to access open document, and load documents (see [[Documentation/DevGuide/OfficeDev/Using the Desktop|Using the Desktop]])
* <idl>com.sun.star.uno.XComponentContext</idl> <code>getComponentContext( )</code>
:Returns the <code>XComponentContext</code> interface which is used to create instances of services (see [[Documentation/DevGuide/ProUNO/Service Manager and Component Context|Service Manager and Component Context]])

Depending on the language the macro accesses <code>XScriptContext</code> in different ways:

* '''BeanShell''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''JavaScript''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument();

* '''Java''': The first parameter passed to the macro method is always of type <code>XScriptContext</code>
Xmodel xDocModel = xScriptContext.getDocument();

* '''Python''': Using the global variable <code>XSCRIPTCONTEXT</code>
oDoc = XSCRIPTCONTEXT.getDocument()

=== Handling arguments passed to macros ===

In certain cases arguments may be passed to macros, for example, when a macro is assigned to a button in a document. In this case the arguments are passed to the macro as follows:

* '''BeanShell''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = (ActionEvent) ARGUMENTS[0];

* '''JavaScript''': In the global <code>Object[]</code> variable <code>ARGUMENTS</code>
event = ARGUMENTS[0];

* '''Java''': The arguments are passed as an <code>Object[]</code> in the second parameter to the macro method
public void handleButtonPress(
XScriptContext xScriptContext, Object[] args)

Each of the arguments in the <code>Object[]</code> are of the UNO type Any. For more information on how the Any type is used in Java see [[Documentation/DevGuide/ProUNO/Java/Type Mappings|Type Mappings]].

The ButtonPressHandler macros in the Highlight library of a {{PRODUCTNAME}} installation show how a macro can handle arguments.

* '''Python''': The arguments are passed as parameters of the called function.

=== Creating dialogs from macros ===

Dialogs which have been built in the Dialog Editor can be loaded by macros using the <idl>com.sun.star.awt.XDialogProvider</idl> API. The method <code>createDialog()</code> from interface <code>XDialogProvider</code> uses a string as a parameter. This string is the URL to the dialog. It is formed as follows:

vnd.sun.star.script:DIALOGREF?location=[application|document]

where <code>DIALOGREF</code> is the name of the dialog that you want to create, and location is either application or document depending on where the dialog is stored.

For example if you wanted to load dialog called MyDialog, which is in a Dialog Library called MyDialogLibrary in the {{PRODUCTNAME}} dialogs area of your installation then the URL would be:

vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application

If you wanted to load a dialog called MyDocumentDialog which in a library called MyDocumentLibrary which is located in a document then the URL would be:

vnd.sun.star.script:MyDocumentLibrary.MyDocumentDialog?location=document

The following code shows how to create a dialog from a Java macro:
<source lang="java">
public XDialog getDialog(XScriptContext context)
{
XDialog theDialog;

// We must pass the XModel of the current document when creating a DialogProvider object
Object[] args = { context.getDocument() };

Object obj;
try {
obj = xmcf.createInstanceWithArgumentsAndContext(
"com.sun.star.awt.DialogProvider", args, context.getComponentContext());
}
catch (com.sun.star.uno.Exception e) {
System.err.println("Error getting DialogProvider object");
return null;
}

XDialogProvider xDialogProvider = (XDialogProvider)
UnoRuntime.queryInterface(XDialogProvider.class, obj);

// Got DialogProvider, now get dialog
try {
theDialog = xDialogProvider.createDialog(
"vnd.sun.star.script:MyDialogLibrary.MyDialog?location=application");
}
catch (java.lang.Exception e) {
System.err.println("Got exception on first creating dialog: " + e.getMessage());
}
return theDialog;
}
</source>

=== Calling a macro with the Scripting Framework ===

The service <idl>com.sun.star.script.provider.ScriptProvider</idl> exports interface <idls>com.sun.star.script.provider.XScriptProvider</idls> which offers method <code>getScript( )</code>. This method returns an interface <idls>com.sun.star.script.provider.XScript</idls> which offers the method <code>invoke( )</code> which will call the script with parameters if necessary.

The identity and location of the called script is contained in an URI, which follows a [[Documentation/DevGuide/Scripting/Scripting_Framework_URI_Specification|particular syntax]].

Here are links to some code examples written by the community:
* [http://codesnippets.services.openoffice.org/Office/Office.HowToCallJavaProgramUsingScriptingFramework.snip Java calling a Java script]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=69328 Java calling a Basic macro]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=59534 Basic macro calling a Python script]
* [http://www.oooforum.org/forum/viewtopic.phtml?t=69350 Python script calling a Basic macro]

{{PDL1}}

[[Category:Documentation/Developer's Guide/Scripting]]

Python/Transfer from Basic to Python

2013-12-19T03:03:54Z

Hanya: Fix Executing Macros from Toolbar Buttons section to be heading

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==
In Basic, you can call subroutines defined in other modules or other libraries that has been loaded.
<source lang="Python">
BasicLibraries.loadLibrary("Library1")
Library1.Foo()
</source>
In Python, you can import some modules that can be found in sys.path list. If you want to import your own module placed inside Scripts/python directory, put your module in pythonpath directory nearby your script file.
<pre>
- Scripts/
- python/
- macro.py
- pythonpath/ # this directory is added automatically before your macro executed
- your_module.py # this module can be found
</pre>
When you execute the macro from your script file, the internal executor adds the pythonpath/ directory to sys.path list to be used as one of lookup location.

Please keep in mind, the name of module conflict each other if you have the same named module in the some location, this is the standard python mechanism of importing modules, put your each modules in differently named library to avoid the name conflict.

== Dialog ==
In Basic, there is CreateUnoDialog runtime function to instantiate the dialog.
<source lang="Python">
DialogLibraries.loadLibrary("Standard")
dialog = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
dialog.execute()
dialog.dispose()
</source>
In Python, such shortcut function is not provided but you can easily instantiate your dialog using <idl>com.sun.star.awt.DialogProvider</idl> service.
<source lang="Python">
def dialog_example():
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)
dialog = dp.createDialog("vnd.sun.star.script:Standard.Dialog1?location=user")
dialog.execute()
dialog.dispose()
</source>

== Message Box ==
In Basic, you can use MsgBox runtime function to show some message to the users.
<source lang="Python">
Msgbox "Hello."
</source>
In Python, no shortcut function is provided but you can use <idl>com.sun.star.awt.XMessageBoxFactory</idl> interface through the toolkit.

<source lang="Python">
def messagebox(ctx, parent, message, title, message_type, buttons):
""" Show message in message box. """
toolkit = parent.getToolkit()
older_imple = check_method_parameter(
ctx, "com.sun.star.awt.XMessageBoxFactory", "createMessageBox",
1, "com.sun.star.awt.Rectangle")
if older_imple:
msgbox = toolkit.createMessageBox(
parent, Rectangle(), message_type, buttons, title, message)
else:
message_type = uno.getConstantByName("com.sun.star.awt.MessageBoxType." + {
"messbox": "MESSAGEBOX", "infobox": "INFOBOX",
"warningbox": "WARNINGBOX", "errorbox": "ERRORBOX",
"querybox": "QUERYBOX"}[message_type])
msgbox = toolkit.createMessageBox(
parent, message_type, buttons, title, message)
n = msgbox.execute()
msgbox.dispose()
return n

def check_method_parameter(ctx, interface_name, method_name, param_index, param_type):
""" Check the method has specific type parameter at the specific position. """
cr = create_service(ctx, "com.sun.star.reflection.CoreReflection")
try:
idl = cr.forName(interface_name)
m = idl.getMethod(method_name)
if m:
info = m.getParameterInfos()[param_index]
return info.aType.getName() == param_type
except:
pass
return False
</source>

== Input Box ==

No function provided for Python, you have to make your own one.

== Executing Macros from Toolbar Buttons ==
In Basic, you can call any subroutines or functions through toolbar buttons.
<source lang="Python">
Sub WriteHello()
ThisComponent.getText().getEnd().setString("Hello!")
End Sub
</source>

In Python, you have to define your Python function with an argument (or variable length arguments) to take an argument passed when the function executed through assigned toolbar button.
<source lang="Python">
def writeHello(*args):
# writeHello(arg): is also ok but if you want to call this function
# by some ways, define your function takes variable arguments.
XSCRIPTCONTEXT.getDocument().getText().getEnd().setString("Hello!")
</source>

[[Category:Python]]

Python/Transfer from Basic to Python

2013-12-17T08:35:00Z

Hanya: Added Executing Macros from Toolbar Buttons section

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==
In Basic, you can call subroutines defined in other modules or other libraries that has been loaded.
<source lang="Python">
BasicLibraries.loadLibrary("Library1")
Library1.Foo()
</source>
In Python, you can import some modules that can be found in sys.path list. If you want to import your own module placed inside Scripts/python directory, put your module in pythonpath directory nearby your script file.
<pre>
- Scripts/
- python/
- macro.py
- pythonpath/ # this directory is added automatically before your macro executed
- your_module.py # this module can be found
</pre>
When you execute the macro from your script file, the internal executor adds the pythonpath/ directory to sys.path list to be used as one of lookup location.

Please keep in mind, the name of module conflict each other if you have the same named module in the some location, this is the standard python mechanism of importing modules, put your each modules in differently named library to avoid the name conflict.

== Dialog ==
In Basic, there is CreateUnoDialog runtime function to instantiate the dialog.
<source lang="Python">
DialogLibraries.loadLibrary("Standard")
dialog = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
dialog.execute()
dialog.dispose()
</source>
In Python, such shortcut function is not provided but you can easily instantiate your dialog using <idl>com.sun.star.awt.DialogProvider</idl> service.
<source lang="Python">
def dialog_example():
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
dp = smgr.createInstanceWithContext("com.sun.star.awt.DialogProvider", ctx)
dialog = dp.createDialog("vnd.sun.star.script:Standard.Dialog1?location=user")
dialog.execute()
dialog.dispose()
</source>

== Message Box ==
In Basic, you can use MsgBox runtime function to show some message to the users.
<source lang="Python">
Msgbox "Hello."
</source>
In Python, no shortcut function is provided but you can use <idl>com.sun.star.awt.XMessageBoxFactory</idl> interface through the toolkit.

<source lang="Python">
def messagebox(ctx, parent, message, title, message_type, buttons):
""" Show message in message box. """
toolkit = parent.getToolkit()
older_imple = check_method_parameter(
ctx, "com.sun.star.awt.XMessageBoxFactory", "createMessageBox",
1, "com.sun.star.awt.Rectangle")
if older_imple:
msgbox = toolkit.createMessageBox(
parent, Rectangle(), message_type, buttons, title, message)
else:
message_type = uno.getConstantByName("com.sun.star.awt.MessageBoxType." + {
"messbox": "MESSAGEBOX", "infobox": "INFOBOX",
"warningbox": "WARNINGBOX", "errorbox": "ERRORBOX",
"querybox": "QUERYBOX"}[message_type])
msgbox = toolkit.createMessageBox(
parent, message_type, buttons, title, message)
n = msgbox.execute()
msgbox.dispose()
return n

def check_method_parameter(ctx, interface_name, method_name, param_index, param_type):
""" Check the method has specific type parameter at the specific position. """
cr = create_service(ctx, "com.sun.star.reflection.CoreReflection")
try:
idl = cr.forName(interface_name)
m = idl.getMethod(method_name)
if m:
info = m.getParameterInfos()[param_index]
return info.aType.getName() == param_type
except:
pass
return False
</source>

== Input Box ==

No function provided for Python, you have to make your own one.

== Executing Macros from Toolbar Buttons
In Basic, you can call any subroutines or functions through toolbar buttons.
<source lang="Python">
Sub WriteHello()
ThisComponent.getText().getEnd().setString("Hello!")
End Sub
</source>

In Python, you have to define your Python function with an argument (or variable length arguments) to take an argument passed when the function executed through assigned toolbar button.
<source lang="Python">
def writeHello(*args):
# writeHello(arg): is also ok but if you want to call this function
# by some ways, define your function takes variable arguments.
XSCRIPTCONTEXT.getDocument().getText().getEnd().setString("Hello!")
</source>

[[Category:Python]]

Using Python on Windows

2013-12-12T06:22:18Z

Hanya: Add description about recent installer

{{Extensions}}
===Introduction to Python on OOo===

You need OpenOffice.org installed with its Python-UNO bridge.

If you do not customize the installation, Python-UNO bridge is installed as default on recent version.
Install OpenOffice.org. If you are installing it for the first time, then be sure to do a Custom install and install the Python-UNO bridge under Optional Components.

If you already have OpenOffice.org installed, then go into your OOo folder and run Setup. Pick Modify, click Next. Under Optional Components, be sure to install the Python-UNO bridge.

In order to use the python-uno bridge, the python code must run from the Python that comes with OOo 1.1.0. There is apparently some issue with the standard C library. The Python 2.2.2 that comes with OOo has been compiled using the StdCLib that OOo uses rather than the one that python would normally be compiled with.

If you want an interactive Python command shell right now, go into your OOo\program subfolder and run the batch file named ''python.bat''. You get a python shell. You can then use the statement Code:
import uno
You can now connect to any OOo that will accept a remote UNO connection.

I suppose that leads us to the next issue.... Configuring OOo to listen for UNO connections.

It is also possible to write a component in Python and install it into the office. It is my understanding (but I have not tried yet) that when you do this you do NOT need to configure OOo to listen for uno connections.

Therefore, the two ways to use Python are...
* Outside of OOo -- with a remote uno connection.
* Inside of OOo -- as an installed component.

Approach 1 is the quick and easy way to write and debug code.

Approach 2 is a great way to _deliver_ finished code to a user.

See this for more information about the Python-UNO bridge in OOo.
http://udk.openoffice.org/python/python-bridge.html

===Configuring OOo to listen for UNO connections===

If you write programs in Java or Python and run them external to OOo, then you need to configure OOo to listen for a uno connection.

It is possible to run your program on computer A, and connect to computer B which is running OOo, and have your program at A manipulate the OOo running on B. In fact, A and B can even be running different operating systems. I have done this personally using Java. With Python, I have only run my program on the same computer as OOo -- but it should work the same way.

In the past, it was necessary to either
* launch OOo with a special parameter to make it listen
* hand edit one of OOo's configuration files

Both of the above options I explained here previously.
http://www.oooforum.org/forum/viewtopic.php?p=12370#12370

You can hand edit an XML file for version 1.0 of OOo, or an XCU file for version 1.1 of OOo (the current version).

Later, I developed a macro to do this editing and announced it here.
http://www.oooforum.org/forum/viewtopic.php?t=3754

My '''UnoConnectionListener document''' can be obtained from OOoMacros.org.

http://ooomacros.org/files.php?type=macro#UNOConnectionListener

http://sourceforge.net/project/showfiles.php?group_id=87718&package_id=100069

Just download the document. Open it. Configure text boxes to taste. (Read the text of the above post if necessary.) Then click a button. Quit OOo. Re-launch OOo and it should henceforth (until you reconfigure it again) always listen for Uno connections. You can configure it to listen to connections only from localhost, or from any other computer.
[[Category:Extensions]]
[[Category:Python]]

Python/Transfer from Basic to Python

2013-10-03T09:28:10Z

Hanya: /* Input Box */

Python/Transfer from Basic to Python

2013-10-03T09:20:18Z

Hanya: Add code to message box section

Python/Transfer from Basic to Python

2013-10-03T09:14:42Z

Hanya: Add short description about message box

Python/Transfer from Basic to Python

2013-10-03T09:08:30Z

Hanya: Add description about Dialog creation

Python/Transfer from Basic to Python

2013-10-03T08:53:37Z

Hanya: Add description about Importing Modules

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==
In Basic, you can call subroutines defined in other modules or other libraries that has been loaded.
<source lang="Python">
BasicLibraries.loadLibrary("Library1")
Library1.Foo()
</source>
In Python, you can import some modules that can be found in sys.path list. If you want to import your own module placed inside Scripts/python directory, put your module in pythonpath directory nearby your script file.
<pre>
- Scripts/
- python/
- macro.py
- pythonpath/ # this directory is added automatically before your macro executed
- your_module.py # this module can be found
</pre>
When you execute the macro from your script file, the internal executor adds the pythonpath/ directory to sys.path list to be used as one of lookup location.

Please keep in mind, the name of module conflict each other if you have the same named module in the some location, this is the standard python mechanism of importing modules, put your each modules in differently named library to avoid the name conflict.

== Dialog ==

== Message Box ==

== Input Box ==

[[Category:Python]]

Python/Transfer from Basic to Python

2013-10-03T08:01:58Z

Hanya: /* Listener and Interface */

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have to define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):
pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==

== Dialog ==

== Message Box ==

== Input Box ==

[[Category:Python]]

Python/Transfer from Basic to Python

2013-10-03T07:36:47Z

Hanya: Add Type section

{{DISPLAYTITLE:Transfer from Basic to Python}}

Translation [[ES/Manuales/GuiaAOO/TemasAvanzados/Macros/Python/BasicAPython| Español]]

If you feel some displeasure at StarBasic/OpenOffice Basic or you meet requirement of custom UNO component, now it is the time to transfer coding environment from Basic to Python.

In StarBasic, there are some runtime function provides shortcut to do something. But using Python-UNO bridge, you have to do such task by API ways.

Let's start with Python's tutorial and return back to here when you have learned a bit about Python language.

== Macro Location ==
On the current version, script organizer for Python do not provide the way to manage script files. So you have to manage yourself. Macros written in Python should be placed in the specific directory under your user's profile, shared profile or script directory of your document.

The python directory (in all lowercase) should be created in Scripts directory and you can put your python scripts that contain python code.
<pre>
path_to_directory/Scripts/python/your_file.py
</pre>

You can make subdirectories to put macro files in them under Scripts/python directory.

You have to add "py" file extension to your file name.

== Macro Editor ==

There is no built-in editor dedicated to code in Python. But you can choose your favorite text editor application to edit your Python script.

This is discussed in another page.

== Short Example ==

Here is a small example written in Python.

<source lang="python">
def hello():
XSCRIPTCONTEXT.getDocument().getText().setString("Hello!")
</source>
Each callable function is the executable unit of Python macro (you can choose which function should be listed in the GUI, see other document).

You can access the current document through getDocument method of XSCRIPTCONTEXT variable of the module. And it changes the document content to "Hello!" of the Writer document.

== Usable Modules ==

<source lang="Python">
import uno

import unohelper
</source>

== Script Context ==

StarBasic is embedded runtime and it always works with living instance of the office. So the context is always the match with the office's one. But Python-UNO bridge provides the way to work as RPC client. At that time, remote Python instance does have different context from the office instance. Therefore you have to use correct component context to tell to the multi component factory to instantiate a service.

In StarBasic, you have no matching object provided.

'''In Python''' macro, you have to use '''XSCRIPTCONTEXT''' module variable that provides <idl>com.sun.star.script.provider.XScriptContext</idl> interface.

* <idl>com.sun.star.frame.XModel</idl> '''getDocument()'''
:Returns current document object.
* <idl>com.sun.star.document.XScriptInvocationContext</idl> '''getInvocationContext()'''
:Returns invocation dependent object.
* <idl>com.sun.star.frame.XDesktop</idl> '''getDesktop()'''
:Returns instance of <idl>com.sun.star.frame.Desktop</idl> service.
* <idl>com.sun.star.uno.XComponentContext</idl> '''getComponentContext()'''
:Returns current component context that is used to tell the which context is.

Please keep in mind, '''XSCRIPTCONTEXT''' variable is defined in module level and it is not provided to imported modules from your script.

== Component Context ==

In StarBasic, you can get component context as follows:
<source lang="Python">
ctx = GetDefaultContext()
</source>
But you do not need to access to it until you need to get singletons.

In Python, you can get access to the component context through the script context.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
</source>

You need this value to instantiate services.

== Service Manager ==

In StarBasic, you can get service manager as follows:
<source lang="Python">
smgr = GetProcessServiceManager()
</source>
But not so many people having to access to it.

In Python, this instance is most important value to instantiate services to work with the office APIs.
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
</source>

You need both the component context and the service manager to instantiate services.

== Service Instance ==

In StarBasic, you can instantiate services by built-in function as follows:
<source lang="Python">
sfa = CreateUnoService("com.sun.star.ucb.SimpleFileAccess")
</source>
or with initialize arguments:
<source lang="Python">
arg = com.sun.star.ui.dialogs.TemplateDescription.FILESAVE_SIMPLE
file_picker = CreateUnoServiceWithArguments("com.sun.star.ui.dialogs.FilePicker", Array(arg))
</source>

In Python, you have to work with com.sun.star.lang.XMultiComponentFactory interface as follows:
<source lang="Python">
ctx = XSCRIPTCONTEXT.getComponentContext()
smgr = ctx.getServiceManager()
sfa = smgr.createInstanceWithContext("com.sun.star.ucb.SimpleFileAccess", ctx)
</source>
If you need to initialize the instance, use createInstanceWithArgumentsAndContext method:
<source lang="Python">
from com.sun.star.ui.dialogs.TemplateDescription import FILESAVE_SIMPLE
file_picker = smgr.createInstanceWithArgumentsAndContext("com.sun.star.ui.dialogs.FilePicker", (FILESAVE_SIMPLE,) ctx)
</source>
or initialize after the instantiation:
<source lang="Python">
file_picker = smgr.createInstanceWithContext("com.sun.star.ui.dialogs.FilePicker", ctx)
file_picker.initialize((FILESAVE_SIMPLE,))
</source>

== Service with Constructor ==

In StarBasic, you can call service construct from its module:
<source lang="Python">
shell_execute = com.sun.star.system.SystemShellExecute.create()
</source>
In Python, you have to instantiate it with XMultiComponentFactory::createInstanceWithArgumentsAndContext method with initial arguments or instantiate after the instantiation.

The constructor calling does type checking before to pass arguments to createInstanceWithArgumentsAndContext method.

== Current Document ==

In StarBasic, ThisComponent runtime function provides access to the current document:
<source lang="Python">
doc = ThisComponent
</source>
Its return value is bound to the macro location. If the macro stored in a document, the result of ThisComponent is the document that the storage of the macro belongs to. And if your macro is stored in application wide, the returned value is the document model of currently active frame, this is the same result taken from StarDesktop.'''getCurrentComponent()'''.

'''In Python''', you can access to the current document through the script context:
<source lang="Python">
doc = XSCRIPTCONTEXT.getDocument()
</source>
If your macro is '''embedded in the document''', the document model is match with the document that the macro stored in. If your macro is stored in user or shared location, the document object is from active frame.

== Desktop ==

In StarBasic, StarDesktop runtime function is provided:
<source lang="oobas">
desktop = StarDesktop()
</source>

'''In Python''', you can get access to the desktop through the script context:
<source lang="Python">
desktop = XSCRIPTCONTEXT.getDesktop()
</source>

== Struct Instance ==

In Basic, instance of struct can be instantiated in two ways:
<source lang="oobas">
Dim a As New com.sun.star.awt.Point
a = CreateUnoStruct("com.sun.star.awt.Point")
</source>
With Dim statement and New keyword, you can instantiate a struct or array of structs. Or CreateUnoStruct method provides the way to instantiate a struct at runtime. You can not initialize the instance at the creation, you have to set its value of members.

'''In Python''', you can use the following ways to instantiate a struct. Import struct class and call it.
<source lang="Python">
from com.sun.star.awt import Point

a = Point() # instantiate with default values, X=0, Y=0
b = Point(100, 200) # initialize with initial values, X=100, Y=200
</source>
Calling the class to create new instance of the struct, you can empty its arguments or you have to pass values for all fields. In other words, you can not pass insufficient number of arguments to initialize. And its order should be match with definition of the struct in its IDL. For example, instance of struct b having X=100 and Y=200 in the above piece of code.

You can initialize without to import the class of your target struct with uno.createUnoStruct function as follows:
<source lang="Python">
import uno

a = uno.createUnoStruct("com.sun.star.awt.Point")
b = uno.createUnoStruct("com.sun.star.awt.Point", 100, 200)
</source>
This makes the same result with the above example. The first parameter of the createUnoStruct method is the name of the struct to initialize. The following arguments are initial values for new instance.

== Enum ==

In Basic, you can access to the module of the enum as follows:
<source lang="Python">
ITALIC = com.sun.star.awt.FontSlant.ITALIC
</source>

'''In Python''', the following ways can be used:
<source lang="Python">
import uno

from com.sun.star.awt.FontSlant import ITALIC
ITALIC = uno.getConstantByName("com.sun.star.awt.FontSlant.ITALIC")
ITALIC = uno.Enum("com.sun.star.awt.FontSlant", "ITALIC")
</source>
All of the way results the instance of uno.Enum class.

== Constants ==

In StarBasic, you can get access to constants through its module:
<source lang="Python">
BOLD = com.sun.star.awt.FontWeight.BOLD
</source>

In Python, the following ways are provided:
<source lang="Python">
import uno

from com.sun.star.awt.FontWeight import BOLD
BOLD = uno.getConstantsByName("com.sun.star.awt.FontWeight.BOLD")
</source>

== Sequence ==

The sequence is sequential value of the same type.

In StarBasic, array is used.

In Python, tuple is chosen to represent UNO's sequence. Note, list is not allowed to pass as sequence value.

== Boolean ==

In Python, True or False.

== String ==

Python's string can contain over 64K bytes.

If you have to write non Ascii 7 bit characters in your script, write magic comment at the head of your file. This is standard Python instructions.

<source lang="Python">
# -*- coding: utf_8 -*-
</source>

Please read Python's documentation for more detail.

You have to use unicode string to write some unicode characters in Python 2.X. And strings coming from UNO is decoded in unicode in Python 2.X.

== Char ==

There is no dedicated value for char type in StarBasic.

In Python, uno.Char class is defined for char type.
<source lang="Python">
import uno
c = uno.Char("a")
</source>

== Type ==

"Type" type is meta type of UNO that represents type of UNO.
Since 3.4, if you pass string value to method as an argument that should be type, the bridge of Basic read it as type.

<source lang="Python">
oMap = com.sun.star.container.EnumerableMap.create("string", "string")
</source>

In Python, the following ways can be used to create new valu of type.
<source lang="Python">
import uno
t = uno.getTypeByName("string")
t = uno.Type("string", uno.Enum("com.sun.star.uno.TypeClass", "STRING"))
</source>

== Byte Sequence ==

The byte sequence is sequence of byte type.

In Basic, array of byte is used to represent it.

'''In Python''', it is represented by str wrapped by uno.ByteSequence class. If you takes some byte sequences from UNO, they are the instance of uno.ByteSequence. If you need to get real value of them, refer its ''value'' instance variable.

== Exception ==

In StarBasic, you get thrown exception as some error. And On Error statement is used to catch it.

<source lang="oobas">
Sub ErrorExample

On Error GoTo Handler

' ... error

Exit Sub

Handler:

End Sub
</source>
And you can not throw any exceptions from StarBasic.

In Python, the exception thrown in UNO world can be treated as normal Python's exception. Here is an example:
<source lang="Python">
from com.sun.star.container import IndexOutOfBoundsException

try:
obj.getByIndex(100) # raises IndexOutOfBoundsException
except IndexOutOfBoundsException as e:
print(e)
</source>
If getByIndex method raises IndexOutOfBoundsException, it can be caught in except statement because all exceptions inherit Python's Exception class.

And also you can throw UNO's exception from your Python code as follows:
<source lang="Python">
from com.sun.star.uno import RuntimeException
raise RuntimeException("Some message", None)
</source>

== Empty Value ==

In Basic, there are some situations to meet variables that they do not contain any value (this is not correct). Null, empty, missing, nothing and so on.

In Python, None is used. If a method defined as void return value in its IDL, it results None if you call it. If you need to pass invalid interface as an argument for the method that takes some interface, pass None for it. The result of this behavior is fully dependent to the implementation of the method.

== Listener and Interface ==

In StarBasic, you can create new listener using CreateUnoListener runtime function with some subroutines or functions.
<source lang="oobas">
Sub Add

d = CreateUnoDialog(DialogLibraries.Standard.Dialog1)
listener = CreateUnoListener("ActionListener", "com.sun.star.awt.XActionListener")
d.getControl("CommandButton1").addActionListener(listener)
d.execute()
d.dispose()

End Sub

Sub ActionListener_actionPerformed(ev)

End Sub

Sub ActionListener_disposing(ev)

End Sub
</source>

'''In Python''', you have define your own class with desired interfaces. With helper class, you can define easily as follows:
<source lang="Python">
import unohelper

from com.sun.star.awt import XActionListener

class ActionListener(unohelper.Base, XActionListener):
def __init__(self):
pass

def disposing(self, ev):
pass

def actionPerformed(self, ev):

pass
</source>

unohelper.Base class provides required interface for UNO components.

== Containers ==

In StarBasic, container object provides the way to access to its contents in sequentially.

'''In Python''', there is no shortcut provided.

If you need to access to elements of indexed container, use range function to generate sequential indexes.
<source lang="Python">
for i in range(container.getCount()):
obj = container.getByIndex(i)
</source>

== URL and System Path ==

If you work with a file stored in your local file system, you have to get its corresponding URL.

In StarBasic, ConvertToURL runtime function is prepared for this task. And there is ConvertFromURL runtime function for reverse conversion.

'''In Python''', the following functions are defined in uno module for such task.
<source lang="Python">
import uno

path = "/home/foo/Documents/file.odt"
url = uno.sytemPathToFileUrl(path)
path = uno.fileUrlToSystemPath(url)
</source>

== Arguments and Return Value ==

In StarBasic, mode of the first argument of parseStrict method is "inout" in the following code:
<source lang="oobas">
aURL = CreateUnoStruct("com.sun.star.util.URL")
aURL.Complete = ".uno:Paste"
CreateUnoService("com.sun.star.util.URLTransformer").parseStrict(aURL)
</source>
The content of aURL variable is updated after calling the method.

'''In Python''', out mode parameter is returned as part of return value.
<source lang="Python">
from com.sun.star.util import URL

aURL = URL()
aURL.Complete = ".uno:Paste"
dummy, aURL = smgr.createInstanceWithContext("com.sun.star.util.URLTransformer", ctx).parseStrict(aURL)
# Definition of com.sun.star.util.XURLTransformer::parseStrict method:
# void parseStrict([inout] com.sun.star.util.URL aURL);
</source>
If a method has out mode in its parameters, its return is always tuple that contains original return value and values for out parameters.

Here is a potential example:
<source lang="Python">
# boolean getSomeValue([in] string aName, [out] short aNum, [inout] long aNum2);
result, num, num2 = obj.getSomeValue("foo", 100, 200)
</source>
In the above example, ''result'' variable takes original return value, ''num'' takes output value for second parameter and ''num2'' takes output value for third parameter. The method takes 100 as the second parameter but it is not used as input of value. No entry in returned tuple for in mode parameter.

== Functions to be Executed ==

In Basic, you can not choose routines to be executed by users.

'''In Python''', define '''g_exportedScripts''' variable that contains tuple of callable in your macro file.
<source lang="Python">
def func_a(): pass
def func_b(): pass
def func_hidden(): pass # not shown in the UI

g_exportedScripts = func_a, func_b
</source>
In the above code, func_hidden is not shown in execution dialog of macros.

== Importing Modules ==

== Dialog ==

== Message Box ==

== Input Box ==

[[Category:Python]]

Python/Transfer from Basic to Python

2013-10-03T07:07:43Z

Hanya: Add description about unicode in String

Python/Transfer from Basic to Python

2013-10-03T06:59:56Z

Hanya: Fix source tag in Constants

Python/Transfer from Basic to Python

2013-10-03T06:43:34Z

Hanya: Add spaces between return value and method in Script Context

Python/Transfer from Basic to Python

2013-10-03T06:10:27Z

Hanya: /* Short Example */

Python/Transfer from Basic to Python

2013-10-03T06:10:02Z

Hanya: Add short example

Python/Transfer from Basic to Python

2013-10-03T06:01:37Z

Hanya: /* Macro Location */

Python/Transfer from Basic to Python

2013-10-03T05:56:21Z

Hanya: Add descriptions about macro location

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:45:58Z

Hanya: Add description about css.awt.ImageScaleMode

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in the members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.ImageScaleMode
** Member names were corrected to be uppercase.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

* com.sun.star.frame.XStatusbarController
** click and doubleClick methods takes an argument.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:44:14Z

Hanya: /* Other com.sun.star.awt Module */

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in the members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

* com.sun.star.frame.XStatusbarController
** click and doubleClick methods takes an argument.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:43:03Z

Hanya: Add description about css.frame.XStatusbarController

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in the members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

* com.sun.star.frame.XStatusbarController
** click and doubleClick methods takes an argument.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:20:57Z

Hanya: /* Menu */

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in the members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:18:44Z

Hanya: Remove regcompare description, it does not list all differences

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in there members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:15:10Z

Hanya: Add description about MessageBoxResults.IGNORE member

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

The following differences were detected by regcompare program bound to SDK with f and c options between rdb files of 3.4 and 4.0.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box. Renamed from MessageBoxCommand. And IGNORE member was added.

* com.sun.star.awt.MessageBoxCommand
** Renamed to MessageBoxResults.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in there members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T07:01:01Z

Hanya: Fix MailClientFlags was renamed from SimpleMailClientFlags

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

The following differences were detected by regcompare program bound to SDK with f and c options between rdb files of 3.4 and 4.0.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box.

* com.sun.star.awt.MessageBoxCommand
** Removed, deprecated module.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in there members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMail
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
* com.sun.star.system.SimpleMailClientFlags
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.
* com.sun.star.system.MailClientFlags
** Renamed from SimpleMailClientFlags.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T06:54:32Z

Hanya: Add about stlport removal

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

The following differences were detected by regcompare program bound to SDK with f and c options between rdb files of 3.4 and 4.0.

== Impact ==
The impact of these changes are influence differently over your code.
* C++: recompilation required because of stlport removal.
* Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box.

* com.sun.star.awt.MessageBoxCommand
** Removed, deprecated module.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in there members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.MailClientFlags
* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMai
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

User:Hanya/API Changes on 4.0 since 3.4

2013-07-30T06:52:22Z

Hanya: Add css.ui.XStatusbarItem

There are some API changes applied to Apache OpenOffice 4.0 since version 3.4.

The following differences were detected by regcompare program bound to SDK with f and c options between rdb files of 3.4 and 4.0.

== Impact ==
The impact of these changes are influence differently over your code.
* C++ or Java: should be migrated and recompiled.
* Basic or Python: should be migrated.

== Message box ==
Message box APIs were cleaned up. See issue 121544.

* com.sun.star.awt.XMessageBoxFactory
** createMessageBox method
*** second argument that specifiy size of the box was removed, it was not used.
*** third argument that specify the type of the icon shown in the box is changed from string to com.sun.star.awt.MessageBoxType, see below.

* com.sun.star.awt.XMessageBox
** setCaptionText, getCaptionText, setMessageText, getMessageText methods were changed to corresponding attributes.
** return value of execute method was defined in com.sun.star.awt.MessageBoxResults, see below.
** No longer deprecated.

* com.sun.star.awt.MessageBoxType
** Member of this enumerated value can be used to specify type of the message box.

* com.sun.star.awt.MessageBoxResults
** Member of this constants group can be used to check the result of the execution of the message box.

* com.sun.star.awt.MessageBoxCommand
** Removed, deprecated module.

== Menu ==
Menu APIs were integrated. See issue 121542.

* com.sun.star.awt.XMenuBarExtended
** Integrated into other interfaces, this interface is used to integrate some menu interfaces without any methods.
* com.sun.star.awt.XMenuExtended
** getCommand, getCommand, setHelpCommand and getHelpCommmand methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XMenuExtended2
** isPopupMenu, clear, getItemType, hideDisableEntries methods are moved into com.sun.star.awt.XMenu interface.
* com.sun.star.awt.XPopupMenuExtended
** isInExecute, endExecute, setAcceleratorKeyEvent, getAcceleratorKeyEvent, setItemImage and getItemImage methods were moved into com.sun.star.awt.XPopupMenu interface.
** setHelpText, getHelpText, setTipHelpText and getTipHelpText methods were moved into com.sun.star.awt.XMenu interface.
** setItemImageAngle, getItemImageAngle, setItemImageMirrorMode and isItemImageInMirrorMode methods were removed.

* com.sun.star.awt.XPopupMenu
** Some methods were moved from each interfaces described above to this interface.
* com.sun.star.awt.XMenu
** Some methods were moved from each interfaces to this interface.

* com.sun.star.awt.XMenuListener
** The following method names were changed.
*** highlight -> itemHighlighted
*** select -> itemSelected
*** activate -> itemActivated
*** deactivate -> itemDeactivated

* com.sun.star.awt.MenuItemStyle
** Unpublished, no changes in there members.

* com.sun.star.awt.PopupMenuDirection
** deprecated members were removed.

* com.sun.star.awt.MenuLogo
** Removed. See issue 121542.

== Controls ==
com.sun.star.awt.UnoControlThrobberModel was replaced with com.sun.star.awt.SpinningProgressControlModel. See issue 121513.

* com.sun.star.awt.UnoControlThrobber
* com.sun.star.awt.UnoControlThrobberModel
* com.sun.star.awt.XThrobber
** Please use com.sun.star.awt.AnimatedImagesControl control with com.sun.star.awt.SpinningProgressControlModel.

com.sun.star.awt.UnoControlSimpleAnimation control was replaced with com.sun.star.awt.AnimatedImagesControl.
* com.sun.star.awt.UnoControlSimpleAnimation
* com.sun.star.awt.UnoControlSimpleAnimationModel
* com.sun.star.awt.XSimpleAnimation
** Please use com.sun.star.awt.AnimatedImagesControl. issue 121514.

== Other com.sun.star.awt Module ==
Graphics APIs were cleaned up. See issue 121442.

* com.sun.star.awt.XGraphics
** getDevice, getFontMetric, setFont, setTextColor, setTextFillColor, setLineColor, setFillColor, setRasterOp methods were changed to corresponding attributes.
** clear and drawImage methods were added.

* com.sun.star.awt.ImageDrawMode
** Added. Constants are used to specify the mode in com.sun.star.awt.XGraphics::drawImage method.

* com.sun.star.awt.PrinterServer
** This service was converted into new style service with constructor.

== System ==

Clean-up system mail API. See issue 121579.

* com.sun.star.system.MailClientFlags
* com.sun.star.system.SimpleCommandMail
* com.sun.star.system.SimpleMailClientFlags
* com.sun.star.system.SimpleSystemMai
* com.sun.star.system.XMailClient
* com.sun.star.system.XMailMessage
* com.sun.star.system.XSimpleMailClient
* com.sun.star.system.XSimpleMailClientSupplier
* com.sun.star.system.XSimpleMailMessage
* com.sun.star.system.XSystemMailProvider
** Removed. See below.
* com.sun.star.system.SystemMailProvider
** System dependent mail services were integrated into com.sun.star.system.SystemMailProvider.
Remove deprecated system proxy API. See issue 121548.

* com.sun.star.system.ProxySettings
* com.sun.star.system.XProxySettings
* com.sun.star.system.SystemProxySettings
* com.sun.star.system.SOffice52ProxySettings
** No longer used, removed.

* com.sun.star.system.SystemShellExecute
** This service was converted to new style service with a constructor.

== com.sun.star.text Module ==

* com.sun.star.text.AutoTextGroup
** FilePath and Title properties were added for documenting. See issue 87780.

* com.sun.star.text.ViewSettings
** ShowContentTips and ShowScrollBarTips properties were added. See issue 25945.

== com.sun.star.frame Module ==

* com.sun.star.frame.PopupMenuControllerFactory
* com.sun.star.frame.StatusbarControllerFactory
** These services were converted to new style service with constructors.

* com.sun.star.frame.ToolbarControllerFactory
* com.sun.star.frame.XUIControllerFactory
** Added.

== Sidebar ==
See issue 121420.
* com.sun.star.ui.ContextChangeEventMultiplexer
* com.sun.star.ui.ContextChangeEventObject
* com.sun.star.ui.XContextChangeEventMultiplexer
* com.sun.star.ui.XContextChangeEventListener
* com.sun.star.ui.XSidebar
* com.sun.star.ui.XSidebarPanel
* com.sun.star.ui.LayoutSize
* com.sun.star.util.EventMultiplexer
** Added. They are used in the sidebar.

== UCB ==

* com.sun.star.ucb.Content
** addProperty and removeProperty commands were added. See issue 121935.
* com.sun.star.ucb.PropertyCommandArgument
** Added. Argument for the new commands.

* com.sun.star.ucb.XWebDAVCommandEnvironment
** Request method is specified by WebDAVHTTPMethod, see below.
* com.sun.star.ucb.WebDAVHTTPMethod
** Added. Request methods were defined in WebDAVHTTPMethod.

== SmartTag ==

Make smarttag function more powrful.

See issue 121391, 121730, 121731, 121732, 121733, 121734 and http://mail-archives.apache.org/mod_mbox/openoffice-dev/201302.mbox/browser .

* com.sun.star.smarttags.XRangeBasedSmartTagRecognizer
** Added.
* com.sun.star.smarttags.XSmartTagAction
** getActionCount method takes additional parameter.
* com.sun.star.text.XMarkingAccess
* com.sun.star.container.XNamedEx
** Added.
* com.sun.star.text.XTextMarkup
** commitTextMarkup method was renamed to commitStringMarkup
** commitTextRangeMarkup method was added.

== Calc ==
See issue 120478.

* com.sun.star.sheet.XNamedRange2
* com.sun.star.sheet.XNamedRanges2
* com.sun.star.sheet.RangeScopeName
** Added.

== Other ==

* com.sun.star.configuration.BootstrapContext
** Deprecated. See issue 118815.

* com.sun.star.ui.XStatusbarItem
** Added. See issue 121442.

Talk:Extensions/Extensions and Apache OpenOffice 4.0

2013-07-27T13:30:10Z

Hanya: Possibility to make the package compatible about add-ons toolbar

Here is an example add-on toolbar in old structure:
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
oor:name="Addons" oor:package="org.openoffice.Office">
<node oor:name="AddonUI">
<node oor:name="OfficeToolBar">
<node oor:name="foo.bar.hoge.addons.ToolbarTest.old" oor:op="replace">
<node oor:name="button_1" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value xml:lang="en-US">Show All</value>
</prop>
<prop oor:name="URL" oor:type="xs:string">
<value>vnd.sun.star.script:myts?language=Basic&location=application</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.sheet.SpreadsheetDocument</value>
</prop>
</node>
</node>
</node>
</node>
</oor:component-data>
</source>

with its name:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
oor:name="CalcWindowState" oor:package="org.openoffice.Office.UI">
<node oor:name="UIElements">
<node oor:name="States">
<node oor:name="private:resource/toolbar/addon_foo.bar.hoge.addons.ToolbarTest.old" oor:op="replace">
<prop oor:name="UIName" oor:type="xs:string">
<value xml:lang="en">Toolbar Title</value>
</prop>
</node>
</node>
</node>
</oor:component-data>
</source>

It should be converted into the following structure:
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
oor:name="Addons" oor:package="org.openoffice.Office">
<node oor:name="AddonUI">
<node oor:name="OfficeToolBar">
<node oor:name="foo.bar.hoge.addons.ToolbarTest.new" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value xml:lang="en-US">Toolbar Title</value>
</prop>
<node oor:name="ToolBarItems">
<node oor:name="button_1" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value xml:lang="en-US">Show All</value>
</prop>
<prop oor:name="URL" oor:type="xs:string">
<value>vnd.sun.star.script:myts?language=Basic&location=application</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.sheet.SpreadsheetDocument</value>
</prop>
</node>
</node>
</node>
</node>
</node>
</oor:component-data>
</source>

Add Title property in your child node of OfficeToolBar node to specify its title. And create ToolBarItems node in your toolbar node, and move your toolbar entries into it.

In the above example, new one has different toolbar name from the older one. When I put both older one and new one into the same package as the following list of contents, the toolbar of the package is shown on both Apache OpenOffice 3.4 and 4.0 (I testes only OpenOffice.org 3.2 and 3.3, Apache OpenOffice 3.4 and 4.0 on Linux environment. I thought configuration data has been checked to match with installed schema during the installation of the package in the past but I forgot version that has been changed.).

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<manifest:manifest>
<manifest:file-entry manifest:full-path="Addons_old.xcu"
manifest:media-type="application/vnd.sun.star.configuration-data"/>
<manifest:file-entry manifest:full-path="CalcWindowState.xcu"
manifest:media-type="application/vnd.sun.star.configuration-data"/>
<manifest:file-entry manifest:full-path="Addons_new.xcu"
manifest:media-type="application/vnd.sun.star.configuration-data"/>
</manifest:manifest>
</source>

Extensions/Extensions and Apache OpenOffice 4.0

2013-07-27T12:03:20Z

Hanya: Fix link URL to Magenta Lorem Ipsum generator

== Introduction ==

Apache OpenOffice 4.0 introduces new handling mechanisms and new APIs for Extensions.

Extensions compatible with OpenOffice 3.x may or may not work in version 4.0.

This pages collects useful information for end users and developers.

== Information For End Users ==

=== General upgrade information ===

Extensions that you installed in OpenOffice 3.x won't be automatically available in OpenOffice 4.0 when you upgrade from OpenOffice 3.x to OpenOffice 4.0.

It is recommended that, '''before installing OpenOffice 4.0''', you take note of the installed Extensions with: ''Tools'' → ''Manage Extensions''.

You can then check the site you downloaded the Extensions from (usually http://extensions.openoffice.org) and search for your Extensions, to see if there is a version compatible with OpenOffice 4.0.

In doubt, you can download the latest version and install it in OpenOffice 4.0 (save the file from the Extensions site, then open it with ''File'' → ''Open'' in OpenOffice) and check if it works correctly.

For commercial extensions, please contact the publisher for support. In case an extension is not publicly available, but only used privately or in your company/institution, please ask either the author of your extension or a person responsible in your company/institution for help.

''Please note: If a certain extension is crucial for your personal or professional workflow, you should not install OpenOffice 4.0 before having made sure that this extension will work on version 4.0 or that an update of the extension is available.''

=== Extensions known to be working ===

Popular Extensions that are '''reported to work correctly''' with OpenOffice 4.0 are:
* All dictionaries
* [http://extensions.openoffice.org/en/node/17351 PDF Import - NEW VERSION] (use this one by Ariel, not the old "Oracle" one)
* [http://extensions.openoffice.org/en/node/5644 MySQL Driver for Apache OpenOffice - NEW VERSION] (use this one by Ariel, not the old "Sun MySQL Connector")

=== Extensions known not to be working ===

The following Extensions do not have a release compatible with OpenOffice 4.0:
* [http://extensions.openoffice.org/en/project/pdfimport Oracle PDF Import] - needs to be updated for OpenOffice 4.0 on Windows, Mac, 32-bit Linux and the '''4.0-compatible update''' is available at http://extensions.openoffice.org/en/node/17351
* [http://extensions.openoffice.org/en/project/mysql_connector MySQL Connector] and [http://code.google.com/a/apache-extras.org/p/aoo-my-sdbc/ Ariel's old version of it] - both need to be updated for OpenOffice 4.0 on Windows, Mac, 32-bit Linux and the '''4.0-compatible update''' is available at http://extensions.openoffice.org/en/node/5644
* [http://extensions.openoffice.org/en/project/magenta-lorem-ipsum-generator Magenta Lorem Ipsum generator] - reported to be incompatible.

Please check the http://extensions.openoffice.org site (or your provider) for the latest information about upgrades.

== Information for Developers ==

OpenOffice 4.0 brings some significant changes to the API used in Extensions.

=== Good practices ===

==== Specify both a minimal and maximal version of OpenOffice for compatibility ====

This is to be done when you create a new Extension release, within the <tt>description.xml</tt> file.

Typical (minimal version only) configuration:

<dependencies>
<OpenOffice.org-minimal-version value="3.0" d:name="OpenOffice.org 3.0" />
</dependencies>

Recommended (both minimal and maximal version) configuration:

<dependencies>
<OpenOffice.org-minimal-version value="3.0" d:name="OpenOffice.org 3.0" />
<OpenOffice.org-maximal-version value="4.0" d:name="OpenOffice.org 4.0" />
</dependencies>

==== Test your Extension with a recent OpenOffice 4.0 snapshot ====

Download a recent OpenOffice 4.0 snapshot from [https://cwiki.apache.org/confluence/display/OOOUSERS/Development+Snapshot+Builds#DevelopmentSnapshotBuilds-AOOSnapshotfullsets here] (remember: snapshots are not official releases and they are meant for testing only) and try installing your Extension.

Check that everything works, especially toolbar integration.

If the Extension works, you may want to create a new micro release with updated minimal and maximal version compatibility and upload it to http://extensions.openoffice.org

=== Technical details ===

* All dictionaries will work with no modifications in version 4.0.
* If your Extension does not contain an <tt>addons.xcu</tt> file, it will work with no modifications too.
* If your Extension contains an <tt>addons.xcu</tt> file, you will usually have to make some small changes for it to run in OpenOffice 4.0, see below.

[TODO: Example: how to adapt <tt>addons.xcu</tt> from version 3.x to version 4.0]

User:Hanya/Translation Review

2013-07-18T03:26:42Z

Hanya: Add about creation of search plug-in in Pootle server

Some tools to help reviewing existing translations in UI and help contents.

== Create Pootle Search Plug-in ==
Recent web browser supports embedded search plug-in to search. It can be make one for your locale using Ready2Search[1] easily.

Here is an example to make one for ja locale:

# Open Ready2Search page.
# the search name: Pootle UI-ja target
# the front of search term: https://translate.apache.org/ja/aoo40/translate.html#sfields=target&search=
# description of the search: Pootle Search in UI-ja target
# input encoding: UTF-8
# output encoding: not specified
# Push Make search plug-in button
# Push Download the setting of OpenSearch to store the result
# Deploy it according to your web browser instructions

The front of search term should be:
https://translate.apache.org/{LOCALE}/{CATEGORY}/translate.html#sfields=target&search=

* LOCALE: ISO language and country code for your target locale.
* CATEGORY: aoo40 or aoo40help

sfields specifies the context to search in. It should be one of source: source text,target: translated text, notes: comments and locations: position. If you want to search in the two or more context at a time, separate multiple items with ",", c.g. sfields=source,target.

If you want to share it with your coworker, sent the setting URL shown after the creation.

[1] http://ready.to/search/en/

User:Hanya

2013-07-18T03:20:52Z

Hanya: Add link to new page