[haiku-commits] haiku: hrev45241 - in docs/user: support midi2 interface interface/images drivers
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Thu, 7 Feb 2013 20:00:16 +0100 (CET)
hrev45241 adds 2 changesets to branch 'master'
old head: 8cf4ba89b647baa3f243c132c0b210f8312d8cc9
new head: 6dc7e05ecf9371c87c58efa09c1656e500c0ff44
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=6dc7e05+%5E8cf4ba8
----------------------------------------------------------------------------
820dca4: Big docs cleanup.
* Fixed headers including:
- All rights reserved not All Rights Reserved.
- name, email@xxxxxxxxxx not name <email@xxxxxxxxxx>
- tabs and spaces
- Authors: not Documented by:
* Renamed string.dox to String.dox
* Renamed midixxx.dox files to MidiXxx.dox
* Moved images into images subdirectories and updated Doxfile.
* Re-format all files with tabs instead of spaces.
* Fix many spelling mistakes.
* Added all files, classes, structs, and enums to libbe group.
6dc7e05: Update BBuffer class docs.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
109 files changed, 6412 insertions(+), 4860 deletions(-)
docs/user/Doxyfile | 6 +-
docs/user/apidoc.dox | 171 +-
docs/user/app/Application.dox | 8 +-
docs/user/app/Clipboard.dox | 9 +-
docs/user/app/Cursor.dox | 9 +-
docs/user/app/Handler.dox | 11 +-
docs/user/app/Looper.dox | 9 +-
docs/user/app/Message.dox | 397 ++---
docs/user/app/MessageFilter.dox | 11 +-
docs/user/app/MessageQueue.dox | 8 +-
docs/user/app/_app_intro.dox | 12 +-
docs/user/app/_app_messaging.dox | 57 +-
docs/user/book.css | 12 +-
docs/user/drivers/USB3.dox | 1459 ++++++++++--------
docs/user/drivers/USB_spec.dox | 320 ++--
docs/user/drivers/drivers.dox | 10 +-
docs/user/drivers/fs_interface.dox | 1 +
docs/user/drivers/fs_modules.dox | 1 -
docs/user/drivers/usb_modules.dox | 773 +++++-----
docs/user/game/DirectWindow.dox | 37 +-
docs/user/game/FileGameSound.dox | 2 +
docs/user/game/GameProducer.dox | 4 +
docs/user/interface/AbstractLayout.dox | 15 +-
docs/user/interface/Alert.dox | 34 +-
docs/user/interface/Bitmap.dox | 19 +-
docs/user/interface/Box.dox | 10 +-
docs/user/interface/Button.dox | 12 +-
docs/user/interface/CheckBox.dox | 10 +-
docs/user/interface/ColorControl.dox | 30 +-
docs/user/interface/Control.dox | 14 +-
docs/user/interface/Dragger.dox | 6 +-
docs/user/interface/Font.dox | 130 +-
docs/user/interface/GridLayout.dox | 17 +-
docs/user/interface/GroupLayout.dox | 67 +-
docs/user/interface/IconUtils.dox | 13 +-
docs/user/interface/InterfaceDefs.dox | 45 +-
docs/user/interface/Layout.dox | 24 +-
docs/user/interface/LayoutBuilder.Group.dox | 10 +-
docs/user/interface/LayoutBuilder.dox | 22 +-
docs/user/interface/LayoutItem.dox | 19 +-
docs/user/interface/Screen.dox | 17 +-
docs/user/interface/TwoDimensionalLayout.dox | 15 +-
docs/user/interface/View.dox | 14 +-
docs/user/interface/_interface_intro.dox | 16 +-
docs/user/interface/_layout_intro.dox | 32 +-
.../interface/{ => images}/BAlert_example.png | Bin
.../user/interface/{ => images}/BBox_example.png | Bin
.../{ => images}/BBox_with_checkbox.png | Bin
.../interface/{ => images}/BButton_example.png | Bin
.../interface/{ => images}/BCheckBox_example.png | Bin
.../{ => images}/BColorControl_example.png | Bin
.../BColorControl_example_256_colors.png | Bin
.../interface/{ => images}/BDragger_example.png | Bin
.../interface/{ => images}/B_FANCY_BORDER.png | Bin
.../interface/{ => images}/B_PLAIN_BORDER.png | Bin
docs/user/interface/layout_tips.dox | 1 -
docs/user/locale/Catalog.dox | 10 +-
docs/user/locale/Collator.dox | 9 +-
docs/user/locale/Country.dox | 29 +-
docs/user/locale/DurationFormat.dox | 14 +-
docs/user/locale/Locale.dox | 12 +-
docs/user/locale/LocaleRoster.dox | 17 +-
docs/user/locale/TimeZone.dox | 22 +-
docs/user/locale/UnicodeChar.dox | 62 +-
docs/user/media/Buffer.dox | 65 +-
docs/user/media/FileInterface.dox | 8 +-
docs/user/midi2/Midi2Defs.dox | 220 ++-
docs/user/midi2/MidiConsumer.dox | 323 ++++
docs/user/midi2/MidiEndpoint.dox | 322 ++++
docs/user/midi2/MidiProducer.dox | 359 +++++
docs/user/midi2/MidiRoster.dox | 418 +++++
docs/user/midi2/{ => images}/midi2concepts.png | Bin
docs/user/midi2/midiconsumer.dox | 291 ----
docs/user/midi2/midiendpoint.dox | 296 ----
docs/user/midi2/midifiles.dox | 31 -
docs/user/midi2/midiproducer.dox | 308 ----
docs/user/midi2/midiroster.dox | 309 ----
docs/user/storage/AppFileInfo.dox | 18 +-
docs/user/storage/Directory.dox | 3 +
docs/user/storage/Entry.dox | 24 +-
docs/user/storage/EntryList.dox | 8 +-
docs/user/storage/File.dox | 2 +
docs/user/storage/FilePanel.dox | 14 +-
docs/user/storage/FindDirectory.dox | 8 +-
docs/user/storage/Mime.dox | 27 +-
docs/user/storage/MimeType.dox | 3 +
docs/user/storage/Node.dox | 18 +-
.../storage/{ => images}/BFilePanel_example.png | Bin
docs/user/support/Archivable.dox | 39 +-
docs/user/support/Archiver.dox | 14 +-
docs/user/support/Autolock.dox | 153 +-
docs/user/support/Beep.dox | 53 +-
docs/user/support/BlockCache.dox | 14 +-
docs/user/support/BufferIO.dox | 290 ++--
docs/user/support/DataIO.dox | 516 ++++---
docs/user/support/Flattenable.dox | 283 ++--
docs/user/support/List.dox | 128 +-
docs/user/support/Locker.dox | 279 ++--
docs/user/support/{string.dox => String.dox} | 451 ++++--
[ *** stats truncated: 10 lines dropped *** ]
############################################################################
Commit: 820dca4df6c7bf955c46e8f6521b9408f50b2900
URL: http://cgit.haiku-os.org/haiku/commit/?id=820dca4
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Thu Feb 7 02:05:00 2013 UTC
Big docs cleanup.
* Fixed headers including:
- All rights reserved not All Rights Reserved.
- name, email@xxxxxxxxxx not name <email@xxxxxxxxxx>
- tabs and spaces
- Authors: not Documented by:
* Renamed string.dox to String.dox
* Renamed midixxx.dox files to MidiXxx.dox
* Moved images into images subdirectories and updated Doxfile.
* Re-format all files with tabs instead of spaces.
* Fix many spelling mistakes.
* Added all files, classes, structs, and enums to libbe group.
----------------------------------------------------------------------------
diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile
index 43e0c1f..340997c 100644
--- a/docs/user/Doxyfile
+++ b/docs/user/Doxyfile
@@ -738,10 +738,10 @@ EXAMPLE_RECURSIVE = NO
# the \image command).
IMAGE_PATH = . \
- interface \
+ interface/images \
keyboard \
- midi2 \
- storage
+ midi2/images \
+ storage/images
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/docs/user/apidoc.dox b/docs/user/apidoc.dox
index 7cbaad9..7faff53 100644
--- a/docs/user/apidoc.dox
+++ b/docs/user/apidoc.dox
@@ -1,9 +1,12 @@
/*
* Copyright 2007 Niels Sascha Reedijk. All rights reserved.
+ * Copyright 2008-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ * John Scipione, jscipione@xxxxxxxxx
+ *
* Proofreaders:
* Alan Smale, ajsmale@xxxxxxxxx
*/
@@ -67,8 +70,8 @@
not only means that they get the same name, but also
that the order
of the methods, variables, functions, etc. will have to
be the same.
-# The root directory of the public API headers is at \c
- /trunk/headers/os. In a similar vein, the root of the
documentation
- files is at \c /trunk/docs/user. The subdirectory
+ headers/os. In a similar vein, the root of the
documentation
+ files is at \c docs/user. The subdirectory
structure, or the division of kits, will also be
replicated.
-# The name of the files is the same as the base of the header
files,
with the \c dox extension. So \c Something.h becomes \c
@@ -80,41 +83,52 @@
copyright block, with a reference to the author(s) and against which
revision the documentation was written.
- \verbatim
+\verbatim
/*
-* Copyright 2007 Niels Sascha Reedijk. All rights reserved.
-* Distributed under the terms of the MIT License.
-*
-* Authors:
-* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
-* Proofreaders:
-* Alan Smale, ajsmale@xxxxxxxxx
-* Corresponds to:
-* /trunk/headers/os/support/String.h rev 19731
-* /trunk/src/kits/support/String.cpp rev 19731
-*/
- \endverbatim
+ * Copyright 2007-2013 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ *
+ * Proofreaders:
+ * Alan Smale, ajsmale@xxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/support/String.h rev 19731
+ * src/kits/support/String.cpp rev 19731
+ */
+\endverbatim
The example above has a few elements that you should take note of:
- -# The header is put in a standard C comment, which is enclosed between
\c
- /* and \c *\/.
- -# Every line starts with a whitespace and an asterix, followed by
another
+ -# The header is put in a standard C comment, which is enclosed between
+\verbatim
+/*
+\endverbatim
+ and
+\verbatim
+*/
+\endverbatim
+ -# Every line starts with a whitespace and an asterisk followed by
another
space. If the text is part of a category, such as
<tt>Authors</tt>, put
three spaces after the delimiter.
-# The first line is empty, then we get to the copyright notice. You may
either retain the copyright yourself, or you can attribute to
to Haiku
- Inc. It's your choice. The next line is the \e MIT licence
notice,
+ Inc. It's your choice. The next line is the \e MIT License
notice,
followed by an empty line.
-# Then there is a label <tt>Authors:</tt>, which is followed by
lines with names and email addresses. The latter one is
optional, but
- recommended. Each author is preceeded by two tabs after the
asterix.
+ recommended. Each author is proceeded by two tabs after the
asterisk.
-# In the same vein there is the label <tt>Proofreaders:</tt> in case
the
file has been proofread.
-# The final part is underneath the label <tt>Corresponds to:</tt>.
Underneath there is a list of files and their svn revisions
that the
current documentation is known to correspond with.
- -# The header block ends with the \c *\/, where the asterix is aligned
with
- the ones above it.
+ -# The header block ends with the
+\verbatim
+*/
+\endverbatim
+ where the asterisk is aligned with the ones above it.
\subsection formalrequirements_blocks Blocks
@@ -126,27 +140,34 @@
we need to reproduce them in our \c dox files.
Blocks should adhere to the following standards:
- -# All blocks open with \c /*! and close with \c * /
+ -# All blocks open with
+\verbatim
+/*!
+\endverbatim
+ and close with
+\verbatim
+*/
+\endverbatim
-# The documentation is placed in between these markers.
-# All the contents in between the markers is indented by tabs. The tab
length should be four.
-# Between blocks, there should be two empty lines.
- -# The maximum width of the contents between blocks is 80 columns.
<em>Try
- not to cross this limit</em>, because it will severely limit
+ -# The maximum width of the contents between blocks is 80 columns.
<b>Try
+ not to cross this limit</b>, because it will severely limit
readability.
-
+
Example:
- \verbatim
+\verbatim
/*!
- \fn bool BList::AddItem(void *item)
- \brief Append an item to the list.
-
- \param item The item to add.
- \retval true The item was appended.
- \retval false Item was not appended, since resizing the list failed.
- \sa AddItem(void *item, int32 index)
+ \fn bool BList::AddItem(void *item)
+ \brief Append an item to the list.
+
+ \param item The item to add.
+ \retval true The item was appended.
+ \retval false Item was not appended, since resizing the list failed.
+ \sa AddItem(void *item, int32 index)
*/
- \endverbatim
+\endverbatim
\note Doxygen also allows the use of single line comments, starting
with
\c //!, however, we won't use these \b except for group
markers, which
@@ -253,7 +274,6 @@
There are also a number of things that can be used in pages and member
documentation. See the style section to find out the appropriate
situations
in which to use them.
-
- \c \\note {text}
- \c \\attention {text}
- \c \\warning {text}
@@ -312,7 +332,7 @@
same arguments as \c \\page, namely the \c \<name\> and the
<tt>(title)</tt>. If you need a deeper hierarchy you may use \c
\\subsection
and \c \\subsubsection, again, both with the same syntax. If you need to
- distinguish between sections in subsubsections, you are able to use
+ distinguish between sections in sub-sub-sections, you are able to use
\c \\paragraph, which takes the same arguments.
\note Before and after each of the commands above, you need to have an
empty
@@ -349,17 +369,20 @@
\verbatim
/*!
- \\name Appending Methods
-
- These methods append things to the object.
+ \name Appending Methods
+
+ These methods append things to the object.
*/
//! \@{
-... names of the methods ...
+
+... methods ...
+
//! \@}
+
\endverbatim
The block preceding the block opening marker, <tt>//! \@{</tt>,
contains a
@@ -401,7 +424,7 @@
Modules are defined in the main book, and you can add classes to them by
using the \c \\ingroup command. This commands adds the class to the
module
and groups it on a separate page. At this moment, the group handling
has yet
- to be finalised. For now, add the classes to the kit they belong in. In
the
+ to be finalized. For now, add the classes to the kit they belong in. In
the
future this might change.
Finally, it is a good idea to link between parts of the documentation.
There
@@ -431,10 +454,10 @@
here, which means you should use the right names. So use \b
method
instead of function, and data member instead of variable (where
appropriate).
- - Avoid informalism. Avoid constructs like 'if you want to
+ - Avoid in-formalism. Avoid constructs like 'if you want to
disconnect the object', but rather use 'to disconnect the
object'. Avoid
- familiarisms, or jokes.
-
+ familiarizes, or jokes.
+
\remarks It isn't the goal to create dry, legal-style documentation.
Just
try to find a balance. Read through documentation that's
already been
approved to get a hint of what you should be aiming for.
@@ -497,15 +520,15 @@
\verbatim
/*!
- \file String.h
- \brief Defines the BString class and global operators and functions for
- handling strings.
+ \file String.h
+ \brief Defines the BString class and global operators and functions for
+ handling strings.
*/
/*!
- \file SupportDefs.h
- \brief Defines basic types and definitions for the Haiku API.
+ \file SupportDefs.h
+ \brief Defines basic types and definitions for the Haiku API.
*/
\endverbatim
@@ -619,15 +642,15 @@
They are a short phrase that mention what the variable contains.
Example:
\verbatim
- /*!
- \var char* BString::fPrivateData
- \brief BString's storage for data.
-
- This member is deprecated and might even become \c private in future
- releases.
-
- If you are planning to derive from this object and you want to
manipulate
- the raw string data, please have a look at LockBuffer() and
UnlockBuffer().
+/*!
+ \var char* BString::fPrivateData
+ \brief BString's storage for data.
+
+ This member is deprecated and might even become \c private in future
+ releases.
+
+ If you are planning to derive from this object and you want to manipulate
+ the raw string data, please have a look at LockBuffer() and UnlockBuffer().
*/
\endverbatim
@@ -667,18 +690,18 @@
documentation belongs to the class description, not to the enumeration.
\subsection style_groups Groups
-
+
If you subdivide members of classes into groups, you have the ability to
apply some general information that will be listed above the listing of
the
members in that group. See the section \ref commands_grouping on how to
define groups. This section is on what to put in the header block.
-
+
First of all, it's probably a good idea to give your group a name. This
name
will be printed as a title and will enhance the clarity of what the
group
contains. If you put the \c \\name command as the first command of a
group,
the rest of the words on that line will be used as the title. You should
choose simple titles of no more than three words.
-
+
It's possible to add one or two paragraphs of information. These
paragraphs
should contain some quick notes on which of the members in that group
to use
for what purpose. See it as a quick subdivision that a developer could
use
@@ -688,17 +711,18 @@
\verbatim
/*!
- \name Comparison Methods
-
- There are two different comparison methods. First of all there is the
whole
- range of operators that return a boolean value, secondly there are
methods
- that return an integer value, both case sensitive and case insensitive.
-
- There are also global comparison operators and global compare functions.
- You might need these in case you have a sort routine that takes a
generic
- comparison function, such as BList::SortItems().
- See the String.h documentation file to see the specifics, as they are
- basically the same as implemented in this class.
+ \name Comparison Methods
+
+ There are two different comparison methods. First of all there is the whole
+ range of operators that return a boolean value, secondly there are methods
+ that return an integer value, both case sensitive and case insensitive.
+
+ There are also global comparison operators and global compare functions.
+ You might need these in case you have a sort routine that takes a generic
+ comparison function, such as BList::SortItems().
+
+ See the String.h documentation file to see the specifics, as they are
+ basically the same as implemented in this class.
*/
\endverbatim
@@ -706,5 +730,4 @@
the members up into two groups and refers to other functions the
developer
might be looking for. The hard limit is two (short) paragraphs. Using
more
will not improve clarity.
-
*/
diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox
index f48beb9..aa18fea 100644
--- a/docs/user/app/Application.dox
+++ b/docs/user/app/Application.dox
@@ -1,18 +1,20 @@
/*
- * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, jscipione@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Application.h rev 42794
- * /trunk/src/kits/app/Application.cpp rev 42794
+ * headers/os/app/Application.h rev 42794
+ * src/kits/app/Application.cpp rev 42794
*/
/*!
\file Application.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BApplication class.
*/
diff --git a/docs/user/app/Clipboard.dox b/docs/user/app/Clipboard.dox
index 3cc3e89..f1fbbc2 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 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,13 +7,15 @@
* John Scipione, jscipione@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Clipboard.h rev 42274
- * /trunk/src/kits/app/Clipboard.cpp rev 42274
+ * headers/os/app/Clipboard.h rev 42274
+ * src/kits/app/Clipboard.cpp rev 42274
*/
/*!
\file Clipboard.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BClipboard class.
*/
@@ -27,6 +29,7 @@
/*!
\class BClipboard
\ingroup app
+ \ingroup libbe
\brief Used for short-term data storage between documents and
applications via copy and paste operations.
diff --git a/docs/user/app/Cursor.dox b/docs/user/app/Cursor.dox
index 56d9dbe..4b266d8 100644
--- a/docs/user/app/Cursor.dox
+++ b/docs/user/app/Cursor.dox
@@ -1,18 +1,20 @@
/*
- * Copyright 2012 Haiku, Inc. All Rights Reserved.
+ * Copyright 2012 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, jscipione@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Cursor.h hrev45039
- * /trunk/src/kits/app/Cursor.cpp hrev45039
+ * headers/os/app/Cursor.h hrev45039
+ * src/kits/app/Cursor.cpp hrev45039
*/
/*!
\file Cursor.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BCursor class.
*/
@@ -200,6 +202,7 @@
/*!
\class BCursor
\ingroup app
+ \ingroup libbe
\brief BCursor describes a view-wide or application-wide cursor.
\note As BeOS only supports 16x16 monochrome cursors, to see a nice
diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox
index 33fc2a0e..2279718 100644
--- a/docs/user/app/Handler.dox
+++ b/docs/user/app/Handler.dox
@@ -1,22 +1,26 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Handler.h rev 22577
- * /trunk/src/kits/app/Handler.cpp rev 21332
+ * headers/os/app/Handler.h rev 22577
+ * src/kits/app/Handler.cpp rev 21332
*/
/*!
\file Handler.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BHandler class.
*/
+
///// Globals /////
+
/*!
\def B_OBSERVE_WHAT_CHANGE
\brief Internal.
@@ -51,6 +55,7 @@
/*!
\class BHandler
\ingroup app
+ \ingroup libbe
\brief Handles messages that are passed on by a BLooper.
The BHandler class implements two important pieces of functionality. It
diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox
index cfabdee..b3ac2e9 100644
--- a/docs/user/app/Looper.dox
+++ b/docs/user/app/Looper.dox
@@ -1,17 +1,19 @@
/*
- * Copyright 2008, Haiku, Inc. All Rights Reserved.
+ * Copyright 2008 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Looper.h rev 21863
- * /trunk/src/kits/app/Looper.cpp rev 21864
+ * headers/os/app/Looper.h rev 21863
+ * src/kits/app/Looper.cpp rev 21864
*/
/*!
\file Looper.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BLooper class.
*/
@@ -25,6 +27,7 @@
/*!
\class BLooper
\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
diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox
index 123c743..e7ea4e5 100644
--- a/docs/user/app/Message.dox
+++ b/docs/user/app/Message.dox
@@ -1,18 +1,20 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
*
* Corresponds to:
- * /trunk/headers/os/app/Message.h rev 21562
- * /trunk/src/kits/app/Message.cpp rev 22240
+ * headers/os/app/Message.h rev 21562
+ * src/kits/app/Message.cpp rev 22240
*/
/*!
\file Message.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BMessage class.
*/
@@ -90,35 +92,36 @@
/*!
\class BMessage
\ingroup app
+ \ingroup libbe
\brief A container that can be send and received using the Haiku
messaging
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
<b>important elements</b>: the #what identifier, and the data members.
The
first can be directly manipulated, the latter can be manipulated through
AddData(), FindData() and ReplaceData() and their derivatives. Neither
of
these elements are mandatory.
-
+
The second important role of BMessage is that it stores <b>meta
data</b>:
who sent the message and with what intention? The methods of BMessage
will
disclose if the message was a reply (IsReply()), where it came from
(IsSourceRemote()), whether a reply is expected (IsSourceWaiting()),
and in
case the message is a reply, what it's a reply to (Previous()).
-
+
Mostly, messages are used to pass information between the the objects in
your application, but because messages are such flexible data
containers,
they are also often used for other <b>data storage purposes</b>. Many
applications store their settings as messages. Because messages can be
flattened to data streams (such as files), they provide an easy but
powerful tool for data storage.
-
+
All methods can be classified in these areas:
- Adding, Finding, Replacing and Removing Data.
- Statistics and Miscellaneous information.
- Delivery information.
- Utilities to reply to messages.
-
+
To see how messages fit in with the greater picture, have a look at the
\ref app_messaging "Messaging Introduction".
*/
@@ -127,7 +130,7 @@
/*!
\var BMessage::what
\brief A 4-byte constant that determines the type of message.
-
+
You can directly manipulate this data member.
*/
@@ -136,7 +139,7 @@
\fn BMessage::BMessage()
\brief Construct an empty message, without any data members and with a
\a what constant set to \c 0.
-
+
\see BMessage(uint32 what)
\see BMessage(const BMessage &other)
*/
@@ -146,7 +149,7 @@
\fn BMessage::BMessage(uint32 what)
\brief Construct an empty message with the \a what member set to the
specified value.
-
+
\see BMessage::BMessage()
\see BMessage::BMessage(const BMessage &other)
*/
@@ -155,13 +158,13 @@
/*!
\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.
-
+
\remarks BeOS R5 did keep the metadata of the message. Haiku deviates
from
this behavior. Please use the Haiku implementation of message copying as
the default behavior. This will keep your applications backwards
@@ -175,7 +178,7 @@
/*!
\fn BMessage::~BMessage()
\brief Free the data members associated with the message.
-
+
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.
*/
@@ -184,7 +187,7 @@
/*!
\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.
*/
@@ -203,7 +206,7 @@
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.
-
+
\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.
@@ -221,7 +224,7 @@
\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.
-
+
\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.
@@ -235,7 +238,7 @@
int32 *countFound) const
\brief Retrieve the type and the number of data items in this message
that
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
@@ -243,11 +246,11 @@
\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.
-
+
\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.
-
+
\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.
@@ -259,7 +262,7 @@
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,
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
@@ -270,13 +273,13 @@
/*!
\fn int32 BMessage::CountNames(type_code type) const
\brief Count the number of names of a certain \a type.
-
+
This method can be used to count the number of items of a certain type.
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.
-
+
\return The number of data items in this message with the specified
\a type, or \c 0 in case no items match the type.
*/
@@ -285,7 +288,7 @@
/*!
\fn bool BMessage::IsEmpty() const
\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.
\see MakeEmpty()
@@ -295,7 +298,7 @@
/*!
\fn bool BMessage::IsSystem() const
\brief Check if the message is a system message.
-
+
\return If this message is a system message, the method will return
\c true.
*/
@@ -304,7 +307,7 @@
/*!
\fn bool BMessage::IsReply() const
\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.
*/
@@ -312,7 +315,7 @@
/*!
\fn void BMessage::PrintToStream() const
\brief Print the message to the standard output.
-
+
This method can be used to debug your application. It can be used to
check
if it creates the messages properly, by checking if all the required
fields
are present, and it can be used to debug your message handling routines,
@@ -324,10 +327,10 @@
/*!
\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.
\param newEntry The new name of the data entry.
-
+
\retval B_OK Renaming succeeded.
\retval B_BAD_VALUE Either the \a oldEntry or the
\a newEntry pointers are \c NULL.
@@ -348,15 +351,15 @@
/*!
\fn bool BMessage::WasDelivered() const
\brief Check if this message was delivered through the delivery methods.
-
+
If this message is passed via a BMessenger or BLooper::PostMessage(),
this
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.
-
+
\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.
@@ -366,7 +369,7 @@
/*!
\fn bool BMessage::IsSourceWaiting() const
\brief Check if the sender expects a reply.
-
+
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.
*/
@@ -381,18 +384,18 @@
/*!
\fn BMessenger BMessage::ReturnAddress() const
\brief Get a messenger that points to the sender of the message.
-
+
Using this method, you can fetch a BMessenger that can be used to
deliver
replies to this message. This method works both for local and remote
deliveries.
-
+
For remote deliveries, this approach is preferred over sending the reply
using a standard BMessenger that is created with the signature of the
application. A standard BMessenger sends the messages to the main
BLooper
of the application, the BApplication object. With the delivery data
stored
in the messages, the reply using this messenger will be directed at a
specific looper that is able to handle the replies.
-
+
If this method is called on a message that has not been delivered (yet),
it will return an empty BMessenger object.
*/
@@ -401,7 +404,7 @@
/*!
\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
@@ -412,7 +415,7 @@
/*!
\fn bool BMessage::WasDropped() const
\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
@@ -424,18 +427,18 @@
/*!
\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
verified with the WasDropped() method, this method will return a BPoint
to
where exactly the drop off was made.
-
+
Because drop messages are delivered to the BWindow in which they were
dropped, and BWindow is a subclass of BLooper, you can use BWindow to
determine based on the location, how you should react to it.
-
+
If this message was not delivered through drag and drop, it will return
a \c NULL pointer.
-
+
\see WasDropped()
*/
@@ -454,7 +457,7 @@
/*!
\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.
*/
@@ -464,7 +467,7 @@
\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).
Use this variant if you want to send the message to a specific handler
(instead of a complete messenger).
@@ -475,13 +478,13 @@
\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,
you specify a messenger that handles a reply back to the message you
specify as the \a reply argument. You can set a timeout for the
message to be delivered. This method blocks until the message has been
received, or the \a timeout has been reached.
-
+
\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.
@@ -489,7 +492,7 @@
\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.
-
+
\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).
@@ -506,7 +509,7 @@
\fn status_t BMessage::SendReply(uint32 command, BMessage *replyToReply)
\brief Synchronously send a reply to this message, and wait for a reply
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.
@@ -518,7 +521,7 @@
bigtime_t sendTimeout, bigtime_t replyTimeout)
\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
the receiver. If a reply is received, that reply is copied into the
@@ -526,7 +529,7 @@
If the message was delivered properly, but the receiver did not reply
within the specified \a replyTimeout, the \a what member of
\a replyToReply will be set to \c B_NO_REPLY.
-
+
\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.
@@ -535,7 +538,7 @@
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.
-
+
\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
@@ -556,7 +559,7 @@
/*!
\name Flattening methods
-
+
Because of historical reasons and for binary compatibility, this class
provides a flattening API without inheriting the BFlattenable class. The
API is more or less the same, but you are inconvenienced when you want
to
@@ -565,7 +568,7 @@
//! @{
-
+
/*!
\fn ssize_t BMessage::FlattenedSize() const
@@ -577,13 +580,13 @@
/*!
\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.
-
+
\warning Make sure the buffer is large enough to hold the message. This
method does not double-check for you!
\see FlattenedSize()
@@ -594,13 +597,13 @@
/*!
\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.
-
+
\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.
@@ -613,11 +616,11 @@
\fn status_t BMessage::Unflatten(const char *flatBuffer)
\brief Unflatten a message from a buffer and put it into the current
object.
-
+
This action clears the current contents of the message.
-
+
\param flatBuffer The buffer that contains the message.
-
+
\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
@@ -631,11 +634,11 @@
\fn status_t BMessage::Unflatten(BDataIO *stream)
\brief Unflatten a message from a stream and put it into the current
object.
-
+
This action clears the current contents of the message.
-
+
\param stream The stream that contains the message.
-
+
\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
@@ -650,9 +653,9 @@
/*!
\name Specifiers (Scripting)
*/
-
+
//! @{
-
+
/*!
\fn status_t BMessage::AddSpecifier(const char *property)
@@ -719,19 +722,19 @@
//! @{
-
+
/*!
\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
stored at the label specified in \a name. You are responsible for
specifying the correct \a type. The Haiku API already specifies
many constants, such as \c B_FLOAT_TYPE or \c B_RECT_TYPE. See
TypeConstants.h for more information on the system-wide defined types.
-
+
If the field with the \a name already exists, the data is added in
an array-like form. If you are adding a certain \a name for the
first time, you are able to specify some properties of this array. You
can
@@ -743,12 +746,12 @@
If consecutive method calls specify a different \a type than the
initial, these calls will fail.
-
+
There is no limit to the number of labels, or the amount of data, but
note that searching of data members is linear, as well as that some
messages will be copied whilst being passed around, so if the amount of
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.
@@ -767,7 +770,7 @@
\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.
-
+
\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,
@@ -782,9 +785,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param aRect The rectangle to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -796,9 +799,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param aPoint The point to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -810,9 +813,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param aString The string to copy to the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -824,9 +827,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param aString The string to copy to the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -838,23 +841,23 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param value The value to store in the message.
\see AddData() for a more detailed overview of the inner workings.
\see FindInt8()
\see ReplaceInt8()
*/
-
+
/*!
\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.
-
+
\param name The label to associate the data with.
\param value The value to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -866,9 +869,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param value The value to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -880,9 +883,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param value The value to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -894,9 +897,9 @@
/*!
\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.
-
+
\param name The label to associate the data with.
\param aBoolean The value to store in the message.
\see AddData() for a more detailed overview of the inner workings.
@@ -937,7 +940,7 @@
\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, please
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
@@ -1031,10 +1034,10 @@
\fn status_t BMessage::RemoveData(const char *name, int32 index)
\brief Remove data associated with \a name at a specified
\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.
-
+
\param name The \a name of which the associated data should be cleared.
\param index The \a index of the item that should be cleared.
\retval B_OK The data has been removed.
@@ -1050,10 +1053,10 @@
/*!
\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,
if you want to.
-
+
\param name The \a name that refers to the data you want to clear
out.
\retval B_OK All the data is removed.
@@ -1067,10 +1070,10 @@
/*!
\fn status_t BMessage::MakeEmpty()
\brief Clear all data and metadata in this message.
-
+
Everything is cleared out, all labels and all associated data, as well
as metadata such as reply info.
-
+
\return This method always returns \c B_OK.
\see RemoveData()
\see RemoveName()
@@ -1082,13 +1085,13 @@
/*!
\name Finding Data
-
+
Look at FindData() for a general introduction to finding data.
*/
/* TODO:
Quick overview:
-
+
<table>
<tr><th>Type of data</th><th>Type code</th><th>Method</td></tr>
<tr><td>BRect</td><td>\c
B_RECT_TYPE</td><td>FindRect()</td></tr>
@@ -1104,19 +1107,19 @@
int32 index, const void **data, ssize_t *numBytes) const
\brief Find \a data that is stored in this message at an
\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
\a index number. If all these things match, you will get a pointer
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 **),
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
message is deleted.
-
+
\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.
@@ -1138,7 +1141,7 @@
\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 method of
FindData(const char *, type_code, int32, const void **, ssize_t *) const
where data is sought at \a index \c 0.
@@ -1148,7 +1151,7 @@
/*!
\fn status_t BMessage::FindRect(const char *name, BRect *rect) const
\brief Find a rectangle at the label \a name.
-
+
This is an overloaded method of
FindRect(const char *, int32, BRect *) const
where the data is sought at \a index \c 0.
@@ -1158,10 +1161,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param rect The object in which the data should be copied.
@@ -1175,7 +1178,7 @@
/*!
\fn status_t BMessage::FindPoint(const char *name, BPoint *point) const
\brief Find a point at the label \a name.
-
+
This is an overloaded method of
FindPoint(const char *, int32, BPoint *) const
where the data is sought at \a index \c 0.
@@ -1185,10 +1188,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param point The object in which the data should be copied.
@@ -1202,7 +1205,7 @@
/*!
\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 method of
FindString(const char *, int32, const char **) const
where the data is sought at \a index \c 0.
@@ -1213,11 +1216,11 @@
\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
pointer to the internal buffer of the message. Note that this pointer is
valid, until the message is deleted.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param string The object in which the data should be copied.
@@ -1232,7 +1235,7 @@
/*!
\fn status_t BMessage::FindString(const char *name, BString *string)
const
\brief Find a string at the label \a name.
-
+
This is an overloaded method of
FindString(const char *, int32, BString *) const
where the data is sought at \a index \c 0.
@@ -1242,10 +1245,10 @@
/*!
\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
into the \a string object.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param string The object in which the data should be copied.
@@ -1260,7 +1263,7 @@
/*!
\fn status_t BMessage::FindInt8(const char *name, int8 *value) const
\brief Find an integer at the label \a name.
-
+
This is an overloaded method of FindInt8(const char *, int32, int8 *)
const
where the data is sought at \a index \c 0.
*/
@@ -1269,10 +1272,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1286,7 +1289,7 @@
/*!
\fn status_t BMessage::FindInt16(const char *name, int16 *value) const
\brief Find an integer at the label \a name.
-
+
This is an overloaded method of FindInt8(const char *, int32, int16 *)
const
where the data is sought at \a index \c 0.
*/
@@ -1295,10 +1298,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1312,7 +1315,7 @@
/*!
\fn status_t BMessage::FindInt32(const char *name, int32 *value) const
\brief Find an integer at the label \a name.
-
+
This is an overloaded method of
FindInt32(const char *, int32, int32 *) const
where the data is sought at \a index \c 0.
@@ -1322,10 +1325,10 @@
/*!
\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.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1339,7 +1342,7 @@
/*!
\fn status_t BMessage::FindInt64(const char *name, int64 *value) const
\brief Find an integer at the label \a name.
-
+
This is an overloaded method of
FindInt64(const char *, int32, int64 *) const
where the data is sought at \a index \c 0.
@@ -1349,10 +1352,10 @@
/*!
\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.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1366,7 +1369,7 @@
/*!
\fn status_t BMessage::FindBool(const char *name, bool *value) const
\brief Find a boolean at the label \a name.
-
+
This is an overloaded method of
FindBool(const char *, int32, bool *) const
where the data is sought at \a index \c 0.
@@ -1376,10 +1379,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1393,7 +1396,7 @@
/*!
\fn status_t BMessage::FindFloat(const char *name, float *value) const
\brief Find a float at the label \a name.
-
+
This is an overloaded method of
FindFloat(const char *, int32, float *) const
where the data is sought at \a index \c 0.
@@ -1403,10 +1406,10 @@
/*!
\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.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1420,7 +1423,7 @@
/*!
\fn status_t BMessage::FindDouble(const char *name, double *value) const
\brief Find a double at the label \a name.
-
+
This is an overloaded method of
FindDouble(const char *, int32, double *) const
where the data is sought at \a index \c 0.
@@ -1430,10 +1433,10 @@
/*!
\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
a provided buffer.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param value The object in which the data should be copied.
@@ -1447,7 +1450,7 @@
/*!
\fn status_t BMessage::FindPointer(const char *name, void **pointer)
const
\brief Find a pointer at the label \a name.
-
+
This is an overloaded method of
FindPointer(const char *, int32, void *) const
where the data is sought at \a index \c 0.
@@ -1457,16 +1460,16 @@
/*!
\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.
-
+
\warning If you want to share objects between applications, please
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.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param pointer The object in which the data should be copied.
@@ -1480,7 +1483,7 @@
/*!
\fn status_t BMessage::FindMessenger(const char *name, BMessenger
*messenger) const
\brief Find a messenger at the label \a name.
-
+
This is an overloaded method of
FindMessenger(const char *, int32, BMessenger *) const
where the data is sought at \a index \c 0.
@@ -1490,10 +1493,10 @@
/*!
\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
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.
\param messenger The object in which the data should be copied.
@@ -1507,7 +1510,7 @@
/*!
\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 method of
FindRef(const char *, int32, entry_ref *) const
where the data is sought at \a index \c 0.
@@ -1518,10 +1521,10 @@
\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.
-
+
This method looks for the data with the \c B_REF_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.
\param ref The object in which the data should be copied.
@@ -1535,7 +1538,7 @@
/*!
\fn status_t BMessage::FindMessage(const char *name, BMessage *message)
const
\brief Find a message at the label \a name.
-
+
This is an overloaded method of
FindMessage(const char *, int32, BMessage *) const
where the data is sought at \a index \c 0.
@@ -1545,10 +1548,10 @@
/*!
\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.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be copied.
\param message The object in which the data should be copied.
@@ -1562,7 +1565,7 @@
/*!
\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 method of
FindFlat(const char *, int32, BFlattenable *) const
where the data is sought at \a index \c 0.
@@ -1574,11 +1577,11 @@
BFlattenable *object) const
\brief Find a flattened object at the label \a name at an
\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
object will be called.
-
+
\param name The label to which the data is associated.
\param index The index from which the data should be unflattened.
\param object The object in which the data should be unflattened.
@@ -1594,7 +1597,7 @@
/*!
\name Replacing Data
-
+
Look at ReplaceData() for a general introduction to replacing data.
*/
@@ -1606,7 +1609,7 @@
\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).
@@ -1618,22 +1621,22 @@
int32 index, const void *data, ssize_t numBytes)
\brief Replace the data at label \a name at a specified
\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.
-
+
There is also a collection of convenience methods, that allow you to
efficiently replace rectanges (ReplaceRect()), booleans (ReplaceBool()),
and so on.
-
+
\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 numBytes The size of the new data.
-
+
\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,
@@ -1645,7 +1648,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1656,7 +1659,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_RECT_TYPE.
\param name The name associated with the data to replace.
@@ -1671,7 +1674,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1682,7 +1685,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_POINT_TYPE.
\param name The name associated with the data to replace.
@@ -1697,7 +1700,7 @@
/*!
\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 *).
It replaces the data at \a index \c 0.
@@ -1708,7 +1711,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_STRING_TYPE.
\param name The name associated with the data to replace.
@@ -1723,7 +1726,7 @@
/*!
\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 &).
It replaces the data at \a index \c 0.
@@ -1734,7 +1737,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_STRING_TYPE.
\param name The name associated with the data to replace.
@@ -1749,7 +1752,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1760,7 +1763,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_INT8_TYPE.
\param name The name associated with the data to replace.
@@ -1775,7 +1778,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1786,7 +1789,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_INT16_TYPE.
\param name The name associated with the data to replace.
@@ -1801,7 +1804,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1812,7 +1815,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_INT32_TYPE.
\param name The name associated with the data to replace.
@@ -1827,7 +1830,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1838,7 +1841,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_INT64_TYPE.
\param name The name associated with the data to replace.
@@ -1853,7 +1856,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1864,7 +1867,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_BOOL_TYPE.
@@ -1880,7 +1883,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1891,7 +1894,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_FLOAT_TYPE.
@@ -1907,7 +1910,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1918,7 +1921,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_DOUBLE_TYPE.
@@ -1934,7 +1937,7 @@
/*!
\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 *).
It replaces the data at \a index \c 0.
@@ -1944,7 +1947,7 @@
/*!
\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 matches the \c B_POINTER_TYPE.
@@ -1960,7 +1963,7 @@
/*!
\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).
It replaces the data at \a index \c 0.
@@ -1971,7 +1974,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_MESSENGER_TYPE.
@@ -1987,7 +1990,7 @@
/*!
\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 *).
It replaces the data at \a index \c 0.
@@ -1998,7 +2001,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_REF_TYPE.
@@ -2014,7 +2017,7 @@
/*!
\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 *).
It replaces the data at \a index \c 0.
@@ -2025,7 +2028,7 @@
\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.
-
+
The data at the specified \a name and \a index will be
replaced, if it matches the \c B_MESSAGE_TYPE.
@@ -2041,7 +2044,7 @@
/*!
\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 *).
@@ -2053,11 +2056,11 @@
\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.
-
+
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
BFlattenable::TypeCode() to determine the type of the object.
-
+
\param name The name associated with the data to replace.
\param index The index in the array to replace.
\param object The object to store in the message.
@@ -2074,7 +2077,7 @@
/*!
\name Deprecated methods
-
+
These methods are \e very likely to disappear, and they have been
replaced
by safer and more powerful methods. These methods are still implemented
for binary compatibility, but they are not documented.
@@ -2199,13 +2202,13 @@
/*!
- \fn bool BMessage::HasData(const char *, type_code , int32) const
+ \fn bool BMessage::HasData(const char *, type_code , int32) const
\brief Deprecated.
*/
/*!
- \fn BRect BMessage::FindRect(const char *, int32) const
+ \fn BRect BMessage::FindRect(const char *, int32) const
\brief Deprecated.
*/
@@ -2229,7 +2232,7 @@
/*!
- \fn int16 BMessage::FindInt16(const char *, int32) const
+ \fn int16 BMessage::FindInt16(const char *, int32) const
\brief Deprecated.
*/
diff --git a/docs/user/app/MessageFilter.dox b/docs/user/app/MessageFilter.dox
index 29b9bbe..4d517f8 100644
--- a/docs/user/app/MessageFilter.dox
+++ b/docs/user/app/MessageFilter.dox
@@ -1,14 +1,20 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/app/MessageFilter.h
+ * src/kits/app/MessageFilter.cpp
*/
/*!
\file MessageFilter.h
+ \ingroup app
+ \ingroup libroot
\brief Provides BMessageFilter class.
*/
@@ -18,7 +24,7 @@
\brief Return Codes and Protocol of the #filter_hook.
These return codes should be used in your own filter_hook function, or
by
- your overrided BMessageFilter::Filter() function.
+ your overridden BMessageFilter::Filter() method.
*/
@@ -137,6 +143,7 @@
/*!
\class BMessageFilter
\ingroup app
+ \ingroup libbe
\brief Describes a message filter for BLooper and BHandler.
Objects of this class serve as a description of properties that incoming
diff --git a/docs/user/app/MessageQueue.dox b/docs/user/app/MessageQueue.dox
index 12c4914..c02de9e 100644
--- a/docs/user/app/MessageQueue.dox
+++ b/docs/user/app/MessageQueue.dox
@@ -1,10 +1,10 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007, Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
- * Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
- *
+ * Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
+ *
* Corresponds to:
* /trunk/headers/os/app/MessageQueue.h rev 19956
* /trunk/src/kits/app/MessageQueue.cpp rev 19956
@@ -12,6 +12,8 @@
/*!
\file MessageQueue.h
+ \ingroup app
+ \ingroup libroot
\brief Provides the BMessageQueue class.
*/
diff --git a/docs/user/app/_app_intro.dox b/docs/user/app/_app_intro.dox
index ab458fa..ac9aaee 100644
--- a/docs/user/app/_app_intro.dox
+++ b/docs/user/app/_app_intro.dox
@@ -1,21 +1,21 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
- * Documentation by:
- * Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
+ * Authors:
+ * Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
*/
/*!
\page app_intro Introduction to the Application Kit.
-
+
The Application Kit should be your starting point if you want to write
native Haiku applications with a GUI. The application kit does
exactly as its name suggests; it is the basis for Haiku applications.
You
should read through this document and the documents referenced here
before
moving on to any other part of the API.
-
+
The Application Kit classes can be divided into two groups: the
"messaging"
classes and the "system interaction" classes. The larger group contains
the messaging classes. Have a look at the \link app_messaging
@@ -29,7 +29,7 @@
- BMessageQueue
- BMessageRunner
- BMessenger
-
+
The second group is the system interaction classes. These classes
provide hooks for your application to interact with the rest of the
system.
The most important class is BApplication. This is a list of all the
diff --git a/docs/user/app/_app_messaging.dox b/docs/user/app/_app_messaging.dox
index 5236706..d715862 100644
--- a/docs/user/app/_app_messaging.dox
+++ b/docs/user/app/_app_messaging.dox
@@ -1,15 +1,14 @@
/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, niels.reedijk@xxxxxxxxx
*/
-
/*!
\page app_messaging Messaging Foundations
-
+
One of the foundations of the Haiku API is the messaging system. This
framework is the basis for the efficient multithreaded Haiku
applications,
because it solves one of the fundamental issues of multithreading: it
@@ -17,21 +16,21 @@
framework allows inter-application messaging as well as
intra-application messaging, and it will always use the most effective
mechanism for the communication automatically.
-
+
This page will introduce you to the subject of messaging. It is meant
as a
broad overview to the classes, rather than a tutorial. If you are
looking
for effective messaging techniques or a tutorial on messaging, have a
look
at the developer section of the Haiku website.
-
+
<b>Table of contents</b>
- Overview of the Messaging Classes
- Receiving and Handling Messages
- Sending messages
-
+
\section app_messaging_overview Overview of the Messaging Classes
-
+
\subsection app_messaging_overview_bmessage BMessage
-
+
The BMessage class is the class that is in the center of all the
messenger
operations, because it represents a message. A message is nothing more
than
an object that contains:
@@ -49,15 +48,15 @@
context. The Haiku API defines several messages and their required data
members. Several applications provide a scripting interface with defined
message syntax. You can do the same for your application.
-
+
\subsection app_messaging_overview_blooper BLooper
-
+
Objects of the BLooper type are objects that run message loops. Every
object runs in its own thread. The BLooper objects continually check for
incoming messages. To process the messages, the looper looks for message
handlers that handle the messages within the thread's context. Message
handling within a looper is synchronous.
-
+
BLooper inherits BHandler, the base class for message handling.
However, it
is possible to chain additional handlers to the object. For example, if
you
have an application that understands different networking protocols, and
@@ -65,23 +64,23 @@
can provide handlers that you can chain in your general message parser
thread. See AddHandler() and SetPreferredHandler() for information on
handlers.
-
+
Messages can be posted to the looper by using the object's PostMessage()
method. This method puts the message in the BMessageQueue of the looper.
Since PostMessage() is asynchronous, the message might not be handled
immediately. See \ref app_messaging_overview_bmessenger "BMessenger"
for a synchronous implementation.
-
+
Loopers can have a generic filter that discards messages based on
user-definable characteristics. The BMessageFilter class provides the
foundation for the qualifying of messages. See AddCommonFilterList() and
SetCommonFilterList() for more information.
-
+
To get the most out of the functionality of BLooper, it is usually
subclassed to create a self-contained event 'machine'. Most of the time,
these subclasses also perform the message handling, which is possible
due to the fact that it is also a subclass of BHandler.
-
+
In the Haiku API, there are two major classes that inherit BLooper:
the base application class, BApplication, and the window class, BWindow.
Because they inherit BLooper, each application and each window has its
@@ -90,47 +89,47 @@
event handling that requires more processing power, is done within its
own
BLooper context. Networking usually qualifies as a candidate for its own
thread.
-
+
\subsection app_messaging_overview_bhandler BHandler
-
+
Objects of the BHandler type are associated to BLoopers. When they are
created, they should be passed to the BLooper::AddHandler() method of
the
looper they want to handle messages for. They can then either be set as
preferred handlers (by chaining them with
BLooper::SetPreferredHandler()),
or they can be added to other BHandlers with the SetNextHandler()
method.
-
+
The magic of the class happens in the MessageReceived() method. In your
subclasses you override this method, to check the incoming BMessage.
Usually, you check the \c what member of the message in a switch
statement.
If your handler cannot handle the object, it will pass the message on to
the parent class.
-
+
\warning Don't forget to actuall call the MessageReceived() method of
the
base class. Failing to do this will mean that the message chain
will
not completely be followed, which can lead to unhandled
messages. There
might be some internal system messages that the Haiku API
classes
handle, and not actually handling these messages could lead to
inconsistent internal behavior.
-
+
\subsection app_messaging_overview_bmessenger BMessenger
-
+
BMessenger objects can send messages to both local and remote targets.
For
local targets, a BMessenger provides an advantage over directly calling
the BLooper::PostMessage() method: some variants of the
BMessenger::SendMessage() methods allow for synchronous replies. So, the
call will actually verify the handling thread processes the message, and
reply to the sender.
-
+
The other feature of BMessenger is that it is able to be constructed
with
the signature of another application as argument. This allows the
messenger
to pass messages to other applications. It facilitates inter-application
communication.
-
+
\subsection app_messaging-overview-other Other messaging classes
-
+
There are several convenience classes supplied with the application kit,
which can make your life easier in some specific cases.
-
+
- BInvoker binds together a message and a target. By calling
BInvoker::Invoke(), the message will be sent. This class is inherited
by
the controls in the interface kit, such as BButton.
@@ -146,12 +145,10 @@
Filter() \endlink method.
\section app-messaging-receiving Receiving Messages
-
+
To do...
-
+
\section app-messaging-sending Sending Messages
-
+
To do...
-
*/
-
\ No newline at end of file
diff --git a/docs/user/book.css b/docs/user/book.css
index bef8af3..a310bde 100644
--- a/docs/user/book.css
+++ b/docs/user/book.css
@@ -1,13 +1,13 @@
/*
- * Copyright 2008, Haiku. All rights reserved.
+ * Copyright 2008-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
- * François Revol <revol@xxxxxxx>
- * Stephan Aßmus <superstippi@xxxxxx>
- * Braden Ewing <brewin@xxxxxxxxx>
- * Humdinger <humdingerb@xxxxxxxxx>
- * John Scipione <jscipione@xxxxxxxxx>
+ * François Revol, revol@xxxxxxx
+ * Stephan Aßmus, superstippi@xxxxxx
+ * Braden Ewing, brewin@xxxxxxxxx
+ * Humdinger, humdingerb@xxxxxxxxx
+ * John Scipione, jscipione@xxxxxxxxx
*/
/* color names provided by: http://chir.ag/projects/name-that-color */
diff --git a/docs/user/drivers/USB3.dox b/docs/user/drivers/USB3.dox
index b617a7d..9df6323 100644
--- a/docs/user/drivers/USB3.dox
+++ b/docs/user/drivers/USB3.dox
@@ -1,674 +1,785 @@
-/*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
- * Distributed under the terms of the MIT License.
- *
- * Documentation by:
- * Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
- * Corresponds to:
- * /trunk/headers/os/drivers/USB3.h rev 19915
- */
-
-/*!
- \file USB3.h
- \ingroup drivers
- \brief Interface for the USB module.
-*/
-
-/*!
- \typedef struct usb_module_info usb_module_info
- \brief The main interface object. See the usb_module_info documentation.
-*/
-
-/*!
- \typedef uint32 usb_id
- \brief Uniquely identify various USB objects that are used in the
module.
-*/
-
-/*!
- \typedef usb_id usb_device
- \brief Uniquely identify USB devices.
-*/
-
-/*!
- \typedef usb_id usb_interface
- \brief Uniquely identify USB interfaces.
-*/
-
-/*!
- \typedef usb_id usb_pipe
- \brief Uniquely identify USB pipes.
-*/
-
-/*!
- \typedef struct usb_endpoint_info usb_endpoint_info
- \brief Container for USB endpoint descriptors.
- \see Documentation for usb_endpoint_info.
-*/
-
-/*!
- \typedef struct usb_interface_info usb_interface_info
- \brief Container for USB interface descriptors.
- \see Documentation for usb_interface_info.
-*/
-
-/*!
- \typedef struct usb_interface_list usb_interface_list
- \brief Container that holds a list of USB interface descriptors.
- \see Documentation for usb_interface_list.
-*/
-
-/*!
- \typedef struct usb_configuration_info usb_configuration_info
- \brief Container for USB configuration descriptors.
- \see Documentation for usb_configuration_info.
-*/
-
-///// usb_notify_hooks /////
-
-/*!
- \struct usb_notify_hooks
- \brief Hooks that the USB stack can callback in case of events.
-*/
-
-/*!
- \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void
**cookie)
- \brief Called by the stack in case a device is added.
-
- Once you have registered hooks using the
- usb_module_info::install_notify() method, this hook will be called as
soon as
- a device is inserted that matches your provided usb_support_descriptor.
-
- \param device A unique id that identifies this USB device.
- \param[in] cookie You can store a pointer to an object in this variable.
- When the device is removed, this cookie will be provided to you.
- \return You should return \c B_OK in case of success. The USB stack
will then
- request the kernel to republish your device names so that the new
device
- will be shown in the \c /dev tree. If you return an error value, the
- \a device id will become invalid and you will not be notified if this
- device is removed.
- \see device_removed()
-*/
-
-/*!
- \var status_t (*usb_notify_hooks::device_removed)(void *cookie)
- \brief Called by the stack in case a device you are using is removed.
-
- If you have accepted a device in the device_added() hook, this hook will
- be called as soon as the device is removed.
-
- \param cookie The cookie you provided in the device_added() hook. Make
sure
- that you free the cookie if necessary.
- \return Currently the return value of this hook is ignored. It is
recommended
- to return \c B_OK though.
-*/
-
-///// usb_support_descriptor /////
-
-/*!
- \struct usb_support_descriptor
- \brief Description of device descriptor that the driver can handle.
-
- Support descriptors can be used to match any form of class, subclass or
- protocol, or they can be used to match a vendor and/or product.
- If any field has the value \c 0, it is treated as a wildcard.
-
- For example, if you want to watch for all the hubs, which have a device
- class of \c 0x09, you would pass this descriptor:
-
- \code
- usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 };
- \endcode
-
- See usb_module_info::register_driver() for more information on how to
use
- this object.
-*/
-
-/*!
- \var usb_support_descriptor::dev_class
- \brief The supported device classes.
-*/
-
-/*!
- \var usb_support_descriptor::dev_subclass
- \brief The supported device subclasses.
-*/
-
-/*!
- \var usb_support_descriptor::dev_protocol
- \brief The supported device protocols.
-*/
-
-/*!
- \var usb_support_descriptor::vendor
- \brief The supported device vendor.
-*/
-
-/*!
- \var usb_support_descriptor::product
- \brief The supported device products.
-*/
-
-///// usb_endpoint_info /////
-
-/*!
- \struct usb_endpoint_info
- \brief Container for endpoint descriptors and their Haiku USB stack
- identifiers.
-*/
-
-/*!
- \var usb_endpoint_descriptor *usb_endpoint_info::descr
- \brief Pointer to the descriptor of the endpoint.
-*/
-
-/*!
- \var usb_pipe usb_endpoint_info::handle
- \brief Handle to use when using the stack to transfer data to and from
this
- endpoint.
-*/
-
-///// usb_interface_info /////
-
-/*!
- \struct usb_interface_info
- \brief Container for interface descriptors and their Haiku USB stack
- identifiers.
-*/
-
[ *** diff truncated: 16509 lines dropped *** ]
############################################################################
Revision: hrev45241
Commit: 6dc7e05ecf9371c87c58efa09c1656e500c0ff44
URL: http://cgit.haiku-os.org/haiku/commit/?id=6dc7e05
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Thu Feb 7 07:11:09 2013 UTC
Update BBuffer class docs.
----------------------------------------------------------------------------
Other related posts:
- » [haiku-commits] haiku: hrev45241 - in docs/user: support midi2 interface interface/images drivers - jscipione
