Programming Guide:xppguide

The metafile - XbpMetaFile() Foundation

Metafiles play a central role in storing and exchanging graphic data and drawings. Metafiles store images in the same form they are drawn in the presentation space and allow the drawing to be redisplayed as necessary in the same or in another application. Images can be stored and printed in the format of the metafile, they can be exchanged between two work stations in this format, and they can be temporarily stored in the Clipboard while being transferred from one application to another.

The sequence of graphic primitives used to create a drawing is stored in the metafile. This includes the coordinates of the graphic primitives and their attributes. A metafile generally contains a vector image, because it stores a sequence of graphic primitives that can be "played back" again after the metafile is loaded in a presentation space. Metafiles are also used to exchange drawings between two work stations. As long as the metafile contains a drawing created using only graphic primitives, a drawing can be output on different screens or printers. Raster images can also be stored in a metafile (see function GraBitBlt()), and in this case the correct redisplay of a metafile on different output devices is not guaranteed since it is device dependent.

Xbase++ allows loading, displaying, storing and creating metafiles. For loading and displaying, objects of the class XbpMetaFile() are used. They manage metafiles that are already stored on a disk. The following lines of code show how metafiles are displayed in a window:

oMF := XbpMetaFile():new():create() // create metafile object 
oMF:load( "METAFILE.MET" )          // load metafile 

oPS := SetAppWindow():presSpace()   // get presentation space 
                                    // from the window 

oMF:draw( oPS )                     // redisplay the contents of the 
                                    // metafile in presentation space 

This procedure is designed to load existing metafiles into an Xbase++ application. But it is also possible to store graphic output created by an Xbase++ application in a metafile. To accomplish this, an XbpFileDev object must be created. It represents the device context where the graphic output of the Gra...() functions is recorded. Example:

   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 combine with DC 

   GraBox( oPS, {10,10}, {400,100} )  // graphic output 
   GraStringAt( oPS, {20,50}, ; 
               "Image will be stored in metafile") 
   oPS:configure()                    // detach device context 

   oMF := oDC:metaFile()              // create XbpMetaFile object 
   oDC:destroy()                      // release device context 

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

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

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

   oPS:= SetAppWindow():presSpace()   // get PS from window 
   oMF:draw( oPS )                    // output in this PS 

   WAIT                               // wait for keypress 

In this example, an XbpFileDev object is created as a device context and associated with a presentation space. The graphic output is performed in this presentation space. When the output is completed, the device context is detached from the presentation space using a call to the :configure() method of the presentation space. The XbpFileDev object is now able to create an XbpMetaFile object containing the graphic output of GraBox() and GraStringAt(). The method :save() saves this graphic information in a new 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.