Message Bar items are messages with an accompanying hyperlink that, when clicked, navigates the user to a location in the navigation tree.
Add a message bar item with NavInsertItem.
void AddMessageBarItem(LPCWSTR text, LPCWSTR link)
{
// First get the root of the MESSAGEBAR domain
NAVSETITEM messageBarRootData;
memset(&messageBarRootData, 0, sizeof(NAVSETITEM));
if( !NavGetItem(_T("MESSAGEBAR"), &messageBarRootData) )
{
return; // Failed to find MESSAGEBAR root
}
NavHandle messageBarRoot = messageBarRootData.hItem;
// Now add a simple message bar item
NAVSETITEM newItem;
memset(&newItem, 0, sizeof(newItem));
newItem.flags = NI_FLAG_MESSAGEBAR_ICONWARNING; // The icon we want to show. NI_FLAG_MESSAGEBAR_ICONINFO, NI_FLAG_MESSAGEBAR_ICONWARNING and NI_FLAG_MESSAGEBAR_ICONSHIELD
newItem.EventMask = NI_EVENT_MOUSE_LCLICK; // Need click events to navigate somewhere when the link is clicked
newItem.strLabel = L"This is a message bar message";
newItem.strDescription = L"NAVIGATIONTREE\\ControlPanel\\Events"; // Override description field as the FQN or alias to navigate to when the link is clicked
newItem.lParam = 0; // Custom context data
newItem.pInterface = ¬ificationInterface; // Interface to handle messages from the message bar
NavInsertItem(messageBarRoot, _T("MyComponentWarningEvents"), &newItem);
} |
Items added in the manner shown above display the strLabel text as the message, followed by a link that says "Go There". If you click the link, the WMC navigates to the location specified in strDescription. You can provide customised hyperlink text by providing your own XAML content. See Custom link text.
The flags field of the NAVSETITEM structure dictates how the message bar item will be handled.
| Flag | Description |
|---|---|
NI_FLAG_MESSAGEBAR_ICONWARNING NI_FLAG_MESSAGEBAR_ICONINFO NI_FLAG_MESSAGEBAR_ICONSHIELD | The type of icon to show. Mutually exclusive. |
| NI_FLAG_MESSAGEBAR_NOTIFY | Notify the item of the click. Calls the NavItemNotify handler of the notification interface supplied in NavInsertItem. Without this flag the default behaviour is to go to a navigation location. |
| NI_FLAG_MESSAGEBAR_USERXAML | Specify to supply custom XAML for the item. See below for details. |
The default link text is Go There but it can be customised by providing your own message string with your link text surrounded by the <a></a> tags when inserting the element. To use a custom message you need to set the flag NI_FLAG_MESSAGEBAR_CUSTOMMESSAGE in the NAVSETITEM structure.
void AddMessageBarItem(LPCWSTR text, LPCWSTR link)
{
// First get the root of the MESSAGEBAR domain
NAVSETITEM messageBarRootData;
memset(&messageBarRootData, 0, sizeof(NAVSETITEM));
if( !NavGetItem(_T("MESSAGEBAR"), &messageBarRootData) )
{
return; // Failed to find MESSAGEBAR root
}
NavHandle messageBarRoot = messageBarRootData.hItem;
NAVSETITEM newItem;
memset(&newItem, 0, sizeof(newItem));
newItem.flags = NI_FLAG_MESSAGEBAR_CUSTOM_MESSAGE;
newItem.EventMask = NI_EVENT_MOUSE_LCLICK;
newItem.strLabel = L"This is the text <a>with an embedded link</a> to navigate to";
newItem.strDestination = _T("{Notifications}"); // where to go to
newItem.lParam = (LPARAM)this;
newItem.pInterface = &gTaskInterface;
NavInsertItem(hMessageBar, _T("NotificationWarning"), &newItem);
NavHandle messageBarItem = newItem.hItem;
} |
Hyperlink tag is always the item to look up to check how the event is processed (NOTIFY or GOTO).
If item wants to be notified (MESSAGEBAR_NOTIFY) then Hyperlink tag is the string to call NavNotifyItem on e.g. "MESSAGEBAR\NotificationWarning". So basically the target and notify items are the same.