/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; fill-column: 100 -*- */
/*
 * 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/.
 */

#ifndef __com_sun_star_system_windows_XJumpList_idl__
#define __com_sun_star_system_windows_XJumpList_idl__

#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/lang/IllegalArgumentException.idl>
#include <com/sun/star/system/SystemShellExecuteException.idl>


module com { module sun { module star { module system { module windows {

/** Specifies an interface for adding custom jump lists to the task bar (Windows only)

    To add a new jump list, call
    1. XJumpList::beginList
    2. XJumpList::appendCategory / XJumpList::addTasks / XJumpList::showRecentFiles / XJumpList::showFrequentFiles
    3. XJumpList::commitList

    Use XJumpList::abortList to cancel a current list building session.
    Use XJumpList::getRemovedItems to see which items were removed by the user.

    @since LibreOffice 7.4
*/
interface XJumpList: com::sun::star::uno::XInterface
{
    /**
       Start a new jump list.

       @param application
        Used to map the jump list to the correct application. Use one of the following values:
        <ul>
            <li>Writer</li>
            <li>Calc</li>
            <li>Impress</li>
            <li>Draw</li>
            <li>Math</li>
            <li>Base</li>
            <li>Startcenter</li>
        </ul>

        "Startcenter" will map to the generic "LibreOffice" icon.

        @throws com::sun::star::lang::IllegalArgumentException
        When `application` is invalid

        @throws com::sun::star::util::InvalidStateException
        When there is already an open list.
     */
    void beginList([in] string application)
        raises( ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::util::InvalidStateException );

    /** Add a jump list category.

        Users can pin or remove items added via this method.
        Use XJumpList::getRemovedItems to see which items were removed by the user.

        @param category
        Specifies the category name. It will appear as the title of the custom jump list.
        Must not include embedded NULs ('\\0')

        @param jumpListItems
        Specifies a list of com::sun::star::system::JumpListItem.
        Must contain at least one item.
        These will be added as entries below the category name in the custom jump list.

        Make sure you don't add items which the user has removed before
        (check the result of `getRemovedItems` before updating a category).
        If you try to add items which the user removed before,
        they will be silently ignored and not added to the list.

        @throws com::sun::star::lang::IllegalArgumentException
        When one of the following applies:
        <ul>
            <li>`category` is empty</li>
            <li>`jumpListItems` is empty or contains only items which were removed by the user</li>
        </ul>

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
    */
    void appendCategory( [in] string category,
                         [in] sequence<com::sun::star::system::windows::JumpListItem> jumpListItems )
        raises( ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::util::InvalidStateException );

    /** Add items to the "Tasks" category. This category is system-defined and the category title cannot be changed.
        Also the user cannot remove or pin items from this category (as he can with items added via XJumpList::appendCategory ).

        @param jumpListItems
        Specifies a list of com::sun::star::system::JumpListItem.
        Must contain at least one item.
        These will be added as entries below the "Tasks" system category.

        @throws com::sun::star::lang::IllegalArgumentException
        When `jumpListItems` is empty

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
    */
    void addTasks([in] sequence<com::sun::star::system::windows::JumpListItem> jumpListItems)
        raises( ::com::sun::star::lang::IllegalArgumentException, ::com::sun::star::util::InvalidStateException );

    /** Display the recently used files (populated by LibreOffice)

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
     */
    void showRecentFiles()
        raises (::com::sun::star::util::InvalidStateException);

    /** Display the frequently used files (populated by LibreOffice)

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
     */
    void showFrequentFiles()
        raises (::com::sun::star::util::InvalidStateException);

    /**
        Commits the list.

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
     */
    void commitList()
        raises( ::com::sun::star::util::InvalidStateException );

    /**
        Aborts a list building session started with beginList.

        @throws com::sun::star::util::InvalidStateException
        When there is no open list.
     */
    void abortList()
        raises( ::com::sun::star::util::InvalidStateException );

    /** Deletes the Jump List for a certain application

        @param application
        Used to map the jump list to the correct application. Use one of the following values:
        <ul>
            <li>Writer</li>
            <li>Calc</li>
            <li>Impress</li>
            <li>Draw</li>
            <li>Math</li>
            <li>Base</li>
            <li>Startcenter</li>
        </ul>

        "Startcenter" will map to the generic "LibreOffice" icon.

        @throws com::sun::star::lang::IllegalArgumentException
        When `application` is invalid
    */
    void deleteList( [in] string application )
        raises( ::com::sun::star::lang::IllegalArgumentException );

    /** Returns items that were removed from the jump list by the user.

        `appendCategory` will ignore items which were removed by the user before.
        Use this method to learn which items were removed by the user.

        @param application
        Used to map the jump list to the correct application. Use one of the following values:
        <ul>
            <li>Writer</li>
            <li>Calc</li>
            <li>Impress</li>
            <li>Draw</li>
            <li>Math</li>
            <li>Base</li>
            <li>Startcenter</li>
        </ul>

        "Startcenter" will map to the generic "LibreOffice" icon.

        @return List of removed items.
    */
    sequence<com::sun::star::system::windows::JumpListItem> getRemovedItems([in] string application);
};


}; }; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab cinoptions=b1,g0,N-s cinkeys+=0=break: */