Invoking Commands on a COM Object :: COM and DDE Support (Windows Only) (External Interfaces)

External Interfaces

Invoking Commands on a COM Object

When invoking either MATLAB COM functions or methods belonging to COM objects, the simplest syntax to use is dot syntax. Specify the object name, the dot (.), and then the name of the function or method you are calling. Enclose any input arguments in parentheses after the function name. Specify output arguments to the left of the equals sign:

outputvalue = object.function(arg1, arg2, ...)

For further explanation of command syntax and alternative forms of syntax, see

An Example of Calling Syntax

To work with the example that follows, first create an ActiveX control called mwsamp. (The mwsamp control is built into MATLAB to enable you to work with the examples shown in the COM documentation. The control displays a circle and text label that you can manipulate from MATLAB).

Call actxcontrol to create the mwsamp control. This function returns a handle h that you will need to work further with the control.

h = actxcontrol('mwsamp.mwsampctrl.2', [200 120 200 200]);

Once you have a handle to an object, you can invoke MATLAB functions on the object by referencing it through the handle. This next statement invokes a function, addproperty, on the object using dot syntax. There is one input argument passed in the call, the string 'Position':

```
h.addproperty('Position');
```

An alternative syntax for the same operation begins with the function name and specifies the object handle h as the first argument in the argument list:

```
addproperty(h, 'Position');
```

MATLAB supports both of these command forms.

Specifying Property, Method, and Event Names

You can specify the names of properties and methods using the simple notation

```
handle.propertyname
handle.methodname
```

For example, the mwsamp object has a property called Radius that represents the radius of the circle it draws, and a method called Redraw that redraws the circle. You can get the circle's radius by typing

```
h.Radius
```

You can redraw the circle with

```
h.Redraw
```

More information is provided on this in the following sections, Implicit Syntax for Calling get, set, and invoke and Exceptions to Using Implicit Syntax. Here are a few specific rules regarding how to express property, method, and event names.

Property Names. You can abbreviate the names of properties, as long as you include enough characters in the name to distinguish it from another property. Property names are also case insensitive.

These two statements produce the same result:

```
x = h.Radius
x = h.r
```

Method Names. Method names cannot be abbreviated and must be entered in the correct letter case.

Event Names. Event names are always specified as quoted strings in arguments to a function. Event names must be entered in full but are not sensitive to letter case.

These statements produce the same result:

h.registerevent({'MouseDown' 'mymoused'});
h.registerevent({'MOUSEdown' 'myMOUSEd'});

Implicit Syntax for Calling get, set, and invoke

When calling get, set, or invoke on a COM object, MATLAB provides a simpler syntax that doesn't require an explicit function call. You can use this shortened syntax in all but a few cases (see Exceptions to Using Implicit Syntax).

Continue with the mwsamp control created in the last section and represented by handle h. To get the value of Radius property and assign it to variable x, use the syntax shown here. MATLAB still makes the call to get, but this shortened syntax is somewhat easier to enter:

```
x = h.Radius
x =
    20
```

The same shortened syntax applies when calling the set and invoke functions. Compare these two ways of setting a new radius value for the circle and invoking the Redraw method of mwsamp to display the circle in its enlarged size. The commands on the left call set and invoke explicitly. The commands on the right make implicit calls:

h.set('Radius', 40);              h.Radius = 40;
h.invoke('Redraw');               h.Redraw;

Exceptions to Using Implicit Syntax

There are some conditions under which you must explicitly call get, set, and invoke:

When the property or method is not public
When accessing a property that takes arguments
When operating on a vector of objects

Nonpublic properties and methods. If the property or method you want to access is not provided as a public property or method of the object class, or if it is not in the type library for the control or server, then you must call get, set, or invoke explicitly. For example, the Visible property of an Internet Explorer application is not public and must be accessed using get and set:

h = actxserver('internetexplorer.application');

% This syntax is invalid because 'Visible' is not public.
v = h.Visible
??? No appropriate method or public field Visible for class
   COM.internetexplorer.application.

% You must call the get function explicitly.
v = h.get('Visible')
v =
     1

% The same holds true when setting nonpublic properties.
h.set('Visible', 1);

Public properties and methods are those that are listed in response to the following commands on COM object h:

publicproperties = h.get
publicmethods = h.invoke

Accessing Properties That Take Arguments. Some COM objects have properties that behave somewhat like methods in that they accept input arguments. This is explained fully in the section Properties That Take Arguments. In order to get or set the value of such a property, you must make an explicit call to the get or set function, as shown here. In this example, A1 and B2 are arguments that specify which Range interface to return on the get operation:

eActivesheetRange = e.Activesheet.get('Range', 'A1', 'B2')
eActivesheetRange =
   Interface.Microsoft_Excel_5.0_Object_Library.Range

Operating on a Vector of Objects. If you operate on a vector of objects, (see Get and Set on a Vector of Objects), you must call get and set explicitly to access properties.

This example creates a vector of handles to two Microsoft Calendar objects. It then modifies the Day property of both objects in one operation by invoking set on the vector. Explicit calls to get and set are required:

h1 = actxcontrol('mscal.calendar', [0 200 250 200]);
h2 = actxcontrol('mscal.calendar', [250 200 250 200]);
H = [h1 h2];

H.set('Day', 23)
H.get('Day')
ans = 
    [23]
    [23]

This applies only to get and set. You cannot invoke a method on more than one COM object at a time, even if you call invoke explicitly.

Getting Interfaces to the Object Identifying Objects and Interfaces