A container attached to a BView that accepts BDragger objects (replicants). More...

Inherits BHandler.

Public Member Functions
	BShelf (BDataIO stream, BView view, bool allowDrags=true, const char *shelfType=NULL)
	Creates a BShelf object that is attached to a view, and sets stream as the data stream source from where to load the archived BDragger objects and where to save them.

	BShelf (BMessage *archive)
	Unimplemented.

	BShelf (BView view, bool allowDrags=true, const char shelfType=NULL)
	Creates a BShelf object that is attached to a view.

	BShelf (const entry_ref ref, BView view, bool allowDrags=true, const char *shelfType=NULL)
	Creates a BShelf object that is attached to a view, and sets ref as the source from where to load the archived BDragger objects and where to save them.

virtual	~BShelf ()
	The destructor calls Save(), frees the data sources and replicant data of the replicants and detaches itself from the container BView.

status_t	AddReplicant (BMessage *archive, BPoint location)
	Adds a replicant whose data is in archive to the shelf in location.

bool	AllowsDragging () const
	Check if the user is able to drag replicants to the shelf.

bool	AllowsZombies () const
	Checks if zombie views are allowed in the shelf.

int32	CountReplicants () const
	Tells the number of replicants currently contained by the shelf.

status_t	DeleteReplicant (BMessage *archive)
	Removes the replicant identified by the archive replicant message.

status_t	DeleteReplicant (BView *replicant)
	Removes the replicant referred by the replicant BView.

status_t	DeleteReplicant (int32 index)
	Removes the replicant identified by index.

bool	DisplaysZombies () const
	Checks if zombie views are displayed on the shelf.

virtual status_t	GetSupportedSuites (BMessage *data)
	Report the suites of messages this control understands.

int32	IndexOf (const BMessage *archive) const
	Returns the index of a replicant identified by its archive replicant message.

int32	IndexOf (const BView *replicantView) const
	Returns the index of a replicant identified by its replicantView view.

int32	IndexOf (uint32 id) const
	Returns the index of a replicant identified by its unique identifier id.

bool	IsDirty () const
	Retrieves the "dirty" flag status of the shelf.

bool	IsTypeEnforced () const
	Checks if the shelf enforces the type or not.

virtual void	MessageReceived (BMessage *message)
	Handle message received by the associated looper.

virtual status_t	Perform (perform_code code, void *data)
	Perform some action (Internal method defined for binary compatibility purposes).

BMessage *	ReplicantAt (int32 index, BView *view=NULL, uint32 uid=NULL, status_t *perr=NULL) const
	Retrieves the replicant data referenced by its index.

virtual BHandler *	ResolveSpecifier (BMessage message, int32 index, BMessage specifier, int32 form, const char *property)
	Determine the proper handler for a scripting message.

status_t	Save ()
	Saves the BShelf contents as an archived BMessage into a filesystem entry or BDataIO stream if any of them were specified with the constructor.

BDataIO *	SaveLocation (entry_ref *ref) const
	Retrieves the save location for the shelf data.

void	SetAllowsDragging (bool state)
	Allows or disallows the shelf to accept the replicants dragged into it by the user.

void	SetAllowsZombies (bool state)
	Sets the shelf to allow zombie views or not.

virtual void	SetDirty (bool state)
	Sets the "dirty" state flag. This flag is used by the application and is also automatically applied when the save location is changed.

void	SetDisplaysZombies (bool state)
	Sets the shelf to display zombie views or not.

status_t	SetSaveLocation (BDataIO *stream)
	Configures the save location of the shelf data to stream.

status_t	SetSaveLocation (const entry_ref *ref)
	Configures the save location of the shelf data to ref.

void	SetTypeEnforced (bool state)
	Sets the type enforcement flag.

Public Member Functions inherited from BHandler
	BHandler (const char *name=NULL)
	Construct a new handler with a name.

virtual	~BHandler ()
	Free the filters of this handler, as well as the list of observers.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

	BHandler (BMessage *data)
	Construct a handler from an archived message.

BLooper *	Looper () const
	Return a pointer to the looper that this handler is associated with.

void	SetName (const char *name)
	Set or change the name of this handler.

const char *	Name () const
	Return the name of this handler.

virtual void	SetNextHandler (BHandler *handler)
	Set the next handler in the chain that the message is passed on to if this handler cannot process it.

BHandler *	NextHandler () const
	Return the next hander in the chain to which the message is passed on.

virtual void	AddFilter (BMessageFilter *filter)
	Add filter as a prerequisite to this handler.

virtual bool	RemoveFilter (BMessageFilter *filter)
	Remove filter from the filter list.

virtual void	SetFilterList (BList *filters)
	Set the internal list of filters to filters.

BList *	FilterList ()
	Return a pointer to the list of filters.

bool	LockLooper ()
	Lock the looper associated with this handler.

status_t	LockLooperWithTimeout (bigtime_t timeout)
	Lock the looper associated with this handler, with a time out value.

void	UnlockLooper ()
	Unlock the looper.

status_t	StartWatching (BMessenger target, uint32 what)
	Subscribe this handler to watch a specific state change of a target.

status_t	StartWatchingAll (BMessenger target)
	Subscribe this handler to watch a target for all events.

status_t	StopWatching (BMessenger target, uint32 what)
	Unsubscribe this handler from watching a specific state.

status_t	StopWatchingAll (BMessenger target)
	Unsubscribe this handler from watching all states.

status_t	StartWatching (BHandler *observer, uint32 what)
	Subscribe an observer for a specific state change of this handler.

status_t	StartWatchingAll (BHandler *observer)
	Subscribe an observer for a all state changes.

status_t	StopWatching (BHandler *observer, uint32 what)
	Unsubscribe an observer from watching a specific state.

status_t	StopWatchingAll (BHandler *observer)
	Unsubscribe an observer from watching all states.

virtual void	SendNotices (uint32 what, const BMessage *notice=NULL)
	Emit a state change to the observers.

bool	IsWatched () const
	Check if there are any observers watching this handler.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

Protected Member Functions
virtual BPoint	AdjustReplicantBy (BRect, BMessage *) const
	Adjusts the replicant's location to fit the rect in the shelf.

virtual bool	CanAcceptReplicantMessage (BMessage *archive) const
	Determines if the archive message where the replicant should be contained is formatted as expected.

virtual bool	CanAcceptReplicantView (BRect, BView , BMessage ) const
	Determines whether the replicant's view is accepted or rejected.

virtual void	ReplicantDeleted (int32 index, const BMessage archive, const BView replicant)
	Unimplemented.

Archiving
virtual status_t	Archive (BMessage *archive, bool deep=true) const
	Unimplemented.

static BArchivable *	Instantiate (BMessage *archive)
	Unimplemented.

Additional Inherited Members
Static Public Member Functions inherited from BHandler
static BArchivable *	Instantiate (BMessage *data)
	Static method to instantiate a handler from an archived message.

Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

Detailed Description

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 shelfType parameter from the constructors allows the shelf to have a filter-like system. This is reflected in the archived field 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

Constructor & Destructor Documentation

◆ BShelf() [1/4]

BShelf::BShelf	(	BView *	view,
		bool	allowDrags = `true`,
		const char *	shelfType = `NULL`
	)

Creates a BShelf object that is attached to a view.

Parameters

[in]	view	The container BView.
[in]	allowDrags	Specifies if the shelf accepts replicants dragged to it by the user or not.
[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

◆ BShelf() [2/4]

BShelf::BShelf	(	const entry_ref *	ref,
		BView *	view,
		bool	allowDrags = `true`,
		const char *	shelfType = `NULL`
	)

Creates a BShelf object that is attached to a view, and sets ref as the source from where to load the archived BDragger objects and where to save them.

Parameters

[in]	ref	The filesystem entry from where the archived BDragger objects will be loaded during the initialization and saved.
[in]	view	The container BView.
[in]	allowDrags	Specifies if the shelf accepts replicants dragged to it by the user or not.
[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

◆ BShelf() [3/4]

BShelf::BShelf	(	BDataIO *	stream,
		BView *	view,
		bool	allowDrags = `true`,
		const char *	shelfType = `NULL`
	)

Creates a BShelf object that is attached to a view, and sets stream as the data stream source from where to load the archived BDragger objects and where to save them.

Parameters

[in]	stream	The data stream from where the archived BDragger objects will be loaded during the initialization and saved.
[in]	view	The container BView.
[in]	allowDrags	Specifies if the shelf accepts replicants dragged to it by the user or not.
[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

◆ BShelf() [4/4]

BShelf::BShelf ( BMessage * archive )

Unimplemented.

Since: BeOS R3

◆ ~BShelf()

BShelf::~BShelf ( )

virtual

The destructor calls Save(), frees the data sources and replicant data of the replicants and detaches itself from the container BView.

Since: BeOS R3

Member Function Documentation

◆ AddReplicant()

status_t BShelf::AddReplicant	(	BMessage *	archive,
		BPoint	location
	)

Adds a replicant whose data is in archive to the shelf in 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.

Parameters

archive	The archive data from where the replicant information is retrieved.
location	The place where the replicant was dropped on the shelf.

Returns: A status code.

Return values

B_ERROR One of these happened:
- the replicant's type and shelf's type does not match;
- the replicant data was rejected by CanAcceptReplicantMessage();
- the replicant only allows a unique instance and there is already an instance of the replicant on the shelf;
- the object could not be instantiated and the archive did not contain an instantiated BView;
- the replicant could not be loaded, and the creation of a zombie view was disabled.

B_OK The replicant was added successfully.

Since: BeOS R3

◆ AdjustReplicantBy()

BPoint BShelf::AdjustReplicantBy	(	BRect	rect,
		BMessage *	archive
	)		const

protectedvirtual

Adjusts the replicant's location to fit the rect in the shelf.

Called upon a replicant was dropped on the shelf.

Since: BeOS R3

◆ AllowsDragging()

bool BShelf::AllowsDragging ( ) const

Check if the user is able to drag replicants to the shelf.

Returns: true if the shelf accepts the replicants dragged into it, or false otherwise.

Since: BeOS R3

◆ AllowsZombies()

bool BShelf::AllowsZombies ( ) const

Checks if zombie views are allowed in the shelf.

Returns: true if the shelf allows zombie views, or false otherwise.

Since: BeOS R3

◆ Archive()

status_t BShelf::Archive	(	BMessage *	archive,
		bool	deep = `true`
	)		const

virtual

Unimplemented.

Since: BeOS R3

Reimplemented from BHandler.

◆ CanAcceptReplicantMessage()

bool BShelf::CanAcceptReplicantMessage ( BMessage * archive ) const

protectedvirtual

Determines if the 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.

Parameters

[in] archive The replicant's message.

Return values

true	The replicant was accepted.
false	The replicant was rejected.

Since: BeOS R3

◆ CanAcceptReplicantView()

bool BShelf::CanAcceptReplicantView	(	BRect	rect,
		BView *	view,
		BMessage *	archive
	)		const

protectedvirtual

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.

Parameters

[in]	rect	The rect that the replicant will occupy on the shelf.
[in]	view	The replicant's view.
[in]	archive	The replicant's archived message.

Return values

true	The replicant was accepted.
false	The replicant was rejected.

Since: BeOS R3

◆ CountReplicants()

int32 BShelf::CountReplicants ( ) const

Tells the number of replicants currently contained by the shelf.

Returns: The number of attached replicants.

Since: BeOS R3

◆ DeleteReplicant() [1/3]

status_t BShelf::DeleteReplicant ( BMessage * archive )

Removes the replicant identified by the archive replicant message.

Parameters

[in] archive The replicant's data archive of reference.

Returns: A status code.

Return values

B_OK	The replicant was removed successfully.
B_BAD_VALUE	There is no replicant identified by such message.

Since: BeOS R3

◆ DeleteReplicant() [2/3]

status_t BShelf::DeleteReplicant ( BView * replicant )

Removes the replicant referred by the replicant BView.

Parameters

[in] replicant The view identified by the replicant BView.

Returns: A status code.

Return values

B_OK	The replicant was removed successfully.
B_BAD_VALUE	There is no replicant identified by such BView.

Since: BeOS R3

◆ DeleteReplicant() [3/3]

status_t BShelf::DeleteReplicant ( int32 index )

Removes the replicant identified by index.

Parameters

[in] index The replicant's index number.

Returns: A status code.

Return values

B_OK	The replicant was removed successfully.
B_BAD_INDEX	There is no replicant identified by such index.

Since: BeOS R3

◆ DisplaysZombies()

bool BShelf::DisplaysZombies ( ) const

Checks if zombie views are displayed on the shelf.

Returns: true if the shelf displays zombie views, or false otherwise.

Since: BeOS R3

◆ GetSupportedSuites()

status_t BShelf::GetSupportedSuites ( BMessage * data )

virtual

Report the suites of messages this control understands.

Adds the string "suite/vnd.Be-shelf" to the message.

See also: BHandler::GetSupportedSuites()

Since: BeOS R3

Reimplemented from BHandler.

◆ IndexOf() [1/3]

int32 BShelf::IndexOf ( const BMessage * archive ) const

Returns the index of a replicant identified by its archive replicant message.

Parameters

[in] archive The replicant's message archive.

Returns: The index of the specified replicant, or -1 if it does not exist.

Since: BeOS R3

◆ IndexOf() [2/3]

int32 BShelf::IndexOf ( const BView * replicantView ) const

Returns the index of a replicant identified by its replicantView view.

Parameters

[in] replicantView The replicant's BView.

Returns: The index of the specified replicant, or -1 if it does not exist.

Since: BeOS R3

◆ IndexOf() [3/3]

int32 BShelf::IndexOf ( uint32 id ) const

Returns the index of a replicant identified by its unique identifier id.

Parameters

[in] id The replicant's unique identifier.

Returns: The index of the specified replicant, or -1 if it does not exist.

Since: BeOS R3

◆ Instantiate()

BArchivable * BShelf::Instantiate ( BMessage * archive )

static

Unimplemented.

Since: BeOS R3

◆ IsDirty()

bool BShelf::IsDirty ( ) const

Retrieves the "dirty" flag status of the shelf.

Returns: true if the shelf is "dirty", or false otherwise.

See also: SetDirty(bool)

Since: BeOS R3

◆ IsTypeEnforced()

bool BShelf::IsTypeEnforced ( ) const

Checks if the shelf enforces the type or not.

Returns: true if the shelf enforces the type filtering, or false otherwise.

Since: BeOS R3

◆ MessageReceived()

void BShelf::MessageReceived ( BMessage * message )

virtual

Handle message received by the associated looper.

Parameters

message The message received by the associated looper.

See also: BHandler::MessageReceived()

Since: BeOS R3

Reimplemented from BHandler.

◆ Perform()

virtual status_t BShelf::Perform	(	perform_code	d,
		void *	arg
	)

virtual

Perform some action (Internal method defined for binary compatibility purposes).

Reimplemented from BHandler.

◆ ReplicantAt()

BMessage * BShelf::ReplicantAt	(	int32	index,
		BView **	view = `NULL`,
		uint32 *	uid = `NULL`,
		status_t *	perr = `NULL`
	)		const

Retrieves the replicant data referenced by its index.

Parameters

[in]	index	The replicant index.
[out]	view	If not `NULL`, returns the respective BView of the replicant at index, or `NULL` otherwise.
[out]	uid	If not `NULL`, returns the unique identifier of the replicant at index, or ~(uint32)0 uint32 __haiku_uint32 uint32 4-bytes unsigned integer. Definition: SupportDefs.h:25 (maximum value of an unsigned integer) otherwise.
[out]	perr	If not `NULL`, returns the replicant's current status code (usually B_OK if everything is OK), or `B_BAD_INDEX` otherwise.

Returns: A replicant's data message, or NULL if there is not a replicant at such index.

Since: BeOS R3

◆ ReplicantDeleted()

void BShelf::ReplicantDeleted	(	int32	index,
		const BMessage *	archive,
		const BView *	replicant
	)

protectedvirtual

Unimplemented.

Since: BeOS R3

◆ ResolveSpecifier()

virtual BHandler * BShelf::ResolveSpecifier	(	BMessage *	message,
		int32	index,
		BMessage *	specifier,
		int32	what,
		const char *	property
	)

virtual

Determine the proper handler for a scripting message.

Parameters

message	The scripting message to determine the handler.
index	The index of the specifier.
specifier	The message which contains the specifier.
what	The 'what' field of the specifier message.
property	The name of the target property.

Returns: A pointer to the proper BHandler for the given scripting message.

Since: BeOS R3

Reimplemented from BHandler.

◆ Save()

status_t BShelf::Save ( )

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().

Returns: A status code.

Return values

B_OK	The operation was performed successfully.
B_ERROR	The archiving operation failed, or there was not any data destination specified.

Since: BeOS R3

◆ SaveLocation()

BDataIO * BShelf::SaveLocation ( entry_ref * ref ) const

Retrieves the save location for the shelf data.

If ref is not NULL, there it will be saved an entry_ref of the saving location.

Returns: A BDataIO stream where the shelf data is saved, or NULL if the saving location does not translate into a BDataIO.

Since: BeOS R3

◆ SetAllowsDragging()

void BShelf::SetAllowsDragging ( bool state )

Allows or disallows the shelf to accept the replicants dragged into it by the user.

Parameters

[in] state true to allow dragging, or false to disallow it.

Since: BeOS R3

◆ SetAllowsZombies()

void BShelf::SetAllowsZombies ( bool state )

Sets the shelf to allow zombie views or not.

Parameters

state true if zombie views are allowed, or false otherwise.

Since: BeOS R3

◆ SetDirty()

void BShelf::SetDirty ( bool state )

virtual

Sets the "dirty" state flag. This flag is used by the application and is also automatically applied when the save location is changed.

Parameters

state true to set it as "dirty", or false to remove the flag.

See also: IsDirty()

Since: BeOS R3

◆ SetDisplaysZombies()

void BShelf::SetDisplaysZombies ( bool state )

Sets the shelf to display zombie views or not.

Parameters

state true if zombie views are displayed, or false otherwise.

Since: BeOS R3

◆ SetSaveLocation() [1/2]

status_t BShelf::SetSaveLocation ( BDataIO * stream )

Configures the save location of the shelf data to stream.

It also sets the "dirty" flag.

Return values

B_OK	The save location was set to stream.

Since: BeOS R3

◆ SetSaveLocation() [2/2]

status_t BShelf::SetSaveLocation ( const entry_ref * ref )

Configures the save location of the shelf data to ref.

It also sets the "dirty" flag.

Return values

B_OK	The save location was set to ref.

Since: BeOS R3

◆ SetTypeEnforced()

void BShelf::SetTypeEnforced ( bool state )

Sets the type enforcement flag.

Parameters

state true to enforce the type and reject replicants without the same type, or false to disable the enforcement.

Since: BeOS R3

Public Member Functions

Protected Member Functions

Archiving

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BShelf() [1/4]

◆ BShelf() [2/4]

◆ BShelf() [3/4]

◆ BShelf() [4/4]

◆ ~BShelf()

Member Function Documentation

◆ AddReplicant()

◆ AdjustReplicantBy()

◆ AllowsDragging()

◆ AllowsZombies()

◆ Archive()

◆ CanAcceptReplicantMessage()

◆ CanAcceptReplicantView()

◆ CountReplicants()

◆ DeleteReplicant() [1/3]

◆ DeleteReplicant() [2/3]

◆ DeleteReplicant() [3/3]

◆ DisplaysZombies()

◆ GetSupportedSuites()

◆ IndexOf() [1/3]

◆ IndexOf() [2/3]

◆ IndexOf() [3/3]

◆ Instantiate()

◆ IsDirty()

◆ IsTypeEnforced()

◆ MessageReceived()

◆ Perform()

◆ ReplicantAt()

◆ ReplicantDeleted()

◆ ResolveSpecifier()

◆ Save()

◆ SaveLocation()

◆ SetAllowsDragging()

◆ SetAllowsZombies()

◆ SetDirty()

◆ SetDisplaysZombies()

◆ SetSaveLocation() [1/2]

◆ SetSaveLocation() [2/2]

◆ SetTypeEnforced()