BCheckBox doc updates.

Many missing methods added.

docs/user/interface/CheckBox.dox

@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 Haiku Inc. All rights reserved.
+ * Copyright 2011-2014 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
  * Authors:
@@ -8,8 +8,8 @@
  *		John Scipione, [email protected]
  *
  * Corresponds to:
- *		headers/os/interface/CheckBox.h	 rev 42794
+ *		headers/os/interface/CheckBox.h	 hrev47274
- *		src/kits/interface/CheckBox.cpp	 rev 42794
+ *		src/kits/interface/CheckBox.cpp	 hrev47274
  */
 
 
@@ -25,104 +25,187 @@
 	\class BCheckBox
 	\ingroup interface
 	\ingroup libbe
-	\brief BCheckBox is a user interface element used to make a binary
+	\brief A user interface element used to make a binary decision.
-		decision.
 
-	A BCheckBox object is used to draw a checkbox element. This simple control
+	A BCheckBox is used to draw a check box UI control. This simple control
-	has 2 states, \c B_CONTROL_OFF when the checkbox is unchecked and
+	has 2 states, \c B_CONTROL_OFF when the check box is unchecked and
-	\c B_CONTROL_ON when the checkbox is checked. A checkbox can also have a
+	\c B_CONTROL_ON when the check box is checked. A check box can also have a
-	descriptive label drawn to the right of the checkbox.
+	descriptive label drawn to the right of the check box.
 
-	When the checkbox is checked it has an X drawn inside of it. The checkbox
+	When the check box is checked it has an X drawn inside of it. The check box
 	can be checked by a mouse click or by pushing \key{Space} on the
-	keyboard when the checkbox has focus. A checkbox object with focus
+	keyboard when the check box has focus. A check box object with focus
-	is surrounded by a blue border. A checkbox can also be set
+	is surrounded by a blue border. A check box can also be set
 	programmatically by calling the SetValue() method.
 
-	A few checkbox examples can be seen below in unchecked state, checked
+	A few check box examples can be seen below in unchecked state, checked
-	state, and another unchecked checkbox with focus on it.
+	state, and another unchecked check box with focus on it.
 
 	\image html BCheckBox_example.png
 */
 
 
 /*!
-	\fn BCheckBox::BCheckBox(BRect frame, const char *name, const char *label,
+	\fn BCheckBox::BCheckBox(BRect frame, const char* name, const char* label,
-							 BMessage *message, uint32 resizingMode,
+		BMessage* message, uint32 resizingMode, uint32 flags)
-							 uint32 flags)
+	\brief Construct a check box in the \a frame with a \a name, \a label,
-	\brief Construct a checkbox in the \a frame with a \a name, \a label,
 		model \a message, \a resizingMode, and creation \a flags.
 
-	The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF).
+	\note This constructor will resize the control to it's minimum height if needed
+	      for compatibility with BeOS R5.
+
+	The initial value of the check box is 0 (\c B_CONTROL_OFF).
 	The \a label and the \a message parameters can be set to \c NULL.
 
-	\param frame The frame to draw the checkbox in.
+	\param frame The \a frame to draw the check box in.
-	\param name The name of the checkbox.
+	\param name The \a name of the check box.
-	\param label The label displayed along with the checkbox.
+	\param label The \a label displayed along with the check box control.
-	\param message The message to send when the checkbox is activated.
+	\param message The \a message to send when the check box is activated.
-	\param resizingMode Defines the behavior of the checkbox as the parent
+	\param resizingMode Defines the behavior of the check box as the parent
-		view resizes.
+		view resizes. See BView for details.
-	\param flags Behavior flags for the checkbox. See BView for details.
+	\param flags Behavior \a flags for the check box. See BView for details.
 */
 
 
 /*!
-	\fn BCheckBox::BCheckBox(const char *name, const char *label,
+	\fn BCheckBox::BCheckBox(const char* name, const char* label,
-							 BMessage *message, uint32 flags)
+		BMessage* message, uint32 flags)
-	\brief Construct a checkbox with a \a name, \a label, model \a message,
+	\brief Construct a check box with a \a name, \a label, model \a message,
 		and creation \a flags suitable for use with the Layout API.
 
-	The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF).
+	The initial value of the check box is 0 (\c B_CONTROL_OFF).
 	The \a label and the \a message parameters can be set to \c NULL.
 
-	\param name The name of the checkbox.
+	\param name The \a name of the check box.
-	\param label The label displayed along with the checkbox.
+	\param label The \a label displayed along with the check box control.
-	\param message The message to send when the checkbox is activated.
+	\param message The \a message to send when the check box is activated.
-	\param flags Behavior flags for the checkbox. See BView for details.
+	       See BView for details.
+	\param flags Behavior \a flags for the check box. See BView for details.
 */
 
 
 /*!
-	\fn BCheckBox::BCheckBox(const char *label, BMessage *message)
+	\fn BCheckBox::BCheckBox(const char* label, BMessage* message)
 	\brief Constructs a BCheckBox object with just a \a label and model
 		\a message.
 
-	The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF).
+	The initial value of the check box is set to 0 (\c B_CONTROL_OFF).
 	The \a label and the \a message parameters can be set to \c NULL.
 
-	\param label The label displayed along with the checkbox.
+	\param label The \a label displayed along with the check box.
-	\param message The message to send when the checkbox is activated.
+	\param message The \a message to send when the check box is activated.
 */
 
 
 /*!
-	\fn BCheckBox::BCheckBox(BMessage *archive)
+	\fn BCheckBox::BCheckBox(BMessage* archive)
 	\brief Constructs a BCheckBox object from an \a archive message.
 
-	This method is usually not called directly. If you want to build a
+	This method is usually not called directly, if you want to build a
-	checkbox from a message you should call Instantiate() which can
+	check box from an archived message you should call Instantiate() instead
-	handle errors properly.
+	because it can handle errors properly.
 
-	If the \a archive deep, the BCheckBox object will also unarchive each
+	\param archive The message to construct the BCheckBox object from.
-	of its child views recursively.
-
-	\param archive The \a archive message to restore from.
 */
 
 
 /*!
 	\fn BCheckBox::~BCheckBox()
-	\brief Destructor Method.
+	\brief Destructor, does nothing.
+*/
+
+
+/*!
+	\name Archiving
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BArchivable* BCheckBox::Instantiate(BMessage* archive)
+	\brief Creates a new BCheckBox object from the \a archive message.
+
+	\return A newly created check box or \c NULL if the message doesn't
+	        contain an archived BCheckBox.
+*/
+
+
+/*!
+	\fn status_t BCheckBox::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 BCheckBox::AttachedToWindow()
+	\brief Hook method called when the control is attached to a window.
+
+	The default implementation does nothing.
+
+	\sa BControl::AttachedToWindow()
+*/
+
+
+/*!
+	\fn void BCheckBox::DetachedFromWindow()
+	\brief Hook method called when the control is detached from a window.
+
+	The default implementation does nothing.
+
+	\sa BControl::DetachedFromWindow()
+*/
+
+
+/*!
+	\fn void BCheckBox::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 BCheckBox::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()
 */
 
 
 /*!
 	\fn void BCheckBox::Draw(BRect updateRect)
-	\brief Draws the area of the checkbox that intersects \a updateRect.
+	\brief Draws the area of the check box that intersects \a updateRect.
 
 	\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 checkbox
+	      have to call it yourself. If you need to forcefully redraw a
-	consider calling Invalidate() instead.
+	      check box consider calling Invalidate() instead.
 
 	\param updateRect The rectangular area to be drawn.
 
@@ -131,22 +214,146 @@
 
 
 /*!
-	\fn void BCheckBox::GetPreferredSize(float* _width, float* _height)
+	\fn void BCheckBox::FrameMoved(BPoint newPosition)
-	\brief Fill out the preferred width and height of the checkbox
+	\brief Hook method called when the check box is moved.
-		into the \a _width and \a _height parameters.
 
-	\param _width Pointer to a \c float to hold the width of the checkbox.
+	The default implementation does nothing.
-	\param _height Pointer to a \c float to hold the height of the checkbox.
 
-	\sa BView::GetPreferredSize()
+	\param newPosition The point that the check box has been moved to.
+
+	\sa BView::FrameMoved()
 */
 
 
 /*!
-	\fn void BCheckBox::SetValue(int32 value)
+	\fn void BCheckBox::FrameResized(float width, float height)
-	\brief Turn the checkbox on or off.
+	\brief Hook method called when the check box is resized.
 
-	\param value The value to set the checkbox to, should be
+	The default implementation does nothing.
+
+	\param width The new \a width of the check box.
+	\param height The new \a height of the check box.
+
+	\sa BView::FrameResized()
+*/
+
+
+/*!
+	\fn void BCheckBox::GetPreferredSize(float* _width, float* _height)
+	\brief Fill out the preferred width and height of the check box
+	       into the \a _width and \a _height parameters.
+
+	\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 BCheckBox::GetSupportedSuites(BMessage* message)
+	\brief Report the suites of messages this control understands.
+
+	\param message Allows you to add the names of the suites the check box
+	       implements to the suites array.
+
+	\return \c B_OK if all went well or an error code otherwise.
+
+	\sa BControl::GetSupportedSuites();
+*/
+
+
+
+/*!
+	\fn void BCheckBox::KeyDown(const char* bytes, int32 numBytes)
+	\brief Hook method called when a keyboard key is pressed.
+
+	Inverts the value 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 BCheckBox::MessageReceived(BMessage* message)
+	\brief Handle \a message received by the associated looper.
+
+	\param message The \a message received by the associated looper.
+
+	\see BControl::MessageReceived()
+*/
+
+
+/*!
+	\fn void BCheckBox::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 BCheckBox::MouseMoved(BPoint where, uint32 code,
+		const BMessage* dragMessage)
+	\brief Hook method called when the mouse is moved.
+
+	Once MouseDown() has been called on a check box this method updates
+	the outline when the cursor is inside the control redrawing as necessary.
+
+	\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 control.
+	- \c B_INSIDE_VIEW The cursor is inside the control.
+	- \c B_EXITED_VIEW The cursor has left the control's bounds. This only gets
+	     sent if the scope of the mouse events that the control 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 BCheckBox::MouseUp(BPoint where)
+	\brief Hook method called when a mouse button is released.
+
+	Inverts the check box value.
+
+	\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.
+
+	\sa BControl::MouseUp()
+*/
+
+
+
+/*!
+	\fn void BCheckBox::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 BCheckBox::SetValue(int32 value)
+	\brief Turn the check box on or off.
+
+	\param value The value to set the check box to, should be
 		either \c B_CONTROL_ON or \c B_CONTROL_OFF.
 
 	\sa BControl::SetValue()