udkapi/com/sun/star/script/XEventAttacherManager.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XEventAttacherManager.idl,v $
  10  * $Revision: 1.12 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_script_XEventAttacherManager_idl__
  31 #define __com_sun_star_script_XEventAttacherManager_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_script_ScriptEventDescriptor_idl__
  38 #include <com/sun/star/script/ScriptEventDescriptor.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  42 #include <com/sun/star/lang/IllegalArgumentException.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_lang_ServiceNotRegisteredException_idl__
  46 #include <com/sun/star/lang/ServiceNotRegisteredException.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_script_XScriptListener_idl__
  50 #include <com/sun/star/script/XScriptListener.idl>
  51 #endif
  52
  53
  54 //=============================================================================
  55
  56  module com {  module sun {  module star {  module script {
  57
  58 //=============================================================================
  59 /** registers listeners for specified events.
  60  */
  61 published interface XEventAttacherManager: com::sun::star::uno::XInterface
  62 {
  63     //-------------------------------------------------------------------------
  64     /** registers one event for an object identified by its index.
  65
  66         <p>If any object is attached under this index, then this
  67         event is attached automatically.</p>
  68         <p>Exceptions of type
  69         <type scope="com::sun::star::beans">IntrospectionException</type> and
  70         <type scope="com::sun::star::script">CannotCreateAdapterException</type>
  71         that can be thrown by methods of <type>XEventAttacher</type> are caught
  72         and ignored.</p>
  73      */
  74     void registerScriptEvent( [in] long nIndex,
  75              [in] com::sun::star::script::ScriptEventDescriptor aScriptEvent )
  76             raises( com::sun::star::lang::IllegalArgumentException );
  77
  78     //-------------------------------------------------------------------------
  79     /** registers several events for an object identified by its index.
  80
  81         <p>The result is the same as if the method <member>registerScriptEvent
  82         </member> was called once for each <type>ScriptEventDescriptor</type>
  83         in the sequence.</p>
  84
  85         <p>If any object is attached under this index, then this
  86         event is attached automatically (see <member>attach</member>)</p>
  87
  88         <p>Exceptions of type
  89         <type scope="com::sun::star::beans">IntrospectionException</type> and
  90         <type scope="com::sun::star::script">CannotCreateAdapterException</type>
  91         that can be thrown by methods of <type>XEventAttacher</type> are caught
  92         and ignored.</p>
  93
  94         @see registerScriptEvent
  95         @see attach
  96      */
  97     void registerScriptEvents( [in] long nIndex,
  98              [in] sequence<com::sun::star::script::ScriptEventDescriptor> aScriptEvents )
  99             raises( com::sun::star::lang::IllegalArgumentException );
 100
 101     //-------------------------------------------------------------------------
 102     /** revokes the registration of an event.
 103
 104         <p>The parameters <var>ListenerType</var> and
 105         <var>EventMethod</var> are equivalent to the first two
 106         members of the <type>ScriptEventDescriptor</type>
 107         used to register events. If this event at this index has
 108         been attached to any object, it is detached automatically
 109         (see <member>attach</member>).</p>
 110
 111         <p>Exceptions of type
 112         <type scope="com::sun::star::beans">IntrospectionException</type> and
 113         <type scope="com::sun::star::script">CannotCreateAdapterException</type>
 114         that can be thrown by methods of <type>XEventAttacher</type> are caught
 115         and ignored.</p>
 116
 117         @see attach
 118      */
 119     void revokeScriptEvent( [in] long nIndex,
 120              [in] string aListenerType,
 121              [in] string aEventMethod,
 122              [in] string aRemoveListenerParam )
 123             raises( com::sun::star::lang::IllegalArgumentException );
 124
 125     //-------------------------------------------------------------------------
 126     /** revokes all events which are registered for the given index.
 127
 128         <p>If the events at this index have been attached to any
 129         object, they are detached automatically.
 130         (see <member>attach</member>).</p>
 131
 132         @see attach
 133      */
 134     void revokeScriptEvents( [in] long nIndex )
 135             raises( com::sun::star::lang::IllegalArgumentException );
 136
 137     //-------------------------------------------------------------------------
 138     /** creates an empty entry at the given position.
 139
 140         <p>The index <var>n</var> of all entries with <code>n &amp;gt;=
 141         nIndex</code> will be increased by one.</p>
 142      */
 143     void insertEntry( [in] long nIndex )
 144             raises( com::sun::star::lang::IllegalArgumentException );
 145
 146     //-------------------------------------------------------------------------
 147     /** removes the entry at the given position.
 148
 149         <p>If any events are registered at this index, they will
 150         be revoked, too. So if the events at this index have been
 151         attached to any object they are detached automatically.
 152         (see <member>attach</member>).</p>
 153
 154         @see attach
 155      */
 156     void removeEntry( [in] long nIndex )
 157             raises( com::sun::star::lang::IllegalArgumentException );
 158
 159     //-------------------------------------------------------------------------
 160     /** @eturns
 161             all events registered for the given object index.
 162
 163         @param Index
 164             an index previously inserted with the method insertEntry.
 165
 166         @throws IllegalArgumentException
 167             if Index is not valid.
 168      */
 169     sequence<com::sun::star::script::ScriptEventDescriptor> getScriptEvents( [in] long Index )
 170             raises( com::sun::star::lang::IllegalArgumentException );
 171
 172     //-------------------------------------------------------------------------
 173     /** attaches all the <type>ScriptEvent</type>s which are registered
 174         for the given index to the given object.
 175
 176         <p>Exceptions of type
 177         <type scope="com::sun::star::beans">IntrospectionException</type> and
 178         <type scope="com::sun::star::script">CannotCreateAdapterException</type>
 179         that can be thrown by methods of <type>XEventAttacher</type> are caught
 180         and ignored.</p>
 181      */
 182     void attach( [in] long nIndex,
 183              [in] com::sun::star::uno::XInterface xObject,
 184              [in] any aHelper )
 185             raises( com::sun::star::lang::IllegalArgumentException,
 186                     com::sun::star::lang::ServiceNotRegisteredException );
 187
 188     //-------------------------------------------------------------------------
 189     /** detaches all the <type>ScriptEvent</type>s from the given object
 190         which are registered at this object for the given index.
 191
 192         <p>Exceptions of type
 193         <type scope="com::sun::star::beans">IntrospectionException</type> and
 194         <type scope="com::sun::star::script">CannotCreateAdapterException</type>
 195         that can be thrown by methods of <type>XEventAttacher</type> are caught
 196         and ignored.</p>
 197      */
 198     void detach( [in] long nIndex,
 199              [in] com::sun::star::uno::XInterface xObject )
 200             raises( com::sun::star::lang::IllegalArgumentException );
 201
 202     //-------------------------------------------------------------------------
 203     /** adds an <type>XScriptListener</type> that will be notified when an
 204         event takes place. For that a
 205         <type>ScriptEventDescriptor</type> is registered at and
 206         attached to an object by an <type>XEventAttacherManager</type>.
 207
 208        <p>It is suggested to allow multiple registration of the same listener,
 209         thus for each time a listener is added, it has to be removed.
 210
 211         @see removeScriptListener
 212      */
 213     void addScriptListener( [in] com::sun::star::script::XScriptListener xListener )
 214             raises( com::sun::star::lang::IllegalArgumentException );
 215
 216     //-------------------------------------------------------------------------
 217     /** removes a <type>XScriptListener</type> from the listener list.
 218
 219         <p>Nothing happens if the listener is not registered.
 220
 221        <p>It is suggested to allow multiple registration of the same listener,
 222         thus for each time a listener is added, it has to be removed.
 223
 224         @see addScriptListener
 225      */
 226     void removeScriptListener( [in] com::sun::star::script::XScriptListener Listener )
 227             raises( com::sun::star::lang::IllegalArgumentException );
 228
 229 };
 230
 231 //=============================================================================
 232
 233 }; }; }; };
 234
 235 #endif