Management Functions > VpeOpenDocFile

The same as VpeOpenDoc(), but instead of storing all document pages in memory, only the current page is held in memory. All other pages are swapped to a VPE document file. This implies minimum memory usage at very high performance and allows to create huge documents. VPE's file swapping is VERY fast.

Even for file-based documents you can add new pages to the end of a document at any point in time.

Editions below the Professional Edition: after a page has been swapped to file, you can not modify the page, i.e. add new objects to it.

The Professional Edition and higher allow to add new objects to pages which have already been written to file and to clear, insert and delete pages at any position in a document file.

A page is swapped to file after:

•Adding a new blank page by calling VpePageBreak()

•Moving to a different page by calling VpeGotoPage()

For details about creating and using VPE document files, please see the "Programmer's Manual", chapter "Programming Techniques", subchapter "VPE Document Files".

VpeHandle VpeOpenDocFile(

HWND hWndParent,

LPCSTR file_name,

LPCSTR title,

long flags

)

HWND hwndParent

a window of your calling application that will be the parent window of the VPE Preview Window. VPE exchanges messages with it. If the Preview is embedded, this will also be the host window of the Preview.

This parameter may be NULL, for example to use VPE in windowless applications like server processes or batch jobs. In this case you can install a message callback function, in order to receive events generated by VPE. For details, see VpeSetMsgCallback().

For non-Windows platforms this parameter must be NULL.

LPCSTR file_name

name of file to open or create

it is very important that all VPE document files have the suffix ".vpe". Always use this suffix, because "VPE View" (the document browser, see "VPE View" in the Programmer's Manual) is associated with this suffix.

LPCSTR title

title of the Preview Window

long flags

controls the style of the Preview and the behavior of VPE (see VpeOpenDoc())

Returns:

The handle (=identifier) to the virtual document. This handle has to be provided to all other VPE calls. In case of an error, NULL (0) is returned.

On 32-bit platforms the handle is a 32-bit integer, on 64-bit platforms it is a 64-bit integer.

You can check for error conditions - for example, if there is not enough free space left on disk for the SwapFile - by testing the property VpeGetLastError() after calling VpeOpenDocFile() and each time after calling VpePageBreak().

Remarks:

When you create a new document with this function, compression is always activated.

Example:

VpeHandle hDoc;

long count;

hDoc = VpeOpenDocFile(hwndParent, "c:\docs\report1.vpe", "Example", 0);

if (hDoc == NULL)

return; // error

count = VpeGetPageCount(hDoc);

VpePageBreak(hDoc);

VpePrint(hDoc, 1, 1, "Added a new page.");

VpePreviewDoc(hDoc, NULL, VPE_SHOW_NORMAL);

If the VPE document file "c:\docs\report1.vpe" is already existing, the file will be opened and the first page is read into memory. If the document file is not existing, VPE will create it with an initial blank page. The variable "count" is assigned the number of pages the document contains. VPE will add a new page at the end of the document and insert the text "Added a new page." there. Then the preview is shown.

The flag VPE_DOCFILE_READONLY:

If you use this flag, the Document file is opened with read-only permission. A VPE document file can not be created if this flag is specified. You can only use it to open an existing file for read-only purposes.

If a VPE document file is opened for read / write (the default), no other application can open this file - even if it tries to open the file with read-only permission. Multiple applications can open the file at the same time only, if all applications use ReadOnly = True.

Example:

VpeHandle hDoc;

long count;

hDoc = VpeOpenDocFile(hwndParent, "c:\docs\report1.vpe", "Example", VPE_DOCFILE_READONLY);

if (hDoc == NULL)

return; // error

count = VpeGetPageCount(hDoc);

VpeGotoVisualPage(hDoc, count);

VpePreviewDoc(hDoc, NULL, VPE_SHOW_NORMAL);

If the VPE document file "c:\docs\report1.vpe" is not existing, VpeOpenDocFile() will return NULL (= error). Otherwise the file will be opened in read-only mode and the first page is read into memory. The variable "count" is assigned the number of pages the document contains. The preview will show the last page contained in the document.

When calling VpeOpenDocFile(), the JobName is set automatically to the file name.