[haiku-commits] haiku: hrev45221 - in docs/user/app: . docs/user
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Thu, 31 Jan 2013 01:25:19 +0100 (CET)
hrev45221 adds 4 changesets to branch 'master'
old head: c0b42ec1c191f7934d2960efda9047384461ff1f
new head: ce5b408f1f6b6a0372229ca45911abb03c7d1073
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=ce5b408+%5Ec0b42ec
----------------------------------------------------------------------------
8bbff5c: Update dd style in API docs.
Only make the font size 12px for the special note, warning, etc. blocks
not all dd blocks.
c896b0c: Color parameters grenadier (orange) in API docs.
a3c5efd: Color parameters in parameter lists grenadier (orange) as well.
ce5b408: A few doc fixes to BApplication and BHandler.
* Since <em> is used for parameters we can't use it for emphasis.
* Add \a in a few places it was missing to indicate a parameter.
* Change \a to a \c in one instance, param -> constant.
* Lots of whitespace fixes, most just deleting leading tabs.
* Don't indent code blocks, they should be flush to left since any
indentation is preserved in the output.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
3 files changed, 101 insertions(+), 93 deletions(-)
docs/user/app/Application.dox | 9 +-
docs/user/app/Handler.dox | 172 +++++++++++++++++++-------------------
docs/user/book.css | 13 ++-
############################################################################
Commit: 8bbff5c9edace51a1f5d2799cfc97e7ac615671d
URL: http://cgit.haiku-os.org/haiku/commit/?id=8bbff5c
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Wed Jan 30 23:43:09 2013 UTC
Update dd style in API docs.
Only make the font size 12px for the special note, warning, etc. blocks
not all dd blocks.
----------------------------------------------------------------------------
diff --git a/docs/user/book.css b/docs/user/book.css
index 41cff2d..d7a937a 100644
--- a/docs/user/book.css
+++ b/docs/user/book.css
@@ -309,10 +309,6 @@ div.contents li {
margin-left: 20px;
}
-div.contents dd {
- font-size: 12px;
-}
-
div.contents dt {
margin-top: 16px;
margin-bottom: 8px;
@@ -328,6 +324,10 @@ dl.note, dl.remark, dl.warning, dl.attention {
min-height: 48px;
}
+dl.note dd, dl.remark dd, dl.warning dd, dl.attention dd {
+ font-size: 12px;
+}
+
dl.note {
/* rice flower */
background:#e4ffde
url('http://haiku-os.org/sites/haiku-os.org/themes/shijin/haiku-icons/alert_info_32.png')
15px 15px no-repeat;
############################################################################
Commit: c896b0c34ca738363a0b184714a7b4f1ec627236
URL: http://cgit.haiku-os.org/haiku/commit/?id=c896b0c
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Wed Jan 30 23:54:16 2013 UTC
Color parameters grenadier (orange) in API docs.
----------------------------------------------------------------------------
diff --git a/docs/user/book.css b/docs/user/book.css
index d7a937a..c224b54 100644
--- a/docs/user/book.css
+++ b/docs/user/book.css
@@ -259,6 +259,10 @@ div.contents em, div.contents code {
font-style: normal;
}
+div.contents em {
+ color: #dc3c01; /* grenadier */
+}
+
div.contents code {
color: blue;
}
############################################################################
Commit: a3c5efd2e9f15814be3dd6e73b10fed601b7fdd4
URL: http://cgit.haiku-os.org/haiku/commit/?id=a3c5efd
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Wed Jan 30 23:58:55 2013 UTC
Color parameters in parameter lists grenadier (orange) as well.
----------------------------------------------------------------------------
diff --git a/docs/user/book.css b/docs/user/book.css
index c224b54..bef8af3 100644
--- a/docs/user/book.css
+++ b/docs/user/book.css
@@ -768,6 +768,7 @@ div.memdoc dl dd table.params td.paramname {
vertical-align: top;
font-weight: normal;
font-style: normal;
+ color: #dc3c01; /* grenadier */
width: 157px;
}
############################################################################
Revision: hrev45221
Commit: ce5b408f1f6b6a0372229ca45911abb03c7d1073
URL: http://cgit.haiku-os.org/haiku/commit/?id=ce5b408
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Thu Jan 31 00:18:30 2013 UTC
A few doc fixes to BApplication and BHandler.
* Since <em> is used for parameters we can't use it for emphasis.
* Add \a in a few places it was missing to indicate a parameter.
* Change \a to a \c in one instance, param -> constant.
* Lots of whitespace fixes, most just deleting leading tabs.
* Don't indent code blocks, they should be flush to left since any
indentation is preserved in the output.
----------------------------------------------------------------------------
diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox
index f64f239..f48beb9 100644
--- a/docs/user/app/Application.dox
+++ b/docs/user/app/Application.dox
@@ -387,10 +387,10 @@ main()
/*!
\fn BWindow* BApplication::WindowAt(int32 index) const
- \brief Returns the BWindow object at the specified index in the
+ \brief Returns the BWindow object at the specified \a index in the
application's window list.
-
- If index is out of range, this function returns \c NULL.
+
+ If \a index is out of range, this function returns \c NULL.
\warning Locking the BApplication object doesn't lock the window list.
@@ -520,7 +520,8 @@ main()
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.
+ \param rate The rate at which \c B_PULSE messages are sent to the
+ application.
*/
diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox
index 87f7e84..4f61593 100644
--- a/docs/user/app/Handler.dox
+++ b/docs/user/app/Handler.dox
@@ -26,7 +26,7 @@
/*!
\def B_OBSERVE_ORIGINAL_WHAT
\brief Constant for a message data field in observer messages.
-
+
If you have called one of the flavors of BHandler::StartWachting(), and
you receive a notification, sometimes there can be send a BMessage to go
with that notification. The message you receive is a copy of that
message,
@@ -52,17 +52,17 @@
\class BHandler
\ingroup app
\brief Handles messages that are passed on by a BLooper.
-
+
The BHandler class implements two important pieces of functionality. It
provides the foundations for <b>handling messages</b>, and it serves as
a
<b>state machine</b> that sends out notifications of the state changes.
-
+
The most common use of this class is to <b>handle messages</b>. Handlers
can be tied to loopers, which are the objects that send and receive
messages. As soon as a message is received, the looper passes through
its
list of associated handlers and tries them in a certain order until the
message is handled, or the options are exhausted.
-
+
You should know that a looper is a subclass of a handler, and as such,
loopers can be self-contained and do not need additional handlers. In
many
cases, this construction will suffice. You will simply subclass the
looper,
@@ -74,18 +74,18 @@
messages such as clicks are received, the window loops the handlers
until
there is a handler that is at the screen position the click was in. It
is
not unlikely that you will some day want to use this functionality of
the
- API.
-
+ API.
+
If your handler is limited to a certain type of messages, you can set a
filter that the looper will apply to your message before passing it on
to
your overridden MessageReceived() method. The BMessageFilter class
provides
the framework for the flexible filtering options, and using AddFilter()
you
can apply filters to this handler. Note that a filter object should
only be
applied to one handler. They cannot be shared.
-
+
For more information on the handling chain, have a look at the
documentation of the BLooper class.
-
+
Using BHandler as a <b>state machine</b> is a second area of
functionality.
Since handlers process messages, and perform actions associated with
those,
they are the center of keeping track on the current state of things
within
@@ -93,7 +93,7 @@
parts of your application, you could perform this manually by sending
messages to the interested components, or you can use the more flexible
approach with observers.
-
+
Observers watch a certain state. A handler can track one or more
different
states. Each state is represented by a four byte constant - just like
the
\c what property of a message. Using the StartWatching() methods, you
can
@@ -105,7 +105,7 @@
that you want to be send to the observers. This data is in the form of
the
very flexible BMessage, as such you are almost free to pass anything you
want.
-
+
Whenever SendNotices() is called, all interested observers will receive
a
message of the \a B_OBSERVER_NOTICE_CHANGE type. Please note that the
constant that is associated with the state itself is not transmitted. If
@@ -121,7 +121,7 @@
/*!
\fn BHandler::BHandler(const char* name = NULL)
\brief Construct a new handler with a \a name.
-
+
The newly constructed handler is not associated with a looper until you
explicitly request this to happen. To associate this handler with a
looper,
use BLooper::AddHandler().
@@ -131,11 +131,11 @@
/*!
\fn BHandler::~BHandler()
\brief Free the filters of this handler, as well as the list of
observers.
-
+
This method does not remove the handler from the looper to which this
handler is associated. You should do this yourself, using
BLooper::RemoveHandler().
-
+
\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.
@@ -145,7 +145,7 @@
/*!
\fn BArchivable *BHandler::Instantiate(BMessage *data)
\brief Static method to instantiate a handler from an archived message.
-
+
\return A pointer to the instantiated handler, or \c NULL if the \a data
is not a valid archived BHandler object.
\see BHandler(BMessage* data)
@@ -156,18 +156,19 @@
/*!
\name Archiving
+
BHandler inherits the BArchivable class, and as such implements support
for
archiving and unarchiving handlers.
*/
//! @{
-
-
+
+
/*!
\fn BHandler::BHandler(BMessage* data)
\brief Construct a handler from an archived message.
-
+
This \a data has to be created using the BHandler::Archive() method.
Note that only the name is stored. The filters, the associated looper
and
the observers are not stored, and should be manually added when you are
@@ -178,10 +179,10 @@
/*!
\fn status_t BHandler::Archive(BMessage *data, bool deep) const
\brief Archive a handler to a message
-
+
Currently, only the name is archived. The filters, the associated looper
and the observers are not stored.
-
+
\param data The message to archive the object in.
\param deep This parameter is ignored, as BHandler does not have
children.
\retval B_OK Archiving succeeded.
@@ -279,19 +280,19 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn void BHandler::SetNextHandler(BHandler *handler)
\brief Set the next handler in the chain that the message is passed on
to
- if this handler cannot process it.
-
+ if this \a handler cannot process it.
+
This method has three requirements:
- -# This handler should belong to a looper.
+ -# This \a handler should belong to a looper.
-# The looper needs to be locked. See LockLooper().
-# The \a handler that you pass must be associated with the same looper.
-
+
Failure to meet any of these requirements will result in your
application
crashing.
-
+
By default, the handlers are chained in order that they were associated
to
a looper with BLooper::AddHander().
-
+
\see NextHandler()
*/
@@ -316,19 +317,19 @@ ShowImageApp::MessageReceived(BMessage *message)
//! @{
-
-
+
+
/*!
\fn void BHandler::AddFilter(BMessageFilter *filter)
\brief Add a filter as a prerequisite to this handler.
-
+
If the handler is associated with a looper, this looper needs to be
locked
in order for this operation to succeed.
-
+
Note that the filter is not copied, rather a pointer to the filter is
stored. As such, you need to make sure that the filter object exists as
long as it is added to this handler.
-
+
\see RemoveFilter(), SetFilterList()
*/
@@ -336,16 +337,16 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn bool BHandler::RemoveFilter(BMessageFilter *filter)
\brief Remove a filter from the filter list.
-
+
If the handler is associated with a looper, this looper needs to be
locked
in order for this operation to succeed.
-
+
Note that the filter is not deleted, merely removed from the list. You
need
to take care of the memory yourself.
-
+
\retval true The filter was in the filter list and is removed.
\retval false The filter was not found in the filter list.
-
+
\see AddFilter(), FilterList()
*/
@@ -356,7 +357,7 @@ ShowImageApp::MessageReceived(BMessage *message)
If the handler is associated with a looper, this looper needs to be
locked
in order for this operation to succeed.
-
+
The internal list will be replaced with the new list of \a filters. All
the
existing filters will be \b deleted.
@@ -367,11 +368,11 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn BList *BHandler::FilterList()
\brief Return a pointer to the list of filters.
-
+
\return A pointer to the list of filters. Do not manipulate the list of
filters directly, but use the methods provided by this class,
in order
to maintain internal consistency.
-
+
\see AddFilter(), RemoveFilter(), SetFilterList().
*/
@@ -384,22 +385,22 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\name Locking
-
+
This class provides some utility functions to look the looper associated
with this handler.
*/
//! @{
-
-
+
+
/*!
\fn bool BHandler::LockLooper()
\brief Lock the looper associated with this handler.
-
+
\retval true The looper is locked.
\retval false There was an error acquiring the lock.
-
+
\see LockLooperWithTimeout(), UnlockLooper()
*/
@@ -407,16 +408,16 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::LockLooperWithTimeout(bigtime_t timeout)
\brief Lock the looper associated with this handler, with a time out
value.
-
+
\param timeout The time to wait for acquiring the lock in microseconds.
You
may also use B_INFINITE_TIMEOUT, in which this method will wait
as long
as it takes to acquire the lock.
-
+
\retval B_OK Locking succeeded.
\retval B_BAD_VALUE This handler is not associated with a looper
(anymore).
\retval B_TIMED_OUT The time specified in \a timeout has passed without
locking the looper.
-
+
\see LockLooper(), UnlockLooper()
*/
@@ -463,16 +464,16 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\name Observing
-
+
Handlers can function as state machines, which emit messages to
observers
when the state changes. Use the following methods to subscribe to these
notifications.
-
+
Note that there is a semantic difference between the two StartWatching()
methods. The overloaded method that accepts a BHandler, expects as
- argument an \a observer that watches <em>this handler</em>. The method
that
+ argument an \a observer that watches this handler. The method that
accepts a BMessenger, expects a \a target that emits the state changes
- <em>to this handler</em>.
+ to this handler.
*/
@@ -483,25 +484,26 @@ ShowImageApp::MessageReceived(BMessage *message)
\fn status_t BHandler::StartWatching(BMessenger target, uint32 what)
\brief Subscribe this handler to watch a specific state change of a
\a target.
-
- Use this method to subscribe messengers to watch state changes in
<em>this
- handler</em>. This means that also observers from other teams can be
+
+ Use this method to subscribe messengers to watch state changes in this
+ handler, this also means that observers from other teams can be
subscribed.
-
+
\code
- // Handler B watches Handler A
- BHandler A, B;
- BMessenger messengerA(&A)
-
- B.StartWatching(messengerA, kNetworkConnection);
+// Handler B watches Handler A
+BHandler A, B;
+BMessenger messengerA(&A)
+
+B.StartWatching(messengerA, kNetworkConnection);
\endcode
-
+
\param target The messenger from which the notifications would be
received.
\param what The state that needs to be watched.
\return During the call of this method, a notification will be
transmitted
using the \a target. If this works, then this method will return
\c B_OK.
+
\see StartWatchingAll(BMessenger), StopWatching(BMessenger, uint32)
*/
@@ -509,10 +511,10 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StartWatchingAll(BMessenger target)
\brief Subscribe this handler to watch a \a target for all events.
-
+
This method performs the same task as StartWatching(BMessenger, uint32),
but it will subscribe to all the state changes the \a target knows.
-
+
\see StartWatching(BMessenger, uint32), StopWatchingAll(BMessenger)
*/
@@ -520,10 +522,10 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StopWatching(BMessenger target, uint32 what)
\brief Unsubscribe this handler from watching a specific state.
-
+
This method will unsubscribe this handler from watching a specific event
in a \a target.
-
+
\see StartWatching(BMessenger, uint32)
*/
@@ -531,9 +533,9 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StopWatchingAll(BMessenger target)
\brief Unsubscribe this handler from watching all states.
-
+
This method will unsubscribe the \a target from watching all state
changes.
-
+
\see StartWatchingAll(BMessenger)
*/
@@ -541,39 +543,39 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StartWatching(BHandler* observer, uint32 what)
\brief Subscribe an \a observer for a specific state change of this
handler.
-
+
Use this method to subscribe observers to watch this handler. State
changes
- of this handler that match the \a what argment, will be sent.
+ of this handler that match the \a what argument, will be sent.
\code
- // Handler B wants to observe Handler A
- BHandler A, B;
-
- A.StartWatching(&B, kNetworkConnection);
+// Handler B wants to observe Handler A
+BHandler A, B;
+
+A.StartWatching(&B, kNetworkConnection);
\endcode
Since pointers to handlers can only
exist in the local namespace, have a look at
StartWatching(BMessenger, uint32) for inter-team watching.
-
+
\param observer The observer for this handler.
\param what The state that needs to be watched.
\return During the call of this method, a notification will be
transmitted
using the \a observer. If this works, then this method will
return
\c B_OK.
-
+
\see StartWatchingAll(BHandler*), StopWatching(BHandler*, uint32)
*/
/*!
\fn status_t BHandler::StartWatchingAll(BHandler* observer)
- \brief Subscribe an \a observer for a all state changes.
-
+ \brief Subscribe an \a observer for a all state changes.
+
This method performs the same task as StartWatching(BHandler, uint32),
but it will subscribe the \a observer to all the state changes this
handler
tracks.
-
+
\see StartWatching(BHandler*, uint32), StopWatchingAll(BHandler*)
*/
@@ -591,9 +593,9 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn status_t BHandler::StopWatchingAll(BHandler* handler)
\brief Unsubscribe an observer from watching all states.
-
+
This method will unsubscribe the \a handler from watching all state
changes.
-
+
\see StartWatchingAll(BHandler*)
*/
@@ -606,6 +608,7 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\name Emitting State Changes
+
If your handler functions as a state machine, and it has observers
(which
subscribed using the StartWatching() method), you can emit these state
changes.
@@ -613,12 +616,12 @@ ShowImageApp::MessageReceived(BMessage *message)
//! @{
-
-
+
+
/*!
\fn void BHandler::SendNotices(uint32 what, const BMessage *msg)
\brief Emit a state change to the observers.
-
+
The actual state (specified by \a what) will not be transmitted. This is
merely for internal bookkeeping. It is not entirely unimaginable that
you
still want to inform the observers of what actually took place. You can
@@ -626,13 +629,13 @@ ShowImageApp::MessageReceived(BMessage *message)
message will be copied and slightly altered: the \c what member of the
message will be \c B_OBSERVER_NOTICE_CHANGE, and the \c what constant
you
specified will be stored in the #B_OBSERVE_ORIGINAL_WHAT label.
-
+
\param what The identifier of the state.
\param msg Any data associated with the state change. You retain
ownership
of this data, so make sure you dispose it when you are done.
*/
-
-
+
+
/*!
\fn bool BHandler::IsWatched() const
\brief Check if there are any observers watching this handler.
@@ -640,4 +643,3 @@ ShowImageApp::MessageReceived(BMessage *message)
//! @}
-
Other related posts:
