xref: /aoo41x/main/offapi/com/sun/star/awt/XPopupMenu.idl (revision d026be40)
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/Point.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            the coordinates where the popup menu should be executed.
88
89        @param Direction
90            the direction in which a popup menu will grow, as specified
91            by one of the <type>PopupMenuDirection</type> constants.
92
93        @return
94            returns the selected item or <code>0</code>, if cancelled.
95     */
96    short execute( [in] XWindowPeer Parent,
97                   [in] Point Position,
98                   [in] short Direction );
99
100    /** queries if the <type>PopupMenu</type> is being.
101
102        <p>Returns <TRUE/> only if the <type>PopupMenu</type> is being executed
103        as a result of invoking <member >XPopupMenu::execute()</member>; that is,
104        for a <type>PopupMenu</type> activated by a <type>MenuBar</type> item,
105        this methods returns <FALSE/>.</p>
106
107        @return
108            <TRUE/> if the <type>PopupMenu</type> is being executed,
109            <FALSE/> otherwise.
110
111        @see <member >XPopupMenu::execute()</member>
112    */
113    boolean isInExecute();
114
115    /** ends the execution of the <type>PopupMenu</type>.
116        <p><member scope="com::sun::star::awt">XPopupMenu::execute()</member>
117        will then return 0.</p>
118
119        @see <member scope="com::sun::star::awt">XPopupMenu::execute()</member>
120    */
121    void endExecute();
122
123    /** sets the <type>KeyEvent</type> for the menu item.
124
125        <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
126        the shortcut information, this methods only draws the text corresponding to
127        this keyboard shortcut. The client code is responsible for listening to
128        keyboard events (typicaly done via <type>XUserInputInterception</type>),
129        and dispatch the respective command.</p>
130
131        @param nItemId
132            specifies the menu item identifier for which the <type>KeyEvent</type> should be set.
133
134        @param aKeyEvent
135            specifies the <type>KeyEvent</type> for the menu item.
136    */
137    void setAcceleratorKeyEvent( [in] short nItemId,
138                                 [in] KeyEvent aKeyEvent );
139
140    /** retrieves the <type>KeyEvent</type> for the menu item.
141
142        <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
143        the shortcut information, so that in this case
144        <member scope="::com::sun::star::lang::">EventObject::Source</member> is <NULL/>.</p>
145
146        @param nItemId
147            specifies the menu item identifier for which the <type>KeyEvent</type> should be retrieved.
148
149        @return
150            the <type>KeyEvent</type> struct assigned to the requested menu item.
151    */
152    KeyEvent getAcceleratorKeyEvent( [in] short nItemId );
153
154    /** sets the image for the menu item.
155
156        @param nItemId
157            specifies the menu item identifier for which the image should be set.
158
159        @param xGraphic
160            specifies the image for the menu item.
161
162        @param bScale
163            if <TRUE/>, the image will be scaled to the standard size used internally by
164            the implementation.
165    */
166    void setItemImage( [in] short nItemId,
167                       [in] ::com::sun::star::graphic::XGraphic xGraphic,
168                       [in] boolean bScale );
169
170    /** retrieves the image for the menu item.
171
172        @param nItemId
173            specifies the menu item identifier for which the image should be retrieved.
174
175        @return
176            a <type scope="::com::sun::star::graphic::">XGraphic</type> reference
177            to the current image for the requested menu item.
178    */
179    ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId );
180
181};
182
183}; }; }; };
184
185#endif
186