From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- offapi/com/sun/star/frame/XFrame.idl | 357 +++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 offapi/com/sun/star/frame/XFrame.idl (limited to 'offapi/com/sun/star/frame/XFrame.idl') diff --git a/offapi/com/sun/star/frame/XFrame.idl b/offapi/com/sun/star/frame/XFrame.idl new file mode 100644 index 000000000..b2d7e41e4 --- /dev/null +++ b/offapi/com/sun/star/frame/XFrame.idl @@ -0,0 +1,357 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_frame_XFrame_idl__ +#define __com_sun_star_frame_XFrame_idl__ + +#include +#include + + + module com { module sun { module star { module frame { + + published interface XFrameActionListener; + published interface XController; + published interface XFramesSupplier; + +/** a frame object can be considered to be an "anchor" object where a component + can be attached to. + +

+ A frame can be (it's not a must!) a part of a frame tree. If not this frame won't be + accessible by using the API. This mode make sense for previews. + The root node of the tree can be a Desktop implementation. +

+ + @see Desktop + */ +published interface XFrame: com::sun::star::lang::XComponent +{ + /** 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.

+ + @param xWindow + the new container window + + @see XFrame::getContainerWindow() + */ + void initialize( [in] com::sun::star::awt::XWindow xWindow ); + + /** provides access to the container window of the frame. + +

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

+ + @return + the container window of this frame + + @see XFrame::initialize() + */ + com::sun::star::awt::XWindow getContainerWindow(); + + /** 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()) +

+ + @param Creator + the creator (parent) of this frame + + @see XFrame::getCreator() + */ + void setCreator( [in] XFramesSupplier Creator ); + + /** provides access to the creator (parent) of this frame + + @returns + the frame container that created and contains this frame. + + @see XFrame::setCreator() + */ + XFramesSupplier getCreator(); + + /** access to the name property of this frame + + @returns + the programmatic name of this frame. + + @see XFrame::setName() + */ + string getName(); + + /** 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: +

    +
  • XFrame::findFrame() +
  • XDispatchProvider::queryDispatch() +
  • XComponentLoader::loadComponentFromURL() +
+ Note: Special targets like "_blank", "_self" etc. are not allowed. + That's why frame names shouldn't start with a sign "_". +

+ + @param aName + the new programmatic name of this frame + + @see XFrame::findFrame() + @see XFrame::getName() + @see XDispatchProvider + @see XComponentLoader + */ + void setName( [in] string aName ); + + /** 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: + + + + + +
""/"_self"address the starting frame itself
"_parent"address the direct parent frame only
"_top"address the top frame of this subtree of the frametree
"_blank"creates a new top frame
+

+ +

+ 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. +

+ + @param aTargetFrameName + identify +
  • (a) a special target ("_blank","_self" ...) or
    • +
  • (b) any well known frame
+ to search it inside the current hierarchy + + @param nSearchFlags + optional parameter to regulate search if no special target was used for TargetFrameName + + @see FrameSearchFlag + */ + XFrame findFrame( + [in] string aTargetFrameName, + [in] long nSearchFlags); + + /** 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 + `TRUE` if frame supports top frame specification +
+ `FALSE` otherwise + */ + boolean isTop(); + + /** 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. +

+ + @see XFrame::deactivate() + @see XFrame::isActive() + */ + void activate(); + + /** 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. +

+ + @see XFrame::activate() + @see XFrame::isActive() + */ + void deactivate(); + + /** determines if the frame is active. + + @return + `TRUE` for active or UI active frames +
+ `FALSE` otherwise + + @see XFrame::activate() + @see XFrame::deactivate() + */ + boolean isActive(); + + /** sets a new component into the frame or release an existing one from a frame. + + @param xComponentWindow + the window of the new component or `NULL` for release + +

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

+ + @param xController + the controller of the new component or `NULL` for release + +

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

+ + @return + `TRUE`if setting of new component or release of an existing one was successfully +
+ `FALSE` otherwise (especially, if an existing controller disagree within his + XController::suspend() call) + + @see XFrame::getComponentWindow() + @see XFrame::getContainerWindow() + @see XFrame::getController() + */ + boolean setComponent( + [in] com::sun::star::awt::XWindow xComponentWindow, + [in] XController xController); + + /** provides access to the component window + +

+ Note: Don't dispose this window - the frame is the owner of it. +

+ + @returns + the current visible component in this frame +
+ or `NULL` if no one currently exist + + @see XFrame::setComponent() + */ + com::sun::star::awt::XWindow getComponentWindow(); + + /** 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. +

+ + @returns + the current controller within this frame +
+ or `NULL` if no one currently exist + + @see XFrame::setComponent() + */ + XController getController(); + + /** 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 requery dispatches. + + @see XFrameEventListener + @see FrameAction + @see XFrame::addFrameActionListener() + */ + void contextChanged(); + + /** 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. +

+ + @param xListener + specifies the listener which will be informed + + @see XFrame::removeFrameActionListener() + */ + void addFrameActionListener( [in]XFrameActionListener xListener ); + + /** unregisters an event listener + + @param xListener + specifies the listener which won't be informed any longer + + @see XFrame::addFrameActionListener() + */ + void removeFrameActionListener( [in] XFrameActionListener xListener ); +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ -- cgit v1.2.3