1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
19 #ifndef _VCL_PDFWRITER_HXX
20 #define _VCL_PDFWRITER_HXX
22 #include <sal/types.h>
24 #include <tools/gen.hxx>
25 #include <tools/string.hxx>
26 #include <tools/color.hxx>
28 #include <vcl/dllapi.h>
29 #include <vcl/vclenum.hxx>
30 #include <vcl/font.hxx>
31 #include <vcl/graphictools.hxx>
33 #include "com/sun/star/io/XOutputStream.hpp"
34 #include "com/sun/star/beans/XMaterialHolder.hpp"
35 #include "com/sun/star/security/XCertificate.hpp"
36 #include "com/sun/star/lang/Locale.hpp"
38 #include <boost/scoped_ptr.hpp>
62 class PDFExtOutDevData
;
67 String Title
; // optional title for the popup containing the note
68 String Contents
; // contents of the note
71 class VCL_DLLPUBLIC PDFOutputStream
74 virtual ~PDFOutputStream();
75 virtual void write( const com::sun::star::uno::Reference
< com::sun::star::io::XOutputStream
>& xStream
) = 0;
78 class VCL_DLLPUBLIC PDFWriter
80 boost::scoped_ptr
<PDFWriterImpl
> pImplementation
;
83 enum CapType
{ capButt
, capRound
, capSquare
};
84 enum JoinType
{ joinMiter
, joinRound
, joinBevel
};
88 double m_fTransparency
;
92 std::vector
< double > m_aDashArray
;
94 ExtLineInfo() : m_fLineWidth( 0.0 ),
95 m_fTransparency( 0.0 ),
102 enum Orientation
{ Portrait
, Landscape
, Seascape
, Inherit
};
104 // in case the below enum is added PDF_1_6 PDF_1_7, please add them just after PDF_1_5
105 enum PDFVersion
{ PDF_1_2
, PDF_1_3
, PDF_1_4
, PDF_1_5
, PDF_A_1
};//i59651, PDF/A-1b & -1a, only -1b implemented for now
106 // for the meaning of DestAreaType please look at PDF Reference Manual
107 // version 1.4 section 8.2.1, page 475
108 enum DestAreaType
{ XYZ
, Fit
, FitHorizontal
, FitVertical
,
109 FitRectangle
, FitPageBoundingBox
, FitPageBoundingBoxHorizontal
,
110 FitPageBoundingBoxVertical
113 // for a definition of structural element types please refer to
114 // PDF Reference, 3rd ed. section 9.7.4
117 // special element to place outside the structure hierarchy
120 Document
, Part
, Article
, Section
, Division
, BlockQuote
,
121 Caption
, TOC
, TOCI
, Index
,
123 // block level elements
124 Paragraph
, Heading
, H1
, H2
, H3
, H4
, H5
, H6
,
125 List
, ListItem
, LILabel
, LIBody
,
126 Table
, TableRow
, TableHeader
, TableData
,
128 // inline level elements
129 Span
, Quote
, Note
, Reference
, BibEntry
, Code
, Link
,
131 // illustration elements
132 Figure
, Formula
, Form
137 Placement
, WritingMode
, SpaceBefore
, SpaceAfter
, StartIndent
, EndIndent
,
138 TextIndent
, TextAlign
, Width
, Height
, BlockAlign
, InlineAlign
,
139 LineHeight
, BaselineShift
, TextDecorationType
, ListNumbering
,
142 // link destination is an artificial attribute that sets
143 // the link annotation ID of a Link element
144 // further note: since structure attributes can only be
145 // set during content creation, but links can be
146 // created after the fact, it is possible to set
147 // an arbitrary id as structure attribute here. In this
148 // case the arbitrary id has to be passed again when the
149 // actual link annotation is created via SetLinkPropertyID
151 // Language currently sets a LanguageType (see i18nlangtag/lang.h)
152 // which will be internally changed to a corresponding locale
156 enum StructAttributeValue
161 Block
, Inline
, Before
, After
, Start
, End
,
172 // TextDecorationType
173 Underline
, Overline
, LineThrough
,
175 Disc
, Circle
, Square
, Decimal
, UpperRoman
, LowerRoman
, UpperAlpha
, LowerAlpha
181 SplitHorizontalInward
, SplitHorizontalOutward
,
182 SplitVerticalInward
, SplitVerticalOutward
,
183 BlindsHorizontal
, BlindsVertical
,
184 BoxInward
, BoxOutward
,
185 WipeLeftToRight
, WipeBottomToTop
, WipeRightToLeft
, WipeTopToBottom
,
187 GlitterLeftToRight
, GlitterTopToBottom
, GlitterTopLeftToBottomRight
192 PushButton
, RadioButton
, CheckBox
, Edit
, ListBox
, ComboBox
, Hierarchy
,
198 // PushButton, RadioButton, CheckBox; Down means selected for
199 // RadioButton and CheckBox
205 // transparent object occurred and was draw opaque because
206 // PDF/A does not allow transparency
207 Warning_Transparency_Omitted_PDFA
,
209 // transparent object occurred but is only supported since
211 Warning_Transparency_Omitted_PDF13
,
213 // a form action was exported that is not suitable for PDF/A
214 // the action was skipped
215 Warning_FormAction_Omitted_PDFA
,
217 // transparent objects were converted to a bitmap in order
218 // to removetransparencies from the output
219 Warning_Transparency_Converted
222 struct VCL_DLLPUBLIC AnyWidget
225 WidgetType Type
; // primitive RTTI
227 OUString Name
; // a distinct name to identify the control
228 OUString Description
;// descriptive text for the contro (e.g. for tool tip)
229 OUString Text
; // user text to appear on the control
230 sal_uInt16 TextStyle
; // style flags
232 Rectangle Location
; // describes the area filled by the control
233 bool Border
; // true: widget should have a border, false: no border
234 Color BorderColor
;// COL_TRANSPARENT and Border=true means get color from application settings
235 bool Background
; // true: widget shall draw its background, false: no background
236 Color BackgroundColor
; // COL_TRANSPARENT and Background=true means get color from application settings
237 Font TextFont
; // an empty font will be replaced by the
238 // appropriate font from the user settings
239 Color TextColor
; // COL_TRANSPARENT will be replaced by the appropriate color from application settings
240 sal_Int32 TabOrder
; // lowest number is first in tab order
242 /* style flags for text are those for OutputDevice::DrawText
244 TEXT_DRAW_LEFT, TEXT_DRAW_CENTER, TEXT_DRAW_RIGHT, TEXT_DRAW_TOP,
245 TEXT_DRAW_VCENTER, TEXT_DRAW_BOTTOM,
246 TEXT_DRAW_MULTILINE, TEXT_DRAW_WORDBREAK
248 if TextStyle is 0, then each control will fill in default values
251 // note: the Name member comprises the field name of the resulting
252 // PDF field names need to be globally unique. Therefore if any
253 // Widget with an already used name is created, the name will be
254 // made unique by adding an underscore ('_') and an ascending number
257 AnyWidget( WidgetType eType
) :
262 BorderColor( COL_TRANSPARENT
),
264 BackgroundColor( COL_TRANSPARENT
),
265 TextColor( COL_TRANSPARENT
),
268 virtual ~AnyWidget();
270 WidgetType
getType() const { return Type
; }
272 virtual AnyWidget
* Clone() const = 0;
275 // note that this equals the default compiler-generated copy-ctor, but we want to have it
276 // protected, to only allow sub classes to access it
277 AnyWidget( const AnyWidget
& rSource
)
278 :Type( rSource
.Type
)
279 ,Name( rSource
.Name
)
280 ,Description( rSource
.Description
)
281 ,Text( rSource
.Text
)
282 ,TextStyle( rSource
.TextStyle
)
283 ,ReadOnly( rSource
.ReadOnly
)
284 ,Location( rSource
.Location
)
285 ,Border( rSource
.Border
)
286 ,BorderColor( rSource
.BorderColor
)
287 ,Background( rSource
.Background
)
288 ,BackgroundColor( rSource
.BackgroundColor
)
289 ,TextFont( rSource
.TextFont
)
290 ,TextColor( rSource
.TextColor
)
291 ,TabOrder( rSource
.TabOrder
)
294 AnyWidget
& operator=( const AnyWidget
& ); // never implemented
297 struct PushButtonWidget
: public AnyWidget
299 /* If Dest is set to a valid link destination,
300 Then pressing the button will act as a goto
301 action within the document.
304 An empty URL means this button will reset the form.
306 If URL is not empty and Submit is set, then the URL
307 contained will be set as the URL to submit the
308 form to. In this case the submit method will be
309 either GET if SubmitGet is true or POST if
312 If URL is not empty and Submit is clear, then
313 the URL contained will be interpreted as a
314 hyperlink to be executed on pushing the button.
316 There will be no error checking or any kind of
317 conversion done to the URL parameter execept this:
318 it will be output as 7bit Ascii. The URL
319 will appear literally in the PDF file produced
327 : AnyWidget( vcl::PDFWriter::PushButton
),
328 Dest( -1 ), Submit( false ), SubmitGet( false )
331 virtual AnyWidget
* Clone() const
333 return new PushButtonWidget( *this );
337 struct CheckBoxWidget
: public AnyWidget
343 : AnyWidget( vcl::PDFWriter::CheckBox
),
348 virtual AnyWidget
* Clone() const
350 return new CheckBoxWidget( *this );
354 struct RadioButtonWidget
: public AnyWidget
357 sal_Int32 RadioGroup
;
359 OUString OnValue
; // the value of the radio button if it is selected
362 : AnyWidget( vcl::PDFWriter::RadioButton
),
368 virtual AnyWidget
* Clone() const
370 return new RadioButtonWidget( *this );
372 // radio buttons having the same RadioGroup id comprise one
373 // logical radio button group, that is at most one of the RadioButtons
374 // in a group can be checked at any time
376 // note: a PDF radio button field consists of a named field
377 // containing unnamed checkbox child fields. The name of the
378 // radio button field is taken from the first RadioButtonWidget created
382 struct EditWidget
: public AnyWidget
384 bool MultiLine
; // whether multiple lines are allowed
385 bool Password
; // visible echo off
386 bool FileSelect
; // field is a file selector
387 sal_Int32 MaxLen
; // maximum field length in characters, 0 means unlimited
390 : AnyWidget( vcl::PDFWriter::Edit
),
397 virtual AnyWidget
* Clone() const
399 return new EditWidget( *this );
403 struct ListBoxWidget
: public AnyWidget
408 std::vector
<OUString
> Entries
;
409 std::vector
<sal_Int32
> SelectedEntries
;
410 // if MultiSelect is false only the first entry of SelectedEntries
411 // will be taken into account. the same is implicit for PDF < 1.4
412 // since multiselect is a 1.4+ feature
415 : AnyWidget( vcl::PDFWriter::ListBox
),
421 virtual AnyWidget
* Clone() const
423 return new ListBoxWidget( *this );
427 // note: PDF only supports dropdown comboboxes
428 struct ComboBoxWidget
: public AnyWidget
431 std::vector
<OUString
> Entries
;
432 // set the current value in AnyWidget::Text
435 : AnyWidget( vcl::PDFWriter::ComboBox
),
439 virtual AnyWidget
* Clone() const
441 return new ComboBoxWidget( *this );
445 struct SignatureWidget
: public AnyWidget
447 // Use Sig prefix for members to avoid conflict with
448 // the Location member of the AnyWidget which spcifies the coordinates
451 OUString SigLocation
;
453 OUString SigContactInfo
;
457 : AnyWidget( vcl::PDFWriter::Signature
),
461 virtual AnyWidget
* Clone() const
463 return new SignatureWidget( *this );
467 enum ExportDataFormat
{ HTML
, XML
, FDF
, PDF
};
468 // see 3.6.1 of PDF 1.4 ref for details, used for 8.1 PDF v 1.4 ref also
469 // These emuns are treated as integer while reading/writing to configuration
470 enum PDFViewerPageMode
476 // These emuns are treated as integer while reading/writing to configuration
485 // These enums are treated as integer while reading/writing to configuration
494 // These emuns are treated as integer while reading/writing to configuration
495 //what default action to generate in a PDF hyperlink to external document/site
496 enum PDFLinkDefaultAction
499 URIActionDestination
,
504 The following structure describes the permissions used in PDF security
506 struct PDFEncryptionProperties
509 bool Security128bit
; // true to select 128 bit encryption, false for 40 bit
510 //for both 40 and 128 bit security, see 3.5.2 PDF v 1.4 table 3.15, v 1.5 and v 1.6 table 3.20.
511 bool CanPrintTheDocument
;
512 bool CanModifyTheContent
;
513 bool CanCopyOrExtract
;
515 //for revision 3 (bit 128 security) only
516 bool CanFillInteractive
;
517 bool CanExtractForAccessibility
;
521 // encryption will only happen if EncryptionKey is not empty
522 // EncryptionKey is actually a construct out of OValue, UValue and DocumentIdentifier
523 // if these do not match, behavior is undefined, most likely an invalid PDF will be produced
524 // OValue, UValue, EncryptionKey and DocumentIdentifier can be computed from
525 // PDFDocInfo, Owner password and User password used the InitEncryption method which
526 // implements the algorithms described in the PDF reference chapter 3.5: Encryption
527 std::vector
<sal_uInt8
> OValue
;
528 std::vector
<sal_uInt8
> UValue
;
529 std::vector
<sal_uInt8
> EncryptionKey
;
530 std::vector
<sal_uInt8
> DocumentIdentifier
;
532 //permission default set for 128 bit, accessibility only
533 PDFEncryptionProperties() :
534 Security128bit ( true ),
535 CanPrintTheDocument ( false ),
536 CanModifyTheContent ( false ),
537 CanCopyOrExtract ( false ),
538 CanAddOrModify ( false ),
539 CanFillInteractive ( false ),
540 CanExtractForAccessibility ( true ),
541 CanAssemble ( false ),
542 CanPrintFull ( false )
547 { return ! OValue
.empty() && ! UValue
.empty() && ! DocumentIdentifier
.empty(); }
552 String Title
; // document title
553 String Author
; // document author
554 String Subject
; // subject
555 String Keywords
; // keywords
556 String Creator
; // application that created the original document
557 String Producer
; // OpenOffice
562 DrawColor
, DrawGreyscale
565 struct PDFWriterContext
567 /* must be a valid file: URL usable by osl */
569 /* the URL of the document being exported, used for relative links*/
571 /*if relative to file system should be formed*/
572 bool RelFsys
;//i56629, i49415?, i64585?
573 /*the action to set the PDF hyperlink to*/
574 PDFWriter::PDFLinkDefaultAction DefaultLinkAction
;
575 //convert the .od? target file type in a link to a .pdf type
576 //this is examined before doing anything else
577 bool ConvertOOoTargetToPDFTarget
;
578 //when the file type is .pdf, force the GoToR action
581 /* decides the PDF language level to be produced */
583 /* valid for PDF >= 1.4
584 causes the MarkInfo entry in the document catalog to be set
587 /* forces the embedding of PDF standard fonts */
588 bool EmbedStandardFonts
;
589 /* determines in which format a form
592 PDFWriter::ExportDataFormat SubmitFormat
;
593 bool AllowDuplicateFieldNames
;
594 bool FieldsUseSystemFonts
;
595 /* the following data members are used to customize the PDF viewer
598 /* see 3.6.1 PDF v 1.4 ref*/
599 PDFWriter::PDFViewerPageMode PDFDocumentMode
;
600 PDFWriter::PDFViewerAction PDFDocumentAction
;
601 // in percent, valid only if PDFDocumentAction == ActionZoom
604 /* see 8.6 PDF v 1.4 ref
605 specifies whether to hide the viewer tool
606 bars when the document is active.
608 bool HideViewerToolbar
;
609 bool HideViewerMenubar
;
610 bool HideViewerWindowControls
;
612 bool OpenInFullScreenMode
;
614 bool DisplayPDFDocumentTitle
;
615 PDFPageLayout PageLayout
;
617 // intially visible page in viewer (starting with 0 for first page)
618 sal_Int32 InitialPage
;
619 sal_Int32 OpenBookmarkLevels
; // -1 means all levels
621 PDFWriter::PDFEncryptionProperties Encryption
;
622 PDFWriter::PDFDocInfo DocumentInfo
;
625 OUString SignLocation
;
626 OUString SignPassword
;
628 OUString SignContact
;
629 com::sun::star::lang::Locale DocumentLocale
; // defines the document default language
630 sal_uInt32 DPIx
, DPIy
; // how to handle MapMode( MAP_PIXEL )
631 // 0 here specifies a default handling
632 PDFWriter::ColorMode ColorMode
;
633 com::sun::star::uno::Reference
< com::sun::star::security::XCertificate
> SignCertificate
;
636 RelFsys( false ), //i56629, i49415?, i64585?
637 DefaultLinkAction( PDFWriter::URIAction
),
638 ConvertOOoTargetToPDFTarget( false ),
639 ForcePDFAction( false ),
640 Version( PDFWriter::PDF_1_4
),
642 EmbedStandardFonts( false ),
643 SubmitFormat( PDFWriter::FDF
),
644 AllowDuplicateFieldNames( false ),
645 FieldsUseSystemFonts( true ),
646 PDFDocumentMode( PDFWriter::ModeDefault
),
647 PDFDocumentAction( PDFWriter::ActionDefault
),
649 HideViewerToolbar( false ),
650 HideViewerMenubar( false ),
651 HideViewerWindowControls( false ),
653 OpenInFullScreenMode( false ),
654 CenterWindow( false ),
655 DisplayPDFDocumentTitle( true ),
656 PageLayout( PDFWriter::DefaultLayout
),
657 FirstPageLeft( false ),
659 OpenBookmarkLevels( -1 ),
664 ColorMode( PDFWriter::DrawColor
),
669 PDFWriter( const PDFWriterContext
& rContext
, const com::sun::star::uno::Reference
< com::sun::star::beans::XMaterialHolder
>& );
672 /** Returns an OutputDevice for formatting
673 <p>This Output device is guaranteed to use the same
674 font metrics as the resulting PDF file.</p>
677 the reference output device
679 OutputDevice
* GetReferenceDevice();
681 /** Creates a new page to fill
682 <p>If width and height are not set the page size
683 is inherited from the page tree</p>
685 resets the graphics state: MapMode, Font
686 Colors and other state information MUST
687 be set again or are undefined.
691 returns the page id of the new page
693 sal_Int32
NewPage( sal_Int32 nPageWidth
= 0, sal_Int32 nPageHeight
= 0, Orientation eOrientation
= Inherit
);
694 /** Play a metafile like an outputdevice would do
696 struct PlayMetafileContext
698 int m_nMaxImageResolution
;
699 bool m_bOnlyLosslessCompression
;
701 bool m_bTransparenciesWereRemoved
;
703 PlayMetafileContext()
704 : m_nMaxImageResolution( 0 )
705 , m_bOnlyLosslessCompression( false )
706 , m_nJPEGQuality( 90 )
707 , m_bTransparenciesWereRemoved( false )
711 void PlayMetafile( const GDIMetaFile
&, const PlayMetafileContext
&, vcl::PDFExtOutDevData
* pDevDat
= NULL
);
713 /* sets the document locale originally passed with the context to a new value
714 * only affects the output if used before calling <code>Emit/code>.
716 void SetDocumentLocale( const com::sun::star::lang::Locale
& rDocLocale
);
718 /* finishes the file */
722 * Get a list of errors that occurred during processing
723 * this should enable the producer to give feedback about
724 * any anomalies that might have occurred
726 std::set
< ErrorCode
> GetErrors();
728 static com::sun::star::uno::Reference
< com::sun::star::beans::XMaterialHolder
>
729 InitEncryption( const OUString
& i_rOwnerPassword
,
730 const OUString
& i_rUserPassword
,
734 /* functions for graphics state */
735 /* flag values: see vcl/outdev.hxx */
736 void Push( sal_uInt16 nFlags
= 0xffff );
739 void SetClipRegion();
740 void SetClipRegion( const basegfx::B2DPolyPolygon
& rRegion
);
741 void MoveClipRegion( long nHorzMove
, long nVertMove
);
742 void IntersectClipRegion( const Rectangle
& rRect
);
743 void IntersectClipRegion( const basegfx::B2DPolyPolygon
& rRegion
);
745 void SetLayoutMode( sal_uLong nMode
);
746 void SetDigitLanguage( LanguageType eLang
);
748 void SetLineColor( const Color
& rColor
);
749 void SetLineColor() { SetLineColor( Color( COL_TRANSPARENT
) ); }
751 void SetFillColor( const Color
& rColor
);
752 void SetFillColor() { SetFillColor( Color( COL_TRANSPARENT
) ); }
754 void SetFont( const Font
& rNewFont
);
755 void SetTextColor( const Color
& rColor
);
756 void SetTextFillColor();
757 void SetTextFillColor( const Color
& rColor
);
759 void SetTextLineColor();
760 void SetTextLineColor( const Color
& rColor
);
761 void SetOverlineColor();
762 void SetOverlineColor( const Color
& rColor
);
763 void SetTextAlign( ::TextAlign eAlign
);
765 void SetMapMode( const MapMode
& rNewMapMode
);
768 /* actual drawing functions */
769 void DrawText( const Point
& rPos
, const String
& rText
);
771 void DrawTextLine( const Point
& rPos
, long nWidth
,
772 FontStrikeout eStrikeout
,
773 FontUnderline eUnderline
,
774 FontUnderline eOverline
,
775 sal_Bool bUnderlineAbove
= sal_False
);
776 void DrawTextArray( const Point
& rStartPt
, const XubString
& rStr
,
777 const sal_Int32
* pDXAry
= NULL
,
778 xub_StrLen nIndex
= 0,
779 xub_StrLen nLen
= STRING_LEN
);
780 void DrawStretchText( const Point
& rStartPt
, sal_uLong nWidth
,
781 const XubString
& rStr
,
782 xub_StrLen nIndex
= 0, xub_StrLen nLen
= STRING_LEN
);
783 void DrawText( const Rectangle
& rRect
,
784 const XubString
& rStr
, sal_uInt16 nStyle
= 0 );
786 void DrawPixel( const Point
& rPt
, const Color
& rColor
);
787 void DrawPixel( const Point
& rPt
)
788 { DrawPixel( rPt
, Color( COL_TRANSPARENT
) ); }
790 void DrawLine( const Point
& rStartPt
, const Point
& rEndPt
);
791 void DrawLine( const Point
& rStartPt
, const Point
& rEndPt
,
792 const LineInfo
& rLineInfo
);
793 void DrawPolyLine( const Polygon
& rPoly
);
794 void DrawPolyLine( const Polygon
& rPoly
,
795 const LineInfo
& rLineInfo
);
796 void DrawPolyLine( const Polygon
& rPoly
, const ExtLineInfo
& rInfo
);
797 void DrawPolygon( const Polygon
& rPoly
);
798 void DrawPolyPolygon( const PolyPolygon
& rPolyPoly
);
799 void DrawRect( const Rectangle
& rRect
);
800 void DrawRect( const Rectangle
& rRect
,
801 sal_uLong nHorzRount
, sal_uLong nVertRound
);
802 void DrawEllipse( const Rectangle
& rRect
);
803 void DrawArc( const Rectangle
& rRect
,
804 const Point
& rStartPt
, const Point
& rEndPt
);
805 void DrawPie( const Rectangle
& rRect
,
806 const Point
& rStartPt
, const Point
& rEndPt
);
807 void DrawChord( const Rectangle
& rRect
,
808 const Point
& rStartPt
, const Point
& rEndPt
);
810 void DrawBitmap( const Point
& rDestPt
, const Size
& rDestSize
,
811 const Bitmap
& rBitmap
);
813 void DrawBitmapEx( const Point
& rDestPt
, const Size
& rDestSize
,
814 const BitmapEx
& rBitmapEx
);
816 void DrawGradient( const Rectangle
& rRect
, const Gradient
& rGradient
);
817 void DrawGradient( const PolyPolygon
& rPolyPoly
, const Gradient
& rGradient
);
819 void DrawHatch( const PolyPolygon
& rPolyPoly
, const Hatch
& rHatch
);
821 void DrawWallpaper( const Rectangle
& rRect
, const Wallpaper
& rWallpaper
);
822 void DrawTransparent( const PolyPolygon
& rPolyPoly
,
823 sal_uInt16 nTransparencePercent
);
825 /** Start a transparency group
827 Drawing operations can be grouped together to acquire a common transparency
828 behaviour; after calling <code>BeginTransparencyGroup</code> all drawing
829 operations will be grouped together into a transparent object.
831 The transparency behaviour is set with ond of the <code>EndTransparencyGroup</code>
832 calls and can be either a constant transparency factor or a transparent
833 soft mask in form of an 8 bit gray scale bitmap.
835 It is permissible to nest transparency group.
837 Transparency groups MUST NOT span multiple pages
839 Transparency is a feature introduced in PDF1.4, so transparency group
840 will be ignored if the produced PDF has a lower version. The drawing
841 operations will be emitted normally.
843 void BeginTransparencyGroup();
845 /** End a transparency group with constant transparency factor
847 This ends a transparency group and inserts it on the current page. The
848 coordinates of the group result out of the grouped drawing operations.
851 The bounding rectangle of the group
853 @param nTransparencePercent
854 The transparency factor
856 void EndTransparencyGroup( const Rectangle
& rBoundRect
, sal_uInt16 nTransparencePercent
);
858 /** Insert a JPG encoded image (optionally with mask)
861 a Stream containing the encoded image
864 true: jpeg is 24 bit true color, false: jpeg is 8 bit greyscale
867 size in pixel of the image
870 where to put the image
873 optional mask; if not empty it must have
874 the same pixel size as the image and
875 be either 1 bit black&white or 8 bit grey
877 void DrawJPGBitmap( SvStream
& rJPGData
, bool bIsTrueColor
, const Size
& rSrcSizePixel
, const Rectangle
& rTargetArea
, const Bitmap
& rMask
);
879 /** Create a new named destination to be used in a link from another PDF document
882 the name (label) of the bookmark, to be used to jump to
885 target rectangle on page to be displayed if dest is jumped to
888 number of page the dest is on (as returned by NewPage)
889 or -1 in which case the current page is used
892 what dest type to use
895 the destination id (to be used in SetLinkDest) or
896 -1 if page id does not exist
898 sal_Int32
CreateNamedDest( const OUString
& sDestName
, const Rectangle
& rRect
, sal_Int32 nPageNr
= -1, DestAreaType eType
= XYZ
);
899 /** Create a new destination to be used in a link
902 target rectangle on page to be displayed if dest is jumped to
905 number of page the dest is on (as returned by NewPage)
906 or -1 in which case the current page is used
909 what dest type to use
912 the destination id (to be used in SetLinkDest) or
913 -1 if page id does not exist
915 sal_Int32
CreateDest( const Rectangle
& rRect
, sal_Int32 nPageNr
= -1, DestAreaType eType
= XYZ
);
916 /** Create a new link on a page
919 active rectangle of the link (that is the area that has to be
920 hit to activate the link)
923 number of page the link is on (as returned by NewPage)
924 or -1 in which case the current page is used
927 the link id (to be used in SetLinkDest, SetLinkURL) or
928 -1 if page id does not exist
930 sal_Int32
CreateLink( const Rectangle
& rRect
, sal_Int32 nPageNr
= -1 );
932 /** creates a destination which is not intended to be referred to by a link, but by a public destination Id.
934 Form widgets, for instance, might refer to a destination, without ever actually creating a source link to
935 point to this destination. In such cases, a public destination Id will be assigned to the form widget,
936 and later on, the concrete destination data for this public Id will be registered using RegisterDestReference.
939 target rectangle on page to be displayed if dest is jumped to
942 number of page the dest is on (as returned by NewPage)
943 or -1 in which case the current page is used
946 what dest type to use
949 the internal destination Id.
951 sal_Int32
RegisterDestReference( sal_Int32 nDestId
, const Rectangle
& rRect
, sal_Int32 nPageNr
= -1, DestAreaType eType
= XYZ
);
954 /** Set the destination for a link
955 <p>will change a URL type link to a dest link if necessary</p>
958 the link to be changed
961 the dest the link shall point to
964 -1 in case the link id does not exist
965 -2 in case the dest id does not exist
967 sal_Int32
SetLinkDest( sal_Int32 nLinkId
, sal_Int32 nDestId
);
968 /** Set the URL for a link
969 <p>will change a dest type link to an URL type link if necessary</p>
971 the link to be changed
974 the URL the link shall point to.
975 The URL will be parsed (and corrected) by the <code>com.sun.star.util.URLTransformer</code>
976 service; the result will then appear literally in the PDF file produced
980 -1 in case the link id does not exist
982 sal_Int32
SetLinkURL( sal_Int32 nLinkId
, const OUString
& rURL
);
983 /** Resolve link in logical structure
985 If a link is created after the corresponding visual appearance was drawn
986 it is not possible to set the link id as a property attribute to the
987 link structure item that should be created in tagged PDF around the
988 visual appearance of a link.
991 For this reason an arbitrary id can be given to
992 <code>SetStructureAttributeNumerical</code> at the time the text for
993 the link is drawn. To resolve this arbitrary id again when the actual
994 link annotation is created use SetLinkPropertyID. When <code>Emit</code>
995 finally gets called all <code>LinkAnnotation</code> type structure attributes
996 will be replaced with the correct link id.
999 CAUTION: this technique must be used either for all or none of the links
1000 in a document since the link id space and arbitrary property id space
1001 could overlap and it would be impossible to resolve whether a <code>Link</code>
1002 structure attribute value was arbitrary or already a real id.
1006 the link to be mapped
1009 the arbitrary id set in a <code>Link</code> structure element to address
1010 the link with real id <code>nLinkId</code>
1012 void SetLinkPropertyID( sal_Int32 nLinkId
, sal_Int32 nPropertyID
);
1013 /** Create a new outline item
1016 declares the parent of the new item in the outline hierarchy.
1017 An invalid value will result in a new toplevel item.
1020 sets the title text of the item
1023 declares which Dest (created with CreateDest) the outline item
1027 the outline item id of the new item
1029 sal_Int32
CreateOutlineItem( sal_Int32 nParent
= 0, const OUString
& rText
= OUString(), sal_Int32 nDestID
= -1 );
1031 /** Set an outline item's parent
1034 specififies which item should be reparented.
1037 specifies which outline item will be the item's new parent.
1038 Use 0 for reparenting to top level.
1041 -1 if the item does not exist
1042 -2 if the new parent does not exist, item will be reparented to top level.
1044 sal_Int32
SetOutlineItemParent( sal_Int32 nItem
, sal_Int32 nNewParent
);
1046 /** Set an outline item's title text
1049 specififies which item should get a new text
1052 sets the title text of the item
1055 0 if the item exists and the text was changed
1056 -1 if the item does not exist
1058 sal_Int32
SetOutlineItemText( sal_Int32 nItem
, const OUString
& rText
);
1060 /** Set an outline item's destination
1063 specififies which item should get a new dest
1066 specifies the item's new destination
1069 -1 if the item does not exist
1070 -2 if the new dest does not exist, dest will remain unchanged
1072 sal_Int32
SetOutlineItemDest( sal_Int32 nItem
, sal_Int32 nDestID
);
1074 /** Create a new note on a page
1077 active rectangle of the note (that is the area that has to be
1078 hit to popup the annotation)
1081 specifies the contents of the note
1084 number of page the note is on (as returned by NewPage)
1085 or -1 in which case the current page is used
1087 void CreateNote( const Rectangle
& rRect
, const PDFNote
& rNote
, sal_Int32 nPageNr
= -1 );
1089 /** begin a new logical structure element
1092 BeginStructureElement/EndStructureElement calls build the logical structure
1093 of the PDF - the basis for tagged PDF. Structural elements are implemented
1094 using marked content tags. Each structural element can contain sub elements
1095 (e.g. a section can contain a heading and a paragraph). The structure hierarchy
1096 is build automatically from the Begin/EndStructureElement calls.
1098 A structural element need not be contained on one page; e.g. paragraphs often
1099 run from one page to the next. In this case the corresponding EndStructureElement
1100 must be called while drawing the next page.
1104 BeginStructureElement and EndStructureElement must be called only after
1105 <member scope="vcl">PDFWriter::NewPage</member> has been called and before
1106 <member scope="vcl">PDFWriter::Emit</member>gets called. The current page
1107 number is an implicit context parameter for Begin/EndStructureElement.
1111 For pagination artifacts that are not part of the logical structure
1112 of the document (like header, footer or page number) the special
1113 StructElement <code>NonStructElement</code> exists. To place content
1114 outside of the struture tree simply call
1115 <code>BeginStructureElement( NonStructElement )</code> then draw your
1116 content and then call <code>EndStructureElement()</code>. All children
1117 of a <code>NonStructElement</code> will not be part of the structure.
1118 Nonetheless if you add a child structural element to a
1119 <code>NonStructElement</code> you will still have to call
1120 <code>EndStructureElement</code> for it. Best think of the structure
1125 Note: there is always one structural element in existance without having
1126 called <code>BeginStructureElement</code>; this is the root of the structure
1127 tree (called StructTreeRoot). The StructTreeRoot has always the id 0.
1131 denotes what kind of element to begin (e.g. a heading or paragraph)
1134 the specified alias will be used as structure tag. Also an entry in the PDF's
1135 role map will be created mapping alias to regular structure type.
1138 the new structure element's id for use in <code>SetCurrentStructureElement</code>
1140 sal_Int32
BeginStructureElement( enum StructElement eType
, const OUString
& rAlias
= OUString() );
1141 /** end the current logical structure element
1144 Close the current structure element. The current element's
1145 parent becomes the current structure element again.
1148 @see BeginStructureElement
1150 void EndStructureElement();
1151 /** set the current structure element
1154 For different purposes it may be useful to paint a structure element's
1155 content discontinously. In that case an already existing structure element
1156 can be appended to by using <code>SetCurrentStructureElement</code>. The
1157 refenrenced structure element becomes the current structure element with
1158 all consequences: all following structure elements are appended as children
1159 of the current element.
1163 the id of the new current structure element
1166 <true/> if the current structure element could be set successfully
1167 <false/> if the current structure element could not be changed
1168 (e.g. if the passed element id is invalid)
1170 bool SetCurrentStructureElement( sal_Int32 nElement
);
1172 /** set a structure attribute on the current structural element
1174 SetStructureAttribute sets an attribute of the current structural element to a
1175 new value. A consistency check is performed before actually setting the value;
1176 if the check fails, the function returns <FALSE/> and the attribute remains
1180 denotes what attribute to change
1183 the value to set the attribute to
1186 <TRUE/> if the value was valid and the change has been performed,
1187 <FALSE/> if the attribute or value was invalid; attribute remains unchanged
1189 bool SetStructureAttribute( enum StructAttribute eAttr
, enum StructAttributeValue eVal
);
1190 /** set a structure attribute on the current structural element
1192 SetStructureAttributeNumerical sets an attribute of the current structural element
1193 to a new numerical value. A consistency check is performed before actually setting
1194 the value; if the check fails, the function returns <FALSE/> and the attribute
1198 denotes what attribute to change
1201 the value to set the attribute to
1204 <TRUE/> if the value was valid and the change has been performed,
1205 <FALSE/> if the attribute or value was invalid; attribute remains unchanged
1207 bool SetStructureAttributeNumerical( enum StructAttribute eAttr
, sal_Int32 nValue
);
1208 /** set the bounding box of a structural element
1210 SetStructureBoundingBox sets the BBox attribute to a new value. Since the BBox
1211 attribute can only be applied to <code>Table</code>, <code>Figure</code>,
1212 <code>Form</code> and <code>Formula</code> elements, a call of this function
1213 for other element types will be ignored and the BBox attribute not be set.
1216 the new bounding box for the structural element
1218 void SetStructureBoundingBox( const Rectangle
& rRect
);
1220 /** set the ActualText attribute of a structural element
1222 ActualText contains the Unicode text without layout artifacts that is shown by
1223 a structural element. For example if a line is ended prematurely with a break in
1224 a word and continued on the next line (e.g. "happen-<newline>stance") the
1225 corresponding ActualText would contain the unbroken line (e.g. "happenstance").
1228 contains the complete logical text the structural element displays.
1230 void SetActualText( const String
& rText
);
1232 /** set the Alt attribute of a strutural element
1234 Alt is s replacement text describing the contents of a structural element. This
1235 is mainly used by accessibility applications; e.g. a screen reader would read
1236 the Alt replacement text for an image to a visually impaired user.
1239 contains the replacement text for the structural element
1241 void SetAlternateText( const String
& rText
);
1243 /** Sets the time in seconds a page will appear before the next
1244 page is shown automatically
1247 time in seconds the current page will be shown; pass 0 for manual advancement
1250 the page number to apply the autoadvance time to; -1 denotes the current page
1252 void SetAutoAdvanceTime( sal_uInt32 nSeconds
, sal_Int32 nPageNr
= -1 );
1254 /** Sets the transitional effect to be applied when the current page gets shown.
1257 the kind of effect to be used; use Regular to disable transitional effects
1261 the duration of the transitional effect in milliseconds;
1262 set 0 to disable transitional effects
1265 the page number to apply the effect to; -1 denotes the current page
1267 void SetPageTransition( PageTransition eType
, sal_uInt32 nMilliSec
, sal_Int32 nPageNr
= -1 );
1269 /** create a new form control
1271 This function creates a new form control in the PDF and sets its various
1272 properties. Do not pass an actual AnyWidget as <code>rControlType</code>
1273 will be cast to the type described by the type member.
1276 a descendant of <code>AnyWidget</code> determing the control's properties
1279 the new control's id for reference purposes
1281 sal_Int32
CreateControl( const AnyWidget
& rControlType
, sal_Int32 nPageNr
= -1 );
1283 /** Inserts an additional stream to the PDF file
1285 This function adds an arbitrary stream to the produced PDF file. May be called
1286 any time before <code>Emit()</code>. The stream will be written during
1287 <code>Emit</code> by calling the <code>PDFOutputStream</code> Object's <code>write</code>
1288 method. After the call the <code>PDFOutputStream</code> will be deleted.
1290 All additional streams and their mimetypes will be entered into an array
1291 in the trailer dictionary.
1294 the mimetype of the stream
1297 the interface to the additional stream
1300 specifies whether the stream should be flate encoded by PDFWriter or not
1302 void AddStream( const String
& rMimeType
, PDFOutputStream
* pStream
, bool bCompress
);
1308 #endif // _VCL_PDFWRITER_HXX
1310 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */