From ac9714d8a432d321345e9ba8425164b59a4f0d50 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Wed, 11 Jun 2014 16:25:57 -0400 Subject: [PATCH] Update App Kit Documentation. 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. --- docs/user/app/Application.dox | 169 ++-- docs/user/app/Clipboard.dox | 60 +- docs/user/app/Cursor.dox | 90 ++- docs/user/app/Handler.dox | 188 +++-- docs/user/app/Looper.dox | 555 ++++++++----- docs/user/app/Message.dox | 1337 ++++++++++++++++++++++--------- docs/user/app/MessageFilter.dox | 112 ++- docs/user/app/MessageQueue.dox | 60 +- 8 files changed, 1803 insertions(+), 768 deletions(-) diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox index 02567c2a4ae..56d9bc01122 100644 --- a/docs/user/app/Application.dox +++ b/docs/user/app/Application.dox @@ -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, jscipione@gmail.com * * 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. + + Run() does not spawn a new thread. - \returns the thread_id of the thread that the BApplication is called from. + \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() */ diff --git a/docs/user/app/Clipboard.dox b/docs/user/app/Clipboard.dox index 60716f9c7ff..c34a77e3919 100644 --- a/docs/user/app/Clipboard.dox +++ b/docs/user/app/Clipboard.dox @@ -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, jscipione@gmail.com * * 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 */ diff --git a/docs/user/app/Cursor.dox b/docs/user/app/Cursor.dox index f7bca2a3a49..aa655d36177 100644 --- a/docs/user/app/Cursor.dox +++ b/docs/user/app/Cursor.dox @@ -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, jscipione@gmail.com * * 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 */ diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox index d4e47f0cfb6..20962110f5f 100644 --- a/docs/user/app/Handler.dox +++ b/docs/user/app/Handler.dox @@ -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, niels.reedijk@gmail.com - * + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com + * * 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() + \see UnlockLooper() - \see LockLooperWithTimeout(), 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 */ diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox index dbd9cb42cfb..61caaa8131e 100644 --- a/docs/user/app/Looper.dox +++ b/docs/user/app/Looper.dox @@ -1,15 +1,17 @@ /* - * Copyright 2008 Haiku, Inc. All rights reserved. + * Copyright 2008-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Niels Sascha Reedijk, niels.reedijk@gmail.com - * + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com + * * Corresponds to: - * headers/os/app/Looper.h rev 21863 - * src/kits/app/Looper.cpp rev 21864 + * headers/os/app/Looper.h hrev47355 + * src/kits/app/Looper.cpp hrev47355 */ + /*! \file Looper.h \ingroup app @@ -21,6 +23,8 @@ /*! \def B_LOOPER_PORT_DEFAULT_CAPACITY \brief The default size of the port of a BLooper. + + \since BeOS R3 */ @@ -29,7 +33,7 @@ \ingroup app \ingroup libbe \brief Receive and process messages in a separate thread. - + When an object of this class is created, the message loop can be started with Run(). This spawns the thread that receives messages and processes messages. Messages are actually passed on to \link BHandler handlers \endlink @@ -38,8 +42,8 @@ a \c B_QUIT_REQUESTED message using one of the message post functions. When a looper receives such a request, it will \b delete itself. As such, looper should always be created on the heap (with \c new), and never on - the stack. - + the stack. + Posting messages can be done using the various PostMessage() methods. Whenever a message is posted, it will be added through to the message queue. It is possible to apply filters (see AddCommonFilter()) to filter @@ -47,7 +51,7 @@ copy the contents of the message and this copy is processed, so make sure you delete the original messages in case you create them on the heap. The handler for the message is chosen using the following criteria: - + -# If PostMessage() or the BMessenger is set to a specific handler, and this handler is associated with this looper, than the message is processed by that handler. @@ -55,13 +59,13 @@ SetPreferredHandler(). -# If there is no preferred handler, then the looper itself will process the message. - + Because a looper usually is used in multiple threads, you should make sure you Lock() and Unlock() it during most operations. Locking calls can be recursive (so multiple locks can come from a single thread), but make sure you pair every Lock() with an Unlock() call. Failing to do so will inevitably cause a deadlock. - + Because a looper provides a separate thread, and the inherited handler is usually a default handler, you will most often use this class by subclassing it. For example, you are likely to subclass BWindow (which is @@ -73,57 +77,63 @@ additional procedures during closing time. You can also override DispatchMessage() if you want to do something with all incoming messages before they are dispatched to a handler. - + BLooper is one of the major base classes of the Haiku application programmers interface. Closely related classes are BMessage, BHandler and BMessenger. It is used in the interface kit, for example by the BWindow class, which makes sure every window runs it its own thread. - + BLooper 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 BLooper::BLooper(const char* name, int32 priority, int32 port_capacity) + \fn BLooper::BLooper(const char* name, int32 priority, int32 portCapacity) \brief Construct a new BLooper with a \a priority and an \a capacity. - + The new looper is, by default, not running yet. If you have set up everything properly, you may call Run(). - + \attention Remember that loopers should be created on the heap, because - they will \c delete themselves in the Quit() method. - + they will \c delete themselves in the Quit() method. + \param name The name of the looper. \param priority The priority of the message thread of this looper. The - default priority should be good enough for most tasks. Also, some - derived versions of BLooper will use a specialized priority. So it is - advised to leave this setting at the default, unless you know why you - would like another setting. - \param port_capacity Loopers use ports to send and receive messages (see - the kernel kit). Ports have a maximum capacity; if there are so many - messages queued that the port is full, all other incoming messages are - dropped. There are situations where the size of the port should be - different from the default. This might be when your looper receives - a lot of messages, or if the message handling thread runs at a lower - priority than normal, which would decrease the processing speed. - Finding a suitable value for these custom scenarios would be done by - testing. - + default priority should be good enough for most tasks. Also, some + derived versions of BLooper will use a specialized priority. So it + is advised to leave this setting at the default, unless you know + why you would like another setting. + \param portCapacity Loopers use ports to send and receive messages (see + the kernel kit). Ports have a maximum capacity; if there are so many + messages queued that the port is full, all other incoming messages + are dropped. There are situations where the size of the port should + be different from the default. This might be when your looper + receives a lot of messages, or if the message handling thread runs + at a lower priority than normal, which would decrease the processing + speed. Finding a suitable value for these custom scenarios would be + done by testing. + \see Run() + + \since BeOS R3 */ /*! \fn BLooper::~BLooper() \brief Destruct the looper. - + You will never delete a looper yourself. You should pass a \c B_QUIT_REQUESTED message, or if you are destroying the looper from inside its own message handling thread, you should call Quit(). - + \see Quit() + + \since BeOS R3 */ @@ -136,48 +146,57 @@ //! @{ - + /*! - \fn BLooper::BLooper(BMessage *data) + \fn BLooper::BLooper(BMessage* data) \brief Construct a looper from an archived message. - + The \a data message has to be constructed by a BLooper::Archive() call. Note that the data that is restored, is merely the port capacity and the name of the looper/handler. Other data, such as filters, is not archived by the default archiver. - + \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. + any BMessage, you should - if you are not sure about the exact + type - use the Instantiate() method, which does check the type. \see Instantiate() \see Archive() + + \since BeOS R3 */ /*! - \fn BArchivable *BLooper::Instantiate(BMessage *data) + \fn BArchivable* BLooper::Instantiate(BMessage* data) \brief Static method to instantiate a looper from an archived message. \return A pointer to the instantiated looper, or \c NULL if the \a data - is not a valid archived BLooper object. + is not a valid archived BLooper object. + \see BLooper(BMessage* data) + + \since BeOS R3 */ /*! - \fn status_t BLooper::Archive(BMessage *data, bool deep) const + \fn status_t BLooper::Archive(BMessage* data, bool deep) const \brief Archive a looper to a message - + Currently, only the name and the port capacity are archived. Any other data, such as the filters, is not stored. - + \param data The message to archive the object in. \param deep This parameter is ignored, as BLooper does not have children. + \retval B_OK Archiving succeeded. \retval B_BAD_VALUE The \a data parameter is not a valid message. - \see BLooper::Instantiate(BMessage *data) + + \see BLooper::Instantiate(BMessage* data) + + \since BeOS R3 */ @@ -190,110 +209,117 @@ //! @{ - + /*! \fn status_t BLooper::PostMessage(uint32 command) \brief Post a message with the \a command as \c what identifier to this - looper. - + looper. + Posting a message puts it in the message queue. The message passes through the default handler chain. - + \param command The \c what identifier of the message that needs to be sent. - + + \return A status code. \retval B_OK The operation succeeded, and the message is sent to the port. \retval B_ERROR There was a general operation error. \retval B_BAD_VALUE This looper is not yet running and therefore cannot - receive messages. - + receive messages. + \see PostMessage(BMessage *) if you want to send a message with data - members. + members. \see PostMessage(uint32, BHandler *, BHandler *) if you want to send a - message to a specific handler, and request a reply. + message to a specific handler, and request a reply. \see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing, but with a complete message. + + \since BeOS R5 */ /*! - \fn status_t BLooper::PostMessage(BMessage *message) + \fn status_t BLooper::PostMessage(BMessage* message) \brief Post a \a message to this looper. - + Posting a message puts it in the message queue. The message passes through the default handler chain. - + The \a message is copied, and as such, you should make sure you will not leak it. The best way to send messages is like this: - \code BMessage message; message.what = B_DO_SOMETHING; message.AddString("some_data", "This is data") - + aLooper->PostMessage(&message); \endcode - + \param message The message you would like to pass to this method. - + + \return A status code. \retval B_OK The operation succeeded, and the message is sent to the port. \retval B_ERROR There was a general operation error. \retval B_BAD_VALUE This looper is not yet running and therefore cannot receive messages. - + \see PostMessage(uint32) if you want to send a message without data - members. + members. \see PostMessage(uint32, BHandler *, BHandler *) if you want to send a - message to a specific handler, and request a reply. + message to a specific handler, and request a reply. \see PostMessage(BMessage *, BHandler *, BHandler *) for the same thing, - but with a complete message. + but with a complete message. + + \since BeOS R5 */ /*! - \fn status_t BLooper::PostMessage(uint32 command, BHandler *handler, - BHandler *replyTo) + \fn status_t BLooper::PostMessage(uint32 command, BHandler* handler, + BHandler* replyTo) \brief Send a message with the \a command as \c what identifier to the - \a handler associated with this looper, and (optionally) request a - reply. - + \a handler associated with this looper, and (optionally) request a + reply. + The target \a handler should be associated with this looper. This method bypasses the default message queue. - + \param command The value you want as the message's \c what identifier. \param handler The handler you would like to pass this message to. \param replyTo If you would like to request a reply, pass the handler to - which this reply should be directed to. If you pass \c NULL, you will - not receive a reply. - + which this reply should be directed to. If you pass \c NULL, you + will not receive a reply. + + \return A status code. \retval B_OK The operation succeeded, and the message is sent to the port. \retval B_ERROR There was a general operation error. \retval B_BAD_VALUE This looper is not yet running and therefore cannot - receive messages. + receive messages. \retval B_MISMATCHED_VALUES The \a handler is not associated with this - looper. - + looper. + \see PostMessage(uint32) if you want to send a message without data - members. + members. \see PostMessage(BMessage *) if you want to send a message with data - members. + members. \see PostMessage(BMessage *, BHandler *, BHandler *) if you want to send a - message to a specific handler, and request a reply. + message to a specific handler, and request a reply. + + \since BeOS R5 */ /*! - \fn status_t BLooper::PostMessage(BMessage *message, BHandler *handler, - BHandler *replyTo) + \fn status_t BLooper::PostMessage(BMessage* message, BHandler* handler, + BHandler* replyTo) \brief Send a \a message to the \a handler associated with this looper, - and (optionally) request a reply. - + and (optionally) request a reply. + The target \a handler should be associated with this looper. This method bypasses the default message queue. - + The \a message is copied, and as such, you should make sure you will not leak it. The best way to send messages is like this: - \code BMessage message; message.what = B_DO_SOMETHING; @@ -301,26 +327,29 @@ aLooper->PostMessage(&message, aHandler); \endcode - + \param message The message you want to pass. \param handler The handler you would like to pass this message to. \param replyTo If you would like to request a reply, pass the handler to - which this reply should be directed to. If you pass \c NULL, you will - not receive a reply. - + which this reply should be directed to. If you pass \c NULL, you + will not receive a reply. + + \return A status code. \retval B_OK The operation succeeded, and the message is sent to the port. \retval B_ERROR There was a general operation error. \retval B_BAD_VALUE This looper is not yet running and therefore cannot - receive messages. + receive messages. \retval B_MISMATCHED_VALUES The \a handler is not associated with this - looper. - + looper. + \see PostMessage(uint32) if you want to send a message without data - members. + members. \see PostMessage(BMessage *) if you want to send a message with data - members. + members. \see PostMessage(uint32, BHandler *, BHandler *) if you want to send a - message without data to a specific handler, and request a reply. + message without data to a specific handler, and request a reply. + + \since BeOS R5 */ @@ -338,84 +367,95 @@ /*! \fn void BLooper::DispatchMessage(BMessage *message, BHandler *handler) \brief Dispatch a message to a handler. Override if there are messages that - you want to catch before they are sent to the handlers. - + you want to catch before they are sent to the handlers. + This method is called by the message looping thread to dispatch a message to \a handler. If you implement the BLooper class and your looper receives messages that absolutely have to be processed by the looper instead of any of the handlers, override this method. For example, the default implementation catches B_QUIT_REQUESTED messages before they are sent to the handlers, so that the looper will quit at those messages. - + You are discouraged from using this method to filter out any messages you do not want to process. For this, there is a more generic method using the BMessageFilter class. If you want to skip messages with certain patterns, have a look at the AddCommonFilter() and SetCommonFilterList() methods. - + If you do override this method, please remember to call the DispatchMessage() method of the parent class. + + \since BeOS R3 */ /*! - \fn void BLooper::MessageReceived(BMessage *msg) + \fn void BLooper::MessageReceived(BMessage* message) \brief Process a message received by the internal handler of this looper. - + Reimplemented from BHandler::MessageReceived(); + + \since BeOS R5 */ /*! \fn BMessage* BLooper::CurrentMessage() const \brief Retrieve the current message. - + \attention Only call this method from within the thread that processes the - messages. It contains a pointer to the message that is currently being - handled. Due to the multithreaded nature of the operating system, this - method will not safely let you read the message that is being processed - by this handler from outside the context of the processing. If you do - want to use a message outside of the processing thread, have a look at - DetachCurrentMessage() to safely retrieve a message. - + messages. It contains a pointer to the message that is currently + being handled. Due to the multithreaded nature of the operating + system, this method will not safely let you read the message + that is being processed by this handler from outside the context + of the processing. If you do want to use a message outside of + the processing thread, have a look at DetachCurrentMessage() to + safely retrieve a message. + \return A pointer to the message that is currently being processed. Note - that calling it from outside the thread that processes the message, - could give you a \c NULL pointer or an invalid pointer. + that calling it from outside the thread that processes the message, + could give you a \c NULL pointer or an invalid pointer. + + \since BeOS R5 */ /*! \fn BMessage* BLooper::DetachCurrentMessage() \brief Get ownership of the message currently being processed. - + Retrieve the current message and gain ownership of it. This means that the message will not be deleted as soon as the looper is done processing it. You can then use it for different purposes. - + \attention Only call this method from within the thread that processes the - messages. Due to the multithreaded nature of the operating system, calling - it from another thread is very likely to give you an invalid or a \c NULL - pointer. + messages. Due to the multithreaded nature of the operating + system, calling it from another thread is very likely to give + you an invalid or a \c NULL pointer. + + \since BeOS R5 */ /*! \fn BMessageQueue* BLooper::MessageQueue() const \brief Get a pointer to the internal message queue of this looper. - + You can use this pointer to manipulate the message queue. Note that the message that is being processed is already detached from this queue. - + \return A pointer to the internal message queue. + + \since BeOS R5 */ /*! \fn bool BLooper::IsMessageWaiting() const \brief Check if there is a message waiting. - - \retval true There are still messages to be processed. - \retval false There is no message waiting. + + \return \c true if there are still messages to be processed, + \c false if there is no message waiting. */ @@ -433,86 +473,106 @@ /*! \fn void BLooper::AddHandler(BHandler* handler) \brief Associate a \a handler to this looper. - + The \a handler will be associated to this looper. By default, the handler in this looper will be chained to the supplied \a handler. - - \param handler The handler to associate with this looper. If the handler is - already associated to another looper, the operation will fail silently. - Check beforehand if you cannot be sure that the \a handler is - unassociated. - + + \param handler The handler to associate with this looper. If the handler + is already associated to another looper, the operation will fail + silently. Check beforehand if you cannot be sure that the + \a handler is unassociated. + \see RemoveHandler() + + \since BeOS R3 */ /*! \fn bool BLooper::RemoveHandler(BHandler* handler) \brief Disassociate a \a handler from this looper. - + If the handler is disassociated, it can be reassociated to another looper. - - \retval true The \a handler has been removed from this looper. - \retval false The \a handler was invalid. or the handler was not - associated to this looper. + + \return \c true if the \a handler has been removed from this looper, + \c false The \a handler was invalid or the handler was not + associated to this looper. + \see AddHandler() + + \since BeOS R3 */ /*! \fn int32 BLooper::CountHandlers() const \brief Get the number of handlers associated with this looper. - - \see HandlerAt(), IndexOf() + + \see HandlerAt() + \see IndexOf() + + \since BeOS R3 */ /*! \fn BHandler* BLooper::HandlerAt(int32 index) const \brief Get the handler at an \a index of the list of associated handlers. - + \return A pointer to the handler at that \a index, or \c NULL if the - \a index is out of range. + \a index is out of range. - \see CountHandlers(), IndexOf() + \see CountHandlers() + \see IndexOf() + + \since BeOS R3 */ /*! \fn int32 BLooper::IndexOf(BHandler* handler) const \brief Get the index of the \a handler that is in the associated handler - list. - - \return If the \a handler is not in the list, this method will return -1. - Else, you will get the index of the handler in the list. + list. + + \return The index of the handler in the list if the \a handler is in the + list, else this method will return -1. + + \since BeOS R3 */ /*! \fn BHandler* BLooper::PreferredHandler() const \brief Get the preferred handler. - + \return A pointer to the preferred handler, or \c NULL if none is set. + \see SetPreferredHandler() + + \since BeOS R3 */ /*! \fn void BLooper::SetPreferredHandler(BHandler* handler) \brief Set a preferred handler. - + If messages are posted to this looper using one of the PostMessage() methods without a specific BHandler argument, the messages will be handled by the looper itself (since a looper is a subclass of BHandler, this is perfectly possible). If you want to override that behavior, you should set a preferred handler. This handler will be called if incoming messages do not ask to be directly passed on to a specific handler. - + \param handler The preferred handler you want undesignated messages to be - handled by. If you want to unset the preferred handler, pass \c NULL. - If the supplied \a handler is not associated with this looper, this - call will fail silently and the current preferred handler will be unset. + handled by. If you want to unset the preferred handler, pass + \c NULL. If the supplied \a handler is not associated with this + looper, this call will fail silently and the current preferred + handler will be unset. + \see PreferredHandler() + + \since BeOS R3 */ @@ -530,40 +590,44 @@ /*! \fn thread_id BLooper::Run() \brief Start the event loop. - + After the looper has been constructed, it needs to be started using this method. A thread will be spawned, which will receive messages. - + Make sure the looper is not yet running before you call this method. - + \return A (positive) thread id if spawning the thread succeeded, or an - error code. + error code. + + \since BeOS R3 */ /*! \fn void BLooper::Quit() \brief Hook method that is called after a \c B_QUIT_REQUESTED message. - + If you want to quit and delete the looper, you should post a \c B_QUIT_REQUESTED message. This will first call the hook method QuitRequested(), which can be overridden in child classes in case there are conditions that would prevent the looper to be quit. If you really know what you are doing, and you definitely want to quit this looper, you may call this method, but only after performing a Lock() operation. - + Override this method if your subclass needs to perform specific clean-up tasks. Remember to call the base class implementation when you're done. - + \attention You will not have to delete the looper object, if a looper quits - it will delete itself. + it will delete itself. + + \since BeOS R3 */ /*! \fn bool BLooper::QuitRequested() \brief Hook method that is called during a \c B_QUIT_REQUESTED message. - + This hook function is called by the looper thread when a \c B_QUIT_REQUESTED is received. The default implementation always accepts the message, but if your subclass needs a special condition to be met @@ -571,90 +635,119 @@ in this hook method. A good example is a window (which is a derivative of BLooper), which contains a modified document. The condition may be that a modal dialog requesting a path of action is closed. - - \retval true The looper can be quit and destroyed. - \retval false Do not accept the quit message and continue processing - messages. + + \return \c true if the looper can be quit and destroyed, + \c false if this method does not accept the quit message + and continue processing messages. + + \since BeOS R3 */ /*! \fn bool BLooper::Lock() \brief Lock the looper. - + For most operations involving the internal data of the looper, you need to hold the lock. Each looper implements a global lock, which you can use to perform operations on internal data in a thread-safe manner. - + Do not forget to pair each Lock() request with an Unlock() request. Lock() requests can be stacked, which means that recursively locking a looper from a thread that actually holds the lock, will not cause a deadlock. See BLocker for more information on locking internals. - - \retval true The locking request succeeded. - \retval false The locking request could not be completed. There are a - variety of reasons for this to happen, for example when the looper is - destroyed. - \see Unlock(), LockWithTimeout(), IsLocked() + + \return \c true if the locking request succeeded, + \c false if the locking request could not be completed. There are a + variety of reasons for this to happen, for example when the + looper is destroyed. + + \see Unlock() + \see LockWithTimeout() + \see IsLocked() + + \since BeOS R5 */ /*! \fn void BLooper::Unlock() \brief Unlock a locked looper. - + Use this method paired with Lock() calls, to release a lock. Make sure that this method is only called on a locked looper. - - \see Lock(), LockWithTimeout(), IsLocked() + + \see Lock() + \see LockWithTimeout() + \see IsLocked() + + \since BeOS R5 */ /*! \fn bool BLooper::IsLocked() const \brief Check if a looper is locked. - - \retval true The looper is locked. - \retval false The looper is not locked, or the looper has been deleted. - \see Lock(), Unlock(), LockWithTimeout() + + \return \c true if the looper is locked, + \c false if the looper is not locked, or the looper has been + deleted. + + \see Lock() + \see Unlock() + \see LockWithTimeout() + + \since BeOS R5 */ /*! \fn status_t BLooper::LockWithTimeout(bigtime_t timeout) \brief Lock a looper with a \a timeout. - + This method locks the looper like Lock(), but if the locking request does not succeed within the provided \a timeout, the method will return. - + \param timeout The maximum time to wait for the lock request to succeed. - + + \return A status code. \retval B_OK The lock is acquired. \retval B_BAD_VALUE The looper has been destroyed. \retval "other errors" There was an error acquiring the lock. - \see Lock(), Unlock(), IsLocked() + + \see Lock() + \see Unlock() + \see IsLocked() + + \since BeOS R5 */ /*! \fn thread_id BLooper::Thread() const \brief Return the thread id of the internal message looper thread. - + If the looper is not yet running, this method will return 0. - + \see Run() + + \since BeOS R3 */ /*! \fn team_id BLooper::Team() const \brief Return the team id in which this looper exists. + + \since BeOS R3 */ /*! \fn BLooper* BLooper::LooperForThread(thread_id thread) \brief Static method to retrieve a BLooper for a specified \a thread. + + \since BeOS R3 */ @@ -662,40 +755,48 @@ /*! - \name Loop debugging - + \name Loop Debugging + These methods may aid you in debugging problems when they occur, but do not - use these in actual production code. These methods are unrealiable because + use these in actual production code. These methods are unreliable because they are not thread-safe, and as such are only useful in specific debugging situations. Handle with care. */ //! @{ - + /*! \fn thread_id BLooper::LockingThread() const - \brief Return the thread id of the thread that currenty holds the lock. + \brief Return the thread id of the thread that currently holds the lock. + + \since BeOS R3 */ /*! \fn int32 BLooper::CountLocks() const \brief Return the number of recursive locks that are currently being held - on this looper + on this looper. + + \since BeOS R3 */ /*! \fn int32 BLooper::CountLockRequests() const \brief Return the number of pending locks. + + \since BeOS R3 */ /*! \fn sem_id BLooper::Sem() const \brief Return the id of the semaphore that is used to lock this looper. + + \since BeOS R3 */ @@ -703,7 +804,7 @@ /*! - \name Scripting Functions + \name Scripting */ @@ -711,11 +812,11 @@ /*! - \fn BHandler* BLooper::ResolveSpecifier(BMessage* msg, int32 index, - BMessage* specifier, int32 form, const char* property) + \fn BHandler* BLooper::ResolveSpecifier(BMessage* message, int32 index, + BMessage* specifier, int32 what, const char* property) \brief Determine the proper handler for a scripting message. - \see BHandler::ResolveSpecifier() + \copydetails BHandler::ResolveSpecifier() */ @@ -724,9 +825,7 @@ \brief Reports the suites of messages and specifiers that derived classes understand. - \param data The message to report the suite of messages and specifiers. - - \see BHandler::GetSupportedSuites() + \copydetails BHandler::GetSupportedSuites() */ @@ -735,6 +834,7 @@ /*! \name Looper Message Filters + Note that filters added with these methods will be applied to all associated handlers. Have a look at the filtering methods of the BHandler class to see how filters can be applied to the inherited handler of this @@ -748,26 +848,34 @@ /*! \fn void BLooper::AddCommonFilter(BMessageFilter* filter) \brief Add a common filter to the list of filters that are applied to all - incoming messages. - + incoming messages. + Filters can only be applied once, so they cannot be shared between loopers, a handler and a looper or between two handlers. - + The \a filter is not copied; rather a pointer is stored. Keep the \a filter alive as long as it is used by a looper. - - \see RemoveCommonFilter(), SetCommonFilterList(), CommonFilterList() + + \see RemoveCommonFilter() + \see SetCommonFilterList() + \see CommonFilterList() + + \since BeOS R3 */ /*! \fn bool BLooper::RemoveCommonFilter(BMessageFilter* filter) \brief Remove a \a filter from the common message filter list. - + Note that this will not free the memory used by the \a filter, so you should dispose of it yourself. - - \see AddCommonFilter(), SetCommonFilterList(), CommonFilterList() + + \see AddCommonFilter() + \see SetCommonFilterList() + \see CommonFilterList() + + \since BeOS R3 */ @@ -775,45 +883,57 @@ \fn void BLooper::SetCommonFilterList(BList* filters) \brief Set a new list of \a filters that need to be applied to all incoming messages. - + You are responsible for validating that all the items in the list of \a filters are actual filters. The old list is discarded; all the filters are \b destroyed. - + Note that filters can only be applied to one looper or handler. If any of the filters is already associated with another one, this call will fail. - - \see AddCommonFilter(), RemoveCommonFilter(), CommonFilterList() + + \see AddCommonFilter() + \see RemoveCommonFilter() + \see CommonFilterList() + + \since BeOS R3 */ /*! \fn BList* BLooper::CommonFilterList() const \brief Return a list of filters applied to all incoming messages. - + \return A pointer to the internal filter list, or \c NULL if such a list - has not yet been created. Please note that you should use the internal - list management functions to manipulate the internal filter list, in - order to maintain internal consistency. - \see AddCommonFilter(), RemoveCommonFilter(), SetCommonFilterList() + has not yet been created. Please note that you should use the + internal list management functions to manipulate the internal + filter list, in order to maintain internal consistency. + + \see AddCommonFilter() + \see RemoveCommonFilter() + \see SetCommonFilterList() + + \since BeOS R3 */ + //! @} /*! \fn status_t BLooper::Perform(perform_code d, void* arg) \brief Internal method. + + \since Haiku R1 */ /*! \fn BMessage* BLooper::MessageFromPort(bigtime_t timeout) \brief Hook method to retrieve a message from the looper's port. - + The default implementation is called by the internal message looping thread and retrieves the next message from the port that belongs to this looper. - + If you use a looper in a context where it might receive messages from other sources, you can override this method in order to insert these methods into the message processing. Note that any messages that are returned by this @@ -821,5 +941,6 @@ the message. If you override this method, remember to call the base implementation every now and then, in order to retrieve the messages arriving at the default port. -*/ + \since Haiku R1 +*/ diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox index 3de90ef594c..7e32d361c41 100644 --- a/docs/user/app/Message.dox +++ b/docs/user/app/Message.dox @@ -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, niels.reedijk@gmail.com - * + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * John Scipione, jscpione@gmail.com + * * Corresponds to: - * headers/os/app/Message.h rev 21562 - * src/kits/app/Message.cpp rev 22240 + * headers/os/app/Message.h hrev47355 + * src/kits/app/Message.cpp hrev47355 */ @@ -25,66 +26,88 @@ /*! \def B_FIELD_NAME_LENGTH \brief Undocumented... + + \since BeOS R3 */ /*! \def B_PROPERTY_NAME_LENGTH \brief Undocumented... + + \since BeOS R3 */ /*! \var B_NO_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_DIRECT_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_INDEX_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_REVERSE_INDEX_SPECIFIER, \brief Undocumented... + + \since BeOS R3 */ /*! \var B_RANGE_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_REVERSE_RANGE_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_NAME_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_ID_SPECIFIER \brief Undocumented... + + \since BeOS R3 */ /*! \var B_SPECIFIERS_END \brief Undocumented... + + \since BeOS R3 */ @@ -96,7 +119,7 @@ \ingroup app \ingroup libbe \brief A container that can be send and received using the Haiku messaging - subsystem. + subsystem. This class is at the center of the web of messaging classes, in the sense that it defines the actual structure of the messages. Messages have two @@ -126,6 +149,8 @@ To see how messages fit in with the greater picture, have a look at the \ref app_messaging "Messaging Introduction". + + \since BeOS R3 */ @@ -134,46 +159,55 @@ \brief A 4-byte constant that determines the type of message. You can directly manipulate this data member. + + \since BeOS R3 */ /*! \fn BMessage::BMessage() \brief Construct an empty message, without any data members and with a - \a what constant set to \c 0. + \a what constant set to \c 0. \see BMessage(uint32 what) - \see BMessage(const BMessage &other) + \see BMessage(const BMessage& other) + + \since BeOS R3 */ /*! \fn BMessage::BMessage(uint32 what) \brief Construct an empty message with the \a what member set to the - specified value. + specified value. \see BMessage::BMessage() - \see BMessage::BMessage(const BMessage &other) + \see BMessage::BMessage(const BMessage& other) + + \since BeOS R3 */ /*! - \fn BMessage::BMessage(const BMessage &other) + \fn BMessage::BMessage(const BMessage& other) \brief Construct a new message that is a copy of another message. The \a what member and the data values are copied. The metadata, such as - whether or not the message is a drop message or reply information, is - not copied. So if the original message is a reply to a previous message, - which will make IsReply() return \c true, calling the same method on a copy - of the message will return \c false. + whether or not the message is a drop message or reply information is + not copied. If the original message is a reply to a previous message + this will make IsReply() return \c true, while calling the same method on + a copy of the message will return \c false. - \remarks BeOS R5 did keep the metadata of the message. Haiku deviates from - this behavior. Use the Haiku implementation of message copying as the - default behavior. This will keep your applications backwards compatible. + \remark BeOS kept the metadata of the message while Haiku deviates from + this behavior. Use the Haiku implementation of message copying + as the default behavior to keep your applications backwards + compatible. \see BMessage::BMessage() \see BMessage(uint32 what) -*/ + + \since BeOS R3 +*/ /*! @@ -182,15 +216,8 @@ If there still is a sender waiting for a reply, the \c B_NO_REPLY message will be sent to inform them that there won't be a reply. -*/ - - -/*! - \fn BMessage &BMessage::operator=(const BMessage &other) - \brief Copy one message into another. - See the copy constructor, BMessage(const BMessage &other), for details on - what is copied, and what isn't. + \since BeOS R3 */ @@ -204,68 +231,75 @@ /*! \fn status_t BMessage::GetInfo(type_code typeRequested, int32 index, - char **nameFound, type_code *typeFound, int32 *countFound) const + char** nameFound, type_code* typeFound, int32* countFound) const \brief Retrieve the name, the type and the number of items in a message by - an \a index. + an \a index. \param[in] typeRequested If you want to limit the search to only one type, - pass that type code here. If you don't care which type the data has, - you can pass \c B_ANY_TYPE. + pass that type code here. If you don't care which type the data + has, you can pass \c B_ANY_TYPE. \param[in] index The index of the data you want to investigate. \param[out] nameFound The name of the item if it is found. Haiku will fill - in a pointer to the internal name buffer in the message. This means - that you should not manipulate this name. If you are not interested in - the name, you can safely pass \c NULL. + in a pointer to the internal name buffer in the message. This + means that you should not manipulate this name. If you are not + interested in the name, you can safely pass \c NULL. \param[out] typeFound The type of the item at \a index. If you are - not interested in the type (because you specifically asked for a type), - you can safely pass \c NULL. + not interested in the type (because you specifically asked for + a type), you can safely pass \c NULL. \param[out] countFound The number of items at \a index. If data - items have the same name, they will be placed under the same index. + items have the same name, they will be placed under the same + index. \return If the \a index is found, and matches the requested type, - then the other parameters will be filled in. If this is not the case, - the method will return with an error. + then the other parameters will be filled in. If this is not the + case, the method will return with an error. \retval B_OK An match was found. The values have been filled in. \retval B_BAD_INDEX The \a index was out of range. None of the - passed variables have been altered. + passed variables have been altered. \retval B_BAD_TYPE The data field at \a index does not have the - requested type. + requested type. + + \since BeOS R3 */ /*! - \fn status_t BMessage::GetInfo(const char *name, type_code *typeFound, - int32 *countFound) const + \fn status_t BMessage::GetInfo(const char* name, type_code* typeFound, + int32* countFound) const \brief Retrieve the type and the number of data items in this message that - are associated with a \a name. + are associated with a \a name. \param[in] name The name of the data member that you are looking for. \param[out] typeFound In case of a match, the name of the data member will - be put in this parameter. In case you are not interested, you can pass - \c NULL. + be put in this parameter. In case you are not interested, you + can pass \c NULL. \param[out] countFound In case of a match, the number of items at this - label will be in this parameter. In case you are not interested, you - can safely pass \c NULL. + label will be in this parameter. In case you are not + interested, you can safely pass \c NULL. \return If the message has data associated with the given \a name, - the other parameters will contain information associated with the data, - else, the method will return with an error. + the other parameters will contain information associated with the + data, else, the method will return with an error. \retval B_OK A match was found. The other parameters have been filled in. \retval B_BAD_VALUE You passed \c NULL as argument to \a name. \retval B_NAME_NOT_FOUND There is no data with the label \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::GetInfo(const char *name, type_code *typeFound, - bool *fixedSize) const + \fn status_t BMessage::GetInfo(const char* name, type_code* typeFound, + bool* fixedSize) const \brief Retrieve the type and whether or not the size of the data is fixed associated with a \a name. - This method is the same as GetInfo(const char *,type_code *, int32 *) const, + This method is the same as GetInfo(const char*, type_code*, int32*) const, with the difference that you can find out whether or not the size of the data associated with the \a name is fixed. You will get this value in the variable you passed as \a fixedSize parameter. + + \since BeOS R4 */ @@ -277,10 +311,12 @@ It's practical use is limited to debugging purposes. \param type The type you want to find. If you pass \c B_ANY_TYPE, this - method will return the total number of data items. + method will return the total number of data items. \return The number of data items in this message with the specified - \a type, or \c 0 in case no items match the type. + \a type, or \c 0 in case no items match the type. + + \since BeOS R3 */ @@ -289,8 +325,11 @@ \brief Check if the message has data members. \return If this message contains data members, this method will return - \c true, else it will return \c false. + \c true, else it will return \c false. + \see MakeEmpty() + + \since BeOS R3 */ @@ -299,7 +338,9 @@ \brief Check if the message is a system message. \return If this message is a system message, the method will return - \c true. + \c true. + + \since BeOS R3 */ @@ -308,6 +349,8 @@ \brief Check if the message is a reply to a (previous) message. \return If this message is a reply, this method will return \c true. + + \since BeOS R3 */ @@ -320,11 +363,13 @@ are present, and it can be used to debug your message handling routines, especially the handling of those that are sent by external applications, to see if you understand the semantics correctly. + + \since BeOS R3 */ /*! - \fn status_t BMessage::Rename(const char *oldEntry, const char *newEntry) + \fn status_t BMessage::Rename(const char* oldEntry, const char* newEntry) \brief Rename a data label. \param oldEntry The name of the label you want to rename. @@ -333,9 +378,11 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK Renaming succeeded. \retval B_BAD_VALUE Either the \a oldEntry or the - \a newEntry pointers are \c NULL. + \a newEntry pointers are \c NULL. \retval B_NAME_NOT_FOUND There is no data associated with the label - \a oldEntry. + \a oldEntry. + + \since Haiku R1 */ @@ -358,13 +405,15 @@ method will return \c true. \warning This method should not be abused by a thread that sends a message - to track whether or not a message was delivered. This is because the - ownership of the message goes to the receiving looper, which will - delete the message as soon as it is done with it. + to track whether or not a message was delivered. This is because + the ownership of the message goes to the receiving looper, which + will delete the message as soon as it is done with it. \warning If you need to check whether a message is delivered, you should - either ask for a reply, or use one of the synchronous - BMessenger::SendMessage() methods. + either ask for a reply, or use one of the synchronous + BMessenger::SendMessage() methods. + + \since BeOS R3 */ @@ -374,12 +423,16 @@ This method will return \c true, if the sender flagged that it is waiting for a reply, and such a reply has not yet been sent. + + \since BeOS R3 */ /*! \fn bool BMessage::IsSourceRemote() const \brief Check if the message is sent by another application. + + \since BeOS R3 */ @@ -400,17 +453,21 @@ If this method is called on a message that has not been delivered (yet), it will return an empty BMessenger object. + + \since BeOS R3 */ /*! - \fn const BMessage *BMessage::Previous() const + \fn const BMessage* BMessage::Previous() const \brief Get the message to which this message is a reply. \return Returns a new BMessage with the same data stuctures as the message - to which this message is a reply. You get the ownership of this - message, so free it when you're done. If this message isn't a reply to - another message, this method will return \c NULL. + to which this message is a reply. You get the ownership of this + message, so free it when you're done. If this message isn't a + reply to another message, this method will return \c NULL. + + \since BeOS R3 */ @@ -419,16 +476,18 @@ \brief Check if the message was delivered through 'drag and drop'. \return This method returns \c true if the message has been delivered - through drag and drop. It returns \c false if it has been delivered - through the regular messaging functions, or if the message has not - been delivered at all. + through drag and drop. It returns \c false if it has been delivered + through the regular messaging functions, or if the message has not + been delivered at all. \see DropPoint() + + \since BeOS R3 */ /*! - \fn BPoint BMessage::DropPoint(BPoint *offset) const + \fn BPoint BMessage::DropPoint(BPoint* offset) const \brief Get the coordinates of the drop point of the message. If the message has been delivered because of drag and drop, which can be @@ -443,6 +502,8 @@ a \c NULL pointer. \see WasDropped() + + \since BeOS R3 */ @@ -458,28 +519,33 @@ /*! - \fn status_t BMessage::SendReply(uint32 command, BHandler *replyTo) + \fn status_t BMessage::SendReply(uint32 command, BHandler* replyTo) \brief Asynchronously send a reply to this message. - This is an overloaded member of SendReply(BMessage *, BMessenger, bigtime_t). - Use this variant if you want to send a message without data members. + This is an overloaded member of + SendReply(BMessage*, BMessenger, bigtime_t). Use this variant if you + want to send a message without data members. + + \since BeOS R3 */ /*! - \fn status_t BMessage::SendReply(BMessage *reply, BHandler *replyTo, - bigtime_t timeout) + \fn status_t BMessage::SendReply(BMessage* reply, BHandler* replyTo, + bigtime_t timeout) \brief Asynchronously send a reply to this message. - This is an overloaded member of SendReply(BMessage *, BMessenger, bigtime_t). + This is an overloaded member of SendReply(BMessage*, BMessenger, bigtime_t). Use this variant if you want to send the message to a specific handler (instead of a complete messenger). + + \since BeOS R3 */ /*! - \fn status_t BMessage::SendReply(BMessage *reply, BMessenger replyTo, - bigtime_t timeout) + \fn status_t BMessage::SendReply(BMessage* reply, BMessenger replyTo, + bigtime_t timeout) \brief Asynchronously send a reply to this message. This method sends a reply to this message to the sender. On your turn, @@ -490,41 +556,46 @@ \param reply The message that is in reply to this message. \param replyTo In case the receiver needs to reply to the message you are - sending, you can specify the return address with this argument. + sending, you can specify the return address with this argument. \param timeout The maximum time in microseconds this delivery may take. The - \a timeout is a relative timeout. You can also use - \c B_INFINITE_TIMEOUT if you want to wait infinitely for the message - to be delivered. + \a timeout is a relative timeout. You can also use + \c B_INFINITE_TIMEOUT if you want to wait infinitely for the message + to be delivered. \returns A status code, \c B_OK on success or an error code. \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. \retval B_BAD_PORT_ID The reply address is not valid (anymore). \retval B_WOULD_BLOCK The delivery \a timeout was - \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when trying - to deliver the message. + \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when + trying to deliver the message. \retval B_TIMED_OUT The timeout expired while trying to deliver the - message. - \see SendReply(uint32 command, BHandler *replyTo) + message. + + \see SendReply(uint32 command, BHandler* replyTo) + + \since Haiku R1 */ /*! - \fn status_t BMessage::SendReply(uint32 command, BMessage *replyToReply) + \fn status_t BMessage::SendReply(uint32 command, BMessage* replyToReply) \brief Synchronously send a reply to this message, and wait for a reply - back. + back. + + This is an overloaded member of + SendReply(BMessage*, BMessage*, bigtime_t, bigtime_t) + Use this variant if you want to send a message without data members. - This is an overloaded member of SendReply(BMessage *, BMessage *, - bigtime_t, bigtime_t) Use this variant if you want to send a message - without data members. + \since BeOS R3 */ /*! - \fn status_t BMessage::SendReply(BMessage *reply, BMessage *replyToReply, + \fn status_t BMessage::SendReply(BMessage* reply, BMessage* replyToReply, bigtime_t sendTimeout, bigtime_t replyTimeout) - \brief Synchronously send a reply to this message, and wait for a reply - back. + \brief Synchronously send a reply to this message, and wait for a reply + back. This method sends a reply to this message to the sender. The \a reply is delivered, and then the method waits for a reply from @@ -537,25 +608,28 @@ \param reply The message that is in reply to this message. \param[out] replyToReply The reply is copied into this argument. \param sendTimeout The maximum time in microseconds this delivery may take. - The \a timeout is a relative timeout. You can also use - \c B_INFINITE_TIMEOUT if you want to wait infinitely for the message - to be delivered. + The \a timeout is a relative timeout. You can also use + \c B_INFINITE_TIMEOUT if you want to wait infinitely for the message + to be delivered. \param replyTimeout The maximum time in microseconds you want to wait for a - reply. Note that the timer starts when the message has been delivered. + reply. Note that the timer starts when the message has been + delivered. \returns A status code, \c B_OK on success or an error code. \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. - \retval B_BAD_VALUE Either \a reply or \a replyToReply is - \c NULL. + \retval B_BAD_VALUE Either \a reply or \a replyToReply is \c NULL. \retval B_BAD_PORT_ID The reply address is not valid (anymore). \retval B_WOULD_BLOCK The delivery \a timeout was - \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when trying - to deliver the message. + \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when + trying to deliver the message. \retval B_TIMED_OUT The timeout expired while trying to deliver the - message. + message. \retval B_NO_MORE_PORTS All reply ports are in use. - \see SendReply(uint32 command, BMessage *replyToReply) + + \see SendReply(uint32 command, BMessage* replyToReply) + + \since BeOS R3 */ @@ -563,7 +637,7 @@ /*! - \name Flattening methods + \name Flattening Because of historical reasons and for binary compatibility, this class provides a flattening API without inheriting the BFlattenable class. The @@ -578,49 +652,57 @@ /*! \fn ssize_t BMessage::FlattenedSize() const \brief Return the size in bytes required when you want to flatten this - message to a stream of bytes. + message to a stream of bytes. + + \since BeOS R3 */ /*! - \fn status_t BMessage::Flatten(char *buffer, ssize_t size) const + \fn status_t BMessage::Flatten(char* buffer, ssize_t size) const \brief Flatten the message to a \a buffer. \param buffer The buffer to write the data to. \param size The size of the buffer. - \return \c B_OK in case of success, or an error code in case something went - awry. + \return \c B_OK in case of success, or an error code in case something + went awry. \warning Make sure the buffer is large enough to hold the message. This - method does not double-check for you! + method does not double-check for you! + \see FlattenedSize() - \see Flatten(BDataIO *stream, ssize_t *size) const + \see Flatten(BDataIO* stream, ssize_t* size) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::Flatten(BDataIO *stream, ssize_t *size) const + \fn status_t BMessage::Flatten(BDataIO* stream, ssize_t* size) const \brief Flatten the message to a \a stream. - \param[in] stream The stream to flatten the message to. - \param[out] size The method writes the number of bytes actually written to - this argument. - \return \c B_OK in case of success, or an error code in case something went - awry. + \param[in] stream The stream to flatten the message to. + \param[out] size The method writes the number of bytes actually written + to this argument. + \return \c B_OK in case of success, or an error code in case something + went awry. \warning Make sure the subclass of the BDataIO interface either protects - against buffer overwrites, or check if the number of bytes that is - going to be written isn't larger than it can handle. + against buffer overwrites, or check if the number of bytes that + is going to be written isn't larger than it can handle. + \see FlattenedSize() - \see Flatten(char *buffer, ssize_t size) const + \see Flatten(char* buffer, ssize_t size) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::Unflatten(const char *flatBuffer) + \fn status_t BMessage::Unflatten(const char* flatBuffer) \brief Unflatten a message from a buffer and put it into the current - object. + object. This action clears the current contents of the message. @@ -630,16 +712,19 @@ \retval B_OK The buffer has been unflattened. \retval B_BAD_VALUE The buffer does not contain a valid message. \retval B_NO_MEMORY An error occured whilst allocating memory for the data - members. - \see Flatten(char *buffer, ssize_t size) const - \see Unflatten(BDataIO *stream) + members. + + \see Flatten(char* buffer, ssize_t size) const + \see Unflatten(BDataIO* stream) + + \since BeOS R3 */ /*! - \fn status_t BMessage::Unflatten(BDataIO *stream) + \fn status_t BMessage::Unflatten(BDataIO* stream) \brief Unflatten a message from a stream and put it into the current - object. + object. This action clears the current contents of the message. @@ -648,10 +733,13 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The message has been unflattened. \retval B_BAD_VALUE The stream does not contain a valid message. - \retval B_NO_MEMORY An error occured whilst allocating memory for the data - members. - \see Flatten(BDataIO *stream, ssize_t *size) const - \see Unflatten(const char *flatBuffer) + \retval B_NO_MEMORY An error occured whilst allocating memory for the + data members. + + \see Flatten(BDataIO* stream, ssize_t* size) const + \see Unflatten(const char*) + + \since BeOS R3 */ @@ -659,7 +747,7 @@ /*! - \name Specifiers (scripting) + \name Specifiers (Scripting) */ @@ -667,58 +755,76 @@ /*! - \fn status_t BMessage::AddSpecifier(const char *property) + \fn status_t BMessage::AddSpecifier(const char* property) \brief Undocumented. + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddSpecifier(const char *property, int32 index) + \fn status_t BMessage::AddSpecifier(const char* property, int32 index) \brief Undocumented. + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddSpecifier(const char *property, int32 index, - int32 range) + \fn status_t BMessage::AddSpecifier(const char* property, int32 index, + int32 range) \brief Undocumented. + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddSpecifier(const char *property, const char *name) + \fn status_t BMessage::AddSpecifier(const char* property, const char* name) \brief Undocumented. + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddSpecifier(const BMessage *specifier) + \fn status_t BMessage::AddSpecifier(const BMessage* specifier) \brief Undocumented. + + \since BeOS R3 */ /*! \fn status_t BMessage::SetCurrentSpecifier(int32 index) \brief Undocumented. + + \since Haiku R1 */ /*! - \fn status_t BMessage::GetCurrentSpecifier(int32 *index, - BMessage *specifier, int32 *what, const char **property) const + \fn status_t BMessage::GetCurrentSpecifier(int32* index, + BMessage* specifier, int32* what, const char** property) const \brief Undocumented. + + \since BeOS R3 */ /*! \fn bool BMessage::HasSpecifiers() const \brief Undocumented. + + \since BeOS R3 */ /*! \fn status_t BMessage::PopSpecifier() \brief Undocumented. + + \since BeOS R3 */ @@ -734,8 +840,8 @@ /*! - \fn status_t BMessage::AddData(const char *name, type_code type, - const void *data, ssize_t numBytes, bool isFixedSize, int32 count) + \fn status_t BMessage::AddData(const char* name, type_code type, + const void* data, ssize_t numBytes, bool isFixedSize, int32 count) \brief Add \a data of a certain \a type to the message. The amount of \a numBytes is copied into the message. The data is @@ -762,38 +868,39 @@ data you need to pass is too big, find another way to pass it. \param name The label to which this data needs to be associated. If the - \a name already exists, the new data will be added in an - array-like style. + \a name already exists, the new data will be added in an + array-like style. \param type The type of data. If you are adding data to the same \a name, make sure it is the same type. \param data The data buffer to copy the bytes from. - \param numBytes The number of bytes to be copied. If this is the first call - to this method for this type of data, and you set - \a isFixedSize to \c true, this will specify the size of all - consecutive calls to this - method. + \param numBytes The number of bytes to be copied. If this is the first + call to this method for this type of data, and you set + \a isFixedSize to \c true, this will specify the size of all + consecutive calls to this method. \param isFixedSize If this is the first call to this method with this - \a name, you can specify the whether or not all items in this - array should have the same fixed size. + \a name, you can specify the whether or not all items in this + array should have the same fixed size. \param count If this is the first call to this method with this - \a name, you can instruct this message to allocate a number of - items in advance. This does not limit the amount of items though. The - array will grow if needed. + \a name, you can instruct this message to allocate a number of + items in advance. This does not limit the amount of items though. + The array will grow if needed. \returns A status code, \c B_OK on success or an error code. \retval B_OK The \a data is succesfully added. \retval B_BAD_VALUE The \a numBytes is less than, or equal to \c 0, - or the size of this item is larger than the \a name allows, - since it has been specified to have a fixed size. - \retval B_ERROR There was an error whilst creating the label with your - \a name. + or the size of this item is larger than the \a name allows, + since it has been specified to have a fixed size. + \retval B_ERROR There was an error whilst creating the label with + your \a name. \retval B_BAD_TYPE The \a type you specified is different than the - one already associated with \a name. + one already associated with \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddRect(const char *name, BRect aRect) + \fn status_t BMessage::AddRect(const char* name, BRect aRect) \brief Convenience method to add a BRect to the label \a name. This method calls AddData() with the \c B_RECT_TYPE \a type. @@ -807,11 +914,13 @@ \see FindRect() \see GetRect() \see ReplaceRect() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddPoint(const char *name, BPoint aPoint) + \fn status_t BMessage::AddPoint(const char* name, BPoint aPoint) \brief Convenience method to add a BPoint to the label \a name. This method calls AddData() with the \c B_POINT_TYPE \a type. @@ -825,11 +934,13 @@ \see FindPoint() \see GetPoint() \see ReplacePoint() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddString(const char *name, const char *aString) + \fn status_t BMessage::AddString(const char* name, const char* aString) \brief Convenience method to add a C-string to the label \a name. This method calls AddData() with the \c B_STRING_TYPE \a type. @@ -843,11 +954,13 @@ \see FindString() \see GetString() \see ReplaceString() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddString(const char *name, const BString &aString) + \fn status_t BMessage::AddString(const char* name, const BString& aString) \brief Convenience method to add a BString to the label \a name. This method calls AddData() with the \c B_STRING_TYPE \a type. @@ -861,11 +974,13 @@ \see FindString() \see GetString() \see ReplaceString() + + \since BeOS R5 */ /*! - \fn status_t BMessage::AddInt8(const char *name, int8 value) + \fn status_t BMessage::AddInt8(const char* name, int8 value) \brief Convenience method to add an \c int8 to the label \a name. This method calls AddData() with the \c B_INT8_TYPE \a type. @@ -879,11 +994,13 @@ \see FindInt8() \see GetInt8() \see ReplaceInt8() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddInt16(const char *name, int16 value) + \fn status_t BMessage::AddInt16(const char* name, int16 value) \brief Convenience method to add an \c int16 to the label \a name. This method calls AddData() with the \c B_INT16_TYPE \a type. @@ -897,11 +1014,13 @@ \see FindInt16() \see GetInt16() \see ReplaceInt16() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddInt32(const char *name, int32 value) + \fn status_t BMessage::AddInt32(const char* name, int32 value) \brief Convenience method to add an \c int32 to the label \a name. This method calls AddData() with the \c B_INT32_TYPE \a type. @@ -915,11 +1034,13 @@ \see FindInt32() \see GetInt32() \see ReplaceInt32() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddInt64(const char *name, int64 value) + \fn status_t BMessage::AddInt64(const char* name, int64 value) \brief Convenience method to add an \c int64 to the label \a name. This method calls AddData() with the \c B_INT64_TYPE \a type. @@ -933,11 +1054,13 @@ \see FindInt64() \see GetInt64() \see ReplaceInt64() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddBool(const char *name, bool aBoolean) + \fn status_t BMessage::AddBool(const char* name, bool aBoolean) \brief Convenience method to add a \c bool to the label \a name. This method calls AddData() with the \c B_BOOL_TYPE \a type. @@ -951,10 +1074,12 @@ \see FindBool() \see GetBool() \see ReplaceBool() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddFloat(const char *name, float aFloat) + \fn status_t BMessage::AddFloat(const char* name, float aFloat) \brief Convenience method to add a \c float to the label \a name. This method calls AddData() with the \c B_FLOAT_TYPE \a type. @@ -968,11 +1093,13 @@ \see FindFloat() \see GetFloat() \see ReplaceFloat() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddDouble(const char *name, double aDouble) + \fn status_t BMessage::AddDouble(const char* name, double aDouble) \brief Convenience method to add a \c double to the label \a name. This method calls AddData() with the \c B_DOUBLE_TYPE \a type. @@ -986,20 +1113,23 @@ \see FindDouble() \see GetDouble() \see ReplaceDouble() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddPointer(const char *name, const void *aPointer) + \fn status_t BMessage::AddPointer(const char* name, const void* aPointer) \brief Convenience method to add a \c pointer to the label \a name. This method calls AddData() with the \c B_POINTER_TYPE \a type. \warning If you want to share objects between applications, remember - that each application has its own address space, and that it therefore - is useless to try to pass around objects by sending pointers in - messages. You should think about copying the entire object in the - message, or you should consider using shared memory. + that each application has its own address space, and that it + therefore is useless to try to pass around objects by sending + pointers in messages. You should think about copying the + entire object in the message, or you should consider using + shared memory. \param name The label to associate the data with. \param aPointer The value to store in the message. @@ -1010,11 +1140,13 @@ \see FindPointer() \see GetPointer() \see ReplacePointer() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddMessenger(const char *name, BMessenger messenger) + \fn status_t BMessage::AddMessenger(const char* name, BMessenger messenger) \brief Convenience method to add a messenger to the label \a name. This method calls AddData() with the \c B_MESSENGER_TYPE \a type. @@ -1027,13 +1159,15 @@ \see AddData() for a more detailed overview of the inner workings. \see FindMessenger() \see ReplaceMessenger() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddRef(const char *name, const entry_ref *ref) + \fn status_t BMessage::AddRef(const char* name, const entry_ref* ref) \brief Convenience method to add an \c entry_ref to the label - \a name. + \a name. This method calls AddData() with the \c B_REF_TYPE \a type. @@ -1045,11 +1179,14 @@ \see AddData() for a more detailed overview of the inner workings. \see FindRef() \see ReplaceRef() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddMessage(const char *name, const BMessage *message) + \fn status_t BMessage::AddMessage(const char* name, + const BMessage* message) \brief Convenience method to add a message to the label \a name. This method calls AddData() with the \c B_MESSAGE_TYPE \a type. @@ -1062,11 +1199,13 @@ \see AddData() for a more detailed overview of the inner workings. \see FindMessage() \see ReplaceMessage() + + \since BeOS R3 */ /*! - \fn status_t BMessage::AddFlat(const char *name, BFlattenable *object, + \fn status_t BMessage::AddFlat(const char* name, BFlattenable* object, int32 count = 1) \brief Convenience method to add a flattenable to the label \a name. @@ -1079,13 +1218,15 @@ \param name The label to associate the data with. \param object The object to flatten into the message. \param count The number of items to pre-allocate associated with this - \a name. + \a name. \returns A status code, \c B_OK on success or an error code. \see AddData() for a more detailed overview of the inner workings. \see FindFlat() \see ReplaceFlat() + + \since BeOS R3 */ @@ -1101,9 +1242,9 @@ /*! - \fn status_t BMessage::RemoveData(const char *name, int32 index) + \fn status_t BMessage::RemoveData(const char* name, int32 index) \brief Remove data associated with \a name at a specified - \a index. + \a index. If this is the only instance of the data, then the entire label will be removed. This means you can recreate it with another type. @@ -1120,11 +1261,13 @@ \see RemoveName() \see MakeEmpty() + + \since BeOS R3 */ /*! - \fn status_t BMessage::RemoveName(const char *name) + \fn status_t BMessage::RemoveName(const char* name) \brief Remove all data associated with a \a name. This also removes the label, so that you can recreate it with another type, @@ -1139,6 +1282,8 @@ \see RemoveData() \see MakeEmpty() + + \since BeOS R3 */ @@ -1153,6 +1298,8 @@ \see RemoveData() \see RemoveName() + + \since BeOS R3 */ @@ -1179,10 +1326,10 @@ /*! - \fn status_t BMessage::FindData(const char *name, type_code type, - int32 index, const void **data, ssize_t *numBytes) const + \fn status_t BMessage::FindData(const char* name, type_code type, + int32 index, const void** data, ssize_t* numBytes) const \brief Find \a data that is stored in this message at an - \a index. + \a index. This method matches the label \a name with the \a type you are asking for, and it looks for the data that is stored at a certain @@ -1190,7 +1337,7 @@ to the internal buffer, and the method will put the size of the item in \a numBytes. - Note that only this method, and FindString(const char *, const char **), + Note that only this method, and FindString(const char*, const char**), pass a pointer to the internal buffer. The other more specific methods, such as FindBool() and FindRect() copy the data into a buffer you specify. This means that the data retrieved with this method is valid until the @@ -1198,9 +1345,9 @@ \param name The label the data should be associated with. \param type The type of data you want to retrieve. You can pass - \c B_ANY_TYPE if you don't mind which type the data is. + \c B_ANY_TYPE if you don't mind which type the data is. \param index The index in the array of the data that you want to retrieve. - Note that the array is zero-based. + Note that the array is zero-based. \param[out] data A pointer to a pointer where the data can point to. \param[out] numBytes The size of the data will be put in this parameter. @@ -1211,34 +1358,41 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see status_t FindData(const char *, type_code, int32, - const void **, ssize_t *) const + \see status_t FindData(const char*, type_code, int32, + const void**, ssize_t*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindData(const char *name, type_code type, - const void **data, ssize_t *numBytes) const + \fn status_t BMessage::FindData(const char* name, type_code type, + const void** data, ssize_t* numBytes) const \brief Find \a data that is stored in this message. This is an overloaded version of - FindData(const char *, type_code, int32, const void **, ssize_t *) const + FindData(const char*, type_code, int32, const void**, ssize_t*) const where data is sought at \a index \c 0. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindRect(const char *name, BRect *rect) const + \fn status_t BMessage::FindRect(const char* name, BRect* rect) const \brief Find a rectangle at the label \a name. This is an overloaded version of - FindRect(const char *, int32, BRect *) const + FindRect(const char*, int32, BRect*) const where the data is sought at \a index \c 0. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindRect(const char *name, int32 index, BRect *rect) const + \fn status_t BMessage::FindRect(const char* name, int32 index, + BRect* rect) const \brief Find a rectangle at the label \a name at an \a index. This method looks for the data with the \c B_RECT_TYPE, and copies it into @@ -1253,22 +1407,27 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindRect(const char *, BRect *) const + \see FindRect(const char*, BRect*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindPoint(const char *name, BPoint *point) const + \fn status_t BMessage::FindPoint(const char* name, BPoint* point) const \brief Find a point at the label \a name. This is an overloaded version of - FindPoint(const char *, int32, BPoint *) const + FindPoint(const char*, int32, BPoint*) const where the data is sought at \a index \c 0. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindPoint(const char *name, int32 index, BPoint *point) const + \fn status_t BMessage::FindPoint(const char* name, int32 index, + BPoint* point) const \brief Find a point at the label \a name at an \a index. This method looks for the data with the \c B_POINT_TYPE, and copies it into @@ -1283,23 +1442,28 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindPoint(const char *, BPoint *) const + \see FindPoint(const char*, BPoint*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindString(const char *name, const char **string) const + \fn status_t BMessage::FindString(const char* name, + const char** string) const \brief Find a string at the label \a name. This is an overloaded version of - FindString(const char *, int32, const char **) const + FindString(const char*, int32, const char**) const where the data is sought at \a index \c 0. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindString(const char *name, int32 index, - const char ** string) const + \fn status_t BMessage::FindString(const char* name, int32 index, + const char** string) const \brief Find a string at the label \a name at an \a index. This method looks for the data with the \c B_STRING_TYPE, and returns a @@ -1315,23 +1479,28 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindString(const char *, const char **) const - \see FindString(const char *, int32, BString *) const + \see FindString(const char*, const char**) const + \see FindString(const char*, int32, BString*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindString(const char *name, BString *string) const + \fn status_t BMessage::FindString(const char* name, BString* string) const \brief Find a string at the label \a name. This is an overloaded version of - FindString(const char *, int32, BString *) const + FindString(const char*, int32, BString*) const where the data is sought at \a index \c 0. + + \since BeOS R5 */ /*! - \fn status_t BMessage::FindString(const char *name, int32 index, BString *string) const + \fn status_t BMessage::FindString(const char* name, int32 index, + BString* string) const \brief Find a string at the label \a name at an \a index. This method looks for the data with the \c B_STRING_TYPE, and copies it @@ -1346,22 +1515,28 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindString(const char *, BString *) const - \see FindString(const char *, int32, const char **) const + \see FindString(const char*, BString*) const + \see FindString(const char*, int32, const char**) const + + \since BeOS R5 */ /*! - \fn status_t BMessage::FindInt8(const char *name, int8 *value) const + \fn status_t BMessage::FindInt8(const char* name, int8* value) const \brief Find an integer at the label \a name. - This is an overloaded version of FindInt8(const char *, int32, int8 *) const + This is an overloaded version of + FindInt8(const char*, int32, int8*) const where the data is sought at \a index \c 0. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt8(const char *name, int32 index, int8 *value) const + \fn status_t BMessage::FindInt8(const char* name, int32 index, + int8* value) const \brief Find an integer at the label \a name at an \a index. This method looks for the data with the \c B_INT8_TYPE, and copies it into @@ -1376,15 +1551,17 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindInt8(const char *, int8 *) const + \see FindInt8(const char*, int8*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt16(const char *name, int16 *value) const + \fn status_t BMessage::FindInt16(const char* name, int16* value) const \brief Find an integer at the label \a name. - This is an overloaded version of FindInt8(const char *, int32, int16 *) const + This is an overloaded version of FindInt8(const char*, int32, int16*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1393,11 +1570,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt16(const char *name, int32 index, int16 *value) const + \fn status_t BMessage::FindInt16(const char* name, int32 index, + int16* value) const \brief Find an integer at the label \a name at an \a index. This method looks for the data with the \c B_INT16_TYPE, and copies it into @@ -1412,16 +1592,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindInt16(const char *, int16 *) const + \see FindInt16(const char*, int16*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt32(const char *name, int32 *value) const + \fn status_t BMessage::FindInt32(const char* name, int32* value) const \brief Find an integer at the label \a name. This is an overloaded version of - FindInt32(const char *, int32, int32 *) const + FindInt32(const char*, int32, int32*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1430,15 +1612,18 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt32(const char *name, int32 index, int32 *value) const + \fn status_t BMessage::FindInt32(const char* name, int32 index, + int32* value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \c B_INT32_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_INT32_TYPE, and copies + it into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1449,16 +1634,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindInt32(const char *, int32 *) const + \see FindInt32(const char*, int32*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt64(const char *name, int64 *value) const + \fn status_t BMessage::FindInt64(const char* name, int64* value) const \brief Find an integer at the label \a name. This is an overloaded version of - FindInt64(const char *, int32, int64 *) const + FindInt64(const char*, int32, int64*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1467,15 +1654,18 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindInt64(const char *name, int32 index, int64 *value) const + \fn status_t BMessage::FindInt64(const char* name, int32 index, + int64* value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \c B_INT64_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_INT64_TYPE, and copies + it into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1486,16 +1676,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindInt64(const char *, int64 *) const + \see FindInt64(const char*, int64*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindBool(const char *name, bool *value) const + \fn status_t BMessage::FindBool(const char* name, bool* value) const \brief Find a boolean at the label \a name. This is an overloaded version of - FindBool(const char *, int32, bool *) const + FindBool(const char*, int32, bool*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1504,11 +1696,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindBool(const char *name, int32 index, bool *value) const + \fn status_t BMessage::FindBool(const char* name, int32 index, + bool* value) const \brief Find a boolean at the label \a name at an \a index. This method looks for the data with the \c B_BOOL_TYPE, and copies it into @@ -1523,16 +1718,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindBool(const char *, bool *) const + \see FindBool(const char*, bool*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindFloat(const char *name, float *value) const + \fn status_t BMessage::FindFloat(const char* name, float* value) const \brief Find a float at the label \a name. This is an overloaded version of - FindFloat(const char *, int32, float *) const + FindFloat(const char*, int32, float*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1541,15 +1738,18 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindFloat(const char *name, int32 index, float *value) const + \fn status_t BMessage::FindFloat(const char* name, int32 index, + float* value) const \brief Find a float at the label \a name at an \a index. - This method looks for the data with the \c B_FLOAT_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_FLOAT_TYPE, and copies + it into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1560,16 +1760,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindFloat(const char *, float *) const + \see FindFloat(const char*, float*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindDouble(const char *name, double *value) const + \fn status_t BMessage::FindDouble(const char* name, double* value) const \brief Find a double at the label \a name. This is an overloaded version of - FindDouble(const char *, int32, double *) const + FindDouble(const char*, int32, double*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1578,11 +1780,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindDouble(const char *name, int32 index, double *value) const + \fn status_t BMessage::FindDouble(const char* name, int32 index, + double* value) const \brief Find a double at the label \a name at an \a index. This method looks for the data with the \c B_DOUBLE_TYPE, and copies it into @@ -1597,16 +1802,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindDouble(const char *, double *) const + \see FindDouble(const char*, double*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindPointer(const char *name, void **pointer) const + \fn status_t BMessage::FindPointer(const char* name, void** pointer) const \brief Find a pointer at the label \a name. This is an overloaded version of - FindPointer(const char *, int32, void *) const + FindPointer(const char*, int32, void*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1615,21 +1822,24 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindPointer(const char *name, int32 index, void **pointer) const + \fn status_t BMessage::FindPointer(const char* name, int32 index, + void** pointer) const \brief Find a pointer at the label \a name at an \a index. - This method looks for the data with the \c B_POINTER_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_POINTER_TYPE, and copies + it into a provided buffer. \warning If you want to share objects between applications, remember - that each application has its own address space, and that it therefore - is useless to try to pass around objects by sending pointers in - messages. You should think about copying the entire object in the - message, or you should consider using shared memory. + that each application has its own address space, and that it + therefore is useless to try to pass around objects by sending + pointers in messages. You should think about copying the entire + object in the message, or you should consider using shared memory. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1640,16 +1850,19 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindPointer(const char *, double *) const + \see FindPointer(const char*, double*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindMessenger(const char* name, BMessenger* messenger) const + \fn status_t BMessage::FindMessenger(const char* name, + BMessenger* messenger) const \brief Find a messenger at the label \a name. This is an overloaded version of - FindMessenger(const char *, int32, BMessenger *) const + FindMessenger(const char*, int32, BMessenger*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1658,11 +1871,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindMessenger(const char *name, int32 index, BMessenger *messenger) const + \fn status_t BMessage::FindMessenger(const char* name, int32 index, + BMessenger* messenger) const \brief Find a messenger at the label \a name at an \a index. This method looks for the data with the \c B_MESSENGER_TYPE, and copies it @@ -1677,16 +1893,18 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindMessenger(const char *, BMessenger *) const + \see FindMessenger(const char*, BMessenger*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindRef(const char *name, entry_ref *ref) const + \fn status_t BMessage::FindRef(const char* name, entry_ref* ref) const \brief Find a reference to a file at the label \a name. This is an overloaded version of - FindRef(const char *, int32, entry_ref *) const + FindRef(const char*, int32, entry_ref*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1695,13 +1913,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindRef(const char *name, int32 index, entry_ref *ref) const + \fn status_t BMessage::FindRef(const char* name, int32 index, + entry_ref* ref) const \brief Find a reference to a file at the label \a name at an - \a index. + \a index. This method looks for the data with the \c B_REF_TYPE, and copies it into a provided buffer. @@ -1715,16 +1936,19 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindRef(const char *, entry_ref *) const + \see FindRef(const char*, entry_ref*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindMessage(const char *name, BMessage *message) const + \fn status_t BMessage::FindMessage(const char* name, + BMessage* message) const \brief Find a message at the label \a name. This is an overloaded version of - FindMessage(const char *, int32, BMessage *) const + FindMessage(const char*, int32, BMessage*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1733,15 +1957,18 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindMessage(const char *name, int32 index, BMessage *message) const + \fn status_t BMessage::FindMessage(const char* name, int32 index, + BMessage* message) const \brief Find a message at the label \a name at an \a index. - This method looks for the data with the \c B_MESSAGE_TYPE, and copies it - into a provided buffer. + This method looks for the data with the \c B_MESSAGE_TYPE, and + copies it into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1752,16 +1979,19 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindMessage(const char *, BMessage *) const + \see FindMessage(const char*, BMessage*) const + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindFlat(const char *name, BFlattenable *object) const + \fn status_t BMessage::FindFlat(const char* name, + BFlattenable* object) const \brief Find a flattened object at the label \a name. This is an overloaded version of - FindFlat(const char *, int32, BFlattenable *) const + FindFlat(const char*, int32, BFlattenable*) const where the data is sought at \a index \c 0. \param name The label to which the data is associated. @@ -1770,14 +2000,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::FindFlat(const char *name, int32 index, - BFlattenable *object) const + \fn status_t BMessage::FindFlat(const char* name, int32 index, + BFlattenable* object) const \brief Find a flattened object at the label \a name at an - \a index. + \a index. The type is determined by the type of the passed object. If that type is available at the specified label, then the Unflatten() method of that @@ -1792,7 +2024,9 @@ \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see FindFlat(const char *, BFlattenable *) const + \see FindFlat(const char*, BFlattenable*) const + + \since BeOS R3 */ @@ -1810,33 +2044,34 @@ /*! - \fn status_t BMessage::ReplaceData(const char *name, type_code type, - const void *data, ssize_t numBytes) + \fn status_t BMessage::ReplaceData(const char* name, type_code type, + const void* data, ssize_t numBytes) \brief Replace the data at label \a name. This method is an overloaded method that replaces the data at \a index \c 0. See - ReplaceData(const char *, type_code, int32, const void *, ssize_t). + ReplaceData(const char*, type_code, int32, const void*, ssize_t). \param name The name associated with the data to replace. \param type The type of the data. - \param data A pointer to the new data that needs to be copied into the - message. + \param data A pointer to the new data that needs to be copied into + the message. \param numBytes The size of the new data. \returns A status code, \c B_OK on success or an error code. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceData(const char *name, type_code type, - int32 index, const void *data, ssize_t numBytes) + \fn status_t BMessage::ReplaceData(const char* name, type_code type, + int32 index, const void* data, ssize_t numBytes) \brief Replace the data at label \a name at a specified - \a index. + \a index. The conditions for replacing data are that the\a name is correct, - the \a type matches and the data entry at \a index - exists. + the \a type matches and the data entry at \a index exists. There is also a collection of convenience methods, that allow you to efficiently replace rectanges (ReplaceRect()), booleans (ReplaceBool()), @@ -1845,25 +2080,28 @@ \param name The name associated with the data to replace. \param type The type of the data. \param index The index in the array to replace. - \param data A pointer to the new data that needs to be copied into the - message. + \param data A pointer to the new data that needs to be copied into + the message. \param numBytes The size of the new data. \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_BAD_VALUE One of the input parameters are invalid. Check that - you did not pass \c NULL, and in case the field has fixed sized data, - check that \a numBytes is the same as the specified fixed size. + you did not pass \c NULL, and in case the field has fixed sized + data, check that \a numBytes is the same as the specified fixed + size. \retval B_BAD_INDEX The \a index is out of range. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceRect(const char *name, BRect aRect) + \fn status_t BMessage::ReplaceRect(const char* name, BRect aRect) \brief Replace a rectangle at the label \a name. This method is an overloaded method of - ReplaceRect(const char *, int32, BRect). + ReplaceRect(const char*, int32, BRect). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -1872,13 +2110,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceRect(const char *name, int32 index, BRect aRect) + \fn status_t BMessage::ReplaceRect(const char* name, int32 index, + BRect aRect) \brief Replace a rectangle at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_RECT_TYPE. @@ -1893,15 +2134,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceRect(const char*, BRect) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplacePoint(const char *name, BPoint aPoint) + \fn status_t BMessage::ReplacePoint(const char* name, BPoint aPoint) \brief Replace a point at the label \a name. This method is an overloaded method of - ReplacePoint(const char *, int32, BPoint). + ReplacePoint(const char*, int32, BPoint). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -1910,13 +2153,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The object now contains the requested data. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplacePoint(const char *name, int32 index, BPoint aPoint) + \fn status_t BMessage::ReplacePoint(const char* name, int32 index, + BPoint aPoint) \brief Replace a point at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_POINT_TYPE. @@ -1931,15 +2177,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplacePoint(const char*, aPoint) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceString(const char *name, const char *aString) + \fn status_t BMessage::ReplaceString(const char* name, const char* aString) \brief Replace a string at the label \a name. This method is an overloaded method of - ReplaceString(const char *, int32, const char *). + ReplaceString(const char*, int32, const char*). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -1948,13 +2196,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceString(const char *name, int32 index, const char *aString) + \fn status_t BMessage::ReplaceString(const char* name, int32 index, + const char* aString) \brief Replace a string at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_STRING_TYPE. @@ -1968,16 +2219,19 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplaceString(const char*, const char *) + \see ReplaceString(const char*, const char*) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceString(const char *name, const BString &aString) + \fn status_t BMessage::ReplaceString(const char* name, + const BString& aString) \brief Replace a string at the label \a name. This method is an overloaded method of - ReplaceString(const char *, int32, BString &). + ReplaceString(const char*, int32, BString&). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -1986,13 +2240,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R5 */ /*! - \fn status_t BMessage::ReplaceString(const char *name, int32 index, const BString &aString) + \fn status_t BMessage::ReplaceString(const char* name, int32 index, + const BString& aString) \brief Replace a string at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_STRING_TYPE. @@ -2006,16 +2263,18 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplaceString(const char*, BString &) + \see ReplaceString(const char*, BString&) + + \since BeOS R5 */ /*! - \fn status_t BMessage::ReplaceInt8(const char *name, int8 value) + \fn status_t BMessage::ReplaceInt8(const char* name, int8 value) \brief Replace an integer at the label \a name. This method is an overloaded method of - ReplaceInt8(const char *, int32, int8). + ReplaceInt8(const char*, int32, int8). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2024,13 +2283,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt8(const char *name, int32 index, int8 value) + \fn status_t BMessage::ReplaceInt8(const char* name, int32 index, + int8 value) \brief Replace an integer at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT8_TYPE. @@ -2045,15 +2307,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceInt8(const char*, int8) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt16(const char *name, int16 value) + \fn status_t BMessage::ReplaceInt16(const char* name, int16 value) \brief Replace an integer at the label \a name. This method is an overloaded method of - ReplaceInt16(const char *, int32, int16). + ReplaceInt16(const char*, int32, int16). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2062,13 +2326,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt16(const char *name, int32 index, int16 value) + \fn status_t BMessage::ReplaceInt16(const char* name, int32 index, + int16 value) \brief Replace an integer at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT16_TYPE. @@ -2083,15 +2350,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceInt16(const char*, int16) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt32(const char *name, int32 value) + \fn status_t BMessage::ReplaceInt32(const char* name, int32 value) \brief Replace an integer at the label \a name. This method is an overloaded method of - ReplaceInt8(const char *, int32, int32). + ReplaceInt8(const char*, int32, int32). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2100,13 +2369,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt32(const char *name, int32 index, int32 value) + \fn status_t BMessage::ReplaceInt32(const char* name, int32 index, + int32 value) \brief Replace an integer at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT32_TYPE. @@ -2121,15 +2393,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceInt32(const char*, int32) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt64(const char *name, int64 value) + \fn status_t BMessage::ReplaceInt64(const char* name, int64 value) \brief Replace an integer at the label \a name. This method is an overloaded method of - ReplaceInt8(const char *, int32, int64). + ReplaceInt8(const char*, int32, int64). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2138,13 +2412,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceInt64(const char *name, int32 index, int64 value) + \fn status_t BMessage::ReplaceInt64(const char* name, int32 index, + int64 value) \brief Replace an integer at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT64_TYPE. @@ -2159,15 +2436,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceInt64(const char*, int64) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceBool(const char *name, bool aBoolean) + \fn status_t BMessage::ReplaceBool(const char* name, bool aBoolean) \brief Replace a boolean at the label \a name. This method is an overloaded method of - ReplaceBool(const char *, int32, bool). + ReplaceBool(const char*, int32, bool). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2176,13 +2455,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceBool(const char *name, int32 index, bool aBoolean) + \fn status_t BMessage::ReplaceBool(const char* name, int32 index, + bool aBoolean) \brief Replace a boolean at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_BOOL_TYPE. @@ -2197,15 +2479,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceBool(const char*, bool) + + \since BeOS R5 */ /*! - \fn status_t BMessage::ReplaceFloat(const char *name, float aFloat) + \fn status_t BMessage::ReplaceFloat(const char* name, float aFloat) \brief Replace a float at the label \a name. This method is an overloaded method of - ReplaceFloat(const char *, int32, float). + ReplaceFloat(const char*, int32, float). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2214,13 +2498,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceFloat(const char *name, int32 index, float aFloat) + \fn status_t BMessage::ReplaceFloat(const char* name, int32 index, + float aFloat) \brief Replace a float at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_FLOAT_TYPE. @@ -2235,15 +2522,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceFloat(const char*, float) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceDouble(const char *name, double aDouble) + \fn status_t BMessage::ReplaceDouble(const char* name, double aDouble) \brief Replace a double at the label \a name. This method is an overloaded method of - ReplaceDouble(const char *, int32, double). + ReplaceDouble(const char*, int32, double). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2252,13 +2541,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceDouble(const char *name, int32 index, double aDouble) + \fn status_t BMessage::ReplaceDouble(const char* name, int32 index, + double aDouble) \brief Replace a double at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_DOUBLE_TYPE. @@ -2273,15 +2565,18 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceDouble(const char*, double) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplacePointer(const char *name, const void *pointer) + \fn status_t BMessage::ReplacePointer(const char* name, + const void* pointer) \brief Replace a pointer at the label \a name. This method is an overloaded method of - ReplacePointer(const char *, int32, const void *). + ReplacePointer(const char*, int32, const void*). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2290,11 +2585,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplacePointer(const char *name, int32 index, const void *pointer) + \fn status_t BMessage::ReplacePointer(const char* name, int32 index, + const void* pointer) \brief Replace a pointer at the label \a name at a specified \a index. The data at the specified \a name and \a index will be replaced, if it @@ -2309,16 +2607,19 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplacePointer(const char*, const void *) + \see ReplacePointer(const char*, const void*) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceMessenger(const char *name, BMessenger messenger) + \fn status_t BMessage::ReplaceMessenger(const char* name, + BMessenger messenger) \brief Replace a messenger at the label \a name. This method is an overloaded method of - ReplaceMessenger(const char *, int32, BMessenger). + ReplaceMessenger(const char*, int32, BMessenger). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2327,13 +2628,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceMessenger(const char *name, int32 index, BMessenger messenger) + \fn status_t BMessage::ReplaceMessenger(const char* name, int32 index, + BMessenger messenger) \brief Replace a messenger at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_MESSENGER_TYPE. @@ -2348,15 +2652,17 @@ \retval B_NAME_NOT_FOUND There is no field with this \a name. \see ReplaceMessenger(const char*, BMessenger) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceRef(const char *name,const entry_ref *ref) + \fn status_t BMessage::ReplaceRef(const char* name, const entry_ref* ref) \brief Replace a reference to a file at the label \a name. This method is an overloaded method of - ReplaceRef(const char *, int32, entry_ref *). + ReplaceRef(const char*, int32, entry_ref*). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2365,11 +2671,14 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceRef( const char *name, int32 index, const entry_ref *ref) + \fn status_t BMessage::ReplaceRef(const char* name, int32 index, + const entry_ref* ref) \brief Replace a reference to a file at the label \a name at a specified \a index. @@ -2385,16 +2694,19 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplaceRef(const char*, entry_ref *) + \see ReplaceRef(const char*, entry_ref*) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceMessage(const char *name, const BMessage *message) + \fn status_t BMessage::ReplaceMessage(const char* name, + const BMessage* message) \brief Replace a message at the label \a name. This method is an overloaded method of - ReplaceMessage(const char *, int32, BMessage *). + ReplaceMessage(const char*, int32, BMessage*). It replaces the data at \a index \c 0. \param name The name associated with the data to replace. @@ -2403,13 +2715,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceMessage(const char *name, int32 index, const BMessage *message) + \fn status_t BMessage::ReplaceMessage(const char* name, int32 index, + const BMessage* message) \brief Replace a message at the label \a name at a specified - \a index. + \a index. The data at the specified \a name and \a index will be replaced, if it matches the \c B_MESSAGE_TYPE. @@ -2423,16 +2738,18 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplaceMessage(const char*, BMessage *) + \see ReplaceMessage(const char*, BMessage*) + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceFlat(const char *name, BFlattenable *object) + \fn status_t BMessage::ReplaceFlat(const char* name, BFlattenable* object) \brief Replace a flattened object at the label \a name. This method is an overloaded method of - ReplaceFlat(const char *, int32, BFlattenable *). + ReplaceFlat(const char*, int32, BFlattenable*). It replaces the data at \a index \c 0. @@ -2442,13 +2759,16 @@ \returns A status code, \c B_OK on success or an error code. \retval B_OK The operation succeeded. \retval B_NAME_NOT_FOUND There is no field with this \a name. + + \since BeOS R3 */ /*! - \fn status_t BMessage::ReplaceFlat(const char *name, int32 index, BFlattenable *object) + \fn status_t BMessage::ReplaceFlat(const char* name, int32 index, + BFlattenable* object) \brief Replace a flattened object at the label \a name at a - specified \a index. + specified \a index. The data at the specified \a name and \a index will be replaced, if it matches the type returned by your object. This method uses @@ -2463,7 +2783,9 @@ \retval B_BAD_INDEX The index was out of range. \retval B_NAME_NOT_FOUND There is no field with this \a name. - \see ReplaceFlat(const char*, BFlattenable *) + \see ReplaceFlat(const char*, BFlattenable*) + + \since BeOS R3 */ @@ -2471,11 +2793,10 @@ /*! - \name Deprecated methods + \name Operators - These methods are likely to disappear as they have been replaced by safer - and more powerful methods but are implemented for the purpose of binary - compatibility. + The new and delete operators are deprecated and are only provided for + backwards compatibility. */ @@ -2483,182 +2804,328 @@ /*! - \fn void *BMessage::operator new(size_t size) - \brief Internal operator. + \fn BMessage& BMessage::operator=(const BMessage& other) + \brief Copy one message into another. + + See the copy constructor, BMessage(const BMessage& other), for details on + what is copied, and what isn't. + + \since BeOS R3 */ /*! - \fn void *BMessage::operator new(size_t, void *pointer) - \brief Internal operator. + \fn void* BMessage::operator new(size_t size) + \brief Allocates \a size bytes of memory for a BMessage. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn void BMessage::operator delete(void *pointer, size_t size) - \brief Internal operator. + \fn void* BMessage::operator new(size_t, void* pointer) + \brief Allocates \a size bytes of memory for a BMessage. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasRect(const char *, int32) const + \fn void BMessage::operator delete(void* pointer, size_t size) + \brief Frees memory allocated by new. + + \warning This method is deprecated, do not use. + + \since BeOS R5 +*/ + + +//! @} + + +/*! + \name Deprecated Methods + + These methods are likely to disappear as they have been replaced by safer + and more powerful methods but are implemented for the purpose of binary + compatibility. +*/ + + +//! @{ + + +/*! + \fn bool BMessage::HasRect(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasPoint(const char *, int32) const + \fn bool BMessage::HasPoint(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasString(const char *, int32) const + \fn bool BMessage::HasString(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasInt8(const char *, int32) const + \fn bool BMessage::HasInt8(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasInt16(const char *, int32) const + \fn bool BMessage::HasInt16(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasInt32(const char *, int32) const + \fn bool BMessage::HasInt32(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasInt64(const char *, int32) const + \fn bool BMessage::HasInt64(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasBool(const char *, int32) const + \fn bool BMessage::HasBool(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasFloat(const char *, int32) const + \fn bool BMessage::HasFloat(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasDouble(const char *, int32) const + \fn bool BMessage::HasDouble(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasPointer(const char *, int32) const + \fn bool BMessage::HasPointer(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasMessenger(const char *, int32) const + \fn bool BMessage::HasMessenger(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasRef(const char *, int32) const + \fn bool BMessage::HasRef(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasMessage(const char *, int32) const + \fn bool BMessage::HasMessage(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasFlat(const char *, const BFlattenable *) const + \fn bool BMessage::HasFlat(const char*, const BFlattenable*) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasFlat(const char *, int32, const BFlattenable *) const + \fn bool BMessage::HasFlat(const char*, int32, const BFlattenable*) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::HasData(const char *, type_code , int32) const + \fn bool BMessage::HasData(const char*, type_code, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn BRect BMessage::FindRect(const char *, int32) const + \fn BRect BMessage::FindRect(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn BPoint BMessage::FindPoint(const char *, int32) const + \fn BPoint BMessage::FindPoint(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn const char *BMessage::FindString(const char *, int32) const + \fn const char* BMessage::FindString(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn int8 BMessage::FindInt8(const char *, int32) const + \fn int8 BMessage::FindInt8(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn int16 BMessage::FindInt16(const char *, int32) const + \fn int16 BMessage::FindInt16(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn int32 BMessage::FindInt32(const char *, int32) const + \fn int32 BMessage::FindInt32(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn int64 BMessage::FindInt64(const char *, int32) const + \fn int64 BMessage::FindInt64(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn bool BMessage::FindBool(const char *, int32) const + \fn bool BMessage::FindBool(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn float BMessage::FindFloat(const char *, int32) const + \fn float BMessage::FindFloat(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ /*! - \fn double BMessage::FindDouble(const char *, int32) const + \fn double BMessage::FindDouble(const char*, int32) const \brief Deprecated. + + \warning This method is deprecated, do not use. + + \since BeOS R3 */ @@ -2705,6 +3172,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2720,6 +3189,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2733,6 +3204,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2748,6 +3221,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2761,6 +3236,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2776,6 +3253,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2789,6 +3268,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2804,6 +3285,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2817,6 +3300,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2832,6 +3317,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2845,6 +3332,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2860,6 +3349,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2873,6 +3364,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2888,6 +3381,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2901,6 +3396,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2916,6 +3413,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2929,6 +3428,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2944,6 +3445,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2957,6 +3460,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2972,6 +3477,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -2985,6 +3492,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3000,6 +3509,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3014,6 +3525,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3029,6 +3542,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3043,6 +3558,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3058,6 +3575,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3072,6 +3591,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3087,6 +3608,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3100,6 +3623,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3115,6 +3640,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3129,6 +3656,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3144,6 +3673,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3158,6 +3689,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ @@ -3173,6 +3706,8 @@ bool enabled = GetBool("enabled", false); is not found. \return The item with \a name, or \a defaultValue if not found. + + \since Haiku R1 */ diff --git a/docs/user/app/MessageFilter.dox b/docs/user/app/MessageFilter.dox index 744fd0b56a9..3f1497c19d5 100644 --- a/docs/user/app/MessageFilter.dox +++ b/docs/user/app/MessageFilter.dox @@ -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, niels.reedijk@gmail.com - * + * John Scipione, jscipione@gmail.com + * * 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 */ diff --git a/docs/user/app/MessageQueue.dox b/docs/user/app/MessageQueue.dox index 67868374fcd..9503f25af37 100644 --- a/docs/user/app/MessageQueue.dox +++ b/docs/user/app/MessageQueue.dox @@ -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, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com * * 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 */