1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/Picture.h hrev47233 10 * src/kits/interface/Picture.cpp hrev47233 11 */ 12 13 14/*! 15 \file Picture.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BPicture class definition. 19*/ 20 21 22/*! 23 \class BPicture 24 \ingroup interface 25 \ingroup libbe 26 \brief Records a series of drawing instructions that can be "replayed" 27 later. 28 29 A BPicture, unlike a BBitmap, is independent of the display resolution 30 as it contains drawing instructions rather than image data. 31 32 To begin drawing you first create a new BPicture object and pass it to 33 BView::BeginPicture(). All subsequent drawing instructions are drawn 34 into the BPicture object instead of the BView. When you are done recording 35 call BView::EndPicture() which stops drawing into the BPicture object and 36 passes a pointer to it back to the caller. 37 38 For example: 39\code 40 BPicture* picture; 41 view->BeginPicture(new BPicture); 42 // drawing instructions go here 43 picture = view->EndPicture(); 44\endcode 45 46 Only drawing instructions performed directly on the view, not it's child 47 views are send to the BPicture object and BPicture captures only primitive 48 graphics operations. The view must be attached to a window for the drawing 49 instruction to be recorded. Drawing instructions are recorded even if the 50 view is hidden or resides outside the clipping region or the window is 51 off-screen. 52 53 The BPicture object data is erased when passed to BView::BeginPicture(). 54 If you'd like to append data to a BPicture object instead use 55 BView::AppendToPicture(). Both BView::BeginPicture() and 56 BView::AppendToPicture() must be followed by a call to BView::EndPicture() 57 to finish recording. 58 59 \sa BView::AppendToPicture() 60 \sa BView::BeginPicture() 61 \sa BView::EndPicture() 62 63 \since BeOS R3 64*/ 65 66 67/*! 68 \fn BPicture::BPicture() 69 \brief Initializes an empty BPicture object. 70 71 \since BeOS R3 72*/ 73 74 75/*! 76 \fn BPicture::BPicture(const BPicture& otherPicture) 77 \brief Initializes an BPicture object copying the data from \a otherPicture. 78 79 \since BeOS R3 80*/ 81 82 83/*! 84 \fn BPicture::BPicture(BMessage* data) 85 \brief Initializes an BPicture object copying the data from from the 86 passed in \a data archive. 87 88 \since BeOS R3 89*/ 90 91 92/*! 93 \fn BPicture::~BPicture() 94 \brief Destroys the BPicture object and deletes all associated data. 95 96 \since BeOS R3 97*/ 98 99 100/*! 101 \name Archiving 102*/ 103 104 105//! @{ 106 107 108/*! 109 \fn BArchivable* BPicture::Instantiate(BMessage* data) 110 \brief Returns a pointer to a new BPicture object created from the BPicture 111 data archived in \a data. 112 113 \returns A newly created BPicture object or \c NULL if the message doesn't 114 contain an archived BPicture. 115 116 \see BArchivable::Instantiate() 117 118 \since BeOS R3 119*/ 120 121 122/*! 123 \fn status_t BPicture::Archive(BMessage* data, bool deep) const 124 \brief Archives the BPicture object into the \a data message. 125 126 \param data A pointer to the BMessage object to archive into. 127 \param deep The parameter has no effect to this method. 128 129 \return A status code, \c B_OK if everything went well or an error code 130 otherwise. 131 \retval B_OK The object was archived successfully. 132 \retval B_NO_MEMORY Ran out of memory while archiving the object. 133 134 \sa BArchivable::Archive() 135 \sa BPicture::Instantiate() 136 137 \since BeOS R3 138*/ 139 140 141//! @} 142 143 144/*! 145 \fn status_t BPicture::Perform(perform_code code, void* arg) 146 \brief Perform some action (internal method defined for binary 147 compatibility purposes). 148 149 \since Haiku R1 150*/ 151 152 153/*! 154 \fn status_t BPicture::Play(void** callBackTable, int32 tableEntries, 155 void* user) 156 \brief Plays back a picture using the passed in call back functions. 157 158 See http://haiku-os.org/legacy-docs/bebook/BPicture.html#BPicture_Play 159 for details. 160 161 \param callBackTable An array of pointers to pointers of call back functions. 162 \param tableEntries Specifies the number of function pointers found in 163 \a callBackTable. 164 \param user A hook to pass additional data to each call back function. 165 166 \returns A status code. 167 \retval B_OK The BPicture object was played back successfully. 168 \retval B_ERROR BPicture data is \c NULL. 169 170 \since BeOS R3 171*/ 172 173 174/*! 175 \fn status_t BPicture::Flatten(BDataIO* stream) 176 \brief Flattens the contents of the BPicture object into \a stream. 177 178 \param stream The stream to write to. 179 180 \returns A status code, \c B_OK on success or an error code otherwise. 181 \retval B_OK The BPicture object was flattened successfully. 182 \retval B_BAD_VALUE The \a stream pointer was \c NULL or the data was invalid. 183 \retval B_IO_ERROR The number of bytes written does not equal the size 184 of the contents of the BPicture object. 185 186 \since Haiku R1 187*/ 188 189 190/*! 191 \fn status_t BPicture::Unflatten(BDataIO* stream) 192 \brief Unflattens the contents from the \a stream into the BPicture object. 193 194 \param stream The stream to read from. 195 196 \returns A status code, \c B_OK on success or an error code otherwise. 197 \retval B_OK The object was unflattened successfully. 198 \retval B_BAD_VALUE The \a stream pointer was \c NULL or the data was invalid. 199 \retval B_IO_ERROR The number of bytes read does not equal the size 200 of the contents of the BPicture object. 201 202 \since Haiku R1 203*/ 204