Changing Shape's Position in Stacking Order

Although the 2D presentation is flat, shapes are drawn in a certain order and shown one above the other. This order is called the Z-order because there is a virtual Z axis perpendicular to the surface of the presentation and extending towards the viewer.

There are four common commands that allow you to change the Z-order of a shape:

Command

Description

Bring To Front

Places the shape on top of all other shapes.

Bring Forward

Moves the shape one step up (swaps it with the shape directly in front).

Send Backward

Moves the shape one step down (sends the shape backward one level).

Send To Back

Places the shape below all other shapes.

 To change the Z-order of a shape

  1. Select the shape in the graphical editor by clicking it.
  2. Click the corresponding [Command] toolbar button, or
    Right-click (Mac OS: Ctrl+click) the shape in the graphical editor and choose Order > [Command] from the context menu, or
    Choose Draw > Order > [Command]  from the main menu.
The figure below illustrates these commands. Here we change the Z-order of the red star that is initially placed below two shapes (cyan rounded rectangle and white oval) and on top of two other ones (circle and rectangle). You can see that by changing the Z-order of a shape, you move it in the Presentation tree up or down. The elements of the Presentation tree are actually displayed according to their Z-order - the shape that is placed below all other shapes is the topmost item of the tree, and so on.

Sometimes shapes get hidden below other shapes. You can still select those shapes either by clicking their location several times in the graphical editor or by using the Presentation tree.

 To select a shape that is hidden below other shapes in the graphical editor

  1. Click in the position where the hidden shape is located. The top level shape gets selected.
  2. Continue clicking in the same position until you select the shape you are looking for. With each click, the next shape in the stacking order will be selected. In the Properties view, you can see which shape is currently selected.

Changing the shape's Z-order at model runtime

You can change the shape's Z-order dynamically at model runtime by calling presentation.remove() and presentation.insert() functions.

The insert() function takes two arguments. The first one is the integer index of the new position of the shape in the presentation's Z-order. The second argument is the shape itself.

Note that the shape should be removed from all the groups where it is contained prior to removing this shape from the agent's presentation. 

In the table below we provide you with the code snippets that change the Z-order of the shape named rectangle.

Action

Code

Bring to front

presentation.remove(rectangle);
presentation.insert(presentation.size()-1, rectangle);

Send to back

presentation.remove(rectangle);
presentation.insert(0, rectangle);

Bring forward

int shapeIndex = presentation.indexOf(rectangle);
if ( shapeIndex < presentation.size() - 1 )
{
    presentation.remove(rectangle);
    presentation.insert(shapeIndex + 1, rectangle);
}

Send backward

int shapeIndex = presentation.indexOf(rectangle);
if
shapeIndex > 0 )
{
    presentation.remove(rectangle);
    presentation.insert(
shapeIndex - 1, rectangle);
}

You can also play with visibility of the shapes to create the required dynamic presentation.