Newsletters - MATLAB Digest

Introducing New ActiveX Features in MATLAB 6.5

by Nausheen Moulana

With the release of MATLAB 6.5, you can now incorporate ActiveX controls¹ as elements of your graphical user interfaces (GUI) more easily. Reusable component program objects, ActiveX controls are widely available on the Web -some at no cost -and can be seamlessly integrated into your MATLAB GUIs instead of developing them yourself.

This article details the new properties, methods, events, and lifecycle management of objects representing ActiveX controls in MATLAB 6.5.

---

All the features mentioned in this article apply to ActiveX servers² with the exception of events, which are currently not supported for servers.

---

Robust Memory Management

Prior versions of MATLAB required you to use the release and delete methods to reclaim memory used by interfaces and controls. Failure to invoke these functions resulted in a memory leak when the variable representing the ActiveX control was reassigned or went out of scope. With MATLAB 6.5, variables representing controls and interfaces are destroyed automatically when they are reassigned or go out of scope, eliminating the potential memory leak. Also, in MATLAB 6.5, when the figure window that contains the control is disposed, the object representing the control and all of its interfaces in memory are released.

Enhanced Property Support

MATLAB 6.5 also includes enhancements for accessing, modifying, and customizing the ActiveX control properties, including custom properties, enumerated values, and vectorized access and modification:

Custom Properties

Every ActiveX control has properties that are implemented by the control itself, called default properties. In addition to these properties, with MATLAB 6.5, you can add your own properties once the object is created. These properties, called custom or runtime properties, let you store any data in them and delete them. As with default properties, you can use the set and get methods of the object to assign a value to and query the value of custom properties.

You create custom properties using the new addproperty method of the ActiveX control object. Here is an example using the mwsamp ActiveX control in MATLAB to add a new property called Position and set its value to [200 120]:

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

Using the get method, you can 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

You can remove the custom property using the new deleteproperty method of the ActiveX control object. The following code demonstrates how to remove the Position property and verify that it no longer exists:

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

Note: The deleteproperty method deletes only custom properties (i.e., those created with addproperty); it does not delete a control's default properties.

Enumerated Values

You can now use an enumerated string in place of its equivalent numeric value when setting the value of an ActiveX control's property. For example, if the days of the week are represented as a property that supports enumeration, then it is easier to use Monday than its numeric value. Along with improving the readability of the program, enumeration helps you avoid referencing and remembering the numeric values of a property.

Finding Properties that Support Enumerated Values

Use the set and get methods of the object to list all possible enumerated values for a property or to list the current enumerated value. The following example demonstrates how to first create an object representing the Microsoft Excel application as an ActiveX server, and then use the set method to determine which properties use enumerated types.

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 that offer a choice of settings are displayed as a multirow cell array, with one row per setting (see Cursor in the example above). Properties that offer only one possible setting are displayed as a single row cell array (see Creator above).

To display the current values of these properties, use the handle to the ActiveX server object you just created as the input to the get method as follows:

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

Setting Enumerated Property Values

You can also use the set method to modify a property to the value represented by an enumerated string. To do this, first obtain a list of all possible enumerated values for a specific property. You can use set with the property name argument to obtain this list. The output is a cell array of strings -one string for each possible setting of the specified property. Here are all the possible enumerated values of the Cursor property of the Excel server object from above:

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 the desired enumerated value.

---

You can abbreviate the enumeration string, as shown in the second line below. However, to avoid ambiguity, make sure you use enough unique letters in the string to distinguish the desired property value from other possible selections. The enumeration string is not case sensitive.

---

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

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

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

get(h, 'Cursor')
ans =
  xlNorthwestArrow

Vectorized Access and Modification

You can use the set and get methods on more than one ActiveX object at a time by putting the object handles into a vector and then operating on the vector. For example, to modify the Year property of a vector of handles representing Microsoft Calendar control objects, do the following:

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

---

To modify the desired property, you must make sure that all the elements of the vector represent the same type of ActiveX control.

---

As with enumerated strings for property values, you can abbreviate property names, which are also not case sensitive.

Reference Parameter Support

Certain ActiveX objects expose methods with input arguments that are also used as output. This is referred to as by-reference argument passing. Prior versions of MATLAB did not support passing arguments by reference. MATLAB 6.5 helps you pass arguments by reference by sending the output as the return parameter from the method.

To illustrate the support for by-reference parameters, this example uses the GetFullMatrix method of MATLAB itself as an ActiveX server. The function signature for GetFullMatrix is:

[SafeArray Pointer(double), SafeArray Pointer(double)]
GetFullMatrix(handle, string, string, SafeArray Pointer(double), SafeArray Pointer(double))

The fourth and fifth arguments of this method, which represent the size of the real and imaginary parts of the variable respectively, are by-reference arguments. Therefore, the modified values of these arguments are returned as output arguments. To see how this works, first create a MATLAB ActiveX server object from the currently executing MATLAB client session:

h = actxserver('matlab.application');

This creates a new MATLAB server session. Next, from the MATLAB client, create a new variable in the workspace of the MATLAB server:

Execute(h, 'var = magic(4)');

Now, pass the size of the variable var into the fourth and fifth arguments of GetFullMatrix to import the variable into the MATLAB client workspace from the MATLAB server:

[var, var_imag] = GetFullMatrix(h, 'var', 'base', zeros(4), zeros(4));

The variable var is now available in the MATLAB client workspace. MATLAB does not inherently support passing arguments by-reference. As a result, the modified value of the fourth argument, which in this example represents the variable var, is returned as the first output argument.

Dynamic Event Handling

In prior versions of MATLAB, you could register events for the control only at the time you created the control. For example, to register two events (Click and MouseDown) and two respective handler routines (myclick and mymoused) with the mwsamp control at control creation time, required:

h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], gcf, ...
  {'Click' 'myclick'; 'MouseDown' 'mymoused'});

MATLAB 6.5 lets you register and unregister a control's events any time after control creation using two new methods of the control object called registerevent and unregisterevent. Control creation and event management can now be separated as follows:

h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], gcf);
< …>
<code that interacts with the control>
< …>
registerevent(h, {'Click' 'myclick'; 'MouseDown' 'mymoused'});
< …>
<code that interacts with the control>
< …>
unregisterevent(h, {'Click' 'myclick'; 'MouseDown' 'mymoused'});

A new method called eventlisteners returns a list of all events and their corresponding handlers, which are currently registered for a control. Managing events at any time after the control is created, along with the new eventlisteners method, offers great flexibility in developing your application.

You still have two choices in designing your event handlers: create a single handler for all events or a specific handler for each event.

GUIs for Properties and Methods

MATLAB 6.5 features two new GUIs that make viewing methods and viewing and modifying the properties of ActiveX objects easier. You access these GUIs with the functions methodsview and inspect.

The methodsview function displays information on all methods implemented by the class representing the ActiveX object. For each method supported by the object, this GUI displays information such as name of the method, data type returned by the method, arguments passed to the method, parent of the specified object, etc.

The inspect function lists and enables you to modify property values of the desired ActiveX object via the Property Inspector GUI. To modify a property of an object in the figure window, select the desired property name and enter the new value in the corresponding GUI element (for example, Edit field, Popup menu, or Check box) for the selected property.

Additional Resources

Demos: Run the Automation Client Interface section in MATLAB 6.5.