Copying Objects

On this page…
Accessing the Clipboard Object copy Method Limitations Copying by Grouping (Recommended) Copying Objects Individually

Accessing the Clipboard Object

The Clipboard object (only one exists) provides an interface to the clipboard used in copying Stateflow objects. You cannot directly create or destroy the Clipboard object as you do other Stateflow API objects. However, you can attach a handle to it to use its properties and methods to copy Stateflow objects.

You create a handle to the Clipboard object by using the sfclipboard function as follows:

cb = sfclipboard;

Clipboard objects have two methods, copy and pasteTo, that together provide the functionality to copy objects from one object to another. The copy method copies the specified objects to the Clipboard object, and the pasteTo method pastes the contents of the clipboard to a new container.

Back to Top

copy Method Limitations

The copy method is subject to these limitations for all objects:

• The objects you copy must be all graphical (states, boxes, functions, transitions, junctions) or all nongraphical (data, events, targets).

  You cannot copy a mixture of graphical and nongraphical objects to the clipboard in the same copy operation.

• To maintain the transition connections and containment relationships between copied objects, you must copy the entire array of related objects.

  All related objects must be part of the array of objects copied to the clipboard. For example, if you try to copy two states connected by a transition to another container, you can only accomplish this by copying both the states and the transition at the same time. That is, you must do a single copy of a single array containing both the states and the transition that connects them.

  If you copy a grouped state to the clipboard, you copy all the objects contained in the state, as well as all the relations among the objects in the grouped state. See Copying by Grouping (Recommended).

Copying Graphical Objects

The copy method is subject to these limitations for all graphical objects:

• Copying graphical objects also copies the Data, Event, and Target objects that the graphical objects contain.

• If all copied objects are graphical, they must all be visible in the same subviewer.

  In other words, all graphical objects copied in a single copy command must reside in the same chart or subchart.

Back to Top

Copying by Grouping (Recommended)

Copying a grouped state in a Stateflow chart copies not only the state but all of its contents. By grouping a state before you copy it, you can copy it and all of its contained objects at all levels of containment with the Stateflow API. This method is the simplest way of copying objects. Use it whenever possible.

You use the Boolean IsGrouped property for a state to group that state. If you set the IsGrouped property for a state to a value of true (=1), it is grouped. If you set IsGrouped to a value of false (=0), the state is not grouped.

This example procedure copies state A to the chart X through grouping. In this example, assume that you already have a handle to state A and chart X through the MATLAB variables sA and chX, respectively:

1. If the state to copy is not already grouped, group it along with its contents by setting the IsGrouped property for that state to true (=1).

   prevGrouping = sA.IsGrouped;
   if (prevGrouping == 0)
   	sA.IsGrouped = 1;
   end
   

2. Get a handle to the Clipboard object.

   cb = sfclipboard;
   

3. Copy the grouped state to the clipboard using the Clipboard object.

   cb.copy(sA);
   

4. Paste the grouped object to its new container.

   cb.pasteTo(chX);
   

5. Set the copied state and its source state to its previous IsGrouped property value.

   sA.IsGrouped=prevGrouping;
   sNew=chX.find('-isa','Stateflow.State','Name',sA.Name);
   sNew.IsGrouped=prevGrouping;
   

Back to Top

Copying Objects Individually

You can copy specific objects from one object to another. However, in order to preserve transition connections and containment relations between objects, you must copy all the connected objects at once. To accomplish this, use the general technique of appending objects from successive finds in the MATLAB workspace to a growing array of objects before copying the finished object array to the clipboard.

Using the example of the Stateflow chart at the end of Creating New Objects in the Chart, you can copy states A1, A2, and the transition connecting them to another state, B, with these API commands, where sA and sB are object handles to states A and B, respectively.

objArrayS = sA.find('-isa','Stateflow.State','-depth',1);
objArrayT = sA.find('-isa','Stateflow.Transition','-depth',1);
sourceObjs = {objArrayS ; objArrayT};
cb = sfclipboard;
cb.copy(sourceObjs);
cb.pasteTo(sB);

You can also copy nongraphical data, events, and target objects individually. However, since there is no way for these objects to find their new owners, you must ensure that you copy each of these objects separately to its appropriate owner object.

Note   Copying objects individually is harder than copying grouped objects. See Copying by Grouping (Recommended).

Back to Top

Moving Graphical Objects

Zooming a Chart Object with the API

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS