xref: /aoo41x/main/offapi/com/sun/star/frame/XDispatch.idl (revision d1766043)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_frame_XDispatch_idl__
24#define __com_sun_star_frame_XDispatch_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_util_URL_idl__
31#include <com/sun/star/util/URL.idl>
32#endif
33
34#ifndef __com_sun_star_beans_PropertyValue_idl__
35#include <com/sun/star/beans/PropertyValue.idl>
36#endif
37
38#ifndef __com_sun_star_frame_XStatusListener_idl__
39#include <com/sun/star/frame/XStatusListener.idl>
40#endif
41
42
43//=============================================================================
44
45module com {  module sun {  module star {  module frame {
46
47//=============================================================================
48/** serves state information of objects which can be connected to
49        controls (e.g. toolbox controls).
50
51    <p>
52    Each state change is to be broadcasted to all registered
53	status listeners. The first notification should be performed
54    synchronously from <member>XDispatch::addStatusListener()</member>;
55        if not, controls may flicker. State listener must be aware of this
56    synchronous notification.
57    </p>
58
59    <p>
60    The state consists of enabled/disabled and a short descriptive text
61	of the function (e.g. "undo insert character"). It is to be broadcasted
62        whenever this state changes or the control should re-get the value
63	for the URL it is connected to. Additionally, a context-switch-event
64	is to be broadcasted whenever the object may be out of scope,
65    to force the state listener to requery the <type>XDispatch</type>.
66    </p>
67
68    @see Frame
69    @see FeatureStateEvent
70 */
71published interface XDispatch: com::sun::star::uno::XInterface
72{
73	//-------------------------------------------------------------------------
74	/** dispatches (executes) an URL asynchronously.
75
76        <p>
77        It is only allowed to dispatch URLs for which this <type>XDispatch</type>
78        was explicitely queried. Additional arguments ("'#..." or "?...") are allowed.
79        </p>
80
81        @param URL
82            fully parsed URL describing the feature which should be dispatched (=executed)
83
84        @param Arguments
85            optional arguments for this request.
86            They depend on the real implementation of the dipsatch object.
87
88        @example
89            <listing>
90            <i><font COLOR="#949494">// some code for a click-handler (Java)</font></i>
91            void <strong>myOnClick</strong>(<em>String</em> sURL,<em>String</em> sTargetFrame,<em>com.sun.star.beans.PropertyValue[]</em> lArguments)
92            {
93            &nbsp;&nbsp;com.sun.star.util.URL[] aURL = new com.sun.star.util.URL[1];
94            &nbsp;&nbsp;aURL[0] = new com.sun.star.util.URL();
95            &nbsp;&nbsp;aURL[0].Complete = sURL;
96
97            &nbsp;&nbsp;com.sun.star.util.XURLTransformer xParser = (com.sun.star.util.XURLTransformer)UnoRuntime.queryInterface(
98            &nbsp;&nbsp;&nbsp;&nbsp;com.sun.star.util.XURLTransformer.class,
99            &nbsp;&nbsp;&nbsp;&nbsp;mxServiceManager.createInstance("com.sun.star.util.URLTransformer"));
100
101            &nbsp;&nbsp;xParser.parseStrict(aURL);
102
103            &nbsp;&nbsp;com.sun.star.frame.XDispatch xDispatcher = mxFrame.queryDispatch(aURL[0], sTargetFrame, com.sun.star.frame.FrameSearchFlag.GLOBAL);
104
105            &nbsp;&nbsp;if(xDispatcher!=null)
106            &nbsp;&nbsp;&nbsp;&nbsp;xDispatcher.dispatch(aURL[0], lArguments);
107            }
108            </listing>
109	 */
110    [oneway] void dispatch(
111        [in] com::sun::star::util::URL URL,
112        [in] sequence<com::sun::star::beans::PropertyValue> Arguments);
113
114	//-------------------------------------------------------------------------
115        /** registers a listener of a control for a specific URL
116		at this object to receive status events.
117
118        <p>
119        It is only allowed to register URLs for which this <type>XDispatch</type>
120        was explicitely queried. Additional arguments ("#..." or "?...") will be ignored.
121        </p>
122        Note: Notifications can't be guaranteed! This will be a part of interface <type>XNotifyingDispatch</type>.
123
124        @param Control
125            listener that wishes to be informed
126
127        @param URL
128            the URL (without additional arguments) the listener wishes to be registered for.
129            A listener can be registered for more than one URL at the same time.
130
131        @see XStatusListener
132        @see XDispatch::removeStatusListener()
133	 */
134    [oneway] void addStatusListener(
135        [in] XStatusListener Control,
136        [in] com::sun::star::util::URL URL);
137
138	//-------------------------------------------------------------------------
139        /** unregisters a listener from a control.
140
141        @param Control
142            listener that wishes to be unregistered
143
144        @param URL
145            URL the listener was registered for.
146            Additional arguments ("#..." or "?...") will be ignored.
147
148        @see XStatusListener
149        @see XDispatch::addStatusListener()
150	 */
151    [oneway] void removeStatusListener(
152        [in] XStatusListener Control,
153        [in] com::sun::star::util::URL URL);
154};
155
156//=============================================================================
157
158}; }; }; };
159
160#endif
161