The Interface Kit: BPicture

Derived from: public BArchivable

Declared in: <interface/Picture.h>

Overview

A BPicture object holds a set of drawing instructions in the Application Server, where they can be reused over and over again simply by passing the object to BView's DrawPicture() function. Because it contains instructions for producing an image, not the rendered result of those instructions, a picture (unlike a bitmap) is independent of the resolution of the display device.

Recording a Picture

Drawing instructions are captured by bracketing them with calls to a BView's BeginPicture() and EndPicture() functions. An empty BPicture object is passed to BeginPicture(); EndPicture() returns the same object, fully initialized. For example:

   BPicture *myPict;
   someView->BeginPicture(new BPicture);
   /* drawing code goes here */
   myPict = someView->EndPicture();

The BPicture object records all of the drawing instructions given to the BView following the BeginPicture() call and preceding the EndPicture() call. Only drawing that the BView does is recorded; drawing done by children and other views attached to the window is ignored, as is everything except drawing code.

Drawing instructions that are captured between BeginPicture() and EndPicture() do not also produce a rendered image; ignored instructions may be rendered if they draw into the visible region of an on-screen window.

If the BPicture object passed to BeginPicture() isn't empty, the new drawing is appended to the code that's already in place.

The Picture Definition

The picture captures everything that affects the image that's drawn. It takes a snapshot of the BView's graphics parameters--the pen size, high and low colors, font size, and so on--at the time BeginPicture() is called. It then captures all subsequent modifications to those parameters, such as calls to MovePenTo(), SetLowColor(), and SetFontSize(). However, changes to the coordinate system (ScrollBy() and ScrollTo()) are ignored.

The picture records all primitive drawing instructions--such as, DrawBitmap(), StrokeEllipse(), FillRect(), and DrawString(). It can even include a call to DrawPicture(); one picture can incorporate another.

The BPicture traces exactly what the BView would draw if the drawing code were not bracketed by BeginPicture() and EndPicture() calls, and reproduces it precisely. For example, whatever pen size happens to be in effect when a line is stroked will be the pen size that the picture records, whether it was explicitly set while the BPicture was being recorded or assumed from the BView's graphics environment.

The picture makes its own copy of any data that's passed during the recording session. For example, it copies the bitmap passed to DrawBitmap() and the picture passed to DrawPicture(). If that bitmap or picture later changes, it won't affect what was recorded.

See also: BView::BeginPicture(), BView::DrawPicture(), the BPictureButton class

Constructor and Destructor

BPicture()

      BPicture(void)
      BPicture(const BPicture &picture)
      BPicture(void *data, int32 size)
      BPicture(BMessage *archive)

Initializes the BPicture object by ensuring that it's empty, by copying data from another picture, or by copying size bytes of picture data. The data should be taken, directly or indirectly, from another BPicture object.

~BPicture()

      virtual ~BPicture(void)

Destroys the Application Server's record of the BPicture object and deletes all its picture data.

Static Functions

Instantiate()

      static BPicture *Instantiate(BMessage *archive) 

Returns a new BPicture object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn't contain BPicture data, this function returns NULL.

See also: BArchivable::Instantiate(), instantiate_object(), Archive()

Member Functions

Archive()

      virtual status_t Archive(BMessage *archive, bool deep = true) const

Calls the inherited version of Archive(), then adds the picture data to the BMessage archive.

See also: BArchivable::Archive(), Instantiate() static function

Data()

      const void *Data(void) const

Returns a pointer to the data contained in the BPicture. The data can be copied from the object, stored on disk (perhaps as a resource), and later used to initialize another BPicture object.

See also: the BPicture constructor

DataSize()

      int32 DataSize(void) const

Returns how many bytes of data the BPicture object contains.

See also: Data()

The Be Book, in lovely HTML, for the BeOS Preview Release.

Copyright © 1997 Be, Inc. All rights reserved.

Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.

Last modified June 30, 1997.