Customize Toolbars and Ribbons

To access this screen:

  • Right-click an empty space in the toolbar area and select Customize.
  • Click on the arrow on the right-hand edge of any toolbar and select Customize.

There are 2 ways of creating user-defined toolbars in DTS.

Customizing Toolbars in DTS

If displayed through the user interface, the Customize screen lets you to add and edit menus and toolbars, add program shortcuts and keyboard shortcuts.

Using Custom Icons

If you add commands to a toolbar, you can either use a default image supplied with DTS, or you can add your own image.

The limitation ocustomizing DTS via the application is that you can only add internal DTS commands (functions that exist already). There is little scope of integrating your own software with DTS using this mechanism.

Note: The maximum number of toolbars that can be created this way is 10.

To use your own images, you need to create a Windows bitmap (.bmp) file called userimages.bmp. This file must be located in the same folder where DTS is installed, and should contain one or more 16x16 images in a strip, with no spaces in between, for example:

Images with a bit depth of (up to) 24 bits per pixel are permitted. An alpha channel can be specified using RGB (255,0,255) (Magenta).

Note: If a custom toolbar is added using a configuration file (see below) then its bitmaps take precedence, and userimages.bmp will not be loaded.

Changing the width of combo boxes on toolbars

A "combo box" is a list item (in this case, on a toolbar) that allows custom entries to be typed.

In order to change the width of a combo box on a toolbar:

  1. Display the Customize screen.

  2. Select the combo box to edit.

    The combo box appears with a solid outline.

  3. Mouse over the right-hand edge of this frame.

  4. Drag the combo box to the desired width.

Customizing Toolbars using a Configuration File

The second method - typically aimed at developers and DTS implementers - uses a configuration file to provide details of custom toolbars (and menus) as well as panels on the ribbon interface.

The advantage of this mechanism is that it allows you to run any command line action, as well as raise events to your own programs if they communicate with DTS through the COM interface. It is also possible to ship the configuration file with DTS, so there is no user intervention required to get the additional toolbars functioning.

The configuration file can have any name as long as the file extension is .ini and it must be stored in the common application data folder.

Note: For technical information see SHGetFolderPath and CSIDL_COMMON_APPDATA in the MSDN documentation.

Depending on the operating system and its install path this is typically:

  • C:\Documents and Settings\All Users\Application Data\Datamine
  • C:\ProgramData\Datamine

The toolbar is simply added below all other toolbars. On the ribbon interface a panel is inserted at the end of the Tools category.

Configuration File Format

You can supply up to 5 configuration files to create 5 toolbars or ribbon panels. Each toolbar or ribbon panel can have a maximum of 10 buttons (including separators).

The configuration file has following format:

/* ===================================================================== */
/* Specify image filename without path.                                  */
/* Number of buttons must include separators.                            */
/* ===================================================================== */
[TOOLBAR_INFO]
image_file_name=toolbarimages.bmp
image_file_32=ribbonimages.bmp
number_buttons=5
toolbarname=VIZ
vendor=Sirius01


/* ===================================================================== */
/* Specify the button type, i.e. BUTTON, STATE or SEPARATOR.             */
/* ===================================================================== */
[BUTTON_TYPE]
btn1=BUTTON
btn2=SEPARATOR
btn3=BUTTON
btn4=BUTTON
btn5=STATE

/* ===================================================================== */
/* 1-based index corresponding to image position in the bmp file.        */
/* The same index is used for 16x16 and 32x32 image lists                */
/* In this example button 2 is a separator, hence no image is specified. */
/* ===================================================================== */
[BUTTON_IMAGE_IDX]
imageidx1=1
imageidx3=2
imageidx4=3
imageidx5=4
 
/* ===================================================================== */
/* Specify the preferred image size, i.e. LARGE or SMALL. This applies   */
/* only to the ribbon interface. Separators are skipped.                 */
/* ===================================================================== */
[BUTTON_IMAGE_SIZE]
imagesize1=LARGE
imagesize3=SMALL
imagesize4=SMALL
imagesize5=SMALL

/* ===================================================================== */
/* Specify the text for the menu (toolbar interface) and the buttons     */
/* on the ribbon interface. Separators are skipped.                      */
/* In this example button 2 is a separator, hence no text is specified.  */
/* ===================================================================== */
[BUTTON_TEXT]
text1=OpenVIZ
text3=Tooltip for button3
text4=Tooltip for button4
text5=Tooltip for button5
 
/* ===================================================================== */
/* Specify the tooltip text for each button. This applies to both the    */
/* toolbar as well as the ribbon interface. Separators are skipped.      */
/* ===================================================================== */
[TOOLTIP_TEXT]
text1=Lengthy description for this button
text3=Tooltip for button 3
text4=Tooltip for button 4
text5=Tooltip for button 5

/* ===================================================================== */
/* The message command ID associated with the button.                    */
/* In this example button 2 is a separator, hence no cmd is specified.   */
/* Also, the action of the first button is to run a shell command, hence */
/* no command ID is specified.                                           */
/* ===================================================================== */
[BUTTON_CMD]
cmd3=5
cmd4=10
cmd5=99

/* ===================================================================== */
/* Specify the action to be associated with each button.                 */
/* 1=execute shell command, 2=fire event                                 */
/* In this example button 2 is a separator, hence no action specified.   */
/* ===================================================================== */
[BUTTON_ACTION]
action1=1
action3=2
action4=2
action5=2

/* ===================================================================== */
/* Only present if corresponding action in [BUTTON_ACTION] above is 1.   */
/* Supply the absolute path to the executable to be opened.              */
/* If there are no parameters, leave out shellcmdparam                   */
/* ===================================================================== */
[BUTTON_SHELLCMD_PATH]
shellcmdpath1="C:\Windows\notepad.exe"
shellcmdparam1="C:\samplefile.txt"  

The tags have following meanings:

  • [TOOLBAR_INFO] – Section tag pertaining to general toolbar/ribbon information

  • image_file_name – Specifies a bitmap of type Windows Bitmap, and contains one or more 16 pixel x 16 pixel images with a colour depth of 24 bits per pixel (see note on images below), as shown in the example for the previous customization method.

    This image file is used for the toolbar interface, and also supplies the small icons to the ribbon interface. If it is omitted, then the toolbar interface will not have any images on the user-defined toolbar(s), and the ribbon interface will not have any small icons. As stated earlier, once this mechanism of creating a user-defined toolbar is in operation, the user can no longer make use of his/her own bitmap file (userimages.bmp) in the DTS installation folder.

  • image_file_32 – Specifies a bitmap of type Windows Bitmap, and contains one or more 32 pixel x 32 pixel images with a colour depth of 24 bits per pixel (see note on images below).

    This image file is used by the ribbon interface and supplies the large ribbon icons. If it is omitted, then the ribbon interface will only show the text associated with each button. The toolbar interface will not be affected by this omission. As stated earlier, once this mechanism of creating a user-defined toolbar is in operation, the user can no longer make use of his/her own bitmap file (userimages.bmp) in the DTS installation folder.

  • number_buttons – Specify the number of buttons (including separators) that will be defined in this file.
  • toolbarname – Specify the name that will appear in the un-docked toolbar's title bar, or as the panel name on the ribbon interface.
  • vendor – Specify a unique name (generally the vendor name should be unique), which will be used to distinguish between possibly several custom toolbars and ensure that there is no conflict between command IDs on different toolbars. If you will be supplying more than one toolbar, it is advisable that you ensure this text remains unique, otherwise you will need to ensure that you do not duplicate command IDs. Omitting this parameter will have undesirable side-effects if another vendor inserts its own custom toolbar(s).
  • [BUTTON_TYPE] – Section tag pertaining to button types
    • btn1..btn10 – Specifies the type of each one of these buttons. Possible types are BUTTON (normal push button), STATE (state button which remains in a pressed state until pressed again) and SEPARATOR (separator between buttons). You only need to specify the number of entries corresponding to the number of buttons in number_buttons.
  • [BUTTON_IMAGE_IDX] – Section tag pertaining to button images
    • imageidx1..imageidx10 – 1-based index corresponding to the image position in the image files specified previously. The same index is used for 16x16 and 32x32 image lists, so it is essential that both image lists contain the same number of images. You only need to specify the number of entries corresponding to the number of buttons in number_buttons. Entries for separators can be excluded.
  • [BUTTON_IMAGE_SIZE] – Section tag dealing with image sizes relevant only for the ribbon interface
    • imagesize1..imagesize10 – Specify the image size to be used for each button on the ribbon interface. Possible sizes are LARGE (this will use a 32x32 image) and SMALL (this will use a 16x16 image). You only need to specify the number of entries corresponding to the number of buttons in number_buttons. Entries for separators can be excluded.
  • [BUTTON_TEXT] – Section tag pertaining to text displayed on menus and ribbon panels
    • text1..text10 – Specify the text that will be used on the Tools menu (toolbar interface) or on the Tools category (ribbon interface) on the relevant panel. You only need to specify the number of entries corresponding to the number of buttons in number_buttons. Entries for separators can be excluded.
  • [TOOLTIP_TEXT] – Section pertaining to tooltips for both toolbar and ribbon interfaces
    • text1..text10 - Specify the text that will be used for tooltips when hovering over the relevant button. You only need to specify the number of entries corresponding to the number of buttons in number_buttons. Entries for separators can be excluded.
  • [BUTTON_CMD] – Section tag pertaining to command IDs.
    • cmd1..cmd10 – Specify the command ID that will be passed as a parameter to the calling program when the OnUserButtonClicked event is raised. This must be a number (LONG). You only need these tags for each button of type 2 as specified in the [BUTTON_ACTION] section.
  • [BUTTON_ACTION] – Section tag pertaining to the actions performed by each button.
    • action1..action10 – Possible values are 1 (execute shell command for which further parameters are specified in the next section) or 2 (fire event OnUserButtonClicked which passes the command ID as parameter). You only need to specify the number of entries corresponding to the number of buttons in number_buttons. Entries for separators can be excluded. Automation clients can act the events raised by DTS by implementing the _EEpsSchedule.OnUserButtonClicked event.
  • [BUTTON_SHELLCMD_PATH] – Section tag pertaining to buttons of type 1 (see [BUTTON_ACTION] section)
    • shellcmdpath1..shellcmdpath10 – Specifies the command line to execute (excluding command line parameters, which are specified separately). You only need to specify the number of entries corresponding to the buttons that perform action 1.
    • shellcmdparam1..shellcmdparam10 – Optional tag which specifies the command line parameters for the relevant shellcmdpath tag.

COM Interface

Following methods and events are useful when implementing custom toolbars, as these give specific feedback to an automation client about the state of the custom toolbars:

  • Event _EEpsSchedule.OnUserButtonClicked

  • Method IApplication.GetButtonState

    Method IApplication.SetButtonState

Related topics and activities