Class Dialogs

class ooodev.dialog.Dialogs[source]

Manages creating, accessing and inserting controls into dialogs

StateEnum: alias of TriStateKind

classmethod create_dialog(*, x, y, width, height, title, **props)[source]

Creates a dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

x (int) – X coordinate. If -1, the dialog Position is not set.
y (int) – Y coordinate. If -1, the dialog Position is not set.
width (int) – Width. If -1, the dialog Size is not set.
height (int) – Height. If -1, the dialog Size is not set.
title (str) – Dialog title.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create dialog.

Returns:

Control.

Return type:

CtlDialog

See also

API UnoControlDialogModel Service

classmethod create_dialog_peer(dialog_ctrl)[source]

Creates a dialog peer.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:: dialog_ctrl (XControl) – control.
Returns:: Dialog.
Return type:: XDialog

static create_name(elem_container, name)[source]

Creates a name.

Make a unique string by appending a number to the supplied name.

Method is Lo Instance Safe for use with multiple documents.

Parameters:

elem_container (XNameAccess) – container.
name (str) – current name.

Returns:

a name not in container.

Return type:

str

static find_control(dialog_ctrl, name)[source]

Finds control by name.

Method is Lo Instance Safe for use with multiple documents.

Parameters:

dialog_ctrl (XControl) – Control.
name (str) – Name to find.

Returns:

Control if found, else None.

Return type:

XControl

classmethod find_controls(dialog_ctrl, control_type)[source]

Finds controls by type.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
control_type (ControlT) – Control type.

Returns:

List of controls.

Return type:

List[ControlT]

classmethod find_radio_siblings(dialog_ctrl, radio_button)[source]

Given the name of the first radio button of a group, return all the controls of the group.

For dialogs, radio buttons are considered of the same group when their tab indexes are contiguous.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
radio_button (str) – Specifies the exact name of the 1st radio button of the group.

Returns:

List of the names of the 1st and the next radio buttons. belonging to the same group in their tab index order. does not include the first button.

Return type:

List[CtlRadioButton]

See also

get_radio_group_value().

classmethod get_control_class_id(control)[source]

Gets control class id.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: control (XControl) – control.
Returns:: class id.
Return type:: str

classmethod get_control_name(control)[source]

Get the name of a control.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: control (XControl) – control.
Returns:: control name.
Return type:: str

static get_control_props(control_model)[source]

Gets property set for a control model.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: control_model (Any) – control model.
Returns:: Property set.
Return type:: XPropertySet

static get_dialog(dialog_ctrl)[source]

Gets dialog from dialog control.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: dialog_ctrl (XControl) – control.
Returns:: dialog.
Return type:: XDialog

static get_dialog_control(dialog)[source]

Gets dialog control.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: dialog (XDialog) – dialog.
Returns:: control.
Return type:: XControl

static get_dialog_control_instance(dialog_ctrl)[source]

Gets a control as a DialogControlBase control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:: dialog_ctrl (XControl) – Control.
Returns:: Returns a DialogControlBase such as CtlButton or CtlCheckBox if found, else None
Return type:: DialogControlBase | None

static get_dialog_controls_arr(dialog_ctrl)[source]

Gets all controls for a given control.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: dialog_ctrl (XControl) – control.
Returns:: controls.
Return type:: Tuple[XControl, …]

static get_dialog_nm_con(ctrl)[source]

Gets Name container from control.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: ctrl (XControl) – Dialog control.
Returns:: Name Container.
Return type:: XNameContainer

static get_dialog_window(dialog_ctrl)[source]

Gets dialog window.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: dialog_ctrl (XControl) – dialog control.
Returns:: Top window instance.
Return type:: XTopWindow

static get_event_control(event)[source]

Gets event control from event.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: event (EventObject) – event.
Returns:: control.
Return type:: XControl

classmethod get_event_source_name(event)[source]

Get event source name.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: event (EventObject) – event.
Returns:: event source name.
Return type:: str

classmethod get_radio_group_value(dialog_ctrl, radio_button)[source]

Get a radio button group. Similar to find_radio_siblings() but also includes first radio button.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
radio_button (str) – Name of the first radio button of the group.

Returns:

Value of the selected radio button.

Return type:

Any

See also

find_radio_siblings().

classmethod insert_button(dialog_ctrl, *, label, x, y, width, height=20, btn_type=None, name='', **props)[source]

Insert Button Control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
label (str) – Button Label.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
btn_type (PushButtonType | None, optional) – Type of Button.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create button control.

Returns:

Button control.

Return type:

CtlButton

Hint

PushButtonType can be imported from ooo.dyn.awt.push_button_type.

See also

API UnoControlButtonModel Service

classmethod insert_check_box(dialog_ctrl, *, label, x, y, width, height=8, tri_state=True, state=TriStateKind.CHECKED, border=BorderKind.BORDER_3D, name='', **props)[source]

Inserts a check box control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
label (str) – Checkbox label text.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int,, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 8. If -1, the dialog Size is not set.
tri_state (TriStateKind, optional) – Specifies that the control may have the state “don’t know”. Defaults to True.
state (TriStateKind, optional) – Specifies the state of the control.Defaults to TriStateKind.CHECKED.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of Checkbox. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create checkbox control.

Returns:

Check box control.

Return type:

CtlCheckBox

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
TriStateKind can be imported from ooodev.utils.kind.tri_state_kind.

See also

API UnoControlCheckBoxModel Service

classmethod insert_combo_box(dialog_ctrl, *, entries, x, y, width, height=20, max_text_len=0, drop_down=True, read_only=False, border=BorderKind.BORDER_3D, name='', **props)[source]

Insert a combo box control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
entries (Iterable[str]) – Combo box entries.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
max_text_len (int, optional) – Specifies the maximum character count, There’s no limitation, if set to 0. Defaults to 0.
drop_down (bool, optional) – Specifies if the control has a drop down button. Defaults to True.
read_only (bool, optional) – Specifies that the content of the control cannot be modified by the user. Defaults to False.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create combo box control.

Returns:

Combo box control.

Return type:

CtlComboBox

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

See also

API UnoControlComboBoxModel Service

classmethod insert_currency_field(dialog_ctrl, *, x, y, width, height=20, value=0.0, min_value=-1000000.0, max_value=1000000.0, spin_button=False, increment=1, accuracy=2, border=BorderKind.BORDER_3D, name='', **props)[source]

Inserts a currency control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
value (float, optional) – Control Value. Defaults to 0.0.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to -1000000.0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 1000000.0.
spin_button (bool, optional) – When True, a spin button is present. Defaults to False.
increment (int, optional) – The step when the spin button is pressed. Defaults to 1.
accuracy (int, optional) – Specifies the decimal accuracy. Default is 2 decimal digits.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create currency field box control.

Returns:

Currency field control.

Return type:

CtlCurrencyField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_date_field(dialog_ctrl, *, x, y, width, height=20, date_value=None, min_date=datetime.datetime(1900, 1, 1, 0, 0), max_date=datetime.datetime(2200, 12, 31, 0, 0), drop_down=True, date_format=DateFormatKind.SYSTEM_SHORT, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type DateField in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
date_value (datetime.datetime | None, optional) – Specifics control datetime. Defaults to None.
min_date (datetime.datetime, optional) – Specifics control min datetime. Defaults to datetime(1900, 1, 1, 0, 0, 0, 0).
max_date (datetime.datetime, optional) – Specifics control Min datetime. Defaults to datetime(2200, 12, 31, 0, 0, 0, 0).
drop_down (bool, optional) – Specifies if the control is a dropdown. Defaults to True.
date_format (DateFormatKind, optional) – Date format. Defaults to DateFormatKind.SYSTEM_SHORT.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create date field control.

Returns:

Date field control.

Return type:

CtlDateField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
DateFormatKind can be imported from ooodev.utils.kind.date_format_kind.

classmethod insert_file_control(dialog_ctrl, *, x, y, width, height=20, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type FileControl in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create file control.

Returns:

File Control.

Return type:

CtlFile

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_fixed_line(dialog_ctrl, *, x, y, width, height=1, orientation=OrientationKind.HORIZONTAL, name='', **props)[source]

Create a new control of type Fixed Line in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 1. If -1, the dialog Size is not set.
orientation (OrientationKind, optional) – Orientation. Defaults to OrientationKind.HORIZONTAL.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create fixed line control.

Returns:

Fixed Line Control.

Return type:

CtlFixedLine

Hint

OrientationKind can be imported from ooodev.utils.kind.orientation_kind.

classmethod insert_formatted_field(dialog_ctrl, *, x, y, width, height=20, value=None, min_value=-1000000.0, max_value=1000000.0, spin_button=False, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type FormattedField in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
value (float, optional) – Control Value. Defaults to 0.0.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to -1000000.0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 1000000.0.
spin_button (bool, optional) – When True, a spin button is present. Defaults to False.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create formatted field control.

Returns:

Formatted Field.

Return type:

CtlFormattedField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_group_box(dialog_ctrl, *, x, y, width, height, label='', name='', **props)[source]

Create a new control of type GroupBox in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
label (str, optional) – Group box label.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create group box control.

Returns:

Group box Control.

Return type:

CtlGroupBox

classmethod insert_hyperlink(dialog_ctrl, *, label, url, x, y, width, height=20, align=AlignKind.LEFT, vert_align=VerticalAlignment.TOP, multiline=False, border=BorderKind.NONE, name='', **props)[source]

Create a new control of type Hyperlink in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
label (str) – Hyperlink label.
url (str) – Hyperlink URL.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
align (AlignKind, optional) – Horizontal alignment. Defaults to AlignKind.LEFT.
vert_align (VerticalAlignment, optional) – Vertical alignment. Defaults to VerticalAlignment.TOP.
multiline (bool, optional) – Specifies if the control can display multiple lines of text. Defaults to False.
border (BorderKind, optional) – Border option. Defaults to BorderKind.NONE.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create Hyperlink control.

Returns:

Hyperlink Control.

Return type:

CtlHyperlinkFixed

Hint

AlignKind can be imported from ooodev.utils.kind.align_kind.
BorderKind can be imported from ooodev.utils.kind.border_kind.
VerticalAlignment can be imported from ooo.dyn.style.vertical_alignment.

classmethod insert_image_control(dialog_ctrl, *, x, y, width, height=20, border=BorderKind.BORDER_3D, scale=ImageScaleModeEnum.NONE, image_url='', name='', **props)[source]

Create a new control of type ImageControl in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, , UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
image_url (PathOrStr, optional) – Image URL. When setting the value it can be a string or a Path object. If a string is passed it can be a URL or a path to a file. Value such as file:///path/to/image.png and /path/to/image.png are valid. Relative paths are supported.
scale (int | ImageScaleModeEnum, optional) – Image scale mode. Defaults to ImageScaleModeEnum.NONE.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create image control.

Returns:

Image Control.

Return type:

CtlImage

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
ImageScaleModeEnum can be imported from ooo.dyn.awt.image_scale_mode.
VerticalAlignment can be imported from ooo.dyn.style.vertical_alignment.

classmethod insert_label(dialog_ctrl, *, label, x, y, width, height=20, name='', **props)[source]

Insert a Fixed Text into a control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
label (str) – Contents of label.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Default 20. If -1, the dialog Size is not set.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create Fixed Text.

Returns:

Fixed Text Control.

Return type:

CtlFixedText

See also

API UnoControlFixedTextModel Service

classmethod insert_list_box(dialog_ctrl, *, entries, x, y, width, height=100, drop_down=False, read_only=False, line_count=5, multi_select=False, border=BorderKind.BORDER_3D, name='', **props)[source]

Insert a list box control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
entries (Iterable[str]) – List box entries.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 100. If -1, the dialog Size is not set.
drop_down (bool, optional) – Specifies if the control has a drop down button. Defaults to False.
read_only (bool, optional) – Specifies that the content of the control cannot be modified by the user. Defaults to False.
line_count (int, optional) – Specifies the number of lines to display. Defaults to 5.
multi_select (int, optional) – Specifies if multiple entries can be selected. Defaults to False.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create list box control.

Returns:

List box control.

Return type:

CtlListBox

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_numeric_field(dialog_ctrl, *, x, y, width, height=20, value=None, min_value=-1000000.0, max_value=1000000.0, spin_button=False, increment=1, accuracy=2, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type NumericField in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Default 20. If -1, the dialog Size is not set.
value (float, optional) – Control Value. Defaults to 0.0.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to -1000000.0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 1000000.0.
spin_button (bool, optional) – When True, a spin button is present. Defaults to False.
increment (int, optional) – The step when the spin button is pressed. Defaults to 1.
accuracy (int, optional) – Specifies the decimal accuracy. Default is 2 decimal digits
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create numeric field control.

Returns:

Numeric Field Control.

Return type:

CtlNumericField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_password_field(dialog_ctrl, *, text, x, y, width, height=20, border=BorderKind.NONE, name='', **props)[source]

Inserts a password field.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
text (str) – Text value.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
border (BorderKind, optional) – Border option. Defaults to BorderKind.NONE.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create text field.

Returns:

Text Field Control.

Return type:

CtlTextEdit

See also

insert_text_field().

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_pattern_field(dialog_ctrl, *, x, y, width, height=20, edit_mask='', literal_mask='', border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type PatternField in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Default``20``. If -1, the dialog Size is not set.
edit_mask (str, optional) – Specifies a character code that determines what the user may enter. Defaults to "".
literal_mask (str, optional) – Specifies the initial values that are displayed in the pattern field. Defaults to "".
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create pattern field control.

Returns:

Pattern Field Control.

Return type:

CtlPatternField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_progress_bar(dialog_ctrl, *, x, y, width, height, min_value=0, max_value=100, value=0, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type Progress Control in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to 0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 100.
value (int, optional) – The value initial value of the progress bar. Defaults to 0.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create numeric field control.

Returns:

Progress Bar Control.

Return type:

CtlProgressBar

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

classmethod insert_radio_button(dialog_ctrl, *, label, x, y, width, height=20, multiline=False, name='', **props)[source]

Create a new control of type RadioButton in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
label (str) – Contents of label.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Default 20. If -1, the dialog Size is not set.
multiline (bool, optional) – Specifies if the control can display multiple lines of text. Defaults to False.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create radio button.

Returns:

Radio button control.

Return type:

CtlRadioButton

classmethod insert_scroll_bar(dialog_ctrl, *, x, y, width, height, min_value=0, max_value=100, orientation=OrientationKind.HORIZONTAL, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type ScrollBar in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to 0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 100.
orientation (OrientationKind, optional) – Orientation. Defaults to OrientationKind.HORIZONTAL.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create scroll bar control.

Returns:

Scroll Bar Control.

Return type:

CtlScrollBar

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
OrientationKind can be imported from ooodev.utils.kind.orientation_kind.

classmethod insert_spin_button(dialog_ctrl, *, x, y, width, height, min_value=0, max_value=100, orientation=OrientationKind.HORIZONTAL, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type Spin Button in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
min_value (float, optional) – Specifies the smallest value that can be entered in the control. Defaults to 0.
max_value (float, optional) – Specifies the largest value that can be entered in the control. Defaults to 100.
orientation (OrientationKind, optional) – Orientation. Defaults to OrientationKind.HORIZONTAL.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create spin button control.

Returns:

Spin Button Control.

Return type:

CtlSpinButton

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
OrientationKind can be imported from ooodev.utils.kind.orientation_kind.

New in version 0.29.0.

classmethod insert_tab_control(dialog_ctrl, *, x, y, width, height=1, border=BorderKind.NONE, name='')[source]

Create a new control of type tab in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 1. If -1, the dialog Size is not set.
border (BorderKind, optional) – Border option. Defaults to BorderKind.NONE.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.

Raises:

DialogError – If unable to create tab control.

Returns:

Tab Control.

Return type:

CtlTabPageContainer

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

See also

insert_tab_page().

classmethod insert_tab_page(dialog_ctrl, *, tab_ctrl, title, tab_position, name='', **props)[source]

Create a new control of type Tab Page in the actual tab control.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
tab_ctrl (CtlTabPageContainer) – Tab Container.
title (str) – Tab title.
tab_position (int) – Tab position.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create tab page control.

Returns:

Tab Page Control.

Return type:

CtlTabPage

See also

insert_tab_control().

classmethod insert_table_control(dialog_ctrl, *, x, y, width, height, row_header=True, col_header=True, grid_lines=False, scroll_bars=HorzVertKind.NONE, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type TableControl in the actual dialog.

To add data to the table use set_table_data().

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
row_header (bool, optional) – Specifies if the control has a row header. Defaults to True.
col_header (bool, optional) – Specifies if the control has a column header. Defaults to True.
grid_lines (bool, optional) – Specifies if the control has grid lines. when True horizontal and vertical lines are painted between the grid cells. Defaults to False.
scroll_bars (HorzVertKind, optional) – Specifies if the control has scroll bars. Scrollbars always appear dynamically when they are needed. Defaults to HorzVertKind.NONE.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create table control.

Returns:

Table Control.

Return type:

CtlGrid

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
HorzVertKind can be imported from ooodev.utils.kind.horz_ver_kind.

See also

set_table_data().

classmethod insert_text_field(dialog_ctrl, *, x, y, width, height=20, text='', echo_char='', border=BorderKind.NONE, name='', **props)[source]

Inserts a text Field.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
text (str, optional) – Text value.
echo_char (str, optional) – Character used for masking. Must be a single character.
border (BorderKind, optional) – Border option. Defaults to BorderKind.NONE.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create text field.

Returns:

Text Field Control.

Return type:

CtlTextEdit

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

See also

API UnoControlEditModel Service

classmethod insert_time_field(dialog_ctrl, *, x, y, width, height=20, time_value=None, min_time=datetime.time(0, 0), max_time=datetime.time(23, 59, 59, 999999), time_format=TimeFormatKind.SHORT_24H, spin_button=True, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type TimeField in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – Control.
x (int, UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int, UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int, UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int, UnitT, optional) – Height in Pixels or UnitT. Defaults to 20. If -1, the dialog Size is not set.
time_value (datetime.time | None, optional) – Specifics the control time. Defaults to None.
min_time (datetime.time, optional) – Specifics control min time. Defaults to time(0, 0, 0, 0).
max_time (datetime.time, optional) – Specifics control min time. Defaults to a time(23, 59, 59, 999_999).
time_format (TimeFormatKind, optional) – Date format. Defaults to TimeFormatKind.SHORT_24H.
spin_button (bool, optional) – When True, a spin button is present. Defaults to True.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create time field control.

Returns:

Time field control.

Return type:

CtlTimeField

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.
TimeFormatKind can be imported from ooodev.utils.kind.time_format_kind.

classmethod insert_tree_control(dialog_ctrl, *, x, y, width, height, border=BorderKind.BORDER_3D, name='', **props)[source]

Create a new control of type Tree in the actual dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

dialog_ctrl (XControl) – control.
x (int , UnitT) – X coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
y (int , UnitT) – Y coordinate in Pixels or UnitT. If -1, the dialog Position is not set.
width (int , UnitT) – Width in Pixels or UnitT. If -1, the dialog Size is not set.
height (int , UnitT) – Height in Pixels or UnitT. If -1, the dialog Size is not set.
border (BorderKind, optional) – Border option. Defaults to BorderKind.BORDER_3D.
name (str, optional) – Name of button. Must be a unique name. If empty, a unique name is generated.
props (dict, optional) – Extra properties to set for control.

Raises:

DialogError – If unable to create Tree control.

Returns:

Tree Control.

Return type:

CtlTree

Hint

BorderKind can be imported from ooodev.utils.kind.border_kind.

static load_addon_dialog(extension_id, dialog_fnm)[source]

Loads addon dialog.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

extension_id (str) – Addon id.
dialog_fnm (str) – Addon file path.

Raises:

Exception – if unable to create dialog.

Returns:

Dialog instance

Return type:

XDialog

static load_dialog(script_name)[source]

Create a dialog for the given script name.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:: script_name (str) – script name.
Raises:: Exception – if unable to create dialog.
Returns:: Dialog instance.
Return type:: XDialog

classmethod show_control_info(dialog_ctrl)[source]

Prints info for a control to console.

Method is Lo Instance Safe for use with multiple documents.

Parameters:: dialog_ctrl (XControl) – Control
Return type:: None