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

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