This SDK helps developers to use printer PP55
within AppForge MobileVB 3.0+.

In order to use PP55 the following steps must be performed:
  1. Invoke Printer Applet on PDA and make sure you connected the right printer and whether it is available from the PDA. For more specific information check the associated PDA helps.
  2. Copy the file named 'afPrnSupp.DLL', from SDK subfolder 'Target\PROCESSOR', where PROCESSOR is ARM, MIPS or SH3 - appropriate for your PDA, to the folder named '\Windows' on PDA. If you want to copy the file to some other location, go to the function PCE_Init and type the full path and name where the 'afPrnSupp.DLL' was copied.
  3. Add from the menu 'Project/References' reference to AfUser.dll and AfCore.dll from '<installation-folder>\AppForge\Platforms\Win32\TargetImage' folder.
  4. Attach the file named 'Printer.BAS' as module to your AppForge PocketPC project.
  5. Put calls to the function PCE_Init in Frame_Load event and PCE_Deinit in Frame_Unload event.
  6. Change, if necessary, the connection string in PrinterSupport.BeginPrinter function. If your PDA will use a printer with different speeds and connection types, then the proper solution is to preced with a call to the function PrinterSupport.InvokePrinterSelection, which gives the ability to change selection of speed and/or orientation and/or paper size.
  7. Use the following sequence for printer usage:
    1. call BeginPrinter (preceded or not with a call to InvokePrinterSelection) and check return code. None of other functions will work, if the call to one of these functions is not successful.
    2. (optional step) call any function for printing Text, Graphic or Barcode, as well as some non-standard ReadMagstripe, ReadPrinterStatus, and/or others.
    3. call EndPrinter to release allocated system resources. This function MUST be invoked. Failing to call it will prohibit further printer usage (until PDA reset)!
  8. For advanced users - there is mode named "dynamic page" which allows to draw anything and in any order on printer's page. The following sequence can be used:
    1. call BeginPrinter and check return code.
    2. call BeginDynamic and check returned value. If call is not successful - go to the last step.
    3. call any dynamic drawing functions: Text, Graphic, Rectangle, Ellipse, Line or Pixel, as well as selection of pen and/or brush.
      • Keep in mind that any drawings will overwrite previous ones. Sometimes the transparency effect can be achieved using this scheme (for example: this allows to draw transparent text over graphic).
      • Other special thing: all drawings can 'continue' from the previous page. There is no restrictions about passed coordinates, so big output (that exceeds the one page height) can be drawn many times with precalculated top coordinates (according to the page height), as result, the continuous output will be shown at the printer.
    4. call EndDynamic with parameter set to True to continue with next step, or with set to False to repeat from step 2 for new page.
    5. call EndPrinter to release allocated system resources. This function MUST be invoked. Failing to call it will prohibit further printer usage (until PDA reset)!
  9. IMPORTANT: the PrinterSupport functions are not reentrant! To preclude such situation add the following guardian code in the begining of every printing function:
    Private Sub AFButtonPrintSomethingXXX_Click()
      If working Then Exit Sub
      working = True
      ...................
      If PrinterSupport.BeginPrinter Then ' check to ensure connection with printer
        Call PrinterSupport.PrintXXXX ' check returned value to ensure correct printing
        ...................
    and pairing with the following at the end of every printing function:
        Call PrinterSupport.EndPrinter ' NEVER forget to call
      Else
        Call MsgBox("Can not connect to the printer!", vbExclamation)
      End If
      working = False
      .................
    End Sub ' AFButtonPrintSomethingXXX_Click()
    where the 'working' is global variable of type boolean.
    It is good practice to check variable before exit program too:
      If Not working Then Unload FormXXX Else MsgBox ("LOL! Wait print finish first!")
Some of the differences with 'standard' printers are:

Due to the MobileVB limitations there is support for PP55 only for PocketPC/WinCE 3.0!
Do not change anything in the source code if you do not know exactly what you are doing!

Function Description
PCE_Init Need to call once at Frame_Load event. Fail to call it will not provide access to the printer.
PCE_Deinit Good practice to call in once at Frame_Unload event.
PrinterVersion Obtain 'afPrnSupp.DLL' module version. Informative only, access to the printer is not required.
InvokePrinterSelection
Shows the printer selection dialog. Use to select default printer and connection type. Call it once as "Printer Setup" procedure and all next calls to the function BeginPrinter with parameter set to 0 (zero) will use selected settings to connect with the printer.
New: Do not create a connection with printer, just sets default one! To connect with the printer use BeginPrinter.
Usage:
If Not InvokePrinterSelection Then MsgBox("Fail to setup default printer!"): Exit
BeginPrinter
Prepare usage of the printer. Invoke it before any other function calls from the module. Check returned value and NEVER forget to call appropriate EndPrinter.
Never forget to check whether values in source code correspond to the currently connected printer, especially the connection string (do not change others, if you do not know what you do)!
Note: the connection string MUST be the same with one, used in Printer Applet.
Examples: "IRDA", "COM1: 9600", "COM1: 57600" or "COM1: 115200".
New: If passed parameter is 0 (zero), then default selected printer is used (see InvokePrinterSelection).
Usage:
If Not BeginPrinter Then MsgBox("Fail to connect with printer!"): Exit
EndPrinter
Ends the printer connection and frees any system resources allocated via BeginPrinter call. Call it as soon as possible, keeping printer 'open' prevents access to it from other applications as well as prevents auto-off printer and other specific features.
Usage:
EndPrinter. Check of returned value is redundant.
PrintText
Enable print WYSIWYG text. The text is printed with the passed point size (not the pixel size!). If you want to change background and/or foreground colors, and/or horizontal alignment, and/or width of font, and/or font name, you must change the source code in the function. Foreground color CLR_INVALID defaults to BLACK (paper is presumed to be WHITE). Background color CLR_INVALID defaults to transparent mode. Horizontal align can be left (default), center or right and applies to the whole text. Width of the fonts can vary (see FW_ constants) but not all widths produce different output (this is a WinCE limitation). Font name defaults to 'Tahoma' and no other choices on many PDAs. The length of text if limited by OS and used controls (probably 32Kb is the length limit).
Note: the text will be followed by feed defined in Printer Applet.
Usage:
If Not PrintText (TextToPrint, 18) Then MsgBox("Fail to print text! Check the printer connection and paper."): Exit
PrintGraphic
Enable print of raster image of .BMP, .JPG, .GIF, .PNG and some other file formats. Load the graphic file and print it. If image dimensions are out of printer ones, use the stretch option. Available options are to stretch by: page width, or whole page (i.e. fit in two directions - always print image onto one page). If the image is smaller or bigger that the current page width (orientation of paper was assumed), picture is enlarged or shrunk. If the image still does not fit into the selected paper size, the rest is printed on next page(s). If the orientation is portrait and there are no margins (default), the print is continuous never mind how many pages are required.
Note: the graphic will be followed by feed defined in Printer Applet.
Usage:
If Not PrintGraphic (FileName, True) Then MsgBox("Fail to print graphic! Check the printer connection and paper."): Exit
PrintWindow
Enable to print the content of WinCE window handle, like graphic. There is special handle value zero (0), which will print the whole desktop. All limitations and features are the same as PrintGraphic.
Note: finding the right window handle is not a trivial task under AppForge and it is out of scope of this SDK.
Usage:PrintWindow (AFWidget1.Window.Frame.SystemWindow)
DefinePrinterLogo
Enable to download raster image file as printer's logo. All limitations and features are the same as PrintGraphic, plus additional limitations comes from the printer: the image can not exceed 384 pixels width (which is the fixed printer's width) and 248 pixels height. The image can be monochrome (black and white) or color, if it is color then, every pixel's color is convert to gray level (0-255), and the levels bellow 128 are treated as black, all others are threated as white. If the dimensions are out of the permited, the downloading is not performed.
Note: the process of converting color image can be very slow.
Command to print logo is GS / n, where n (0-3) defines printing mode. See WritePrinterDirect.
Usage:If Not DefinePrinterLogo(LogoFileName) Then MsgBox("Fail to define logo!"): Exit
ReadMagstripe
Read magnetic card (if the environment exist; check via function ReadPrinterCaps for the CAPS_MAGSTRIPE value). If you want to read three tracks at once, check for the CAPS_THREE_HEAD value, otherwise the command will be reject by the printer. Successful reading is indicated by returned values, if nothing is returned, the timeout has expired.
Usage:
If Not ReadMagstripe(True, Track1, True, Track2, False, "") Then MsgBox( "MCR timeout expire! Try again or reject.")
CheckPayCard
Read magnetic card (if the environment exist; check via function ReadPrinterCaps for the CAPS_MAGSTRIPE value). And after that try to recognize its data as payment card. If recognition is successful then number of card, card holder name (optional exist) and expire date as month/year pair will be returned. If nothing is returned, the timeout has expired.
Usage:
If Not CheckPayCard(Number, Name, Month, Year) Then MsgBox( "MCR timeout expire! Try again or reject.")
ReadPrinterStatus
Allows checking the printer about some conditions, see STATUS_ constants.
Use it to ensure that PP55 printer is properly connected.
Usage:
If Not ReadPrinterStatus(Status) Then MsgBox("Fail to read status from printer!"): Exit
ReadPrinterInfo
Allows checking the printer's battery voltage and head temperature. Voltages above 6.0V are functional for the printer, otherwise any attempt to print will turn off the printer. The temperature of the printing head is measured in Celsius (if the CAPS_FAHRENHEIT then in Fahrenheit) degree. The voltage value is multiplied by 10.
Can be used to ensure that the PP55 printer is properly connected.
Usage:
If Not ReadPrinterInfo(Temp, Volt) Then MsgBox("Fail to read info from printer!"): Exit
ReadPrinterCaps
Allows to check the printer about some equipment and features (see CAPS_ constants) and to retrieve the printer's internal name (including version number and language version). The name is composed from 27 character name (space padded) and three-digit number without dot (where the first digit is major firmware version, next two digits are minor version), followed by two-letter language code (EN stay for English, JP for Japan, and so on).
Use it to ensure that PP55 printer is properly connected.
Usage:
If Not ReadPrinterCaps(Caps, Name) Then MsgBox("Fail to read info from printer!"): Exit
PrintBarcode
Allow printing barcodes. Pass some of the BARCODE_ type, the feed after printed barcode and the barcode data itself. The barcode data must be proper, if it is not, or the barcode does not fit in printer width (48mm), it will not be printed without notification of that. If you want to change barcode width (see BARCODE_WIDTH_ constants), and/or barcode height, and/or duplicate text positions (see BARCODE_TEXTS_ constants) and/or font (see BARCODE_FONT_ constants), you need to change the source code or add additional parameter(s) to the function.
Usage:
If Not PrintBarcode (BARCODE_EAN13, 20, "123456789012") Then MsgBox("Fail to print barcode! Check printer connection and paper."): Exit
ActivatePassthrough
Activates passthrough mode for the printer. The printer will not recognize any command until turned off or deactivated passthrough mode. If you want to disconnect the printer, use ForceClosePrinter.
Usage:
ActivatePassthrough
ControlPassthrough
Activates or deactivates passthrough mode. Use one of the constant PRINTER_DEACTIVATE, to enter in the passthrough mode, or PRINTER_ACTIVATE, to return to the normal mode.
Usage:
....
ActivatePassthrough() - no command will accept by printer and RS line can be used by other(s)
....
If ControlPassthrough (PRINTER_ACTIVATE) Then ...
commands are accepted again...
ForceClosePrinter
Use to disconnect printer placed in passthrough mode. Not necessary to call EndPrinter after that call. Using it in other conditions can discard some printing.
Usage:
ForceClosePrinter. Check of returned value is redundant.
WritePrinterDirect
Writes data directly to the printer. You must know the printer commands, or the data will be treated as text and will be printed with the printer's internal font.
It is a low level function, so it is not recommended for use.
Usage:
Dim dWrite As WritePrinterDirectTag
dWrite.Size = 3
ReDim dWrite.Data(dWrite.Size)
dWrite.Data(0) = 27 ' ESC
dWrite.Data(1) = 74 ' "J"
dWrite.Data(2) = 100 ' 100/203 "
WritePrinterDirect(dWrite) will feed printer by 100/203 of inch.
ReadPrinterDirect
Reads data from the printer. You must know what exactly will come from the printer or the module will sleep until timeout expires.
It is a low level function, so it is not recommended for use.
Usage:
....
Dim dWrite As WritePrinterDirectTag
dWrite.Size = 2
ReDim dWrite.Data(dWrite.Size)
dWrite.Data(0) = 27 ' ESC
dWrite.Data(1) = 118 ' "v"
If Not WritePrinterDirect(dWrite) Then Exit ' send check status command
Dim dRead As ReadPrinterDirectTag
dRead.Size = 1
ReDim dRead.Data(dRead.Size)
If Not ReadPrinterDirect(dRead) Or dRead.Size <> 1 Then Exit
....dRead.Data(0) will contain one byte status from printer.
BeginDynamic
Allows composing the user drawable page. The page dimensions in pixels are returned when successful call occurs. Check returned value and do not forget to call appropriate EndDynamic.
None of the dynamic drawing functions for Text, Graphic, Rectangle, Ellipse, Line or Pixel, as well as selection of pen and/or brush will work if there is no successful call to this function.
Usage:
If Not BeginPrinter Then Exit
If Not BeginDynamic (width, height) Then EndPrinter: Exit
... ' draw with 'dynamic' functions within width and height ranges
EndDynamic (true) ' the last page
EndPrinter ' never forgot to call it
EndDynamic
Ends the user drawable page. If parameter is False - the printer is capable to continue with dynamic drawings (another call to BeginDynamic). If parameter is True - this is the last dynamic page. Fail to call this function (still require call to EndPrinter!) will discard last dynamic page.
Note: the last page will be followed by feed defined in Printer Applet.
Usage:
.... ' dynamic begin and some draws
EndDynamic (true) ' the last page
EndPrinter ' never forgot to call it
DynamicText
Draws the text to the dynamic page, like usual PrintText but output is clipped to the given rectangle (the part of rectangle can be outside of the page). The output still be clipped within printer's page.
Usage: DynamicText (printText, 17, clipbox)
DynamicGraphic
Draws the raster image to the dynamic page, like usual PrintGraphic but output is fitted to the given rectangle (the part of rectangle can be outside of the page). The output still be clipped within printer's page.
Usage: DynamicGraphic (FileName, clipbox)
DynamicWindow
Draws the content of WinCE window handle, like graphic PrintWindow but output is fitted to the given rectangle (the part of rectangle can be outside of the page). The output still be clipped within printer's page.
Usage: DynamicWindow (AFWidget1.Window.Frame.SystemWindow, clipbox)
DynamicPen
Sets the pen for dynamic drawing operations: DynamicRectangle, DynamicEllipse and DinamicLine. The special color value of CLR_INVALID will define null pen i.e. not a pen selection. The default pen is black. The width is given in pixels, where 0 width gives the smallest possible width.
Usage: DynamicPen (2, CLR_DARKGRAY)
DynamicBrush
Sets the fill brush for dynamic drawing operations:DynamicRectangle and DynamicEllipse. The special color value of CLR_INVALID will define null brush i.e. not a brush selection. The default brush is null (empty).
Usage: DynamicBrush (CLR_INVLAID) ' empty brush
DynamicRectangle
Draws a rectangle with defined DynamicPen and DynamicBrush. If both pen and brush are nulls there will be no output.The part of rectangle can be outside of the page. The output still be clipped within printer's page.
Usage: DynamicRectangle (box)
DynamicEllipse
Draws an ellipse (or circle) with defined DynamicPen and DynamicBrush. If both pen and brush are nulls there will be no output.The part of rectangle can be outside of the page. The output still be clipped within printer's page.
Usage: DrawEllipse (box)
DynamicLine
Draws the line between given two points using defined DynamicPen. If pen is null there will be no output. The points can be outside of the page.
Usage: DrawLine (from, to)
DynamicPixel
Draws the pixel at specified position and specified color.
Usage: ' keep in mind that the current pen and brush are not used
DrawPixel (pos, CLR_BLACK)

If you have any problems or suggestions write to PocketPC support or visit our PocketPC PDA site.


© 2003-2004 Datecs Ltd.