hrev47233 adds 4 changesets to branch 'master' old head: 87d5f67840ab6614412f7c7ab31afe76d10d54a5 new head: 18d4375e7c7f1dcfd14e7b322315f14de22406f2 overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=18d4375+%5E87d5f67 ---------------------------------------------------------------------------- df48d3f: BPicture: Style fixes related to documentation. Mostly pointer style adjustments c109d7e: BPictureButton: Style fixes related to documentation Some variable renaming for consistency. 03608f3: Fill out documentation for BPicture class. 18d4375: Fill out documentation for BPictureButton class. [ John Scipione <jscipione@xxxxxxxxx> ] ---------------------------------------------------------------------------- 6 files changed, 612 insertions(+), 146 deletions(-) docs/user/interface/Picture.dox | 146 ++++++++++++- docs/user/interface/PictureButton.dox | 331 +++++++++++++++++++++++++++++- headers/os/interface/Picture.h | 11 +- headers/os/interface/PictureButton.h | 10 +- src/kits/interface/Picture.cpp | 196 ++++++++++-------- src/kits/interface/PictureButton.cpp | 64 +++--- ############################################################################ Commit: df48d3f9a839a18e16b3d7036935bef621b4fbb6 URL: http://cgit.haiku-os.org/haiku/commit/?id=df48d3f Author: John Scipione <jscipione@xxxxxxxxx> Date: Tue May 20 00:09:23 2014 UTC BPicture: Style fixes related to documentation. Mostly pointer style adjustments ---------------------------------------------------------------------------- diff --git a/headers/os/interface/Picture.h b/headers/os/interface/Picture.h index c452df8..39f3312 100644 --- a/headers/os/interface/Picture.h +++ b/headers/os/interface/Picture.h @@ -1,5 +1,5 @@ /* - * Copyright 2001-2009, Haiku, Inc. All rights reserved. + * Copyright 2001-2014 Haiku Inc. All rights reserved. * Distributed under the terms of the MIT License. */ #ifndef _PICTURE_H @@ -20,13 +20,12 @@ class BPicture : public BArchivable { public: BPicture(); BPicture(const BPicture& other); - BPicture(BMessage* archive); + BPicture(BMessage* data); virtual ~BPicture(); - static BArchivable* Instantiate(BMessage* archive); - virtual status_t Archive(BMessage* archive, - bool deep = true) const; - virtual status_t Perform(perform_code d, void* arg); + static BArchivable* Instantiate(BMessage* data); + virtual status_t Archive(BMessage* data, bool deep = true) const; + virtual status_t Perform(perform_code code, void* arg); status_t Play(void** callBackTable, int32 tableEntries, diff --git a/src/kits/interface/Picture.cpp b/src/kits/interface/Picture.cpp index c6ad37e..fee1fce 100644 --- a/src/kits/interface/Picture.cpp +++ b/src/kits/interface/Picture.cpp @@ -1,12 +1,13 @@ /* - * Copyright 2001-2007, Haiku Inc. + * Copyright 2001-2014 Haiku Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Marc Flerackers (mflerackers@xxxxxxxxxx) + * Marc Flerackers, mflerackers@xxxxxxxxxx */ -//! BPicture records a series of drawing instructions that can be "replayed" later. + +// Records a series of drawing instructions that can be "replayed" later. #include <Picture.h> @@ -61,33 +62,32 @@ BPicture::Private::ReconnectToAppServer() struct _BPictureExtent_ { - _BPictureExtent_(const int32 &size = 0); + _BPictureExtent_(const int32& size = 0); ~_BPictureExtent_(); const void* Data() const { return fNewData; } - status_t ImportData(const void *data, - const int32 &size); - - status_t Flatten(BDataIO *stream); - status_t Unflatten(BDataIO *stream); + status_t ImportData(const void* data, + const int32& size); + + status_t Flatten(BDataIO* stream); + status_t Unflatten(BDataIO* stream); int32 Size() const { return fNewSize; } - status_t SetSize(const int32 &size); + status_t SetSize(const int32& size); - bool AddPicture(BPicture *picture) + bool AddPicture(BPicture* picture) { return fPictures.AddItem(picture); } - void DeletePicture(const int32 &index) - { delete static_cast<BPicture *> - (fPictures.RemoveItem(index)); } - - BList* Pictures() { return &fPictures; } - BPicture* PictureAt(const int32 &index) - { return static_cast<BPicture *> - (fPictures.ItemAt(index)); } - + void DeletePicture(const int32& index) + { delete static_cast<BPicture*> + (fPictures.RemoveItem(index)); } + + BList* Pictures() { return &fPictures; } + BPicture* PictureAt(const int32& index) + { return static_cast<BPicture*> + (fPictures.ItemAt(index)); } + int32 CountPictures() const { return fPictures.CountItems(); } - private: void* fNewData; @@ -115,7 +115,7 @@ BPicture::BPicture() } -BPicture::BPicture(const BPicture &otherPicture) +BPicture::BPicture(const BPicture& otherPicture) : fToken(-1), fExtent(NULL), @@ -129,25 +129,27 @@ BPicture::BPicture(const BPicture &otherPicture) link.Attach<int32>(otherPicture.fToken); status_t status = B_ERROR; - if (link.FlushWithReply(status) == B_OK - && status == B_OK) + if (link.FlushWithReply(status) == B_OK && status == B_OK) link.Read<int32>(&fToken); + if (status < B_OK) return; } if (otherPicture.fExtent->Size() > 0) { - fExtent->ImportData(otherPicture.fExtent->Data(), otherPicture.fExtent->Size()); + fExtent->ImportData(otherPicture.fExtent->Data(), + otherPicture.fExtent->Size()); for (int32 i = 0; i < otherPicture.fExtent->CountPictures(); i++) { - BPicture *picture = new BPicture(*otherPicture.fExtent->PictureAt(i)); + BPicture* picture + = new BPicture(*otherPicture.fExtent->PictureAt(i)); fExtent->AddPicture(picture); } } } -BPicture::BPicture(BMessage *archive) +BPicture::BPicture(BMessage* data) : fToken(-1), fExtent(NULL), @@ -156,24 +158,26 @@ BPicture::BPicture(BMessage *archive) _InitData(); int32 version; - if (archive->FindInt32("_ver", &version) != B_OK) + if (data->FindInt32("_ver", &version) != B_OK) version = 0; int8 endian; - if (archive->FindInt8("_endian", &endian) != B_OK) + if (data->FindInt8("_endian", &endian) != B_OK) endian = 0; - const void *data; + const void* pictureData; int32 size; - if (archive->FindData("_data", B_RAW_TYPE, &data, (ssize_t*)&size) != B_OK) + if (data->FindData("_data", B_RAW_TYPE, &pictureData, (ssize_t*)&size) + != B_OK) { return; - + } + // Load sub pictures - BMessage picMsg; + BMessage pictureMessage; int32 i = 0; - while (archive->FindMessage("piclib", i++, &picMsg) == B_OK) { - BPicture *pic = new BPicture(&picMsg); - fExtent->AddPicture(pic); + while (data->FindMessage("piclib", i++, &pictureMessage) == B_OK) { + BPicture* picture = new BPicture(&pictureMessage); + fExtent->AddPicture(picture); } if (version == 0) { @@ -198,7 +202,7 @@ BPicture::BPicture(BMessage *archive) } -BPicture::BPicture(const void *data, int32 size) +BPicture::BPicture(const void* data, int32 size) { _InitData(); // TODO: For now. We'll see if it's worth to support old style data @@ -244,46 +248,46 @@ BPicture::_DisposeData() } -BArchivable * -BPicture::Instantiate(BMessage *archive) +BArchivable* +BPicture::Instantiate(BMessage* data) { - if (validate_instantiation(archive, "BPicture")) - return new BPicture(archive); + if (validate_instantiation(data, "BPicture")) + return new BPicture(data); return NULL; } status_t -BPicture::Archive(BMessage *archive, bool deep) const +BPicture::Archive(BMessage* data, bool deep) const { if (!const_cast<BPicture*>(this)->_AssertLocalCopy()) return B_ERROR; - status_t err = BArchivable::Archive(archive, deep); + status_t err = BArchivable::Archive(data, deep); if (err != B_OK) return err; - err = archive->AddInt32("_ver", 1); + err = data->AddInt32("_ver", 1); if (err != B_OK) return err; - err = archive->AddInt8("_endian", B_HOST_IS_BENDIAN); + err = data->AddInt8("_endian", B_HOST_IS_BENDIAN); if (err != B_OK) return err; - err = archive->AddData("_data", B_RAW_TYPE, fExtent->Data(), fExtent->Size()); + err = data->AddData("_data", B_RAW_TYPE, fExtent->Data(), fExtent->Size()); if (err != B_OK) return err; - + for (int32 i = 0; i < fExtent->CountPictures(); i++) { - BMessage picMsg; + BMessage pictureMessage; - err = fExtent->PictureAt(i)->Archive(&picMsg, deep); + err = fExtent->PictureAt(i)->Archive(&pictureMessage, deep); if (err != B_OK) break; - - err = archive->AddMessage("piclib", &picMsg); + + err = data->AddMessage("piclib", &pictureMessage); if (err != B_OK) break; } @@ -293,26 +297,27 @@ BPicture::Archive(BMessage *archive, bool deep) const status_t -BPicture::Perform(perform_code d, void *arg) +BPicture::Perform(perform_code code, void* arg) { - return BArchivable::Perform(d, arg); + return BArchivable::Perform(code, arg); } status_t -BPicture::Play(void **callBackTable, int32 tableEntries, void *user) +BPicture::Play(void** callBackTable, int32 tableEntries, void* user) { if (!_AssertLocalCopy()) return B_ERROR; - BPrivate::PicturePlayer player(fExtent->Data(), fExtent->Size(), fExtent->Pictures()); + BPrivate::PicturePlayer player(fExtent->Data(), fExtent->Size(), + fExtent->Pictures()); return player.Play(callBackTable, tableEntries, user); } status_t -BPicture::Flatten(BDataIO *stream) +BPicture::Flatten(BDataIO* stream) { // TODO: what about endianess? @@ -323,6 +328,7 @@ BPicture::Flatten(BDataIO *stream) ssize_t bytesWritten = stream->Write(&header, sizeof(header)); if (bytesWritten < B_OK) return bytesWritten; + if (bytesWritten != (ssize_t)sizeof(header)) return B_IO_ERROR; @@ -331,7 +337,7 @@ BPicture::Flatten(BDataIO *stream) status_t -BPicture::Unflatten(BDataIO *stream) +BPicture::Unflatten(BDataIO* stream) { // TODO: clear current picture data? @@ -339,10 +345,11 @@ BPicture::Unflatten(BDataIO *stream) ssize_t bytesRead = stream->Read(&header, sizeof(header)); if (bytesRead < B_OK) return bytesRead; + if (bytesRead != (ssize_t)sizeof(header) || header.magic1 != 2 || header.magic2 != 0) return B_BAD_TYPE; - + status_t status = fExtent->Unflatten(stream); if (status < B_OK) return status; @@ -361,7 +368,7 @@ BPicture::Unflatten(BDataIO *stream) void -BPicture::_ImportOldData(const void *data, int32 size) +BPicture::_ImportOldData(const void* data, int32 size) { // TODO: We don't support old data for now } @@ -433,8 +440,8 @@ BPicture::_Upload() link.Attach<int32>(fExtent->CountPictures()); for (int32 i = 0; i < fExtent->CountPictures(); i++) { - BPicture *picture = fExtent->PictureAt(i); - if (picture) + BPicture* picture = fExtent->PictureAt(i); + if (picture != NULL) link.Attach<int32>(picture->fToken); else link.Attach<int32>(-1); @@ -444,8 +451,9 @@ BPicture::_Upload() status_t status = B_ERROR; if (link.FlushWithReply(status) == B_OK - && status == B_OK) + && status == B_OK) { link.Read<int32>(&fToken); + } return status; } @@ -458,34 +466,34 @@ BPicture::_Download() ASSERT(fToken != -1); BPrivate::AppServerLink link; - + link.StartMessage(AS_DOWNLOAD_PICTURE); link.Attach<int32>(fToken); - + status_t status = B_ERROR; if (link.FlushWithReply(status) == B_OK && status == B_OK) { int32 count = 0; link.Read<int32>(&count); - + // Read sub picture tokens for (int32 i = 0; i < count; i++) { - BPicture *pic = new BPicture; - link.Read<int32>(&pic->fToken); - fExtent->AddPicture(pic); + BPicture* picture = new BPicture; + link.Read<int32>(&picture->fToken); + fExtent->AddPicture(picture); } - + int32 size; link.Read<int32>(&size); status = fExtent->SetSize(size); if (status == B_OK) - link.Read(const_cast<void *>(fExtent->Data()), size); + link.Read(const_cast<void*>(fExtent->Data()), size); } return status; } -const void * +const void* BPicture::Data() const { if (fExtent->Data() == NULL) @@ -506,7 +514,7 @@ BPicture::DataSize() const void -BPicture::Usurp(BPicture *lameDuck) +BPicture::Usurp(BPicture* lameDuck) { _DisposeData(); @@ -518,10 +526,10 @@ BPicture::Usurp(BPicture *lameDuck) } -BPicture * +BPicture* BPicture::StepDown() { - BPicture *lameDuck = fUsurped; + BPicture* lameDuck = fUsurped; fUsurped = NULL; return lameDuck; @@ -533,15 +541,15 @@ void BPicture::_ReservedPicture2() {} void BPicture::_ReservedPicture3() {} -BPicture & -BPicture::operator=(const BPicture &) +BPicture& +BPicture::operator=(const BPicture&) { - return *this; + return* this; } // _BPictureExtent_ -_BPictureExtent_::_BPictureExtent_(const int32 &size) +_BPictureExtent_::_BPictureExtent_(const int32& size) : fNewData(NULL), fNewSize(0) @@ -554,20 +562,20 @@ _BPictureExtent_::~_BPictureExtent_() { free(fNewData); for (int32 i = 0; i < fPictures.CountItems(); i++) - delete static_cast<BPicture *>(fPictures.ItemAtFast(i)); + delete static_cast<BPicture*>(fPictures.ItemAtFast(i)); } status_t -_BPictureExtent_::ImportData(const void *data, const int32 &size) +_BPictureExtent_::ImportData(const void* data, const int32& size) { if (data == NULL) return B_BAD_VALUE; - + status_t status = B_OK; if (Size() != size) status = SetSize(size); - + if (status == B_OK) memcpy(fNewData, data, size); @@ -576,18 +584,18 @@ _BPictureExtent_::ImportData(const void *data, const int32 &size) status_t -_BPictureExtent_::Unflatten(BDataIO *stream) +_BPictureExtent_::Unflatten(BDataIO* stream) { if (stream == NULL) return B_BAD_VALUE; - + int32 count = 0; ssize_t bytesRead = stream->Read(&count, sizeof(count)); if (bytesRead < B_OK) return bytesRead; if (bytesRead != (ssize_t)sizeof(count)) return B_BAD_DATA; - + for (int32 i = 0; i < count; i++) { BPicture* picture = new BPicture; status_t status = picture->Unflatten(stream); @@ -598,24 +606,26 @@ _BPictureExtent_::Unflatten(BDataIO *stream) AddPicture(picture); } - + int32 size; bytesRead = stream->Read(&size, sizeof(size)); if (bytesRead < B_OK) return bytesRead; + if (bytesRead != (ssize_t)sizeof(size)) return B_IO_ERROR; status_t status = B_OK; if (Size() != size) status = SetSize(size); - + if (status < B_OK) return status; - + bytesRead = stream->Read(fNewData, size); if (bytesRead < B_OK) return bytesRead; + if (bytesRead != (ssize_t)size) return B_IO_ERROR; @@ -624,12 +634,13 @@ _BPictureExtent_::Unflatten(BDataIO *stream) status_t -_BPictureExtent_::Flatten(BDataIO *stream) +_BPictureExtent_::Flatten(BDataIO* stream) { int32 count = fPictures.CountItems(); ssize_t bytesWritten = stream->Write(&count, sizeof(count)); if (bytesWritten < B_OK) return bytesWritten; + if (bytesWritten != (ssize_t)sizeof(count)) return B_IO_ERROR; @@ -642,12 +653,14 @@ _BPictureExtent_::Flatten(BDataIO *stream) bytesWritten = stream->Write(&fNewSize, sizeof(fNewSize)); if (bytesWritten < B_OK) return bytesWritten; + if (bytesWritten != (ssize_t)sizeof(fNewSize)) return B_IO_ERROR; bytesWritten = stream->Write(fNewData, fNewSize); if (bytesWritten < B_OK) return bytesWritten; + if (bytesWritten != fNewSize) return B_IO_ERROR; @@ -656,7 +669,7 @@ _BPictureExtent_::Flatten(BDataIO *stream) status_t -_BPictureExtent_::SetSize(const int32 &size) +_BPictureExtent_::SetSize(const int32& size) { if (size < 0) return B_BAD_VALUE; @@ -668,9 +681,10 @@ _BPictureExtent_::SetSize(const int32 &size) free(fNewData); fNewData = NULL; } else { - void *data = realloc(fNewData, size); + void* data = realloc(fNewData, size); if (data == NULL) return B_NO_MEMORY; + fNewData = data; } ############################################################################ Commit: c109d7e06f30cd458630e28aa0ef7309edb339c0 URL: http://cgit.haiku-os.org/haiku/commit/?id=c109d7e Author: John Scipione <jscipione@xxxxxxxxx> Date: Tue May 20 00:10:25 2014 UTC BPictureButton: Style fixes related to documentation Some variable renaming for consistency. ---------------------------------------------------------------------------- diff --git a/headers/os/interface/PictureButton.h b/headers/os/interface/PictureButton.h index e457db8..bf70650 100644 --- a/headers/os/interface/PictureButton.h +++ b/headers/os/interface/PictureButton.h @@ -22,7 +22,7 @@ public: BPicture* off, BPicture* on, BMessage* message, uint32 behavior = B_ONE_STATE_BUTTON, - uint32 resizeMask = B_FOLLOW_LEFT + uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flgs = B_WILL_DRAW | B_NAVIGABLE); BPictureButton(BMessage* archive); @@ -56,10 +56,10 @@ public: virtual void MouseMoved(BPoint where, uint32 transit, const BMessage* message); - virtual void SetEnabledOn(BPicture* on); - virtual void SetEnabledOff(BPicture* off); - virtual void SetDisabledOn(BPicture* on); - virtual void SetDisabledOff(BPicture* off); + virtual void SetEnabledOn(BPicture* picture); + virtual void SetEnabledOff(BPicture* picture); + virtual void SetDisabledOn(BPicture* picture); + virtual void SetDisabledOff(BPicture* picture); BPicture* EnabledOn() const; BPicture* EnabledOff() const; diff --git a/src/kits/interface/PictureButton.cpp b/src/kits/interface/PictureButton.cpp index ee0c79f..613b893 100644 --- a/src/kits/interface/PictureButton.cpp +++ b/src/kits/interface/PictureButton.cpp @@ -6,6 +6,7 @@ * Graham MacDonald (macdonag@xxxxxxxxxxxxxxx) */ + #include <PictureButton.h> #include <new> @@ -14,10 +15,10 @@ BPictureButton::BPictureButton(BRect frame, const char* name, - BPicture* off, BPicture* on, BMessage* message, - uint32 behavior, uint32 resizeMask, uint32 flags) + BPicture* off, BPicture* on, BMessage* message, + uint32 behavior, uint32 resizingMode, uint32 flags) : - BControl(frame, name, "", message, resizeMask, flags), + BControl(frame, name, "", message, resizingMode, flags), fEnabledOff(new(std::nothrow) BPicture(*off)), fEnabledOn(new(std::nothrow) BPicture(*on)), fDisabledOff(NULL), @@ -38,7 +39,7 @@ BPictureButton::BPictureButton(BMessage* data) BMessage pictureArchive; // Default to 1 state button if not here - is this valid? - if (data->FindInt32 ("_behave", (int32* )&fBehavior) != B_OK) + if (data->FindInt32("_behave", (int32*)&fBehavior) != B_OK) fBehavior = B_ONE_STATE_BUTTON; // Now expand the pictures: @@ -65,9 +66,6 @@ BPictureButton::~BPictureButton() } -// #pragma mark - - - BArchivable* BPictureButton::Instantiate(BMessage* data) { @@ -120,9 +118,6 @@ BPictureButton::Archive(BMessage* data, bool deep) const } -// #pragma mark - - - void BPictureButton::AttachedToWindow() { @@ -151,9 +146,6 @@ BPictureButton::AllDetached() } -// #pragma mark - - - void BPictureButton::ResizeToPreferred() { @@ -182,9 +174,6 @@ BPictureButton::FrameResized(float newWidth, float newHeight) } -// #pragma mark - - - void BPictureButton::WindowActivated(bool state) { @@ -227,9 +216,9 @@ BPictureButton::Draw(BRect updateRect) void -BPictureButton::MessageReceived(BMessage* msg) +BPictureButton::MessageReceived(BMessage* message) { - BControl::MessageReceived(msg); + BControl::MessageReceived(message); } @@ -260,10 +249,10 @@ BPictureButton::KeyDown(const char* bytes, int32 numBytes) void -BPictureButton::MouseDown(BPoint point) +BPictureButton::MouseDown(BPoint where) { if (!IsEnabled()) { - BControl::MouseDown(point); + BControl::MouseDown(where); return; } @@ -283,10 +272,10 @@ BPictureButton::MouseDown(BPoint point) void -BPictureButton::MouseUp(BPoint point) +BPictureButton::MouseUp(BPoint where) { if (IsEnabled() && IsTracking()) { - if (Bounds().Contains(point)) { + if (Bounds().Contains(where)) { if (fBehavior == B_ONE_STATE_BUTTON) { if (Value() == B_CONTROL_ON) { snooze(75000); @@ -302,7 +291,8 @@ BPictureButton::MouseUp(BPoint point) void -BPictureButton::MouseMoved(BPoint point, uint32 transit, const BMessage* msg) +BPictureButton::MouseMoved(BPoint where, uint32 transit, + const BMessage* message) { if (IsEnabled() && IsTracking()) { if (transit == B_EXITED_VIEW) @@ -310,7 +300,7 @@ BPictureButton::MouseMoved(BPoint point, uint32 transit, const BMessage* msg) else if (transit == B_ENTERED_VIEW) SetValue(B_CONTROL_ON); } else - BControl::MouseMoved(point, transit, msg); + BControl::MouseMoved(where, transit, message); } @@ -318,34 +308,34 @@ BPictureButton::MouseMoved(BPoint point, uint32 transit, const BMessage* msg) void -BPictureButton::SetEnabledOn(BPicture* on) +BPictureButton::SetEnabledOn(BPicture* picture) { delete fEnabledOn; - fEnabledOn = new (std::nothrow) BPicture(*on); + fEnabledOn = new (std::nothrow) BPicture(*picture); } void -BPictureButton::SetEnabledOff(BPicture* off) +BPictureButton::SetEnabledOff(BPicture* picture) { delete fEnabledOff; - fEnabledOff = new (std::nothrow) BPicture(*off); + fEnabledOff = new (std::nothrow) BPicture(*picture); } void -BPictureButton::SetDisabledOn(BPicture* on) +BPictureButton::SetDisabledOn(BPicture* picture) { delete fDisabledOn; - fDisabledOn = new (std::nothrow) BPicture(*on); + fDisabledOn = new (std::nothrow) BPicture(*picture); } void -BPictureButton::SetDisabledOff(BPicture* off) +BPictureButton::SetDisabledOff(BPicture* picture) { delete fDisabledOff; - fDisabledOff = new (std::nothrow) BPicture(*off); + fDisabledOff = new (std::nothrow) BPicture(*picture); } @@ -399,17 +389,17 @@ BPictureButton::SetValue(int32 value) status_t -BPictureButton::Invoke(BMessage* msg) +BPictureButton::Invoke(BMessage* message) { - return BControl::Invoke(msg); + return BControl::Invoke(message); } BHandler* -BPictureButton::ResolveSpecifier(BMessage* msg, int32 index, +BPictureButton::ResolveSpecifier(BMessage* message, int32 index, BMessage* specifier, int32 form, const char* property) { - return BControl::ResolveSpecifier(msg, index, specifier, form, property); + return BControl::ResolveSpecifier(message, index, specifier, form, property); } @@ -488,7 +478,7 @@ BPictureButton::SetIcon(const BBitmap* icon, uint32 flags) } -// #pragma mark - +// #pragma mark - BPictureButton private methods void BPictureButton::_ReservedPictureButton1() {} ############################################################################ Commit: 03608f354a054d664f7f1c028c5e1449e8ea5b53 URL: http://cgit.haiku-os.org/haiku/commit/?id=03608f3 Author: John Scipione <jscipione@xxxxxxxxx> Date: Tue May 20 00:10:49 2014 UTC Fill out documentation for BPicture class. ---------------------------------------------------------------------------- diff --git a/docs/user/interface/Picture.dox b/docs/user/interface/Picture.dox index 5d58f65..e7d5c76 100644 --- a/docs/user/interface/Picture.dox +++ b/docs/user/interface/Picture.dox @@ -6,8 +6,8 @@ * John Scipione, jscipione@xxxxxxxxx * * Corresponds to: - * headers/os/interface/Picture.h hrev46970 - * src/kits/interface/Picture.cpp hrev46970 + * headers/os/interface/Picture.h hrev47233 + * src/kits/interface/Picture.cpp hrev47233 */ @@ -25,4 +25,146 @@ \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() +*/ + + +/*! + \fn BPicture::BPicture() + \brief Initializes an empty BPicture object. +*/ + + +/*! + \fn BPicture::BPicture(const BPicture& otherPicture) + \brief Initializes an BPicture object copying the data from \a otherPicture. +*/ + + +/*! + \fn BPicture::BPicture(BMessage* data) + \brief Initializes an BPicture object copying the data from from the + passed in \a data archive. +*/ + + +/*! + \fn BPicture::~BPicture() + \brief Destroys the BPicture object and deletes all associated data. +*/ + + +/*! + \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() +*/ + + +/*! + \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() +*/ + + +/*! + \fn status_t BPicture::Perform(perform_code code, void* arg) + \brief Perform some action (internal method defined for binary + compatibility purposes). +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. */ ############################################################################ Revision: hrev47233 Commit: 18d4375e7c7f1dcfd14e7b322315f14de22406f2 URL: http://cgit.haiku-os.org/haiku/commit/?id=18d4375 Author: John Scipione <jscipione@xxxxxxxxx> Date: Tue May 20 00:11:21 2014 UTC Fill out documentation for BPictureButton class. ---------------------------------------------------------------------------- diff --git a/docs/user/interface/PictureButton.dox b/docs/user/interface/PictureButton.dox index 984fcc3..6c9d1a9 100644 --- a/docs/user/interface/PictureButton.dox +++ b/docs/user/interface/PictureButton.dox @@ -6,8 +6,8 @@ * John Scipione, jscipione@xxxxxxxxx * * Corresponds to: - * headers/os/interface/PictureButton.h hrev46970 - * src/kits/interface/PictureButton.cpp hrev46970 + * headers/os/interface/PictureButton.h hrev47233 + * src/kits/interface/PictureButton.cpp hrev47233 */ @@ -15,7 +15,23 @@ \file PictureButton.h \ingroup interface \ingroup libbe - \brief BPictureButton class definition. + \brief BPictureButton class definition and support structures. +*/ + + +/*! + \var B_ONE_STATE_BUTTON + + Acts like a normal BButton, the value is set to \c B_CONTROL_ON when the + button is being pressed and is set to \c B_CONTROL_OFF otherwise. +*/ + + +/*! + \var B_TWO_STATE_BUTTON + + Acts like a checkbox, the value alternates between \c B_CONTROL_ON and + \c B_CONTROL_OFF each time the user presses and releases the button. */ @@ -23,6 +39,311 @@ \class BPictureButton \ingroup interface \ingroup libbe - \brief Displays a button with a BPicture image instead of a text - label like a BButton. + \brief A button draw with a BPicture image instead of a text label. +*/ + + +/*! + \fn BPictureButton::BPictureButton(BRect frame, const char* name, + BPicture* off, BPicture* on, BMessage* message, + uint32 behavior, uint32 resizingMode, uint32 flags) + \brief Initializes a new BPictureButton object. + + \param frame The \a frame rectangle of the button. + \param name The \a name of the button used internally. + \param off The BPicture object to use when the object is \a off. + \param on The BPicture object to use when the object is \a on. + \param message The BMessage to send when the object is invoked. + \param behavior Either \c B_ONE_STATE_BUTTON or \c B_TWO_STATE_BUTTON. + \param resizingMode Defines the view's behavior when its parent is + resized, see BView for more details. + \param flags The view flags, see BView for more details. + + \sa BPictureButton::SetBehavior() + \sa BPictureButton::SetEnabledOn() + \sa BPictureButton::SetEnabledOff() + \sa BPictureButton::SetDisabledOn() + \sa BPictureButton::SetDisabledOff() +*/ + + +/*! + \fn BPictureButton::BPictureButton(BMessage* data) + \brief Initializes an BPictureButton object copying the data from from the + passed in \a data archive. +*/ + + +/*! + \fn BPictureButton::~BPictureButton() + \brief Destroys the BPictureButton along with the associated BPicture objects. +*/ + + +/*! + \fn BArchivable* BPictureButton::Instantiate(BMessage* data) + \brief Returns a pointer to a new BPictureButton object created from the + BPictureButton data archived in \a data. + + \returns A newly created BPictureButton object or \c NULL if the message + doesn't contain an archived BPictureButton. + + \see BArchivable::Instantiate() +*/ + + +/*! + \fn status_t BPictureButton::Archive(BMessage* data, bool deep) const + \brief Archives the BPictureButton object into the \a data message. + + \param data A pointer to the BMessage object to archive into. + \param deep Also archive the associated BPicture objects. + + \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 BPictureButton::Instantiate() +*/ + + +/*! + \fn void BPictureButton::AttachedToWindow() + \see BControl::AttachedToWindow() +*/ + + +/*! + \fn void BPictureButton::DetachedFromWindow() + \see BControl::DetachedFromWindow() +*/ + + +/*! + \fn void BPictureButton::AllAttached() + \see BControl::AllAttached() +*/ + + +/*! + \fn void BPictureButton::AllDetached() + \see BControl::AllDetached() +*/ + + +/*! + \fn void BPictureButton::ResizeToPreferred() + \see BControl::ResizeToPreferred() +*/ + + +/*! + \fn void BPictureButton::GetPreferredSize(float* _width, float* _height) + \see BControl::GetPreferredSize() +*/ + + +/*! + \fn void BPictureButton::FrameMoved(BPoint newPosition) + \see BControl::FrameMoved() +*/ + + +/*! + \fn BPictureButton::FrameResized(float newWidth, float newHeight) + \see BControl::FrameResized() +*/ + + +/*! + \fn void BPictureButton::WindowActivated(bool state) + \see BControl::WindowActivated() +*/ + + +/*! + \fn void BPictureButton::MakeFocus(bool state) + \see BControl::MakeFocus() +*/ + + +/*! + \fn void BPictureButton::Draw(BRect updateRect) + \brief Draws the BPictureButton from its associated BPicture objects. +*/ + + +/*! + \fn void BPictureButton::MessageReceived(BMessage* message) + \see BControl::MessageReceived() +*/ + + +/*! + \fn void BPictureButton::KeyDown(const char* bytes, int32 numBytes) + \brief Invokes the button on either \c B_ENTER \c B_SPACE. + + \sa BControl::KeyDown() +*/ + + +/*! + \fn void BPictureButton::MouseDown(BPoint where) + \brief Sets the button value based on the buttons Behavior(). + + \sa BControl::MouseDown() + \sa Behavior() +*/ + + +/*! + \fn void BPictureButton::MouseUp(BPoint where) + \brief Invokes the button. + + \sa BControl::MouseUp() +*/ + + +/*! + \fn void BPictureButton::MouseMoved(BPoint where, uint32 transit, + const BMessage* message) + \brief + + \sa BControl::MouseMoved() +*/ + + +/*! + \fn void BPictureButton::SetEnabledOn(BPicture* picture) + \brief Sets the BPicture to draw when the button is enabled and on. + + \param picture A pointer to the BPicture object to set. +*/ + + +/*! + \fn void BPictureButton::SetEnabledOff(BPicture* picture) + \brief Sets the BPicture to draw when the button is enabled and off. + + \param picture A pointer to the BPicture object to set. +*/ + + +/*! + \fn void BPictureButton::SetDisabledOn(BPicture* picture) + \brief Sets the BPicture to draw when the button is disabled and on. + + If the behavior is set to \c B_ONE_STATE_BUTTON this does not need be + set because a disabled one-state control can never be on. + + \param picture A pointer to the BPicture object to set. +*/ + + +/*! + \fn void BPictureButton::SetDisabledOff(BPicture* picture) + \brief Sets the BPicture to draw when the button is disabled and off. + + \param picture A pointer to the BPicture object to set. +*/ + + +/*! + \fn BPicture* BPictureButton::EnabledOn() const + \brief Returns a pointer to the BPicture object used when the button + is enabled and on. + + \returns A pointer to a BPicture object or \c NULL if not set. +*/ + + +/*! + \fn BPicture* BPictureButton::EnabledOff() const + \brief Returns a pointer to the BPicture object used when the button + is enabled and off. + + \returns A pointer to a BPicture object or \c NULL if not set. +*/ + + +/*! + \fn BPicture* BPictureButton::DisabledOn() const + \brief Returns a pointer to the BPicture object used when the button + is disabled and on. + + \returns A pointer to a BPicture object or \c NULL if not set. +*/ + + +/*! + \fn BPicture* BPictureButton::DisabledOff() const + \brief Returns a pointer to the BPicture object used when the button + is disabled and off. + + \returns A pointer to a BPicture object or \c NULL if not set. +*/ + + +/*! + \fn void BPictureButton::SetBehavior(uint32 behavior) + \brief Set the behavior to either \c B_ONE_STATE_BUTTON or + \c B_TWO_STATE_BUTTON. + + A one-state BPictureButton acts like a normal button, the value is set to + \c B_CONTROL_ON when the button is being pressed and it is set to + \c B_CONTROL_OFF otherwise. A two-state object acts like a checkbox, the + value alternates between \c B_CONTROL_ON and \c B_CONTROL_OFF each time + the user presses and releases the button. + + \param behavior Either \c B_ONE_STATE_BUTTON or \c B_TWO_STATE_BUTTON. +*/ + + +/*! + \fn uint32 BPictureButton::Behavior() const + \brief Return the currently set behavior. + + \returns Either \c B_ONE_STATE_BUTTON or B_TWO_STATE_BUTTON. + + \see BPictureButton::SetBehavior() +*/ + + +/*! + \fn void BPictureButton::SetValue(int32 value) + \see BControl::SetValue() +*/ + + +/*! + \fn status_t BPictureButton::Invoke(BMessage* message) + \see BControl::Invoke() +*/ + + +/*! + \fn BHandler* BPictureButton::ResolveSpecifier(BMessage* message, + int32 index, BMessage* specifier, int32 form, const char* property) + \see BControl::ResolveSpecifier() +*/ + + +/*! + \fn status_t BPictureButton::GetSupportedSuites(BMessage* data) + \see BControl::GetSupportedSuites() +*/ + + +/*! + \fn status_t BPictureButton::Perform(perform_code code, void* _data) + \brief Perform some action (internal method defined for binary + compatibility purposes). +*/ + + +/*! + \fn status_t BPictureButton::SetIcon(const BBitmap* icon, uint32 flags) + \see BControl::SetIcon() */