47852bff02
* Add \since directive to each method. * Add documentation for BScrollBar and BScrollView classes. * Title Case group titles. * Some other minor documentation updates.
204 lines
5.2 KiB
Plaintext
204 lines
5.2 KiB
Plaintext
/*
|
|
* 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
|
|
*/
|