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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 module com {  module sun {  module star {  module awt {
  21
  22 published interface XWindowPeer;
  23
  24 /** controls a pop-up menu.
  25  */
  26 published interface XPopupMenu: XMenu
  27 {
  28     /** inserts a separator at the specified position.
  29
  30         @param nItemPos
  31             specifies the position where the menu separator will be inserted.
  32      */
  33     void insertSeparator( [in] short nItemPos );
  34
  35     /** sets the menu default item.
  36
  37         @param nItemId
  38             specifies the menu item identifier.
  39      */
  40     void setDefaultItem( [in] short nItemId );
  41
  42     /** returns the menu default item.
  43
  44         @return
  45             the ID of the default item.
  46      */
  47     short getDefaultItem();
  48
  49     /** sets the state of the item to be checked or unchecked.
  50
  51         @param nItemId
  52             specifies the menu item identifier.
  53
  54         @param bCheck
  55             specifies if the item is checked (`TRUE`) or unchecked (`FALSE`).
  56      */
  57     void checkItem( [in] short nItemId,
  58                              [in] boolean bCheck );
  59
  60     /** returns whether the item is checked or unchecked.
  61
  62         @param nItemId
  63             specifies the menu item identifier.
  64
  65         @return
  66             `TRUE` if the item is checked, `FALSE` otherwise.
  67      */
  68     boolean isItemChecked( [in] short nItemId );
  69
  70     /** executes the popup menu and returns the selected item
  71         or <code>0</code>, if cancelled.
  72
  73         @param Parent
  74             the parent window.
  75
  76         @param Position
  77             a Rectangle representing the coordinates system
  78             where the popup menu should be executed.
  79
  80         @param Direction
  81             the direction in which a popup menu will grow, as specified
  82             by one of the PopupMenuDirection constants.
  83
  84         @return
  85             returns the selected item or <code>0</code>, if cancelled.
  86      */
  87     short execute( [in] XWindowPeer Parent,
  88                    [in] Rectangle Position,
  89                    [in] short Direction );
  90
  91     /** queries if the PopupMenu is being.
  92
  93         <p>Returns `TRUE` only if the PopupMenu is being executed
  94         as a result of invoking XPopupMenu::execute(); that is,
  95         for a PopupMenu activated by a MenuBar item,
  96         this methods returns `FALSE`.</p>
  97
  98         @return
  99             `TRUE` if the PopupMenu is being executed,
 100             `FALSE` otherwise.
 101
 102         @see XPopupMenu::execute()
 103     */
 104     boolean isInExecute();
 105
 106     /** ends the execution of the PopupMenu.
 107         <p>com::sun::star::awt::XPopupMenu::execute()
 108         will then return 0.</p>
 109
 110         @see com::sun::star::awt::XPopupMenu::execute()
 111     */
 112     void endExecute();
 113
 114     /** sets the KeyEvent for the menu item.
 115
 116         <p>The KeyEvent is <b>only</b> used as a container to transport
 117         the shortcut information, this methods only draws the text corresponding to
 118         this keyboard shortcut. The client code is responsible for listening to
 119         keyboard events (typically done via XUserInputInterception),
 120         and dispatch the respective command.</p>
 121
 122         @param nItemId
 123             specifies the menu item identifier for which the KeyEvent should be set.
 124
 125         @param aKeyEvent
 126             specifies the KeyEvent for the menu item.
 127     */
 128     void setAcceleratorKeyEvent( [in] short nItemId,
 129                                  [in] KeyEvent aKeyEvent );
 130
 131     /** retrieves the KeyEvent for the menu item.
 132
 133         <p>The KeyEvent is <b>only</b> used as a container to transport
 134         the shortcut information, so that in this case
 135         ::com::sun::star::lang::EventObject::Source is NULL.</p>
 136
 137         @param nItemId
 138             specifies the menu item identifier for which the KeyEvent should be retrieved.
 139
 140         @return
 141             the KeyEvent struct assigned to the requested menu item.
 142     */
 143     KeyEvent getAcceleratorKeyEvent( [in] short nItemId );
 144
 145     /** sets the image for the menu item.
 146
 147         @param nItemId
 148             specifies the menu item identifier for which the image should be set.
 149
 150         @param xGraphic
 151             specifies the image for the menu item.
 152
 153         @param bScale
 154             if `TRUE`, the image will be scaled to the standard size used internally by
 155             the implementation.
 156     */
 157     void setItemImage( [in] short nItemId,
 158                        [in] ::com::sun::star::graphic::XGraphic xGraphic,
 159                        [in] boolean bScale );
 160
 161     /** retrieves the image for the menu item.
 162
 163         @param nItemId
 164             specifies the menu item identifier for which the image should be retrieved.
 165
 166         @return
 167             a XGraphic reference to the current image for the requested menu item.
 168     */
 169     ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId );
 170
 171 };
 172
 173 }; }; }; };
 174
 175 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */