The following content applies to CAB CTP2. You can find more posts by:
Brad Wilson:
Ed Jezierski:
Peter Provost:
- Converting Monitors to Builders – Coming soon!
Eugenio Pace, David Hill, Daniel Cazzulino, Juan Elichirigoity
Workspaces
Between CTP1 and CTP2 of CAB the workspaces have not really changed. The main changes are how to work with workspaces. I will explain below.
There are three ways to work with workspaces.
- Use the WorkItemTypeCatalogService to register WorkItem types and then use CreateEachWorkItem method to create each WorkItem of a specific type or interface type.
- Find them by string using the Workspaces collection of the WorkItem.
- Pass in the workspace to the WorkItem using the constructor or a Show method
1. WorkItemTypeCatalogService : This service registers and creates WorkItems. With this service you can register the WorkItem type. Presumable the WorkItem implements an interface that defines its Show method and how many workspaces it takes. The interfaces should live in a common assembly which other modules could take a dependency on. This will limit the amount of inter module dependency.
e.g.
public class BankTellerWorkItem : WorkItem, IShowInShell
{
public void Show(IWorkspace sideBar, IWorkspace content)
{
}
}
public interface IShowInShell
{
void Show(IWorkspace sideBar, IWorkspace content);
}
How is this helpful? You can create these WorkItems based on the interface and “Show” them where and whenever you like. Most importantly you can “Show” these WorkItems where you have an instance of the workspaces which mean no magic workspace strings. The below code is inside a WorkItem and listens for an EventBroker event which is fired when a user is changed.
e.g.
private void UserChanged(object sender, EventArgs args)
{
workItemTypeCatalog.CreateEachWorkItem<IShowInLayout>(this, delegate(IShowInLayout item)
{
item.Show(this.sideBar, this.mainLayout.mainLayoutWorkspace);
});
}
This is very similar to WorkItemExtensions but it happens when it is specifically told to happen instead of when a WorkItem of a specific type is created. The WorkItemTypeCatalogService provides a lazy load type behavior for WorkItems.
2. Even with the addition of the WorkItemTypeCatalogService there still is addressability of workspaces by name using the WorkItem. The WorkItem has a Workspaces collection which climbs the hierarchy of WorkItems looking for the workspace. So if a specific workspace was need you would just do something like:
IWorkspace workspace = workItem.Workspaces[“TestWorkspace”];
Retrieving workspaces like this should only be done for well known workspaces. Well know workspaces may be published by the shell for WorkItems to use.
3. And the easiest way to get a workspace to a WorkItem is to pass it in. Workspaces can be passed in on a “Show” method or using the constructor.
e.g.
//Pass in workspace to the Show method
WorkItem childWorkItem = this.WorkItems.AddNew<WorkItem>();
childWorkItem.Show(topWorkspace);
//Pass in workspace into constructor.
ChildWorkItem childWorkItem = new ChildWorkItem(topWorkspace);
Each of these techniques has its uses.
- One is used for a late creation of WorkItems usually talking through interfaces.
- Two is to find well known workspaces. These well known workspaces are usually published by the shell. This technique can also be used inside a module between WorkItems to locate workspaces. If the workspaces are not considered well known refrain from accessing them this way across modules.
o Three is used when inside a module and a WorkItem creates a child WorkItem and can pass the workspace directly.
Using the WorkItemTypeCatalogService provides a different statement from using workspace string addressability when talking about module initialization.
o WorkItemTypeCatalogService: ModuleInit says “Register these WorkItems so another can create and use them at a later time.”
e.g.
//In ModuleInit
public override void Load()
{
// Register workitem so others can create it and use it.
workitemCatalog.RegisterWorkItem<BankTellerWorkItem>();
}
o String Addressability: ModuleInit says “Give me these specific workspaces by name so I can Show these WorkItems now.”
e.g
//In ModuleInit
public override void Load()
{
IWorkspace workspace = parentWorkItem.Workspace[“MainWorkspace”];
ChildWorkItem childWorkItem = parentWorkItem.WorkItems.AddNew<ChildWorkItem>();
childWorkItem.Show(workspace);
}
UIElements
UIElements have changed a fair amount since CTP1. This is something we have put a lot of thought into and continue to put even more into. UIElements now have four parts UIElementManagerFactoryCatalog, UIElementService, UIElementManagerFactory, and UIElementManager.
UIElementManagerFactoryCatalog: A catalog of factories that are registered to be used with a specific type of item. ToolStrips, ToolStripItem, MenuStrip, ToolStripMenuItem, and ToolStripItemCollection are already registered in the WinFormsApplication so there is no need to add them again. Registering a new factory if done like below.
e.g.
//Param one is the type this factory will be used for
//Param two is the factory
catalog.RegisterManagerFactory(typeof(ToolStrip), new UIToolStripManagerFactory());
UIElementFactory: The factory’s primary responsibility is to create UIElementManager’s. These managers are created with the correct constructor for the type.
e.g.
//Sample Factory class
public class UIToolStripManagerFactory : UIElementManagerFactory
{
protected override IUIElementManager GetTypedManager(object managedExtension)
{
IUIElementManager manager = null;
if (managedExtension is ToolStripItem)
{
manager = new UIToolStripManager((ToolStripItem)managedExtension);
}
else if (managedExtension is ToolStrip)
{
manager = new UIToolStripManager((ToolStrip)managedExtension);
}
else
{
throw new ArgumentException(Properties.Resources.UIManagerFactory_NoConstructor);
}
return manager;
}
}
UIElementService: Main interaction point for registering “ExtensionSites” and adding UIElements. Using this service it is possible to register new sites with the managed extension (e.g. menuitem), register a new site with a new manager, add new UIElements to a site, or remove UIElements from a site.
e.g.
Add new extension site.
//Items will be added to the fileItem’s parent (i.e. the menustrip).
//Resolves behind the scenes the type of the managed extension
//to create the correct manager using the factories registered with
//the UIElementManagerFactoryCatalog.
uiSvc.RegisterUIExtensionSite(“File”, fileItem);
//Items will be added to the drop down items of the fileItem.
uiSvc.RegisterUIExtensionSite(“FileDropDown”, fileItem.DropDownItems);
Add new extension site with a new manager.
//This should be very rarely used because the factories will create managers on the fly resolving by type.
//But if for some case you need a specific custom manager for a site you can do it this way.
uiSvc.RegisterUIExtensionSite(“File”, new UIToolStripManager());
Add a UIElement to an existing extension site.
customerItem = new ToolStripMenuItem("Customer");
ToolStripMenuItem returnedCustomerItem = uielementService.Add<ToolStripMenuItem>(“File”, customerItem);
Removing a UIElement from an existing extension site.
uielementService.Remove(“File”, customerItem);
Removing all items from an extension site.
uielementService.RemoveAll(“File”);
UIElementManager: The managers are responsible for adding and removing UIElements. The most impacting change is the removal of the locator. UIElements are no longer addressable by Uri. The main motivation for this is we did not want to have sibling WorkItems easily messing around with UIElements that were added by another WorkItem. Now when working with UIElements either keep a reference to it and/or use commands. The UIElementManager defines an “ExtensionSite” that it manages. In CAB there are already managers for ToolStrips and MenuStrips. Just register the new ExtensionSite using a name and the item you would like to extend using the UIElementService which uses these managers behind the scenes.
We have tried to hit most of the use cases for UIElements in the WinForms project so hopefully there will be very few custom managers to achieve the desired result from UIElements.