Class CtlButton

Introduction

Class for working with button controls in a dialog.

EventArgsCallbackT

All EventArgsCallbackT callbacks include control_src as a keyword argument.

A callback can be in the format of:

def on_some_event(
    src: Any, event: EventArgs, control_src: CtlButton, *args, **kwargs
) -> None:
    pass

or

def on_some_event(src: Any, event: EventArgs, *args, **kwargs) -> None:
    # can get control from kwargs
    ctl = cast(CtlButton, kwargs['control_src'])

Example

For an example see Tab and List Box Dialog Example

Class

class ooodev.dialog.dl_control.CtlButton(ctl)[source]

Bases: DialogControlBase, UnoControlButtonModelPartial, ActionEvents

Class for Button Control

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Any

__init__(ctl)[source]

Constructor

Parameters:: ctl (UnoControlButton) – Button Control
Return type:: None

add_event_action_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_action_performed(cb)

Adds a listener for an event.

Event is invoked when an action is performed.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.ActionEvent struct.

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

add_event_focus_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_focus_gained(cb)

Adds a listener for an event.

Event is invoked when a window gains the keyboard focus.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.FocusEvent struct.

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

add_event_focus_lost(cb)

Adds a listener for an event.

Event is invoked when a window loses the keyboard focus.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.FocusEvent struct.

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

add_event_key_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_key_pressed(cb)

Adds a listener for an event.

Event is invoked when a key has been pressed.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.KeyEvent struct.

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

add_event_key_released(cb)

Adds a listener for an event.

Event is invoked when a key has been released.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.KeyEvent struct.

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

add_event_listener(listener)

Adds an event listener to the component.

Parameters:: listener (XEventListener) – The event listener to be added.
Return type:: None

add_event_mouse_dragged(cb)

Adds a listener for an event.

Event is invoked when a mouse button is pressed on a window and then dragged.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent struct.

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

add_event_mouse_entered(cb)

Adds a listener for an event.

Event is invoked when the mouse enters a window.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent struct.

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

add_event_mouse_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_mouse_exited(cb)

Adds a listener for an event.

Event is invoked when the mouse exits a window.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent struct.

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

add_event_mouse_motion_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_mouse_moved(cb)

Adds a listener for an event.

Event Is invoked when the mouse pointer has been moved on a window (with no buttons down).

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent struct.

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

add_event_mouse_pressed(cb)

Adds a listener for an event.

Event is invoked when a mouse button has been pressed on a window.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent struct.

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

add_event_mouse_released(cb)

Adds a listener for an event.

Event is invoked when a mouse button has been released on a window.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.MouseEvent 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_paint_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_properties_change(names, cb)

Add properties to listen for changes.

Parameters:

names (Iterable[str]) – One or more property names to listen for changes.
cb (EventArgsCallbackT) – Callback that is invoked when an event is triggered.

Raises:

ValueError – If names is empty.

Return type:

None

Note

The callback EventArgs.event_data will contain a tuple of com.sun.star.beans.PropertyChangeEvent objects.

Each time this method is called, the previous names are removed and the new names are added.

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

add_event_window_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_window_hidden(cb)

Adds a listener for an event.

Event is invoked when the window has been hidden.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.WindowEvent struct.

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

add_event_window_moved(cb)

Adds a listener for an event.

Event is invoked when the window has been moved.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.WindowEvent struct.

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

add_event_window_paint(cb)

Adds a listener for an event.

Event Is invoked when a region of the window became invalid, e.g. when another window has been moved away.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.PaintEvent struct.

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

add_event_window_resized(cb)

Adds a listener for an event.

Event is invoked when the window has been resized.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.WindowEvent struct.

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

add_event_window_shown(cb)

Adds a listener for an event.

Event is invoked when the window has been shown.

The callback EventArgs.event_data will contain a UNO com.sun.star.awt.WindowEvent struct.

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

add_property_change_listener(name, listener)

Adds a listener for property changes.

Parameters:

name (str) – The name of the property.
listener (Any) – The listener to be added.

Return type:

None

add_vetoable_change_listener(name, listener)

Adds a listener for vetoable changes.

Parameters:

name (str) – The name of the property.
listener (Any) – The listener to be added.

Return type:

None

apply_styles(*styles)

Applies styles to control

Parameters:: *styles (StyleT) – Styles to apply
Return type:: None

create_clone()

Creates a clone of the object.

Returns:: The clone.
Return type:: XCloneable

dispose()

Disposes the component.

Return type:: None

fire_event_properties_change(names)

Fires a sequence of PropertyChangeEvents

Parameters:: names (Iterable[str]) – Sequence of property names to fire event for.
Return type:: None

get_control_kind()

Gets the control kind

Return type:: DialogControlKind

get_control_named_kind()

Gets the control named kind

Return type:: DialogControlNamedKind

get_control_props()

Gets property set for a control model

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

get_model()[source]

Gets the Model for the control

Return type:: UnoControlButtonModel

get_property_set()

Gets the property set for this control

Return type:: XPropertySet

get_property_set_info()

Returns the property set info.

Returns:: The property set info.
Return type:: XPropertySetInfo

get_property_value(name)

Returns the value of a property.

Parameters:: name (str) – The name of the property.
Returns:: The value of the property.
Return type:: Any

get_uno_srv_name()[source]

Returns com.sun.star.awt.UnoControlButton

Return type:: str

get_view()

Return type:: XControl

get_view_ctl()[source]

Return type:: UnoControlButton

remove_event_action_events_disposing(cb)

Removes a listener for an event

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

remove_event_action_performed(cb)

Removes a listener for an event

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

remove_event_focus_events_disposing(cb)

Removes a listener for an event

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

remove_event_focus_gained(cb)

Removes a listener for an event

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

remove_event_focus_lost(cb)

Removes a listener for an event

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

remove_event_key_events_disposing(cb)

Removes a listener for an event

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

remove_event_key_pressed(cb)

Removes a listener for an event

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

remove_event_key_released(cb)

Removes a listener for an event

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

remove_event_listener(listener)

Removes an event listener from the component.

Parameters:: listener (XEventListener) – The event listener to be removed.
Return type:: None

remove_event_mouse_dragged(cb)

Removes a listener for an event

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

remove_event_mouse_entered(cb)

Removes a listener for an event

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

remove_event_mouse_events_disposing(cb)

Removes a listener for an event

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

remove_event_mouse_exited(cb)

Removes a listener for an event.

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

remove_event_mouse_motion_events_disposing(cb)

Removes a listener for an event

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

remove_event_mouse_moved(cb)

Removes a listener for an event.

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

remove_event_mouse_pressed(cb)

Removes a listener for an event.

Event is invoked when a mouse button has been pressed on a window.

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

remove_event_mouse_released(cb)

Removes a listener for an event.

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

remove_event_observer(observer)

Removes an observer

Parameters:: observer (EventObserver) – One or more observers to add.
Returns:: True if observer has been removed; Otherwise, False.
Return type:: bool

remove_event_paint_events_disposing(cb)

Removes a listener for an event

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

remove_event_properties_listener()

Remove Properties Listener

Return type:: None

remove_event_property_change(name)

Removes a listener for an event

Parameters:: name (str) – Property Name
Return type:: None

remove_event_property_change_events_disposing(name)

Removes a listener for an event

Parameters:: name (str) – Property Name
Return type:: None

remove_event_vetoable_change(name)

Removes a listener for an event

Parameters:: name (str) – Property Name
Return type:: None

remove_event_vetoable_change_events_disposing(name)

Removes a listener for an event

Parameters:: name (str) – Property Name
Return type:: None

remove_event_window_events_disposing(cb)

Removes a listener for an event.

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

remove_event_window_hidden(cb)

Removes a listener for an event.

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

remove_event_window_moved(cb)

Removes a listener for an event.

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

remove_event_window_paint(cb)

Removes a listener for an event

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

remove_event_window_resized(cb)

Removes a listener for an event.

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

remove_event_window_shown(cb)

Removes a listener for an event.

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

remove_property_change_listener(name, listener)

Removes a listener for property changes.

Parameters:

name (str) – The name of the property.
listener (Any) – The listener to be removed.

Return type:

None

remove_vetoable_change_listener(name, listener)

Removes a listener for vetoable changes.

Parameters:

name (str) – The name of the property.
listener (Any) – The listener to be removed.

Return type:

None

set_font_descriptor(font_descriptor)

Sets the font descriptor of the control.

Parameters:: font_descriptor (FontDescriptor, FontDescriptorStructComp) – UNO Struct - Font descriptor to set.
Return type:: None

Note

The font_descriptor property can also be used to set the font descriptor.

Hint

FontDescriptor can be imported from ooo.dyn.awt.font_descriptor.

Return type:: None
Parameters:: font_descriptor (FontDescriptor | FontDescriptorStructComp) –

set_property_value(name, value)

Sets the value of a property.

Parameters:

name (str) – The name of the property.
value (Any) – The value of the property.

Return type:

None

subscribe_event(event_name, callback)

Add an event listener to current instance.

Parameters:

event_name (str) – Event Name.
callback (EventCallback) – Callback of the event listener.

Return type:

None

trigger_event(event_name, event_args)

Trigger an event on current instance.

Parameters:

event_name (str) – Event Name.
event_args (EventArgsT) – Event Args.

Return type:

None

unsubscribe_event(event_name, callback)

Remove an event listener from current instance.

Parameters:

event_name (str) – Event Name.
callback (EventCallback) – Callback of the event listener.

Return type:

None

property align: AlignKind | None

Get/Sets the horizontal alignment of the text in the control.

optional

Hint

AlignKind can be imported from ooodev.utils.kind.align_kind.

Return type:: AlignKind | None

property background_color: Color

Gets/Set the background color of the control.

Returns:: Color
Return type:: Color

property default_button: bool

Gets/Sets that the button is the default button on the document.

Return type:: bool

property enabled: bool

Gets/Sets whether the control is enabled or disabled.

Return type:: bool

property event_observer: EventObserver

Gets/Sets The Event Observer for this instance.

Return type:: EventObserver

property events_listener_action: ActionListener

Returns listener

Return type:: ActionListener

property events_listener_focus: FocusListener

Returns listener

Return type:: FocusListener

property events_listener_key: KeyListener

Returns listener

Return type:: KeyListener

property events_listener_mouse: MouseListener

Returns listener

Return type:: MouseListener

property events_listener_mouse_motion: MouseMotionListener

Returns listener

Return type:: MouseMotionListener

property events_listener_paint: PaintListener

Returns listener

Return type:: PaintListener

property events_listener_properties_change_implement: PropertiesChangeListener

Returns listener

Return type:: PropertiesChangeListener

property events_listener_window: WindowListener

Returns listener

Return type:: WindowListener

property focus_on_click: bool

Gets/Sets whether the button control should grab the focus when clicked.

If set to True (which is the default), the button control automatically grabs the focus when the user clicks onto it with the mouse. If set to False, the focus is preserved when the user operates the button control with the mouse.

Return type:: bool

property font_descriptor: FontDescriptorStructComp

Gets/Sets the Font Descriptor.

Setting value can be done with a FontDescriptor or FontDescriptorStructComp object.

Returns:: Font Descriptor
Return type:: FontDescriptorStructComp

Hint

FontDescriptor can be imported from ooo.dyn.awt.font_descriptor.

property font_emphasis_mark: FontEmphasisEnum

Gets/Sets the FontEmphasis value of the text in the control.

Note

Value can be set with FontEmphasisEnum or int.

Hint

FontEmphasisEnum can be imported from ooo.dyn.text.font_emphasis.

Return type:: FontEmphasisEnum

property font_relief: FontReliefEnum

Gets/Sets FontRelief value of the text in the control.

Note

Value can be set with FontReliefEnum or int.

Hint

FontReliefEnum can be imported from ooo.dyn.text.font_relief.

Return type:: FontReliefEnum

property graphic: com.sun.star.graphic.XGraphic

specifies a graphic to be displayed at the button

If this property is present, it interacts with the image_url in the following way:

If image_url is set, graphic will be reset to an object as loaded from the given image URL, or None if image_url does not point to a valid image file.
If graphic is set, image_url will be reset to an empty string.

Return type:: XGraphic

property height: UnitPX

Gets/Sets the height of the control in Pixel units.

When setting can be an integer in Pixels Units or a UnitT.

Returns:: Height of the control.
Return type:: UnitPX

Note

The Height is in Pixel units; however, the model is in AppFont units. This property will convert the AppFont units to Pixel units. When set using UnitAppFontHeight no conversion is done.

property help_text: str

Gets/Sets the tip text

Return type:: str

property help_url: str

Gets/Sets the help URL of the control.

Return type:: str

property image_align: ImageAlignEnum

Gets/Sets the alignment of the image inside the button as image_align value.

Note

Value can be set with ImageAlignEnum or int.

Hint

ImageAlignEnum can be imported from ooo.dyn.awt.image_align

Return type:: ImageAlignEnum

property image_position: ImagePositionEnum | None

Gets/Sets the position of the image, if any, relative to the text, if any

Valid values of this property are specified with image_position.

If this property is present, it supersedes the ImageAlign property - setting one of both properties sets the other one to the best possible match.

optional

Note

Value can be set with ImagePositionEnum or int.

Hint

ImagePositionEnum can be imported from ooo.dyn.awt.image_position

Return type:: ImagePositionEnum | None

property image_url: str

Gets/Sets a URL to an image to use for the button.

Return type:: str

property label: str

Gets/Sets the label of the control.

Return type:: str

property lo_inst: LoInst

Lo Instance

Return type:: LoInst

property model: com.sun.star.awt.UnoControlModel

Uno Control Model

Return type:: UnoControlModel

property model_ex: ModelButton

Gets the extended Model for the control.

This is a wrapped instance for the model property. It add some additional properties and methods to the model.

Return type:: ModelButton

property multi_line: bool | None

Gets/Sets that the text may be displayed on more than one line.

optional

Return type:: bool | None

property name: str

Gets/Sets the name of the control.

Return type:: str

property picture: str

Gets/Sets the picture for the control

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.

Returns:: The picture URL in the format of file:///path/to/image.png or empty string if no picture is set.
Return type:: str

property printable: bool

Gets/Sets that the control will be printed with the document.

Return type:: bool

property push_button_type: PushButtonType

Gets/Sets the default action of the button as push_button_type value.

Note

Value can be set with PushButtonType or int.

Hint

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

Return type:: PushButtonType

property repeat: bool | None

Gets/Sets whether the mouse should show repeating behavior, i.e. repeatedly trigger an action when keeping pressed.

optional

Return type:: bool | None

property repeat_delay: int | None

Gets/Sets the mouse repeat delay, in milliseconds.

When the user presses a mouse in a control area where this triggers an action (such as spinning the value), then usual control implementations allow to repeatedly trigger this action, without the need to release the mouse button and to press it again. The delay between two such triggers is specified with this property.

optional

Return type:: int | None

property state: ButtonStateKind

Gets/Sets the state of the control.

If Toggle property is set to True, the pressed state is enabled and its pressed state can be obtained with this property.

Note

Value can be set with ButtonStateKind or int.

Hint

ButtonStateKind can be imported from ooodev.utils.kind.button_state_kind.

Return type:: ButtonStateKind

property step: int

Gets/Sets the step

Return type:: int

property tab_index: int

Gets/Sets the tab index

Return type:: int

property tabstop: bool

Gets/Sets that the control can be reached with the TAB key.

Return type:: bool

property tag: str

Gets/Sets the tag

Return type:: str

property text_color: Color

Gets/Sets the text color of the control.

Returns:: Color
Return type:: Color

property text_line_color: Color

Gets/Sets the text line color of the control.

Returns:: Color
Return type:: Color

property tip_text: str

Gets/Sets the tip text

Return type:: str

property toggle: bool | None

Gets/Sets whether the button should toggle on a single operation.

If this property is set to True, a single operation of the button control (pressing space while it is focused, or clicking onto it) toggles it between a pressed and a not pressed state.

The default for this property is False, which means the button behaves like a usual push button.

optional

Return type:: bool | None

property vertical_align: VerticalAlignment | None

Gets/Sets the vertical alignment of the text in the control.

optional

Hint

VerticalAlignment can be imported from ooo.dyn.style.vertical_alignment

Return type:: VerticalAlignment | None

property view: com.sun.star.awt.UnoControlButton

Uno Control

Return type:: UnoControlButton

property view_ex: ViewButton

Gets the extended View for the control.

This is a wrapped instance for the view property. It add some additional properties and methods to the view.

Return type:: ViewButton

property visible: bool

Gets/Sets the visible state for the control

Return type:: bool

property width: UnitPX

Gets the width of the control

Return type:: UnitPX

property x: UnitPX

Gets/Sets the X position for the control in pixel units.

When setting can be an integer in Pixels Units or a UnitT.

Returns:: X position of the control.
Return type:: UnitPX

Note

The X is in Pixel units; however, the model is in AppFont units. This property will convert the AppFont units to Pixel units. When set using UnitAppFontX no conversion is done.

property y: UnitPX

Gets/Sets the Y position for the control in pixel units.

When setting can be an integer in Pixels Units or a UnitT.

Returns:: Y position of the control.
Return type:: UnitPX

Note

The Y is in Pixel units; however, the model is in AppFont units. This property will convert the AppFont units to Pixel units. When set using UnitAppFontY no conversion is done.