haiku/docs/user/interface/Picture.dox

204 lines
5.2 KiB
Plaintext
Raw Normal View History

/*
* Copyright 2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* headers/os/interface/Picture.h hrev47233
* src/kits/interface/Picture.cpp hrev47233
*/
/*!
\file Picture.h
\ingroup interface
\ingroup libbe
\brief BPicture class definition.
*/
/*!
\class BPicture
\ingroup interface
\ingroup libbe
\brief Records a series of drawing instructions that can be "replayed"
later.
A BPicture, unlike a BBitmap, is independent of the display resolution
as it contains drawing instructions rather than image data.
To begin drawing you first create a new BPicture object and pass it to
BView::BeginPicture(). All subsequent drawing instructions are drawn
into the BPicture object instead of the BView. When you are done recording
call BView::EndPicture() which stops drawing into the BPicture object and
passes a pointer to it back to the caller.
For example:
\code
BPicture* picture;
view->BeginPicture(new BPicture);
// drawing instructions go here
picture = view->EndPicture();
\endcode
Only drawing instructions performed directly on the view, not it's child
views are send to the BPicture object and BPicture captures only primitive
graphics operations. The view must be attached to a window for the drawing
instruction to be recorded. Drawing instructions are recorded even if the
view is hidden or resides outside the clipping region or the window is
off-screen.
The BPicture object data is erased when passed to BView::BeginPicture().
If you'd like to append data to a BPicture object instead use
BView::AppendToPicture(). Both BView::BeginPicture() and
BView::AppendToPicture() must be followed by a call to BView::EndPicture()
to finish recording.
\sa BView::AppendToPicture()
\sa BView::BeginPicture()
\sa BView::EndPicture()
\since BeOS R3
*/
/*!
\fn BPicture::BPicture()
\brief Initializes an empty BPicture object.
\since BeOS R3
*/
/*!
\fn BPicture::BPicture(const BPicture& otherPicture)
\brief Initializes an BPicture object copying the data from \a otherPicture.
\since BeOS R3
*/
/*!
\fn BPicture::BPicture(BMessage* data)
\brief Initializes an BPicture object copying the data from from the
passed in \a data archive.
\since BeOS R3
*/
/*!
\fn BPicture::~BPicture()
\brief Destroys the BPicture object and deletes all associated data.
\since BeOS R3
*/
/*!
\name Archiving
*/
//! @{
/*!
\fn BArchivable* BPicture::Instantiate(BMessage* data)
\brief Returns a pointer to a new BPicture object created from the BPicture
data archived in \a data.
\returns A newly created BPicture object or \c NULL if the message doesn't
contain an archived BPicture.
\see BArchivable::Instantiate()
\since BeOS R3
*/
/*!
\fn status_t BPicture::Archive(BMessage* data, bool deep) const
\brief Archives the BPicture object into the \a data message.
\param data A pointer to the BMessage object to archive into.
\param deep The parameter has no effect to this method.
\return A status code, \c B_OK if everything went well or an error code
otherwise.
\retval B_OK The object was archived successfully.
\retval B_NO_MEMORY Ran out of memory while archiving the object.
\sa BArchivable::Archive()
\sa BPicture::Instantiate()
\since BeOS R3
*/
//! @}
/*!
\fn status_t BPicture::Perform(perform_code code, void* arg)
\brief Perform some action (internal method defined for binary
compatibility purposes).
\since Haiku R1
*/
/*!
\fn status_t BPicture::Play(void** callBackTable, int32 tableEntries,
void* user)
\brief Plays back a picture using the passed in call back functions.
See http://haiku-os.org/legacy-docs/bebook/BPicture.html#BPicture_Play
for details.
\param callBackTable An array of pointers to pointers of call back functions.
\param tableEntries Specifies the number of function pointers found in
\a callBackTable.
\param user A hook to pass additional data to each call back function.
\returns A status code.
\retval B_OK The BPicture object was played back successfully.
\retval B_ERROR BPicture data is \c NULL.
\since BeOS R3
*/
/*!
\fn status_t BPicture::Flatten(BDataIO* stream)
\brief Flattens the contents of the BPicture object into \a stream.
\param stream The stream to write to.
\returns A status code, \c B_OK on success or an error code otherwise.
\retval B_OK The BPicture object was flattened successfully.
\retval B_BAD_VALUE The \a stream pointer was \c NULL or the data was invalid.
\retval B_IO_ERROR The number of bytes written does not equal the size
of the contents of the BPicture object.
\since Haiku R1
*/
/*!
\fn status_t BPicture::Unflatten(BDataIO* stream)
\brief Unflattens the contents from the \a stream into the BPicture object.
\param stream The stream to read from.
\returns A status code, \c B_OK on success or an error code otherwise.
\retval B_OK The object was unflattened successfully.
\retval B_BAD_VALUE The \a stream pointer was \c NULL or the data was invalid.
\retval B_IO_ERROR The number of bytes read does not equal the size
of the contents of the BPicture object.
\since Haiku R1
*/