ImageGear v26.5 - Updated
Developer Guide / How to Work with ... / Office / Get Started with ImageGear Office
In This Topic
    Get Started with ImageGear Office
    In This Topic

    The ImageGear Office component utilizes LibreOffice to process Microsoft Word, Excel, and PowerPoint documents. In order to utilize the ImageGear Office component, LibreOffice must be installed on the machine.

    Installing LibreOffice

    Windows:

    The Windows installer for LibreOffice can be downloaded from libreoffice.org. Portable versions of LibreOffice are supported and can be found on the LibreOffice website as well.

    Linux:

    LibreOffice can be downloaded from libreoffice.org. Instructions on how to install it via the terminal can be found in the Document Foundation's wiki

    Initializing the ImGearOffice Component

    The ImageGear.Formats.Office Namespace allows you to load and convert Microsoft Word, Excel, and PowerPoint documents.

    The ImGearOffice component relies on the ImGearPDF component for processing. So, to use ImGearOffice you will also need to add the PDF format to the filter list and make a call to ImGearPDF.Initialize().

    Next, you will need to create the office file format objects that you wish to use and add them to the filter list, followed by a call to ImGearOffice.Initialize().

    See our OfficeFileToRasterFormat sample for an example of the above initialization process.

    If your application is single-threaded, the above initialization steps will only need to be performed once for the runtime of your program. Multithreaded applications should ensure that an ImGearPDF.Initialize() and accompanying ImGearPDF.Terminate() call occur on each thread.

    A call to an ImGearOffice.Initialize() method should be paired with a call to the Terminate() method. The very first call to ImGearOffice.Initialize() will initialize LibreOffice, while its paired call to Terminate() method will de-initialize and stop LibreOffice.

    Specifying the LibreOffice Install Location

    When the ImGearOffice component is initialized, you will need to supply a path to the LibreOffice installation on your target machine. The specified path should be the directory containing the file soffice.com on Windows or soffice on Linux. See any of our Office samples on github for an example of how to specify the path when initializing ImGearOffice.

    Working with the ImGearOffice Component

    Once the ImGearOffice component has been initialized you can begin using it to load Office documents and perform conversion to PDF or raster formats.

    Loading a Word Document

    A Word document can be loaded into ImageGear using the ImGearFileFormats.LoadDocument method and once loaded is represented by an ImGearWordDocument. See the OfficeFileToPDFFile sample for an example of how to load a Word document with ImageGear.

    ImageGear Office is thread-safe, but only supports single-threaded loading. Attempting to load many Microsoft Office documents using multiple threads will result in negligible performance improvement.

    Conversion to PDF

    After the Office document is loaded into ImageGear, it can be converted and saved out as a PDF. The same OfficeFileToPDFFile sample demonstrates this conversion process.

    Conversion to Raster

    The ImGearWordDocument can also be converted to raster formats, such as TIF, using the ImageGearFileFormats.SaveDocument method. See our OfficeFileToRasterFormat sample for an example. Alternatively, the Rasterize method and its various overloads can be used on each page to produce an ImGearRasterPage object.

    Conversion to SVG

    Office documents or pages of documents can be converted to Scalable Vector Graphics (SVG) files. Once the document is loaded, this can be done by using the ImageGearFileFormats.SaveDocument or ImGearFileFormats.SavePage methods and specifying the ImGearSavingFormats.SVG as the saving format.

    Since the SVG format is not a multi-page format, the SaveDocument API called with default options will concatenate all converted pages into one SVG file.

    Reading Office Metadata

    Read Office metadata using Simplified Metadata API property ImGearMetadataHead.Office. See the ReadOfficeMetadata sample for an example of that process. The following Office metadata is supported for reading:

    Property DOCX, PPTX, XLSX DOC, PPT, XLS
    Created dcterms:created GKPIDSI_CREATE_DTM
    Creator dc:creator GKPIDSI_AUTHOR
    LastModifiedBy cp:lastModifiedBy GKPIDSI_LASTAUTHOR
    Modified dcterms:modified GKPIDSI_LASTSAVE_DTM
    Revision cp:revision GKPIDSI_REVNUMBER
    Subject dc:subject GKPIDSI_SUBJECT
    Title dc:title GKPIDSI_TITLE

    Office metadata is not settable.

    Terminating the ImGearOffice Component

    The ImGearOffice component must be terminated using the Terminate() method when the application is disposed. See below:

    ImGearOffice.Terminate();
    

    If the ImGearOffice component is terminated then it must be re-initialized in order to continue processing Office documents.