MATLAB Function Reference

linkprop - Keep same value for corresponding properties

Syntax

hlink = linkprop(obj_handles,'PropertyName')
hlink = linkprop(obj_handles,{'PropertyName1','PropertyName2',...})

Description

Use linkprop to maintain the same values for the corresponding properties of different objects.

hlink = linkprop(obj_handles,'PropertyName') maintains the same value for the property PropertyName on all objects whose handles appear in obj_handles. linkprop returns the link object in hlink. See Link Object for more information.

hlink = linkprop(obj_handles,{'PropertyName1','PropertyName2',...}) maintains the same respective values for all properties passed as a cell array on all objects whose handles appear in obj_handles.

Note that the linked properties of all linked objects are updated immediately when linkprop is called. The first object in the list (obj_handles) determines the property values for the rest of the objects.

Link Object

The mechanism to link the properties of different graphics objects is stored in the link object, which is returned by linkprop. Therefore, the link object must exist within the context where you want property linking to occur (such as in the base workspace if users are to interact with the objects from the command line or figure tools).

The following list describes ways to maintain a reference to the link object.

Return the link object as an output argument from a function and keep it in the base workspace while interacting with the linked objects.
Make the hlink variable global.
Store the hlink variable in an object's UserData property or in application data. See the Examples section for an example that uses application data.

Modifying Link Object

If you want to change either the graphics objects or the properties that are linked, you need to use the link object methods designed for that purpose. These methods are functions that operate only on link objects. To use them, you must first create a link object using linkprop.

Method	Purpose
`addtarget`	Add specified graphics object to the link object's targets.
`removetarget`	Remove specified graphics object from the link object's targets.
`addprop`	Add specified property to the linked properties.
`removeprop`	Remove specified property from the linked properties.

Method Syntax

addtarget(hlink,obj_handles)
removetarget(hlink,obj_handles)
addprop(hlink,'PropertyName')
removeprop(hlink,'PropertyName')

Arguments

hlink — Link object returned by linkprop
obj_handles — One or more graphic object handles
PropertyName — Name of a property common to all target objects

Examples

This example creates four isosurface graphs of fluid flow data, each displaying a different isovalue. The CameraPosition and CameraUpVector properties of each subplot axes are linked so that the user can rotate all subplots in unison.

After running the example, select Rotate 3D from the figure Tools menu and observe how all subplots rotate together.

Note If you are using the MATLAB help browser, you can run this example or open it in the MATLAB editor.

The property linking code is in step 3.

Define the data using the flow M-file and specify property values for the isosurface (which is a patch object).

function linkprop_example
[x y z v] = flow;
isoval = [-3 -1 0 1];
props.FaceColor = [0 0 .5];
props.EdgeColor = 'none';
props.AmbientStrength = 1;
props.FaceLighting = 'gouraud';

Create four subplot axes and add an isosurface graph to each one. Add a title and set viewing and lighting parameters using a local function (set_view). (subplot, patch, isosurface, title, num2str)
```
for k = 1:4
    h(k) = subplot(2,2,k);
    patch(isosurface(x,y,z,v,isoval(k)),props)
    title(h(k),['Isovalue = ',num2str(k)])
    set_view(h(k))
end
```
Link the CameraPosition and CameraTarget properties of all subplot axes. Since this example function will have completed execution when the user is rotating the subplots, the link object is stored in the first subplot axes application data. See setappdata for more information on using application data.
```
hlink = linkprop(h,{'CameraPosition','CameraUpVector'});
key = 'graphics_linkprop';
% Store link object on first subplot axes
setappdata(h(1),key,hlink); 
```

The following local function contains viewing and lighting commands issued on each axes. It is called with the creation of each subplot (view, axis, camlight).

function set_view(ax)
% Set the view and add lighting
view(ax,3); axis(ax,'tight','equal')
camlight left; camlight right
% Make axes invisible and title visible
axis(ax,'off')
set(get(ax,'title'),'Visible','on')

Linking an Additional Property

Suppose you want to add the axes PlotBoxAspectRatio to the linked properties in the previous example. You can do this by modifying the link object that is stored in the first subplot axes' application data.

First click the first subplot axes to make it the current axes (since its handle was saved only within the creating function). Then get the link object's handle from application data (getappdata).
```
hlink = getappdata(gca,'graphics_linkprop');
```
Use the addprop method to add a new property to the link object.
```
addprop(hlink,'PlotBoxAspectRatio')
```

Since hlink is a reference to the link object (i.e., not a copy), addprop can change the object that is stored in application data.