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

#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif

#ifndef __com_sun_star_awt_XPopupMenu_idl__
#include <com/sun/star/awt/XPopupMenu.idl>
#endif

#ifndef __com_sun_star_awt_XMenuExtended2_idl__
#include <com/sun/star/awt/XMenuExtended2.idl>
#endif

#ifndef __com_sun_star_awt_MenuLogo_idl__
#include <com/sun/star/awt/MenuLogo.idl>
#endif

#ifndef __com_sun_star_container_NoSuchElementException_idl__
#include <com/sun/star/container/NoSuchElementException.idl>
#endif

#ifndef __com_sun_star_awt_KeyEvent_idl__
#include <com/sun/star/awt/KeyEvent.idl>
#endif

#ifndef com_sun_star_graphic_XGraphic_idl
#include <com/sun/star/graphic/XGraphic.idl>
#endif

//=============================================================================

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

/** specifies extended functions for a <type scope="com::sun::star::awt">PopupMenu</type>.

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

    /** specifies extended menu functions, available for both
        <type scope="com::sun::star::awt">MenuBar</type> and
        <type scope="com::sun::star::awt">PopupMenu</type>.
    */
    interface ::com::sun::star::awt::XMenuExtended2;

    //=========================================================================

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

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

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

        @since OOo 3.1
    */
    boolean isInExecute();

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

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

        @since OOo 3.1
    */
    void endExecute();

    //=============================================================================

    /** sets the <type>MenuLogo</type> for this <type>PopupMenu</type>.

        @param aMenuLogo
            the <type>MenuLogo</type>.

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

    /** retrieves the <type>MenuLogo</type> for this <type>PopupMenu</type>.

        @return
            the <type>MenuLogo</type>.

        @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 <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.

        @throws <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <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.

        @throws <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="::com::sun::star::graphic::">XGraphic</type> reference
            to the current image for the requested menu item.

        @throws <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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 <type scope="com::sun::star::container">NoSuchElementException</type>
            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