Printer Objects

Objects of the IDLgrPrinter class represent a physical printer onto which graphics hierarchies can be rendered in either bitmap or vector mode. What appears when producing bitmap or vector output depends upon several factors. See Bitmap and Vector Graphic Output for details.

Creating Printer Objects

The IDLgrPrinter::Init method takes no arguments. Use the following statement to create a printer object:

myPrinter = OBJ_NEW('IDLgrPrinter')

This creates an object that maintains information about the printer. By default, this information pertains to the default printer installed for your system. To select a different printer or setup attributes of the printer, use the printer dialogs described in the next section.

See "IDLgrPrinter" (IDL Reference Guide) for details on creating printer objects.

Color Model

By default, printer objects use the RGB color model. To create a printer that uses the Indexed color model, set the COLOR_MODEL property of the printer object equal to 1 (one) when creating the printer:

myWindow = OBJ_NEW('IDLgrPrinter', COLOR_MODEL=1)

You cannot change the color model used by a printer after it has been created.

See Color in Object Graphics for a discussion of the two color models.

Printer Dialogs

IDL includes two functions useful for controlling printers and print jobs.

DIALOG_PRINTERSETUP

Call the DIALOG_PRINTERSETUP function with the object reference of a printer object as its argument to open an operating system native dialog for setting the applicable properties of a particular printer. DIALOG_PRINTERSETUP returns a nonzero value if you pressed the OK button in the dialog, or zero otherwise.

result = DIALOG_PRINTERSETUP(myPrinter)

See DIALOG_PRINTERSETUP for details.

DIALOG_PRINTJOB

Call the DIALOG_PRINTJOB function with the object reference of a printer object as its argument to open an operating system native dialog to initiate a printing job. DIALOG_PRINTJOB returns a nonzero value if you pressed the OK button in the dialog, or zero otherwise.

result = DIALOG_PRINTJOB(myPrinter)

See DIALOG_PRINTJOB for details.

Drawing to a Printer

To draw a graphics tree to a printer, call the IDLgrPrinter::Draw method. The argument must be either an IDLgrView object, an IDLgrViewGroup object, or an IDLgrScene object.

myPrinter->Draw, myView

myPrinter->Draw, myScene

All objects contained within the scene, viewgroup, or view will be drawn to the printer.

Note
The scene or view to be drawn may be the same as the scene or view being displayed in one or more windows.

Printing in Bitmap or Vector Graphic Mode

The IDLgrPrinter::Draw method VECTOR keyword specifies whether the output is in bitmap or vector format. The following table shows the keyword options and results for each platform.

Table 12-2: File Types Produced by IDLgrPrinter Draw Method
Keyword Settings	Windows Printer Output	UNIX File Type
VECTOR = 0	Bitmap (BMP)	Encapsulated PostScript (EPS) file (e.g. `xprinter.eps`)
VECTOR = 1	Enhanced MetaFile (EMF)	Encapsulated PostScript (EPS) file (e.g. `xprinter.eps`)

VECTOR=0 is the default. Because Windows printer output is usually sent directly to the printer, EMF and BMP files are not viewable. On UNIX, the printer output is directed to a file named xprinter.eps by default. For more information on printing views, scenes, or viewgroups, see "IDLgrPrinter::Draw" (IDL Reference Guide).

Positioning Objects Within a Page

Objects can be positioned in a printed page by first determining the size of the page. Use the IDLgrPrinter object DIMENSIONS property to return the size of the "drawable" area of the page. You can then use these dimensions to draw a view of specified dimensions in the center of the printed page. The following two examples show positioning objects within the printed page:

The first example scales an orb object based on the page size and draws the view containing the orb to the center of the hardcopy page. See Example: Centering an Orb.

The second example creates two IDLgrAxis objects and an orb object, each with a UNITS property value set to centimeters. The view is positioned in the center of the page, but the other object locations are specified in centimeters and drawn to the view in precise positions. See Example: Precisely Positioning Vector and Bitmap Output.

Example: Centering an Orb

The following example positions a view containing an orb object in the center of a page when it is printed. Centering the view is a common task. Using this example as a guideline, you can easily adapt it to meet your own needs.

PRO center_doc 
 
; Define dimensions in centimeters (cm). 
dims = [5.0, 5.0]  
 
; Create a view with centimeters as units. Add the view to a model. 
oView = OBJ_NEW('IDLgrView', $ 
   UNITS=2, $ 
   VIEWPLANE_RECT=[-dims[0]/2, -dims[1]/2, dims[0], dims[1]], $ 
   ZCLIP=[MAX(dims), -MAX(dims)], EYE=MAX(dims)+1, $ 
   COLOR=[200,200,200]) 
oModel = OBJ_NEW('IDLgrModel') 
oView->Add, oModel  
 
; Create an orb object and add it to the model. 
oOrb1 = OBJ_NEW('orb', COLOR=[0,255,0], SHADING=1, $ 
   STYLE=2, HIDDEN=0) 
oModel->Add, oOrb1 
 
; Make radius 40% of window width. 
oModel->Scale, dims[0]*0.4, dims[0]*0.4, dims[0]*0.4  
oModel->Rotate, [1,1,0], 10 
 
; Create a light and add it to the model.  
oLight = OBJ_NEW('IDLgrLight', TYPE=1, LOCATION=[1.5,1.5,2]) 
oModel->Add, oLight 
 
; Create a printer object, setting centimeters as the units. 
oPrinter=OBJ_NEW('IDLgrPrinter', UNITS=2) 
 
; Retrieve the drawable area of the page in the pagesize 
; variable and use this to position the view. 
oPrinter->GetProperty, DIMENSIONS=pageSize 
centering = ((pageSize - dims)/2.) 
oView->SetProperty, LOCATION=centering, DIMENSIONS=dims 
 
; Print the view. 
oPrinter->Draw, oView, VECTOR=1 
 
OBJ_DESTROY,[oPrinter] 
OBJ_DESTROY,[oView] 
 
END

The following figure shows a subset of the output. The orb is positioned in the center of a printed page when you run this example.

Figure 12-1: Output Centered in Printed Page

Example: Precisely Positioning Vector and Bitmap Output

The following example creates a model and draws some IDLgrAxis objects to the printer in vector mode. It then creates a second model for an orb object and plots the orb, drawing it to the printer in bitmap mode. The entire view is centered in the page, as shown in the previous example. However, this example precisely positions the orb and axes within the view using data units (defined as centimeters).

PRO center2_doc 
 
; Set the view dimensions in units of centimeters (cm). 
viewDims = [10.0, 10.0]  
 
; Set the orb origin in cm, relative to the lower left  
; corner of the view. 
orbLoc = [3.0, 4.0]  
 
; Set the Orb radius in cm. 
orbRadius = 2.2  
 
; Create the Orb object. 
; The Orb object creates a unit orb with a default radius of 1. 
oOrbModel = OBJ_NEW('IDLgrModel') 
oOrb = OBJ_NEW('orb', COLOR=[0,255,0], SHADING=1, STYLE=2) 
oOrbModel->Add, oOrb 
 
; Create axes model. Create and position the axis objects.  
oAxesModel = OBJ_NEW('IDLgrModel') 
oX = OBJ_NEW('IDLgrAxis', 0, RANGE=[1,viewDims[0]-1], $ 
   /EXACT, LOCATION=[orbLoc[0]-orbRadius, 1]) 
oAxesModel->Add, oX 
oY = OBJ_NEW('IDLgrAxis', 1, RANGE=[1, viewDims[1]-1], $ 
   /EXACT, LOCATION=[1, orbLoc[1]-orbRadius]) 
oAxesModel->Add, oY 
 
; Add a box to show view extent.  
oAxesModel->Add, OBJ_NEW('IDLgrPolygon', $ 
   [0, viewDims[0], viewDims[0], 0], $ 
   [0, 0, viewDims[1], viewDims[1]], STYLE=1) 
 
; Create the view using the previously defined dimensions.  
oView = OBJ_NEW('IDLgrView', $ 
   UNITS=2, VIEWPLANE_RECT=[0, 0, viewDims[0], viewDims[1]], $ 
   ZCLIP=[MAX(viewDims), -MAX(viewDims)], EYE=MAX(viewDims)+1, $ 
   COLOR=[255,255,255]) 
oTopModel = OBJ_NEW('IDLgrModel') 
oView->Add, oTopModel 
 
; Add a light. 
oLight = OBJ_NEW('IDLgrLight', TYPE=1, LOCATION=[1.5,1.5,2]) 
oTopModel->Add, oLight 
 
; Set up printer to print user-requested view. Center 
; entire printer output in the page. 
oPrinter=OBJ_NEW('IDLgrPrinter', UNITS=2) 
oPrinter->GetProperty, DIMENSIONS=pageSize 
centering = ((pageSize - viewDims)/2.) 
oView->SetProperty, LOCATION=centering, DIMENSIONS=viewDims 
 
; Print view containing axes in vector mode then remove model. 
oTopModel->Add, oAxesModel 
oPrinter->Draw, oView, VECTOR=1 
oTopModel->Remove, oAxesModel 
 
; Now float the orb into the view and print it in bitmap mode.  
oTopModel->Add, oOrbModel 
oView->SetProperty, VIEWPLANE_RECT = $ 
   [-orbRadius, -orbRadius, 2 * orbRadius, 2 * orbRadius], $ 
   LOCATION=[orbLoc[0]-orbRadius,orbLoc[1]-orbRadius]+centering, $ 
   DIMENSIONS=[2*orbRadius, 2*orbRadius] 
   oPrinter->Draw, oView, VECTOR=0 
 
; oPrinter->NewDocument 
OBJ_DESTROY,[oPrinter] 
OBJ_DESTROY,[oView] 
 
END

The following figure shows a subset of the output. The entire plot area is positioned in the center of a printed page when you run this example.

Figure 12-2: Positioning Objects Within a Printed Page

Starting a New Page on a Printer

To ensure that any subsequent calls to the IDLgrPrinter::Draw method occur on a new page, call the IDLgrPrinter::NewPage method:

myPrinter->NewPage

Submitting a Printer Job

To submit a printer job, call the IDLgrPrinter::NewDocument method. This method submits the printing job (consisting of all previous calls to IDgrPrinter::Draw and IDLgrPrinter::NewPage) to the printer.

After this method has been called, the printer is prepared to accept a new batch of graphics calls (via IDLgrPrinter::Draw).

myPrinter->NewDocument