Class CalcCellRange

class ooodev.calc.CalcCellRange(owner, rng, lo_inst=None)[source]

Bases: LoInstPropsPartial, CalcDocPropPartial, CalcSheetPropPartial, SheetCellRangeComp, EventsPartial, CellProperties2PartialProps, QiPartial, PropPartial, StylePartial, ServicePartial, TheDictionaryPartial, FontOnlyPartial, FontEffectsPartial, FontPartial, TextAlignPartial, TextOrientationPartial, PropertiesPartial, FillColorPartial, CalcBordersPartial, CellProtectionPartial, NumbersNumbersPartial, StylePropertyPartial

Represents a calc cell range.

Parameters:

owner (CalcSheet) –
rng (Any) –
lo_inst (LoInst | None) –

__eq__(other)[source]

Compares two instances of CalcCellRange.

Return type:: bool
Parameters:: other (Any) –

__init__(owner, rng, lo_inst=None)[source]

Constructor

Parameters:

owner (CalcSheet) – Sheet that owns this cell range.
rng (Any) – Range object.
lo_inst (LoInst | None) –

Return type:

None

__ne__(other)[source]

Compares two instances of CalcCellRange.

Return type:: bool
Parameters:: other (Any) –

add_event_chart_data_change_event_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Return type:: None
Parameters:: cb (Any) –

add_event_chart_data_changed(cb)

Adds a listener for an event.

Event is invoked when chart data changes in value or structure.

The callback EventArgs.event_data will contain a UNO com.sun.star.chart.ChartDataChangeEvent struct.

Return type:: None
Parameters:: cb (Any) –

add_event_modified(cb)

Adds a listener for an event.

Event is invoked when something changes in the object.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Return type:: None
Parameters:: cb (Any) –

add_event_modify_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Return type:: None
Parameters:: cb (Any) –

add_event_observers(*args)

Adds observers that gets their trigger method called when this class trigger method is called.

Parameters:: args (EventObserver) – One or more observers to add.
Return type:: None

Note

Observers are removed automatically when they are out of scope.

add_event_property_change(name, cb)

Adds a listener for an event.

Event is invoked when property is changed.

The callback EventArgs.event_data will contain a com.sun.star.beans.PropertyChangeEvent struct.

Parameters:

name (str) – Property Name
cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_property_change_events_disposing(name, cb)

Adds a listener for an event.

Event is invoked when the property listener is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Parameters:

name (str) – Property Name
cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_vetoable_change(name, cb)

Adds a listener for an event.

Event is invoked when property is changed.

The callback EventArgs.event_data will contain a com.sun.star.beans.PropertyChangeEvent struct.

Parameters:

name (str) – Property Name
cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_vetoable_change_events_disposing(name, cb)

Adds a listener for an event.

Event is invoked when the property listener is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Parameters:

name (str) – Property Name
cb (EventArgsCallbackT) – Callback

Return type:

None

apply_styles(*styles, **kwargs)

Applies style to component.

Parameters:

obj. (styles expandable list of styles object such as Font to apply to) –
kwargs (Any, optional) – Expandable list of key value pairs.
styles (StyleT) –

Return type:

None

change_style(style_name)[source]

Changes style of a range of cells.

Parameters:

style_name (str) – Name of style to apply.
range_obj (RangeObj) – Range Object.

Returns:

True if style has been changed; Otherwise, False.

Return type:

bool

clear_cells(cell_flags=None)[source]

Clears the specified contents of the cell range

If cell_flags is not specified then cell range of types VALUE, DATETIME and STRING are cleared

Raises:

MissingInterfaceError – If XSheetOperation interface cannot be obtained.

Events:

Parameters:

cell_flags (CellFlagsEnum, optional) – Cell flags to clear. Default None.

Returns:

True if cells are cleared; Otherwise, False

Return type:

bool

Note

Events arg for this method have a cell type of XCellRange.

Events arg event_data is a dictionary containing cell_flags.

Hint

CellFlagsEnum can be imported from ooo.dyn.sheet.cell_flags

contains(cell_obj: ooodev.utils.data_type.cell_obj.CellObj)[source]

contains(cell_addr: com.sun.star.table.CellAddress)

contains(cell_vals: ooodev.utils.data_type.cell_values.CellValues)

contains(cell_name: str)

contains(*args, **kwargs)

Gets if current instance contains a cell value.

Parameters:

cell_obj (CellObj) – Cell object
cell_addr (CellAddress) – Cell address
cell_vals (CellValues) – Cell Values
cell_name (str) – Cell name

Returns:

True if instance contains cell; Otherwise, False.

Return type:

bool

Note

If cell input contains sheet info the it is use in comparison. Otherwise sheet is ignored.

copy()[source]

Copies the instance.

Returns:: Copied instance.
Return type:: CalcCellRange

New in version 0.47.7.

create_cursor()[source]

Creates a cell cursor to travel in the given range context.

Returns:: Cell cursor
Return type:: CalcCellCursor

delete_cells(is_shift_left)[source]

Deletes cell in a spreadsheet

Parameters:

is_shift_left (bool) – If True then cell are shifted left; Otherwise, cells are shifted up.

Events:

Returns:

True if cells are deleted; Otherwise, False

Return type:

bool

Note

Events args for this method have a cell type of XCellRange

Note

Event args event_data is a dictionary containing is_shift_left.

export_as_image(fnm, resolution=96)[source]

Exports a range of cells as an image.

If the filename extension is .png then the image is exported as a PNG; Otherwise, image is exported as a JPEG.

Parameters:

fnm (PathOrStr) – Filename to export to.
resolution (int, optional) – Resolution in dpi. Defaults to 96.

Return type:

None

Example

from pathlib import Path
from ooodev.events.args.cancel_event_args_export import CancelEventArgsExport
from ooodev.events.args.event_args_export import EventArgsExport
from ooodev.calc.filter.export_png import ExportPngT
from ooodev.calc import CalcNamedEvent

def on_exporting(source: Any, args: CancelEventArgsExport[ExportJpgT]) -> None:
    args.event_data["compression"] = 9

def on_exported(source: Any, args: EventArgsGeneric[ImgExportT]) -> None:
    print(f"Image has been exported to {args.event_data['file']}")

rng = sheet.get_range(range_name="A1:M4")
rng.subscribe_event(CalcNamedEvent.EXPORTING_RANGE_JPG, on_exporting)
rng.subscribe_event(CalcNamedEvent.EXPORTED_RANGE_JPG, on_exported)
pth = Path("./export_range.jpg")
rng.export_as_image(pth)

See also

Live LibreOffice Example Export Calc Sheet Range as Image
export_jpg()
export_png()

New in version 0.20.3.

export_jpg(fnm, resolution=96)[source]

Exports page as jpg image.

Parameters:

fnm (PathOrStr, optional) – Image file name.
resolution (int, optional) – Resolution in dpi. Defaults to 96.

Raises:

ValueError – If fnm is empty.
CancelEventError – If EXPORTING_RANGE_JPG event is canceled.

Events:

Return type:

None

Note

On exporting event is Class CancelEventArgsExport. On exported event is Class EventArgsExport. Args event_data is a ExportJpgT dictionary.

Example

from pathlib import Path
from ooodev.events.args.cancel_event_args_export import CancelEventArgsExport
from ooodev.events.args.event_args_export import EventArgsExport
from ooodev.calc.filter.export_jpg import ExportJpgT
from ooodev.calc import CalcNamedEvent

def on_exporting(source: Any, args: CancelEventArgsExport[ExportJpgT]) -> None:
    args.event_data["quality"] = 80

def on_exported(source: Any, args: EventArgsExport[ExportJpgT]) -> None:
    print(f"Image has been exported to {args.fnm}")

rng = sheet.get_range(range_name="A1:M4")
rng.subscribe_event(CalcNamedEvent.EXPORTING_RANGE_JPG, on_exporting)
rng.subscribe_event(CalcNamedEvent.EXPORTED_RANGE_JPG, on_exported)
pth = Path("./export_range.jpg")
rng.export_jpg(pth)

See also

Live LibreOffice Example Export Calc Sheet Range as Image

New in version 0.21.0.

export_png(fnm, resolution=96)[source]

Exports page as jpg image.

Parameters:

fnm (PathOrStr, optional) – Image file name.
resolution (int, optional) – Resolution in dpi. Defaults to 96.

Raises:

ValueError – If fnm is empty.
CancelEventError – If EXPORTING_RANGE_PNG event is canceled.

Events:

Return type:

None

Note

On exporting event is Class CancelEventArgsExport. On exported event is Class EventArgsExport. Args event_data is a ExportPngT dictionary.

Example

from pathlib import Path
from ooodev.events.args.cancel_event_args_export import CancelEventArgsExport
from ooodev.events.args.event_args_export import EventArgsExport
from ooodev.calc.filter.export_png import ExportPngT
from ooodev.calc import CalcNamedEvent

def on_exporting(source: Any, args: CancelEventArgsExport[ExportPngT]) -> None:
    args.event_data["compression"] = 9

def on_exported(source: Any, args: EventArgsExport[ExportPngT]) -> None:
    print(f"Image has been exported to {args.fnm}")

rng = sheet.get_range(range_name="A1:M4")
rng.subscribe_event(CalcNamedEvent.EXPORTING_RANGE_JPG, on_exporting)
rng.subscribe_event(CalcNamedEvent.EXPORTED_RANGE_JPG, on_exported)
pth = Path("./export_range.png")
rng.export_png(pth)

See also

Live LibreOffice Example Export Calc Sheet Range as Image

New in version 0.21.0.

find_used_range(content_flags=23)[source]

Finds used range.

The used range is found by querying the current range for content specified by the content_flags.

Parameters:: content_flags (int, optional) – CellFlags. Defaults to 23.
Raises:: CellRangeError – If unable to get used range object
Returns:: The Cell Range object that represents the used range.
Return type:: CalcCellRange

Note

Default CellFlags is: CellFlags.FORMULA | CellFlags.VALUE | CellFlags.DATETIME | CellFlags.STRING

CellFlags can be imported from com.sun.star.sheet.

See also

API CellFlags

New in version 0.47.7.

classmethod from_obj(obj, lo_inst=None)[source]

Creates a CalcCellRange from an object.

Parameters:

obj (Any) – Object to create CalcCellRange from. Can be a CalcCellRange, CalcCellRangePropPartial, or any object that can be converted to a CalcCellRange such as a cell.
lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Returns:

CalcSheet if found; Otherwise, None

Return type:

CalcSheet

New in version 0.46.0.

get_address()[source]

Gets Range Address.

Returns:: Cell Range Address.
Return type:: CellRangeAddress

get_array()[source]

Gets a 2-Dimensional array of values from a range of cells.

Returns:: 2-Dimensional array of values.
Return type:: TupleArray

get_cell_range()[source]

Gets the XCellRange for the current range.

Returns:: Cell series
Return type:: XCellRange

get_cell_range_address()[source]

Gets the cell range address for the current range.

Returns:: Cell range address
Return type:: CellRangeAddress

get_cell_series()[source]

Gets the cell series for the current range.

Returns:: Cell series
Return type:: XCellSeries

get_col()[source]

Gets a column of data from spreadsheet.

Parameters:: range_obj (RangeObj) – Range Object.
Returns:: 1-Dimensional List.
Return type:: List[Any]

get_data_array()

Gets an array from the contents of the cell range.

Each element of the result contains a float or a string.

Return type:: Tuple[Tuple[Any, ...], ...]

get_float_array()[source]

Gets a 2-Dimensional List of floats.

Returns:: 2-Dimensional List of floats.
Return type:: FloatTable

get_property(name, default=<object object>)

Get property value

Parameters:

name (str) – Property Name.
default (Any, optional) – Return value if property value is None.

Returns:

Property value or default.

Return type:

Any

get_range_size()[source]

Gets the size of the range.

Returns:: Size, Width is number of Columns and Height is number of Rows
Return type:: Size

get_range_str()[source]

Gets the range as a string in format of A1:B2 or Sheet1.A1:B2

If sheet is included the format Sheet1.A1:B2 is returned; Otherwise, A1:B2 format is returned.

Returns:: range as string
Return type:: str

get_row()[source]

Gets a row of data from spreadsheet

Parameters:: range_obj (RangeObj) – Range Object
Returns:: 1-Dimensional List of values on success; Otherwise, None
Return type:: Row

get_services()

Gets service names for the instance.

Returns:: service names
Return type:: List[str]

get_val()[source]

Get the value of the very first cell in the range.

Useful for merged cells.

Returns:: Value of cell.
Return type:: Any

highlight(headline: str)[source]

highlight(headline: str, color: Color)

highlight(headline, color=11393254)

Draw a colored border around the range and write a headline in the top-left cell of the range.

Parameters:

headline (str) – Headline.
color (Color) – RGB color.

Returns:

Cell object. First cell of range that headline ia applied on.

Return type:

CalcCell

insert_chart(*, cell_name='', width=16, height=9, diagram_name='Column', color_bg=14085119, color_wall=11393254, **kwargs)[source]

Insert a new chart.

Parameters:

cell_name (str, optional) – Cell name such as A1.
width (int, optional) – Width. Default 16.
height (int, optional) – Height. Default 9.
diagram_name (ChartTemplateBase | str) – Diagram Name. Defaults to Column.
color_bg (Color, optional) – Color Background. Defaults to CommonColor.PALE_BLUE. If set to None then no color is applied.
color_wall (Color, optional) – Color Wall. Defaults to CommonColor.LIGHT_BLUE. If set to None then no color is applied.

Keyword Arguments:

chart_name (str, optional) – Chart name
is_row (bool, optional) – Determines if the data is row data or column data.
first_cell_as_label (bool, optional) – Set is first row is to be used as a label.
set_data_point_labels (bool, optional) – Determines if the data point labels are set.

Raises:

ChartError – If error occurs

Returns:

Chart Document that was created and inserted into the sheet.

Return type:

TableChart

Note

Keyword Arguments are to mostly be ignored. If finer control over chart creation is needed then Keyword Arguments can be used.

Note

See Open Office Wiki - The Structure of Charts for more information.

See also

is_merged_cells()[source]

Gets is a range of cells is merged.

Parameters:: range_obj (RangeObj) – Range Object.
Returns:: True if range is merged; Otherwise, False
Return type:: bool

is_single_cell_range()[source]

Gets if a cell address is a single cell or a range

Returns:: True if single cell; Otherwise, False
Return type:: bool

is_single_column_range()[source]

Gets if a cell address is a single column or multi-column

Returns:: True if single column; Otherwise, False
Return type:: bool

is_single_row_range()[source]

Gets if a cell address is a single row or multi-row

Returns:: True if single row; Otherwise, False
Return type:: bool

merge_cells(center=False)[source]

Merges a range of cells

Parameters:: center (bool) – Determines if the merge will be a merge and center. Default False.
Return type:: None

See also

qi(atype, raise_err=False)

Generic method that get an interface instance from an object.

Parameters:

atype (T) – Interface type to query obj for. Any Uno class that starts with ‘X’ such as XInterface
raise_err (bool, optional) – If True then raises MissingInterfaceError if result is None. Default False

Raises:

MissingInterfaceError – If ‘raise_err’ is ‘True’ and result is None

Returns:

instance of interface if supported; Otherwise, None

Return type:

T | None

Note

When raise_err=True return value will never be None.

refresh()[source]

Refreshes the range of cells.

This method should be call if the sheet has rows or columns inserted or deleted since this instance as been created.

Return type:: None

New in version 0.45.0.

remove_border()[source]

Removes border from range of cells.

Return type:: None

New in version 0.25.2.

remove_event_chart_data_change_event_events_disposing(cb)