BCGControlBar Pro for MFC
CBCGPBreadcrumb

Detailed Description

Breadcrumb control allows the user to explore hierarchical data, such as application-defined libraries or file directories. It may be compared with the tree-view control that does not show the whole items tree at once.

Breadcrumb Items

A breadcrumb item represents a single object of displayed hierarchy. The item has text and optionally an image. Any item in a breadcrumb control may have a list of subitems. An item that has one or more child items is called a parent item. A child item is displayed right to its parent. Parent items also have an arrow at the right of them. The items without children do not have such arrows.

Current Selection

The current selection is a breadcrumb item that the user has selected; the selected item is shown rightmost in the breadcrumb control.

Keyboard Support

Breadcrumb control can accept keyboard focus and allows navigation through its items. Left and right arrow keys move the highlight; up or down arrows show the menu for highlighted item if present. SPACE and ENTER keys select the highlighted item. When the menu is dropped down, all the standard menu keyboard navigation options are available. To leave the menu press ESC. Please note, that the control must have WS_TABSTOP style to allow the user to set focus on it using TAB key.

Creating Breadcrumb Control

The following code sample creates a breadcrumb control:

m_wndBreadcrumb.Create(WS_CHILD | WS_VISIBLE, rectBreadcrumb, this, IDC_BREADCRUMB);

Breadcrumb Window Styles

The following window styles are specific to breadcrumb controls:

  • BCCS_SHOWROOTALWAYS: forces the root item to be always shown in the breadcrumb control. Without this style root item is shown only when selected. Either way it is accessible through the leftmost dropdown list.
  • BCCS_WANTRETURN: specifies that a highlighted item will be selected when the user presses the ENTER key. Without this style, pressing the ENTER key has the same effect as pressing the dialog box's default pushbutton.
  • BCCS_EXTERNALBORDER: specifies that the top and bottom borders of items will not be painted. Use this style if the item border color coincides with the background color of parent dialog or if WS_BORDER style is used.

Notification Messages

The following notification messages are supported:

  • BCCN_SELECTIONCHANGED: notifies a control's parent window that the active item has changed.
    • Map entry: ON_NOTIFY(BCCN_SELECTIONCHANGED, IDC_BREADCRUMB, OnBredcrumbSelectionChanged);
    • Function prototype: afx_msg void OnBredcrumbSelectionChanged (UINT id, NMHDR* pNotifyStruct, LRESULT* result);
    • Remarks: use GetSelectedItem() method of CBCGPBreadcrumb to obtain the new selection.
  • BCCN_INITROOT: notifies a control's parent window that it can set up the root item.
    • Map entry: ON_NOTIFY(BCCN_INITROOT, IDC_BREADCRUMB, OnInitBreadcrumb);
    • Function prototype: afx_msg void OnInitBreadcrumb (UINT id, NMHDR* pNotifyStruct, LRESULT* result);
    • Remarks: the notification is sent during the Create function execution after the breadcrumb control has been successfully created.
  • BCCN_MENUSHOW: notifies a parent window that the control menu was dropped down.
    • Map entry: ON_NOTIFY(BCCN_MENUSHOW, IDC_BREADCRUMB, OnMenuShow);
    • Function prototype: afx_msg void OnMenuShow(UINT id, NMHDR* pNotifyStruct, LRESULT* result);
    • Remarks: Set (* result) to nonzero to prevent the control from showing menu.
  • BCCN_MENUCLOSE: notifies a parent window that the control menu is about to close.
    • Map entry: ON_NOTIFY(BCCN_MENUCLOSE, IDC_BREADCRUMB, OnMenuClose);
    • Function prototype: afx_msg void OnMenuClose(UINT id, NMHDR* pNotifyStruct, LRESULT* result);
  • BCCN_DYNAMIC_GETSUBITEMS: notifies a parent window that it should dynamically add the child items for the specified item.
    • Map entry: ON_NOTIFY(BCCN_DYNAMIC_GETSUBITEMS, IDC_BREADCRUMB, OnGetDynamicSubItems);
    • Function prototype: afx_msg void OnGetDynamicSubItems(UINT id, NMHDR* pNotifyStruct, LRESULT* result);
    • Remarks: The BREADCRUMB_ITEM_NOTIFICATION structure contains the additional information about the parent item. BREADCRUMB_ITEM_NOTIFICATION * pItemInfo = (BREADCRUMB_ITEM_NOTIFICATION *)pNotifyStruct;
  • WM_DELETEITEM: notifies the owner window (typically, a dialog) that one of the breadcrumb items is about to delete. The notification comes only for items with nonzero item data.
    • Map entry: ON_WM_DELETEITEM()
    • Function prototype: afx_msg void OnDeleteItem(LPDELETEITEMSTRUCT);
    • Remarks: the itemData member of DELETEITEMSTRUCT contains the user specified application-defined data for the item being deleted.
  • NM_FONTCHANGED: notifies the owner window (typically, a dialog) that the current font of breadcrumb control has been changed.
    • Map entry: ON_NOTIFY(NM_FONTCHANGED, IDC_BREADCRUMB, OnFontChanged);
    • Function prototype: afx_msg void OnFontChanged(UINT id, NMHDR* pNotifyStruct, LRESULT* result);
    • Remarks: the result value is ignored.

Standard custom control notifications:

  • NM_KEYDOW
  • NM_LDOWN
  • NM_RDOWN
  • NM_CLICK
  • NM_RCLICK
  • NM_SETFOCUS
  • NM_KILLFOCUS
+ Inheritance diagram for CBCGPBreadcrumb:

Public Member Functions

 CreateCreates the breadcrumb control as the child control of specified window.
 
 DeleteItemDeletes the specified item.
 
 GetBackColorReturns background color of the breadcrumb control.
 
 GetDefaultHighlightColorReturns default color of highlighted item background.
 
 GetDefaultHighlightedTextColorReturns the default color of highlighted item text.
 
 GetDefaultTextColorReturns the default color of item text.
 
 GetIconSizeReturns the icon size of the image list used with breadcrumb control.
 
 GetImageListReturns the current image list used with breadcrumb control.
 
 GetItemDataReturns the application-defined value for the specified item.
 
 GetItemDynamicTells whether item is marked as dynamic or not.
 
 GetItemImageIndexReturns image index for the specified item or (-1) if there's no image.
 
 GetItemParentRetrieves parent of item.
 
 GetItemPathCreates a path string for the specified item using the specified delimiter.
 
 GetItemTextReturns item text.
 
 GetItemTooltipTextGets item tooltip text.
 
 GetProgressReturns the progress value.
 
 GetRightMarginReturns right margin.
 
 GetRootItemReturns a handle to root item.
 
 GetSelectedItemReturns a handle to currently selected item.
 
 GetSelectedPathReturns path to selected item as string
 
 GetSubItemGets a subitem of an item.
 
 GetSubItemByNameReturns a handle to a child item with specified text.
 
 GetSubItemsCountReturns the number of child items for the specified item.
 
 InsertItemInserts an item as a child of another item.
 
 IsInplaceEditActiveTells whether the breadcrumb is in inplace editing mode now.
 
 IsOnGlassChecks if control is located on DWM ("Glass") area of the parent window.
 
 OnDrawMenuImageCalled by the framework when a menu image is being rendered.
 
 RefreshDynamicItemRefresh a breadcrumb node with dynamic sybitems.
 
 SelectItemSelects the specified item.
 
 SelectPathSelects an item by string path.
 
 SelectSubPathSelect a subpath relative to the currently selected path.
 
 SetBackColorSets background color for the breadcrumb control.
 
 SetDefaultHighlightColorSets the background color used to paint the item under the mouse pointer.
 
 SetDefaultHighlightedTextColorSets color of text used to paint the item under the mouse pointer.
 
 SetDefaultTextColorSets the color of item text.
 
 SetImageListAttaches an image list to Breadcrumb control.
 
 SetItemDataAssociates the application-defined value with the specified item.
 
 SetItemDynamicMarks the specified item as dynamic.
 
 SetItemImageIndexSets image index for specified item.
 
 SetItemTextSets text for specified item.
 
 SetItemTooltipTextSets item tooltip text.
 
 SetProgressSets the progress value.
 
 SetRightMarginSets right margin.
 

Public Attributes

 m_bVisualManagerStyleSpecifies whether a control has a Visual Manager style look.
 

Protected Member Functions

 GetItemChildrenDynamicCalled for items that marked as dynamic.
 
 OnInitRootCalled when Breadcrumb control is successfully created.
 
 OnKeyDownCalled when the control has the keyboard focus and the user presses a key.
 
 OnLeftClickCalled when the user clicks left mouse button on the breadcrumb control.
 
 OnReturnKeyCalled on Enter key.
 
 OnRightClickCalled when the user clicks right mouse button on the breadcrumb control.
 
 OnSelectionChangedCalled when the selected item has changed.