scViewerX User's Guide

scViewerX User's Guide

User's Guide
scViewerX Version 2

Introduction

Welcome to scViewerX
scViewerX is a powerful ActiveX control that allows you to view HPGL/2 files inside Your own application,or on a WEB page.You can implement scViewerX in any development environment that can use ActiveX controls, eg: Visual Basic, MSVC, Delphi.
Below you will find a description of each method,property and event in this control.

Methods

AddCompareDocument
CheckFile
CloseCompareDocument
CloseFile
CopyToClipBoard
EnumeratePen
Export
ExportExtents
GetFileExtent
GetNumPages
GetNumPens
GetPaperSize
GetPenState
GetPenTableEntry
GetResolution
GetRotatedFileExtent
GetVersion
LoadFile
LoadFromString
LoadPenTable
Print
PrintDisplay
PrintPoster
ScreenToWorld
SelectPrinter
SetLicenseOwner
SetPanPosition
SetPenState
SetPenTableEntry
SetSerialNumber
SetUserCursor
SetViewRect
SetZoomType
SetZoomWindowColors
WorldToScreen

Properties

AdjustColorFlag
AntiAliaseRaster
ArcResolution
BackColor
BorderStyle
CenterImage
CurrentPage
EnableAboutBox
EnableContextMenu
EnableContextMenuPrint
ExportAlignmentH
ExportAlignmentV
Flip
ForeColor
Grayscale
HaveRaster
LoadEmbeddedRaster
Mirror
Monochrome
PrintCenterOnPaper
PrintFitToPaper
PrintScale
Rotation
ScalePenTable
ShowScrollBars
TransparentRaster
TrueSize
UseDefaultPrinter
UseFilePaperSize
UsePenTable
WorkspaceColor
ZoomFactor

Events

Progress
MouseDown
MouseMove
MouseUp

Context Menu

Context Menu

Methods

NB! All coordinates are in drawing units (world coordinates).

CheckFile
Check if the given file can be loaded by the control.

Syntax	BOOL CheckFile(BSTR pFileName);
Parameters	pFileName	Name of file to check.
Returns	BOOL	TRUE if file can be loaded.

AddCompareDocument
Add a file that will be compared to the currently loaded file.

Syntax	BOOL AddCompareDocument(BSTR pFileName);
Parameters	pFileName	Name of file to compare to the currently loaded file.
Returns	BOOL	TRUE if file can be loaded.

CloseCompareDocument
Close the compare file and return to normal view mode

Syntax	BOOL CloseCompareDocument();
Parameters	none
Returns	BOOL	TRUE if success.

CloseFile
Close the currently loaded file.

Syntax	BOOL CloseFile();
Parameters	none
Returns	BOOL	TRUE if success.

CopyToClipBoard
Copy the given region to clipboard. If all four coordinates is set to zero, the whole drawing will be copied to the clipboard.

Syntax	BOOL CopyToClipBoard(long x1, long y1, long x2, long y2);
Parameters	x1	Upper left corner of part to copy.
	y1	Upper left corner of part to copy.
	x2	Lower right corner of part to copy.
	y2	Lower right corner of part to copy.
Returns	BOOL	TRUE if success.

EnumeratePen
Returns the real pen number for the given pen index.

Syntax	long EnumeratePen(long lIndex);
Parameters	lIndex	Pen index (0..GetNumPens())
Returns	long	Real pen number.

Export
Export the current loaded file to the given format.

Syntax	BOOL Export(BSTR bstrFileName, BSTR bstrFormat, double dScale, long lBitsPixel, long lDPI);
Parameters	bstrFileName	Name of created file.
	bstrFormat	Format to use. The following formats are supported: BMP (Windows Bitmap) CALS (CALS Type 1 CCITT-G4 Raster Format) CGM (Computer Graphics Metafile) DWF (Drawing Web Format) EMF (Windows Enhanced Metafile) GBR (Gerber RS274X) HPRTL (HP-RTL) JPEG (JFIF Compliant) PCX (Paintbrush Format) PDF (Acrobat PDF) PDFRASTER (Acrobat PDF raster). PNG (Portable Network Graphics) PS (Adobe Postscript) TIFF (Tagged Image File Format) WMF (Windows Metafile)
	dScale	Scalefactor.
	lBitsPixel	Bits Per Pixel (Raster only).
	lDPI	Pixels per Inch (Raster only).
Returns	BOOL	TRUE if file created.

ExportExtents
Does the same as the Export method, but have two extra parameters to control the extent of the exported file. The two properties named ExportAlignmentH and ExportAlignmentV controls the placement of the drawing, if it's smaller than the exported page size.

Syntax	BOOL ExportExtents(BSTR bstrFileName, BSTR bstrFormat, double dWidth, double dHeight, double dScale, long lBitsPixel, long lDPI);
Parameters	bstrFileName	Name of created file.
	bstrFormat	Format to use. The following formats are supported: BMP (Windows Bitmap) CALS (CALS Type 1 CCITT-G4 Raster Format) CGM (Computer Graphics Metafile) DWF (Drawing Web Format) EMF (Windows Enhanced Metafile) GBR (Gerber RS274X) HPRTL (HP-RTL) JPEG (JFIF Compliant) PCX (Paintbrush Format) PDF (Acrobat PDF) PDFRASTER (Acrobat PDF raster). PNG (Portable Network Graphics) PS (Adobe Postscript) TIFF (Tagged Image File Format) WMF (Windows Metafile)
	dWidth	Width of exported file in millimetres.
	dHeight	Height of exported file in millimetres.
	dScale	Scalefactor.
	lBitsPixel	Bits Per Pixel (Raster only).
	lDPI	Pixels per Inch (Raster only).
Returns	BOOL	TRUE if file created.

GetFileExtent
Returns the extents of the currently loaded file.

Syntax	BOOL GetFileExtent(long pWidth, long pHeight);
Parameters	pWidth	Returned Width
	pHeight	Returned Height
Returns	BOOL	TRUE if success.

GetNumPages
Returns the number of pages in the currently loaded file.

Syntax	long GetNumPages();
Parameters	None
Returns	long	Number of pages in loaded HPGL file.

GetNumPens
Returns the number of pens used for current viewed page. Use EnumeratePen to get real pen numbers.

Syntax	long GetNumPens();
Parameters	None
Returns	long	Number of pens used.

GetPaperSize
Returns the papersize as defined in the HPGL file. The width and height will be set to 0 if the size is not defined in the file.

Syntax	long GetPaperSize(double pdW, double pdH);
Parameters	pdW	Returned paper width
Parameters	pdH	Returned paper height
Returns	long	TRUE if success.

GetPenState
Returns state of the given pen.

Syntax	BOOL GetPenState(long lPen, long plState);*
Parameters	lPen	Pen number.
	plState	Returned pen status (0:Off/1:On).
Returns	long	TRUE if success.

GetPenTableEntry
Get width, color and style for the given pen table entry.

Syntax	BOOL GetPenTableEntry(long lPen, double pdWidth, long pcrColor, long plStyle);*
Parameters	lPen	Pen number.
	pdWidth	Returned pen width.
	pcrColor	Returned pen color.
	plStyle	Returned pen style (Windows GDI styles).
Returns	BOOL	TRUE if success.

GetResolution
Returns the resolution of the loaded file in DPI (dots per inch).

Syntax	long GetResolution();
Parameters	None
Returns	BOOL	Dots Per Inch. Zero means unknown.

GetRotatedFileExtent
Returns the extents of the currently loaded file if rotation is used.

Syntax	BOOL GetRotatedFileExtent(long pWidth, long pHeight);
Parameters	pWidth	Returned Width
	pHeight	Returned Height
Returns	BOOL	TRUE if success.

GetVersion
Returns the version and build number for the control.

Syntax	BOOL GetVersion(long plMajor,long plMinor, long plBuild );*
Parameters	plMajor	Major version number
	plMinor	Minor version number
	plBuild	Build number
Returns	BOOL	TRUE if success.

LoadFile
Load a HPGL/2 file.

Syntax	BOOL LoadFile(BSTR pFileName);
Parameters	pFileName	Name of file to load.
Returns	BOOL	TRUE if file loaded.

LoadFromString
Load HPGL/2 data from a string.

Syntax	BOOL LoadFromString(BSTR pData);
Parameters	pData	String containing HPGL/2 instructions.
Returns	BOOL	TRUE if file loaded.

LoadPenTable
Load a ViewCompanion compatible pen table file.

Syntax	BOOL LoadPenTable(BSTR pFileName);
Parameters	pFileName	Name of pentable file to load.
Returns	BOOL	TRUE if pen table loaded.

Print
Print the loaded file. You can control the result using the following properties: PrintScale, PrintFitToPaper and PrintCenterOnPage.

Syntax	BOOL Print();
Parameters	none
Returns	BOOL	TRUE if file printed.

PrintDisplay
Print the current display portion of the loaded file. You can control the result using the following properties: PrintScale, PrintFitToPaper and PrintCenterOnPage.

Syntax	BOOL PrintDisplay();
Parameters	none
Returns	BOOL	TRUE if file printed.

PrintPoster
Print the a file using multiple sheets of paper. Usefull for print e.g A0 drawings on a A4 printer in original size (100% scaling).
You can control the number of sheets by using the PrintScale property.

Syntax	BOOL PrintPoster();
Parameters	none
Returns	BOOL	TRUE if succeeded.

ScreenToWorld
Scale from screen (pixels) to world coordinates. World coordinates are the loaded file's native coordinate system.

Syntax	BOOL ScreenToWorld(long lScreenX, long lScreenY, long plWorldX, long plWorldY);
Parameters	lScreenX	Screen X coordinate.
	lScreenY	Screen Y coordinate.
	plWorldX	Transformed World X coordinate.
	plWorldY	Transformed World Y coordinate.
Returns	BOOL	TRUE if success

SelectPrinter
Select printer to use by giving Driver, Printer and Port names.
Eg.: SelectPrinter( "HPFDJC15.DRV", "HP DeskJet 895C Series Printer", "" );
NB! Will only work if UseDefaultPrinter property is set to False.

Syntax	BOOL SelectPrinter( LPCSTR szDriverName, LPCSTR szPrinterName, LPCSTR szPortName);
	szDriverName	Name of driver.
	szPrinterName	Name of printer.
	szPortName	Name of port.
Returns	BOOL	TRUE if success

SetLicenseOwner
Set the name of the license owner. Will be shown in the About dialog as "Licensed to owner".

Syntax	BOOL SetLicenseOwner( LPCSTR szOwner);
Parameters	szOwner	License owner.
Returns	BOOL	TRUE if success

SetMetaFileDPI
Set resolution to use for metafiles copied to clipboard. Default resolution is 96 dpi.

Syntax	BOOL SetMetaFileDPI(long lDPI);
Parameters	lDPI	Metafile resolution.
Returns	BOOL	TRUE if success

SetPanPosition
Set pan values. Used to together with zoom factor to control which part of the loaded file that is currently shown.

Syntax	BOOL SetPanPosition(long lPosX, long lPosY);
Parameters	lPosX	New horisontal position .
	lPosY	New vertical position .
Returns	BOOL	TRUE if success

SetPenState
Set state of the given pen.

Syntax	BOOL SetPenState(long lPen, long lState);
Parameters	lPen	Pen number.
	lState	Pen status (0:Off/1:On).
Returns	long	TRUE if success.

SetPenTableEntry
Set width, color and style for the given pen table entry.

Syntax	BOOL SetPenTableEntry(long lPen, double dWidth, long crColor, long lStyle);
Parameters	lPen	Pen number.
	dWidth	Pen Width.
	crColor	Pen Color (Windows COLORREF). When specifying an explicit RGB color, the color value has the following hexadecimal form: 0x00bbggrr.
	lStyle	Windows GDI pen style. The following styles are supported: #define PS_SOLID 0 #define PS_DASH 1 /* ------- / #define PS_DOT 2 / ....... / #define PS_DASHDOT 3 / _._._._ / #define PS_DASHDOTDOT 4 / _.._.._ */
Returns	long	TRUE if success.

SetSerialNumber
Unlock the control to use all it's functionality. You get this serialnumber when You purchase a developer license.

Syntax	BOOL SetSerialNumber( LPCSTR szSerialNumber);
Parameters	szSerialNumber	Serial number to unlock control.
Returns	BOOL	TRUE if correct serial number.

SetUserCursor
Set your own cursor to use for the different mouse functions that are available in the control.

Syntax	BOOL SetUserCursor(enumCursorType lCursorType, OLE_HANDLE hCursor);
Parameters	lCursorType	Select which cursor to change: ZoomWindowCursor, PanHandCursor or PressedPanHandCursor.
	hCursor	Handle to cursor loaded by LoadResPicture. Example on usage can be found in the VB demo application. Set hCursor to NULL to use the default cursor.
Returns	BOOL	TRUE if the cursor have been set.

SetZoomWindowColors
Set your own colors and linestyle that will be used for the zoom window rectangle.
SetZoomWindowColors(RGB(101, 114, 224), RGB(199, 216, 248), PS_SOLID) will change the zoom window rectangle to a Windows XP styled zoom window.

Syntax	BOOL SetZoomWindowColors(OLE_COLOR crBorder, OLE_COLOR crFill, long ltBorder);
Parameters	crBorder	Color to use for the rectangle border.
	crFill	Fill Color to use for the rectangle. Set to 0 for no fill.
	ltBorder	Linestyle to use for the rectangle. One of the predefined Windows values, e.g. PS_SOLID.
Returns	BOOL	TRUE if the colors have been set.

SetViewRect
Select a rectangular area of the file that should be viewed. This function uses world coordinates.

Syntax	BOOL SetViewRect(long x1, long y1, long x2, long y2);
Parameters	x1	Left coordinate of area to show.
	y1	Upper coordinate of area to show.
	x2	Right coordinate of area to show.
	y2	Lower coordinate of area to show.
Returns	BOOL	TRUE if success

SetZoomType

Syntax	BOOL SetZoomType(long nZoomType);
Parameters	nZoomType	Set Zoom Type, one of the following: 1. Zoom All 2. Zoom To Width 3. Zoom In 4. Zoom Out 5. Zoom Window 6. Zoom Center 7. Panning Hand
Returns	BOOL	TRUE if success

WorldToScreen
Scale from world to screen coordinates. World coordinates are the loaded file's native coordinate system.

Syntax	BOOL WorldToScreen(long lWorldX, long lWorldY, long plScreenX, long plScreenY);
Parameters	lWorldX	World X coordinate.
	lWorldY	World Y coordinate.
	plScreenX	Transformed Screen X coordinate.
	plScreenY	Transformed Screen Y coordinate.
Returns	BOOL	TRUE if success

Properties

AdjustColorFlag
If this flag is to TRUE all colors equal to or near background color will be inverted.
Default Value : FALSE

AntiAliaseRaster
If this flag is to TRUE all raster images will be drawn with better quality when the image is scaled down.
Default Value : TRUE

ArcResolution
Set the number of line segments a circle or arc will be drawn with.
Default Value : 60

BackColor
Set background color to use.

BorderStyle
Set style for border.

CenterImage
If this option is enabled the image will be centred on the screen when zoomed out.
The area outside the image will be filled with the color defined by WorkspaceColor property.
Default Value : FALSE

CurrentPage
Controls the page currently show in the control.
Default Value : 0

EnableAboutBox
The About item will be visible in the context menu if this set to TRUE.
(Only valid if control is licensed).
Default Value : TRUE

EnableContextMenu
Allows the user to use the right-click popup menu if set to TRUE.
Default Value : TRUE

EnableContextMenuPrint
The Print item will be visible in the context menu if this property set to TRUE.
Default Value : TRUE

ExportAlignmentH
Controls placement of exported drawing if the exported "page" width is larger than the drawing width.
Used by the ExportExtents method.
Available values : hLeft, hCenter and hRight.
Default Value : hLeft

ExportAlignmentV
Controls placement of exported drawing if the exported "page" height is larger than the drawing height.
Used by the ExportExtents method.
Available values : vTop, vMiddle and vBottom.
Default Value : vTop

Flip
Flip the image vertically if set to TRUE.
Default Value : FALSE

ForeColor
Set foreground color to use when monochrome drawing is enabled.

Grayscale
Set grayscale mode. All colors will be replaced by gray colors.
Default Value : FALSE

HaveRaster
Will be true if the currently viewed file contains embedded raster images.
Default Value : FALSE

LoadEmbeddedRaster
Control if embedded raster (RTL) should be loaded or not.
Default Value : TRUE

Mirror
Mirror the image horizontally if set to TRUE.
Default Value : FALSE

Monochrome
If TRUE the loaded file will be shown in monochrome.
Default Value : FALSE

PrintCenterOnPaper
If TRUE the printed drawing will be centered on the paper.
Default Value : TRUE

PrintFitToPaper
If TRUE the printed drawing will scaled to fit the paper.
Default Value : TRUE

PrintScale
Scaling to use when printing the drawing. The scaling is in percentage, eg. 100 is 1:1.
NB! If PrintFitToPaper is enabled, this scale factor is ignored.
Default Value : 100.0 (100%)

Rotation
The rotation to use when the file is displayed. Legal values is between 0.0 and 360.0.
Default Value : 0

ScalePenTable
If TRUE, the pentable widths will be scaled together with the drawing.
Default Value : TRUE

ShowScrollBars
Controls if the scrollbars should be shown or not.
Default Value : TRUE

TransparentRaster
If TRUE all raster images will be drawn using transparency.
Windows 2000/XP only.
Default Value : TRUE

TrueSize
If TRUE all polygons will be filled, and thick lines will be shown using their real width.
Default Value : TRUE

UseDefaultPrinter
If TRUE, the control will use the default printer when printing. If FALSE, a Printer Setup Dialog box will be shown when printing is invoked.
Default Value : TRUE

UseFilePaperSize
If TRUE, the original paper size, if available, will be used when converting, instead of the calculated extents of all drawing entities.
Use this property to maintain white space borders around the drawing.
Default Value : FALSE

UsePenTable
If TRUE, the current loaded or set pentable will be used when drawing,printing and converting.
Default Value : FALSE

WorkspaceColor
Color to use when filling area outside image area.
Default Value : Depends on the theme settings.

ZoomFactor
Set/get current zoom factor.

Events

AfterPrint
void AfterPrint(long lHDC, long lPage)
Called after the loaded file has been printed but before the page is sent to the printer.
This event allows client application to add information to the page by using the given hdc (Windows GDI device context). The lPage parameter contains the number for the page that is printed.

MouseDown
void MouseDown(short Button, short Shift, OLE_XPOS_PIXELS x, OLE_YPOS_PIXELS y)
Called each time user has pressed a mouse button.
Stock Property.

MouseMove
void MouseMove(short Button, short Shift, OLE_XPOS_PIXELS x, OLE_YPOS_PIXELS y)
Called each time user moves the mouse.
Stock Property.

MouseUp
void MouseUp(short Button, short Shift, OLE_XPOS_PIXELS x, OLE_YPOS_PIXELS y)
Called each time user frees a pressed mouse button.
Stock Property.

Progress
void Progress(long lPercent)
Called during load time. Allows the client to show a progress meter.

Context Menu

The context menu is shown when the user clicks the right mouse button inside the control's window. You can use the EnableContextMenu property to disable or enable the menu.
The image below shows the context menu. Left of the image You will see a brief description of each item in the menu:

Zoom All	Show the whole image inside the control window.
Zoom In	Increase scaling factor by 50%.
Zoom Out	Decrease scaling factor by 50&.
Zoom Window	Select a region with the mouse.
Pan Hand	Move around the image by pressing left mouse button and moving the cursor.
Print	Print the image using current settings. This item can be hidden (see EnableContextMenuPrint).
About	Shows information about the program and company. This item can be hidden (see EnableAboutBox).