Controls will not do or display anything unless they are associated with a command. Once a control is associated with a command the control can execute the command and display information about the command.

Commands serve a dual purpose: State and functionality.

State in the sense that when a control displays a text string, or when a button is enabled or disabled, then this is just the control reflecting the state of a command.

Functionality in the sense that whenever a toolbar does something it is because a command has been executed.

In other words, the controls are the UI layer of a toolbar and the commands are the functionality/model layer.

The two layers are completely separated. Communication between the two layers goes through a few well-defined interfaces.

Implementing a toolbar means implementing the commands. The controls are implemented by the framework.

1.2 XML Configuration

Controls and commands are associated through an XML configuration file. The XML file simply lists the controls in the toolbar in order, and associates each control with a named command.

1.3 IWebBrowser2

The IWebBrowser2 interface and the interfaces associated with the DHTML document object model are very important when programming within the Diodia ToolbarCreator framework since all access to the Internet Explorer goes through these interfaces. More information is available at http://msdn.microsoft.com.

1.4 Object Model

The ToolbarCreator object model is very simple. It consists of 6 classes: ControlC, ToolBandC, CommandC, CommandSetC, ToolBandContextC and ToolBandHookC. Each class is described briefly in the following.

1.4.1 ControlC

Control objects represent toolbar buttons etc.. The framework supports 7 different controls types: Menu, button, label, edit, read-only, combo-box and separator.

A menu control implements a pop-up menu. Multiple levels of sub-menus are supported.

Button

Three different button sub-types exist:

1. Push-button: A regular button executing a command.

2. Toggle-button: An on/off button.

3. Mixed-button: A combination of a push-button and a menu.

Push-buttons and toggle-buttons can be placed directly in a toolbar or in menus, where they act as menu entries. Mixed buttons can only be placed directly in a toolbar.

Button controls placed directly in a toolbar can display a bitmap, a text string or both. Button controls placed in a menu can only display a text string.

Label

A label is a fixed text string displayed in the toolbar.

Edit

An edit control is a text field where text can be entered.

Read-only

A read-only control is a text field displaying text that can’t be edited. Read-only controls are usually displaying status information.

Combo-box

A combo-box is a combination of an edit-control and a drop-down list. Two combo-box subtypes exist: Regular and fixed-list. In a regular combo-box text can be typed into the edit control. In a fixed-list combo-box the user must choose between a fixed set of items.

Separator

A separator is a vertical line displayed in the toolbar. Separators are used to give the visual appearance that controls are grouped together.

ControlC objects are implemented entirely by the framework.

1.4.2 ToolBandC

A toolbar is created by adding controls to a toolband object.

The toolband object is responsible for drawing the toolbar on the screen.

ToolBandC objects are implemented entirely by the framework.

1.4.3 CommandC

Command objects implement the actual functionality of a toolbar.

Command objects are activated e.g. when the user clicks on a button in the toolbar, or when he selects an item in a combo-box.

Examples of commands could be a “Go Home” command or a “Search Google” command:

The class CommandC implements basic command functionality such as the ability to be executed and a command name attribute.

All commands created for a specific toolbar are derived from class CommandC.

1.4.4 CommandSetC

The command set object stores a set of command objects.

CommandSetC objects are implemented entirely by the framework.

1.4.5 ToolBandContextC

The toolband context object glues everything together.

The class ToolBandContextC implements basic toolband context functionality such as the ability to store command objects and a reference to the Internet Explorer.

A specific toolbar always derives a more specialized context class from class ToolBandContextC.

The derived context creates command objects for the specific toolbar and defines the toolbar layout.

1.4.6 ToolBandHookC

The toolband hook object is the link between the Internet Explorer and the toolbar.

The Internet Explorer queries the toolbar for information through various interfaces on the hook, e.g. the width and height of the toolbar. All the interfaces are implemented by the framework, so usually you don’t have to worry about the hook.

However, if you want to do something in response to Internet Explorer events, such as “new page opened”, then you must add functionality to the hook.

1.5 Interfaces

The objects model also defines a set of interfaces through which the objects communicate. They are:

CommandContainerI

CommandI

CommandObserverI

CommandSetI

ControlCollectionI

ControlI

ToolBandI

1.6 Getting Started

To create a new toolbar first run Diodia ToolbarCreator. The following assumes that a new toolbar called MyToolbar has been created.

Visual Studio Projects

Diodia ToolbarCreator generates a Visual Studio 2005 project and a corresponding solution file:

MyToolbar.vcproj: A Microsoft Visual Studio 2005 project.
MyToolbar.sln: A Microsoft Visual Studio 2005 solution.

The Visual Studio project includes all the basic functionality required of an Internet Explorer toolbar.

The project contains four build configurations: Debug, Release, Unicode Debug and Unicode Release.

The project can be built immediately. The result is a simple toolbar that illustrates the available controls.

Output from build

A toolbar is just a single self-registering dll. Visual Studio registers the dll automatically when a project is built.

The dll must be registered with e.g. regsvr32.exe if the dll is installed on another PC:

Right-click on the dll, select “Open with…” and choose the program regsvr32.exe, usually located in C:\Windows\System32,
or execute
C:\Windows\System32\regsvr32 <path to dll>
from a shell,

Typically an installation program will install and register the dll. A Visual Studio 2005 Setup Project can be used.

1.6.1 Project Classes

A specific toolbar needs to implement a toolband context, a toolband hook and a set of commands specific to this exact toolbar.

The context and the hook are pre-implemented by the classes ContextC and HookC, respectively.

The context contains the command set to which new commands are added.

Internet Explorer events are handled by adding functionality to the hook.

The initial Visual Studio project implements six sample commands:

MyToolbar.About: Opens an About dialog.
MyToolbar.Scroll: Scrolls the current web page to the top, the middle or the bottom.
MyToolbar.GoHome: Navigates the Internet Explorer to the start page.
MyToolbar.StatusBar: Toggles the Internet Explorer’s status bar on and off.
MyToolbar.SearchGoogle: Searches for a given word or phrase on Google.
MyToolbar.FileSize: Calculates the size in bytes of the current web page.

The commands can be used as templates when the actual commands of the toolbar are implemented.

1.6.2 Built-in Commands

The framework comes with a small set of built-in commands that make it easier to implement common functionality, for example link buttons.

The built-in commands are

Navigate: Navigates the Internet Explorer to a given URL.
JavaScript: Executes a JavaScript on the current web page.
VBScript: Executes a VBScript on the current web page.
ToolBand.ToolbarLayout: Opens a customize dialog, where the user can choose which controls to display in the toolbar.
FindNext: Searches for a word or a phrase on the current web page.
FindPrevious: Ditto.
Highlight: Highlights a word or a phrase on the current web page.
Execute: Starts another application.
Html: Makes it possible to display HTML text in a toolbar.

The sample project illustrates how to use the built-in commands. A few lines must be uncommented in the configuration file ToolbarLayout.xml to activate some of the examples.

1.6.3 Project Files

The Visual Studio projects contain the following files:

Header files:

Commands.h: Class definitions for the toolbar commands.

ContextC.h: Class definition for the specialized toolband context.

HookC.h: Class definition for the specialized toolband hook.

Resource.h: Resource constants.

StdAfx.h: Standard includes.

Source files:

Commands.cpp: Implementation of the toolbar commands.

Context.cpp: Implementation of the specialized toolband context object.

Hook.cpp: Implementation of the specialized toolband hook.

Framework.cpp: Framework initialization.

MyToolbar.def: Standard library definition file.

MyToolbar.idl: COM interface definitions.

StdAfx.xpp: Makes precompiled headers.

Resource files:

*.bmp: Bitmaps for the toolbar buttons.

manifest.xml: Manifest enabling Windows XP visual styles.

MyToolbar.rc: Resource script with strings, dialogs, etc..

MyToolbar.rgs: Registry script for dll self-registration.

ToolbandLayout.xml: XML configuration file defining the toolbar layout.
hello.js: A small JavaScript that can be activated from the toolbar.

1.6.4 Framework includes files

Framework include files are located in the sub-directory include.

1.6.5 Framework library files

Framework library files are located in the sub-directory lib8. Both release and debug versions of the library files are included.

1.7 Adding Controls to a Toolbar

1.7.1 Implementing a “Go Home” Button

To add a “Go Home” button to a toolbar you follow these steps:

1) Implement the “Go Home” command object.

2) Add the “Go Home” command to the command set in the context.

3) Insert a button control in the toolbar.

4) Associate the button control with the “Go Home” command.

All in all, fewer than 20 lines of C++ source code and 1 line of XML configuration.

The first step is to implement the “Go Home” command object.

Command objects are derived from the class CommandC, which implements basic command functionality.

The “Go Home” command object is declared as:

class GoHomeCmdC : public CommandC

{

public:

GoHomeCmdC();

virtual void Execute();

};

Each command must have a unique name, which is defined in the commands constructor:

GoHomeCmdC::GoHomeCmdC()

{

// set unique command name

SetId("MyToolbar.GoHome");

// make the command initially enabled

SetSensitive(true);

}

Once a button is associated with the command, and the button is clicked, the framework calls the command’s Execute() method. The command object can use the mWebBrowser member variable to navigate the Internet Explorer to its home page:

void GoHomeCmdC::Execute()

{

// mWebBrowser is the Internet Explorer’s IWebBrowser2 interface

mWebBrowser->GoHome();

}

The next step is to make the command known to the framework. This is done by adding the command to the context’s command set from the context’s Initialize() method:

void ContextC::Initialize()

{

AddCommand(new GoHomeCmdC);

}

Finally, a button control is inserted in the toolbar and associated with the “Go Home” command by adding a <button> tag to the toolbar’s XML configuration file:

<?xml version="1.0" encoding="ISO-8859-1"?>

1.7.2 Implementing a “Search Google” Combo-Box

The first step is to implement the “Search Google” command object:

class SearchGoogleCmdC : public CommandC

{

public:

SearchGoogleCmdC();

virtual void Apply(CString Text);

};

The drop-down list with previous search phrases would normally be initialized in the constructor, but in this example the command does not save the history, i.e. the history is lost when the Internet Explorer exits.

SearchGoogleCmdC::SearchGoogleCmdC()

{

// set unique command name

SetId("MyToolbar.SearchGoogle");

// make the command initially enabled

SetSensitive(true);

}

The Apply() method is overridden instead of the Execute() method because the command is to be associated with a combo-box. The framework calls Apply() when the user enters text or selects an item in the combo-box:

void SearchGoogleCmdC::Apply(CString Text)

{

// create the query URL

variant_t Url = CString("http://www.google.com/search?q=") + Text;

// navigate to Google's search page

mWebBrowser->Navigate2(&Url, NULL, NULL, NULL, NULL);

// add the query to the search history, if it’s not already there

const ItemList *List = GetItemList();

for (unsigned Idx = 0; Idx < List->mList.size(); Idx++)

if (List->mList[Idx] == Text)

return;

// the search history is saved in the commands item list

AddItem(Text);

}

The “Search Google” command is added to the context’s command set:

void ContextC::Initialize()

{

AddCommand(new SearchGoogleCmdC);

}

And finally, a combo-box control is inserted in the toolbar and associated with the “Search Google” command by adding a <combo-box> tag to the toolbar’s XML configuration file:

<?xml version="1.0" encoding="ISO-8859-1"?>

<combo-box command="MyToolbar.SearchGoogle" width="200"/>
</toolband>

1.7.3 Implementing “Find & Highlight “ Buttons

The Google Toolbar adds a new button to the toolbar for each word or phrase contained in a query when a search is performed. Each button finds the next occurrence of a word or a phrase on the current web page.

To implement similar “Find & Highlight” buttons for the “Search Google” combo-box described in the previous example, first implement a “Find & Highlight” command object:

class FindAndHighlightCmdC : public CommandC

{

public:

FindAndHighlightCmdC(const char *Find);

virtual void Execute();

protected:

std::string mFind;

};

The word to find and highlight is saved in the command constructor. The word is also incorporated in the command name to make the command name unique:

FindAndHighlightCmdC::FindAndHighlightCmdC(const char *Find)

{

mFind = Find;

SetId((std::string("MyToolbar.") + Find).c_str());

SetSensitive(true);

}

The commands Execute() method uses the mWebBrowser member, i.e. the IWebBrowser2 interface and the Internet Explorers object model, to find and highlight a word. The details are omitted here:

void FindAndHighlightCmdC::Execute()

{

// use mWebBrowser member to find and highlight mFind

:
}

Find and highlight buttons are added at the end of the toolbar when a search is performed. This example just adds a single button finding and highlighting the entire query string. A proper implementation would split the query into individual words and phrases, and add a button for each.

A new member function maintaining the find and highlight buttons is added to the “Search Google” command object. Members keeping track of the current buttons are also added:

class SearchGoogleCmdC : public CommandC

{

public:

SearchGoogleCmdC();

virtual void Apply(CString Text);

protected:

void UpdateFindButtons(const char *Query);

CommandPointerSetC mCommands;

ControlPointerSetC mControls;

};

The control collection interface on the toolband object is used to add the search button at the end of the toolbar. If the toolbar contains a button from a previous search then this button is deleted first:

void SearchGoogleCmdC::UpdateFindButtons(const char *Query)

{

ToolBandI *ToolBand = mContext->GetToolBand();

int Idx;

// first delete the old search buttons (there can be at most one)

for (Idx = 0; Idx < mControls.GetSize(); Idx++)

ToolBand->GetControlCollection()->DeleteControl(mControls[Idx]);

mControls.Clear();

for (Idx = 0; Idx < mCommands.GetSize(); Idx++)

mContext->DeleteCommand(mCommands[Idx]);

mCommands.Clear();

// create a new search command and a new search button

CommandC *FindCmd = new FindAndHighlightCmdC(Query);

ControlI *FindButton = CreateButtonControl(FindCmd, Query);

// save command and button, so we can delete later

mCommands.AddCommand(FindCmd);

mControls.AddControl(FindButton);

// add the command to the toolband context

mContext->AddCommand(FindCmd);

// add the new button to the toolband (there is only one)

for (Idx = 0; Idx < mControls.GetSize(); Idx++)

ToolBand->GetControlCollection()->AddControl(mControls[Idx]);

}

Finally, the UpdateSearchButton() is called when a search is performed, i.e. from the Apply() method of the “Search Google” command.

void SearchGoogleCmdC::Apply(CString Text)

{

// create the query URL

variant_t Url = CString("http://www.google.com/search?q=") + Text;

// navigate to Google's search page

mWebBrowser->Navigate2(&Url, NULL, NULL, NULL, NULL);

const ItemList *List = GetItemList();

for (unsigned Idx = 0; Idx < List->mList.size(); Idx++)

if (List->mList[Idx] == Text)

return;

// add the query to drop-down list

AddItem(Text);

// add Find & Highlight buttons

UpdateFindButtons(Text);

}

1.8 Using Built-in Commands

1.8.1 Navigate

The Navigate command is used to open web pages.

In its simplest form it can be used to create a button that opens a specific web site. This is done by adding a button tag to the toolbar configuration file:

By default the Navigate command opens the web page in the same window, but a target frame can be specified. The button defined below opens the same web page in a new window:

The navigate command can also be associated with an edit control or a combo-box control. For example, a Navigate command associated with a “search box” edit control can be used to open a web page with search results.

The URL to the search results includes the search phrase, which in this case is the text displayed in the edit control.

To specify where in the URL to insert the search phrase a pattern is used. The pattern has the form ##ControlId##.

ControlId indicates which control to get the search phrase from. So to make the search box work, an id must be assigned to the “search box” edit control.

The “search box” therefore looks like this in the toolbar configuration file:

The same principle makes it possible to create “search buttons” by using Navigate commands.

For example, suppose you want the edit control to search on Google by default, but sometimes you want to search on Yahoo instead.

This can be achieved this by creating a button next to the edit control that gets its search phrase from the edit control by using the id of the edit control. For example:

1.8.2 JavaScript

The JavaScript command can execute a piece of JavaScript on the current web page.

The code to execute is specified in the script attribute on the control activating the JavaScript command:

If the code to execute is more than a few statements then it can be placed in a file. The file must have the extension .js and it must be included in the toolbar dll as a HTML resource.

The sample toolbar generated by toolbar creator illustrates this.

The framework can either run the script once in the innermost frame on the current web page, or once in each frame on the web page. This is of course only relevant if the web page contains frames.

To run the script once, define a function called diodia_run_once() in the script file. For example:

function diodia_run_once()

{

alert("Hello!");

}

To run the script in all frame, define a function called diodia_run_in_all_frames() in the script file. For example:

function diodia_run_in_all_frames()

{

alert("Hello!");

}

1.8.3 VBScript

The VBScript command is similar to the JavaScript command, except it executes VBScript instead of JavaScript.

VBScript files must have extension .vb or .vbs.

The framework calls either the sub routine diodia_run_once or diodia_run_in_all_frames, so one of these must be defined in the script file. For example:

Sub diodia_run_once()

MsgBox "Hello!"

End Sub

1.8.4 Toolband.ToolbarLayout

The Toolband.ToolbarLayout command opens the customize dialog. The dialog lets the user disable toolbar controls:

1.8.5 FindNext

The FindNext command finds the next occurrence of a text string on the current web page.

The pattern attribute contains the text string to search for, or alternatively, the id of an edit or combo-box control to retrieve the text string from. The id must be enclosed in ##.

Example:

<edit command="Navigate"
        id="SearchBox"
        width="100"
        url="http://www.google.com/search?q=##SearchBox##"/>

<button command="FindNext"

pattern="##SearchBox##"

caption="Find Next"

tooltip="Find Next"

image="203"/>

1.8.6 FindPrevious

The FindPrevious command finds the previous occurrence of a text string on the current web page.

The pattern attribute contains the text string to search for, or alternatively, the id of an edit or combo-box control to retrieve the text string from. The id must be enclosed in ##.

Example:

<edit command="Navigate"
        id="SearchBox"
        width="100"
      url="http://www.google.com/search?q=##SearchBox##"/>

<button command="FindPrevious"

pattern="##SearchBox##"

caption="Find Previous"

tooltip="Find Previous"

image="204"/>

1.8.7 Highlight

The Highlight command highlights all occurrence of a text string on the current web page.

The pattern attribute contains the text string to highlight, or alternatively, the id of an edit or combo-box control to retrieve the text string from. The id must be enclosed in ##.

The color attribute contains the color to highlight with.

Example:

<edit command="Navigate"
        id="SearchBox"
        width="100"
      url="http://www.google.com/search?q=##SearchBox##"/>

<button command="Highlight"

pattern="##SearchBox##"

caption="Highlight"

tooltip="Highlight"

image="205"

color="yellow"

toggle-button="yes"/>

1.8.8 Execute

The Execute command launches an application.

The parameter attribute contains the file name of the application to launch.

Example:

<button command="Execute"

parameter="Calc.exe"

caption="Calculator"

tooltip="Calculator"

image="206"/>

Note: Using the Execute command requires elevation support, even on Windows XP. See 1.8.9 for details.

1.8.9 Elevation

On Windows Vista the Internet Explorer is usually in protected mode, which basically means that browser add-ins can’t access the local file system directly. To learn more about protected mode, see here: http://msdn.microsoft.com/en-us/library/bb250462.aspx

Accessing the local file system requires elevation through a broker process. The ToolbarCreator framework offers some basic support for elevation through the broker application, DiodiaBroker.exe, which is available for download from our web site.

If DiodiaBroker.exe is installed in the same directory as the toolbar dll, and has the proper elevation policy, then the Execute command (see 1.8.8) and the ToolbarContextC method ElevateShellExecute( ) (see 2.1.13) can be used.

Follow these steps to enable elevation in the framework:

1) Download DiodiaBroker.exe from http://www.diodia.com/DiodiaBroker.zip.

2) Include DiodiaBroker.exe in your toolbar setup project.
3) Find the GUID of the broker for your toolbar in the file Framework.cpp, i.e. the string value returned by the function GetHelperGuid( ).

4) Make your setup project create the proper elevation policy for the broker by creating values in the registry key:

HKEY_LOCAL_MACHINE\

SOFTWARE\

Microsoft\

Internet Explorer\

Low Rights\

ElevationPolicy\

The values to create are:

AppName="DiodiaBroker.exe" (STRING)

AppPath="[TARGETDIR]" (STRING)

Policy=00000003 (DWORD)

1.8.10 Html

The Html command holds HTML text to be displayed in an HTML control.

The HTML text to display is specified by attributes on the associated HTML control, either as a URL or as HTML text directly.

Examples:

<html command="Html"
       id="LayoutTest.Html.1"
       width="100">
    <![CDATA[
    <html>
      <head>
        <meta http-equiv="Content-Type"
              content="text/html; charset=UTF-8"/>
      </head>
      <body bgcolor="#eeebdc"
            topmargin="4"
            leftmargin="2">
        <p align="top">
          <b><font face="Arial" size="1">HTML Example</font></b>
        </p>
      </body>
    <html>
    ]]>
</html>

2 Reference

2.1 Classes

2.1.1 class CommandC

CommandC is the base class for all command objects.

Interfaces:

class CommandI
- Provides access to a command from a control object.

Methods:

CommandC()
- Constructor.
~CommandC()
- Destructor.
void Initialize(ToolBandContextC *Context,
IWebBrowser2 *WebBrowser,
HWND BrowserWindow)
- Description: Initializes a command object.
- Usage: Called by the framework to initialize member variables and references from commands to other objects.
- Example: Commands are initialized when they are added to a toolband context.
void SetSensitive(bool Sensitive)
- Description: Changes the sensitivity of a command, i.e. whether or not the command can currently be executed. Controls associated with a command are enabled and disabled according to the sensitivity of the command.
- Usage: Called in response to for example Internet Explorer events such as “new page opened”.
- Example: A “Go Back” button is disabled initially, but enabled when the user navigates away from the start page.
void SetBitmapId(int BitmapId,
COLORREF TransparentColor = RGB(240, 240, 226))
- Description: Sets the resource id of the bitmap associated with a command. Button controls associated with a command automatically updates the display when the bitmap on the command changes.
- Usage: Makes it possible to dynamically change the bitmap on a button during execution.
void SetBitmap(HBITMAP Bitmap,
COLORREF TransparentColor = RGB(240, 240, 226))
- Description: Sets the bitmap associated with a command. Button controls associated with a command automatically updates the display when the bitmap on the command changes.
- Usage: Makes it possible to dynamically change the bitmap on a button during execution.
void SetText(CString Text)
- Description: Sets the text string associated with a command. Label controls, edit controls, read-only controls and button controls associated with a command automatically update the display when the text string on the command changes.
- Usage: Makes it possible to dynamically change the labels etc. during execution.
void SetToolTip(CString ToolTip)
- Description: Not implemented. A tooltip can be associated with a command, but it is not displayed. Buttons controls that display a bitmap, but not a text, use the text string on the associated command as tooltip.
void ClearItemList()
- Description: Clears the item list associated with a command. Combo-box controls associated with the command clears their item list accordingly.
- Usage: Makes it possible to dynamically change the content of a combo-box during execution.
void AddItem(CString Item, int Position = -1)
- Description: Adds a text string to the item list associated with a command. The string is inserted at the specified position. If the specified position is -1 then the string is appended. Combo-box controls associated with the command updates their item lists accordingly.
- Usage: Makes it possible to dynamically change the content of a combo-box during execution.
void SetSelected(int Selected)
- Description: Sets the selected item in the item list associated with a command. Combo-box controls associated with the command updates their edit control accordingly.
void SetFlags(const char *Flags)
- Description: Deprecated.
void SetState(int State)
- Description: Sets the state of a command. Toggle button controls associated with the command are drawn as pushed if the state is non-zero, and as unpushed if the state is zero.

Overridables

void Initialized()
- Description: Called when the attributes on the object have been initialized.
- Usage: Override to do command initialization that requires access to the Internet Explorer’s object model or the toolband context.
void Execute()
- Description: Called when a button control associated with the command is clicked.
- Usage: Implements the actual functionality behind a button in a toolbar.
void Execute(CString Param)
- Description: Same as above.
- Usage: Makes it possible to reuse a command with slight variations by passing a parameter to the command from the toolbar configuration file.
void Execute(ControlI *Control)
- Description: Same as above.
- Usage: Makes it possible to reuse a command with slight variations by adding attributes to the tag defining the control in the toolbar configuration file. See the functions XmlGetNodeAttribute() and XmlGetNodeValue().
void Apply(CString Text)
- Description: Called when Enter is pressed in an edit control associated with the command, and when an item is selected in a combo-box control associated with the command.
- Usage: Implements the actual functionality behind an edit control or a combo-box control in a toolbar.
void Apply(CString Text, CString Param)
- Description: Same as above.
- Usage: Makes it possible to reuse a command with slight variations by passing a parameter to the command from the toolbar configuration file.
void Apply(CString Text, ControlI *Control)
- Description: Same as above.
- Usage: Makes it possible to reuse a command with slight variations by adding attributes to the tag defining the control in the toolbar configuration file. See the functions XmlGetNodeAttribute() and XmlGetNodeValue().
void DropDown()
- Description: Called before a combo-box control associated with the command drops down.
- Usage: Makes it possible to perform late initialization of the item list in a combo-box.
void CancelDropDown()
- Description: Called if a combo-box control associated with the command is closed without a selection being made.
- Example: Makes it possible to “undo” stuff done in DoDropDown().
void MouseOver(ControlI *Control)
- Description: Called when the mouse pointer is over a button associated with the command.
- Example: Makes it possible to change the image on a button when the mouse is over the button.
void MouseOut(ControlI *Control)
- Description: Called when the mouse pointer is no longer over a button associated with the command.
- Example: Makes it possible to change the image on a button when the mouse is over the button.
void ControlCreated(ControlI *Control)
- Description: Called when the control associated with the command is created and attached.
- Example: Makes it possible for a command to read XML attributes from the associated control and update its content accordingly.

Attributes:

ToolBandContextC *mContext
- Description: Back-pointer to the toolband context in which the command is stored.
- Usage: To access e.g. other commands.
IWebBrowser2 *mWebBrowser
- Description: Interface to the Internet Explorer’s object model.
- Usage: Almost everything.
- Example: A “Go Back” command would use the web browser interface in its Execute() method:

void GoBackCmdC::Execute()
{
mWebBrowser->GoBack();
}
HWND mBrowserWindow
- Description: The Internet Explorer’s frame window.
- Usage: As parent when opening dialogs.

2.1.2 class CommandContainerI

Interface providing access to a toolband context from a toolband. Used while a toolbar is being initialized.

Methods:

CommandI *FindCommand(const char *Name)
- Description: Returns the command with the specified name.
- Usage: Called by the framework during toolbar initialization.
CString GetConfigurationUrl()
- Description: Returns the URL of the XML document containing the toolbar description.
- Usage: Called by the framework during toolbar initialization. The method is always implemented by the toolbar specific derivation of class ToolbandContextC.
- Example: The configuration XML document is usually a dll resource:

   CString ContextC::GetConfigurationUrl()
   {
      return CString("res://") +
                     mDllPath +
                     "/ToolBandLayout.xml";
   }
void GetRegistryKey(HKEY *MainKey,
                             const char **SubKey,
                             const char **Name)
- Description: Returns where in the registry to store the new layout when a toolbar is customized by the user.
- Usage: Called by the framework during toolbar initialization.
The method is always implemented by the toolbar specific derivation of class ToolbandContextC.
- Example: The layout is usually stored in the registry hive of the current user:

   void ContextC::GetRegistryKey(HKEY *MainKey,
                                const char **SubKey,
                                const char **Name)
   {
      *MainKey = HKEY_CURRENT_USER;
      *SubKey = "Software\\MyToolbar";
      *Name = "DisabledCommands";
   }
const char *GetToolBandGuid();
- Description: Returns the unique toolbar id used when registering the toolbar as an Internet Explorer toolbar.
- Usage: Called by the framework during toolbar initialization.
const char *GetHelperGuid()
- Description: Returns the unique id of the helper program used to elevate commands on Windows Vista.
- Usage: Called by the framework during toolbar initialization.

2.1.3 class CommandI

The interface is implemented by command objects, and provides access to commands from toolbands and controls.

Types:

ItemList:

   typedef struct
{
     std::vector <std::string> mList;
     int         mSelected;
   }            ItemList;

- Description: The items to display in a combo-box control.

Methods:

void AttachObserver(CommandObserverI *Observer)
- Description: Attaches an observer to a command object. The command object notifies the observer about state changes through the CommandObserverI interface.
- Usage: Called by the framework to attach controls to commands.
- Example: The text displayed in an edit control is managed by a command object. When the command changes text it notifies the attached edit control, which in turn updates the display.
void DetachObserver(CommandObserverI *Observer)
- Description: Detaches an observer from a command object.
- Usage: Called by the framework to detach controls from commands.
- Example: Controls and commands are detached when the Internet Explorer shuts down.
void DoExecute(ControlI *Control)
- Description: Executes a command.
- Usage: Called by the framework when the user activates a control in a toolbar.
- Example: A button control calls the DoExecute method on the associated command when the button is clicked.
void DoApply(CString Text, ControlI *Control)
- Description: Executes a command.
- Usage: Called by the framework when the user activates a control in a toolbar.
- Example: A combo-box control calls the DoApply method on the associated command when as item is selected.
void DoDropDown(CString Text)
- Description: Notifies a command that a combo-box control associated with the command is about to drop down.
- Usage: Called by the framework just before a combo-box drops down.
- Example: Makes it possible to perform late initialization of the item list associated with a command.
void DoUpdateText(CString Text)
- Description: Notifies a command that the text in an edit control has changed.
- Usage: Called by the framework. Updates the text member of the command.
- Example: Makes it possible to retrieve the current text in an edit control from another command.
void DoCancelDropDown()
- Description: Notifies a command that a combo-box control associated with the command has been closed without a selection being made.
- Usage: Called by the framework when the combo-box closes.
- Example: Makes it possible to “undo” stuff done in DoDropDown().
void DoMouseOver(ControlI *Control)
- Description: Notifies a command that the mouse pointer is over a button associated with the command.
- Usage: Called by the framework.
- Example: Makes it possible to change the image on a button when the mouse is over the button.
void DoMouseOut(ControlI *Control)
- Description: Notifies a command that the mouse pointer is no longer over a button associated with the command.
- Usage: Called by the framework.
- Example: Makes it possible to change the image on a button when the mouse is over the button.
void DoControlCreated(ControlI *Control)
- Description: Notifies a command that a control associated with the command has been created and attached.
- Usage: Called by the framework.
- Example: Makes it possible for a command to read XML attributes from the associated control and update its content accordingly.
bool IsSensitive()
- Description: Returns true if a command can currently be executed, and false otherwise.
- Usage: Called by the framework during toolbar initialization.
- Example: A go back button must be disabled until the user has navigated away from the start page. This is implemented by making the command associated with the go back button insensitive until navigation occurs.
int GetBitmapId()
- Description: Returns the resource id of the bitmap associated with a command. Bitmaps can be associated with all commands, but the bitmap is ignored unless the command is associated with a button control.
- Usage: Called by the framework when a toolbar is drawn.
HBITMAP GetBitmap()
- Description: Returns the bitmap associated with a command. Bitmaps can be associated with all commands, but the bitmap is ignored unless the command is associated with a button control.
- Usage: Called by the framework when a toolbar is drawn.
COLORREF GetTransparentColor()
- Description: Returns the color to use as the transparent color in the bitmap associated with a command.
- Usage: Called by the framework when a toolbar is drawn.
const char *GetText()
- Description: Returns the text string associated with a command. The text string is used if the command is associated with a control with one of the following types: Label, menu, button, edit and read-only.
- Usage: Called by the framework when a toolbar is drawn.
CString GetToolTip()
- Description: Not used. A tooltip can be associated with a command, but it is not displayed. Buttons controls that display a bitmap, but no text, use the text string on the associated command as tooltip.
const ItemList *GetItemList()
- Description: Returns the item list associated with a command. The item list is used if the command is associated with a combo-box control.
- Usage: Called by the framework when a combo-box control is drawn.
const char *GetFlags()
- Description: Deprecated.
int GetState()
- Description: Returns the state of a command. The state is used if the command is associated with a toggle button control. If GetState() returns a non-zero value then the button is drawn as pushed, otherwise the button is drawn as unpushed.
- Usage: Called by the framework when a toggle button control is drawn.

2.1.4 class CommandObserverI

The interface is implemented by control objects. Controls are notified about state changes in commands through the command observer interface.

Used internally only.

2.1.5 class CommandPointerSetC

Stores a set of pointers to commands. A command pointer set can be used to keep track of commands created dynamically, for example “Highlight and Word Find” commands.

Methods:

CommandPointerSetC()
- Constructor.
~CommandPointerSetC()
- Destructor.
void AddCommand(CommandI *Cmd)
- Description: Inserts a pointer to a command in the set.
- Usage: For example, to keep track of commands created dynamically, e.g. “Find&Highlight” commands .
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      :

      /* create a find command for the new search */
      mFindCmds.AddCommand(new FindCmdC(Query));

      :
   }
void Clear()
- Description: Removes all pointers from the command pointer set.
- Usage: To clear a set when the commands are no longer needed.
- Note: Clear() does not delete the commands, the pointers are simply removed from the set.
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      /* get rid of old find commands*/
      for (int Idx = 0; Idx < mFindCmds.GetSize(); Idx++)
         delete mFindCmds[Idx];
      mFindCmds.Clear();

      :
   }
int GetSize()
- Description: Returns the number of command pointers in the set.
CommandI *operator[](int Pos) const;
- Description: Returns the nth command pointer in the set.

2.1.6 class CommandSetC

Stores a set of uniquely named command objects. A toolband context aggregates a command set.

Interfaces:

class CommandSetI
- Provides access to the commands in a command set.

Types:

CommandMap:

typedef std::map <std::string, CommandC *,
std::less <std::string> > CommandMap

- Description: A map from command name to command object.

Methods:

CommandSetC()
- Constructor.
~CommandSetC()
- Destructor.
void AddCommand(CommandC *Cmd)
- Description: Inserts a command in a command set.
- Usage: Called by the framework when a command is added to a toolband context.
- Example: A toolbar usually creates its command objects during initialization. The commands are added to the toolband context, which initializes the commands and adds them to the associated command set.

Overridables:

void Quit()
- Description: Called by the framework when the Internet Explorer shuts down.

Attributes:

IdListC mCommandIds
- Description: List containing the names of all the commands in the command set.
CommandMap mMap
- Description: Map from command name to command object.

2.1.7 class CommandSetI

Interface providing access to the commands in a command set.

Types:

IdListC:

typedef std::vector <std::string> IdListC

- Description: A list of command names.

Methods:

const IdListC *GetCommandIds()
- Description: Returns the names of the commands in a command set.
CommandI *GetCommand(std::string Id)
- Description: Returns the command with the specified name.
- Usage: Whenever access to a command is needed.
- Example: To change the text in an edit control associated with a command object called “MyToolbar.Cookie”, use:

GetCommand(“MyToolbar.Cookie”)->SetText(“Chocolate Chip”)
void Quit()
- Description: Notifies the command set that the Internet Explorer is shutting down.

2.1.8 class CommandWithEventsC

CommandWithEventsC is a specialization of class CommandC. It supports all the features of CommandC, as well as handing of web browser events.

Methods:

HRESULT Invoke(DISPID dispidMember,
                        REFIID riid,
                        LCID lcid,
                        WORD wFlags,
                        DISPPARAMS *pDispParams,
                        VARIANT *pvarResult,
                         EXCEPINFO *pExcepInfo,
                        UINT *puArgErr)
- Description: Called by the Internet Explorer to notify about events. See the MSDN documentation of e.g. DWebBrowserEvents2 for a full description of events that can be handled.
- Usage: Override to handle events such as “new page opened”.
- Example:

    STDMETHODIMP HookC::Invoke(DISPID dispidMember,
                             REFIID riid,
                             LCID lcid,
                             WORD wFlags,
                             DISPPARAMS *pDispParams,
                             VARIANT *pvarResult,
                             EXCEPINFO *pExcepInfo,
                             UINT *puArgErr)
   {
      switch (dispidMember)
      {
       case DISPID_NAVIGATECOMPLETE2:
         HandleNewPageOpened();
         break;
      }

      return S_OK;
   }

2.1.9 class ControlC

ControlC implements control objects, i.e. menus, buttons, combo-boxes, etc..

The class is used internally only. Controls are manipulated through the ControlI interface.

2.1.10 class ControlCollectionI

The interface is implemented by toolband objects and menu controls. it makes it possible to dynamically change the controls in a toolbar or a menu.

Methods:

void AddControl(ControlI *Control)
- Description: Adds a control at the end of a toolbar or a menu.
void AddControlBefore(ControlI *Control, ControlI *Target)
- Description: Adds a control before another control in a toolbar or a menu.
void AddControlAfter(ControlI *Control, ControlI *Target)
- Description: Adds a control after another control in a toolbar or a menu.
void DeleteAllControls()
- Description: Removes all controls from a toolbar or a menu.
void DeleteControl(ControlI *Control)
- Description: Deletes a control from a toolbar or a menu.
void FindControlsFromCommandId(const char *Id,
ControlPointerSetC &ControlSet)
- Description: Finds all controls in a toolbar or a menu that are associated with a specific command.
void FindControlsFromText(CString Text,
ControlPointerSetC &ControlSet)
- Description: Finds all controls in a toolbar or a menu that displays the specified text string as caption.
void FindControlsFromBitmapId(int BitmapId,
ControlPointerSetC &ControlSet)
- Description: Finds all controls in a toolbar or a menu that displays the specified bitmap.
void GetAllControls(ControlPointerSetC &ControlSet)
- Description: Finds all controls in a toolbar or a menu.

2.1.11 class ControlI

The interface is implemented by control objects, and provides access to controls from toolbands.

Types:

Mode:

   enum Mode
   {
      TbModeNone = 0,
      TbModeText = 1,
      TbModeImage = 2,
      TbModeTextAndImage = 3
   };

- Description: Whether to display a caption, a bitmap or both on a button control.
Type:

   enum Type
   {
      TbSeparator = 0,
      TbLabel = 1,
      TbButton = 2,
      TbEdit = 3,
      TbReadOnly = 4,
      TbComboBox = 5,
    TbMenu = 6
   };

- Description: Control types.

Flags:

   enum Flags
   {
      TbFlagAutoResize = 0x00000001,
      TbFlagComboBoxList = 0x00000002,
      TbFlagMainMenu = 0x00000004,
      TbFlagCheck = 0x00000008,
      TbFlagDynamic = 0x20000000,
      TbFlagNop = 0x40000000,
      TbFlagDisabled = 0x80000000
   };

- Description: Flags controlling the behavior of controls.

- TbFlagAutoResize: Used on combo-boxes, edit controls and read-only controls to make them automatically adjust their size when the Internet Explorer is resized.
- TbFlagComboBoxList: Used on combo-boxes to make them display a fixed list, i.e. to prevent the user from entering free text in the combo-box.
- TbFlagMainMenu: Used internally (set on the left-most menu in the toolbar displaying the toolbar logo).
- TbFlagCheck: Used on button controls to create toggle-buttons.
- TbFlagDynamic: Used internally (set on dynamically added controls).
- TbFlagNop: Used internally (set if a control is not associated with a command).
- TbFlagDisabled: Used internally (set if a control is disabled by customize).

Methods:

enum Type GetType()
- Description: Returns the control type.
void SetMode(enum Mode)
- Description: Sets whether to display a caption, a bitmap or both on a button control.
void SetFlags(int Flags)
- Description: Sets various flags controlling the behavior of controls. See the description of enum Flags above for details.
void SetWidth(int Width)
- Description: Sets the width of a combo-box, an edit control or a read-only control.
void SetParam(CString Param)
- Description: Sets the parameter associated with the control. The parameter is passed to the command associated with the control when the command is executed.
void SetHotKey(CString Param)
- Description: Sets the hot key (keyboard shortcut) used to activate the control.
void SetNode(IXMLDOMNode *Node)
- Description: Sets the node of the XML tag defining the control in the toolbar configuration file. The node can be used to extract data from the configuration file. See the functions XmlGetNodeAttribute() and XmlGetNodeValue().
CommandI *GetCommand()
- Description: Returns the command associated with the control, if any.
CWnd *GetWindowsControl()
- Description: Returns the underlying Windows control. The return value depends on the control type:

    TbSeparator: NULL
    TbLabel: A CStatic *
    TbButton: NULL
    TbEdit: A CEdit *
    TbReadOnly: A CEdit *
    TbComboBox: A CComboBox *
    TbMenu: NULL
IXMLDOMNode *GetNode()
- Description: Returns the node of the XML tag defining the control in the toolbar configuration file. The node can be used to extract data from the configuration file. See the functions XmlGetNodeAttribute() and XmlGetNodeValue().

2.1.12 class ControlPointerSetC

Stores a set of pointers to controls. A control pointer set can be used to keep track of controls created dynamically, for example “Find&Highlight” buttons.

Methods:

CommandPointerSetC()
- Constructor.
~CommandPointerSetC()
- Destructor.
void AddControl(ControlI *Control)
- Description: Inserts a pointer to a control in the set.
- Usage: For example, to keep track of “Find&Highlight” buttons created dynamically.
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      :

      FindButton = CreateButtonControl(mFindCmd);

      /* remember the button so we can remove when searching again */
      mFindButtons.AddControl(FindButton);

      :
   }
void Clear()
- Description: Removes all pointers from the control pointer set.
- Usage: To clear a set when the controls are no longer needed.
- Note: Clear() does not delete the controls, the pointers are simply removed from the set.
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      :

      /* get rid of old find buttons */
      for (int Idx = 0; Idx < mFindButtons.GetSize(); Idx++)
         ControlCollection->DeleteControl(mFindButtons[Idx]);
      mFindButtons.Clear();

      :
   }
int GetSize()
- Description: Returns the number of control pointers in the set.
ControlI *operator[](int Pos) const;
- Description: Returns the nth control pointer in the set.

2.1.13 class ToolBandContextC

ToolBandContextC is base class for a specialized toolband context.

The toolband context glues everything together.

Interfaces:

class CommandContainerI
- Provides access to a toolband context from a toolband.

Methods:

ToolBandContextC ()
- Constructor.
~ToolBandContextC ()
- Destructor.
static const char *GetDllPath()
- Description: Returns the full path to the toolbar implementation dll.

void AddCommand(CommandC *Cmd)
- Description: Adds a command to the command set in the toolband context. To have the commands initialized properly it is important not to add the commands directly to the command set. Always use the AddCommand() method on the toolband context.
- Usage: Typically called from the Initialize() implementation.
- Example:

   void ContextC::Initialize()
   {
      AddCommand(new AboutCmdC);
   }
void DeleteCommand(CommandC *Cmd)
- Description: Deletes a command from the command set in the toolband context. Disposes of temporary commands, e.g. Find & Highlight commands related to a specific search.
- Usage: Called when changing the toolbar layout dynamically.
- Note: Calls “delete Cmd” !!
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      if (mFindCmd)
      {
         /* delete find command from previous search */
         DeleteCommand(mSearchC);
      }

      /* create a find command for the new search */
      mFindCmd = new FindCmdC(Query);

      /* create a new button, and associate it with the command */
      :
   }
ToolBandI *GetToolBand()
- Description: Returns a toolband interface, which can be used to find the control collection associated with a toolbar.
- Usage: Called when changing the toolbar layout dynamically.
- Example:

   void ContextC::PerformSearch(const char *Query)
   {
      ControlCollectionI *Controls;

      Controls = GetToolBand()->GetControlCollection();

      /* use control collection to add or remove toolbar controls */
      :
}
bool Reconfigure()
- Description: Makes a toolbar reinitialize from an XML file. The framework calls GetConfiguratonUrl() to obtain the location of the new XML file.
- Usage: Called to reset the toolbar layout, or to change the layout of a toolbar completely.
- Note: Reconfigure() fails and returns false if the toolband contains dynamically added controls. Dynamic controls must be deleted using the control collection interface before calling Reconfigure().
- Example:

   void ContextC::AfterLogin()
   {
      mLayoutFile = “/LoginLayout.xml”;
      Reconfigure();
   }

   std::string ContextC::GetConfigurationUrl()
   {
      return std::string("res://") + mDllPath + mLayoutFile;
   }
DWORD ElevateShellExecute(LPCTSTR Operation,
                                         LPCTSTR File,
                                         LPCTSTR Parameters,
                                         LPCTSTR Directory,
                                         INT ShowCmd,
                                          bool WaitForResult)
- Description: Used on Windows Vista to elevate command execution, for example to launch applications. See the Windows SDK documentation of ShellExecute() for description of the first 5 parameters. If WaitForResult is true then ElevateShellExecute() waits for the launched application to terminate and returns the applications exit code.
Note: Using the ElevateShellExecute() requires elevation support, even on Windows XP. See 1.8.9 for details.

Overridables:

void Initialize()
- Description: Called by the framework during toolbar initialization.
- Usage: Commands objects are typically created in Initialize().
- Example:

   void ContextC::Initialize()
   {
      AddCommand(new AboutCmdC);
   }
void ToolBandCreated()
- Description: Called by the framework when the toolbar and all the controls in the XML configuration file have been created.
- Usage: To add extra controls after initializing from XML file.
- Example:

   void ContextC::ToolBandCreated()
   {
      ControlI          *Ctrl;

      /* add an About button at the end of the toolbar */
      Ctrl = CreateButtonControl(FindCommand("MyToolbar.About"),
                                 "About...");
      mToolBand->GetControlCollection()->AddControl(Ctrl);
   }
void OnQuit()
- Description: Called by the framework when the Internet Explorer shuts down.
- Usage: Deallocation of resources.
void KeyboardHook(int nCode, WPARAM wParam, LPARAM lParam)
- Description: Called by the framework when a key is pressed.
- Usage: To create keyboard shortcuts to toolbar functionality.

Attributes:

IWebBrowser2Ptr mWebBrowser
- Description: Interface to the Internet Explorer.
- Usage: Whenever access to the Internet Explorer or the DHTML document object model is needed.
HWND mBrowserWindow
- Description: The window handle of the Internet Explorer’s frame window.
- Usage: Typically used as parent when opening dialogs.
ToolBandHookC *mToolBandHook
- Description: The toolband hook through which the Internet Explorer communicates with a toolbar.
CommandSetC mCommandSet
- Description: The command set in which the command objects of a toolbar are stored.
- Usage: For example to lookup a command to change its state.

2.1.14 class ToolBandHookC

ToolBandHookC is base class for a specialized toolband hook.

The toolband hook is the channel through which the Internet Explorer communicates with a toolbar.

Interfaces:

Various COM interfaces required of an Internet Explorer toolbar.

Methods:

ToolBandHookC(ToolBandContextC *Context)
- Constructor.
~ToolBandHookC()
- Destructor.

Overridables:

HRESULT Invoke(DISPID dispidMember,
                        REFIID riid,
                        LCID lcid,
                        WORD wFlags,
                        DISPPARAMS *pDispParams,
                        VARIANT *pvarResult,
                        EXCEPINFO *pExcepInfo,
                        UINT *puArgErr)
- Description: Called by the Internet Explorer to notify about events. See the MSDN documentation of e.g. DWebBrowserEvents2 for a full description of events that can be handled.
- Usage: Override to handle events such as “new page opened”.
- Example:

   STDMETHODIMP HookC::Invoke(DISPID dispidMember,
                             REFIID riid,
                             LCID lcid,
                              WORD wFlags,
                             DISPPARAMS *pDispParams,
                             VARIANT *pvarResult,
                             EXCEPINFO *pExcepInfo,
                             UINT *puArgErr)
   {
      switch (dispidMember)
      {
       case DISPID_NAVIGATECOMPLETE2:
         mContext->NewPageOpened();
         break;
      }

      return ToolBandHookC::Invoke(...);
   }

Attributes:

ToolBandContextC *mContext
- Description: Reference to the associated toolband context.
- Usage: Internet Explorer events are usually propagated to the toolband context.
int mHeight
- Description: The height of a toolbar in pixels.

2.1.15 class ToolBandC

The class implements the toolband object, which is responsible for drawing the toolbar on the screen.

The class is used internally only.

2.1.16 class ToolBandI

The interface is implemented by toolband objects, and provides access to toolbands from toolband contexts.

Methods:

ControlCollectionI *GetControlCollection()
- Description: Returns the control collection interface of a toolband object.
- Usage: The control collection interfaces is used to dynamically change the toolbar layout, for example to add more buttons.
CToolBarCtrl *GetToolBarCtrl()
- Description: Returns the underlying toolbar control.
- Usage: For example to change the tooltip timeout property of the toolbar.

2.2 Functions

2.2.1 CreateButtonControl

Creates a new button control, which can be added to a toolbar or a menu through a control collection interface.

ControlI *CreateButtonControl(CommandI *Command,
CString Text = NULL)

- Parameters:
Command: The command object to associate with the button.
Text: The caption to display on the button.

- Note: To associate a bitmap with a button, use SetBitmapId() on the command object associated with the button. To make the button display the bitmap, use SetMode() from the ControlI interface after creating the button.

- Note: To create a toggle button, use SetFlags() from the ControlI interface after creating the button.

2.2.2 CreateComboBoxControl

Creates a new combo-box control, which can be added to a toolbar through a control collection interface.

ControlI *CreateComboBoxControl(CommandI *Command,
CString List = "")

- Parameters:
Command: The command object to associate with the control.

List: Items to add to the drop-down list separated by ##, for example "Red##Green##Blue".

- Note: To make the combo-box automatically adjust its size when the Internet Explorer is resized, use SetFlags() from the ControlI interface after creating the combo-box.

Note: To create a fixed width combo-box, use SetWidth() from the ControlI interface after creating the combo-box.

- Note: To prevent users from entering text in the combo-box, i.e. to make the combo-box display a fixed list of items, use SetFlags() from the ControlI interface after creating the combo-box.

2.2.3 CreateEditControl

Creates a new edit control, which can be added to a toolbar through a control collection interface.

ControlI *CreateEditControl(CommandI *Command)

- Parameters:
Command: The command object to associate with the control.

- Note: To make the edit control automatically adjust its size when the Internet Explorer is resized, use SetFlags() from the ControlI interface after creating the edit control.

Note: To create a fixed width edit control, use SetWidth() from the ControlI interface after creating the edit control.

2.2.4 CreateLabelControl

Creates a new label control, which can be added to a toolbar through a control collection interface.

ControlI *CreateLabelControl(CommandI *Command = NULL,
CString Text = NULL)

- Parameters:
Command: The command object to associate with the label. May be NULL if the label is a fixed text string that never changes.

Text: The label to display.

2.2.5 CreateMenuControl

Creates a new menu control, which can be added to a toolbar or a menu through a control collection interface.

ControlI *CreateMenuControl(CommandI *Command = NULL,
CString Text = NULL)

- Parameters:
Command: The command object to associate with the menu. If Command == NULL then an ordinary menu is created. If Command != NULL then a mixed button (i.e. a combination of a button and a menu) is created,.
Text: The caption to display on the menu.

- Note: To associate a bitmap with a menu, use SetBitmapId() on the command object associated with the menu. To make the menu also display the bitmap, use SetMode() from the ControlI interface after creating the button. Bitmaps cannot be associated with sub-menus.

2.2.6 CreateReadOnlyControl

Creates a new read-only control, which can be added to a toolbar through a control collection interface.

ControlI *CreateReadOnlyControl(CommandI *Command)

- Parameters:
Command: The command object to associate with the control.

- Note: To make the read-only control automatically adjust its size when the Internet Explorer is resized, use SetFlags() from the ControlI interface after creating the read-only control.

Note: To create a fixed width read-only control, use SetWidth() from the ControlI interface after creating the read-only control.

2.2.7 CreateHtmlControl

Creates a new HTML control, which can be added to a toolbar through a control collection interface.

ControlI *CreateHtmlControl(CommandI *Command)

- Parameters:
Command: The command object to associate with the control. Use SetText( ) on the command object to specify either a URL or some HTML text to display in the HTML control.

- Note: To make the HTML control automatically adjust its size when the Internet Explorer is resized, use SetFlags() from the ControlI interface after creating the read-only control.

Note: To create a fixed width HTML control, use SetWidth() from the ControlI interface after creating the read-only control.

2.2.8 CreateSeparatorControl

Creates a new separator control, which can be added to a toolbar or a menu through a control collection interface.

ControlI *CreateSeparatorControl()

2.2.9 XmlGetNodeAttribute

Returns the value of an attribute from an XML DOM node.

CString XmlGetNodeAttribute(IXMLDOMNode *Node,
CString Name)

- Parameters:
Node: The DOM node to get an attribute value from.

Name: The name of the attribute.

- Usage: Typically used to get a value from the toolbar configuration file from within a command.

- Example: The Navigate command is used like this in the toolbar configuration file:

The Navigate command can get the value of the url attribute by calling XmlGetNodeAttribute():

void NavigateCmdC::Execute(ControlI *Control)

{

CString Url;

variant_t vtUrl;

Url = XmlGetNodeAttribute(Control->GetNode(), "url");
vtUrl = bstr_t(Url);

mWebBrowser->Navigate2(&vtUrl, &vtMissing,
&vtMissing, &vtMissing, &vtMissing);

}

2.2.10 XmlGetNodeValue

Returns the content of an XML DOM node.

CString XmlGetNodeAttribute(IXMLDOMNode *Node)

- Parameters:
Node: The DOM node to get the content from.

- Usage: Typically used to get a value from the toolbar configuration file from within a command.

- Example: The command ExampleCmd is used like this in the toolbar configuration file:

The command can get the content of the button tag by calling XmlGetNodeValue():

void ExampleCmdC::Execute(ControlI *Control)

{

CString Text;

       Text = XmlGetNodeValue(Control->GetNode());

       /* Text is now “Here is some text!” */
       :

}

3 XML Configuration

3.1 An Example

The layout of a toolbar is described by an XML file.

The XML file is basically an ordered list of the controls in the toolbar. Each control is associated with a named command, and perhaps a caption and a bitmap image.

The XML file below describes a toolbar with three controls: A menu with three entries, a “Go Home” button and a “Search Google” combo-box:

<?xml version="1.0" encoding="ISO-8859-1"?>

</menu>

      <combo-box command="MyToolbar.SearchGoogle"
                 caption="Search Google"
                 width="220"
                 auto-size="yes"
                 fixed-list="no"/>

</toolband>

3.2 Tags and Attributes

3.2.1 <toolbar>

Description: Encapsulates the complete toolbar definition.

Attributes:

name: The name of the toolbar.

Example:

…

</toolband>

3.2.2 <menu>

Description: Inserts a menu control in a toolbar, or a sub-menu in a menu, and encapsulates the items in the menu.

Attributes:

command: The name of a command. If a command is associated with a menu control then the menu becomes a mixed button, i.e. a combination of a push-button and pop-up menu similar to the Back and Forward buttons in the Internet Explorer. If a command is not specified then the menu is a regular pop-up menu.
image: The resource id of the bitmap to display on the menu control.
caption: The text string to display on the menu control, or the tooltip if an image has been specified and show-caption=no.
show-caption: If both an image and a caption has been specified, this attribute determines whether to display the caption on the menu control (show-caption=yes) or use the caption as a tooltip (show-caption=no).

Notes:

Sub-menu items can only display a caption. The attributes image and show-caption are ignored.
The first menu in a toolbar is special. It is often used to display a company logo, or a toolbar logo. The bitmap associated with the first menu in a toolbar can therefore be wider than the bitmaps used on the remaining controls, which must all have the same size. A caption cannot be specified for the first menu control.
The value of the caption attribute is used as control name in the toolbar customization dialog.

Example:

<menu image="211"

caption="MyMenu"
show-caption="yes">

…

</menu>

3.2.3 <button>

Description: Inserts a button control in a toolbar, or a menu item in a menu.

Attributes:

command: The name of the command associated with the button.
image: The resource id of the bitmap to display on the button.
caption: The text string to display on the button, or the tooltip if an image has been specified and show-caption=no.
show-caption: If both an image and a caption has been specified, this attribute determines whether to display the caption on the button (show-caption=yes) or use the caption as a tooltip (show-caption=no).
toggle-button: Determines whether the button is regular push-button (toggle-button=no), or an on/off button (toggle-button=yes).
parameter: Extra string parameter passed to the Execute( ) method of the command associated with the button. It is possible to have a substring of the parameter substituted with the content of an edit or combo-box before the parameter is passed to the command. For example, the pattern ##MyToolbar.SearchBox## will be substituted with the current content of the command MyToolbar.SearchBox.

Notes:

Menu items can only display a caption. The attributes image and show-caption are ignored.
The value of the caption attribute is used as control name in the toolbar customization dialog.

Example:

   <button command="MyToolbar.GoHome"
          image="210"
          caption="Home"
          show-caption="yes"

toggle-button="no"/>

3.2.4 <label>

Description: Inserts a label control in a toolbar.

Attributes:

caption: The text string to display on the label control.

Notes:

The value of the caption attribute is used as control name in the toolbar customization dialog.

Example:

3.2.5 <edit>

Description: Inserts an edit control in a toolbar.

Attributes:

command: The name of the command associated with the edit control.
caption: The name of the edit control. Displayed in the toolbar customization dialog.
width: The width of the edit control in pixels, or the minimum width if auto-width=yes.
auto-width: Specifies whether or not to automatically resize the edit control when the Internet Explorer is resized. If auto-width=yes on at least one control in a toolbar then the toolbar always fits the width of the Internet Explorer. The address field in the Internet Explorer is an example of a control with this behavior.
parameter: Extra string parameter passed to the Apply( ) method of the command associated with the edit control. It is possible to have a substring of the parameter substituted with the content of the edit control before the parameter is passed to the command. For example, the pattern ##MyToolbar.SearchBox## will be substituted with the current content of the command MyToolbar.SearchBox.
id: Alternative command name when a built-in command is associated with the edit control. For example, <edit command=”Navigate” id=”MyToolbar.SearchBox” .../>. Specifying an alternative name makes it possible to extract the content of the edit control.
Note: id is valid only if a built-in command is associated with the edit control, as in the second example below.

Examples:

<edit command="MyToolbar.Find"

caption="Find"

width="200"

auto-size="yes"/>

<edit command="Navigate"

id="MyToolbar.SearchBox"

parameter="www.google.com/search?q=##MyToolbar.SearchBox##"

caption="SearchBox"

width="200"