RADF:How to Create a New Feature

From DocR23

A RADF feature is a plug-in (component) that is extended with a Graphical User Interface (GUI). It may contain a user application, or its part, or common functionality for several applications. Each feature GUI accesses the main application window, and creates and controls GUI elements such as Ribbons and Feature Windows. This article describes a workflow for creating a new feature.

Note: Refer to the Plug-ins article for architectural details about plug-ins and features.

Contents 1 Process Flow 1.1 Create a Factory: Implement the IFeatureFactory Interface 1.2 Implement Additional Interfaces in the Factory 1.3 Create a Feature Class: Implementing the IFeature Interface 1.4 Create a Ribbon 1.5 Create a Feature Window 1.6 Add Functional Class(es) 2 Implementation Steps 2.1 Step 1. Create a New Visual Studio Project 2.2 Step 2. Add a Factory Class 2.3 Step 3. Implement the IPluginFactory Interface in a Factory Class 2.4 Step 4. Implement the IFeatureFactory Interface in a Factory Class 2.5 Step 5. Create a Feature Class 2.6 Step 6. Add a Ribbon 2.7 Step 8. Add a Feature Window 2.8 Step 9. Add Application Options to the Factory (optional) 2.9 Step 10. Implement Functionality 2.10 Step 11. Enable RADF to Discover and Load the Feature 2.10.1 Method 1. Adding to app.config 2.10.2 Method 2. Copying to the \Features Folder 3 See Also

Process Flow

Every feature in RADF must have at least one concrete class implementing the IFeatureFactory interface, to be considered as a feature. Such a class is called a feature factory. A feature assembly (DLL) may have more than one factory. This factory represents the structural part of a feature, wiring the feature into RADF. Apart from the feature factory, a feature must contain the actual functional implementation as well as the GUI. For example, a button to fillet a face will have a RibbonButton object as well as a function (implementation) that it calls.

Create a Factory: Implement the IFeatureFactory Interface

IFeatureFactory derives from IPluginFactory. Refer to Create a Factory: Implement the IPluginFactory Interface for details.

Each feature has a Title that appears on its Ribbon.

The Feature property gives access to the IFeature, created by the factory.

The Create method creates a feature instance, activates its Ribbon, and provides callback (delegate) to create feature windows. The feature factory may decide whether to create one window, or many, or none.

Implement Additional Interfaces in the Factory

Unlike the Plugin Factory, the Feature Factory has a Create method for creating GUI elements. This allows you to interact with internal functionality; therefore, a single IFeatureFactory interface implementation can be sufficient to create a usable feature. However, often more control over the feature is desired, so additional interfaces may be implemented.

For example, you may want to control some feature parameters, but not from the Ribbon. RADF offers the Application Options dialog for this purpose. To add necessary options to the dialog, feature factory must implement the IFeatureFactory, derived from the IOptionsProvider interface.

Create a Feature Class: Implementing the IFeature Interface

This class is a central part of a feature. It not only holds all feature pieces together, but also holds references to the Ribbon, Feature Window, and additional classes.

This class implements the IFeature interface, or derives from the ARibbonFeature abstract class.

Create a Ribbon

You may create a feature Ribbon if necessary. A common practice in RADF is to name it with the suffix Ribbon. Also, you may create an XAML file with GUI elements, and implement the event handlers in the class file.

Create a Feature Window

A Feature Window is where you add your custom GUI. As long as RADF uses the docking manager, this window can be pulled from the main window and designed to look as the application main window. Because this is not always needed, the feature may skip creating one.

Add Functional Class(es)

The functional classes are for application developers to add their implementation code. The feature could be a large application; thus, there is no limit to the number and functionality of these additional classes. For large implementations, a number of dependent assemblies can be created.

Implementation Steps

Step 1. Create a New Visual Studio Project

Open a RADF solution and add a new project. The project type will most likely be WPF User Control Library for proper references set by Visual Studio, and must compile to a DLL. A Feature project cannot be of application- or web-related type.

1. Open Project Properties.
   1. On the Application page, set the property labels for Assembly name and Default namespace, for example:
      <your company name>.RADF.<your feature name>
   2. On the Build page, set Output path to ..\..\$(ARCH)\code\bin\
2. Set references to DLLs in ..\..\$(ARCH)\code\bin\:
   • AvalonDock.dll if the Feature Window will be used.
   • RibbonControlLibrary.dll if the Ribbon will be used.
3. Set references to DLLs in ..\..\$(ARCH)\code\bin\:
   • Spatial.RADF.Core.dll
   • Spatial.RADF.CoreGui.dll
   • Other RADF assemblies, as necessary
4. Add WPF references, if they were not added by Visual Studio:
   • WindowsBase
   • PresentationCore
   • PresentationFramework

Step 2. Add a Factory Class

Add a new class to the project and derive it from the IFeatureFactory interface, which inherits from the IPluginFactory interface.

A common practice in RADF is to name this class with a Factory suffix.

Step 3. Implement the IPluginFactory Interface in a Factory Class

Implement IPluginFactory as described in Implement the IPluginFactory Interface in a Factory Class.

Step 4. Implement the IFeatureFactory Interface in a Factory Class

The IFeatureFactory interface adds the Create method, which creates a feature instance, including a ribbon and feature window if necessary. The caller of the method must supply callbacks for creating a ribbon and feature window, however, they will be filled with content in the ARibbonFeature implementation. The feature factory may create one window, or many, or none. When this method completes successfully, it sets the Activated property to true.

Step 5. Create a Feature Class

This class creates the Ribbon and Feature Window.

To add a new class, extend ARibbonFeature. This class must have implementations of the CreateRibbonTab and CreateFeatureWindowContent methods.

If ARibbonFeature is not suitable, the IFeature interface can be implemented.

Step 6. Add a Ribbon

To create a Ribbon tab for the feature, use another feature's ribbon class or begin from scratch. The implementation of the Ribbon tab must contain both an XAML file and C# file for the XAML. The class must derive from a Microsoft RibbonTab Windows Control.

Refer to How to Extend the GUI for details on adding GUI elements to your feature.

Step 8. Add a Feature Window

Feature windows provide space for the GUI that is specific to the feature. If a feature window is unnecessary, then you may skip this step.

Any WPF control, such as text boxes, labels, and combo-boxes, can be placed on these feature windows. A feature can have any number of feature windows.

To create a feature window, use another feature's window class or begin from scratch. Develop the desired GUI inside of this feature window.

Step 9. Add Application Options to the Factory (optional)

The IOptionsProvider interface may be optionally implemented in the factory to allow user control of some parameters of the new feature. Application options are the application settings that are common to all users. These settings can be modified from within the application using the Options dialog from the File menu. Application options are used for those application settings that are likely to be modified by end users. Examples of application options include Background Color and Selection Color.

Step 10. Implement Functionality

At this point we have a harness for user functionality to become a RADF feature. Add the remaining needed functionality and connect the GUI events as necessary.

Step 11. Enable RADF to Discover and Load the Feature

As mentioned in Plug-in Loading and Management, there are two ways to load a feature or plug-in into RADF:

• Adding it to app.config (as done in the WPF Desktop project)
• Copying the DLL to the \Features folder.

Either of these methods can be used for a particular feature, but not both.

Method 1. Adding to app.config

Add the following to the FeaturesToLoad section of app.config (as done in the WPF Desktop project).

<PluginManager>
      ...
      <FeaturesToLoad>
        ...
        <add name="YourFeatureDllName" />
        ...

The features are loaded in the order in which they appear in this list.

Method 2. Copying to the \Features Folder

Open Properties of the project and go to the Build Events tab. Create a Post-build Event and insert the following:

if not exist $(OutDir)Features\ mkdir $(OutDir)Features\
    copy $(TargetFileName) $(OutDir)Features\

RADF loads features from this folder after loading the ones specified in the app.config file.

See Also

• RADF Definitions
• RADF Plug-ins
• How to Create a New Plug-in