MATLAB®

Exploring Your Object

About Your Object

A COM object has properties, methods, events, and interfaces. Your vendor documentation describes these features, but you can also learn about your object using MATLAB commands.

Back to Top

Exploring Properties

A property is information that is associated with a COM object. This topic shows you how to look at the properties of your object. For detailed information on reading and setting property values, see Using Object Properties.

To see a list of all properties of an object, you can use the get function or the Property Inspector, a GUI provided by MATLAB to display and modify properties.

In this section, we explore a Microsoft Excel object. To begin, create the object myApp:

myApp = actxserver('excel.application');

Listing Properties

The get function lists all properties. For example, from the MATLAB command prompt, type:

myApp.get

MATLAB displays information similar to the following:

     Application: [1x1 Interface.Microsoft_Excel_9.0_
 Object_Library._Application]
         Creator: 'xlCreatorCode'
          Parent: [1x1 Interface.Microsoft_Excel_9.0_
 Object_Library._Application]
      ActiveCell: []
     ActiveChart: [1x50 char]
                :
 OperatingSystem: 'Windows (32-bit) NT 5.01'
OrganizationName: 'The MathWorks'
                :

One property is OrganizationName; its value in this example is The MathWorks.

Using the Property Inspector

The Property Inspector opens a new window showing the object's properties. This topic explains how to open it. For detailed information, see Using the Property Inspector.

You can open the Property Inspector using either of these methods:

• Call the inspect function from the MATLAB command line.

• Double-click the object in the MATLAB Workspace browser.

For example, type:

myApp.inspect

The Inspector window opens.

Scroll down until you see the OrganizationName property. It should be the same value the get function returned; in this case, The MathWorks.

Back to Top

Exploring Methods

A method is a procedure you call to perform a specific action on the COM object. This topic shows you how to identify methods belonging to your object. For detailed information, see Using Methods.

To see a list of all methods supported by an object, use the methods and invoke functions. Alternatively, you can use the methodsview function, which displays the methods in a separate window.

In this section, we explore a Microsoft Calendar object. To create the object cal, type:

cal = actxcontrol('mscal.calendar', [0 0 400 400]);

Listing Methods

The methods and invoke functions return a list of the names of all methods supported by the object, including MATLAB COM functions you can use on the object. For example, type:

cal.methods

MATLAB displays:

Methods for class COM.mscal_calendar:

AboutBox         PreviousMonth    constructorargs  invoke           send
NextDay          PreviousWeek     delete           load             set 
NextMonth        PreviousYear     deleteproperty   move             
NextWeek         Refresh          events           propedit         
NextYear         Today            get              release          
PreviousDay      addproperty      interfaces       save  

When you use the -full switch, MATLAB also lists the input and output arguments for each method. For example, type:

cal.methods('-full')

MATLAB displays:

Methods for class COM.mscal.calendar:

HRESULT AboutBox(handle)
HRESULT NextDay(handle)
HRESULT NextMonth(handle)
HRESULT NextWeek(handle)
        :
MATLAB array move(handle, MATLAB array)
propedit(handle)
release(handle, MATLAB array)
save(handle, string)

The invoke function displays similar information for methods supported by the object. For example, type:

cal.invoke

MATLAB displays:

    NextDay = HRESULT NextDay(handle)
    NextMonth = HRESULT NextMonth(handle)
    NextWeek = HRESULT NextWeek(handle)
    NextYear = HRESULT NextYear(handle)
    PreviousDay = HRESULT PreviousDay(handle)
    PreviousMonth = HRESULT PreviousMonth(handle)
    PreviousWeek = HRESULT PreviousWeek(handle)
    PreviousYear = HRESULT PreviousYear(handle)
    Refresh = HRESULT Refresh(handle)
    Today = HRESULT Today(handle)
    AboutBox = HRESULT AboutBox(handle)

Using methodsview

The methodsview function opens a new window with an easy-to-read display of all methods supported by the object, along with related fields of information, as described in the reference page. For example, type:

cal.methodsview

MATLAB displays:

If the Return Type field for a method is blank, the method returns void.

Back to Top

Exploring Events

An event is typically a user-initiated action that takes place in a server application, which often requires a reaction from the client. For example, a user clicking the mouse at a particular location in a server interface window might require the client take some action in response. When an event is fired, the server communicates this occurrence to the client. If the client is listening for this particular type of event, it responds by executing a routine called an event handler.

This topic shows you how to identify events available to your object. For detailed information, see Using Events. For information on event handlers, see Writing Event Handlers.

Use the events function to list all events known to the control or server and use the eventlisteners function to list only registered events.

In this section, we use the Microsoft Internet Explorer Web browser. To begin, create the object myNet:

myNet = actxserver('internetexplorer.application');

Listing Server Events

Type:

myNet.events

MATLAB displays event information similar to:

        :
StatusTextChange = void StatusTextChange(string Text)
ProgressChange = void ProgressChange(int32 Progress,int32 ProgressMax)
CommandStateChange = void CommandStateChange(int32 Command,bool Enable)
        :  

Listing Registered Events

No events are registered at this time. If you type:

myNet.eventlisteners

MATLAB displays:

ans = 
      {}

Back to Top

Exploring Interfaces

An interface is a set of related functions used to access a COM object's data. When you create a COM object using the actxserver or actxcontrol functions, MATLAB returns a handle to an interface. You use the get and interfaces functions to see other interfaces implemented by your object.

In this section, we explore an Excel object. To begin, create the object e:

e = actxserver('excel.application');

Additional Interfaces

Components often provide additional interfaces, based on IDispatch. To see these interfaces, type:

e.get

MATLAB displays information similar to:

    Application: [1x1 Interface.Microsoft_Excel_11.0_Object_Library._Application]
        Creator: 'xlCreatorCode'
         Parent: [1x1 Interface.Microsoft_Excel_11.0_Object_Library._Application]
     ActiveCell: []
    ActiveChart: [1x50 char]
               :
      Workbooks: [1x1  Interface.Microsoft_Excel_11.0_Object_Library.Workbooks]
               :

In this example, Workbooks is an interface. To explore the Workbooks interface, type:

w = e.Workbooks;

To see its properties, type:

w.get

MATLAB displays:

    Application: [1x1 Interface.Microsoft_Excel_11.0_Object_Library._Application]
        Creator: 'xlCreatorCode'
         Parent: [1x1 Interface.Microsoft_Excel_11.0_Object_Library._Application]
          Count: 0

To see its methods, type:

w.invoke

MATLAB displays:

	Add = handle Add(handle, Variant(Optional))
	Close = void Close(handle)
	Item = handle Item(handle, Variant)
	Open = handle Open(handle, string, Variant(Optional))
	OpenText = void OpenText(handle, string, Variant(Optional))
	OpenDatabase = handle OpenDatabase(handle, string, Variant(Optional))
	CheckOut = void CheckOut(handle, string)
	CanCheckOut = bool CanCheckOut(handle, string)
	OpenXML = handle OpenXML(handle, string, Variant(Optional))

Back to Top

Identifying Objects and Interfaces

You can get additional information about a control or server using the following functions.

This example creates a COM object in an Automation server running the Excel application, giving it the handle e, and a Workbooks interface to the object, with handle w.

e = actxserver('excel.application');
w = e.Workbooks;

Use the iscom function to see if e is a handle to a COM object:

e.iscom
ans =
     1

Use the isa function to test e against a known class name:

e.isa('COM.excel_application')
ans =
     1

Use isinterface to see if w is a handle to a COM interface:

w.isinterface
ans =
     1

Use the class function to find out the class of variable w:

w.class
ans =
   Interface.Microsoft_Excel_11.0_Object_Library.Workbooks

To see if UsableWidth is a property of e, use isprop:

e.isprop('UsableWidth')
ans =
     1

To see if SaveWorkspace is a method of e, use ismethod:

e.ismethod('SaveWorkspace')
ans =
     1

Back to Top

Creating COM Objects

Using Object Properties