API/UNO AWT/Grid Control

Abstract

OpenOffice.org hasn't a Grid Control via UNO API today. The goal is to develop and implement an UNO Grid Control. This Wiki page should help you to implement a UNO Grid Control within your own UNO application.

Overview

Example

Create new columns:

In milestone 3 there are some new features regarding columns. Now it is possible to set width for column, horizontal alignment for the content and define whether a column should be resizeable(default value is true).

Java

 // #1 column
 Object column1Obj = xMultiComponentFactory.createInstanceWithContext(
                "com.sun.star.awt.grid.GridColumn", m_xContext);
 
 XGridColumn column1 = (XGridColumn) UnoRuntime.queryInterface(
                XGridColumn.class, column1Obj);

 column1.setTitle("Column1");
 column1.setColumnWidth(15);
 column1.setHorizontalAlign(com.sun.star.style.HorizontalAlignment.LEFT);
 //this column shouldn't be resizeable
 column1.setResizeable(false);

 // #2 column
 Object column2Obj = xMultiComponentFactory.createInstanceWithContext(
                "com.sun.star.awt.grid.GridColumn", m_xContext);
 XGridColumn column2 = (XGridColumn) UnoRuntime.queryInterface(
                XGridColumn.class, column2Obj);

 column2.setTitle("Column2");
 column2.setColumnWidth(10);
 column2.setHorizontalAlign(com.sun.star.style.HorizontalAlignment.RIGHT);

Basic

oColumnModel = createUnoService( "com.sun.star.awt.grid.DefaultGridColumnModel")

oColumn1 = createUnoService( "com.sun.star.awt.grid.GridColumn")
oColumn1.Title = "City"

oColumn2 = createUnoService( "com.sun.star.awt.grid.GridColumn")
oColumn2.Title = "Country"

Add the columns to the column model of the grid control:

In milestone 3 a new method - XGridColumn copyColumn(XGridColumn xColumn) - was added. It's a convient way to define more columns, which are copies of existing ones. See example:

Java

 Object columnModel = xMultiComponentFactory.createInstanceWithContext(
                "com.sun.star.awt.grid.DefaultGridColumnModel", m_xContext);
 XGridColumnModel xGridColumnModel = (XGridColumnModel) UnoRuntime.queryInterface(
                XGridColumnModel.class, columnModel);
 //xColumn3 will be the same as colum1:with same title, width, alignment and not resizable
 XGridColumn xColumn3 = xGridColumnModel.copyColumn(column1);
 //set new title
 xColumn3.setTitle("Column3");
 xGridColumnModel.addColumn(column1);
 xGridColumnModel.addColumn(column2);
 xGridColumnModel.addColumn(column3);

Basic

oColumnModel.addColumn( oColumn1 )
oColumnModel.addColumn( oColumn2 )

Use the data model of the grid control to add rows:

The main change in milestone 3 regarding DataModel is the possibility to add not only text but also images. That's why addRow-method has as second parameter no more string array but object array. Futher supported types are int, double, float.

Java

 Object dataModel = xMultiComponentFactory.createInstanceWithContext(
                "com.sun.star.awt.grid.DefaultGridDataModel", m_xContext);
 XGridDataModel xGridDataModel = (XGridDataModel) UnoRuntime.queryInterface(
                XGridDataModel.class, dataModel);
 Object oGraphicProvider = xMultiComponentFactory.createInstanceWithContext("com.sun.star.graphic.GraphicProvider", m_xContext);
 XGraphicProvider xGraphicProvider = (XGraphicProvider)     UnoRuntime.queryInterface(XGraphicProvider.class, oGraphicProvider);
 // create the graphic object
 PropertyValue[] aPropertyValues = new PropertyValue[1];
 PropertyValue aPropertyValue = new PropertyValue();
 aPropertyValue.Name = "URL";
 aPropertyValue.Value = "file:///c:/myimages/testimage.png";
 aPropertyValues[0] = aPropertyValue;
 XGraphic xGraphic = xGraphicProvider.queryGraphic(aPropertyValues);
 xGridDataModel.addRow("1", new Object[]{xGraphic, "1,2", 1.3});
 //one row which contains only text
 xGridDataModel.addRow("2", new Object[] {"2,1","2,2", "1,3"} );

Basic

oDataModel = createUnoService( "com.sun.star.awt.grid.DefaultGridDataModel")
'first parameter is for header title if row header exists, else put empty string
oDataModel.addRow ( "1", Array( "Hamburg", "Germany") )
oDataModel.addRow ( "2", Array("Brisbane", "Australia") )

Create the grid model and assign the column and data model:

There are some new features regarding background, text, header and line color coming with milestone 3. So it's possible to have e.g. green headers, blue background color and red text. Default value for background color is white and for header color is grey. Default value for line color is the color of background, so the lines aren't visible. Default text color is black. There is also the possibility to set a second color for background(use property "EvenRowBackgroundColor") so that the rows will have alternating colors.

Java

 Object gridModel = xMultiServiceFactory.createInstance(
                "com.sun.star.awt.grid.UnoControlGridModel");
 XPropertySet xPSetButton = (XPropertySet) UnoRuntime.queryInterface(
                XPropertySet.class, gridModel);

 xPSetButton.setPropertyValue("PositionX", new Integer(50));
 xPSetButton.setPropertyValue("PositionY", new Integer(30));
 xPSetButton.setPropertyValue("Width", new Integer(400));
 xPSetButton.setPropertyValue("Height", new Integer(400));
 xPSetButton.setPropertyValue("Name", "GridControl");
 xPSetButton.setPropertyValue("TabIndex", new Short((short) 0));
 xPSetButton.setPropertyValue("ColumnModel", xGridColumnModel);
 xPSetButton.setPropertyValue("GridDataModel", xGridDataModel);
 //features coming with integration of milestone 3
 xPSetButton.setPropertyValue("LineColor", 0x000000); //black lines
 xPSetButton.setPropertyValue("HeaderBackgroundColor", 0x00AA00);//green headers
 xPSetButton.setPropertyValue("RowBackgroundColor", 0x0000CC);//blue odd rows
 xPSetButton.setPropertyValue("EvenRowBackgroundColor", 0x00CC00);//green even rows
 //vertical alignemnet is for all cells the same
 xPSetButton.setPropertyValue("VerticalAlign", com.sun.star.style.VerticalAlignment.BOTTOM);
 xPSetButton.setPropertyValue("TextColor", 0xAA0000);//red text
 //for gaining the focus on TAB key stroke
 xPSetButton.setPropertyValue("Tabstop", true);

Basic

oModel = oDialogModel.createInstance( "com.sun.star.awt.grid.UnoControlGridModel" )
oModel.Name="Grid1"
oModel.GridDataModel = oDataModel
oModel.ColumnModel = oColumnModel
oModel.ShowColumnHeader = True
oModel.ShowRowHeader = True
oDialogModel.insertByName("Grid1", oModel )

XGridControl methods

In milestone 3 some new methods for handling selections are introduced. For more information please visit:

http://api.openoffice.org/docs/common/ref/com/sun/star/awt/grid/XGridControl.html

(Note: The wiki page will be updated after the milestone is integrated).

It's also possible to set a tooltip using setToolTip(String[] text, int[] cols). The first parameter shows some fixed text, which can be e.g. some information about the content of the column. If you don't want to use it, leave the array empty. The second parameter is the array containing the column numbers, which content should be shown in the tooltip. If both parameters are empty arrays, then the tooltip will contain the text of the cell where the mouse cursor currently is.

Java

 //sets tooltip with output:
 //content col1: <cont1>
 //content col2: <cont2>
 xGrid.setToolTip(new String{"content col1: ", "content col2: "}, new int{0, 1});

 //sets tooltip with output:
 //<cont1>
 //<cont2>
 xGrid.setToolTip(new String{}, new int{0, 1});

Event Handling

Supported Listeners

Name	Method	Comments
XGridDataListener
	rowAdded
	rowRemoved	Invoked after a remove row call. If removedAll was called the GridDataEvent.Index contains -1.
	dataChanged
XGridColumnListener
	columnChanged
XGridSelectionListener
	selectionChanged

XGridDataListener

The XGridDataListener supports methods to indicate operations on the data model of the grid control. The listener will be invoked by the data model. Each event triggered by the listener uses an instance of GridDataEvent to give details.

Example:

Object dataModel = xMultiComponentFactory.createInstanceWithContext(
                "com.sun.star.awt.grid.DefaultGridDataModel", this.context);
xGridDataModel = (XGridDataModel) UnoRuntime.queryInterface(
                XGridDataModel.class, dataModel);

xGridDataModel.addDataListener(new XGridDataListener() {

                public void rowAdded(GridDataEvent arg0) {
                    throw new UnsupportedOperationException("Not supported yet.");
                }

                public void rowRemoved(GridDataEvent arg0) {
                    throw new UnsupportedOperationException("Not supported yet.");
                }

                public void dataChanged(GridDataEvent arg0) {
                    throw new UnsupportedOperationException("Not supported yet.");
                }

                public void disposing(EventObject arg0) {
                    throw new UnsupportedOperationException("Not supported yet.");
                }
            });

XGridColumnListener

The XGridColumnListener supports methods to indicate operations on the columns of the grid control. The listener will be invoked by the column. Each event triggered by the listener uses an instance of GridColumnEvent to give details.

Example:

Object column =  this.m_factory.createInstanceWithContext(
                "com.sun.star.awt.grid.GridColumn", this.context);
XGridColumn xGridColumn = (XGridColumn) UnoRuntime.queryInterface( XGridColumn.class, column);

xGridColumn.addColumnListener(new XGridColumnListener() {
                public void columnChanged(GridColumnEvent arg0) {
                    throw new UnsupportedOperationException("Not supported yet.");
                }
            });

Known Issues

Iteration	Description	Task ID	Status	Comments
1	Currently it's not possible to grain the focus with the TAB key	110517	fixed in m3
1	If the property UnoControlGridModel HScroll is set to TRUE. All data were drawn in a small rectangle in the upper left corner	110518	fixed in m3
1	If the property UnoControlGridModel HScroll is set to FALSE and many columns were added. The office crashes if you slide with the scrollbar to the right end.	110492	fixed in m3
1	If the property UnoControlGridModel SelectionModel is set to NONE. It's still possible to navigate with the arrow keys through the grid but mouse actions were ignored.	110521	fixed in m3
1	All selection were removed by using left or right arrow keys. Usage of left or right arrow keys shouldn't have an effect on selection	110519	fixed in m3
1	If text content of a cell doesn't fit into the cell it's overwrites the neighbour cell	110520	fixed in m3

Feature Set

• Width for each column
• Height for each row
• Each cell has its own data type
• Column and row header
• Vertical and horizontal scrollbars
• Row selection ( Single, Multi, Range )
• Auto resizing
• A11y

Planned Iteration

Iteration	Due date	Status	Comment	Description	Components
1	2009-07-31	done		To do: UnoControl Selection Textdata only Eventhandling Scrollbars Scrollbar modi Column and row headers	UNO IDL Impl. VCL Impl.
2	2009-11-16	done		To do: A11y	UNO IDL Impl. VCL Impl.
3	2010-04-30	ready for QA		To do: modify column and row size exception handling Different data types A11y Background, align, text settings	UNO IDL Impl. VCL Impl.
4		open		To do: Auto resizing Eventhandling A11y	UNO IDL Impl. VCL Impl.
5		open		To do: Basic IDE Docs/Wiki |	IDE Import/Export UI Doc Wiki SDK-Examples

Grid specification

Key And Mouse Usage

Action	Selection Modus	Description
Selection possibilities with the mouse
Mouse click in a cell	SINGLE / RANGE / MULTI	Single row selection.
Ctrl + mouse click in a cell	MULTI	Multiple rows selection possible, if row has been already selected, deselects it.
Shift + mouse click in a cell	RANGE / MULTI	Multiple rows selection, range is between current row and the chosen one.
Selection possibilities with the keyboard
Ctrl + Alt	SINGLE / RANGE / MULTI	Single row selection, if row has been already selected, deselects it.
Shift + UP	RANGE / MULTI	Multiple rows selection above current row, if rows above the current one have been already selected, they can be deselected one by one.
Shift + DOWN	RANGE / MULTI	Multiple rows selection beneath current row, if rows beneath the current one have been already selected, they can be deselected one by one
Shift + HOME	RANGE / MULTI	Multiple row selection, range is between current row and top one.
Shift + END	RANGE / MULTI	Multiple row selection, range is between current row and bottom one .

• Resizing