CMFCOutlookBar Class

Article
08/03/2021

A tabbed pane with the visual appearance of the Navigation Pane in Microsoft Outlook 2000 or Outlook 2003. The CMFCOutlookBar object contains a CMFCOutlookBarTabCtrl Class object and a series of tabs. The tabs can be either CMFCOutlookBarPane Class objects or CWnd-derived objects. To the user, the Outlook bar appears as a series of buttons and a display area. When the user clicks a button, the corresponding control or button pane is displayed.

Syntax

class CMFCOutlookBar : public CBaseTabbedPane

Members

Public Constructors

Name	Description
`CMFCOutlookBar::CMFCOutlookBar`	Default constructor.
`CMFCOutlookBar::~CMFCOutlookBar`	Destructor.

Public Methods

Name	Description
CMFCOutlookBar::AllowDestroyEmptyTabbedPane	Specifies whether an empty tabbed pane can be destroyed. (Overrides CBaseTabbedPane::AllowDestroyEmptyTabbedPane.)
CMFCOutlookBar::CanAcceptPane	Determines whether another pane can be docked to the Outlook bar pane. (Overrides CDockablePane::CanAcceptPane.)
CMFCOutlookBar::CanSetCaptionTextToTabName	Determines whether the caption for the tabbed pane displays the same text as the active tab. (Overrides CBaseTabbedPane::CanSetCaptionTextToTabName.)
CMFCOutlookBar::Create	Creates the Outlook bar control.
CMFCOutlookBar::CreateCustomPage	Creates a custom Outlook bar tab.
`CMFCOutlookBar::CreateObject`	Used by the framework to create a dynamic instance of this class type.
CMFCOutlookBar::DoesAllowDynInsertBefore	Determines whether a user can dock a control bar at the outer edge of the Outlook bar.
CMFCOutlookBar::FloatTab	Floats a pane, but only if the pane currently resides in a detachable tab. (Overrides CBaseTabbedPane::FloatTab.)
CMFCOutlookBar::GetButtonsFont	Returns the font of the text on the buttons of the Outlook bar.
CMFCOutlookBar::GetTabArea	Returns the size and position of the tab areas on the Outlook bar. (Overrides CBaseTabbedPane::GetTabArea.)
`CMFCOutlookBar::GetThisClass`	Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CMFCOutlookBar::IsMode2003	Determines whether the behavior of the Outlook bar mimics that of Microsoft Office Outlook 2003 (see Remarks).
CMFCOutlookBar::OnAfterAnimation	Called by CMFCOutlookBarTabCtrl::SetActiveTab after the active tab has been set using animation.
CMFCOutlookBar::OnBeforeAnimation	Called by CMFCOutlookBarTabCtrl::SetActiveTab before a tab page is set as the active tab using animation.
CMFCOutlookBar::OnScroll	Called by the framework if the Outlook bar is scrolling up or down.
CMFCOutlookBar::RemoveCustomPage	Removes a custom Outlook bar tab.
CMFCOutlookBar::SetButtonsFont	Sets the font of the text on the buttons of the Outlook bar.
CMFCOutlookBar::SetMode2003	Specifies whether the behavior of the Outlook bar mimics that of Outlook 2003 (see Remarks).

Remarks

For an example of an Outlook bar, see the OutlookDemo Sample: MFC OutlookDemo Application.

Implementing the Outlook Bar

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

Embed a CMFCOutlookBar object into the main frame window class.

class CMainFrame : public CMDIFrameWnd
{
    // ...
    CMFCOutlookBar m_wndOutlookBar;
    CMFCOutlookBarPane m_wndOutlookPane;
    // ...
};

When processing the WM_CREATE message in the main frame, call the CMFCOutlookBar::Create method to create the Outlook bar tab control.

m_wndOutlookBar.Create (_T("Shortcuts"),
    this,
    CRect (0, 0, 100, 100),
    ID_VIEW_OUTLOOKBAR,
    WS_CHILD | WS_VISIBLE | CBRS_LEFT);

Obtain a pointer to the underlying CMFCOutlookBarTabCtrl by using CBaseTabbedPane::GetUnderlyingWindow.

CMFCOutlookBarTabCtrl* pOutlookBar = (CMFCOutlookBarTabCtrl*) m_wndOutlookBar.GetUnderlyingWindow ();

Create a CMFCOutlookBarPane Class object for each tab that contains buttons.

m_wndOutlookPane.Create(&m_wndOutlookBar,
    AFX_DEFAULT_TOOLBAR_STYLE,
    ID_OUTLOOK_PANE_GENERAL,
    AFX_CBRS_FLOAT | AFX_CBRS_RESIZE);

// make the Outlook pane detachable (enable docking)
m_wndOutlookPane.EnableDocking(CBRS_ALIGN_ANY);

// add buttons
m_wndOutlookPane.AddButton(theApp.LoadIcon (IDR_MAINFRAME),
    "About",
    ID_APP_ABOUT);

m_wndOutlookPane.AddButton (theApp.LoadIcon (IDR_CUSTOM_OPEN_ICON),
    "Open",
    ID_FILE_OPEN);

Call CMFCOutlookBarTabCtrl::AddTab to add each new tab. Set the bDetachable parameter to FALSE to make a page non-detachable. Or, use CMFCOutlookBarTabCtrl::AddControl to add detachable pages.
```
pOutlookBar->AddTab (&m_wndOutlookPane, "General", (UINT) -1, TRUE);
```
To add a CWnd-derived control (for example, CMFCShellTreeCtrl Class) as a tab, create the control and call CMFCOutlookBarTabCtrl::AddTab to add it to the Outlook bar.

Note

You should use unique control IDs for each CMFCOutlookBarPane Class object and for each CWnd-derived object.

To dynamically add or delete new pages at runtime, use CMFCOutlookBar::CreateCustomPage and CMFCOutlookBar::RemoveCustomPage.

Outlook 2003 Mode

In Outlook 2003 mode, the tab buttons are positioned at the bottom of the Outlook bar pane. When there is not sufficient room to display the buttons, they are displayed as icons in a toolbar-like area along the bottom of the pane.

Use CMFCOutlookBar::SetMode2003 to enable Outlook 2003 mode. Use CMFCOutlookBarTabCtrl::SetToolbarImageList to set the bitmap that contains the icons that are displayed on the bottom of the Outlook bar. The icons in the bitmap must be ordered by tab index.

Inheritance Hierarchy

Requirements

Header: afxoutlookbar.h

CMFCOutlookBar::AllowDestroyEmptyTabbedPane

Specifies whether an empty tabbed pane can be destroyed.

virtual BOOL AllowDestroyEmptyTabbedPane() const;

Return Value

TRUE if an empty tabbed pane can be destroyed; otherwise, FALSE. The default implementation always returns TRUE.

Remarks

If an empty tabbed pane cannot be destroyed, the framework hides it instead.

CMFCOutlookBar::CanAcceptPane

Determines whether another pane can be docked to the Outlook bar pane.

virtual BOOL CanAcceptPane(const CBasePane* pBar) const;

Parameters

pBar
[in] A pointer to another pane that is being docked to this pane.

Return Value

TRUE if another pane can be docked to the Outlook bar pane; otherwise FALSE.

Remarks

If the Outlook bar is in Outlook 2003 mode, docking is not supported, so the return value is FALSE.

If the pBar parameter is NULL, this method returns FALSE.

Otherwise, this method behaves as the base method CBasePane::CanAcceptPane, except that even if docking is not enabled, an Outlook bar can still enable another Outlook bar to be docked over it.

CMFCOutlookBar::CanSetCaptionTextToTabName

Determines whether the caption for the tabbed pane displays the same text as the active tab.

virtual BOOL CanSetCaptionTextToTabName() const;

Return Value

TRUE if the Outlook bar window caption is automatically set to the text of the active tab; otherwise FALSE.

Remarks

Use CBaseTabbedPane::EnableSetCaptionTextToTabName to enable or disable this functionality.

In Outlook 2003 mode, this setting is always enabled.

CMFCOutlookBar::Create

Creates the Outlook bar control.

virtual BOOL Create(
    LPCTSTR lpszCaption,
    CWnd* pParentWnd,
    const RECT& rect,
    UINT nID,
    DWORD dwStyle,
    DWORD dwControlBarStyle=AFX_CBRS_RESIZE,
    CCreateContext* pContext=NULL);

Parameters

lpszCaption
[in] Specifies the window caption.

pParentWnd
[in] Specifies a pointer to a parent window. It must not be NULL.

rect
[in] Specifies the outlook bar size and position in pixels.

nID
[in] Specifies the control ID. Must be distinct from other control IDs used in the application.

dwStyle
[in] Specifies the desired control bar style. For possible values, see Window Styles.

dwControlBarStyle
[in] Specifies the special library-defined styles.

pContext
[in] Create context.

Return Value

Nonzero if the method is successful; otherwise 0.

Remarks

You construct a CMFCOutlookBar object in two steps. First call the constructor, and then call Create, which creates the outlook bar control and attaches it to the CMFCOutlookBar object.

See CBasePane::CreateEx for the list of the available library-defined styles to be specified by dwControlBarStyle.

Example

The following example demonstrates how to use the Create method of the CMFCOutlookBar class. This code snippet is part of the Outlook Multi Views sample.

CMFCOutlookBar m_wndShortcutsBar;

// int nInitialWidth
// CString strCaption
if (!m_wndShortcutsBar.Create(strCaption, this,
                              CRect(0, 0, nInitialWidth, nInitialWidth),
                              ID_VIEW_OUTLOOKBAR, WS_CHILD | WS_VISIBLE | CBRS_LEFT))
{
   TRACE0("Failed to create outlook bar\n");
   return FALSE; // fail to create
}

CMFCOutlookBar::CreateCustomPage

Creates a custom Outlook bar tab.

CMFCOutlookBarPane* CreateCustomPage(
    LPCTSTR lpszPageName,
    BOOL bActivatePage=TRUE,
    DWORD dwEnabledDocking=CBRS_ALIGN_ANY,
    BOOL bEnableTextLabels=TRUE);

Parameters

lpszPageName
[in] The page label.

bActivatePage
[in] If TRUE, the page becomes active upon creation.

dwEnabledDocking
[in] A combination of CBRS_ALIGN_ flags that specifies the enabled docking sides when the page is detached.

bEnableTextLabels
[in] If TRUE, the text labels are enabled for the buttons that reside on the page.

Return Value

A pointer to the newly created page, or NULL if the creation failed.

Remarks

Use this method to enable the users to create custom Outlook bar pages. You can create up to 100 pages per application. The page control IDs start from 0xF000. The creation fails if the total number of custom Outlook bar pages exceeds 100.

Use CMFCOutlookBar::RemoveCustomPage to delete custom pages.

CMFCOutlookBar::DoesAllowDynInsertBefore

Specifies whether a user can dock a pane at the outer edge of the Outlook bar.

DECLARE_MESSAGE_MAP virtual BOOL DoesAllowDynInsertBefore() const;

Return Value

The default implementation returns FALSE.

Remarks

The framework calls the DoesAllowDynInsertBefore method when it looks for a location to dock a dynamic pane. If the function returns FALSE, the framework does not allow the docking of any dynamic pane at the outer edges of the pane.

Usually, you create an Outlook bar as a static non-floating control. You can override this function in a derived class and return TRUE to change this behavior.

Note

Because dynamic panes check the status of docked static panes when docking, you should dock dynamic panes after static panes whenever possible.

CMFCOutlookBar::FloatTab

Floats a pane.

virtual BOOL FloatTab(
    CWnd* pBar,
    int nTabID,
    AFX_DOCK_METHOD dockMethod,
    BOOL bHide);

Parameters

pBar
[in] A pointer to the pane to float.

nTabID
[in] The zero-based index of the tab to float.

dockMethod
[in] Specifies the method to use to make the pane float. For more information, see CBaseTabbedPane::FloatTab.

bHide
[in] TRUE to hide the pane before floating; otherwise, FALSE. Unlike the base class version of this method, this parameter does not have a default value.

Return Value

TRUE if the pane floated; otherwise, FALSE.

Remarks

This method is like CBaseTabbedPane::FloatTab except that it does not enable the last remaining tab on an Outlook bar control to float.

CMFCOutlookBar::GetButtonsFont

Returns the font of the text on the page button tabs of the Outlook bar.

CFont* GetButtonsFont() const;

Return Value

A pointer to the font object that is used to display text on Outlook bar page button tabs.

Remarks

Use this function to retrieve the font that is used to display the text on Outlook page button tabs. You can set the font by calling on CMFCOutlookBar::SetButtonsFont.

CMFCOutlookBar::GetTabArea

Determines the size and position of the tab areas on the Outlook bar.

virtual void GetTabArea(
    CRect& rectTabAreaTop,
    CRect& rectTabAreaBottom) const;

Parameters

rectTabAreaTop
[out] Contains the size and position (in the client coordinates) of the top tab area when the function returns.

rectTabAreaBottom
[out] Contains the size and position (in the client coordinates) of the bottom tab area when the function returns.

Remarks

The framework calls this method to determine the type of docking to the target pane. When the framework determines that the user drags the pane to be docked over the tab area of the target pane, it tries to add the first pane as a new tab of the target pane. Otherwise, it tries to dock the first pane at an appropriate side of the target pane. The framework creates a new container with a slider to accommodate the additional docked pane.

The default implementation of GetTabArea returns the whole client area of the Outlook bar if the Outlook bar is static; that is, if the Outlook bar cannot float. Otherwise, it returns the area that page buttons take at the top and bottom of the Outlook bar control.

Override this method in class derived from CMFCOutlookBar to change this behavior.

CMFCOutlookBar::IsMode2003

Specifies whether the behavior of the Outlook bar mimics that of Microsoft Office Outlook 2003.

BOOL IsMode2003() const;

Return Value

Nonzero if the Outlook bar is running in Microsoft Office 2003 mode; otherwise 0.

Remarks

You can enable this mode by using CMFCOutlookBar::SetMode2003.

CMFCOutlookBar::OnAfterAnimation

Called by CMFCOutlookBarTabCtrl::SetActiveTab after the active tab has been set using animation.

virtual void OnAfterAnimation(int nPage);

Parameters

nPage
[in] The zero-based index of the tab page that has been made active.

Remarks

The visual effect of setting the active tab depends on whether you have enabled animation. For more information, see CMFCOutlookBarTabCtrl::EnableAnimation.

CMFCOutlookBar::OnBeforeAnimation

Called by CMFCOutlookBarTabCtrl::SetActiveTab before a tab page is set as the active tab using animation.

virtual BOOL OnBeforeAnimation(int nPage);

Parameters

nPage
[in] The zero-based index of the tab page that is about to be set active.

Return Value

Returns TRUE if animation should be used in setting the new active tab, or FALSE if animation should be disabled.

Remarks

CMFCOutlookBar::OnScroll

Called by the framework if the Outlook bar is scrolling up or down.

virtual void OnScroll(BOOL bDown);

Parameters

bDown
[in] TRUE if the Outlook bar is scrolling down, or FALSE if it is scrolling up.

Remarks

CMFCOutlookBar::RemoveCustomPage

Removes a custom Outlook bar tab page.

BOOL RemoveCustomPage(
    UINT uiPage,
    CMFCOutlookBarTabCtrl* pTargetWnd);

Parameters

uiPage
[in] Zero-based index of the page in the parent Outlook window.

pTargetWnd
[in] Pointerto the parent Outlook window.

Return Value

Nonzero if the custom page has been removed successfully; otherwise 0.

Remarks

Call this function to delete custom pages. When the page is removed its control ID is returned to the pool of available IDs.

You must provide a pointer to CMFCOutlookBarTabCtrl Class object in which the page to be removed currently resides. Note that a user can move detachable pages between different Outlook bars, but the information about a custom page resides in the Outlook bar object for which you have called CMFCOutlookBar::CreateCustomPage.

Use CBaseTabbedPane::GetUnderlyingWindow to obtain a pointer to the Outlook window.

CMFCOutlookBar::SetButtonsFont

Sets the font of the text on the buttons of the Outlook bar.

void SetButtonsFont(
    CFont* pFont,
    BOOL bRedraw=TRUE);

Parameters

pFont
[in] Specifies the new font.

bRedraw
[in] If TRUE, the Outlook bar will be redrawn.

Remarks

Use this method to set a font for the text displayed on outlook tab page buttons.

CMFCOutlookBar::SetMode2003

Specifies whether the behavior of the Outlook bar mimics that of Outlook 2003.

void SetMode2003(BOOL bMode2003=TRUE);

Parameters

bMode2003
[in] If TRUE, Office 2003 mode is enabled.

Remarks

Use this function to enable or disable Office 2003 mode. In this mode, the Outlook bar has an additional toolbar with a customization button. The behavior of the Outlook bar conforms to the behavior of the Outlook bar in Microsoft Office 2003.

By default, this mode is disabled.

Note

This function must be called before CMFCOutlookBar::Create.

CMFCOutlookBar Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Implementing the Outlook Bar

Outlook 2003 Mode

Inheritance Hierarchy

Requirements

CMFCOutlookBar::AllowDestroyEmptyTabbedPane

Return Value

Remarks

CMFCOutlookBar::CanAcceptPane

Parameters

Return Value

Remarks

CMFCOutlookBar::CanSetCaptionTextToTabName

Return Value

Remarks

CMFCOutlookBar::Create

Parameters

Return Value

Remarks

Example

CMFCOutlookBar::CreateCustomPage

Parameters

Return Value

Remarks

CMFCOutlookBar::DoesAllowDynInsertBefore

Return Value

Remarks

CMFCOutlookBar::FloatTab

Parameters

Return Value

Remarks

CMFCOutlookBar::GetButtonsFont

Return Value

Remarks

CMFCOutlookBar::GetTabArea

Parameters

Remarks

CMFCOutlookBar::IsMode2003

Return Value

Remarks

CMFCOutlookBar::OnAfterAnimation

Parameters

Remarks

CMFCOutlookBar::OnBeforeAnimation

Parameters

Return Value

Remarks

CMFCOutlookBar::OnScroll

Parameters

Remarks

CMFCOutlookBar::RemoveCustomPage

Parameters

Return Value

Remarks

CMFCOutlookBar::SetButtonsFont

Parameters

Remarks

CMFCOutlookBar::SetMode2003

Parameters

Remarks

See also

Feedback

Feedback

Additional resources