Object Programming: Displaying, Copying and Printing Objects

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 for details on creating printer objects. Also see Printing in IDL for information on defining a printer.

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  

or

myPrinter->Draw, myScene  

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

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.

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.

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:

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

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

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  

myPrinter->NewDocument