Contents

Use Object Properties

About Object Properties

You can get the value of a property, and, in some cases, change the value. You also can add custom properties. This topic explains how to do these tasks. If you only want to view your object's properties, see Exploring Properties for basic information.

Property names are not case-sensitive. You can abbreviate them as long as the name is unambiguous.

To work with the properties of a COM object, use these MATLAB® functions.

FunctionDescription

addproperty

Add a custom property to a COM object

deleteproperty

Remove a custom property from a COM object

get

List one or more properties and their values

inspect

Display graphical interface to list and modify property values

isprop

Determine if an item is a property of a COM object

propedit

Display the control's built-in property page

set

Set the value of one or more properties

Working with Multiple Objects

You can use the get and set functions on more than one object at a time by creating a vector of object handles and using these commands on the vector.

    Note:   To get or set values for multiple objects, use the get and set functions explicitly. You can only use dot syntax, for example H.Day, on scalar objects.

Using Enumerated Values for Properties

Enumeration makes examining and changing properties easier because each possible value for the property is given a string to represent it. For example, one of the values for the DefaultSaveFormat property in a Microsoft® Excel® spreadsheet is xlUnicodeText. This is easier to remember than a numeric value like 57.

This section covers the following topics:

Finding All Enumerated Properties

The get and set functions support enumerated values for properties for those applications that provide them. To see which properties use enumerated types, use the set function.

For example, create an instance of an Excel spreadsheet:

h = actxserver('Excel.Application');

Type:

set(h)

MATLAB displays:

ans = 
              Creator: {'xlCreatorCode'}
     ConstrainNumeric: {}
        CopyObjectsWithCells: {}
               Cursor: {4x1 cell}
          CutCopyMode: {2x1 cell}
                     .
                     .

MATLAB displays the properties that accept enumerated types as nonempty cell arrays. In this example, Cursor and CutCopyMode accept a choice of settings. Properties for which there is only one possible setting are displayed as a one-row cell array (see Creator, above).

Use the get function to display the current values of these properties. Type:

get(h)

MATLAB displays information such as:

              Creator: 'xlCreatorCode'
     ConstrainNumeric: 0
 CopyObjectsWithCells: 1
               Cursor: 'xlDefault'
          CutCopyMode: ''
                     .
                     .

Setting Enumerated Values

To list all possible enumerated values for a specific property, use set with the property name argument. The output is a cell array of strings, one string for each possible setting of the specified property:

set(h,'Cursor')
ans = 
    'xlIBeam'
    'xlDefault'
    'xlNorthwestArrow'
    'xlWait'

To set the value of a property, assign the enumerated value to the property name:

handle.property = 'enumeratedvalue';

You can also use the set function with the property name and enumerated value:

set(handle,'property','enumeratedvalue');

You have a choice of using the enumeration or its equivalent numeric value. You can abbreviate the enumeration string, as in the third line of the following example, as long as you use enough letters in the string to make it unambiguous. Enumeration strings are not case-sensitive.

Make the Excel spreadsheet window visible, and then change the cursor from the MATLAB client. To see how the cursor has changed, click the spreadsheet window. Either of the following assignments to h.Cursor sets the cursor to the Wait (hourglass) type:

h.Visible = 1;

h.Cursor = 'xlWait'
h.Cursor = 'xlw'           % Abbreviated form of xlWait

Read the value of the Cursor property you have set:

h.Cursor
ans =
   xlWait

Setting Enumerated Values with the Property Inspector

You can also set enumerated values using the Property Inspector. To learn how to use this feature, see Using the Property Inspector on Enumerated Values.

Using the Property Inspector

The Property Inspector enables you to access the properties of COM objects. To open the Property Inspector, use the inspect function from the MATLAB command line or double-click the object in the MATLAB Workspace browser.

For example, create a server object running the Excel program. Then set the object's DefaultFilePath property to C:\ExcelWork:

h = actxserver('Excel.Application');
h.DefaultFilePath = 'C:\ExcelWork';

Next call the inspect function to display a new window showing the server object's properties:

inspect(h)

Scroll down until you see the DefaultFilePath property that you just changed. It should read C:\ExcelWork.

Using the Property Inspector, change DefaultFilePath once more, this time to MyWorkDirectory. To do this, select the value at the right and type the new value.

Now go back to the MATLAB Command Window and confirm that the DefaultFilePath property has changed as expected.

h.DefaultFilePath

MATLAB displays:

ans =

C:\MyWorkDirectory

    Note:   If you modify properties at the MATLAB command line, refresh the Property Inspector window to see the change reflected there. Refresh the Property Inspector window by reinvoking inspect on the object.

Using the Property Inspector on Enumerated Values

A list button next to a property value indicates that the property accepts enumerated values. To see the values, click anywhere in the field on the right. The following figure displays four enumerated values for the Cursor property. The current value xlDefault is displayed in the field next to the property name.

To change the value, use the list button to display the options for that property, and then click the desired value.

Custom Properties

You can add your own custom properties to an instance of a control using the addproperty function. The syntax h.addproperty('propertyName') creates a custom property for control h.

This example creates the mwsamp2 control, adds a property called Position to it, and assigns the value [200 120] to that property:

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

Use the get function to list all properties of control h.

get(h)

You see the new Position property has been added.

ans = 
     Label: 'Label'
    Radius: 20
  Position: [200 120]

Type:

h.Position

MATLAB displays:

ans =
   200   120

To remove custom properties from a control, use the deleteproperty function. The syntax h.deleteproperty('propertyName') deletes propertyName from h. For example, to delete the Position property that you created and show that it no longer exists, type:

deleteproperty(h,'Position');
get(h)

MATLAB displays:

ans = 
     Label: 'Label'
    Radius: 20

Properties That Take Arguments

Some COM objects have properties that accept input arguments. Internally, MATLAB handles these properties as methods, which means you need to use the invoke function (not get) to view the property.

To explain how this works, look at a spreadsheet property that takes input arguments. This example is taken from Using a MATLAB Application as an Automation Client.

An Example

The Excel Activesheet interface is an object that takes input arguments. This interface has a property called Range. To specify Range, pass in range coordinates.

To begin, create the Worksheet object ws:

e = actxserver('Excel.Application');
e.Workbooks.Add;
ws = e.Activesheet; 

The ws object is an interface:

ws =
    Interface.Microsoft_Excel_11.0_Object_Library._Worksheet

Exploring the Object

You can explore the ws object using the get and invoke functions. (When you type the following commands, MATLAB displays long lists of properties and methods.) When you type ws.get, the property Range is not in the list. Use the invoke function to find Range.

ws.invoke

MATLAB displays (in part):

           :
Range = handle Range(handle, Variant, Variant(Optional))
           :

Exploring Values

The get function also displays the value of a property. For example, one of the properties listed by get is StandardHeight. To see its value, type:

get(ws,'StandardHeight')

MATLAB displays:

ans =
   13.2000

But, if you use this command on Range:

get(ws,'Range');

MATLAB displays:

Invoke Error: Incorrect number of arguments

Consulting Microsoft reference documentation, you find Range requires arguments A1:B2, which specify a rectangular region of the spreadsheet.

If you type:

wsRange = get(ws,'Range', 'A1:B2')

MATLAB shows that wsRange is an interface:

wsRange =
    Interface.Microsoft_Excel_11.0_Object_Library.Range

You find the properties by typing:

get(wsRange)

From the lengthy list MATLAB displays, look at the Value property:

           :
      Value: {2x2 cell}
           :

To see the current value, type:

wsRange.Value

MATLAB displays:

ans = 
    [NaN]    [NaN]
    [NaN]    [NaN]

Setting Values

To copy a MATLAB array A into the wsRange object, type:

A = [1 2; 3 4];
wsRange.Value = A;
wsRange.Value

MATLAB displays:

ans = 
    [1]    [2]
    [3]    [4]

Completing the Example

When you are finished with this example, type:

e.Workbook.Close;

The Excel Close method expects a Yes/No response about saving the workbook. To terminate and remove the server object, type:

Quit(e);
delete(e);
Was this topic helpful?