Using Configuration Abilities

Using Configuration Abilities

Although associating code blocks with individual configurations may be a sufficient solution for some applications, it can sometimes be difficult to maintain. You might find that you are always adding a certain group of configurations to the same code blocks. Or, when adding a new configuration to an existing project, you might find it onerous associating that configuration with each existing and appropriate code block.

In reality, code blocks are usually defined to address some specific feature of the platform to which that code will be deployed; and often, several deployment platforms share the same features and, thus, the same code blocks. To address these problems, configurations have the concept of abilities.

Abilities are identifiers that can be associated with code blocks in much the same way that configuration names are. Configurations can then be associated with as many abilities as desired. Once this is done, activating a configuration uncomments any code block containing either the configuration or any of its associated abilities.

For example, you might be creating an application with six different distributions. In your source, you create some code blocks that handle calls to a vendorspecific Bluetooth implementation. Three of your target distribution platforms will have that specific Bluetooth API available. Rather than list in each code block those three configuration names, you would instead associate that code block with an ability called VendorSpecificBluetoothAPI. Then you associate it with the three configurations that support the Bluetooth API.

This makes maintenance much easier for existing code blocks. Now, if you decide to support a new device that has a certain ability, you can simply attach all appropriate abilities to the new configuration. Then it will automatically be compatible with all existing code blocks.

As such, it is almost always preferable to use abilities when creating code blocks rather than simply configurations. The only cases for using pure configuration names are when you are never planning on supporting more than a few platforms for a given application or when the code block is specific to only one deployment platform.

In principle, abilities can be used as three types of values even though they are all stored as String objects internally. They can be treated as Boolean symbols and the preprocessor can check for their definition; they can be treated and compared as Strings (e.g., ScreenSize="100x120"); and they can also be used as Integers (e.g., ScreenWidth=100) , provided that the string value they hold is a valid integer.

Creating and Associating an Ability with a Configuration

To create and associate an ability with a configuration:

1. Right-click your project in the Projects window and choose Properties to open the Project Properties dialog box.

2. Select the Abilities panel.

3. From the Project Configuration drop-down box, select the configuration you would like to associate with the new ability.

4. Uncheck the Use Values from "DefaultConfiguration" checkbox (if you did not select DefaultConfiguration in the previous step).

5. Click the Add button to bring up the Add Ability dialog box, shown in Figure 14-7.

   Figure 14-7. Add Ability dialog box

   

6. If the ability you wish to associate with the configuration is not in the Abilities list, simply write your own identifying name in the text field, add a value if necessary, and click OK to add the ability. Otherwise, you can use one of the predefined abilities.

7. The newly created ability is listed and selected in the Abilities panel of the Project Properties dialog. If you are done adding abilities to the device configurations, click OK to close the Project Properties dialog box.

Once an ability is associated with at least one configuration in the project, that ability will appear in the code completion popups when you edit preprocessor blocks in the editor as shown in Figure 14-8. The preprocessor code completion is invoked in two regimes, either for directives following the //# token or for abilities following a directive statement.

Figure 14-8. Ability code completion

The list of abilities contained in the Abilities List view of the Add Ability dialog box contains all the abilities that are attached to configurations in any project that the IDE is currently aware of. The IDE is aware of more projects than those that are open, so don't be surprised if you see some abilities there that don't belong to any open project. There is no Remove Ability button in the Add Ability dialog box, because it simply displays all abilities that are associated with any configuration.