Talk:Python as a macro language

I would like to improve some info on this page, but i have never edited a wiki before, so i'm discussing it here first.

Recently it took me 3 whole days to discover some very simple facts about writing a python macro, because they are not clear in the documentation.
Also, some things seem to have changed since the documentation was written.

Here is the information that i want to convey:

To write a simple macro:

• in Python
• stored in the document
• called from a toolbar button (not a dialog)

this is what you need to know, that is different from the existing documentation:

• your function must accept an argument
• it does not need to import uno or unohelper (or anything at all)
• you do not have to modify manifest.xml, it's done automatically

and this is what you need to know, that is hard discover in the existing documentation:
(it's there, but in a different context, so it's hard to know the relevance of it when you first see it)

Within your function, to get to the UNO API,
(like "ThisDocument" and "StarDesktop" in OO Basic)
use XSCRIPTCONTEXT, like this:
this_doc = XSCRIPTCONTEXT.getDocument()
desktop = XSCRIPTCONTEXT.getDesktop()

Code example:

def test_toolbar_button( *tpl_args ):
	"""Test of basic text insertion;
	prints whatever args are passed to this function."""

	this_doc = XSCRIPTCONTEXT.getDocument()
	doc_text = this_doc.Text
	cursor = text.createTextCursor()

	s_text_1 = 'These arguments were passed:\n%r\n\n' % ( tpl_args, )
	doc_text.insertString( cursor, s_text_1, 0 )

	return 0

The following aspects of the task were easy enough to understand from the documentation:

• putting the script file into the document (unzip/zip)
• making a toolbar button and connecting it to the function

To make the documentation easier to follow, i would break it up, providing a separate page for each context; on the first page, start with simple facts, leading the reader to understood which context he needs; introduce complex information only when he has moved into a specialised page.

jim_hill_au 14:00, 8 June 2007 (CEST)