View source for Documentation/BASIC Guide/Structure of Drawings

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Drawings Presentations
|NextPage=Documentation/BASIC Guide/Editing Drawing Objects
|draw=block
}}
{{DISPLAYTITLE:The Structure of Drawings}}

== Pages ==

{{Documentation/Tip|A Draw (or Impress) document is composed of pages, also called slides. What is written here also applies to Impress documents.}}

{{OOo}} 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 <tt>DrawPages</tt> 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)'''

<source lang="oobas">
Dim Doc As Object
Dim Page As Object

Doc = ThisComponent
Page = Doc.DrawPages(0)
</source>

{{Documentation/Note|The expression <code>Doc.DrawPages(0)</code> is a Basic simplification of the API call : <code>Doc.getDrawPages.getByIndex(0)</code>}}

'''Example 2: access by means of the name'''

<source lang="oobas">
Dim Doc As Object
Dim Page As Object

Doc = ThisComponent
Page = Doc.DrawPages.getByName("Slide 1")
</source>

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 <tt>getByName</tt> method.

=== Properties of a page ===

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

;<tt>BorderLeft (Long)</tt>:left-hand border in hundredths of a millimeter
;<tt>BorderRight (Long)</tt>:right-hand border in hundredths of a millimeter
;<tt>BorderTop (Long)</tt>:top border in hundredths of a millimeter
;<tt>BorderBottom (Long)</tt>:bottom border in hundredths of a millimeter
;<tt>Width (Long)</tt>:page width in hundredths of a millimeter
;<tt>Height (Long)</tt>:page height in hundredths of a millimeter
;<tt>Number (Short)</tt>:number of pages (numbering begins at 1), read-only
;<tt>Orientation (Enum)</tt>:page orientation (in accordance with <tt>com.sun.star.view.PaperOrientation</tt> 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:

<source lang="oobas">
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
</source>

=== 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.

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 <code>getName</code> and <code>setName</code> to read and modify its name. Basic can handle both methods like a property <code>Name</code>. Here we rename the first page of the drawing document.

<source lang="oobas">
Dim Doc As Object
Dim Page As Object
 
Doc = ThisComponent
Page = Doc.DrawPages(0)
Page.Name = "First"
</source>

=== Creating and Deleting Pages ===

The <tt>DrawPages</tt> container of a <tt>drawing</tt> document is also used to create and delete individual pages. The following example uses the <tt>hasByName</tt> method to check if a page called '''MyPage''' exists. If it does, the method determines a corresponding object reference by using the <tt>getByName</tt> method and then saves the reference in a variable in <tt>Page</tt>. If the corresponding page does not exist, it is created and inserted in the drawing document by the <tt>insertNewByIndex</tt> 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.

<source lang="oobas">
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
</source>

The <tt>hasByName</tt> and <tt>getByName</tt> methods are obtained from the <idl>com.sun.star.container.XNameAccess</idl> interface. 

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

<source lang="oobas">
Dim Doc As Object
 
Doc = ThisComponent

If Doc.Drawpages.hasByName("MyPage") Then
   Page = Doc.Drawpages.getByName("MyPage")
   Doc.Drawpages.remove(Page)
End If
</source>

=== 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 <code>duplicate</code>. The copy is created at the next position after the original page, with a default name.

<source lang="oobas">
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
</source>

=== 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 <tt>com.sun.star.drawing.Shape</tt> service. This service defines the <tt>Size</tt> and <tt>Position</tt> properties of a drawing object.

{{OOo}} 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:

<source lang="oobas">
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)
</source>

The <tt>Point</tt> and <tt>Size</tt> 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 <tt>Doc.createInstance</tt> call to create the rectangle drawing object as specified by the <idl>com.sun.star.drawing.RectangleShape</idl> service. At the end, the drawing object is assigned to a page using a <tt>Page.add</tt> 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 <idl>com.sun.star.drawing.FillProperties</idl> service.

{{OOo}} 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 <tt>FillStyle</tt> property. The permissible values are defined in <idl>com.sun.star.drawing.FillStyle</idl>.

=== Single Color Fills ===

The main property for single-color fills is:

;<tt>FillColor (Long)</tt>:fill color of area

To use the fill mode, you must the <tt>FillStyle</tt> property to the <tt>SOLID</tt> fill mode.

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

<source lang="oobas">
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)
</source>

=== Color Gradient ===

If you set the <tt>FillStyle</tt> property to <tt>GRADIENT</tt>, you can apply a color gradient to any fill area of a {{OOo}} document.

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

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

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

<source lang="oobas">
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)
</source>

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

=== Hatches ===

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

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

The following example demonstrates the use of a hatch structure:

<source lang="oobas">
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)
</source>

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

=== Bitmaps ===

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

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

The following example creates a rectangle and tiles the Sky bitmap that is available in {{OOo}} to fill the area of the rectangle:

<source lang="oobas">
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)
</source>

=== 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 <tt>FillTransparence</tt> property.

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

<source lang="oobas">
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)
</source>

To make the fill transparent, set the <tt>FillTransparence</tt> property to 100.

In addition to the <tt>FillTransparence</tt> property, the <idl>com.sun.star.drawing.FillProperties</idl> service also provides the <tt>FillTransparenceGradient</tt> 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 <idl>com.sun.star.drawing.LineStyle</idl> service. Some of the properties that this service provides are:

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

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

<source lang="oobas">
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)
</source>

In addition to the listed properties, the <idl>com.sun.star.drawing.LineStyle</idl> service provides options for drawing dotted and dashed lines. For more information, see the {{OOo}} API reference.

=== Text Properties (Drawing Objects) ===

The <idl>com.sun.star.style.CharacterProperties</idl> and <idl>com.sun.star.style.ParagraphProperties</idl> services can format text in drawing objects. These services relate to individual characters and paragraphs and are described in detail in [[Documentation/BASIC Guide/Text Documents|Text Documents]].

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

<source lang="oobas">
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"
</source>

This code uses the <tt>String</tt>-property of the rectangle to insert the text and the <tt>CharWeight</tt> and <tt>CharFontName</tt> properties from the <idl>com.sun.star.style.CharacterProperties</idl> 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 <idl>com.sun.star.drawing.Text</idl> service to position and format text in drawing object. The following are some of the important properties of this service:

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

The following example demonstrates use of the named properties.

<source lang="oobas">
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
</source>

This code inserts a drawing element in a page and then adds text to the top left corner of the drawing object using the <tt>TextVerticalAdjust</tt> and <tt>TextHorizontalAdjust</tt> 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 <idl>com.sun.star.drawing.ShadowProperties</idl> service. The properties of this service are:

;<tt>Shadow (Boolean)</tt>:activates the shadow
;<tt>ShadowColor (Long)</tt>:shadow color
;<tt>ShadowTransparence (Short)</tt>:transparency of the shadow
;<tt>ShadowXDistance (Long)</tt>:vertical distance of the shadow from the drawing object in hundredths of a millimeter
;<tt>ShadowYDistance (Long)</tt>: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.

<source lang="oobas">
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)
</source>

== An Overview of Various Drawing Objects ==

=== Rectangle Shapes ===

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

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

=== Circles and Ellipses ===

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

;<tt>Fill properties</tt>:<idl>com.sun.star.drawing.FillProperties</idl>
;<tt>Line properties</tt>:<idl>com.sun.star.drawing.LineProperties</idl>
;<tt>Text properties</tt>:<idl>com.sun.star.drawing.Text</idl> (with <idl>com.sun.star.style.CharacterProperties</idl> and <idl>com.sun.star.style.ParagraphProperties</idl>)
;<tt>Shadow properties</tt>:<idl>com.sun.star.drawing.ShadowProperties</idl>

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

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

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

;<idl>com.sun.star.drawing.CircleKind.FULL</idl>:full circle or full ellipse
;<idl>com.sun.star.drawing.CircleKind.CUT</idl>:section of circle (partial circle whose interfaces are linked directly to one another)
;<idl>com.sun.star.drawing.CircleKind.SECTION</idl>:circle slice
;<idl>com.sun.star.drawing.CircleKind.ARC</idl>: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)

<source lang="oobas">
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)
</source>

=== Lines ===

{{OOo}} provides the <idl>com.sun.star.drawing.LineShape</idl> 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 <tt>LineShape</tt> service:

;<tt>Line properties</tt>:<idl>com.sun.star.drawing.LineProperties</idl>
;<tt>Text properties</tt>:<idl>com.sun.star.drawing.Text</idl> (with <idl>com.sun.star.style.CharacterProperties</idl> and <idl>com.sun.star.style.ParagraphProperties</idl>)
;<tt>Shadow properties</tt>:<idl>com.sun.star.drawing.ShadowProperties</idl>

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

<source lang="oobas">
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)
</source>

=== Polypolygon Shapes ===

{{OOo}} also supports complex polygonal shapes through the <idl>com.sun.star.drawing.PolyPolygonShape</idl> 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:

;<tt>Fill properties</tt>:<idl>com.sun.star.drawing.FillProperties</idl>
;<tt>Line properties</tt>:<idl>com.sun.star.drawing.LineProperties</idl>
;<tt>Text properties</tt>:<idl>com.sun.star.drawing.Text</idl> (with <idl>com.sun.star.style.CharacterProperties</idl> and <idl>com.sun.star.style.ParagraphProperties</idl>)
;<tt>Shadow properties</tt>:<idl>com.sun.star.drawing.ShadowProperties</idl>

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

* <tt>PolyPolygon (Array)</tt> – field containing the coordinates of the polygon (double array with points of the <idl>com.sun.star.awt.Point</idl> type)

The following example shows how you can define a triangle with the <tt>PolyPolygonShape</tt> service.

<source lang="oobas">
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())
</source>

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 <tt>Array(Coordinates())</tt> 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:

<source lang="oobas">
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())
</source>

With respect as to which areas are filled and which areas are holes, {{OOo}} 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 <idl>com.sun.star.drawing.GraphicObjectShape</idl> service. These can be used with any graphic within {{OOo}} whose appearance can be adapted using a whole range of properties.

Graphic objects support two of the general formatting properties:

;<tt>Text properties</tt>:<idl>com.sun.star.drawing.Text</idl> (with <idl>com.sun.star.style.CharacterProperties</idl> and <idl>com.sun.star.style.ParagraphProperties</idl>)
;<tt>Shadow properties</tt>:<idl>com.sun.star.drawing.ShadowProperties</idl>

Additional properties that are supported by graphic objects are:

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

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

<source lang="oobas">
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)
</source>

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

 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Structure of Drawings}}
{{PDL1}}