/**************************************************************
 *
 * 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
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/

#ifndef __com_sun_star_awt_XPopupMenu_idl__
#define __com_sun_star_awt_XPopupMenu_idl__

#include <com/sun/star/awt/KeyEvent.idl>
#include <com/sun/star/awt/Rectangle.idl>
#include <com/sun/star/awt/XMenu.idl>
#include <com/sun/star/graphic/XGraphic.idl>

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

published interface XWindowPeer;

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

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

    /** sets the menu default item.

        @param nItemId
            specifies the menu item identifier.
     */
    [oneway] 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/>).
     */
    [oneway] 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 <type>Rectangle</type> 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 <type>PopupMenuDirection</type> 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 <type>PopupMenu</type> is being.

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

        @return
            <TRUE/> if the <type>PopupMenu</type> is being executed,
            <FALSE/> otherwise.

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

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

        @see <member scope="com::sun::star::awt">XPopupMenu::execute()</member>
    */
    void endExecute();

    /** sets the <type>KeyEvent</type> for the menu item.

        <p>The <type>KeyEvent</type> 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 (typicaly done via <type>XUserInputInterception</type>),
        and dispatch the respective command.</p>

        @param nItemId
            specifies the menu item identifier for which the <type>KeyEvent</type> should be set.

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

    /** retrieves the <type>KeyEvent</type> for the menu item.

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

        @param nItemId
            specifies the menu item identifier for which the <type>KeyEvent</type> should be retrieved.

        @return
            the <type>KeyEvent</type> 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 <type scope="::com::sun::star::graphic::">XGraphic</type> reference
            to the current image for the requested menu item.
    */
    ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId );

};

}; }; }; };

#endif