AOO410/main/offapi/com/sun/star/frame/XFrame.idl - openoffice - Git at Google

 /**************************************************************
  *
  * 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
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  * KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  *
  *************************************************************/


 #ifndef __com_sun_star_frame_XFrame_idl__
 #define __com_sun_star_frame_XFrame_idl__

 #ifndef __com_sun_star_lang_XComponent_idl__
 #include <com/sun/star/lang/XComponent.idl>
 #endif

 #ifndef __com_sun_star_awt_XWindow_idl__
 #include <com/sun/star/awt/XWindow.idl>
 #endif

 //=============================================================================

  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 willn't be
     accessible by using the api. This mode make sense for previews.
     The root node of the tree can be a <type>Desktop</type> 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 refered 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; normaly a frame should be created by using the api
         and is neccessary for searches inside the tree (e.g. <member>XFrame::findFrame()</member>)
         </p>

         @param Creator
             the creator (parent) of this frame

         @see XFrame::getCreator()
 	 */
     [oneway] 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><member>XFrame::findFrame()</member>
             <li><member>XDispatchProvider::queryDispatch()</member>
             <li><member>XComponentLoader::loadComponentFromURL()</member>
         </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
      */
     [oneway] 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 <const>FrameSearchFlag::CREATE</const>.
         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 <const>FrameSearchFlag::TASKS</const>
         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 <member>XFramesSupplier::setActiveFrame()</member>,
 		then it broadcasts an <type>FrameActionEvent</type> with
 		<const>FrameAction::FRAME_ACTIVATED</const>. 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 <type>FrameLoader</type>.
         </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()
     */
 	[oneway] 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 <type>FrameActionEvent</type> with
         <const>FrameAction::FRAME_DEACTIVATING</const>.
         </p>

         @see XFrame::activate()
         @see XFrame::isActive()
 	 */
 	[oneway] 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 <type scope="com::sun::star::awt">XWindow</type> 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 (especialy, if an existing controller disagree within his
             <member>XController::suspend()</member> 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 <member>XController::getFrame()</member> to dispose
         the frame after you the controller agreed with a
         <member>XController::suspend()</member> 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
         <method>XFrameEventListener::frameAction</method> with
 		<const>FrameAction::CONTEXT_CHANGED</const> to all listeners which
         are registered using <member>XFrame::addFrameActionListener</member>.
 		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()
 	 */
     [oneway] void addFrameActionListener( [in]XFrameActionListener xListener );

 	//-------------------------------------------------------------------------
     /** unregisters an event listener

         @param xListener
             specifies the listener which willn't be informed any longer

         @see XFrame::addFrameActionListener()
 	 */
     [oneway] void removeFrameActionListener( [in] XFrameActionListener xListener );
 };

 //=============================================================================

 }; }; }; };

 #endif
	/**************************************************************
	*
	* 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
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*
	*************************************************************/


	#ifndef __com_sun_star_frame_XFrame_idl__
	#define __com_sun_star_frame_XFrame_idl__

	#ifndef __com_sun_star_lang_XComponent_idl__
	#include <com/sun/star/lang/XComponent.idl>
	#endif

	#ifndef __com_sun_star_awt_XWindow_idl__
	#include <com/sun/star/awt/XWindow.idl>
	#endif

	//=============================================================================

	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 willn't be
	accessible by using the api. This mode make sense for previews.
	The root node of the tree can be a <type>Desktop</type> 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 refered 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; normaly a frame should be created by using the api
	and is neccessary for searches inside the tree (e.g. <member>XFrame::findFrame()</member>)
	</p>

	@param Creator
	the creator (parent) of this frame

	@see XFrame::getCreator()
	*/
	[oneway] 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><member>XFrame::findFrame()</member>
	<li><member>XDispatchProvider::queryDispatch()</member>
	<li><member>XComponentLoader::loadComponentFromURL()</member>
	</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
	*/
	[oneway] 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 <const>FrameSearchFlag::CREATE</const>.
	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 <const>FrameSearchFlag::TASKS</const>
	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 <member>XFramesSupplier::setActiveFrame()</member>,
	then it broadcasts an <type>FrameActionEvent</type> with
	<const>FrameAction::FRAME_ACTIVATED</const>. 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 <type>FrameLoader</type>.
	</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()
	*/
	[oneway] 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 <type>FrameActionEvent</type> with
	<const>FrameAction::FRAME_DEACTIVATING</const>.
	</p>

	@see XFrame::activate()
	@see XFrame::isActive()
	*/
	[oneway] 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 <type scope="com::sun::star::awt">XWindow</type> 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 (especialy, if an existing controller disagree within his
	<member>XController::suspend()</member> 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 <member>XController::getFrame()</member> to dispose
	the frame after you the controller agreed with a
	<member>XController::suspend()</member> 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
	<method>XFrameEventListener::frameAction</method> with
	<const>FrameAction::CONTEXT_CHANGED</const> to all listeners which
	are registered using <member>XFrame::addFrameActionListener</member>.
	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()
	*/
	[oneway] void addFrameActionListener( [in]XFrameActionListener xListener );

	//-------------------------------------------------------------------------
	/** unregisters an event listener

	@param xListener
	specifies the listener which willn't be informed any longer

	@see XFrame::addFrameActionListener()
	*/
	[oneway] void removeFrameActionListener( [in] XFrameActionListener xListener );
	};

	//=============================================================================

	}; }; }; };

	#endif