Class TheDesktop

class ooodev.loader.comp.the_desktop.TheDesktop(component)[source]

Bases: TheDesktopComp

Class for managing theDesktop singleton Class.

Parameters:

component (Any) –

__init__(component)[source]

Constructor

Parameters:

component (Any) – UNO Component that implements com.sun.star.frame.theDesktop service.

Return type:

None

activate()

activates this frame and thus the component within.

At first the frame sets itself as the active frame of its creator by calling XFramesSupplier.setActiveFrame(), then it broadcasts a FrameActionEvent with FrameAction.FRAME_ACTIVATED.

The component within this frame may listen to this event to grab the focus on activation; for simple components this can be done by the FrameLoader.

Finally, most frames may grab the focus to one of its windows or forward the activation to a sub-frame.

Return type:

None

add_event_frame_action(cb)

Adds a listener for an event.

Event is invoked when the master environment is finally terminated.

The callback EventArgs.event_data will contain a UNO com.sun.star.frame.FrameActionEvent struct.

Return type:

None

Parameters:

cb (Any) –

add_event_frame_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_listener(listener)

Adds an event listener to the component.

Parameters:

listener (XEventListener) – The event listener to be added.

Return type:

None

add_event_notify_termination(cb)

Adds a listener for an event.

Event is invoked when the master environment is finally terminated.

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

Return type:

None

Parameters:

cb (Any) –

add_event_query_termination(cb)

Adds a listener for an event.

Event is invoked when the master environment (e.g., desktop) is about to terminate.

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

Return type:

None

Parameters:

cb (Any) –

add_event_terminate_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_frame_action_listener(listener)

Registers an event listener, which will be called when certain things happen to the components within this frame or within sub-frames of this frame.

E.g., it is possible to determine instantiation/destruction and activation/deactivation of components.

Return type:

None

Parameters:

listener (com.sun.star.frame.XFrameActionListener) –

add_terminate_listener(listener)

Registers an event listener to the desktop, which is called when the desktop is queried to terminate, and when it really terminates.

Return type:

None

Parameters:

listener (com.sun.star.frame.XTerminateListener) –

context_changed()

Notifies the frame that the context of the controller within this frame changed (i.e. the selection).

According to a call to this interface, the frame calls XFrameActionListener.frameAction() with FrameAction.CONTEXT_CHANGED to all listeners which are registered using XFrame.addFrameActionListener(). For external controllers this event can be used to re-query dispatches.

Return type:

None

deactivate()

Is called by the creator frame when another sub-frame gets activated.

At first the frame deactivates its active sub-frame, if any. Then broadcasts a FrameActionEvent with FrameAction.FRAME_DEACTIVATING.

Return type:

None

dispose()

Disposes the component.

Return type:

None

find_frame(target_frame_name, search_flags)

searches for a frame with the specified name.

Frames may contain other frames (e.g., a frameset) and may be contained in other frames. This hierarchy is searched with this method. First some special names are taken into account, i.e. _self, _top, _blank etc. SearchFlags is ignored when comparing these names with TargetFrameName; further steps are controlled by SearchFlags. If allowed, the name of the frame itself is compared with the desired one, and then ( again if allowed ) the method is called for all children of the frame. Finally may be called for the siblings and then for parent frame (if allowed).

List of special target names:

If no frame with the given name is found, a new top frame is created; if this is allowed by a special flag FrameSearchFlag.CREATE. The new frame also gets the desired name.

See also

com.sun.star.frame.FrameSearchFlag

Return type:

XFrame

Parameters:

  • target_frame_name (str) –

  • search_flags (int) –

classmethod from_lo(lo_inst=None)

Get the singleton instance from the Lo.

Parameters:

lo_inst (LoInst, optional) – LoInst, Defaults to Lo.current_lo.

Returns:

The instance.

Return type:

TheDesktopComp

get_active_frame()

Gets the current active frame of this container (not of any other available supplier)

This may be the frame itself. The active frame is defined as the frame which contains (recursively) the window with the focus. If no window within the frame contains the focus, this method returns the last frame which had the focus. If no containing window ever had the focus, the first frame within this frame is returned.

Return type:

XFrame

get_component_window()

Provides access to the component window

Note

Don’t dispose this window - the frame is the owner of it.

Return type:

XWindow

get_components()

Provides read access to collection of all currently loaded components inside the frame tree

The component is, by definition, the model of the control which is loaded into a frame, or if no model exists, into the control itself. The service Components which is available from this method is a collection of all components of the desktop which are open within a frame of the desktop.

Return type:

XEnumerationAccess

get_container_window()

Provides access to the container window of the frame.

Normally this is used as the parent window of the component window.

Return type:

XWindow

get_controller()

Provides access to the controller

Note

Don’t dispose it - the frame is the owner of it. Use XController.getFrame() to dispose the frame after you the controller agreed with a XController.suspend() call.

Return type:

XController

get_creator()

Provides access to the creator (parent) of this frame.

Return type:

XFramesSupplier

get_current_component()

Provides read access to the component inside the tree which has the UI focus

Normally, the component is the model part of the active component. If no model exists it is the active controller (view) itself.

Return type:

XComponent

get_current_frame()

provides read access to the frame which contains the current component

Return type:

XFrame

get_frames()

Provides access to this container and to all other XFramesSupplier which are available from this node of frame tree.

Return type:

XFrames

get_name()

Get the name property of this frame.

Return type:

str

initialize(window)

Is called to initialize the frame within a window - the container window.

This window will be used as parent for the component window and to support some UI relevant features of the frame service. Note: Re-parenting mustn’t supported by a real frame implementation! It’s designed for initializing - not for setting.

This frame will take over ownership of the window referred from xWindow. Thus, the previous owner is not allowed to dispose this window anymore.

Return type:

None

Parameters:

window (com.sun.star.awt.XWindow) –

is_active()

determines if the frame is active.

Return type:

bool

is_top()

determines if the frame is a top frame.

In general a top frame is the frame which is a direct child of a task frame or which does not have a parent. Possible frame searches must stop the search at such a frame unless the flag FrameSearchFlag.TASKS is set.

Return type:

bool

load_component_from_url(url, target_frame_name, search_flags, args)

Loads a component specified by a URL into the specified new or existing frame.

To create new documents, use private:factory/scalc, private:factory/swriter, etc. Other special protocols (e.g. slot:, .uno) are not allowed and raise a com.sun.star.lang.IllegalArgumentException.

If a frame with the specified name already exists, it is used, otherwise it is created. There exist some special targets which never can be used as real frame names:

Flags are optional ones and will be used for non special target names only.

For example, ReadOnly with a boolean value specifies whether the document is opened read-only. FilterName specifies the component type to create and the filter to use, for example: Text - CSV. For more information see com.sun.star.document.MediaDescriptor.

This interface is a generic one and can be used to start further requests on loaded document or control the lifetime of it (means dispose() it after using). The real document service behind this interface can be one of follow three ones:

Parameters:

  • url (str) – Specifies the URL of the document to load.

  • target_frame_name (str) – Specifies the name of the frame to view the document in.

  • search_flags (int) – Use the values of FrameSearchFlag to specify how to find the specified TargetFrameName

  • args (Tuple[PropertyValue, ...]) – The arguments.

Raises:

  • com.sun.star.io.IOException – IOException

  • com.sun.star.lang.IllegalArgumentException – IllegalArgumentException

Returns:

The loaded component.

Return type:

XComponent

Note

target_frame_name specifies the name of the frame to view the document in.

  • _blank: Always creates a new frame.

  • _default: Special UI functionality/

  • _self: Always uses the same frame.

  • _parent: Address direct parent of frame

  • _top: Indicates top frame of current path in tree.

  • _beamer: Means special sub frame.

See also

query_dispatch(url, target_frame_name, search_flags=FrameSearchFlagEnum.AUTO)

Returns a dispatch object for the specified URL.

Parameters:

  • url (URL) – Specifies the feature which should be supported by returned dispatch object.

  • target_frame_name (str) – Specifies the frame which should be the target for this request.

  • search_flags (int, FrameSearchFlagEnum, optional) – Optional search parameter for finding the frame if no special TargetFrameName was used.

Returns:

the dispatch object which provides queried functionality or None if no dispatch object is available.

Return type:

XDispatch

query_dispatches(requests)

Returns a list of dispatch objects for the specified URLs.

Actually this method is redundant to query_dispatch() to avoid multiple remote calls.

Parameters:

requests (Tuple[DispatchDescriptor, ...]) – Tuple of dispatch requests

Returns:

multiple dispatch interfaces for the specified descriptors at once

Return type:

Tuple[XDispatch | None, …]

register_dispatch_provider_interceptor(interceptor)

Registers an XDispatchProviderInterceptor, which will become the first interceptor in the chain of registered interceptors.

Return type:

None

Parameters:

interceptor (com.sun.star.frame.XDispatchProviderInterceptor) –

release_dispatch_provider_interceptor(interceptor)

Removes an XDispatchProviderInterceptor which was previously registered

The order of removals is arbitrary. It is not necessary to remove the last registered interceptor first.

Return type:

None

Parameters:

interceptor (com.sun.star.frame.XDispatchProviderInterceptor) –

remove_event_frame_action(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_frame_action_events_disposing(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_notify_termination(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_query_termination(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_terminate_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_frame_action_listener(listener)

Un-registers an event listener

Return type:

None

Parameters:

listener (com.sun.star.frame.XFrameActionListener) –

remove_terminate_listener(listener)

Un-registers an event listener for termination events.

Return type:

None

Parameters:

listener (com.sun.star.frame.XTerminateListener) –

set_active_frame(frame)

Is called on activation of a direct sub-frame.

This method is only allowed to be called by a sub-frame according to XFrame.activate() or XFramesSupplier.setActiveFrame(). After this call XFramesSupplier.getActiveFrame() will return the frame specified by Frame.

In general this method first calls the method XFramesSupplier.setActiveFrame() at the creator frame with this as the current argument. Then it broadcasts the FrameActionEvent FrameAction.FRAME_ACTIVATED.

Note

Given parameter Frame must already exist inside the container (e.g., inserted by using XFrames.append())

Return type:

None

Parameters:

frame (XFrame) –

set_component(window, controller)

Sets a new component into the frame or release an existing one from a frame.

A valid component window should be a child of the frame container window.

Simple components may implement a com.sun.star.awt.XWindow only. In this case no controller must be given here.

Return type:

bool

Parameters:

  • window (com.sun.star.awt.XWindow) –

  • controller (com.sun.star.frame.XController) –

set_creator(creator)

sets the frame container that created this frame.

Only the creator is allowed to call this method. But creator doesn’t mean the implementation which creates this instance … it means the parent frame of the frame hierarchy. Because; normally a frame should be created by using the API and is necessary for searches inside the tree (e.g. XFrame.findFrame())

Return type:

None

Parameters:

creator (com.sun.star.frame.XFramesSupplier) –

set_name(name)

Sets the name of the frame.

Normally the name of the frame is set initially (e.g. by the creator). The name of a frame will be used for identifying it if a frame search was started. These searches can be forced by:

Note

Special targets like _blank, _self etc. are not allowed. That’s why frame names shouldn’t start with a sign _.

Return type:

None

Parameters:

name (str) –

terminate()

Tries to terminate the desktop.

First, every terminate listener is called by this XTerminateListener.queryTermination() method. Throwing of a TerminationVetoException can break the termination process and the listener how has done that will be the new controller of the desktop lifetime. Should try to terminate it by itself after his own processes will be finished. If nobody disagree with the termination request, every listener will be called by his XTerminateListener.notifyTermination() method.

Return type:

bool

property component: com.sun.star.frame.theDesktop

theDesktop Component

Return type:

theDesktop

property components: Components

Desktop Components

Return type:

Components

property events_listener_frame_action: FrameActionListener

Returns listener

Return type:

FrameActionListener

property events_listener_terminate: TerminateListener

Returns listener

Return type:

TerminateListener