Programming Techniques > Dynamic Positioning

The page margins of VPE are virtual margins. That means, you can place text and other objects outside of them.

Nevertheless the margins play an important role for the behavior of some methods:

•The bottom margin tells VPE, where to start with the Automatic Text Break, which means that text exceeding the bottom margin is automatically skipped to the next page. You can change this by modifying the property AutoBreakMode (see “Automatic Text Break”).

•The top margin tells VPE, where to start with automatically broken text on successive pages.

•The right margin is important for text output, as explained in the previous chapter "Dynamic Text".

You set the margins for the current page by setting the properties nLeftMargin, nTopMargin, nRightMargin and nBottomMargin. But this only helps for the current page. A new page, generated either with a call to PageBreak(), or by an Automatic Text Break will use DEFAULT values.

Why? Well, perhaps you want on successive pages other margins, especially if an Automatic Text Break occurs. How else could you change the layout of successive automatically generated pages?

The method provided by VPE for setting the default margins, which are used for newly generated pages is:

SetDefOutRect(LeftMargin, TopMargin, RightMargin, BottomMargin)

Keep in mind that there is a difference between the properties for the margins, which are only valid for the current page you're working on, and the default-margins for newly generated pages.

By default, VPE defines the margins and default margins 2cm from the paper edges. The right and bottom paper edge is defined by the property 'PageFormat', which may be 'DIN_A4', 'US_Letter', etc. or 'User_Defined'. In the latter case the page dimensions are specified individually through the properties 'PageWidth' and 'PageHeight'.

The page dimensions can be set for each page individually.

You can access (read / write) the margins with the properties nLeftMargin, nTopMargin, nRightMargin and nBottomMargin (DLL: use the methods VpeGet() and VpeSet() with the flags VLEFTMARGIN, VTOPMARGIN, VRIGHTMARGIN, VBOTTOMMARGIN).

So they can work as placeholders for you, holding the definitions of the current page / document.

Example:

Write(1, 15, nRightMargin, VFREE, "long text.....")

In the above example, the “long text” will extend to the right margin of the current page.

If you need to change the margins later during the development process, and your calls to VPE are considering them like in the example above, you will have no problems with the new layout.

As you can place text and other objects outside of the margins, the rectangle defined by the margins is also called "Output Rectangle". There are two related methods to define the margins - or output rectangle - at once: SetOutRect() and SetDefOutRect().

Calling SetOutRect() sets all four margin coordinates at once. Both, the nMargin properties and this method modify the margins on the current page you are working on.

In contrast, the DefOutRect defines the margins that will be used for a newly generated page. This is very helpful, if you want to place a text that is automatically broken to the next page with the auto break feature in a completely different rectangle.

Margins: Summary

VPE knows an output rectangle on each page. This can be compared to the printable area or page-margins.

The output-rectangle is only for your own orientation purposes when positioning objects. In addition text output functions use the output-rectangle to consider the maximum right border. You're still able to place objects outside the output-rectangle.

•The output rectangle can be defined and retrieved.

•Each page in a document can have its individual output rectangle.

•You can define a default output rectangle, which will be used for newly generated pages.

•The values for margins are specified in coordinates relative to the top / left paper border, e.g. if the right margin shall be 2cm away from the right paper border, set it to ‘page_width - 2’. If you would set the right margin = 2, it would be 2cm away from the left border.

•After creating a Document with OpenDoc() the default-rectangle is set to:
left = 2, top = 2, right = page_width - 2, bottom = page_height - 2

•The properties to access the output rectangle are:
nLeftMargin, nTopMargin, nRightMargin and nBottomMargin
(DLL: VLEFTMARGIN, VRIGHTMARGIN, VTOPMARGIN, VBOTTOMMARGIN)

•The default output rectangle is set with:
SetDefOutRect(LeftMargin, TopMargin, RightMargin, BottomMargin)

•On an initial blank page, VLEFT is VLEFTMARGIN, VRIGHT is VRIGHTMARGIN, VTOP is VTOPMARGIN and VBOTTOM is VTOPMARGIN (!).

All explained V-Flags except VFREE can be used for ALL objects.

Examples:

DLL:

VpeSet(hDoc, VLEFTMARGIN, 3 );

Control:

<Object>.nLeftMargin = 3;

Sets the left margin of the output rectangle for the current page to 3 cm.

Write(nLeftMargin, nTopMargin, -5, VFREE, "Hello World!")

Inserts the text "Hello World!" at the top left corner of the margins.

Write(16, nTopMargin, nRightMargin, VFREE, "Hello world!")

Text is placed with the right border equal to the right page margin.

Line(VLEFTMARGIN, VTOPMARGIN, VRIGHTMARGIN, VBOTTOMMARGIN)

Draws a line from the upper left to the lower right corners of a page.

Write(VLEFTMARGIN, VTOPMARGIN, VRIGHTMARGIN, VFREE, "long text.....")

This inserts a text object at position (left margin, top margin) with a width up to the right margin. Its height (y2) is calculated and depends on the length of the text and the font size used.

Page Margins

Page Margins