Difference between revisions of "EN/documentation/basic guide/structure of drawings"

From Wiki
Jump to navigationJump to search
 
Line 77: Line 77:
 
=== Renaming Pages ===
 
=== Renaming Pages ===
  
{{Documentation/Caution|If a new page is inserted in a drawing document of several pages, all subsequent pages which have '''not''' been renamed will automatically see their default name change, e.g. '''Slide 3''' will be changed into '''Slide 4''', etc. This automatic renaming works also in reverse when a page is deleted.
+
{{Caution|If a new page is inserted in a drawing document of several pages, all subsequent pages which have '''not''' been renamed will automatically see their default name change, e.g. '''Slide 3''' will be changed into '''Slide 4''', etc. This automatic renaming works also in reverse when a page is deleted.
  
 
The only way to have a fixed page name is to rename the page, by the user interface or by programming.}}
 
The only way to have a fixed page name is to rename the page, by the user interface or by programming.}}

Latest revision as of 10:57, 6 September 2011




Pages

Tip.png A Draw (or Impress) document is composed of pages, also called slides. What is written here also applies to Impress documents.

OpenOffice.org does not limit the number of pages in a drawing document. You can design each page separately. There is also no limit to the number of drawing elements that you can add to a page.

The pages of a drawing document are available through the DrawPages container. You can access individual pages either through their number or their name. If a document has one page and this is called Slide 1, then the following examples are identical.

Example 1: access by means of the number (numbering begins with 0)

Dim Doc As Object
Dim Page As Object

Doc = ThisComponent
Page = Doc.DrawPages(0)
Documentation note.png The expression Doc.DrawPages(0) is a Basic simplification of the API call : Doc.getDrawPages.getByIndex(0)

Example 2: access by means of the name

Dim Doc As Object
Dim Page As Object

Doc = ThisComponent
Page = Doc.DrawPages.getByName("Slide 1")

In Example 1, the page is accessed by its number (counting begins at 0). In the second example, the page is accessed by its name and the getByName method.

Properties of a page

The preceding call returns a page object that supports the com.sun.star.drawing.DrawPage service. The service recognizes the following properties:

BorderLeft (Long)
left-hand border in hundredths of a millimeter
BorderRight (Long)
right-hand border in hundredths of a millimeter
BorderTop (Long)
top border in hundredths of a millimeter
BorderBottom (Long)
bottom border in hundredths of a millimeter
Width (Long)
page width in hundredths of a millimeter
Height (Long)
page height in hundredths of a millimeter
Number (Short)
number of pages (numbering begins at 1), read-only
Orientation (Enum)
page orientation (in accordance with com.sun.star.view.PaperOrientation enumeration)

If these settings are changed, then all of the pages in the document are affected.

The following example sets the page size of a drawing document which has just been opened to 20 x 20 centimeters with a page margin of 0.5 centimeters:

Dim Doc As Object
Dim Page As Object

Doc = ThisComponent
Page = Doc.DrawPages(0)

Page.BorderLeft = 500
Page.BorderRight = 500
Page.BorderTop = 500
Page.BorderBottom = 500

Page.Width = 20000
Page.Height = 20000

Renaming Pages

Documentation caution.png If a new page is inserted in a drawing document of several pages, all subsequent pages which have not been renamed will automatically see their default name change, e.g. Slide 3 will be changed into Slide 4, etc. This automatic renaming works also in reverse when a page is deleted.

The only way to have a fixed page name is to rename the page, by the user interface or by programming.

A page provides methods getName and setName to read and modify its name. Basic can handle both methods like a property Name. Here we rename the first page of the drawing document.

Dim Doc As Object
Dim Page As Object
 
Doc = ThisComponent
Page = Doc.DrawPages(0)
Page.Name = "First"

Creating and Deleting Pages

The DrawPages container of a drawing document is also used to create and delete individual pages. The following example uses the hasByName method to check if a page called MyPage exists. If it does, the method determines a corresponding object reference by using the getByName method and then saves the reference in a variable in Page. If the corresponding page does not exist, it is created and inserted in the drawing document by the insertNewByIndex method. The argument of the method is the position, counted from 0, of the existing page after which the new page will be inserted. Then the new page is renamed.

Dim Doc As Object
Dim Page As Object

Doc = ThisComponent

If Doc.Drawpages.hasByName("MyPage") Then
   Page = Doc.Drawpages.getByName("MyPage")
Else
   Page = Doc.Drawpages.insertNewByIndex(2)
   Page.Name = "MyPage" ' you should always rename a new page
   ' MyPage is the fourth page of the document, i.e. position 3
End If

The hasByName and getByName methods are obtained from the com.sun.star.container.XNameAccess interface.

The insertNewByIndex method is obtained from the com.sun.star.drawing.XDrawPages interface. The same interface provides the method remove to delete (remove) a page:

Dim Doc As Object
 
Doc = ThisComponent

If Doc.Drawpages.hasByName("MyPage") Then
   Page = Doc.Drawpages.getByName("MyPage")
   Doc.Drawpages.remove(Page)
End If

Duplicating a Page

A copy of a given page is created, not from the DrawPages container, but from the drawing document itself with the method duplicate. The copy is created at the next position after the original page, with a default name.

Dim Doc As Object
Dim Page As Object, ClonedPage As Object
 
Doc = ThisComponent
Page = Doc.Drawpages.getByName("MyPage")
ClonedPage = Doc.duplicate(Page)
ClonedPage.Name = "MyCopy" ' you should always rename a new page

Moving a Page

The API does not provide a method to change the position of a page inside a drawing document.


Elementary Properties of Drawing Objects

Drawing objects include shapes (rectangles, circles, and so on), lines, and text objects. All of these share a number of common features and support the com.sun.star.drawing.Shape service. This service defines the Size and Position properties of a drawing object.

OpenOffice.org Basic also offers several other services through which you can modify such properties, as formatting or apply fills. The formatting options that are available depend on the type of drawing object.

The following example creates and inserts a rectangle in a drawing document:

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Doc = ThisComponent
Page = Doc.DrawPages(0)

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

Page.add(RectangleShape)

The Point and Size structures with the point of origin (left hand corner) and the size of the drawing object are then initialized. The lengths are specified in hundredths of a millimeter.

The program code then uses the Doc.createInstance call to create the rectangle drawing object as specified by the com.sun.star.drawing.RectangleShape service. At the end, the drawing object is assigned to a page using a Page.add call.

Fill Properties

This section describes four services and in each instance the sample program code uses a rectangle shape element that combines several types of formatting. Fill properties are combined in the com.sun.star.drawing.FillProperties service.

OpenOffice.org recognizes four main types of formatting for a fill area. The simplest variant is a single-color fill. The options for defining color gradients and hatches let you create other colors into play. The fourth variant is the option of projecting existing graphics into the fill area.

The fill mode of a drawing object is defined using the FillStyle property. The permissible values are defined in com.sun.star.drawing.FillStyle.

Single Color Fills

The main property for single-color fills is:

FillColor (Long)
fill color of area

To use the fill mode, you must the FillStyle property to the SOLID fill mode.

The following example creates a rectangle shape and fills it with red (RGB value 255, 0, 0):

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.SOLID
RectangleShape.FillColor = RGB(255,0,0)

Page.add(RectangleShape)

Color Gradient

If you set the FillStyle property to GRADIENT, you can apply a color gradient to any fill area of a OpenOffice.org document.

If you want to apply a predefined color gradient, you can assign the associated name of the FillTransparenceGradientName property. To define your own color gradient, you need to complete a com.sun.star.awt.Gradient structure to assign the FillGradient property. This property provides the following options:

Style (Enum)
type of gradient, for example, linear or radial (default values in accordance with com.sun.star.awt.GradientStyle)
StartColor (Long)
start color of color gradient
EndColor (Long)
end color of color gradient
Angle (Short)
angle of color gradient in tenths of a degree
XOffset (Short)
X-coordinate at which the color gradient starts, specified in hundredths of a millimeter
YOffset (Short)
Y-coordinate at which the color gradient begins, specified in hundredths of a millimeter
StartIntensity (Short)
intensity of StartColor as a percentage (in OpenOffice.org Basic, you can also specify values higher than 100 percent)
EndIntensity (Short)
intensity of EndColor as a percentage (in OpenOffice.org Basic, you can also specify values higher than 100 percent)
StepCount (Short)
number of color graduations which OpenOffice.org is to calculate for the gradients

The following example demonstrates the use of color gradients with the aid of the com.sun.star.awt.Gradient structure:

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size
Dim Gradient As New com.sun.star.awt.Gradient 

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point
Gradient.Style = com.sun.star.awt.GradientStyle.LINEAR
Gradient.StartColor = RGB(255,0,0)
Gradient.EndColor = RGB(0,255,0)
Gradient.StartIntensity = 150   
Gradient.EndIntensity = 150
Gradient.Angle = 450
Gradient.StepCount = 100

RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.GRADIENT
RectangleShape.FillGradient = Gradient

Page.add(RectangleShape)

This example creates a linear color gradient (Style = LINEAR). The gradient starts with red (StartColor) in the top left corner, and extends at a 45 degree angle (Angle) to green (EndColor) in the bottom right corner. The color intensity of the start and end colors is 150 percent (StartIntensity and EndIntensity) which results in the colors seeming brighter than the values specified in the StartColor and EndColor properties. The color gradient is depicted using a hundred graduated individual colors (StepCount).

Hatches

To create a hatch fill, the FillStyle property must be set to HATCH. The program code for defining the hatch is very similar to the code for color gradients. Again an auxiliary structure, in this case com.sun.star.drawing.Hatch, is used to define the appearance of hatches. The structure for hatches has the following properties:

Style (Enum)
type of hatch: simple, squared, or squared with diagonals (default values in accordance with com.sun.star.awt.HatchStyle)
Color (Long)
color of lines
Distance (Long)
distance between lines in hundredths of a millimeter
Angle (Short)
angle of hatch in tenths of a degree

The following example demonstrates the use of a hatch structure:

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size
Dim Hatch As New com.sun.star.drawing.Hatch

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.HATCH

Hatch.Style = com.sun.star.drawing.HatchStyle.SINGLE
Hatch.Color = RGB(64,64,64)
Hatch.Distance = 20
Hatch.Angle = 450

RectangleShape.FillHatch = Hatch

Page.add(RectangleShape)

This code creates a simple hatch structure (HatchStyle = SINGLE) whose lines are rotated 45 degrees (Angle). The lines are dark gray (Color) and are spaced is 0.2 millimeters (Distance) apart.

Bitmaps

To use bitmap projection as a fill, you must set the FillStyle property to BITMAP. If the bitmap is already available in OpenOffice.org, you just need to specify its name in the FillBitMapName property and its display style (simple, tiled, or elongated) in the FillBitmapMode property (default values in accordance with com.sun.star.drawing.BitmapMode).

If you want to use an external bitmap file, you can specify its URL in the FillBitmapURL property.

The following example creates a rectangle and tiles the Sky bitmap that is available in OpenOffice.org to fill the area of the rectangle:

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.BITMAP
RectangleShape.FillBitmapName = "Sky"
RectangleShape.FillBitmapMode = com.sun.star.drawing.BitmapMode.REPEAT

Page.add(RectangleShape)

Transparency

You can adjust the transparency of any fill that you apply. The simplest way to change the transparency of a drawing element is to use the FillTransparence property.

The following example creates a red rectangle with a transparency of 50 percent.

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.SOLID
RectangleShape.FillTransparence = 50
RectangleShape.FillColor = RGB(255,0,0)
 
Page.add(RectangleShape)

To make the fill transparent, set the FillTransparence property to 100.

In addition to the FillTransparence property, the com.sun.star.drawing.FillProperties service also provides the FillTransparenceGradient property. This is used to define a gradient that specifies the transparency of a fill area.

Line Properties

All drawing objects that can have a border line support the com.sun.star.drawing.LineStyle service. Some of the properties that this service provides are:

LineStyle (Enum)
line type (default values in accordance with com.sun.star.drawing.LineStyle)
LineColor (Long)
line color
LineTransparence (Short)
line transparency
LineWidth (Long)
line thickness in hundredths of a millimeter
LineJoint (Enum)
transitions to connection points (default values in accordance with com.sun.star.drawing.LineJoint )

The following example creates a rectangle with a solid border (LineStyle = SOLID) that is 5 millimeters thick (LineWidth) and 50 percent transparent. The right and left-hand edges of the line extend to their points of intersect with each other (LineJoint = MITER) to form a right-angle.

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.LineColor = RGB(128,128,128)
RectangleShape.LineTransparence = 50
RectangleShape.LineWidth = 500
RectangleShape.LineJoint = com.sun.star.drawing.LineJoint.MITER   

RectangleShape.LineStyle = com.sun.star.drawing.LineStyle.SOLID

Page.add(RectangleShape)

In addition to the listed properties, the com.sun.star.drawing.LineStyle service provides options for drawing dotted and dashed lines. For more information, see the OpenOffice.org API reference.

Text Properties (Drawing Objects)

The com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties services can format text in drawing objects. These services relate to individual characters and paragraphs and are described in detail in Text Documents.

The following example inserts text in a rectangle and formats the font com.sun.star.style.CharacterProperties service.

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size
Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000
Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

Page.add(RectangleShape)

RectangleShape.String = "This is a test"
RectangleShape.CharWeight = com.sun.star.awt.FontWeight.BOLD
RectangleShape.CharFontName = "Arial"

This code uses the String-property of the rectangle to insert the text and the CharWeight and CharFontName properties from the com.sun.star.style.CharacterProperties service to format the text font.

The text can only be inserted after the drawing object has been added to the drawing page. You can also use the com.sun.star.drawing.Text service to position and format text in drawing object. The following are some of the important properties of this service:

TextAutoGrowHeight (Boolean)
adapts the height of the drawing element to the text it contains
TextAutoGrowWidth (Boolean)
adapts the width of the drawing element to the text it contains
TextHorizontalAdjust (Enum)
horizontal position of text within the drawing element (default values in accordance with com.sun.star.drawing.TextHorizontalAdjust)
TextVerticalAdjust (Enum)
vertical position of text within the drawing element (default values in accordance with com.sun.star.drawing.TextVerticalAdjust)
TextLeftDistance (Long)
left-hand distance between drawing element and text in hundredths of a millimeter
TextRightDistance (Long)
right-hand distance between drawing element and text in hundredths of a millimeter
TextUpperDistance (Long)
upper distance between drawing element and text in hundredths of a millimeter
TextLowerDistance (Long)
lower distance between drawing element and text in hundredths of a millimeter

The following example demonstrates use of the named properties.

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

Page.add(RectangleShape)

RectangleShape.String = "This is a test"   ' May only take place after Page.add!

RectangleShape.TextVerticalAdjust = com.sun.star.drawing.TextVerticalAdjust.TOP
RectangleShape.TextHorizontalAdjust = com.sun.star.drawing.TextHorizontalAdjust.LEFT

RectangleShape.TextLeftDistance = 300
RectangleShape.TextRightDistance = 300
RectangleShape.TextUpperDistance = 300
RectangleShape.TextLowerDistance = 300

This code inserts a drawing element in a page and then adds text to the top left corner of the drawing object using the TextVerticalAdjust and TextHorizontalAdjust properties. The minimum distance between the text edge of the drawing object is set to three millimeters.

Shadow Properties

You can add a shadow to most drawing objects with the com.sun.star.drawing.ShadowProperties service. The properties of this service are:

Shadow (Boolean)
activates the shadow
ShadowColor (Long)
shadow color
ShadowTransparence (Short)
transparency of the shadow
ShadowXDistance (Long)
vertical distance of the shadow from the drawing object in hundredths of a millimeter
ShadowYDistance (Long)
horizontal distance of the shadow from the drawing object in hundredths of a millimeter

The following example creates a rectangle with a shadow that is vertically and horizontally offset from the rectangle by 2 millimeters. The shadow is rendered in dark gray with 50 percent transparency.

Dim Doc As Object
Dim Page As Object
Dim RectangleShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.Shadow = True
RectangleShape.ShadowColor = RGB(192,192,192)
RectangleShape.ShadowTransparence = 50
RectangleShape.ShadowXDistance = 200 
RectangleShape.ShadowYDistance = 200

Page.add(RectangleShape)

An Overview of Various Drawing Objects

Rectangle Shapes

Rectangle shape objects (com.sun.star.drawing.RectangleShape) support the following services for formatting objects:

Fill properties
com.sun.star.drawing.FillProperties
Line properties
com.sun.star.drawing.LineProperties
Text properties
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties)
Shadow properties
com.sun.star.drawing.ShadowProperties
CornerRadius (Long)
radius for rounding corners in hundredths of a millimeter

Circles and Ellipses

The Service com.sun.star.drawing.EllipseShape service is responsible for circles and ellipses and supports the following services:

Fill properties
com.sun.star.drawing.FillProperties
Line properties
com.sun.star.drawing.LineProperties
Text properties
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties)
Shadow properties
com.sun.star.drawing.ShadowProperties

In addition to these services, circles and ellipses also provide these properties:

CircleKind (Enum)
type of circle or ellipse (default values in accordance with com.sun.star.drawing.CircleKind )
CircleStartAngle (Long)
start angle in tenths of a degree (only for circle or ellipse segments)
CircleEndAngle (Long)
end angle in tenths of a degree (only for circle or ellipse segments)

The CircleKind property determines if an object is a complete circle, a circular slice, or a section of a circle. The following values are available:

com.sun.star.drawing.CircleKind.FULL
full circle or full ellipse
com.sun.star.drawing.CircleKind.CUT
section of circle (partial circle whose interfaces are linked directly to one another)
com.sun.star.drawing.CircleKind.SECTION
circle slice
com.sun.star.drawing.CircleKind.ARC
angle (not including circle line)

The following example creates a circular slice with a 70 degree angle (produced from difference between start angle of 20 degrees and end angle of 90 degrees)

Dim Doc As Object
Dim Page As Object
Dim EllipseShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

EllipseShape = Doc.createInstance("com.sun.star.drawing.EllipseShape")
EllipseShape.Size = Size
EllipseShape.Position = Point

EllipseShape.CircleStartAngle = 2000
EllipseShape.CircleEndAngle = 9000
EllipseShape.CircleKind =  com.sun.star.drawing.CircleKind.SECTION

Page.add(EllipseShape)

Lines

OpenOffice.org provides the com.sun.star.drawing.LineShape service for line objects. Line objects support all of the general formatting services with the exception of areas. The following are all of the properties that are associated with the LineShape service:

Line properties
com.sun.star.drawing.LineProperties
Text properties
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties)
Shadow properties
com.sun.star.drawing.ShadowProperties

The following example creates and formats a line with the help of the named properties. The origin of the line is specified in the Location property, whereas the coordinates listed in the Size property specify the end point of the line.

Dim Doc As Object
Dim Page As Object
Dim LineShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)
 
LineShape = Doc.createInstance("com.sun.star.drawing.LineShape")
LineShape.Size = Size
LineShape.Position = Point

Page.add(LineShape)

Polypolygon Shapes

OpenOffice.org also supports complex polygonal shapes through the com.sun.star.drawing.PolyPolygonShape service. Strictly speaking, a PolyPolygon is not a simple polygon but a multiple polygon. Several independent lists containing corner points can therefore be specified and combined to form a complete object.

As with rectangle shapes, all the formatting properties of drawing objects are also provided for polypolygons:

Fill properties
com.sun.star.drawing.FillProperties
Line properties
com.sun.star.drawing.LineProperties
Text properties
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties)
Shadow properties
com.sun.star.drawing.ShadowProperties

The PolyPolygonShape service also has a property that lets you define the coordinates of a polygon:

  • PolyPolygon (Array) – field containing the coordinates of the polygon (double array with points of the com.sun.star.awt.Point type)

The following example shows how you can define a triangle with the PolyPolygonShape service.

Dim Doc As Object
Dim Page As Object
Dim PolyPolygonShape As Object
Dim PolyPolygon As Variant
Dim Coordinates(2) As New com.sun.star.awt.Point

Doc = ThisComponent
Page = Doc.DrawPages(0)

PolyPolygonShape = Doc.createInstance("com.sun.star.drawing.PolyPolygonShape")
Page.add(PolyPolygonShape)   ' Page.add must take place before the coordinates are set

Coordinates(0).x = 1000
Coordinates(1).x = 7500
Coordinates(2).x = 10000
Coordinates(0).y = 1000
Coordinates(1).y = 7500
Coordinates(2).y = 5000

PolyPolygonShape.PolyPolygon = Array(Coordinates())

Since the points of a polygon are defined as absolute values, you do not need to specify the size or the start position of a polygon. Instead, you need to create an array of the points, package this array in a second array (using the Array(Coordinates()) call), and then assign this array to the polygon. Before the corresponding call can be made, the polygon must be inserted into the document.

The double array in the definition allows you to create complex shapes by merging several polygons. For example, you can create a rectangle and then insert another rectangle inside it to create a hole in the original rectangle:

Dim Doc As Object
Dim Page As Object
Dim PolyPolygonShape As Object
Dim PolyPolygon As Variant
Dim Square1(3) As New com.sun.star.awt.Point
Dim Square2(3) As New com.sun.star.awt.Point
Dim Square3(3) As New com.sun.star.awt.Point

Doc = ThisComponent
Page = Doc.DrawPages(0)

PolyPolygonShape = Doc.createInstance("com.sun.star.drawing.PolyPolygonShape")

Page.add(PolyPolygonShape)   ' Page.add must take place before the coordinates are set

Square1(0).x = 5000
Square1(1).x = 10000
Square1(2).x = 10000
Square1(3).x = 5000
Square1(0).y = 5000
Square1(1).y = 5000
Square1(2).y = 10000
Square1(3).y = 10000

Square2(0).x = 6500
Square2(1).x = 8500
Square2(2).x = 8500
Square2(3).x = 6500
Square2(0).y = 6500
Square2(1).y = 6500
Square2(2).y = 8500
Square2(3).y = 8500

Square3(0).x = 6500
Square3(1).x = 8500
Square3(2).x = 8500
Square3(3).x = 6500
Square3(0).y = 9000
Square3(1).y = 9000
Square3(2).y = 9500
Square3(3).y = 9500

PolyPolygonShape.PolyPolygon = Array(Square1(), Square2(), Square3())

With respect as to which areas are filled and which areas are holes, OpenOffice.org applies a simple rule: the edge of the outer shape is always the outer border of the polypolygon. The next line inwards is the inner border of the shape and marks the transition to the first hole. If there is another line inwards, it marks the transition to a filled area.

Graphics

The last of the drawing elements presented here are graphic objects that are based on the com.sun.star.drawing.GraphicObjectShape service. These can be used with any graphic within OpenOffice.org whose appearance can be adapted using a whole range of properties.

Graphic objects support two of the general formatting properties:

Text properties
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and com.sun.star.style.ParagraphProperties)
Shadow properties
com.sun.star.drawing.ShadowProperties

Additional properties that are supported by graphic objects are:

GraphicURL (String)
URL of the graphic
AdjustLuminance (Short)
luminance of the colors, as a percentage (negative values are also permitted)
AdjustContrast (Short)
contrast as a percentage (negative values are also permitted)
AdjustRed (Short)
red value as a percentage (negative values are also permitted)
AdjustGreen (Short)
green value as a percentage (negative values are also permitted)
AdjustBlue (Short)
blue value as a percentage (negative values are also permitted)
Gamma (Short)
gamma value of a graphic
Transparency (Short)
transparency of a graphic as a percentage
GraphicColorMode (enum)
color mode, for example, standard, gray stages, black and white (default value in accordance with com.sun.star.drawing.ColorMode )

The following example shows how to insert a page into a graphics object.

Dim Doc As Object
Dim Page As Object
Dim GraphicObjectShape As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size

Point.x = 1000         ' specifications, insignificant because latter
                       coordinates are binding
Point.y = 1000
Size.Width = 10000
Size.Height = 10000

Doc = ThisComponent
Page = Doc.DrawPages(0)

GraphicObjectShape = Doc.createInstance("com.sun.star.drawing.GraphicObjectShape")

GraphicObjectShape.Size = Size
GraphicObjectShape.Position = Point
 
GraphicObjectShape.GraphicURL = "file:///c:/test.jpg"
GraphicObjectShape.AdjustBlue = -50
GraphicObjectShape.AdjustGreen = 5
GraphicObjectShape.AdjustBlue = 10
GraphicObjectShape.AdjustContrast = 20
GraphicObjectShape.AdjustLuminance = 50
GraphicObjectShape.Transparency = 40
GraphicObjectShape.GraphicColorMode = com.sun.star.drawing.ColorMode.STANDARD

Page.add(GraphicObjectShape)

This code inserts the test.jpg graphic and adapts its appearance using the Adjust properties. In this example, the graphics are depicted as 40 percent transparent with no other color conversions do not take place (GraphicColorMode = STANDARD).


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