|
-----------------------------
.NetCF: C#-VB.Net
Documentation eVC
(C/C++/MFC), eVB: ----------------------------- Software Developers Special Topics
Printing Utilities |
PrinterCE.NetCF
Developer's Guide
|
| PrinterCE for .NetCF: The primary class for printing text, images, drawing objects (lines, rectangles, etc) and much more. | |
| AsciiCE for .NetCF: A separate class that allows for printing pure ASCII text to any ASCII printer. | |
| BarcodeCE for .NetCF: An optional class derived from PrinterCE that adds over a dozen barcode types to PrinterCE. |
Simple C# code for using the PrinterCE class to print out "Hello World":
PrinterCE prce =
null;
Create an instance of PrinterCE using one of the following 4 overloaded versions:
Syntax: (4 overloaded versions):
public
PrinterCE();
public PrinterCE(string
initstr);
public PrinterCE(EXCEPTION_LEVEL
exclevel);
public PrinterCE(EXCEPTION_LEVEL exclevel,string
initstr);
initstr-
Developer's License Key used to unlock PrinterCE. Default is for
PrinterCE to
run in evaluation mode. After evaluation time limit has expired on a
device, PrinterCE will be locked and will not function.
exclevel -
Sets level of errors that will cause an
exception, using EXCEPTION_LEVEL enumeration:
|
EXCEPTION_LEVEL Enumeration |
Description |
|
NONE |
PrinterCE will not throw an exception - use StatusCheck to determine if an error has occurred. |
|
ABORT_JOB |
PrinterCE throws an exception if the print job is aborted, either by serious error or user cancel. Certain error conditions that affect only the a specific function will not throw an exception. For example, if DrawPicture is called with an image file that cannot be found or is not a valid image file type. |
|
ALL |
PrinterCE throws an exception for any error found. |
Example:
PrinterCE
prce1 = new
PrinterCE(PrinterCE.EXCEPTION_LEVEL.ABORT_JOB,"YOURLICENSEKEY");
//No
License Key for evaluation
With exception handling disabled, when an error occurs within
For example, if a printer error occurs, the entire
printing job must be aborted, so all calls to
READ-ONLY property returns string describing this version of PrinterCE
Syntax: string
aboutstr=PrinterCE1.About
String describing this version of PrinterCE - including information on WinCE platform, processor type and version. This string can be used in a MessageBox to display the information - MessageBox.Show(PrinterCE1.About,"PrinterCE Version");
MessageBox.Show(PrinterCE1.About,"PrinterCE Version");
This method converts a value from one ScaleMode system to
another.
Syntax:
double
ConvertCoord(double val, MEASUREMENT_UNITS
fromscalemode,
MEASUREMENT_UNITS
toscalemode);
|
MEASUREMENT_UNITS Enumeration |
Description |
|
TWIPS |
1440 Twips per inch |
|
POINTS |
72 points per inch |
|
PIXELS |
Printer resolution - for example 300 dpi |
|
INCHES |
Inches |
|
MILLIMETERS |
Millimeters |
|
CENTIMETERS |
Centimeters |
fromval - Value to be converted
fromscale - "convert from" MEASUREMENT_UNITS
toscale - "convert to" MEASUREMENT_UNITS.
toval - Converted value.
To convert 1.25 inches into printer resolution:
double PrResVal=PrinterCE1.ConvertCoord(1.25,PrinterCE.MEASUREMENT_UNITS.INCHES,
Prints a circle or ellipse on a page.
Syntax: (4 overloaded versions):
void DrawCircle(double x,double
y,double radius);
void DrawCircle(double x,double
y,double radius,Color pen color);
void DrawCircle(double x,double
y,double radius,double
aspect);
x - Horizontal coordinate for the center point of a circle.
y - Vertical coordinate for the center point of a circle.
radius - Radius of a circle.
color – color of a circle's outline. Default is ForeColor value
aspect – aspect ratio of a circle. The default value is 1.0,
which yields a perfect circle. Other values draw an ellipse. (Also see
DrawEllipse for another way to draw ellipses).
The ScaleMode property of object determines the units of
measure used.
The FillColor and FillStyle properties of object determine
how a circle is filled.
The DrawWidth property determines the width of the line used to draw a
circle.
Prints an ellipse on a page.
Syntax (2 overloaded versions):
void DrawEllipse(double
x1,double y1,double
x2,double y2);
void DrawEllipse(double
x1,double y1,double
x2,double y2,Color pencolor);
x1, y1, x2, y2 - Values define a rectangle (x1,y1)
as one corner and (x2,y2) as
opposing corner. An ellipse is drawn that
just fits within this bounding rectangle.
color – color of a circle's outline. Default is ForeColor value
The ScaleMode property of object determines the units of
measure used.
The FillColor and FillStyle properties of object determine
how a circle is filled.
The DrawWidth property determines the width of the line used to draw a
circle.
Prints a line.
Syntax (2
overloaded versions):
void DrawLine(double
x1,double y1,double
x2,double y2);
void
DrawLine(double x1,double
y1,double x2,double
y2,Color pencolor);
Parameters
x1, y1 - starting coordinates for a line or rectangle
x2, y2 - ending coordinates for a line or rectangle.
color – Color used to draw a line. Default is ForeColor value.
The DrawWidth property determines the width of the line.
The
ScaleMode property determines the unit of measure used.
Prints a BMP,
JPG, GIF or PNG image file on the page.
Syntax
(2
overloaded versions):
void
DrawPicture(string picture, double
x, double y);
void DrawPicture(string picture, double
x, double y,
double width, double
height,bool keepaspect);
Parameters
picture
: Path & filename of the image to be drawn.
x,y : Coordinates where picture will be drawn (in ScaleMode units). By
default, x,y is the top/left corner of the image location. Use
JustifyHoriz/JustifyVert to change this to Center or Bottom/Right.
width : Destination width of picture. Default (or if width==0): actual image width
height : Destination height of picture. Default (or if height==0): actual image height is used.
keepaspect :
If width and/or height are negative values, DrawPicture
creates a mirror image along the vertical axis (if width is negative)
and/or the horizontal axis (if height is negative).
Print a point on the page.
Syntax
(2
overloaded versions):
void
DrawPoint(double x,double
y);
void DrawPoint(double x,double
y,Color pencolor);
Parameters
x, y - Coordinates of the point to draw (in ScaleMode units)
color - Color used to draw the point. Default is ForeColor value.
DrawWidth property determines the size of
the point.
Prints a rectangle on a page.
Syntax
(2
overloaded versions):
void
DrawRect(double x1,double
y1,double x2,double
y2);
void DrawRect(double
x1,double y1,double
x2,double y2,Color pencolor);
x1, y1, x2, y2 - defines a rectangle with (x1,y1) as one
corner and (x2,y2) as opposing corner
color - Color used to draw the rectangle. Default is ForeColor value.
Coordinates
are in ScaleMode units.
FillColor and FillStyle properties of object
determine how a rectangle is filled.
DrawWidth property determines the
width of the line used to draw a rectangle.
Prints a rectangle with rounded corners on a page.
Syntax
(2
overloaded versions):
void
DrawRoundedRect(double x1,double
y1,double x2,double
y2,
double corner_width,double
corner_height);
void DrawRoundedRect(double
x1,double y1,double
x2,double y2,
double corner_width,double
corner_height,Color pencolor);
x1, y1, x2, y2 - Defines a rectangle with (x1,y1) as one
corner and (x2,y2) as opposing corner.
cornerwidth,cornerheight - defines the width and height of the curve of
the rounded rectangle..
color - Color used to draw the rectangle. Default is ForeColor value.
Coordinates
are in ScaleMode units.
FillColor and FillStyle properties of object
determine how a rectangle is filled.
DrawWidth property determines the
width of the line used to draw a rectangle.
Prints text on the page. (See also DrawTextFlow).
Syntax
(4
overloaded versions):
void
DrawText(string drawstr);
string - Text to be drawn.
x, y - Coordinates of the text to be drawn. Default: string is drawn at the intrinsic (TextX,TextY) coordinates.
ccnt- Number of characters in "string" that should
be printed Default: entire line of text is printed.
The font properties of the PrinterCE control determines the
appearance of the text.
The ForeColor property determines the color of the
text.
After the text is drawn, TextX, TextY are updated so that the next
DrawText command will print on a new line.
The JustifyHoriz, JustifyVert,
and Rotation properties all impact how and where the text is actually
drawn on the page.
Coordinates are in ScaleMode units
Flows printed text on the page, optionally handling word wrap and page breaks automatically. For sample code visit here.
Syntax
(4
overloaded versions):
int
DrawTextFlow(string drawstr);
drawstr - Text to be drawn.
x, y - Coordinates of the position within
the "drawing box" for the top left corner of the start of the text.
Defaults to x, y coordinates of
most recent DrawText/DrawTextFlow call. Pass -1 to use default values
left, top, width, height - Defines a "drawing box" within
which the text will be flowed on the page.
Defaults to left and top
margins with full page width and height. Pass -1 to use default values.
ccnt - Number of characters in text string to print.
Defaults to all text string. Pass -1 to use default.
flowtype -
Bit flags to enable/disable Draw Flow options (OR these together)
| FLOW_OPTIONS Enumeration | Description |
|
DEFAULT |
Default "flow" working mode: auto word-wrap, auto page break (form feed) |
|
NOWORDWRAP |
Prints one line of text, determining where to break the text string. Returns number of characters printed. |
|
NOFORMFEED |
Prints text, flowing in "drawing box" as appropriate. If reaches the bottom of the "drawing box", stops printing and returns total number of characters printed. |
|
NOENDINGLINEFEED |
Normal operation after flowing text into the "drawing box" is to move to the start of the next line (CR/LF). Using NOENDINGLINEFEED causes (x, y) coordinates to be left immediately after the end of the last character printed. |
|
HARDBREAK |
Normal operation is for DrawTextFlow to try to "break" a line of text in a natural flow, such as at a space. Use HARDBREAK to fit all text possible onto each line, with break made after the last character that will fit. |
Returns number of characters printed during DrawTextFlow operation.
- JustifyHoriz
and Rotation properties are ignored - DrawTextFlow always draws
LEFT justified in NORTH rotation.
- JustifyVert is used to determine vertical justification.
- The ForeColor property determines the color of the
text.
- Coordinates are in ScaleMode units
Property: Returns / sets the line width in ScaleMode uints for output from
a graphics method.
Syntax:
get: double wid = PrinterCE1.DrawWidth;
set: PrinterCE1.DrawWidth = (double) wid;
Begin printing the current page, then reset
printing properties to default.
Syntax: void EndDoc();
Property: Returns / sets the color used to fill in
graphics methods: DrawRect, DrawRoundedRect, DrawCircle and DrawEllipse.
Examples:
get: Color wid = PrinterCE1.FillColor;
set: PrinterCE1.FillColor = Color.Blue;
When the FillStyle property is set to Transparent (default), the FillColor setting is ignored.
Property: Returns / sets the pattern used to fill in
graphics methods: DrawRect, DrawRoundedRect, DrawCircle and DrawEllipse.
|
FILL_STYLE Enumaration |
Description |
|
SOLID |
Solid |
|
TRANSPARENT |
Transparent |
Examples:
get: PrinterCE.FILL_STYLE style = PrinterCE1.FillStyle;
set: PrinterCE1.FillStyle= PrinterCE.FILL_STYLE.SOLID;
When the FillStyle property is set Transparent, the FillColor
setting is ignored.
Property: Returns / sets the Bold font style to true (Bold ON) or false (Bold OFF);
Examples:
get: bool isbold = PrinterCE1.FontBold;
set: PrinterCE1.FontBold=true;
Property: Returns / sets the current font's Bold weight.
Examples:
get: int boldweight = PrinterCE1.FontBoldVal;
set: PrinterCE1.FontBoldVal=850;
value - Integer value between 0 and 1000 to set the weight of
the font. Normal weight setting is 400 and standard Bold is 700.
Property: Returns / sets the Italic font style to true (Italic ON) or false (Italic OFF);
Examples:
get: bool isitalic = PrinterCE1.FontItalic;
set: PrinterCE1.FontItalic=true;
Property: Returns / sets the font used to print text.
Examples:
get: string fontname = PrinterCE1.FontName;
set: PrinterCE1.FontName="Courier New";
Any TrueType font can be used. To install a TrueType font to the device, simply copy from desktop PC to \Windows\Fonts folder on the device. You can use Pocket Word -> Edit -> Format -> pull down list of available fonts to see exact font names of all installed fonts.
Property: Returns / sets the point size of the font to be used for printing.
Examples:
get: int fontsize = PrinterCE1.FontSize;
set: PrinterCE1.FontSize=14; //Set font size to 14 point
Note: to match a point size with equivalent point size of Microsoft Word, use negative point size... for example, to match Word's 12 point font, use PrinterCE1.FontSize = -12.
Max is 2,160 points, min is 4 points.
Property: Returns / sets the Strikethrough style, true = Strikethrough ON, false OFF
Examples:
get: bool isstrikethru = PrinterCE1.FontStrikethru;
set: PrinterCE1.FontStrikethru=true;
Property: Returns / sets the Underline font style.
Examples:
get: bool isunderline = PrinterCE1.FontUnderline;
set: PrinterCE1.FontUnderline=true;
Property: Returns / sets the foreground color used to
print text.
Examples:
get: Color forecolor = PrinterCE1.ForeColor;
set: PrinterCE1.ForeColor=Color.Red;
ERROR GetLastErr
-
|
ERROR Enumeration |
Description |
|
NONE |
No current error |
|
|
Unable to complete printing task. |
|
|
Print operation cancelled by user |
|
|
Not enough memory to complete the task |
|
|
Invalid argument to PrinterCE.NetCF call |
|
|
Unknown error |
|
|
Print Dialog error |
|
|
Couldn't create font. |
|
|
Unable to load image. |
|
|
Check printer settings (page size, margins, etc) |
|
INFRARED |
Unable to establish Infrared link |
|
|
Unable to establish link to printer |
|
|
Lost communications link to printer |
|
|
Dialog error... cannot continue |
|
|
Unable to print across the network. |
|
|
Network support functions for network printing not found on this device. |
|
|
Unable to connect to computer or find network printers. Check computer name and network connection. |
|
|
Network unavailable or this device does not support network printing. |
|
|
Unable to connect with Bluetooth printer... Use Bluetooth Manager to discover your printer and connect it to Serial Port. Verify that Bluetooth Radio is ON. |
Example:
PrinterCE.ERROR
errtype = PrinterCE1.GetLastErr;
if (errtype == PrinterCE.ERROR.USERCANCELLED) {
//Handle user cancel situation
}
This method returns width and height of an image in an image file in ScaleMode units.
Parameters
picture
: Path & filename of the image to be drawn.
width: Actual width of image
height: Actual height of image
Returns: true if valid picture found.
READ-ONLY Property - Returns the height of the current font in ScaleMode units
Syntax: double ht = PrinterCE1.GetStringHeight;
Returns the width of the given text
string (in ScaleMode units)
Syntax: double wid = PrinterCE1.GetStringWidth("TextString");
Returns version of PrinterCE.NetCF - forms major.minor.build.revision
Syntax:
READ-ONLY property returns TRUE if current selected printer can print color.
Syntax: bool usescolor = PrinterCE1.IsColor;
Property: Returns / sets the horizontal justification (left, center, right) of following DrawText and DrawImage methods.
|
JUSTIFY_HORIZ Enumeration |
|
LEFT (Default) |
|
CENTER |
|
RIGHT |
Examples:
get: PrinterCE.JUSTIFY_HORIZ hjust = PrinterCE1.JustifyHoriz;
set: PrinterCE1.JustifyHoriz=PrinterCE.JUSTIFY_HORIZ.CENTER;
Property: Returns / sets the vertical justification (top, center, bottom) of following DrawText and DrawImage methods.
|
JUSTIFY_VERT Enumeration |
|
TOP (Default) |
|
CENTER |
|
BOTTOM |
Examples:
get: PrinterCE.JUSTIFY_VERT vjust = PrinterCE1.JustifyVert;
set: PrinterCE1.JustifyVert=PrinterCE.JUSTIFY_VERT.BOTTOM;
Abort
the current page - Flush all print operations and reset
printing properties to default.
Syntax: void KillDoc();
Begin printing the current page then prepare for another page of printing commands. Do not reset printing properties to default.
Syntax: void NewPage();
Property: Returns / sets an indent from the left margin
of the page where the start of the horizontal printing is found.
Examples:
get: int curleftindent = PrinterCE1.PgIndentLeft;
set: PrinterCE1.PgIndentLeft=300; //Set left indent 300 dots from margin
The PgIndentLeft and PgIndentTop settings can be called
multiple times while printing one page. All subsequent drawing methods use
the new settings. Use this technique to
easily print multiple columns and/or rows of items.
Property: Returns / sets an indent from the top margin
of the page where the start of the vertical printing is found.
Examples:
get: int curtopindent = PrinterCE1.PgIndentTop;
set: PrinterCE1.PgIndentTop=300; //Set top indent 300 dots from margin
The PgIndentLeft and PgIndentTop settings can be called multiple times while printing one page. All subsequent drawing methods use the new settings.
Property: Returns / sets the bottom margin
of the page.
Examples:
get: double curBottomMgn
= PrinterCE1.PrBottomMargin;
set: PrinterCE1.PrBottomMargin = (double)
0.75;
Property: Returns / sets the action of the "Printing in
progress" dialog box (which allows the user to cancel the print
operation).
|
DIALOGBOX_ACTION Enumeration |
Description |
|
UP |
Display "in progress" dialog box |
|
DOWN |
Take down dialog box |
|
DISABLE |
Prevent dialog box from being used |
|
STATUS |
Display status of printing operation |
|
DEBUG_ON |
Uses "in progress" dialog box to show details
about internal mode of PrinterCE during printing. (Off by default). |
|
DEBUG_OFF |
Turns off Debug mode. |
Examples:
get: PrinterCE.DIALOGBOX_ACTION dbox
= PrinterCE1.PrDialogBox;
set: PrinterCE1.PrDialogBox = PrinterCE.DIALOGBOX_ACTION.UP;
By default, the "Printing in progress" dialog box
is displayed with the first call by VB to a PrinterCE page operation
(such as Select Printer, Draw Object, etc). This dialog box will remain
until EndDoc or KillDoc completes the printing job. Calling
PrDialogBox(vbDlgDisable) will prevent PrinterCE from displaying
the dialog box (and will not give the user any chance to cancel).
See PrDialogBoxText() to change the text displayed
or language used by this dialog.
This method allows changing the text displayed or language
used by the "Printing in progress" dialog box.
Syntax:
void PrDialogBoxText(string
MainText,string TitleText,
string
CancelBtnText);
MainStr - String for main text portion of the "Printing
in progress" dialog box.
TitleStr - String for title portion of the "Printing in
progress" dialog box.
CancelBtnStr - String for Cancel Button portion of the "Printing in
progress" dialog box
The text of this dialog box may be changed at any time… if
the dialog box is already displayed, it will be taken down, the new text
added, and then the dialog box will be redisplayed. If the dialog box is
not currently displayed, it will remain down until a call to PrDialogBox()
or until PrinterCE automatically displays it.
READ-ONLY property returns "dots per inch" resolution of currently selected printer
Syntax: int prRes = PrinterCE1.PrinterResolution;
Property: Returns / sets the left margin
of the page.
Examples:
get: double curLeftMgn
= PrinterCE1.PrLeftMargin;
set: PrinterCE1.PrLeftMargin = (double)
0.75;
Property: Returns / sets the right margin
of the page.
Examples:
get: double curRightMgn
= PrinterCE1.PrRightMargin;
set: PrinterCE1.PrRightMargin = (double)
0.75;
This method causes the printer control to reset all
printer-specific values to the printer defaults.
Syntax: void PrinterCE1.PrSetDefaults();
Property: Returns / sets the top margin
of the page.
Examples:
get: double curTopMgn
= PrinterCE1.PrTopMargin;
set: PrinterCE1.PrTopMargin = (double)
0.75;
This property returns and sets the orientation of the printed page using the ORIENTATION enumeration.
|
ORIENTATION Enumeration |
Description |
|
PORTRAIT |
Normal page orientation |
|
LANDSCAPE |
Page rotated landscape |
Example: PrinterCE1.PrOrientation=PrinterCE.ORIENTATION.LANDSCAPE;
Property: Returns / sets the paper selection for the printed page using PAPER_SELECTION enum: