Shape Objects in Text

OpenOffice.org Developer's Guide

Text Documents

< Previous Section

Next Section >

• Example: Fields in a Template
• Example: Visible Cursor Position

• Handling Text Document Files

• Saving Text Documents
• Printing Text Documents

• Working with Text Documents

• Editing Text
• Iterating over Text
• Inserting a Paragraph where no Cursor can go
• Sorting Text
• Inserting Text Files
• Auto Text

• Formatting
• Navigating
• Tables

• Named Table Cells in Rows, Columns and the Table Cursor
• Indexed Cells and Cell Ranges
• Table Naming, Sorting, Charting and Autoformatting
• Text Table Properties
• Inserting Tables
• Accessing Existing Tables

• Text Fields
• Bookmarks
• Indexes and Index Marks
• Reference Marks
• Footnotes and Endnotes
• Shape Objects in Text

• Text Frames
• Embedded Objects
• Graphic Objects
• Drawing Shapes

• Redline
• Ruby

• Overall Document Features

• Settings
• Line Numbering and Outline Numbering
• Text Sections
• Page Layout
• Columns
• Link Targets

• Text Document Controller

• TextView
• TextViewCursor

< Previous Page

Next Page >

Base Frames vs. Drawing Shapes

Shape objects are text contents that act independently of the ordinary text flow. The surrounding text may wrap around them. Shape objects can lie in front or behind text, and be anchored to paragraphs or characters in the text. Anchoring allows the shape objects to follow the paragraphs and characters while the user is writing. Currently, there are two different kinds of shape objects in Apache OpenOffice, base frames and drawing shapes.

Base Frames

The first group are shape objects that are com.sun.star.text.BaseFrames. The three services com.sun.star.text.TextFrame, com.sun.star.text.TextGraphicObject and com.sun.star.text.TextEmbeddedObject are all based on the service com.sun.star.text.BaseFrame. The TextFrames contain an independent text area that can be positioned freely over ordinary text. The TextGraphicObjects are bitmaps or vector oriented images in a format supported by Apache OpenOffice internally. The TextEmbeddedObjects are areas containing a document type other than the document they are embedded in, such as charts, formulas, internal Apache OpenOffice documents (Calc/Draw/Impress), or OLE objects.

The TextFrames, TextGraphicObjects and TextEmbeddedObjects in a text are supplied by their corresponding supplier interfaces at the document model:

• com.sun.star.text.XTextFramesSupplier
• com.sun.star.text.XTextGraphicObjectsSupplier
• com.sun.star.text.XTextEmbeddedObjectsSupplier.

These interfaces all have one single get method that supplies the respective Shape objects collection:

 com::sun::star::container::XNameAccess getTextFrames()
 com::sun::star::container::XNameAccess getTextEmbeddedObjects()
 com::sun::star::container::XNameAccess getTextGraphicObjects()

The method getTextFrames() returns a com.sun.star.text.TextFrames collection, getTextEmbeddedObjects() returns a com.sun.star.text.TextEmbeddedObjects collection and getTextGraphicObjects() yields a com.sun.star.text.TextGraphicObjects collection. All of these collections support com.sun.star.container.XIndexAccess and com.sun.star.container.XNameAccess. The TextFrames collection may (optional) support the com.sun.star.container.XContainer interface to broadcast an event when an Element is added to the collection. However, the current implementation of the TextFrames collection does not support this.

The service com.sun.star.text.BaseFrame defines the common properties and interfaces of text frames, graphic objects and embedded objects. It includes the services com.sun.star.text.BaseFrameProperties and com.sun.star.text.TextContent, and defines the following interfaces.

The position and size of a BaseFrame is covered by com.sun.star.drawing.XShape. All BaseFrame objects share a majority of the core implementation of drawing objects. Therefore, they have a position and size on the DrawPage.

The name of a BaseFrame is set and read through com.sun.star.container.XNamed. The names of the frame objects have to be unique for text frames, graphic objects and embedded objects, respectively.

The com.sun.star.beans.XPropertySet has to be present, because many aspects of BaseFrames are controlled through properties.

The interface com.sun.star.document.XEventsSupplier is not a part of the BaseFrame service, but is available in text frames, graphic objects and embedded objects. This interface provides access to the event macros that may be attached to the object in the GUI.

The properties of BaseFrames are those of the service com.sun.star.text.TextContent, as well there is a number of frame properties defined in the service com.sun.star.text.BaseFrameProperties:

Properties of com.sun.star.text.BaseFrameProperties
AnchorPageNo	short - Contains the number of the page where the objects are anchored.
AnchorFrame	com.sun.star.text.XTextFrame. Contains the text frame the current frame is anchored to.
BackColor	long - Contains the color of the background of the object.
BackGraphicURL	string - Contains the URL for the background graphic.
BackGraphicFilter	string - Contains the name of the file filter for the background graphic.
BackGraphicLocation	Determines the position of the background graphic according to com.sun.star.style.GraphicLocation.
LeftBorder	struct com.sun.star.table.BorderLine. Contains the left border of the object.
RightBorder	struct com.sun.star.table.BorderLine. Contains the right border of the object.
TopBorder	struct com.sun.star.table.BorderLine. Contains the top border of the object.
BottomBorder	struct com.sun.star.table.BorderLine. Contains the bottom border of the object.
BorderDistance	long - Contains the distance from the border to the object.
LeftBorderDistance	long - Contains the distance from the left border to the object.
RightBorderDistance	long - Contains the distance from the right border to the object.
TopBorderDistance	long - Contains the distance from the top border to the object.
BottomBorderDistance	long - Contains the distance from the bottom border to the object.
BackTransparent	boolean - If true, the property BackColor is ignored.
ContentProtected	boolean - Determines if the content is protected.
LeftMargin	long - Contains the left margin of the object.
RightMargin	long - Contains the right margin of the object.
TopMargin	long - Contains the top margin of the object.
BottomMargin	long - Contains the bottom margin of the object.
Height	long - Contains the height of the object (1/100 mm).
Width	long - Contains the width of the object (1/100 mm).
RelativeHeight	short - Contains the relative height of the object.
RelativeWidth	short - Contains the relative width of the object.
IsSyncWidthToHeight	boolean - Determines if the width follows the height.
IsSyncHeightToWidth	boolean - Determines if the height follows the width.
HoriOrient	short - Determines the horizontal orientation of the object according to com.sun.star.text.HoriOrientation.
HoriOrientPosition	long - Contains the horizontal position of the object (1/100 mm).
HoriOrientRelation	short - Determines the environment of the object the orientation is related according to com.sun.star.text.RelOrientation.
VertOrient	short - Determines the vertical orientation of the object according to com.sun.star.text.VertOrientation.
VertOrientPosition	long - Contains the vertical position of the object (1/100 mm). Valid only if TextEmbeddedObject::VertOrient is VertOrientation::NONE.
VertOrientRelation	short - Determines the environment of the object the orientation is related according to com.sun.star.text.RelOrientation.
HyperLinkURL	string - Contains the URL of a hyperlink that is set at the object.
HyperLinkTarget	string - Contains the name of the target for a hyperlink that is set at the object.
HyperLinkName	string - Contains the name of the hyperlink that is set at the object.
Opaque	boolean - Determines if the object is opaque or transparent for text.
PageToggle	boolean - Determines if the object is mirrored on even pages.
PositionProtected	boolean - Determines if the position is protected.
Print	boolean - Determines if the object is included in printing.
ShadowFormat	struct com.sun.star.table.ShadowFormat. Contains the type of the shadow of the object.
ServerMap	boolean - Determines if the object gets an image map from a server.
Size	struct com.sun.star.awt.Size. Contains the size of the object.
SizeProtected	boolean - Determines if the size is protected.
Surround	[deprecated]. Determines the type of the surrounding text.
SurroundAnchorOnly	boolean - Determines if the text of the paragraph where the object is anchored, wraps around the object.

Drawing Shapes

The second group of shape objects are the varied drawing shapes that can be inserted into text, such as rectangles and ellipses. They are based on com.sun.star.text.Shape. The service text.Shape includes Shape, but adds a number of properties related to shapes in text (cf. Drawing Shapes below). In addition, drawing shapes support the interface com.sun.star.text.XTextContent so that they can be inserted into an XText.

There are no specialized supplier interfaces for drawing shapes. All the drawing shapes on the DrawPage object are supplied by the document model's com.sun.star.drawing.XDrawPageSupplier and its single method:

 com::sun::star::drawing::XDrawPage getDrawPage()

The DrawPage not only contains drawing shapes, but the BaseFrame shape objects too, if the document contains any.

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