new operator, on the stack, or as globals. Nor can you
+ delete them. Instead, these objects are obtained through
+ BMidiRoster. The only two exceptions to this rule are BMidiLocalConsumer
+ and BMidiLocalProducer. These two objects may be directly created and
+ subclassed by developers.
+
+ \section midi2refcount Reference Counting
+
+ Each MIDI endpoint has a reference count associated with it, so that
+ the Midi Roster can do proper bookkeeping. When you construct a
+ BMidiLocalProducer or BMidiLocalConsumer endpoint, it starts with a
+ reference count of 1. In addition, BMidiRoster increments the reference
+ count of any object it hands to you as a result of
+ \link BMidiRoster::NextEndpoint() NextEndpoint() \endlink or
+ \link BMidiRoster::FindEndpoint() FindEndpoint() \endlink.
+ Once the count hits 0, the endpoint will be deleted.
+
+ This means that, to delete an endpoint, you don't call the
+ delete operator directly; instead, you call
+ \link BMidiEndpoint::Release() Release() \endlink.
+ To balance this call, there's also an
+ \link BMidiEndpoint::Acquire() Acquire() \endlink, in case you have two
+ disparate parts of your application working with the endpoint, and you
+ don't want to have to keep track of who needs to Release() the endpoint.
+
+ When you're done with any endpoint object, you must Release() it.
+ This is true for both local and remote objects. Repeat after me:
+ Release() when you're done.
+
+ \section midi2events MIDI Events
+
+ To make some actual music, you need to
+ \link BMidiProducer::Connect() Connect() \endlink your consumers to
+ your producers. Then you tell the producer to "spray" MIDI events to all
+ the connected consumers. The consumers are notified of these incoming
+ events through a set of hook functions.
+
+ The Midi Kit already provides a set of commonly used spray functions,
+ such as \link BMidiLocalProducer::SprayNoteOn() SprayNoteOn() \endlink,
+ \link BMidiLocalProducer::SprayControlChange() SprayControlChange()
+ \endlink, and so on. These correspond one-to-one with the message types
+ from the MIDI spec. You don't need to be a MIDI expert to use the kit, but
+ of course some knowledge of the protocol helps. If you are really hardcore,
+ you can also use the
+ \link BMidiLocalProducer::SprayData() SprayData() \endlink to send raw MIDI
+ events to the consumers.
+
+ At the consumer side, a dedicated thread invokes a hook function for every
+ incoming MIDI event. For every spray function, there is a corresponding hook
+ function, e.g. \link BMidiLocalConsumer::NoteOn() NoteOn() \endlink and
+ \link BMidiLocalConsumer::ControlChange() ControlChange() \endlink.
+ The hardcore MIDI fanatics among you will be pleased to know that you can
+ also tap into the \link BMidiLocalConsumer::Data() Data() \endlink hook and
+ get your hands dirty with the raw MIDI data.
+
+ \section midi2time Time
+
+ The spray and hook functions accept a bigtime_t parameter named "time". This
+ indicates when the MIDI event should be performed. The time is given in
+ microseconds since the computer booted. To get the current tick measurement,
+ you call the system_time() function from the Kernel Kit.
+
+ If you override a hook function in one of your consumer objects, it should
+ look at the time argument, wait until the designated time, and then perform
+ its action. The preferred method is to use the Kernel Kit's
+ snooze_until() function, which sends the consumer thread to
+ sleep until the requested time has come. (Or, if the time has already
+ passed, returns immediately.)
+
+ Like this:
+
+ \code
+void MyConsumer::NoteOn(
+ uchar channel, uchar note, uchar velocity, bigtime_t time)
+{
+ snooze_until(time, B_SYSTEM_TIMEBASE);
+ ...do your thing...
+}
+ \endcode
+
+ If you want your producers to run in real time, i.e. they produce MIDI data
+ that needs to be performed immediately, you should pass time 0 to the spray
+ functions (which also happens to be the default value). Since time 0 has
+ already passed, snooze_until() returns immediately, and the
+ consumer will process the events as soon as they are received.
+
+ To schedule MIDI events for a performance time that lies somewhere in the
+ future, the producer must take into account the consumer's latency.
+ Producers should attempt to get notes to the consumer by or before
+ (scheduled_performance_time - latency). The time argument is still
+ the scheduled performance time, so if your consumer has latency, it should
+ snooze like this before it starts to perform the events:
+
+ \code
+snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
+ \endcode
+
+ Note that a typical producer sends out its events as soon as it can;
+ unlike a consumer, it does not have to snooze.
+
+ \section midi2ports Other Timing Issues
+
+ Each consumer object uses a Kernel Kit port to receive MIDI events from
+ connected producers. The queue for this port is only 1 message deep.
+ This means that if the consumer thread is asleep in a
+ snooze_until(), it will not read its port. Consequently,
+ any producer that tries to write a new event to this port will block until
+ the consumer thread is ready to receive a new message. This is intentional,
+ because it prevents producers from generating and queueing up thousands of
+ events.
+
+ This mechanism, while simple, puts on the producer the responsibility
+ for sorting the events in time. Suppose your producer sends three Note
+ On events, the first on t + 0, the second on t + 4, and the third on t + 2.
+ This last event won't be received until after t + 4, so it will be two ticks
+ too late. If this sort of thing can happen with your producer, you should
+ somehow sort the events before you spray them. Of course, if you have two or
+ more producers connected to the same consumer, it is nearly impossible to
+ sort this all out (pardon the pun). So it is not wise to send the same kinds
+ of events from more than one producer to one consumer at the same time.
+
+ The article Introduction to MIDI, Part 2 in OpenBeOS
+ Newsletter 36 describes this problem in more detail, and provides a
+ solution. Go read it now!
+
+ \section midi2filters Writing a Filter
+
+ A typical filter contains a consumer and a producer endpoint. It receives
+ events from the consumer, processes them, and sends them out again using the
+ producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas
+ the producer is simply a BMidiLocalProducer, not a subclass. This is a
+ common configuration, because consumers work by overriding the event hooks
+ to do work when MIDI data arrives. Producers work by sending an event when
+ you call their member functions. You should hardly ever need to derive from
+ BMidiLocalProducer (unless you need to know when the producer gets connected
+ or disconnected, perhaps), but you'll always have to override one or more of
+ BMidiLocalConsumer's member functions to do something useful with incoming
+ data.
+
+ Filters should ignore the time argument from the spray and hook functions,
+ and simply pass it on unchanged. Objects that only filter data should
+ process the event as quickly as possible and be done with it. Do not
+ snooze_until() in the consumer endpoint of a filter!
+
+ \section midi2apidiffs API Differences
+
+ As far as the end user is concerned, the Haiku Midi Kit is mostly the same
+ as the BeOS R5 kits, although there are a few small differences in the API
+ (mostly bug fixes):
+ - BMidiEndpoint::IsPersistent() always returns false.
+ - The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be
+ kit incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the
+ rest of the message was properly structured.
+ - If creating a local endpoint fails, you can still Release() the object
+ without crashing into the debugger.
+
+ \section midi2seealso See also
+
+ More about the Midi Kit:
+ - \ref Midi2Defs.h
+ - Be Newsletter Volume 3, Issue 47 - Motor Mix sample code
+ - Be Newsletter Volume 4, Issue 3 - Overview of the new kit
+ - Newsletter
+ 33, Introduction to MIDI, Part 1
+ - Newsletter
+ 36, Introduction to MIDI, Part 2
+ - Sample code and other goodies at the
+ Haiku Midi Kit team page
+
+ Information about MIDI in general:
+ - MIDI Manufacturers Association
+ - MIDI Tutorials
+ - MIDI Specification
+ - Standard MIDI File Format
+ - Jim Menard's MIDI Reference
+
+
+ \defgroup libmidi2 (libmidi2.so)
+
+
+ \defgroup storage Storage Kit
+ \brief Collection of classes that deal with storing and retrieving
+ information from disk.
+
+
+ \defgroup support Support Kit
+ \brief Collection of utility classes that are used throughout the API.
+
+ The Support Kit provides a handy set of classes that you can use in your
+ applications. These classes provide:
+ - \b Thread \b Safety. Haiku can execute multiple threads of an
+ application in parallel, letting certain parts of an application
+ continue when one part is stalled, as well as letting an application
+ process multiple pieces of data at the same time on multicore or
+ multiprocessor systems. However, there are times when multiple
+ threads desire to work on the same piece of data at the same time,
+ potentially causing a conflict where variables or pointers are
+ changed by one thread causing another to execute incorrectly. To
+ prevent this, Haiku implements a \"locking\" mechanism, allowing one
+ thread to \"lock out\" other threads from executing code that might
+ modify the same data.
+ - \b Archiving \b and \b IO. These classes allow a programmer to
+ convert objects into a form that can more easily be transferred to
+ other applications or stored to disk, as well as performing basic
+ input and output operations.
+ - \b Memory \b Allocation. This class allows a programmer to hand off
+ some of the duties of memory accounting and management.
+ - \b Common \b Datatypes. To avoid unnecessary duplication of code
+ and to make life easier for programmers, Haiku includes classes that
+ handle management of ordered lists and strings.
+
+ There are also a number of utility functions to time actions, play system
+ alert sounds, compare strings, and atomically manipulate integers. Have a
+ look at the overview, or go straight to the complete
+ \link support list of components \endlink of this kit.
+
+ \section Overview
+ - Thread Safety:
+ - BLocker provides a semaphore-like locking mechanism allowing for
+ recursive locks.
+ - BAutolock provides a simple method of automatically removing a
+ lock when a function ends.
+ - \ref TLS.h "Thread Local Storage" allows a global variable\'s
+ content to be sensitive to thread context.
+ - Archiving and IO:
+ - BArchivable provides an interface for \"archiving\" objects so
+ that they may be sent to other applications where an identical
+ copy will be recreated.
+ - BArchiver simplifies archiving of BArchivable hierarchies.
+ - BUnarchiver simplifies unarchiving hierarchies that have been
+ archived using BArchiver.
+ - BFlattenable provides an interface for \"flattening\" objects so
+ that they may be easily stored to disk.
+ - BDataIO provides an interface for generalized read/write streams.
+ - BPositionIO extends BDataIO to allow seeking within the data.
+ - BBufferIO creates a buffer and attaches it to a BPositionIO
+ stream, allowing for reduced load on the underlying stream.
+ - BMemoryIO allows operation on an already-existing buffer.
+ - BMallocIO creates and allows operation on a buffer.
+ - Memory Allocation:
+ - BBlockCache allows an application to allocate a \"pool\" of
+ memory blocks that the application can fetch and dispose of as
+ it pleases, letting the application make only a few large memory
+ allocations, instead of many small expensive allocations.
+ - Common Datatypes:
+ - BList allows simple ordered lists and provides common access,
+ modification, and comparison functions.
+ - BString allows strings and provides common access, modification,
+ and comparison functions.
+ - BStopWatch allows an application to measure the time an action takes.
+ - \ref support_globals "Global functions"
+ - \ref TypeConstants.h "Common types and constants"
+ - Error codes for all kits
+
+
+ \defgroup libbe (libbe.so)
+
+
+ \defgroup libroot (libroot.so)
*/
///// Subgroups /////
/*!
- \defgroup support_globals Global functions in the support kit
- \ingroup support
+ \defgroup support_globals Global functions in the support kit
+ \ingroup support
- \defgroup layout Layout classes in the Interface Kit
- \ingroup interface
+ \defgroup layout Layout classes in the Interface Kit
+ \ingroup interface
*/
diff --git a/docs/user/header.html b/docs/user/header.html
index 2c0fe5b34d..277802f32e 100644
--- a/docs/user/header.html
+++ b/docs/user/header.html
@@ -6,7 +6,8 @@
-
- 
-
+ * John Scipione
* 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.
diff --git a/docs/user/interface/BCheckBox_example.png b/docs/user/interface/BCheckBox_example.png
new file mode 100644
index 0000000000..c8cec5240c
Binary files /dev/null and b/docs/user/interface/BCheckBox_example.png differ
diff --git a/docs/user/interface/BColorControl_example.png b/docs/user/interface/BColorControl_example.png
new file mode 100644
index 0000000000..664da1117d
Binary files /dev/null and b/docs/user/interface/BColorControl_example.png differ
diff --git a/docs/user/interface/BColorControl_example_256_colors.png b/docs/user/interface/BColorControl_example_256_colors.png
new file mode 100644
index 0000000000..a64e7f2007
Binary files /dev/null and b/docs/user/interface/BColorControl_example_256_colors.png differ
diff --git a/docs/user/interface/Box.dox b/docs/user/interface/Box.dox
index 8382b45f82..2c19b69482 100644
--- a/docs/user/interface/Box.dox
+++ b/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 const char* 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.
*/
diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox
index 5977c4e11e..6bcd7d7bba 100644
--- a/docs/user/interface/Button.dox
+++ b/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
+ * John Scipione, jscipione@gmail.com
* 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
*/
-
diff --git a/docs/user/interface/CheckBox.dox b/docs/user/interface/CheckBox.dox
new file mode 100644
index 0000000000..917a272730
--- /dev/null
+++ b/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, superstippi@gmx.de
+ * Marc Flerackers, mflerackers@androme.be
+ * John Scipione, jscipione@gmail.com
+ * 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()
+*/
diff --git a/docs/user/interface/ColorControl.dox b/docs/user/interface/ColorControl.dox
new file mode 100644
index 0000000000..8350e468a5
--- /dev/null
+++ b/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, jscipione@gmail.com
+ * 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()
+
+*/
diff --git a/docs/user/interface/Control.dox b/docs/user/interface/Control.dox
new file mode 100644
index 0000000000..c3575fe27a
--- /dev/null
+++ b/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, jscipione@gmail.com
+ * 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()
+*/
diff --git a/docs/user/interface/View.dox b/docs/user/interface/View.dox
new file mode 100644
index 0000000000..c8a81696b4
--- /dev/null
+++ b/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, jscipione@gmail.com
+ * 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.
+*/
+
+
diff --git a/docs/user/locale/Catalog.dox b/docs/user/locale/Catalog.dox
index c5e3f3208e..94d532e488 100644
--- a/docs/user/locale/Catalog.dox
+++ b/docs/user/locale/Catalog.dox
@@ -8,8 +8,8 @@
* Oliver Tappe, zooey@hirschkaefer.de
*
* Corresponds to:
- * /trunk/headers/os/locale/Catalog.h rev 42274
- * /trunk/src/kits/locale/Catalog.cpp rev 42274
+ * /trunk/headers/os/locale/Catalog.h rev 43095
+ * /trunk/src/kits/locale/Catalog.cpp rev 43095
*/
@@ -73,13 +73,9 @@
/*!
- \fn BCatalog::BCatalog(const char* signature, const char* language = NULL,
- uint32 fingerprint = 0)
- \brief Construct a catalog for the given application.
-
- This constructor builds a catalog for the application with the given mime
- signature. In Haiku, the mime signature is used as a way to uniquely
- identify a catalog and match it with the corresponding application.
+ \fn BCatalog::Catalog(const entry_ref& catalogOwner,
+ const char* language = NULL, uint32 fingerprint = 0);
+ \brief Construct a catalog for the given \a catalogOwner.
If you don't specify a language, the system default list will be used.
The language is passed here as a 2 letter ISO code.
@@ -92,9 +88,8 @@
different versions of your application, it may be useful to separate their
catalogs.
- \param signature Mime-signature of the application for which to load a
- catalog.
- \param language The language of the catalog to load. If NULL, the user
+ \param catalogOwner entry_ref for which to load a catalog.
+ \param language The language of the catalog to load. If \c NULL, the user
settings will be used.
\param fingerprint The fingerprint version-info for the catalog to load.
If \c 0, the fingerprint will not be checked,and any version of the
@@ -146,7 +141,7 @@
\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
\brief Get custom data from the catalog.
- This function allows you to localize something else than raw text. This
+ This method allows you to localize something else than raw text. This
may include pictures, sounds, videos, or anything else. Note there is no
support for generating a catalog with such data inside, and the current
format may not support it. If you need to localize data that is not text,
@@ -167,7 +162,7 @@
but is faster.
Note the current catalog format doesn't allow storing custom data in
- catalogs, so the only way to use this function is providing your own
+ catalogs, so the only way to use this method is providing your own
catalog add-on for storing the data.
*/
@@ -176,7 +171,7 @@
\fn status_t BCatalog::GetSignature(BString* sig)
\brief Get the catalog mime-signature.
- This function fills the sig string with the mime-signature associated to the
+ This method fills the sig string with the mime-signature associated to the
catalog.
\param sig The string where to copy the signature.
@@ -189,7 +184,7 @@
\fn status_t BCatalog::GetLanguage(BString* lang)
\brief Get the catalog language.
- This function fills the lang string with the language name for the catalog.
+ This method fills the lang string with the language name for the catalog.
\param lang The string where to copy the language.
@@ -201,7 +196,7 @@
\fn status_t BCatalog::GetFingerprint(uint32* fp)
\brief Get the catalog fingerprint.
- This function setsfp to the fingerprint of the catalog. This allows you
+ This method setsfp to the fingerprint of the catalog. This allows you
to check which version of the sourcecode this catalog was generated from.
\param fp The integer to set to the fingerprint value.
@@ -211,12 +206,13 @@
/*!
- \fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
+ \fn status_t BCatalog::SetCatalog(const entry_ref& catalogOwner,
+ uint32 fingerprint)
\brief Reload the string data.
- This function reloads the data for the given signature and fingerprint.
+ This method reloads the data for the given signature and fingerprint.
- \param signature The signature of the catalog youwant to load
+ \param catalogOwner The entry_ref of the catalog that you want to load.
\param fingerprint The fingerprint of the catalog you want to load.
\returns An error code.
diff --git a/docs/user/storage/EntryList.dox b/docs/user/storage/EntryList.dox
new file mode 100644
index 0000000000..323852984c
--- /dev/null
+++ b/docs/user/storage/EntryList.dox
@@ -0,0 +1,132 @@
+/*
+ * Copyright 2011, Haiku, Inc. All Rights Reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Erik Jaesler, ejakowatz@users.sourceforge.net
+ * John Scipione, jscipione@gmail.com
+ *
+ * Corresponds to:
+ * /trunk/headers/os/storage/EntryList.h rev 42794
+ * /trunk/src/kits/storage/EntryList.cpp rev 42794
+ */
+
+
+/*!
+ \file EntryList.h
+ \brief Defines the BEntryList class.
+*/
+
+
+/*!
+ \class BEntryList
+ \ingroup storage
+ \ingroup libbe
+ \brief Interface for iterating through a list of filesystem entries.
+
+ Defines a general interface for iterating through a list of entries
+ i.e. files in a folder.
+*/
+
+
+/*!
+ \fn BEntryList::BEntryList()
+ \brief Creates a BEntryList object.
+
+ Does nothing at this time.
+*/
+
+
+/*!
+ \fn BEntryList::~BEntryList()
+ \brief Frees all resources associated with the BEntryList object.
+
+ Does nothing at this time.
+*/
+
+
+/*!
+ \fn status_t BEntryList::GetNextEntry(BEntry *entry, bool traverse)
+ \brief Returns the BEntryList's next entry as a BEntry.
+
+ Places the next entry in the list in \a entry, traversing symlinks if
+ \a traverse is \c true.
+
+ \param entry a pointer to a BEntry to be initialized with the found entry.
+ \param traverse specifies whether to follow it, if the found entry
+ is a symbolic link.
+
+ \note The iterator used by this method is the same one used by
+ GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
+
+ \retval B_OK if successful
+ \retval B_ENTRY_NOT_FOUND when at the end of the list
+ \retval B_ERROR or another error code (depending on the implementation
+ of the derived class).
+*/
+
+
+/*!
+ \fn status_t BEntryList::GetNextRef(entry_ref *ref)
+ \brief Returns the BEntryList's next entry as an entry_ref.
+
+ Places an entry_ref to the next entry in the list into \a ref.
+
+ \param ref a pointer to an entry_ref to be filled in with the data of the
+ found entry.
+
+ \note The iterator used by this method is the same one used by
+ GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
+
+ \retval B_OK if successful
+ \retval B_ENTRY_NOT_FOUND when at the end of the list
+ \retval B_ERROR or another error code (depending on the implementation
+ of the derived class).
+*/
+
+
+/*!
+ \fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length,
+ int32 count)
+ \brief Returns the BEntryList's next entries as dirent structures.
+
+ Reads a number of entries into the array of dirent structures pointed
+ to by \a buf. Reads as many but no more than \a count entries, as many
+ entries as remain, or as many entries as will fit into the array at
+ \a buf with given length \a length (in bytes), whichever is smallest.
+
+ \param buf A pointer to a buffer to be filled with dirent structures of
+ the found entries.
+ \param length The length of the \a buf array.
+ \param count the maximum number of entries to be read.
+
+ \note The iterator used by this method is the same one used by
+ GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
+
+ \returns
+ - The number of dirent structures stored in the buffer or 0 when
+ there are no more entries to be read.
+ - an error code (depending on the implementation of the derived class)
+ if an error occurred.
+*/
+
+
+/*!
+ \fn status_t BEntryList::Rewind()
+ \brief Rewinds the list pointer to the beginning of the list.
+
+ \retval B_OK if successful
+ \retval B_ERROR or another error code (depending on the implementation
+ of the derived class).
+*/
+
+
+/*!
+ \fn int32 BEntryList::CountEntries()
+ \brief Returns the number of entries in the list
+
+ \retval B_OK if successful
+ \retval B_ENTRY_NOT_FOUND when at the end of the list
+ \retval B_ERROR or another error code (depending on the implementation
+ of the derived class).
+*/
\ No newline at end of file
diff --git a/docs/user/storage/FindDirectory.dox b/docs/user/storage/FindDirectory.dox
index f4754c93c1..b507e5a119 100644
--- a/docs/user/storage/FindDirectory.dox
+++ b/docs/user/storage/FindDirectory.dox
@@ -13,8 +13,8 @@
/*!
\file FindDirectory.h
\ingroup storage
- \brief Provides the find_dirctory function.
-
+ \brief Provides the find_directory function.
+
Haiku provides a set of directories for applications to use. These can be
accessed using the find_directory function. It is very important to use the
function at runtime and not hardcode the path, as it may change in future
@@ -26,6 +26,7 @@
in ported applications.
*/
+
/*!
\enum directory_which
\brief Directory constants to use with find_directory.
@@ -45,6 +46,7 @@
settings.
*/
+
/*!
\var directory_which B_DESKTOP_DIRECTORY
The desktop for a given volume.
@@ -162,6 +164,7 @@
\var directory_which B_UTILITIES_DIRECTORY
*/
+
/*!
\fn status_t find_directory(directory_which which, dev_t volume, bool createIt, char* pathString, int32 length)
\brief C interface to find_directory
@@ -171,6 +174,7 @@
set.
*/
+
/*!
\fn status_t find_directory(directory_which which, BPath* path, bool createIt = false, BVolume* volume = NULL)
\brief C++ interface to find_directory
diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox
index b47ce04c8d..bb3f0b2c91 100644
--- a/docs/user/support/Archivable.dox
+++ b/docs/user/support/Archivable.dox
@@ -63,7 +63,8 @@
*/
-/*! \fn BArchivable::BArchivable(BMessage* from)
+/*!
+ \fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does important behind-the-scenes work in the unarchiving
process.
@@ -74,17 +75,20 @@
*/
-/*! \fn BArchivable::BArchivable()
+/*!
+ \fn BArchivable::BArchivable()
\brief Constructor. Does nothing.
*/
-/*! \fn BArchivable::~BArchivable()
+/*!
+ \fn BArchivable::~BArchivable()
\brief Destructor. Does nothing.
*/
-/*! \fn virtual status_t BArchivable::Archive(BMessage* into,
+/*!
+ \fn virtual status_t BArchivable::Archive(BMessage* into,
bool deep = true) const
\brief Archive the object into a BMessage.
@@ -94,20 +98,23 @@
\param into The message you store your object in.
\param deep If \c true, all children of this object should be archived as
well.
- \retval B_OK The archiving succeeded.
- \retval "error codes" The archiving did not succeed.
+
+ \retval B_OK The archive operation was successful.
+ \retval B_BAD_VALUE \c NULL \a archive message.
+ \retval B_ERROR The archive operation failed.
*/
-/*! \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
+/*!
+ \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
\brief Static member to restore objects from messages.
-
+
You should always check that the \a archive argument actually corresponds to
your class. The automatic functions, such as #instantiate_object() and
BUnarchiver::InstantiateObject() will not choose the wrong class but manual
calls to this member might be faulty. You can verify that \c archive
stores an object of your calss with the validate_instantiation() function.
-
+
\param archive The message with the data of the object to restore.
\retval You should return a pointer to the object you create with
\c archive, or \c NULL if unarchival fails.
@@ -120,15 +127,24 @@
*/
-/*! \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
- \brief Internal method defined for binary compatibility purposes.
+/*!
+ \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
+ \brief Perform some action (Internal method defined for binary
+ compatibility purposes).
+
\internal This method is defined for binary compatibility purposes, it is
used to ensure that the correct AllUnarchived() and AllArchived()
methods are called for objects, as those methods are new to Haiku.
+
+ \param d The perform code.
+ \param arg A pointer to store some data.
+
+ \returns A status code.
*/
-/*! \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
+/*!
+ \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
\brief Method relating to the use of \c BUnarchiver.
This hook function is called triggered in the BUnarchiver::Finish() method.
@@ -180,7 +196,8 @@
*/
-/*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
+/*!
+ \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\brief Instantiate an archived object with the object being defined in a
different application or library.
@@ -194,7 +211,8 @@
*/
-/*! \fn BArchivable* instantiate_object(BMessage *from)
+/*!
+ \fn BArchivable* instantiate_object(BMessage *from)
\brief Instantiate an archived object.
This global function will determine the base class, based on the \a from
@@ -209,26 +227,30 @@
*/
-/*! \fn bool validate_instantiation(BMessage* from, const char* className)
+/*!
+ \fn bool validate_instantiation(BMessage* from, const char* className)
\brief Internal function that checks if the \a className is the same as the
one stored in the \a from message.
*/
-/*! \fn instantiation_func find_instantiation_func(const char* className,
+/*!
+ \fn instantiation_func find_instantiation_func(const char* className,
const char* signature)
\brief Internal function that searches for the instantiation func with a
specific signature. Use instantiate_object() instead.
*/
-/*! \fn instantiation_func find_instantiation_func(const char* className)
+/*!
+ \fn instantiation_func find_instantiation_func(const char* className)
\brief Internal function that searches for the instantiation func of a
specific class. Use instantiate_object() instead.
*/
-/*! \fn instantiation_func find_instantiation_func(BMessage* archive)
+/*!
+ \fn instantiation_func find_instantiation_func(BMessage* archive)
\brief Internal function that searches for the instantiation func that
works on the specified \a archive. Use instantiate_object() instead.
*/
diff --git a/docs/user/support/Unarchiver.dox b/docs/user/support/Unarchiver.dox
index 1eca4db9e9..74d0fb2f65 100644
--- a/docs/user/support/Unarchiver.dox
+++ b/docs/user/support/Unarchiver.dox
@@ -11,7 +11,8 @@
*/
-/*! \class BUnarchiver
+/*!
+ \class BUnarchiver
\ingroup support
\ingroup libbe
\brief A class that simplifies the unarchiving of complicated BArchivable
@@ -39,7 +40,8 @@
*/
-/*! \fn BUnarchiver::BUnarchiver(const BMessage* archive)
+/*!
+ \fn BUnarchiver::BUnarchiver(const BMessage* archive)
\brief Constructs a BUnarchiver object to manage \c archive.
\note To guarantee that your AllUnarchived() method will be called during
@@ -55,14 +57,16 @@
*/
-/*! \fn BUnarchiver::~BUnarchiver()
+/*!
+ \fn BUnarchiver::~BUnarchiver()
\brief Destroys a BUnarchiver object.
Calls this objects Finish() method, if it has not yet been called.
*/
-/*! \fn status_t BUnarchiver::EnsureUnarchived(int32 token)
+/*!
+ \fn status_t BUnarchiver::EnsureUnarchived(int32 token)
\brief Ensure the object represented by \a token is unarchived and
instantiated.
@@ -70,7 +74,8 @@
*/
-/*! \fn status_t BUnarchiver::EnsureUnarchived(const char* name,
+/*!
+ \fn status_t BUnarchiver::EnsureUnarchived(const char* name,
int32 index = 0)
\brief Ensure the object archived under \a name at \a index is unarchived
and instantiated.
@@ -80,7 +85,8 @@
*/
-/*! \fn bool BUnarchiver::IsInstantiated(int32 token)
+/*!
+ \fn bool BUnarchiver::IsInstantiated(int32 token)
\brief Checks whether the object represented by \c token has been
instantiated in this session.
@@ -88,7 +94,8 @@
*/
-/*! \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
+/*!
+ \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
\brief Checks whether the object archived under \a name at \a index has been
instantiated in this session.
@@ -97,9 +104,9 @@
*/
-/*! \fn template status_t BUnarchiver::GetObject(int32 token,
+/*!
+ \fn template status_t BUnarchiver::GetObject(int32 token,
ownership_policy owning, T*& object)
-
\brief Recover an object by token that was archived by a BArchiver object.
If the object has not yet been instantiated, and this request is not coming
from an AllUnarchived() implementation, the object will be instantiated now.
@@ -121,9 +128,9 @@
*/
-/*! \fn template status_t BUnarchiver::GetObject(int32 token,
+/*!
+ \fn template status_t BUnarchiver::GetObject(int32 token,
T*& object)
-
\brief Recover and take ownership of an object represented by \a token.
Equivalent to calling GetObject(token, \c B_ASSUME_OWNERSHIP, object)
@@ -142,11 +149,12 @@
/*!
\fn template status_t BUnarchiver::FindObject(const char* name,
int32 index, ownership_policy owning, T*& object)
-
\brief Recover an object that had previously been archived using
- the BArchiver::AddArchivable() method. If the object has not yet been
- instantiated, and this request is not coming from an AllUnarchived()
- implementation, the object will be instantiated now.
+ the BArchiver::AddArchivable() method.
+
+ If the object has not yet been instantiated, and this request is not
+ coming from an AllUnarchived() implementation, the object will be
+ instantiated now.
If the retrieved object is not of the type T, then this method will fail.
If this method fails, you will not receive ownership of the object, no
@@ -167,9 +175,9 @@
*/
-/*! \fn template status_t BUnarchiver::FindObject(const char* name,
+/*!
+ \fn template status_t BUnarchiver::FindObject(const char* name,
int32 index, T*& object)
-
\brief Recover and take ownership of an object that had previously been
archived using the BArchiver::AddArchivable() method.
@@ -186,9 +194,9 @@
*/
-/*! \fn template status_t BUnarchiver::FindObject(const char* name,
+/*!
+ \fn template status_t BUnarchiver::FindObject(const char* name,
ownership_policy owning, T*& object)
-
\brief Recover an object at index \c 0 that had previously been
archived using the BArchiver::AddArchivable() method.
@@ -207,9 +215,9 @@
*/
-/*! \fn template status_t BUnarchiver::FindObject(const char* name,
+/*!
+ \fn template status_t BUnarchiver::FindObject(const char* name,
T*& object)
-
\brief Recover and take ownership of an object at index \c 0 that had
previously been archived using the BArchiver::AddArchivable() method.
@@ -227,7 +235,8 @@
*/
-/*! \fn status_t BUnarchiver::Finish(status_t err = B_OK);
+/*!
+ \fn status_t BUnarchiver::Finish(status_t err = B_OK);
\brief Report any unarchiving errors and possibly complete the archiving
session.
@@ -260,8 +269,8 @@
*/
-/*! \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
-
+/*!
+ \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
\brief Checks whether \a archive was managed by a BArchiver object.
This method can be used to maintain archive backwards-compatibility for a
@@ -293,7 +302,8 @@ MyArchivableClas::MyArchivableClass(BMessage* archive)
*/
-/*! \fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive)
+/*!
+ \fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive)
\brief Prepares \c archive for use by a BUnarchiver.
This method must be called if you plan to use a BUnarchiver on an archive.
@@ -319,7 +329,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
*/
-/*! \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
+/*!
+ \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
\brief Become the owner of \a archivable.
After calling this method you are responsible for deleting the
@@ -329,7 +340,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
*/
-/*! \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
+/*!
+ \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
\brief Relinquish ownership of \a archivable. If \a archivable remains
unclaimed at the end of the unarchiving session, it will be deleted
(unless it is the root object).
@@ -338,7 +350,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
*/
-/*! \fn template status_t BUnarchiver::InstantiateObject(
+/*!
+ \fn template status_t BUnarchiver::InstantiateObject(
BMessage* from, T*& object)
\brief Attempt to instantiate an object of type T from BMessage*
\a from.
diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox
index ac935cd794..50dec07b18 100644
--- a/docs/user/support/string.dox
+++ b/docs/user/support/string.dox
@@ -1369,21 +1369,21 @@
*/
/*!
- \fn BString& BString::ReplaceSet(const char *setOfChars, char with)
+ \fn BString& BString::ReplaceSet(const char *setOfBytes, char with)
\brief Replaces characters that are in a certain set with a chosen
character.
- \param setOfChars The set of characters that need to be replaced.
+ \param setOfBytes The set of characters that need to be replaced.
\param with The character to replace the occurences with.
\return This method always returns \c *this.
*/
/*!
- \fn BString& BString::ReplaceSet(const char *setOfChars, const char *with)
+ \fn BString& BString::ReplaceSet(const char *setOfBytes, const char *with)
\brief Replaces characters that are in a certain set with a chosen string.
- \param setOfChars The set of characters that need to be replaced.
+ \param setOfBytes The set of characters that need to be replaced.
\param with The string to replace the occurences with.
\return This method always returns \c *this.
diff --git a/src/kits/storage/EntryList.cpp b/src/kits/storage/EntryList.cpp
index fd8bd416f7..2e51ac9419 100644
--- a/src/kits/storage/EntryList.cpp
+++ b/src/kits/storage/EntryList.cpp
@@ -2,103 +2,21 @@
// This software is part of the OpenBeOS distribution and is covered
// by the OpenBeOS license.
//---------------------------------------------------------------------
-/*!
- \file EntryList.cpp
- BEntryList implementation.
-*/
#include
-// constructor
-//! Creates a BEntryList.
-/*! Does nothing at this time.
-*/
BEntryList::BEntryList()
{
}
-// destructor
-//! Frees all resources associated with this BEntryList.
-/*! Does nothing at this time.
-*/
BEntryList::~BEntryList()
{
}
-// GetNextEntry
-/*! \fn status_t BEntryList::GetNextEntry(BEntry *entry, bool traverse)
- \brief Returns the BEntryList's next entry as a BEntry.
- Places the next entry in the list in \a entry, traversing symlinks if
- \a traverse is \c true.
- \param entry a pointer to a BEntry to be initialized with the found entry
- \param traverse specifies whether to follow it, if the found entry
- is a symbolic link.
- \note The iterator used by this method is the same one used by
- GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
- \return
- - \c B_OK if successful,
- - \c B_ENTRY_NOT_FOUND when at the end of the list,
- - another error code (depending on the implementation of the derived class)
- if an error occured.
-*/
-
-// GetNextRef
-/*! \fn status_t BEntryList::GetNextRef(entry_ref *ref)
- \brief Returns the BEntryList's next entry as an entry_ref.
- Places an entry_ref to the next entry in the list into \a ref.
- \param ref a pointer to an entry_ref to be filled in with the data of the
- found entry
- \note The iterator used by this method is the same one used by
- GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
- \return
- - \c B_OK if successful,
- - \c B_ENTRY_NOT_FOUND when at the end of the list,
- - another error code (depending on the implementation of the derived class)
- if an error occured.
-*/
-
-// GetNextDirents
-/*! \fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length, int32 count)
- \brief Returns the BEntryList's next entries as dirent structures.
- Reads a number of entries into the array of dirent structures pointed to by
- \a buf. Reads as many but no more than \a count entries, as many entries as
- remain, or as many entries as will fit into the array at \a buf with given
- length \a length (in bytes), whichever is smallest.
- \param buf a pointer to a buffer to be filled with dirent structures of
- the found entries
- \param length the maximal number of entries to be read.
- \note The iterator used by this method is the same one used by
- GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
- \return
- - The number of dirent structures stored in the buffer, 0 when there are
- no more entries to be read.
- - an error code (depending on the implementation of the derived class)
- if an error occured.
-*/
-
-// Rewind
-/*! \fn status_t BEntryList::Rewind()
- \brief Rewinds the list pointer to the beginning of the list.
- \return
- - \c B_OK if successful,
- - an error code (depending on the implementation of the derived class)
- if an error occured.
-*/
-
-// CountEntries
-/*! \fn int32 BEntryList::CountEntries()
- \brief Returns the number of entries in the list
- \return
- - the number of entries in the list,
- - an error code (depending on the implementation of the derived class)
- if an error occured.
-*/
-
-
-/*! Currently unused */
+// Currently unused
void BEntryList::_ReservedEntryList1() {}
void BEntryList::_ReservedEntryList2() {}
void BEntryList::_ReservedEntryList3() {}
- $title
+
diff --git a/docs/user/interface/Alert.dox b/docs/user/interface/Alert.dox
index 53d42cdc58..8cccdaa933 100644
--- a/docs/user/interface/Alert.dox
+++ b/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