offapi/com/sun/star/awt/XPopupMenuExtended.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XPopupMenuExtended.idl,v $
  10  * $Revision: 1.0 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_awt_XPopupMenuExtended_idl__
  31 #define __com_sun_star_awt_XPopupMenuExtended_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_awt_XPopupMenu_idl__
  38 #include <com/sun/star/awt/XPopupMenu.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_awt_XMenuExtended2_idl__
  42 #include <com/sun/star/awt/XMenuExtended2.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_awt_MenuLogo_idl__
  46 #include <com/sun/star/awt/MenuLogo.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  50 #include <com/sun/star/container/NoSuchElementException.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_awt_KeyEvent_idl__
  54 #include <com/sun/star/awt/KeyEvent.idl>
  55 #endif
  56
  57 #ifndef com_sun_star_graphic_XGraphic_idl
  58 #include <com/sun/star/graphic/XGraphic.idl>
  59 #endif
  60
  61 //=============================================================================
  62
  63 module com {  module sun {  module star {  module awt {
  64
  65 /** specifies extended functions for a <type scope="com::sun::star::awt">PopupMenu</type>.
  66
  67     @since OOo 3.1
  68  */
  69 interface XPopupMenuExtended
  70 {
  71     /** specifies basic functions for a popup menu.
  72     */
  73     interface ::com::sun::star::awt::XPopupMenu;
  74
  75     /** specifies extended menu functions, available for both
  76         <type scope="com::sun::star::awt">MenuBar</type> and
  77         <type scope="com::sun::star::awt">PopupMenu</type>.
  78     */
  79     interface ::com::sun::star::awt::XMenuExtended2;
  80
  81     //=========================================================================
  82
  83     /** queries if the <type scope="com::sun::star::awt">PopupMenu</type>
  84         is being executed as a result of invoking
  85         <member scope="com::sun::star::awt">XPopupMenu::execute()</member>; that is,
  86         for a <type>PopupMenu</type> activated by a <type>MenuBar</type> item,
  87         this methods returns <FALSE/>.
  88
  89         @return
  90             <TRUE/> if the <type scope="com::sun::star::awt">PopupMenu</type>
  91             is being executed, <FALSE/> otherwise.
  92
  93         @see <member scope="com::sun::star::awt">XPopupMenu::execute()</member>
  94
  95         @since OOo 3.1
  96     */
  97     boolean isInExecute();
  98
  99     /** ends the execution of the <type scope="com::sun::star::awt">PopupMenu</type>.
 100         <member scope="com::sun::star::awt">XPopupMenu::execute()</member> will then return 0.
 101
 102         @see <member scope="com::sun::star::awt">XPopupMenu::execute()</member>
 103
 104         @since OOo 3.1
 105     */
 106     void endExecute();
 107
 108     //=============================================================================
 109
 110     /** sets the <type>MenuLogo</type> for this <type>PopupMenu</type>.
 111
 112         @param aMenuLogo
 113             the <type>MenuLogo</type>.
 114
 115         @since OOo 3.1
 116     */
 117     void setLogo( [in] ::com::sun::star::awt::MenuLogo aMenuLogo );
 118
 119     /** retrieves the <type>MenuLogo</type> for this <type>PopupMenu</type>.
 120
 121         @return
 122             the <type>MenuLogo</type>.
 123
 124         @since OOo 3.1
 125     */
 126     ::com::sun::star::awt::MenuLogo getLogo();
 127
 128
 129     //=========================================================================
 130
 131
 132     /** specifies whether mnemonics are automatically assigned to menu items, or not.
 133
 134         @param bEnable
 135             if <TRUE/>, mnemonics are automatically assigned to menu items.
 136     */
 137     void enableAutoMnemonics( [in] boolean bEnable );
 138
 139
 140     //=========================================================================
 141
 142     /** sets the <type>KeyEvent</type> for the menu item.
 143
 144         <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
 145         the shortcut information, this methods only draws the text corresponding to
 146         this keyboard shortcut. The client code is responsible for listening to
 147         keyboard events (typicaly done via <type>XUserInputInterception</type>),
 148         and dispatch the respective command.</p>
 149
 150         @param nItemId
 151             specifies the menu item identifier for which the <type>KeyEvent</type> should be set.
 152
 153         @param aKeyEvent
 154             specifies the <type>KeyEvent</type> for the menu item.
 155
 156         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 157             if there is no menu item with the identifier specified in <var>nItemId</var>.
 158
 159         @since OOo 3.1
 160     */
 161     void setAcceleratorKeyEvent( [in] short nItemId, [in] ::com::sun::star::awt::KeyEvent aKeyEvent )
 162         raises ( ::com::sun::star::container::NoSuchElementException );
 163
 164     /** retrieves the <type>KeyEvent</type> for the menu item.
 165
 166         <p>The <type>KeyEvent</type> is <b>only</b> used as a container to transport
 167         the shortcut information, so that in this case
 168         <member scope="::com::sun::star::lang::">EventObject::Source</member> is <NULL/>.</p>
 169
 170         @param nItemId
 171             specifies the menu item identifier for which the <type>KeyEvent</type> should be retrieved.
 172
 173         @return
 174             the <type>KeyEvent</type> struct assigned to the requested menu item.
 175
 176         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 177             if there is no menu item with the identifier specified in <var>nItemId</var>.
 178
 179         @since OOo 3.1
 180     */
 181     ::com::sun::star::awt::KeyEvent getAcceleratorKeyEvent( [in] short nItemId )
 182         raises ( ::com::sun::star::container::NoSuchElementException );
 183
 184     //=============================================================================
 185
 186     /** sets the help text for the menu item.
 187
 188         @param nItemId
 189             specifies the menu item identifier for which the help text should be set.
 190
 191         @param sHelpText
 192             specifies the help text for the menu item.
 193
 194         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 195             if there is no menu item with the identifier specified in <var>nItemId</var>.
 196
 197         @since OOo 3.1
 198     */
 199     void setHelpText( [in] short nItemId, [in] string sHelpText )
 200         raises ( ::com::sun::star::container::NoSuchElementException );
 201
 202     /** retrieves the help text for the menu item.
 203
 204         @param nItemId
 205             specifies the menu item identifier for which the help text should be retrieved.
 206
 207         @return
 208             a string with the help text.
 209
 210         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 211             if there is no menu item with the identifier specified in <var>nItemId</var>.
 212
 213         @since OOo 3.1
 214     */
 215     string getHelpText( [in] short nItemId )
 216         raises ( ::com::sun::star::container::NoSuchElementException );
 217
 218     //=============================================================================
 219
 220     /** sets the tip help text for the menu item.
 221
 222         @param nItemId
 223             specifies the menu item identifier for which the tip help text should be set.
 224
 225         @param sTipHelpText
 226             specifies the tip help text for the menu item.
 227
 228         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 229             if there is no menu item with the identifier specified in <var>nItemId</var>.
 230
 231         @since OOo 3.1
 232     */
 233     void setTipHelpText( [in] short nItemId, [in] string sTipHelpText )
 234         raises ( ::com::sun::star::container::NoSuchElementException );
 235
 236     /** retrieves the tip help text for the menu item.
 237
 238         @param nItemId
 239             specifies the menu item identifier for which the tip help text should be retrieved.
 240
 241         @return
 242             a string with the tip help text.
 243
 244         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 245             if there is no menu item with the identifier specified in <var>nItemId</var>.
 246
 247         @since OOo 3.1
 248     */
 249     string getTipHelpText( [in] short nItemId )
 250         raises ( ::com::sun::star::container::NoSuchElementException );
 251
 252     //=============================================================================
 253
 254     /** sets the image for the menu item.
 255
 256         @param nItemId
 257             specifies the menu item identifier for which the image should be set.
 258
 259         @param xGraphic
 260             specifies the image for the menu item.
 261
 262         @param bScale
 263             if <TRUE/>, the image will be scaled to the standard size used internally by
 264             the implementation.
 265
 266         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 267             if there is no menu item with the identifier specified in <var>nItemId</var>.
 268
 269         @since OOo 3.1
 270     */
 271     void setItemImage(      [in] short nItemId,
 272                             [in] ::com::sun::star::graphic::XGraphic xGraphic,
 273                             [in] boolean bScale )
 274         raises ( ::com::sun::star::container::NoSuchElementException );
 275
 276     /** retrieves the image for the menu item.
 277
 278         @param nItemId
 279             specifies the menu item identifier for which the image should be retrieved.
 280
 281         @return
 282             a <type scope="::com::sun::star::graphic::">XGraphic</type> reference
 283             to the current image for the requested menu item.
 284
 285         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 286             if there is no menu item with the identifier specified in <var>nItemId</var>.
 287
 288         @since OOo 3.1
 289     */
 290     ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId )
 291         raises ( ::com::sun::star::container::NoSuchElementException );
 292
 293     //.............................................................................
 294
 295
 296     /** sets the rotation angle of a menu item image.
 297
 298         @param nItemId
 299             specifies the menu item identifier for which the image angle should be set.
 300
 301         @param nAngle
 302             specifies the rotation angle for the menu item image.
 303
 304         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 305             if there is no menu item with the identifier specified in <var>nItemId</var>.
 306
 307         @since OOo 3.1
 308     */
 309     void setItemImageAngle( [in] short nItemId, [in] long nAngle )
 310         raises ( ::com::sun::star::container::NoSuchElementException );
 311
 312     /** retrieves the rotation angle of a menu item image.
 313
 314         @param nItemId
 315             specifies the menu item identifier for which the rotation angle should be retrieved.
 316
 317         @return the rotation angle of the menu item image, or 0 if it has no rotation.
 318
 319         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 320             if there is no menu item with the identifier specified in <var>nItemId</var>.
 321
 322         @since OOo 3.1
 323     */
 324     long getItemImageAngle( [in] short nItemId )
 325         raises ( ::com::sun::star::container::NoSuchElementException );
 326
 327     //.............................................................................
 328
 329     /** sets the mirror mode of a menu item image.
 330
 331         @param nItemId
 332             specifies the menu item identifier for which the mirror mode should be set.
 333
 334         @param bMirror
 335             if <TRUE/>, the item image is mirrored.
 336
 337         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 338             if there is no menu item with the identifier specified in <var>nItemId</var>.
 339
 340         @since OOo 3.1
 341     */
 342     void setItemImageMirrorMode( [in] short nItemId, [in] boolean bMirror )
 343         raises ( ::com::sun::star::container::NoSuchElementException );
 344
 345     /** indicates whether the menu item image is mirrored.
 346
 347         @param nItemId
 348             specifies the menu item identifier for which the image mirror mode should be checked.
 349
 350         @return <TRUE/> if the item image is mirrored, <FALSE/> otherwise.
 351
 352         @throws <type scope="com::sun::star::container">NoSuchElementException</type>
 353             if there is no menu item with the identifier specified in <var>nItemId</var>.
 354
 355         @since OOo 3.1
 356     */
 357     boolean isItemImageInMirrorMode( [in] short nItemId )
 358         raises ( ::com::sun::star::container::NoSuchElementException );
 359
 360 };
 361
 362 }; }; }; };
 363
 364 #endif