Windows Layout SDK
Programming Manual
for Version 1.3.0
Windows Layout SDK
Revision History
Date Version Description
2009.06.01 1.0.0.0 - First issue. (Layout Utilities Users Guide)
2009.11.19 1.0.1.0 - Changed to hide the printing dialog in Layout Print Engine.
2013.11.22 1.1.0.0 - Added support OS:
Windows 7, Windows 8, Windows 8.1, Windows Server 2008,
Windows Server 2008R2, Windows Server 2012
- Supports the creation of 64-bit user applications.
- Supports multi-threaded user applications for printing.
- Added support barcode:
MaxiCode, Data Matrix, GS1 Composite, GS1 Databar (RSS), iQR
- Support for dot-by-dot print of the image.
And, Changed the property name from [FixedAspect] to [SizeMode].
- Added speed up method for the first printing:
PreparePrint(), HidePreview()
2014.09.08 1.2.0.0 - No update of Windows Layout SDK
2016.08.16 1.3.0.0 - Added support OS: Windows 10
- Changed to .Net Framework 4.0 based.
- Change the designation from "Layout Print Engine" to "Layout SDK".
- Separated from users guide for Layout SDK programmer. (This document)
-2- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
Permission Notice
1. Unauthorized use of all or any part of this document is prohibited.
2. The information in this document is subject to change without prior notice.
3. This document has been created with full attention. If, however, you find an error or question,
Please contact us.
4. We shall not be liable for any effect resulting from operation regardless of the above item 3.
5. If you do not agree with the above terms, you are not permitted to use this library.
Copyright / Trademarks
The copyright for this Programming Manual belongs to Citizen Systems Japan Co., Ltd.
CITIZEN is a registered trademark of Citizen Watch Co., Ltd.
Windows and Windows Server are either registered trademarks or trademarks of Microsoft
Corporation in the United States and/or other countries.
Pentium is a trademark or registered trademark of Intel Corporation or its subsidiaries in the United
States and other countries.
QR Code and iQR Code are registered trademarks of DENSO WAVE INCORPORATED in Japan
and in other countries.
Android is a trademark of Google Inc.
Oracle and JavaScript are registered trademarks of Oracle and/or its affiliates.
All other company and/or brand/product names are trademarks and/or registered trademarks of their
respective owners.
-3- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
Table of Contents
Revision History.......................................................................................................................................... 2
Permission Notice....................................................................................................................................... 3
Copyright / Trademarks .............................................................................................................................. 3
Table of Contents........................................................................................................................................ 4
1. Introduction.......................................................................................................................................... 5
1.1. Who should read this document .................................................................................................. 5
1.2. System summary ......................................................................................................................... 5
1.3. Supported PC .............................................................................................................................. 6
1.4. Supported printer ......................................................................................................................... 6
1.5. Library files ................................................................................................................................... 7
1.6. Library References....................................................................................................................... 7
1.7. Functions list ................................................................................................................................ 8
2. Library interface .................................................................................................................................. 9
2.1. Constructor .................................................................................................................................. 9
2.2. Open .......................................................................................................................................... 10
2.3. Close .......................................................................................................................................... 11
2.4. BeginPrint .................................................................................................................................. 12
2.5. EndPrint ..................................................................................................................................... 13
2.6. DoPrint ....................................................................................................................................... 14
2.7. DoPreview .................................................................................................................................. 15
2.8. InitFrame .................................................................................................................................... 16
2.9. GetParts ..................................................................................................................................... 17
2.10. SetPartsData .......................................................................................................................... 18
2.11. AddFrame............................................................................................................................... 19
2.12. PreparePrint ........................................................................................................................... 20
2.13. HidePreview ........................................................................................................................... 21
3. Example of using the method ( C# ) ................................................................................................. 22
4. Notes ................................................................................................................................................. 23
4.1. About the detection of print completion ..................................................................................... 23
-4- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
1. Introduction
This document is a programming manual for the Windows Layout SDK.
1.1. Who should read this document
This document is intended for reference of Windows application developers that use the CITIZEN layout
file.
1.2. System summary
This library is referred by Windows application program to use CITIZEN layout file.
Windows application
Windows Layout SDK Layout file
CITIZEN Printer Driver
Printer Drawer
Windows (.NET Framework)
Wired/Wireless LAN, USB, LPT, COM, Bluetooth
System diagram of the library
-5- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
1.3. Supported PC
OS ・ Windows XP
・ Windows 7 (32bit, 64bit)
・ Windows 8 (32bit, 64bit)
・ Windows 8.1 (32bit, 64bit)
・ Windows 10 (32bit, 64bit)
・ Windows Server 2008
・ Windows Server 2008R2
・ Windows Server 2012
Required ・ .NET Framework 4.0
・ CITIZEN Printer Driver
1.4. Supported printer
Target printer of this library is supported by the CITIZEN printer driver.
Refer to user’s manual of each printer for more details.
-6- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
1.5. Library files
This library can be utilized by installing the Layout Utilities, is structured of the following files.
・ AxInterop.QRMAKERADLib.dll
・ Citizen.LayoutUtilities.Common.dll
・ Citizen.LayoutUtilities.Printing.dll
・ GrapeSystems.Core.Common.dll
・ GrapeSystems.Core.Drawing.Fx20.dll
・ GrapeSystems.Core.Parts.dll
・ GrapeSystems.Core.Parts.Frames.dll
・ GrapeSystems.Library.BarcodeAd.dll
・ GrapeSystems.Library.Controls.dll
・ GrapeSystems.Library.Image.dll
・ Interop.QRMAKERADLib.dll
1.6. Library References
How to add references in Visual Studio are as follows:
To add a reference in Visual C#
1. In Solution Explorer, right-click the project node and click Add Reference.
2. In the Add Reference dialog box, select the tab indicating the type of component you want to
reference.
3. Select the following file, and then click OK.
C:¥Program Files¥CITIZEN¥Layout Utilities¥Citizen.LayoutUtilities.Printing.dll
To add a reference in Visual Basic
1. In Solution Explorer, double-click the My Project node for the project.
2. In the Project Designer, click the References tab.
3. Click the Add button to open the Add Reference dialog box.
4. In the Add Reference dialog box, select the tab indicating the type of component you want to
reference.
5. Select the following file, and then click OK.
C:¥Program Files¥CITIZEN¥Layout Utilities¥Citizen.LayoutUtilities.Printing.dll
-7- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
1.7. Functions list
This library provides the following functions.
Methods list
No. Name Function
1 Controller This is constructor method.
2 Open Opens the CLF file with the specified path.
3 Close Closes the CLF file that is currently open.
4 BeginPrint Starts preparing for printing.
5 EndPrint Discards the printing data.
6 DoPrint Executes printing from the specified printer.
7 DoPreview Displays the print preview for the specified printer.
Searches for the frame to set up the printing data.
8 InitFrame It will search by the specified frame name and returns the internally controlled
frame number.
Searches for the parts to set up the printing data.
It will search for the parts subjected to setting by the frame number obtained
9 GetParts
by InitFrame() and the part name and returns the internally controlled part
number.
Sets up the printing data (text, barcode, image) for the part.
It will search for the part subjected to setting by the frame number obtained by
10 SetPartsData
InitFrame() and the part number obtained by GetParts() and sets the
specified character string.
11 AddFrame Registers a frame set up with printing data as a print subject.
12 PreparePrint
Prepares to speed up the first printing.
13 HidePreview
-8- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2. Library interface
2.1. Constructor
<Definition>
Citizen.LayoutUtilities.Printing.Controller ()
<Function>
It is the constructor for this library. Create an instance.
<Argument>
None.
<Returned value>
None.
<Example>
Citizen.LayoutUtilities.Printing.Controller clpe = new Citizen.LayoutUtilities.Printing.Controller();
-9- CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.2. Open
<Definition>
int Open ( string pathName )
<Function>
Opens the CLF file with the specified path.
<Argument>
pathName
Specifies the full path of the CLF file to be used as template.
<Returned value>
0 : Indicates that the CLF file was opened properly.
Other than 0 : Indicates that some kind of error has occurred, including failure to find the
CLF file.
<Example>
clpe.Open( "my_layout_File.CLF" );
- 10 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.3. Close
<Definition>
void Close ()
<Function>
Closes the CLF file that is currently open.
<Argument/returned value>
None.
<Example>
clpe.Close();
- 11 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.4. BeginPrint
<Definition>
void BeginPrint ()
<Function>
Starts preparing for printing.
<Argument/returned value>
None.
<Example>
clpe.BeginPrint();
- 12 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.5. EndPrint
<Definition>
void EndPrint ()
<Function>
Discards the printing data.
<Argument/returned value>
None.
<Example>
clpe.EndPrint();
- 13 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.6. DoPrint
<Definition>
int DoPrint ( string printerName )
<Function>
Executes printing from the specified printer.
<Argument>
printerName
Specifies the name of printer to print.
The default printer is used to print when blank is specified.
<Returned value>
0 : Indicates that the process was completed successfully.
Other than 0 : Indicates that some kind of error has occurred, including failure to find the
specified printer.
<Example>
clpe.DoPrint( "Printer Name" );
- 14 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.7. DoPreview
<Definition>
int DoPreview ( string printerName )
<Function>
Displays the print preview for the specified printer.
<Argument>
printerName
Specifies the name of the printer to execute print preview.
The print preview by the default printer will be displayed if blank is specified.
<Returned value>
0 : Indicates that the process was completed successfully.
Other than 0 : Indicates that some kind of error has occurred, including failure to find the
specified printer.
<Example>
clpe.DoPreview( "Printer Name" );
- 15 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.8. InitFrame
<Definition>
int InitFrame ( string frameName )
<Function>
Searches for the frame to set up the printing data.
It will search by the specified frame name and return the internally controlled frame number.
<Argument>
frameName
Specifies the name of frame to be subjected.
<Returned value>
0 or larger : Indicates the internally controlled frame number.
-1 : Indicates that some kind of error has occurred, including failure to find the
specified frame.
<Example>
int frameIndex = clpe.InitFrame( "Frame1" );
- 16 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.9. GetParts
<Definition>
int GetParts ( int frameIndex, string partsName )
<Function>
Searches for the parts to set up the printing data.
It will search for the parts subjected to setting by the frame number obtained by InitFrame() and the
part name and return the internally controlled part number.
<Argument>
frameIndex
Specifies the frame number to be subjected (obtained by initFrame()).
partsName
Specifies the name of the part to be subjected.
<Returned value>
0 or larger : Indicates the internally controlled part number.
-1 : Indicates that some kind of error has occurred, including failure to find the
specified part.
<Example>
int partsIndex = clpe.GetParts( frameIndex, "Text1" );
- 17 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.10. SetPartsData
<Definition>
int SetPartsData ( int frameIndex, int partsIndex, string setText )
<Function>
Sets up the printing data (text, barcode, image) for the part.
It will search for the part subjected to setting by the frame number obtained by InitFrame() and the
part number obtained by GetParts and sets the specified character string.
<Argument>
frameIndex
Specifies the frame number to be subjected (obtained by InitFrame()).
partsIndex
Specifies the part number to be subjected (obtained by GetParts).
setText
Specifies the printing data (text, barcode, image) to be set up.
<Returned value>
0 : Indicates that the process was completed successfully.
Other than 0 : Indicates that some kind of error has occurred, including setup failure.
<Example>
clpe.SetPartsData( frameIndex, partsIndex, "New Text" );
clpe.SetPartsData( frameIndex, partsIndex, "New Image File Path" );
- 18 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.11. AddFrame
<Definition>
int AddFrame ( int frameIndex )
<Function>
Registers a frame set up with printing data as a print subject.
<Argument>
frameIndex
Specifies the frame number to be subjected (obtained by InitFrame()).
<Returned value>
0 or larger : Indicates the internally controlled frame number from print registration.
-1 : Indicates that some kind of error has occurred, including registration failure.
<Example>
clpe.AddFrame( frameIndex );
- 19 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.12. PreparePrint
<Definition>
int PreparePrint ( string pathName )
<Function>
Prepares to speed up the first printing.
<Argument>
pathName
Specifies the full path of the CLF file to be used as template.
<Returned value>
0 : Indicates that the process was completed successfully.
Other than 0 : Indicates that some kind of error has occurred.
<Example>
clpe.PreparePrint( "my_layout_File.CLF" );
-Note-
This software is based on .NET Framework technology.
.NET Framework libraries are loaded automatically into memory at the start of printing without
users being aware.
The first printing becomes slow because it requires several seconds for the loading process.
Then the printing after that will be faster.
PreparePrint(), HidePreview() are the methods that improve the speed of the first printing.
Please run this method once before the first printing in your program.
Depending on the operating environment, improvement may not lasts long.
If the slower printing is observed after the first printing, please consider to run this method on a
regular basis.
- 20 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
2.13. HidePreview
<Definition>
int HidePreview ( string pathName )
<Function>
Prepares to speed up the first printing.
In HidePreview(), the first print will be speeded up from PreparePrint(). However, please take into
account that the processing time of HidePreview() is longer and the preview generation dialog is
displayed.
<Argument>
pathName
Specifies the full path of the CLF file to be used as template.
<Returned value>
0 : Indicates that the process was completed successfully.
Other than 0 : Indicates that some kind of error has occurred.
<Example>
clpe.HidePreview( "my_layout_File.CLF" );
-Note-
This software is based on .NET Framework technology.
.NET Framework libraries are loaded automatically into memory at the start of printing without
users being aware.
The first printing becomes slow because it requires several seconds for the loading process.
Then the printing after that will be faster.
PreparePrint(), HidePreview() are the methods that improve the speed of the first printing.
Please run this method once before the first printing in your program.
Depending on the operating environment, improvement may not lasts long.
If the slower printing is observed after the first printing, please consider to run this method on a
regular basis.
- 21 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
3. Example of using the method ( C# )
Citizen.LayoutUtilities.Printing.Controller clpe =
new Citizen.LayoutUtilities.Printing.Controller(); // Windows Layout SDK
int result = clpe.Open( "clf File Name" );
if (0 == result) {
clpe.BeginPrint();
int frameIndex = clpe.InitFrame( "Frame1" );
int partsIndex = clpe.GetParts( frameIndex, "Text1" );
clpe.SetPartsData( frameIndex, partsIndex, "New Text" );
clpe.AddFrame( frameIndex );
clpe.DoPrint( "Printer Name" );
clpe.EndPrint();
clpe.Close();
}
- Note -
Please refer to the Layout SDK sample program for more information.
http://www.citizen-systems.co.jp/english/support/download/printer/sdk/index.html
- 22 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
4. Notes
Notes of this library are as follows.
4.1. About the detection of print completion
The library will make the print using the Print Spooler service that provided by Windows. Therefore you
cannot detect the print completion. Please note.
- 23 - CITIZEN SYSTEMS JAPAN
Windows Layout SDK
Windows Layout SDK
Programming Manual
for Version 1.3.0
- 24 - CITIZEN SYSTEMS JAPAN
