[haiku-commits] r42608 - in haiku/trunk/docs/user: . app drivers interface locale ...
- From: pulkomandy@xxxxxxxxxxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 9 Aug 2011 23:46:15 +0200 (CEST)
Author: pulkomandy
Date: 2011-08-09 23:46:13 +0200 (Tue, 09 Aug 2011)
New Revision: 42608
Changeset: https://dev.haiku-os.org/changeset/42608
Added:
haiku/trunk/docs/user/app/Application.dox
haiku/trunk/docs/user/interface/Alert.dox
haiku/trunk/docs/user/interface/BAlert_example.png
haiku/trunk/docs/user/interface/BBox_example.png
haiku/trunk/docs/user/interface/BBox_with_checkbox.png
haiku/trunk/docs/user/interface/BButton_example.png
haiku/trunk/docs/user/interface/B_FANCY_BORDER.png
haiku/trunk/docs/user/interface/B_PLAIN_BORDER.png
haiku/trunk/docs/user/interface/Bitmap.dox
haiku/trunk/docs/user/interface/Button.dox
haiku/trunk/docs/user/interface/InterfaceDefs.dox
haiku/trunk/docs/user/locale/TimeZone.dox
haiku/trunk/docs/user/media/
haiku/trunk/docs/user/media/Buffer.dox
haiku/trunk/docs/user/storage/
haiku/trunk/docs/user/storage/AppFileInfo.dox
Removed:
haiku/trunk/docs/user/locale/TimeZone.cpp
Modified:
haiku/trunk/docs/user/Doxyfile
haiku/trunk/docs/user/app/Handler.dox
haiku/trunk/docs/user/app/Looper.dox
haiku/trunk/docs/user/app/Message.dox
haiku/trunk/docs/user/book.css
haiku/trunk/docs/user/book.dox
haiku/trunk/docs/user/drivers/USB3.dox
haiku/trunk/docs/user/drivers/fs_interface.dox
haiku/trunk/docs/user/interface/Box.dox
haiku/trunk/docs/user/interface/GridLayout.dox
haiku/trunk/docs/user/interface/GroupLayout.dox
haiku/trunk/docs/user/interface/Layout.dox
haiku/trunk/docs/user/interface/LayoutBuilder.Group.dox
haiku/trunk/docs/user/interface/LayoutBuilder.dox
haiku/trunk/docs/user/interface/LayoutItem.dox
haiku/trunk/docs/user/interface/TwoDimensionalLayout.dox
haiku/trunk/docs/user/locale/Catalog.dox
haiku/trunk/docs/user/locale/Collator.dox
haiku/trunk/docs/user/locale/Country.dox
haiku/trunk/docs/user/locale/Locale.dox
haiku/trunk/docs/user/locale/LocaleRoster.dox
haiku/trunk/docs/user/locale/UnicodeChar.dox
haiku/trunk/docs/user/support/Archivable.dox
haiku/trunk/docs/user/support/Beep.dox
haiku/trunk/docs/user/support/List.dox
haiku/trunk/docs/user/support/SupportDefs.dox
haiku/trunk/docs/user/support/Unarchiver.dox
haiku/trunk/docs/user/support/string.dox
Log:
Merge work by John Scipione on the Haiku Book.
* Some new classes documented
* Screenshots for the interface kit controls
* A lot of typo fixes
* Some css tweaks
This has some backporting to the current version of Doxygen, since
there are experiments to get coloring similar to the one in the Be
Book that will hopefully be upstreamed in Doxygen.
Modified: haiku/trunk/docs/user/Doxyfile
===================================================================
--- haiku/trunk/docs/user/Doxyfile 2011-08-09 19:39:10 UTC (rev 42607)
+++ haiku/trunk/docs/user/Doxyfile 2011-08-09 21:46:13 UTC (rev 42608)
@@ -177,7 +177,8 @@
# will result in a user-defined paragraph with heading "Side Effects:".
# You can put \n's in the value part of an alias to insert newlines.
-ALIASES =
+# For keyboard shortcuts and anything related to pressing keys
+ALIASES = "key{1}=<span class=\"keycap\">\1</span>"
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
# sources only. Doxygen will then generate output that is more tailored for C.
@@ -475,16 +476,21 @@
../../headers/os/drivers/USB3.h \
../../headers/os/drivers/USB_spec.h \
../../headers/os/interface/AbstractLayout.h \
+
../../headers/os/interface/Alert.h \
+
../../headers/os/interface/Button.h \
+
../../headers/os/interface/Bitmap.h \
../../headers/os/interface/Box.h \
../../headers/os/interface/GridLayout.h \
../../headers/os/interface/GroupLayout.h \
../../headers/os/interface/IconUtils.h \
+
../../headers/os/interface/InterfaceDefs.h \
../../headers/os/interface/Layout.h \
../../headers/os/interface/LayoutBuilder.h \
../../headers/os/interface/LayoutItem.h \
../../headers/os/interface/TwoDimensionalLayout.h \
../../headers/os/locale \
../../headers/os/midi2 \
+
../../headers/os/storage/AppFileInfo.h \
../../headers/os/support \
../../headers/posix/syslog.h
@@ -565,6 +571,7 @@
# the \image command).
IMAGE_PATH = . \
+ interface\
midi2
# The INPUT_FILTER tag can be used to specify a program that doxygen should
Added: haiku/trunk/docs/user/app/Application.dox
===================================================================
--- haiku/trunk/docs/user/app/Application.dox (rev 0)
+++ haiku/trunk/docs/user/app/Application.dox 2011-08-09 21:46:13 UTC (rev
42608)
@@ -0,0 +1,550 @@
+/*
+ * 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 42274
+ * /trunk/src/kits/app/Application.cpp rev 42274
+ */
+
+
+/*!
+ \file Application.h
+ \brief Provides the BApplication class.
+*/
+
+
+/*!
+ \class BApplication
+ \ingroup app
+ \brief A container object for an application.
+
+ A BApplication establishes a connection between the application and the
+ Application Server.
+
+ The most common task performed by a BApplication object is to handle
+ messages sent to it. The BApplication object also is used
+ to get information about your application such as the number of windows
+ it has, its signature, executable location, and launch flags.
+
+ The BApplication object is automatically assigned to the global \c
be_app
+ variable. The \c be_app variable allows you to refer to your
BApplication
+ object from anywhere in the code.
+
+ To use a BApplication you first construct the object and then begin its
+ message loop by calling the Run() method. The Run() method
+ continues until the application is told to quit. Once Run() returns you
+ should then delete the BApplication object to free its memory usage.
+
+ Typically, you initialize the BApplication object in the programs main()
+ function. A typical main() function looks something like this:
+
+ \code
+#include Application.h
+
+main()
+{
+ /* Vendor is your vendor name, application is your application name */
+ BApplication app("application/x-vnd.vendor-application");
+ app->Run();
+ delete app;
+
+ return 0;
+}
+ \endcode
+*/
+
+
+/*!
+ \fn BApplication::BApplication(const char *signature)
+ \brief Initialize a BApplication with the passed in \a signature.
+
+ The new BApplication is, by default, not running yet. If you have
+ everything set up properly call Run() to start the application.
+
+ You should call InitCheck() to check for constructor initialization
+ errors.
+
+ \param signature The \a signature of the application.
+*/
+
+
+/*!
+ \fn BApplication::BApplication(const char *signature, status_t *_error)
+ \brief Initialize a BApplication with the passed in \a signature and a
+ pointer to an error message.
+
+ 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
+ error then you should not call Run().
+
+ Alternately, you can call InitCheck() to check for constructor
+ initialization errors.
+
+ \param signature The \a signature of the application.
+ \param _error A pointer to a \c status_t set by the BApplication
+ constructor.
+*/
+
+/*!
+ \fn status_t BApplication::InitCheck() const
+ \brief Returns the status of the constructor.
+
+ \returns If initialization succeeded returns \c B_OK, otherwise returns
an
+ error status.
+*/
+
+
+/*!
+ \name Archiving
+*/
+
+
+//! @{
+
+
+/*!
+ \fn BApplication::BApplication(BMessage *data)
+ \brief Initialize a BApplication object from a message.
+
+ The message must contain the signature of the application you wish to
+ initialize in the "mime_sig" variable.
+
+ \param data The message to initialize the BApplication from.
+*/
+
+
+/*!
+ \fn status_t BApplication::Archive(BMessage *data, bool deep) const
+ \brief Archive the BApplication object into a BMessage.
+
+ \sa BArchivable::Archive()
+*/
+
+
+/*!
+ \fn BArchivable* BApplication::Instantiate(BMessage* data)
+ \brief Restores the BApplication object from a BMessage.
+
+ \sa BArchivable::Instantiate()
+*/
+
+
+//! @}
+
+
+/*!
+ \fn BApplication::~BApplication()
+ \brief Destructor Method
+*/
+
+
+/*!
+ \name Message Loop Control
+*/
+
+
+//! @{
+
+
+/*!
+ \fn thread_id BApplication::Run()
+ \brief Starts the message loop in the thread that it is called from,
+ and doesn't return until the message loop stops. Run() does not
spawn
+ a new thread.
+
+ \returns the thread_id of the thread that the BApplication is called
from.
+*/
+
+
+/*!
+ \fn void BApplication::Quit()
+ \brief Tells the thread to finish processing the message queue,
disallowing
+ any new messages.
+
+ Quit() doesn't kill the looper thread. After Quit() returns, it doesn't
wait
+ for the message queue to empty. Run() will be then able to return.
+
+ Quit() doesn't delete the BApplication object after Run() is called. You
+ should delete the BApplication object yourself one Run() returns.
+ However Quit() does delete the object if it's called before the message
loop
+ starts i.e. before Run() is called.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Hook Methods
+*/
+
+
+//! @{
+
+
+/*!
+ \fn bool BApplication::QuitRequested()
+ \brief Hook method that gets invoked when the BApplication receives a
+ \c B_QUIT_REQUESTED message.
+
+ BApplication sends a QuitRequested() message to each of its BWindow
objects.
+ If all of the BWindow s return \c true then the windows are
+ each destroyed (through BWindow::Quit()) and QuitRequested() returns
+ \c true. If any of the BWindow returns \c false, the BWindow s
+ are not destroyed and QuitRequested() returns \c false.
+
+ \retval true The application quit.
+ \retval false The application failed to quit.
+*/
+
+
+/*!
+ \fn void BApplication::ReadyToRun()
+ \brief Hook method that's invoked when the BApplication receives a
+ \c B_READY_TO_RUN message.
+
+ The ReadyToRun() method is automatically called by the Run() method. It
is
+ sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED
messages
+ (if any) have already been handled. ReadyToRun() is the only message
that
+ every running application is guaranteed to receive.
+
+ The default version of ReadyToRun() is empty. You should override the
+ ReadyToRun() method to do whatever you want to do. If you haven't
+ constructed any windows in your application yet then this would be a
good
+ place to do so.
+*/
+
+
+/*!
+ \fn void BApplication::ArgvReceived(int32 argc, char **argv)
+ \brief Hook method that gets invoked when the application receives a
+ \c B_ARGV_RECEIVED message.
+
+ If command line arguments are specified when the application is launched
+ from the the shell, or if \c argv/argc values are passed to
+ BRoster::Launch(), then this method is executed.
+
+ \warning ArgvReceived() is not called if no command line arguments are
+ specified, or if BRoster::Launch() was called without any \c argv/argc
+ values.
+
+ The arguments passed to ArgvReceived() are the constructed in the same
way
+ as those passed to command line programs. The number of command line
+ arguments is passed in \a argc and the arguments themselves are passed
as an
+ array of strings in \a argv. The first \a argv string is the name of the
+ program and the rest of the strings are the command line arguments.
+
+ BRoster::Launch() adds the program name to the front of the \a argv
array
+ and increments the \a argc value.
+
+ The \c B_ARGV_RECEIVED message (if sent) is sent only once, just
+ before the \c B_READY_TO_RUN message is sent. However, if you try to
+ relaunch an application that is already running and the application is
set
+ to \c B_EXCLUSIVE_LAUNCH or \c B_SINGLE_LAUNCH then the application will
+ generate a \c B_ARGV_RECEIVED message and send it to the already running
+ instance. Thus in this case the \c B_ARGV_RECEIVED message can show
+ up at any time.
+*/
+
+
+/*!
+ \fn void BApplication::AppActivated(bool active)
+ \brief Hook method that gets invoked when the application receives
+ \c B_APP_ACTIVATED message.
+
+ The message is sent whenever the application changes its active
application
+ status. The active flag set to is \c true when the application becomes
+ active and is set to \c false when the application becomes inactive.
+
+ The application becomes activated in response to a user action such as
+ clicking on or unhiding one of its windows. The application can have its
+ active status set programmatically by calling either the
BWindow::Activate()
+ or BRoster::ActivateApp() methods.
+
+ This method is called after ReadyToRun() provided the application is
+ displaying a window that can be set active.
+*/
+
+
+/*!
+ \fn void BApplication::RefsReceived(BMessage *message)
+ \brief Hook method that gets invoked when the application receives a
+ \c B_REFS_RECEIVED message.
+
+ The message is sent in response to a user action such as a user
+ drag-and-dropping a file on your app's icon or opening a file that the
+ application is set to handle. You can use the IsLaunching() method to
+ discern whether the message arrived when the application is launched or
+ after the application has already been running.
+
+ The default implementation is empty. You can override this method to do
+ something with the received refs. Typically you create BEntry or BFile
+ objects from the passed in refs.
+
+ \param message contains a single field named "be:refs" that contains
one or
+ more entry_ref (\c B_REF_TYPE) items, one for each file sent.
+*/
+
+
+/*!
+ \fn void BApplication::AboutRequested()
+ \brief Hook method that gets invoked when the BApplication receives a
+ \c B_ABOUT_REQUESTED message.
+
+ You should override this method to pop an alert to provide information
+ about the application.
+
+ The default implementation pops a basic alert dialog.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Cursor
+*/
+
+
+//! @{
+
+
+/*!
+ \fn BApplication::ShowCursor()
+ \brief Restores the cursor.
+*/
+
+
+/*!
+ \fn void BApplication::HideCursor()
+ \brief Hides the cursor from the screen.
+*/
+
+
+/*!
+ \fn void BApplication::ObscureCursor()
+ \brief Hides the cursor until the mouse is moved.
+*/
+
+
+/*!
+ \fn bool BApplication::IsCursorHidden() const
+ \brief Returns whether or not the cursor is hidden.
+
+ \returns \c true if the cursor is hidden, \c false if not.
+*/
+
+
+/*!
+ \fn void BApplication::SetCursor(const void *cursor)
+ \brief Sets the \a cursor to be used when the application is active.
+
+ You can pass one of the pre-defined cursor constants such as
+ \c B_HAND_CURSOR or \c B_I_BEAM_CURSOR or you can create your own pass
+ in your own cursor image. The cursor data format is described in the
BCursor
+ class.
+
+ \param cursor The cursor data to set the cursor to.
+*/
+
+
+/*!
+ \fn void BApplication::SetCursor(const BCursor *cursor, bool sync)
+ \brief Sets the \a cursor to be used when the application is active
+ with \a sync immediately option.
+
+ The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand
+ cursor and \c B_CURSOR_I_BEAM for the I-beam cursor.
+
+ \param cursor A BCursor object to set the \a cursor to.
+ \param sync synchronize the cursor immediately.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Info
+*/
+
+
+//! @{
+
+
+/*!
+ \fn int32 BApplication::CountWindows() const
+ \brief Returns the number of windows created by the application.
+
+ \returns the number of windows created by the application.
+*/
+
+
+/*!
+ \fn BWindow* BApplication::WindowAt(int32 index) const
+ \brief Returns the BWindow object at the specified index in the
+ application's window list.
+
+ If index is out of range, this function returns \c NULL.
+
+ \warning Locking the BApplication object doesn't lock the window list.
+
+ \param index The \a index of the desired BWindow.
+
+ \returns The BWindow object at the specified \a index or \c NULL
+ if the \a index is out of range.
+*/
+
+
+/*!
+ \fn int32 BApplication::CountLoopers() const
+ \brief Returns the number of BLoopers created by the application.
+
+ \warning This method may return \c B_ERROR.
+
+ \returns The number of BLoopers in the application.
+*/
+
+
+/*!
+ \fn BLooper* BApplication::LooperAt(int32 index) const
+ \brief Returns the BLooper object at the specified index in the
+ application's looper list.
+
+ If index is out of range, this function returns \c NULL.
+
+ \returns The BLooper object at the specified \a index or \c NULL
+ if the \a index is out of range.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Status
+*/
+
+
+//! @{
+
+
+/*!
+ \fn bool BApplication::IsLaunching() const
+ \brief Returns whether or not the application is in the process of
+ launching.
+
+ \returns \c true if the application is launching, \c false if the
+ application is already running.
+*/
+
+
+/*!
+ \fn status_t BApplication::GetAppInfo(app_info *info) const
+ \brief Fills out the \a info parameter with information about the
+ application.
+
+ This is equivalent to
+ be_roster->GetRunningAppInfo(be_app->Team(), info);
+
+ \returns \c B_NO_INIT on an error or \c B_OK if all goes well.
+
+ \sa BRoster::GetAppInfo()
+*/
+
+
+/*!
+ \fn BResources* BApplication::AppResources()
+ \brief Returns a BResources object for the application.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Message Mechanics
+*/
+
+
+//! @{
+
+
+/*!
+ \fn void BApplication::MessageReceived(BMessage *message)
+ \sa BHandler::MessageReceived()
+*/
+
+
+/*!
+ \fn void BApplication::DispatchMessage(BMessage *message,
+ BHandler *handler)
+ \sa BLooper::DispatchMessage()
+*/
+
+
+//! @}
+
+
+/*!
+ \name Pulse
+*/
+
+
+//! @{
+
+
+/*!
+ \fn void BApplication::Pulse()
+ \brief Hook method that gets invoked when the BApplication receives a
+ \c B_PULSE message.
+
+ An action is performed each time app_server calls the Pulse() method.
+ The pulse rate is set by SetPulseRate(). You can implement Pulse() to do
+ anything you want. The default version does nothing. The pulse
granularity
+ is no better than once per 100,000 microseconds.
+
+ \sa SetPulseRate()
+*/
+
+
+/*!
+ \fn void BApplication::SetPulseRate(bigtime_t rate)
+ \brief Sets the interval that the \c B_PULSE messages are sent.
+
+ If the \a rate is set to 0 then the \c B_PULSE messages are not sent.
+ The pulse rate can be no faster than once per 100,000 microseconds or
so.
+
+ \param rate The rate \a B_PULSE messages are sent to the application.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Scripting
+*/
+
+
+//! @{
+
+
+/*!
+ \fn BHandler* BApplication::ResolveSpecifier(BMessage *message, int32
index,
+ BMessage *specifier, int32 what, const char *property)
+ \sa BHandler::ResolveSpecifier()
+*/
+
+
+/*!
+ \fn status_t BApplication::GetSupportedSuites(BMessage *data)
+ \sa BHandler::GetSupportedSuites()
+*/
+
+
+//! @}
Modified: haiku/trunk/docs/user/app/Handler.dox
===================================================================
--- haiku/trunk/docs/user/app/Handler.dox 2011-08-09 19:39:10 UTC (rev
42607)
+++ haiku/trunk/docs/user/app/Handler.dox 2011-08-09 21:46:13 UTC (rev
42608)
@@ -444,13 +444,14 @@
/*!
\fn BHandler * BHandler::ResolveSpecifier(BMessage *msg, int32 index,
BMessage *specifier, int32 form, const char *property)
- \brief Undocumented.
+ \brief Determine the proper handler for a scripting message.
*/
/*!
\fn status_t BHandler::GetSupportedSuites(BMessage *data)
- \brief Undocumented.
+ \brief Reports the suites of messages and specifiers that derived
classes
+ understand.
*/
Modified: haiku/trunk/docs/user/app/Looper.dox
===================================================================
--- haiku/trunk/docs/user/app/Looper.dox 2011-08-09 19:39:10 UTC (rev
42607)
+++ haiku/trunk/docs/user/app/Looper.dox 2011-08-09 21:46:13 UTC (rev
42608)
@@ -147,7 +147,7 @@
\warning This constructor does no type check whatsoever. Since you can
pass
any BMessage, you should - if you are not sure about the exact
type -
use the Instantiate() method, which does check the type.
-
+
\see Instantiate()
\see Archive()
*/
@@ -710,13 +710,20 @@
/*!
\fn BHandler* BLooper::ResolveSpecifier(BMessage* msg, int32 index,
BMessage* specifier, int32 form, const char* property)
- \brief Undocumented.
+ \brief Determine the proper handler for a scripting message.
+
+ \see BHandler::ResolveSpecifier()
*/
/*!
\fn status_t BLooper::GetSupportedSuites(BMessage* data)
- \brief Undocumented.
+ \brief Reports the suites of messages and specifiers that derived
classes
+ understand.
+
+ \param data The message to report the suite of messages and specifiers.
+
+ \see BHandler::GetSupportedSuites()
*/
@@ -799,7 +806,7 @@
/*!
\fn BMessage* BLooper::MessageFromPort(bigtime_t timeout)
- \brief Hook function to retrieve a message from the looper's port.
+ \brief Hook method to retrieve a message from the looper's port.
The default implementation is called by the internal message looping
thread
and retrieves the next message from the port that belongs to this
looper.
@@ -813,5 +820,3 @@
arriving at the default port.
*/
-
-
\ No newline at end of file
Modified: haiku/trunk/docs/user/app/Message.dox
===================================================================
--- haiku/trunk/docs/user/app/Message.dox 2011-08-09 19:39:10 UTC (rev
42607)
+++ haiku/trunk/docs/user/app/Message.dox 2011-08-09 21:46:13 UTC (rev
42608)
@@ -95,9 +95,9 @@
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 identifer, and the data members.
The
+ <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 deratives. Neither of
+ 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>:
@@ -115,7 +115,7 @@
All methods can be classified in these areas:
- Adding, Finding, Replacing and Removing Data.
- - Statistics and Miscelanous information.
+ - Statistics and Miscellaneous information.
- Delivery information.
- Utilities to reply to messages.
@@ -135,7 +135,7 @@
/*!
\fn BMessage::BMessage()
\brief Construct an empty message, without any data members and with a
- \c what constant set to zero (0).
+ \a what constant set to \c 0.
\see BMessage(uint32 what)
\see BMessage(const BMessage &other)
@@ -144,7 +144,7 @@
/*!
\fn BMessage::BMessage(uint32 what)
- \brief Construct an empty message with the \c what member set tot the
+ \brief Construct an empty message with the \a what member set to the
specified value.
\see BMessage::BMessage()
@@ -156,14 +156,14 @@
\fn BMessage::BMessage(const BMessage &other)
\brief Construct a new message that is a copy of another message.
- The \c what member and the data values are copied. The metadata, such as
+ 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 behaviour. Please use the Haiku implementation of message copying
as
+ this behavior. Please use the Haiku implementation of message copying as
the default behavior. This will keep your applications backwards
compatible.
@@ -185,13 +185,13 @@
\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.
+ See the copy constructor, BMessage(const BMessage &other), for details
on
+ what is copied, and what isn't.
*/
/*!
- \name Statistics and Miscelanous Information
+ \name Statistics and Miscellaneous Information
*/
@@ -212,21 +212,21 @@
in a pointer to the internal name buffer in the message. This
means
that you should not manipulate this name. If you are not
interested in
the name, you can safely pass \c NULL.
- \param[out] typeFound The type of the item at \a index. If you are not
- interested in the type (because you specifically asked for a
type), you
- can safely pass NULL.
- \param[out] countFound The number of items at \a index. If data items
have
- the same name, they will be placed under the same index.
+ \param[out] typeFound The type of the item at \a index. If you are
+ not interested in the type (because you specifically asked for
a type),
+ you can safely pass \c NULL.
+ \param[out] countFound The number of items at \a index. If data
+ items have the same name, they will be placed under the same
index.
- \return If the \a index is found, and matches the requested type, the
- other parameters will be filled in. If this is not the case,
the method
- will return with an error.
+ \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.
- \retval B_BAD_TYPE The data field at \a index does not have the
requested
- type.
+ \retval B_BAD_INDEX The \a index was out of range. None of the
+ passed variables have been altered.
+ \retval B_BAD_TYPE The data field at \a index does not have the
+ requested type.
*/
@@ -244,9 +244,9 @@
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.
+ \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.
@@ -260,9 +260,10 @@
\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 in the variable you passed as \a fixedSize parameter.
+ This method is the same as GetInfo(const char *,type_code *, int32 *)
const,
+ with the difference that you can find out whether or not the size of the
+ data associated with the \a name is fixed. You will get this value
+ in the variable you passed as \a fixedSize parameter.
*/
@@ -277,7 +278,7 @@
method will return the total number of data items.
\return The number of data items in this message with the specified
- \a type, or zero in case no items match the type.
+ \a type, or \c 0 in case no items match the type.
*/
@@ -328,8 +329,8 @@
\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.
+ \retval B_BAD_VALUE Either the \a oldEntry or the
+ \a newEntry pointers are \c NULL.
\retval B_NAME_NOT_FOUND There is no data associated with the label
\a oldEntry.
*/
@@ -477,9 +478,9 @@
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.
+ 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
@@ -492,8 +493,9 @@
\retval B_OK The message has been delivered.
\retval B_DUPLICATE_REPLY There already has been a reply to this
message.
\retval B_BAD_PORT_ID The reply address is not valid (anymore).
- \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT
- (zero) and the target port was full when trying to deliver the
message.
+ \retval B_WOULD_BLOCK The delivery \a timeout was
+ \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when
trying
+ to deliver the message.
\retval B_TIMED_OUT The timeout expired while trying to deliver the
message.
\see SendReply(uint32 command, BHandler *replyTo)
@@ -517,12 +519,13 @@
\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 \a replyToReply
argument.
+ 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
+ \a replyToReply argument.
If the message was delivered properly, but the receiver did not reply
- within the specified \a replyTimeout, the \c what member of \a
replyToReply
- will be set to \c B_NO_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.
@@ -535,10 +538,12 @@
\retval B_OK The message has been delivered.
\retval B_DUPLICATE_REPLY There already has been a reply to this
message.
- \retval B_BAD_VALUE Either \a reply or \a replyToReply is \c NULL.
+ \retval B_BAD_VALUE Either \a reply or \a replyToReply is
+ \c NULL.
\retval B_BAD_PORT_ID The reply address is not valid (anymore).
- \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT
- (zero) and the target port was full when trying to deliver the
message.
+ \retval B_WOULD_BLOCK The delivery \a timeout was
+ \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when
trying
+ to deliver the message.
\retval B_TIMED_OUT The timeout expired while trying to deliver the
message.
\retval B_NO_MORE_PORTS All reply ports are in use.
@@ -721,20 +726,23 @@
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
- B_FLOAT_TYPE or B_RECT_TYPE. See TypeConstants.h for more information on
- the system-wide defined types.
+ 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 fix the
size
- of each data entry, and you can also instruct BMessage to allocate a
- \a count of items. The latter does not mean that the number of items is
- fixed; the array will grow nonetheless. Also, note that every \a name
can
- only be associated with one \a type of data. If consecutive method calls
- specify a different \a type than the initial, these calls will fail.
+ 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
+ fix the size of each data entry, and you can also instruct BMessage to
+ allocate a \a count of items. The latter does not mean that the
+ number of items is fixed; the array will grow nonetheless. Also, note
that
+ every \a name can only be associated with one \a type of
+ data.
+
+ 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
@@ -742,31 +750,32 @@
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.
- \param type The type of data. If you are adding data to the same \a
name,
- make sure it is the same type.
+ \a name already exists, the new data will be added in an
+ array-like style.
+ \param type The type of data. If you are adding data to the same
+ \a name, make sure it is the same type.
\param data The data buffer to copy the bytes from.
\param numBytes The number of bytes to be copied. If this is the first
call
- to this method for this type of data, and you set \a
isFixedSize to
- \c true, this will specify the size of all consecutive calls to
this
+ to this method for this type of data, and you set
+ \a isFixedSize to \c true, this will specify the size of all
+ consecutive calls to this
method.
\param isFixedSize If this is the first call to this method with this
- \a name, you can specify the whether or not all items in this
array
- should have the same fixed size.
+ \a name, you can specify the whether or not all items in this
+ array should have the same fixed size.
\param count If this is the first call to this method with this
- \a name, you can instruct this message to allocate a number of
items in
- advance. This does not limit the amount of items though. The
array will
- grow if needed.
+ \a name, you can instruct this message to allocate a number of
+ items in advance. This does not limit the amount of items
though. The
+ array will grow if needed.
\retval B_OK The \a data is succesfully added.
- \retval B_BAD_VALUE The \a numBytes is less than, or equal to zero (0),
or
- the size of this item is larger than the \a name allows, since
it has
- been specified to have a fixed size.
+ \retval B_BAD_VALUE The \a numBytes is less than, or equal to \c 0,
+ or the size of this item is larger than the \a name allows,
+ since it has been specified to have a fixed size.
\retval B_ERROR There was an error whilst creating the label with your
\a name.
- \retval B_BAD_TYPE The \a type you specified is different than the one
- already associated with \a name.
+ \retval B_BAD_TYPE The \a type you specified is different than the
+ one already associated with \a name.
*/
@@ -959,7 +968,8 @@
/*!
\fn status_t BMessage::AddRef(const char *name, const entry_ref *ref)
- \brief Convenience method to add an \c entry_ref to the label \a name.
+ \brief Convenience method to add an \c entry_ref to the label
+ \a name.
This method calls AddData() with the \c B_REF_TYPE \a type.
@@ -992,9 +1002,9 @@
This method uses BFlattenable::TypeCode() to determine the type. It also
uses BFlattenable::IsFixedSize() to determine whether or not the size of
- the object is supposedly always the same. You can specify a \a count, to
- pre-allocate more entries if you are going to add more than one of this
- type.
+ the object is supposedly always the same. You can specify a
+ \a count, to pre-allocate more entries if you are going to add
+ more than one of this type.
[... truncated: 12583 lines follow ...]
Other related posts:
- » [haiku-commits] r42608 - in haiku/trunk/docs/user: . app drivers interface locale ... - pulkomandy
