F. API documentation
think-cell allows you to programatically control some functionality through an API. Here you can find an overview over all available API functions, and general instruction for how to setup your development environment to write macros, add-ins, or standalone programs that access them.
Contents
- F.1
- Getting started
- F.2
- API reference
F.1 Getting started
think-cell's API is integrated into the Office Automation model, so it can be accessed from any language with which you can program Office, such as Visual Basic for Applications (VBA) or C#.
The entry point into think-cell is the think-cell add-in object. It can be accessed via the Application.COMAddIns
collection. Calls into think-cell are always late-bound, thus there is no type library or reference to add. See Microsoft’s knowledge base for an explanation:
Using early binding and late binding in Automation
Some API functions are methods of the think-cell add-in object in PowerPoint, and some of the think-cell add-in object in Excel. We will use tcPpAddIn
for references to the PowerPoint add-in, and tcXlAddIn
for references to the Excel add-in.
F.1.1 Visual Basic for Applications
To write macros using Visual Basic for Applications (VBA), you use the development environment integrated into the Office host application. This can be accessed by pressing Alt+F11. The definition of a macro is usually contained in a module, which you can add via Insert > Module. You can view all macros defined for a given document by pressing Alt+F8.
To indicate that method calls into the think-cell add-in are late-bound, you need to declare the variable containing the reference to it as Object
:
The type library for the Office host application is always referenced by default. If you need to access the object model of another Office application, you need to add its type library as a reference.
For example, if you want to use a macro in PowerPoint to manipulate data in an Excel sheet before updating a think-cell chart from it, you need to manually add the Microsoft Excel 16.0 Object Library via the Tools > References dialog in the VBA development environment.
Note: 16.0 is the version number of Office 2016 and later. For Office 2010 or 2013, you need to use the 14.0 or 15.0 object libraries, respectively. If you have multiple versions of Office installed, the References dialog will only show the object libraries of the latest version installed. We will assume in the following that you are using Office 2016 or later.
Using Application.COMAddIns("thinkcell.addin").Object
will always get you the think-cell add-in object of the current Office host application, that is tcPpAddIn
or tcXlAddIn
, depending on whether you use it in PowerPoint or Excel. To acquire a reference to the add-in object in the other Office application, and access the API functions it exposes, acquire it through an appropriate application instance.
For example, to acquire a reference to tcXlAddIn
from PowerPoint:
Note that this requires the Excel object library to be added as as a reference.
We recommend using the Option Explicit
statement, which forces the explicit declaration of all variables, thereby helping to avoid common programming errors and improving the suggestions provided by IntelliSense. You can have it automatically added to all modules by activating Tools > Options > Code Settings > Require Variable Declaration. It is included in all our code samples.
F.1.2 C#
You can use the think-cell API from C# when developing add-ins and document code extensions running inside an Office host application, as well as when developing standalone applications.
We will assume in the following that you are using Visual Studio 2017 or later to develop Office solutions in C#. Refer to the next section for more specific setup instructions for add-in development. With each of our code samples, we will indicate which Visual Studio project template to use.
To make method calls to the think-cell add-in object late-bound, declare the variable containing the reference to the think-cell add-in object as dynamic
; this is also the type inferred by the compiler when declaring the reference as var
, so that you can simply write:
Here ppapp
is a reference to a PowerPoint Application
object in which think-cell is loaded.
To access the object model of an Office application, you need to add either its type library or its primary interop assembly (PIA) as a reference to your project. We recommend adding the type library if possible, since Visual Studio will automatically add a reference to the corresponding PIA, if one is available, or generate an interop assembly from the type library if there is none (see here).
For example, to be able to get the reference to the think-cell add-in object as above, you would add the Microsoft PowerPoint 16.0 Object Library found in the COM > Type Libraries tab of the Reference Manager dialog. Depending on your project type, this dialog is accessed either by right-clicking References or Dependencies in the Solution Explorer and selecting Add (COM) Reference.
Note: 16.0 is the version number of Office 2016 and later. By using the Embed Interop Types option, which is enabled by default for a reference to a COM type library, an application compiled with this reference will be backward (and forward) compatible with other versions of Office as long as all interfaces used exist in their object model. See here for more information.
think-cell's API functions indicate errors using COM HRESULT
s. Some of these are automatically mapped onto corresponding .NET exception classes, see How to: Map HRESULTs and Exceptions .
F.1.2.1 Add-in development
To develop add-ins for Office, or code extensions for Office documents, you use the PowerPoint/Excel VSTO Add-in and Excel VSTO Template/Workbook project templates. These are part of the Office Developer Tools for Visual Studio, which are installed as part of the default configuration. Should these tools and templates not be available in your Visual Studio installation, you can add them, for example, by going to Settings > Apps > Visual Studio 2022 > Modify > Other Toolsets, checking Office/SharePoint development and clicking Modify. See also Microsoft's documentation here and here.
The PIA for the Office host application of the selected template is always loaded by default. If you need to access the object model of another Office application, you need to add its type library as a reference as explained above.
Note: think-cell's API cannot be used from Office Web Add-Ins—unfortunately now simply called "Office Add-ins" by Microsoft—as they cannot interact with the Office application's object model directly, and in particular cannot interact with COM add-ins such as think-cell.
F.2 API reference
F.2.1 Updating elements and presentation templates with Excel data
F.2.3 Importing Mekko Graphics charts
F.2.1 Updating elements and presentation templates with Excel data
The functions in this section can be used to programatically update think-cell elements, usually placeholders in a presentation template, with data from Excel. UpdateChart
updates think-cell elements, specified by a name assigned to it in the template, with data from an Excel range passed as an argument. See also 24. Introduction to automation for how to prepare the template.
PresentationFromTemplate
instantiates a presentation template with data from a linked Excel workbook. See also 21. Excel data links for how to create Excel links.
The functions in this section are methods of the think-cell add-in in Excel.
F.2.1.1 UpdateChart
F.2.1.1.1 Signature
VBA
C#
F.2.1.1.2 Description
This function updates all elements in target
with name strName
with the data contained in rgData
. For the data to be interpreted correctly for charts, the range rgData
must conform to their configured datasheet layout, or its transposed version, see also 21.1 Creating a chart from Excel and 21.2 Fitting the data layout. Whether the default or the transposed version is to be used is indicated by setting bTransposed
to false
or true
, respectively. For elements other than charts, tables for example, the value of bTransposed
is ignored.
target
must be a Presentation
or SlideRange
, or a single Slide
, Master
or CustomLayout
.
The name strName
is matched case-insensitively. It must have been previously assigned in PowerPoint using the UpdateChart Name property control as described in 24. Introduction to automation.
To ensure that the correct elements are targeted, make sure that they are the only ones with their UpdateChart Name set to strName
in the object passed as pres
.
If a targeted element is linked to an Excel data range when invoking this function, the link is broken. Afterwards, the element will not be linked to any Excel range.
F.2.1.1.3 Examples
To use these samples, prepare a presentation as described in 24. Introduction to automation, and save it as C:\Samples\UpdateChart\template.pptx
.
VBA
To use this sample add it to a module in an Excel workbook.
It requires a reference to the Microsoft PowerPoint 16.0 Object Library (see F.1.1 Visual Basic for Applications for details).
Running UpdateChart_Sample
in a workbook will update the chart in the presentation template with the data contained in range A1:D5
of its first sheet.
C#
To use this sample, replace the code in Program.cs
of the C# Console App project template with it.
It requires references to the Microsoft PowerPoint 16.0 Object Library, the Microsoft Excel 16.0 Object Library and the Microsoft Office 16.0 Object Library (see F.1.2 C# for details).
Running the resulting application will update the chart in the presentation template to contain a single series named "Series 1" with values 1, 2, 3, and save the result as template_updated.pptx
.
F.2.1.2 PresentationFromTemplate
F.2.1.2.1 Signature
VBA
C#
F.2.1.2.2 Description
This function uses the data links between the Excel workbook wb
and the template with filename strTemplate
to instantiate that template by updating the linked elements with the data from the ranges they are linked to. The result is a new presentation within the PowerPoint instance ppapp
.
strTemplate
can either be a full path or a relative path, which is then taken to be relative to the location of the Excel workbook file wb
.
All elements in strTemplate
that are linked to the Excel workbook wb
are updated (regardless whether they are set to auto-update or not). In the resulting presentation, their data links are broken to prevent further changes to these elements.
Elements in strTemplate
which are linked to Excel workbooks other than wb
are left unchanged and still linked, so it is possible to update links from multiple Excel workbooks by saving the result of this function as a new template and then calling this function again with the next workbook.
If you want to control the colors of chart segments or the formatting of table cells with the Excel link, you can set the color scheme to Use Datasheet Fill on Top (see 3.8.2 Color scheme) or the Use Datasheet... options (see 17.3 Formatting a table), respectively. Likewise, to control the number format with the Excel link, set it to Use Excel Format (see 6.5.3 Number format).
Make sure to set the relevant formatting options and the number format of the respective cells in Excel before calling PresentationFromTemplate
.
F.2.1.2.3 Examples
To use these samples, first create a presentation containing a stacked chart linked to the range G1:K4
of the first sheet in an Excel workbook as explained in 21.1 Creating a chart from Excel. Save the resulting presentation as C:\Samples\PresentationFromTemplate\template.pptx
and the workbook as data.xlsx
in the same directory.
VBA
To use this sample, add it to a module in the Excel workbook data.xlsx
prepared as explained above.
It requires a reference to the Microsoft PowerPoint 16.0 Object Library (see F.1.1 Visual Basic for Applications for details).
Running PresentationFromTemplate_Sample
will change the value in cell Sheet1!H3
, which is linked to the first value of the first series of the chart contained in template.pptx
, from i=1
to 10
, create a new presentation with the chart in the template updated to contain that value, and which is not linked to the workbook anymore, and save it as output_i.pptx
in the same directory as the template.
C#
To use this sample replace the code in Program.cs
of the C# Console App project template with it.
It requires references to the Microsoft PowerPoint 16.0 Object Library, the Microsoft Excel 16.0 Object Library and the Microsoft Office 16.0 Object Library (see F.1.2 C# for details).
Running the resulting application will visibly open Excel, load the workbook data.xlsx
, change the value in cell H3
, which is linked to the first value of the first series of the chart contained in template.pptx
, from i=1
to 10
, create a new presentation with the chart in the template updated to contain that value, and which is not linked to the workbook anymore, and save it as output_i.pptx
in the same directory as the template.
F.2.2 Controlling styles
The functions in this section can be used to programmatically load, inspect, and remove think-cell styles. LoadStyle
loads a style from a style file into a master slide or a single custom layout. LoadStyleForRegion
loads a style from a style file into a specific region of a custom layout. GetStyleName
returns the name of the style loaded into a master or custom layout. RemoveStyles
removes all styles from a custom layout.
See C.1 Creating a think-cell style and D. Style file format for more information on creating and editing styles. See C.2 Loading style files for more information on loading them.
The functions in this section are methods of the think-cell add-in in PowerPoint.
F.2.2.1 LoadStyle
F.2.2.1.1 Signature
VBA
C#
F.2.2.1.2 Description
This function loads the style contained in the style file at FileName
into a master or custom layout, specified via the parameter CustomLayoutOrMaster
.
CustomLayoutOrMaster
must be a CustomLayout
or Master
.
When applied to a custom layout where a regional style has been set (see F.2.2.2 LoadStyleForRegion), the regional style will be removed. This means that you need to load the style that should apply on the rest of the slide using this function before you load a style restricted to a region.
When applied to a master, any styles loaded into the custom layouts contained in that master, regional and unrestricted, will be removed. This means that you need to load the style that should apply to custom layouts without a specific style into the master before loading a style applying to a specific custom layout using this function.
F.2.2.1.3 Examples
VBA
To use this sample, add the following code to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
F.2.2.2 LoadStyleForRegion
F.2.2.2.1 Signature
VBA
C#
F.2.2.2.2 Description
This function loads the style file at FileName
into the custom layout CustomLayout
and restricts it to a region given by Left
, Top
, Width
, Height
. On the rest of the slide, the style loaded into the master, or the one previously loaded into the custom layout with LoadStyle
applies.
The parameters Left
, Top
, Width
, Height
are given in PowerPoint points. Left
and Top
specify the distance of the left and top edges of the region from the left and top edges of the custom layout, respectively. Usually you will set them as fractions of the total slide height and width. For example, for a region covering the right two thirds of the custom layout, you would set
You can also manually add a shape to a slide or custom layout, query its properties Left
, Top
, Width
, Height
programmatically and use the values with LoadStyleForRegion
to restrict the style to the same region covered by the shape.
think-cell supports a maximum of two styles per custom layout. One is set with LoadStyle
and covers everything not restricted to a region, the other is set with LoadStyleForRegion
.
F.2.2.2.3 Examples
VBA
To use this sample, add the following code to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
F.2.2.3 GetStyleName
Supported in think-cell 13 and later.
F.2.2.3.1 Signature
VBA
C#
F.2.2.3.2 Description
This function returns the name of the style loaded into the CustomLayout
or Master
CustomLayoutOrMaster
. This is the same name that is specified in the name
attribute of the <style>
element of the corresponding style file (see D.2.1 style).
It returns an empty string when no style is loaded into CustomLayoutOrMaster
. Note that a master always has a style loaded into it when think-cell is active and that the name of a style cannot be empty.
If a name is returned for a CustomLayout
, it is the name of the style loaded into it with F.2.2.1 LoadStyle, not of the one loaded with F.2.2.2 LoadStyleForRegion, if any.
F.2.2.3.3 Examples
VBA
To use this sample, add the following code to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
F.2.2.4 RemoveStyles
F.2.2.4.1 Signature
VBA
C#
F.2.2.4.2 Description
This function removes all styles from the custom layout CustomLayout
. Afterwards, the style loaded into the master applies. Potentially, there can be a style loaded into the custom layout and another style restricted to a specific region of the custom layout. As RemoveStyles
removes all styles, both will be removed. The style loaded into a master cannot be removed, as there always needs to be a valid style associated with a master. It can be overwritten with a different style file.
F.2.2.4.3 Examples
VBA
To use this sample, add the following code to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
F.2.3 Importing Mekko Graphics charts
The functions in this section can be used to programmatically import and inspect charts created with Mekko Graphics to think-cell. ImportMekkoGraphicsCharts
replaces Mekko Graphics charts with equivalent think-cell charts. GetMekkoGraphicsXML
extracts the XML definition of a Mekko Graphics chart.
The functions in this section are methods of the think-cell add-in in PowerPoint.
F.2.3.1 ImportMekkoGraphicsCharts
Supported in think-cell 13 and later.
F.2.3.1.1 Signature
VBA
C#
F.2.3.1.2 Description
This function replaces all Mekko Graphics charts in the array of Shape
s passed to it with an equivalent think-cell chart. The shapes must all be on the same slide. Before modifying the slide, the function will make a copy of the unmodified slide and insert it directly after the modified version.
The function returns a reference to this copy, if one was made.
It returns Nothing
/null
, if the presentation was not modified, for example because the array did not contain any Mekko Graphics charts.
F.2.3.1.3 Examples
VBA
To use this sample, add it to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
Running ImportAll
on a presentation will go through the slides in the presentation and replace all visible Mekko Graphics charts with equivalent think-cell charts, making a copy of each slide containing one before modifying it.
C#
To use this sample, add this method to the ThisAddIn
class of the C# PowerPoint VSTO Add-in project template (see F.1.2 C# and F.1.2.1 Add-in development for details).
Add the following line to the ThisAddIn_Startup
method to run ImportAll
on each presentation that is opened:
F.2.3.2 GetMekkoGraphicsXML
Supported in think-cell 13 and later.
F.2.3.2.1 Signature
VBA
C#
F.2.3.2.2 Description
This function returns the XML of the Mekko Graphics chart in shp
as a string. It does not modify the shape passed to it.
If shp
is not a Mekko Graphics chart, an E_INVALIDARG (0x80070057)
error is raised.
F.2.3.2.3 Examples
VBA
To use this sample, add the following code to a module in PowerPoint (see F.1.1 Visual Basic for Applications for details).
C#
To use this sample replace the code in Program.cs
of a Console App with it.
It requires references to the Microsoft PowerPoint 16.0 Object Library and Microsoft Office 16.0 Object Library (see F.1.2 C# for details).
Running the application will go through the presentation in C:\Samples\GetMekkoGraphicsXML\presentation.pptx
and print the XML of the Mekko Graphics charts contained in it to the console.
F.2.4 Miscellaneous
The functions in this section are methods of the think-cell add-in in PowerPoint.
F.2.4.1 StartTableInsertion
Supported in think-cell 13 and later.
F.2.4.1.1 Signature
VBA
C#
F.2.4.1.2 Description
Calling this method has the same effect as clicking Table in the Elements menu in PowerPoint.