Class XbpFileDev() Foundation

Class function of the XbpFileDev class.


Objects of the XbpFileDev() class are exclusively used for the initial creation of a metafile. Metafiles contain graphic information that is created by the Xbase++ GRA engine. Metafiles allow drawings to be saved in a file as a series of graphic primitives and later displayed by "playing back" the metafile. After a metafile has been saved on the hard disk, it can be reloaded and displayed using objects of the XbpMetaFile() class.

An XbpFileDev object represents the device context for a presentation space where graphic output can occur. Rather than displaying the graphic output, it is saved in a metafile. The presentation space is linked with this device context to manage a file as the output device.

Metafiles are normally loaded and displayed using XbpMetaFile objects. In the special case where the metafile does not already exist, the output of graphic functions occurs in main memory and the information is stored by an XbpFileDev object. This object records all calls to graphic functions. After the graphic output in the presentation space is finished, the XbpFileDev object must be detached from the presentation space. The :metaFile() method is called to create the XbpMetaFile object. The object is then ready to save the graphic information in a metafile.

Creating a metafile requires several steps involving objects of the XbpPresSpace(), XbpFileDev() and XbpMetaFile() classes. In the example shown later, user defined functions are used to simplify this process.

Class methods
Creates an instance of the XbpFileDev class.
Life cycle
Requests system resources for a device context to use in creating metafiles.
This method has no effect in the XbpFileDev() class.
Releases the system resources of the XbpFileDev object.
Creates an XbpMetaFile object that can be used to save the recorded graphic information in a metafile.
Indicates a page break.
Save graphic data in metafiles

// This example demonstrates the basic process of 
// creating metafiles to save graphic information. 

   LOCAL oPS, oDC, oMF 

   SetColor( "N/W" )                  // Fill window pale gray 

   oDC := XbpFileDev():New():Create() // Create device context 
                                      // Create presentation space 
   oPS := XbpPresSpace():New():Create( oDC ) // and connect with DC 

   GraBox( oPS, {10,10}, {400,100} )  // Graphic output 
   GraStringAt( oPS, {20,50}, ; 
               "Image is stored in metafile") 

   oPS:configure()                    // Detach device context 

   oMF := oDC:metaFile()              // Create XbpMetaFile object 
   oDC:destroy()                      // Release device context 

   IF File( "Test.met" )              // Ensure that no TEST.MET 
      FErase( "Test.met" )            // file exists 

   oMF:save( "Test.met" )             // Save image in file 
   WAIT "Metafile is created, press a key..." 

   oMF:= XbpMetaFile():new():create() // New MetaFile object 
   oMF:load( "Test.met" )             // Load file 

   oPS:= SetAppWindow():presSpace()   // Get PS from the window 
   oMF:draw( oPS )                    // Output in this PS 

   WAIT                               // Wait for keypress 
Create metafiles using user defined functions

// In the example, two UDFs are programmed to simplify 
// metafile creation. The MetaFilePS() function 
// generates a presentation space that is linked 
// to a device context. Graphic output in this 
// presentation space is recorded by the XbpFileDev 
// object. When this presentation space is passed to 
// the UDF MetaFileCreate(), the graphic information 
// is saved in a metafile and an XbpMetaFile object 
// is returned. 

#include "" 

   LOCAL oPS, oMF 

   SetColor( "N/W" )                  // Fill window pale gray 
                                     // Create presentation space 
   oPS := MetaFilePS( {500,320}, GRA_PU_ARBITRARY ) 

   GraBox( oPS, {10,10}, {300,100} )  // Graphic output 
   GraStringAt( oPS, {20,50}, "Image is saved in metafile") 

   oMF := MetaFileCreate( oPS, "Test.met" ) 

   oPS:= SetAppWindow():presSpace()   // Get PS from the window 
   oMF:draw( oPS )                    // Output in this PS 

   WAIT                               // Wait for keypress 

* This function creates a presentation space linked 
* with a device context for metafiles 
FUNCTION MetaFilePS( aPageSize, nPageUnits ) 
   LOCAL oDC := XbpFileDev():new():create() 
   LOCAL oPS := XbpPresSpace():new() 

RETURN  oPS:create( oDC, aPageSize, nPageUnits ) 

* This function creates a metafile and returns 
* an XbpMetafile object that contains the saved graphic 
* information of the presentation space 
FUNCTION MetaFileCreate( oPS, cFileName ) 
   LOCAL oMF, oDC := oPS:device()     // Read device context 

   oPS:configure()                    // Detach device context 

   oMF := oDC:metaFile()              // Create metafile object 
   IF File( cFileName )               // Delete existing 
      FErase( cFileName )             // metafile 

   oMF:save( cFileName )              // Create metafile 

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.