MATLAB®

Using Object Properties

About Object Properties

You can get the value of a property, and, in some cases, change the value. You also can create 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. They can be abbreviated, as long as the name is unambiguous.

Use these MATLAB functions to work with the properties of a COM object.

In this topic, you can use Microsoft Calendar control to demonstrate these functions. To begin, create the calendar object cal. A figure window opens; leave it open as you try the examples in this topic. Type:

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

Back to Top

Working with Properties

This section covers the following topics:

• Listing Properties and Interfaces

• Getting Property Values

• Abbreviating Property Names

• Getting Multiple Property Values

• Working with Interfaces

Listing Properties and Interfaces

The get function lists all properties and interfaces of the object. The inspect function opens the Property Inspector, which is described in Using the Property Inspector.

Using the previously created calendar object, type:

cal.get

MATLAB displays a list of all available properties and interfaces (the values for your object will be different):

         BackColor: 2147483663
               Day: 13
           DayFont: [1x1 Interface.Microsoft_Forms_2.0_Object_Library.Font]
      DayFontColor: 0
         DayLength: 1
          FirstDay: 7
    GridCellEffect: 1
          GridFont: [1x1 Interface.Microsoft_Forms_2.0_Object_Library.Font]
     GridFontColor: 10485760
    GridLinesColor: 2147483664
             Month: 8
       MonthLength: 1
 ShowDateSelectors: 1
          ShowDays: 1
ShowHorizontalGrid: 1
         ShowTitle: 1
  ShowVerticalGrid: 1
         TitleFont: [1x1 Interface.Microsoft_Forms_2.0_Object_Library.Font]
    TitleFontColor: 10485760
             Value: '8/13/2007'
       ValueIsNull: 0
              Year: 2007

Getting Property Values

In this example, Year is a property and TitleFont is an interface. For information about interfaces, see Working with Interfaces. The following table shows different ways to get the value of the Year property.

MATLAB displays the same value for each of these commands, for example:

myYear =
        2007

Abbreviating Property Names

You can abbreviate property names, as long as the name is unambiguous.

Using the previously created calendar object cal, the command cal.showda is ambiguous because MATLAB cannot distinguish between the properties ShowDateSelectors and ShowDays. The command cal.showdat is unambiguous.

Getting Multiple Property Values

To get values for more than one property using a single command, you must use the get function. The values are returned a cell array. The syntax of this command is:

C = h.get({'prop1', 'prop2', ...});

Using the previously created calendar object, type:

myDate = cal.get({'Day','Month','Year'});
myDate{:}

MATLAB displays the current date, for example:

ans =
    13

ans =
     8

ans =
    2007

Working with Interfaces

The TitleFont interface provides additional functionality for your calendar object. To work with this interface, create a calendar title object calTitle then list its properties. For example, type:

calTitle=cal.TitleFont;
calTitle.get

MATLAB displays the available properties and their current values. For example:

             Name: 'Arial'
             Size: 12
             Bold: 1
           Italic: 0
        Underline: 0
    Strikethrough: 0
           Weight: 700
          Charset: 0

Back to Top

Setting the Value of a Property

This section covers the following topics:

• Command Line Options

• Setting Multiple Property Values

• Setting Values with the Property Inspector

• Using the Property Page

• Using the Control GUI

Command Line Options

You can set property values from the command line using different syntax statements. Working with the previously defined calTitle object, select your calendar figure window and observe the month name as you type the following commands.

After making these changes, type:

calTitle.get

MATLAB displays the updated values:

             Name: 'Times New Roman'
             Size: 30
             Bold: 1
           Italic: 1
        Underline: 1
    Strikethrough: 0
           Weight: 700
          Charset: 0

Setting Multiple Property Values

To change more than one property with one command, you must use the set function. The syntax of this command is:

handle.set('pname1', value1, 'pname2', value2, ...)

For example, observe the month name in your calendar figure window when you type:

calTitle.set('Size',9,'Underline',0,'Italic',0); 

Setting Values with the Property Inspector

You can use the Property Inspector to change values. For information, see Using the Property Inspector.

Using the Property Page

Some controls have a built-in property page. The propedit function gives you access to this page. You can both read and set property values. For example, typing:

cal.propedit

opens the ActiveX Control Properties window. You can experiment with changing values. To save new values, click the Apply button. Depending on what changes you make, type cal.get or cal.titlefont.get to see the new values.

Using the Control GUI

The Microsoft Calendar control provides a GUI for changing values. Select your calendar figure window and observe as you change the month and year from the drop-down lists, and click on a day of the month. To see your changes, at the command line type:

cal.Value

MATLAB displays the updated date, for example:

ans =
 
3/15/2008

Back to Top

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.

This example creates a vector H of handles to four calendar objects.

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

Click on different days on each of the calendars. To see your changes, type:

H.get('Day')

MATLAB displays the day for each calendar. For example:

ans = 
    [20]
    [18]
    [ 8]
    [29]

To change the Day on all four calendars, type:

H.set('Day', 23)

To see the results, type:

H.get('Day')

MATLAB displays:

ans = 
    [23]
    [23]
    [23]
    [23]

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

Back to Top

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

• Setting Enumerated Values

• Setting Enumerated Values with the Property Inspector

Finding All Enumerated Properties

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

For example, create an Excel spreadsheet:

h = actxserver('excel.application');

Type:

h.set

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:

h.get

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:

h.set('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:

handle.set('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, you need to 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 just 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.

Back to Top

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:

h.inspect

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, you must 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 the property accepts enumerated values. Click anywhere in the field on the right to see the values. 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.

Back to Top

Custom Properties

You can create your own properties to 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 new property called Position to it, and assigns the value [200 120] to that property:

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

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

h.get

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 just created and show that it no longer exists, type:

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

MATLAB displays:

ans = 
     Label: 'Label'
    Radius: 20

Back to Top

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

• Exploring the Object

• Exploring Values

• Setting Values

• Completing the Example

An Example

The Excel Activesheet interface is an object that takes input arguments. This interface has a property called Range. To specify Range, you must 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. You must 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:

ws.get('StandardHeight')

MATLAB displays:

ans =
   13.2000

But, if you use this command on Range:

ws.get('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 = ws.get('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:

wsRange.get

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:

e.Quit;
e.delete;

Back to Top

Exploring Your Object

Using Methods