Haiku Book: Added GameSound, Shelf
Change-Id: I1377ab80e7128a5406bf9f0523564e5e7f9e9f1b Reviewed-on: https://review.haiku-os.org/c/haiku/+/8624 Reviewed-by: Adrien Destugues <[email protected]> Haiku-Format: Haiku-format Bot <[email protected]> Tested-by: Commit checker robot <[email protected]>
This commit is contained in:
cafeina
committed by
Adrien Destugues
Adrien Destugues
parent
a4d7ac5b5f
commit
102726ea26
@@ -0,0 +1,254 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2024 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina, cafeina@world
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/game/GameSound.h hrev58367
|
||||||
|
* src/kits/game/GameSound.cpp hrev58367
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file GameSound.h
|
||||||
|
\ingroup game
|
||||||
|
\ingroup libbe
|
||||||
|
\brief Provides the BGameSound base class.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\class BGameSound
|
||||||
|
\ingroup game
|
||||||
|
\ingroup libbe
|
||||||
|
\brief BGameSound is the base class used in the other sound classes in
|
||||||
|
the kit.
|
||||||
|
|
||||||
|
This class is not meant to be used directly. Any of the derived classes
|
||||||
|
should be used instead.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BGameSound::BGameSound(BGameSoundDevice* device = NULL)
|
||||||
|
\brief Creates a BGameSound object.
|
||||||
|
|
||||||
|
The \a device parameter is currently unused and has to be defined as \c NULL.
|
||||||
|
Currently the class itself will retrieve the default device.
|
||||||
|
|
||||||
|
\param[in] device The sound device to be used.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual BGameSound::~BGameSound()
|
||||||
|
\brief Destroys the BGameSound object and frees the memory it uses.
|
||||||
|
|
||||||
|
It releases any buffer connected to the game sound device and then
|
||||||
|
releases the device itself.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual BGameSound* BGameSound::Clone() = 0
|
||||||
|
\brief Pure virtual method to create a copy of the BGameSound object.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BGameSound::InitCheck() const
|
||||||
|
\brief Verifies if the BGameSound object was successfully initialized.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BGameSoundDevice* BGameSound::Device() const
|
||||||
|
\brief Returns a pointer to the sound playback device.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn gs_id BGameSound::ID() const
|
||||||
|
\brief Returns the identifier of the sound associated with the BGameSound
|
||||||
|
object.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const gs_audio_format& BGameSound::Format() const
|
||||||
|
\brief Returns a gs_audio_format struct instance with the format of the sound
|
||||||
|
associated with the BGameSound object.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Playback
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual status_t BGameSound::StartPlaying()
|
||||||
|
\brief Plays the sound in the playback device.
|
||||||
|
|
||||||
|
\retval B_OK Playback started successfully.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual bool BGameSound::IsPlaying()
|
||||||
|
\brief Checks whether the sound is being played or not in the playback
|
||||||
|
device.
|
||||||
|
|
||||||
|
\retval true The sound is currently being played.
|
||||||
|
\retval false The sound is not being played.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual status_t BGameSound::StopPlaying()
|
||||||
|
\brief Stops the playback of a sound currently playing.
|
||||||
|
|
||||||
|
\retval B_OK The sound stopped playing.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @}
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Sound Attributes
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BGameSound::SetGain(float gain, bigtime_t duration = 0)
|
||||||
|
\brief Sets the gain of the sound, that is, the amount of amplification of the
|
||||||
|
input signal.
|
||||||
|
|
||||||
|
The \a gain is represented as a proportion, from 0.0 as the lowest to 1.0 as
|
||||||
|
the highest level of gain.
|
||||||
|
|
||||||
|
A non-zero \a duration makes the transition from the current gain to the new
|
||||||
|
gain take place over time in the amount set (in microseconds). If it is \c 0,
|
||||||
|
the change occurs immediately instead.
|
||||||
|
|
||||||
|
\param[in] gain Level of sound gain.
|
||||||
|
\param[in] duration Duration of transition from the older gain level to the
|
||||||
|
newer level.
|
||||||
|
|
||||||
|
\retval B_OK The gain was applied successfully.
|
||||||
|
\retval B_BAD_VALUE An out-of-bounds value for the gain was provided
|
||||||
|
(not being 0.0 <= gain <= 1.0).
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BGameSound::SetPan(float pan, bigtime_t duration = 0)
|
||||||
|
\brief Sets the panning of the sound, that is, the distribution of the audio
|
||||||
|
signal anywhere in the stereophonic sound field.
|
||||||
|
|
||||||
|
A value of \a pan of -1.0 sets the sound at the most left side, 0.0 at the
|
||||||
|
front, and 1.0 at the most right side.
|
||||||
|
|
||||||
|
A non-zero \a duration makes the transition from the current pan to the new
|
||||||
|
pan take place over time in the amount set (in microseconds). If it is \c 0,
|
||||||
|
the change occurs immediately instead.
|
||||||
|
|
||||||
|
\param[in] pan Level of panning.
|
||||||
|
\param[in] duration Duration of transition from the older panning value to
|
||||||
|
the newer value.
|
||||||
|
|
||||||
|
\retval B_OK The pan was applied successfully.
|
||||||
|
\retval B_ERROR The BGameSound's sound was not initialized.
|
||||||
|
\retval B_BAD_VALUE An out-of-bounds value for the pan was provided
|
||||||
|
(not being -1.0 <= pan <= 1.0).
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn float BGameSound::Gain()
|
||||||
|
\brief Retrieves the current level of gain of the sound.
|
||||||
|
|
||||||
|
If there is no sound initialized, by default it returns 0.0.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn float BGameSound::Pan()
|
||||||
|
\brief Retrieves the current value of panning of the sound.
|
||||||
|
|
||||||
|
If there is no sound initialized, by default it returns 0.0.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual status_t BGameSound::SetAttributes(gs_attribute* attributes, size_t attributeCount)
|
||||||
|
\brief Sets the attributes for the current sound.
|
||||||
|
|
||||||
|
\param[in] attributes An array of the group of attributes to be applied to the
|
||||||
|
sound.
|
||||||
|
\param[in] attributeCount The number of those attributes.
|
||||||
|
|
||||||
|
\retval B_OK The attributes were applied successfully, or no error.
|
||||||
|
\retval B_ERROR The BGameSound's sound was not initialized.
|
||||||
|
\retval others Depending on the type of attribute.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual status_t BGameSound::GetAttributes(gs_attribute* attributes, size_t attributeCount)
|
||||||
|
\brief Retrieves the attributes of the current sound.
|
||||||
|
|
||||||
|
\a attributes is a pre-allocated array of gs_attribute structures, with the
|
||||||
|
"attribute" field of each one pre-filled with the desired attribute's
|
||||||
|
identifier, for which the information is going to be retrieved.
|
||||||
|
|
||||||
|
\param[out] attributes The gs_attribute list where to save the attributes.
|
||||||
|
\param[in] attributeCount The number of items in the \a attributes list.
|
||||||
|
|
||||||
|
\retval B_OK The attributes were retrieved successfully.
|
||||||
|
\retval B_ERROR The BGameSound's sound was not initialized.
|
||||||
|
|
||||||
|
\since BeOS R4.5
|
||||||
|
*/
|
||||||
|
|
||||||
@@ -0,0 +1,561 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2024 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina, cafeina@world
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/interface/Shelf.h hrev58367
|
||||||
|
* src/kits/interface/Shelf.cpp hrev58367
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file Shelf.h
|
||||||
|
\ingroup interface
|
||||||
|
\ingroup libbe
|
||||||
|
\brief BShelf class definition.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\class BShelf
|
||||||
|
\ingroup interface
|
||||||
|
\ingroup libbe
|
||||||
|
\brief A container attached to a BView that accepts BDragger objects
|
||||||
|
(replicants).
|
||||||
|
|
||||||
|
A BShelf object creates a container where to store BDragger
|
||||||
|
objects, also known as "replicants". When the user drops a replicant
|
||||||
|
on the shelf, or a shelf is loaded from an archived message, it will
|
||||||
|
load and display it as a child object. Once created, it could
|
||||||
|
either save the replicant's data in a filesystem entry or in a
|
||||||
|
BDataIO data stream and retrieve the data from either source to display the
|
||||||
|
replicant.
|
||||||
|
|
||||||
|
During the construction, or afterwards with SetAllowsDragging(), it
|
||||||
|
can be configured to allow or disallow to accept the replicants
|
||||||
|
dropped by the user onto the shelf. This behavior can be queried by
|
||||||
|
calling the method AllowsDragging().
|
||||||
|
|
||||||
|
The \a shelfType parameter from the constructors allows the shelf to
|
||||||
|
have a filter-like system. This is reflected in the archived field
|
||||||
|
\c shelf_type. In this way, the shelf could reject any replicant
|
||||||
|
whose shelf type does not match shelf's type, or the other way around.
|
||||||
|
But the shelf accepts by default the replicants without a type (and
|
||||||
|
a shelf without a type could also accept any kind of replicants, as
|
||||||
|
long as they do not reject it). However, this behavior can be disabled
|
||||||
|
by using the type enforcement with SetTypeEnforced(), allowing the
|
||||||
|
shelf to reject any replicant strictly without the same type of the shelf.
|
||||||
|
The state of this behavior can be queried with IsTypeEnforced().
|
||||||
|
|
||||||
|
When a replicant was unable to be loaded, a "zombie view" could be
|
||||||
|
deployed instead. "Zombie views" are placeholder views that are deployed
|
||||||
|
in place of a replicant whose application of origin cannot be found.
|
||||||
|
This behavior can be modified to disable the generation of zombie views
|
||||||
|
with SetAllowsZombies(), or to hide them with SetDisplayZombies().
|
||||||
|
AllowsZombies() and DisplaysZombies() queries the state of any of those
|
||||||
|
behaviors.
|
||||||
|
|
||||||
|
This class supports the standard scripting protocol.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BShelf::BShelf(BView* view, bool allowDrags = true,
|
||||||
|
const char* shelfType = NULL)
|
||||||
|
\brief Creates a BShelf object that is attached to a view.
|
||||||
|
|
||||||
|
\param[in] view The container BView.
|
||||||
|
\param[in] allowDrags Specifies if the shelf accepts replicants dragged
|
||||||
|
to it by the user or not.
|
||||||
|
\param[in] shelfType Specifies a filter-like name for the object's
|
||||||
|
underlying BHandler. This can be used to reject BDragger objects
|
||||||
|
whose names does not match shelfType.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BShelf::BShelf(const entry_ref* ref, BView* view,
|
||||||
|
bool allowDrags = true,
|
||||||
|
const char* shelfType = NULL)
|
||||||
|
\brief Creates a BShelf object that is attached to a view, and sets
|
||||||
|
\a ref as the source from where to load the archived BDragger objects
|
||||||
|
and where to save them.
|
||||||
|
|
||||||
|
\param[in] ref The filesystem entry from where the archived BDragger objects
|
||||||
|
will be loaded during the initialization and saved.
|
||||||
|
\param[in] view The container BView.
|
||||||
|
\param[in] allowDrags Specifies if the shelf accepts replicants dragged
|
||||||
|
to it by the user or not.
|
||||||
|
\param[in] shelfType Specifies a filter-like name for the object's
|
||||||
|
underlying BHandler. This can be used to reject BDragger objects
|
||||||
|
whose names does not match shelfType.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BShelf::BShelf(BDataIO* stream, BView* view,
|
||||||
|
bool allowDrags = true,
|
||||||
|
const char* shelfType = NULL)
|
||||||
|
\brief Creates a BShelf object that is attached to a view, and sets
|
||||||
|
\a stream as the data stream source from where to load the archived
|
||||||
|
BDragger objects and where to save them.
|
||||||
|
|
||||||
|
\param[in] stream The data stream from where the archived BDragger objects
|
||||||
|
will be loaded during the initialization and saved.
|
||||||
|
\param[in] view The container BView.
|
||||||
|
\param[in] allowDrags Specifies if the shelf accepts replicants dragged
|
||||||
|
to it by the user or not.
|
||||||
|
\param[in] shelfType Specifies a filter-like name for the object's
|
||||||
|
underlying BHandler. This can be used to reject BDragger objects
|
||||||
|
whose names does not match shelfType.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BShelf::BShelf(BMessage* archive)
|
||||||
|
\brief Unimplemented.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn virtual BShelf::~BShelf()
|
||||||
|
\brief The destructor calls Save(), frees the data sources and replicant
|
||||||
|
data of the replicants and detaches itself from the container BView.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Archiving
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BArchivable* BShelf::Instantiate(BMessage* archive)
|
||||||
|
\brief Unimplemented.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::Archive(BMessage* archive, bool deep = true) const
|
||||||
|
\brief Unimplemented.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @}
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::MessageReceived(BMessage* message)
|
||||||
|
\brief Handle \a message received by the associated looper.
|
||||||
|
|
||||||
|
\param message The \a message received by the associated looper.
|
||||||
|
|
||||||
|
\sa BHandler::MessageReceived()
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::Save()
|
||||||
|
\brief Saves the BShelf contents as an archived BMessage into a filesystem
|
||||||
|
entry or BDataIO stream if any of them were specified with the
|
||||||
|
constructor.
|
||||||
|
|
||||||
|
In case there was not a data destination specified with the constructor, it
|
||||||
|
can be set with SetSaveLocation().
|
||||||
|
|
||||||
|
\return A status code.
|
||||||
|
\retval B_OK The operation was performed successfully.
|
||||||
|
\retval B_ERROR The archiving operation failed, or there was not any
|
||||||
|
data destination specified.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::SetDirty(bool state)
|
||||||
|
\brief Sets the "dirty" state flag. This flag is used by the application and
|
||||||
|
is also automatically applied when the save location is changed.
|
||||||
|
|
||||||
|
\param state \c true to set it as "dirty", or \c false to remove the flag.
|
||||||
|
|
||||||
|
\sa IsDirty()
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::IsDirty() const
|
||||||
|
\brief Retrieves the "dirty" flag status of the shelf.
|
||||||
|
|
||||||
|
\return \c true if the shelf is "dirty", or \c false otherwise.
|
||||||
|
|
||||||
|
\sa SetDirty(bool)
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::GetSupportedSuites(BMessage* data)
|
||||||
|
\brief Report the suites of messages this control understands.
|
||||||
|
|
||||||
|
Adds the string "suite/vnd.Be-shelf" to the message.
|
||||||
|
|
||||||
|
\sa BHandler::GetSupportedSuites()
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::AllowsDragging() const
|
||||||
|
\brief Check if the user is able to drag replicants to the shelf.
|
||||||
|
|
||||||
|
\return \c true if the shelf accepts the replicants dragged into it,
|
||||||
|
or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::SetAllowsDragging(bool state)
|
||||||
|
\brief Allows or disallows the shelf to accept the replicants dragged
|
||||||
|
into it by the user.
|
||||||
|
|
||||||
|
\param[in] state \c true to allow dragging, or \c false to disallow it.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::AllowsZombies() const
|
||||||
|
\brief Checks if zombie views are allowed in the shelf.
|
||||||
|
|
||||||
|
\return \c true if the shelf allows zombie views, or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::SetAllowsZombies(bool state)
|
||||||
|
\brief Sets the shelf to allow zombie views or not.
|
||||||
|
|
||||||
|
\param state \c true if zombie views are allowed, or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::DisplaysZombies() const
|
||||||
|
\brief Checks if zombie views are displayed on the shelf.
|
||||||
|
|
||||||
|
\return \c true if the shelf displays zombie views, or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::SetDisplaysZombies(bool state)
|
||||||
|
\brief Sets the shelf to display zombie views or not.
|
||||||
|
|
||||||
|
\param state \c true if zombie views are displayed, or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::IsTypeEnforced() const
|
||||||
|
\brief Checks if the shelf enforces the type or not.
|
||||||
|
|
||||||
|
\return \c true if the shelf enforces the type filtering,
|
||||||
|
or \c false otherwise.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::SetTypeEnforced(bool state)
|
||||||
|
\brief Sets the type enforcement flag.
|
||||||
|
|
||||||
|
\param state \c true to enforce the type and reject replicants
|
||||||
|
without the same type, or \c false to disable the enforcement.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::SetSaveLocation(BDataIO* stream)
|
||||||
|
\brief Configures the save location of the shelf data to \a stream.
|
||||||
|
|
||||||
|
It also sets the "dirty" flag.
|
||||||
|
|
||||||
|
\retval B_OK The save location was set to \a stream.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::SetSaveLocation(const entry_ref* ref)
|
||||||
|
\brief Configures the save location of the shelf data to \a ref.
|
||||||
|
|
||||||
|
It also sets the "dirty" flag.
|
||||||
|
|
||||||
|
\retval B_OK The save location was set to \a ref.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BDataIO* BShelf::SaveLocation(entry_ref* ref) const
|
||||||
|
\brief Retrieves the save location for the shelf data.
|
||||||
|
|
||||||
|
If \a ref is not \c NULL, there it will be saved an entry_ref of the saving
|
||||||
|
location.
|
||||||
|
|
||||||
|
\return A BDataIO stream where the shelf data is saved, or \c NULL if the
|
||||||
|
saving location does not translate into a BDataIO.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::AddReplicant(BMessage* archive, BPoint location)
|
||||||
|
\brief Adds a replicant whose data is in \a archive to the shelf
|
||||||
|
in \a location.
|
||||||
|
|
||||||
|
This method is automatically called when a replicant is dropped on
|
||||||
|
the shelf.
|
||||||
|
|
||||||
|
If type enforcement is enabled, the replicant must have the same type,
|
||||||
|
otherwise it will be rejected.
|
||||||
|
|
||||||
|
\param archive The archive data from where the replicant information is
|
||||||
|
retrieved.
|
||||||
|
\param location The place where the replicant was dropped on the shelf.
|
||||||
|
|
||||||
|
\return A status code.
|
||||||
|
\retval B_ERROR One of these happened: \n- the replicant's type and
|
||||||
|
shelf's type does not match; \n- the replicant data was rejected by
|
||||||
|
CanAcceptReplicantMessage(); \n- the replicant only allows a unique
|
||||||
|
instance and there is already an instance of the replicant on the shelf;
|
||||||
|
\n- the object could not be instantiated and the archive did not
|
||||||
|
contain an instantiated BView; \n- the replicant could not be loaded, and
|
||||||
|
the creation of a zombie view was disabled.
|
||||||
|
\retval B_OK The replicant was added successfully.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::DeleteReplicant(BView* replicant)
|
||||||
|
\brief Removes the replicant referred by the \a replicant BView.
|
||||||
|
|
||||||
|
\param[in] replicant The view identified by the \a replicant BView.
|
||||||
|
|
||||||
|
\return A status code.
|
||||||
|
\retval B_OK The replicant was removed successfully.
|
||||||
|
\retval B_BAD_VALUE There is no replicant identified by such BView.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::DeleteReplicant(BMessage* archive)
|
||||||
|
\brief Removes the replicant identified by the \a archive
|
||||||
|
replicant message.
|
||||||
|
|
||||||
|
\param[in] archive The replicant's data archive of reference.
|
||||||
|
|
||||||
|
\return A status code.
|
||||||
|
\retval B_OK The replicant was removed successfully.
|
||||||
|
\retval B_BAD_VALUE There is no replicant identified by such message.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BShelf::DeleteReplicant(int32 index)
|
||||||
|
\brief Removes the replicant identified by \a index.
|
||||||
|
|
||||||
|
\param[in] index The replicant's index number.
|
||||||
|
|
||||||
|
\return A status code.
|
||||||
|
\retval B_OK The replicant was removed successfully.
|
||||||
|
\retval B_BAD_INDEX There is no replicant identified by such index.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BShelf::CountReplicants() const
|
||||||
|
\brief Tells the number of replicants currently contained by the shelf.
|
||||||
|
|
||||||
|
\return The number of attached replicants.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BMessage* BShelf::ReplicantAt(int32 index, BView** view = NULL,
|
||||||
|
uint32* uid = NULL,
|
||||||
|
status_t* perr = NULL) const
|
||||||
|
\brief Retrieves the replicant data referenced by its \a index.
|
||||||
|
|
||||||
|
\param[in] index The replicant index.
|
||||||
|
\param[out] view If not \c NULL, returns the respective BView of
|
||||||
|
the replicant at \a index, or \c NULL otherwise.
|
||||||
|
\param[out] uid If not \c NULL, returns the unique identifier of
|
||||||
|
the replicant at \a index, or \code ~(uint32)0 \endcode
|
||||||
|
(maximum value of an unsigned integer) otherwise.
|
||||||
|
\param[out] perr If not \c NULL, returns the replicant's current
|
||||||
|
status code (usually B_OK if everything is OK), or
|
||||||
|
\c B_BAD_INDEX otherwise.
|
||||||
|
|
||||||
|
\return A replicant's data message, or NULL if there is not a
|
||||||
|
replicant at such \a index.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BShelf::IndexOf(const BView* replicantView) const
|
||||||
|
\brief Returns the index of a replicant identified by its
|
||||||
|
\a replicantView view.
|
||||||
|
|
||||||
|
\param[in] replicantView The replicant's BView.
|
||||||
|
|
||||||
|
\return The index of the specified replicant, or \c -1 if
|
||||||
|
it does not exist.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BShelf::IndexOf(const BMessage* archive) const
|
||||||
|
\brief Returns the index of a replicant identified by its
|
||||||
|
\a archive replicant message.
|
||||||
|
|
||||||
|
\param[in] archive The replicant's message archive.
|
||||||
|
|
||||||
|
\return The index of the specified replicant, or \c -1 if
|
||||||
|
it does not exist.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BShelf::IndexOf(uint32 id) const
|
||||||
|
\brief Returns the index of a replicant identified by its
|
||||||
|
unique identifier \a id.
|
||||||
|
|
||||||
|
\param[in] id The replicant's unique identifier.
|
||||||
|
|
||||||
|
\return The index of the specified replicant, or \c -1 if
|
||||||
|
it does not exist.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::CanAcceptReplicantMessage(BMessage* archive) const
|
||||||
|
\brief Determines if the \a archive message where the replicant should
|
||||||
|
be contained is formatted as expected.
|
||||||
|
|
||||||
|
It is called during the execution of AddReplicant().
|
||||||
|
|
||||||
|
An undesired format of the message makes it to return to false and
|
||||||
|
discard it.
|
||||||
|
|
||||||
|
\param[in] archive The replicant's message.
|
||||||
|
|
||||||
|
\retval true The replicant was accepted.
|
||||||
|
\retval false The replicant was rejected.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BShelf::CanAcceptReplicantView(BRect rect,
|
||||||
|
BView* view, BMessage* archive) const
|
||||||
|
\brief Determines whether the replicant's view is accepted or rejected.
|
||||||
|
|
||||||
|
It is called during the execution of AddReplicant().
|
||||||
|
|
||||||
|
If the view has not been accepted, the replicant will be rejected.
|
||||||
|
|
||||||
|
\param[in] rect The rect that the replicant will occupy on the shelf.
|
||||||
|
\param[in] view The replicant's view.
|
||||||
|
\param[in] archive The replicant's archived message.
|
||||||
|
|
||||||
|
\retval true The replicant was accepted.
|
||||||
|
\retval false The replicant was rejected.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BPoint BShelf::AdjustReplicantBy(BRect rect, BMessage* archive) const
|
||||||
|
\brief Adjusts the replicant's location to fit the rect in the shelf.
|
||||||
|
|
||||||
|
Called upon a replicant was dropped on the shelf.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BShelf::ReplicantDeleted(int32 index,
|
||||||
|
const BMessage* archive,
|
||||||
|
const BView *replicant)
|
||||||
|
\brief Unimplemented.
|
||||||
|
|
||||||
|
\since BeOS R3
|
||||||
|
*/
|
||||||
Reference in New Issue
Block a user