Update the style of the Haiku Book to resemble the User Guide.
If you have never seen this before you are in for a bit of a shock. Update the Doxyfile to 1.7.3 (the version that gets auto-generated). Update the book.dox front page with some nice introductory text. Add new documentation for the following classes: BCheckBox BClipboard BColorControl BControl BEntryList BView (preliminary) Remove redundant documentation from src/kits/storage/EntryList.cpp Minor documentation update for the following classes: BAlert BApplication BArchivable BBox BButton BCatalog BFindDirectory BHandler BUnarchiver BString git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@43096 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
John Scipione
+137
-126
@@ -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.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user