Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update the style of the Haiku Book to resemble the User Guide.

Browse Source 
If you have never seen this before you are in for a bit of a shock.
Update the Doxyfile to 1.7.3 (the version that gets auto-generated).

Update the book.dox front page with some nice introductory text.

Add new documentation for the following classes:
BCheckBox
BClipboard
BColorControl
BControl
BEntryList
BView (preliminary)

Remove redundant documentation from src/kits/storage/EntryList.cpp

Minor documentation update for the following classes:
BAlert
BApplication
BArchivable
BBox
BButton
BCatalog
BFindDirectory
BHandler
BUnarchiver
BString

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@43096 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
John Scipione 2011-11-02 08:36:02 +00:00
parent 740ae7fef6
commit 6ac7032dc6
24 changed files with 4228 additions and 1369 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1545
docs/user/Doxyfile
View File

File diff suppressed because it is too large Load Diff

5
docs/user/app/Application.dox
View File

@ -6,8 +6,8 @@
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* /trunk/headers/os/app/Application.h rev 42274
* /trunk/src/kits/app/Application.cpp rev 42274
* /trunk/headers/os/app/Application.h rev 42794
* /trunk/src/kits/app/Application.cpp rev 42794
*/
@ -20,6 +20,7 @@
/*!
\class BApplication
\ingroup app
\ingroup libbe
\brief A container object for an application.
A BApplication establishes a connection between the application and the

343
docs/user/app/Clipboard.dox Normal file
View File

@ -0,0 +1,343 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Gabe Yoder, gyoder@stny.rr.com
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* /trunk/headers/os/app/Clipboard.h rev 42274
* /trunk/src/kits/app/Clipboard.cpp rev 42274
*/
/*!
\file Clipboard.h
\brief Provides the BClipboard class.
*/
/*!
\var be_clipboard
\brief Global system clipboard object.
*/
/*!
\class BClipboard
\ingroup app
\brief Used for short-term data storage between documents and
applications via copy and paste operations.
Clipboards are differentiated by their name. In order for two
applications to share a clipboard they simply have to create a
BClipboard object with the same name. However, it is rarely necessary
to create your own clipboard, instead you can use the \c be_clipboard
system clipboard object.
\remark To access the system clipboard without a BApplication object,
create a BClipboard object with the name "system". You should avoid
creating a custom clipboard with the name "system" for your own use.
To access the clipboard data call the Data() method. The BMessage object
returned by the Data() method has the following properties:
- The \c what value is unused.
- The clipboard data is stored in a message field typed as
\c B_MIME_TYPE.
- The MIME type of the data is used as the name of the field that
holds the data.
- Each field in the data message contains the same data with a
different format.
To read and write to the clipboard you must first lock the BClipboard
object. If you fail to lock the BClipboard object then the Data() method
will return \c NULL instead of a pointer to a BMessage object.
Below is an example of reading a string from the system clipboard.
\code
const char *string;
int32 stringLen;
if (be_clipboard->Lock()) {
// Get the clipboard BMessage
BMessage *clip = be_clipboard->Data();
// Read the string from the clipboard data message
clip->FindData("text/plain", B_MIME_TYPE, (const void **)&string,
&stringLen);
be_clipboard->Unlock();
} else
fprintf(stderr, "could not lock clipboard.\n");
\endcode
Below is an example of writing a string to the system clipboard.
\code
const char* string = "Some clipboard data";
if (be_clipboard->Lock()) {
// Clear the clipboard data
be_clipboard->Clear();
// Get the clipboard data message
BMessage *clip = be_clipboard->Data();
// Write string data to the clipboard data message
clip->AddData("text/plain", B_MIME_TYPE, string, strlen(string));
// Commit the data to the clipboard
status = be_clipboard->Commit();
if (status != B_OK)
fprintf(stderr, "could not commit data to clipboard.\n");
be_clipboard->Unlock();
} else
fprintf(stderr, "could not lock clipboard.\n");
\endcode
*/
/*!
\fn BClipboard::BClipboard(const char *name, bool transient = false)
\brief Create a BClipboard object with the given \a name.
If the \a name parameter is \c NULL then the "system" BClipboard object
is constructed instead.
\param name The \a name of the clipboard.
\param transient If \c true, lose data after a reboot (currently unused).
*/
/*!
\fn BClipboard::~BClipboard()
\brief Destroys the BClipboard object. The clipboard data is not destroyed.
*/
/*!
\fn const char* BClipboard::Name() const
\brief Returns the name of the BClipboard object.
\returns The name of the clipboard.
*/
/*!
\name Commit Count Methods
*/
//! @{
/*!
\fn uint32 BClipboard::LocalCount() const
\brief Returns the (locally cached) number of commits to the clipboard.
The returned value is the number of successful Commit() invocations for
the clipboard represented by this object, either invoked on this object
or another (even from another application). This method returns a locally
cached value, which might already be obsolete. For an up-to-date value
use SystemCount().
\return The number of commits to the clipboard.
\sa SystemCount()
*/
/*!
\fn uint32 BClipboard::SystemCount() const
\brief Returns the number of commits to the clipboard.
The returned value is the number of successful Commit() invocations for
the clipboard represented by this object, either invoked on this object
or another (even from another application). This method retrieves the
value directly from the system service managing the clipboards, so it is
more expensive, but more up-to-date than LocalCount(), which returns a
locally cached value.
\return The number of commits to the clipboard.
\sa LocalCount()
*/
//! @}
/*!
\name Monitoring Methods
*/
//! @{
/*!
\fn status_t BClipboard::StartWatching(BMessenger target)
\brief Start watching the BClipboard object for changes.
When a change in the clipboard occurs, most like as the result of a cut
or copy action, a \a B_CLIPBOARD_CHANGED message is sent to \a target.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a target is invalid.
\retval B_ERROR An error occured.
\sa StopWatching()
*/
/*!
\fn status_t BClipboard::StopWatching(BMessenger target)
\brief Stop watching the BClipboard object for changes.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a target is invalid.
\retval B_ERROR An error occurred.
\sa StartWatching()
*/
//! @}
/*!
\name Locking Methods
*/
//! @{
/*!
\fn bool BClipboard::Lock()
\brief Locks the clipboard so that no other tread can read from it or
write to it.
You should call Lock() before reading or writing to the clipboard.
\returns \c true if the clipboard was locked, \c false otherwise.
\sa Unlock()
*/
/*!
\fn void BClipboard::Unlock()
\brief Unlocks the clipboard.
\sa Lock()
*/
/*!
\fn bool BClipboard::IsLocked() const
\brief Returns whether or not the clipboard is locked.
\returns \c true if the clipboard is locked, \c false if it is unlocked.
*/
//! @}
/*!
\name Clipboard Data Transaction Methods
*/
//! @{
/*!
\fn status_t BClipboard::Clear()
\brief Clears out all data from the clipboard.
You should call Clear() before adding new data to the BClipboard object.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_NO_MEMORY Ran out of memory initializing the data message.
\retval B_ERROR Another error occurred.
*/
/*!
\fn status_t BClipboard::Commit()
\brief Commits the clipboard data to the BClipboard object.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_ERROR Another error occurred.
*/
/*!
\fn status_t BClipboard::Commit(bool failIfChanged)
\brief Commits the clipboard data to the BClipboard object with the
option to fail if there is a change to the clipboard data.
\param failIfChanged Whether or not to fail to commit the changes
if there is a change in the clipboard data.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_ERROR Another error occurred.
*/
/*!
\fn status_t BClipboard::Revert()
\brief Reverts the clipboard data.
The method should be used in the case that you have made a change to the
clipboard data message and then decide to revert the change instead of
committing it.
\retval B_OK Everything went find.
\retval B_NOT_ALLOWED The clipboard is not locked.
\retval B_NO_MEMORY Ran out of memory initializing the data message.
\retval B_ERROR Another error occurred.
*/
//! @}
/*!
\name Clipboard Data Message Methods
*/
//! @{
/*!
\fn BMessenger BClipboard::DataSource() const
\brief Gets a BMessenger object targeting the application that last
modified the clipboard.
The clipboard object does not need to be locked to call this method.
\returns A BMessenger object that targets the application that last
modified the clipboard.
*/
/*!
\fn BMessage* BClipboard::Data() const
\brief Gets a pointer to the BMessage object that holds the clipboard
data.
If the BClipboard object is not locked this method returns \c NULL.
\returns A pointer to the BMessage object that holds the clipboard
data or \c NULL if the clipboard is not locked.
*/
//! @}

32
docs/user/app/Handler.dox
View File

@ -207,15 +207,15 @@
/*!
\fn void BHandler::MessageReceived(BMessage *message)
\brief Handle a message that has been received by the associated looper.
This method is reimplemented in your subclasses. If the messages that have
This method is reimplemented by subclasses. If the messages that have
been received by a looper pass through the filters, then they end up in
the MessageReceived() methods.
The example shows a very common way to handle message. Usually, this
involves parsing the BMessage::what constant and then perform an action
based on that.
The example below shows a very common way to handle message. Usually,
this involves parsing the BMessage::what constant and then perform an
action based on that.
\code
void
ShowImageApp::MessageReceived(BMessage *message)
@ -239,14 +239,14 @@ ShowImageApp::MessageReceived(BMessage *message)
}
\endcode
If your handler cannot process this message, you should pass it on to the
base class. Eventually, it will reach the default implementation, which
will reply with a \c B_MESSAGE_NOT_UNDERSTOOD constant.
\attention If you want to keep or manipulate the \a message, have a look
at the \link BLooper::DetachCurrentMessage() DetachCurrentMessage() \endlink
method to get ownership of the message.
If your handler cannot process this message, you should pass it on
to the base class. Eventually, it will reach the base implementation,
which will reply with \c B_MESSAGE_NOT_UNDERSTOOD.
\attention If you want to keep or manipulate the \a message, have a
look at BLooper::DetachCurrentMessage() to receive ownership of
the message.
\param message The message that needs to be handled.
*/
@ -254,7 +254,7 @@ ShowImageApp::MessageReceived(BMessage *message)
/*!
\fn BLooper *BHandler::Looper() const
\brief Return a pointer to the looper that this handler is associated with.
\return If the handler is not yet associated with a looper, it will return
\c NULL.
\see BLooper::AddHandler()

996
docs/user/book.css
View File

File diff suppressed because it is too large Load Diff

573
docs/user/book.dox
View File

@ -1,50 +1,555 @@
/*!
\mainpage The Haiku Book
\mainpage Welcome to the Haiku Book
\section kits Kits and Servers
Below you will find documentation on the Application Programming
Interface (API) of the Haiku operating system. This API describes
the internals of the operating system allowing developers to write
native C++ applications and device drivers. See the
<a href="http://api.haiku-os.org">online version</a> for the most
updated version of this document. If you would like to help contribute
contact the <a href="http://www.freelists.org/list/haiku-doc">documentation
mailing list</a>. For guidelines on how to help document the API see
the \link apidoc Documenting the API\endlink page. A list of
contributors can be found \ref credits page. Documenting the API is
an ongoing process so contributions are greatly appreciated.
- \ref app | \link app_intro \em Introduction \endlink
- \ref drivers
- \ref interface | \link interface_intro \em Introduction \endlink
- \ref locale | \link locale_intro \em Introduction \endlink
- \ref media | \em Introduction
- \ref midi1
- \ref midi2 | \link midi2_intro \em Introduction \endlink
- \ref storage | \em Introduction
- \ref support | \link support_intro \em Introduction \endlink
The Haiku API is based on the BeOS R5 API but changes and additions have
been included where appropriate. Important compatibility differences are
detailed on the \ref compatibility page. New classes and methods
and incompatible API changes to the BeOS R5 API are noted in the
appropriate sections.
A complete reference to the BeOS R5 API is available on the web in
<a href="http://haiku-os.org/legacy-docs/bebook/">The Be Book</a>.
The Be Book is used with permission from
<a href="http://www.access-company.com/">Access Co.</a>, the current
owners of Be's intellectual property.
\section notes General Notes and Information
- \ref compatibility
- \ref apidoc
- \ref credits
\section kits Kits and Servers
The API is split into several kits and servers each detailing a different
aspect of the operating system.
- The \ref app is the starting point for developing applications
and includes classes for messaging and for interacting with
the rest of the system.
- The \ref interface is used to create responsive and attractive
graphical user interfaces building on the messaging facilities
provided by the Application Kit.
- The \link layout_intro Layout API \endlink is a new addition
to the Interface Kit in Haiku which provides resources to
layout your application flexibly and easily.
- The \ref locale includes classes to localize your application to
different languages, timezones, number formatting conventions and
much more.
- The \ref media provides a unified and consistent interface for media
streams and applications to intercommunicate.
- The \ref midi2 describes an interface to generating, processing,
and playing music in MIDI format. For reference documentation on the
\ref midi1 is also included.
- The \ref storage is a collection of classes that deal with storing and
retrieving information from disk.
- The \ref support contains support classes to use in your application
including resources for thread safety, IO, and serialization.
\section special_topics Special Topics
- \ref drivers
*/
///// Define main kits /////
/*!
\defgroup app Application Kit
\defgroup drivers Drivers
\defgroup interface Interface Kit
\brief API for displaying a graphical user interface.
\defgroup media
\defgroup midi2 MIDI 2 Kit
\brief API for producing and consuming MIDI events.
\defgroup libmidi2 (libmidi2.so)
\defgroup storage
\defgroup support Support Kit
\brief Collection of utility classes that are used throughout the API.
\defgroup libbe (libbe.so)
\defgroup libroot (libroot.so)
\defgroup locale Locale Kit
\brief Collection of classes for localizing applications.
\defgroup app Application Kit
\brief The Application Kit is the starting point for writing native Haiku
GUI applications.
The application kit is exactly what its name suggests &mdash; it is the
basis of Haiku applications. You should first read through this document
and the references here before moving on to the other parts of the API.
The Application Kit classes can be divided into two groups: the messaging
classes and the system interaction classes. The larger of the two groups is
the messaging classes. Since the Haiku API relies on pervasive
multithreading messaging is an essential topic for any application. Have a
look at the \link app_messaging Introduction to Messaging \endlink for more
information.
The following messaging classes which allow you to easily and securely
communicate between threads.
- BHandler
- BInvoker
- BLooper
- BMessage
- BMessageFilter
- BMessageQueue
- BMessageRunner
- BMessenger
The second group is the system interaction classes. These classes
provide hooks for your application to interact with the rest of the system.
The most important class in this group is BApplication. Below is a list of
all system interaction classes:
- BApplication
- BClipboard
- BCursor
- BPropertyInfo
- BRoster
\defgroup drivers Device Drivers
\defgroup interface Interface Kit
\brief API for displaying a graphical user interface.
The Interface Kit holds all the classes you'll need to develop a GUI.
Building on the messaging facilities provided by the Application Kit,
the Interface Kit can be used to create a responsive and attractive
graphical user interface.
The most important class in the Interface Kit is the BView class, which
handles drawing and user interaction. Pointer and keyboard events are
processed in this class.
Another important class is the BWindow class, which holds BViews and makes
them visible to the user. The BWindow class also handles BView focusing
and BMessage dispatching, among other things.
A new addition Haiku has added over the BeOS API is the Layout API, which
is based around the BLayoutItem and BLayout classes. These classes will
take care of making sure all your GUI widgets end up where you want them,
with enough space to be useful. You can start learning the Layout API
by reading the \link layout_intro introduction \endlink.
\defgroup locale Locale Kit
\brief Collection of classes for localizing applications.
The Locale Kit provides a set of tools for internationalizing,
localizing and translating your software. This includes not only
replacing string with their translations at runtime, but also more
complex tasks such as formatting numbers, dates, and times in a way
that match the locale preferences of the user.
The main way to access locale data is through the be_locale_roster.
This is a global instance of the BLocaleRoster class, storing the data
for localizing an application according to the user's preferred settings.
The locale roster also acts as a factory to instantiate most of the other
classes. However, there are some cases where you will need to instantiate
another class by yourself, to use it with custom settings. For example, you
may need to format a date with a fixed format in english for including in an
e-mail header, as it is the only format accepted there.
Unlike the other kits in Haiku, the Locale kit does not live in libbe.
When building a localized application, you have to link it to
liblocale.so. If you want to use the catalog macros, you also have to
link each of your images (that is, applications, libraries and add-ons)
to liblocalestub.a.
\defgroup media Media Kit
\brief Collection of classes that deal with audio and video.
\defgroup midi1 The old MIDI Kit (libmidi.so)
\brief The old MIDI kit.
\defgroup midi2 MIDI 2 Kit
\brief The Midi Kit is the API that implements support for generating,
processing, and playing music in MIDI format.
<A HREF="http://www.midi.org/">MIDI</A>, which stands for 'Musical
Instrument Digital Interface', is a well-established standard for
representing and communicating musical data. This document serves as
an overview. If you would like to see all the components, please look
at \link midi2 the list with classes \endlink.
\section midi2twokits A Tale of Two MIDI Kits
BeOS comes with two different, but compatible Midi Kits. This
documentation focuses on the "new" Midi Kit, or midi2 as we like to
call it, that was introduced with BeOS R5. The old kit, which we'll
refer to as midi1, is more complete than the new kit, but less powerful.
Both kits let you create so-called MIDI endpoints, but the endpoints
from midi1 cannot be shared between different applications. The midi2
kit solves that problem, but unlike midi1 it does not include a General
MIDI softsynth, nor does it have a facility for reading and playing
Standard MIDI Files. Don't worry: both kits are compatible and you can
mix-and-match them in your applications.
The main differences between the two kits:
- Instead of one BMidi object that both produces and consumes events,
we have BMidiProducer and BMidiConsumer.
- Applications are capable of sharing MIDI producers and consumers
with other applications via the centralized Midi Roster.
- Physical MIDI ports are now sharable without apps "stealing" events
from each other.
- Applications can now send/receive raw MIDI byte streams (useful if
an application has its own MIDI parser/engine).
- Channels are numbered 0&ndash;15, not 1&ndash;16
- Timing is now specified in microseconds rather than milliseconds.
\section midi2concepts Midi Kit Concepts
A brief overview of the elements that comprise the Midi Kit:
- \b Endpoints. This is what the Midi Kit is all about: sending MIDI
messages between endpoints. An endpoint is like a MIDI In or MIDI
Out socket on your equipment; it either receives information or it
sends information. Endpoints that send MIDI events are called
\b producers; the endpoints that receive those events are called
\b consumers. An endpoint that is created by your own application
is called \b local; endpoints from other applications are
\b remote. You can access remote endpoints using \b proxies.
- \b Filters. A filter is an object that has a consumer and a producer
endpoint. It reads incoming events from its consumer, performs some
operation, and tells its producer to send out the results. In its
current form, the Midi Kit doesn't provide any special facilities
for writing filters.
- \b Midi \b Roster. The roster is the list of all published producers
and consumers. By publishing an endpoint, you allow other
applications to talk to it. You are not required to publish your
endpoints, in which case only your own application can use them.
- \b Midi \b Server. The Midi Server does the behind-the-scenes work.
It manages the roster, it connects endpoints, it makes sure that
endpoints can communicate, and so on. The Midi Server is started
automatically when BeOS boots, and you never have to deal with it
directly. Just remember that it runs the show.
- \b libmidi. The BMidi* classes live inside two shared libraries:
libmidi.so and libmidi2.so. If you write an application that uses
old Midi Kit, you must link it to libmidi.so. Applications that use
the new Midi Kit must link to libmidi2.so. If you want to
mix-and-match both kits, you should also link to both libraries.
Here is a pretty picture:
\image html midi2concepts.png
\section midi2mediakit Midi Kit != Media Kit
Be chose not to integrate the Midi Kit into the Media Kit as another media
type, mainly because MIDI doesn't require any of the format negotiation that
other media types need. Although the two kits look similar -- both have a
"roster" for finding or registering "consumers" and "producers" -- there are
some very important differences.
The first and most important point to note is that BMidiConsumer and
BMidiProducer in the Midi Kit are \b NOT directly analogous to
BBufferConsumer and BBufferProducer in the Media Kit! In the Media Kit,
consumers and producers are the data consuming and producing properties
of a media node. A filter in the Media Kit, therefore, inherits from both
BBufferConsumer and BBufferProducer, and implements their virtual member
functions to do its work.
In the Midi Kit, consumers and producers act as endpoints of MIDI data
connections, much as media_source and media_destination do in the Media Kit.
Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer;
instead, it contains BMidiConsumer and BMidiProducer objects for each of its
distinct endpoints that connect to other MIDI objects. The Midi Kit does not
allow the use of multiple virtual inheritance, so you can't create an object
that's both a BMidiConsumer and a BMidiProducer.
This also contrasts with the old Midi Kit's conception of a BMidi object,
which stood for an object that both received and sent MIDI data. In the new
Midi Kit, the endpoints of MIDI connections are all that matters. What lies
between the endpoints, i.e. how a MIDI filter is actually structured, is
entirely at your discretion.
Also, rather than use token structs like media_node to make connections
via the MediaRoster, the new kit makes the connections directly via the
BMidiProducer object.
\section midi2remotelocal Remote vs. Local Objects
The Midi Kit makes a distinction between remote and local MIDI objects.
You can only create local MIDI endpoints, which derive from either
BMidiLocalConsumer or BMidiLocalProducer. Remote endpoints are endpoints
that live in other applications, and you access them through BMidiRoster.
BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and
BMidiProducers. When you want to talk to remote MIDI objects, you do so
through the proxy objects that BMidiRoster provides. Unlike
BMidiLocalConsumer and BMidiLocalProducer, these classes do not provide a
lot of functions. That is intentional. In order to hide the details of
communication with MIDI endpoints in other applications, the Midi Kit must
hide the details of how a particular endpoint is implemented.
So what can you do with remote objects? Only what BMidiConsumer,
BMidiProducer, and BMidiEndpoint will let you do. You can connect
objects, get the properties of these objects -- and that's about it.
\section midi2lifespan Creating and Destroying Objects
The constructors and destructors of most midi2 classes are private,
which means that you cannot directly create them using the C++
<CODE>new</CODE> operator, on the stack, or as globals. Nor can you
<CODE>delete</CODE> 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
<CODE>delete</CODE> 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
<CODE>snooze_until()</CODE> 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, <CODE>snooze_until()</CODE> 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
<I>(scheduled_performance_time - latency)</I>. 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
<CODE>snooze_until()</CODE>, 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 <A
HREF="http://open-beos.sourceforge.net/nsl.php?mode=display&id=36">OpenBeOS
Newsletter 36</A> 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
<CODE>snooze_until()</CODE> 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
- <A HREF="http://haiku-os.org/documents/dev/introduction_to_midi_part_1">Newsletter
33</A>, Introduction to MIDI, Part 1
- <A HREF="http://haiku-os.org/documents/dev/introduction_to_midi_part_2">Newsletter
36</A>, Introduction to MIDI, Part 2
- Sample code and other goodies at the
<A HREF="http://haiku-os.org/about/teams/midi_kit">Haiku Midi Kit team page</A>
Information about MIDI in general:
- <A HREF="http://www.midi.org">MIDI Manufacturers Association</A>
- <A HREF="http://www.borg.com/~jglatt/tutr/miditutr.htm">MIDI Tutorials</A>
- <A HREF="http://www.borg.com/~jglatt/tech/midispec.htm">MIDI Specification</A>
- <A HREF="http://www.borg.com/~jglatt/tech/midifile.htm">Standard MIDI File Format</A>
- <A HREF="http://www.io.com/~jimm/midi_ref.html">Jim Menard's MIDI Reference</A>
\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
*/

7
docs/user/header.html
View File

@ -6,7 +6,8 @@
<link href="book.css" rel="stylesheet" type="text/css">
</head>
<body>
<div class="logo">
<img src="logo.png" alt="logo" width="372" height="84" />
<div class="title">$title</div>
<div id="banner">
<div class="logo">
<span class="subtitle">API Documentation</span>
</div>
</div>

9
docs/user/interface/Alert.dox
View File

@ -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 <jscipione@gmail.com>
* John Scipione <jscipione@gmail.com>
* 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.

BIN
docs/user/interface/BCheckBox_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.0 KiB

BIN
docs/user/interface/BColorControl_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.0 KiB

BIN
docs/user/interface/BColorControl_example_256_colors.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.4 KiB

263
docs/user/interface/Box.dox
View File

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

155
docs/user/interface/Button.dox
View File

@ -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 <jscipione@gmail.com>
* 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
*/

239
docs/user/interface/CheckBox.dox Normal file
View File

@ -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()
*/

316
docs/user/interface/ColorControl.dox Normal file
View File

@ -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()
*/

422
docs/user/interface/Control.dox Normal file
View File

@ -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()
*/

297
docs/user/interface/View.dox Normal file
View File

@ -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.
*/

36
docs/user/locale/Catalog.dox
View File

@ -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.

132
docs/user/storage/EntryList.dox Normal file
View File

@ -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).
*/

8
docs/user/storage/FindDirectory.dox
View File

@ -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

58
docs/user/support/Archivable.dox
View File

@ -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.
*/

69
docs/user/support/Unarchiver.dox
View File

@ -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<class T> status_t BUnarchiver::GetObject(int32 token,
/*!
\fn template<class T> 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<class T> status_t BUnarchiver::GetObject(int32 token,
/*!
\fn template<class T> 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<class T> 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<class T> status_t BUnarchiver::FindObject(const char* name,
/*!
\fn template<class T> 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<class T> status_t BUnarchiver::FindObject(const char* name,
/*!
\fn template<class T> 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<class T> status_t BUnarchiver::FindObject(const char* name,
/*!
\fn template<class T> 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<class T> status_t BUnarchiver::InstantiateObject(
/*!
\fn template<class T> status_t BUnarchiver::InstantiateObject(
BMessage* from, T*& object)
\brief Attempt to instantiate an object of type T from BMessage*
\a from.

8
docs/user/support/string.dox
View File

@ -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.

84
src/kits/storage/EntryList.cpp
View File

@ -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 <EntryList.h>
// 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() {}