office-gobmx/offapi/com/sun/star/awt/XPopupMenuExtended.idl

/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/
#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 <type scope="com::sun::star::awt">PopupMenu</type>.

    @since OOo 3.1
 */
published interface XPopupMenuExtended
{
    /** specifies basic functions for a pop-up 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 method only draws the text corresponding to
        this keyboard shortcut. The client code is responsible for listening to
        keyboard events (typically 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