wxWidgets/interface/wx/taskbarbutton.h

/////////////////////////////////////////////////////////////////////////////
// Name:        taskbarbutton.h
// Purpose:     Interface of taskbar buttons features.
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    State of the taskbar button.
    @since 3.1.0
*/
enum wxTaskBarButtonState
{
    wxTASKBAR_BUTTON_NO_PROGRESS   = 0,
    wxTASKBAR_BUTTON_INDETERMINATE = 1,
    wxTASKBAR_BUTTON_NORMAL        = 2,
    wxTASKBAR_BUTTON_ERROR         = 4,
    wxTASKBAR_BUTTON_PAUSED        = 8
};

/**
    @class wxThumbBarButton

    A thumbnail toolbar button is a control that displayed in the thumbnail
    image of a window in a taskbar button flyout.

    @library{wxcore}
    @category{misc}

    @onlyfor{wxmsw}

    @see wxTaskBarButton
    @since 3.1.0
*/
class WXDLLIMPEXP_CORE wxThumbBarButton {
public:
    /**
        Default constructor to allow 2-phase creation.
    */
    wxThumbBarButton();

    /**
        Constructs the thumbnail toolbar button.

        @param id
            The identifier for the control.
        @param icon
            The icon used as the button image.
        @param tooltip
            The text of the button's tooltip, displayed when the mouse pointer
            hovers over the button.
        @param enable
            If @true (default), the button is active and available to the user.
            If @false, the button is disabled. It is present, but has a visual
            state that indicates that it will not respond to user action.
        @param dismissOnClick
            If @true, when the button is clicked, the taskbar button's flyout
            closes immediately. @false by default.
        @param hasBackground
            If @false, the button border is not drawn. @true by default.
        @param shown
            If @false, the button is not shown to the user. @true by default.
        @param interactive
            If @false, the button is enabled but not interactive; no pressed
            button state is drawn. This flag is intended for instances where
            the button is used in a notification. @true by default.
    */
    wxThumbBarButton(int id,
                     const wxIcon& icon,
                     const wxString& tooltip = wxString(),
                     bool enable = true,
                     bool dismissOnClick = false,
                     bool hasBackground = true,
                     bool shown = true,
                     bool interactive = true);

    bool Create(int id,
                const wxIcon& icon,
                const wxString& tooltip = wxString(),
                bool enable = true,
                bool dismissOnClick = false,
                bool hasBackground = true,
                bool shown = true,
                bool interactive = true);

    virtual ~wxThumbBarButton();

    /**
        Returns the identifier associated with this control.
    */
    int GetID() const;

    /**
        Returns the icon associated with this control.
    */
    const wxIcon& GetIcon() const;

    /**
        Returns the tooltip.
    */
    const wxString& GetTooltip() const;

    /**
        Returns @true if the button is enabled, @false if it has been disabled.
    */
    bool IsEnable() const;

    /**
        Enables or disables the thumbnail toolbar button.
    */
    void Enable(bool enable = true);

    /**
        Equivalent to calling wxThumbBarButton::Enable(false).
    */
    void Disable();

    /**
        Returns @true if the button will dismiss on click.
    */
    bool IsDismissOnClick() const;

    /**
        Whether the window thumbnail is dismissed after a button click.
    */
    void EnableDismissOnClick(bool enable = true);

    /**
        Equivalent to calling wxThumbBarButton::DisableDimissOnClick(false).
    */
    void DisableDimissOnClick();

    /**
        Returns @true if the button has button border.
    */
    bool HasBackground() const;

    /**
        Set the property that whether the button has background.
    */
    void SetHasBackground(bool has = true);

    /**
        Returns @true if the button is shown, @false if it has been hidden.
    */
    bool IsShown() const;

    /**
        Show or hide the thumbnail toolbar button.
    */
    void Show(bool shown = true);

    /**
        Hide the thumbnail toolbar button. Equivalent to calling wxThumbBarButton::Show(false).
    */
    void Hide();

    /**
        Returns @true if the button is interactive.
    */
    bool IsInteractive() const;

    /**
        Set the property which holds whether the button is interactive.

        A non-interactive thumbnail toolbar button does not react to user
        interaction, but is still visually enabled.
    */
    void SetInteractive(bool interactive = true);
};

/**
    @class wxTaskBarButton

    A taskbar button that associated with the window under Windows 7 or later.

    It is used to access the functionality including thumbnail representations,
    thumbnail toolbars, notification and status overlays, and progress
    indicators.

    @note This class is only created and initialized in the internal implementation
    of wxFrame by design. You can only get the pointer of the instance which
    associated with the frame by calling wxFrame::MSWGetTaskBarButton().

    @library{wxcore}
    @category{misc}

    @nativeimpl{wxmsw}
    @onlyfor{wxmsw}

    @see wxFrame::MSWGetTaskBarButton()
    @since 3.1.0
*/
class WXDLLIMPEXP_CORE wxTaskBarButton
{
public:
    /**
        Starts showing a determinate progress indicator.

        Call SetProgressValue() after this call to update the progress
        indicator.

        If @a range is 0, the progress indicator is dismissed.
    */
    virtual void SetProgressRange(int range);

    /**
        Update the progress indicator, setting the progress to the new value .

        @param value Must be in the range from 0 to the argument to the last
        SetProgressRange() call. When it is equal to the range, the progress
        bar is dismissed.
    */
    virtual void SetProgressValue(int value);

    /**
        Makes the progress indicator run in indeterminate mode.

        The first call to this method starts showing the indeterminate progress
        indicator if it hadn't been shown yet.

        Call SetProgressRange(0) to stop showing the progress indicator.
    */
    virtual void PulseProgress();

    /**
        Show in the taskbar.
    */
    virtual void Show(bool show = true);

    /**
        Hide in the taskbar.
    */
    virtual void Hide();

    /**
        Specifies or updates the text of the tooltip that is displayed
        when the mouse pointer rests on an individual preview thumbnail
        in a taskbar button flyout.
    */
    virtual void SetThumbnailTooltip(const wxString& tooltip);

    /**
        Set the state of the progress indicator displayed on a taskbar button.

        @see wxTaskBarButtonState
    */
    virtual void SetProgressState(wxTaskBarButtonState state);

    /**
        Set an overlay icon to indicate application status or a notification top
        the user.

        @param icon
            This should be a small icon, measuring 16x16 pixels at 96 dpi. If an
            overlay icon is already applied to the taskbar button, that existing
            overlay is replaced. Setting with wxNullIcon to remove.
        @param description
            The property holds the description of the overlay for accessibility
            purposes.
    */
    virtual void SetOverlayIcon(const wxIcon& icon,
                                const wxString& description = wxString());

    /**
        Selects a portion of a window's client area to display as that window's
        thumbnail in the taskbar.

        @param  rect
            The portion inside of the window. Setting with an empty wxRect will
            restore the default display of the thumbnail.
    */
    virtual void SetThumbnailClip(const wxRect& rect);

    /**
        Selects the child window area to display as that window's thumbnail in
        the taskbar.
    */
    virtual void SetThumbnailContents(const wxWindow *child);

    /**
        Inserts the given button before the position pos to the taskbar
        thumbnail toolbar.

        @note The number of buttons and separators is limited to 7.

        @see AppendThumbBarButton(), AppendSeparatorInThumbBar()
    */
    virtual bool InsertThumbBarButton(size_t pos, wxThumbBarButton *button);

    /**
        Appends a button to the taskbar thumbnail toolbar.

        @note The number of buttons and separators is limited to 7.

        @see InsertThumbBarButton(), AppendSeparatorInThumbBar()
    */
    virtual bool AppendThumbBarButton(wxThumbBarButton *button);

    /**
        Appends a separator to the taskbar thumbnail toolbar.

        @note The number of buttons and separators is limited to 7.

        @see AppendThumbBarButton(), InsertThumbBarButton()
    */
    virtual bool AppendSeparatorInThumbBar();

    /**
        Removes the thumbnail toolbar button from the taskbar button but doesn't
        delete the associated c++ object.

        @param button
            The thumbnail toolbar button to remove.

        @return A pointer to the button which was detached from the taskbar
            button.
    */
    virtual wxThumbBarButton* RemoveThumbBarButton(wxThumbBarButton *button);

    /**
        Removes the thumbnail toolbar button from the taskbar button but doesn't
        delete the associated c++ object.

        @param id
            The identifier of the thumbnail toolbar button to remove.

        @return A pointer to the button which was detached from the taskbar
            button.
    */
    virtual wxThumbBarButton* RemoveThumbBarButton(int id);
};

/**
    Type of jump list item.

    @since 3.1.0
*/
enum wxTaskBarJumpListItemType
{
    /** A separator, Only tasks category supports separators. */
    wxTASKBAR_JUMP_LIST_SEPARATOR,

    /** A task, represents a link to application. */
    wxTASKBAR_JUMP_LIST_TASK,

    /** Item acts as a link to a file that the application can open. */
    wxTASKBAR_JUMP_LIST_DESTINATION
};

/**
    @class wxTaskBarJumpListItem

    A wxTaskBarJumpListItem represents an item in a jump list category.

    @library{wxcore}
    @category{misc}

    @onlyfor{wxmsw}
    @since 3.1.0
*/
class WXDLLIMPEXP_CORE wxTaskBarJumpListItem
{
public:
    /**
        Constructs a jump list item.

        @param parentCategory
            Category that the jump list item belongs to. Can be NULL if the item
            is going to be added to the category later.
        @param type
            The type for this item.
        @param title
            The title of this item.
        @param filePath
            The filePath of this item, the meaning of which depends on the type
            of this item: If the item type is wxTASKBAR_JUMP_LIST_DESTINATION,
            filePath is the path to a file that can be opened by an application.
            If the item type is wxTASKBAR_JUMP_LIST_TASK, filePath is the path
            to an executable that is executed when this item is clicked by the
            user.
        @param arguments
            The command-line arguments of this item.
        @param tooltip
            The description tooltip of this item.
        @param iconPath
            The path to the file containing the icon.
        @param iconIndex
            The index of the icon, which is specified by iconPath.
    */
    wxTaskBarJumpListItem(wxTaskBarJumpListCategory *parentCategory = NULL,
        wxTaskBarJumpListItemType type = wxTASKBAR_JUMP_LIST_SEPARATOR,
        const wxString& title = wxEmptyString,
        const wxString& filePath = wxEmptyString,
        const wxString& arguments = wxEmptyString,
        const wxString& tooltip = wxEmptyString,
        const wxString& iconPath = wxEmptyString,
        int iconIndex = 0);

    /**
        Returns the type of this item.
    */
    wxTaskBarJumpListItemType GetType() const;

    /**
        Sets the type of this item.
    */
    void SetType(wxTaskBarJumpListItemType type);

    /**
        Returns the title of this item.
    */
    const wxString& GetTitle() const;

    /**
        Sets the title of this item.
    */
    void SetTitle(const wxString& title);

    /**
        Returns the file path of this item.
    */
    const wxString& GetFilePath() const;

    /**
        Sets the file path of this item.
    */
    void SetFilePath(const wxString& filePath);

    /**
        Returns the command-line arguments of this item.
    */
    const wxString& GetArguments() const;

    /**
        Sets the command-line arguments of this item.
    */
    void SetArguments(const wxString& arguments);

    /**
        Returns the description tooltip of this item.
    */
    const wxString& GetTooltip() const;

    /**
        Sets the description tooltip of this item.
    */
    void SetTooltip(const wxString& tooltip);

    /**
        Returns the icon path of this item.
    */
    const wxString& GetIconPath() const;

    /**
        Sets the icon path of this item.
    */
    void SetIconPath(const wxString& iconPath);

    /**
        Returns the icon index of icon in this item.
    */
    int GetIconIndex() const;

    /**
        Sets the icon index of icon in this item.
    */
    void SetIconIndex(int iconIndex);

    /**
        Returns the category this jump list item is in, or NULL if this jump
        list item is not attached.
    */
    wxTaskBarJumpListCategory* GetCategory() const;

    /**
        Sets the parent category which will contain this jump list item.
    */
    void SetCategory(wxTaskBarJumpListCategory *category);
};

/**
    A vector of wxTaskBarJumpListItem pointers.

    @since 3.1.0
*/
typedef wxVector<wxTaskBarJumpListItem*> wxTaskBarJumpListItems;

/**
    @class wxTaskBarJumpListCategory

    This class represents a category of jump list in the taskbar button. There
    are four kinds of categories in Windows: Recent, Frequent, Tasks and
    custom.

    @library{wxcore}
    @category{misc}

    @onlyfor{wxmsw}

    @see wxTaskBarJumpList, wxTaskBarJumpListItem

    @since 3.1.0
*/
class WXDLLIMPEXP_CORE wxTaskBarJumpListCategory
{
public:
    /**
        Constructs the jump list category.

        @param parent
            Jump list that the jump list category belongs to. Can be NULL if
            the category is going to be added to the jump list later.
        @param title
            The title of the category.
    */
    wxTaskBarJumpListCategory(wxTaskBarJumpList *parent = NULL,
                              const wxString& title = wxEmptyString);
    virtual ~wxTaskBarJumpListCategory();

    /**
        Appends a jump list item.

        @param item
            The jump list item to be appended. It will be owned by the
            wxTaskBarJumpListCategory object after this function is called, so
            do not delete it yourself.

        @see Insert(), Prepend()
    */
    wxTaskBarJumpListItem* Append(wxTaskBarJumpListItem *item);

    /**
        Deletes the jump list item from the category.

        @param item
            The jump list item to be deleted.

        @see Remove()
    */
    void Delete(wxTaskBarJumpListItem *item);

    /**
        Removes the jump list item from the category but doesn't delete the
        associated C++ object.

        @param item
            The jump list item to be removed.
    */
    wxTaskBarJumpListItem* Remove(wxTaskBarJumpListItem *item);

    /**
        Returns the wxTaskBarJumpListItem given a position in the category.
    */
    wxTaskBarJumpListItem* FindItemByPosition(size_t pos) const;

    /**
        Inserts the given item before the position pos.

        @see Append(), Prepend()
    */
    wxTaskBarJumpListItem* Insert(size_t pos, wxTaskBarJumpListItem *item);

    /**
        Inserts the given item at position 0, i.e. before all the other existing
        items.

        @see Append(), Insert();
    */
    wxTaskBarJumpListItem* Prepend(wxTaskBarJumpListItem *item);

    /**
        Sets the title of the category.
    */
    void SetTitle(const wxString& title);

    /**
        Gets the title of the category.
    */
    const wxString& GetTitle() const;

    /**
        Gets the jump list items of the category.
    */
    const wxTaskBarJumpListItems& GetItems() const;
};

/**
    A vector of wxTaskBarJumpListCategory pointers.
*/
typedef wxVector<wxTaskBarJumpListCategory*> wxTaskBarJumpListCategories;

/**
    @class wxTaskBarJumpList

    This class is an transparent wrapper around Windows Jump Lists. Jump
    Lists, as an new feature since Windows 7, are lists of recently opened
    items, such as files, folders, or websites, which are organized by the
    program that the user use to open them. Jump Lists don't just show
    shortcuts to files. Sometimes they can also provide quick access to tasks.
    With this class, you can access the recent and frequent category in the
    jump lists. You can also set the tasks category of the Jump Lists of your
    application. What's more, you can add custom category to them.

    @library{wxcore}
    @category{misc}

    @onlyfor{wxmsw}

    @see wxTaskBarJumpListCategory, wxTaskBarJumpListItem
    @since 3.1.0
*/
class WXDLLIMPEXP_CORE wxTaskBarJumpList
{
public:
    /**
        Constructs the jump list.

        @param appID
            Specifies a unique identifier for the application jump list, can be
            empty by default.

            See <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx">
            Application User Model IDs</a> on MSDN for further details.
    */
    wxTaskBarJumpList(const wxString& appID = wxEmptyString);
    virtual ~wxTaskBarJumpList();

    /**
        Shows or hides the recent category.
    */
    void ShowRecentCategory(bool shown = true);

    /**
        Hides the recent category. Equivalent to calling wxTaskBarJumpList::ShowFrequentCategory(false).
    */
    void HideRecentCategory();

    /**
        Shows or hides the frequent category.
    */
    void ShowFrequentCategory(bool shown = true);

    /**
        Hides the frequent category. Equivalent to calling wxTaskBarJumpList::ShowFrequentCategory(false).
    */
    void HideFrequentCategory();

    /**
        Accesses the built in tasks category.

        With the returned tasks category, you can append an new task, remove
        an existing task, modify the task item etc.
    */
    wxTaskBarJumpListCategory& GetTasks() const;

    /**
        Gets the built in frequent category.

        Note that the returned category is read-only.
    */
    const wxTaskBarJumpListCategory& GetFrequentCategory() const;

    /**
        Gets the built in recent category.

        Note that the returned category is read-only.

    */
    const wxTaskBarJumpListCategory& GetRecentCategory() const;

    /**
        Gets the custom categories.
    */
    const wxTaskBarJumpListCategories& GetCustomCategories() const;

    /**
        Add an new custom category.

        @param category
            A wxTaskBarJumpListCategory object. It will be owned by the
            wxTaskBarJumpList object after this function is called, so
            do not delete it yourself.
    */
    void AddCustomCategory(wxTaskBarJumpListCategory* category);

    /**
        Removes the custom category from the jump lists but doesn't delete the
        associated C++ object.

        @param title
            The title of the custom category.
    */
    wxTaskBarJumpListCategory* RemoveCustomCategory(const wxString& title);

    /**
        Deletes the custom category from the jump lists.

        @param title
            The title of the custom category.
    */
    void DeleteCustomCategory(const wxString& title);
};