xref: /trunk/main/offapi/com/sun/star/awt/XPopupMenu.idl (revision a893be29)
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#ifndef __com_sun_star_awt_XPopupMenu_idl__
23#define __com_sun_star_awt_XPopupMenu_idl__
24
25#include <com/sun/star/awt/KeyEvent.idl>
26#include <com/sun/star/awt/Rectangle.idl>
27#include <com/sun/star/awt/XMenu.idl>
28#include <com/sun/star/graphic/XGraphic.idl>
29
30module com {  module sun {  module star {  module awt {
31
32published interface XWindowPeer;
33
34/** controls a popup menu.
35 */
36published interface XPopupMenu: XMenu
37{
38    /** inserts a separator at the specified position.
39
40        @param nItemPos
41            specifies the position where the menu separator will be insterted.
42     */
43    [oneway] void insertSeparator( [in] short nItemPos );
44
45    /** sets the menu default item.
46
47        @param nItemId
48            specifies the menu item identifier.
49     */
50    [oneway] void setDefaultItem( [in] short nItemId );
51
52    /** returns the menu default item.
53
54        @return
55            the ID of the default item.
56     */
57    short getDefaultItem();
58
59    /** sets the state of the item to be checked or unchecked.
60
61        @param nItemId
62            specifies the menu item identifier.
63
64        @param bCheck
65            specifies if the item is checked (<TRUE/>) or unchecked (<FALSE/>).
66     */
67    [oneway] void checkItem( [in] short nItemId,
68                             [in] boolean bCheck );
69
70    /** returns whether the item is checked or unchecked.
71
72        @param nItemId
73            specifies the menu item identifier.
74
75        @return
76            <TRUE/> if the item is checked, <FALSE/> otherwise.
77     */
78    boolean isItemChecked( [in] short nItemId );
79
80    /** executes the popup menu and returns the selected item
81        or <code>0</code>, if cancelled.
82
83        @param Parent
84            the parent window.
85
86        @param Position
87            a <type>Rectangle</type> representing the coordinates system
88            where the popup menu should be executed.
89
90        @param Direction
91            the direction in which a popup menu will grow, as specified
92            by one of the <type>PopupMenuDirection</type> constants.
93
94        @return
95            returns the selected item or <code>0</code>, if cancelled.
96     */
97    short execute( [in] XWindowPeer Parent,
98                   [in] Rectangle Position,
99                   [in] short Direction );
100
101    /** queries if the <type>PopupMenu</type> is being.
102
103        <p>Returns <TRUE/> only if the <type>PopupMenu</type> is being executed
104        as a result of invoking <member >XPopupMenu::execute()</member>; that is,
105        for a <type>PopupMenu</type> activated by a <type>MenuBar</type> item,
106        this methods returns <FALSE/>.</p>
107
108        @return
109            <TRUE/> if the <type>PopupMenu</type> is being executed,
110            <FALSE/> otherwise.
111
112        @see <member >XPopupMenu::execute()</member>
113    */
114    boolean isInExecute();
115
116    /** ends the execution of the <type>PopupMenu</type>.
117        <p><member scope="com::sun::star::awt">XPopupMenu::execute()</member>
118        will then return 0.</p>
119
120        @see <member scope="com::sun::star::awt">XPopupMenu::execute()</member>
121    */
122    void endExecute();
123
124    /** sets the <type>KeyEvent</type> for the menu item.
125
126        <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
127        the shortcut information, this methods only draws the text corresponding to
128        this keyboard shortcut. The client code is responsible for listening to
129        keyboard events (typically done via <type>XUserInputInterception</type>),
130        and dispatch the respective command.</p>
131
132        @param nItemId
133            specifies the menu item identifier for which the <type>KeyEvent</type> should be set.
134
135        @param aKeyEvent
136            specifies the <type>KeyEvent</type> for the menu item.
137    */
138    void setAcceleratorKeyEvent( [in] short nItemId,
139                                 [in] KeyEvent aKeyEvent );
140
141    /** retrieves the <type>KeyEvent</type> for the menu item.
142
143        <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
144        the shortcut information, so that in this case
145        <member scope="::com::sun::star::lang::">EventObject::Source</member> is <NULL/>.</p>
146
147        @param nItemId
148            specifies the menu item identifier for which the <type>KeyEvent</type> should be retrieved.
149
150        @return
151            the <type>KeyEvent</type> struct assigned to the requested menu item.
152    */
153    KeyEvent getAcceleratorKeyEvent( [in] short nItemId );
154
155    /** sets the image for the menu item.
156
157        @param nItemId
158            specifies the menu item identifier for which the image should be set.
159
160        @param xGraphic
161            specifies the image for the menu item.
162
163        @param bScale
164            if <TRUE/>, the image will be scaled to the standard size used internally by
165            the implementation.
166    */
167    void setItemImage( [in] short nItemId,
168                       [in] ::com::sun::star::graphic::XGraphic xGraphic,
169                       [in] boolean bScale );
170
171    /** retrieves the image for the menu item.
172
173        @param nItemId
174            specifies the menu item identifier for which the image should be retrieved.
175
176        @return
177            a <type scope="::com::sun::star::graphic::">XGraphic</type> reference
178            to the current image for the requested menu item.
179    */
180    ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId );
181
182};
183
184}; }; }; };
185
186#endif
187