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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21
  22  module com {  module sun {  module star {  module script {
  23
  24 /** registers listeners for specified events.
  25  */
  26 published interface XEventAttacherManager: com::sun::star::uno::XInterface
  27 {
  28     /** registers one event for an object identified by its index.
  29
  30         <p>If any object is attached under this index, then this
  31         event is attached automatically.</p>
  32         <p>Exceptions of type
  33         com::sun::star::beans::IntrospectionException and
  34         com::sun::star::script::CannotCreateAdapterException
  35         that can be thrown by methods of XEventAttacher are caught
  36         and ignored.</p>
  37      */
  38     void registerScriptEvent( [in] long nIndex,
  39              [in] com::sun::star::script::ScriptEventDescriptor aScriptEvent )
  40             raises( com::sun::star::lang::IllegalArgumentException );
  41
  42     /** registers several events for an object identified by its index.
  43
  44         <p>The result is the same as if the method registerScriptEvent()
  45         was called once for each ScriptEventDescriptor
  46         in the sequence.</p>
  47
  48         <p>If any object is attached under this index, then this
  49         event is attached automatically (see attach())</p>
  50
  51         <p>Exceptions of type
  52         com::sun::star::beans::IntrospectionException and
  53         com::sun::star::script::CannotCreateAdapterException
  54         that can be thrown by methods of XEventAttacher are caught
  55         and ignored.</p>
  56
  57         @see registerScriptEvent
  58         @see attach
  59      */
  60     void registerScriptEvents( [in] long nIndex,
  61              [in] sequence<com::sun::star::script::ScriptEventDescriptor> aScriptEvents )
  62             raises( com::sun::star::lang::IllegalArgumentException );
  63
  64     /** revokes the registration of an event.
  65
  66         <p>The parameters <var>ListenerType</var> and
  67         <var>EventMethod</var> are equivalent to the first two
  68         members of the ScriptEventDescriptor
  69         used to register events. If this event at this index has
  70         been attached to any object, it is detached automatically
  71         (see attach()).</p>
  72
  73         <p>Exceptions of type
  74         com::sun::star::beans::IntrospectionException and
  75         com::sun::star::script::CannotCreateAdapterException
  76         that can be thrown by methods of XEventAttacher are caught
  77         and ignored.</p>
  78
  79         @see attach
  80      */
  81     void revokeScriptEvent( [in] long nIndex,
  82              [in] string aListenerType,
  83              [in] string aEventMethod,
  84              [in] string aRemoveListenerParam )
  85             raises( com::sun::star::lang::IllegalArgumentException );
  86
  87     /** revokes all events which are registered for the given index.
  88
  89         <p>If the events at this index have been attached to any
  90         object, they are detached automatically.
  91         (see attach()).</p>
  92
  93         @see attach
  94      */
  95     void revokeScriptEvents( [in] long nIndex )
  96             raises( com::sun::star::lang::IllegalArgumentException );
  97
  98     /** creates an empty entry at the given position.
  99
 100         <p>The index <var>n</var> of all entries with <code>n &amp;gt;=
 101         nIndex</code> will be increased by one.</p>
 102      */
 103     void insertEntry( [in] long nIndex )
 104             raises( com::sun::star::lang::IllegalArgumentException );
 105
 106     /** removes the entry at the given position.
 107
 108         <p>If any events are registered at this index, they will
 109         be revoked, too. So if the events at this index have been
 110         attached to any object they are detached automatically.
 111         (see attach()).</p>
 112
 113         @see attach
 114      */
 115     void removeEntry( [in] long nIndex )
 116             raises( com::sun::star::lang::IllegalArgumentException );
 117
 118     /** @return
 119             all events registered for the given object index.
 120
 121         @param Index
 122             an index previously inserted with the method insertEntry.
 123
 124         @throws IllegalArgumentException
 125             if Index is not valid.
 126      */
 127     sequence<com::sun::star::script::ScriptEventDescriptor> getScriptEvents( [in] long Index )
 128             raises( com::sun::star::lang::IllegalArgumentException );
 129
 130     /** attaches all the ScriptEvents which are registered
 131         for the given index to the given object.
 132
 133         <p>Exceptions of type
 134         com::sun::star::beans::IntrospectionException and
 135         com::sun::star::script::CannotCreateAdapterException
 136         that can be thrown by methods of XEventAttacher are caught
 137         and ignored.</p>
 138      */
 139     void attach( [in] long nIndex,
 140              [in] com::sun::star::uno::XInterface xObject,
 141              [in] any aHelper )
 142             raises( com::sun::star::lang::IllegalArgumentException,
 143                     com::sun::star::lang::ServiceNotRegisteredException );
 144
 145     /** detaches all the ScriptEvents from the given object
 146         which are registered at this object for the given index.
 147
 148         <p>Exceptions of type
 149         com::sun::star::beans::IntrospectionException and
 150         com::sun::star::script::CannotCreateAdapterException
 151         that can be thrown by methods of XEventAttacher are caught
 152         and ignored.</p>
 153      */
 154     void detach( [in] long nIndex,
 155              [in] com::sun::star::uno::XInterface xObject )
 156             raises( com::sun::star::lang::IllegalArgumentException );
 157
 158     /** adds an XScriptListener that will be notified when an
 159         event takes place. For that a
 160         ScriptEventDescriptor is registered at and
 161         attached to an object by an XEventAttacherManager.
 162
 163        <p>It is suggested to allow multiple registration of the same listener,
 164         thus for each time a listener is added, it has to be removed.
 165
 166         @see removeScriptListener
 167      */
 168     void addScriptListener( [in] com::sun::star::script::XScriptListener xListener )
 169             raises( com::sun::star::lang::IllegalArgumentException );
 170
 171     /** removes a XScriptListener from the listener list.
 172
 173         <p>Nothing happens if the listener is not registered.
 174
 175        <p>It is suggested to allow multiple registration of the same listener,
 176         thus for each time a listener is added, it has to be removed.
 177
 178         @see addScriptListener
 179      */
 180     void removeScriptListener( [in] com::sun::star::script::XScriptListener Listener )
 181             raises( com::sun::star::lang::IllegalArgumentException );
 182
 183 };
 184
 185
 186 }; }; }; };
 187
 188 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */