| /************************************************************** |
| * |
| * 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_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 |