OpenOffice.org Macro Selector Specification

OpenOffice.org 2.0

Document - ID	Specification Owner	Last Change	Status
	Tomas O'Connor	23. April 2004	Final
Conforms to	
Applies to	All OOo modules
Task ID(s)	i21148
Category	Feature

Abstract

The Macro Selector dialog is a utility dialog used from various parts of the OpenOffice.org UI to select

scripts supported by the Scripting Framework, and commands supported by the Slot API.

i-Team Members

	Name	E-mail Address
User Experience	Bettina Haberer (BH)	Bettina.haberer@sun.com
Development	Tomas O'Connor (TOC)	tomas.oconnor@sun.com
Quality Assurance	Joerg Skottke (JSK)	joerg.skottke@sun.com
Documentation	Uwe Fischer (UFI)	Uwe.Fischer@sun.com

Approved for Implementation

	Approved by	Date
User Experience	Bettina Haberer	April 16, 2004
Development	Tomas O'Connor	April 16, 2004
Quality Assurance	Joerg Skottke	April 16, 2004
Documentation	Uwe Fischer	April 16, 2004
String Review	Elizabeth Matthis	23. April 2004

Document Change History

Rev. Level	Change	Initials	Date
0,8	Copy of Macro Selector section from iTeam approved Toolbar specification	TOC	03/19/03
0,9	Review, added remarks	BH	04/13/04
1,0	Final draft	TOC	04/16/04
	Started string review and added comments to string lists	EM	19.04.04
	Answered questions and included one more string	TOC	20.04.04
	Added secion 6.5 with two mockups and one more string	BH	23.04.04
	Added changes based on Package Manager spec. Removed Tools/Configure mockups as they are being dealt with elsewhere.	TOC	10.06.04

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	2

4.1	Requirements	2

5	Competitive Analysis	2

6	Detailed Specification	2

6.1	Selecting a Macro	2

6.2	Running a Macro	4

6.3	Selecting a Command	5

6.4	Other User Scenarios	6

7	Future Tasks	7

8	Notes	7

9	References	7

Glossary

Term	Description
Script Selector	This dialog was previously known as the Script Selector dialog, but for consistency with the existing UI and terminology it has been renamed to Macro Selector. For the purposes of this document the terms Script Selector and Macro Selector are synonymous, but only Macro Selector should be used in the UI and documentation.
Script	An executeble piece of code. This term should not be used in the UI or documentation. For the purposes of this document a Script and a Macro are the same thing.
Macro	An executable piece of code

Motivation

Enhance the programmability of OpenOffice.org by making it possible to select Scripting Framework scripts when creating assignments.

User Scenarios

User A opens the Insert/Fields/Other dialog and selects the Functions tab. If the user selects the Execute Macro type and click on the Macro button, they should be able to select scripts from all of the languages supported by the Scripting Framework.

User B opens a spreadsheet, highlights a cell and opens the Data/Validity dialog. If the user selects the Error Alert tab, select the Action Macro and click on the Browse button, they should be able to select scripts from all of the Scripting Framework languages.

User C creates an Impress presentation and inserts a rectangle on a slide. The user right clicks on the slide and select the Interaction menu item. If they select Run Macro as the Action at mouse click and click the Browse button, they should be presented with a dialog that lists scripts in all the Scripting Framework languages.

User D opens the Tools/Configure dialog. They should be able to assign scripts from any of the Scripting Framework languages to menu items, keyboard shortcuts, toolbar items and application and document events.

User G wants to run a macro of any of the scripting framework languages via menu and starts Run... from Tools / Macros menu. The Macro Selector opens, where the user selects a macro and clicks on the Run... button. The structure of the Tools/Macro menu is redefined in the Script Organizer specification (see References).

The new Macro Selector dialog will replace the Macro Chooser dialog in user scenarios 1, 2 and 3.

Goals

The goals of implementing the Macro Selector are:

Provide a uniform way of selecting Scripts and Slot API commands for assignment.

Reduce the complexity of the tabs in the Tools/Configure dialog.

Add support for creating assignments to all scripting languages supported by the Scripting Framework.

Requirements and Dependencies

Requirements

The Macro Selector dialog must fulfill the following requirements:

It must be possible to drag items from the Commands listbox of the dialog, and the dialog should be modeless.

It must be possible to programmatically configure whether Slot API commands are displayed in the Category list box.

The Macro Selector needs to consider all the macro assignments covered by user scenarios 1 – 5.

The dialog has the following dependencies:

The Scripting Framework BrowseNode API must be available.

A configuration file with the Slot API commands organised according to the menus in which they would appear must be provided by the Framework team, otherwise Slot API commands will be listed in the same way that they were listed before.

Competitive Analysis

The Macro Selector makes possible to assign macros of several scripting languages to application and document events. The support of several scripting languages is only given in OpenOffice.org until now. So a conparison with another Office-product is not possible yet.

Detailed Specification

Selecting a Macro

This is the default view of the new Macro Selector dialog. To keep consistency with existing concepts from Basic, the term macros will be used instead of scripts. Figures 1 – 3 show the different modes of this dialog.

Figure 1 Macro Selector dialog of OpenOffice.org 2.0 CommonLang OK

To keep consistency with the new Organizer and Package Manager UI, also the Macro Selector should only show the top level nodes My Macros and %PRODUCTNAME Macros . The node user is defaulted when the dialog is opened. If the dialog has been cached, the node that was selected the last the dialog was closed is highlighted when it is reopened, that is the behaviour as in the Script Organizer and Package Manager UI.

Where possible, nodes will be sorted alphabetically. In other words when the user, share, or document node is expanded the nodes that are listed under it should be sorted alphabetically according to their names.

Item	English	German	Comments
Dialog Title	Macro Selector	Makro-Selektor	I chose to keep “Selektor” in German because a noun form of “auswählen” would sound silly, though it would fit our terminology better.
Label	Select the library that contains the macro you want. Then select the macro under '%macname'.	Wählen Sie zuerst die Bibliothek, die das gewünschte Makro enthält. Dann wählen Sie das Makro unter '%macname'.	This placeholder will be replaced at runtime by the translation made for the string “Macro name” (EM->TOC: I asked our Japanese translator and she said there is no l10n problem caused by placeholders.)
Label	Library	Bibliothek	
Label	~Macro name	Name des Makros	Replaces the placeholder “%macname”
Listbox Label	My Macros	Meine Makros	
Listbox Label	%PRODUCTNAME Macros	%PRODUCTNAME Makros	
Separator	Description	Beschreibung	The description changes depending on the selection and is obtained programmatically.
Button (default)	~OK	OK	
Button	Cancel	Abbrechen	
Button	~Help	~Hilfe	

Icons
If possible the following icons should be used within the Macro Selector. This depends on whether the VCL controls used within the Macro Selector support icons.

Harddisk for My Macros and %PRODUCTNAME Macros	
Modulfolder / basic script library (these icons are an optimized version of the older one)	
Documenticons instead of	

Running a Macro

In the case where the selector is used to select a macro to run, it must be possible to change the label of the OK button to Run.

CommonLang

When the user selects Tools / Macros / Run..., they get the dialog as shown in figure 2. The OK button is labelled Run in this case.

Item	English	German	Comments
Button (default)	~Run	Ausführen	

Selecting a Command

The following items in the dialog will be changed if the Slot API commands are listed in the dialog

The title of the dialog.

The message about how to use the dialog.

The label of the right hand listbox.

The label of the left hand tree view.

The label of the OK button.

Figure 3The Macro Selector dialog with Slot API commands displayed

The dialog can also be used to select commands to assign to Menus, Keyboard shortcuts etc.

Item	English	German	Comments
Label	Select the category and then the command you want to add.	Wählen Sie zuerst die Kategorie und dann den Befehl, den Sie hinzufügen möchten.	
All other strings found in the Add Commands dialog are defined in: http://specs.openoffice.org/ui_in_general/toolbars/openoffice_org_toolbar_spec.sxw

Other User Scenarios

Insert/Fields/Other dialog in Writer

The following screenshot shows how the Insert/Fields/Other dialog will look when Execute Macro is selected in the Functions tab:

Item	English	German	Comments
Label	F~ormat	Format	This string is already available in the resource files

The changes made to the dialog are as follows:

The label of the centre ListBox is changed from Select to Format to be in keeping with the label used when other Types are selected.

The Format list will not be populated after a macro has been selected as this is not possible using the new Scripting Framework macro selector dialog. This has been agreed with Oliver Specht of the Writer team. The workflow for the dialog will be:

Clicking the Macro button will open the Macro Selector dialog.

The user selects a macro and clicks OK in the Macro Selector.

The name of the selected macro will be inserted in Macro Name text field of the Insert/Fields/Other dialog.

No new strings are introduced by these changes.

Future Tasks

Notes

For a list of the places where the Macro Selector dialog is now used instead of the Macro Chooser dialog, see the User Scenarios section of this document.

As the Macro Selector does not allow the user to modify nodes in the dialog, the nodes under the share directory are not displayed any differently than nodes under user or document.

TOC: I have removed references to the Tools/Configure dialog from this specification as this dialog is being redesigned in the new Customize Toolbar, Customize Menu and Customize Events specifications.

References

Script Organizer Specification:

http://specs.openoffice.org/scripting_framework/ScriptOrganizerSpecification.sxw

Customize Toolbar Specification:

http://specs.openoffice.org/ui_in_general/toolbar_concept/openoffice_org_toolbar_spec.sxw

Customize Menu Specification:

http://specs.openoffice.org/appwide/menus/customize_menu_spec.sxw

Customize Events Specification:

http://specs.openoffice.org/scripting_framework/config_events_spec.sxw

http://specs.openoffice.org/scripting_framework/MacroSelectorSpecification.sxw	Page 8

Christian Jansen

2003-09-15T13:45:24

Bettina Haberer

Elizabeth Matthis