PDF Reflow

Definitions for reflow related operation.
Definitions and functions in this module are included in fpdf_reflow_r.h.
Module: PDFReflow
License Identifier: PDFReflow/All
Available License Right: Reading. More...

Classes
struct	FSPDF_REFLOWPAGE
	Handle type to PDF reflow page. More...

Functions
FS_RESULT	FSPDF_ReflowPage_Create (FSCRT_PAGE pdfPage, FSPDF_REFLOWPAGE *reflowPage)
	Create a reflow page from a PDF page. More...
FS_RESULT	FSPDF_ReflowPage_Release (FSPDF_REFLOWPAGE reflowPage)
	Release all resources allocated for a PDF reflow page handle. More...
FS_RESULT	FSPDF_ReflowPage_SetSize (FSPDF_REFLOWPAGE reflowPage, FS_FLOAT width, FS_FLOAT height)
	Set screen size before calling function FSPDF_ReflowPage_StartParse. More...
FS_RESULT	FSPDF_ReflowPage_SetLineSpace (FSPDF_REFLOWPAGE reflowPage, FS_FLOAT lineSpace)
	Set line space before calling function FSPDF_ReflowPage_StartParse. More...
FS_RESULT	FSPDF_ReflowPage_SetTopSpace (FSPDF_REFLOWPAGE reflowPage, FS_FLOAT topSpace)
	Set the top space of page before calling function FSPDF_ReflowPage_StartParse. More...
FS_RESULT	FSPDF_ReflowPage_StartParse (FSPDF_REFLOWPAGE reflowPage, FS_DWORD flags, FSCRT_PROGRESS *reflowProgress)
	Start parsing process for a reflow page. More...
FS_RESULT	FSPDF_ReflowPage_GetContentSize (FSPDF_REFLOWPAGE reflowPage, FS_FLOAT *width, FS_FLOAT *height)
	Get width and height of a reflow page after calling function FSPDF_ReflowPage_StartParse. More...
FS_RESULT	FSPDF_ReflowPage_GetMatrix (FSPDF_REFLOWPAGE reflowPage, FS_INT32 x, FS_INT32 y, FS_INT32 width, FS_INT32 height, FS_INT32 rotation, FSCRT_MATRIX *matrix)
	Get matrix of a reflow page. More...
FS_RESULT	FSPDF_RenderContext_StartReflowPage (FSPDF_RENDERCONTEXT pdfRenderContext, FSCRT_RENDERER renderer, FSPDF_REFLOWPAGE reflowPage, FSCRT_PROGRESS *renderProgress)
	Start rendering a reflow page. More...
FS_RESULT	FSPDF_ReflowPage_GetFocusData (FSPDF_REFLOWPAGE reflowPage, const FSCRT_MATRIX *matrix, FS_INT32 x, FS_INT32 y, FSCRT_BSTR *focusData)
	Get focus data corresponding to a given position in device coordinate system. More...
FS_RESULT	FSPDF_ReflowPage_GetFocusPosition (FSPDF_REFLOWPAGE reflowPage, const FSCRT_MATRIX *matrix, const FSCRT_BSTR *focusData, FS_INT32 *x, FS_INT32 *y)
	Get a point of a position in device coordinate system corresponding to a given focus data. More...

Macro Definitions for Reflow Parser Flags
#define	FSPDF_REFLOWFLAG_NORMAL   0x0
	Reflow parsing flag for normal mode, without image.
#define	FSPDF_REFLOWFLAG_IMAGE   0x1
	Reflow parsing flag for image mode.
#define	FSPDF_REFLOWFLAG_NOTRUNCATE   0x2
	Reflow parsing flag for single screen mode. More...

Detailed Description

Definitions for reflow related operation.
Definitions and functions in this module are included in fpdf_reflow_r.h.
Module: PDFReflow
License Identifier: PDFReflow/All
Available License Right: Reading.

This module contains following features:

• 1. Reflow PDF page:
  • a. Create or release a page-reflow object, set page size and line space for a page-reflow object, and start reflowing in a progressive process.
  • b. PDF page-reflow is a common feature to display page contents in a small screen device. It re-lays out page contents.
  • c. Note: the progressive process of page-reflow should finish before rendering reflowed result or accessing its data.
• 2. Render reflowed page:
  • a. Get content size of a reflowed page, get transformation matrix for a reflowed page, and render a reflowed page.
  • b. When a page is reflowed, its coordinates are different. Caller should get a new transformation matrix to display.
• 3. Data of reflowed page:
  • a. Get focus data for a position, retrieve focus position from focus data, and get text page object.
  • b. In order to track a position in a reflowed page, Foxit PDF SDK uses a focus data to represent the position. Caller can store focus data or save the data to file so that the position can be retrieved later. Focus is similar to bookmark or destination in PDF, but it is simpler.
    Functions defined in fpdf_textpage_r.h can be used to get text information.

Macro Definition Documentation

#define FSPDF_REFLOWFLAG_NOTRUNCATE   0x2

Reflow parsing flag for single screen mode.

The flag can avoid that truncate problem the bottom of screen displaying the upper part of last text or image in single screen mode. The truncate problem is related to the height of the set by calling FSPDF_ReflowPage_SetSize and if it is not set this flag, the screen could display the upper part of text in the last line or image. It can improve the effect when reading single screen mode, however, the scroll screen mode would be affected.

Function Documentation

FS_RESULT FSPDF_ReflowPage_Create	(	FSCRT_PAGE	pdfPage,
		FSPDF_REFLOWPAGE *	reflowPage
	)

Create a reflow page from a PDF page.

Parameters

[in]	pdfPage	Handle to a FSCRT_PAGE object which is a PDF page object.
[out]	reflowPage	Pointer to a FSPDF_REFLOWPAGE handle to receive the new reflow page handle if successful. Application should release this handle if not use it any more by calling function FSPDF_ReflowPage_Release.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter pdfPage or reflowPage is a NULL pointer.
FSCRT_ERRCODE_INVALIDTYPE if parameter pdfPage is not a type of PDF page.
FSCRT_ERRCODE_INVALIDLICENSE if the current license is not authorized or reflow page is not allowed.
FSCRT_ERRCODE_NOTPARSED if parameter pdfPage is not parsed.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if the function cannot create a reflow page because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• pdfPage: this handle is long-term partially recoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_GetContentSize	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_FLOAT *	width,
		FS_FLOAT *	height
	)

Get width and height of a reflow page after calling function FSPDF_ReflowPage_StartParse.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.
[out]	width	Pointer to a float that receives the width of reflow page.
[out]	height	Pointer to a float that receives the height of reflow page.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage, width or height is a NULL pointer.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_NOTPARSED if parameter reflowPage has not been parsed yet.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_GetFocusData	(	FSPDF_REFLOWPAGE	reflowPage,
		const FSCRT_MATRIX *	matrix,
		FS_INT32	x,
		FS_INT32	y,
		FSCRT_BSTR *	focusData
	)

Get focus data corresponding to a given position in device coordinate system.

Focus data of a specific content is fixed, and will not change because of different sizes of reflow pages, which are retrieved from the same PDF page of the same content. So focus data can be used to locate the same content of a PDF page in reflow pages with different sizes but same reflow content.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create. This should have been parsed successfully by calling function FSPDF_ReflowPage_StartParse.
[in]	matrix	Pointer to a FSCRT_MATRIX structure returned by function FSPDF_ReflowPage_GetMatrix.
[in]	x	X-coordinate of a specific position, in device coordinate system.
[in]	y	Y-coordinate of a specific position, in device coordinate system.
[out]	focusData	Pointer to a FSCRT_BSTR structure that receives the focus data corresponding to the specific position.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage, matrix or focusData is a NULL pointer.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_NOTPARSED if parameter reflowPage has not been parsed yet.
FSCRT_ERRCODE_ERROR if the function cannot get focus data because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_GetFocusPosition	(	FSPDF_REFLOWPAGE	reflowPage,
		const FSCRT_MATRIX *	matrix,
		const FSCRT_BSTR *	focusData,
		FS_INT32 *	x,
		FS_INT32 *	y
	)

Get a point of a position in device coordinate system corresponding to a given focus data.

Focus data of a specific content is fixed, and will not change because of different sizes of reflow pages, which are retrieved from same PDF page and with same content. So focus data can be used to locate the same content of a PDF page in reflow pages with different sizes but same reflow content.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create. This should have been parsed successfully by calling function FSPDF_ReflowPage_StartParse.
[in]	matrix	Pointer to a FSCRT_MATRIX structure returned by function FSPDF_ReflowPage_GetMatrix.
[in]	focusData	Focus data used to get its corresponding position in device coordinate system, with specific matrix. This is returned by function FSPDF_ReflowPage_GetFocusData.
[out]	x	Pointer to a FS_INT32 object that receives x-coordinate of a position. This position is just corresponding to given focus data in device coordinate system.
[out]	y	Pointer to a FS_INT32 object that receives y-coordinate of a position. This position is just corresponding to given focus data in device coordinate system.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage, matrix, focusData, x or y is a NULL pointer.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_NOTPARSED if parameter reflowPage has not been parsed yet.
FSCRT_ERRCODE_ERROR if the function cannot get focus position because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_GetMatrix	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_INT32	x,
		FS_INT32	y,
		FS_INT32	width,
		FS_INT32	height,
		FS_INT32	rotation,
		FSCRT_MATRIX *	matrix
	)

Get matrix of a reflow page.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create. This should have been parsed successfully by calling function FSPDF_ReflowPage_StartParse.
[in]	x	Left pixel of the display area in the device coordinate system.
[in]	y	Top pixel of the display area in the device coordinate system.
[in]	width	Horizontal size (in pixels) for displaying the page.
[in]	height	Vertical size (in pixels) for displaying the page.
[in]	rotation	Page orientation. Valid values are: 0: Normal 1: Rotate 90 degrees clockwise 2: Rotate 180 degrees 3: Rotate 90 degrees counter-clockwise
[out]	matrix	Pointer to a FSCRT_MATRIX struct that receives the output matrix.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage or matrix is a NULL pointer, or parameter rotation is invalid.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_NOTPARSED if parameter reflowPage has not been parsed yet.
FSCRT_ERRCODE_ERROR if the function cannot get matrix because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term unrecoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_Release

(

FSPDF_REFLOWPAGE

reflowPage

)

Release all resources allocated for a PDF reflow page handle.

Parameters

[in]

reflowPage

Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage is a NULL pointer.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is not thread safe. Do not call it for the same objects under multi-threaded environment; otherwise, the application should be synchronized.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_SetLineSpace	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_FLOAT	lineSpace
	)

Set line space before calling function FSPDF_ReflowPage_StartParse.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.
[in]	lineSpace	The line space. Default value: 0.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage is a NULL pointer.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_SetSize	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_FLOAT	width,
		FS_FLOAT	height
	)

Set screen size before calling function FSPDF_ReflowPage_StartParse.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.
[in]	width	Width of desired page. This value should be more than 20.
[in]	height	Height of desired page. This value should be more than 20.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage is a NULL pointer, or parameter width or height is equal to or less than 20.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_SetTopSpace	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_FLOAT	topSpace
	)

Set the top space of page before calling function FSPDF_ReflowPage_StartParse.

The function is used to set the distance between the page's top and the screen's top when to reflow a page.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.
[in]	topSpace	The top space of page when to reflow and this value should be equal or greater than zero. Default value: 0.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter reflowPage is a NULL pointer, or topSpace is less than zero.
. For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_ReflowPage_StartParse	(	FSPDF_REFLOWPAGE	reflowPage,
		FS_DWORD	flags,
		FSCRT_PROGRESS *	reflowProgress
	)

Start parsing process for a reflow page.

It may take a long time to parsing a reflow page, so Foxit PDF SDK uses a progressive process to do this.
Caller should set parameter reflowProgress and call function FSCRT_Progress_Continue to continue parsing in steps if necessary, and should call function FSCRT_Progress_Release to destroy reflowProgress object after parsing process.
All the resources about reflow page will be loaded after the reflow page is parsed.
Function FSPDF_ReflowPage_SetSize must be called before this function sets the screen size. And this function should be called before any getting reflow method can be used.

Parameters

[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create.
[in]	flags	Reflow parsing mode. It should be one of the following macro definitions: FSPDF_REFLOWFLAG_NORMAL FSPDF_REFLOWFLAG_IMAGE FSPDF_REFLOWFLAG_NOTRUNCATE
[out]	reflowProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process if successful.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_FINISHED if parameter reflowPage has reflowed over.
FSCRT_ERRCODE_PARAM if parameter reflowPage or reflowProgress is a NULL pointer, or parameter flagsis invalid.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if the function cannot start reflowing page because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.
• reflowProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.

FS_RESULT FSPDF_RenderContext_StartReflowPage	(	FSPDF_RENDERCONTEXT	pdfRenderContext,
		FSCRT_RENDERER	renderer,
		FSPDF_REFLOWPAGE	reflowPage,
		FSCRT_PROGRESS *	renderProgress
	)

Start rendering a reflow page.

It will take a long time to render reflow a page with complex or large contents, so Foxit PDF SDK uses a progressive process to do this.
Caller should pass renderProgress to FSCRT_Progress_Continue to continue rendering in steps, and should call FSCRT_Progress_Release to destroy renderProgress object after rendering process.

Parameters

[in]	pdfRenderContext	Handle to a FSPDF_RENDERCONTEXT object which is a PDF rendering context, created by function FSPDF_RenderContext_Create.
[in]	renderer	Handle to a FSCRT_RENDERER object which represents a rendering engine, created by function FSCRT_Renderer_CreateOnBitmap or platform-dependednt renderer creating functions.
[in]	reflowPage	Handle to a FSPDF_REFLOWPAGE object returned by function FSPDF_ReflowPage_Create. This should have been parsed successfully by calling function FSPDF_ReflowPage_StartParse.
[out]	renderProgress	Pointer to a FSCRT_PROGRESS handle that receives a handle of progressive process if successful.

Returns

FSCRT_ERRCODE_SUCCESS for success.
FSCRT_ERRCODE_PARAM if parameter pdfRenderContext, renderer, reflowPage or renderProgress is a NULL pointer.
FSCRT_ERRCODE_NOTPARSED if parameter reflowPage is not parsed.
FSCRT_ERRCODE_UNRECOVERABLE if the function can not be recovered.
FSCRT_ERRCODE_OUTOFMEMORY if there is not enough memory or if the memory access is wrong.
FSCRT_ERRCODE_ERROR if the function cannot start rendering a reflow page because of any other reason.
For more error codes, please refer to macro definitions FSCRT_ERRCODE_XXX.

Note

Among functions FSPDF_RenderContext_SetXXX, only FSPDF_RenderContext_SetMatrix is effective for the rendering of reflow page .

Attention

Thread Safety: this function is thread safe.
OOM Information:
OOM handling is only for mobile platforms, not for server or desktop.

• This function is long-term recoverable.
• pdfRenderContext: this handle is long-term recoverable.
• renderer: this handle is long-term recoverable.
• reflowPage: this handle is long-term partially recoverable.
• renderProgress: this handle is long-term partially recoverable.

Please refer to the document "Robust PDF Applications with Limited Memory" for more details.