XLL+ Class Library (7.0)

RtdHandleDemo Sample

Demonstrates the use of RTD handles to represent objects in Excel

Overview

This add-in contains the code described in the User Guide topic Using object handles.

It contains four sets of add-in functions, each of which consists of a creator function (e.g. Thing.Create), which creates an object and returns it to Excel as a handle, and some "getter" functions, which return properties of the object (e.g. Thing.Value).

The three sets of functions demonstrate different handle techniques:

Object Functions Description

Thing

Thing.Create
Thing.Name
Thing.Value
Thing.CreationTime

The simple case: a Thing object is created, and is returned as a handle.

CachedThing

CachedThing.Create
CachedThing.Name
CachedThing.Value
CachedThing.CreationTime

The creator function CachedThing.Create is marked as Cache results. This means that no unnecessary objects are created: for any given set of constructor parameters, only one object is ever created.

See Combining handles with other features in the User Guide for more details.

CustomThing

CustomThing.Create
CustomThing.Name
CustomThing.Value
CustomThing.CreationTime

A custom formatter class CustomThingHandleFormatter is defined, and is applied to the object cache for CustomThings.

See Custom handles formats in the User Guide for more details.

map

Map.Create
Map.GetValue

The object created is a complex type, std::map<std::string, std::string>, which contains namespaces and a template with arguments. Note that as of XLL+ version 7.0.6 the generated code deals with this seamlessly.

You may encounter some warnings (warning C4503) when you compile the code. This is due to the length of the names of the templated types. As is normal with this warning, you can use a typdef to work around it; this also makes the code more readable.

Requirements

To edit the functions in this add-in, you need to load the extension file RtdHandles.xpe. See Loading an extension file for instructions.

You should also make sure that none of the following extension files is loaded, since the various types of handles are mutually exclusive.

Classes and functions used

psl::CreateHandleInCache | CHandleFormatter<T>

Sample project

Each sample project is located in a sub-directory of the Samples directory of the XLL+ installation. To use the sample project, open the solution file RtdHandleDemo.sln or the project file RtdHandleDemo.vcproj.

You can enable debugging under Excel by using the Setup Debugging command in the XLL+ ToolWindow.

When delivered, the help files are excluded from the build. You can enable the help build by selecting the files RtdHandleDemo.help.xml and RtdHandleDemo.chm in the Solution Explorer, and using the right-click menu to view Properties. Select the page "Configuration Properties/General" and set the "Excluded from build" property to "No". See Generating help in the User Guide for more information.

See Also

List of Sample Projects | Using object handles | NumericHandleDemo sample | StringHandleDemo sample | StringPtrHandleDemo sample