<< Click to Display Table of Contents >> Navigation:  Management Functions > VpeOpenDoc

Creates a new document with one initial blank page.

VpeHandle VpeOpenDoc(

HWND hwndParent,

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 title

title of the Preview Window. The title is also used by VPE to compose the default JobName of the print job.

long flags

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

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.

Remarks:

You may create an unlimited number of pages per document and an unlimited number of documents simultaneously, but both is limited by available memory. How much memory is needed, depends on the number of objects you insert and what type of objects you insert. So we can't give clear guidelines about memory usage. In case of doubt, use a monitoring tool to view how much memory is needed for your specific kind of document(s). For example, one page in the "Speed + Tables" demo needs about 10 KB of memory. This is really low, but 100 pages need about 1MB of memory.

If the memory usage is too high, we recommend to use File Swapping (see VpeOpenDocFile()).

A VPE document can exist without showing a preview. But if a preview is shown, the document is closed and removed from memory by default, when the preview is closed by the user or when the parent window is closed. If you call VpeEnableAutoDelete(hDoc, false), the document is not closed when the preview is closed.

On non-Windows platforms you must always call VpeCloseDoc() to remove a document from memory.

 

Windows platform: Embedding the preview into a host window

A preview window can be embedded into the window of the calling application. This means that VPE does not open its own window, but draws its preview into the caller's window. To do this, you just need to:

1.Use the flag VPE_EMBEDDED in  VpeOpenDoc()

2.In the window-procedure of your parent window (where the preview shall be embedded), give the following response to the WM_SIZE message:

MoveWindow(VpeGetWindowHandle(hDoc), 0, 0, LOWORD(lParam), HIWORD(lParam), TRUE)

this will size the VPE preview window accordingly with the parent window.

3.In the window-procedure of the parent window, respond to the WM_SETFOCUS message with:

SetFocus(VpeGetWindowHandle(hDoc))

this will route the keyboard and mouse-wheel messages to the VPE preview window.

 

Caution:

Using VPE from interpreters can cause some trouble when stopping program execution without a prior call to VpeCloseDoc(). Some interpreters will not unload VPE, so the document stays open.  In this case the memory used by VPE isn't released to the system and in some cases GPF’s might occur.

 

Flags:

If you want to customize the preview or behavior of VPE you can specify one or more flags. VPE has been configured in a way that you can use 0 (zero) as flags-value for a default behavior.

 

The flag VPE_DOCFILE_READONLY: see VpeOpenDocFile()

 

The flag VPE_FIXED_MESSAGES: if you use VPE_FIXED_MESSAGES, VPE will directly send the VPE_xyz message constants to the window procedure of your parent window, instead of sending the globally registered messages. For a detailed discussion on how to handle messages see VpeMapMessage().

 

Example:

VpeHandle hDoc;

hDoc = VpeOpenDoc(hwndParent, "Report", VPE_NO_STATUSSEG + VPE_NO_RULERS);

if (hDoc == NULL)

 return; // error

VpePreviewDoc(hDoc, 0, VPE_SHOW_MAXIMIZED);

Creates a document where the preview will have the title "Report". In this example the preview will have no status segment and no rulers. Note that the preview is not automatically shown after calling VpeOpenDoc() - it just creates the document, which is then ready for inserting objects and adding pages. The preview is shown by calling VpePreviewDoc().

 

Community Edition:

For the Community Edition the GUI elements can not be changed, i.e. the preview has always a toolbar, rulers, scrollers and a statusbar. The open, save, grid and help buttons are not available, the other buttons of the toolbar can not be made invisible. In addition embedding the preview is not supported by the Community Edition. The only flags accepted by the Community Edition are VPE_DOCFILE_READONLY and VPE_FIXED_MESSAGES.