LibreOffice Developer's Guide: Chapter 9 - Drawing Documents and Presentation Documents

From The Document Foundation Wiki
Jump to navigation Jump to search

Draw and Impress are vector-oriented applications with the ability to create drawings and presentations. The drawing capabilities of Draw and Impress are identical. Both programs support a number of different shape types, such as rectangle, text, curve, or graphic shapes, that can be edited and arranged in various ways. Impress offers a presentation functionality where Draw does not. Impress is the ideal application to create and show presentations. It supports special presentation features, such as an enhanced page structure, presentation objects, and many slide transition and object effects. Draw is especially adapted for printed or standalone graphics, whereas Impress is optimized to fit screen dimensions and offers effects for business presentations.

The following diagrams show the document structure of Draw and Impress Documents.

In contrast to text documents and spreadsheet documents, the main content of drawing and presentation documents are their draw pages. Therefore the illustrations show the draw page container as integral part of the drawing and presentation document model. The drawing elements on the draw pages have to be created by the document service manager and are added to the draw pages afterwards.

Note the master pages and the layer manager, which are specific to drawings and presentations. Like for texts and spreadsheets, a controller is used to present the drawing in the GUI and services for styles and layout are available to handle overall document features such as styles.

Drawing Document Overview

In addition to drawing documents, a presentation document has special presentation aspects, which are shown on the lower left of the illustration below. There is a presentation supplier to obtain a presentation object, which is used to start and stop presentations, it is possible to edit and run custom presentations and the page layout for presentation handouts is accessible through a handout master supplier.

Presentation Document Overview

Example: Creating a Simple Organizational Chart

The following example creates a simple organizational chart with two levels. It consists of five rectangle shapes and four connectors that connect the boxes on the second level with the root box on the first level.

Sample Organigram

The method getRemoteServiceManager() that is used in the example connects to the office. The First Steps discussed this method. First an empty drawing document is loaded and retrieves the draw page object of slide number 1 to find the page dimensions. Then the organigram data is prepared and the shape sizes are calculated. The shapes are added in a for loop that iterates over the organigram data, and connectors are added for all shapes on the second level of the organigram.

public void drawOrganigram() throws java.lang.Exception {
    xRemoteServiceManager = this.getRemoteServiceManager(
        "uno:socket,host=localhost,port=2083;urp;StarOffice.ServiceManager");
    Object desktop = xRemoteServiceManager.createInstanceWithContext(
        "com.sun.star.frame.Desktop", xRemoteContext);
    XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface(
        XComponentLoader.class, desktop);
    PropertyValue[] loadProps = new PropertyValue[0];
    XComponent xDrawComponent = xComponentLoader.loadComponentFromURL(
        "private:factory/sdraw", "_blank", 0, loadProps);

    // get draw page by index
    com.sun.star.drawing.XDrawPagesSupplier xDrawPagesSupplier =
        (com.sun.star.drawing.XDrawPagesSupplier)
            UnoRuntime.queryInterface(
    com.sun.star.drawing.XDrawPagesSupplier.class, xDrawComponent );
    com.sun.star.drawing.XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
    Object drawPage = xDrawPages.getByIndex(0);
    com.sun.star.drawing.XDrawPage xDrawPage = (com.sun.star.drawing.XDrawPage)
        UnoRuntime.queryInterface(
            com.sun.star.drawing.XDrawPage.class, drawPage);

    // find out page dimensions
    com.sun.star.beans.XPropertySet xPageProps = (com.sun.star.beans.XPropertySet)
        UnoRuntime.queryInterface(
            com.sun.star.beans.XPropertySet.class, xDrawPage);
    int pageWidth = AnyConverter.toInt(xPageProps.getPropertyValue("Width"));
    int pageHeight = AnyConverter.toInt(xPageProps.getPropertyValue("Height"));
    int pageBorderTop = AnyConverter.toInt(xPageProps.getPropertyValue("BorderTop"));
    int pageBorderLeft = AnyConverter.toInt(xPageProps.getPropertyValue("BorderLeft"));
    int pageBorderRight = AnyConverter.toInt(xPageProps.getPropertyValue("BorderRight"));
    int drawWidth = pageWidth - pageBorderLeft - pageBorderRight;
    int horCenter = pageBorderLeft + drawWidth / 2;

    // data for organigram
    String[][] orgUnits = new String[2][4];
    orgUnits[0][0] = "Management"; // level 0
    orgUnits[1][0] = "Production"; // level 1
    orgUnits[1][1] = "Purchasing"; // level 1
    orgUnits[1][2] = "IT Services"; // level 1
    orgUnits[1][3] = "Sales"; // level 1
    int[] levelCount = {1, 4};

    // calculate shape sizes and positions
    int horSpace = 300;
    int verSpace = 3000;
    int shapeWidth = (drawWidth - (levelCount[1] - 1) * horSpace) / levelCount[1];
    int shapeHeight = pageHeight / 20;
    int shapeX = pageWidth / 2 - shapeWidth / 2;
    int levelY = 0;
    com.sun.star.drawing.XShape xStartShape = null;
    // get document factory
    com.sun.star.lang.XMultiServiceFactory xDocumentFactory = (com.sun.star.lang.XMultiServiceFactory)
        UnoRuntime.queryInterface(
            com.sun.star.lang.XMultiServiceFactory.class, xDrawComponent);
    // creating and adding RectangleShapes and Connectors
    for (int level = 0; level <= 1; level++) {
        levelY = pageBorderTop + 2000 + level * (shapeHeight + verSpace);
        for (int i = levelCount[level] - 1; i > -1; i--) {
            shapeX = horCenter -
                    (levelCount[level] * shapeWidth + (levelCount[level] - 1) * horSpace) / 2 +
                    i * shapeWidth + i * horSpace;
            Object shape = xDocumentFactory.createInstance("com.sun.star.drawing.RectangleShape");
            com.sun.star.drawing.XShape xShape = (com.sun.star.drawing.XShape)
                UnoRuntime.queryInterface(
                    com.sun.star.drawing.XShape.class, shape);
            xShape.setPosition(new com.sun.star.awt.Point(shapeX, levelY));
            xShape.setSize(new com.sun.star.awt.Size(shapeWidth, shapeHeight));
            xDrawPage.add(xShape);

            // set the text
            com.sun.star.text.XText xText = (com.sun.star.text.XText)
                UnoRuntime.queryInterface(
                    com.sun.star.text.XText.class, xShape);
            xText.setString(orgUnits[level][i]);
            // memorize the root shape, for connectors
            if (level == 0 && i == 0)
                xStartShape = xShape;

            // add connectors for level 1
            if (level == 1) {
                Object connector = xDocumentFactory.createInstance(
                    "com.sun.star.drawing.ConnectorShape");
                com.sun.star.drawing.XShape xConnector = (com.sun.star.drawing.XShape)
                    UnoRuntime.queryInterface(
                com.sun.star.drawing.XShape.class, connector);
                xDrawPage.add(xConnector);
                com.sun.star.beans.XPropertySet xConnectorProps = (com.sun.star.beans.XPropertySet)
                    UnoRuntime.queryInterface(
                        com.sun.star.beans.XPropertySet.class, connector);
                xConnectorProps.setPropertyValue("StartShape", xStartShape);
                xConnectorProps.setPropertyValue("EndShape", xShape);
                // glue point positions: 0=top 1=left 2=bottom 3=right
                xConnectorProps.setPropertyValue("StartGluePointIndex", new Integer(2));
                xConnectorProps.setPropertyValue("EndGluePointIndex", new Integer(0));
            }

        }
    }
}

Handling Drawing Document Files

Creating and Loading Drawing Documents

If a document in LibreOffice is required, begin by getting the <idl>com.sun.star.frame.Desktop</idl> service from the service manager. The desktop handles all document components in LibreOffice among other things. It is discussed thoroughly in the chapter Office Development. Office documents are often called components because they support the <idl>com.sun.star.lang.XComponent</idl> interface. An XComponent is a UNO object that can be disposed explicitly and broadcast an event to other UNO objects when this happens.

The Desktop loads new and existing components from a URL. The desktop has a <idl>com.sun.star.frame.XComponentLoader</idl> interface that has one single method to load and instantiate components from a URL into a frame:

com::sun::star::lang::XComponent loadComponentFromURL( [in] string aURL,
                                    [in] string aTargetFrameName,
                                    [in] long nSearchFlags,
                                    [in] sequence< com::sun::star::beans::PropertyValue > aArgs )

The parameters in our context are the URL that describes the resource to be loaded, and the load arguments. For the target frame pass in "_blank" and set the search flags to 0. In most cases, you will not want to reuse an existing frame.

The URL can be a file: URL, an http: URL, an ftp: URL or a private: URL. The correct URL format is located in the load URL box at the function bar of LibreOffice. For new Draw documents, a special URL scheme is used. The scheme is "private:", followed by "factory" as the hostname and the resource is "sdraw" for LibreOffice Draw documents. Thus, for a new Draw document, use "private:factory/sdraw".

The load arguments are described in <idl>com.sun.star.document.MediaDescriptor</idl>. The properties AsTemplate and Hidden are boolean values and used for programming. If AsTemplate is true, the loader creates a new untitled document from the given URL. If it is false, template files are loaded for editing. If Hidden is true, the document is loaded in the background. This is useful to generate a document in the background without letting the user observe what is happening. For instance, use it to generate a document and print it out without previewing. Refer to Office Development or other available options.

The introductory example shows how to load a drawing document. This snippet loads a new drawing document in hidden mode:

// the method getRemoteServiceManager is described in the chapter First Steps
mxRemoteServiceManager = this.getRemoteServiceManager();

// retrieve the Desktop object, we need its XComponentLoader
Object desktop = mxRemoteServiceManager.createInstanceWithContext(
    "com.sun.star.frame.Desktop", mxRemoteContext);

// query the XComponentLoader interface from the Desktop service
XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface(
    XComponentLoader.class, desktop);

// define load properties according to com.sun.star.document.MediaDescriptor
// the boolean property Hidden tells the office to open a file in hidden mode
PropertyValue[] loadProps = new PropertyValue[1];
loadProps[0] = new PropertyValue();
loadProps[0].Name = "Hidden";
loadProps[0].Value = new Boolean(true);

/* or simply create an empty array of com.sun.star.beans.PropertyValue structs:
    PropertyValue[] loadProps = new PropertyValue[0]
*/

// load
com.sun.star.lang.XComponent xComponentLoader.loadComponentFromURL(
    "private:factory/sdraw", "_blank", 0, loadProps);

Saving Drawing Documents

The normal File – Save command for drawing documents can only store the current document in the native LibreOffice Draw format and its predecessors. There are other formats that can be stored through the File – Export option. This is mirrored in the API. Exporting in the current version of LibreOffice Draw and Impress is a different procedure than storing.

Storing

Documents are storable through their interface <idl>com.sun.star.frame.XStorable</idl>. The Office Development discusses this in detail. An XStorable implements these operations:

boolean hasLocation()
string getLocation()
boolean isReadonly()
void store()
void storeAsURL( [in] string aURL,
    [in] sequence < com::sun::star::beans::PropertyValue > aArgs)
void storeToURL( [in] string aURL,
    [in] sequence < com::sun::star::beans::PropertyValue > aArgs)

The method names should be evident. The method storeAsUrl() is the exact representation of File - Save As, that is, it changes the current document location. In contrast, storeToUrl() stores a copy to a new location, but leaves the current document URL untouched. There are also store arguments. A filter name can be passed that tells LibreOffice to use older StarOffice Draw file formats. Exporting is a different matter as shown below. The property needed is FilterName which is a string argument that takes filter names defined in the configuration file:

 <OfficePath>\share\config\registry\instance\org\openoffice\Office\TypeDetection.xml

In TypeDetection.xml, find <Filter/> elements, their cfg:name attribute contains the required strings for FilterName. The correct filter name for StarDraw 5.x files is "StarDraw 5.0". The following is the element in TypeDetection.xml that describes the StarDraw 5.0 document filter:

<Filter cfg:name="StarDraw 5.0">
    <Installed cfg:type="boolean">true</Installed>
    <UIName cfg:type="string" cfg:localized="true">
        <cfg:value xml:lang="en-US">StarDraw 5.0</cfg:value>
    </UIName>
    <Data cfg:type="string">
        10,draw_StarDraw_50,com.sun.star.drawing.DrawingDocument,,268435559,,5050,,
    </Data>
</Filter>

The following method stores a document using this filter:

/** Store a document, using the StarDraw 5.0 Filter */
protected void storeDocComponent(XComponent xDoc, String storeUrl) throws java.lang.Exception {
    XStorable xStorable = (XStorable)UnoRuntime.queryInterface(XStorable.class, xDoc);
    PropertyValue[] storeProps = new PropertyValue[1];
    storeProps[0] = new PropertyValue();
    storeProps[0].Name = "FilterName";
    storeProps[0].Value = "StarDraw 5.0";
    xStorable.storeAsURL(storeUrl, storeProps);
}

If an empty array of PropertyValue structs is passed, the native .odg format of LibreOffice is used.

Exporting

Exporting is not a feature of drawing documents. There is a separate service available from the global service manager for exporting, <idl>com.sun.star.drawing.GraphicExportFilter</idl>. It supports three interfaces: <idl>com.sun.star.document.XFilter</idl>, <idl>com.sun.star.document.XExporter</idl> and <idl>com.sun.star.document.XMimeTypeInfo</idl>.

GraphicExportFilter

Exporting is a simple process. After getting a GraphicExportFilter from the ServiceManager, use its XExporter interface to inform the filter which draw page, shape or shape collection to export.

Method of com.sun.star.document.XExporter:

void setSourceDocument ( [in] com::sun::star::lang::XComponent xDoc)

The method name setSourceDocument() may be confusing. Actually, the method would allow exporting entire documents, however, it is only possible to export draw pages, single shapes or shape collections from a drawing document. Since these objects support the XComponent interface, the method specification allows maximum flexibility.

Next, run the method filter() at the XFilter interface. To interrupt the exporting process, call cancel() on the same interface.

Methods of com.sun.star.document.XFilter:

boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)
void cancel()

Filter Options

The method filter() takes a sequence of PropertyValue structs describing the filter parameters. The following properties from the <idl>com.sun.star.document.MediaDescriptor</idl> are supported:

Properties of <idl>com.sun.star.document.MediaDescriptor</idl> supported by GraphicExportFilter
<idlm>com.sun.star.document.MediaDescriptor:MediaType</idlm> Depending on the export filters supported by this component, this is the mime type of the target graphic file. The mime types currently supported are:

image/x-MS-bmp application/dxf application/postscript image/gif image/jpeg image/png image/x-pict image/x-pcx image/x-portable-bitmap image/x-portable-graymap image/x-portable-pixmap image/x-cmu-raster image/targa image/tiff image/x-xbitmap image/x-xpixmap image/svg+xml

<idlm>com.sun.star.document.MediaDescriptor:FilterName</idlm> This property can been used if no MediaType exists with "Windows Metafile" or "Enhanced Metafile". FilterName has to be set to the extension of these graphic formats (WMF, EMF, BMP).
<idlm>com.sun.star.document.MediaDescriptor:URL</idlm> The target URL of the file that is created during export.
Note pin.svg

Note:
If necessary, use the interface XMimeTypeInfo to get all mime types supported by the GraphicExportFilter. It offers the following methods:

boolean supportsMimeType( [in] string MimeTypeName )
sequence< string > getSupportedMimeTypeNames()

XMimeTypeInfo is currently not supported by the GraphicExportFilter.

The following example exports a draw page xPage from a given document xDrawDoc:

//get draw pages
com.sun.star.drawing.XDrawPagesSupplier xPageSupplier = (com.sun.star.drawing.XDrawPagesSupplier)
    UnoRuntime.queryInterface(com.sun.star.drawing.XDrawPagesSupplier.class, xDrawDoc);
com.sun.star.drawing.XDrawPages xDrawPages = xPageSupplier.getDrawPages();

// first page
Object page = xDrawPages.getByIndex(0);
com.sun.star.drawing.XDrawPage xPage = (com.sun.star.drawing.XDrawPage)UnoRuntime.queryInterface(
    com.sun.star.drawing.XDrawPage.class, page);

Object GraphicExportFilter = xServiceFactory.createInstance(
    "com.sun.star.drawing.GraphicExportFilter");

// use the XExporter interface to set xPage as source component
// for the GraphicExportFilter
XExporter xExporter = (XExporter)UnoRuntime.queryInterface(
    XExporter.class, GraphicExportFilter );

XComponent xComp = (XComponent)UnoRuntime.queryInterface(XComponent.class, xPage);
xExporter.setSourceDocument(xComp);

// prepare the media descriptor for the filter() method in XFilter
PropertyValue aProps[] = new PropertyValue[2];

aProps[0] = new PropertyValue();
aProps[0].Name = "MediaType";
aProps[0].Value = "image/gif";

// for some graphic formats, e.g. Windows Metafile, there is no Mime type,
// therefore it is also possible to use the property FilterName with
// Filter names as defined in the file TypeDetection.xml (see "Storing")
/* aProps[0].Name = "FilterName";
    aProps[0].Value = "WMF - MS Windows Metafile";
*/

aProps[1] = new PropertyValue();
aProps[1].Name = "URL";
aProps[1].Value = "file:///home/images/page1.gif";

// get XFilter interface and launch the export
XFilter xFilter = (XFilter) UnoRuntime.queryInterface(
    XFilter.class, GraphicExportFilter);
xFilter.filter(aProps);

Printing Drawing Documents

Printer and Print Job Settings

Printing is a common office functionality. Refer to Chapter Office Development for additional information. The Draw document implements the <idl>com.sun.star.view.XPrintable</idl> interface for printing. It consists of three methods:

sequence< com::sun::star::beans::PropertyValue > getPrinter()
void setPrinter(
    [in] sequence< com::sun::star::beans::PropertyValue > aPrinter)
void print(
    [in] sequence< com::sun::star::beans::PropertyValue > xOptions)

To print to the standard printer without settings, use the snippet below with a given document xDoc:

// query the XPrintable interface from your document
XPrintable xPrintable = (XPrintable)UnoRuntime.queryInterface(XPrintable.class, xDoc);

// create an empty printOptions array
PropertyValue[] printOpts = new PropertyValue[0];

// kick off printing
xPrintable.print(printOpts);

There are two groups of properties involved in general printing. The first one is used with setPrinter() and getPrinter(), and controls the printer, the second one is passed to print() and controls the print job.

The method getPrinter() returns a sequence of PropertyValue structs describing the printer containing the properties specified in the service <idl>com.sun.star.view.PrinterDescriptor</idl>. It comprises the following properties:

Properties of <idl>com.sun.star.view.PrinterDescriptor</idl>
<idlm>com.sun.star.view.PrinterDescriptor:Name</idlm> string - Specifies the name of the printer queue to be used.
<idlm>com.sun.star.view.PrinterDescriptor:PaperOrientation</idlm> <idl>com.sun.star.view.PaperOrientation</idl>. Specifies the orientation of the paper.
<idlm>com.sun.star.view.PrinterDescriptor:PaperFormat</idlm> <idl>com.sun.star.view.PaperFormat</idl>. Specifies a predefined paper size or if the paper size is a user-defined size.
<idlm>com.sun.star.view.PrinterDescriptor:PaperSize</idlm> <idl>com.sun.star.awt.Size</idl>. Specifies the size of the paper in 1/100 mm.
<idlm>com.sun.star.view.PrinterDescriptor:IsBusy</idlm> boolean - Indicates if the printer is busy.
<idlm>com.sun.star.view.PrinterDescriptor:CanSetPaperOrientation</idlm> boolean - Indicates if the printer allows changes to PaperOrientation.
<idlm>com.sun.star.view.PrinterDescriptor:CanSetPaperFormat</idlm> boolean - Indicates if the printer allows changes to PaperFormat.
<idlm>com.sun.star.view.PrinterDescriptor:CanSetPaperSize</idlm> boolean - Indicates if the printer allows changes to PaperSize.

The PrintOptions offer the following choices for a print job:

Properties of <idl>com.sun.star.view.PrintOptions</idl>
<idlm>com.sun.star.view.PrintOptions:CopyCount</idlm> short - Specifies the number of copies to print.
<idlm>com.sun.star.view.PrintOptions:FileName</idlm> string - If set, specifies the name of a file to print to.
<idlm>com.sun.star.view.PrintOptions:Collate</idlm> boolean - Advises the printer to collate the pages of the copies. If true, a whole document is printed prior to the next copy, otherwise copies for each page are completed together.
<idlm>com.sun.star.view.PrintOptions:Pages</idlm> string - Specifies the pages to print. It has the same format as in the print dialog of the GUI, for example, 1, 3, 4-7, 9.
<idlm>com.sun.star.view.PrintOptions:Wait</idlm> boolean - Advises that the print job should be performed synchronously, i.e. wait until printing is complete before returning from printing. Otherwise return is immediate and following actions (e.g. closing the corresponding model) may fail until printing is complete. Default is false.

The following method uses PrinterDescriptor and PrintOptions to print to a specific printer, and preselect the pages to print:

The following method uses both, PrinterDescriptor and PrintOptions, to print to a specific printer and preselect the pages to print:

protected void printDocComponent(XComponent xDoc) throws java.lang.Exception {
    XPrintable xPrintable = (XPrintable)UnoRuntime.queryInterface(XPrintable.class, xDoc);
    PropertyValue[] printerDesc = new PropertyValue[1];
    printerDesc[0] = new PropertyValue();
    printerDesc[0].Name = "Name";
    printerDesc[0].Value = "5D PDF Creator";

    xPrintable.setPrinter(printerDesc);

    PropertyValue[] printOpts = new PropertyValue[1];
    printOpts[0] = new PropertyValue();
    printOpts[0].Name = "Pages";
    printOpts[0].Value = "1-4,7";

    xPrintable.print(printOpts);
}

In Draw documents, one slide is printed as one page on the printer by default. In the example above, slide one through four and slide seven are printed.

Special Print Settings

The printed drawing view (drawings, notes, handout pages, outline), the print quality (color, grayscale), the page options (tile, fit to page, brochure, paper tray) and additional options (page name, date, time, hidden pages) can all be controlled. Settings describes how these settings are used.

Working with Drawing Documents

Document Structure

DrawingDocument Structure

Draw documents maintain their drawing content on draw pages, master pages and layers. If a new draw document is opened, it contains one slide that corresponds to a <idl>com.sun.star.drawing.DrawPage</idl> service. Switching to Master View brings up the master page handled by the service <idl>com.sun.star.drawing.MasterPage</idl>. The Layer View allows access to layers to structure your drawings. These layers can be controlled through <idl>com.sun.star.drawing.Layer</idl> and <idl>com.sun.star.drawing.LayerManager</idl>.

Page Handling

Draw and Impress documents supply their pages (slides) through the interface <idl>com.sun.star.drawing.XDrawPagesSupplier</idl>. The method com.sun.star.drawing.XDrawPagesSupplier:getDrawPages() returns a container of draw pages with a <idl>com.sun.star.drawing.XDrawPages</idl> interface that is derived from <idl>com.sun.star.container.XIndexAccess</idl>. That is, XDrawPages allows accessing, inserting and removing pages of a drawing document:

type getElementType()
boolean hasElements()
long getCount()
any getByIndex(long Index)

com::sun::star::drawing::XDrawPage insertNewByIndex(long nIndex)
void remove(com::sun::star::drawing::XDrawPage xPage)

The example below demonstrates how to access and create draw and master pages. Layers will be described later.

XDrawPagesSupplier xDrawPagesSupplier = (XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);

// XDrawPages inherits from com.sun.star.container.XIndexAccess
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
// get the page count for standard pagesint nPageCount = xDrawPages.getCount();
// get draw page by index
XDrawPage xDrawPage = (XDrawPage)UnoRuntime.queryInterface(XDrawPage .class,
    xDrawPages.getByIndex(nIndex));
/* create and insert a draw page into the given position,
    the method returns the newly created page
*/
XDrawPage xNewDrawPage = xDrawPages.insertNewByIndex(0);
// remove the given page
xDrawPages.remove( xDrawPage );
/* now repeat the same procedure as described above for the master pages,
    the main difference is to get the XDrawPages from the XMasterPagesSupplier
    interface
*/
XMasterPagesSupplier xMasterPagesSupplier = (XMasterPagesSupplier)UnoRuntime.queryInterface(
    XMasterPagesSupplier.class, xComponent);
XDrawPages xMasterPages = xMasterPagesSupplier.getMasterPages();
// xMasterPages can now be used in the same manner as xDrawPages is used above

Each draw page always has one master page. The interface <idl>com.sun.star.drawing.XMasterPageTarget</idl> offers methods to get and set the master page that is correlated to a draw page.

// query for MasterPageTarget
XMasterPageTarget xMasterPageTarget = (XMasterPageTarget)UnoRuntime.queryInterface(
    XMasterPageTarget.class, xDrawPage);
// now we can get the corresponding master page
XDrawPage xMasterPage = xMasterPageTarget.getMasterPage();
/* this method now sets a new master page,
    it is important to mention that the applied page must be part of the MasterPages
*/
xMasterPageTarget.setMasterPage(xMasterPage);

It is possible to copy pages using the interface [IDL:com.sun.star.drawing.XDrawPageDuplicator] of drawing or presentation documents.

Methods of <idl>com.sun.star.drawing.XDrawPageDuplicator</idl>:

com::sun::star::drawing::XDrawPage duplicate( [in] com::sun::star::drawing::XDrawPage xPage)

Pass a draw page reference to the method duplicate(). It appends a new draw page at the end of the page list, using the default naming scheme for pages, "slide n".

Page Partitioning

All units and dimensions are measured in 1/100th of a millimeter. The coordinates are increasing from left to right, and from top to bottom. The upper-left position of a page is (0, 0).

The page size, margins and orientation can be determined using the following properties of a draw page (generic draw page):

Properties of <idl>com.sun.star.drawing.GenericDrawPage</idl>
<idlm>com.sun.star.drawing.GenericDrawPage:Height</idlm> long - Height of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:Width</idlm> long - Width of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:BorderBottom</idlm> long - Bottom margin of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:BorderLeft</idlm> long - Left margin of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:BorderRight</idlm> long - Right margin of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:BorderTop</idlm> long - Top margin of the page.
<idlm>com.sun.star.drawing.GenericDrawPage:Orientation</idlm> <idl>com.sun.star.view.PaperOrientation</idl>. Determines if the printer output should be turned by 90??. Possible values are: PORTRAIT and LANDSCAPE.

Shapes

Drawings consist of shapes on draw pages. Shapes are drawing elements, such as rectangles, circles, polygons, and lines. To create a drawing, get a shape by its service name at the ServiceFactory of a drawing document and add it to the appropriate DrawPage.

The code below demonstrates how to create shapes. It consists of a static helper method located in the class ShapeHelper and will be used throughout this chapter to create shapes. The parameter xComponent must be a reference to a loaded drawing document. The x, y, height and width are the desired position and size, and sShapeType expects a service name for the shape, such as "com.sun.star.drawing.RectangleShape". The method does not actually insert the shape into a page. It instantiates it and returns the instance to the caller.

Shape

The size and position of a shape can be set before adding a shape to a page. After adding the shape, change the shape properties through <idl>com.sun.star.beans.XPropertySet</idl>.

public static XShape createShape( XComponent xComponent,
    int x, int y, int width, int height, String sShapeType) throws java.lang.Exception {
    // query the document for the document-internal service factory
    XMultiServiceFactory xFactory = (XMultiServiceFactory)UnoRuntime.queryInterface(
        XMultiServiceFactory.class, xComponent);

    // get the given Shape service from the factory
    Object xObj = xFactory.createInstance(sShapeType);
    Point aPos = new Point(x, y);
    Size aSize = new Size(width, height);

    // use its XShape interface to determine position and size before insertion
    xShape = (XShape)UnoRuntime.queryInterface(XShape.class, xObj);
    xShape.setPosition(aPos);
    xShape.setSize(aSize);
    return xShape;
}

Warning.svg

Warning:
Notice, the following restrictions: A shape cannot be inserted into multiple pages, and most methods do not work before the shape is inserted into a draw page.


The previously declared method will be used to create a simple rectangle shape with a size of 10 cm x 5 cm that is positioned in the upper-left, and inserted into a drawing page.

Simple rectangle shape

// query DrawPage for XShapes interface
XShapes xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPage);
// create the shape
XShape xShape = createShape(xComponent, 0, 0, 10000, 5000, "com.sun.star.drawing.RectangleShape");
// add shape to DrawPage
xShapes.add(xShape);
// set text
XText xText = (XText)UnoRuntime.queryInterface( XText.class, xShape );
xText.setString("My new RectangleShape");
// to be able to set Properties a XPropertySet interface is needed
XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xShape);
xPropSet.setPropertyValue("CornerRadius", new Integer(1000));
xPropSet.setPropertyValue("Shadow", new Boolean(true));
xPopSet.setPropertyValue("ShadowXDistance", new Integer(250));
xPropSet.setPropertyValue("ShadowYDistance", new Integer(250));
// blue fill color
xPropSet.setPropertyValue("FillColor", new Integer(0xC0C0C0));
// black line color
xPropSet.setPropertyValue("LineColor", new Integer(0x000000));
xPropSet.setPropertyValue("Name", "Rounded Gray Rectangle");

The UML diagram in the illustration below describes all services that are included by the <idl>com.sun.star.drawing.RectangleShape</idl> service and provides an overview of properties that can be used with such a simple shape.

RectangleShape

Shape Types

ShapeTypes
ShapeTypes

The following table lists all shapes supported in Draw and Impress documents. They come from the <idlmodule>com.sun.star.drawing</idlmodule>. Each shape is based on <idl>com.sun.star.drawing.Shape</idl>. Additionally, there are five services in the module com.sun.star.drawing that most of the shapes have in common:

<idl>com.sun.star.drawing.Text</idl>, <idl>com.sun.star.drawing.LineProperties</idl>, <idl>com.sun.star.drawing.FillProperties</idl> and <idl>com.sun.star.drawing.ShadowProperties</idl> handle shape formatting, whereas <idl>com.sun.star.drawing.RotationDescriptor</idl> controls rotation and shearing. The section General Drawing Properties below discusses shape formatting in more detail. Refer to the section Shape Operations for information on rotation and shearing.

Note pin.svg

Note:
The service <idl>com.sun.star.drawing.Text</idl> is different from other Text services. It consists of the service <idl>com.sun.star.drawing.TextProperties</idl> and the interface <idl>com.sun.star.text.XText</idl> that was introduced in the chapter First Steps. Drawing text does not supports text contents other than paragraphs consisting of character strings.

An x denotes which of these services are supported by each shape. The rightmost column shows the services, interfaces and properties that are specific for the various shapes.

ShapeType Text Line Properties Fill Properties Shadow Properties Rotation Descriptor Supported services, Exported interfaces, Properties
<idls>com.sun.star.drawing.ClosedBezierShape</idls>
x
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonBezierDescriptor</idl>

<idls>com.sun.star.drawing.ConnectorShape</idls>
x
x
x
x
included service:

<idl>com.sun.star.drawing.ConnectorProperties</idl>

properties:
<idl>com.sun.star.drawing.XShape</idl> StartShape
<idl>com.sun.star.drawing.XShape</idl> EndShape
<idl>com.sun.star.awt.Point</idl> StartPosition
<idl>com.sun.star.awt.Point</idl> EndPosition
long StartGluePointIndex
long EndGluePointIndex
long EdgeLine1Delta
long EdgeLine2Delta
long EdgeLine3Delta

<idls>com.sun.star.drawing.ControlShape</idls> exported interface: <idl>com.sun.star.drawing.XControlShape</idl>
<idls>com.sun.star.drawing.EllipseShape</idls>
x
x
x
x
x
properties:<idl>com.sun.star.drawing.CircleKind</idl> CircleKind

long CircleStartAngle
long CircleEndAngle

<idls>com.sun.star.drawing.GraphicObjectShape</idls>
x
x
x
properties:

string GraphicURL
string GraphicStreamURL
short AdjustLuminance
short AdjustContrast
short AdjustRed
short AdjustGreen
short AdjustBlue
double Gamma
short Transparency
<idl>com.sun.star.drawing.ColorMode</idl> GraphicColorMode

optional properties:
<idl>com.sun.star.awt.XBitmap</idl> GraphicObjectFillBitmap
<idl>com.sun.star.container.XIndexContainer</idl> ImageMap

<idls>com.sun.star.drawing.GroupShape</idls> exported interfaces:

<idl>com.sun.star.drawing.XShapeGroup</idl>
<idl>com.sun.star.drawing.XShapes</idl>

<idls>com.sun.star.drawing.LineShape</idls>
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonDescriptor</idl>

<idls>com.sun.star.drawing.MeasureShape</idls>
x
x
x
x
included service:

<idl>com.sun.star.drawing.MeasureProperties</idl>

properties:
<idl>com.sun.star.awt.Point</idl> StartingPosition
<idl>com.sun.star.awt.Point</idl> EndPosition

<idls>com.sun.star.drawing.OLE2Shape</idls> properties:

string CLSID

readonly properties:
<idl>com.sun.star.frame.XModel</idl> Model
boolean IsInternal

<idls>com.sun.star.drawing.OpenBezierShape</idls>
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonBezierDescriptor</idl>

<idls>com.sun.star.drawing.PageShape</idls>
<idls>com.sun.star.drawing.PolyLineShape</idls>
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonDescriptor</idl>

<idls>com.sun.star.drawing.PolyPolygonBezierShape</idls>
x
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonBezierDescriptor</idl>

<idls>com.sun.star.drawing.PolyPolygonShape</idls>
x
x
x
x
x
included service:

<idl>com.sun.star.drawing.PolyPolygonDescriptor</idl>

<idls>com.sun.star.drawing.RectangleShape</idls>
x
x
x
x
x
properties:

long CornerRadius

<idls>com.sun.star.drawing.TextShape</idls>
x
x
x
x
x
properties:

long CornerRadius

<idls>com.sun.star.drawing.PluginShape</idls> properties:

string PluginMimeType
string PluginURL
sequence< <idl>com.sun.star.beans.PropertyValue</idl> > PluginCommands

Bezier Shapes

Draw supports three different kinds of Bezier curves: OpenBezierShape, ClosedBezierShape and PolyPolygonBezierShape. They are all controlled by <idl>com.sun.star.drawing.PolyPolygonBezierDescriptor</idl> which is made up of the following properties:

Properties of <idl>com.sun.star.drawing.PolyPolygonBezierDescriptor</idl>
<idlm>com.sun.star.drawing.PolyPolygonBezierDescriptor:PolygonKind</idlm> [readonly] <idl>com.sun.star.drawing.PolygonKind</idl>. Type of the polygon. Possible values are:

LINE for a LineShape.

POLY for a PolyPolygonShape.

PLIN for a PolyLineShape.

PATHLINE for an OpenBezierShape.

PATHFILL for a ClosedBezierShape.

<idlm>com.sun.star.drawing.PolyPolygonBezierDescriptor:PolyPolygonBezier</idlm> struct <idl>com.sun.star.drawing.PolyPolygonBezierCoords</idl>. These are the bezier points of the polygon. The struct members are Coordinates and Flags, which are both sequences of sequences. The Coordinates sequence contains <idl>com.sun.star.awt.Point</idl> structs and the Flags sequence contains <idl>com.sun.star.drawing.PolygonFlags</idl> enums. Point members are X and Y. Possible PolygonFlags values are:
  • NORMAL the point is normal, from the curve discussion view.
  • SMOOTH the point is smooth, the first derivation from the curve discussion view.
  • CONTROL the point is a control point, to control the curve from the user interface.
  • SYMMETRIC the point is symmetric, the second derivation from the curve discussion view.
<idlm>com.sun.star.drawing.PolyPolygonBezierDescriptor:Geometry</idlm> <idl>com.sun.star.drawing.PolyPolygonBezierCoords</idl>. These are the untransformed bezier coordinates of the polygon. The property has the same type as PolyPolygonBezier.

The next Java example will demonstrate how to create a ClosedBezierShape that looks like the following picture.

Closed bezier shape

XShape xPolyPolygonBezier = createShape( xComponent, 0, 0, 0, 0,
    "com.sun.star.drawing.ClosedBezierShape");
// take care of the fact that the shape must have been added
// to the page before it is possible to apply changes
XShapes xShapes = (XShapes)UnoRuntime.queryInterface( XShapes.class, xDrawPage);
xShapes.add(xPolyPolygonBezier);
// now it is possible to edit the PropertySet
XPropertySet xShapeProperties = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xPolyPolygonBezier);
// The following values are exemplary and provokes that a PolyPolygon of
// sixteen single polygons containing four points each is created. The
// PolyPolygon total point count will be 64.
// If control points are used they are allowed to appear as pair only,
// before and after such pair has to be a normal point.
// A bezier point sequence may look like
// this (n=normal, c=control) : n c c n c c n n c c n
int nPolygonCount = 16;
int nPointCount = 4;
int nWidth = 10000;
int nHeight = 10000;
PolyPolygonBezierCoords aCoords = new PolyPolygonBezierCoords();
// allocating the outer sequence
aCoords.Coordinates = new Point[nPolygonCount][];
aCoords.Flags = new PolygonFlags[nPolygonCount][];
int i, n, nY;

// fill the inner point sequence now
for (nY = 0, i = 0; i < nPolygonCount; i++, nY += nHeight / nPolygonCount) {
    // create a polygon using two normal and two control points
    // allocating the inner sequence
    Point[] pPolyPoints = new Point[nPointCount];
    PolygonFlags[]pPolyFlags = new PolygonFlags[nPointCount];
    for (n = 0; n < nPointCount; n++)
        pPolyPoints[n] = new Point();
    pPolyPoints[0].X = 0;
    pPolyPoints[0].Y = nY;
    pPolyFlags [0] = PolygonFlags.NORMAL;
    pPolyPoints[1].X = nWidth / 2;
    pPolyPoints[1].Y = nHeight;
    pPolyFlags[1] = PolygonFlags.CONTROL;
    pPolyPoints[2].X = nWidth / 2;
    pPolyPoints[2].Y = nHeight;
    pPolyFlags [2] = PolygonFlags.CONTROL;
    pPolyPoints[3].X = nWidth;
    pPolyPoints[3].Y = nY;
    pPolyFlags [3] = PolygonFlags.NORMAL;
    aCoords.Coordinates[i] = pPolyPoints;
    aCoords.Flags[i] = pPolyFlags;
}
try {
    xShapeProperties.setPropertyValue("PolyPolygonBezier", aCoords);
} catch (Exception ex)
{
}

Shape Operations

You can modify shapes in many different ways:

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

Moving and scaling of a shape can be done by using the corresponding methods getPosition(), setPosition(), getSize() and setSize() of the <idl>com.sun.star.drawing.XShape</idl> interface:

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

Point and Size are IDL structs. In Java, these structs are mapped to classes with constructors that take values for the struct members. Therefore, when new is used to instantiate these classes, the coordinates and dimensions are passed to initialize the class members X, Y, Width and Height.

Rotating and Shearing

Most shapes, except OLE and group objects, can be rotated and sheared. All of these objects include the <idl>com.sun.star.drawing.RotationDescriptor</idl> service that has the properties RotateAngle and ShearAngle.

Setting the <idl>com.sun.star.drawing.RotationDescriptor</idl> rotates or shears a shape:

Properties of <idl>com.sun.star.drawing.RotationDescriptor</idl>
<idlm>com.sun.star.drawing.RotationDescriptor:RotateAngle</idlm> long - This is the angle for rotation of this shape in 1/100th of a degree. The shape is rotated counter-clockwise around the center of the bounding box.
<idlm>com.sun.star.drawing.RotationDescriptor:ShearAngle</idlm> long - This is the amount of shearing for this shape in 1/100th of a degree. The shape is sheared clockwise around the center of the bounding box.
Note pin.svg

Note:
Notice that the rotation works counter-clockwise, while shearing works clockwise.

Rotation and Shearing by 25 degrees

The following example shows how a shape can be rotated by 25 degrees counterclockwise:

// xShape will be rotated by 25 degrees
    XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(
        XPropertySet.class, xShape );
    xPropSet.setPropertyValue( "RotateAngle", new Integer( 2500 ) );

Transforming

Changing the size, rotation and shearing of an object can be done by using the transformation mechanism provided by LibreOffice. The matrix of our API is a standard homogenous 3x3 matrix that may be used together with the java.awt.geom.AffineTransform class from Java. The transformation received describes the actual values of the transformations as a linear combination of the single matrices. The basic object without transformation has a size of (1, 1) and a position of (0, 0), and is not rotated or sheared. Thus, to transform an object get its matrix and multiply from the left side to influence the current appearance. To set the whole transformation directly, build a combined matrix of the single values mentioned above and apply it to the object.

XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface( XPropertySet.class, xShape );
// take the current tranformation matrix
HomogenMatrix3 aHomogenMatrix3 = (HomogenMatrix3)xPropSet.getPropertyValue("Transformation");
java.awt.geom.AffineTransform aOriginalMatrix =
new java.awt.geom.AffineTransform(aHomogenMatrix3.Line1.Column1,
                                aHomogenMatrix3.Line2.Column1,
                                aHomogenMatrix3.Line1.Column2,
                                aHomogenMatrix3.Line2.Column2,
                                aHomogenMatrix3.Line1.Column3,
                                aHomogenMatrix3.Line2.Column3 );
// rotate the object by 15 degrees
AffineTransform aNewMatrix1 = new AffineTransform();
aNewMatrix1.setToRotation(Math.toRadians(15));
aNewMatrix1.concatenate(aOriginalMatrix);
// and translate the object by 2cm on the x-axis
AffineTransform aNewMatrix2 = new AffineTransform();
aNewMatrix2.setToTranslation(2000, 0);
aNewMatrix2.concatenate(aNewMatrix1);
double aFlatMatrix[] = new double[6];aNewMatrix2.getMatrix(aFlatMatrix);
// convert the flatMatrix to our HomogenMatrix3 structure
aHomogenMatrix3.Line1.Column1 = aFlatMatrix[0];
aHomogenMatrix3.Line2.Column1 = aFlatMatrix[1];
aHomogenMatrix3.Line1.Column2 = aFlatMatrix[2];
aHomogenMatrix3.Line2.Column2 = aFlatMatrix[3];
aHomogenMatrix3.Line1.Column3 = aFlatMatrix[4];
aHomogenMatrix3.Line2.Column3 = aFlatMatrix[5];
xPropSet.setPropertyValue("Transformation", aHomogenMatrix3);

Ordering

The property ZOrder of the <idl>com.sun.star.drawing.Shape</idl> service defines the order a shape is drawn. That is, if there are many shapes on a page, the shape that has the lowest ZOrder value is drawn first, and the shape that has the highest ZOrder is drawn last. By using this property it is possible to bring an object to the back or front of a page. It is also possible to switch the order of two shapes as demonstrated in the following example:

XPropertySet xPropSet1 = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xShape1);
XPropertySet xPropSet2 = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xShape2);
// get current positions
int nOrderOfShape1 = ((Integer)xPropSet1.getPropertyValue("ZOrder")).intValue();
int nOrderOfShape2 = ((Integer)xPropSet2.getPropertyValue("ZOrder")).intValue();
// set new positions
xPropSet1.setPropertyValue("ZOrder", new Integer(nOrderOfShape2));
xPropSet2.setPropertyValue("ZOrder", new Integer(nOrderOfShape1));

Grouping, Combining and Binding

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

Methods of <idl>com.sun.star.drawing.XShapeGrouper</idl>
<idlm>com.sun.star.drawing.XShapeGrouper:group</idlm>() Parameter:

<idl>com.sun.star.drawing.XShapes</idl> xShapes

Groups the shapes inside a collection. They must all be inserted into the same GenericDrawPage.

Returns a recently created GroupShape that contains all shapes from xShapes, and is also added to the GenericDrawPage of the Shapes in xShapes.

<idlm>com.sun.star.drawing.XShapeGrouper:ungroup</idlm>() Parameter:

<idl>com.sun.star.drawing.XShapeGroup</idl>

Ungroups a given GroupShape. Moves all Shapes from this GroupShape to the parent XShapes of the GroupShape. The GroupShape is then removed from the GenericDrawPage and disposed.

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

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

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

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

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

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

Methods of <idl>com.sun.star.drawing.XShapeGroup</idl>:

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

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

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

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

Methods of <idl>com.sun.star.drawing.XShapeCombiner</idl>
<idlm>com.sun.star.drawing.XShapeCombiner:combine</idlm>() Parameter:

<idl>com.sun.star.drawing.XShapes</idl>

Combines shapes. The shapes inside this container are converted to PolyPolygonBezierShapes and are than combined into one PolyPolygonBezierShape. The shapes in xShape are removed from the GenericDrawPage and disposed.

Returns a recently created PolyPolygonBezierShape that contains all the converted PolyPolygonBezierShapes combined. It is also added to the GenericDrawPage of the source Shapes.

<idlm>com.sun.star.drawing.XShapeCombiner:split</idlm>() Parameter:

<idl>com.sun.star.drawing.XShape</idl>

Splits shapes. The Shape is converted to a PolyPolygonBezierShape and then split into several PolyPolygonBezierShapes. The shape s in xShape are removed from the GenericDrawPage and disposed.

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

Methods of <idl>com.sun.star.drawing.XShapeBinder</idl>
<idlm>com.sun.star.drawing.XShapeBinder:bind</idlm>() Parameter:

<idl>com.sun.star.drawing.XShapes</idl>

binds shapes together. A container with shapes that will be bound together. All shapes are converted to a PolyPolygonBezierShape and the lines are connected. The Shapes in xShape are removed from the GenericDrawPage and disposed.

Returns a recently created PolyPolygonBezierShape that contains all line segments from the supplied Shapes. It is also added to the GenericDrawPage of the source Shapes.

<idlm>com.sun.star.drawing.XShapeBinder:unbind</idlm>() Parameter:

<idl>com.sun.star.drawing.XShape</idl>

breaks a shape into its line segments. The given shape will be converted to a PolyPolygonBezierShape and the line segments of this shape are used to create new PolyPolygonBezierShape shapes. The original shape is removed from its GenericDrawPage and disposed.

General Drawing Properties

This chapter introduces the relevant drawing attributes provided by services, such as <idl>com.sun.star.drawing.LineProperties</idl>, <idl>com.sun.star.drawing.FillProperties</idl> and <idl>com.sun.star.drawing.TextProperties</idl>. The service is described by listing all its properties, followed by an example that uses and explains some of the properties. Each of the following Java examples assumes an already existing valid shape xShape that has already been inserted into the page.

Colors are given in Hex ARGB format, a four-byte value containing the alpha, red, green and blue components of a color in the format 0xAARRGGBB. The leading component can be omitted if it is zero. The hex format 0xFF0000 is light red, 0xFF00 is green, and 0xFF is blue.

Angles must be given in steps of 1/100th of a degree.

Measures, such as line widths and lengths are given in 100th of a millimeter.

Properties provided by the service :

Properties of <idl>com.sun.star.drawing.LineProperties</idl>
<idlm>com.sun.star.drawing.LineProperties:LineStyle</idlm> <idl>com.sun.star.drawing.LineStyle</idl>. This enumeration selects the style of the line.
<idlm>com.sun.star.drawing.LineProperties:LineDash</idlm> <idl>com.sun.star.drawing.LineDash</idl>. This enumeration selects the dash of the line
<idlm>com.sun.star.drawing.LineProperties:LineColor</idlm> long - Color of the line.
<idlm>com.sun.star.drawing.LineProperties:LineTransparence</idlm> short - Degree of transparency.
<idlm>com.sun.star.drawing.LineProperties:LineWidth</idlm> long - Width of the line in 1/100th of a millimeter.
<idlm>com.sun.star.drawing.LineProperties:LineJoint</idlm> <idl>com.sun.star.drawing.LineJoint</idl>. Rendering of joints between thick lines.
<idlm>com.sun.star.drawing.LineProperties:LineStartName</idlm> [optional] string - Name of the line that starts poly polygon bezier.
<idlm>com.sun.star.drawing.LineProperties:LineStart</idlm> [optional] <idl>com.sun.star.drawing.PolyPolygonBezierCoords</idl>. Line starts in the form of a poly polygon bezier.
<idlm>com.sun.star.drawing.LineProperties:LineEnd</idlm> [optional] <idl>com.sun.star.drawing.PolyPolygonBezierCoords</idl>. Line ends in the form of a poly polygon bezier.
<idlm>com.sun.star.drawing.LineProperties:LineStartCenter</idlm> [optional] boolean - If true, the line starts from the center of the polygon.
<idlm>com.sun.star.drawing.LineProperties:LineStartWidth</idlm> [optional] long - Width of the line start polygon.
<idlm>com.sun.star.drawing.LineProperties:LineEndCenter</idlm> [optional] boolean - If true, the line ends in the center of the polygon.
<idlm>com.sun.star.drawing.LineProperties:LineEndWidth</idlm> [optional] long - Width of the line end polygon.

/* create a blue line with dashes and dots */
XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xShape );
xPropSet.setPropertyValue( "LineStyle", LineStyle.DASH );
LineDash aLineDash = new LineDash();
aLineDash.Dots = 3;
aLineDash.DotLen = 150;
aLineDash.Dashes = 3;
aLineDash.DashLen = 300;
aLineDash.Distance = 150;
xPropSet.setPropertyValue( "LineDash", aLineDash );
xPropSet.setPropertyValue( "LineColor", new Integer( 0x0000ff ) );
xPropSet.setPropertyValue( "LineWidth", new Integer( 200 ) );

Properties of <idl>com.sun.star.drawing.FillProperties</idl>
<idlm>com.sun.star.drawing.FillProperties:FillStyle</idlm> <idl>com.sun.star.drawing.FillStyle</idl>. This enumeration selects the style that the area is filled with.
<idlm>com.sun.star.drawing.FillProperties:FillColor</idlm> long - If the FillStyle is set to SOLID, this is the color used.
<idlm>com.sun.star.drawing.FillProperties:FillTransparence</idlm> short - The transparency of the filled area in percent.
<idlm>com.sun.star.drawing.FillProperties:FillTransparenceGradientName</idlm> string - This is the name of the transparent gradient style used if a gradient is used for transparency, or it is empty. This style is used to set the name of a transparent gradient style contained in the document.
<idlm>com.sun.star.drawing.FillProperties:FillTransparenceGradient</idlm> [optional] <idl>com.sun.star.awt.Gradient</idl>. Transparency of the fill area as a gradient.
<idlm>com.sun.star.drawing.FillProperties:FillGradientName</idlm> string - If the FillStyle is set to GRADIENT, this is the name of the fill gradient style used.
<idlm>com.sun.star.drawing.FillProperties:FillGradient</idlm> [optional] <idl>com.sun.star.awt.Gradient</idl>. If the FillStyle is set to GRADIENT, this describes the gradient used.
<idlm>com.sun.star.drawing.FillProperties:FillHatchName</idlm> string - If the FillStyle is set to GRADIENT, this is the name of the fill hatch style used.
<idlm>com.sun.star.drawing.FillProperties:FillHatch</idlm> [optional] <idl>com.sun.star.drawing.Hatch</idl>. If the FillStyle is set to HATCH, this describes the hatch used.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapName</idlm> string - If the FillStyle is set to BITMAP, this is the name of the fill bitmap style used.
<idlm>com.sun.star.drawing.FillProperties:FillBitmap</idlm> [optional] <idl>com.sun.star.awt.XBitmap</idl>. If the FillStyle is set to BITMAP, this is the bitmap used.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapURL</idlm> [optional] string. If the FillStyle is set to BITMAP, this is a URL to the bitmap used.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapOffsetX</idlm> short - Horizontal offset where the tile starts.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapOffsetY</idlm> short - Vertical offset where the tile starts. It is given in percent in relation to the width of the bitmap.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapPositionOffsetX</idlm> short - Every second line of tiles is moved the given percent of the width of the bitmap.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapPositionOffsetY</idlm> short - Every second row of tiles is moved the given percent of the width of the bitmap.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapRectanglePoint</idlm> <idl>com.sun.star.drawing.RectanglePoint</idl>. The RectanglePoint specifies the position inside of the bitmap to use as the top-left position for rendering.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapLogicalSize</idlm> boolean - Specifies if the size is given in percentage or as an absolute value.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapSizeX</idlm> long - Width of the tile for filling.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapSizeY</idlm> long - Height of the tile for filling.
<idlm>com.sun.star.drawing.FillProperties:FillBitmapMode</idlm> <idl>com.sun.star.drawing.BitmapMode</idl>. Enumeration selects how an area is filled with a single bitmap.
<idlm>com.sun.star.drawing.FillProperties:FillBackground</idlm> boolean - If true , the transparent background of a hatch filled area is drawn in the current background color.

/* apply a gradient fill style that goes from top left to bottom
    right and is changing its color from green to yellow */
XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xShape );
xPropSet.setPropertyValue( "FillStyle", FillStyle.GRADIENT );
Gradient aGradient = new Gradient();
aGradient.Style = GradientStyle.LINEAR;
aGradient.StartColor = 0x00ff00;
aGradient.EndColor = 0xffff00;
aGradient.Angle = 450;
aGradient.Border = 0;
aGradient.XOffset = 0;
aGradient.YOffset = 0;
aGradient.StartIntensity = 100;
aGradient.EndIntensity = 100;
aGradient.StepCount = 10;
xPropSet.setPropertyValue( "FillGradient", aGradient );

Properties of <idl>com.sun.star.drawing.TextProperties</idl>
<idlm>com.sun.star.drawing.TextProperties:IsNumbering</idlm> [optional] boolean - If true, numbering is on for the text of this shape.
<idlm>com.sun.star.drawing.TextProperties:NumberingRules</idlm> [optional] <idl>com.sun.star.container.XIndexReplace</idl>. Describes the numbering levels.
<idlm>com.sun.star.drawing.TextProperties:TextAutoGrowHeight</idlm> boolean - If true, the height of the shape is automatically expanded or shrunk when text is added or removed from the shape.
<idlm>com.sun.star.drawing.TextProperties:TextAutoGrowWidth</idlm> boolean - If true, the width of the shape is automatically expanded or shrunk when text is added or removed from the shape.
<idlm>com.sun.star.drawing.TextProperties:TextContourFrame</idlm> boolean - If true, the left edge of every line of text is aligned with the left edge of this shape.
<idlm>com.sun.star.drawing.TextProperties:TextFitToSize</idlm> <idl>com.sun.star.drawing.TextFitToSizeType</idl>. Determines how the text inside of the Shape is stretched to fit in the Shape. Possible values are NONE, PROPORTIONAL, ALLLINES, and RESIZEATTR.
<idlm>com.sun.star.drawing.TextProperties:TextHorizontalAdjust</idlm> <idl>com.sun.star.drawing.TextHorizontalAdjust</idl>. Adjusts the horizontal position of the text inside of the shape.
<idlm>com.sun.star.drawing.TextProperties:TextVerticalAdjust</idlm> <idl>com.sun.star.drawing.TextVerticalAdjust</idl>. Adjusts the vertical position of the text inside of the shape.
<idlm>com.sun.star.drawing.TextProperties:TextLeftDistance</idlm> long - Distance from the left edge of the shape to the left edge of the text.
<idlm>com.sun.star.drawing.TextProperties:TextRightDistance</idlm> long - Distance from the right edge of the shape to the right edge of the text.
<idlm>com.sun.star.drawing.TextProperties:TextUpperDistance</idlm> long - Distance from the upper edge of the shape to the upper edge of the text.
<idlm>com.sun.star.drawing.TextProperties:TextLowerDistance</idlm> long - Distance from the lower edge of the shape to the lower edge of the text.
<idlm>com.sun.star.drawing.TextProperties:TextMaximumFrameHeight</idlm> long - Maximum height of the surrounding frame.
<idlm>com.sun.star.drawing.TextProperties:TextMaximumFrameWidth</idlm> long - Maximum width of the surrounding frame.
<idlm>com.sun.star.drawing.TextProperties:TextMinimumFrameHeight</idlm> long - Minimum height of the surrounding frame.
<idlm>com.sun.star.drawing.TextProperties:TextMinimumFrameWidth</idlm> long - Minimum width of the surrounding frame.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationAmount</idlm> short - Number of pixels that the text is moved in each animation step.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationCount</idlm> short - Defines how many times the text animation is repeated.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationDelay</idlm> short - Delay between the animation steps in thousandths of a second.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationDirection</idlm> <idl>com.sun.star.drawing.TextAnimationDirection</idl>. This enumeration defines the direction that the text moves.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationKind</idlm> <idl>com.sun.star.drawing.TextAnimationKind</idl>. Defines the type of animation.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationStartInside</idlm> boolean. If true, the text is visible at the start of the animation.
<idlm>com.sun.star.drawing.TextProperties:TextAnimationStopInside</idlm> boolean. If true, the text is visible at the end of the animation.
<idlm>com.sun.star.drawing.TextProperties:TextWritingMode</idlm> <idl>com.sun.star.text.WritingMode</idl>. This value selects the writing mode for the text.

The service <idl>com.sun.star.drawing.TextProperties</idl> includes <idl>com.sun.star.style.ParagraphProperties</idl> and <idl>com.sun.star.style.CharacterProperties</idl>. Since these services contain optional properties, the properties actually supported by drawing shapes are listed. Refer to the API reference or explanations or Formatting.

The service <idl>com.sun.star.drawing.TextProperties</idl> includes <idl>com.sun.star.style.ParagraphProperties</idl> and <idl>com.sun.star.style.CharacterProperties</idl>. Since these services contain many optional properties, we list the properties actually supported by drawing shapes. Please look up the explanations in the API reference or in Formatting.

<idl>com.sun.star.style.CharacterProperties</idl> of drawing text
<idlm>com.sun.star.style.CharacterProperties:CharAutoKerning</idlm> boolean
<idlm>com.sun.star.style.CharacterProperties:CharColor</idlm> long
<idlm>com.sun.star.style.CharacterProperties:CharContoured</idlm> boolean
<idlm>com.sun.star.style.CharacterProperties:CharCrossedOut</idlm> boolean
<idlm>com.sun.star.style.CharacterProperties:CharEmphasis</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharEscapement</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharEscapementHeight</idlm> byte
<idlm>com.sun.star.style.CharacterProperties:CharFontCharSet</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharFontFamily</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharFontName</idlm> string
<idlm>com.sun.star.style.CharacterProperties:CharFontPitch</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharFontStyleName</idlm> string
<idlm>com.sun.star.style.CharacterProperties:CharHeight</idlm> float
<idlm>com.sun.star.style.CharacterProperties:CharKerning</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharLocale</idlm> <idl>com.sun.star.lang.Locale</idl>
<idlm>com.sun.star.style.CharacterProperties:CharPosture</idlm> <idl>com.sun.star.awt.FontSlant</idl>
<idlm>com.sun.star.style.CharacterProperties:CharRelief</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharScaleWidth</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharShadowed</idlm> boolean
<idlm>com.sun.star.style.CharacterProperties:CharStrikeout</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharUnderline</idlm> short
<idlm>com.sun.star.style.CharacterProperties:CharUnderlineColor</idlm> long
<idlm>com.sun.star.style.CharacterProperties:CharUnderlineHasColor</idlm> boolean
<idlm>com.sun.star.style.CharacterProperties:CharWeight</idlm> float
<idlm>com.sun.star.style.CharacterProperties:CharWordMode</idlm> boolean

There are Asian counterparts for a number of character properties.

<idl>com.sun.star.style.CharacterPropertiesAsian</idl> of drawing shapes
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharFontPitchAsian</idlm> short
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharFontStyleNameAsian</idlm> string
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharHeightAsian</idlm> float
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharPostureAsian</idlm> <idl>com.sun.star.awt.FontSlant</idl>
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharLocaleAsian</idlm> <idl>com.sun.star.lang.Locale</idl>
<idlm>com.sun.star.style.CharacterPropertiesAsian:CharWeightAsian</idlm> float

There is also a Complex flavor of the same properties:

<idl>com.sun.star.style.CharacterPropertiesComplex</idl> of drawing text
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharFontPitchComplex</idlm> short
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharFontStyleNameComplex</idlm> string
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharHeightComplex</idlm> float
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharLocaleComplex</idlm> <idl>com.sun.star.lang.Locale</idl>
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharPostureComplex</idlm> <idl>com.sun.star.awt.FontSlant</idl>
<idlm>com.sun.star.style.CharacterPropertiesComplex:CharWeightComplex</idlm> float

Paragraphs in drawing text support a selection of <idl>com.sun.star.style.ParagraphProperties</idl>:

Properties of <idl>com.sun.star.style.ParagraphProperties</idl>
<idlm>com.sun.star.style.ParagraphProperties:ParaAdjust</idlm> short
<idlm>com.sun.star.style.ParagraphProperties:ParaBottomMargin</idlm> long
<idlm>com.sun.star.style.ParagraphProperties:ParaFirstLineIndent</idlm> long
<idlm>com.sun.star.style.ParagraphProperties:ParaIsHyphenation</idlm> boolean
<idlm>com.sun.star.style.ParagraphProperties:ParaLastLineAdjust</idlm> short
<idlm>com.sun.star.style.ParagraphProperties:ParaLeftMargin</idlm> long
<idlm>com.sun.star.style.ParagraphProperties:ParaLineSpacing</idlm> <idl>com.sun.star.style.LineSpacing</idl>
<idlm>com.sun.star.style.ParagraphProperties:ParaRightMargin</idlm> long
<idlm>com.sun.star.style.ParagraphProperties:ParaTabStops</idlm> sequence <<idl>com.sun.star.style.TabStop</idl> >
<idlm>com.sun.star.style.ParagraphProperties:ParaTopMargin</idlm> long
<idlm>com.sun.star.style.ParagraphProperties:ParaUserDefinedAttributes</idlm> <idl>com.sun.star.uno.XInterface</idl>

And of <idl>com.sun.star.style.ParagraphPropertiesAsian</idl>:

Properties of <idl>com.sun.star.style.ParagraphPropertiesAsian</idl>
<idlm>com.sun.star.style.CharacterPropertiesAsian:ParaIsCharacterDistance</idlm> boolean
<idlm>com.sun.star.style.CharacterPropertiesAsian:ParaIsForbiddenRules</idlm> boolean
<idlm>com.sun.star.style.CharacterPropertiesAsian:ParaIsHangingPunctuation</idlm> boolean

The next example introduces a method that appends single text portions to a shape. It returns the XPropertySet interface of the text range that has been added.

/** add text to a shape.
    the return value is the PropertySet of the text range that has been added
*/
public static XPropertySet addPortion(XShape xShape, String sText, boolean bNewParagraph)
        throws com.sun.star.lang.IllegalArgumentException {
    XText xText = (XText)UnoRuntime.queryInterface(XText.class, xShape);
    XTextCursor xTextCursor = xText.createTextCursor();
    xTextCursor.gotoEnd(false);
    if (bNewParagraph) {
        xText.insertControlCharacter(xTextCursor, ControlCharacter.PARAGRAPH_BREAK, false);
        xTextCursor.gotoEnd(false);
    }
    XTextRange xTextRange = (XTextRange)UnoRuntime.queryInterface(XTextRange.class, xTextCursor);
    xTextRange.setString(sText);
    xTextCursor.gotoEnd(true);
    XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xTextRange);
    return xPropSet;
}

Using the previous method, the next example creates a rectangle shape that has a border of 2.5 cm with the text of two paragraphs is stretched by using the <idl>com.sun.star.drawing.TextFitToSizeType</idl> property. The text of the first paragraph is then colored green, and the second red. The Editing Text provides further details of handling text.

createShape(xComponent, new Point(0,0),
    new Size(21000, 12500), "com.sun.star.drawing.RectangleShape");
xShapes.add(xRectangle);
xShapePropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xRectangle);
// TextFitToSize
xShapePropSet.setPropertyValue("TextFitToSize", TextFitToSizeType.PROPORTIONAL);
// border size
xShapePropSet.setPropertyValue("TextLeftDistance", new Integer(2500));
xShapePropSet.setPropertyValue("TextRightDistance", new Integer(2500));
xShapePropSet.setPropertyValue("TextUpperDistance", new Integer(2500));
xShapePropSet.setPropertyValue("TextLowerDistance", new Integer(2500));
xTextPropSet = ShapeHelper.addPortion(xRectangle, "using TextFitToSize", false);
xTextPropSet.setPropertyValue("ParaAdjust", ParagraphAdjust.CENTER);
xTextPropSet.setPropertyValue("CharColor", new Integer(0xff00 ));
xTextPropSet = ShapeHelper.addPortion(xRectangle, "and a Border distance of 2,5 cm", true);
xTextPropSet.setPropertyValue("CharColor", new Integer(0xff0000));

Many shapes cast shadows. The ShadowProperties controls how this shadow looks:

Properties of <idl>com.sun.star.drawing.ShadowProperties</idl>
<idlm>com.sun.star.drawing.ShadowProperties:Shadow</idlm> boolean - Enables or disables the shadow of a shape.
<idlm>com.sun.star.drawing.ShadowProperties:ShadowColor</idlm> long - Color of the shadow of the shape.
<idlm>com.sun.star.drawing.ShadowProperties:ShadowTransparence</idlm> short - Defines the degree of transparency of the shadow in percent.
<idlm>com.sun.star.drawing.ShadowProperties:ShadowXDistance</idlm> long - Horizontal distance between the left edge of the shape and the shadow.
<idlm>com.sun.star.drawing.ShadowProperties:ShadowYDistance</idlm> long - Vertical distance between the top edge of the shape and the shadow.
Glue Points and Connectors

By default, there are four glue points available that are used within the properties StartGluePointIndex and EndGluePointIndex. If a connector connects to the top, bottom, left or right of a shape, a new glue point is not created. The four directions are declared in the following example.

The first example demonstrates how to create a <idl>com.sun.star.drawing.ConnectorShape</idl> and connect it to two other shapes using the glue point index property.

XDrawPagesSupplier xDrawPagesSupplier = (XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
XPage xPage = (XdrawPage)UnoRuntime.queryInterface(XDrawPage.class, xDrawPages.getByIndex(0));
XShapes xShapes = (XShapes) UnoRuntime.queryInterface(XShapes.class, xPage);
// create two rectangles
XShape xShape1 = ShapeHelper.createShape(xDrawDoc, new Point(15000, 1000), new Size(5000, 5000),
    "com.sun.star.drawing.RectangleShape");
XShape xShape2 = ShapeHelper.createShape(xDrawDoc, new Point(2000, 15000), new Size(5000, 5000),
    "com.sun.star.drawing.EllipseShape");
// and a connector
XShape xConnector = ShapeHelper.createShape(xDrawDoc,
    new Point(0, 0), new Size(0, 0), "com.sun.star.drawing.ConnectorShape");
xShapes.add(xShape1);
xShapes.add(xShape2);
xShapes.add(xConnector);
XPropertySet xConnectorPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xConnector);
// Index value of 0 : the shape is connected at the top
// Index value of 1 : the shape is connected at the left
// Index value of 2 : the shape is connected at the bottom
// Index value of 3 : the shape is connected at the right
int nStartIndex = 3;
int nEndIndex = 1;
// the "StartPosition" or "EndPosition" property needs not to be set
// if there is a shape to connect
xConnectorPropSet.setPropertyValue("StartShape", xShape1);
xConnectorPropSet.setPropertyValue("StartGluePointIndex", new Integer(nStartIndex));
xConnectorPropSet.setPropertyValue("EndShape", xShape2);
xConnectorPropSet.setPropertyValue("EndGluePointIndex", new Integer(nEndIndex));

The next example demonstrates the usage of user defined glue points.

XGluePointsSupplier xGluePointsSupplier;
XIndexContainer xIndexContainer;
XIdentifierContainer xIdentifierContainer;
/* take care to use the structure GluePoint2 and not
    GluePoint, because otherwise the XIdentifierContainer
    won't accept it
*/
GluePoint2 aGluePoint = new GluePoint2();
aGluePoint.IsRelative = false;
aGluePoint.PositionAlignment = Alignment.CENTER;
aGluePoint.Escape = EscapeDirection.SMART;
aGluePoint.IsUserDefined = true;
aGluePoint.Position.X = 0;
aGluePoint.Position.Y = 0;
// create and insert a glue point at shape1
xGluePointsSupplier = (XGluePointsSupplier)UnoRuntime.queryInterface(
    XGluePointsSupplier.class, xShape1);
xIndexContainer = xGluePointsSupplier.getGluePoints();
xIdentifierContainer = (XIdentifierContainer)UnoRuntime.queryInterface(
    XIdentifierContainer.class, xIndexContainer);
int nIndexOfGluePoint1 = xIdentifierContainer.insert(aGluePoint);
// create and insert a glue point at shape2
xGluePointsSupplier = (XGluePointsSupplier)
    UnoRuntime.queryInterface(XGluePointsSupplier.class, xShape2);
xIndexContainer = xGluePointsSupplier.getGluePoints();
xIdentifierContainer = (XIdentifierContainer)UnoRuntime.queryInterface(
    XIdentifierContainer.class, xIndexContainer);
int nIndexOfGluePoint2 = xIdentifierContainer.insert(aGluePoint);
// create and add a connector
XShape xConnector2 = ShapeHelper.createShape(xDrawDoc,
    new Point(0, 0), new Size(0, 0), "com.sun.star.drawing.ConnectorShape");
xShapes.add( xConnector2 );
XPropertySet xConnector2PropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xConnector2);
xConnector2PropSet.setPropertyValue("StartShape", xShape1);
xConnector2PropSet.setPropertyValue("StartGluePointIndex", new Integer(nIndexOfGluePoint1));
xConnector2PropSet.setPropertyValue( "EndShape", xShape2 );
xConnector2PropSet.setPropertyValue( "EndGluePointIndex", new Integer(nIndexOfGluePoint2));

Layer Handling

In Draw and Impress, each shape is associated to exactly one layer. The layer has properties that specify if connected shapes are visible, printable or editable.

The service <idl>com.sun.star.drawing.DrawingDocument</idl> implements the interface <idl>com.sun.star.drawing.XLayerSupplier</idl> that gives access to the <idl>com.sun.star.drawing.XLayerManager</idl> interface. The <idl>com.sun.star.drawing.XLayerManager</idl> interface is used to create and edit a layer, and is used to attach a layer to a shape.

XShapes xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xPage);
XShape xRect1 = ShapeHelper.createShape(xComponent, new Point(1000, 1000), new Size(5000, 5000),
    "com.sun.star.drawing.RectangleShape");
XShape xRect2 = ShapeHelper.createShape(xComponent, new Point(1000, 7000), new Size(5000, 5000),
    "com.sun.star.drawing.RectangleShape" );
xShapes.add(xRect1);
xShapes.add(xRect2);
XPropertySet xTextProp = ShapeHelper.addPortion(xRect2, "this shape is locked", false);
xTextProp.setPropertyValue("ParaAdjust", ParagraphAdjust.CENTER);
ShapeHelper.addPortion(xRect2, "and the shape above is not visible", true);
ShapeHelper.addPortion(xRect2, "(switch to the layer view to gain access)", true);
// query for the XLayerManager
XLayerSupplier xLayerSupplier = (XLayerSupplier)UnoRuntime.queryInterface(
    XLayerSupplier.class, xComponent);
XNameAccess xNameAccess = xLayerSupplier.getLayerManager();
XLayerManager xLayerManager = (XLayerManager)UnoRuntime.queryInterface(
    XLayerManager.class, xNameAccess);
// create a layer and set its properties
XPropertySet xLayerPropSet;
XLayer xNotVisibleAndEditable = xLayerManager.insertNewByIndex(xLayerManager.getCount());
xLayerPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xNotVisibleAndEditable);
xLayerPropSet.setPropertyValue("Name", "NotVisibleAndEditable");
xLayerPropSet.setPropertyValue("IsVisible", new Boolean(false));
xLayerPropSet.setPropertyValue("IsLocked", new Boolean(true));
// create a second layer
XLayer xNotEditable = xLayerManager.insertNewByIndex(xLayerManager.getCount());
xLayerPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xNotEditable);
xLayerPropSet.setPropertyValue("Name", "NotEditable" );
xLayerPropSet.setPropertyValue("IsVisible", new Boolean(true));
xLayerPropSet.setPropertyValue("IsLocked", new Boolean(true));
// attach the layer to the rectangles
xLayerManager.attachShapeToLayer(xRect1, xNotVisibleAndEditable);
xLayerManager.attachShapeToLayer(xRect2, xNotEditable);

Inserting Files

Currently it is not possible to insert slides from a drawing or presentation into a drawing document through API. To accomplish this, use the Insert – File command from the menu.

Navigating

Initially, shapes in a document can only be accessed by their index. The only method to get more information about a shape on the page is to test for the shape type, so it is impossible to identify a particular shape. However, after a shape is inserted, you can name it in the user interface or through the shape interface <idl>com.sun.star.container.XNamed</idl>, and identify the shape by its name after retrieving it by index. Shapes cannot be accessed by their names.

Searching and replacing text in Drawing documents retrieves the shapes that contain the text that is searched for. For more information, refer to Search and Replace.

Handling Presentation Document Files

Creating and Loading Presentation Documents

The URL that must be used with loadComponentFromURL() for new presentation documents is "private:factory/simpress".

To avoid the initial dialog in new presentation documents, set the property Silent defined in <idl>com.sun.star.document.MediaDescriptor</idl> to true. This property has to be used with the sequence of PropertyValue structs that is passed to loadComponentFromURL().

The snippet below loads a new presentation document in silent mode:

// the method getRemoteServiceManager is described in the chapter First Steps
mxRemoteServiceManager = this.getRemoteServiceManager();

// retrieve the Desktop object, we need its XComponentLoader
Object desktop = mxRemoteServiceManager.createInstanceWithContext(
    "com.sun.star.frame.Desktop", mxRemoteContext);

// query the XComponentLoader interface from the Desktop service
XComponentLoader xComponentLoader = (XComponentLoader)UnoRuntime.queryInterface(
    XComponentLoader.class, desktop);

// define load properties according to com.sun.star.document.MediaDescriptor
// the boolean property Silent tells the office to suppress the impress startup wizard
PropertyValue[] loadProps = new PropertyValue[1];
loadProps[0] = new PropertyValue();
loadProps[0].Name = "Silent";
loadProps[0].Value = new Boolean(true);

// load
com.sun.star.uno.XComponent xComponentLoader.loadComponentFromURL(
    "private:factory/simpress", "_blank", 0, loadProps);

Printing Presentation Documents

Presentation documents have the following specific properties to define if the notes and outline view should be printed:

Properties of <idl>com.sun.star.presentation.DocumentSettings</idl>
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintNotes</idlm> boolean - Specifies if the notes are also printed.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintOutline</idlm> boolean - Specifies if the outline is also printed.

Settings describes how these settings are used.

Working with Presentation Documents

The structure of Impress documents is enhanced by a handout page per document, one notes page per draw page, and one notes master page for each master page. This means that the creation of normal draw and draw master pages automatically create corresponding notes and notes master pages. Due to this fact there are no interfaces for creation or deletion of notes or notes master pages.

The following UML diagram describes the whole page structure of Impress. The horizontal dotted line illustrates the general page structure lying beneath the dotted line, and the enhanced page structure of Impress lying above.

PresentationDocument

Calling getDrawPages() at the <idl>com.sun.star.drawing.XDrawPagesSupplier</idl> interface of a presentation document retrieves a collection of <idl>com.sun.star.presentation.DrawPage</idl> instances with presentation specific properties.

The following two examples demonstrate how to access the notes pages and the handout page of an Impress document:

/** in Impress documents each draw page as also each draw master page has
    a corresponding notes page
*/
static public XDrawPage getNotesPage(XDrawPage xDrawPage) {
    XDrawPage xNotesPage;
    XPresentationPage xPresentationPage = (XPresentationPage)UnoRuntime.queryInterface(
        XPresentationPage.class, xDrawPage);
    /* only Impress pages support the XPresentationPage interface,
        for all other pages the interface will be zero, so a test
        won't hurt
    */
    if (xPresentationPage != null)
        xNotesPage = xPresentationPage.getNotesPage();
    return xNotesPage;
}

The notes master page that corresponds to a notes page can be accessed by the <idl>com.sun.star.presentation.XPresentation</idl> interface of the master page.

/** in impress each document has one handout page */
static public XDrawPage getHandoutMasterPage(XComponent xComponent) {
    XHandoutMasterSupplier aHandoutMasterSupplier =
        (XHandoutMasterSupplier)UnoRuntime.queryInterface(
            XHandoutMasterSupplier.class, xComponent);
    return aHandoutMasterSupplier.getHandoutMasterPage();
}

Presentation Settings

Impress documents contain a Presentation service that controls a running presentation. This <idl>com.sun.star.presentation.Presentation</idl> service can be accessed through the <idl>com.sun.star.presentation.XPresentationSupplier</idl> interface through the method:

com::sun::star::presentation::XPresentation getPresentation()

The method getPresentation() returns a <idl>com.sun.star.presentation.Presentation</idl> service. It contains properties for presentation settings and the interface <idl>com.sun.star.presentation.XPresentation</idl>.

The presentation settings define the slide range, which custom show is used, and how the presentation is executed. These settings are provided as properties of the service <idl>com.sun.star.presentation.Presentation</idl>. This service also exports the <idl>com.sun.star.presentation.XPresentation</idl> interface that starts and ends a presentation.

Methods of <idl>com.sun.star.presentation.XPresentation</idl>
<idlm>com.sun.star.presentation.XPresentation:start</idlm>() Starts the presentation in full-screen mode.
<idlm>com.sun.star.presentation.XPresentation:end</idlm>() Stops the presentation.
<idlm>com.sun.star.presentation.XPresentation:rehearseTimings</idlm>() Starts the presentation from the beginning and shows the actual running time to the user.
Properties of <idl>com.sun.star.presentation.Presentation</idl>
<idlm>com.sun.star.presentation.Presentation:AllowAnimations</idlm> boolean - Enables/disables the shape animations.
<idlm>com.sun.star.presentation.Presentation:CustomShow</idlm> string - Contains the name of a customized show that is used for the presentation.
Presentation:FirstPage string - Contains the name of the page where the presentation is started.
<idlm>com.sun.star.presentation.Presentation:IsAlwaysOnTop</idlm> boolean - If true, the window of the presentation is always on top of all the other windows.
<idlm>com.sun.star.presentation.Presentation:IsAutomatic</idlm> boolean - If true, all pages are changed automatically.
<idlm>com.sun.star.presentation.Presentation:IsEndless</idlm> boolean - If true, the presentation is repeated endlessly.
<idlm>com.sun.star.presentation.Presentation:IsFullScreen</idlm> boolean - If true, the presentation runs in full-screen mode.
<idlm>com.sun.star.presentation.Presentation:IsLivePresentation</idlm> boolean - With this property, the presentation is set to live mode.
<idlm>com.sun.star.presentation.Presentation:IsMouseVisible</idlm> boolean - If true, the mouse is visible during the presentation.
<idlm>com.sun.star.presentation.Presentation:Pause</idlm> long - Duration of the black screen after the presentation has finished.
<idlm>com.sun.star.presentation.Presentation:StartWithNavigator</idlm> boolean - If true, the Navigator is opened at the start of the presentation.
<idlm>com.sun.star.presentation.Presentation:UsePen</idlm> boolean - If true, a pen is shown during presentation.
<idlm>com.sun.star.presentation.Presentation:IsShowAll</idlm> boolean - Show all slides.
<idlm>com.sun.star.presentation.Presentation:IsShowLogo</idlm> boolean - Show LibreOffice logo on pause page in automatic mode.
<idlm>com.sun.star.presentation.Presentation:IsTransitionOnClick</idlm> boolean - Slide change on mouse click, in addition to pressing cursor right.

The properties IsShowAll, IsShowLogo and IsTransitionOnClick are currently not documented in the API reference.

The next example demonstrates how to start a presentation that is automatically repeated and plays in full-screen mode by modifying the presentation settings.

XPresentationSupplier xPresSupplier = (XPresentationSupplier)UnoRuntime.queryInterface(
    XPresentationSupplier.class, xComponent);
XPresentation xPresentation = xPresSupplier.getPresentation();
XPropertySet xPresPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xPresentation);
xPresPropSet.setPropertyValue("IsEndless", Boolean.TRUE);
xPresPropSet.setPropertyValue("IsFullScreen", Boolean.TRUE);
xPresPropSet.setPropertyValue("Pause", new Integer(0));
xPresentation.start();

Custom Slide Show

Custom presentations are available at the <idl>com.sun.star.presentation.XCustomPresentationSupplier</idl> interface of the presentation document. It contains the method:

com::sun::star::container::XNameContainer getCustomPresentations()

The method getCustomPresentations() returns a <idl>com.sun.star.presentation.CustomPresentationAccess</idl> service that consists of the interfaces <idl>com.sun.star.container.XNameContainer</idl> and <idl>com.sun.star.lang.XSingleServiceFactory</idl>. The standard API interface <idl>com.sun.star.container.XNameContainer</idl> derived from <idls>com.sun.star.container.XNameContainer</idls> obtains existing Custom Presentations and to add new custom presentations by name. It introduces the methods:

void replaceByName( [in] string aName, [in] any aElement)

void insertByName( [in] string aName, [in] any aElement)
void removeByName( [in] string Name)

To add a new CustomPresentation, create it using createInstance() at the XSingleServiceFactory interface of the CustomPresentationAccess.

Methods of <idl>com.sun.star.lang.XSingleServiceFactory</idl>:

com::sun::star::uno::XInterface createInstance()
com::sun::star::uno::XInterface createInstanceWithArguments( [in] sequence< any aArguments >)

The CustomPresentation is now created. Its content consists of a <idl>com.sun.star.presentation.CustomPresentation</idl>. From the API, it is a named container of selected presentation draw pages. Draw pages can be added to a custom presentation or removed using its interface <idl>com.sun.star.container.XIndexContainer</idl>. In addition to the methods of an XIndexAccess, this standard API interface supports the following operations:

Methods introduced by com.sun.star.container.XIndexContainer:

void replaceByIndex( [in] long Index, [in] any Element)
void insertByIndex( [in] long Index, [in] any Element)
void removeByIndex( [in] long Index)

The name of a CustomPresentation is read and written using the interface <idl>com.sun.star.container.XNamed</idl>:

Methods of XNamed:

string getName()
void setName( [in] string aName)

A custom show is a collection of slides in a user-defined order that can be executed as a presentation. It is also possible to use a slide twice or skip slides. For instance, it is possible to create a short version of a presentation and a long version within the same document. The number of custom shows is unlimited.

The next example demonstrates how to create two custom shows and set one of them as an active presentation.

XDrawPagesSupplier xDrawPagesSupplier = (XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
// take care that this document has ten pages
while (xDrawPages.getCount() < 10)
    xDrawPages.insertNewByIndex(0);
// assign a name to each page
String aNameArray[] = {"Introduction", "page one", "page two", "page three", "page four",
                        "page five", "page six", "page seven", "page eight", "page nine"};
int i;
for (i = 0; i < 10; i++) {
    XNamed xPageName = (XNamed)UnoRuntime.queryInterface(XNamed.class, xDrawPages.getByIndex(i));
    xPageName.setName(aNameArray[i]);
}
/* create two custom shows, one will play slide 6 to 10 and is named "ShortVersion"
    the other one will play slide 2 til 10 and is named "LongVersion"
*/
XCustomPresentationSupplier xCustPresSupplier = (XCustomPresentationSupplier)
    UnoRuntime.queryInterface(XCustomPresentationSupplier.class, xComponent);
/* the following container is a container for further container
    which concludes the list of pages that are to play within a custom show
*/
XNameContainer xNameContainer = xCustPresSupplier.getCustomPresentations();
XSingleServiceFactory xFactory = (XSingleServiceFactory)UnoRuntime.queryInterface(
    XSingleServiceFactory.class, xNameContainer);
Object xObj;
XIndexContainer xContainer;
/* instanciate an IndexContainer that will take
    a list of draw pages for the first custom show
*/
xObj = xFactory.createInstance();
xContainer = (XIndexContainer)
    UnoRuntime.queryInterface(XIndexContainer.class, xObj);
for (i = 5; i < 10; i++)
    xContainer.insertByIndex(xContainer.getCount(), xDrawPages.getByIndex(i));
xNameContainer.insertByName("ShortVersion", xContainer);
/* instanciate an IndexContainer that will take
    a list of draw page for a second custom show
*/
xObj = xFactory.createInstance();
xContainer = (XindexContainer)UnoRuntime.queryInterface(XIndexContainer.class, xObj);
for (i = 1; i < 10; i++)
    xContainer.insertByIndex(xContainer.getCount(), xDrawPages.getByIndex(i));
xNameContainer.insertByName("LongVersion", xContainer);
/* which custom show is to use
    can been set in the presentation settings
*/
XPresentationSupplier xPresSupplier = (XPresentationSupplier)UnoRuntime.queryInterface(
    XPresentationSupplier.class, xComponent);
XPresentation xPresentation = xPresSupplier.getPresentation();
XPropertySet xPresPropSet = (XPropertySet)UnoRuntime.queryInterface(
    XPropertySet.class, xPresentation);
xPresPropSet.setPropertyValue("CustomShow", "ShortVersion");

Presentation Effects

There are two kinds of presentation effects, the fading of one page to another, and the animation of objects and texts within a slideshow.

Slide Transition

In Impress, each page has its own slide transition that can be composed by the properties of the service <idl>com.sun.star.presentation.DrawPage</idl>.

Setting the following properties enables slide transition:

Properties of <idl>com.sun.star.presentation.DrawPage</idl>
<idlm>com.sun.star.presentation.DrawPage:Change</idlm> long - Specifies how the page change is triggered. If this is 0, the user must click to start each object animation and to change the page. If set to 1, the page is automatically switched. If it is set to 2, all object effects run automatically, but the user has to click on the page to change it.
<idlm>com.sun.star.presentation.DrawPage:Duration</idlm> long - If the property Change is set to 1, this property is the time in seconds the page is shown, before switching to the next page.
<idlm>com.sun.star.presentation.DrawPage:Effect</idlm> <idl>com.sun.star.presentation.FadeEffect</idl>. This is the effect that is used to fade in the page.
<idlm>com.sun.star.presentation.DrawPage:Speed</idlm> <idl>com.sun.star.presentation.AnimationSpeed</idl>. Defines the speed of the fade-in effect of the page. Possible values are:
  • SLOW sets the speed from the animation or fade to slow.
  • MEDIUM sets the speed from the animation or fade to medium.
  • FAST sets the speed from the animation or fade to fast.
<idlm>com.sun.star.presentation.DrawPage:Layout</idlm> short - This number specifies a presentation layout for this page, if this property is not ZERO.

The next table contains all available <idl>com.sun.star.presentation.FadeEffect</idl> enum values:

NONE RANDOM DISSOLVE
FADE_FROM_LEFT

FADE_FROM_RIGHT
FADE_FROM_TOP
FADE_FROM_BOTTOM
FADE_FROM_UPPERLEFT
FADE_FROM_UPPERRIGHT
FADE_FROM_LOWERLEFT
FADE_FROM_LOWERRIGHT

MOVE_FROM_LEFT

MOVE_FROM_RIGHT
MOVE_FROM_TOP
MOVE_FROM_BOTTOM
MOVE_FROM_UPPERLEFT
MOVE_FROM_UPPERRIGHT
MOVE_FROM_LOWERRIGHT
MOVE_FROM_LOWERLEFT

UNCOVER_TO_LEFT

UNCOVER_TO_RIGHT
UNCOVER_TO_TOP
UNCOVER_TO_BOTTOM
UNCOVER_TO_UPPERLEFT
UNCOVER_TO_UPPERRIGHT
UNCOVER_TO_LOWERRIGHT
UNCOVER_TO_LOWERLEFT

FADE_TO_CENTER

FADE_FROM_CENTER

VERTICAL_STRIPES

HORIZONTAL_STRIPES

CLOCKWISE

COUNTERCLOCKWISE

ROLL_FROM_LEFT

ROLL_FROM_RIGHT
ROLL_FROM_TOP
ROLL_FROM_BOTTOM

CLOSE_VERTICAL

CLOSE_HORIZONTAL
OPEN_VERTICAL
OPEN_HORIZONTAL

SPIRALIN_LEFT

SPIRALIN_RIGHT
SPIRALOUT_LEFT
SPIRALOUT_RIGHT

WAVYLINE_FROM_LEFT

WAVYLINE_FROM_RIGHT
WAVYLINE_FROM_TOP
WAVYLINE_FROM_BOTTOM

STRETCH_FROM_LEFT

STRETCH_FROM_RIGHT
STRETCH_FROM_TOP
STRETCH_FROM_BOTTOM

VERTICAL_LINES

HORIZONTAL_LINES

VERTICAL_CHECKERBOARD

HORIZONTAL_CHECKERBOARD

The following Java example shows how to set slide transition effects that are applied to the first page.

// set the slide transition effect of the first page
XDrawPagesSupplier xDrawPagesSupplier =(XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
XDrawPage xDrawPage = (XdrawPage)UnoRuntime.queryInterface(XDrawPage.class,
    xDrawPages.getByIndex(0));
xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPage);
XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xDrawPage);
// set the slide transition effect properties
xPropSet.setPropertyValue("Effect", com.sun.star.presentation.FadeEffect.RANDOM);
xPropSet.setPropertyValue("Speed", com.sun.star.presentation.AnimationSpeed.MEDIUM);
/* Change specifies how the page change is triggered. If this
    is 0, the user must click to start each object animation
    and to change the page. If set to 1, the page is
    automatically switched. If it is set to 2, all object
    effects run automatically, but the user has to click on the
    page to change it.
*/
xPropSet.setPropertyValue("Change", new Integer(1));
/* If the property DrawPage::Change is set to 1, Duration specifies the
    time in seconds the page is shown before switching to the next page.
*/
xPropSet.setPropertyValue("Duration", new Integer(5));

Animations and Interactions

In a Presentation, each shape of the draw and master page provides the <idl>com.sun.star.presentation.Shape</idl> service with a number of properties that describe the manner the shape is displayed or acting in a presentation.

There are two kinds of shape effects. The first kind of effects are visual changes, such as animations and dimming effects. The second kind of effects are OnClick actions. All of these effects are controlled by the properties of a presentation shape:

Properties of <idl>com.sun.star.presentation.Shape</idl>
<idlm>com.sun.star.presentation.Shape:OnClick</idlm> <idl>com.sun.star.presentation.ClickAction</idl>. Selects an action performed after the user clicks on this shape. Possible values are:
  • NONE - no action is performed on click
  • PREVPAGE - the presentation jumps to the previous page
  • NEXTPAGE - the presentation jumps to the next page
  • FIRSTPAGE - the presentation continues with the first page
  • LASTPAGE - the presentation continues with the last page
  • BOOKMARK - the presentation jumps to the bookmark URL defined in the shape property Bookmark
  • DOCUMENT - the presentation jumps to the document given in Bookmark. It selects the object whose name is given after a # in the Bookmark URL.
  • INVISIBLE - the object renders itself invisible after a click
  • SOUND - the sound specified in Sound is played after a click
  • VERB - the OLE verb specified in the shape property Verb is performed on this object
  • VANISH - the object vanishes with the effect specified in the property Effect
  • PROGRAM - the program specified in Bookmark is executed after a click
  • MACRO - the LibreOffice Basic macro specified in Bookmark is executed after the click. For the syntax of Basic macro URLs, refer to the chapter LibreOffice Basic.
  • STOPPRESENTATION - the presentation is stopped after the click
<idlm>com.sun.star.presentation.Shape:Bookmark</idlm> string - A generic URL for the property OnClick.
<idlm>com.sun.star.presentation.Shape:Verb</idlm> long - Valid only for OLE shapes. Specifies an "OLE2" verb for the ClickAction VERB in the property OnClick. For possible verbs, select the OLE shape, and point the cursor to Edit - Object. The order of appearance corresponds to the value needed for Verb.
<idlm>com.sun.star.presentation.Shape:DimPrevious</idlm> boolean - Only valid when Effect contains an AnimationEffect. If true, this shape is painted using DimColor on the next click after finishing the AnimationEffect.
<idlm>com.sun.star.presentation.Shape:DimHide</idlm> boolean - Only valid when Effect contains an AnimationEffect. If this property and the property DimPrevious are both true, the shape is hidden on the next click after the AnimationEffect has finished.
<idlm>com.sun.star.presentation.Shape:DimColor</idlm> long - Only valid when Effect contains an AnimationEffect. This color is used to paint the shape on the next click after the animation effect has finished. The property DimPrevious must be true and DimHide must be false for this property to work.
<idlm>com.sun.star.presentation.Shape:Effect</idlm> <idl>com.sun.star.presentation.AnimationEffect</idl>. Selects the animation effect of this shape. For possible values see the table below.
<idlm>com.sun.star.presentation.Shape:PresentationOrder</idlm> long - This is the position of this shape in the order of the shapes that can be animated on its page. The animations are executed in the order given in PresentationOrder, starting at the shape with the PresentationOrder 1. You can change the order by changing this number. Setting it to 1 makes this shape the first shape in the execution order for the animation effects.
<idlm>com.sun.star.presentation.Shape:SoundOn</idlm> boolean - If true, the sound file specified in Sound is played while the animation effect is executed.
<idlm>com.sun.star.presentation.Shape:Sound</idlm> string - This is the URL to a sound file that is played while the animation effect of this shape is running.
<idlm>com.sun.star.presentation.Shape:PlayFull</idlm> boolean - If true, the sound specified in the Sound property of this shape is played completely. If false, the sound stops after completing the AnimationEffect specified in Effect.
<idlm>com.sun.star.presentation.Shape:Speed</idlm> <idl>com.sun.star.presentation.AnimationSpeed</idl> This is the speed of the animation effect. Possible values: SLOW, MEDIUM, and FAST.
<idlm>com.sun.star.presentation.Shape:TextEffect</idlm> <idl>com.sun.star.presentation.AnimationEffect</idl>. This is the animation effect for the text inside this shape. For possible values, see the table below.
<idlm>com.sun.star.presentation.Shape:IsEmptyPresentationObject</idlm> [readonly] boolean - If this is a default presentation object and if it is empty, this property is true.
<idlm>com.sun.star.presentation.Shape:IsPresentationObject</idlm> [readonly] boolean - If true, a shape is part of the current AutoLayout and is considered a presentation object. AutoLayouts are predefined page layouts consisting of shapes, such as a title box and an outline box.

The next table contains all available <idl>com.sun.star.presentation.AnimationEffect</idl> enums.

NONE RANDOM DISSOLVE
APPEAR HIDE PATH
FADE_FROM_LEFT

FADE_FROM_RIGHT
FADE_FROM_TOP
FADE_FROM_BOTTOM
FADE_FROM_UPPERLEFT
FADE_FROM_UPPERRIGHT
FADE_FROM_LOWERLEFT
FADE_FROM_LOWERRIGHT

MOVE_FROM_LEFT

MOVE_FROM_RIGHT
MOVE_FROM_TOP
MOVE_FROM_BOTTOM
MOVE_FROM_UPPERLEFT
MOVE_FROM_UPPERRIGHT
MOVE_FROM_LOWERRIGHT
MOVE_FROM_LOWERLEFT

ZOOM_IN_FROM_LEFT

ZOOM_IN_FROM_RIGHT
ZOOM_IN_FROM_TOP
ZOOM_IN_FROM_BOTTOM
ZOOM_IN_FROM_UPPERLEFT
ZOOM_IN_FROM_UPPERRIGHT
ZOOM_IN_FROM_LOWERRIGHT
ZOOM_IN_FROM_LOWERLEFT

CLOCKWISE

COUNTERCLOCKWISE

CLOSE_VERTICAL

CLOSE_HORIZONTAL

OPEN_VERTICAL

OPEN_HORIZONTAL

LASER_FROM_LEFT

LASER_FROM_RIGHT
LASER_FROM_TOP
LASER_FROM_BOTTOM
LASER_FROM_UPPERLEFT
LASER_FROM_UPPERRIGHT
LASER_FROM_LOWERLEFT
LASER_FROM_LOWERRIGHT

MOVE_TO_LEFT

MOVE_TO_RIGHT
MOVE_TO_TOP
MOVE_TO_BOTTOM
MOVE_TO_UPPERLEFT
MOVE_TO_UPPERRIGHT
MOVE_TO_LOWERRIGHT
MOVE_TO_LOWERLEFT

MOVE_SHORT_TO_LEFT

MOVE_SHORT_TO_RIGHT
MOVE_SHORT_TO_TOP
MOVE_SHORT_TO_BOTTOM
MOVE_SHORT_TO_UPPERLEFT
MOVE_SHORT_TO_UPPERRIGHT
MOVE_SHORT_TO_LOWERRIGHT
MOVE_SHORT_TO_LOWERLEFT

ZOOM_OUT_FROM_LEFT

ZOOM_OUT_FROM_RIGHT
ZOOM_OUT_FROM_TOP
ZOOM_OUT_FROM_BOTTOM
ZOOM_OUT_FROM_UPPERLEFT
ZOOM_OUT_FROM_UPPERRIGHT
ZOOM_OUT_FROM_LOWERRIGHT
ZOOM_OUT_FROM_LOWERLEFT

STRETCH_FROM_LEFT

STRETCH_FROM_RIGHT
STRETCH_FROM_TOP
STRETCH_FROM_BOTTOM
STRETCH_FROM_UPPERLEFT
STRETCH_FROM_UPPERRIGHT
STRETCH_FROM_LOWERRIGHT
STRETCH_FROM_LOWERLEFT

MOVE_SHORT_FROM_LEFT

MOVE_SHORT_FROM_RIGHT
MOVE_SHORT_FROM_TOP
MOVE_SHORT_FROM_BOTTOM
MOVE_SHORT_FROM_UPPERLEFT
MOVE_SHORT_FROM_UPPERRIGHT
MOVE_SHORT_FROM_LOWERRIGHT
MOVE_SHORT_FROM_LOWERLEFT

WAVYLINE_FROM_LEFT

WAVYLINE_FROM_RIGHT
WAVYLINE_FROM_TOP
WAVYLINE_FROM_BOTTOM

SPIRALIN_LEFT

SPIRALIN_RIGHT
SPIRALOUT_LEFT
SPIRALOUT_RIGHT

FADE_FROM_CENTER

FADE_TO_CENTER
VERTICAL_STRIPES
HORIZONTAL_STRIPES

ZOOM_IN

ZOOM_IN_SMALL
ZOOM_IN_SPIRAL

ZOOM_OUT

ZOOM_OUT_SMALL
ZOOM_OUT_SPIRAL

VERTICAL_LINES

HORIZONTAL_LINES

ZOOM_IN_FROM_CENTER

ZOOM_OUT_FROM_CENTER

VERTICAL_CHECKERBOARD

HORIZONTAL_CHECKERBOARD

VERTICAL_ROTATE

HORIZONTAL_ROTATE

HORIZONTAL_STRETCH

VERTICAL_STRETCH

The next example demonstrates how to set object effects and object interaction.

The example use a method createAndInsertShape() from the ShapeHelper class. It takes the drawing document, the XShapes interface of the DrawPage the shape is to be inserted in, the position and size of the new shape, and the service name of the required shape. It delegates shape creation to the helper method createShape() and inserts the new shape into the given XShapes container. Finally, it retrieves the XPropertySet interface of the inserted shape and returns it to the caller.

public static XPropertySet createAndInsertShape( XComponent xDrawDoc,
        XShapes xShapes, Point aPos, Size aSize, String sShapeType) throws java.lang.Exception {
    XShape xShape = createShape(xDrawDoc, aPos, aSize, sShapeType);
    xShapes.add(xShape);
    XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xShape);
    return xPropSet;
}

The following example shows animations and OnClick actions for four shapes. On click, the first shape builds up in a wavy line from the bottom and is dimmed (painted) red afterwards. The second shape is hidden on click. Clicking the third shape makes the presentation jump to the first page, whereas clicking the fourth shape jumps to a bookmark. The bookmark contains the name of the second slide "page - two".

XShapes xShapes;
XPropertySet xShapePropSet;
XDrawPagesSupplier xDrawPagesSupplier = (XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
// create pages, so that three are available
while (xDrawPages.getCount() < 3)
    xDrawPages.insertNewByIndex(0);
// get the shape container for page one
xShapes = (XShapes)UnoRuntime.queryInterface(
    XShapes.class, xDrawPages.getByIndex(0));
// create a rectangle that is placed on the top left of the page
xShapePropSet = ShapeHelper.createAndInsertShape( xComponent,
    xShapes, new Point(1000, 1000), new Size(5000, 5000),
    "com.sun.star.drawing.RectangleShape" );
// and now set an object animation
xShapePropSet.setPropertyValue("Effect",
    com.sun.star.presentation.AnimationEffect.WAVYLINE_FROM_BOTTOM);
/* the following three properties provoke that the shape is dimmed to red
    after the animation has been finished
*/
xShapePropSet.setPropertyValue("DimHide", new Boolean(false));
xShapePropSet.setPropertyValue("DimPrevious", new Boolean(true));
xShapePropSet.setPropertyValue("DimColor", new Integer(0xff0000));
// get the shape container for the second page
xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPages.getByIndex(1));
// create an ellipse that is placed on the bottom right of second page
xShapePropSet = ShapeHelper.createAndInsertShape( xComponent, xShapes,
    new Point(21000, 15000), new Size(5000, 5000), "com.sun.star.drawing.EllipseShape");
xShapePropSet.setPropertyValue("Effect", com.sun.star.presentation.AnimationEffect.HIDE);
/* create two objects for the third page.
    clicking the first object lets the presentation jump
    to page one by using ClickAction.FIRSTPAGE,
    the second object lets the presentation jump to page two
    by using a ClickAction.BOOKMARK
*/
xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPages.getByIndex(2));
xShapePropSet = ShapeHelper.createAndInsertShape(xComponent, xShapes,
    new Point(1000, 8000), new Size(5000, 5000),
    "com.sun.star.drawing.EllipseShape" );
xShapePropSet.setPropertyValue("Effect", com.sun.star.presentation.AnimationEffect.FADE_FROM_BOTTOM );
xShapePropSet.setPropertyValue("OnClick", com.sun.star.presentation.ClickAction.FIRSTPAGE);
xShapePropSet = ShapeHelper.createAndInsertShape(xComponent, xShapes,
    new Point(22000, 8000), new Size(5000, 5000),
    "com.sun.star.drawing.RectangleShape");
xShapePropSet.setPropertyValue("Effect", com.sun.star.presentation.AnimationEffect.FADE_FROM_BOTTOM);
xShapePropSet.setPropertyValue( "OnClick", com.sun.star.presentation.ClickAction.BOOKMARK);
// set the name of page two, and use it with the bookmark action
XNamed xPageName = (Xnamed)UnoRuntime.queryInterface(XNamed.class, xDrawPages.getByIndex(1));
xPageName.setName("page - two");
xShapePropSet.setPropertyValue("Bookmark", xPageName.getName());

Overall Document Features

Styles

Graphics Styles

Graphics Styles are available in drawing and presentation documents, and they control the formatting of the drawing shapes in drawing or presentation slides. In contrast to styles in text documents, the style property of a shape is not a string, but a <idl>com.sun.star.style.XStyle</idl>. To work with an existing graphics style, get the styles container from the <idl>com.sun.star.style.XStyleFamiliesSupplier</idl> and use its <idl>com.sun.star.container.XNameAccess</idl> to retrieve the style family named "graphics". The programmatic names of the style families in graphics are:

GUI name Programmatic name Remark
Default standard The style Default (standard) is used for newly inserted filled rectangles, filled ellipses, lines, connectors, text boxes, and 3D objects.
Dimension Line measure Used for newly inserted dimension lines.
First line indent textbodyindent Apply manually.
Heading headline Apply manually.
Heading1 headline1 Apply manually.
Heading2 headline2 Apply manually.
Object with Arrow objectwitharrow Apply manually.
Object with shadow objectwithshadow Apply manually.
Object without fill objectwithoutfill Used for newly inserted rectangles and ellipses without filling.
Text text Newly inserted text boxes do not use this style. They use Default and remove the fill settings for Default.
Text body textbody Apply manually.
Text body justified textbodyjustfied Apply manually.
Title title Apply manually.
Title1 title1 Apply manually.
Title2 title2 Apply manually.

There are two methods to change an applied shape style:

  • Retrieve the style from the style family "graphics" by its programmatic name, change the properties, and put back into the style family using replaceByName() at the style family's <idl>com.sun.star.container.XNameContainer</idl> interface.
  • Apply an existing style object that is not applied to a shape by setting the shape's style property.

New styles can be created, as well. For this purpose, use createInstance() at the document factory of a drawing document and ask for a "com.sun.star.style.Style" service. Set the properties of the new style, as required. Append the new style to the style family "graphics" using insertByName() at its XNameContainer interface. Now use the Style property of existing shapes to put the new style to work.

You can either change a currently applied shape style by retrieving it from the style family "graphics" by its programmatic name, changing its properties and putting it back into the style family using replaceByName() at the style family's <idl>com.sun.star.container.XNameContainer</idl> interface. Or you can apply an existing, but currently unapplied style object to a shape by setting the shape's Style property accordingly.

You can create new styles as well. For this purpose, use createInstance() at the document factory of a drawing document and ask for a "com.sun.star.style.Style" service. Set the properties of the new style as needed. Afterwards append the new style to the style family "graphics" using insertByName() at its XNameContainer interface. Now you can use the Style property of existing shapes in order to put your new style to work.

Styles created by the document factory support the properties of the following services:

  • <idl>com.sun.star.drawing.FillProperties</idl>
  • <idl>com.sun.star.drawing.LineProperties</idl>
  • <idl>com.sun.star.drawing.ShadowProperties</idl>
  • <idl>com.sun.star.drawing.ConnectorProperties</idl>
  • <idl>com.sun.star.drawing.MeasureProperties</idl>
  • <idl>com.sun.star.style.ParagraphProperties</idl>
  • <idl>com.sun.star.style.CharacterProperties</idl>
  • <idl>com.sun.star.drawing.TextProperties</idl>

Presentation Styles

Presentation styles are only available in presentation documents and control the formatting of the following parts of a presentation:

  • title text
  • subtitle text
  • outline text
  • background
  • background shapes
  • notes text

The corresponding style family has the programmatic name "Default" and is available at the <idls>com.sun.star.style.XStyleFamiliesSupplier</idls> of a presentation document.

GUI Name Programmatic Name Remark
Title title Style for text of new title presentation objects.
Subtitle subtitle Style that is used for the presentation object on pages with a "Title Slide" layout.
Background background Style for the page background.
Background objects backgroundobjects Style for shapes on the background.
notes Notes Style for notes text.
outline1 Outline 1 Style for outline level 1.
outline2 Outline 2 Style for outline level 2.
outline3 Outline 3 Style for outline level 3.
outline4 Outline 4 Style for outline level 4.
outline5 Outline 5 Style for outline level 5.
outline6 Outline 6 Style for outline level 6.
outline7 Outline 7 Style for outline level 7.
outline8 Outline 8 Style for outline level 8.
outline9 Outline 9 Style for outline level 9.

Existing presentation styles can only be altered. New styles can not be created and a different presentation style cannot be applied other than the current one. The following example works with presentation styles.

You can only alter existing presentation styles. You cannot create new styles and you cannot apply a different presentation style other than the current one. The following example works with presentation styles:

// The first part of this demo will set each "CharColor" Property
// that is available within the styles of the document to red. It
// will also print each family and style name to the standard output

XModel xModel = (XModel)UnoRuntime.queryInterface(XModel.class, xComponent);
com.sun.star.style.XStyleFamiliesSupplier xSFS = (com.sun.star.style.XStyleFamiliesSupplier)
    UnoRuntime.queryInterface(com.sun.star.style.XStyleFamiliesSupplier.class, xModel);
com.sun.star.container.XNameAccess xFamilies = xSFS.getStyleFamilies();

// the element should now contain at least two Styles. The first is
// "graphics" and the other one is the name of the Master page
String[] Families = xFamilies.getElementNames();
for (int i = 0; i < Families.length; i++) {
    // this is the family
    System.out.println("\n" + Families[i]);

    // and now all available styles
    Object aFamilyObj = xFamilies.getByName(Families[i]);
    com.sun.star.container.XNameAccess xStyles = (com.sun.star.container.XNameAccess)
        UnoRuntime.queryInterface(com.sun.star.container.XNameAccess.class, aFamilyObj);
    String[] Styles = xStyles.getElementNames();
    for (int j = 0; j < Styles.length; j++) {
        System.out.println( " " + Styles[j]);
        Object aStyleObj = xStyles.getByName(Styles[j]);
        com.sun.star.style.XStyle xStyle = (com.sun.star.style.XStyle)
        UnoRuntime.queryInterface(com.sun.star.style.XStyle.class, aStyleObj);
        // now we have the XStyle Interface and the CharColor for all styles
        // is exemplary be set to red.
        XPropertySet xStylePropSet = (XPropertySet)
            UnoRuntime.queryInterface( XPropertySet.class, xStyle );
        XPropertySetInfo xStylePropSetInfo = xStylePropSet.getPropertySetInfo();
        if (xStylePropSetInfo.hasPropertyByName("CharColor")) {
            xStylePropSet.setPropertyValue("CharColor", new Integer(0xff0000));
        }
    }
}

/* now create a rectangle and apply the "title1" style of
    the "graphics" family
*/
Object obj = xFamilies.getByName("graphics");
com.sun.star.container.XNameAccess xStyles = (XNameAccess)
    UnoRuntime.queryInterface(com.sun.star.container.XNameAccess.class, obj);
obj = xStyles.getByName("title1");
com.sun.star.style.XStyle xTitle1Style = (com.sun.star.style.XStyle)UnoRuntime.queryInterface(
    com.sun.star.style.XStyle.class, obj);

XDrawPagesSupplier xDrawPagesSupplier = (XDrawPagesSupplier)UnoRuntime.queryInterface(
    XDrawPagesSupplier.class, xComponent);
XDrawPages xDrawPages = xDrawPagesSupplier.getDrawPages();
XDrawPage xDrawPage = (XdrawPage)UnoRuntime.queryInterface(XDrawPage.class, xDrawPages.getByIndex(0));
XShapes xShapes = (XShapes)UnoRuntime.queryInterface(XShapes.class, xDrawPage);
XShape xShape = ShapeHelper.createShape(xComponent, new Point(0, 0),
    new Size(5000, 5000), "com.sun.star.drawing.RectangleShape");
xShapes.add(xShape);
XPropertySet xPropSet = (XPropertySet)UnoRuntime.queryInterface(XPropertySet.class, xShape);
xPropSet.setPropertyValue("Style", xTitle1Style);

Settings

To use the global document settings, the document service factory must be asked for a <idl>com.sun.star.document.Settings</idl> service using the method createInstance() at its <idl>com.sun.star.lang.XMultiServiceFactory</idl> interface. This service supports <idl>com.sun.star.beans.PropertySet</idl> and acts upon the current document by setting its properties.

The services <idl>com.sun.star.drawing.DocumentSettings</idl> and <idl>com.sun.star.presentation.DocumentSettings</idl> provide the following properties additionally to the global document settings.

Properties of <idl>com.sun.star.drawing.DocumentSettings</idl>
<idlm>com.sun.star.drawing.DocumentSettings:MeasureUnit</idlm> short - this is the default logical measure unit that is used for string formatings inside the document.
<idlm>com.sun.star.drawing.DocumentSettings:ScaleNumerator</idlm> long - is the numerator for the logical scale of the document.
<idlm>com.sun.star.drawing.DocumentSettings:ScaleDenominator</idlm> long - is the denominator for the logical scale of the document.
<idlm>com.sun.star.drawing.DocumentSettings:IsPrintFitPage</idlm> boolean - this property enables or disables the fitting of the page to the printable area during print, true enable and false disable.
<idlm>com.sun.star.drawing.DocumentSettings:IsPrintTilePage</idlm> boolean - If the property IsPrintTilePage is set to 1 and the paper size for printing is larger than the paper size of the printer than the content is tiled over multiple pages.
<idlm>com.sun.star.drawing.DocumentSettings:PageNumberFormat</idlm> long - is the number format used for page number fields.
<idlm>com.sun.star.drawing.DocumentSettings:ParagraphSummation</idlm> boolean - If the property ParagraphSummation is set to 1, the distance between two paragraphs is the sum of ParaTopMargin of the previous and ParaBottomMargin of the next paragraph. If 0, only the greater of the two is choosen.
Properties of <idl>com.sun.star.presentation.DocumentSettings</idl>
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintDrawing</idlm> boolean - this property enables or disables the printing of the drawing pages, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintNotes</idlm> boolean - this property enables or disables the printing of the notes pages, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintHandout</idlm> boolean - this property enables or disables the printing of the handout pages, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintOutline</idlm> boolean - this property enables or disables the printing of the outline pages, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintHiddenPages</idlm> boolean - this property enables or disables the printing of draw pages that are marked hidden, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintFitPage</idlm> boolean - this property enables or disables the fitting of the page to the printable area during print, true enable and false disable.
<idlm>com.sun.star.presentation.DocumentSettings:IsPrintTilePage</idlm> boolean - If this property IsPrintTilePage is set to 1 and the paper size for printing is larger than the paper size of the printer than the content is tiled over multiple pages.
<idlm>com.sun.star.presentation.DocumentSettings:PageNumberFormat</idlm> long - is the number format used for page number fields.
<idlm>com.sun.star.presentation.DocumentSettings:ParagraphSummation</idlm> boolean - If the property ParagraphSummation is set to 1, the distance between two paragraphs is the sum of ParaTopMargin of the previous and ParaBottomMargin of the next paragraph. If 0, only the greater of the two is choosen.

Page Formatting

As opposed to text and spreadsheet documents, page formatting in drawings and presentations is not done through styles. Rather, hard format the following properties:

Properties of <idl>com.sun.star.drawing.GenericDrawPage</idl>
<idlm>com.sun.star.drawing.GenericDrawPage:BorderBottom</idlm> long
<idlm>com.sun.star.drawing.GenericDrawPage:BorderLeft</idlm> long
<idlm>com.sun.star.drawing.GenericDrawPage:BorderRight</idlm> long
<idlm>com.sun.star.drawing.GenericDrawPage:BorderTop</idlm> long
<idlm>com.sun.star.drawing.GenericDrawPage:Height</idlm> long
<idlm>com.sun.star.drawing.GenericDrawPage:Number</idlm> short
<idlm>com.sun.star.drawing.GenericDrawPage:Orientation</idlm> <idl>com.sun.star.view.PaperOrientation</idl>
<idlm>com.sun.star.drawing.GenericDrawPage:Width</idlm> long

Drawing and Presentation Document Controller

The controller is available at the XModel interface of the document model:

com::sun::star::frame::XController getCurrentController()

Setting the Current Page, Using the Selection

The controller is a <idl>com.sun.star.drawing.DrawingDocumentDrawView</idl> that supports the following interfaces:

  • <idl>com.sun.star.drawing.XDrawView</idl>
  • <idl>com.sun.star.beans.XPropertySet</idl>
  • <idl>com.sun.star.frame.XController</idl>
  • <idl>com.sun.star.view.XSelectionSupplier</idl>

The following methods of <idl>com.sun.star.view.XSelectionSupplier</idl> control the current selection in the GUI:

boolean select( [in] any anObject)
any getSelection()
void addSelectionChangeListener (
    [in] com::sun::star::view::XSelectionChangeListener aListen
void removeSelectionChangeListener (
    [in] com::sun::star::view::XSelectionChangeListener aListener)

With these methods of <idl>com.sun.star.drawing.XDrawView</idl>, the visible page is set in the GUI:

void setCurrentPage(com::sun::star::drawing::XDrawPage aPage)
com::sun::star::drawing::XDrawPage getCurrentPage()

In addition to DrawingDocumentDrawView, it supports the following interfaces. For details about these interfaces, refer to Office Development.

  • <idl>com.sun.star.task.XStatusIndicatorSupplier</idl>
  • <idl>com.sun.star.ui.XContextMenuInterception</idl>
  • <idl>com.sun.star.frame.XDispatchProvider</idl>

Zooming

Zooming can be set by certain drawing-specific controller properties of the <idl>com.sun.star.drawing.DrawingDocumentDrawView</idl>service:

Properties of <idl>com.sun.star.drawing.DrawingDocumentDrawView</idl>
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:VisibleArea</idlm> [readonly] <idl>com.sun.star.awt.Rectangle</idl> - This is the area that is currently visible.
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:ZoomType</idlm> [optional] short - This property defines the zoom type for the document. The values of <idl>com.sun.star.view.DocumentZoomType</idl> are used.
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:ZoomValue</idlm> [optional] short - Defines the zoom value to use. Valid only if the ZoomType is set to BY_VALUE.
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:ViewOffset</idlm> [optional] <idl>com.sun.star.awt.Point</idl> - Defines the offset from the top left position of the displayed page to the top left position of the view area in 100th/mm.

Other Drawing-Specific View Settings

Drawings and presentations can be switched to certain view modes. This is done by the following drawing-specific controller properties of <idl>com.sun.star.drawing.DrawingDocumentDrawView</idl>:

Properties of <idl>com.sun.star.drawing.DrawingDocumentDrawView</idl>
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:IsLayerMode</idlm> boolean - Switch to layer mode.
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:IsMasterPageMode</idlm> boolean - Switch to master page mode.
<idlm>com.sun.star.drawing.DrawingDocumentDrawView:CurrentPage</idlm> <idl>com.sun.star.drawing.XDrawPage</idl> - This is the drawing page that is currently visible.

Furthermore, there are many properties that can be changed through the XViewDataSupplier interface of the document:

Methods of <idl>com.sun.star.document.XViewDataSupplier</idl>:

com::sun::star::container::XIndexAccess getViewData()
void setViewData( [in] com::sun::star::container::XIndexAccess aData)

To use ViewData properties, call getViewData() and receive a com.sun.star.container.XIndexContainer:

Methods of XIndexContainer:

type getElementType()
boolean hasElements()
long getCount()
any getByIndex( [in] long Index)
void replaceByIndex( [in] long Index, any Element)
void insertByIndex( [in] long Index, any Element)
void removeByIndex( [in] long Index)

Use getByIndex() to iterate over the view data properties, find the required <idl>com.sun.star.beans.PropertyValue</idl> by checking the property names. If found, set the Value Member of the property value and put it back into the container using replaceByIndex(). Finally, apply the whole ViewData container to the document using setViewData().

The method setViewData() is currently not working. It can only be used with loadComponentFromURL().

Heckert GNU white.svg

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