146 lines
6.2 KiB
Text
146 lines
6.2 KiB
Text
/*************************************************************************
|
|
*
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* Copyright 2008 by Sun Microsystems, Inc.
|
|
*
|
|
* OpenOffice.org - a multi-platform office productivity suite
|
|
*
|
|
* $RCSfile: XComponent.idl,v $
|
|
* $Revision: 1.18 $
|
|
*
|
|
* This file is part of OpenOffice.org.
|
|
*
|
|
* OpenOffice.org is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU Lesser General Public License version 3
|
|
* only, as published by the Free Software Foundation.
|
|
*
|
|
* OpenOffice.org is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License version 3 for more details
|
|
* (a copy is included in the LICENSE file that accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public License
|
|
* version 3 along with OpenOffice.org. If not, see
|
|
* <http://www.openoffice.org/license.html>
|
|
* for a copy of the LGPLv3 License.
|
|
*
|
|
************************************************************************/
|
|
#ifndef __com_sun_star_lang_XComponent_idl__
|
|
#define __com_sun_star_lang_XComponent_idl__
|
|
|
|
#ifndef __com_sun_star_uno_XInterface_idl__
|
|
#include <com/sun/star/uno/XInterface.idl>
|
|
#endif
|
|
|
|
//=============================================================================
|
|
|
|
module com { module sun { module star { module lang {
|
|
|
|
published interface XEventListener;
|
|
|
|
//=============================================================================
|
|
|
|
// DocMerge from xml: interface com::sun::star::lang::XComponent
|
|
/** allows to exclicitly free resources and break cyclic references.
|
|
|
|
<p>Actually the real lifetime of an UNO object is controlled by
|
|
references kept on interfaces of this object. But there are two
|
|
distinct meanings in keeping a reference to an interface:
|
|
1st to own the object and 2nd to know the object.
|
|
|
|
<p>You are only allowed to keep references of interfaces
|
|
to UNO objects if you are by definition the owner of that object or
|
|
your reference is very temporary or you have registered an
|
|
EventListener at that object and release the reference when
|
|
"disposing" is called.</p>
|
|
*/
|
|
published interface XComponent: com::sun::star::uno::XInterface
|
|
{
|
|
//-------------------------------------------------------------------------
|
|
|
|
// DocMerge from xml: method com::sun::star::lang::XComponent::dispose
|
|
/** The owner of an object calls this method to explicitly free all
|
|
resources kept by this object and thus break cyclic references.
|
|
|
|
<p>Only the owner of this object is allowed to call this method.
|
|
The object should release all resources and references in the
|
|
easiest possible manner ( for instance no serialization should
|
|
take place anymore ).
|
|
</p>
|
|
<p>
|
|
The object must notify all registered listeners using the method
|
|
<member>XEventListener::disposing</member>. All notfied objects
|
|
should release there references to this object without
|
|
calling <member>XComponent::removeEventListener</member>
|
|
(the disposed object will release the listeners eitherway).
|
|
</p>
|
|
|
|
<p>After this method has been called, the object should behave as passive
|
|
as possible, thus it should ignore all calls
|
|
in case it can comply with its specification (for instance addEventListener()).
|
|
Often the object can't fulfill its specification anymore,
|
|
in this case it must throw the <type>DisposedException</type>
|
|
(which is derived from <type scope="com::sun::star::uno">RuntimeException</type>)
|
|
when it gets called.</p>
|
|
|
|
<p>For some objects no real owner can be identified, thus it can be
|
|
disposed from multiple reference holders. In this case
|
|
the object should be able to cope with multiple dispose()-calls (which
|
|
are inevitable in a multithreaded environment).
|
|
*/
|
|
void dispose();
|
|
|
|
//-------------------------------------------------------------------------
|
|
|
|
// DocMerge from xml: method com::sun::star::lang::XComponent::addEventListener
|
|
/** adds an event listener to the object.
|
|
|
|
<p>The broadcaster fires the disposing method of this listener
|
|
if the <member>XComponent::dispose</member> method is called.</p>
|
|
|
|
<p>It is suggested to allow multiple registration of the same listener,
|
|
thus for each time a listener is added, it has to be removed.</p>
|
|
|
|
<p>If this <type scope="com::sun::star::lang">XComponent</type> is
|
|
already disposed when <member scope="com::sun::star::lang">
|
|
XComponent::addEventListener</member> is called, the call will not fail
|
|
with a <type scope="com::sun::star::lang">DisposedException</type>, but
|
|
the caller will be notified via the
|
|
<member scope="com::sun::star::lang">XEventListener::disposing</member>
|
|
callback. This callback can occur synchronously within the
|
|
<member scope="com::sun::star::lang">XComponent::addEventListener
|
|
</member> call.</p>
|
|
|
|
@see XComponent::removeEventListener
|
|
*/
|
|
void addEventListener( [in] XEventListener xListener );
|
|
|
|
//-------------------------------------------------------------------------
|
|
|
|
// DocMerge from xml: method com::sun::star::lang::XComponent::removeEventListener
|
|
/** removes an event listener from the listener list.
|
|
|
|
<p>It is a "noop" if the specified listener is not registered.</p>
|
|
|
|
<p>It is suggested to allow multiple registration of the same listener,
|
|
thus for each time a listener is added, it has to be removed.
|
|
|
|
<p>If this <type scope="com::sun::star::lang">XComponent</type> is
|
|
already disposed when <member scope="com::sun::star::lang">
|
|
XComponent::removeEventListener</member> is called, the call will not
|
|
fail with a <type scope="com::sun::star::lang">DisposedException</type>,
|
|
but will rather be ignored silently.</p>
|
|
|
|
@see XComponent::addEventListener
|
|
*/
|
|
void removeEventListener( [in] XEventListener aListener );
|
|
|
|
};
|
|
|
|
//=============================================================================
|
|
|
|
}; }; }; };
|
|
|
|
#endif
|