Edit an UIC File

The content of a User Interface Customization (UIC) file is created using the CAF based applications’ built-in interactive user interface customization tool available from the Customize window. Click to display the Customize window.

Active Customization File

The customization system supports the concept of multiple configuration files. Any number of levels of customization file can be defined either using the module customization configuration file or the CommandBarManager. AddUICustomizationFile() method, and they are layered on-top of each other in the order they appear in the list.

Selecting an entry in the list will update the customize explorer will show command tools with all configuration information defined in the selected file and those above it. Any items in the customize explorer or list of command tools view which are not defined in the currently active customization file are displayed with an italic font in grey.

Any customization file which a user does not have write access to does not appear in the drop-down list, but its contents are included in the customize explorer and list of command tools view.

The selected customization file will become the active customization file. It will only be possible to edit customization information defined in this file.

Customize Explorer

The Customize Explorer is populated with a representation of the active customization. It shows CommandBars and their contents, Menubars and their entries, Context Menus and their entries and Ribbons and their contents defined in all of the configuration files above and including the currently selected file. It also contains a list of the currently loaded resource files.

When a node in the customize explorer is selected, the property grid is updated with the corresponding object so that its properties can be edited. Only objects which are defined in the currently Active Customization File can have their properties modified.

Selecting a node in the customize explorer which represents an object defined in a non-active file will update the property grid, but it will be disabled, preventing modification.

If the selected node represents a resource file, the Resource Editor will be displayed instead of the property grid.

The tools owned by a MenuTool or Ribbon can be re-ordered by dragging the tool to the new desired position.

Note:
Only ribbons and their contents (tabs, groups and menus) are described.

Command Tools

The list of command tools is populated with each of the tools defined in each of the configuration files above and including the currently selected file.

Use the functionality available to:

• Select a Node in the List

• Drag & Drop from the List to the Customization Explorer

• List Context Menu.

Select a Node in the List

The property grid is updated with the corresponding tool object so that its properties can be edited. Only objects which are defined in the currently active customization file can have their properties modified. Selecting a tool which is defined in a non-active file updates the property grid, but it will be disabled thus preventing modification.

Drag & Drop from the List to the Customization Explorer

Tools can be dragged from the list of command tools and dropped into a MenuTool or Ribbon in the customization explorer. It is also possible to add tools to a menu or ribbon defined in a higher level customization file.

The functionality can be used to integrate new tools into an existing system defined menu hierarchy and extend system toolbars as well as creating new top level menus and new tabs.

One possible risk of adding tools to menus or ribbons defined at a higher level is that the higher level structure might at a later date be modified making these tools ‘orphaned’, or making the data which is stored to indicate their position within the host invalid. To warn of this, these tools are displayed in red within the customization explorer.

List Context Menu

Use the right-click menu available from the List of Command Tools pane of the Customize window to delete, create a tool or get an image from the clipboard.

Delete

Deletes the currently selected tool, if the selected tool is not editable then the delete operation is disabled. If the tool has been used then a warning message is displayed to confirm that the delete should be carried out.

New

Uses the displayed menu to create a new menu tool, create a new tool of the required type with a unique default name (Tool<N>) and add it to the list. New tools can also be created using the icons on the left side of the command tool pane.

The properties for the new menu tool are displayed in the properties grid and can be edited.

Property Grid

Use the functionality available from the property grid to edit the various properties of the tools. The customize explorer or the list of tools is kept up to date with any property changes.

Tool Properties

The following properties can be set for all Tools:

• ApplicationContext

  • Currently unused

• Arguments

  • List of arguments supplied to the Command

• Caption

  • Text to display on CommandBar

• Command

  • Command to run (see below)

• DisplayStyle

  • Determines how the tool is displayed on the CommandBar

    • Default- The tool is displayed in a default style.

    • DefaultForToolType - The tool is displayed based on the default for the tools type and its location.

    • TextOnlyAlways - The tool is always displayed as text only.

    • TextOnlyInMenus - The Tool is displayed as a graphic when located on a Toolbar, and displayed as text when located on a Menu.

    • ImageAndText - The tool is displayed using its assigned image and text. This setting is ignored when the item is on a top-level menu.

    • ImageOnlyOnToolbars - The Tool is displayed as a graphic when located on a Toolbar, and displayed as image and text when located on a Menu.

• Icon

  • Icon to display on CommandBar

• KeyTip

  • Tip is shown on the ribbon when the Alt key is pressed, aids quick navigation

• Name

  • Unique name for this tool

• Shortcut

  • Shortcut key to activate this tool

• Tooltip

  • Plain tool-tip text to display on mouse-over

• TooltipFormattedText

  • Formatted tool-tip text to display on mouse-over

• TooltipTitle

  • Title for tool-tip

The following properties are available on some Command Tools:

• AutoComplete

  • Sets whether the edit portion is automatically updated to match an item in the list as new characters are typed.

• Control

  • Control embedded in container

• Editable

  • Sets if the text is editable by the user

• MaxLength

  • Maximum number of characters the user is allowed to enter

• Password

  • Display text in password mode (hidden)

• ValueList

  • List of values to display

• Width

  • Tool width on the CommandBar

If required, the command property can be modified, click . . . in the Command field to display the Command window. By default the command type is set to Command, other command types available for selection are Macro and Command Class.

Here a list of the currently loaded CAF Command objects is displayed for selection.

Macro

The macro functionality uses a special command class to invoke the entered single PML command. This enables the PML developer to use the interactive customization tool to create their own menus and commandbars without needing to write C# command classes.

Command Class

Use the functionality available from the Command window, to select a command class from populated list:

• DockedWindowStateCommand

• ModuleSwitchCommand

• SelectTaskPaneCommand

• CommandBarStateCommand.

Ribbon

The ribbon section of the explorer enables the creation of tools; application menus, contextual tab groups and tabs, the creation, modification, deletion or group order is identical to that previously described. Refer to Edit an UIC File for further information.

Resource Files

Use of the resource editor enables each of the currently loaded resource sets to be edited. It supports String, Icon and Bitmap resources. Each resource set can comprise a number of resource files, with an Invariant Language resource file and any number of locale specific resource files. When a resource file is selected, the Resource Editor is activated.

Resource Editor Command Bar

When active, the resource editor command bar contains the following operations:

New resource files (icon or bitmaps) can be added using drag-and-drop from a windows explorer. The resource id is generated from the filename, capitalized and prefixed with "ID_". If there is a clash with an existing resource, a confirmation window is displayed prompting for confirmation of file replacement.

Note:
Functionality is available for icons and bitmaps only.

New String Resource

Use the property grid to add new string resource(s), double click in the available blank entry in the grid. Once created a new blank row is automatically added to the grid.

Modify String Resources

Use the Edit Formatted Text window to edit existing resource(s), right click the required string resource in the property grid, from the displayed menu select Formatted Text Editor.

Note:
The functionality available from the formatted text editor is standard.

Locale specific resource file

Use the localizable resources functionality to customize a locale specific resource file or add a new locale specific resource file to the resource file set (this can then be selected for editing). Refer to Resource Manager for further information.

View Style

Use the standard functionality available for selection from the View Style menu to change how information is displayed in the resource file editor.

The icon and bitmap tabs also have a popup menu which provides access to these functions as well as a rename function. Double clicking on a resource also enters the rename mode.

Using Resources for Properties

Properties of tools which are strings or the icon property can use resources for their value. Reference to a resource is made using the form <ResourceSet Name>:<Resource Id> as shown below:

The caption and icon properties can be set on a tool in the tool list by drag-and-drop from the resource editor onto the tool.

Standalone Resource Editor

There is a standalone version of the resource editor available to enable resource files to be created and edited. This program is called "ResourceEditor.exe" and can be found in the installation directory.

When started it displays a file selection window which enables the choice of an existing resource file or the addition a new resource file.