/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

module com {  module sun {  module star {  module awt {

published interface XWindowPeer;

/** controls a pop-up menu.
 */
published interface XPopupMenu: XMenu
{
    /** inserts a separator at the specified position.

        @param nItemPos
            specifies the position where the menu separator will be inserted.
     */
    void insertSeparator( [in] short nItemPos );

    /** sets the menu default item.

        @param nItemId
            specifies the menu item identifier.
     */
    void setDefaultItem( [in] short nItemId );

    /** returns the menu default item.

        @return
            the ID of the default item.
     */
    short getDefaultItem();

    /** sets the state of the item to be checked or unchecked.

        @param nItemId
            specifies the menu item identifier.

        @param bCheck
            specifies if the item is checked (`TRUE`) or unchecked (`FALSE`).
     */
    void checkItem( [in] short nItemId,
                             [in] boolean bCheck );

    /** returns whether the item is checked or unchecked.

        @param nItemId
            specifies the menu item identifier.

        @return
            `TRUE` if the item is checked, `FALSE` otherwise.
     */
    boolean isItemChecked( [in] short nItemId );

    /** executes the popup menu and returns the selected item
        or <code>0</code>, if cancelled.

        @param Parent
            the parent window.

        @param Position
            a Rectangle representing the coordinates system
            where the popup menu should be executed.

        @param Direction
            the direction in which a popup menu will grow, as specified
            by one of the PopupMenuDirection constants.

        @return
            returns the selected item or <code>0</code>, if cancelled.
     */
    short execute( [in] XWindowPeer Parent,
                   [in] Rectangle Position,
                   [in] short Direction );

    /** queries if the PopupMenu is being.

        <p>Returns `TRUE` only if the PopupMenu is being executed
        as a result of invoking XPopupMenu::execute(); that is,
        for a PopupMenu activated by a MenuBar item,
        this methods returns `FALSE`.</p>

        @return
            `TRUE` if the PopupMenu is being executed,
            `FALSE` otherwise.

        @see XPopupMenu::execute()
    */
    boolean isInExecute();

    /** ends the execution of the PopupMenu.
        <p>com::sun::star::awt::XPopupMenu::execute()
        will then return 0.</p>

        @see com::sun::star::awt::XPopupMenu::execute()
    */
    void endExecute();

    /** sets the KeyEvent for the menu item.

        <p>The KeyEvent is <b>only</b> used as a container to transport
        the shortcut information, this methods only draws the text corresponding to
        this keyboard shortcut. The client code is responsible for listening to
        keyboard events (typically done via XUserInputInterception),
        and dispatch the respective command.</p>

        @param nItemId
            specifies the menu item identifier for which the KeyEvent should be set.

        @param aKeyEvent
            specifies the KeyEvent for the menu item.
    */
    void setAcceleratorKeyEvent( [in] short nItemId,
                                 [in] KeyEvent aKeyEvent );

    /** retrieves the KeyEvent for the menu item.

        <p>The KeyEvent is <b>only</b> used as a container to transport
        the shortcut information, so that in this case
        ::com::sun::star::lang::EventObject::Source is NULL.</p>

        @param nItemId
            specifies the menu item identifier for which the KeyEvent should be retrieved.

        @return
            the KeyEvent struct assigned to the requested menu item.
    */
    KeyEvent getAcceleratorKeyEvent( [in] short nItemId );

    /** sets the image for the menu item.

        @param nItemId
            specifies the menu item identifier for which the image should be set.

        @param xGraphic
            specifies the image for the menu item.

        @param bScale
            if `TRUE`, the image will be scaled to the standard size used internally by
            the implementation.
    */
    void setItemImage( [in] short nItemId,
                       [in] ::com::sun::star::graphic::XGraphic xGraphic,
                       [in] boolean bScale );

    /** retrieves the image for the menu item.

        @param nItemId
            specifies the menu item identifier for which the image should be retrieved.

        @return
            a XGraphic reference to the current image for the requested menu item.
    */
    ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId );

};

}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */