UNO Grid Control

From Apache OpenOffice Wiki
< API‎ | UNO AWT
Jump to: navigation, search

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

Overview gridcontrol.png

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
Retrieved from "https://wiki.openoffice.org/w/index.php?title=API/UNO_AWT/Grid_Control&oldid=165648"
Personal tools