MATLAB®

Using Methods

About Methods

You execute, or invoke, COM functions or methods belonging to COM objects. This topic explains how to determine what methods are available for an object and how to invoke them. If you only want to view your object's methods, see Exploring Methods for basic information.

Method names are case sensitive. You cannot abbreviate them.

Use the following MATLAB^® functions to work with the methods of a COM object.

Back to Top

Getting Method Information

You can see what methods are supported by a COM object using the methodsview, methods, or invoke functions. Each function presents specific information, as described in the following table.

In this topic, you can use the built-in MATLAB control mwsamp to try out these functions. To create the control object sampObj, type:

sampObj = actxcontrol('mwsamp.mwsampctrl.1', [0 0 500 500]);

The control opens a figure window and displays a circle and text label.

Using invoke

The invoke function returns a cell array containing a list of all methods supported by the object, along with the signatures for these methods. This list is not sorted alphabetically.

For example, type:

sampObj.invoke

MATLAB displays:

    Beep = void Beep(handle)
    Redraw = void Redraw(handle)
    GetVariantArray = Variant GetVariantArray(handle)
    GetIDispatch = handle GetIDispatch(handle)
    GetBSTR = string GetBSTR(handle)
    GetI4Array = Variant GetI4Array(handle)
    GetBSTRArray = Variant GetBSTRArray(handle)
    GetI4 = int32 GetI4(handle)
    GetR8 = double GetR8(handle)
    GetR8Array = Variant GetR8Array(handle)
    FireClickEvent = void FireClickEvent(handle)
    GetVariantVector = Variant GetVariantVector(handle)
    GetR8Vector = Variant GetR8Vector(handle)
    GetI4Vector = Variant GetI4Vector(handle)
    SetBSTRArray = Variant SetBSTRArray(handle, Variant)
    SetI4 = int32 SetI4(handle, int32)
    SetI4Vector = Variant SetI4Vector(handle, Variant)
    SetI4Array = Variant SetI4Array(handle, Variant)
    SetR8 = double SetR8(handle, double)
    SetR8Vector = Variant SetR8Vector(handle, Variant)
    SetR8Array = Variant SetR8Array(handle, Variant)
    SetBSTR = string SetBSTR(handle, string)
    AboutBox = void AboutBox(handle)

Using methods

The methods function returns the names of all methods for the object, including MATLAB COM functions that you can use on the object. There is no information about how to call the method. This list is sorted alphabetically; however, method names with initial caps are listed before methods with lowercase names.

For example, type:

sampObj.methods

MATLAB displays:

Methods for class COM.mwsamp_mwsampctrl_1:
 
AboutBox          GetVariantVector  deleteproperty    
Beep              Redraw            events            
FireClickEvent    SetBSTR           get               
GetBSTR           SetBSTRArray      interfaces        
GetBSTRArray      SetI4             invoke            
GetI4             SetI4Array        load              
GetI4Array        SetI4Vector       move              
GetI4Vector       SetR8             propedit          
GetIDispatch      SetR8Array        release           
GetR8             SetR8Vector       save              
GetR8Array        addproperty       send              
GetR8Vector       constructorargs   set               
GetVariantArray   delete     

Examples of MATLAB COM functions are addproperty and set. Although the list is sorted alphabetically, uppercase function names are listed first. For example, Redraw appears before get.

Using methods with -full

When you include the -full qualifier in the methods function, MATLAB also specifies the input and output arguments for each method. For an overloaded method, the returned array includes a description of each of its signatures.

Type:

sampObj.methods('-full')

MATLAB displays:

Methods for class COM.mwsamp_mwsampctrl_1:
 
AboutBox(handle)
Beep(handle)
FireClickEvent(handle)
string GetBSTR(handle)
Variant GetBSTRArray(handle)
int32 GetI4(handle)
Variant GetI4Array(handle)
Variant GetI4Vector(handle)
handle GetIDispatch(handle)
double GetR8(handle)
Variant GetR8Array(handle)
Variant GetR8Vector(handle)
Variant GetVariantArray(handle)
Variant GetVariantVector(handle)
Redraw(handle)
string SetBSTR(handle, string)
Variant SetBSTRArray(handle, Variant)
int32 SetI4(handle, int32)
Variant SetI4Array(handle, Variant)
Variant SetI4Vector(handle, Variant)
double SetR8(handle, double)
Variant SetR8Array(handle, Variant)
Variant SetR8Vector(handle, Variant)
addproperty(handle, string)
MATLAB array constructorargs(handle)
delete(handle, MATLAB array)
deleteproperty(handle, string)
MATLAB array events(handle, MATLAB array)
MATLAB array get(handle)
MATLAB array get(handle, MATLAB array, MATLAB array)
MATLAB array get(handle vector, MATLAB array, MATLAB array)
MATLAB array interfaces(handle)
MATLAB array invoke(handle)
MATLAB array invoke(handle, string, MATLAB array)
load(handle, string)
MATLAB array move(handle, MATLAB array)
MATLAB array move(handle)
propedit(handle)
release(handle, MATLAB array)
save(handle, string)
MATLAB array send(handle) 
MATLAB array set(handle vector, MATLAB array, MATLAB array)
MATLAB array set(handle, MATLAB array, MATLAB array)
MATLAB array set(handle)

In the mwsamp control, get is an overloaded function, and MATLAB displays each of its signatures.

Using methodsview

The methodsview function opens a new window with an easy-to-read display of all methods supported by the object. It displays the same information as the handle.methods('-full') command.

For example, type:

sampObj.methodsview

MATLAB opens a window showing (in part):

Back to Top

Invoking Methods on an Object

This section covers the following topics:

• Calling Syntax

• Input and Output Arguments

• Example Using mwsamp

Calling Syntax

To invoke a method on a COM object, use dot syntax, also called dot notation. This is a simpler syntax that doesn't require an explicit function call. For situations where you cannot use this syntax, see Exceptions to Using Implicit Syntax.

The format of a dot syntax statement is:

outputvalue = object.methodname('arg1', 'arg2', ...);

Specify the object name, the dot (.), and the name of the function or method. Enclose any input arguments in parentheses after the function name. Specify output arguments to the left of the equal sign.

Dot syntax is a special case of calling by method name. An alternative syntax for calling by method name is:

outputvalue = methodname(object, 'arg1', 'arg2', ...);

MATLAB also supports the following explicit syntax statements:

outputvalue = invoke(object, 'methodname', 'arg1', 'arg2', ...);
outputvalue = object.invoke('methodname', 'arg1', 'arg2', ...);

Input and Output Arguments

The methodsview output window and the methods -full command show what data types to use for input and output arguments. For information about reading a signature statement and using input and output arguments, see Handling COM Data in MATLAB^® Software.

Example Using mwsamp

The following example creates three circles in a MATLAB figure window. It shows different commands you can use to change the circles.

To create the COM objects, type:

h1 = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200]);
h2 = actxcontrol('mwsamp.mwsampctrl.2', [200 200 200 200]);
h3 = actxcontrol('mwsamp.mwsampctrl.2', [400 0 200 200]);

You can explicitly change the size of and redraw a circle using the commands:

h1.set('Radius', 100);
invoke(h1, 'Redraw')

You can implicitly change the size using:

h2.Radius = 50;
h3.Radius = 25;

To redraw the circles using method name syntax, type:

Redraw(h2)
h3.Redraw

Close the figure window.

Back to Top

Exceptions to Using Implicit Syntax

You cannot use dot syntax and must explicitly call the get, set, and invoke functions under the following conditions:

• Accessing Nonpublic Properties and Methods

• Accessing Properties That Take Arguments

• Operating on a Vector of Objects

Accessing Nonpublic Properties and Methods

If the property or method you want to access is not a public property or method of the object class, or if it is not in the type library for the control or server, you must call get, set, or invoke explicitly.

If you use a syntax statement of the following format for a nonpublic property aProperty:

x = handle.aProperty

MATLAB displays a message such as:

??? No appropriate method or public field aProperty for class
   COM.aClass.application.

Instead, you must use the get function explicitly:

x = handle.get('aProperty')

To find public properties and methods on COM object h, type:

publicproperties = h.get
publicmethods = h.invoke

Accessing Properties That Take Arguments

Some COM objects have properties that accept input arguments. MATLAB treats these properties like methods. For an example of this feature, see Properties That Take Arguments.

To get or set the value of such a property, you must make an explicit call to the get or set function, as shown in the following example. 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');

Operating on a Vector of Objects

If you operate on a vector of objects you must call get or set explicitly to access properties. For an example, see Working with Multiple Objects. This applies only to the get and set functions. You cannot invoke a method on multiple COM objects, even if you call the invoke function explicitly.

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, as follows:

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

Observe the figure window as you type:

H.set('Day', 23)

To verify, type:

H.get('Day')

MATLAB displays:

ans = 
    [23]
    [23]

Close the figure window.

Back to Top

Specifying Enumerated Parameters

Enumeration is a way of assigning a descriptive name to a symbolic value.

For example, the input to a function is the atomic number of an element. It is easier to remember an element name than the atomic number. Using enumeration, you can pass the word 'arsenic' in place of the value 33.

MATLAB supports enumeration for parameters passed to methods under the condition that the type library in use reports the parameter as ENUM, and only as ENUM.

Note    MATLAB does not support enumeration for any parameter that the type library reports as both ENUM and Optional.

In this example, the Location method accepts the enumerated value 'xlLocationAsObject'.

Create a Microsoft^® Excel^® Chart object:

e = actxserver('Excel.Application');

% Insert a new workbook.
Workbook = e.Workbooks.Add;
e.Visible = 1;
Sheets = e.ActiveWorkBook.Sheets;

% Get a handle to the active sheet.
Activesheet = e.Activesheet;

%Add a Chart
Charts = Workbook.Charts;
Chart = Charts.Add;

To see what type of chart you can create, type:

Chart.inspect

Scroll through the Property Inspector window to find ChartType. Click the drop-down arrow to see all possible ChartType values. This is an enumerated list. Close the property inspector.

To programmatically set the ChartType, type:

% Set chart type to be a line plot.
Chart.ChartType = 'xlXYScatterLines'
C1 = Chart.Location('xlLocationAsObject', 'Sheet1');

Close the Excel^® spreadsheet.

Back to Top

Optional Input Arguments

When calling a method that takes optional input arguments, you can skip any optional argument by specifying an empty array ([]) in its place. The syntax for calling a method with second argument arg2 not specified is:

handle.methodname(arg1, [], arg3);

The following example uses the Add method to add new sheets to an Excel workbook. The Add method has the following optional input arguments:

• Before — The sheet before which to add the new sheet

• After — The sheet after which to add the new sheet

• Count — The total number of sheets to add

• Type — The type of sheet to add

The following code creates a workbook with the default number of worksheets, and inserts an additional sheet after Sheet 1. To do this, call Add with the second argument, After. You omit the first argument, Before, by using [] in its place, as shown in the last line of the example:

% Open an Excel Server.
e = actxserver('excel.application');

% Insert a new workbook.
e.Workbooks.Add;
e.Visible = 1;

% Get the Active Workbook with three sheets.
eSheets = e.ActiveWorkbook.Sheets;

% Add a new sheet after eSheet1.
eSheet1 = eSheets.Item(1);
eNewSheet = eSheets.Add([], eSheet1);

Close the Excel spreadsheet.

Back to Top

Returning Multiple Output Arguments

If you know that a server function supports multiple outputs, you can return any or all of those outputs to a MATLAB client.

The following syntax shows a server function functionname called by the MATLAB client. retval is the function's first output argument, or return value. The other output arguments are out1, out2, ....

[retval out1 out2 ...] = handle.functionname(in1, in2, ...);

MATLAB makes use of the pass-by-reference capabilities in COM to implement this feature. Note that pass-by-reference is a COM feature; MATLAB does not support pass-by-reference.

Back to Top

Argument Callouts in Error Messages

When a MATLAB client sends a command with an invalid argument to a COM server application, the server sends back an error message, similar to the following, identifying the invalid argument.

??? Error: Type mismatch, argument 3.

If you do not use the dot syntax format, be careful interpreting the argument number in this type of message.

For example, using dot syntax, if you type:

handle.PutFullMatrix('a', 'base', 7, [5 8]);

MATLAB displays:

??? Error: Type mismatch, argument 3.

In this case, the argument, 7, is invalid because PutFullMatrix expects the third argument to be an array data type, not a scalar. In this example, the error message identifies 7 as argument 3.

However, if you use the syntax:

PutFullMatrix(handle, 'a', 'base', 7, [5 8]);

MATLAB displays:

??? Error: Type mismatch, argument 3.

In this call to the PutFullMatrix function, 7 is argument four. However, the COM server does not receive the first argument. The handle argument merely identifies the server. It does not get passed to the server. This means the server sees 'a' as the first argument, and the invalid argument, 7, as the third.

If you use the syntax:

invoke(handle, 'PutFullMatrix', 'a', 'base', 7, [5 8]);

MATLAB again displays:

??? Error: Type mismatch, argument 3.

As in the previous example, MATLAB uses the handle argument to identify the server. The 'PutFullMatrix' argument is also only used by MATLAB. While the invalid argument is the fifth argument in your MATLAB command, the server still identifies it as argument 3, because the first two arguments are not seen by the server.

Back to Top

Using Object Properties

Using Events