704 lines
20 KiB
Objective-C
704 lines
20 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// 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_DESTIONATION
|
|
};
|
|
|
|
/**
|
|
@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_DESTIONATION,
|
|
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);
|
|
};
|