i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update App Kit Documentation.

Browse Source 
The biggest change is the addition of \since to each method. I've gone
through old versions of the BeBook and documented what version of BeOS
each method was introduced in. I'm only counting production releases
so I'm starting with BeOS R3 ignoring all DR and PR releases. Likewise,
all methods new to Haiku are listed as being introduced \since Haiku R1
ignoring alpha releases.
This commit is contained in:
John Scipione
2014-06-11 16:25:57 -04:00
parent 1c52b28f3e
commit ac9714d8a4
8 changed files with 1813 additions and 778 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/app/Application.dox
+124 -45
View File
@@ -1,13 +1,13 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/app/Application.h rev 42794
* src/kits/app/Application.cpp rev 42794
* headers/os/app/Application.h hrev47355
* src/kits/app/Application.cpp hrev47355
*/
@@ -19,6 +19,22 @@
*/
/*!
\var be_app
\brief Global system app object.
\since BeOS R3
*/
/*!
\var be_app_messenger
\brief Global system app messenger object.
\since BeOS R3
*/
/*!
\class BApplication
\ingroup app
@@ -45,7 +61,7 @@
Typically, you initialize the BApplication object in the programs main()
function. A typical main() function looks something like this:
\code
\code
#include Application.h
main()
@@ -57,12 +73,14 @@ main()
return 0;
}
\endcode
\endcode
\since BeOS R3
*/
/*!
\fn BApplication::BApplication(const char *signature)
\fn BApplication::BApplication(const char* signature)
\brief Initialize a BApplication with the passed in \a signature.
The new BApplication is, by default, not running yet. If you have
@@ -72,13 +90,15 @@ main()
errors.
\param signature The \a signature of the application.
\since BeOS R3
*/
/*!
\fn BApplication::BApplication(const char *signature, status_t *_error)
\fn BApplication::BApplication(const char* signature, status_t* _error)
\brief Initialize a BApplication with the passed in \a signature and a
pointer to an error message.
pointer to an error message.
Any error that occurs while constructing the BApplication will be
set to the \a _error pointer. If \a _error points to a \c status_t
@@ -90,6 +110,8 @@ main()
\param signature The \a signature of the application.
\param _error A pointer to a \c status_t set by the BApplication
constructor.
\since BeOS R5
*/
/*!
@@ -97,7 +119,9 @@ main()
\brief Returns the status of the constructor.
\returns If initialization succeeded returns \c B_OK, otherwise returns an
error status.
error status.
\since BeOS R5
*/
@@ -110,21 +134,25 @@ main()
/*!
\fn BApplication::BApplication(BMessage *data)
\fn BApplication::BApplication(BMessage* data)
\brief Initialize a BApplication object from a message.
The message must contain the signature of the application you wish to
initialize in the "mime_sig" variable.
\param data The message to initialize the BApplication from.
\since BeOS R3
*/
/*!
\fn status_t BApplication::Archive(BMessage *data, bool deep) const
\fn status_t BApplication::Archive(BMessage* data, bool deep) const
\brief Archive the BApplication object into a BMessage.
\sa BArchivable::Archive()
\since BeOS R3
*/
@@ -133,6 +161,8 @@ main()
\brief Restores the BApplication object from a BMessage.
\sa BArchivable::Instantiate()
\since BeOS R3
*/
@@ -142,6 +172,8 @@ main()
/*!
\fn BApplication::~BApplication()
\brief Destructor Method
\since BeOS R3
*/
@@ -156,17 +188,20 @@ main()
/*!
\fn thread_id BApplication::Run()
\brief Starts the message loop in the thread that it is called from,
and doesn't return until the message loop stops. Run() does not spawn
a new thread.
and doesn't return until the message loop stops.
\returns the thread_id of the thread that the BApplication is called from.
Run() does not spawn a new thread.
\return The thread_id of the thread that the BApplication is called from.
\since BeOS R3
*/
/*!
\fn void BApplication::Quit()
\brief Tells the thread to finish processing the message queue, disallowing
any new messages.
any new messages.
Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait
for the message queue to empty. Run() will be then able to return.
@@ -175,6 +210,8 @@ main()
should delete the BApplication object yourself one Run() returns.
However Quit() does delete the object if it's called before the message loop
starts i.e. before Run() is called.
\since BeOS R3
*/
@@ -192,7 +229,7 @@ main()
/*!
\fn bool BApplication::QuitRequested()
\brief Hook method that gets invoked when the BApplication receives a
\c B_QUIT_REQUESTED message.
\c B_QUIT_REQUESTED message.
BApplication sends a QuitRequested() message to each of its BWindow objects.
If all of the BWindow s return \c true then the windows are
@@ -200,15 +237,17 @@ main()
\c true. If any of the BWindow returns \c false, the BWindow s
are not destroyed and QuitRequested() returns \c false.
\retval true The application quit.
\retval false The application failed to quit.
\return \c true if the application quit or \c false if the
application failed to quit.
\since BeOS R3
*/
/*!
\fn void BApplication::ReadyToRun()
\brief Hook method that's invoked when the BApplication receives a
\c B_READY_TO_RUN message.
\c B_READY_TO_RUN message.
The ReadyToRun() method is automatically called by the Run() method. It is
sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED messages
@@ -219,13 +258,15 @@ main()
ReadyToRun() method to do whatever you want to do. If you haven't
constructed any windows in your application yet then this would be a good
place to do so.
\since BeOS R3
*/
/*!
\fn void BApplication::ArgvReceived(int32 argc, char **argv)
\fn void BApplication::ArgvReceived(int32 argc, char** argv)
\brief Hook method that gets invoked when the application receives a
\c B_ARGV_RECEIVED message.
\c B_ARGV_RECEIVED message.
If command line arguments are specified when the application is launched
from the the shell, or if \c argv/argc values are passed to
@@ -251,6 +292,8 @@ main()
generate a \c B_ARGV_RECEIVED message and send it to the already running
instance. Thus in this case the \c B_ARGV_RECEIVED message can show
up at any time.
\since BeOS R3
*/
@@ -270,13 +313,15 @@ main()
This method is called after ReadyToRun() provided the application is
displaying a window that can be set active.
\since BeOS R3
*/
/*!
\fn void BApplication::RefsReceived(BMessage *message)
\fn void BApplication::RefsReceived(BMessage* message)
\brief Hook method that gets invoked when the application receives a
\c B_REFS_RECEIVED message.
\c B_REFS_RECEIVED message.
The message is sent in response to a user action such as a user
drag-and-dropping a file on your app's icon or opening a file that the
@@ -288,20 +333,24 @@ main()
something with the received refs. Typically you create BEntry or BFile
objects from the passed in refs.
\param message contains a single field named "be:refs" that contains one or
more entry_ref (\c B_REF_TYPE) items, one for each file sent.
\param message contains a single field named "be:refs" that contains one
or more entry_ref (\c B_REF_TYPE) items, one for each file sent.
\since BeOS R3
*/
/*!
\fn void BApplication::AboutRequested()
\brief Hook method that gets invoked when the BApplication receives a
\c B_ABOUT_REQUESTED message.
\c B_ABOUT_REQUESTED message.
You should override this method to pop an alert to provide information
about the application.
The default implementation pops a basic alert dialog.
\since BeOS R3
*/
@@ -319,18 +368,24 @@ main()
/*!
\fn BApplication::ShowCursor()
\brief Restores the cursor.
\since BeOS R3
*/
/*!
\fn void BApplication::HideCursor()
\brief Hides the cursor from the screen.
\since BeOS R3
*/
/*!
\fn void BApplication::ObscureCursor()
\brief Hides the cursor until the mouse is moved.
\since BeOS R3
*/
@@ -339,11 +394,13 @@ main()
\brief Returns whether or not the cursor is hidden.
\returns \c true if the cursor is hidden, \c false if not.
\since BeOS R3
*/
/*!
\fn void BApplication::SetCursor(const void *cursor)
\fn void BApplication::SetCursor(const void* cursor)
\brief Sets the \a cursor to be used when the application is active.
You can pass one of the pre-defined cursor constants such as
@@ -352,19 +409,23 @@ main()
class.
\param cursor The cursor data to set the cursor to.
\since BeOS R3
*/
/*!
\fn void BApplication::SetCursor(const BCursor *cursor, bool sync)
\fn void BApplication::SetCursor(const BCursor* cursor, bool sync)
\brief Sets the \a cursor to be used when the application is active
with \a sync immediately option.
with \a sync immediately option.
The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand
cursor and \c B_CURSOR_I_BEAM for the I-beam cursor.
\param cursor A BCursor object to set the \a cursor to.
\param sync synchronize the cursor immediately.
\since BeOS R5
*/
@@ -384,13 +445,15 @@ main()
\brief Returns the number of windows created by the application.
\returns the number of windows created by the application.
\since BeOS R3
*/
/*!
\fn BWindow* BApplication::WindowAt(int32 index) const
\brief Returns the BWindow object at the specified \a index in the
application's window list.
application's window list.
If \a index is out of range, this function returns \c NULL.
@@ -399,7 +462,9 @@ main()
\param index The \a index of the desired BWindow.
\returns The BWindow object at the specified \a index or \c NULL
if the \a index is out of range.
if the \a index is out of range.
\since BeOS R3
*/
@@ -410,18 +475,22 @@ main()
\warning This method may return \c B_ERROR.
\returns The number of BLoopers in the application.
\since BeOS R5
*/
/*!
\fn BLooper* BApplication::LooperAt(int32 index) const
\brief Returns the BLooper object at the specified index in the
application's looper list.
application's looper list.
If index is out of range, this function returns \c NULL.
\returns The BLooper object at the specified \a index or \c NULL
if the \a index is out of range.
if the \a index is out of range.
\since BeOS R5
*/
@@ -439,17 +508,19 @@ main()
/*!
\fn bool BApplication::IsLaunching() const
\brief Returns whether or not the application is in the process of
launching.
launching.
\returns \c true if the application is launching, \c false if the
application is already running.
application is already running.
\since BeOS R3
*/
/*!
\fn status_t BApplication::GetAppInfo(app_info *info) const
\brief Fills out the \a info parameter with information about the
application.
application.
This is equivalent to
be_roster->GetRunningAppInfo(be_app->Team(), info);
@@ -457,12 +528,16 @@ main()
\returns \c B_NO_INIT on an error or \c B_OK if all goes well.
\sa BRoster::GetAppInfo()
\since BeOS R3
*/
/*!
\fn BResources* BApplication::AppResources()
\brief Returns a BResources object for the application.
\since BeOS R5
*/
@@ -479,14 +554,14 @@ main()
/*!
\fn void BApplication::MessageReceived(BMessage *message)
\sa BHandler::MessageReceived()
\copydoc BHandler::MessageReceived()
*/
/*!
\fn void BApplication::DispatchMessage(BMessage *message,
BHandler *handler)
\sa BLooper::DispatchMessage()
\copydoc BLooper::DispatchMessage()
*/
@@ -504,7 +579,7 @@ main()
/*!
\fn void BApplication::Pulse()
\brief Hook method that gets invoked when the BApplication receives a
\c B_PULSE message.
\c B_PULSE message.
An action is performed each time app_server calls the Pulse() method.
The pulse rate is set by SetPulseRate(). You can implement Pulse() to do
@@ -512,6 +587,8 @@ main()
is no better than once per 100,000 microseconds.
\sa SetPulseRate()
\since BeOS R3
*/
@@ -523,7 +600,9 @@ main()
The pulse rate can be no faster than once per 100,000 microseconds or so.
\param rate The rate at which \c B_PULSE messages are sent to the
application.
application.
\since BeOS R3
*/
@@ -539,15 +618,15 @@ main()
/*!
\fn BHandler* BApplication::ResolveSpecifier(BMessage *message, int32 index,
BMessage *specifier, int32 what, const char *property)
\sa BHandler::ResolveSpecifier()
\fn BHandler* BApplication::ResolveSpecifier(BMessage* message,
int32 index, BMessage *specifier, int32 what, const char *property)
\copydoc BHandler::ResolveSpecifier()
*/
/*!
\fn status_t BApplication::GetSupportedSuites(BMessage *data)
\sa BHandler::GetSupportedSuites()
\fn status_t BApplication::GetSupportedSuites(BMessage* data)
\copydoc BHandler::GetSupportedSuites()
*/
docs/user/app/Clipboard.dox
+50 -10
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,8 +7,8 @@
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/app/Clipboard.h rev 42274
* src/kits/app/Clipboard.cpp rev 42274
* headers/os/app/Clipboard.h hrev47355
* src/kits/app/Clipboard.cpp hrev47355
*/
@@ -23,6 +23,8 @@
/*!
\var be_clipboard
\brief Global system clipboard object.
\since BeOS R3
*/
@@ -97,11 +99,13 @@ if (be_clipboard->Lock()) {
} else
fprintf(stderr, "could not lock clipboard.\n");
\endcode
\since BeOS R3
*/
/*!
\fn BClipboard::BClipboard(const char *name, bool transient = false)
\fn BClipboard::BClipboard(const char* name, bool transient = false)
\brief Create a BClipboard object with the given \a name.
If the \a name parameter is \c NULL then the "system" BClipboard object
@@ -109,12 +113,16 @@ if (be_clipboard->Lock()) {
\param name The \a name of the clipboard.
\param transient If \c true, lose data after a reboot (currently unused).
\since BeOS R3
*/
/*!
\fn BClipboard::~BClipboard()
\brief Destroys the BClipboard object. The clipboard data is not destroyed.
\since BeOS R3
*/
@@ -123,11 +131,13 @@ if (be_clipboard->Lock()) {
\brief Returns the name of the BClipboard object.
\returns The name of the clipboard.
\since BeOS R3
*/
/*!
\name Commit Count Methods
\name Commit Count
*/
@@ -147,6 +157,8 @@ if (be_clipboard->Lock()) {
\return The number of commits to the clipboard.
\sa SystemCount()
\since BeOS R5
*/
@@ -164,6 +176,8 @@ if (be_clipboard->Lock()) {
\return The number of commits to the clipboard.
\sa LocalCount()
\since BeOS R5
*/
@@ -171,7 +185,7 @@ if (be_clipboard->Lock()) {
/*!
\name Monitoring Methods
\name Monitoring
*/
@@ -190,6 +204,8 @@ if (be_clipboard->Lock()) {
\retval B_ERROR An error occured.
\sa StopWatching()
\since BeOS R5
*/
@@ -202,6 +218,8 @@ if (be_clipboard->Lock()) {
\retval B_ERROR An error occurred.
\sa StartWatching()
\since BeOS R5
*/
@@ -209,7 +227,7 @@ if (be_clipboard->Lock()) {
/*!
\name Locking Methods
\name Locking
*/
@@ -219,13 +237,15 @@ if (be_clipboard->Lock()) {
/*!
\fn bool BClipboard::Lock()
\brief Locks the clipboard so that no other tread can read from it or
write to it.
write to it.
You should call Lock() before reading or writing to the clipboard.
\returns \c true if the clipboard was locked, \c false otherwise.
\sa Unlock()
\since BeOS R3
*/
@@ -234,6 +254,8 @@ if (be_clipboard->Lock()) {
\brief Unlocks the clipboard.
\sa Lock()
\since BeOS R3
*/
@@ -242,6 +264,8 @@ if (be_clipboard->Lock()) {
\brief Returns whether or not the clipboard is locked.
\returns \c true if the clipboard is locked, \c false if it is unlocked.
\since BeOS R5
*/
@@ -249,7 +273,7 @@ if (be_clipboard->Lock()) {
/*!
\name Clipboard Data Transaction Methods
\name Clipboard Data Transaction
*/
@@ -262,10 +286,13 @@ if (be_clipboard->Lock()) {
You should call Clear() before adding new data to the BClipboard object.
\return A status code.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_NO_MEMORY Ran out of memory initializing the data message.
\retval B_ERROR Another error occurred.
\since BeOS R3
*/
@@ -273,9 +300,12 @@ if (be_clipboard->Lock()) {
\fn status_t BClipboard::Commit()
\brief Commits the clipboard data to the BClipboard object.
\return A status code.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_ERROR Another error occurred.
\since BeOS R3
*/
@@ -287,9 +317,12 @@ if (be_clipboard->Lock()) {
\param failIfChanged Whether or not to fail to commit the changes
if there is a change in the clipboard data.
\return A status code.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_ERROR Another error occurred.
\since BeOS R5
*/
@@ -301,10 +334,13 @@ if (be_clipboard->Lock()) {
clipboard data message and then decide to revert the change instead of
committing it.
\return A status code.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_NO_MEMORY Ran out of memory initializing the data message.
\retval B_ERROR Another error occurred.
\since BeOS R5
*/
@@ -312,7 +348,7 @@ if (be_clipboard->Lock()) {
/*!
\name Clipboard Data Message Methods
\name Clipboard Data Message
*/
@@ -328,6 +364,8 @@ if (be_clipboard->Lock()) {
\returns A BMessenger object that targets the application that last
modified the clipboard.
\since BeOS R3
*/
@@ -340,6 +378,8 @@ if (be_clipboard->Lock()) {
\returns A pointer to the BMessage object that holds the clipboard
data or \c NULL if the clipboard is not locked.
\since BeOS R3
*/
docs/user/app/Cursor.dox
+86 -4
View File
@@ -1,13 +1,13 @@
/*
* Copyright 2012 Haiku, Inc. All rights reserved.
* Copyright 2012-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/app/Cursor.h hrev45039
* src/kits/app/Cursor.cpp hrev45039
* headers/os/app/Cursor.h hrev47355
* src/kits/app/Cursor.cpp hrev47355
*/
@@ -22,180 +22,240 @@
/*!
\enum BCursorID
List of predefined cursor IDs
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_SYSTEM_DEFAULT
System default cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_CONTEXT_MENU
Context menu cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_COPY
Copy cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_CREATE_LINK
Symlink cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_CROSS_HAIR
Cross hairs cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_FOLLOW_LINK
Follow html link cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_GRAB
Grab cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_GRABBING
Grabbing cursor (mouse down)
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_HELP
Help cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_I_BEAM
I beam cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_I_BEAM_HORIZONTAL
Horizontal I beam cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_MOVE
Move cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_NO_CURSOR
No cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_NOT_ALLOWED
Not allowed cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_PROGRESS
Progress cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH
Resize north cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_EAST
Resize east cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_SOUTH
Resize south cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_WEST
Resize west cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH_EAST
Resize north east cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH_WEST
Resize north west cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_SOUTH_EAST
Resize south east cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_SOUTH_WEST
Resize south west cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH_SOUTH
Resize north south cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_EAST_WEST
Resize east west cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH_EAST_SOUTH_WEST
Resize north east south west cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_RESIZE_NORTH_WEST_SOUTH_EAST
Resize north west south east cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_ZOOM_IN
Zoom in cursor
\since BeOS R5
*/
/*!
\var BCursorID B_CURSOR_ID_ZOOM_OUT
Zoom out cursor
\since BeOS R5
*/
@@ -207,6 +267,8 @@
\note As BeOS only supports 16x16 monochrome cursors, to see a nice
shadowed one we will need to extend this.
\since BeOS R5
*/
@@ -218,6 +280,8 @@
with the cursor data.
\param cursorData The cursor data.
\since BeOS R5
*/
@@ -226,6 +290,8 @@
\brief Initializes a new cursor object from a predefined cursor \a id.
\param id The predefined \a id to initialize to.
\since BeOS R5
*/
@@ -234,6 +300,8 @@
\brief Initializes a new cursor object from another cursor object.
\param other The cursor object to initialize from.
\since BeOS R5
*/
@@ -242,24 +310,32 @@
\brief Initializes a new cursor object from a message archive.
\param data The message data to initialize from.
\since BeOS R5
*/
/*!
\fn BCursor::~BCursor()
\brief Destroy the cursor and free it's memory.
\since BeOS R5
*/
/*!
status_t BCursor::Archive(BMessage *into, bool deep) const
\brief Archive the cursor. Not implemented.
\since BeOS R5
*/
/*!
BArchivable* BCursor::Instantiate(BMessage *data)
\brief Instantiate the cursor from a message. Not implemented.
\since BeOS R5
*/
@@ -270,6 +346,8 @@
\param other The cursor object to copy from.
\returns the new cursor object.
\since BeOS R5
*/
@@ -280,7 +358,9 @@
\param other The cursor object to compare to.
\returns \c true if the cursor objects are equal, \c false if the cursor
objects are not equal.
objects are not equal.
\since BeOS R5
*/
@@ -292,4 +372,6 @@
\returns \c true if the cursor objects are not equal, \c false if the cursor
objects are equal.
\since BeOS R5
*/
docs/user/app/Handler.dox
+141 -47
View File
@@ -1,13 +1,14 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/app/Handler.h rev 22577
* src/kits/app/Handler.cpp rev 21332
* headers/os/app/Handler.h hrev47355
* src/kits/app/Handler.cpp hrev47355
*/
/*!
@@ -24,6 +25,8 @@
/*!
\def B_OBSERVE_WHAT_CHANGE
\brief Internal.
\since BeOS R5
*/
@@ -37,6 +40,8 @@
but with the what constant set to \c B_OBSERVER_NOTICE_CHANGE. The original
\c what constant of the transmitted data message is stored behind the
label defined by this constant.
\since BeOS R5
*/
@@ -46,6 +51,8 @@
\note Specifying this parameter as the \a what value, leads to the same
results as calling BHandler::StartWatchingAll().
\since BeOS R5
*/
@@ -120,16 +127,20 @@
BHandler is a part of the chain in the eloquent messaging structure. For a
proper understanding of all its facets, have a look at the \ref app_messaging
"messaging overview".
\since BeOS R3
*/
/*!
\fn BHandler::BHandler(const char *name)
\fn BHandler::BHandler(const char* name)
\brief Construct a new handler with a \a name.
The newly constructed handler is not associated with a looper until you
explicitly request this to happen. To associate this handler with a looper,
use BLooper::AddHandler().
\since BeOS R3
*/
@@ -144,16 +155,21 @@
\warning This constructor does no type check whatsoever. Since you can pass
any BMessage, you should - if you are not sure about the exact type -
use the Instantiate() method, which does check the type.
\since BeOS R3
*/
/*!
\fn BArchivable *BHandler::Instantiate(BMessage *data)
\fn BArchivable* BHandler::Instantiate(BMessage* data)
\brief Static method to instantiate a handler from an archived message.
\return A pointer to the instantiated handler, or \c NULL if the \a data
is not a valid archived BHandler object.
\see BHandler(BMessage* data)
\since BeOS R3
*/
@@ -178,11 +194,13 @@
Note that only the name is stored. The filters, the associated looper and
the observers are not stored, and should be manually added when you are
using this object.
\since BeOS R3
*/
/*!
\fn status_t BHandler::Archive(BMessage *data, bool deep) const
\fn status_t BHandler::Archive(BMessage* data, bool deep) const
\brief Archive a handler to a message
Currently, only the name is archived. The filters, the associated looper
@@ -190,9 +208,14 @@
\param data The message to archive the object in.
\param deep This parameter is ignored, as BHandler does not have children.
\return A status code.
\retval B_OK Archiving succeeded.
\retval B_BAD_VALUE The \a data parameter is not a valid message.
\see BHandler::Instantiate(BMessage *data)
\see BHandler::Instantiate(BMessage* data)
\since BeOS R3
*/
@@ -211,7 +234,7 @@
/*!
\fn void BHandler::MessageReceived(BMessage *message)
\fn void BHandler::MessageReceived(BMessage* message)
\brief Handle \a message that has been received by the associated looper.
This method is reimplemented by subclasses. If the messages that have
@@ -250,42 +273,53 @@ ShowImageApp::MessageReceived(BMessage *message)
which will reply with \c B_MESSAGE_NOT_UNDERSTOOD.
\attention If you want to keep or manipulate the \a message, have a
look at BLooper::DetachCurrentMessage() to receive ownership of
the \a message.
look at BLooper::DetachCurrentMessage() to receive ownership
of the \a message.
\param message The message that needs to be handled.
\since BeOS R3
*/
/*!
\fn BLooper *BHandler::Looper() const
\fn BLooper* BHandler::Looper() const
\brief Return a pointer to the looper that this handler is associated with.
\return If the handler is not yet associated with a looper, it will return
\c NULL.
\c NULL.
\see BLooper::AddHandler()
\see LockLooper()
\since BeOS R3
*/
/*!
\fn void BHandler::SetName(const char *name)
\brief Set or change the name of this handler.
\see Name()
\since BeOS R3
*/
/*!
\fn const char *BHandler::Name() const
\fn const char* BHandler::Name() const
\brief Return the name of this handler.
\see SetName()
\since BeOS R3
*/
/*!
\fn void BHandler::SetNextHandler(BHandler *handler)
\fn void BHandler::SetNextHandler(BHandler* handler)
\brief Set the next handler in the chain that the message is passed on to
if this \a handler cannot process it.
if this \a handler cannot process it.
This method has three requirements:
-# This \a handler should belong to a looper.
@@ -299,14 +333,19 @@ ShowImageApp::MessageReceived(BMessage *message)
a looper with BLooper::AddHander().
\see NextHandler()
\since BeOS R3
*/
/*!
\fn BHandler *BHandler::NextHandler() const
\fn BHandler* BHandler::NextHandler() const
\brief Return the next hander in the chain to which the message is passed
on.
on.
\see SetNextHandler()
\since BeOS R3
*/
@@ -335,12 +374,15 @@ ShowImageApp::MessageReceived(BMessage *message)
stored. As such, you need to make sure that the \a filter object exists as
long as it is added to this handler.
\see RemoveFilter(), SetFilterList()
\see RemoveFilter()
\see SetFilterList()
\since BeOS R3
*/
/*!
\fn bool BHandler::RemoveFilter(BMessageFilter *filter)
\fn bool BHandler::RemoveFilter(BMessageFilter* filter)
\brief Remove \a filter from the filter list.
If the handler is associated with a looper, this looper needs to be locked
@@ -349,10 +391,13 @@ ShowImageApp::MessageReceived(BMessage *message)
Note that the \a filter is not deleted, merely removed from the list. You
need to take care of the memory yourself.
\retval true The \a filter was in the filter list and is removed.
\retval false The \a filter was not found in the filter list.
\return \c true if the \a filter was in the filter list and is removed,
\c false if the \a filter was not found in the filter list.
\see AddFilter(), FilterList()
\see AddFilter()
\see FilterList()
\since BeOS R3
*/
@@ -367,18 +412,24 @@ ShowImageApp::MessageReceived(BMessage *message)
existing filters will be \b deleted.
\see AddFilter(), FilterList()
\since BeOS R3
*/
/*!
\fn BList *BHandler::FilterList()
\fn BList* BHandler::FilterList()
\brief Return a pointer to the list of filters.
\return A pointer to the list of filters. Do not manipulate the list of
filters directly, but use the methods provided by this class, in order
to maintain internal consistency.
filters directly, but use the methods provided by this class, in
order to maintain internal consistency.
\see AddFilter(), RemoveFilter(), SetFilterList().
\see AddFilter()
\see RemoveFilter()
\see SetFilterList().
\since BeOS R3
*/
@@ -403,10 +454,13 @@ ShowImageApp::MessageReceived(BMessage *message)
\fn bool BHandler::LockLooper()
\brief Lock the looper associated with this handler.
\retval true The looper is locked.
\retval false There was an error acquiring the lock.
\return \c true if the looper is locked, \c false if there was an error
acquiring the lock.
\see LockLooperWithTimeout(), UnlockLooper()
\see LockLooperWithTimeout()
\see UnlockLooper()
\since BeOS R4
*/
@@ -415,21 +469,27 @@ ShowImageApp::MessageReceived(BMessage *message)
\brief Lock the looper associated with this handler, with a time out value.
\param timeout The time to wait for acquiring the lock in microseconds. You
may also use B_INFINITE_TIMEOUT, in which this method will wait as long
as it takes to acquire the lock.
may also use \c B_INFINITE_TIMEOUT, in which this method will wait
as long as it takes to acquire the lock.
\return A status code.
\retval B_OK Locking succeeded.
\retval B_BAD_VALUE This handler is not associated with a looper (anymore).
\retval B_TIMED_OUT The time specified in \a timeout has passed without
locking the looper.
\see LockLooper(), UnlockLooper()
\see LockLooper()
\see UnlockLooper()
\since BeOS R4
*/
/*!
\fn void BHandler::UnlockLooper()
\brief Unlock the looper.
\since BeOS R4
*/
@@ -448,16 +508,29 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn BHandler * BHandler::ResolveSpecifier(BMessage *msg, int32 index,
BMessage *specifier, int32 form, const char *property)
\fn BHandler* BHandler::ResolveSpecifier(BMessage* message, int32 index,
BMessage* specifier, int32 what, const char* property)
\brief Determine the proper handler for a scripting message.
\param message The scripting message to determine the handler.
\param index The index of the specifier.
\param specifier The message which contains the specifier.
\param what The 'what' field of the specifier message.
\param property The name of the target property.
\return A pointer to the proper BHandler for the given scripting
message.
\since BeOS R3
*/
/*!
\fn status_t BHandler::GetSupportedSuites(BMessage *data)
\fn status_t BHandler::GetSupportedSuites(BMessage* data)
\brief Reports the suites of messages and specifiers that derived classes
understand.
\since BeOS R3
*/
@@ -488,7 +561,7 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StartWatching(BMessenger target, uint32 what)
\brief Subscribe this handler to watch a specific state change of a
\a target.
\a target.
Use this method to subscribe messengers to watch state changes in this
handler, this also means that observers from other teams can be
@@ -502,14 +575,16 @@ BMessenger messengerA(&A)
B.StartWatching(messengerA, kNetworkConnection);
\endcode
\param target The messenger from which the notifications would be
received.
\param target The messenger from which the notifications would be received.
\param what The state that needs to be watched.
\return During the call of this method, a notification will be transmitted
using the \a target. If this works, then this method will return
\c B_OK.
using the \a target. If this works, then this method will return
\c B_OK.
\see StartWatchingAll(BMessenger), StopWatching(BMessenger, uint32)
\since BeOS R5
*/
@@ -521,6 +596,8 @@ B.StartWatching(messengerA, kNetworkConnection);
but it will subscribe to all the state changes the \a target knows.
\see StartWatching(BMessenger, uint32), StopWatchingAll(BMessenger)
\since BeOS R5
*/
@@ -532,6 +609,8 @@ B.StartWatching(messengerA, kNetworkConnection);
in a \a target.
\see StartWatching(BMessenger, uint32)
\since BeOS R5
*/
@@ -542,6 +621,8 @@ B.StartWatching(messengerA, kNetworkConnection);
This method will unsubscribe the \a target from watching all state changes.
\see StartWatchingAll(BMessenger)
\since BeOS R5
*/
@@ -570,6 +651,8 @@ A.StartWatching(&B, kNetworkConnection);
\c B_OK.
\see StartWatchingAll(BHandler*), StopWatching(BHandler*, uint32)
\since BeOS R5
*/
@@ -582,6 +665,8 @@ A.StartWatching(&B, kNetworkConnection);
tracks.
\see StartWatching(BHandler*, uint32), StopWatchingAll(BHandler*)
\since BeOS R5
*/
@@ -592,6 +677,8 @@ A.StartWatching(&B, kNetworkConnection);
This method will unsubscribe the \a handler from watching a specific event.
\see StartWatching(BHandler*, uint32)
\since BeOS R5
*/
@@ -602,6 +689,8 @@ A.StartWatching(&B, kNetworkConnection);
This method will unsubscribe the \a handler from watching all state changes.
\see StartWatchingAll(BHandler*)
\since BeOS R5
*/
@@ -624,26 +713,31 @@ A.StartWatching(&B, kNetworkConnection);
/*!
\fn void BHandler::SendNotices(uint32 what, const BMessage *msg)
\fn void BHandler::SendNotices(uint32 what, const BMessage* notice)
\brief Emit a state change to the observers.
The actual state (specified by \a what) will not be transmitted. This is
merely for internal bookkeeping. It is not entirely unimaginable that you
still want to inform the observers of what actually took place. You can
use the \a msg to transmit this, and any other data you want. Note that the
message will be copied and slightly altered: the \c what member of the
use the \a msg to transmit this, and any other data you want. Note that
the message will be copied and slightly altered: the \c what member of the
message will be \c B_OBSERVER_NOTICE_CHANGE, and the \c what constant you
specified will be stored in the #B_OBSERVE_ORIGINAL_WHAT label.
\param what The identifier of the state.
\param msg Any data associated with the state change. You retain ownership
of this data, so make sure you dispose it when you are done.
\param notice Any data associated with the state change. You retain
ownership of this data, so make sure you dispose it when you are
done.
\since BeOS R5
*/
/*!
\fn bool BHandler::IsWatched() const
\brief Check if there are any observers watching this handler.
\since BeOS R5
*/
docs/user/app/Looper.dox
+339 -218
View File
File diff suppressed because it is too large Load Diff
docs/user/app/Message.dox
+945 -410
View File
File diff suppressed because it is too large Load Diff
docs/user/app/MessageFilter.dox
+82 -30
View File
@@ -1,13 +1,14 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/app/MessageFilter.h
* src/kits/app/MessageFilter.cpp
* headers/os/app/MessageFilter.h hrev47355
* src/kits/app/MessageFilter.cpp hrev47355
*/
@@ -25,20 +26,26 @@
These return codes should be used in your own filter_hook function, or by
your overridden BMessageFilter::Filter() method.
\since BeOS R3
*/
/*!
\var B_SKIP_MESSAGE
\brief The message does not pass the filter criteria and should not be
handled.
handled.
\since BeOS R3
*/
/*!
\var B_DISPATCH_MESSAGE
\brief The message passes the filter criteria and should be dispatched to
a BHandler.
a BHandler.
\since BeOS R3
*/
@@ -46,27 +53,29 @@
\typedef filter_result (*filter_hook) (BMessage* message,
BHandler** target, BMessageFilter* filter)
\brief Prototype for a custom \c filter_hook for use in the BMessageFilter
class.
class.
This hook can be used when you are constructing a new BMessageFilter
object. It is a custom filter function you can use.
This hook should handle the following parameters:
\param[in] message The message that needs to be verified.
\param[out] target If your filter hook is conscious about the available
handlers, you can set a specific BHandler based on your filters
requirements. You do not have to change this field, because there will
always be a working default.
handlers, you can set a specific BHandler based on your filters
requirements. You do not have to change this field, because
there will always be a working default.
\param[in] filter A pointer to the filter from which this hook is called.
\return You should return #B_SKIP_MESSAGE in case the message does not
conform to the filter criteria, or #B_DISPATCH_MESSAGE if the message
passes these criteria.
conform to the filter criteria, or #B_DISPATCH_MESSAGE if the
message passes these criteria.
\see BMessageFilter(uint32, filter_hook)
BMessageFilter(message_delivery, message_source, filter_hook)
BMessageFilter(message_delivery, message_source, uint32, filter_hook)
\see BMessageFilter(message_delivery, message_source, filter_hook)
\see BMessageFilter(message_delivery, message_source, uint32, filter_hook)
\since BeOS R3
*/
@@ -81,25 +90,33 @@
With this filter you can, for example, specify that your handler only
handles deliveries that were programmed by you, and not any random drag and
drop actions initiated by the user.
\since BeOS R3
*/
/*!
\var B_ANY_DELIVERY
\brief Accept both delivery methods.
\since BeOS R3
*/
/*!
\var B_DROPPED_DELIVERY
\brief Only accept messages that were dropped by the user in the GUI.
\since BeOS R3
*/
/*!
\var B_PROGRAMMED_DELIVERY
\brief Only accept messages that were delivered using the
BLooper::PostMessage() method.
BLooper::PostMessage() method.
\since BeOS R3
*/
@@ -116,27 +133,35 @@
You use these constants in the constructors of the BMessageFilter class.
\warning System messages, for example from the \c app_server, are
considered remote messages. Keep this in mind when you want to set up
criteria for your window and application loopers.
considered remote messages. Keep this in mind when you want
to set up criteria for your window and application loopers.
\since BeOS R3
*/
/*!
\var B_ANY_SOURCE
\brief Accept both local and remote messages.
\since BeOS R3
*/
/*!
\var B_REMOTE_SOURCE
\brief Only accept messages from a remote source, so from other
applications.
applications.
\since BeOS R3
*/
/*!
\var B_LOCAL_SOURCE
\brief Only accept messages from your own local application.
\since BeOS R3
*/
@@ -150,16 +175,15 @@
messages should have in order to be processed by a handler or a looper.
BMessageFilter provides three default filter criteria, the \c what
constant, the #message_source and the type of message_delivery,
and an extendible #filter_hook.
and an extendible #filter_hook.
BMessageFilter's standard filter criteria can be extended in two ways:
-# Specify a #filter_hook. This is a static function that takes a message
and a pointer to a BHandler as arguments, and allows you to accept or
reject the message, and even redirect it to a specific BHandler.
and a pointer to a BHandler as arguments, and allows you to accept or
reject the message, and even redirect it to a specific BHandler.
-# Subclass the BMessageFilter class and override the Filter() function.
This has the same capabilities as using a #filter_hook, but it allows
cleaner code (in some cases).
This has the same capabilities as using a #filter_hook, but it allows
cleaner code (in some cases).
Both methods have their merits, but please remember that you have to choose
which one you want to use, since you can't use both. The order of
processing the criteria is in this order: the source, the delivery method,
@@ -212,6 +236,8 @@ looper->AddCommonFilter(filter);
The two classes that use BMessageFilter are BLooper and BHandler. In the
general messaging introduction, there is also a section on
\ref app-messaging-receiving "handling messages".
\since BeOS R3
*/
@@ -225,6 +251,8 @@ looper->AddCommonFilter(filter);
\see BMessageFilter(message_delivery, message_source, filter_hook)
\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
\since BeOS R3
*/
@@ -239,6 +267,8 @@ looper->AddCommonFilter(filter);
\see BMessageFilter(uint32 what,filter_hook)
\see BMessageFilter(message_delivery, message_source, uint32 what, filter_hook)
\since BeOS R3
*/
@@ -253,30 +283,40 @@ looper->AddCommonFilter(filter);
\see BMessageFilter(uint32 what,filter_hook)
\see BMessageFilter(message_delivery, message_source, filter_hook)
\since BeOS R3
*/
/*!
\fn BMessageFilter::BMessageFilter(const BMessageFilter& filter)
\brief Copy constructor. Copy the criteria from another object.
\since BeOS R3
*/
/*!
\fn BMessageFilter::BMessageFilter(const BMessageFilter* filter)
\brief Create a new object based on criteria of another object.
\since BeOS R3
*/
/*!
\fn BMessageFilter::~BMessageFilter()
\brief Destructor. Does nothing.
\since BeOS R3
*/
/*!
\fn BMessageFilter &BMessageFilter::operator=(const BMessageFilter& from)
\fn BMessageFilter& BMessageFilter::operator=(const BMessageFilter& from)
\brief Assignment operator. Copies criteria from another filter.
\since BeOS R3
*/
@@ -291,23 +331,29 @@ looper->AddCommonFilter(filter);
\param message The message that needs to be filtered.
\param target If you want to, you can specify a handler that should handle
this message. Note that you do have to pass a handler that is
associated with the looper that received the message.
this message. Note that you do have to pass a handler that is
associated with the looper that received the message.
\return You should return \c B_DISPATCH_MESSAGE in case the message passes
the tests, or \c B_SKIP_MESSAGE in case the message does not pass.
the tests, or \c B_SKIP_MESSAGE in case the message does not pass.
\since BeOS R3
*/
/*!
\fn message_delivery BMessageFilter::MessageDelivery() const
\brief Return the message_delivery criterium of this filter.
\since BeOS R3
*/
/*!
\fn message_source BMessageFilter::MessageSource() const
\brief Return the message_source criterium of this filter.
\since BeOS R3
*/
@@ -319,6 +365,8 @@ looper->AddCommonFilter(filter);
the message constant.
\see FiltersAnyCommand() const
\since BeOS R3
*/
@@ -327,10 +375,14 @@ looper->AddCommonFilter(filter);
\brief Return whether or not this filter has a message command criterium.
\see Command() const
\since BeOS R3
*/
/*!
\fn BLooper *BMessageFilter::Looper() const
\fn BLooper* BMessageFilter::Looper() const
\brief Return the looper this filter is associated with.
\since BeOS R3
*/
docs/user/app/MessageQueue.dox
+46 -14
View File
@@ -1,15 +1,17 @@
/*
* Copyright 2007, Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/MessageQueue.h rev 19956
* /trunk/src/kits/app/MessageQueue.cpp rev 19956
* /trunk/headers/os/app/MessageQueue.h hrev47355
* /trunk/src/kits/app/MessageQueue.cpp hrev47355
*/
/*!
\file MessageQueue.h
\ingroup app
@@ -37,19 +39,23 @@
perform, that you only do this after the object has been locked (see
Lock()). The most important method, NextMessage() will fail if you have not
complied with this requirement.
\since BeOS R3
*/
/*!
\fn BMessageQueue::BMessageQueue()
\brief Constructs an empty message queue.
\since BeOS R3
*/
/*!
\fn BMessageQueue::~BMessageQueue()
\brief Destruct the BMessageQueue. It iterates over any messages left on
the queue and deletes them.
the queue and deletes them.
The implementation is careful not to release the lock when the
BMessageQueue is deconstructed. If the lock is released, it is
@@ -58,6 +64,8 @@
BLocker from the destructor once it is acquired. That way, any thread
waiting to do a AddMessage() will fail to acquire the lock since the
BLocker will be deleted before they can acquire it.
\since BeOS R3
*/
@@ -71,6 +79,8 @@
Because a BMessageQueue claims ownership of the \a message, it is important
that the message does not belong to another BMessageQueue.
\since BeOS R3
*/
@@ -80,45 +90,55 @@
If the \a message is indeed associated with this queue, it is removed from
it. This effectively means that you regain ownership of the message.
\since BeOS R3
*/
/*!
\fn int32 BMessageQueue::CountMessages() const
\brief Return the number of messages waiting in the queue.
\since BeOS R3
*/
/*!
\fn bool BMessageQueue::IsEmpty() const
\brief Check if there are messages waiting in the queue.
\since BeOS R3
*/
/*!
\fn BMessage *BMessageQueue::FindMessage(int32 index) const
\fn BMessage* BMessageQueue::FindMessage(int32 index) const
\brief Retrieve the message at the \a index of this queue.
\param index A zero-based index of the message you want to retrieve.
\return A pointer to a message, or \c NULL if the \a index is out of
bounds.
bounds.
\see FindMessage(uint32, int32) for a variant that takes a specific \c what
identifier.
identifier.
\since BeOS R3
*/
/*!
\fn BMessage *BMessageQueue::FindMessage(uint32 what, int32 index) const
\fn BMessage* BMessageQueue::FindMessage(uint32 what, int32 index) const
\brief Retrieve the message at the \a index of this queue, but only if it
has a specific \a what constant.
has a specific \a what constant.
\param index A zero-based index of the message you want to retrieve.
\param what The \a what code of the message.
\return A pointer to a message, or \c NULL if there is no message at the
\a index with that \a what constant, or if the \a index is out of
bounds.
\a index with that \a what constant, or if the \a index is out of
bounds.
\since BeOS R3
*/
@@ -127,6 +147,8 @@
\brief Lock the queue so no other thread can perform operations on it.
\see Unlock()
\since BeOS R3
*/
@@ -135,6 +157,8 @@
\brief Unlock the queue after a Lock() request.
\see Lock()
\since BeOS R3
*/
@@ -142,21 +166,27 @@
\fn bool BMessageQueue::IsLocked() const
\brief Check if the queue is locked.
\see Lock() and Unlock()
\see Lock()
\see Unlock()
\since Haiku R1
*/
/*!
\fn BMessage *BMessageQueue::NextMessage()
\fn BMessage* BMessageQueue::NextMessage()
\brief Remove the first BMessage on the queue and return it to the caller.
After calling this method, you get the ownership of the message, so make
sure it is deleted after you are done.
\return A pointer to a message, or \c NULL if the queue is empty, or the
object has not been properly locked.
object has not been properly locked.
\see Lock()
\see IsNextMessage()
\since BeOS R3
*/
@@ -164,4 +194,6 @@
\fn bool BMessageQueue::IsNextMessage(const BMessage* message) const
\brief Check if the pointer to a \a message points at the next message on
the queue.
\since Haiku R1
*/