diff options
Diffstat (limited to '')
| -rw-r--r-- | offapi/com/sun/star/frame/XFrame.idl | 357 |
1 files changed, 357 insertions, 0 deletions
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 <com/sun/star/lang/XComponent.idl> +#include <com/sun/star/awt/XWindow.idl> + + + 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. + + <p> + 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. + </p> + + @see Desktop + */ +published interface XFrame: com::sun::star::lang::XComponent +{ + /** is called to initialize the frame within a window - the container window. + + <p> + 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. + </p> + + <p>This frame will take over ownership of the window referred from + <var>xWindow</var>. Thus, the previous owner is not allowed to + dispose this window anymore. </p> + + @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. + + <p> + Normally this is used as the parent window of the + component window. + </p> + + @return + the container window of this frame + + @see XFrame::initialize() + */ + com::sun::star::awt::XWindow getContainerWindow(); + + /** sets the frame container that created this frame. + + <p> + 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()) + </p> + + @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. + + <p> + 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: + <ul> + <li>XFrame::findFrame() + <li>XDispatchProvider::queryDispatch() + <li>XComponentLoader::loadComponentFromURL() + </ul> + Note: Special targets like "_blank", "_self" etc. are not allowed. + That's why frame names shouldn't start with a sign "_". + </p> + + @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. + + <p> + 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. <var>SearchFlags</var> is ignored when + comparing these names with <var>TargetFrameName</var>; further steps are + controlled by <var>SearchFlags</var>. 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). + </p> + + <p> + List of special target names: + <table border=1> + <tr><td>""/"_self"</td><td>address the starting frame itself</td></tr> + <tr><td>"_parent"</td><td>address the direct parent frame only</td></tr> + <tr><td>"_top"</td><td>address the top frame of this subtree of the frametree</td></tr> + <tr><td>"_blank"</td><td>creates a new top frame</td></tr> + </table> + </p> + + <p> + 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. + </p> + + @param aTargetFrameName + identify + <ul><li>(a) a special target ("_blank","_self" ...) or</li> + <li>(b) any well known frame</li></ul> + to search it inside the current hierarchy + + @param nSearchFlags + optional parameter to regulate search if no special target was used for <var>TargetFrameName</var> + + @see FrameSearchFlag + */ + XFrame findFrame( + [in] string aTargetFrameName, + [in] long nSearchFlags); + + /** determines if the frame is a top frame. + + <p> + 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. + </p> + + @return + `TRUE` if frame supports top frame specification + <br> + `FALSE` otherwise + */ + boolean isTop(); + + /** activates this frame and thus the component within. + + <p> + 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. + </p> + + <p> + Finally, most frames may grab the focus to one of its windows + or forward the activation to a sub-frame. + </p> + + @see XFrame::deactivate() + @see XFrame::isActive() + */ + void activate(); + + /** is called by the creator frame when another sub-frame gets activated. + + <p> + At first the frame deactivates its active sub-frame, if any. + Then broadcasts a FrameActionEvent with + FrameAction::FRAME_DEACTIVATING. + </p> + + @see XFrame::activate() + @see XFrame::isActive() + */ + void deactivate(); + + /** determines if the frame is active. + + @return + `TRUE` for active or UI active frames + <br> + `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 + + <p> + A valid component window should be a child of the frame container window. + </p> + + @param xController + the controller of the new component or `NULL` for release + + <p> + Simple components may implement a com::sun::star::awt::XWindow only. + In this case no controller must be given here. + </p> + + @return + `TRUE`if setting of new component or release of an existing one was successfully + <br> + `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 + + <p> + Note: Don't dispose this window - the frame is the owner of it. + </p> + + @returns + the current visible component in this frame + <br> + or `NULL` if no one currently exist + + @see XFrame::setComponent() + */ + com::sun::star::awt::XWindow getComponentWindow(); + + /** provides access to the controller + + <p> + 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. + </p> + + @returns + the current controller within this frame + <br> + 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). + + <p> + 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. + + <p> + E.g., it is possible to determine instantiation/destruction and + activation/deactivation of components. + </p> + + @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: */ |