/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   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 .
 */
#ifndef __com_sun_star_script_XEventAttacherManager_idl__
#define __com_sun_star_script_XEventAttacherManager_idl__

#include <com/sun/star/uno/XInterface.idl>

#include <com/sun/star/script/ScriptEventDescriptor.idl>

#include <com/sun/star/lang/IllegalArgumentException.idl>

#include <com/sun/star/lang/ServiceNotRegisteredException.idl>

#include <com/sun/star/script/XScriptListener.idl>



 module com {  module sun {  module star {  module script {

/** registers listeners for specified events.
 */
published interface XEventAttacherManager: com::sun::star::uno::XInterface
{
    /** registers one event for an object identified by its index.

        <p>If any object is attached under this index, then this
        event is attached automatically.</p>
        <p>Exceptions of type
        com::sun::star::beans::IntrospectionException and
        com::sun::star::script::CannotCreateAdapterException
        that can be thrown by methods of XEventAttacher are caught
        and ignored.</p>
     */
    void registerScriptEvent( [in] long nIndex,
             [in] com::sun::star::script::ScriptEventDescriptor aScriptEvent )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** registers several events for an object identified by its index.

        <p>The result is the same as if the method registerScriptEvent()
        was called once for each ScriptEventDescriptor
        in the sequence.</p>

        <p>If any object is attached under this index, then this
        event is attached automatically (see attach())</p>

        <p>Exceptions of type
        com::sun::star::beans::IntrospectionException and
        com::sun::star::script::CannotCreateAdapterException
        that can be thrown by methods of XEventAttacher are caught
        and ignored.</p>

        @see registerScriptEvent
        @see attach
     */
    void registerScriptEvents( [in] long nIndex,
             [in] sequence<com::sun::star::script::ScriptEventDescriptor> aScriptEvents )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** revokes the registration of an event.

        <p>The parameters <var>ListenerType</var> and
        <var>EventMethod</var> are equivalent to the first two
        members of the ScriptEventDescriptor
        used to register events. If this event at this index has
        been attached to any object, it is detached automatically
        (see attach()).</p>

        <p>Exceptions of type
        com::sun::star::beans::IntrospectionException and
        com::sun::star::script::CannotCreateAdapterException
        that can be thrown by methods of XEventAttacher are caught
        and ignored.</p>

        @see attach
     */
    void revokeScriptEvent( [in] long nIndex,
             [in] string aListenerType,
             [in] string aEventMethod,
             [in] string aRemoveListenerParam )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** revokes all events which are registered for the given index.

        <p>If the events at this index have been attached to any
        object, they are detached automatically.
        (see attach()).</p>

        @see attach
     */
    void revokeScriptEvents( [in] long nIndex )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** creates an empty entry at the given position.

        <p>The index <var>n</var> of all entries with <code>n &amp;gt;=
        nIndex</code> will be increased by one.</p>
     */
    void insertEntry( [in] long nIndex )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** removes the entry at the given position.

        <p>If any events are registered at this index, they will
        be revoked, too. So if the events at this index have been
        attached to any object they are detached automatically.
        (see attach()).</p>

        @see attach
     */
    void removeEntry( [in] long nIndex )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** @return
            all events registered for the given object index.

        @param Index
            an index previously inserted with the method insertEntry.

        @throws IllegalArgumentException
            if Index is not valid.
     */
    sequence<com::sun::star::script::ScriptEventDescriptor> getScriptEvents( [in] long Index )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** attaches all the ScriptEvents which are registered
        for the given index to the given object.

        <p>Exceptions of type
        com::sun::star::beans::IntrospectionException and
        com::sun::star::script::CannotCreateAdapterException
        that can be thrown by methods of XEventAttacher are caught
        and ignored.</p>
     */
    void attach( [in] long nIndex,
             [in] com::sun::star::uno::XInterface xObject,
             [in] any aHelper )
            raises( com::sun::star::lang::IllegalArgumentException,
                    com::sun::star::lang::ServiceNotRegisteredException );

    /** detaches all the ScriptEvents from the given object
        which are registered at this object for the given index.

        <p>Exceptions of type
        com::sun::star::beans::IntrospectionException and
        com::sun::star::script::CannotCreateAdapterException
        that can be thrown by methods of XEventAttacher are caught
        and ignored.</p>
     */
    void detach( [in] long nIndex,
             [in] com::sun::star::uno::XInterface xObject )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** adds an XScriptListener that will be notified when an
        event takes place. For that a
        ScriptEventDescriptor is registered at and
        attached to an object by an XEventAttacherManager.

       <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.

        @see removeScriptListener
     */
    void addScriptListener( [in] com::sun::star::script::XScriptListener xListener )
            raises( com::sun::star::lang::IllegalArgumentException );

    /** removes a XScriptListener from the listener list.

        <p>Nothing happens if the listener is not registered.

       <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.

        @see addScriptListener
     */
    void removeScriptListener( [in] com::sun::star::script::XScriptListener Listener )
            raises( com::sun::star::lang::IllegalArgumentException );

};


}; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */