Label Gallery SDK User Guide 1 COPYRIGHTS Rev: Rev-20120323 Copyright © 2012 SATO CORPORATION. All rights reserved. www.satoworldwide.com The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements. No part of the publication may be reproduced, stored in a retrieval system, or transmitted in any form or any means electronically or mechanically, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of SATO Corporation. SATO assumes no responsibilities for any errors that may appear. TRADEMARKS SATO Label Gallery is a trademark or registered trademark of Sato Corporation. in Japan and other countries. Microsoft and Windows are registered trademarks of Microsoft Corporation. Other brands and their products are trademarks or registered trademarks of their respective holders and should be noted as such. 2 Table of Contents 1. Label Gallery SDK Overview........................................................................4 1.1 Introduction to Label Gallery Development Series.................................................4 1.2 Introduction to Label Gallery SDK (Software Development Kit)............................4 1.3 Label Gallery SDK Workflow.....................................................................................5 1.4 Label Gallery SDK Components................................................................................5 1.5 Functional comparison between Label Gallery Engine and Label Gallery Plus.......................................................................................................6 1.6 Programming Syntax..................................................................................................6 1.6.1 More information.............................................................................................6 1.7 Label Design................................................................................................................7 2. Installing LabelGallery SDK.........................................................................9 2.1 System Requirements................................................................................................9 2.2 Deploying LabelGallery Engine Files........................................................................9 2.2.1 Deploying GalleryLabel Engine with the Installer (Interactive Deployment)...9 2.2.1 Deploying Label Gallery Engine without the Installer (Automatic Deployment) ......................................................................................................................10 2.2.1 Deploying Label Gallery Engine with Windows Installer Merge Module.......12 2.3 Location of Label Gallery SDK Files.......................................................................14 2.3.1 Location of files for the deployment type of installation................................14 2.3.1 Location of files for the developer type of installation...................................14 2.4 Setting up Support for Logging (Optional)............................................................14 2.4.1 Installing logging support..............................................................................15 2.4.1 Defining the logging parameters...................................................................15 3. Activating LabelGallery SDK......................................................................17 3.1 Adding Support for Hardware Key (Optional)........................................................17 3.2 Manually Activating Label Gallery SDK..................................................................18 4. Glossary.......................................................................................................19 5. Appendix......................................................................................................21 6. Technical Support.......................................................................................23 Regional HQ..........................................................................................................................23 AMERICAS..................................................................................................................23 ASIA PACIFIC..............................................................................................................25 3 1. Label Gallery SDK Overview 1.1 Introduction to Label Gallery Development Series Label Gallery Developer Series is a line of products that provides tools to integrate bar code and RFID label printing into 3rd party software applications. TheLabel Gallery Developer Series addresses development needs for label printing from desktop, server, mobilesoftware applications. TheLabel Gallery Developer Series provides tools for label printing integration from 3rd party applications that lack ability to print labels to thermal printers. The heart of the products inthe Developer Series isLabel Gallery Engine, the print engine that you can embed into the application and is responsible for optimized label processing and printing. You can communicate with theLabel Gallery Engine through different programming interfaces (dependant on the platform you use). Figure1:Label GalleryDeveloper Series- Quick implementation combined with flawless performance 1.2 Introduction to Label Gallery SDK (Software Development Kit) Label Gallery SDK (Software Development Kit) is anintegration edition ofLabel Gallery software for developers.Label Gallery SDK has all of the label design functionality ofLabel GalleryPlus and includes all label printing functionality of the Label Gallery print engine. TheLabel Gallery SDK edition includes documentation, samples and tools designed to help you develop your labelprinting applications usingLabel Gallery as the background print engine to process labels and send the print jobs to the label printers. The heart ofLabel Gallery SDK istheLabel Gallery Engine designed to be integrated to other Windows-based applications through the ActiveX (OLE Automation) or .NET programming interfaces. The available ActiveX methods and properties are the same as for the regularLabel Gallery Plus edition and its programming interface. The Label Gallery Engine acts as a label printing motor and enables software publishers to add label-printing functionality to their own applications.Label Gallery Engine becomes a seamlessly integrated component of the software publisher's application. Label Gallery Engine is not used for label design but purely for label processing and printing. It provides the same reliable and robust print engine asthe stand-alone editions ofLabel Gallery software. Label Gallery SDK is a great opportunity for businesses where you need the option to easily deploy and efficiently print the labels. In this case the label design user-interface and other user-support files are not necessary. Label Gallery SDK includes only the core label-printing related files ofLabel Gallery Plus (Label 4 Gallery Engine). The installation is stripped of all unnecessary files and user interface that otherwise accompany regular editions of theLabel Gallery software. Label Gallery SDK includes the program code snippets and complete ready-made sample applications from different development platforms. From these samples you can learn how to use the power of the Label Gallery Engine for your own applications. 1.3 Label Gallery SDK Workflow Label Gallery Engine can print labels that have been created withthe licensed version of theLabel Gallery software.LabelGalleryEngine does not have any label design capabilities and cannot be used to create labels. You must create all labels with one of theregularLabel Gallery software editions. The Label Gallery SDK edition includes one copy of thelicensed version ofLabelGallery Plus that is used as a label design tool. TheLabel Gallery Plus license is not distributed to the end users. It is solely used by the software publishers to design labels for their customers and embed them with their own applications. The typical deployment scenario forLabel Gallery SDK is the following: 1. Software Publisher creates the labels withLabel Gallery Plus. The license to activate Label Gallery Plus is included in theLabel Gallery SDK package. 2. Software publisher usesLabel Gallery SDK tointegrateLabel Gallery Engine into the application using the ActiveX or .NET programming interface as the communication protocol. 3. When end users install the application on their computer,Label Gallery Engine will be installed at the same time. InstallingLabel Gallery Engine can be both: a seamless part of the main application installation (recommended) or a separate installation. 4. Software Publisher activates Label Gallery Engine on the user’s computer. This step can also be completed automatically within the installation of your application. 5. Labels are copied to the user’s computer in a predefined folder. This step can also be completed automatically within the installation of your application. 6. The application uses Label Gallery Engine as the label printing engine. The user is not aware of Label Gallery software running in the background and printing labels. 1.4 Label Gallery SDK Components TheLabel Gallery SDK includes the following components: 1. Label Gallery Engine The necessary files to install and run print engine embedded within your application. Distribution rights are determined by the included license agreement. 2. Label Gallery Plus Label Gallery software that enables the design of labels to be printed withLabel Gallery Engine. You can also test-print your labels. 3. LabelGallery SDK Software Key The softwware key is a license that allows the designer or developer to runLabel GalleryPlus in a design mode and create or modify labels. 4. Label Gallery SDK User Guide Instructions for installation, licensing and basic usage of theLabel Gallery Engine. 5. Label Programming Guide Document provides detailed information on how to use theLabel Gallery ActiveX interface. It will help you learn how to integrateLabel Gallery Engine into your applications. 6. Label Gallery SDK License Agreement The vital part of eachLabelGallerySDK installation. The certificate file is mandatory to activate and runLabel Gallery Engine. 7. GalleryDrivers GalleryDrivers are optimized Windows drivers for high-quality, speed-efficient printing on industrial thermal label printers. 5 1.5 Functional comparison between Label Gallery Engine and Label Gallery Plus Label Gallery Engine1 Label Gallery Plus Create labels NO YES Print labels YES YES Needs custom YES NO application for initiation of label printing ActiveX YES YES programming interface Class Name LabelGalleryPlus3.Engine LabelGalleryPlus3.Application 1.6 Programming Syntax You need to be a programmer to useLabel Gallery SDK and integrateLabel Gallery Engine into your application. ActiveX and .NET communication is possible to theLabel Gallery Engine. For the list of available methods and properties of ActiveX interface inLabel Gallery Engine, please refer to the Label Gallery Programming Guide. The programming guide is available on: 1. Label Gallery Developer Series CD 2. Label Galleryonlineathttp://www.satoworldwide.com/label-gallery.aspx 3. On your computer in the folderc:\ProgramFiles\Sato\LabelGallery SDK, when you have installedLabel Gallery SDK using the developer type of installation. Refer to the chapter ‘InstallingLabelGallerySDK’ for more information about installation types. Make sure to use the proper class name when communicating with theLabel Gallery Engine. Pay attention to the following class names: 1. LabelGalleryPlus3Engine:To connect to the ActiveX interface of Label Galleryprint engine, use the class name “LabelGalleryPlus3.Engine”. 2. LabelGalleryPlus3Application: To connect to the ActiveX interface ofLabel Gallery Plus, use the class name “LabelGalleryPlus3.Application”. The different class names for theLabel Gallery Engine andLabel Gallery Plus edition is the only difference between both ActiveX interfaces. All ActiveX commands and propertiesofLabel Gallery Engine andLabel Gallery Plus are the same. 1.6.1 More information See the ready-made code samples to understand how to work with the Label Gallery programming interface. The samples are available with theLabel Gallery Integration Pack. The pack is a self-extractable file that contains theLabel Gallery programming samples prepared in different development environments (Delphi, C++, Visual Basic, etc.) The Integration Pack is available ontheLabel Gallery Developer Series CD and onlineat http://www.satoworldwide.com/label-gallery.aspx 1 The same Label Gallery Engine s available also with any Label Gallery Plus and Label Gallery TruePro edition (including Network and Print-Only products). However, in this case Label Gallery Engine cannot be distributed as a separate product, like it is in the Developer Series. 6 1.7 Label Design The followingLabel Gallery editions can be used to design labels that will be printed with theLabel Gallery SDK: - Label Gallery Plus from theLabel Gallery SDK package. The hardware key included in the package gives you full access to allLabel GalleryPlus design features. - Any other stand-aloneLabel Gallery software with label design capabilities equal or greater thanLabel Gallery Plus. Note:Labels designed for printing with the Label Gallery SDK can use the full range of Label Gallery Plus functionality. For more information about designing labels refer to theLabel Gallery Plus user guide available on the Label Gallery Developer Series CD and online athttp://www.satoworldwide.com/label-gallery.aspx/ 7 Installing LabelGallery SDK 2. Installing LabelGallery SDK This section provides details for installingLabel Gallery SDK on deployment computers as well as on development computers. When the installation process is complete, you have to activatetheLabel Gallery Engine with the provided certificate file. 2.1 System Requirements To ensure adequate performance, Label Gallery SDK has the followingsystem requirements for theLabel Gallery Engine. Please ensure that the target systems meet these requirements before starting the installation process:  Pentium based computer with at least 128 MB of RAM  One of the 32-bit or 64-bit Windows operating systems: Microsoft 2000, XP, 2003, Vista and 7.  Hard disk with 75 to 210 MB of free disk space (depending on the installation options). CD- ROM drive 2.2 Deploying LabelGallery Engine Files You can installLabelGallery Engine with the provided installer in interactive or automatic mode. If you use Windows Installer for your application installation, you can also embed the installation of the LabelGallery Engine with your software as Windows Installer merge module. 2.2.1 Deploying GalleryLabel Engine with the Installer (Interactive Deployment) You can easily deployLabelGallery SDK to the client’s computer with the installer. You can run the installer in interactive mode (with the user interface), or in the silent automatic mode (without the user interface). To deployLabelGallery SDK interactively, do the following: 1. InsertLabel Gallery Development Series CD in the CD-ROM drive. 2. Click the optionInstall Developer Products. 3. Click the optionLabel Gallery SDK. The installation will start. 4. When you are asked to specify the setup type, make sure to select the optionDeployment. Using this option makes sure only the necessaryLabel Gallery Engine files are installed. 9 Installing LabelGallery SDK Figure2: Selecting Deployment type of theLabel Gallery SDK setup 5. ClickNext. 6. If you need support for label printing logging, make sure to enable the optionPrint Job Logging Supportwhen you are asked for the component selection. Note:When you select Print Job Logging Support, Label Gallery SDK will be configured to log all printing activities into the MS Access log database. For more information refer to the chapter ‘Setting upSupport for Logging(Optional)’. 7. Follow on-screen instructions to finish the installation. 8. To see where the files have been installed refer to the chapter‘LocationofLabelGallerySDK Files’. 2.2.1 Deploying Label Gallery Engine without the Installer (Automatic Deployment) You can alsoinstallLabel Gallery SDK automatically without any interaction with the installer. In this scenario you see no dialog boxes and the installation completes silently in the background. You can use this typeof installation to initiateLabel Gallery SDK deployment when the installation of your application has been completed. You must use the command-line switch /s for automatic installation. To deployLabel Gallery SDK automatically, do the following: 1. InsertLabel Gallery Development Series CD in the CD-ROM drive. 2. Do not use the menu in the auto-run application. 10