CMFCTasksPane Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CMFCTasksPane Class.
INCLUDEcpp_fp_under_construction]
The CMFCTasksPane class implements a list of clickable items (tasks).
Syntax
class CMFCTasksPane : public CDockablePane
Members
Public Constructors
| Name | Description |
|---|---|
| CMFCTasksPane::CMFCTasksPane | Constructs a CMFCTasksPane object. |
Public Methods
| Name | Description |
|---|---|
| CMFCTasksPane::AddGroup | Adds a new group of tasks to the task pane control. |
| CMFCTasksPane::AddLabel | Adds a new static label into the specified task group. |
| CMFCTasksPane::AddMRUFilesList | Adds tasks specified by a Most Recently Used (MRU) file list into a group. |
| CMFCTasksPane::AddPage | Adds a new page to the task pane. |
| CMFCTasksPane::AddSeparator | |
| CMFCTasksPane::AddTask | Adds a new task to the specified task group. |
| CMFCTasksPane::AddWindow | Adds a child window to the task pane. |
| CMFCTasksPane::CollapseAllGroups | |
| CMFCTasksPane::CollapseGroup | Programmatically collapses a group. |
| CMFCTasksPane::CreateDefaultMiniframe | (Overrides CPane::CreateDefaultMiniframe.) |
| CMFCTasksPane::CreateMenu | Called by the framework to create a menu for the Other Tasks Panes menu button. |
| CMFCTasksPane::EnableAnimation | Enables or disables animation while collapsing or expanding task groups. |
| CMFCTasksPane::EnableGroupCollapse | Specifies whether tasks groups can be collapsed. |
| CMFCTasksPane::EnableHistoryMenuButtons | Enables or disables drop-down menus in Next and Previous navigation buttons. |
| CMFCTasksPane::EnableNavigationToolbar | Enables or disables the navigation toolbar. |
| CMFCTasksPane::EnableOffsetCustomControls | |
| CMFCTasksPane::EnableScrollButtons | Enables scroll buttons instead of a scrollbar. |
| CMFCTasksPane::EnableWrapLabels | Enables or disables word wrapping for labels. |
| CMFCTasksPane::EnableWrapTasks | Enables or disables word wrapping for tasks. |
| CMFCTasksPane::GetActivePage | Returns the zero-based index for the active page. |
| CMFCTasksPane::GetGroupCaptionHeight | Returns the height of the group captions. |
| CMFCTasksPane::GetGroupCaptionHorzOffset | Returns the current offset of a group caption from the left and right edges of the task pane. |
| CMFCTasksPane::GetGroupCaptionVertOffset | Returns the current offset of a group caption from the top and bottom edges of the task pane. |
| CMFCTasksPane::GetGroupCount | Returns the total number of groups. |
| CMFCTasksPane::GetGroupLocation | Returns the internal group index for a given group. |
| CMFCTasksPane::GetGroupVertOffset | Returns the vertical offset of a group. |
| CMFCTasksPane::GetHorzMargin | Returns the horizontal spacing between a task pane and the edges of the client area. |
| CMFCTasksPane::GetNextPages | |
| CMFCTasksPane::GetPageByGroup | Retrieves the page index for a specified group. |
| CMFCTasksPane::GetPagesCount | Returns the number of pages. |
| CMFCTasksPane::GetPreviousPages | |
| CMFCTasksPane::GetScrollBarCtrl | (Overrides CWnd::GetScrollBarCtrl.) |
| CMFCTasksPane::GetTask | Retrieves a task. |
| CMFCTasksPane::GetTaskCount | Returns the number of task items in a specified group. |
| CMFCTasksPane::GetTaskGroup | Returns a task group for a given group index. |
| CMFCTasksPane::GetTaskLocation | Returns the group and the index for a given task. |
| CMFCTasksPane::GetTasksHorzOffset | Returns the horizontal offset of tasks from the left and right edges of their parent groups. |
| CMFCTasksPane::GetTasksIconHorzOffset | |
| CMFCTasksPane::GetTasksIconVertOffset | |
| CMFCTasksPane::GetVertMargin | Returns the vertical spacing between a task pane and the edges of the client area. |
| CMFCTasksPane::IsAccessibilityCompatible | (Overrides CDockablePane::IsAccessibilityCompatible.) |
| CMFCTasksPane::IsAnimationEnabled | Indicates whether animation is enabled. |
| CMFCTasksPane::IsBackButtonEnabled | Indicates whether the back button is enabled. |
| CMFCTasksPane::IsForwardButtonEnabled | Indicates whether the forward button is enabled. |
| CMFCTasksPane::IsGroupCollapseEnabled | |
| CMFCTasksPane::IsHistoryMenuButtonsEnabled | Indicates whether the Next and Previous navigation buttons have drop-down menus. |
| CMFCTasksPane::IsNavigationToolbarEnabled | Indicates whether the navigation toolbar is enabled. |
| CMFCTasksPane::IsToolBox | |
| CMFCTasksPane::IsWrapLabelsEnabled | Indicates whether the task pane wraps words in labels. |
| CMFCTasksPane::IsWrapTasksEnabled | Indicates whether the task pane wraps words in tasks. |
| CMFCTasksPane::LoadState | (Overrides CDockablePane::LoadState.) |
| CMFCTasksPane::OnCancel | |
| CMFCTasksPane::OnClickTask | Called by the framework when the user clicks an item in the task pane. |
| CMFCTasksPane::OnOK | |
| CMFCTasksPane::OnPressBackButton | Called by the framework when the user clicks the back button. |
| CMFCTasksPane::OnPressForwardButton | Called by the framework when the user clicks the forward navigation button. |
| CMFCTasksPane::OnPressHomeButton | Called by the framework when the user clicks the home navigation button |
| CMFCTasksPane::OnPressOtherButton | |
| CMFCTasksPane::OnSetAccData | (Overrides CBasePane::OnSetAccData.) |
| CMFCTasksPane::OnUpdateCmdUI | (Overrides CDockablePane::OnUpdateCmdUI.) |
| CMFCTasksPane::PreTranslateMessage | (Overrides CDockablePane::PreTranslateMessage.) |
| CMFCTasksPane::RecalcLayout | (Overrides CPane::RecalcLayout.) |
| CMFCTasksPane::RemoveAllGroups | Removes all groups on the specified page. |
| CMFCTasksPane::RemoveAllPages | Removes all pages from the task pane except the default (first) page. |
| CMFCTasksPane::RemoveAllTasks | Removes all tasks from the group. |
| CMFCTasksPane::RemoveGroup | Removes a group. |
| CMFCTasksPane::RemovePage | Removes a specified page from the task pane. |
| CMFCTasksPane::RemoveTask | Removes a task from a task group. |
| CMFCTasksPane::SaveState | (Overrides CDockablePane::SaveState.) |
| CMFCTasksPane::Serialize | (Overrides CDockablePane::Serialize.) |
| CMFCTasksPane::SetActivePage | Activates a specified page in the task pane. |
| CMFCTasksPane::SetCaption | Sets the caption name of a task pane. |
| CMFCTasksPane::SetGroupCaptionHeight | Sets the height of a group caption. |
| CMFCTasksPane::SetGroupCaptionHorzOffset | Sets the horizontal offset of a group caption. |
| CMFCTasksPane::SetGroupCaptionVertOffset | Sets the vertical offset of a group caption. |
| CMFCTasksPane::SetGroupName | Sets a group name. |
| CMFCTasksPane::SetGroupTextColor | Sets the text color for a group caption. |
| CMFCTasksPane::SetGroupVertOffset | Sets the vertical offset for a group. |
| CMFCTasksPane::SetHorzMargin | Sets the horizontal spacing between a task pane and the edges of the client area. |
| CMFCTasksPane::SetIconsList | Sets the image list associated with tasks. |
| CMFCTasksPane::SetPageCaption | Sets the caption text for a task pane page. |
| CMFCTasksPane::SetTaskName | Sets the name for a task. |
| CMFCTasksPane::SetTasksIconHorzOffset | |
| CMFCTasksPane::SetTasksIconVertOffset | |
| CMFCTasksPane::SetTaskTextColor | Sets the text color for a task. |
| CMFCTasksPane::SetTasksHorzOffset | Sets the horizontal offset of tasks from the left and right edges of their parent groups. |
| CMFCTasksPane::SetVertMargin | Sets the vertical spacing between a task pane and the edges of the client area. |
| CMFCTasksPane::SetWindowHeight | Sets the height for a window. |
| CMFCTasksPane::ShowCommandMessageString | |
| CMFCTasksPane::ShowTask | Shows or hides a task. |
| CMFCTasksPane::ShowTaskByCmdId | Shows or hides a task based on its command ID. |
| CMFCTasksPane::Update | Updates the GUI elements that belong to a task pane. |
Protected Methods
| Name | Description |
|---|---|
| CMFCTasksPane::OnActivateTasksPanePage | Called by the framework when a new task pane page is activated. |
Remarks
The CMFCTasksPane class implements the following functionality:
Items can be grouped and each item grouping can have an associated caption.
Item groupings can be collapsed or expanded.
An icon can be assigned to each item in the task pane.
Individual items can be associated with a command ID which executes when a user clicks the item. When the click occurs, the
WM_COMMANDmessage is sent to the owner of the task pane control.
To use the CMFCTasksPane control in your application, follow these steps:
Embed a
CMFCTasksPaneobject into the main frame window class.When processing the
WM_CREATEmessage, call theCreatemethod. You can use the regular CControlBar styles. For more information, seeCControlBar::Create.Call the CMFCTasksPane::AddGroup method to add various groups.
Call the CMFCTasksPane::AddTask, CMFCTasksPane::AddLabel or CMFCTasksPane::AddMRUFilesList member functions to add new items (tasks) to each group.
Call CMFCTasksPane::EnableGroupCollapse to specify whether item groups can collapse.
The following illustration shows a typical task pane control. The first group is a special group and its caption is a darker color. The third group is collapsed. The last group is aligned to the bottom of the task pane and has no caption, and the last task in the group is a simple label:
.jpeg "Example of Task Pane")
You can customize the appearance of the task pane by adjusting various margins and offsets. The following illustration clarifies the meaning of these variables:
.jpeg "Custom task group")
Example
The following example demonstrates how to construct a CMFCTasksPane object and use various methods in the CMFCTasksPane class. The example shows how to enable the collapsing of task groups, enable the drop-down menus on the Next and Previous navigation buttons, enable the scroll buttons instead of a scroll bar, enable the word wrapping for the text in labels, set the caption name of the task pane, set the text color for a group caption, and set the horizontal and vertical margins.
CMFCTasksPane* tPane = new CMFCTasksPane();
tPane->EnableGroupCollapse(true);
tPane->EnableHistoryMenuButtons(true);
tPane->EnableScrollButtons(true);
tPane->EnableWrapLabels(true);
tPane->SetCaption(_T("Task Pane"));
tPane->SetGroupTextColor(0,RGB(0,0,128));
tPane->SetHorzMargin(15);
tPane->SetVertMargin(15);
tPane->Update();
Inheritance Hierarchy
Requirements
Header: afxTasksPane.h
CMFCTasksPane::AddGroup
Adds a new group of tasks to the task pane control.
int AddGroup(
int nPageIdx,
LPCTSTR lpszGroupName,
BOOL bBottomLocation = FALSE,
BOOL bSpecial = FALSE,
HICON hIcon = NULL);
int AddGroup(
LPCTSTR lpszGroupName,
BOOL bBottomLocation = FALSE,
BOOL bSpecial = FALSE,
HICON hIcon = NULL);
Parameters
[in] nPageIdx
Specifies the zero-based page index.
[in] lpszGroupName
Specifies the group name.
[in] bBottomLocation
TRUE to create the group at the bottom of the task pane control; otherwise, FALSE.
[in] bSpecial
TRUE to mark this group as a special group; otherwise, FALSE. For more information about special groups, see the Remarks section of CMFCTasksPane Class.
[in] hIcon
Specifies the icon to display in the group caption.
Return Value
The zero-based index of the group in the internal list of groups that the class maintains.
Remarks
Call this method to create a group of tasks and to add that group to the task pane control.
The framework displays task groups at the top of the task pane control or at the bottom. The framework can display only one group at the bottom; this group must be added last.
CMFCTasksPane::AddLabel
Adds a label to the specified task group.
int AddLabel(
int nGroup,
LPCTSTR lpszLabelName,
int nTaskIcon = -1,
BOOL bIsBold = FALSE);
Parameters
[in] nGroup
Specifies the index of the group where the label is added.
[in] lpszLabelName
Specifies the name of the label.
[in] nTaskIcon
Specifies the icon to display next to the label. The framework stores icons in a list of images. This parameter is an index into that list.
[in] bIsBold
TRUE to display the label in bold text; otherwise, FALSE.
Return Value
The zero-based index of the group where the label was added, or -1 if the group specified by nGroup does not exist.
Remarks
The framework handles tasks and labels differently. When a user clicks on a task, the framework executes a command. When a user clicks on a label, no command is executed. For more information, see CMFCTasksPane::AddTask.
CMFCTasksPane::AddMRUFilesList
Adds a task for each file stored in a Most Recently Used (MRU) files list into a group.
int AddMRUFilesList(
int nGroup,
int nMaxFiles = 4);
Parameters
[in] nGroup
Specifies the index of a group. This method adds the MRU files list to the group specified by this parameter.
[in] nMaxFiles
Specifies the number of files to display in the MRU files list.
Return Value
The zero-based index of the group where the MRU files list was added, or -1 if the group specified by nGroup does not exist.
CMFCTasksPane::AddPage
Adds a page to the task pane.
int AddPage(LPCTSTR lpszPageLabel);
Parameters
[in] lpszPageLabel
Specifies the label for the page.
Return Value
The zero-based index of the new page.
CMFCTasksPane::AddSeparator
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
int AddSeparator(int nGroup);
Parameters
[in] nGroup
Return Value
Remarks
CMFCTasksPane::AddTask
Adds a task to the specified task group.
int AddTask(
int nGroup,
LPCTSTR lpszTaskName,
int nTaskIcon = -1,
UINT uiCommandID = 0,
DWORD dwUserData = 0);
Parameters
[in] nGroup
Specifies the group index where the task is added.
[in] lpszTaskName
Specifies the name of the task.
[in] nTaskIcon
Specifies the icon to display next to the task. The framework stores icons in a list of images. This parameter is an index into that list.
[in] uiCommandID
Specifies the command ID of the command to execute when the user clicks the task. The task is treated as a label if uiCommandID is 0.
[in] dwUserData
Specifies the user-defined data to be associated with the task.
Return Value
The zero-based index of the group where the task was added, or -1 if the group specified by nGroup does not exist.
CMFCTasksPane::AddWindow
Adds a child window to the task pane.
int AddWindow(
int nGroup,
HWND hwndTask,
int nWndHeight,
BOOL bAutoDestroyWindow = FALSE,
DWORD dwUserData = 0);
Parameters
[in] nGroup
Specifies the group index where the window is added.
[in] hwndTask
Specifies the handle of the window to add.
[in] nWndHeight
Specifies the height of the window.
[in] bAutoDestroyWindow
TRUE to destroy the window when the task is removed; otherwise, FALSE.
[in] dwUserData
Specifies the user-defined data associated with the task.
Return Value
The zero-based index of the group where the window was added, or -1 if the group specified by nGroup does not exist.
Remarks
Call this method to add a control to a task pane. For example, you can add an edit control that functions like a search bar.
CMFCTasksPane::CMFCTasksPane
Constructs a CMFCTasksPane object.
CMFCTasksPane();
CMFCTasksPane::CollapseAllGroups
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
void CollapseAllGroups(BOOL bCollapse = TRUE);
void CollapseAllGroups(
int nPageIdx,
BOOL bCollapse);
Parameters
[in] bCollapse
[in] nPageIdx
Remarks
CMFCTasksPane::CollapseGroup
Collapses or expands a group.
BOOL CollapseGroup(
CMFCTasksPaneTaskGroup* pGroup,
BOOL bCollapse = TRUE);
BOOL CollapseGroup(
int nGroup,
BOOL bCollapse = TRUE);
Parameters
[in] pGroup
Specifies the group to collapse.
[in] bCollapse
TRUE to collapse the group; FALSE to expand the group.
[in] nGroup
Specifies the zero-based index of the group to collapse in the internal list of groups.
Return Value
TRUE if the group collapses or expands successfully; otherwise, FALSE.
Remarks
A collapsed group shows only the group caption; the list of tasks is hidden.
CMFCTasksPane::CreateDefaultMiniframe
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual CPaneFrameWnd* CreateDefaultMiniframe(CRect rectInitial);
Parameters
[in] rectInitial
Return Value
Remarks
CMFCTasksPane::CreateMenu
Creates a menu that appears when a user clicks the Other Tasks Panes menu button.
HMENU CreateMenu() const;
Return Value
A handle to the new menu.
Remarks
Override this method in a derived class to customize the menu for a task pane.
The pop-up menu that this method creates contains the list of pages in the task pane. The menu displays a check mark next to the active page.
CMFCTasksPane::EnableAnimation
Enables or disables the animation that occurs when a task group expands or collapses.
void EnableAnimation(BOOL bEnable = TRUE);
Parameters
[in] bEnable
TRUE to enable the animation that occurs when a task group expands or collapses; otherwise, FALSE.
Remarks
By default, the animation that occurs when a task group expands or collapses is enabled.
CMFCTasksPane::EnableGroupCollapse
Specifies whether a user can collapse task groups.
void EnableGroupCollapse(BOOL bEnable);
Parameters
[in] bEnable
TRUE if users can collapse task groups; otherwise, FALSE.
Remarks
A task group that is collapsed displays only the group caption; the list of tasks is hidden.
CMFCTasksPane::EnableHistoryMenuButtons
Enables drop-down menus on the Next and Previous navigation buttons.
void EnableHistoryMenuButtons(BOOL bEnable = TRUE);
Parameters
[in] bEnable
TRUE to enable drop-down menus on the Next and Previous navigation buttons; otherwise, FALSE.
Remarks
By default, the drop-down menus on the Next and Previous buttons are disabled.
The menus contain the history of tasks pages that the user used.
CMFCTasksPane::EnableNavigationToolbar
Enables or disables the navigation toolbar.
void EnableNavigationToolbar(
BOOL bEnable = TRUE,
UINT uiToolbarBmpRes = 0,
CSize sizeToolbarImage = CSize(0,
0),
CSize sizeToolbarButton = CSize(0,
0));
Parameters
[in] bEnable
TRUE to enable the navigation toolbar; otherwise, FALSE.
[in] uiToolbarBmpRes
Specifies the resource ID of the bitmap that contains the images to display on the toolbar.
[in] sizeToolbarImage
Specifies the size of a toolbar image.
[in] sizeToolbarButton
Specifies the size of a toolbar button.
Remarks
The navigation toolbar is a toolbar that the framework displays at the top of the task pane. The navigation toolbar contains the Back, Forward, and Home navigation buttons and a menu button that contains the list of available pages.
By default, the framework does not display the navigation toolbar. If the navigation toolbar is not displayed, the navigation buttons are located on the caption of the docking bar.
CMFCTasksPane::EnableOffsetCustomControls
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
void EnableOffsetCustomControls(BOOL bEnable);
Parameters
[in] bEnable
Remarks
CMFCTasksPane::EnableScrollButtons
Enables scroll buttons instead of a scroll bar.
void EnableScrollButtons(BOOL bEnable = TRUE);
Parameters
[in] bEnable
TRUE to display scroll buttons in the task pane instead of a scroll bar; otherwise, FALSE.
Remarks
By default, the framework displays scroll buttons in the task pane.
CMFCTasksPane::EnableWrapLabels
Enables or disables word wrapping for the text in labels.
void EnableWrapLabels(BOOL bEnable = TRUE);
Parameters
[in] bEnable
TRUE to wrap the text in labels that appear on the task pane; otherwise, FALSE.
Remarks
By default, the framework does not wrap the text in labels. When word wrapping is enabled, the text in labels can appear in multiple lines. The label can include line breaking markers such as \n and the underline marker &.
CMFCTasksPane::EnableWrapTasks
Enables or disables word wrapping for the text in tasks.
void EnableWrapTasks(BOOL bEnable = TRUE);
Parameters
[in] bEnable
TRUE to wrap tasks in the task pane; otherwise, FALSE.
Remarks
By default, word wrapping for tasks is disabled.
CMFCTasksPane::GetActivePage
Returns the zero-based index for the active page.
int GetActivePage() const;
Return Value
The zero-based index of the active page.
CMFCTasksPane::GetGroupCaptionHeight
Returns the height of the group caption.
int GetGroupCaptionHeight() const;
Return Value
The height of the group caption, in pixels.
CMFCTasksPane::GetGroupCaptionHorzOffset
Returns the horizontal offset of a group caption.
int GetGroupCaptionHorzOffset() const;
Return Value
The horizontal offset of a group caption. The horizontal offset is the distance in pixels from the left or right edge of the task pane.
CMFCTasksPane::GetGroupCaptionVertOffset
Returns the vertical offset of a group caption.
int GetGroupCaptionVertOffset() const;
Return Value
The vertical offset of a group caption from the top and bottom edges of the task pane.
Remarks
The default value for the vertical offset is 7 pixels.
CMFCTasksPane::GetGroupCount
Returns the total number of groups.
int GetGroupCount()const;
Return Value
The total number of groups in the task pane.
CMFCTasksPane::GetGroupLocation
Returns the internal group index for the specified group.
BOOL GetGroupLocation(
CMFCTasksPaneTaskGroup* pGroup,
int& nGroup) const;
Parameters
[in] pGroup
Specifies the task group whose location is retrieved.
[out] nGroup
Contains the zero-based index of the task group.
Return Value
TRUE if the task group was found; otherwise, FALSE.
CMFCTasksPane::GetGroupVertOffset
Returns the vertical offset of a group.
int GetGroupVertOffset() const;
Return Value
The vertical offset of a group, in pixels.
CMFCTasksPane::GetHorzMargin
Returns the horizontal spacing between a task pane and the edge of the client area.
int GetHorzMargin() const;
Return Value
The horizontal spacing between a task pane and the edge of the client area.
Remarks
The default spacing between a task pane and the edge of the client area is 12 pixels.
CMFCTasksPane::GetNextPages
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
void GetNextPages(CStringList& lstNextPages) const;
Parameters
[in] lstNextPages
Remarks
CMFCTasksPane::GetPageByGroup
Retrieves the page index for a specified group.
BOOL GetPageByGroup(
int nGroup,
int& nPage) const;
Parameters
[in] nGroup
Specifies the zero-based index of the task group.
[out] nPage
Contains the page index for the specified group. If the task group only contains a default page, the returned value is 0.
Return Value
TRUE if the group nGroup exists; otherwise, FALSE.
CMFCTasksPane::GetPagesCount
Returns the number of pages.
int GetPagesCount() const;
Return Value
The number of pages in the task pane.
CMFCTasksPane::GetPreviousPages
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
void GetPreviousPages(CStringList& lstPrevPages) const;
Parameters
[in] lstPrevPages
Remarks
CMFCTasksPane::GetScrollBarCtrl
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual CScrollBar* GetScrollBarCtrl(int nBar) const;
Parameters
[in] nBar
Return Value
Remarks
CMFCTasksPane::GetTask
Retrieves a task.
CMFCTasksPaneTask* GetTask(
int nGroup,
int nTask) const;
Parameters
[in] nGroup
Specifies the zero-based index of the group that contains the task.
[in] nTask
Specifies the zero-based index of the task in the list specified by nGroup.
Return Value
The task at the specified index.
CMFCTasksPane::GetTaskCount
Returns the number of tasks in a specified group.
int GetTaskCount(int nGroup) const;
Parameters
[in] nGroup
Specifies the index of the task group.
Return Value
The number of tasks in the specified group, or 0 if nGroup is invalid.
CMFCTasksPane::GetTaskGroup
Returns a task group for a specified group index.
CMFCTasksPaneTaskGroup* GetTaskGroup(int nGroup) const;
Parameters
[in] nGroup
Specifies the zero-based index of the group to retrieve.
Return Value
The task group at the specified index.
CMFCTasksPane::GetTaskLocation
Returns the group and the index for a specified task.
BOOL GetTaskLocation(
UINT uiCommandID,
int& nGroup,
int& nTask) const;
BOOL GetTaskLocation(
HWND hwndTask,
int& nGroup,
int& nTask) const;
BOOL GetTaskLocation(
CMFCTasksPaneTask* pTask,
int& nGroup,
int& nTask) const;
Parameters
[in] uiCommandID
Specifies the command ID of the task to find.
[out] nGroup
Contains the group index of the task.
[out] nTask
Contains the index of the task in the task group.
[in] hwndTask
Specifies the window associated with the task.
[in] pTask
Specifies the task to find.
Return Value
TRUE if the task location was found; FALSE if the specified task does not exist.
Remarks
This method retrieves the group index and task index for the specified task. If the method returns FALSE, nGroup and nTask are set to -1.
CMFCTasksPane::GetTasksHorzOffset
Returns the horizontal offset of tasks.
int GetTasksHorzOffset() const;
Return Value
The horizontal offset of tasks from the left and right edges of their parent groups.
Remarks
The default horizontal offset of tasks is 12 pixels.
CMFCTasksPane::GetTasksIconHorzOffset
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
int GetTasksIconHorzOffset() const;
Return Value
Remarks
CMFCTasksPane::GetTasksIconVertOffset
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
int GetTasksIconVertOffset() const;
Return Value
Remarks
CMFCTasksPane::GetVertMargin
Returns the vertical margin between a task pane and the edges of the client area.
int GetVertMargin() const;
Return Value
The vertical margin between a task pane and the edges of the client area.
Remarks
The vertical margin is the space between a task pane and the edges of the client area. The default value of the vertical margin is 12 pixels.
CMFCTasksPane::IsAccessibilityCompatible
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL IsAccessibilityCompatible();
Return Value
Remarks
CMFCTasksPane::IsAnimationEnabled
Indicates whether animation is enabled.
BOOL IsAnimationEnabled() const;
Return Value
TRUE if the animation that occurs when a user expands or collapses a group is enabled; otherwise, FALSE.
Remarks
Call CMFCTasksPane::EnableAnimation to enable or disable animation.
CMFCTasksPane::IsBackButtonEnabled
Indicates whether the back button is enabled.
BOOL IsBackButtonEnabled() const;
Return Value
TRUE if the back button is enabled; otherwise, FALSE.
Remarks
When a user clicks the back button, the framework displays the previous task page.
CMFCTasksPane::IsForwardButtonEnabled
Indicates whether the forward button is enabled.
BOOL IsForwardButtonEnabled() const;
Return Value
TRUE if the forward button is enabled; otherwise, FALSE.
Remarks
The forward button enables forward navigation in the history of task pages.
CMFCTasksPane::IsGroupCollapseEnabled
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
BOOL IsGroupCollapseEnabled() const;
Return Value
Remarks
CMFCTasksPane::IsHistoryMenuButtonsEnabled
Indicates whether the Next and Previous navigation buttons have drop-down menus.
BOOL IsHistoryMenuButtonsEnabled() const;
Return Value
TRUE if the Next and Previous navigation buttons have drop-down menus; otherwise, FALSE.
CMFCTasksPane::IsNavigationToolbarEnabled
Indicates whether the navigation toolbar is enabled.
BOOL IsNavigationToolbarEnabled() const;
Return Value
TRUE if the navigation toolbar is enabled; otherwise, FALSE.
CMFCTasksPane::IsToolBox
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL IsToolBox() const;
Return Value
Remarks
CMFCTasksPane::IsWrapLabelsEnabled
Indicates whether the task pane wraps words in labels.
BOOL IsWrapLabelsEnabled() const;
Return Value
TRUE if words in labels are wrapped; otherwise, FALSE.
CMFCTasksPane::IsWrapTasksEnabled
Specifies whether the framework wraps the task string.
BOOL IsWrapTasksEnabled() const;
Return Value
TRUE if the task string is wrapped; otherwise, FALSE.
CMFCTasksPane::LoadState
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL LoadState(
LPCTSTR lpszProfileName=NULL,
int nIndex=-1,
UINT uiID=(UINT)-1);
Parameters
[in] lpszProfileName
[in] nIndex
[in] uiID
Return Value
Remarks
CMFCTasksPane::OnActivateTasksPanePage
Called by the framework when it makes a task pane page active.
virtual void OnActivateTasksPanePage();
Remarks
Override this method in a derived class to customize the appearance of the task pane page.
CMFCTasksPane::OnCancel
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void OnCancel();
Remarks
CMFCTasksPane::OnClickTask
Called by the framework when the user clicks an item in the task pane.
virtual void OnClickTask(
int nGroupNumber,
int nTaskNumber,
UINT uiCommandID,
DWORD dwUserData);
Parameters
[in] nGroupNumber
Specifies the zero-based index of the group that contains the clicked task.
[in] nTaskNumber
Specifies the zero-based index of the clicked task.
[in] uiCommandID
Specifies the command ID associated with the task.
[in] dwUserData
Contains user-defined data associated with the clicked task.
Remarks
The framework calls this method when a user clicks a task. By default, the framework checks the command ID associated with the clicked task and, if it is not zero, sends the WM_COMMAND message to the owner of the task pane control.
Override this method in a derived class to execute custom code when a task is clicked.
CMFCTasksPane::OnOK
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void OnOK();
Remarks
CMFCTasksPane::OnPressBackButton
Called by the framework when the user clicks the back button.
virtual void OnPressBackButton();
Remarks
By default, the framework displays the previously viewed page.
Override this method in a derived class to execute custom code when the user clicks the back button.
CMFCTasksPane::OnPressForwardButton
Called by the framework when the user clicks the forward navigation button.
virtual void OnPressForwardButton();
Remarks
By default, the framework displays the page that the user viewed before clicking the Back button.
Override this method in a derived class to execute custom code when the user clicks the forward button.
CMFCTasksPane::OnPressHomeButton
Called by the framework when the user clicks the home navigation button.
virtual void OnPressHomeButton();
Remarks
By default, the framework displays the default page for the task group.
Override this method in a derived class to execute custom code when the user clicks the home navigation button.
CMFCTasksPane::OnPressOtherButton
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void OnPressOtherButton(
CMFCCaptionMenuButton* pbtn,
CWnd* pWndOwner);
Parameters
[in] pbtn
[in] pWndOwner
Remarks
CMFCTasksPane::OnSetAccData
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL OnSetAccData(long lVal);
Parameters
[in] lVal
Return Value
Remarks
CMFCTasksPane::OnUpdateCmdUI
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void OnUpdateCmdUI(
CFrameWnd* pTarget,
BOOL bDisableIfNoHndler);
Parameters
[in] pTarget
[in] bDisableIfNoHndler
Remarks
CMFCTasksPane::PreTranslateMessage
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL PreTranslateMessage(MSG* pMsg);
Parameters
[in] pMsg
Return Value
Remarks
CMFCTasksPane::RecalcLayout
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
void RecalcLayout(BOOL bRedraw = TRUE);
Parameters
[in] bRedraw
Remarks
CMFCTasksPane::RemoveAllGroups
Removes all groups on the specified page.
void RemoveAllGroups(int nPageIdx = 0);
Parameters
[in] nPageIdx
Specifies the zero-based index of the page.
Remarks
Removes all groups on the page specified by nPageIdx, or all groups if there is only a default page.
CMFCTasksPane::RemoveAllPages
Removes all pages from the task pane except the default (first) page.
void RemoveAllPages();
CMFCTasksPane::RemoveAllTasks
Removes all tasks from the specified group.
void RemoveAllTasks(int nGroup);
Parameters
[in] nGroup
Specifies the zero-based index of the group.
CMFCTasksPane::RemoveGroup
Removes a group.
void RemoveGroup(int nGroup);
Parameters
[in] nGroup
Specifies the zero-based index of the group to remove.
Remarks
This method removes a single group. To remove all groups, call CMFCTasksPane::RemoveAllGroups instead.
When the framework removes a group, all tasks and user windows associated with it are destroyed.
CMFCTasksPane::RemovePage
Removes a specified page from the task pane.
void RemovePage(int nPageIdx);
Parameters
[in] nPageIdx
Specifies the zero-based index of the page to remove.
CMFCTasksPane::RemoveTask
Removes a task from a task group.
BOOL RemoveTask(
int nGroup,
int nTask,
BOOL bRedraw = TRUE);
Parameters
[in] nGroup
Specifies the zero-based index of the task group that contains the task to remove.
[in] nTask
Specifies the zero-based index of the task to remove.
[in] bRedraw
TRUE to redraw the task pane; otherwise, FALSE.
Return Value
TRUE if the function succeeds; FALSE if nGroup or nTask is invalid.
CMFCTasksPane::SaveState
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual BOOL SaveState(
LPCTSTR lpszProfileName=NULL,
int nIndex=-1,
UINT uiID=(UINT)-1);
Parameters
[in] lpszProfileName
[in] nIndex
[in] uiID
Return Value
Remarks
CMFCTasksPane::Serialize
This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.
virtual void Serialize(CArchive& ar);
Parameters
[in] ar
Remarks
CMFCTasksPane::SetActivePage
Makes the specified page in the task pane active.
void SetActivePage(int nPageIdx);
Parameters
[in] nPageIdx
Specifies the zero-based index of the page to display.
Remarks
This method asserts if the nPageIdx is invalid.
CMFCTasksPane::SetCaption
Sets the caption name of a task pane.
void SetCaption(LPCTSTR lpszName);
Parameters
[in] lpszName
Specifies the caption name.
Remarks
If a task pane has multiple pages, the default page has the caption that was set by using this function.
CMFCTasksPane::SetGroupCaptionHeight
Sets the height of a group caption.
void SetGroupCaptionHeight(int n = -1);
Parameters
[in] n
Specifies the caption height.
Remarks
Call this method to customize the margins of the task pane elements.
If n is -1, the framework determines the margin value by using the visual manager ( CMFCVisualManager::GetTasksPaneGroupCaptionHeight). The default caption height is 25 pixels.
CMFCTasksPane::SetGroupCaptionHorzOffset
Sets the horizontal offset of a group caption.
void SetGroupCaptionHorzOffset(int n = -1);
Parameters
[in] n
Specifies the horizontal offset of the group caption.
CMFCTasksPane::SetGroupCaptionVertOffset
Sets the vertical offset of a group caption.
void SetGroupCaptionVertOffset(int n = -1);
Parameters
[in] n
Specifies the vertical offset, in pixels, of the group caption.
CMFCTasksPane::SetGroupName
Sets a group name.
BOOL SetGroupName(
int nGroup,
LPCTSTR lpszGroupName);
Parameters
[in] nGroup
Specifies the zero-based index of the group.
[in] lpszGroupName
Specifies the name of the group.
Return Value
TRUE if the group name was successfully set; otherwise, FALSE.
CMFCTasksPane::SetGroupTextColor
Sets the text color for a group caption.
BOOL SetGroupTextColor(
int nGroup,
COLORREF color,
COLORREF colorHot = (COLORREF)-1);
Parameters
[in] nGroup
Specifies the zero-based index of the group.
[in] color
Specifies the text color.
[in] colorHot
Specifies the text color for the highlighted group. If -1, the default highlight color is used.
Return Value
TRUE if the group text color was successfully changed; otherwise, FALSE.
CMFCTasksPane::SetGroupVertOffset
Sets the vertical offset for a group.
void SetGroupVertOffset(int n = -1);
Parameters
[in] n
Specifies the vertical offset.
Remarks
The vertical offset is the distance between a task group and the border of the task pane.
Call this method to customize the margins of task pane elements. If n is -1, the framework determines the margin value by using the visual manager ( CMFCVisualManager::GetTasksPaneGroupVertOffset). The default offset is 15 pixels.
CMFCTasksPane::SetHorzMargin
Sets the horizontal margin.
void SetHorzMargin(int n = -1);
Parameters
[in] n
Specifies the margin, in pixels.
Remarks
The horizontal margin is the distance between a task pane and the top or bottom edge of the client area.
If n is -1, and the framework determines the margin value by using the visual manager ( CMFCVisualManager::GetTasksPaneHorzMargin). The default horizontal margin is 12 pixels.
CMFCTasksPane::SetIconsList
Sets the image list.
BOOL SetIconsList(
UINT uiImageListResID,
int cx,
COLORREF clrTransparent=RGB(255, 0, 255));
void SetIconsList(HIMAGELIST hIcons);
```
### Parameters
[in] `uiImageListResID`
Specifies the resource ID of the image list.
[in] `cx`
Specifies the size of icons in the image list.
[in] `clrTransparent`
Specifies the transparent color.
[in] `hIcons`
Specifies the image list that contains the icons for the task pane.
### Remarks
The framework stores icons in an image list. Tasks are associated with icons that are stored in that list.
This method associates an image list with the task pane control. To set the icon for a task when you call [CMFCTasksPane::AddTask](#cmfctaskspane__addtask), set `nTaskIcon` to the appropriate zero-based index in this image list.
## <a name="cmfctaskspane__setpagecaption"></a> CMFCTasksPane::SetPageCaption
Sets the caption text for a task pane page.
void SetPageCaption( int nPageIdx,
LPCTSTR lpszName);
### Parameters
[in] `nPageIdx`
Specifies the zero-based index of the page.
[in] `lpszName`
Specifies the caption text to display on the page.
### Remarks
If a task pane has multiple pages, the default page has the caption that was set by using this method.
## <a name="cmfctaskspane__settaskname"></a> CMFCTasksPane::SetTaskName
Sets the name for a task.
BOOL SetTaskName( int nGroup,
int nTask,
LPCTSTR lpszTaskName);
### Parameters
[in] `nGroup`
Specifies the zero-based index of the task group.
[in] `nTask`
Specifies the zero-based index of the task.
[in] `lpszTaskName`
Specifies the task name.
### Return Value
`TRUE` if the task name was successfully set; otherwise, `FALSE`.
## <a name="cmfctaskspane__settaskshorzoffset"></a> CMFCTasksPane::SetTasksHorzOffset
Sets the horizontal offset for tasks.
void SetTasksHorzOffset(int n = -1);
### Parameters
[in] `n`
Specifies the horizontal offset.
### Remarks
The horizontal offset is the distance in pixels from the left and right edges of a group.
If `n` is -1, this method sets the horizontal offset to the value returned by the `CMFCVisualManager::GetTasksPaneTaskHorzOffset` method.
The default horizontal offset is 12 pixels.
## <a name="cmfctaskspane__settasksiconhorzoffset"></a> CMFCTasksPane::SetTasksIconHorzOffset
[!INCLUDE[cpp_fp_under_construction](../Token/cpp_fp_under_construction_md.md)]
void SetTasksIconHorzOffset(it n = -1);
### Parameters
[in] `n`
### Remarks
## <a name="cmfctaskspane__settasksiconvertoffset"></a> CMFCTasksPane::SetTasksIconVertOffset
[!INCLUDE[cpp_fp_under_construction](../Token/cpp_fp_under_construction_md.md)]
void SetTasksIconVertOffset(it n = -1);
### Parameters
[in] `n`
### Remarks
## <a name="cmfctaskspane__settasktextcolor"></a> CMFCTasksPane::SetTaskTextColor
Sets the text color for a task.
BOOL SetTaskTextColor( int nGroup,
int nTask,
COLORREF color,
COLORREF colorHot = (COLORREF)-1);
### Parameters
[in] `nGroup`
Specifies the zero-based index of the task group that contains the task.
[in] `nTask`
Specifies the zero-based index of the task.
[in] `color`
Specifies the text color for the task.
[in] `colorHot`
Specifies the text color for the highlighted group. If -1, this method uses the default highlight color.
### Return Value
`TRUE` if the text color for the task was successfully set; otherwise, `FALSE`.
## <a name="cmfctaskspane__setvertmargin"></a> CMFCTasksPane::SetVertMargin
Sets the vertical margin.
void SetVertMargin(int n = -1);
### Parameters
[in] `n`
Specifies the vertical margin to set.
### Remarks
The vertical margin is the distance between a task pane and the vertical edges of the client area.
If `n` is -1, the framework determines the margin value by using the visual manager ( `CMFCVisualManager::GetTasksPaneVertMargin`). The default margin is 12 pixels.
## <a name="cmfctaskspane__setwindowheight"></a> CMFCTasksPane::SetWindowHeight
Sets the height for a window control.
BOOL SetWindowHeight( int nGroup,
HWND hwndTask,
int nWndHeight);
BOOL SetWindowHeight( HWND hwndTask,
int nWndHeight);
### Parameters
[in] `nGroup`
Specifies the zero-based index of the group that contains the window control.
[in] `hwndTask`
Specifies the handle to the window control.
[in] `nWndHeight`
Specifies the height to set.
### Return Value
`TRUE` if the height of the window control was successfully set; `FALSE` if `nGroup` is invalid or if `hwndTask` does not exist.
### Remarks
Call [CMFCTasksPane::AddWindow](#cmfctaskspane__addwindow) to add tasks with window controls.
## <a name="cmfctaskspane__showcommandmessagestring"></a> CMFCTasksPane::ShowCommandMessageString
[!INCLUDE[cpp_fp_under_construction](../Token/cpp_fp_under_construction_md.md)]
virtual void ShowCommandMessageString(UINT uiCmdId);
### Parameters
[in] `uiCmdId`
### Remarks
## <a name="cmfctaskspane__showtask"></a> CMFCTasksPane::ShowTask
Shows or hides a task.
BOOL ShowTask( int nGroup,
int nTask,
BOOL bShow = TRUE,
BOOL bRedraw = TRUE);
### Parameters
[in] `nGroup`
Specifies the zero-based index of the group.
[in] `nTask`
Specifies the zero-based index of the task to show or hide.
[in] `bShow`
`TRUE` to show the task; `FALSE` to hide the task.
[in] `bRedraw`
`TRUE` to redraw the task pane; otherwise, `FALSE`.
### Return Value
`TRUE` if the task was successfully shown or hidden; `FALSE` if the specified group or task does not exist.
### Remarks
Use [CMFCTasksPane::ShowTaskByCmdId](#cmfctaskspane__showtaskbycmdid) to show or hide a task based on its command ID.
## <a name="cmfctaskspane__showtaskbycmdid"></a> CMFCTasksPane::ShowTaskByCmdId
Shows or hides a task based on its command ID.
BOOL ShowTaskByCmdId( UINT uiCommandID,
BOOL bShow = TRUE,
BOOL bRedraw = TRUE);
### Parameters
[in] `uiCommandID`
Specifies the command ID of the task to show or hide.
[in] `bShow`
`TRUE` to show the task; `FALSE` to hide the task.
[in] `bRedraw`
`TRUE` to redraw the task pane; otherwise, `FALSE`.
### Return Value
`TRUE` if the task was successfully shown or hidden; `FALSE` if a task with the specified command ID does not exist.
### Remarks
Use [CMFCTasksPane::ShowTask](#cmfctaskspane__showtask) to show or hide a task based on its command ID.
## <a name="cmfctaskspane__update"></a> CMFCTasksPane::Update
Refreshes all of the controls in a task pane.
virtual void Update();
### Remarks
This method updates the task pane caption, adjusts the scroll bar, repositions all tasks, and redraws all of the task pane controls.
Override this method in a derived class to execute custom code when the framework refreshes the task pane.
## See Also
[Hierarchy Chart](../Topic/Hierarchy%20Chart.md)
[Classes](../Topic/MFC%20Classes.md)
[CMFCTasksPaneTaskGroup Class](../Topic/CMFCTasksPaneTaskGroup%20Class.md)
[CMFCTasksPaneTask Class](../Topic/CMFCTasksPaneTask%20Class.md)
[CMFCOutlookBar Class](../Topic/CMFCOutlookBar%20Class.md)
[CMFCVisualManager Class](../Topic/CMFCVisualManager%20Class.md)