Introduction
This article provides a implementation of a WPF Breadcrumb control, and describe how to develop one.
Background
When Vista released one of it's main features is Breadcrumb explorer bar, I always want to build one, but I was lack of knowledge to develop one myself.
nesher created a
breadcrumb component couple months ago, which is fully working one, but it is a xaml intensive solution and is too complicated for me to understand the code, not to mention I want to modify it and add features, so I write my own using MVP pattern (where the model is a string).
His implementation gave me idea how to develop a breadcrumb, and
I took a couple style from his implementation.
Beside that, my implementation Is a complete rewrite, and they have a couple differences :
- It is fully string based, that means
- SubFolder polling is done manually. You cannot bind a HierarchicalDataModel. and expect it to work automatically.
(you can still attach your model in the BreadcrumbItemBase however).
- you can "change folder" by supplying a path, the component support conversion from display to logical path, or vice versa.
- you can use two or more different "Root", like Folder and Animal in demo, this is changable in runtime.
- expander support, which shows when you have too many BreadcrumbItems on the Breadcrumb.
- dropdown support, the BreadcrumbControl itself is a ComboBox. (ver2)
- progressbar support,
- autocomplete textbox support.
- remember child position when changing directory, only rearrange when necessary.
How to use?
If you want to use the component as directory Breadcrumb only, just add the main control to your window.
The main control have a bindable property named
SelectedFolder, which is a string, you can bind it to other component, e.g.
<TextBox x:Name="tb" Text="{Binding ElementName=breadcrumb, Path=RootFolder}" />
<uc:BreadcrumbControl Margin="0,50,0,0" x:Name="breadcrumb" />
If you want to use the component to display custom data, you will have to write
- a view, a view, which is a DataTemplate,
<DataTemplate x:Key="folderDataTemplate">
<DockPanel>
<!-- an Icon and a textbox -->
<Image Height="16" Width="16"
Source="{Binding Icon}" />
<TextBlock Text="{Binding DisplayName}" Margin="2,0" />
</DockPanel>
</DataTemplate>
<!-- hook it to SubItemTemplate of BreadcrumbControl -->
<uc:BreadcrumbControl SubItemTemplate="{StaticResource folderDataTemplate}"/>
- a presenter, which derived from BreadcrumbItemBase, which implements the following :
If you want to attach your model, you can attach it inside your derived presenter.
//Required//
//Poll a list of subfolders of current directory. (it's only called when needed)
//Threading is already implemented, you dont have to implement your own.
public override BreadcrumbItemBase[] PollSubFolders();
//Optionsl//
//Convert from DisplayPath to LogicalPath, or vice versa
//DisplayPath is based on DisplayName (e.g. Computer\C:\\Program Files\qzLite3)
//LogicalPath is based on FolderName (e.g. C:\ProgramFiles\qzLite3)
public override string ConvertPath(BreadcrumbItemBase.PathType pt, string path)
//Return Icon of current folder
public override ImageSource GetIcon()
- modify the BreadcrumbControl to support your new presenter and view.
CustomPresenter Root = new CustomPresenter();
SwitchPresenter(Root);
//Once you run the above code, the BreadcrumbControl will use your presenter.
How it works?
As I mentioned before, the whole thing is string base, ItemsPresenter
return string as folder, folder creation is based on a folder name,
thats why you have to make sure the code is legit before passing it to
CurrentFolder property in BreadcrumbControl, (TypedPresenter do have
some kind of lookup, other implementations dont check if the folder
exists),
String based make it easier to develop (Breadcrumb usually use as navigation purpose, sometimes you dont want to make a model for every navigation item), however, it restrict the amount
of information to display in view, fortunately for BreadcrumbItems, it
requires only an Icon and a text, I can easily use a "Converter" to do
this work. for folder path, I used PathToDirNameConverter, for Icon, I
used a
FileToIcon converter.
The diagram is as follows.
Part of the program (AutoCompleteTextBox and BreadcrumbCore) is designed using Model - View - Presenter design pattern, this separate UI code and Logic code and reduce complexity.
The BreadcrubCore contain a number of components :
- a BreadcrumbCore - contain an expander,
- Contain one or more BreadcrumbItems
- an AutoCompleteTextBox (AutoCompleteTextBox)
- a ProgressBar.(accessable via Progress and IsIndeterminate in BreadcrumbControl)
- a number of buttons
- a toggle button which toggle between the AutoCompleteTextBox and BreadcrumbCore.
- a toggle button for dropdown
- a refresh button (raise RefreshClicked event when clicked).
AutoCompleteTextBox The "AutoCompleteTextBox
" suggest items based on input, it will look for all items in the current folder, and display if the text is matched :
List<string> retVal = new List<string>();
foreach (BreadcrumbItemBase subFolder in _currentPresenter.ActualSubFolders)
if (subFolder.FolderPath.ToLower().StartsWith(_selectedPath.ToLower()))
retVal.Add(subFolder.FolderPath);
Suggestions = retVal.ToArray(); // output the suggestions
The BreadcrumbItem
The BreadcrumbItem are items inside the container, it's composed of a custom
BreadcrumbItemBase(Presenter) and
a ComboBox(View):
BreadcrumbItemBase is the presenter of BreadcrumbItems, a couple ItemsPresenter defined in the demo :
- BreadcrumbItemBase - base class, derive from this for define custom BreadcrumbItemBase
- FolderPresenter - contain logic to current folder and poll subfolders.
- AnimalPresenter - for test purpose only, generate cat/dog/rat combination as subfolders.
The view part of BreadcrumbItems is a styled ComboBox, which have Items bound to ItemPresenter's SubFolders, the ComboBox have the following items :
- Main button (buttonCurrent), which occupied most space on the ComboBox, when user click on it, change to current folder. (thats why it caled button Current)
- Toggle button (buttonExpand) which specify if the Popup is shown (I used nesher's style here)
- Popup (PART_Popup), the popup part, it's called that way because WPF required it..
- ItemsPresenter (itemList), located in the popup, hold all SubFolders (strings).
nesher's implementation uses a context menu instead of ComboBox, this can be easier implemented using ComboBox, however, the default position of the Popup in the ComboBox Aligned Left side of the ComboBox, one have to change the Placement and PlacementTarget property of the Popup, like below :
<Popup ... Placement="Bottom" PlacementTarget="{Binding ElementName=buttonExpand}" />
and BTW, TranslateTransform doesnt work to reposition the Popup, e.g. the following doesnt work :
<Popup.RenderTransform>
<TranslateTransform X="150" Y="0"/>
</Popup.RenderTransform>
To Implement expander :
The BreadcrumbCore 's container
is a customized Panel (
BreadcrumbCorePanel),
this panel overrided ArrangeOverride and MeasureOverride, so when out
of space, the first visible items is hidden until enough space for
latter items. Because hidden items should be shown on the expander (or
Root), when
BreadcrumbCorePanel hide a BreadcrumbItemBase, it
will set it's IsHitTestVisible to false, BreadcrumbItemBase listen to
this property so when it's changed to false, it will call add itself to
expander.
public bool HitTestVisible { get { return true; } set { changedHitTestVisible(value); } } //Bound to UI
private void changedHitTestVisible(bool value)
{
if (!value) _parentPresenter.Expander.Add(DisplayPath);
else _parentPresenter.Expander.Remove(DisplayPath);
}
The ToggleButton is hidden if there's no item in the list.
Uncompleted items
References
History
02-01-09 Initial version
03-01-09 Fix : ghost folder in expander.
03-01-09 Add: return selected folder model (for TypedPresenter)
04-01-09 Add: Alt+D Toggle TextBox/Breadcrumb
04-01-09 Add: autocomplete textbox now support non-diskfolder types.
04-01-09 Version 1.2
04-01-09 Fix : pressing enter button in textbox does not switch back to breadcrumb if the text is not changed.
05-01-09 Upd : code clean up, assembly is created. (QuickZip.UserControls.Breadcrumb.dll)
05-01-09 Add : the view part is moved to BreadcrumbControl.SubItemTemplate (See Demo, article require update)
05-01-09 Fix : some update to TypedPresenter is added.
05-01-09 Version 1.3
05-01-09 Fix : Alt+D Toggle not working correctly.
05-01-09 Upd : select last char when toggle to textbox.
05-01-09 Add : remember child position
05-01-09 Fix : crash when suggestion changes when selection folder.
05-01-09 Version 1.4
06-01-09 Fix : ghost folder again (broken in last version)
06-01-09 Version 1.5
07-01-09 Add : QuickZip.UserControls.TypedBreadcrumb.dll, designed for Model use.
07-01-09 ---- : (Expander is not complete and autocomplete textbox not showing suggestions in some case, will be added in next version)
07-01-09 Upd : demo updated to reflect changes.
07-01-09 Article update
07-01-09 Version 1.6
08-01-09 Fix : Expander and AutocompleteTextbox in TypedBreadcrumb.
08-01-09 Version 1.7
16-01-09 Upd : Rewrite, simplify the code and added some documentation (not finished yet).
16-01-09 Upd : Removed the expander and place the expander logic in root (look more like vista's breadcrumb).
16-01-09 Add : Support folder with null FolderName now (e.g. Desktop\Computer)
16-01-09 Add : Support Adding Custom folder to expander list now (see IRoot interface in IExpander.cs, or the demo)
16-01-09 Add : Support Adding Separator to expander list.
16-01-09 Version 2.1
16-01-09 Add : Refresh button.
16-01-09 Add : History dropdown
16-01-09 Fix : Splitter width.
16-01-09 Upd : Display Root caption when no items is selected
17-01-09 Fix : IsTextBoxEnabled is now working.
17-01-09 Version 2.2
17-01-09 Fix : DropDown SelectedIndex not reset when opened.
18-01-09 Add : RefreshCommand/Parameter/Target.
18-01-09 Upd : Documentation of BreadcrumbItemBase.cs
18-01-09 Version 2.3
20-01-09 Upd : Better DataBinding support.
22-01-09 Add : Animation when root folder resizing, change folder.
22-01-09 Version 2.4
23-01-09 Fix : Adding folder to expander (internally) will change root selected index, and lead to unintended folder change.
23-01-09 Version 2.5
