home | download | documentation | examples | sourceforge | forums

## Handles

### Hierarchy of Handles

A handle is an opaque pointer to handle objects. All functions in Haru include one or more handles in their parameter list.
The following figure illustrates the relationship between the various types of handles.

### Document Handle (HPDF_Doc)

The document handle is a handle to operate a document object. It is created by invoking HPDF_New() or HPDF_NewEx(). And it is freed by invoking HPDF_Free().
When HPDF_Free() is invoked, all objects owned by the document object are freeed all together.

### Page Handle (HPDF_Page)

The page handle is used to operate an individual page. When HPDF_AddPage() or HPDF_InsertPage() is invoked, a page object is created and the handle of the page object is returned.
The functions whose name started with "HPDF_Page_" require page handle as first parameter.

### Image Handle (HPDF_Image)

The image handle is used to display image to a page mainly.
When the following functions are invoked, an image object is created and the handle of the image is returned.

- HPDF_LoadPngImageFromFile()
- HPDF_LoadJpegImageFromFile()
- HPDF_LoadRawImageFromFile()
- HPDF_LoadRawImageFromMem()

### Font Handle (HPDF_Font)

The font handle is a handle to handle a font object.
A font handle is returned by invoking HPDF_GetFont().

### Encoding Handle (HPDF_Encoding)

The encoding handle is a handle to handle a encoding object.
A encoding handle is returned by invoking HPDF_GetEncoding().

### Outline Handle (HPDF_Outline)

The outline handle is used to operate an outline of a document.
When HPDF_CreateOutline() is invoked, an outline-node object is created and the handle of the node is returned.

### Destination Handle (HPDF_Destination)

The destination object specifies the view of the page to be displayed when the outline item or annotation is clicked.
And the destination handle is used to operate destination object.

### Annotation Handle (HPDF_Annotation)

There are three type of annotation-object on Haru. First is the text-annotation which represents a "sticky note". Second is the link-annotation which represents a hypertext link to a destination. And third is the URI-link-annotation which represents a hypertext link to a web page.
The annotation handle is used to set properties of an annotation object.