/* -*- 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 .
 */
#ifndef __com_sun_star_awt_XPopupMenuExtended_idl__
#define __com_sun_star_awt_XPopupMenuExtended_idl__

#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/awt/XPopupMenu.idl>
#include <com/sun/star/awt/XMenuExtended2.idl>
#include <com/sun/star/awt/MenuLogo.idl>
#include <com/sun/star/container/NoSuchElementException.idl>
#include <com/sun/star/awt/KeyEvent.idl>
#include <com/sun/star/graphic/XGraphic.idl>


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

/** specifies extended functions for a com::sun::star::awt::PopupMenu.

    @since OOo 3.1
 */
interface XPopupMenuExtended
{
    /** specifies basic functions for a pop-up menu.
    */
    interface ::com::sun::star::awt::XPopupMenu;

    /** specifies extended menu functions, available for both
        com::sun::star::awt::MenuBar and
        com::sun::star::awt::PopupMenu.
    */
    interface ::com::sun::star::awt::XMenuExtended2;


    /** queries if the com::sun::star::awt::PopupMenu
        is being executed as a result of invoking
        com::sun::star::awt::XPopupMenu::execute(); that is,
        for a PopupMenu activated by a MenuBar item,
        this methods returns <FALSE/>.

        @return
            <TRUE/> if the com::sun::star::awt::PopupMenu
            is being executed, <FALSE/> otherwise.

        @see com::sun::star::awt::XPopupMenu::execute()

        @since OOo 3.1
    */
    boolean isInExecute();

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

        @see com::sun::star::awt::XPopupMenu::execute()

        @since OOo 3.1
    */
    void endExecute();


    /** sets the MenuLogo for this PopupMenu.

        @param aMenuLogo
            the MenuLogo.

        @since OOo 3.1
    */
    void setLogo( [in] ::com::sun::star::awt::MenuLogo aMenuLogo );

    /** retrieves the MenuLogo for this PopupMenu.

        @return
            the MenuLogo.

        @since OOo 3.1
    */
    ::com::sun::star::awt::MenuLogo getLogo();




    /** specifies whether mnemonics are automatically assigned to menu items, or not.

        @param bEnable
            if <TRUE/>, mnemonics are automatically assigned to menu items.
    */
    void enableAutoMnemonics( [in] boolean bEnable );



    /** sets the KeyEvent for the menu item.

        <p>The KeyEvent is <b>only</b> used as a container to transport
        the shortcut information, this method 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.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setAcceleratorKeyEvent( [in] short nItemId, [in] ::com::sun::star::awt::KeyEvent aKeyEvent )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** 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.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    ::com::sun::star::awt::KeyEvent getAcceleratorKeyEvent( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );


    /** sets the help text for the menu item.

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

        @param sHelpText
            specifies the help text for the menu item.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setHelpText( [in] short nItemId, [in] string sHelpText )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** retrieves the help text for the menu item.

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

        @return
            a string with the help text.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    string getHelpText( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );


    /** sets the tip help text for the menu item.

        @param nItemId
            specifies the menu item identifier for which the tip help text should be set.

        @param sTipHelpText
            specifies the tip help text for the menu item.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setTipHelpText( [in] short nItemId, [in] string sTipHelpText )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** retrieves the tip help text for the menu item.

        @param nItemId
            specifies the menu item identifier for which the tip help text should be retrieved.

        @return
            a string with the tip help text.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    string getTipHelpText( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );


    /** 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.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setItemImage(      [in] short nItemId,
                            [in] ::com::sun::star::graphic::XGraphic xGraphic,
                            [in] boolean bScale )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** retrieves the image for the menu item.

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

        @return
            a ::com::sun::star::graphic::::XGraphic reference
            to the current image for the requested menu item.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    ::com::sun::star::graphic::XGraphic getItemImage( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );

    //.............................................................................


    /** sets the rotation angle of a menu item image.

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

        @param nAngle
            specifies the rotation angle for the menu item image.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setItemImageAngle( [in] short nItemId, [in] long nAngle )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** retrieves the rotation angle of a menu item image.

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

        @return the rotation angle of the menu item image, or 0 if it has no rotation.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    long getItemImageAngle( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );

    //.............................................................................

    /** sets the mirror mode of a menu item image.

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

        @param bMirror
            if <TRUE/>, the item image is mirrored.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    void setItemImageMirrorMode( [in] short nItemId, [in] boolean bMirror )
        raises ( ::com::sun::star::container::NoSuchElementException );

    /** indicates whether the menu item image is mirrored.

        @param nItemId
            specifies the menu item identifier for which the image mirror mode should be checked.

        @return <TRUE/> if the item image is mirrored, <FALSE/> otherwise.

        @throws com::sun::star::container::NoSuchElementException
            if there is no menu item with the identifier specified in <var>nItemId</var>.

        @since OOo 3.1
    */
    boolean isItemImageInMirrorMode( [in] short nItemId )
        raises ( ::com::sun::star::container::NoSuchElementException );

};

}; }; }; };

#endif

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