Difference between revisions of "Calc/Features/DataPilot drill-down on data field"

From Apache OpenOffice Wiki
< Calc‎ | Features
Jump to: navigation, search
(DataPilotFieldFilter: comment for MatchValue.)
(DataPilotTablePositionData: added javadoc comments.)
Line 143: Line 143:
 
//=============================================================================
 
//=============================================================================
  
 +
/** This structure contains information on a cell within a DataPilot table.
 +
 +
    <p>This structure contains information on a particular cell within a DataPilot
 +
    table, and is used to retrieve its metadata.  The <member>PositionType</member>
 +
    member specifies in which sub-area of the table the cell is positioned, which
 +
    in turn determines the type of metadata contained in the <member>PositionData</member>
 +
    member.</p>
 +
*/
 
struct DataPilotTablePositionData
 
struct DataPilotTablePositionData
 
{
 
{
     /** See DataPilotTablePositionType. */
+
//-------------------------------------------------------------------------
 +
 
 +
     /** This parameter specifies which sub-area of a DataPilot table a given
 +
        cell is positioned.  See <type scope="com::sun::star::sheet">DataPilotTablePositionType</type>
 +
        for how to interpret the value of this parameter.
 +
 
 +
        @see <type scope="com::sun::star::sheet">DataPilotTablePositionType</type>
 +
    */
 
     long    PositionType;
 
     long    PositionType;
  
     /** Different depending on the position type. */
+
//-------------------------------------------------------------------------
 +
 
 +
     /** <p>This member contains a structure of different types depending on the  
 +
        position type specified in <member scope="com::sun::star::sheet">PositionType</member> member.</p>
 +
 
 +
        <p>When the value of <member scope="com::sun::star::sheet">PositionType</member> is
 +
        <const scope="com::sun::star::sheet">DataPilotTablePositionType::RESULT</const>,
 +
        <member scope="com::sun::star::sheet">PositionData</member> contains an instance of type
 +
        <type scope="com::sun::star::sheet">DataPilotTableResultData</type>, whereas when the value of
 +
        <member scope="com::sun::star::sheet">PositionType</member> is either <const scope="com::sun::star::sheet">
 +
        DataPilotTablePositionType::ROW_HEADER</const> or <const scope="com::sun::star::sheet">
 +
        DataPilotTablePositionType::COLUMN_HEADER</const>, then the <member scope="com::sun::star::sheet">
 +
        PositionData</member> member contains an instance of type <type scope="com::sun::star::sheet">
 +
        DataPilotTableHeaderData</type></p>
 +
 
 +
        @see <type scope="com::sun::star::sheet">DataPiotTableResultData</type>
 +
        @see <type scope="com::sun::star::sheet">DataPiotTableHeaderData</type>
 +
    */
 
     any    PositionData;
 
     any    PositionData;
 
};
 
};

Revision as of 22:01, 6 December 2007

DataPilot Drill-Down on Data Field

Specification Status
Author Kohei Yoshida
Last Change See wiki history
Status Preliminary

Abstract

Foo

References

Fill this.

Contacts

Role Name E-Mail Address
Developer Kohei Yoshida kyoshida@novell.com
Quality Assurance nobody
Documentation nobody
User Experience nobody

Description

When a cell within the data field is double-clicked, it inserts a new sheet containing a subset of rows from the original data source that constitutes the result data displayed in that cell. For instance, when the data field function is selected to be SUM, then the number that is shown in the data field cell must be identical to the sum of all the data field values in the constituent rows displayed in the inserted sheet.

The area that can provide a drill-down sheet spans from the top-left cell in the data field to the bottom-right corner of the data pilot output, including the Total Result row and column.

The same function is available using "Data / Group and Outline / Show Details" from the menu, with the cell cursor on the result cell.

Hidden items ("Hide items" or "Show automatically" in the field options dialog) are not evaluated, the rows for the hidden items are included.

The feature is available for DataPilot tables from cell ranges or database data, but not yet for external service implementations (see API Change below).

API Change (scheduled for 3.0)

This functionality introduces the following new API.

DataPilotSource

The following three optional properties have been added to the existing DataPilotSource service:

  • RowFieldCount - specifies the number of row fields in the data source.
  • ColumnFieldCount - specifies the number of column fields in the data source.
  • DataFieldCount - specifies the number of data fields in the data source.

Note that these properties are read-only, thus you cannot directly set their values via API.

[idl,N] module com { module sun { module star { module sheet {

published service DataPilotSource {

   (....)
   //-------------------------------------------------------------------------
   /** specifies the number of row fields. */
   [readonly, property, optional] long RowFieldCount;
   //-------------------------------------------------------------------------
   /** specifies the number of column fields. */
   [readonly, property, optional] long ColumnFieldCount;
   //-------------------------------------------------------------------------
   /** specifies the number of data fields. */
   [readonly, property, optional] long DataFieldCount;

};

}; }; }; };

DataPilotFieldFilter

[idl,N] module com { module sun { module star { module sheet {

//=============================================================================

/** A single filtering condition used when constructing a drill-down sheet.


Each instance of <type scope="com::sun::star::sheet">DataPilotFieldFilter</type> represents a filtering condition. It is used when evaluating a row in a data source whether or not to include it in a filtered subset of the original data. For example, for a given row to be included in the output of a drill-down data table, the row must match every single instance of <type scope="com::sun::star::sheet">DataPilotFieldFilter</type> to be qualified. If the field specified by the value of <member scope="com::sun::star::sheet">FieldName</member> is not found, then that filter condition will not be evaluated.

Note that this struct is typically used in a sequence and is not normally used as a single instance.

  @see <method scope="com::sun::star::sheet">XDrillDownDataSupplier::getDrillDownData</method>
  @see <type scope="com::sun::star::sheet">DataPilotTableResultData</type>
  @since OOo 3.0.0
*/

struct DataPilotFieldFilter {

   /** Field name.
       @see <type scope="com::sun::star::sheet">DataPilotField</type>
    */
   string FieldName;
   /** String value to match against. */
   string MatchValue;

};

//=============================================================================

}; }; }; };

DataPilotTablePositionData

[idl,N] module com { module sun { module star { module sheet {

//=============================================================================

/** This structure contains information on a cell within a DataPilot table.

This structure contains information on a particular cell within a DataPilot table, and is used to retrieve its metadata. The <member>PositionType</member> member specifies in which sub-area of the table the cell is positioned, which in turn determines the type of metadata contained in the <member>PositionData</member> member.

*/

struct DataPilotTablePositionData { //-------------------------------------------------------------------------

   /** This parameter specifies which sub-area of a DataPilot table a given 
       cell is positioned.  See <type scope="com::sun::star::sheet">DataPilotTablePositionType</type>
       for how to interpret the value of this parameter.
       @see <type scope="com::sun::star::sheet">DataPilotTablePositionType</type>
    */
   long    PositionType;

//-------------------------------------------------------------------------

/**

This member contains a structure of different types depending on the position type specified in <member scope="com::sun::star::sheet">PositionType</member> member.

When the value of <member scope="com::sun::star::sheet">PositionType</member> is <const scope="com::sun::star::sheet">DataPilotTablePositionType::RESULT</const>, <member scope="com::sun::star::sheet">PositionData</member> contains an instance of type <type scope="com::sun::star::sheet">DataPilotTableResultData</type>, whereas when the value of <member scope="com::sun::star::sheet">PositionType</member> is either <const scope="com::sun::star::sheet"> DataPilotTablePositionType::ROW_HEADER</const> or <const scope="com::sun::star::sheet"> DataPilotTablePositionType::COLUMN_HEADER</const>, then the <member scope="com::sun::star::sheet"> PositionData</member> member contains an instance of type <type scope="com::sun::star::sheet"> DataPilotTableHeaderData</type>

       @see <type scope="com::sun::star::sheet">DataPiotTableResultData</type>
       @see <type scope="com::sun::star::sheet">DataPiotTableHeaderData</type>
    */
   any     PositionData;

};

//=============================================================================

}; }; }; };

DataPilotTablePositionType

[idl,N] module com { module sun { module star { module sheet {

//============================================================================

constants DataPilotTablePositionType {

   //------------------------------------------------------------------------
   const long NOT_IN_TABLE = 0;
   //------------------------------------------------------------------------
   const long RESULT = 1;
   //------------------------------------------------------------------------
   const long ROW_HEADER = 2;
   //------------------------------------------------------------------------
   const long COLUMN_HEADER = 3;
   //------------------------------------------------------------------------

};

//============================================================================

}; }; }; };

DataPilotOutputRangeType

[idl,N] constants DataPilotOutputRangeType {

   //------------------------------------------------------------------------
   const long WHOLE = 0;
   //------------------------------------------------------------------------
   const long TABLE = 1;
   //------------------------------------------------------------------------
   const long RESULT = 2;

};

DataPilotTableHeaderData

[idl,N] module com { module sun { module star { module sheet {

//=============================================================================

/** information about a cell positioned within the column or row header area of a DataPilot table.

   {TODO: detailed description}
   @see com::sun::star::sheet::DataPilotTablePositionData
   @see com::sun::star::sheet::DataPilotTablePositionType
   @see com::sun::star::sheet::DataPilotFieldFilter
   @see com::sun::star::sheet::DataResult
*/

struct DataPilotTableHeaderData {

   long    Dimension;
   long    Hierarchy;
   long    Level;
   long    Flags;
   string  MemberName;

};

//=============================================================================

}; }; }; };

DataPilotTableResultData

[idl,N] struct DataPilotTableResultData {

   sequence< DataPilotFieldFilter >    FieldFilters;
   long                                DataFieldIndex;
   DataResult                          Result;

};

XDataPilotTable2

[idl,N] module com { module sun { module star { module sheet {

interface XDataPilotTable2: com::sun::star::sheet::XDataPilotTable {

   sequence< sequence< any > > getDrillDownData( [in] com::sun::star::table::CellAddress aAddr );
   DataPilotTablePositionData getPositionData( [in] com::sun::star::table::CellAddress aAddr );
   void insertDrillDownSheet( [in] com::sun::star::table::CellAddress aAddr );
   com::sun::star::table::CellRangeAddress getOutputRangeByType( [in] long nRegionType );

};

}; }; }; }; The interface com.sun.star.sheet.XDataPilotTable2 extends the existing com.sun.star.sheet.XDataPilotTable interface to provide additional method getDrillDownData() so that the client code can obtain constituent rows from the data pilot table. The existing com.sun.star.sheet.DataPilotTable service will support this new interface.

XDrillDownDataSupplier

[idl,N] module com { module sun { module star { module sheet {

interface XDrillDownDataSupplier: com::sun::star::uno::XInterface {

   sequence< sequence< any > > getDrillDownData( 
       [in] sequence< com::sun::star::sheet::DataPilotFieldFilter > aFilters );

};

}; }; }; };

The com.sun.star.sheet.DataPilotSource service will support the XDrillDownDataSupplier interface to provide a 2-dimensional array data consisting of a subset of the original data source table that satisfies a given set of filtering criteria. A sequence of DataPilotFieldFilter provides desired filtering criteria to getDrillDownData() method. This interface is intended for an external UNO package so that it can overwrite the interface to provide constituent rows when requested.

Migration

This does not affect migration as it is a completely new feature. However, it may help migration from Excel as Excel already has similar feature in place.

Configuration

File Format

This feature will not introduce a file format change.

Open Issues

Personal tools