Wednesday, January 21, 2004

Menu items, Toolbars, glyphs... etc..

One area that has always been a common source of questions with the Open Tools API is "how do I add a menu item and tool button to the IDE." Well... starting with C#Builder new methods have been added to INTAServices that make adding items such as these much simpler. If you look in ToolsAPI.pas at INTAServices:

INTAServices = interface(INTAServices70)
{! AddImages takes all the images from the given image list and adds them to the
main application imagelist. It also creates an internal mapping array from the
original image indices to the new indices in the main imagelist. This
mapping is used by AddActionItem to remap the ImageIndex property of the
action object to the new ImageIndex. This should be the first method
called when adding actions and menu items to the main application window.
The return value is the first index in the main application image list of
the first image in the source list. Call this function with an nil
image list to clear the internal mapping array. }

function AddImages(AImages: TCustomImageList): Integer;
{! AddActionMenu takes an action item, a menu item, and a menu item component name
and inserts the action in to the main action list and the menu item into the
menu either preceding or following the named menu component. If the action
component has an ImageIndex > -1, then the mapping table created by the
previous call to AddImages above is used to determine the new value for
ImageIndex. NewAction can be nil, in which case only the menu item is
added. Likewise, NewMenu can be nil, in which case the Name param is
ignored and only the action is added to the main action list. If Name
cannot be found, an exception is raised. If the ImageIndex of NewAction
is out of range, then it is set to -1. }

procedure AddActionMenu(const Name: string; NewAction: TCustomAction;
NewItem: TMenuItem; InsertAfter: Boolean = True; InsertAsChild: Boolean = False);
{! NewToolBar creates a new toolbar with the given name and caption.
If the ReferenceToolBar parameter is specified, it is used as a reference point
for insertion based on the InsertBefore parameter. If InsertBefore is True, then
the new toolbar is inserted physically before the reference, else it is after.
if ReferenceToolBar is not specified, then the toolbar is inserted into a
position determined by the IDE. }

function NewToolbar(const Name, Caption: string;
const ReferenceToolBar: string = '';
InsertBefore: Boolean = False): TToolbar;
{! AddToolButton creates a new toolbutton on the named toolbar using the given
Action component. In order for the user to be able to add and remove this
toolbutton, an Action *must* be specified. otherwise the user may remove
the button, never to return until the toolbar config entries in the registry
are deleted and the toolbars are reset to the original configuration. If
IsDivider is True, then Action is ignored since a divider toolbutton is
created. If you wish the toolbutton to have a dropdown menu, then owner-
ship of that menu *must* be transferred to the owner of the toolbutton. }

function AddToolButton(const ToolBarName, ButtonName: string;
AAction: TCustomAction; const IsDivider: Boolean = False;
const ReferenceButton: string = ''; InsertBefore: Boolean = False): TControl;
{! UpdateMenuAccelerators causes the IDE to reset all the assigned accelerator
keys to the associated menu items. This is the accelerators as defined in
the current keymap }

procedure UpdateMenuAccelerators(Menu: TMenu);
{! ReadToolbar reads the configuration of the given toolbar from the
registry and recreates it if necessary. If SubKey is specified, it will
attempt to obtain a stream from that key first and if not found, then
will get the stream from the main toolbar key. Use Subkey to read
view-specific version of a toolbar. You can also optionally pass in a
TStream object if you wish to control the actual storage of the stream
itself. Set DefaultToolbar to true in order to read one of the global
toolbars from the "toolbar reset" storage. This is the default
configuration of the toolbar. }

procedure ReadToolbar(AOwner: TComponent; AParent: TWinControl; const AName: string;
var AToolBar: TWinControl; const ASubKey: string = ''; AStream: TStream = nil;
DefaultToolbar: Boolean = False);
{! WriteToolbar will take the given toolbar and write it out to the registry
under the subkey name if specified. Use SubKey to write view-specific
versions of a toolbar. }

procedure WriteToolbar(AToolbar: TWinControl; const AName: string = '';
const ASubkey: string = ''; AStream: TStream = nil);
{! CustomizeToolbars will open the toolbar customize dialog and set the given
toolbars into customize mode. The INTACustomizeToolbarNotifier interface
is used to handler certain events during the customizing process. If
ActionList is specified, then only the actions in that action list can
be used to customize the toolbar. If not specified, =nil, then the IDE's
global action list is used. The return value is the customize dialog
component. You can add a FreeNotification in order to know when the user
closes the dialog and customization is complete. }

function CustomizeToolbar(const AToolbars: array of TWinControl;
const ANotifier: INTACustomizeToolbarNotifier; AButtonOwner: TComponent = nil;
AActionList: TCustomActionList = nil; AButtonsOnly: Boolean = True): TComponent;
{! Call CloseCustomize when it is needed to forcibly terminate the customize
mode. For instance if the view being customized is destroyed or hidden,
this procedure may be called to terminate customization. }

procedure CloseCustomize;
{! Call ToolbarModified if you wish to notify all interested parties that
a toolbar was modified by means other than calling CustomizeToolbar. For
instance, when the toolbar is on a TControlBar and the toolbar band was
repositioned. This will cause all registered INTACustomizeToolbarNotifier.ToolbarModified
events to be called. }

procedure ToolbarModified(AToolbar: TWinControl);
{! RegisterToolbarNotifier registers the given INTACustomizeToolbarNotifier
in order to receive certain events related to toolbars and customizing
them. The most often used event will probably be the ToolbarModified
event since that is how other views can know when a particular named
toolbar is customized. }

function RegisterToolbarNotifier(const ANotifier: IOTANotifier): Integer;
procedure UnregisterToolbarNotifier(Index: Integer);
{! MenuBegin/EndUpdate allows the caller to control how often the main
menu will be updated. If many changes to the main menu are made at
one time performance can be improved by using these methods. }

procedure MenuBeginUpdate;
procedure MenuEndUpdate;


This interface is designed to be used when initializing an IDE addin. What many of the internally developed IDE addins do is to create Data Module. On that data module, drop a TImageList, TActionList, and TPopupMenu. Add the images you want to use with the toolbar buttons and menu items to the image list. Add the action items, reference the image list and the index of the specific images (these will be fixed up later). Now add a menu item to the popup menu and assign the specific action item to the Action property of the menu item. This is all done via the designer (Delphi 7 can be used to do this). Now, when you want to initialize your add-in, you need to create an instance of the data module then call in this order:

NTAServices: INTAServices;
ToolBar: TToolBar;
NTAServices := BorlandIDEServices as INTAServices;
// Inserts the new menu item just before the File|Exit... menu item
NTAServices.AddActionMenu('FileExitItem', ActionItem1, MenuItem1, False);
NTAServices.AddActionMenu(...);// add any other menu items.
ToolBar := NTAServices.NewToolBar('NewCustomToolbar', 'Allen''s Custom Toolbar');
NTAServices.AddToolButton('NewCustomToolbar', 'ActionButton1', ActionItem1);


One item of note is that currently, if you attempt to query BorlandIDEServices from within IDERegister, it will fail. This is due to the fact that IDERegister is call very early in the initialization cycle. One workaround is to set a timer and try it again periodically. Another, more accurate technique is to create a hidden window (See AllocateHWnd and DeallocateHWnd in Classes.pas), and post a message with PostMessage to that window handle. This will ensure that you know the initialization is complete because the message loop has started (TApplication.Run).

The above technique is how all internally developed IDE personalities and extensions add their items to the main menu. The benefit of following these procedures is that your newly added action items will now participate in toolbar customization and persistence. Some of the more advanced uses of this interface and the attending INTAToolbarNotifier interface you can implement, is the ability to have local-view toolbars that can be persisted and designed just like the main toolbars (see the toolbar on the WinForm Designer view).