# Graphical Editing

This section explains the use of the graphical editor and all user gestures (mouse clicks, keyboard actions, etc.) in more detail.

## Tool Palette

The Tool Palette appears along the right edge of the Drawing Canvas, although it can also be “docked” at the left edge. It consists of several “tool drawers” which can be individually expanded and collapsed, or pinned open (see screenshot at left).

Figure 9: Tool Palette

The Tool Palette can also be collapsed to save screen real-estate, using the button in the title bar.

Tool Drawers contain any number of “tools” which are categorized either as Selection Tools, Connector Tools or Creation Tools. The category defines their behavior:

Selection Tools remain active as long as they are enabled. The Select tool allows you to select individual elements on the Drawing Canvas by clicking the primary (left) mouse button; holding either the Control or Shift key allows you to select additional elements. The Marquee tool is used to select multiple elements by dragging a rectangular selection box around the elements. Additional elements can be selected by switching back to the Select tool.

Connector Tools also remain active as long as they are enabled. To create a connection between two elements, click the first element (the “source” of the connection) and then the second (the “target”).

Creation Tools are “single shot”, that is they are only active for a single mouse click action. Once the element has been created on the Drawing Canvas, the Select tool becomes active again.

Pressing the ESC key while a tool is active cancels its action, and re-activates the Select tool.

The Tool Palette’s behavior and appearance can be adjusted in the Settings dialog which is accessible from its context menu, as shown here:

Figure 10: Tool Palette Configuration

The Tool Palette supports the concept of “Profiles” which customizes the tools available based on the task to be accomplished. For example, the jBPM Target Runtime extension defines the following Profiles; each Profile is designed to limit the Tool Palette for a specific task:

Figure 11: Tool Palette Profiles

See also the User Preferences section for information about Tool Profiles.

## Context Button Pad

As mentioned in the Anatomy of the BPMN2 Modeler section, when the mouse is hovered over a shape, a Context Button Pad appears for that shape as shown here:

Figure 12: Context Button Pad

The list below describes these buttons and their function. Note that not all buttons are available for all types of elements, for example, it does not make sense to have an Append Activity button on an End Event. See the Appendix for more information.

Delete – deletes the selected element.

Show Properties – displays the element’s properties in a popup dialog. This allows the Property View to be completely hidden and open more screen real-estate for the Drawing Canvas.

Append Activity – appends a new Activity to the selected element and joins the new one with a Sequence Flow. The type of activity created is selected from a popup menu that appears when the Append Activity button is clicked.

Append Gateway – connects a new Gateway to the selected element with a Sequence Flow. The type of gateway is selected from a popup menu, similar to Append Activity.

Append Event – connects a new intermediate or End Event to the selected element with a Sequence Flow.

Morph Activity/Gateway – changes the element’s type, depending on whether the selected element is an Activity or Gateway. The new type can be selected from a popup menu when the button is clicked.

Create Connection – creates a new connection between this element and another element on the canvas. To create a new connection, click and drag the Create Connection button to the target element. When the mouse is released, a popup menu shows the type of connections that are valid for the source and target element. Select a type from this popup menu to complete the connection.

Collapse – this is available for Sub-Process, Transaction and Ad Hoc Sub-Process only. This action collapses the figure into a smaller rectangle and hides its contents.

Expand/Show Diagram – the opposite of Collapse, restores a collapsed Sub-Process, Transaction or Ad Hoc Sub-Process so that all of its contents are again visible. Show Diagram is only available for Call Activities; when clicked, the tab that contains the called process is activated. If the process is contained in an external file, a new editor will be opened for that file.

Push-Down – this is available for Pool, Sub-Process, Transaction and Ad Hoc Sub-Process only. This action moves the contents of the figure into a new diagram which is displayed as a separate tab at the bottom of the editor window. The Pool, Sub-Process, Transaction or Ad Hoc Sub-Process is then shown as a collapsed figure.

Pull-Up – the opposite of Push-Down, moves the contents of the Pool, Sub-Process, Transaction or Ad Hoc Sub-Process back to its parent and expands the figure. The tab that once contained these elements is removed from the editor.

Change Orientation – switches the orientation of the Pool or Lane figure from vertical to horizontal or vice-versa. Elements contained in the Pool or Lane, are moved as well to conform to the new orientation.

Whitebox – this is available for Choreography Participant Bands only. This action creates a new diagram tab that contains the Process for the Participant Band. This action is similar to Push-Down, with the exception that a Participant Band cannot be used to display the underlying Process as embedded elements.

Blackbox – this is the opposite of Whitebox. This action deletes the Process and diagram tab associated with the Participant Band.

Add Participant Band – available for Choreography Tasks only. This action adds a new Participant Band to the Choreography Task. Note that a Choreography Task may have any number of Participants, but only one of them can be the Initiator. See the Appendix for an explanation of Participants and Choreographies.

Remove Participant Band – available for Choreography Participant Bands only. This action removes a Participant Band from its Choreography Task.

Add Message – available for Choreography Participant Bands only. This action adds a Message to the Participant Band.

Remove Message – available for Choreography Participant Bands only. This action removes the Message attached to the Participant Band. This has the same effect as selecting the attached Message and deleting it.

## Connections

Connections between shapes can be created in one of three ways: using the Connector tools from the Tool Palette, using the Create Connection Context Button and implicitly using the Append Context buttons.

When a Connection is selected, one or more “handles” will appear on the connection line. The connection’s path can be altered by dragging one of these handles. Note that new handles will appear as a handle is dragged to create new line segments. The locations of these handles are known as “bendpoints” to the graphical editor, but are stored as Waypoint elements in the BPMN file.

BPMN2 Modeler allows you to specify different layout styles (“Routings”) for connections. Routing styles are applied by connection type, so for example, all Sequence Flows can be laid out using Manhattan routing, all Associations can use Manual Bendpoint routing, and so on. The Editor Appearance Preferences section explains how to configure connection routing styles.

Connections may also have labels, which are edited using the Property View. The labels are situated about the center of the connection, but may be dragged to a different location with the mouse.