Grouping, Combining and Binding

OpenOffice.org Developer's Guide

Drawing Documents and Presentation Documents

< Previous Section

Next Section >

• Example: Creating a Simple Organizational Chart

• Handling Drawing Document Files

• Saving Drawing Documents

• Storing
• Exporting
• Filter Options

• Printing Drawing Documents

• Working with Drawing Documents

• Shapes

• Shape Types
• Bezier Shapes
• Shape Operations

• Moving and Scaling
• Rotating and Shearing
• Transforming
• Ordering
• Grouping, Combining and Binding
• General Drawing Properties
• Glue Points and Connectors
• Layer Handling

• Inserting Files
• Navigating

• Handling Presentation Document Files

• Printing Presentation Documents

• Working with Presentation Documents

• Presentation Settings

• Custom Slide Show
• Presentation Effects
• Slide Transition
• Animations and Interactions

• Overall Document Features

• Settings
• Page Formatting

• Drawing and Presentation Document Controller

• Setting the Current Page
• Zooming
• Other Drawing Specific View Settings

< Previous Page

Next Page >

The DrawPage plays an important role for the handling of multiple shapes. It has three interfaces for this purpose. Its interface com.sun.star.drawing.XShapeGrouper is used to create a group shape from a ShapeCollection and ungroup existing groups.

Methods of com.sun.star.drawing.XShapeGrouper
group()	Parameter: com.sun.star.drawing.XShapes xShapes Groups the shapes inside a collection. They must all be inserted into the same GenericDrawPage. Returns a recently created GroupShape that contains all shapes from xShapes, and is also added to the GenericDrawPage of the Shapes in xShapes.
ungroup()	Parameter: com.sun.star.drawing.XShapeGroup Ungroups a given GroupShape. Moves all Shapes from this GroupShape to the parent XShapes of the GroupShape. The GroupShape is then removed from the GenericDrawPage and disposed.

The example below creates a group using the com.sun.star.drawing.XShapeGrouper interface. For this purpose, the shapes that are to be grouped have to be added to a com.sun.star.drawing.ShapeCollection that is created by the com.sun.star.lang.XMultiServiceFactory of the global service manager. It is a container of shapes that is accessed using the interface com.sun.star.drawing.XShapes. The following example accesses the XShapes interface of the DrawPage to locate two shapes on the DrawPage, and uses the XShapes interface of the ShapeCollection to add these shapes to the ShapeCollection. Finally, it employs the XShapeGrouper interface of the DrawPage to move the shapes from the ShapeCollection into a new GroupShape.

  /* try to group the first two objects of the drawpage */
  // create a container that will receive the 
  // shapes that are to be grouped 
  Object xObj = xMultiServiceFactory.createInstance("com.sun.star.drawing.ShapeCollection");
  XShapes xToGroup = (XShapes)UnoRuntime.queryInterface(XShapes.class, xObj);
  // query for the shape collection of xDrawPage
  XShapes xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPage);
  // test if the shape collection of the page has at least two shapes
  if (xShapes.getCount() >= 2) {
      // collect shapes we want to group
      xToGroup.add((XShape)UnoRuntime.queryInterface(XShape.class, xShapes.getByIndex(0)));
      xToGroup.add((XShape)UnoRuntime.queryInterface(XShape.class, xShapes.getByIndex(1)));
      // now group the shapes we have collected by using the XShapeGrouper
      XShapeGrouper xShapeGrouper = (XShapeGrouper)UnoRuntime.queryInterface(
          XShapeGrouper.class, xDrawPage);
      xShapeGrouper.group(xToGroup);
  }

The service com.sun.star.drawing.GroupShape includes com.sun.star.drawing.Shape and supports two additional interfaces:

• com.sun.star.drawing.XShapes is used to access the shapes in the group.
• com.sun.star.drawing.XShapeGroup handles access to the group.

The interface XShapes inherits from com.sun.star.container.XIndexAccess, and introduces add() and remove(). It contains the following methods:

  type getElementType()
  boolean hasElements()
  long getCount()
  any getByIndex( [in] long Index)
  void add( [in] com::sun::star::drawing::XShape xShape)
  void remove( [in] com::sun::star::drawing::XShape xShape)

Methods of com.sun.star.drawing.XShapeGroup:

  string getShapeType()
  com::sun::star::awt::Point getPosition()
  void setPosition( [in] com::sun::star::awt::Point aPosition)
  com::sun::star::awt::Size getSize()
  void setSize( [in] com::sun::star::awt::Size aSize)

It is also possible to create GroupShapes directly without using the XShapeGrouper interface. The following code demonstrates the creation of a com.sun.star.drawing.GroupShape that takes up three other shapes.

  // create a group shape first. The size and position does not matter, because
  // it depends to the position and size of objects that will be inserted later
  XShape xGroup = createShape(xComponent, 0, 0, 0, 0, "com.sun.star.drawing.GroupShape");
  // before it is possible to insert shapes,
  // the group shape must have been added to the page
  XShapes xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPage);
  xShapes.add(xGroup);
  // query for the XShapes interface, which will take our new shapes 
  XShapes xShapesGroup = (XShapes)UnoRuntime.queryInterface(XShapes.class, xGroup);
  // new shapes can be inserted into the shape collection directly
  xShapesGroup.add( createShape(xComponent, 1000, 1000, 2000, 4000,
      "com.sun.star.drawing.EllipseShape"));
  xShapesGroup.add( createShape(xComponent, 8000, 8000, 2000, 2000,
      "com.sun.star.drawing.EllipseShape"));
  xShapesGroup.add( createShape(xComponent, 2000, 3000, 7000, 6000,
      "com.sun.star.drawing.LineShape"));

The interface com.sun.star.drawing.XShapeCombiner combines shapes and is equivalent to Modify - Combine in the user interface.

Methods of com.sun.star.drawing.XShapeCombiner
combine()	Parameter: com.sun.star.drawing.XShapes Combines shapes. The shapes inside this container are converted to PolyPolygonBezierShapes and are than combined into one PolyPolygonBezierShape. The shapes in xShape are removed from the GenericDrawPage and disposed. Returns a recently created PolyPolygonBezierShape that contains all the converted PolyPolygonBezierShapes combined. It is also added to the GenericDrawPage of the source Shapes.
split()	Parameter: com.sun.star.drawing.XShape Splits shapes. The Shape is converted to a PolyPolygonBezierShape and then split into several PolyPolygonBezierShapes. The shape s in xShape are removed from the GenericDrawPage and disposed.

The draw page interface com.sun.star.drawing.XShapeBinder draws a connection line between the ending point of a line shape (or curve) to the starting point of another line shape (or curve), merging the connected lines into a single shape object. This function corresponds to Modify - Connect in the user interface. It works for area shapes as well, but the connection line usually can not resolve them.

Methods of com.sun.star.drawing.XShapeBinder
bind()	Parameter: com.sun.star.drawing.XShapes binds shapes together. A container with shapes that will be bound together. All shapes are converted to a PolyPolygonBezierShape and the lines are connected. The Shapes in xShape are removed from the GenericDrawPage and disposed. Returns a recently created PolyPolygonBezierShape that contains all line segments from the supplied Shapes. It is also added to the GenericDrawPage of the source Shapes.
unbind()	Parameter: com.sun.star.drawing.XShape breaks a shape into its line segments. The given shape will be converted to a PolyPolygonBezierShape and the line segments of this shape are used to create new PolyPolygonBezierShape shapes. The original shape is removed from its GenericDrawPage and disposed.

Content on this page is licensed under the Public Documentation License (PDL).