External Interfaces/API

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
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');
  
  get(h)
  ans = 
     Application: [1x1 Interface.excel.application.Application]
         Creator: 'xlCreatorCode'
          Parent: [1x1 Interface.excel.application.Parent]
      ActiveCell: []
     ActiveChart: [1x50 char]
   ActivePrinter: '\\PRINTERS\Kunkel on Ne01:'
     ActiveSheet: []
    ActiveWindow: []
          AddIns: [1x1 Interface.excel.application.AddIns]
           :
           :
  

To return the value of just one property, specify the property name in the argument list:

• get(h, 'OrganizationName')
  ans =
     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:

• get(h, 'org')
  ans =
     The MathWorks, Inc.
  

Setting the Value of a Property

Use set to change the value of a property, specifying both the property name and new value:

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

You can change more than one property at a time using this syntax:

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

For example, to set the Label and Radius fields of COM object h, use

• set(h, 'Label', 'Click to fire event', 'Radius', 40);
  

Get and Set on Multiple 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];
  
  set(H, 'Day', 23)
  get(H, 'Day')
  ans = 
      [23]
      [23]
      [23]
      [23]
  

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

• get(h)
                       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:

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

To set the value of a property to an enumerated type, use set with the property name and enumerated value. (You can also set these properties to an integer value.) Note that you can abbreviate the enumeration string, as in the second line shown below. You must use enough letters in the string to make it unambiguous. The enumeration string is also case-insensitive.

Either of the following commands sets the Cursor to a NorthwestArrow type:

• set(h, 'Cursor', 'xlNorthwestArrow')
  set(h, 'Cursor', 'xln')
  

Use get with the property name argument to read the value of the property you have just set:

• get(h, 'Cursor')
  ans =
     xlNorthwestArrow
  

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 Workspace Browser

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

Now check this field in the MATLAB command window and confirm that it has changed:

• get(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 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, xlNorthwestArrow, is indicated by a checkmark.

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:

• addproperty(h, 'propertyName')
  

This example creates the mwsamp 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]);
  addproperty(h, 'Position');
  set(h, 'Position', [200 120]);
  

Use get to list all properties of control, h. You see that the new Position property has been added:

• get(h)
  ans = 
       Label: 'Label'
      Radius: 20
    Position: [200 120]
  
  get(h, 'Position')
  ans =
     200   120
  

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

• deleteproperty(h, 'propertyName')
  

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

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

Creating COM Objects

Invoking Methods