|  |  | 4.4 Group objects

## 4.4 Group objects

Group objects are created by selecting any number of objects and using the Group function from the Edit menu. The grouped objects then behave like a single object. To modify a group object, it has to be decomposed into its parts using Ungroup.

#### Clipping

You can set a clipping path for a group. The group will then be clipped to this path—nothing will be drawn outside the clipping path. This is useful, for instance, to clip out an interesting part of an existing drawing or bitmap.

To add a clipping path, select a group as the primary selection, and a path object as the secondary selection. Then select Add clipping path from the group's context menu.

#### Decorations

Group objects can be decorated. A decoration consists of one or more path objects that are drawn around the group. The decoration is automatically resized to fit the bounding box of the group.

To use decorations, you first need to add a stylesheet to your document that defines decoration symbols—you may want to start with the provided style sheet decorations.isy. Then use the group's object menu to choose a decoration for the group.

#### Editing text in group

Groups often contain some text. For instance, a graph vertex is nicely represented as a group consisting of a text label and either a mark symbol such as a disk, or a path object (a circle, rectangle, or a more complicated shape). When drawing a graph, one can place the vertices by copying and pasting these vertex objects, but then one needs to set the text label in each vertex.

To make this easy, the Edit object operation (which is otherwise used to edit the text in text objects and the shape of path objects) can also be used for group objects that contain at lease one text object. It allows you to update the text inside the top-most text object of the group.

#### Recursive group edit

Often you want to modify the contents of a group without disturbing the rest of your drawing. To make this easy, Ipe provides the Edit group operation, available either from the Edit menu or from the group's context menu.

Group editing is implemented by un-grouping the group into a newly created layer whose name will start with EDIT-GROUP. Ipe locks all other layers, so that you can concentrate on editing the objects in the group. When you are done, you select End group edit from the Edit menu. Ipe will take all the objects in the group edit layer, group them together, and place the group back in its original layer.

You can edit groups recursively: If your group contains another group that you want to modify, you can perform another group edit operation. Each End group edit closes one group edit layer, until you return to your normal drawing workflow.

Group edit is not a special mode—all the state needed by Ipe to manage editing the group is stored inside the drawing. This means that you can save your drawing during a group edit (also, auto-saving works during a group edit). If you have a document with multiple pages, you can also start group edits on several pages in parallel, for instance to copy and paste objects between groups.

It is legal to unlock the other layers of the page so that you can move objects into and out of the group. You should, however, be careful with changing anything about the layers of the page—do not re-order or rename the layers. If you need new layers, create them at the end of the layer list.

When you perform the End group edit operation, the group edit layer must be the active layer. If you changed the active layer, you will have to change it back to be able to return from the group edit.

Note that group edit does not currently preserve a clipping path or a link destination set on the group. It does preserve the group's decoration.

#### Links to websites, videos, and other pages

Group objects allow you to create active links: when the PDF document is viewed in a PDF viewer, one can click inside the bounding box of the group to cause some action.

You add a link to a group by bringing up the object menu, and using Set link URL. Note that only top-level group objects on a page (that is, a group object that is not inside another group) are turned into active links.

Ipe supports several types of link actions:

##### Websites

If you provide a URL such as http://ipe.otfried.org as a link action, then clicking on the link will open the webpage in a web browers.

##### Launching media

If the link action starts with launch:, then the action starts a program to view the given file. For instance, the link action launch:apollo17.avi would start a video player playing the file apollo17.avi in the directory that also contains the PDF file.

The PDF presentations apps Présentation and pdfpc understand these links, and play the video inside the presentation app. Pdfpc will even embed the video into the current slide, using the bounding box of the group object to place the video.

Pdfpc allows you to provide a few more parameters: for instance, the link action

    launch:apollo17.avi?autostart&loop&start=5&stop=12

will start the movie as soon as the slide is viewed, plays the movie in a loop, starting at 5 seconds and ending at 12 seconds into the movie.

You can also launch other types of documents. For instance, clicking on a group object with link action launch:summary.txt will open the text file summary.txt in a text editor.

##### Navigating inside the document

If the link action starts with goto:, then clicking on the group object will navigate to another page of the same PDF document. You identify pages using their section name. So if you have a page with section name chapter3 in your document, then the link action goto:chapter3 will jump to that page.

##### Standard actions

PDF currently defines four standard actions: NextPage, PrevPage, FirstPage, and LastPage. You use these by prefixing them with named:. For example, the link action named:PrevPage creates an action to go to the previous page. This can be used, for instance, to place buttons in a background layer that appears on every page of a document.