Class PopupRngSelPartial

class ooodev.calc.partial.popup_rng_sel_partial.PopupRngSelPartial(doc)[source]

A partial class for Selecting a range from a popup.

Parameters:: doc (CalcDoc) –

Parameters:: doc (CalcDoc) –
Return type:: None

get_range_selection_from_popup(title='Please select a range', close_on_mouse_release=False, single_cell_mode=False, initial_value='')[source]

Gets a range selection from a popup that allows the user to select a range with the mouse.

There is a automatic timeout of 60 seconds for the popup to be displayed. The timeout is to prevent the method from hanging indefinitely if the popup is not displayed. If the popup is not displayed within 60 seconds, the method will return None.

If you are running from the command line, you can use this method; Otherwise, use invoke_range_selection() method instead.

If macro mode ( no bridge connection ) is detected, the method will use the invoke_range_selection() method instead and no result will be returned.

Parameters:

title (str, optional) – The title of the popup. Defaults to “Please select a range”.
close_on_mouse_release (bool, optional) – Specifies if the dialog closes when mouse is released. Defaults to False.
single_cell_mode (bool, optional) – Specifies if the dialog is in single cell mode. Defaults to False.
initial_value (str, optional) – The initial value of the range. Defaults to “”.

Returns:

The range object or None if no selection was made.

Return type:

RangeObj | None

Warning

This method requires the GUI to be present and will not work in Headless mode.

Note

This method triggers the following events when this partial class is used in a class that inherits from EventsPartial:

BeforePopupRangeSelection
AfterPopupRangeSelection

The event data for the BeforePopupRangeSelection event is a DotDict with the following keys:

doc: The CalcDoc object
title: The title of the popup
close_on_mouse_release: Specifies if the dialog closes when mouse is released.
single_cell_mode: Specifies if the dialog is in single cell mode.
initial_value: The initial value of the range.

The event data for the AfterPopupRangeSelection event is a DotDict with the following keys:

view: The CalcSheetView object
state: The state of the selection, either “done” or “aborted”
rng_obj: The RangeObj object, which is the range selected by the user or None.
close_on_mouse_release: Specifies if the dialog closes when mouse is released.
single_cell_mode: Specifies if the dialog is in single cell mode.
initial_value: The initial value of the range selection.
result: The result of the range selection from RangeSelectionEvent.RangeDescriptor Can be a string such as $Sheet1.$A$1:$B$2.

The GlobalCalcRangeSelector has the same event data as the AfterPopupRangeSelection event. See the invoke_range_selection() method for an example of using the global event.

New in version 0.47.1.

invoke_range_selection(title='Please select a range', close_on_mouse_release=False, single_cell_mode=False, initial_value='')[source]

Displays a range selection popup that allows the user to select a range with the mouse.

If you are running from the command line, you can use the get_range_selection_from_popup() method instead.

There is a automatic timeout of 60 seconds for the popup to be displayed. The timeout is to prevent the method from hanging indefinitely if the popup is not displayed. If the popup is not displayed within 60 seconds, the method will return None.

Parameters:

title (str, optional) – The title of the popup. Defaults to “Please select a range”.
close_on_mouse_release (bool, optional) – Specifies if the dialog closes when mouse is released. Defaults to False.
single_cell_mode (bool, optional) – Specifies if the dialog is in single cell mode. Defaults to False.
initial_value (str, optional) – The initial value of the range. Defaults to “”.

Return type:

None

Warning

This method requires the GUI to be present and will not work in Headless mode.

Note

This method triggers the following events when this partial class is used in a class that inherits from EventsPartial:

BeforePopupRangeSelection
AfterPopupRangeSelection

The event data for the BeforePopupRangeSelection event is a DotDict with the following keys:

doc: The CalcDoc object
title: The title of the popup
close_on_mouse_release: Specifies if the dialog closes when mouse is released.
single_cell_mode: Specifies if the dialog is in single cell mode.
initial_value: The initial value of the range.

The event data for the AfterPopupRangeSelection event is a DotDict with the following keys:

view: The CalcSheetView object
state: The state of the selection, either “done” or “aborted”
rng_obj: The RangeObj object, which is the range selected by the user or None.
close_on_mouse_release: Specifies if the dialog closes when mouse is released.
single_cell_mode: Specifies if the dialog is in single cell mode.
initial_value: The initial value of the range selection.
result: The result of the range selection from RangeSelectionEvent.RangeDescriptor Can be a string such as $Sheet1.$A$1:$B$2.

Because popup dialogs can block the main GUI Thread, this method is run in a separate thread. That means it is not possible to return the result of the range selection directly. Instead, the result is passed to the AfterPopupRangeSelection event and in a global event named GlobalCalcRangeSelector.

The GlobalCalcRangeSelector has the same event data as the AfterPopupRangeSelection event.

Example

Example of using the global event GlobalCalcRangeSelector. In this case MyObj could also be a dialog that need to be update when the range selection is done.

from typing import Any
from ooodev.globals import GblEvents
from ooodev.events.args.event_args import EventArgs

class MyObj:
    def __init__(self):
        self._fn_on_range_sel = self._on_range_sel
        GblEvents().subscribe("GlobalCalcRangeSelector", self._fn_on_range_sel)

    def on_range_selection(self, src:Any, event: EventArgs):
        if event.event_data.state == "done":
            print("Range Selection", event.event_data.rng_obj)

New in version 0.47.3.