Chapter 8 Drawings and Presentations

This chapter provides an introduction to the macro-controlled creation and editing of drawings. The first section describes the structure of drawings, including the basic elements that contain drawings. The second section addresses more complex editing functions, such as grouping, rotating, and scaling objects.

Information about creating, opening, and saving drawings can be found in Chapter 5, Working with StarOffice Documents.

The Structure of Drawings

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

This picture is slightly complicated by the presence of layers. By default, each drawing document contains the Layout, Controls, and Dimension Lines layers and all drawing elements are added to the Layout layer. You also have the option to add new layers. See the StarOffice Developer's Guide for more information about drawing layers.

Pages

The pages of a drawing document are available through the DrawPages list. 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:

Dim Doc As Object
Dim Page As Object

Doc = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)

Example 2:

Dim Doc As Object
Dim Page As Object

Doc = StarDesktop.CurrentComponent
Page = Doc.drawPages.getByName("Slide 1")

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

Dim sUrl As String, sFilter As String
Dim sOptions As String
Dim oSheets As Object, oSheet As Object

   oSheets = oDocument.Sheets

   If oSheets.hasByName("Link") Then
      oSheet = oSheets.getByName("Link")
   Else
      oSheet = oDocument.createInstance("com.sun.star.sheet.Spreadsheet")
      oSheets.insertByName("Link", oSheet)
      oSheet.IsVisible = False
   End If

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 = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)

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

Page.Width = 20000
Page.Height = 20000

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.

StarOffice 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 = StarDesktop.CurrentComponent
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)

This example uses the StarDesktop.CurrentComponent call to determine which document is open. The document object determined this way returns the first page of the drawing through the drawPages(0) call.

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.

StarOffice 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 = StarDesktop.CurrentComponent
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 StarOffice 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 StarOffice Basic, you can also specify values higher than 100 percent)

• EndIntensity (Short) - intensity of EndColor as a percentage (in StarOffice Basic, you can also specify values higher than 100 percent)

• StepCount (Short) - number of color graduations which StarOffice 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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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 StarOffice, 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 StarOffice 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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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 StarOffice 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 Chapter 6 (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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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

StarOffice 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 = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)

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

Page.add(LineShape)

Polypolygon Shapes

StarOffice 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 = StarDesktop.CurrentComponent
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 = StarDesktop.CurrentComponent
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, StarOffice 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 StarOffice 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 = StarDesktop.CurrentComponent
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).

Editing Drawing Objects

Grouping Objects

In many situations, it is useful to group several individual drawing objects together so that they behave as a single large object.

The following example combines two drawing objects:

Dim Doc As Object
Dim Page As Object
Dim Square As Object
Dim Circle As Object
Dim Shapes As Object
Dim Group As Object
Dim Point As New com.sun.star.awt.Point
Dim Size As New com.sun.star.awt.Size
Dim NewPos As New com.sun.star.awt.Point
Dim Height As Long
Dim Width As Long

Doc = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)
Point.x = 3000
Point.y = 3000
Size.Width = 3000
Size.Height = 3000
' create square drawing element
Square = Doc.createInstance("com.sun.star.drawing.RectangleShape")
Square.Size = Size
Square.Position = Point
Square.FillColor = RGB(255,128,128) 
Page.add(Square)
' create circle drawing element
Circle = Doc.createInstance("com.sun.star.drawing.EllipseShape")
Circle.Size = Size
Circle.Position = Point
Circle.FillColor = RGB(255,128,128) 
Circle.FillColor = RGB(0,255,0)
Page.add(Circle)
' combine square and circle drawing elements
Shapes = createUnoService("com.sun.star.drawing.ShapeCollection")
Shapes.add(Square)
Shapes.add(Circle)
Group = Page.group(Shapes)
' centre combined drawing elements
Height = Page.Height
Width = Page.Width
NewPos.X = Width / 2
NewPos.Y = Height / 2
Height = Group.Size.Height
Width = Group.Size.Width
NewPos.X = NewPos.X - Width / 2
NewPos.Y = NewPos.Y - Height / 2
Group.Position = NewPos

This code creates a rectangle and a circle and inserts them into a page. It then creates an object that supports the com.sun.star.drawing.ShapeCollection service and uses the Add method to add the rectangle and the circle to this object. The ShapeCollection is added to the page using the Group method and returns the actual Group object that can be edited like an individual Shape.

If you want to format the individual objects of a group, apply the formatting before you add them to the group. You cannot modify the objects once they are in the group.

Rotating and Shearing Drawing Objects

All of the drawing objects that are described in the previous sections can also be rotated and sheared using the com.sun.star.drawing.RotationDescriptor service.

The service provides the following properties:

• RotateAngle (Long) – rotary angle in hundredths of a degree

• ShearAngle (Long) – shear angle in hundredths of a degree

The following example creates a rectangle and rotates it by 30 degrees using the RotateAngle property:

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 = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)

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

RectangleShape.RotateAngle = 3000

Page.add(RectangleShape)

The next example creates the same rectangle as in the previous example, but instead shears it through 30 degrees using the ShearAngle property.

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 = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")
RectangleShape.Size = Size
RectangleShape.Position = Point

RectangleShape.ShearAngle = 3000

Page.add(RectangleShape)

Searching and Replacing

As in text documents, drawing documents provide a function for searching and replace. This function is similar to the one that is used in text documents as described in Chapter 6, Text Documents. However, in drawing documents the descriptor objects for searching and replacing are not created directly through the document object, but rather through the associated character level. The following example outlines the replacement process within a drawing:

Dim Doc As Object
Dim Page As Object
Dim ReplaceDescriptor As Object
Dim I As Integer

Doc = StarDesktop.CurrentComponent
Page = Doc.drawPages(0)

ReplaceDescriptor = Page.createReplaceDescriptor()
ReplaceDescriptor.SearchString = "is"
ReplaceDescriptor.ReplaceString = "was"

For I = 0 to Doc.drawPages.Count - 1
   Page = Doc.drawPages(I)
   Page.ReplaceAll(ReplaceDescriptor) 
Next I

This code uses the first DrawPage of the document to create a ReplaceDescriptor and then applies this descriptor in a loop to all of the pages in the drawing document.

Presentations

StarOffice presentations are based on drawing documents. Each page in the presentation is a slide. You can access slides in the same way as a standard drawing is accessed through the DrawPages list of the document object. The com.sun.star.presentation.PresentationDocument service, responsible for presentation documents, also provides the complete com.sun.star.drawing.DrawingDocument service.

Working With Presentations

In addition to the drawing functions that are provided by the Presentation property, the presentation document has a presentation object that provides access to the main properties and control mechanisms for presentations. For example, this object provides a start method that can start presentations.

Dim Doc As Object
Dim Presentation As Object
   
Doc = StarDesktop.CurrentComponent
Presentation = Doc.Presentation
Presentation.start()

The code used in this example creates a Doc object that references the current presentation document and establishes the associated presentation object. The start() method of the object is used to start the example and run the screen presentation.

The following methods are provided as presentation objects:

• start - starts the presentation

• end - ends the presentation

• rehearseTimings - starts the presentation from the beginning and establishes its runtime

The following properties are also available:

• AllowAnimations (Boolean)– runs animations in the presentation

• CustomShow (String) – allows you to specify the name of the presentation so that you can reference the name in the presentation

• FirstPage (String) – name of slide that you want to start the presentation with

• IsAlwaysOnTop (Boolean) – always displays the presentation window as the first window on the screen

• IsAutomatic (Boolean) – automatically runs through the presentation

• IsEndless (Boolean) – restarts the presentation from the beginning once it ends

• IsFullScreen (Boolean) – automatically starts the presentation in full screen mode

• IsMouseVisible (Boolean) – displays the mouse during the presentation

• Pause (long) – the amount of time that a blank screen is displayed at the end of the presentation

• StartWithNavigator (Boolean) – displays the navigator window when the presentation starts

• UsePn (Boolean) – displays the pointer during the presentation