Merge branch 'master' of git://github.com/haiku/haiku

docs/user/interface/Alert.dox

@@ -1,12 +1,12 @@
 /*
  * Copyright 2011, Haiku inc.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
  * Documentation by:
- *  John Scipione <[email protected]>
+ *		John Scipione <[email protected]>
  * Corresponds to:
- *  /trunk/headers/os/interface/Alert.h	 rev 42274
- *  /trunk/src/kits/interface/Alert.cpp	 rev 42274
+ *		/trunk/headers/os/interface/Alert.h	 rev 42274
+ *		/trunk/src/kits/interface/Alert.cpp	 rev 42274
  */
 
 
@@ -77,6 +77,7 @@
 /*!
 	\class BAlert
 	\ingroup interface
+	\ingroup libbe
 	\brief The BAlert class defines a modal alert dialog which displays a short
 		message and provides a set of labeled buttons that allow the user to
 		respond.

docs/user/interface/Box.dox

@@ -20,17 +20,15 @@
 /*!
 	\class BBox
 	\ingroup interface
-	\brief The BBox class is used to draw a square box in a window with an
-	optional label to group related subviews.
-
-	A BBox is an organizational interface element used to group related views 
-	together visually. A basic BBox looks like this:
+	\brief A rectangular view with a border and an optional label to group
+		related subviews visually.
 
+	A basic BBox looks like this:
 	\image html B_FANCY_BORDER.png
 
-	A box's label can either be text or it can be another control such
+	A box's label can either be composed of text or it can be a view such
 	as a checkbox or dropdown box. See SetLabel() for more details on setting
-	the label on a BBox.
+	the box's label.
 */
 
 
@@ -39,17 +37,17 @@
 		uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
 		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
 		border_style border = B_FANCY_BORDER)
-	\brief Constructs a BBox from a set of dimensions.
+	\brief Constructs a named BBox object from a set of dimensions.
 
-	\note This is the only constructor that can be used if the BBox is to be
+	\note This is the only constructor that can be used if the box is to be
 		inserted in a window that doesn't use the layout system.
 
-	\param frame The bounds of the BBox.
-	\param name The name of the BBox.
-	\param resizingMode Defines the behavior of the BBox as the parent view
-		resizes.
-	\param flags Behavior flags for the BBox. See BView for details.
-	\param border The border_style of the BBox.
+	\param frame The bounds of the box.
+	\param name The name of the box.
+	\param resizingMode Defines the behavior of the box as the parent view
+		resizes. See BView for details.
+	\param flags Behavior flags for the box. See BView for details.
+	\param border The border_style of the box.
 */
 
 
@@ -57,40 +55,39 @@
 	\fn BBox::BBox(const char* name,
 		uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP,
 		border_style border = B_FANCY_BORDER, BView* child = NULL)
-	\brief Constructs a named BBox with dimensions defined automatically by the
-		Layout Kit.
+	\brief Constructs a named BBox object with its dimensions defined
+		automatically by the Layout API.
 
-	\param name The name of the BBox.
-	\param flags Behavior flags for the BBox. See BView for details.
-	\param border The border_style of the BBox.
-	\param child Adds an initial child to the BBox. See the Layout Kit for
-		details.
+	\param name The name of the box.
+	\param flags Behavior flags for the box. See BView for details.
+	\param border The border_style of the box.
+	\param child Adds an initial child to the Box object. See the Layout
+		API for details.
 */
 
 
 /*!
 	\fn BBox::BBox(border_style border, BView* child)
-	\brief Constructs an anonymous BBox, with a defined border style and
-		a child.
+	\brief Constructs an anonymous BBox object with a defined border style
+		and child view.
 
-	There can only be a single child view in the BBox. This view can, however,
-	act as a nesting container if you need more things to show inside the BBox.
+	There can only be a single child view. This view can, however, act as a
+	nesting container if you need to show more items inside the box.
 */
 
 
 /*!
 	\fn BBox::BBox(BMessage* archive)
-	\brief For archive restoration, allows a BBox to be constructed from an
-		\a archive message.
+	\brief Constructs a BBox object from an \a archive message.
 
 	This method is usually not called directly. If you want to build a BBox
-	from a message then you should call Instantiate() which can handle errors
-	properly.
+	object from a message you should call Instantiate() which can
+	handle errors properly.
 
-	If the \a archive is a deep one, the BBox will also unarchive all
-	of its children recursively.
+	If the \a archive deep, the BBox object will also unarchive each of its
+	child views recursively.
 
-	\param archive The \a archive to restore from.
+	\param archive The \a archive message to restore from.
 */
 
 
@@ -104,77 +101,89 @@
 
 
 /*!
-	\fn static BArchivable*	BBox::Instantiate(BMessage* archive)
-	\brief Creates a new BBox from an \a archive.
+	\fn static BArchivable* BBox::Instantiate(BMessage* archive)
+	\brief Creates a new object from an \a archive.
 
-	If the message is a valid BBox then an instance of BBox created from the
+	If the message is a valid object then the instance created from the
 	passed in \a archive will be returned. Otherwise this method will
 	return \c NULL.
 
 	\param archive The \a archive message.
 
-	\returns An instance of BBox if the \a archive is valid or \c NULL.
+	\returns An instance of the object if \a archive is valid or \c NULL.
+
+	\sa BArchivable::Instantiate()
 */
 
 
 /*!
 	\fn virtual	status_t BBox::Archive(BMessage* archive,
 		bool deep = true) const;
-	\brief Archives the BBox into \a archive.
+	\brief Archives the object into \a archive.
+
+	\param archive The target \a archive that the data will go into.
+	\param deep Whether or not to recursively archive child views.
 
-	\param archive The target \a archive which the BBox data will go
-		into.
-	\param deep Whether or not to recursively archive the children.
-	\returns A status flag indicating if the archive operation was successful.
-	
 	\retval B_OK The archive operation was successful.
-	\retval B_BAD_VALUE The archive operation failed.
+	\retval B_BAD_VALUE \c NULL \a archive message.
+	\retval B_ERROR The archive operation failed.
+
+	\sa BArchivable::Archive()
 */
 
 
 /*!
-	\fn virtual	void BBox::SetBorder(border_style border)
-	\brief Sets the border style.
+	\fn virtual void BBox::SetBorder(border_style border)
+	\brief Sets the #border_style.
 
-	Possible values are \c B_PLAIN_BORDER (a single 1-pixel line border),
-	\c B_FANCY_BORDER (the default, beveled look), and \c B_NO_BORDER, which
-	is used to make an invisible box. See border_style for more details.
+	Possible #border_style values include:
+		- \c B_PLAIN_BORDER A single 1-pixel line border.
+		- \c B_FANCY_BORDER The default, beveled look.
+		- \c B_NO_BORDER Used to make a borderless box.
+
+	\param border The #border_style to set.
 */
 
 
 /*!
 	\fn border_style BBox::Border() const
-	\brief Gets the current border_style of a BBox.
+	\brief Gets the current #border_style.
 
-	\returns The border_style flag that is currently set to the BBox.
+	Possible #border_style values include:
+		- \c B_PLAIN_BORDER A single 1-pixel line border.
+		- \c B_FANCY_BORDER The default, beveled look.
+		- \c B_NO_BORDER Used to make a borderless box.
+
+	\returns The #border_style of the box.
 */
 
 
 /*!
 	\fn float BBox::TopBorderOffset()
-	\brief Gets the distance from the very top of the BBox to the top border
-		line in pixels as a \c float.
+	\brief Gets the distance from the very top of the box to the top border
+		line in pixels.
 
 	\warning This method is not part of the BeOS R5 API and is not yet
 		finalized.
 
-	The distance may vary depending on the text or view used as label, and the
-	font settings. The border is drawn center aligned with the label. You can
-	use this value to line up two boxes visually if one has a label and the
-	other does not.
+	The distance may vary depending on the text or view used as label and the
+	font settings. The border is drawn center-aligned with the label. This
+	method can be used to line up two boxes visually if one has a label and
+	the other does not.
 
-	\returns The distance offset of the BBox as a \c float.
+	\returns The distance from the very top of the box to the top border
+		line in pixels as a \c float.
 */
 
 
 /*!
 	\fn BRect BBox::InnerFrame()
-	\brief Gets the rectangle just inside the border of the BBox as a BRect.
+	\brief Gets the frame rectangle just inside the border of the box.
 
 	\warning This method is not part of the BeOS R5 API and is not yet
 		finalized.
 
-	\returns A BRect of the dimensions of the box's inside border.
+	\returns A BRect set to the dimensions of the box's inside border.
 */
 
 
@@ -182,12 +191,11 @@
 	\fn void BBox::SetLabel(const char* string)
 	\brief Sets the box's label text.
 
-	Below is an example of a BBox with a simple text label:
+	Below is an example of a box with some simple text label:
 
 	\image html BBox_example.png
 
-	The code to create a BBox with a text label looks like this:
-
+	The code to create a box with a text label looks like this:
 	\code
 fIconBox = new BBox("Icon Box");
 fIconBox->SetLabel("Icon");
@@ -199,18 +207,16 @@ fIconBox->SetLabel("Icon");
 
 /*!
 	\fn status_t BBox::SetLabel(BView* viewLabel)
-	\brief Sets the label from a pre-existing BView.
+	\brief Sets the label from a BView.
 
-	This version of SetLabel() allows building a BBox with a control as a
-	label widget. You can pass in any type of BView derived control for this
-	such as a BPopupMenu or BCheckBox.
-
-	An example of a BBox with a BCheckBox control attached is shown below:
+	This version of SetLabel() provides for building a BBox object with a
+	control used in place of the text label. You can pass in any type of
+	BView derived control for this such as a BPopupMenu or BCheckBox.
 
+	An example of a box with a checkbox view is shown below:
 	\image html BBox_with_checkbox.png
 
-	The code to create such a BBox looks like this:
-
+	The code to create such a box looks like this:
 	\code
 fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box",
 	"Enable virtual memory", new BMessage(kVirtualMemoryEnabled));
@@ -220,132 +226,137 @@ fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox);
 	\endcode
 
 	\param viewLabel A BView.
+
 	\returns \c B_OK
 */
 
 
 /*!
-	\fn const char*	BBox::Label() const
-	\brief Gets the label's text.
+	\fn const char* BBox::Label() const
+	\brief Gets the text of the box's label.
 
-	This only works if the label was set as text. If you set another view as the
-	label, you have to get its text by other means, likely starting with
+	This only works if the label is set as text. If you set the label to a
+	BView, you have to get the text by other means, likely starting with
 	LabelView.
 
-	\returns The label text of the BBox as a <tt>const char*</tt> if the BBox
-		has a text label or \c NULL otherwise.
+	\returns The label text of the BBox if the box has a text label or
+		\c NULL otherwise.
 */
 
 
 /*!
-	\fn BView*	BBox::LabelView() const
+	\fn BView* BBox::LabelView() const
 	\brief Gets the BView representing the label.
+
+	\returns a pointer to a BView object.
 */
 
 
 /*!
-	\fn virtual	void BBox::Draw(BRect updateRect)
-	\brief Draws onto the parent window the part of the BBox that intersects
-		the dirty area.
+	\fn virtual void BBox::Draw(BRect updateRect)
+	\brief Draws the area of the box that intersects \a updateRect.
 
-	This is an hook method called by the interface kit. You don't have to call
-	it yourself. If you need to force redrawing of (part of) the BBox, consider
-	using Invalidate instead.
+	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 view,
+	consider calling Invalidate() instead.
 
-	\param updateRect The area that needs to be redrawn. Note the box may draw
-		more around the rectangle.
+	\param updateRect The rectangular area to be drawn.
 */
 
 
 /*!
-	\fn virtual	void BBox::AttachedToWindow()
-	\brief Hook method called when the BBox is attached to a window.
+	\fn virtual void BBox::AttachedToWindow()
+	\brief Hook method that is called when the object is attached to a
+		window.
 
-	This method sets the box's background color to the background of the
-	parent view.
+	This method overrides BView::AttachedToWindow() to set the background
+	color of the box to the background of its parent view.
 
 	If you are using the layout system, the BBox is also resized according to
 	the layout of the parent view.
+
+	\sa BView::AttachedToWindow()
 */
 
 
 /*!
 	\fn virtual void BBox::FrameResized(float width, float height)
-	\brief Called when the BBox needs to change its size.
+	\brief Hook method that gets called when the BBox object is resized.
 
-	This method may be called either because the window in which the BBox is
-	was resized, or because the window layout was otherwise altered.
+	This method may be called either because the window in which the BBox
+	object was resized, or because the window layout was otherwise altered.
 
-	It recomputes the layout of the BBox (including label and contents) and
-	makes it redraw as necessary.
+	This method recomputes the layout of the BBox (including label and
+	contents) and makes it redraw as necessary.
 */
 
 
 /*!
 	\fn virtual void BBox::ResizeToPreferred()
-	\brief Resizes the BBox to its preferred dimensions.
+	\brief Resizes the box to its preferred dimensions.
 
-	This only works in the non-layout mode, as it forces the resizing.
+	\note This only works in the non-layout mode, as it forces the resizing.
 */
 
 
 /*!
 	\fn virtual void BBox::GetPreferredSize(float* _width, float* _height)
-	\brief Gets the dimensions that the BBox would prefer to be.
-
-	The size is computed from the children sizes, unless it was explicitly set
-	for the BBox (which can be done only if the BBox is configured to
-	use the Layout Kit).
+	\brief Fill out the preferred width and height of the box
+		into the \a _width and \a _height parameters.
 
 	\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.
+	The size is computed from the child view sizes, unless it was explicitly
+	set for the BBox (which can be done only if the BBox is configured to
+	use the Layout API).
+
+	\param[out] _width Pointer to a \c float to store the width of the view.
+	\param[out] _height Pointer to a \c float to store the height of the view.
 */
 
 
 /*!
-	\fn virtual	BSize BBox::MinSize()
-	\brief Gets the minimum possible size of the BBox.
+	\fn virtual BSize BBox::MinSize()
+	\brief Gets the minimum possible size of the BBox object.
 
-	Drawing the BBox at this size ensures the label and the child view are
-	visible. Going smaller means something may get invisible on screen for lack
-	of space.
+	Drawing the box at this size ensures the label and the child view are
+	visible. Reducing the size even more would mean that a view would not
+	be visible.
 */
 
 
 /*!
-	\fn virtual	BSize BBox::MaxSize()
-	\brief Gets the maximum possible size of the BBox.
+	\fn virtual BSize BBox::MaxSize()
+	\brief Gets the maximum possible size of the BBox object.
 
-	The maximum size depends on the child view's one.
+	The maximum size depends on the maximize size of the child views.
 
-	\returns A BSize of the maximum possible size of the BBox.
+	\returns The maximum possible size of the BBox as a BSize.
 */
 
 
 /*!
-	\fn virtual	BSize BBox::PreferredSize()
-	\brief Returns the box's preferred size.
+	\fn virtual BSize BBox::PreferredSize()
+	\brief Returns the preferred size of the box.
 
-	This is the same as GetPreferredSize, but using the more convenient BSize
-	struct.
+	This method works the same as GetPreferredSize, but uses the more
+	convenient BSize object.
 
-	\returns A BSize of the minimum possible size of the BBox.
+	\returns The minimum possible size of the BBox as a BSize.
 */
 
 
 /*!
-	\fn virtual	void BBox::DoLayout()
-	\brief Lays out the BBox. Moves everything into its appropriate position.
+	\fn virtual void BBox::DoLayout()
+	\brief Lays out the box moving everything into its appropriate position.
 
-	This only works if the BBox uses the layout system from the Layout Kit,
+	This only works if the BBox object was constructed using the Layout API,
 	i.e. it was created with one of the BRect-less constructors.
 
-	Once the size of the BBox is known, from layouting of the parent views,
-	this method is called so the BBox can adjust the position and size of the
-	label, eventually truncating the text if there is not enough space. The
-	exact border positions are also computed, then the child view is also
-	layouted if its size constraints changed.
+	Once the size of the box is known from laying out its parent views,
+	this method is called so the box can adjust the position and size of the
+	label, eventually truncating the label text if there is not enough space.
+	The exact border positions are also computed, then the child view is also
+	laid out if its size constraints change.
 */

docs/user/interface/Button.dox

@@ -1,12 +1,12 @@
 /*
  * Copyright 2011, Haiku inc.
- * Distributed under the terms of the MIT Licence.
+ * Distributed under the terms of the MIT License.
  *
  * Documentation by:
- *  John Scipione <[email protected]>
+ *		John Scipione, [email protected]
  * Corresponds to:
- *  /trunk/headers/os/interface/Button.h
- *  /trunk/src/kits/interface/Button.cpp
+ *		/trunk/headers/os/interface/Button.h	 rev 42794
+ *		/trunk/src/kits/interface/Button.cpp	 rev 42794
 
 
 /*!
@@ -141,59 +141,51 @@
 
 
 /*! \fn BButton::BButton(BMessage* archive)
-	\brief Creates a new BButton from an \a archive.
+	\brief Constructs a BButton object from an \a archive message.
 
-	If the message is a valid button then an instance of BButton created
-	from the passed in \a archive will be returned. Otherwise this method
-	will return \c NULL.
+	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.
 
-	\returns An instance of BButton if the \a archive is valid or \c NULL.
-*/
+	If the \a archive deep, the BButton object will also unarchive each
+	of its child views recursively.
 
-
-/*!
-	\fn BArchivable* BButton::Instantiate(BMessage* archive)
-	\brief Instantiates a BButton from a BMessage.
-
-	\param archive The \c archive message to instantiate the BButton.
-
-	\returns a BArchivable object of the BButton.
-*/
-
-
-/*!
-	\fn status_t BButton::Archive(BMessage* archive, bool deep) const
-	\brief Archives the BButton into \a archive.
-
-	\param archive The target \a archive which the BButton data will
-		go into.
-	\param deep Whether or not to recursively archive the BButton's children.
-
-	\retval B_OK The archive operation was successful.
-	\retval B_BAD_VALUE The archive operation failed.
+	\param archive The \a archive message to restore from.
 */
 
 
 /*!
 	\fn void BButton::Draw(BRect updateRect)
-	\brief Draws the button and sets its label.
+	\brief Draws the area of the button that intersects \a updateRect and
+		sets the label.
 
-	\param updateRect The BRect which the button is drawn into.
+	\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.
+
+	\param updateRect The rectangular area to be drawn.
+
+	\sa BView::Draw()
 */
 
 
 /*!
 	\fn void BButton::MouseDown(BPoint point)
-	\brief Hook method to respond to a MouseDown event.
+	\brief Hook method that is called when a mouse button is pressed.
 
-	\param point The point on the screen that the mouse pointer is located at.
+	\param point The point on the screen where to mouse pointer is when
+		the mouse button is pressed.
+
+	\sa BView::MouseDown()
 */
 
 
 /*!
 	\fn void BButton::AttachedToWindow()
-	\brief Hook method that is called when the BButton view is attached
-	to the window.
+	\brief Hook method that is called when the object is attached to a
+		window.
+
+	\sa BControl::AttachedToWindow()
 */
 
 
@@ -235,50 +227,6 @@
 */
 
 
-/*!
-	\fn void BButton::MessageReceived(BMessage *message)
-	\brief Hook method that is called when a message is received by the BButton.
-
-	\param message The message received.
-*/
-
-
-/*!
-	\fn void BButton::WindowActivated(bool active)
-	\brief Sets the window that the BButton is attached to as activated or not.
-
-	\param active if \c true the window is activated, if \c false the window is
-		deactivated.
-*/
-
-
-/*!
-	\fn void BButton::MouseMoved(BPoint point, uint32 transit,
-		const BMessage *message)
-	\brief Hook method that is called when the mouse is moved.
-
-	\param point The point on the screen that the mouse pointer is located at.
-	\param transit ???
-	\param message The message that is received when the mouse is moved.
-*/
-
-
-/*!
-	\fn void BButton::MouseUp(BPoint point)
-	\brief Hook method that is called when a mouse button is unpressed.
-
-	\param point The point on the screen that the mouse pointer is located at.
-*/
-
-
-/*!
-	\fn void BButton::DetachedFromWindow()
-	\brief Detaches the BButton from the window.
-
-	\see BControl::DetachedFromWindow()
-*/
-
-
 /*!
 	\fn void BButton::SetValue(int32 value)
 	\brief Sets the value of the BButton.
@@ -314,7 +262,7 @@
 	\fn void BButton::ResizeToPreferred()
 	\brief Resizes the BButton to its preferred size.
 
-	\see BControl::ResizeToPreferred()
+	\see BView::ResizeToPreferred()
 */
 
 
@@ -343,7 +291,7 @@
 	\param newLocation The location on the screen that the BButton
 		is moved to.
 
-	\see BControl::FrameMoved();
+	\see BView::FrameMoved();
 */
 
 
@@ -354,7 +302,7 @@
 	\param width the new \a width of the BButton
 	\param height the new \a height of the BButton
 
-	\see BControl::FrameResized();
+	\see BView::FrameResized();
 */
 
 
@@ -362,47 +310,13 @@
 	\fn void BButton::MakeFocus(bool focused)
 	\brief Focus or unfocus the BButton.
 
-	\param focused If \c true focus the BButton, otherwise unfocus the BButton.
+	\param focused If \c true focus the button, otherwise remove focus from
+		the button.
 
 	\see BControl::MakeFocus()
 */
 
 
-/*!
-	\fn void BButton::AllAttached()
-	\brief Hook method that is called when the BButton is attached.
-
-	\see BControl::AllAttached()
-*/
-
-
-/*!
-	\fn void BButton::AllDetached()
-	\brief Hook method that is called when the BButton is deattached.
-
-	\see BControl::AllDetached()
-*/
-
-
-/*!
-	\fn BHandler* BButton::ResolveSpecifier(BMessage *message, int32 index,
-		BMessage *specifier, int32 what, property)
-	\brief Resolves specifiers for properties.
-	\see BHandler::ResolveSpecifier()
-*/
-
-
-/*!
-	\fn status_t BButton::GetSupportedSuites(BMessage *message)
-	\brief Reports the suites of messages and specifiers that derived classes
-		understand.
-
-	\param message The message to report the suite of messages and specifiers.
-
-	\see BWindow::GetSupportedSuites()
-*/
-
-
 /*!
 	\fn status_t BButton::Perform(perform_code code, void* _data)
 	\brief Perform an action on the BButton.
@@ -453,4 +367,3 @@
 
 	\returns The preferred BButton size as a BSize
 */
-

docs/user/interface/CheckBox.dox

@@ -0,0 +1,239 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *		Stephan Aßmus, [email protected]
+ *		Marc Flerackers, [email protected]
+ *		John Scipione, [email protected]
+ * Corresponds to:
+ *		/trunk/headers/os/interface/CheckBox.h	 rev 42794
+ *		/trunk/src/kits/interface/CheckBox.cpp	 rev 42794
+ */
+
+/*!
+	\file CheckBox.h
+	\brief Defines the BCheckBox class
+*/
+
+
+/*!
+	\class BCheckBox
+	\ingroup interface
+	\ingroup libbe
+	\brief BCheckBox is a user interface element used to make a binary
+		decision.
+
+	A BCheckBox object is used to draw a checkbox element. This simple control
+	has 2 states, \c B_CONTROL_OFF when the checkbox is unchecked and
+	\c B_CONTROL_ON when the checkbox is checked. A checkbox can also have a
+	descriptive label drawn to the right of the checkbox.
+
+	When the checkbox is checked it has an X drawn inside of it. The checkbox
+	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
+	is surrounded by a blue border. A checkbox can also be set
+	programmatically by calling the SetValue() method.
+
+	A few checkbox examples can be seen below in unchecked state, checked
+	state, and another unchecked checkbox with focus on it.
+
+	\image html BCheckBox_example.png
+*/
+
+
+/*!
+	\fn BCheckBox::BCheckBox(BRect frame, const char *name, const char *label,
+							 BMessage *message, uint32 resizingMode,
+							 uint32 flags)
+	\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).
+	The \a label and the \a message parameters can be set to \c NULL.
+
+	\param frame The frame to draw the checkbox in.
+	\param name The name of the checkbox.
+	\param label The label displayed along with the checkbox.
+	\param message The message to send when the checkbox is activated.
+	\param resizingMode Defines the behavior of the checkbox as the parent
+		view resizes.
+	\param flags Behavior flags for the checkbox. See BView for details.
+*/
+
+
+/*!
+	\fn BCheckBox::BCheckBox(const char *name, const char *label,
+							 BMessage *message, uint32 flags)
+	\brief Construct a checkbox 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 \a label and the \a message parameters can be set to \c NULL.
+
+	\param name The name of the checkbox.
+	\param label The label displayed along with the checkbox.
+	\param message The message to send when the checkbox is activated.
+	\param flags Behavior flags for the checkbox. See BView for details.
+*/
+
+
+/*!
+	\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 \a label and the \a message parameters can be set to \c NULL.
+
+	\param label The label displayed along with the checkbox.
+	\param message The message to send when the checkbox is activated.
+*/
+
+
+/*!
+	\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
+	checkbox from a message you should call Instantiate() which can
+	handle errors properly.
+
+	If the \a archive deep, the BCheckBox object will also unarchive each
+	of its child views recursively.
+
+	\param archive The \a archive message to restore from.
+*/
+
+
+/*!
+	\fn BCheckBox::~BCheckBox()
+	\brief Destructor Method.
+*/
+
+
+/*!
+	\fn void BCheckBox::Draw(BRect updateRect)
+	\brief Draws the area of the checkbox 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
+	consider calling Invalidate() instead.
+
+	\param updateRect The rectangular area to be drawn.
+
+	\sa BView::Draw()
+*/
+
+
+/*!
+	\fn void BCheckBox::FrameMoved(BPoint newLocation)
+	\brief Hook method that gets called when the checkbox is moved.
+
+	\param newLocation The point that the top left corner of the frame
+		is moved to.
+
+	\sa BView::FrameMoved()
+*/
+
+
+/*!
+	\fn void BCheckBox::FrameResized(float width, float height)
+	\brief Hook method that gets called when the checkbox is resized.
+
+	\param width The new \a width of the checkbox.
+	\param height The new \a height of the checkbox.
+
+	\sa BView::FrameResized()
+*/
+
+
+/*!
+	\fn void BCheckBox::GetPreferredSize(float* _width, float* _height)
+	\brief Fill out the preferred width and height of the checkbox
+		into the \a _width and \a _height parameters.
+
+	\param _width Pointer to a \c float to hold the width of the checkbox.
+	\param _height Pointer to a \c float to hold the height of the checkbox.
+
+	\sa BView::GetPreferredSize()
+*/
+
+
+/*!
+	\fn void BCheckBox::ResizeToPreferred()
+	\brief Resize the checkbox to its preferred size.
+
+	\sa BView::ResizeToPreferred()
+*/
+
+
+/*!
+	\fn void BCheckBox::InvalidateLayout(bool descendants)
+	\brief \brief Redraws the checkbox.
+
+	\param descendants Redraw child views as well.
+
+	\sa BLayout::InvalidateLayout()
+*/
+
+
+/*!
+	\fn BSize BCheckBox::MinSize()
+	\brief Get the minimum size of the checkbox.
+
+	\return The minimum size of the checkbox as a BSize.
+
+	\sa BAbstractLayout::MinSize()
+*/
+
+
+/*!
+	\fn BSize BCheckBox::MaxSize()
+	\brief Get the maximum size of the checkbox.
+
+	\return The maximum size of the checkbox as a BSize.
+
+	\sa BAbstractLayout::MaxSize()
+*/
+
+
+/*!
+	\fn BSize BCheckBox::PreferredSize()
+	\brief Get the preferred size of the checkbox.
+
+	\return The preferred size of the checkbox as a BSize.
+
+	\sa BAbstractLayout::PreferredSize()
+*/
+
+
+/*!
+	\fn void BCheckBox::MakeFocus(bool focused)
+	\brief Gives or removes focus from the checkbox.
+
+	\param focused \a true to set focus, \a false to remove it.
+
+	\sa BControl::MakeFocus()
+*/
+
+
+/*!
+	\fn void BCheckBox::SetValue(int32 value)
+	\brief Turn the checkbox on or off.
+
+	\param value The value to set the checkbox to, should be
+		either \c B_CONTROL_ON or \c B_CONTROL_OFF.
+
+	\sa BControl::SetValue()
+*/
+
+
+/*!
+	\fn status_t BCheckBox::Invoke(BMessage *message)
+	\brief Tells the messenger to send a message.
+
+	\param message The \a message to send.
+
+	\sa BInvoker::Invoke()
+*/

docs/user/interface/ColorControl.dox

@@ -0,0 +1,316 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *		John Scipione, [email protected]
+ * Corresponds to:
+ *		/trunk/headers/os/interface/ColorControl.h	 rev 42794
+ *		/trunk/src/kits/interface/ColorControl.cpp	 rev 42794
+ */
+
+
+/*!
+	\file ColorControl.h
+	\brief BColorControl class definition and support enums.
+*/
+
+
+/*! \enum color_control_layout
+	Enumeration of the color control layout options.
+*/
+
+/*!
+	\var color_control_layout B_CELLS_4x64
+	cells are arranged in 4 columns, 64 rows.
+*/
+
+/*!
+	\var color_control_layout B_CELLS_8x32
+	cells are arranged in 8 columns, 32 rows.
+*/
+
+/*!
+	\var color_control_layout B_CELLS_16x16
+	cells are arranged in 16 columns, 16 rows.
+*/
+
+/*!
+	\var color_control_layout B_CELLS_32x8
+	cells are arranged in 32 columns, 8 rows.
+*/
+
+/*!
+	\var color_control_layout B_CELLS_64x4
+	cells are arranged in 64 columns, 4 rows.
+*/
+
+
+/*!
+	\class BColorControl
+	\ingroup interface
+	\ingroup libbe
+
+	\brief BColorControl displays an on-screen color picker.
+
+	The value of the color control is a rgb_color data structure
+	containing a 32-bit color. If a message is specified in the
+	constructor then the message is sent to a target in response to
+	changes in the color value.
+
+	The color value is initially set to 0 which corresponds to black.
+	To set the color of the color control use the SetValue() method.
+
+	An example of creating a color control looks like this:
+\code
+colorControl = new BColorControl(BPoint(0, 0), B_CELLS_32x8, 7.0,
+	"ColorControl", new BMessage(kValueChanged));
+colorControl->SetValue(0x336698);
+\endcode
+
+	A BColorControl contains four color ramps to set the red, green,
+	and blue components of the color control value. A greyscale slider
+	is provided to easily select black, white, and shades of grey. The color
+	control also contains three child BTextControl objects used to set the
+	color by typing in a number between 0 and 255 for the red, green, and
+	blue components of the color value.
+
+	\image html BColorControl_example.png
+
+	If the screen is set to 8-bit (256) colors then the color ramps are
+	replaced with a palette of color cells.
+
+	\image html BColorControl_example_256_colors.png
+
+	You can set the size of these cells by calling the SetCellSize() method.
+*/
+
+
+/*!
+	\fn BColorControl::BColorControl(BPoint leftTop,
+		color_control_layout layout, float cellSize, const char *name,
+		BMessage *message = NULL, bool bufferedDrawing = false)
+	\brief Constructs a new color control object.
+
+	\param leftTop location of the left top corner of the frame rectangle
+		relative to the parent view.
+	\param layout The \a layout of the BColorControl. See the
+		#color_control_layout enum for more information. Color control
+		layout options include:
+			- \c B_CELLS_4x64
+			- \c B_CELLS_8x32
+			- \c B_CELLS_16x16
+			- \c B_CELLS_32x8
+			- \c B_CELLS_32x8
+	\param cellSize The size of the sides of the color cell.
+	\param name The name of the color control.
+	\param message The optional \a message to send to a target in response
+		to a change in color value.
+	\param bufferedDrawing If \c true, all on-screen changes are first
+		made to an off-screen bitmap and then copied to the screen
+		making the drawing smoother, but requiring more memory
+		(currently unused).
+*/
+
+
+/*!
+	\fn BColorControl::BColorControl(BMessage* archive)
+	\brief Constructs a BColorControl object from an \a archive message.
+
+	This method is usually not called directly. If you want to build a
+	color control from a message you should call Instantiate() which can
+	handle errors properly.
+
+	If the \a archive deep, the BColorControl object will also unarchive
+	each of its child views recursively.
+
+	\param archive The \a archive message to restore from.
+*/
+
+
+/*!
+	\fn BColorControl::~BColorControl()
+	\brief Destructor method.
+*/
+
+
+/*!
+	\fn void BColorControl::SetLayout(BLayout* layout)
+	\brief Set the layout of the BColorControl object to \a layout.
+
+	\param layout The \a layout to set.
+
+	\sa BView::SetLayout()
+*/
+
+
+/*!
+	\fn void BColorControl::SetLayout(color_control_layout layout)
+	\brief Set the layout of the color control.
+
+	Color control layout options include:
+		- \c B_CELLS_4x64
+		- \c B_CELLS_8x32
+		- \c B_CELLS_16x16
+		- \c B_CELLS_32x8
+		- \c B_CELLS_32x8
+
+	\param layout The color control layout to set.
+*/
+
+
+
+/*!
+	\fn void BColorControl::SetValue(int32 value)
+	\brief Set the color of the BColorControl to \a value.
+
+	\param value The 32-bit color value to set.
+*/
+
+
+/*!
+	\fn inline void BColorControl::SetValue(rgb_color color)
+	\brief Set the color of the BColorControl to \a color.
+
+	\param color The rgb_color to set.
+*/
+
+
+/*!
+	\fn rgb_color BColorControl::ValueAsColor()
+	\brief Return the current color value as an rgb_color.
+
+	\returns The current color as an rgb_color.
+*/
+
+
+/*!
+	\fn void BColorControl::SetEnabled(bool enabled)
+	\brief Enable and disable the color control.
+
+	\param enabled Whether to enable or disable the color control.
+*/
+
+
+/*!
+	\fn void BColorControl::AttachedToWindow()
+	\brief Hook method that is called when the object is attached to a
+		window.
+
+	This method also sets the view color and low color of the color control
+	to be the same as its parent's view color and sets the red, green, and
+	blue BTextControl color values.
+
+	\sa BControl::AttachedToWindow()
+	\sa BView::SetViewColor()
+*/
+
+
+/*!
+	\fn void BColorControl::Draw(BRect updateRect)
+	\brief Draws the area of the color control 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 color
+	control consider calling Invalidate() instead.
+
+	\param updateRect The area to be drawn.
+
+	\sa BView::Draw()
+*/
+
+
+/*!
+	\fn void BColorControl::SetCellSize(float cellSide)
+	\brief Set the size of the color cell in the color control.
+
+	\param cellSide The cell size to set.
+*/
+
+
+/*!
+	\fn float BColorControl::CellSize() const
+	\brief Get the current color cell size.
+
+	\returns the current color cell size as a float.
+*/
+
+
+/*!
+	\fn color_control_layout BColorControl::Layout() const
+	\brief Get the current color control layout.
+
+	\returns The current color_control_layout
+*/
+
+
+/*!
+	\fn void BColorControl::DetachedFromWindow()
+	\brief Hook method that is called when the object is detached from a
+		window.
+
+	\sa BView::DetachedFromWindow()
+*/
+
+
+/*!
+	\fn void BColorControl::GetPreferredSize(float *_width, float *_height)
+	\brief Fill out the preferred width and height of the checkbox
+		into the \a _width and \a _height parameters.
+
+	\param _width Pointer to a \c float to hold the width of the checkbox.
+	\param _height Pointer to a \c float to hold the height of the checkbox.
+
+	\sa BView::GetPreferredSize()
+*/
+
+
+/*!
+	\fn void BColorControl::ResizeToPreferred()
+	\brief Resize the color control to its preferred size.
+
+	\sa BView::ResizeToPreferred()
+*/
+
+
+/*!
+	\fn status_t BColorControl::Invoke(BMessage *msg)
+	\brief Tells the messenger to send a message.
+
+	\param msg The message to send.
+
+	\sa BControl::Invoke()
+*/
+
+
+/*!
+	\fn void BColorControl::FrameMoved(BPoint new_position)
+	\brief Hook method that gets called when the color control is moved.
+
+	\param new_position The point that the top left corner of the frame
+		is moved to.
+
+	\sa BView::FrameMoved()
+*/
+
+
+/*!
+	\fn void BColorControl::FrameResized(float new_width, float new_height)
+	\brief Hook method that gets called when the checkbox is resized.
+
+	\param new_width The new width of the checkbox.
+	\param new_height The new height of the checkbox.
+
+	\sa BView::FrameResized()
+*/
+
+
+/*!
+	\fn void BColorControl::MakeFocus(bool state)
+	\brief Gives focus to or removes focus from the color control.
+
+	\param state \a true to set focus, \a false to remove it.
+
+	\sa BControl::MakeFocus()
+
+*/

docs/user/interface/Control.dox

@@ -0,0 +1,422 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *		John Scipione, [email protected]
+ * Corresponds to:
+ *		/trunk/headers/os/interface/Control.h	 rev 42794
+ *		/trunk/src/kits/interface/Control.cpp	 rev 42794
+ */
+
+/*!
+	\file Control.h
+	\brief BControl class definition and support enums.
+*/
+
+
+/*!
+	\var B_CONTROL_ON
+	Control on
+*/
+
+
+/*!
+	\var B_CONTROL_OFF
+	Control off
+*/
+
+
+/*!
+	\class BControl
+	\ingroup interface
+	\ingroup libbe
+	\brief BControl is the base class for user-event handling objects.
+
+	Simple controls such as BCheckBox and BButton deviate only a bit from
+	BControl, whereas more complicated controls such as BColorControl and
+	BSlider re-implement much more functionality. Whether you are building
+	a simple control or something more complicated you should inherit from
+	BControl as it provides a common set of methods for intercepting
+	received messages from mouse and keyboard events.
+
+	Controls have state which they keep in their value. The value of a
+	control, stored as an int32, is read and set by the virtual Value() and
+	SetValue() methods. BControl defines \c B_CONTROL_ON and \c B_CONTROL_OFF
+	values that you can use as a convenience if your control has a simple
+	on/off state. If your BControl derived class stores a larger set of
+	states then you should define your own integer values instead.
+*/
+
+
+/*!
+	\fn BControl::BControl(BRect frame, const char *name, const char *label,
+						   BMessage *message, uint32 resizingMode,
+						   uint32 flags)
+	\brief Construct a control in the \a frame with a \a name, \a label,
+		model \a message, \a resizingMode, and creation \a flags.
+
+	The initial value of the control is set to 0 (\c B_CONTROL_OFF).
+	The \a label and the \a message parameters can be set to \c NULL.
+
+	\param frame The \a frame to draw the control in.
+	\param name The \a name of the control.
+	\param label The \a label displayed along with the control.
+	\param message The \a message to send when the control is activated.
+	\param resizingMode Defines the behavior of the control as the parent
+		view resizes.
+	\param flags Behavior \a flags for the control. See BView for details.
+*/
+
+
+/*!
+	\fn BControl::BControl(const char *name, const char *label,
+						   BMessage *message, uint32 flags)
+	\brief Construct a control 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 control is set to 0 (\c B_CONTROL_OFF).
+	The \a label and the \a message parameters can be set to \c NULL.
+
+	\param name The \a name of the control.
+	\param label The \a label displayed along with the control.
+	\param message The \a message to send when the control is activated.
+	\param flags Behavior \a flags for the control. See BView for details.
+*/
+
+
+/*!
+	\fn BControl::~BControl()
+	\brief Frees all memory used by the BControl object including the memory
+		used by the model message.
+*/
+
+
+/*!
+	\fn BControl::BControl(BMessage *archive)
+	\brief Constructs a BControl object from an \a archive message.
+
+	This method is usually not called directly. If you want to build a
+	control from a message you should call Instantiate() which can
+	handle errors properly.
+
+	If the \a archive deep, the BControl object will also unarchive each
+	of its child views recursively.
+
+	\param archive The \a archive message to restore from.
+*/
+
+
+/*!
+	\fn BArchivable* BControl::Instantiate(BMessage *archive)
+	\brief Creates a new object from an \a archive.
+
+	If the message is a valid object then the instance created from the
+	passed in \a archive will be returned. Otherwise this method will
+	return \c NULL.
+
+	\param archive The \a archive message.
+
+	\returns An instance of the object if \a archive is valid or \c NULL.
+
+	\sa BArchivable::Instantiate()
+*/
+
+
+/*!
+	\fn status_t BControl::Archive(BMessage *archive, bool deep) const
+	\brief Archives the object into \a archive.
+
+	\param archive The target \a archive that the data will go into.
+	\param deep Whether or not to recursively archive child views.
+	
+	\retval B_OK The archive operation was successful.
+	\retval B_BAD_VALUE \c NULL \a archive message.
+	\retval B_ERROR The archive operation failed.
+
+	\sa BArchivable::Archive()
+*/
+
+
+/*!
+	\fn void BControl::WindowActivated(bool active)
+	\brief Hook method that is called when the attached window becomes
+		activated or deactivated.
+
+	The BControl is redrawn if it is a child of the focused view.
+
+	\param active \c true if the window becomes activated, \c false if the
+		window becomes deactivated.
+
+	\sa BView::WindowActivated()
+*/
+
+
+/*!
+	\fn void BControl::AttachedToWindow()
+	\brief Hook method that is called when the object is attached to a
+		window.
+
+	This method overrides BView::AttachedToWindow() setting the low color
+	and view color of the BControl so that it matches the view color of the
+	control's parent view. It also makes the attached window the default
+	target for Invoke() as long as another target has not already been set.
+
+	\sa BView::AttachedToWindow()
+	\sa Invoke()
+	\sa BInvoker::SetTarget()
+*/
+
+
+/*!
+	\fn void BControl::DetachedFromWindow()
+	\brief Hook method that is called when the object is detached from a
+		window.
+
+	\sa BView::DetachedFromWindow()
+*/
+
+
+/*!
+	\fn void BControl::AllAttached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+		all child views have already been attached to a window.
+
+	\sa BView::AllAttached()
+*/
+
+
+/*!
+	\fn void BControl::AllDetached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+		all child views have already been detached from a window.
+
+	\sa BView::AllDetached()
+*/
+
+
+/*!
+	\fn void BControl::MakeFocus(bool focused)
+	\brief Gives or removes focus from the control.
+
+	BControl::MakeFocus() overrides BView::MakeFocus() to call Draw() when
+	the focus changes. Derived classes generally don't have to re-implement
+	MakeFocus().
+
+	IsFocusChanging() returns \c true when Draw() is called from this method.
+
+	\param focused \a true to set focus, \a false to remove it.
+
+	\sa BView::MakeFocus()
+	\sa IsFocusChanging()
+*/
+
+
+/*!
+	\fn void BControl::KeyDown(const char *bytes, int32 numBytes)
+	\brief Hook method that is called when a keyboard key is pressed.
+
+	Overrides BView::KeyDown() to toggle the control value and then
+	calls Invoke() for \c B_SPACE or \c B_ENTER. If this is not desired
+	you should override this method in derived classes.
+
+	The KeyDown() method is only called if the BControl is the focus view
+	in the active window. If the window has a default button, \c B_ENTER
+	will be passed to that object instead of the focus view.
+
+	\param bytes The bytes of the key combination pressed.
+	\param numBytes The number of bytes in \a bytes.
+
+	\sa BView::KeyDown()
+	\sa MakeFocus()
+*/
+
+
+/*!
+	\fn void BControl::MouseDown(BPoint point)
+	\brief Hook method that is called when a mouse button is pressed.
+
+	\param point The point on the screen where to mouse pointer is when
+		the mouse button is pressed.
+
+	\sa BView::MouseDown()
+*/
+
+
+/*!
+	\fn void BControl::MouseUp(BPoint point)
+	\brief Hook method that is called when a mouse button is released.
+
+	\param point The point on the screen where to mouse pointer is when
+		the mouse button is released.
+
+	\sa BView::MouseUp()
+*/
+
+
+/*!
+	\fn void BControl::MouseMoved(BPoint point, uint32 transit,
+								  const BMessage *message)
+	\brief Hook method that is called when the mouse is moved.
+
+	\sa BView::MouseMoved()
+*/
+
+
+/*!
+	\fn void BControl::SetLabel(const char *label)
+	\brief Sets the \a label of the control.
+
+	If the \a label changes the control is redrawn.
+
+	\param label The \a label to set, can be \c NULL.
+*/
+
+
+/*!
+	\fn const char* BControl::Label() const
+	\brief Gets the label of the control.
+
+	returns The control's label.
+*/
+
+
+/*!
+	\fn void BControl::SetValue(int32 value)
+	\brief Sets the value of the control.
+
+	If the \a value changes the control is redrawn.
+
+	\param value The \a value to set.
+
+	\sa SetValueNoUpdate()
+*/
+
+
+/*!
+	\fn void BControl::SetValueNoUpdate(int32 value)
+	\brief Sets the value of the control without redrawing.
+
+	\param value The \a value to set.
+
+	\sa SetValue()
+*/
+
+
+/*!
+	\fn int32 BControl::Value() const
+	\brief Gets the value of the control.
+
+	\returns The control's value.
+*/
+
+
+/*!
+	\fn void BControl::SetEnabled(bool enabled)
+	\brief Enables or disables the control.
+
+	BControl objects are enabled by default. If the control changes enabled
+	state then it is redrawn.
+
+	Disabled controls generally won't allow the user to focus on them
+	(The \c B_NAVIGABLE flag is turned off), and don't post any messages.
+
+	Disabled controls in derived classes should be drawn in subdued colors
+	to visually indicate that they are disabled and should not respond to
+	keyboard or mouse events.
+
+	\param enabled If \c true enables the control, if \c false, disables it.
+*/
+
+
+/*!
+	\fn bool BControl::IsEnabled() const
+	\brief Gets whether or not the control is currently enabled.
+
+	\returns \c true if the control is enabled, \c false if it is disabled.
+*/
+
+
+/*!
+	\fn void BControl::GetPreferredSize(float *_width, float *_height)
+	\brief Fill out the preferred width and height of the control
+		into the \a _width and \a _height parameters.
+
+	Derived classes can override this method to set the preferred
+	width and height of the control.
+
+	\param _width Pointer to a \c float to hold the width of the control.
+	\param _height Pointer to a \c float to hold the height of the control.
+
+	\sa BView::GetPreferredSize()
+*/
+
+
+/*!
+	\fn void BControl::ResizeToPreferred()
+	\brief Resize the control to its preferred size.
+
+	\sa BView::ResizeToPreferred()
+*/
+
+
+/*!
+	\fn status_t BControl::Invoke(BMessage *message)
+	\brief Sends a copy of the model \a message to the designated target.
+
+	BControl::Invoke() overrides BInvoker::Invoke(). Derived classes
+	should use this method in their MouseDown() and KeyDown() methods
+	and should call IsEnabled() to check if the control is enabled
+	before calling Invoke().
+
+	The following fields added to the BMessage:
+		- "when"	\c B_INT64_TYPE	system_time()
+		- "source"	\c B_POINTER_TYPE	A pointer to the BControl object.
+
+	\param message The \a message to send.
+
+	\sa BInvoker::Invoke()
+	\sa IsEnabled()
+*/
+
+
+/*!
+	\fn BHandler* BControl::ResolveSpecifier(BMessage *message, int32 index,
+											 BMessage *specifier, int32 what,
+											 const char *property)
+	\brief Determine the proper specifier for scripting messages.
+
+	\sa BHandler::ResolveSpecifier()
+*/
+
+
+/*!
+	\fn status_t BControl::GetSupportedSuites(BMessage *message)
+	\brief Report the suites of understood messages.
+
+	\sa BHandler::GetSupportedSuites();
+*/
+
+
+/*!
+	\fn status_t BControl::Perform(perform_code code, void* _data)
+	\brief Perform some action. (Internal Method)
+
+	The following perform codes are recognized:
+		- \c PERFORM_CODE_MIN_SIZE
+		- \c PERFORM_CODE_MAX_SIZE
+		- \c PERFORM_CODE_PREFERRED_SIZE
+		- \c PERFORM_CODE_LAYOUT_ALIGNMENT
+		- \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH
+		- \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH
+		- \c PERFORM_CODE_SET_LAYOUT
+		- \c PERFORM_CODE_INVALIDATE_LAYOUT
+		- \c PERFORM_CODE_DO_LAYOUT
+
+	\param code The perform code.
+	\param _data A pointer to store some data.
+
+	\returns A status code.
+
+	\sa BHandler::Perform()
+*/

docs/user/interface/InterfaceDefs.dox

@@ -3,11 +3,14 @@
  * Distributed under the terms of the MIT License.
  */
 
-/*!	\file InterfaceDefs.h
+/*!
+	\file InterfaceDefs.h
 	\brief Defines standard interface definitions for controls.
 */
 
-/*!	\enum border_style
+
+/*!
+	\enum border_style
 	Collection of flags that determine the border style drawn around a BBox.
 */
 
@@ -32,12 +35,15 @@
 	No border.
 */
 
-/*!	\enum orientation
+
+/*!
+	\enum orientation
 Orientation flag sets the layout to either horizontal or vertical
 	alignment.
 */
 
-/*!	\var orientation B_HORIZONTAL
+/*!
+	\var orientation B_HORIZONTAL
 	Horizontal alignment
 */
 
@@ -45,21 +51,132 @@ Orientation flag sets the layout to either horizontal or vertical
 	Vertical alignment
 */
 
-/*!	\enum button_width
+
+/*!
+	\enum button_width
 	Collection of flags that determine how wide to draw the buttons in a
 	BAlert dialog.
 */
 
-/*!	\var button_width B_WIDTH_AS_USUAL
+/*!
+	\var button_width B_WIDTH_AS_USUAL
 	Set the width of each button based on the standard width.
 */
 
-/*!	\var button_width B_WIDTH_FROM_WIDEST
+/*!
+	\var button_width B_WIDTH_FROM_WIDEST
 	Set the width of each button based on the width of the widest button.
 */
 
-/*!	\var button_width B_WIDTH_FROM_LABEL
+/*!
+	\var button_width B_WIDTH_FROM_LABEL
 	Set the width of each button to accomidate the width of the button's
 	label.
 */
 
+
+///// Keyboard related functions
+
+
+/*!
+	\fn uint32 modifiers()
+	\brief Gets a bitmap of each modifier key pressed down and each active
+		keyboard lock.
+
+	Test the bitmap returned using a bit mask composed of the following
+	modifier key constants:
+		- \c B_CAPS_LOCK
+		- \c B_COMMAND_KEY
+		- \c B_CONTROL_KEY
+		- \c B_MENU_KEY
+		- \c B_NUM_LOCK
+		- \c B_OPTION_KEY
+		- \c B_SCROLL_LOCK
+		- \c B_SHIFT_KEY
+
+	You may use a bit mask of 0 to test that no modifier keys are pressed.
+	If it is important to know if the left or right modifier key is pressed
+	down you can use the following additional constants:
+		- \c B_LEFT_SHIFT_KEY
+		- \c B_RIGHT_SHIFT_KEY
+		- \c B_LEFT_CONTROL_KEY
+		- \c B_RIGHT_CONTROL_KEY
+		- \c B_LEFT_OPTION_KEY
+		- \c B_RIGHT_OPTION_KEY
+		- \c B_LEFT_COMMAND_KEY
+		- \c B_RIGHT_COMMAND_KEY
+
+	\returns A bitmap containing each active modifier keys and locks.
+*/
+
+
+/*!
+	\fn status_t get_key_info(key_info* info)
+	\brief Fills out the key_info struct with the current state of the
+		keyboard.
+
+	\param info The key_info struct to fill out.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the key_info struct.
+*/
+
+
+/*!
+	\fn void get_key_map(key_map** _map, char** _keyBuffer)
+	\brief Provides a copy of the system keymap.
+
+	\attention You must free \a _map and \a _keyBuffer when you are done
+		with them.
+
+	\param _map A pointer to the system keymap structure.
+	\param _keyBuffer A pointer containing the UTF-8 character encodings.
+*/
+
+
+/*!
+	\fn status_t get_keyboard_id(uint16* _id)
+	\brief Fills out \a _id with the id of the currently attached keyboard.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the keyboard id.
+*/
+
+
+/*!
+	\fn status_t get_modifier_key(uint32 modifier, uint32 *key)
+	\brief Gets the code of the requested \a modifier key from the
+		system keymap.
+
+	\param modifier The modifier key to get from the system keymap.
+	\param key A pointer to an int32 to store the key code.
+
+	\retval B_OK Everything went fine.
+	\retval B_ERROR There was an error retrieving the modifier key.
+*/
+
+
+/*!
+	\fn void set_modifier_key(uint32 modifier, uint32 key)
+	\brief Set the \a modifier \a key to the specified code in the
+		system keymap.
+
+	\param modifier The modifier key to set in the system keymap.
+	\param key The key code to set the modifier key to.
+*/
+
+
+/*!
+	\fn void set_keyboard_locks(uint32 modifiers)
+	\brief Set the keyboard locks.
+
+	Pass in a bit mask containing the following constants:
+		- \c B_CAPS_LOCK
+		- \c B_NUM_LOCK
+		- \c B_SCROLL_LOCK
+
+	The constants present in the bit mask will turn the lock on, those
+	absent will turn the lock off. Pass 0 in to turn off all locks.
+
+	\param modifiers A bitmap of lock keys to set.
+*/

docs/user/interface/Screen.dox

@@ -0,0 +1,640 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT Licence.
+ *
+ * Documentation by:
+ *		Stefano Ceccherini, [email protected]
+ *		Axel Dörfler, [email protected]
+ *		John Scipione, [email protected]
+ * Corresponds to:
+ *		/trunk/headers/os/interface/Screen.h	 rev 42759
+ *		/trunk/src/kits/interface/Screen.cpp	 rev 42759
+ */
+
+
+/*!
+	\file Screen.h
+	\brief Defines the BScreen class and support structures.
+*/
+
+
+/*!
+	\class BScreen
+	\ingroup interface
+	\brief The BScreen class provides methods to retrieve and change display
+		settings.
+
+	Each BScreen object describes one display connected to the computer.
+	Multiple BScreen objects can represent the same physical display.
+
+	\attention Haiku currently supports only a single display. The main
+	screen with id \c B_MAIN_SCREEN_ID contains the origin in its top left
+	corner. Additional displays, when they become supported, will extend
+	the coordinates of the main screen.
+
+	Some utility methods provided by this class are ColorSpace() to get the
+	color space of the screen, Frame() to get the frame rectangle, and ID()
+	to get the identifier of the screen.
+
+	Methods to convert between 8-bit and 32-bit colors are provided by
+	IndexForColor() and ColorForIndex().
+
+	You can also use this class to take a screenshot of the entire screen or
+	a particular portion of it. To take a screenshot use either the GetBitmap()
+	or ReadBitmap() method.
+
+	Furthermore, you can use this class get and set the background color of a
+	workspace. To get the background color call DesktopColor() or to set the
+	background color use SetDesktopColor().
+
+	This class provides methods to get and set the resolution, pixel depth,
+	and color map of a display. To get a list of the display modes supported
+	by the graphics card use the GetModeList() method. You can get and set
+	the screen resolution by calling the GetMode() and SetMode() methods.
+	The color map of the display can be retrieved by calling the ColorMap()
+	method.
+
+	You can use this class to get information about the graphics card and
+	monitor connected to the computer by calling the GetDeviceInfo() and
+	GetMonitorInfo() methods.
+
+	VESA Display Power Management Signaling support allow you to put the
+	monitor into a low-power mode. Call DPMSCapabilites() to check what
+	modes are supported by your monitor. DPMSState() tells you what state
+	your monitor is currently in and SetDPMS() allows you to change it.
+*/
+
+
+/*!
+	\fn BScreen::BScreen(screen_id id)
+	\brief Creates a BScreen object which represents the display
+	 	connected to the computer with the given screen_id.
+
+	In the current implementation, there is only one display
+	(\c B_MAIN_SCREEN_ID). To be sure that the object was constructed
+	correctly, call IsValid().
+
+	\param id The screen_id of the screen to create a BScreen object from.
+*/
+
+
+/*!
+	\fn BScreen::BScreen(BWindow* window)
+	\brief Creates a BScreen object which represents the display that
+		contains \a window.
+
+	In the current implementation, there is only one display
+	(\c B_MAIN_SCREEN_ID). To be sure that the object was constructed
+	correctly, call IsValid().
+
+	\param window A BWindow object.
+*/
+
+
+/*!
+	\fn BScreen::~BScreen()
+	\brief Frees the resources used by the BScreen object and unlocks the
+		screen.
+
+	\note The main screen object will never go away, even if you disconnect
+		all monitors.
+*/
+
+
+/*!
+	\name Utility Methods
+*/
+
+
+//! @{
+
+
+/*! 
+	\fn bool BScreen::IsValid()
+	\brief Checks that the BScreen object represents a real display that is
+		connected to the computer.
+
+	\return \c true if the BScreen object is valid, \c false otherwise.
+*/
+
+
+/*!
+	\fn status_t BScreen::SetToNext()
+	\brief Sets the BScreen object to the next display in the screen list.
+
+	\return \c B_OK if successful, otherwise \c B_ERROR.
+*/
+
+
+/*!	\fn color_space BScreen::ColorSpace()
+	\brief Gets the color_space of the display.
+
+	\return \c B_CMAP8, \c B_RGB15, \c B_RGB32, or \c B_NO_COLOR_SPACE
+		if the BScreen object is invalid.
+*/
+
+
+/*!
+	\fn BRect BScreen::Frame()
+	\brief Gets the frame of the screen in the screen's coordinate system.
+
+	For example if the BScreen object points to the main screen with a
+	resolution of 1,366x768 then this method returns
+	BRect(0.0, 0.0, 1365.0, 767.0). If the BScreen object is invalid then
+	this method returns an empty rectangle i.e. BRect(0.0, 0.0, 0.0, 0.0)
+
+	You can set the frame programmatically by calling the SetMode() method.
+
+	\return a BRect frame of the screen in the screen's coordinate system.
+*/
+
+
+/*!
+	\fn screen_id BScreen::ID()
+	\brief Gets the identifier of the display.
+
+	In the current implementation this method returns \c B_MAIN_SCREEN_ID
+	even if the object is invalid.
+
+	\return A screen_id that identifies the screen.
+*/
+
+
+/*!
+	\fn status_t BScreen::WaitForRetrace()
+	\brief Blocks until the monitor has finished its current vertical retrace.
+
+	\return \c B_OK or \c B_ERROR if the screen object is invalid.
+*/
+
+
+/*!
+	\fn status_t BScreen::WaitForRetrace(bigtime_t timeout)
+	\brief Blocks until the monitor has finished its current vertical retrace
+		or until \a timeout has expired.
+
+	\param timeout The amount of time to wait before returning.
+
+	\return \c B_OK if the monitor has retraced in the given \a timeout
+		duration, \c B_ERROR otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Color Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn inline uint8 BScreen::IndexForColor(rgb_color color)
+	\brief Gets the 8-bit color index that most closely matches a
+		32-bit \a color.
+
+	\param color The 32-bit \a color to get the 8-bit index of.
+
+	\return An 8-bit color index in the screen's color_map.
+*/
+
+
+/*!
+	\fn uint8 BScreen::IndexForColor(uint8 red, uint8 green, uint8 blue,
+									 uint8 alpha)
+	\brief Gets the 8-bit color index that most closely matches a set of
+		\a red, \a green, \a blue, and \a alpha values.
+
+	\param red The \a red value.
+	\param green The \a green value.
+	\param blue The \a blue value.
+	\param alpha The \a alpha value.
+
+	\return An 8-bit color index in the screen's color_map.
+*/
+
+
+/*!
+	\fn rgb_color BScreen::ColorForIndex(const uint8 index)
+	\brief Gets the 32-bit color representation of an 8-bit color \a index.
+
+	\param index The 8-bit color \a index to convert to a 32-bit color.
+
+	\return A 32-bit rgb_color structure.
+*/
+
+
+/*!
+	\fn uint8 BScreen::InvertIndex(uint8 index)
+	\brief Gets the "Inversion" of an 8-bit color \a index.
+
+	Inverted colors are useful for highlighting.
+
+	\param index The 8-bit color \a index.
+
+	\return An 8-bit color \a index that represents the "Inversion" of the
+		given color in the screen's color_map.
+*/
+
+
+/*!
+	\fn const color_map* BScreen::ColorMap()
+	\brief Gets the color_map of the BScreen.
+
+	\return A pointer to the BScreen object's color_map.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Bitmap Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BScreen::GetBitmap(BBitmap** _bitmap, bool drawCursor,
+									BRect* bounds)
+	\brief Allocates a BBitmap and copies the contents of the screen into it.
+
+	\note GetBitmap() will allocate a BBitmap object for you while
+		ReadBitmap() requires you to pre-allocate a BBitmap object first.
+
+	\note The caller is responsible for freeing the BBitmap object.
+
+	\param _bitmap A pointer to a BBitmap pointer where this method will
+		store the contents of the display.
+	\param drawCursor Specifies whether or not to draw the cursor.
+	\param bounds Specifies the screen area that you want copied. If
+		\a bounds is \c NULL then the entire screen is copied.
+
+	\return \c B_OK if the operation was successful, \c B_ERROR otherwise.
+*/
+
+
+/*!
+	\fn status_t BScreen::ReadBitmap(BBitmap* bitmap, bool drawCursor,
+									 BRect* bounds)
+	\brief Copies the contents of the screen into a BBitmap.
+
+	\note ReadBitmap() requires you to pre-allocate a BBitmap object first,
+		while GetBitmap() will allocate a BBitmap object for you.
+
+	\param bitmap A pointer to a pre-allocated BBitmap where this
+		method will store the contents of the display.
+	\param drawCursor Specifies whether or not to draw the cursor.
+	\param bounds Specifies the screen area that you want copied. If
+		\a bounds is \c NULL then the entire screen is copied.
+
+	\return \c B_OK if the operation was successful, \c B_ERROR otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Desktop Color Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn rgb_color BScreen::DesktopColor()
+	\brief Gets the background color of the current workspace.
+
+	\return A 32-bit rgb_color structure containing the background color
+		of the current workspace.
+*/
+
+
+/*!
+	\fn rgb_color BScreen::DesktopColor(uint32 workspace)
+	\brief Gets the background color of the specified \a workspace.
+
+	\param workspace The \a workspace index to get the desktop background
+		color of.
+
+	\return An 32-bit rgb_color structure containing the background color
+		of the specified \a workspace.
+*/
+
+
+/*!
+	\fn void BScreen::SetDesktopColor(rgb_color color, bool stick)
+	\brief Set the background \a color of the current workspace.
+
+	\param color The 32-bit \a color to paint the desktop background.
+	\param stick Whether or not the \a color will stay after a reboot.
+*/
+
+
+/*!
+	\fn void BScreen::SetDesktopColor(rgb_color color, uint32 workspace,
+									  bool stick)
+	\brief Set the background \a color of the specified \a workspace.
+
+	\param color The 32-bit \a color to paint the desktop background.
+	\param workspace The \a workspace index to update.
+	\param stick Whether or not the \a color will stay after a reboot.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Display Mode Methods
+
+	The following methods retrieve and alter the display_mode structure
+	of a screen. The display_mode structure contains screen size,
+	pixel depth, and display timings settings.
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BScreen::ProposeMode(display_mode* target,
+									  const display_mode* low,
+									  const display_mode* high)
+	\brief Adjust the \a target mode to make it a supported mode.
+
+	The list of supported modes for the graphics card is supplied by
+	the GetModeList() method.
+
+	\param target The mode you want adjust.
+	\param low The lower display mode limit.
+	\param high The higher display mode limit.
+
+	\retval B_OK if \a target is supported and falls within the
+		\a low and \a high limits.
+	\retval B_BAD_VALUE if \a target is supported but does not
+		fall within the \a low and \a high limits.
+	\retval B_ERROR if the target mode isn't supported.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetModeList(display_mode** _modeList, uint32* _count)
+	\brief Allocates and returns a list of the display modes supported by the
+		graphics card into \a _modeList.
+
+	\warning The monitor may not be able to display all of the modes that
+		GetModeList() retrieves.
+
+	\note The caller is responsible for freeing the display_mode object.
+
+	\param _modeList A pointer to a display_mode pointer, where the function
+		will allocate an array of display_mode structures.
+	\param _count A pointer to an integer used to store the count of
+		available display modes.
+
+	\retval B_OK if the operation was successful.
+	\retval B_ERROR if \a modeList or \a count is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetMode(display_mode* mode)
+	\brief Fills out the display_mode struct from the current workspace.
+
+	\param mode A pointer to a display_mode struct to copy into.
+
+	\retval B_OK if the operation was successful.
+	\retval B_BAD_VALUE if \a mode is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetMode(uint32 workspace, display_mode* mode)
+	\brief Fills out the display_mode struct from the specified
+		\a workspace.
+
+	\param workspace The index of the \a workspace to query.
+	\param mode A pointer to a display_mode structure to copy into.
+
+	\retval B_OK if the operation was successful
+	\retval B_BAD_VALUE if \a mode is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::SetMode(display_mode* mode, bool makeDefault)
+	\brief Sets the screen in the current workspace to the given \a mode.
+
+	\param mode A pointer to a display_mode struct.
+	\param makeDefault Whether or not \a mode is set as the default.
+
+	\return \c B_OK if the operation was successful, \c B_ERROR otherwise.
+*/
+
+
+/*!
+	\fn status_t BScreen::SetMode(uint32 workspace, display_mode* mode,
+								  bool makeDefault)
+	\brief Set the screen in the specified \a workspace to the given \a mode.
+
+	\param workspace The index of the workspace to set the \a mode of.
+	\param mode A pointer to a display_mode struct.
+	\param makeDefault Whether or not the \a mode is set as the default
+		for the specified \a workspace.
+
+	\return \c B_OK if the operation was successful, \c B_ERROR otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Display and Graphics Card Info Methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BScreen::GetDeviceInfo(accelerant_device_info* info)
+	\brief Fills out the \a info struct with information about a graphics card.
+
+	\param info An accelerant_device_info struct to store the device
+		\a info.
+
+	\retval B_OK if the operation was successful.
+	\retval B_BAD_VALUE if \a info is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetMonitorInfo(monitor_info* info)
+	\brief Fills out the \a info struct with information about a monitor.
+
+	\param info A monitor_info struct to store the monitor \a info.
+
+	\retval B_OK if the operation was successful.
+	\retval B_BAD_VALUE if \a info is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetPixelClockLimits(display_mode* mode,
+											  uint32* _low, uint32* _high)
+	\brief Gets the minimum and maximum pixel clock rates that are possible
+		for the specified \a mode.
+
+	\param mode A pointer to a display_mode structure.
+	\param _low A pointer to a uint32 where the method stores the lowest
+		available pixel clock.
+	\param _high A pointer to a uint32 where the method stores the highest
+		available pixel clock.
+
+	\retval B_OK if the operation was successful.
+	\retval B_BAD_VALUE if \a mode, \a low, or \a high is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+/*!
+	\fn status_t BScreen::GetTimingConstraints(display_timing_constraints*
+											   constraints)
+	\brief Fills out the \a constraints structure with the timing constraints
+		of the current display mode.
+
+	\param constraints A pointer to a display_timing_constraints structure
+		to store the timing constraints.
+
+	\retval B_OK if the operation was successful.
+	\retval B_BAD_VALUE if \a constraints is invalid.
+	\retval B_ERROR for all other errors.
+*/
+
+
+//! @}
+
+
+/*!
+	\name VESA Display Power Management Signaling Settings
+
+	VESA Display Power Management Signaling (or DPMS) is a standard from the
+	VESA consortium for managing the power usage of displays through the
+	graphics card. DPMS allows you to shut off the display after the computer
+	has been unused for some time to save power.
+
+	DPMS states include:
+		- \c B_DPMS_ON Normal display operation.
+		- \c B_DPMS_STAND_BY Image not visible normal operation and returns to
+			normal after ~1 second.
+		- \c B_DPMS_SUSPEND Image not visible, returns to normal after ~5
+			seconds.
+		- \c B_DPMS_OFF Image not visible, display is off except for power to
+			monitoring circuitry. Returns to normal after ~8-20 seconds.
+
+	Power usage in each of the above states depends on the monitor used. CRT
+	monitors typically receive larger power savings than LCD monitors in
+	low-power states.
+*/
+
+
+//! @{
+
+
+/*!
+	\fn status_t BScreen::SetDPMS(uint32 dpmsState)
+	\brief Sets the VESA Display Power Management Signaling (DPMS) state for
+		the display.
+
+	\param dpmsState The DPMS state to set.
+		valid values are:
+		- \c B_DPMS_ON
+		- \c B_DPMS_STAND_BY
+		- \c B_DPMS_SUSPEND
+		- \c B_DPMS_OFF
+
+	\return \c B_OK if the operation was successful, otherwise an error code.
+*/
+
+
+/*!
+	\fn uint32 BScreen::DPMSState()
+	\brief Gets the current VESA Display Power Management Signaling (DPMS)
+		state of the screen.
+
+	\return The current VESA Display Power Management Signaling (DPMS) state
+		of the display or 0 in the case of an error.
+*/
+
+
+
+/*!
+	\fn uint32 BScreen::DPMSCapabilites()
+	\brief Gets the VESA Display Power Management Signaling (DPMS)
+		modes that the display supports as a bit mask.
+
+	- \c B_DPMS_ON is worth 1
+	- \c B_DPMS_STAND_BY is worth 2
+	- \c B_DPMS_SUSPEND is worth 4
+	- \c B_DPMS_OFF is worth 8
+
+	\return A bit mask of the VESA Display Power Management Signaling (DPMS)
+		modes that the display supports or 0 in the case of an error.
+*/
+
+
+//! @}
+
+
+/*!
+	\name Deprecated methods
+*/
+
+
+//! @{
+
+
+/*!
+	\fn BPrivate::BPrivateScreen* BScreen::private_screen()
+	\brief Returns the BPrivateScreen used by the BScreen object.
+
+	\return A pointer to the BPrivateScreen class internally used by the BScreen
+		object.
+*/
+
+
+/*!
+	\fn status_t BScreen::ProposeDisplayMode(display_mode* target,
+											 const display_mode* low,
+											 const display_mode* high)
+	\brief Deprecated, use ProposeMode() instead.
+*/
+
+
+/*!
+	\fn void* BScreen::BaseAddress()
+	\brief Returns the base address of the frame buffer.
+*/
+
+
+/*!
+	\fn uint32 BScreen::BytesPerRow()
+	\brief Returns the bytes per row of the frame buffer.
+*/
+
+
+//! @}

docs/user/interface/View.dox

@@ -0,0 +1,297 @@
+/*
+ * Copyright 2011, Haiku inc.
+ * Distributed under the terms of the MIT License.
+ *
+ * Documentation by:
+ *		John Scipione, [email protected]
+ * Corresponds to:
+ *		/trunk/headers/os/interface/View.h	 rev 42794
+ *		/trunk/src/kits/interface/View.cpp	 rev 42794
+ */
+
+
+/*!
+	\file View.h
+	\brief BView class definition and support enums.
+*/
+
+
+/*!
+	\class BView
+	\ingroup interface
+	\ingroup libbe
+
+	\brief View base class.
+*/
+
+
+/*!
+	\fn void BView::AttachedToWindow()
+	\brief Hook method that is called when the object is attached to a
+		window.
+*/
+
+
+/*!
+	\fn void BView::AllAttached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+		all child views have already been attached to a window.
+*/
+
+
+/*!
+	\fn void BView::DetachedFromWindow()
+	\brief Hook method that is called when the object is detached from a
+		window.
+*/
+
+/*!
+	\fn void BView::AllDetached()
+	\brief Similar to AttachedToWindow() but this method is triggered after
+		all child views have already been detached from a window.
+*/
+
+/*!
+	\fn void BView::Draw(BRect updateRect)
+	\brief Draws the area of the view that intersects \a updateRect.
+
+	Derived classes should override this method to draw their view.
+
+	\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 view
+	consider calling Invalidate() instead.
+
+	\param updateRect The rectangular area to be drawn.
+*/
+
+
+/*!
+	\fn void BView::DrawAfterChildren(BRect r)
+	\brief Perform any drawing that needs to be done after child view have
+		already been drawn.
+
+	\param r The rectangular area to be drawn.
+*/
+
+
+/*!
+	\fn void BView::FrameMoved(BPoint newPosition)
+	\brief Hook method that gets called when the view is moved.
+
+	\param newPosition The point of the top left corner of the frame
+		that the view has been moved to.
+*/
+
+
+/*!
+	\fn void BView::FrameResized(float newWidth, float newHeight)
+	\brief Hook method that gets called when the view is resized.
+
+	\param newWidth The new \a width of the view.
+	\param newHeight The new \a height of the view.
+*/
+
+
+/*!
+	\fn void BView::GetPreferredSize(float* _width, float* _height)
+	\brief Fill out the preferred width and height of the view
+		into the \a _width and \a _height parameters.
+
+	Derived classes should override this method to set the preferred
+	size of object.
+
+	\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 of the view.
+	\param[out] _height Pointer to a \c float to store the height of the view.
+*/
+
+
+/*!
+	\fn void BView::ResizeToPreferred()
+	\brief Resize the view to its preferred size.
+*/
+
+
+/*!
+	\fn void BView::KeyDown(const char* bytes, int32 numBytes)
+	\brief Hook method that is called when a keyboard key is pressed.
+
+	\param bytes The bytes of the key combination pressed.
+	\param numBytes The number of bytes in \a bytes.
+*/
+
+
+/*!
+	\fn void BView::KeyUp(const char* bytes, int32 numBytes)
+	\brief Hook method that is called when a keyboard key is released.
+
+	\param bytes The bytes of the key combination pressed.
+	\param numBytes The number of bytes in \a bytes.
+*/
+
+
+/*!
+	\fn void BView::MouseDown(BPoint where)
+	\brief Hook method that is called when a mouse button is pressed.
+
+	\param where The point on the screen where to mouse pointer is when
+		the mouse button is pressed.
+*/
+
+
+/*!
+	\fn void BView::MouseUp(BPoint where)
+	\brief Hook method that is called when a mouse button is released.
+
+	\param where The point on the screen where to mouse pointer is when
+		the mouse button is released.
+*/
+
+
+/*!
+	\fn void BView::MouseMoved(BPoint where, uint32 code,
+		const BMessage* a_message)
+	\brief Hook method that is called when the mouse is moved.
+*/
+
+
+/*!
+	\fn void BView::Pulse()
+	\brief Hook method that gets invoked when the view receives a
+		\c B_PULSE message.
+
+	An action is performed each time the 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 BView::WindowActivated(bool state)
+	\brief Hook method that is called when the attached window becomes
+		activated or deactivated.
+
+	\param state \c true if the window becomes activated, \c false if the
+		window becomes deactivated.
+*/
+
+
+/*!
+	\fn void BView::MakeFocus(bool focusState)
+	\brief Gives or removes focus from the control.
+
+	\param focusState \a true to set focus, \a false to remove it.
+*/
+
+
+/*!
+	\fn status_t BView::Perform(perform_code code, void* _data)
+	\brief Perform some action. (Internal Method)
+
+	The following perform codes are recognized:
+		- \c PERFORM_CODE_MIN_SIZE:
+		- \c PERFORM_CODE_MAX_SIZE:
+		- \c PERFORM_CODE_PREFERRED_SIZE:
+		- \c PERFORM_CODE_LAYOUT_ALIGNMENT:
+		- \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH:
+		- \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH:
+		- \c PERFORM_CODE_SET_LAYOUT:
+		- \c PERFORM_CODE_INVALIDATE_LAYOUT:
+		- \c PERFORM_CODE_DO_LAYOUT:
+		- \c PERFORM_CODE_GET_TOOL_TIP_AT:
+		- \c PERFORM_CODE_ALL_UNARCHIVED:
+		- \c PERFORM_CODE_ALL_ARCHIVED:
+
+	\param code The perform code.
+	\param _data A pointer to store some data.
+
+	\returns A status code.
+
+	\sa BHandler::Perform()
+*/
+
+
+/*!
+	\fn BSize BView::MinSize()
+	\brief Get the minimum size of the view.
+
+	\return The minimum size of the view as a BSize.
+
+	\sa BAbstractLayout::MinSize()
+*/
+
+
+/*!
+	\fn BSize BView::MaxSize()
+	\brief Get the maximum size of the view.
+
+	\return The maximum size of the view as a BSize.
+
+	\sa BAbstractLayout::MaxSize()
+*/
+
+
+/*!
+	\fn BSize BView::PreferredSize()
+	\brief Get the preferred size of the view.
+
+	\return The preferred size of the view as a BSize.
+
+	\sa BAbstractLayout::PreferredSize()
+*/
+
+
+/*!
+	\fn void BView::SetExplicitMinSize(BSize size)
+	\brief Set this item's explicit min size, to be used by MinSize().
+
+	\sa BAbstractLayout::SetExplicitMinSize()
+*/
+
+
+/*!
+	\fn void BView::SetExplicitMaxSize(BSize size)
+	\brief Set this item's explicit max size, to be used by MaxSize().
+
+	\sa BAbstractLayout::SetExplicitMaxSize()
+*/
+
+
+/*!
+	\fn void BView::SetExplicitPreferredSize(BSize size)
+	\brief Set this item's explicit preferred size, to be used by
+		PreferredSize().
+
+	\sa BAbstractLayout::SetExplicitPreferredSize()
+*/
+
+
+/*!
+	\fn void BView::SetExplicitAlignment(BAlignment alignment)
+	\brief Set this item's explicit alignment, to be used by Alignment().
+
+	\sa BAbstractLayout::SetExplicitAlignment()
+*/
+
+
+/*!
+	\fn void BView::SetLayout(BLayout* layout)
+	\brief Set the \a layout of the view.
+
+	\param layout The \a layout to set.
+*/
+
+
+/*!
+	\fn BLayout* BView::GetLayout() const
+	\brief Get the layout of the view.
+
+	\returns The layout of the view.
+*/
+
+