Sheet import
The following interfaces handle importing of contents and properties related to individual sheets.
-
class import_sheet
Interface for importing the content and properties of a sheet.
Public Functions
-
virtual ~import_sheet()
-
virtual import_sheet_view *get_sheet_view()
Get an optional interface for importing properties that are specific to a view of a sheet.
- Returns:
pointer to the interface for importing view properties, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_sheet_properties *get_sheet_properties()
Get an optional interface for importing sheet properties.
- Returns:
pointer to the interface for importing sheet properties, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_data_table *get_data_table()
Get an optional interface for importing data tables. Note that the implementer may decide not to support this feature in which case this method should return a
nullptr
.The implementor should initialize the internal state of the temporary data table object when this method is called.
- Returns:
pointer to the data table interface object, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_auto_filter *get_auto_filter()
Get an optional interface for importing auto filter ranges.
The implementor should initialize the internal state of the temporary auto filter object when this method is called.
- Returns:
pointer to the auto filter interface object, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_table *get_table()
Get an interface for importing tables.
The implementor should initialize the internal state of the temporary table object when this method is called.
- Returns:
pointer to the table interface object, or
nullptr
if the implementer doesn’t support importing of tables.
-
virtual import_conditional_format *get_conditional_format()
Get an optional interface for importing conditional formats.
- Returns:
pointer to the conditional format interface object, or
nullptr
if the implementer doesn’t support importing conditional formats.
-
virtual import_named_expression *get_named_expression()
Get an optional interface for importing sheet-local named expressions.
- Returns:
pointer to the sheet-local named expression interface, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_array_formula *get_array_formula()
Get an optional interface for importing array formulas. An array formula is a formula expression applied to a range of cells where each cell may have a different result value.
- Returns:
pointer to the array formula import interface, or a
nullptr
if the implementor doesn’t support it.
-
virtual import_formula *get_formula()
Get an optional interface for importing formula cells.
- Returns:
pointer to the formula interface object, or a
nullptr
if the implementer doesn’t support importing of formula cells.
-
virtual void set_auto(row_t row, col_t col, std::string_view s) = 0
Set raw string value to a cell and have the implementation auto-recognize its data type.
- Parameters:
row – row ID
col – column ID
s – raw string value.
-
virtual void set_string(row_t row, col_t col, string_id_t sindex) = 0
Set string value to a cell.
- Parameters:
row – row ID
col – column ID
sindex – 0-based string index in the shared string table.
-
virtual void set_value(row_t row, col_t col, double value) = 0
Set numerical value to a cell.
- Parameters:
row – row ID
col – column ID
value – value being assigned to the cell.
-
virtual void set_bool(row_t row, col_t col, bool value) = 0
Set a boolean value to a cell.
- Parameters:
row – row ID
col – col ID
value – boolean value being assigned to the cell
-
virtual void set_date_time(row_t row, col_t col, int year, int month, int day, int hour, int minute, double second) = 0
Set date and time value to a cell.
- Parameters:
row – row ID
col – column ID
year – 1-based value representing year
month – 1-based value representing month, varying from 1 through 12.
day – 1-based value representing day, varying from 1 through 31.
hour – the hour of a day, ranging from 0 through 23.
minute – the minute of an hour, ranging from 0 through 59.
second – the second of a minute, ranging from 0 through 59.
-
virtual void set_format(row_t row, col_t col, size_t xf_index) = 0
Set cell format to specified cell. The cell format is referred to by the xf (cell format) index in the styles table.
Note
This method gets called after both set_column_format() and set_row_format().
- Parameters:
row – row ID
col – column ID
xf_index – 0-based xf (cell format) index
-
virtual void set_format(row_t row_start, col_t col_start, row_t row_end, col_t col_end, size_t xf_index) = 0
Set cell format to specified cell range. The cell format is referred to by the xf (cell format) index in the styles table.
- Parameters:
row_start – start row ID
col_start – start column ID
row_end – end row ID
col_end – end column ID
xf_index – 0-based xf (cell format) index
-
virtual void set_column_format(col_t col, col_t col_span, std::size_t xf_index) = 0
Set cell format to a specified column. The cell format is referred to by the xf (cell format) index in the styles table.
Note
This method gets called first before set_row_format() or set_format() variants.
- Parameters:
col – column ID
col_span – number of contiguous columns to apply the format to. It must be at least one.
xf_index – 0-based xf (cell format) index
-
virtual void set_row_format(row_t row, std::size_t xf_index) = 0
Set cell format to a specified row. The cell format is referred to by the xf (cell format) index in the styles table.
Note
This method gets called after set_column_format() but before set_format().
- Parameters:
row – row ID
xf_index – 0-based xf (cell format) index
-
virtual void fill_down_cells(row_t src_row, col_t src_col, row_t range_size) = 0
Duplicate the value of the source cell to one or more cells located immediately below it.
- Parameters:
src_row – row ID of the source cell
src_col – column ID of the source cell
range_size – number of cells below the source cell to copy the source cell value to. It must be at least one.
-
virtual range_size_t get_sheet_size() const = 0
Get the size of the sheet.
- Returns:
structure containing the numbers of rows and columns of the sheet.
-
virtual ~import_sheet()
-
class import_sheet_properties
Interface for importing sheet properties. Sheet properties include:
column widths and row heights,
hidden flags for columns and rows, and
merged cell ranges.
Public Functions
-
virtual ~import_sheet_properties()
-
virtual void set_column_width(col_t col, col_t col_span, double width, orcus::length_unit_t unit) = 0
Set a column width to one or more columns.
- Parameters:
col – 0-based position of the first column.
col_span – number of contiguous columns to apply the width to.
width – column width to apply.
unit – unit of measurement to use for the width value.
Set a column hidden flag to one or more columns.
- Parameters:
col – 0-based position of the first column.
col_span – number of contiguous columns to apply the flag to.
hidden – flag indicating whether or not the columns are hidden.
-
virtual void set_row_height(row_t row, double height, orcus::length_unit_t unit) = 0
Set a row height to specified row.
- Todo:
Convert this to take a raw span.
- Parameters:
row – 0-based position of a row.
height – new row height value to set.
unit – unit of the new row height value.
Set a row hidden flag to a specified row.
- Todo:
Convert this to take a raw span.
- Parameters:
row – 0-based position of a row.
hidden – flag indicating whether or not the row is hidden.
-
class import_data_table
Interface for importing data tables.
Public Functions
-
virtual ~import_data_table()
-
virtual void set_type(data_table_type_t type) = 0
Set the type of a data table. A data table can either:
be a single-variable column-oriented,
be a single-variable row-oriented, or
use two variables that use both column and row.
- Parameters:
type – type of a data table.
-
virtual void set_range(const range_t &range) = 0
Set the range of a data table.
- Parameters:
range – range of a data table.
-
virtual void set_first_reference(std::string_view ref, bool deleted) = 0
Set the reference of the first input cell.
- Parameters:
ref – reference of the first input cell.
deleted – whether or not this input cell has been deleted.
-
virtual void set_second_reference(std::string_view ref, bool deleted) = 0
Set the reference of the second input cell but only if the data table uses two variables.
Note
This method gets called only if the data table uses two variables.
- Parameters:
ref – reference of the second input cell.
deleted – whether or not this input cell has been deleted.
-
virtual void commit() = 0
Store the current data table data in the buffer to the backend sheet storage.
-
virtual ~import_data_table()
-
class import_auto_filter
Interface for importing auto filters.
Importing a single auto filter would roughly follow the following flow:
import_auto_filter* iface = ... ; range_t range; range.first.column = 0; range.first.row = 0; range.last.column = 3; range.last.row = 1000; iface->set_range(range); // Auto filter is applied for A1:D1001. // Column A is filtered for a value of "A". iface->set_column(0); iface->append_column_match_value("A"); iface->commit_column(); // Column D is filtered for values of 1 and 4. iface->set_column(3); iface->append_column_match_value("1"); iface->append_column_match_value("4"); iface->commit_column(); // Push the autofilter data in the current buffer to the sheet store. iface->commit();
Public Functions
-
virtual ~import_auto_filter()
-
virtual void set_range(const range_t &range) = 0
Specify the range where the auto filter is applied.
- Parameters:
range – structure containing the top-left and bottom-right positions of the auto filter range.
-
virtual void set_column(col_t col) = 0
Specify the column position of a filter. The position is relative to the first column in the auto filter range. This method gets called at the beginning of each column filter data. The implementor may initialize the column filter data buffer when this method is called.
Note
This column position is relative to the first column in the autofilter range.
- Parameters:
col – 0-based column position of a filter relative to the first column of the auto filter range.
-
virtual void append_column_match_value(std::string_view value) = 0
Append a match value to the current column filter. A single column filter may have one or more match values.
- Parameters:
value – match value to append to the current column filter.
-
virtual void commit_column() = 0
Commit the current column filter data to the current auto filter buffer. The implementor may clear the current column filter buffer after this call.
-
virtual void commit() = 0
Commit current auto filter data stored in the buffer to the sheet store.
-
virtual ~import_auto_filter()
-
class import_conditional_format
This is an optional interface to import conditional formatting.
In general, a single conditional format consists of:
a cell range the format is applied to, and
one or more rule entries.
a type of rule,
zero or more rule properties, and
zero or more conditions depending on the rule type.
a formula, value, or string,
an optional color.
import_conditional_format* iface = ... ; iface->set_range("A2:A13"); iface->set_xf_id(14); // apply differential format (dxf) whose ID is 14 iface->set_type(conditional_format_t::condition); // rule entry type iface->set_operator(condition_operator_t::expression); iface->set_operator(condition_operator_t::greater); iface->set_formula("2"); iface->commit_condition(); iface->commit_entry(); iface->commit_format();
- Todo:
Revise this API for simplification.
Public Functions
-
virtual ~import_conditional_format()
-
virtual void set_color(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0
Sets the color of the current condition. only valid for type == databar or type == colorscale.
-
virtual void set_formula(std::string_view formula) = 0
Sets the formula, value or string of the current condition.
-
virtual void set_condition_type(condition_type_t type) = 0
Sets the type for the formula, value or string of the current condition. Only valid for type = iconset, databar or colorscale.
-
virtual void set_date(condition_date_t date) = 0
Only valid for type = date.
-
virtual void commit_condition() = 0
commits the current condition to the current entry.
-
virtual void set_icon_name(std::string_view name) = 0
Name of the icons to use in the current entry. only valid for type = iconset
-
virtual void set_databar_gradient(bool gradient) = 0
Use a gradient for the current entry. only valid for type == databar
-
virtual void set_databar_axis(databar_axis_t axis) = 0
Position of the 0 axis in the current entry. only valid for type == databar.
-
virtual void set_databar_color_positive(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0
Databar color for positive values. only valid for type == databar.
-
virtual void set_databar_color_negative(color_elem_t alpha, color_elem_t red, color_elem_t green, color_elem_t blue) = 0
Databar color for negative values. only valid for type == databar.
-
virtual void set_min_databar_length(double length) = 0
Sets the minimum length for a databar. only valid for type == databar.
-
virtual void set_max_databar_length(double length) = 0
Sets the maximum length for a databar. only valid for type == databar.
-
virtual void set_show_value(bool show) = 0
Don’t show the value in the cell. only valid for type = databar, iconset, colorscale.
-
virtual void set_iconset_reverse(bool reverse) = 0
Use the icons in reverse order. only valid for type == iconset.
-
virtual void set_xf_id(size_t xf) = 0
TODO: In OOXML the style is stored as dxf and in ODF as named style.
-
virtual void set_operator(condition_operator_t condition_type) = 0
Sets the current operation used for the current entry. only valid for type == condition
-
virtual void set_type(conditional_format_t type) = 0
-
virtual void commit_entry() = 0
-
virtual void set_range(std::string_view range) = 0
-
virtual void commit_format() = 0
-
class import_table
Interface for table. A table is a range of cells within a sheet that consists of one or more data columns with a header row that contains their labels.
Public Functions
-
virtual ~import_table()
-
virtual import_auto_filter *get_auto_filter()
Get an optional interface for importing auto filter data stored as part of a table.
The implementor should initialize the internal state of the temporary auto filter object when this method is called.
- Returns:
pointer to the auto filter interface object, or a
nullptr
if the implementor doesn’t support it.
-
virtual void set_identifier(size_t id) = 0
Set an integral identifier unique to the table.
- Parameters:
id – identifier associated with the table.
-
virtual void set_range(const range_t &range) = 0
Set a 2-dimensional cell range associated with the table.
- Parameters:
range – cell range associated with the table.
-
virtual void set_totals_row_count(size_t row_count) = 0
Set the number of totals rows.
- Parameters:
row_count – number of totals rows.
-
virtual void set_name(std::string_view name) = 0
Set the internal name of the table.
- Parameters:
name – name of the table.
-
virtual void set_display_name(std::string_view name) = 0
Set the displayed name of the table.
- Parameters:
name – displayed name of the table.
-
virtual void set_column_count(size_t n) = 0
Set the number of columns the table contains.
Note
This method gets called before the column data gets imported. The implementor can use this call to initialize the buffer for storing the column data.
- Parameters:
n – number of columns in the table.
-
virtual void set_column_identifier(size_t id) = 0
Set an integral identifier for a column.
- Parameters:
id – integral identifier for a column.
-
virtual void set_column_name(std::string_view name) = 0
Set a name of a column.
- Parameters:
name – name of a column.
-
virtual void set_column_totals_row_label(std::string_view label) = 0
Set the totals row label for a column.
- Parameters:
label – row label for a column.
-
virtual void set_column_totals_row_function(totals_row_function_t func) = 0
Set the totals row function for a column.
- Parameters:
func – totals row function for a column.
-
virtual void commit_column() = 0
Push and append the column data stored in the current column data buffer into the table buffer.
-
virtual void set_style_name(std::string_view name) = 0
Set the name of a style to apply to the table.
- Parameters:
name – name of a style to apply to the table.
-
virtual void set_style_show_first_column(bool b) = 0
Specify whether or not the first column in the table should have the style applied.
- Parameters:
b – whether or not the first column in the table should have the style applied.
-
virtual void set_style_show_last_column(bool b) = 0
Specify whether or not the last column in the table should have the style applied.
- Parameters:
b – whether or not the last column in the table should have the style applied.
-
virtual void set_style_show_row_stripes(bool b) = 0
Specify whether or not row stripe formatting is applied.
- Parameters:
b – whether or not row stripe formatting is applied.
-
virtual void set_style_show_column_stripes(bool b) = 0
Specify whether or not column stripe formatting is applied.
- Parameters:
b – whether or not column stripe formatting is applied.
-
virtual void commit() = 0
Push the data stored in the table buffer into the document store.
-
virtual ~import_table()
-
class import_formula
Interface for importing the properties of a single formula cell. A formula cell contains a formula expression that can be computed, and optionally a cached result of the last computation performed on the expression.
Public Functions
-
virtual ~import_formula()
-
virtual void set_position(row_t row, col_t col) = 0
Set the position of a cell.
- Parameters:
row – row position.
col – column position.
-
virtual void set_formula(formula_grammar_t grammar, std::string_view formula) = 0
Set formula string to a cell.
- Parameters:
grammar – grammar to use to compile the formula string into tokens.
formula – formula expression to store.
Register the formula stored in a cell as a shared formula to be shared with other cells, if the cell contains a formula string.
If a cell references a shared formula stored in another cell, only specify the index of that shared formula without specifying a formula string of its own. In that case, it is expected that another formula cell registers its formula string for that index.
- Parameters:
index – shared string index to register the formula with.
-
virtual void set_result_string(std::string_view value) = 0
Set cached result of string type.
- Parameters:
value – string result value.
-
virtual void set_result_value(double value) = 0
Set cached result of numeric type.
- Parameters:
value – numeric value to set as a cached result.
-
virtual void set_result_bool(bool value) = 0
Set cached result of boolean type.
- Parameters:
value – boolean value to set as a cached result.
-
virtual void set_result_empty() = 0
Set empty value as a cached result.
-
virtual void commit() = 0
Commit all the formula data to the specified cell.
-
virtual ~import_formula()
-
class import_array_formula
Interface for importing the properties of an array formula which occupies a range of cells. Cells that are part of an array formula share the same formula expression but may have different calculation results.
Public Functions
-
virtual ~import_array_formula()
-
virtual void set_range(const range_t &range) = 0
Set the range of an array formula.
- Parameters:
range – range of an array formula.
-
virtual void set_formula(formula_grammar_t grammar, std::string_view formula) = 0
Set the formula expression of an array formula.
- Parameters:
grammar – grammar to use to compile the formula string into tokens.
formula – formula expression of an array formula.
-
virtual void set_result_string(row_t row, col_t col, std::string_view value) = 0
Set a cached string result of a cell within the array formula range.
- Parameters:
row – 0-based row position of a cell.
col – 0-based column position of a cell.
value – cached string value to set.
-
virtual void set_result_value(row_t row, col_t col, double value) = 0
Set a cached numeric result of a cell within the array formula range.
- Parameters:
row – 0-based row position of a cell.
col – 0-based column position of a cell.
value – cached numeric value to set.
-
virtual void set_result_bool(row_t row, col_t col, bool value) = 0
Set a cached boolean result of a cell within the array formula range.
- Parameters:
row – 0-based row position of a cell.
col – 0-based column position of a cell.
value – cached boolean value to set.
-
virtual void set_result_empty(row_t row, col_t col) = 0
Set an empty value as a cached result to a cell within the array formula range.
- Parameters:
row – 0-based row position of a cell.
col – 0-based column position of a cell.
-
virtual void commit() = 0
Push the properties of an array formula currently stored in the buffer to the sheet store.
-
virtual ~import_array_formula()