Go to the source code of this file.
Classes | |
| struct | MuOfficeBitmap |
| struct | MuOfficePoint |
| struct | MuOfficeBox |
| struct | MuOfficePathPoint |
| struct | MuOfficeRenderArea |
Typedefs | |
| typedef int | MuError |
| typedef enum MuOfficeDocErrorType | MuOfficeDocErrorType |
| typedef enum MuOfficePointType | MuOfficePointType |
| typedef struct MuOfficeLib | MuOfficeLib |
| typedef struct MuOfficeDoc | MuOfficeDoc |
| typedef struct MuOfficePage | MuOfficePage |
| typedef struct MuOfficeRender | MuOfficeRender |
| typedef void * | MuOfficeAllocFn(void *cookie, size_t size) |
| typedef void | MuOfficeLoadingProgressFn(void *cookie, int pagesLoaded, int complete) |
| typedef void | MuOfficeLoadingErrorFn(void *cookie, MuOfficeDocErrorType error) |
| typedef void | MuOfficePageUpdateFn(void *cookie, const MuOfficeBox *area) |
| typedef void | MuOfficeRenderProgressFn(void *cookie, MuError error) |
| typedef enum MuOfficeSaveResult | MuOfficeSaveResult |
| typedef void | MuOfficeSaveResultFn(void *cookie, MuOfficeSaveResult result) |
Typedef Documentation
◆ MuError
| typedef int MuError |
Mu Office Library
This helper layer provides an API for loading, and displaying a file. It is deliberately as identical as possible to the smart-office-lib.h header file in Smart Office to facilitate a product which can use both Smart Office and MuPDF. Error type returned from most MuOffice functions
0 means no error
non-zero values mean an error occurred. The exact value is an indication of what went wrong and should be included in bug reports or support queries. Library users should not test this value except for 0, non-zero and any explicitly documented values.
◆ MuOfficeAllocFn
| typedef void * MuOfficeAllocFn(void *cookie, size_t size) |
Allocator function used by some functions to get blocks of memory.
- Parameters
-
cookie data pointer passed in with the allocator. size the size of the required block.
- Returns
- as for malloc. (NULL implies OutOfMemory, or size == 0). Otherwise a pointer to an allocated block.
◆ MuOfficeDoc
| typedef struct MuOfficeDoc MuOfficeDoc |
◆ MuOfficeDocErrorType
| typedef enum MuOfficeDocErrorType MuOfficeDocErrorType |
Errors returned to MuOfficeLoadingErrorFn
Other values may also be returned.
◆ MuOfficeLib
| typedef struct MuOfficeLib MuOfficeLib |
◆ MuOfficeLoadingErrorFn
| typedef void MuOfficeLoadingErrorFn(void *cookie, MuOfficeDocErrorType error) |
Callback function used to monitor errors in the process of loading a document.
- Parameters
-
cookie the data pointer that was originally passed to MuOfficeLib_loadDocument. error the error being reported
◆ MuOfficeLoadingProgressFn
| typedef void MuOfficeLoadingProgressFn(void *cookie, int pagesLoaded, int complete) |
Callback function monitoring document loading
Also called when the document is edited, either adding or removing pages, with the pagesLoaded value decreasing in the page-removal case.
- Parameters
-
cookie the data pointer that was originally passed to MuOfficeLib_loadDocument. pagesLoaded the number of pages so far discovered. complete whether loading has completed. If this flag is set, pagesLoaded is the actual number of pages in the document.
◆ MuOfficePage
| typedef struct MuOfficePage MuOfficePage |
◆ MuOfficePageUpdateFn
| typedef void MuOfficePageUpdateFn(void *cookie, const MuOfficeBox *area) |
Callback function used to monitor page changes
- Parameters
-
cookie the data pointer that was originally passed to MuOfficeDoc_getPage. area the area that has changed.
◆ MuOfficePointType
| typedef enum MuOfficePointType MuOfficePointType |
◆ MuOfficeRender
| typedef struct MuOfficeRender MuOfficeRender |
◆ MuOfficeRenderProgressFn
| typedef void MuOfficeRenderProgressFn(void *cookie, MuError error) |
Callback function used to monitor a background render of a document page. The function is called exactly once.
- Parameters
-
cookie the data pointer that was originally passed to MuOfficeDoc_monitorRenderProgress. error error returned from the rendering process
◆ MuOfficeSaveResult
| typedef enum MuOfficeSaveResult MuOfficeSaveResult |
The possible results of a save operation
◆ MuOfficeSaveResultFn
| typedef void MuOfficeSaveResultFn(void *cookie, MuOfficeSaveResult result) |
Callback function used to monitor save operations.
- Parameters
-
cookie the data pointer that was originally passed to MuOfficeDoc_save. result the result of the save operation
Enumeration Type Documentation
◆ MuOfficeDocErrorType
| enum MuOfficeDocErrorType |
Errors returned to MuOfficeLoadingErrorFn
Other values may also be returned.
◆ MuOfficeDocType
| enum MuOfficeDocType |
◆ MuOfficePointType
| enum MuOfficePointType |
◆ MuOfficeSaveResult
| enum MuOfficeSaveResult |
Function Documentation
◆ MuOfficeDoc_abortLoad()
| void MuOfficeDoc_abortLoad | ( | MuOfficeDoc * | doc | ) |
Stop a document loading. The document is not destroyed, but no further content will be read from the file.
- Parameters
-
doc the MuOfficeDoc object
◆ MuOfficeDoc_destroy()
| void MuOfficeDoc_destroy | ( | MuOfficeDoc * | doc | ) |
Destroy a MuOfficeDoc object. Loading of the document is shutdown and no further callbacks will be issued for the specified object.
- Parameters
-
doc the MuOfficeDoc object
◆ MuOfficeDoc_docType()
| MuOfficeDocType MuOfficeDoc_docType | ( | MuOfficeDoc * | doc | ) |
Return the type of an open document
- Parameters
-
doc the document object
- Returns
- the document type
◆ MuOfficeDoc_getNumPages()
| MuError MuOfficeDoc_getNumPages | ( | MuOfficeDoc * | doc, |
| int * | pNumPages ) |
Return the number of pages of a document
This function waits for document loading to complete before returning the result. It may block the calling thread for a significant period of time. To avoid blocking, this call should be avoided in favour of using the MuOfficeLib_loadDocument callbacks to monitor loading.
If background loading fails, the associated error will be returned from this call.
- Parameters
-
doc the document pNumPages address for return of the number of pages
- Returns
- error indication - 0 for success
◆ MuOfficeDoc_getPage()
| MuError MuOfficeDoc_getPage | ( | MuOfficeDoc * | doc, |
| int | pageNumber, | ||
| MuOfficePageUpdateFn * | updateFn, | ||
| void * | cookie, | ||
| MuOfficePage ** | pPage ) |
Get a page of a document
- Parameters
-
doc the document object pageNumber the number of the page to load (lying in the range 0 to one less than the number of pages) updateFn Function to be called back when the page updates cookie Opaque value to pass for any updates pPage Address for return of the page object
- Returns
- error indication - 0 for success
◆ MuOfficeDoc_hasBeenModified()
| int MuOfficeDoc_hasBeenModified | ( | MuOfficeDoc * | doc | ) |
Determine if the document has been modified
- Parameters
-
doc the document
- Returns
- modified flag
◆ MuOfficeDoc_providePassword()
| int MuOfficeDoc_providePassword | ( | MuOfficeDoc * | doc, |
| const char * | password ) |
Provide the password for a document
This function should be called to provide a password with a document error if MuOfficeError_PasswordRequired is received.
If a password is requested again, this means the password was incorrect.
- Parameters
-
doc the document object password the password (UTF8 encoded)
- Returns
- error indication - 0 for success
◆ MuOfficeDoc_run()
| MuError MuOfficeDoc_run | ( | MuOfficeDoc * | doc, |
| void(* | fn )(fz_context *ctx, fz_document *doc, void *arg), | ||
| void * | arg ) |
Perform MuPDF native operations on a given document.
The function is called with fz_context and fz_document values that can be safely used (i.e. the context is cloned/dropped appropriately around the function, and locking is used to ensure that no other threads are simultaneously using the document). Functions can signal errors by fz_throw-ing.
Due to the locking, it is best to ensure that as little time is taken here as possible (i.e. if you fetch some data and then spend a long time processing it, it is probably best to fetch the data using MuOfficeDoc_run and then process it outside). This avoids potentially blocking the UI.
- Parameters
-
doc the document object. fn the function to call with fz_context/fz_document values. arg Opaque data pointer.
- Returns
- error indication - 0 for success
◆ MuOfficeDoc_save()
| MuError MuOfficeDoc_save | ( | MuOfficeDoc * | doc, |
| const char * | path, | ||
| MuOfficeSaveResultFn * | resultFn, | ||
| void * | cookie ) |
Start a save operation
- Parameters
-
doc the document path path of the file to which to save resultFn callback used to report completion cookie a pointer to pass to the callback
- Returns
- error indication - 0 for success
◆ MuOfficeLib_create()
| MuError MuOfficeLib_create | ( | MuOfficeLib ** | pMu | ) |
Create a MuOfficeLib instance.
- Parameters
-
pMu address of variable to receive the created instance
- Returns
- error indication - 0 for success
◆ MuOfficeLib_destroy()
| void MuOfficeLib_destroy | ( | MuOfficeLib * | mu | ) |
Destroy a MuOfficeLib instance
- Parameters
-
mu the instance to destroy
◆ MuOfficeLib_getDocTypeFromFileExtension()
| MuOfficeDocType MuOfficeLib_getDocTypeFromFileExtension | ( | const char * | path | ) |
Find the type of a file given its filename extension.
- Parameters
-
path path to the file (in utf8)
- Returns
- a valid MuOfficeDocType value, or MuOfficeDocType_Other
◆ MuOfficeLib_getSupportedFileExtensions()
| char * MuOfficeLib_getSupportedFileExtensions | ( | void | ) |
Return a list of filename extensions supported by Mu Office library.
- Returns
- comma-delimited list of extensions, without the leading ".". The caller should free the returned pointer..
◆ MuOfficeLib_loadDocument()
| MuError MuOfficeLib_loadDocument | ( | MuOfficeLib * | mu, |
| const char * | path, | ||
| MuOfficeLoadingProgressFn * | progressFn, | ||
| MuOfficeLoadingErrorFn * | errorFn, | ||
| void * | cookie, | ||
| MuOfficeDoc ** | pDoc ) |
Load a document
Call will return immediately, leaving the document loading in the background
- Parameters
-
mu a MuOfficeLib instance path path to the file to load (in utf8) progressFn callback for monitoring progress errorFn callback for monitoring errors cookie a pointer to pass back to the callbacks pDoc address for return of a MuOfficeDoc object
- Returns
- error indication - 0 for success
The progress callback may be called several times, with increasing values of pagesLoaded. Unless MuOfficeDoc_destroy is called, before loading completes, a call with "completed" set to true is guaranteed.
Once MuOfficeDoc_destroy is called there will be no further callbacks.
Alternatively, in a synchronous context, MuOfficeDoc_getNumPages can be called to wait for loading to complete and return the total number of pages. In this mode of use, progressFn can be NULL.
◆ MuOfficeLib_run()
| MuError MuOfficeLib_run | ( | MuOfficeLib * | mu, |
| void(* | fn )(fz_context *ctx, void *arg), | ||
| void * | arg ) |
Perform MuPDF native operations on a given MuOfficeLib instance.
The function is called with a fz_context value that can be safely used (i.e. the context is cloned/dropped appropriately around the call). The function should signal errors by fz_throw-ing.
- Parameters
-
mu the MuOfficeLib instance. fn the function to call to run the operations. arg Opaque data pointer.
- Returns
- error indication - 0 for success
◆ MuOfficePage_calculateZoom()
| MuError MuOfficePage_calculateZoom | ( | MuOfficePage * | page, |
| int | width, | ||
| int | height, | ||
| float * | pXZoom, | ||
| float * | pYZoom ) |
Return the zoom factors necessary to render at to a given size in pixels. (deprecated)
- Parameters
-
page the page object width the desired width height the desired height pXZoom Address for return of zoom necessary to fit width pYZoom Address for return of zoom necessary to fit height
- Returns
- error indication - 0 for success
◆ MuOfficePage_destroy()
| void MuOfficePage_destroy | ( | MuOfficePage * | page | ) |
Destroy a page object
Note this does not delete or remove the page from the document. It simply destroys the page object which is merely a reference to the page.
- Parameters
-
page the page object
◆ MuOfficePage_getSize()
| MuError MuOfficePage_getSize | ( | MuOfficePage * | page, |
| float * | pWidth, | ||
| float * | pHeight ) |
Get the size of a page in pixels
This returns the size of the page in pixels. Pages can be rendered with a zoom factor. The returned value is the size of bitmap appropriate for rendering with a zoom of 1.0 and corresponds to 90 dpi. The returned values are not necessarily whole numbers.
- Parameters
-
page the page object pWidth address for return of the width pHeight address for return of the height
- Returns
- error indication - 0 for success
◆ MuOfficePage_getSizeForZoom()
| MuError MuOfficePage_getSizeForZoom | ( | MuOfficePage * | page, |
| float | zoom, | ||
| int * | pWidth, | ||
| int * | pHeight ) |
Get the size of a page in pixels for a specified zoom factor (deprecated)
This returns the size of bitmap that should be used to display the entire page at the given zoom factor. A zoom of 1.0 corresponds to 90 dpi.
- Parameters
-
page the page object zoom the zoom factor pWidth address for return of the width pHeight address for return of the height
- Returns
- error indication - 0 for success
◆ MuOfficePage_render()
| MuError MuOfficePage_render | ( | MuOfficePage * | page, |
| float | zoom, | ||
| const MuOfficeBitmap * | bitmap, | ||
| const MuOfficeRenderArea * | area, | ||
| MuOfficeRenderProgressFn * | progressFn, | ||
| void * | cookie, | ||
| MuOfficeRender ** | pRender ) |
Schedule the rendering of an area of document page to an area of a bitmap.
The alignment between page and bitmap is defined by specifying document's origin within the bitmap, possibly either positive or negative. A render object is returned via which the process can be monitored or terminated.
The progress function is called exactly once per render in either the success or failure case.
Note that, since a render object represents a running thread that needs access to the page, document, and library objects, it is important to call MuOfficeRender_destroy, not only before using or deallocating the bitmap, but also before calling MuOfficePage_destroy, etc..
- Parameters
-
page the page to render zoom the zoom factor bitmap the bitmap area area to render progressFn the progress callback function cookie a pointer to pass to the callback function pRender Address for return of the render object
- Returns
- error indication - 0 for success
◆ MuOfficePage_run()
| MuError MuOfficePage_run | ( | MuOfficePage * | page, |
| void(* | fn )(fz_context *ctx, fz_page *page, void *arg), | ||
| void * | arg ) |
Perform MuPDF native operations on a given page.
The function is called with fz_context and fz_page values that can be safely used (i.e. the context is cloned/dropped appropriately around the function, and locking is used to ensure that no other threads are simultaneously using the document). Functions can signal errors by fz_throw-ing.
Due to the locking, it is best to ensure that as little time is taken here as possible (i.e. if you fetch some data and then spend a long time processing it, it is probably best to fetch the data using MuOfficePage_run and then process it outside). This avoids potentially blocking the UI.
- Parameters
-
page the page object. fn the function to call with fz_context/fz_document values. arg Opaque data pointer.
- Returns
- error indication - 0 for success
◆ MuOfficeRender_abort()
| void MuOfficeRender_abort | ( | MuOfficeRender * | render | ) |
Abort a render
This call aborts any rendering currently underway. The 'render complete' callback (if any) given when the render was created will still be called. If a render has completed, this call will have no effect.
This call will not block to wait for the render thread to stop, but will cause it to stop as soon as it can in the background.
- Note
- It is important not to start any new render to the same bitmap until the callback comes in (or until waitUntilComplete returns), as otherwise you can have multiple renders drawing to the same bitmap with unpredictable consequences.
- Parameters
-
render The render object to abort
◆ MuOfficeRender_destroy()
| void MuOfficeRender_destroy | ( | MuOfficeRender * | render | ) |
Destroy a render
This call destroys a MuOfficeRender object, aborting any current render.
This call is intended to support an app dealing with a user quickly flicking through document pages. A render may be scheduled but, before completion, be found not to be needed. In that case the bitmap will need to be reused, which requires any existing render to be aborted. The call to MuOfficeRender_destroy will cut short the render and allow the bitmap to be reused immediately.
- Note
- If an active render thread is destroyed, it will be aborted. While fast, this is not an instant operation. For maximum responsiveness, it is best to 'abort' as soon as you realise you don't need the render, and to destroy when you get the callback.
- Parameters
-
render The render object
◆ MuOfficeRender_waitUntilComplete()
| MuError MuOfficeRender_waitUntilComplete | ( | MuOfficeRender * | render | ) |
Wait for a render to complete.
This call will not return until rendering is complete, so on return the bitmap will contain the page image (assuming the render didn't run into an error condition) and will not be used further by any background processing. Any error during rendering will be returned from this function.
This call may block the calling thread for a significant period of time. To avoid blocking, supply a progress-monitoring callback function to MuOfficePage_render.
- Parameters
-
render The render object to destroy
- Returns
- render error condition - 0 for no error.
