UNO Grid Control

    From The Document Foundation Wiki
    < API

    Abstract

    LibreOffice 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

    File: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


    Apache Feather Logo.svg

    This work is licensed under the Apache License version 2.0