...
NavInsertItem takes a Navigation Path and uses it to create an item for that path. The 4 separate types of navigation items have their own hierarchy and you cannot put one type into another hierarchy. The paths can be any path that you define (Apart from the root item) and have little bearing on each other apart from help items and navigation tree items which are discussed below.
Navigation Tree Items and Help
NAVIGATIONTREE and HELP items share a special relationship in the WMC. When a user navigates to an item in the navigation tree, the HELP item with that has a sub path that is the same as the Navigation Path of the item is queried and the resulting content is used to populate the help pane. Therefore, to get help working for your component you should register a HELP such that it has a Navigation Path that is the same as the one used for the NAVIGATIONTREE item. e.g.
Complete Navigation Path of navigation tree item: NAVIGATIONTREE\ControlPanel\MyComponent
Complete Navigation Path of help item: HELP\NAVIGATIONTREE\ControlPanel\MyComponent
In order to ensure the paths match, you can get the navigation path for the tree item with NavGetItem and use the strFQN field as the path passed to NavInsertItem for the help item. The following example inserts an item under the Control Panel item in the tree and associates dynamic help with it.
Code Block |
---|
static NavigationItemUIInterface notificationInterface;
void SetupNotificationInterface()
{
// Set up our notification interface so we can receive messages relating to the the navigation item we will insert into the tree
memset(&gDataUI,0,sizeof(NavigationItemUIInterface));
notificationInterface.dwSize = sizeof(NavigationItemUIInterface);
notificationInterface.NavItemCreateWindow = NavItemCreateWindow; // Called when the framework wants a window from us
notificationInterface.NavItemDrawItem = NULL;
notificationInterface.NavItemNotify = NavItemNotify; // For receiving general messages
notificationInterface.NavItemGetHelpContent = NavItemGetHelpContent; // For dynamic help content in the help pane of the UI
notificationInterface.NavItemFreeHelpContent = NavItemFreeHelpContent;
notificationInterface.NavItemShowContextHelp = NavItemShowContextHelp; // For F1 help
notificationInterface.NavItemKeyboardNavigate = NavItemKeyboardNavigate; // To handle custom keyboard navigation within our panel. (optional)
}
// Called below
NavHandle CreateTreeItem()
{
// Get the correct location to insert our new item under. In this case it will be the "Control Panel" node. This has a well known alias that we can use.
NAVSETITEM controlPanelItem;
if ( !NavGetItem(_T("{ControlPanel}"), &controlPanelItem) )
{
return NULL; // Couldn't find it, so we won't go any further
}
NAVSETITEM treeItem;
memset(&treeItem, 0, treeItem);
treeItem.size = sizeof(NAVSETITEM);
treeItem.flags = NI_FLAG_CUSTOMCONTAINER; // This is a custom container where we control the panel.
treeItem.lParam = NULL; // Set any special context data that you want to be sent with messages to the notificationInterface
treeItem.strLabel = L"Ad Blocker";
treeItem.strDescription = L"This component adds an HTTP Filter that blocks advertising";
treeItem.hModule = AfxGetResourceHandle(); // Where to get resources from
treeItem.nIconId = iconResourceId; // Some resource id of the icon to display in the navigation tree
treeItem.EventMask = 0; // No special events. NI_EVENT_ACTIVATE, NI_EVENT_DEACTIVATE are always sent. See NavInsertItem for more information
treeItem.pInterface = notificationInterface; // The interface we are wanting to use to handle events from this item
treeItem.strAlias = L"{MyCompanyAdBlocker}"; // Adds an alias. Makes it easier to find and compare navigation items later.
if ( !NavInsertItem(controlPanelItem.hItem, L"MyCompanyAdBlockerPath", &treeItem) ) // The path "MyCompanyAdBlockerPath" is an internal name the user never sees but must be unique under a particular root.
{
return NULL;
}
return treeItem.hItem;
}
std::wstring GetFQNOfTreeItem(NavHandle treeItem)
{
NAVSETITEM itemData;
NavGetItemEx(treeItem, &itemData);
return itemData.strFQN;
}
NavHandle GetHelpRoot()
{
NAVSETITEM item;
if(NavGetItem(_T("HELP"), &item))
{
return item.hItem;
}
return 0;
}
void SetUpNavigationItems()
{
SetupNotificationInterface();
NavHandle treeItem = CreateTreeItem();
std::wstring treeItemFqn = GetFQNOfTreeItem(treeItem);
NavHandle helpRoot = GetHelpRoot();
NAVSETITEM helpItem;
memset(&helpItem, 0, helpItem);
helpItem.size = sizeof(NAVSETITEM);
helpItem.strLabel = L"My help label";
helpItem.strDescription = L"Help for my component";
helpItem.flags = NI_FLAG_DYNAMICHELP; // We want to be called dynamically.
helpItem.EventMask = NI_EVENT_NOTIFY; // Need to set this so our callback for dynamic help is processed
helpItem.pInterface = ¬ificationInterface; // Interface to handle callbacks to ask for dynamic help
NavInsertItem(helpRoot, treeItemFqn, helpItem); // Insert the item as a child of HELP, with the same path as the tree item
}
|
Aliases
Navigation Paths can have aliases that are used to quickly reference a path without having to know the entire underlying path. NavInsertItem allows you to specify an alias when you add the item. It must consist of a '{' character followed by the (case sensitive) alias name and a '}'. e.g {ControlPanel} references the Control Panel node in the navigation tree whose real Navigation Path is NAVIGATIONTREE\ControlPanel
Help
HELP\NAVIGATIONTREE\Header - All Header items are put into header of help, regardless of location in tree
HELP\NAVIGATIONTREE\Main