External Interfaces

Object Properties

This section covers the following topics describing how to set and get the value of a property, and how to create custom properties:

• Functions for Working with Object Properties
• Getting the Value of a Property
• Setting the Value of a Property
• Get and Set on a Vector of Objects
• Using Enumerated Values for Properties
• Using the Property Inspector
• Custom Properties

Functions for Working with Object Properties

Use these MATLAB functions to get, set, and modify the properties of a COM object or interface, or to add your own custom properties.

Function	Description
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 a property on an interface

Getting the Value of a Property

The get function returns information on one or more properties belonging to a COM object or interface. Use get with only the handle argument, and MATLAB returns a list of all properties for the object, and their values:

• h = actxserver('excel.application');
  
  h.get
      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]
                   .
                   .
  

To return the value of just one property, specify the object handle and property name using dot syntax:

• company = h.OrganizationName
  company =
     The MathWorks, Inc.
  

Property names are not case sensitive and may also be abbreviated, as long as you include enough letters in the name to make it unambiguous. You can use 'org' in place of the full 'OrganizationName' property name used above:

• company = h.org
  company =
     The MathWorks, Inc.
  

You can also use the get function, without dot syntax, for this same purpose:

• filepath = h.get('DefaultFilePath')
  filepath =
     H:\Documents
  

Getting Multiple Property Values.   To get more than one property with just one command, you must use the get function, specifying the property names in a cell array of strings. This returns a cell array containing a column for each property value:

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

For example, to get the DefaultFilePath and UserName property values for COM object h, use

• h = actxserver('excel.application');
  
  C = h.get({'DefaultFilePath', 'UserName'});
  C{:}
  ans =
     H:\Documents
  ans =
     C. Coolidge
  

Setting the Value of a Property

The simplest way to set or modify the value of a property is just to use an assignment statement like that shown in the second line below. This sets the value of the DefaultFilePath property for object h to 'C:\ExcelWork':

• h = actxserver('excel.application');
  h.DefaultFilePath = 'C:\ExcelWork';
  

You can also use the set function, without dot syntax, for this same purpose. Specify both the property name and new value as input arguments to set:

• h.set('DefaultFilePath', 'C:\ExcelWork');
  

Setting Multiple Property Values.   To change more than one property with just one command, you must use the set function:

• h.set('prop1', 'value1', 'prop2', 'value2', ...);
  

For example, to set the DefaultFilePath and UserName fields of COM object h, use

• h = actxserver('excel.application');
  h.set('DefaultFilePath', 'C:\ExcelWork', ...
     'UserName', 'H. Hoover');
  

Properties That Take Arguments

Some COM objects have properties that behave somewhat like methods in that they accept input arguments. On a get or set operation, the value they end up getting or setting depends on the arguments you pass in.

The Activesheet interface of a Microsoft Excel application running as a COM server is one example. This interface has a property called Range, which is actually another interface. In order to get the correct Range interface, you must pass in specific range coordinates.

The first line of code shown here (taken from the example in Using MATLAB as an Automation Client) returns a specific Range interface. Arguments A1 and B2 specify which rectangular region of the spreadsheet to get the interface for:

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

To get or set this type of property, use the get or set function as shown above for the Range property. Enter the input arguments in the parentheses following the property name:

• handle.get(propertyname, arg1, arg2, ...);
  

In some ways, MATLAB handles these properties internally as though they were actually methods. The most important difference is that you need to use invoke, not get, to view the property:

• e.Activesheet.invoke
             :
     Range = handle Range(handle, Variant, Variant(Optional))
             :
  

Get and Set on a Vector of Objects

You can use the get and set functions on more than one object at a time by putting the object handles into a vector and then operating on the vector.

This example creates a vector of handles to four Microsoft Calendar objects. It then modifies the Day property of all the objects in one operation by invoking set on the vector:

• 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];
  
  H.set('Day', 23)
  H.get('Day')
  ans = 
      [23]
      [23]
      [23]
      [23]
  

Note    To get or set values for multiple objects, you must use the get and set functions explicitly. Syntax like H.Day is only supported for 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 an Excel application is xlUnicodeText. This is much easier to remember than a numeric value like 57.

Finding All Enumerated Properties.   The MATLAB COM 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 with just the object handle argument:

• h = actxserver('excel.application');
  
  h.set
  ans = 
                       Creator: {'xlCreatorCode'}
              ConstrainNumeric: {}
          CopyObjectsWithCells: {}
                        Cursor: {4x1 cell}
                   CutCopyMode: {2x1 cell}
                           .
                           .
  

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

To display the current values of these properties, use get with just the object handle argument:

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

Setting an Enumerated Value.   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 to an enumerated type, simply 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 shown below, as long as you use enough letters in the string to make it unambiguous. Enumeration strings are also case insensitive.

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 on 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
  

Using the Property Inspector

MATLAB also provides a graphical user interface to display and modify properties. You can open the Property Inspector by either of these two methods:

• Invoke the inspect function from the MATLAB command line
• Double-click on the object in the MATLAB Workspace browser

Create a server object running Microsoft Excel, and then set the object's DefaultFilePath property to 'C:\ExcelWork':

• h = actxserver('excel.application');
  h.DefaultFilePath = 'C:\ExcelWork';
  

Now 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 C:\MyWorkDirectory. To do this, click on the property name at the left and then enter the new value at the right.

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

• h.DefaultFilePath
  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.   Properties that accept enumerated values are marked by a button in the Property Inspector window. The window shown below displays four enumerated values for the Cursor property. The current value will be indicated by a check mark.

To change a property's value using the Property Inspector, simply click on the button to display the options for that property, and then click on the desired value.

Custom Properties

You can attach your own properties to a control using the addproperty function. The syntax shown here creates a custom property for control, h:

• h.addproperty('propertyName')
  

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 get to list all properties of control, h. You see that the new Position property has been added:

• h.get
  ans = 
       Label: 'Label'
      Radius: 20
    Position: [200 120]
  
  h.Position
  ans =
     200   120
  

To remove custom properties from a control, use deleteproperty with the following syntax:

• h.deleteproperty('propertyName')
  

For example, delete the Position property that you just created, and use get to show that it no longer exists:

• h.deleteproperty('Position');
  
  h.get
       Label: 'Label'
      Radius: 20
  

Invoking Methods

Control and Server Events

© 1994-2005 The MathWorks, Inc.