diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox
index 55587df63e..4c9bca0c40 100644
--- a/docs/user/interface/Button.dox
+++ b/docs/user/interface/Button.dox
@@ -6,8 +6,8 @@
  *		John Scipione, jscipione@gmail.com
  *
  * Corresponds to:
- *		headers/os/interface/Button.h	 rev 42794
- *		src/kits/interface/Button.cpp	 rev 42794
+ *		headers/os/interface/Button.h	 hrev47274
+ *		src/kits/interface/Button.cpp	 hrev47273
 
 
 /*!
@@ -22,21 +22,28 @@
 	\class BButton Button.h
 	\ingroup interface
 	\ingroup libbe
-	\brief A BButton is a labeled on-screen button.
+	\brief A control used to initiate an action.
 
-	A BButton control is used to initiate an action. An action is activated
-	by clicking on the button with the mouse or by a keyboard button.
-	If the BButton is the default button for the active window then you can
-	activate it by pushing the <span class="keycap">Enter</span> key.
+	An action is activated by clicking on the button with the mouse
+	or by a keyboard button. If the button is the default button for
+	the active window then you can activate it by pushing the
+	<span class="keycap">Enter</span> key.
 
 	\image html BButton_example.png
 
-	A BButton, unlike other user interface elements such as check boxes and
-	radio buttons has only a single state. During a click event the
-	BButton's value is set to 1, (\c B_CONTROL_ON) otherwise this value
-	is 0 (\c B_CONTROL_OFF).
+	The behavior of a button depends on its behavior. The normal behavior
+	of a button is to set the value to 1 (\c B_CONTROL_ON) only when the
+	button is activated, otherwise the value is 0 (\c B_CONTROL_OFF).
+	Setting a button to use \c B_TOGGLE_BEHAVIOR makes the button behave
+	like a checkbox so that each time the button is activate the value
+	toggles between \c B_CONTROL_OFF and \c B_CONTROL_ON. The third
+	behavior to use is \c B_POP_UP_BEHAVIOR which adds a pop-up marker
+	to the button similar to that of BMenuField.
 
-	BButton inherits from the BControl class.
+	A button may have either a text label, an icon, or both. The button's
+	label is set in the constructor or by the SetLabel() method. To set the
+	icon for a button use the SetIcon() method. The text label will draw
+	to the right of the icon.
 */
 
 
@@ -59,40 +66,13 @@
 	passed up the inheritance chain to the BView class.
 
 	\param frame The frame rectangle that the button is draw into.
-	\param name The name of the button
-	\param label The button label text
-	\param message The BButtons's action message
+	\param name The name of the button. Can be \c NULL.
+	\param label The button label text. Can be \c NULL.
+	\param message The BButtons's action message. Can be \c NULL.
 	\param resizingMode Mask sets the parameters by which the BButton can be
-		resized. It should be set to one option for vertical resizing combined
-		with one option for horizontal resizing.
-		\n\n Horizontal resizing options are
-			\li \c B_FOLLOW_LEFT
-			\li \c B_FOLLOW_RIGHT
-			\li \c B_FOLLOW_LEFT_RIGHT
-			\li \c B_FOLLOW_H_CENTER
-
-		Vertical resizing options are
-			\li \c B_FOLLOW_TOP
-			\li \c B_FOLLOW_BOTTOM
-			\li \c B_FOLLOW_TOP_BOTTOM
-			\li \c B_FOLLOW_V_CENTER
-
-		There are two other possibilities
-			\li \c B_FOLLOW_ALL_SIDES
-			\li \c B_FOLLOW_NONE
-
-		See BView for more information on resizing options.
-	\param flags The flags mask sets what notifications the BButton can receive.
-			\n\n Any combination of the following options is allowed
-			\li \c B_WILL_DRAW
-			\li \c B_PULSE_NEEDED
-			\li \c B_FRAME_EVENTS
-			\li \c B_FULL_UPDATE_ON_RESIZE
-			\li \c B_NAVIAGBLE
-			\li \c B_NAVIAGBLE_JUMP
-			\li \c B_SUBPIXEL_PRECISE
-
-		See BView for more information on \a flags.
+	       resized. See BView for more information on resizing options.
+	\param flags The \a flags mask sets what notifications the BButton can
+	       receive. See BView for more information on \a flags.
 */
 
 
@@ -107,20 +87,11 @@
 	height of the button's frame rectange to fit the button's border and
 	label in the button's font.
 	
-	\param name The \a name of the button
-	\param label The button's \a label text
-	\param message The button's action \a message
+	\param name The \a name of the button. Can be \c NULL.
+	\param label The button's \a label text. Can be \c NULL.
+	\param message The button's action \a message. Can be \c NULL.
 	\param flags The \a flags mask sets what notifications the button can
-		receive. Any combination of the following options is allowed:
-			\li \c B_WILL_DRAW
-			\li \c B_PULSE_NEEDED
-			\li \c B_FRAME_EVENTS
-			\li \c B_FULL_UPDATE_ON_RESIZE
-			\li \c B_NAVIAGBLE
-			\li \c B_NAVIAGBLE_JUMP
-			\li \c B_SUBPIXEL_PRECISE
-
-			See BView for more information on \a flags.
+	       receive. See BView for more information on \a flags.
 */
 
 
@@ -131,30 +102,113 @@
 	Creates the button with the specified \a label. The action carried out
 	by the button is specified by the \a message.
 
-	\param label The button's \a label text
-	\param message The buttons action \a message
+	\param label The button's \a label text. Can be \c NULL.
+	\param message The buttons action \a message. Can be \c NULL.
 */
 
 
-/*!
-	\fn BButton::~BButton()
-	\brief Destructor method.
-
-	Standard Destructor.
-*/
-
-
-/*! \fn BButton::BButton(BMessage* archive)
-	\brief Constructs a BButton object from an \a archive message.
+/*! \fn BButton::BButton(BMessage* data)
+	\brief Constructs a BButton object from an \a data message.
 
 	This method is usually not called directly. If you want to build a
 	button from a message you should call Instantiate() which can
 	handle errors properly.
 
-	If the \a archive deep, the BButton object will also unarchive each
+	If the \a data deep, the BButton object will also unarchive each
 	of its child views recursively.
 
-	\param archive The \a archive message to restore from.
+	\param data The \a data message to restore from.
+*/
+
+
+/*!
+	\fn BButton::~BButton()
+	\brief Destructor, does nothing.
+*/
+
+
+/*!
+	\name Archiving
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BArchivable* BButton::Instantiate(BMessage* archive)
+	\brief Creates a new BButton object from the \a archive message.
+
+	\return A newly created check box or \c NULL if the message doesn't
+	        contain an archived BButton.
+*/
+
+
+/*!
+	\fn status_t BButton::Archive(BMessage* data, bool deep) const
+	\brief Archives the object into the \a data message.
+
+	\param data A pointer to the BMessage object to archive the object into.
+	\param deep Whether or not to archive child views as well.
+
+	\return A status code, \c B_OK if everything went well or an error code
+	        otherwise.
+
+	\sa BControl::Archive()
+*/
+
+
+//! @}
+
+
+/*!
+	\name Hook Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn void BButton::AttachedToWindow()
+	\brief Hook method called when the button is attached to a window.
+
+	The view color is set to \c B_TRANSPARENT_COLOR. If the button is
+	the default button the window's default button is updated.
+
+	\sa BControl::AttachedToWindow()
+*/
+
+
+/*!
+	\fn void BButton::DetachedFromWindow()
+	\brief Hook method called when the button is detached from a window.
+
+	The default implementation does nothing.
+
+	\sa BControl::DetachedFromWindow()
+*/
+
+
+/*!
+	\fn void BButton::AllAttached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+	       all child views have already been attached to a window.
+
+	The default implementation does nothing.
+
+	\sa BView::AllAttached()
+*/
+
+
+/*!
+	\fn void BButton::AllDetached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+	       all child views have already been detached from a window.
+
+	The default implementation does nothing.
+
+	\sa BView::AllDetached()
 */
 
 
@@ -164,8 +218,8 @@
 		sets the label.
 
 	\note This is an hook method called by the Interface Kit, you don't
-	have to call it yourself. If you need to forcefully redraw the button
-	consider calling Invalidate() instead.
+	      have to call it yourself. If you need to forcefully redraw the
+	      button consider calling Invalidate() instead.
 
 	\param updateRect The rectangular area to be drawn.
 
@@ -174,77 +228,366 @@
 
 
 /*!
-	\fn void BButton::MakeDefault(bool flag)
-	\brief Make the BButton the default button i.e. it will be activated
-		when the user pushes the \key{Enter} key.
-	
-	\param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned
-		by the Layout Kit.
+	\fn void BButton::FrameMoved(BPoint newPosition)
+	\brief Hook method called when the button is moved.
+
+	The default implementation does nothing.
+
+	\param newPosition The point that the button has been moved to.
+
+	\sa BView::FrameMoved()
 */
 
 
 /*!
-	\fn void BButton::SetLabel(const char *string)
-	\brief Sets the BButton's label.
-	
-	\param string The string to set the label to.
+	\fn void BButton::FrameResized(float width, float height)
+	\brief Hook method called when the button is resized.
+
+	The default implementation does nothing.
+
+	\param width The new \a width of the button.
+	\param height The new \a height of the button.
+
+	\sa BView::FrameResized()
+*/
+
+
+/*!
+	\fn void BButton::KeyDown(const char* bytes, int32 numBytes)
+	\brief Hook method called when a keyboard key is pressed.
+
+	Invokes the button on \a B_ENTER or \a B_SPACE.
+
+	\param bytes The bytes of the key combination pressed.
+	\param numBytes The number of bytes in \a bytes.
+*/
+
+
+/*!
+	\fn void BButton::LayoutInvalidated(bool descendants)
+	\brief Hook method called when the layout is invalidated.
+
+	Invalidate cached preferred size.
+
+	\note This method was not available in BeOS R5.
+
+	\param descendants Whether or not child views have also been invalidated.
+*/
+
+
+/*!
+	\fn void BButton::MessageReceived(BMessage* message)
+	\brief Handle \a message received by the associated looper.
+
+	The default implemenation does nothing.
+
+	\param message The \a message received by the associated looper.
+
+	\see BControl::MessageReceived()
+*/
+
+
+/*!
+	\fn void BButton::MouseDown(BPoint where)
+	\brief Hook method called when a mouse button is pressed.
+
+	Begins tracking the mouse cursor.
+
+	\param where The point on the screen where to mouse pointer is when
+	       the mouse button is pressed.
+*/
+
+
+/*!
+	\fn void BButton::MouseMoved(BPoint where, uint32 code,
+		const BMessage* dragMessage)
+	\brief Hook method called when the mouse is moved.
+
+	Once MouseDown() has been called this method updates the button's value
+	if the mouse cursor is inside the button. The value that is set depends on
+	if the button is using \c B_TOGGLE_BEHAVIOR or not.
+
+	\param where The new location of the mouse in the control's coordinate system.
+	\param code One of the following:
+	- \c B_ENTERED_VIEW The cursor has just entered the button.
+	- \c B_INSIDE_VIEW The cursor is inside the button.
+	- \c B_EXITED_VIEW The cursor has left the button's bounds. This only gets
+	     sent if the scope of the mouse events that the button can receive has
+	     been expanded by BView::SetEventMask() or BView::SetMouseEventMask().
+	- \c B_OUTSIDE_VIEW The cursor is outside the button. This only gets sent if
+	     the scope of the mouse events that the control can receive has been
+	     expanded by SetEventMask() or SetMouseEventMask().
+	\param dragMessage If a drag-and-drop operation is taking place this is a
+	     pointer to a BMessage that holds the drag information, otherwise the
+	     pointer is \c NULL.
+*/
+
+
+/*!
+	\fn void BButton::MouseUp(BPoint where)
+	\brief Hook method called when a mouse button is released.
+
+	Set the value of the button if MouseDown() was previously called on the
+	button. The value that is set depends on if the button is using
+	\c B_TOGGLE_BEHAVIOR or not.
+
+	\param where The point on the screen where the mouse pointer is located when
+	       the mouse button is released in the view's coordinate system.
+*/
+
+
+/*!
+	\fn void BButton::WindowActivated(bool active)
+	\brief Hook method called when the attached window is activated or
+	       deactivated.
+
+	The default implementation does nothing.
+
+	\param active \c true if the window becomes activated, \c false if the
+	       window becomes deactivated.
+
+	\sa BControl::WindowActivated()
+*/
+
+
+//! @}
+
+
+/*!
+	\fn void BButton::GetPreferredSize(float* _width, float* _height)
+	\brief Fill out the preferred width and height of the button
+		into the \a _width and \a _height parameters.
+
+	The size is computed from the children sizes, unless it was explicitly set
+	for the BButton, which can be done only if the BButton is configured to
+	use the Layout APIs.
+
+	\note Either the \a _width or \a _height parameter may be set to \c NULL
+	      if you only want to get the other one.
+
+	\param[out] _width Pointer to a \c float to store the width.
+	\param[out] _height Pointer to a \c float to store the height.
+*/
+
+
+/*!
+	\fn status_t BButton::GetSupportedSuites(BMessage* message)
+	\brief Report the suites of messages this control understands.
+
+	\param message Allows you to add the names of the suites the button
+	       implements to the suites array.
+
+	\return \c B_OK if all went well or an error code otherwise.
+
+	\sa BControl::GetSupportedSuites();
+*/
+
+
+/*!
+	\fn status_t BButton::Invoke(BMessage* message)
+	\brief Sends a copy of the model \a message to the designated target.
+
+	\param message The \a message to send.
+
+	\return \c B_OK if the button was invoked, otherwise an error
+	        code is returned.
+
+	\sa BControl::Invoke()
+*/
+
+
+/*!
+	\fn void BButton::MakeDefault(bool flag)
+	\brief Make the BButton the default button i.e. it will be activated
+		when the user pushes the \key{Enter} key.
+
+	A window can have only one default button at a time.
+
+	\param flag \c true to make the button the default button, \c false
+	       to remove the default button status.
+
+	\sa BWindow::SetDefaultButton()
+*/
+
+
+/*!
+	\fn void BButton::MakeFocus(bool focused)
+	\brief Makes the button the current focus view of the window or
+	       gives up being the window's focus view.
+
+	The default implementation does nothing.
+
+	\param focused \a true to set focus, \a false to remove it.
+
+	\sa BControl::MakeFocus()
+*/
+
+
+/*!
+	\fn BSize BButton::MinSize()
+	\brief Returns the button's minimum size.
+
+	\note This method was not available in BeOS R5.
+
+	\return The button's minimum size as a BSize.
+*/
+
+
+/*!
+	\fn BSize BButton::MaxSize()
+	\brief Returns the button's maximum size.
+
+	\note This method was not available in BeOS R5.
+
+	\return The button's maximum size as a BSize.
+*/
+
+
+/*!
+	\fn BSize BButton::PreferredSize()
+	\brief Returns the button's preferred size.
+
+	\note This method was not available in BeOS R5.
+
+	\return The button's preferred size as a BSize.
+*/
+
+
+/*!
+	\fn status_t BButton::Perform(perform_code code, void* _data)
+	\brief Perform some action. (Internal Method)
+*/
+
+
+/*!
+	\fn void BButton::ResizeToPreferred()
+	\brief Resize the button to its preferred size.
+
+	\sa BView::ResizeToPreferred()
+*/
+
+
+/*!
+	\fn BHandler* BButton::ResolveSpecifier(BMessage* message,
+		int32 index, BMessage* specifier, int32 what, const char* property)
+	\brief Determine the proper specifier for scripting messages.
+
+	The default implementation does nothing.
+
+	\sa BControl::ResolveSpecifier()
+*/
+
+
+/*!
+	\fn void BButton::SetLabel(const char* label)
+	\brief Sets the button's label.
+
+	\param label The string to set the label to.
 */
 
 
 /*!
 	\fn bool BButton::IsDefault() const
-	\brief Returns whether or not the BButton is the default button or not, i.e.
-	it responds to the \key{Enter} key.
-	
-	\retval true The button is the default button.
-	\retval false The button is \b not the default button.
+	\brief Returns whether or not the button is the default button on the
+	       window, i.e. whether or not it responds to the \key{Enter} key.
+
+	\returns \c true if the button is the default button, \c false otherwise.
+*/
+
+
+/*!
+	\fn bool BButton::IsFlat() const
+	\brief Returns whether or not the button is flat or not.
+
+	\note This method was not available in BeOS R5.
+
+	\returns \c true if the button is flat, \c false otherwise.
+*/
+
+
+/*!
+	\fn void BButton::SetFlat(bool flat)
+	\brief Sets or unsets the button to be flat.
+
+	\note This method was not available in BeOS R5.
+
+	\param flat \c true to make the button flat, \c false to make the button
+	       not flat.
+*/
+
+
+/*!
+	\fn BButton::BBehavior BButton::Behavior() const
+	\brief Returns the buttons behavior.
+
+	\note This method was not available in BeOS R5.
+
+	\return The button behavior flag.
+*/
+
+
+/*!
+	\fn void BButton::SetBehavior(BBehavior behavior)
+	\brief Sets the button behavior.
+
+	\note This method was not available in BeOS R5.
+
+	\param behavior One of the following:
+	- \c B_BUTTON_BEHAVIOR Normal behavior,
+	- \c B_TOGGLE_BEHAVIOR Acts like a check box,
+	- \c B_POP_UP_BEHAVIOR Adds a pop-up marker to the button
+	     (similar to that of BMenuField).
+*/
+
+
+/*!
+	\fn BMessage* BButton::PopUpMessage() const
+	\brief Returns the message sent to the button's target when the
+	       pop-up marker is selected using \c B_POP_UP_BEHAVIOR.
+
+	\note This method was not available in BeOS R5.
+
+	\return The message sent to the button's target.
+*/
+
+
+/*!
+	\fn void BButton::SetPopUpMessage(BMessage* message)
+	\brief Sets the message sent to the button's target when the
+	       pop-up marker is selected using \c B_POP_UP_BEHAVIOR.
+
+	\note This method was not available in BeOS R5.
+
+	\param message The \a message sent to the button's target.
+*/
+
+
+/*!
+	\fn status_t BControl::SetIcon(const BBitmap* icon, uint32 flags)
+	\brief This convenience method is used to set the bitmaps
+	       for the standard states from a single bitmap.
+
+	\note This method was not available in BeOS R5.
+
+	\param icon The \a icon to set.
+	\param flags Modify how the icon is set.
+
+	\return \c B_OK if the icon was set or an error code otherwise.
+
+	\sa BControl::SetIcon()
 */
 
 
 /*!
 	\fn void BButton::SetValue(int32 value)
-	\brief Sets the value of the BButton.
+	\brief Sets the value of the button.
 
 	\note This method can be overridden in order to take a different action
 	when the value changes.
 
 	\param value The value to set to the BButton to. Options include:
-		\li \c 0 (\c B_CONTROL_OFF)
-		\li \c 1 (\c B_CONTROL_ON)
+		- \c 0 (\c B_CONTROL_OFF)
+		- \c 1 (\c B_CONTROL_ON)
 
 	\see BControl::SetValue()
 */
-
-
-/*!
-	\fn void BButton::GetPreferredSize(float *_width, float *_height)
-	\brief Gets the dimensions that the BButton would prefer to be.
-
-	The size is computed from the children sizes, unless it was explicitly set
-	for the BButton (which can be done only if the BButton is configured to
-	use the Layout Kit).
-
-	\note Either the \a _width or \a _height parameter may be set to \c NULL
-		if you only want to get the other one.
-
-	\param[out] _width  The width of the preferred size is placed in here.
-	\param[out] _height The height of the preferred size is placed in here.
-*/
-
-
-/*!
-	\fn status_t BButton::Invoke(BMessage *message)
-	\brief The BButton is invoked from a message.
-
-	This method is used to post a message when the button is clicked or
-	activated by a keyboard button. You can set the object that will
-	handle the message by calling a BControl::SetTarget() from a
-	BInvoker inherited control. A model for the message is set by the
-	BButton constructor or by the BControl::SetMessage() method
-	inherited from BInvoker.
-
-	\returns B_OK If the BButton was invoked, otherwise an error
-		\a status_t flag is returned.
-
-	\see BControl::Invoke()
-*/