CMFCTasksPane Class

Article
01/25/2023

For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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_COMMAND message is sent to the owner of the task pane control.

To use the CMFCTasksPane control in your application, follow these steps:

Embed a CMFCTasksPane object into the main frame window class.
When processing the WM_CREATE message, call the Create method. You can use the regular CControlBar styles. For more information, see CControlBar::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:

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:

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

CObject
└ CCmdTarget
└ CWnd
└ CBasePane
└ CPane
└ CDockablePane
└ CMFCTasksPane

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

nPageIdx
[in] Specifies the zero-based page index.

lpszGroupName
[in] Specifies the group name.

bBottomLocation
[in] TRUE to create the group at the bottom of the task pane control; otherwise, FALSE.

bSpecial
[in] TRUE to mark this group as a special group; otherwise, FALSE. For more information about special groups, see the Remarks section of CMFCTasksPane.

hIcon
[in] 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

nGroup
[in] Specifies the index of the group where the label is added.

lpszLabelName
[in] Specifies the name of the label.

nTaskIcon
[in] 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.

bIsBold
[in] 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

nGroup
[in] Specifies the index of a group. This method adds the MRU files list to the group specified by this parameter.

nMaxFiles
[in] 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

lpszPageLabel
[in] Specifies the label for the page.

Return Value

The zero-based index of the new page.

CMFCTasksPane::AddSeparator

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

nGroup
[in] Specifies the group index where the task is added.

lpszTaskName
[in] Specifies the name of the task.

nTaskIcon
[in] 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.

uiCommandID
[in] 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.

dwUserData
[in] 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

nGroup
[in] Specifies the group index where the window is added.

hwndTask
[in] Specifies the handle of the window to add.

nWndHeight
[in] Specifies the height of the window.

bAutoDestroyWindow
[in] TRUE to destroy the window when the task is removed; otherwise, FALSE.

dwUserData
[in] 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

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

pGroup
[in] Specifies the group to collapse.

bCollapse
[in] TRUE to collapse the group; FALSE to expand the group.

nGroup
[in] 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

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

bEnable
[in] 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

bEnable
[in] 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

bEnable
[in] 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

bEnable
[in] TRUE to enable the navigation toolbar; otherwise, FALSE.

uiToolbarBmpRes
[in] Specifies the resource ID of the bitmap that contains the images to display on the toolbar.

sizeToolbarImage
[in] Specifies the size of a toolbar image.

sizeToolbarButton
[in] 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

void EnableOffsetCustomControls(BOOL bEnable);

Parameters

[in] bEnable

Remarks

CMFCTasksPane::EnableScrollButtons

Enables scroll buttons instead of a scroll bar.

void EnableScrollButtons(BOOL bEnable = TRUE);

Parameters

bEnable
[in] 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

bEnable
[in] 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

bEnable
[in] 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

pGroup
[in] Specifies the task group whose location is retrieved.

nGroup
[out] 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

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

nGroup
[in] Specifies the zero-based index of the task group.

nPage
[out] 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

void GetPreviousPages(CStringList& lstPrevPages) const;

Parameters

[in] lstPrevPages

Remarks

CMFCTasksPane::GetScrollBarCtrl

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

nGroup
[in] Specifies the zero-based index of the group that contains the task.

nTask
[in] 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

nGroup
[in] 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

nGroup
[in] 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

uiCommandID
[in] Specifies the command ID of the task to find.

nGroup
[out] Contains the group index of the task.

nTask
[out] Contains the index of the task in the task group.

hwndTask
[in] Specifies the window associated with the task.

pTask
[in] 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

int GetTasksIconHorzOffset() const;

Return Value

Remarks

CMFCTasksPane::GetTasksIconVertOffset

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

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

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

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

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

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

nGroupNumber
[in] Specifies the zero-based index of the group that contains the clicked task.

nTaskNumber
[in] Specifies the zero-based index of the clicked task.

uiCommandID
[in] Specifies the command ID associated with the task.

dwUserData
[in] 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

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

virtual void OnPressOtherButton(
    CMFCCaptionMenuButton* pbtn,
    CWnd* pWndOwner);

Parameters

[in] pbtn
[in] pWndOwner

Remarks

CMFCTasksPane::OnSetAccData

virtual BOOL OnSetAccData(long lVal);

Parameters

[in] lVal

Return Value

Remarks

CMFCTasksPane::OnUpdateCmdUI

virtual void OnUpdateCmdUI(
    CFrameWnd* pTarget,
    BOOL bDisableIfNoHndler);

Parameters

[in] pTarget
[in] bDisableIfNoHndler

Remarks

CMFCTasksPane::PreTranslateMessage

virtual BOOL PreTranslateMessage(MSG* pMsg);

Parameters

[in] pMsg

Return Value

Remarks

CMFCTasksPane::RecalcLayout

void RecalcLayout(BOOL bRedraw = TRUE);

Parameters

[in] bRedraw

Remarks

CMFCTasksPane::RemoveAllGroups

Removes all groups on the specified page.

void RemoveAllGroups(int nPageIdx = 0);

Parameters

nPageIdx
[in] 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

nGroup
[in] Specifies the zero-based index of the group.

CMFCTasksPane::RemoveGroup

Removes a group.

void RemoveGroup(int nGroup);

Parameters

nGroup
[in] 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

nPageIdx
[in] 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

nGroup
[in] Specifies the zero-based index of the task group that contains the task to remove.

nTask
[in] Specifies the zero-based index of the task to remove.

bRedraw
[in] TRUE to redraw the task pane; otherwise, FALSE.

Return Value

TRUE if the function succeeds; FALSE if nGroup or nTask is invalid.

CMFCTasksPane::SaveState

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

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

nPageIdx
[in] 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

lpszName
[in] 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

n
[in] 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

n
[in] Specifies the horizontal offset of the group caption.

CMFCTasksPane::SetGroupCaptionVertOffset

Sets the vertical offset of a group caption.

void SetGroupCaptionVertOffset(int n = -1);

Parameters

n
[in] Specifies the vertical offset, in pixels, of the group caption.

CMFCTasksPane::SetGroupName

Sets a group name.

BOOL SetGroupName(
    int nGroup,
    LPCTSTR lpszGroupName);

Parameters

nGroup
[in] Specifies the zero-based index of the group.

lpszGroupName
[in] 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

nGroup
[in] Specifies the zero-based index of the group.

color
[in] Specifies the text color.

colorHot
[in] 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

n
[in] 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

n
[in] 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

uiImageListResID
[in] Specifies the resource ID of the image list.

cx
[in] Specifies the size of icons in the image list.

clrTransparent
[in] Specifies the transparent color.

hIcons
[in] 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, set nTaskIcon to the appropriate zero-based index in this image list.

CMFCTasksPane::SetPageCaption

Sets the caption text for a task pane page.

void SetPageCaption(
    int nPageIdx,
    LPCTSTR lpszName);

Parameters

nPageIdx
[in] Specifies the zero-based index of the page.

lpszName
[in] 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.

CMFCTasksPane::SetTaskName

Sets the name for a task.

BOOL SetTaskName(
    int nGroup,
    int nTask,
    LPCTSTR lpszTaskName);

Parameters

nGroup
[in] Specifies the zero-based index of the task group.

nTask
[in] Specifies the zero-based index of the task.

lpszTaskName
[in] Specifies the task name.

Return Value

TRUE if the task name was successfully set; otherwise, FALSE.

CMFCTasksPane::SetTasksHorzOffset

Sets the horizontal offset for tasks.

void SetTasksHorzOffset(int n = -1);

Parameters

n
[in] 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.

CMFCTasksPane::SetTasksIconHorzOffset

void SetTasksIconHorzOffset(int n = -1);

Parameters

[in] n

Remarks

CMFCTasksPane::SetTasksIconVertOffset

void SetTasksIconVertOffset(int n = -1);

Parameters

[in] n

Remarks

CMFCTasksPane::SetTaskTextColor

Sets the text color for a task.

BOOL SetTaskTextColor(
    int nGroup,
    int nTask,
    COLORREF color,
    COLORREF colorHot = (COLORREF)-1);

Parameters

nGroup
[in] Specifies the zero-based index of the task group that contains the task.

nTask
[in] Specifies the zero-based index of the task.

color
[in] Specifies the text color for the task.

colorHot
[in] 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.

CMFCTasksPane::SetVertMargin

Sets the vertical margin.

void SetVertMargin(int n = -1);

Parameters

n
[in] 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.

CMFCTasksPane::SetWindowHeight

Sets the height for a window control.

BOOL SetWindowHeight(
    int nGroup,
    HWND hwndTask,
    int nWndHeight);

BOOL SetWindowHeight(
    HWND hwndTask,
    int nWndHeight);

Parameters

nGroup
[in] Specifies the zero-based index of the group that contains the window control.

hwndTask
[in] Specifies the handle to the window control.

nWndHeight
[in] 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 to add tasks with window controls.

CMFCTasksPane::ShowCommandMessageString

virtual void ShowCommandMessageString(UINT uiCmdId);

Parameters

[in] uiCmdId

Remarks

CMFCTasksPane::ShowTask

Shows or hides a task.

BOOL ShowTask(
    int nGroup,
    int nTask,
    BOOL bShow = TRUE,
    BOOL bRedraw = TRUE);

Parameters

nGroup
[in] Specifies the zero-based index of the group.

nTask
[in] Specifies the zero-based index of the task to show or hide.

bShow
[in] TRUE to show the task; FALSE to hide the task.

bRedraw
[in] 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 to show or hide a task based on its command ID.

CMFCTasksPane::ShowTaskByCmdId

Shows or hides a task based on its command ID.

BOOL ShowTaskByCmdId(
    UINT uiCommandID,
    BOOL bShow = TRUE,
    BOOL bRedraw = TRUE);

Parameters

uiCommandID
[in] Specifies the command ID of the task to show or hide.

bShow
[in] TRUE to show the task; FALSE to hide the task.

bRedraw
[in] 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 to show or hide a task based on its command ID.

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.

Share via

CMFCTasksPane Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Remarks

Example

Inheritance Hierarchy

Requirements

CMFCTasksPane::AddGroup

Parameters

Return Value

Remarks

CMFCTasksPane::AddLabel

Parameters

Return Value

Remarks

CMFCTasksPane::AddMRUFilesList

Parameters

Return Value

CMFCTasksPane::AddPage

Parameters

Return Value

CMFCTasksPane::AddSeparator

Parameters

Return Value

Remarks

CMFCTasksPane::AddTask

Parameters

Return Value

CMFCTasksPane::AddWindow

Parameters

Return Value

Remarks

CMFCTasksPane::CMFCTasksPane

CMFCTasksPane::CollapseAllGroups

Parameters

Remarks

CMFCTasksPane::CollapseGroup

Parameters

Return Value

Remarks

CMFCTasksPane::CreateDefaultMiniframe

Parameters

Return Value

Remarks

CMFCTasksPane::CreateMenu

Return Value

Remarks

CMFCTasksPane::EnableAnimation

Parameters

Remarks

CMFCTasksPane::EnableGroupCollapse

Parameters

Remarks

CMFCTasksPane::EnableHistoryMenuButtons

Parameters

Remarks

CMFCTasksPane::EnableNavigationToolbar

Parameters

Remarks

CMFCTasksPane::EnableOffsetCustomControls

Parameters

Remarks

CMFCTasksPane::EnableScrollButtons

Parameters

Remarks

CMFCTasksPane::EnableWrapLabels

Parameters

Remarks

CMFCTasksPane::EnableWrapTasks

Parameters

Remarks

CMFCTasksPane::GetActivePage

Return Value

CMFCTasksPane::GetGroupCaptionHeight

Return Value

CMFCTasksPane::GetGroupCaptionHorzOffset