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

Update App Kit Documentation.

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