From a33f8fbdec035ff322cc1ef364877a3092e99a09 Mon Sep 17 00:00:00 2001 From: Adrien Destugues Date: Tue, 9 Aug 2011 21:46:13 +0000 Subject: [PATCH] Merge work by John Scipione on the Haiku Book. * Some new classes documented * Screenshots for the interface kit controls * A lot of typo fixes * Some css tweaks This has some backporting to the current version of Doxygen, since there are experiments to get coloring similar to the one in the Be Book that will hopefully be upstreamed in Doxygen. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42608 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- docs/user/Doxyfile | 9 +- docs/user/app/Application.dox | 550 +++++ docs/user/app/Handler.dox | 5 +- docs/user/app/Looper.dox | 17 +- docs/user/app/Message.dox | 548 ++--- docs/user/book.css | 18 + docs/user/book.dox | 2 + docs/user/drivers/USB3.dox | 867 ++++---- docs/user/drivers/fs_interface.dox | 89 +- docs/user/interface/Alert.dox | 389 ++++ docs/user/interface/BAlert_example.png | Bin 0 -> 8972 bytes docs/user/interface/BBox_example.png | Bin 0 -> 3834 bytes docs/user/interface/BBox_with_checkbox.png | Bin 0 -> 9664 bytes docs/user/interface/BButton_example.png | Bin 0 -> 4803 bytes docs/user/interface/B_FANCY_BORDER.png | Bin 0 -> 3476 bytes docs/user/interface/B_PLAIN_BORDER.png | Bin 0 -> 3369 bytes docs/user/interface/Bitmap.dox | 556 +++++ docs/user/interface/Box.dox | 335 +-- docs/user/interface/Button.dox | 456 +++++ docs/user/interface/GridLayout.dox | 115 +- docs/user/interface/GroupLayout.dox | 124 +- docs/user/interface/InterfaceDefs.dox | 65 + docs/user/interface/Layout.dox | 216 +- docs/user/interface/LayoutBuilder.Group.dox | 68 +- docs/user/interface/LayoutBuilder.dox | 12 +- docs/user/interface/LayoutItem.dox | 108 +- docs/user/interface/TwoDimensionalLayout.dox | 93 +- docs/user/locale/Catalog.dox | 375 ++-- docs/user/locale/Collator.dox | 239 ++- docs/user/locale/Country.dox | 111 +- docs/user/locale/Locale.dox | 543 ++++- docs/user/locale/LocaleRoster.dox | 234 ++- docs/user/locale/TimeZone.cpp | 72 - docs/user/locale/TimeZone.dox | 110 + docs/user/locale/UnicodeChar.dox | 244 ++- docs/user/media/Buffer.dox | 113 ++ docs/user/storage/AppFileInfo.dox | 769 +++++++ docs/user/support/Archivable.dox | 71 +- docs/user/support/Beep.dox | 43 +- docs/user/support/List.dox | 8 +- docs/user/support/SupportDefs.dox | 252 ++- docs/user/support/Unarchiver.dox | 218 +- docs/user/support/string.dox | 1921 +++++++++++------- 43 files changed, 7151 insertions(+), 2814 deletions(-) create mode 100644 docs/user/app/Application.dox create mode 100644 docs/user/interface/Alert.dox create mode 100644 docs/user/interface/BAlert_example.png create mode 100644 docs/user/interface/BBox_example.png create mode 100644 docs/user/interface/BBox_with_checkbox.png create mode 100644 docs/user/interface/BButton_example.png create mode 100644 docs/user/interface/B_FANCY_BORDER.png create mode 100644 docs/user/interface/B_PLAIN_BORDER.png create mode 100644 docs/user/interface/Bitmap.dox create mode 100644 docs/user/interface/Button.dox create mode 100644 docs/user/interface/InterfaceDefs.dox delete mode 100644 docs/user/locale/TimeZone.cpp create mode 100644 docs/user/locale/TimeZone.dox create mode 100644 docs/user/media/Buffer.dox create mode 100644 docs/user/storage/AppFileInfo.dox diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index cd2bc99882..081015ff96 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -177,7 +177,8 @@ TAB_SIZE = 4 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = +# For keyboard shortcuts and anything related to pressing keys +ALIASES = "key{1}=\1" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C # sources only. Doxygen will then generate output that is more tailored for C. @@ -475,16 +476,21 @@ INPUT = . \ ../../headers/os/drivers/USB3.h \ ../../headers/os/drivers/USB_spec.h \ ../../headers/os/interface/AbstractLayout.h \ + ../../headers/os/interface/Alert.h \ + ../../headers/os/interface/Button.h \ + ../../headers/os/interface/Bitmap.h \ ../../headers/os/interface/Box.h \ ../../headers/os/interface/GridLayout.h \ ../../headers/os/interface/GroupLayout.h \ ../../headers/os/interface/IconUtils.h \ + ../../headers/os/interface/InterfaceDefs.h \ ../../headers/os/interface/Layout.h \ ../../headers/os/interface/LayoutBuilder.h \ ../../headers/os/interface/LayoutItem.h \ ../../headers/os/interface/TwoDimensionalLayout.h \ ../../headers/os/locale \ ../../headers/os/midi2 \ + ../../headers/os/storage/AppFileInfo.h \ ../../headers/os/support \ ../../headers/posix/syslog.h @@ -565,6 +571,7 @@ EXAMPLE_RECURSIVE = NO # the \image command). IMAGE_PATH = . \ + interface\ midi2 # The INPUT_FILTER tag can be used to specify a program that doxygen should diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox new file mode 100644 index 0000000000..c7418b312f --- /dev/null +++ b/docs/user/app/Application.dox @@ -0,0 +1,550 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/app/Application.h rev 42274 + * /trunk/src/kits/app/Application.cpp rev 42274 + */ + + +/*! + \file Application.h + \brief Provides the BApplication class. +*/ + + +/*! + \class BApplication + \ingroup app + \brief A container object for an application. + + A BApplication establishes a connection between the application and the + Application Server. + + The most common task performed by a BApplication object is to handle + messages sent to it. The BApplication object also is used + to get information about your application such as the number of windows + it has, its signature, executable location, and launch flags. + + The BApplication object is automatically assigned to the global \c be_app + variable. The \c be_app variable allows you to refer to your BApplication + object from anywhere in the code. + + To use a BApplication you first construct the object and then begin its + message loop by calling the Run() method. The Run() method + continues until the application is told to quit. Once Run() returns you + should then delete the BApplication object to free its memory usage. + + Typically, you initialize the BApplication object in the programs main() + function. A typical main() function looks something like this: + + \code +#include Application.h + +main() +{ + /* Vendor is your vendor name, application is your application name */ + BApplication app("application/x-vnd.vendor-application"); + app->Run(); + delete app; + + return 0; +} + \endcode +*/ + + +/*! + \fn BApplication::BApplication(const char *signature) + \brief Initialize a BApplication with the passed in \a signature. + + The new BApplication is, by default, not running yet. If you have + everything set up properly call Run() to start the application. + + You should call InitCheck() to check for constructor initialization + errors. + + \param signature The \a signature of the application. +*/ + + +/*! + \fn BApplication::BApplication(const char *signature, status_t *_error) + \brief Initialize a BApplication with the passed in \a signature and a + pointer to an error message. + + Any error that occurs while constructing the BApplication will be + set to the \a _error pointer. If \a _error points to a \c status_t + error then you should not call Run(). + + Alternately, you can call InitCheck() to check for constructor + initialization errors. + + \param signature The \a signature of the application. + \param _error A pointer to a \c status_t set by the BApplication + constructor. +*/ + +/*! + \fn status_t BApplication::InitCheck() const + \brief Returns the status of the constructor. + + \returns If initialization succeeded returns \c B_OK, otherwise returns an + error status. +*/ + + +/*! + \name Archiving +*/ + + +//! @{ + + +/*! + \fn BApplication::BApplication(BMessage *data) + \brief Initialize a BApplication object from a message. + + The message must contain the signature of the application you wish to + initialize in the "mime_sig" variable. + + \param data The message to initialize the BApplication from. +*/ + + +/*! + \fn status_t BApplication::Archive(BMessage *data, bool deep) const + \brief Archive the BApplication object into a BMessage. + + \sa BArchivable::Archive() +*/ + + +/*! + \fn BArchivable* BApplication::Instantiate(BMessage* data) + \brief Restores the BApplication object from a BMessage. + + \sa BArchivable::Instantiate() +*/ + + +//! @} + + +/*! + \fn BApplication::~BApplication() + \brief Destructor Method +*/ + + +/*! + \name Message Loop Control +*/ + + +//! @{ + + +/*! + \fn thread_id BApplication::Run() + \brief Starts the message loop in the thread that it is called from, + and doesn't return until the message loop stops. Run() does not spawn + a new thread. + + \returns the thread_id of the thread that the BApplication is called from. +*/ + + +/*! + \fn void BApplication::Quit() + \brief Tells the thread to finish processing the message queue, disallowing + any new messages. + + Quit() doesn't kill the looper thread. After Quit() returns, it doesn't wait + for the message queue to empty. Run() will be then able to return. + + Quit() doesn't delete the BApplication object after Run() is called. You + should delete the BApplication object yourself one Run() returns. + However Quit() does delete the object if it's called before the message loop + starts i.e. before Run() is called. +*/ + + +//! @} + + +/*! + \name Hook Methods +*/ + + +//! @{ + + +/*! + \fn bool BApplication::QuitRequested() + \brief Hook method that gets invoked when the BApplication receives a + \c B_QUIT_REQUESTED message. + + BApplication sends a QuitRequested() message to each of its BWindow objects. + If all of the BWindow s return \c true then the windows are + each destroyed (through BWindow::Quit()) and QuitRequested() returns + \c true. If any of the BWindow returns \c false, the BWindow s + are not destroyed and QuitRequested() returns \c false. + + \retval true The application quit. + \retval false The application failed to quit. +*/ + + +/*! + \fn void BApplication::ReadyToRun() + \brief Hook method that's invoked when the BApplication receives a + \c B_READY_TO_RUN message. + + The ReadyToRun() method is automatically called by the Run() method. It is + sent after the initial \c B_REFS_RECEIVED and \c B_ARGV_RECEIVED messages + (if any) have already been handled. ReadyToRun() is the only message that + every running application is guaranteed to receive. + + The default version of ReadyToRun() is empty. You should override the + ReadyToRun() method to do whatever you want to do. If you haven't + constructed any windows in your application yet then this would be a good + place to do so. +*/ + + +/*! + \fn void BApplication::ArgvReceived(int32 argc, char **argv) + \brief Hook method that gets invoked when the application receives a + \c B_ARGV_RECEIVED message. + + If command line arguments are specified when the application is launched + from the the shell, or if \c argv/argc values are passed to + BRoster::Launch(), then this method is executed. + + \warning ArgvReceived() is not called if no command line arguments are + specified, or if BRoster::Launch() was called without any \c argv/argc + values. + + The arguments passed to ArgvReceived() are the constructed in the same way + as those passed to command line programs. The number of command line + arguments is passed in \a argc and the arguments themselves are passed as an + array of strings in \a argv. The first \a argv string is the name of the + program and the rest of the strings are the command line arguments. + + BRoster::Launch() adds the program name to the front of the \a argv array + and increments the \a argc value. + + The \c B_ARGV_RECEIVED message (if sent) is sent only once, just + before the \c B_READY_TO_RUN message is sent. However, if you try to + relaunch an application that is already running and the application is set + to \c B_EXCLUSIVE_LAUNCH or \c B_SINGLE_LAUNCH then the application will + generate a \c B_ARGV_RECEIVED message and send it to the already running + instance. Thus in this case the \c B_ARGV_RECEIVED message can show + up at any time. +*/ + + +/*! + \fn void BApplication::AppActivated(bool active) + \brief Hook method that gets invoked when the application receives + \c B_APP_ACTIVATED message. + + The message is sent whenever the application changes its active application + status. The active flag set to is \c true when the application becomes + active and is set to \c false when the application becomes inactive. + + The application becomes activated in response to a user action such as + clicking on or unhiding one of its windows. The application can have its + active status set programmatically by calling either the BWindow::Activate() + or BRoster::ActivateApp() methods. + + This method is called after ReadyToRun() provided the application is + displaying a window that can be set active. +*/ + + +/*! + \fn void BApplication::RefsReceived(BMessage *message) + \brief Hook method that gets invoked when the application receives a + \c B_REFS_RECEIVED message. + + The message is sent in response to a user action such as a user + drag-and-dropping a file on your app's icon or opening a file that the + application is set to handle. You can use the IsLaunching() method to + discern whether the message arrived when the application is launched or + after the application has already been running. + + The default implementation is empty. You can override this method to do + something with the received refs. Typically you create BEntry or BFile + objects from the passed in refs. + + \param message contains a single field named "be:refs" that contains one or + more entry_ref (\c B_REF_TYPE) items, one for each file sent. +*/ + + +/*! + \fn void BApplication::AboutRequested() + \brief Hook method that gets invoked when the BApplication receives a + \c B_ABOUT_REQUESTED message. + + You should override this method to pop an alert to provide information + about the application. + + The default implementation pops a basic alert dialog. +*/ + + +//! @} + + +/*! + \name Cursor +*/ + + +//! @{ + + +/*! + \fn BApplication::ShowCursor() + \brief Restores the cursor. +*/ + + +/*! + \fn void BApplication::HideCursor() + \brief Hides the cursor from the screen. +*/ + + +/*! + \fn void BApplication::ObscureCursor() + \brief Hides the cursor until the mouse is moved. +*/ + + +/*! + \fn bool BApplication::IsCursorHidden() const + \brief Returns whether or not the cursor is hidden. + + \returns \c true if the cursor is hidden, \c false if not. +*/ + + +/*! + \fn void BApplication::SetCursor(const void *cursor) + \brief Sets the \a cursor to be used when the application is active. + + You can pass one of the pre-defined cursor constants such as + \c B_HAND_CURSOR or \c B_I_BEAM_CURSOR or you can create your own pass + in your own cursor image. The cursor data format is described in the BCursor + class. + + \param cursor The cursor data to set the cursor to. +*/ + + +/*! + \fn void BApplication::SetCursor(const BCursor *cursor, bool sync) + \brief Sets the \a cursor to be used when the application is active + with \a sync immediately option. + + The default BCursors to use are \c B_CURSOR_SYSTEM_DEFAULT for the hand + cursor and \c B_CURSOR_I_BEAM for the I-beam cursor. + + \param cursor A BCursor object to set the \a cursor to. + \param sync synchronize the cursor immediately. +*/ + + +//! @} + + +/*! + \name Info +*/ + + +//! @{ + + +/*! + \fn int32 BApplication::CountWindows() const + \brief Returns the number of windows created by the application. + + \returns the number of windows created by the application. +*/ + + +/*! + \fn BWindow* BApplication::WindowAt(int32 index) const + \brief Returns the BWindow object at the specified index in the + application's window list. + + If index is out of range, this function returns \c NULL. + + \warning Locking the BApplication object doesn't lock the window list. + + \param index The \a index of the desired BWindow. + + \returns The BWindow object at the specified \a index or \c NULL + if the \a index is out of range. +*/ + + +/*! + \fn int32 BApplication::CountLoopers() const + \brief Returns the number of BLoopers created by the application. + + \warning This method may return \c B_ERROR. + + \returns The number of BLoopers in the application. +*/ + + +/*! + \fn BLooper* BApplication::LooperAt(int32 index) const + \brief Returns the BLooper object at the specified index in the + application's looper list. + + If index is out of range, this function returns \c NULL. + + \returns The BLooper object at the specified \a index or \c NULL + if the \a index is out of range. +*/ + + +//! @} + + +/*! + \name Status +*/ + + +//! @{ + + +/*! + \fn bool BApplication::IsLaunching() const + \brief Returns whether or not the application is in the process of + launching. + + \returns \c true if the application is launching, \c false if the + application is already running. +*/ + + +/*! + \fn status_t BApplication::GetAppInfo(app_info *info) const + \brief Fills out the \a info parameter with information about the + application. + + This is equivalent to + be_roster->GetRunningAppInfo(be_app->Team(), info); + + \returns \c B_NO_INIT on an error or \c B_OK if all goes well. + + \sa BRoster::GetAppInfo() +*/ + + +/*! + \fn BResources* BApplication::AppResources() + \brief Returns a BResources object for the application. +*/ + + +//! @} + + +/*! + \name Message Mechanics +*/ + + +//! @{ + + +/*! + \fn void BApplication::MessageReceived(BMessage *message) + \sa BHandler::MessageReceived() +*/ + + +/*! + \fn void BApplication::DispatchMessage(BMessage *message, + BHandler *handler) + \sa BLooper::DispatchMessage() +*/ + + +//! @} + + +/*! + \name Pulse +*/ + + +//! @{ + + +/*! + \fn void BApplication::Pulse() + \brief Hook method that gets invoked when the BApplication receives a + \c B_PULSE message. + + An action is performed each time 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 BApplication::SetPulseRate(bigtime_t rate) + \brief Sets the interval that the \c B_PULSE messages are sent. + + If the \a rate is set to 0 then the \c B_PULSE messages are not sent. + The pulse rate can be no faster than once per 100,000 microseconds or so. + + \param rate The rate \a B_PULSE messages are sent to the application. +*/ + + +//! @} + + +/*! + \name Scripting +*/ + + +//! @{ + + +/*! + \fn BHandler* BApplication::ResolveSpecifier(BMessage *message, int32 index, + BMessage *specifier, int32 what, const char *property) + \sa BHandler::ResolveSpecifier() +*/ + + +/*! + \fn status_t BApplication::GetSupportedSuites(BMessage *data) + \sa BHandler::GetSupportedSuites() +*/ + + +//! @} diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox index 0fcf051f32..04ecddb1c9 100644 --- a/docs/user/app/Handler.dox +++ b/docs/user/app/Handler.dox @@ -444,13 +444,14 @@ ShowImageApp::MessageReceived(BMessage *message) /*! \fn BHandler * BHandler::ResolveSpecifier(BMessage *msg, int32 index, BMessage *specifier, int32 form, const char *property) - \brief Undocumented. + \brief Determine the proper handler for a scripting message. */ /*! \fn status_t BHandler::GetSupportedSuites(BMessage *data) - \brief Undocumented. + \brief Reports the suites of messages and specifiers that derived classes + understand. */ diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox index 7ef6428398..cfabdee7e4 100644 --- a/docs/user/app/Looper.dox +++ b/docs/user/app/Looper.dox @@ -147,7 +147,7 @@ \warning This constructor does no type check whatsoever. Since you can pass any BMessage, you should - if you are not sure about the exact type - use the Instantiate() method, which does check the type. - + \see Instantiate() \see Archive() */ @@ -710,13 +710,20 @@ /*! \fn BHandler* BLooper::ResolveSpecifier(BMessage* msg, int32 index, BMessage* specifier, int32 form, const char* property) - \brief Undocumented. + \brief Determine the proper handler for a scripting message. + + \see BHandler::ResolveSpecifier() */ /*! \fn status_t BLooper::GetSupportedSuites(BMessage* data) - \brief Undocumented. + \brief Reports the suites of messages and specifiers that derived classes + understand. + + \param data The message to report the suite of messages and specifiers. + + \see BHandler::GetSupportedSuites() */ @@ -799,7 +806,7 @@ /*! \fn BMessage* BLooper::MessageFromPort(bigtime_t timeout) - \brief Hook function to retrieve a message from the looper's port. + \brief Hook method to retrieve a message from the looper's port. The default implementation is called by the internal message looping thread and retrieves the next message from the port that belongs to this looper. @@ -813,5 +820,3 @@ arriving at the default port. */ - - \ No newline at end of file diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox index d6b724f7bb..123c743edd 100644 --- a/docs/user/app/Message.dox +++ b/docs/user/app/Message.dox @@ -95,9 +95,9 @@ This class is at the center of the web of messaging classes, in the sense that it defines the actual structure of the messages. Messages have two - important elements: the #what identifer, and the data members. The + important elements: the #what identifier, and the data members. The first can be directly manipulated, the latter can be manipulated through - AddData(), FindData() and ReplaceData() and their deratives. Neither of + AddData(), FindData() and ReplaceData() and their derivatives. Neither of these elements are mandatory. The second important role of BMessage is that it stores meta data: @@ -115,7 +115,7 @@ All methods can be classified in these areas: - Adding, Finding, Replacing and Removing Data. - - Statistics and Miscelanous information. + - Statistics and Miscellaneous information. - Delivery information. - Utilities to reply to messages. @@ -135,7 +135,7 @@ /*! \fn BMessage::BMessage() \brief Construct an empty message, without any data members and with a - \c what constant set to zero (0). + \a what constant set to \c 0. \see BMessage(uint32 what) \see BMessage(const BMessage &other) @@ -144,7 +144,7 @@ /*! \fn BMessage::BMessage(uint32 what) - \brief Construct an empty message with the \c what member set tot the + \brief Construct an empty message with the \a what member set to the specified value. \see BMessage::BMessage() @@ -156,14 +156,14 @@ \fn BMessage::BMessage(const BMessage &other) \brief Construct a new message that is a copy of another message. - The \c what member and the data values are copied. The metadata, such as + The \a what member and the data values are copied. The metadata, such as whether or not the message is a drop message or reply information, is not copied. So if the original message is a reply to a previous message, which will make IsReply() return \c true, calling the same method on a copy of the message will return \c false. \remarks BeOS R5 did keep the metadata of the message. Haiku deviates from - this behaviour. Please use the Haiku implementation of message copying as + this behavior. Please use the Haiku implementation of message copying as the default behavior. This will keep your applications backwards compatible. @@ -185,13 +185,13 @@ \fn BMessage &BMessage::operator=(const BMessage &other) \brief Copy one message into another. - See the copy constructor, BMessage(const BMessage &other), for details on what is - copied, and what isn't. + See the copy constructor, BMessage(const BMessage &other), for details on + what is copied, and what isn't. */ /*! - \name Statistics and Miscelanous Information + \name Statistics and Miscellaneous Information */ @@ -212,21 +212,21 @@ in a pointer to the internal name buffer in the message. This means that you should not manipulate this name. If you are not interested in the name, you can safely pass \c NULL. - \param[out] typeFound The type of the item at \a index. If you are not - interested in the type (because you specifically asked for a type), you - can safely pass NULL. - \param[out] countFound The number of items at \a index. If data items have - the same name, they will be placed under the same index. + \param[out] typeFound The type of the item at \a index. If you are + not interested in the type (because you specifically asked for a type), + you can safely pass \c NULL. + \param[out] countFound The number of items at \a index. If data + items have the same name, they will be placed under the same index. - \return If the \a index is found, and matches the requested type, the - other parameters will be filled in. If this is not the case, the method - will return with an error. + \return If the \a index is found, and matches the requested type, + then the other parameters will be filled in. If this is not the case, + the method will return with an error. \retval B_OK An match was found. The values have been filled in. - \retval B_BAD_INDEX The \a index was out of range. None of the passed - variables have been altered. - \retval B_BAD_TYPE The data field at \a index does not have the requested - type. + \retval B_BAD_INDEX The \a index was out of range. None of the + passed variables have been altered. + \retval B_BAD_TYPE The data field at \a index does not have the + requested type. */ @@ -244,9 +244,9 @@ label will be in this parameter. In case you are not interested, you can safely pass \c NULL. - \return If the message has data associated with the given \a name, the - other parameters will contain information associated with the data. - Else, the method will return with an error. + \return If the message has data associated with the given \a name, + the other parameters will contain information associated with the data, + else, the method will return with an error. \retval B_OK A match was found. The other parameters have been filled in. \retval B_BAD_VALUE You passed \c NULL as argument to \a name. @@ -260,9 +260,10 @@ \brief Retrieve the type and whether or not the size of the data is fixed associated with a \a name. - This method is the same as GetInfo(const char *,type_code *, int32 *) const , with the difference that you can find out whether or - not the size of the data associated with the \a name is fixed. You will - get this value in the variable you passed as \a fixedSize parameter. + This method is the same as GetInfo(const char *,type_code *, int32 *) const, + with the difference that you can find out whether or not the size of the + data associated with the \a name is fixed. You will get this value + in the variable you passed as \a fixedSize parameter. */ @@ -277,7 +278,7 @@ method will return the total number of data items. \return The number of data items in this message with the specified - \a type, or zero in case no items match the type. + \a type, or \c 0 in case no items match the type. */ @@ -328,8 +329,8 @@ \param newEntry The new name of the data entry. \retval B_OK Renaming succeeded. - \retval B_BAD_VALUE Either the \a oldEntry or the \a newEntry pointers are - \c NULL. + \retval B_BAD_VALUE Either the \a oldEntry or the + \a newEntry pointers are \c NULL. \retval B_NAME_NOT_FOUND There is no data associated with the label \a oldEntry. */ @@ -477,9 +478,9 @@ This method sends a reply to this message to the sender. On your turn, you specify a messenger that handles a reply back to the message you - specify as the \a reply argument. You can set a timeout for the message - to be delivered. This method blocks until the message has been received, - or the \a timeout has been reached. + specify as the \a reply argument. You can set a timeout for the + message to be delivered. This method blocks until the message has been + received, or the \a timeout has been reached. \param reply The message that is in reply to this message. \param replyTo In case the receiver needs to reply to the message you are @@ -492,8 +493,9 @@ \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. \retval B_BAD_PORT_ID The reply address is not valid (anymore). - \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT - (zero) and the target port was full when trying to deliver the message. + \retval B_WOULD_BLOCK The delivery \a timeout was + \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when trying + to deliver the message. \retval B_TIMED_OUT The timeout expired while trying to deliver the message. \see SendReply(uint32 command, BHandler *replyTo) @@ -517,12 +519,13 @@ \brief Synchronously send a reply to this message, and wait for a reply back. - This method sends a reply to this message to the sender. The \a reply is - delivered, and then the method waits for a reply from the receiver. If a - reply is received, that reply is copied into the \a replyToReply argument. + This method sends a reply to this message to the sender. The + \a reply is delivered, and then the method waits for a reply from + the receiver. If a reply is received, that reply is copied into the + \a replyToReply argument. If the message was delivered properly, but the receiver did not reply - within the specified \a replyTimeout, the \c what member of \a replyToReply - will be set to \c B_NO_REPLY. + within the specified \a replyTimeout, the \a what member of + \a replyToReply will be set to \c B_NO_REPLY. \param reply The message that is in reply to this message. \param[out] replyToReply The reply is copied into this argument. @@ -535,10 +538,12 @@ \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. - \retval B_BAD_VALUE Either \a reply or \a replyToReply is \c NULL. + \retval B_BAD_VALUE Either \a reply or \a replyToReply is + \c NULL. \retval B_BAD_PORT_ID The reply address is not valid (anymore). - \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT - (zero) and the target port was full when trying to deliver the message. + \retval B_WOULD_BLOCK The delivery \a timeout was + \c B_INFINITE_TIMEOUT (\c 0) and the target port was full when trying + to deliver the message. \retval B_TIMED_OUT The timeout expired while trying to deliver the message. \retval B_NO_MORE_PORTS All reply ports are in use. @@ -721,20 +726,23 @@ const void *data, ssize_t numBytes, bool isFixedSize, int32 count) \brief Add \a data of a certain \a type to the message. - The amount of \a numBytes is copied into the message. The data is stored - at the label specified in \a name. You are responsible for specifying the - correct \a type. The Haiku API already specifies many constants, such as - B_FLOAT_TYPE or B_RECT_TYPE. See TypeConstants.h for more information on - the system-wide defined types. + The amount of \a numBytes is copied into the message. The data is + stored at the label specified in \a name. You are responsible for + specifying the correct \a type. The Haiku API already specifies + many constants, such as \c B_FLOAT_TYPE or \c B_RECT_TYPE. See + TypeConstants.h for more information on the system-wide defined types. - If the field with the \a name already exists, the data is added in an - array-like form. If you are adding a certain \a name for the first time, - you are able to specify some properties of this array. You can fix the size - of each data entry, and you can also instruct BMessage to allocate a - \a count of items. The latter does not mean that the number of items is - fixed; the array will grow nonetheless. Also, note that every \a name can - only be associated with one \a type of data. If consecutive method calls - specify a different \a type than the initial, these calls will fail. + If the field with the \a name already exists, the data is added in + an array-like form. If you are adding a certain \a name for the + first time, you are able to specify some properties of this array. You can + fix the size of each data entry, and you can also instruct BMessage to + allocate a \a count of items. The latter does not mean that the + number of items is fixed; the array will grow nonetheless. Also, note that + every \a name can only be associated with one \a type of + data. + + If consecutive method calls specify a different \a type than the + initial, these calls will fail. There is no limit to the number of labels, or the amount of data, but note that searching of data members is linear, as well as that some @@ -742,31 +750,32 @@ data you need to pass is too big, find another way to pass it. \param name The label to which this data needs to be associated. If the - \a name already exists, the new data will be added in an array-like - style. - \param type The type of data. If you are adding data to the same \a name, - make sure it is the same type. + \a name already exists, the new data will be added in an + array-like style. + \param type The type of data. If you are adding data to the same + \a name, make sure it is the same type. \param data The data buffer to copy the bytes from. \param numBytes The number of bytes to be copied. If this is the first call - to this method for this type of data, and you set \a isFixedSize to - \c true, this will specify the size of all consecutive calls to this + to this method for this type of data, and you set + \a isFixedSize to \c true, this will specify the size of all + consecutive calls to this method. \param isFixedSize If this is the first call to this method with this - \a name, you can specify the whether or not all items in this array - should have the same fixed size. + \a name, you can specify the whether or not all items in this + array should have the same fixed size. \param count If this is the first call to this method with this - \a name, you can instruct this message to allocate a number of items in - advance. This does not limit the amount of items though. The array will - grow if needed. + \a name, you can instruct this message to allocate a number of + items in advance. This does not limit the amount of items though. The + array will grow if needed. \retval B_OK The \a data is succesfully added. - \retval B_BAD_VALUE The \a numBytes is less than, or equal to zero (0), or - the size of this item is larger than the \a name allows, since it has - been specified to have a fixed size. + \retval B_BAD_VALUE The \a numBytes is less than, or equal to \c 0, + or the size of this item is larger than the \a name allows, + since it has been specified to have a fixed size. \retval B_ERROR There was an error whilst creating the label with your \a name. - \retval B_BAD_TYPE The \a type you specified is different than the one - already associated with \a name. + \retval B_BAD_TYPE The \a type you specified is different than the + one already associated with \a name. */ @@ -959,7 +968,8 @@ /*! \fn status_t BMessage::AddRef(const char *name, const entry_ref *ref) - \brief Convenience method to add an \c entry_ref to the label \a name. + \brief Convenience method to add an \c entry_ref to the label + \a name. This method calls AddData() with the \c B_REF_TYPE \a type. @@ -992,9 +1002,9 @@ This method uses BFlattenable::TypeCode() to determine the type. It also uses BFlattenable::IsFixedSize() to determine whether or not the size of - the object is supposedly always the same. You can specify a \a count, to - pre-allocate more entries if you are going to add more than one of this - type. + the object is supposedly always the same. You can specify a + \a count, to pre-allocate more entries if you are going to add + more than one of this type. \param name The label to associate the data with. \param object The object to flatten into the message. @@ -1019,7 +1029,8 @@ /*! \fn status_t BMessage::RemoveData(const char *name, int32 index) - \brief Remove data associated with \a name at a specified \a index. + \brief Remove data associated with \a name at a specified + \a index. If this is the only instance of the data, then the entire label will be removed. This means you can recreate it with another type. @@ -1027,10 +1038,10 @@ \param name The \a name of which the associated data should be cleared. \param index The \a index of the item that should be cleared. \retval B_OK The data has been removed. - \retval B_BAD_VALUE The \a index is less than zero (0). + \retval B_BAD_VALUE The \a index is less than \c 0. \retval B_BAD_INDEX The \a index is out of bounds. - \retval B_NAME_NOT_FOUND The \a name does not hava any data associated with - it. + \retval B_NAME_NOT_FOUND The \a name does not hava any data + associated with it. \see RemoveName() \see MakeEmpty() */ @@ -1043,7 +1054,8 @@ This also removes the label, so that you can recreate it with another type, if you want to. - \param name The \a name that refers to the data you want to clear out. + \param name The \a name that refers to the data you want to clear + out. \retval B_OK All the data is removed. \retval B_BAD_VALUE The \a name pointer points to \c NULL. \retval B_NAME_NOT_FOUND The \a name does not exist in this message. @@ -1059,7 +1071,7 @@ Everything is cleared out, all labels and all associated data, as well as metadata such as reply info. - \return This method always returns B_OK. + \return This method always returns \c B_OK. \see RemoveData() \see RemoveName() */ @@ -1079,7 +1091,7 @@ - +
Type of dataType codeMethod
BRectB_RECT_TYPEFindRect()
BRect\c B_RECT_TYPEFindRect()
*/ @@ -1090,12 +1102,14 @@ /*! \fn status_t BMessage::FindData(const char *name, type_code type, int32 index, const void **data, ssize_t *numBytes) const - \brief Find \a data that is stored in this message at an \a index. + \brief Find \a data that is stored in this message at an + \a index. - This method matches the label \a name with the \a type you are asking for, - and it looks for the data that is stored at a certain \a index number. If - all these things match, you will get a pointer to the internal buffer, and - the method will put the size of the item in \a numBytes. + This method matches the label \a name with the \a type you + are asking for, and it looks for the data that is stored at a certain + \a index number. If all these things match, you will get a pointer + to the internal buffer, and the method will put the size of the item in + \a numBytes. Note that only this method, and FindString(const char *, const char **), pass a pointer to the internal buffer. The other more specific methods, @@ -1110,8 +1124,8 @@ Note that the array is zero-based. \param[out] data A pointer to a pointer where the data can point to. \param[out] numBytes The size of the data will be put in this parameter. - \retval B_OK The \a name was found, matches the type, and the data at - \a index has been put in \a data. + \retval B_OK The \a name was found, matches the type, and the data + at \a index has been put in \a data. \retval B_BAD_VALUE One of the output arguments were \c NULL. \retval B_BAD_INDEX The \a index does not exist. \retval B_NAME_NOT_FOUND There is no field with this \a name. @@ -1125,8 +1139,9 @@ const void **data, ssize_t *numBytes) const \brief Find \a data that is stored in this message. - This is an overloaded method of FindData(const char *, type_code, int32, - const void **, ssize_t *) const, where data is sought at \a index 0. + This is an overloaded method of + FindData(const char *, type_code, int32, const void **, ssize_t *) const + where data is sought at \a index \c 0. */ @@ -1134,8 +1149,9 @@ \fn status_t BMessage::FindRect(const char *name, BRect *rect) const \brief Find a rectangle at the label \a name. - This is an overloaded method of FindRect(const char *, int32, BRect *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindRect(const char *, int32, BRect *) const + where the data is sought at \a index \c 0. */ @@ -1143,7 +1159,7 @@ \fn status_t BMessage::FindRect(const char *name, int32 index, BRect *rect) const \brief Find a rectangle at the label \a name at an \a index. - This method looks for the data with the \a B_RECT_TYPE, and copies it into + This method looks for the data with the \c B_RECT_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1160,8 +1176,9 @@ \fn status_t BMessage::FindPoint(const char *name, BPoint *point) const \brief Find a point at the label \a name. - This is an overloaded method of FindPoint(const char *, int32, BPoint *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindPoint(const char *, int32, BPoint *) const + where the data is sought at \a index \c 0. */ @@ -1169,7 +1186,7 @@ \fn status_t BMessage::FindPoint(const char *name, int32 index, BPoint *point) const \brief Find a point at the label \a name at an \a index. - This method looks for the data with the \a B_POINT_TYPE, and copies it into + This method looks for the data with the \c B_POINT_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1186,8 +1203,9 @@ \fn status_t BMessage::FindString(const char *name, const char **string) const \brief Find a string at the label \a name. - This is an overloaded method of FindString(const char *, int32, const char **) const - where the data is sought at \a index zero. + This is an overloaded method of + FindString(const char *, int32, const char **) const + where the data is sought at \a index \c 0. */ @@ -1196,7 +1214,7 @@ const char ** string) const \brief Find a string at the label \a name at an \a index. - This method looks for the data with the \a B_STRING_TYPE, and returns a + This method looks for the data with the \c B_STRING_TYPE, and returns a pointer to the internal buffer of the message. Note that this pointer is valid, until the message is deleted. @@ -1215,17 +1233,17 @@ \fn status_t BMessage::FindString(const char *name, BString *string) const \brief Find a string at the label \a name. - This is an overloaded method of FindString(const char *, int32, BString *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindString(const char *, int32, BString *) const + where the data is sought at \a index \c 0. */ /*! - \fn status_t BMessage::FindString(const char *name, int32 index, - BString *string) const + \fn status_t BMessage::FindString(const char *name, int32 index, BString *string) const \brief Find a string at the label \a name at an \a index. - This method looks for the data with the \a B_STRING_TYPE, and copies it + This method looks for the data with the \c B_STRING_TYPE, and copies it into the \a string object. \param name The label to which the data is associated. @@ -1244,7 +1262,7 @@ \brief Find an integer at the label \a name. This is an overloaded method of FindInt8(const char *, int32, int8 *) const - where the data is sought at \a index zero. + where the data is sought at \a index \c 0. */ @@ -1252,7 +1270,7 @@ \fn status_t BMessage::FindInt8(const char *name, int32 index, int8 *value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \a B_INT8_TYPE, and copies it into + This method looks for the data with the \c B_INT8_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1270,7 +1288,7 @@ \brief Find an integer at the label \a name. This is an overloaded method of FindInt8(const char *, int32, int16 *) const - where the data is sought at \a index zero. + where the data is sought at \a index \c 0. */ @@ -1278,7 +1296,7 @@ \fn status_t BMessage::FindInt16(const char *name, int32 index, int16 *value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \a B_INT16_TYPE, and copies it into + This method looks for the data with the \c B_INT16_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1295,8 +1313,9 @@ \fn status_t BMessage::FindInt32(const char *name, int32 *value) const \brief Find an integer at the label \a name. - This is an overloaded method of FindInt32(const char *, int32, int32 *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindInt32(const char *, int32, int32 *) const + where the data is sought at \a index \c 0. */ @@ -1304,7 +1323,7 @@ \fn status_t BMessage::FindInt32(const char *name, int32 index, int32 *value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \a B_INT32_TYPE, and copies it into + This method looks for the data with the \c B_INT32_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1321,8 +1340,9 @@ \fn status_t BMessage::FindInt64(const char *name, int64 *value) const \brief Find an integer at the label \a name. - This is an overloaded method of FindInt64(const char *, int32, int64 *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindInt64(const char *, int32, int64 *) const + where the data is sought at \a index \c 0. */ @@ -1330,7 +1350,7 @@ \fn status_t BMessage::FindInt64(const char *name, int32 index, int64 *value) const \brief Find an integer at the label \a name at an \a index. - This method looks for the data with the \a B_INT64_TYPE, and copies it into + This method looks for the data with the \c B_INT64_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1347,8 +1367,9 @@ \fn status_t BMessage::FindBool(const char *name, bool *value) const \brief Find a boolean at the label \a name. - This is an overloaded method of FindBool(const char *, int32, bool *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindBool(const char *, int32, bool *) const + where the data is sought at \a index \c 0. */ @@ -1356,7 +1377,7 @@ \fn status_t BMessage::FindBool(const char *name, int32 index, bool *value) const \brief Find a boolean at the label \a name at an \a index. - This method looks for the data with the \a B_BOOL_TYPE, and copies it into + This method looks for the data with the \c B_BOOL_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1373,8 +1394,9 @@ \fn status_t BMessage::FindFloat(const char *name, float *value) const \brief Find a float at the label \a name. - This is an overloaded method of FindFloat(const char *, int32, float *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindFloat(const char *, int32, float *) const + where the data is sought at \a index \c 0. */ @@ -1382,7 +1404,7 @@ \fn status_t BMessage::FindFloat(const char *name, int32 index, float *value) const \brief Find a float at the label \a name at an \a index. - This method looks for the data with the \a B_FLOAT_TYPE, and copies it into + This method looks for the data with the \c B_FLOAT_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1399,8 +1421,9 @@ \fn status_t BMessage::FindDouble(const char *name, double *value) const \brief Find a double at the label \a name. - This is an overloaded method of FindDouble(const char *, int32, double *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindDouble(const char *, int32, double *) const + where the data is sought at \a index \c 0. */ @@ -1408,7 +1431,7 @@ \fn status_t BMessage::FindDouble(const char *name, int32 index, double *value) const \brief Find a double at the label \a name at an \a index. - This method looks for the data with the \a B_DOUBLE_TYPE, and copies it into + This method looks for the data with the \c B_DOUBLE_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1425,16 +1448,17 @@ \fn status_t BMessage::FindPointer(const char *name, void **pointer) const \brief Find a pointer at the label \a name. - This is an overloaded method of FindPointer(const char *, int32, void *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindPointer(const char *, int32, void *) const + where the data is sought at \a index \c 0. */ /*! - \fn status_t BMessage::FindPointer(const char *name, int32 index, void **pointer) const + \fn status_t BMessage::FindPointer(const char *name, int32 index, void **pointer) const \brief Find a pointer at the label \a name at an \a index. - This method looks for the data with the \a B_POINTER_TYPE, and copies it into + This method looks for the data with the \c B_POINTER_TYPE, and copies it into a provided buffer. \warning If you want to share objects between applications, please remember @@ -1457,18 +1481,18 @@ \fn status_t BMessage::FindMessenger(const char *name, BMessenger *messenger) const \brief Find a messenger at the label \a name. - This is an overloaded method of FindMessenger(const char *, int32, BMessenger *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindMessenger(const char *, int32, BMessenger *) const + where the data is sought at \a index \c 0. */ /*! - \fn status_t BMessage::FindMessenger(const char *name, int32 index, - BMessenger *messenger) const + \fn status_t BMessage::FindMessenger(const char *name, int32 index, BMessenger *messenger) const \brief Find a messenger at the label \a name at an \a index. - This method looks for the data with the \a B_MESSENGER_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_MESSENGER_TYPE, and copies it + into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1484,16 +1508,18 @@ \fn status_t BMessage::FindRef(const char *name, entry_ref *ref) const \brief Find a reference to a file at the label \a name. - This is an overloaded method of FindRef(const char *, int32, entry_ref *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindRef(const char *, int32, entry_ref *) const + where the data is sought at \a index \c 0. */ /*! \fn status_t BMessage::FindRef(const char *name, int32 index, entry_ref *ref) const - \brief Find a reference to a file at the label \a name at an \a index. + \brief Find a reference to a file at the label \a name at an + \a index. - This method looks for the data with the \a B_REF_TYPE, and copies it into + This method looks for the data with the \c B_REF_TYPE, and copies it into a provided buffer. \param name The label to which the data is associated. @@ -1510,18 +1536,18 @@ \fn status_t BMessage::FindMessage(const char *name, BMessage *message) const \brief Find a message at the label \a name. - This is an overloaded method of FindMessage(const char *, int32, BMessage *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindMessage(const char *, int32, BMessage *) const + where the data is sought at \a index \c 0. */ /*! - \fn status_t BMessage::FindMessage(const char *name, int32 index, - BMessage *message) const + \fn status_t BMessage::FindMessage(const char *name, int32 index, BMessage *message) const \brief Find a message at the label \a name at an \a index. - This method looks for the data with the \a B_MESSAGE_TYPE, and copies it into - a provided buffer. + This method looks for the data with the \c B_MESSAGE_TYPE, and copies it + into a provided buffer. \param name The label to which the data is associated. \param index The index from which the data should be copied. @@ -1537,15 +1563,17 @@ \fn status_t BMessage::FindFlat(const char *name, BFlattenable *object) const \brief Find a flattened object at the label \a name. - This is an overloaded method of FindFlat(const char *, int32, BFlattenable *) const - where the data is sought at \a index zero. + This is an overloaded method of + FindFlat(const char *, int32, BFlattenable *) const + where the data is sought at \a index \c 0. */ /*! \fn status_t BMessage::FindFlat(const char *name, int32 index, BFlattenable *object) const - \brief Find a flattened object at the label \a name at an \a index. + \brief Find a flattened object at the label \a name at an + \a index. The type is determined by the type of the passed object. If that type is available at the specified label, then the Unflatten() method of that @@ -1579,18 +1607,21 @@ const void *data, ssize_t numBytes) \brief Replace the data at label \a name. - This method is an overloaded method that replaces the data at \a index - zero. See ReplaceData(const char *, type_code, int32, const void *, ssize_t). + This method is an overloaded method that replaces the data at + \a index \c 0. See + ReplaceData(const char *, type_code, int32, const void *, ssize_t). */ /*! \fn status_t BMessage::ReplaceData(const char *name, type_code type, int32 index, const void *data, ssize_t numBytes) - \brief Replace the data at label \a name at a specified \a index. + \brief Replace the data at label \a name at a specified + \a index. - The conditions for replacing data are that the \a name is correct, the - \a type matches and the data entry at \a index exists. + The conditions for replacing data are that the\a name is correct, + the \a type matches and the data entry at \a index + exists. There is also a collection of convenience methods, that allow you to efficiently replace rectanges (ReplaceRect()), booleans (ReplaceBool()), @@ -1615,17 +1646,19 @@ \fn status_t BMessage::ReplaceRect(const char *name, BRect aRect) \brief Replace a rectangle at the label \a name. - This method is an overloaded method of ReplaceRect(const char *, int32, BRect). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceRect(const char *, int32, BRect). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceRect(const char *name, int32 index, BRect aRect) - \brief Replace a rectangle at the label \a name at a specified \a index. + \brief Replace a rectangle at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_RECT_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_RECT_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param aRect The object to store in the message. @@ -1639,17 +1672,19 @@ \fn status_t BMessage::ReplacePoint(const char *name, BPoint aPoint) \brief Replace a point at the label \a name. - This method is an overloaded method of ReplacePoint(const char *, int32, BPoint). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplacePoint(const char *, int32, BPoint). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplacePoint(const char *name, int32 index, BPoint aPoint) - \brief Replace a point at the label \a name at a specified \a index. + \brief Replace a point at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_POINT_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_POINT_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param aPoint The object to store in the message. @@ -1663,17 +1698,19 @@ \fn status_t BMessage::ReplaceString(const char *name, const char *aString) \brief Replace a string at the label \a name. - This method is an overloaded method of ReplaceString(const char *, int32, const char *). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceString(const char *, int32, const char *). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceString(const char *name, int32 index, const char *aString) - \brief Replace a string at the label \a name at a specified \a index. + \brief Replace a string at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_STRING_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_STRING_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param aString The object to store in the message. @@ -1687,17 +1724,19 @@ \fn status_t BMessage::ReplaceString(const char *name, const BString &aString) \brief Replace a string at the label \a name. - This method is an overloaded method of ReplaceString(const char *, int32, BString &). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceString(const char *, int32, BString &). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceString(const char *name, int32 index, const BString &aString) - \brief Replace a string at the label \a name at a specified \a index. + \brief Replace a string at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_STRING_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_STRING_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param aString The object to store in the message. @@ -1711,17 +1750,19 @@ \fn status_t BMessage::ReplaceInt8(const char *name, int8 value) \brief Replace an integer at the label \a name. - This method is an overloaded method of ReplaceInt8(const char *, int32, int8). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceInt8(const char *, int32, int8). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceInt8(const char *name, int32 index, int8 value) - \brief Replace an integer at the label \a name at a specified \a index. + \brief Replace an integer at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_INT8_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_INT8_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param value The object to store in the message. @@ -1735,17 +1776,19 @@ \fn status_t BMessage::ReplaceInt16(const char *name, int16 value) \brief Replace an integer at the label \a name. - This method is an overloaded method of ReplaceInt16(const char *, int32, int16). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceInt16(const char *, int32, int16). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceInt16(const char *name, int32 index, int16 value) - \brief Replace an integer at the label \a name at a specified \a index. + \brief Replace an integer at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_INT16_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_INT16_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param value The object to store in the message. @@ -1759,17 +1802,19 @@ \fn status_t BMessage::ReplaceInt32(const char *name, int32 value) \brief Replace an integer at the label \a name. - This method is an overloaded method of ReplaceInt8(const char *, int32, int32). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceInt8(const char *, int32, int32). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceInt32(const char *name, int32 index, int32 value) - \brief Replace an integer at the label \a name at a specified \a index. + \brief Replace an integer at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_INT32_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_INT32_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param value The object to store in the message. @@ -1783,17 +1828,19 @@ \fn status_t BMessage::ReplaceInt64(const char *name, int64 value) \brief Replace an integer at the label \a name. - This method is an overloaded method of ReplaceInt8(const char *, int32, int64). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceInt8(const char *, int32, int64). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceInt64(const char *name, int32 index, int64 value) - \brief Replace an integer at the label \a name at a specified \a index. + \brief Replace an integer at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_INT64_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_INT64_TYPE. \param name The name associated with the data to replace. \param index The index in the array to replace. \param value The object to store in the message. @@ -1807,17 +1854,20 @@ \fn status_t BMessage::ReplaceBool(const char *name, bool aBoolean) \brief Replace a boolean at the label \a name. - This method is an overloaded method of ReplaceBool(const char *, int32, bool). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceBool(const char *, int32, bool). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceBool(const char *name, int32 index, bool aBoolean) - \brief Replace a boolean at the label \a name at a specified \a index. + \brief Replace a boolean at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_BOOL_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_BOOL_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param aBoolean The object to store in the message. @@ -1831,17 +1881,20 @@ \fn status_t BMessage::ReplaceFloat(const char *name, float aFloat) \brief Replace a float at the label \a name. - This method is an overloaded method of ReplaceFloat(const char *, int32, float). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceFloat(const char *, int32, float). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceFloat(const char *name, int32 index, float aFloat) - \brief Replace a float at the label \a name at a specified \a index. + \brief Replace a float at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_FLOAT_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_FLOAT_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param aFloat The object to store in the message. @@ -1855,17 +1908,20 @@ \fn status_t BMessage::ReplaceDouble(const char *name, double aDouble) \brief Replace a double at the label \a name. - This method is an overloaded method of ReplaceDouble(const char *, int32, double). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceDouble(const char *, int32, double). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceDouble(const char *name, int32 index, double aDouble) - \brief Replace a double at the label \a name at a specified \a index. + \brief Replace a double at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_DOUBLE_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_DOUBLE_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param aDouble The object to store in the message. @@ -1879,17 +1935,19 @@ \fn status_t BMessage::ReplacePointer(const char *name, const void *pointer) \brief Replace a pointer at the label \a name. - This method is an overloaded method of ReplacePointer(const char *, int32, const void *). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplacePointer(const char *, int32, const void *). + It replaces the data at \a index \c 0. */ /*! - \fn status_t BMessage::ReplacePointer(const char *name,int32 index,const void *pointer) + \fn status_t BMessage::ReplacePointer(const char *name,int32 index, const void *pointer) \brief Replace a pointer at the label \a name at a specified \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_POINTER_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_POINTER_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param pointer The object to store in the message. @@ -1903,17 +1961,20 @@ \fn status_t BMessage::ReplaceMessenger(const char *name, BMessenger messenger) \brief Replace a messenger at the label \a name. - This method is an overloaded method of ReplaceMessenger(const char *, int32, BMessenger). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceMessenger(const char *, int32, BMessenger). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceMessenger(const char *name, int32 index, BMessenger messenger) - \brief Replace a messenger at the label \a name at a specified \a index. + \brief Replace a messenger at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_MESSENGER_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_MESSENGER_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param messenger The object to store in the message. @@ -1927,18 +1988,20 @@ \fn status_t BMessage::ReplaceRef(const char *name,const entry_ref *ref) \brief Replace a reference to a file at the label \a name. - This method is an overloaded method of ReplaceRef(const char *, int32, entry_ref *). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceRef(const char *, int32, entry_ref *). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceRef( const char *name, int32 index, const entry_ref *ref) - \brief Replace a reference to a file at the label \a name at a specified - \a index. + \brief Replace a reference to a file at the label \a name at a + specified \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_REF_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_REF_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param ref The object to store in the message. @@ -1952,17 +2015,20 @@ \fn status_t BMessage::ReplaceMessage(const char *name, const BMessage *message) \brief Replace a message at the label \a name. - This method is an overloaded method of ReplaceMessage(const char *, int32, BMessage *). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceMessage(const char *, int32, BMessage *). + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceMessage(const char *name, int32 index, const BMessage *message) - \brief Replace a message at the label \a name at a specified \a index. + \brief Replace a message at the label \a name at a specified + \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the \c B_MESSAGE_TYPE. + The data at the specified \a name and \a index will be + replaced, if it matches the \c B_MESSAGE_TYPE. + \param name The name associated with the data to replace. \param index The index in the array to replace. \param message The object to store in the message. @@ -1976,25 +2042,29 @@ \fn status_t BMessage::ReplaceFlat(const char *name, BFlattenable *object) \brief Replace a flattened object at the label \a name. - This method is an overloaded method of ReplaceFlat(const char *, int32, BFlattenable *). - It replaces the data at \a index zero. + This method is an overloaded method of + ReplaceFlat(const char *, int32, BFlattenable *). + + It replaces the data at \a index \c 0. */ /*! \fn status_t BMessage::ReplaceFlat(const char *name, int32 index, BFlattenable *object) - \brief Replace a flattened object at the label \a name at a specified - \a index. + \brief Replace a flattened object at the label \a name at a + specified \a index. - The data at the specified \a name and \a index will be replaced, if it - matches the type returned by your object. This method uses + The data at the specified \a name and \a index will be + replaced, if it matches the type returned by your object. This method uses BFlattenable::TypeCode() to determine the type of the object. \param name The name associated with the data to replace. \param index The index in the array to replace. \param object The object to store in the message. + \retval B_OK The operation succeeded. \retval B_BAD_INDEX The index was out of range. + \see ReplaceFlat(const char*, BFlattenable *) */ @@ -2005,9 +2075,9 @@ /*! \name Deprecated methods - These methods are very likely to disappear, and they have been - replaced by safer and more powerful methods. These methods are still - implemented for binary compatibility, but they are not documented. + These methods are \e very likely to disappear, and they have been replaced + by safer and more powerful methods. These methods are still implemented + for binary compatibility, but they are not documented. */ diff --git a/docs/user/book.css b/docs/user/book.css index 0ef01740a7..42c2079a55 100644 --- a/docs/user/book.css +++ b/docs/user/book.css @@ -186,6 +186,24 @@ div.contents { background: #ffeae6 url(images/alert_stop_32.png) 15px 15px no-repeat; } + +/* For keyboard shortcuts and the like (also from userguide) */ + +div.contents span.keycap { + -webkit-border-radius: 3px; + -khtml-border-radius: 3px; + -moz-border-radius: 3px; + border-radius: 3px; + border-color: #c7c7c7; + border-style: solid; + border-width: 1px; + padding: 0px 2px 0px 2px; + background-color: #e8e8e8; + font-family: serif; + font-variant: small-caps; +} + + /* Continue with the rest of the standard Doxygen stuff... */ CAPTION { font-weight: bold } diff --git a/docs/user/book.dox b/docs/user/book.dox index cb23cc1697..d5d392e3ad 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -7,8 +7,10 @@ - \ref drivers - \ref interface | \link interface_intro \em Introduction \endlink - \ref locale | \link locale_intro \em Introduction \endlink + - \ref media | \link media_intro \em Introduction \endlink - \ref midi1 - \ref midi2 | \link midi2_intro \em Introduction \endlink + - \ref storage | \link storage_intro \em Introduction \endlink - \ref support | \link support_intro \em Introduction \endlink \section notes General Notes and Information diff --git a/docs/user/drivers/USB3.dox b/docs/user/drivers/USB3.dox index 4f1f0e3d4e..b617a7de48 100644 --- a/docs/user/drivers/USB3.dox +++ b/docs/user/drivers/USB3.dox @@ -9,218 +9,218 @@ */ /*! - \file USB3.h - \ingroup drivers - \brief Interface for the USB module. + \file USB3.h + \ingroup drivers + \brief Interface for the USB module. */ /*! - \typedef struct usb_module_info usb_module_info - \brief The main interface object. See the usb_module_info documentation. + \typedef struct usb_module_info usb_module_info + \brief The main interface object. See the usb_module_info documentation. */ /*! - \typedef uint32 usb_id - \brief Uniquely identify various USB objects that are used in the module. + \typedef uint32 usb_id + \brief Uniquely identify various USB objects that are used in the module. */ /*! - \typedef usb_id usb_device - \brief Uniquely identify USB devices. + \typedef usb_id usb_device + \brief Uniquely identify USB devices. */ /*! - \typedef usb_id usb_interface - \brief Uniquely identify USB interfaces. + \typedef usb_id usb_interface + \brief Uniquely identify USB interfaces. */ /*! - \typedef usb_id usb_pipe - \brief Uniquely identify USB pipes. + \typedef usb_id usb_pipe + \brief Uniquely identify USB pipes. */ /*! - \typedef struct usb_endpoint_info usb_endpoint_info - \brief Container for USB endpoint descriptors. - \see Documentation for usb_endpoint_info. + \typedef struct usb_endpoint_info usb_endpoint_info + \brief Container for USB endpoint descriptors. + \see Documentation for usb_endpoint_info. */ /*! - \typedef struct usb_interface_info usb_interface_info - \brief Container for USB interface descriptors. - \see Documentation for usb_interface_info. + \typedef struct usb_interface_info usb_interface_info + \brief Container for USB interface descriptors. + \see Documentation for usb_interface_info. */ /*! - \typedef struct usb_interface_list usb_interface_list - \brief Container that holds a list of USB interface descriptors. - \see Documentation for usb_interface_list. + \typedef struct usb_interface_list usb_interface_list + \brief Container that holds a list of USB interface descriptors. + \see Documentation for usb_interface_list. */ /*! - \typedef struct usb_configuration_info usb_configuration_info - \brief Container for USB configuration descriptors. - \see Documentation for usb_configuration_info. + \typedef struct usb_configuration_info usb_configuration_info + \brief Container for USB configuration descriptors. + \see Documentation for usb_configuration_info. */ ///// usb_notify_hooks ///// /*! - \struct usb_notify_hooks - \brief Hooks that the USB stack can callback in case of events. + \struct usb_notify_hooks + \brief Hooks that the USB stack can callback in case of events. */ /*! - \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie) - \brief Called by the stack in case a device is added. - - Once you have registered hooks using the - usb_module_info::install_notify() method, this hook will be called as soon as - a device is inserted that matches your provided usb_support_descriptor. - - \param device A unique id that identifies this USB device. - \param[in] cookie You can store a pointer to an object in this variable. - When the device is removed, this cookie will be provided to you. - \return You should return \c B_OK in case of success. The USB stack will then - request the kernel to republish your device names so that the new device - will be shown in the \c /dev tree. If you return an error value, the - \a device id will become invalid and you will not be notified if this - device is removed. - \see device_removed() + \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie) + \brief Called by the stack in case a device is added. + + Once you have registered hooks using the + usb_module_info::install_notify() method, this hook will be called as soon as + a device is inserted that matches your provided usb_support_descriptor. + + \param device A unique id that identifies this USB device. + \param[in] cookie You can store a pointer to an object in this variable. + When the device is removed, this cookie will be provided to you. + \return You should return \c B_OK in case of success. The USB stack will then + request the kernel to republish your device names so that the new device + will be shown in the \c /dev tree. If you return an error value, the + \a device id will become invalid and you will not be notified if this + device is removed. + \see device_removed() */ /*! - \var status_t (*usb_notify_hooks::device_removed)(void *cookie) - \brief Called by the stack in case a device you are using is removed. - - If you have accepted a device in the device_added() hook, this hook will - be called as soon as the device is removed. - - \param cookie The cookie you provided in the device_added() hook. Make sure - that you free the cookie if necessary. - \return Currently the return value of this hook is ignored. It is recommended - to return \c B_OK though. + \var status_t (*usb_notify_hooks::device_removed)(void *cookie) + \brief Called by the stack in case a device you are using is removed. + + If you have accepted a device in the device_added() hook, this hook will + be called as soon as the device is removed. + + \param cookie The cookie you provided in the device_added() hook. Make sure + that you free the cookie if necessary. + \return Currently the return value of this hook is ignored. It is recommended + to return \c B_OK though. */ - + ///// usb_support_descriptor ///// - + /*! - \struct usb_support_descriptor - \brief Description of device descriptor that the driver can handle. - - Support descriptors can be used to match any form of class, subclass or - protocol, or they can be used to match a vendor and/or product. - If any field has the value \c 0, it is treated as a wildcard. - - For example, if you want to watch for all the hubs, which have a device - class of \c 0x09, you would pass this descriptor: - - \code - usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; - \endcode - - See usb_module_info::register_driver() for more information on how to use - this object. + \struct usb_support_descriptor + \brief Description of device descriptor that the driver can handle. + + Support descriptors can be used to match any form of class, subclass or + protocol, or they can be used to match a vendor and/or product. + If any field has the value \c 0, it is treated as a wildcard. + + For example, if you want to watch for all the hubs, which have a device + class of \c 0x09, you would pass this descriptor: + + \code + usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; + \endcode + + See usb_module_info::register_driver() for more information on how to use + this object. */ - + /*! - \var usb_support_descriptor::dev_class - \brief The supported device classes. + \var usb_support_descriptor::dev_class + \brief The supported device classes. */ /*! - \var usb_support_descriptor::dev_subclass - \brief The supported device subclasses. + \var usb_support_descriptor::dev_subclass + \brief The supported device subclasses. */ /*! - \var usb_support_descriptor::dev_protocol - \brief The supported device protocols. + \var usb_support_descriptor::dev_protocol + \brief The supported device protocols. */ /*! - \var usb_support_descriptor::vendor - \brief The supported device vendor. + \var usb_support_descriptor::vendor + \brief The supported device vendor. */ /*! - \var usb_support_descriptor::product - \brief The supported device products. + \var usb_support_descriptor::product + \brief The supported device products. */ ///// usb_endpoint_info ///// /*! - \struct usb_endpoint_info - \brief Container for endpoint descriptors and their Haiku USB stack - identifiers. + \struct usb_endpoint_info + \brief Container for endpoint descriptors and their Haiku USB stack + identifiers. */ /*! - \var usb_endpoint_descriptor *usb_endpoint_info::descr - \brief Pointer to the descriptor of the endpoint. + \var usb_endpoint_descriptor *usb_endpoint_info::descr + \brief Pointer to the descriptor of the endpoint. */ /*! - \var usb_pipe usb_endpoint_info::handle - \brief Handle to use when using the stack to transfer data to and from this - endpoint. + \var usb_pipe usb_endpoint_info::handle + \brief Handle to use when using the stack to transfer data to and from this + endpoint. */ ///// usb_interface_info ///// /*! - \struct usb_interface_info - \brief Container for interface descriptors and their Haiku USB stack - identifiers. + \struct usb_interface_info + \brief Container for interface descriptors and their Haiku USB stack + identifiers. */ //! @{ /*! - \var usb_interface_descriptor *usb_interface_info::descr - \brief Pointer to the descriptor of the interface. + \var usb_interface_descriptor *usb_interface_info::descr + \brief Pointer to the descriptor of the interface. */ /*! - \var usb_interface usb_interface_info::handle - \brief Handle to use when using the stack to manipulate this interface. + \var usb_interface usb_interface_info::handle + \brief Handle to use when using the stack to manipulate this interface. */ //! @} /*! - \name Endpoints + \name Endpoints */ //! @{ /*! - \var size_t usb_interface_info::endpoint_count - \brief The number of endpoints in this interface. + \var size_t usb_interface_info::endpoint_count + \brief The number of endpoints in this interface. */ /*! - \var usb_endpoint_info *usb_interface_info::endpoint - \brief An array of endpoints that are associated to this interface. + \var usb_endpoint_info *usb_interface_info::endpoint + \brief An array of endpoints that are associated to this interface. */ //! @} /*! - \name Unparsed descriptors + \name Unparsed descriptors */ //! @{ /*! - \var size_t usb_interface_info::generic_count - \brief The number of unparsed descriptors in this interface. + \var size_t usb_interface_info::generic_count + \brief The number of unparsed descriptors in this interface. */ /*! - \var usb_descriptor **usb_interface_info::generic - \brief Unparsed descriptors in this interface. + \var usb_descriptor **usb_interface_info::generic + \brief Unparsed descriptors in this interface. */ //! @} @@ -228,444 +228,447 @@ ///// usb_interface_list ///// /*! - \struct usb_interface_list - \brief List of interfaces available to a configuration. + \struct usb_interface_list + \brief List of interfaces available to a configuration. */ /*! - \var size_t usb_interface_list::alt_count - \brief Number of available interfaces. + \var size_t usb_interface_list::alt_count + \brief Number of available interfaces. */ /*! - \var usb_interface_info *usb_interface_list::alt - \brief Array of available interfaces. + \var usb_interface_info *usb_interface_list::alt + \brief Array of available interfaces. */ /*! - \var usb_interface_info *usb_interface_list::active - \brief Pointer to active interface. + \var usb_interface_info *usb_interface_list::active + \brief Pointer to active interface. */ ///// usb_configuration_info ///// /*! - \struct usb_configuration_info - \brief Container for a specific configuration descriptor of a device. + \struct usb_configuration_info + \brief Container for a specific configuration descriptor of a device. */ /*! - \var usb_configuration_descriptor *usb_configuration_info::descr - \brief The configuration descriptor. + \var usb_configuration_descriptor *usb_configuration_info::descr + \brief The configuration descriptor. */ /*! - \var size_t usb_configuration_info::interface_count - \brief The number of interfaces in this configuration. + \var size_t usb_configuration_info::interface_count + \brief The number of interfaces in this configuration. */ /*! - \var usb_interface_list *usb_configuration_info::interface - \brief The list of interfaces available to this configuration. + \var usb_interface_list *usb_configuration_info::interface + \brief The list of interfaces available to this configuration. */ ///// usb_iso_packet_descriptor ///// /*! - \struct usb_iso_packet_descriptor - \brief The descriptor for data packets of isochronous transfers. + \struct usb_iso_packet_descriptor + \brief The descriptor for data packets of isochronous transfers. */ /*! - \var int16 usb_iso_packet_descriptor::req_len - \brief Length of the request. + \var int16 usb_iso_packet_descriptor::request_length + \brief Length of the request. */ /*! - \var int16 usb_iso_packet_descriptor::act_len - \brief The USB stack writes the actual transferred length in this variable. + \var int16 usb_iso_packet_descriptor::actual_length + \brief The USB stack writes the actual transferred length in this variable. */ /*! - \var status_t usb_iso_packet_descriptor::status - \brief The status of the transfer. + \var status_t usb_iso_packet_descriptor::status + \brief The status of the transfer. */ - + ///// usb_callback_func ///// /*! - \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength) - \brief Callback function for asynchronous transfers. - - \param cookie The cookie you supplied when you queued the transfer. - \param status The status of the transfer. This is one of the following: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
B_OKThe transfer succeeded.
B_CANCELEDThe transfer was cancelled by the user - via a usb_module_info::cancel_queued_transfers() call.
B_DEV_MULTIPLE_ERRORSMore than one of the errors - below occurred. Unfortunately, the stack cannot give you more - information.
B_DEV_STALLEDThe endpoint is stalled. You can use - usb_module_info::clear_feature() method with the associated pipe and - the USB_FEATURE_ENDPOINT_HALT arguments.
B_DEV_DATA_OVERRUNIncoming transfer: more data - flowing in than the size of the buffer.
B_DEV_DATA_UNDERRUNOutgoing transfer: more data - is flowing out than the endpoint accepts.
B_DEV_CRC_ERRORThe internal data consistency - checks of the USB protocol failed. It is best to retry. If you keep - on getting this error there might be something wrong with the - device.
B_DEV_UNEXPECTED_PIDThere was an internal error. - You should retry your transfer.
B_DEV_FIFO_OVERRUNinternal error. - You should retry your transfer.
B_DEV_FIFO_UNDERRUNThere was an internal error. - You should retry your transfer.
- \param data The provided buffer. - \param actualLength The amount of bytes read or written during the transfer. + \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength) + \brief Callback function for asynchronous transfers. + \param cookie The cookie you supplied when you queued the transfer. + \param status The status of the transfer. This is one of the following: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
B_OKThe transfer succeeded.
B_CANCELEDThe transfer was cancelled by the user + via a usb_module_info::cancel_queued_transfers() call.
B_DEV_MULTIPLE_ERRORSMore than one of the errors + below occurred. Unfortunately, the stack cannot give you more + information.
B_DEV_STALLEDThe endpoint is stalled. You can + use usb_module_info::clear_feature() method with the associated pipe + and the USB_FEATURE_ENDPOINT_HALT arguments.
B_DEV_DATA_OVERRUNIncoming transfer: more data + flowing in than the size of the buffer.
B_DEV_DATA_UNDERRUNOutgoing transfer: more data + is flowing out than the endpoint accepts.
B_DEV_CRC_ERRORThe internal data consistency + checks of the USB protocol failed. It is best to retry. If you keep + on getting this error there might be something wrong with the + device.
B_DEV_UNEXPECTED_PIDThere was an internal error. + You should retry your transfer.
B_DEV_FIFO_OVERRUNinternal error. + You should retry your transfer.
B_DEV_FIFO_UNDERRUNThere was an internal error. + You should retry your transfer.
+ \param data The provided buffer. + \param actualLength The amount of bytes read or written during the transfer. */ ///// usb_module_info ///// /*! - \struct usb_module_info - \brief Interface for drivers to interact with Haiku's USB stack. + \struct usb_module_info + \brief Interface for drivers to interact with Haiku's USB stack. */ /*! - \var usb_module_info::binfo - \brief Instance of the bus_manager_info object. + \var usb_module_info::binfo + \brief Instance of the bus_manager_info object. */ /*! - \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName) - \brief Register your driver. - - To let the USB stack know that a driver is available to support devices, a - driver needs to register itself first. To let the stack know about devices - it needs to notify the driver of, have a look at usb_support_descriptor. - - It is possible to supply a list of support constructors. You should allocate - an array of support constructors and give the amount of constructors in the - array using the \a supportDescriptorCount parameter. - - In case your driver supports all devices or, more likely, you want to - monitor all devices plugged in and removed, it is safe to pass \c NULL to the - \a supportDescriptors paramater and zero (0) to \a supportDescriptorCount. - - \param driverName A unique name that identifies your driver. Avoid names like - \c webcam or \c mouse, instead use vendor names and device types to avoid - nameclashes. The install_notify() and uninstall_notify() functions use the - driver name as an identifier. - \param supportDescriptors An array of the type usb_support_descriptor. Pass - the amount of objects in the next parameter. - \param supportDescriptorCount The number of objects in the array supplied in - the previous parameter. - \param optionalRepublishDriverName Unused parameter. You should pass \c NULL. - \retval B_OK The driver is registered. You can now call install_notify() - \retval B_BAD_VALUE You passed \c NULL as \a driverName. - \retval B_ERROR General internal error in the USB stack. You may retry the - request in this case. - \retval B_NO_MEMORY Error allocating some internal objects. The system is - out of memory. + \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName) + \brief Register your driver. + + To let the USB stack know that a driver is available to support devices, a + driver needs to register itself first. To let the stack know about devices + it needs to notify the driver of, have a look at usb_support_descriptor. + + It is possible to supply a list of support constructors. You should allocate + an array of support constructors and give the amount of constructors in the + array using the \a supportDescriptorCount parameter. + + In case your driver supports all devices or, more likely, you want to + monitor all devices plugged in and removed, it is safe to pass \c NULL to + the \a supportDescriptors paramater and zero (0) to + \a supportDescriptorCount. + + \param driverName A unique name that identifies your driver. Avoid names + like \c webcam or \c mouse, instead use vendor names and device types to + avoid nameclashes. The install_notify() and uninstall_notify() functions use + the driver name as an identifier. + + \param supportDescriptors An array of the type usb_support_descriptor. Pass + the amount of objects in the next parameter. + \param supportDescriptorCount The number of objects in the array supplied in + the previous parameter. + \param optionalRepublishDriverName Unused parameter. You should pass + \c NULL. + + \retval B_OK The driver is registered. You can now call install_notify() + \retval B_BAD_VALUE You passed \c NULL as \a driverName. + \retval B_ERROR General internal error in the USB stack. You may retry the + request in this case. + \retval B_NO_MEMORY Error allocating some internal objects. The system is + out of memory. */ /*! - \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks) - \brief Install notify hooks for your driver. - - After your driver is registered, you need to pass hooks to your driver that - are called whenever a device that matches your \link usb_support_descriptor - support descriptor \endlink . - - As soon as the hooks are installed, you'll receive callbacks for devices that - are already attached; so make sure your driver is initialized properly when - calling this method. - - \param driverName The name you passed in register_driver(). - \param hooks The hooks the stack should call in case the status of devices - that match your support descriptor changes. - \retval B_OK Hooks are installed succesfully. - \retval B_NAME_NOT_FOUND Invalid \a driverName. - - \see usb_notify_hooks for information on how your hooks should behave. - \see uninstall_notify() + \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks) + \brief Install notify hooks for your driver. + + After your driver is registered, you need to pass hooks to your driver that + are called whenever a device that matches your \link usb_support_descriptor + support descriptor \endlink . + + As soon as the hooks are installed, you'll receive callbacks for devices + that are already attached; so make sure your driver is initialized properly + when calling this method. + + \param driverName The name you passed in register_driver(). + \param hooks The hooks the stack should call in case the status of devices + that match your support descriptor changes. + + \retval B_OK Hooks are installed succesfully. + \retval B_NAME_NOT_FOUND Invalid \a driverName. + + \see usb_notify_hooks for information on how your hooks should behave. + \see uninstall_notify() */ /*! - \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName) - \brief Uninstall notify hooks for your driver. - - If your driver needs to stop, you can uninstall the notifier hooks. This will - clear the stored hooks in the driver, and you will not receive any - notifications when new devices are attached. This method will also call - usb_notify_hooks::device_removed() for all the devices that you are using and - all the stack's resources that are allocated to your driver are cleared. - - \param driverName The name you passed in register_driver(). - \retval B_OK Hooks are uninstalled. - \retval B_NAME_NOT_FOUND Invalid \a driverName. + \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName) + \brief Uninstall notify hooks for your driver. + + If your driver needs to stop, you can uninstall the notifier hooks. This + will clear the stored hooks in the driver, and you will not receive any + notifications when new devices are attached. This method will also call + usb_notify_hooks::device_removed() for all the devices that you are using + and all the stack's resources that are allocated to your driver are + cleared. + + \param driverName The name you passed in register_driver(). + \retval B_OK Hooks are uninstalled. + \retval B_NAME_NOT_FOUND Invalid \a driverName. */ /*! - \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device) - \brief Get the device descriptor. - - \param device The id of the device you want to query. - \return The standard usb_device_descriptor, or \c NULL in case of an error. + \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device) + \brief Get the device descriptor. + + \param device The id of the device you want to query. + \return The standard usb_device_descriptor, or \c NULL in case of an error. */ /*! - \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index) - \brief Get a configuration descriptor by index. - - \param device The id of the device you want to query. - \param index The (zero based) offset of the list of configurations. - \return This will normally return the usb_configuration_info with the - standard usb configuration descriptor. \c NULL will be returned if the - \a id is invalid or the \a index is out of bounds. + \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index) + \brief Get a configuration descriptor by index. + + \param device The id of the device you want to query. + \param index The (zero based) offset of the list of configurations. + \return This will normally return the usb_configuration_info with the + standard usb configuration descriptor. \c NULL will be returned if the + \a id is invalid or the \a index is out of bounds. */ /*! - \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device) - \brief Get the current configuration. - - \param id The id of the device you want to query. - \retval This will return usb_configuration_info with the standard usb - configuration descriptor, or it will return\c NULL if the \a id is invalid. + \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device) + \brief Get the current configuration. + + \param id The id of the device you want to query. + \retval This will return usb_configuration_info with the standard usb + configuration descriptor, or it will return\c NULL if the \a id is invalid. */ /*! - \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration) - \brief Change the current configuration. - - Changing the configuration will destroy all the current endpoints. If the - \a configuration points to the current configuration, the request will be - ignored and \c B_OK will be returned. - - \param device The id of the device you want to query. - \param configuration The pointer to the new configuration you want to set. - \retval B_OK The new configuration is set succesfully. - \retval B_DEV_INVALID_PIPE The \a device parameter is invalid. - \retval B_BAD_VALUE The configuration does not exist. - - \note This method also allows you to completely unconfigure the device, which - means that all the current endpoints, pipes and transfers will be freed. - Pass \c NULL to the parameter \a configuration if you want to do that. + \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration) + \brief Change the current configuration. + + Changing the configuration will destroy all the current endpoints. If the + \a configuration points to the current configuration, the request will be + ignored and \c B_OK will be returned. + + \param device The id of the device you want to query. + \param configuration The pointer to the new configuration you want to set. + \retval B_OK The new configuration is set succesfully. + \retval B_DEV_INVALID_PIPE The \a device parameter is invalid. + \retval B_BAD_VALUE The configuration does not exist. + + \note This method also allows you to completely unconfigure the device, which + means that all the current endpoints, pipes and transfers will be freed. + Pass \c NULL to the parameter \a configuration if you want to do that. */ /*! - \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface) - \brief Set an alternative interface. Not implemented. - - This method currently always returns \c B_ERROR. + \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface) + \brief Set an alternative interface. Not implemented. + + This method currently always returns \c B_ERROR. */ /*! - \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector) - \brief Convenience function for standard control pipe set feature requests. - - Both the set_feature() and clear_feature() requests work on all the Stack's - objects: devices, interfaces and pipes. - - \param handle The object you want to query. - \param selector The value you want to pass in the feature request. - \return \c B_OK in case the request succeeded and the device responded - positively, or an error code in case it failed. + \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe set feature requests. + Both the set_feature() and clear_feature() requests work on all the Stack's + objects: devices, interfaces and pipes. + + \param handle The object you want to query. + \param selector The value you want to pass in the feature request. + \return \c B_OK in case the request succeeded and the device responded + positively, or an error code in case it failed. */ /*! - \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector) - \brief Convenience function for standard control pipe clear feature requests. - - \see set_feature() to see how this method works. + \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe clear feature requests. + + \see set_feature() to see how this method works. */ /*! - \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status) - \brief Convenience function for standard usb status requests. - - \param[in] handle The object you want to query. - \param[out] status A variable in which the device can store it's status. - \return \c B_OK is returned in case the request succeeded and the device - responded positively, or an error code is returned in case it failed. + \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status) + \brief Convenience function for standard usb status requests. + + \param[in] handle The object you want to query. + \param[out] status A variable in which the device can store it's status. + \return \c B_OK is returned in case the request succeeded and the device + responded positively, or an error code is returned in case it failed. */ - + /*! - \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength, size_t *actualLength) - \brief Convenience function to get a descriptor from a device. - - \param[in] device The device you want to query. - \param[in] descriptorType The type of descriptor you are requesting. - \param[in] index In case there are multiple descriptors of this type, you - select which one you want. - \param[in] languageID The language you want the descriptor in (if applicable, - as with string_descriptors). - \param[out] data The buffer in which the descriptor can be written. - \param[in] dataLength The size of the buffer (in bytes). - \param[out] actualLength A pointer to a variable in which the actual number - of bytes written can be stored. - \retval B_OK The request succeeded, and the descriptor is written. - \retval B_DEV_INVALID_PIPE Invalid \a device parameter. - \retval "other errors" Request failed. + \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength, size_t *actualLength) + \brief Convenience function to get a descriptor from a device. + + \param[in] device The device you want to query. + \param[in] descriptorType The type of descriptor you are requesting. + \param[in] index In case there are multiple descriptors of this type, you + select which one you want. + \param[in] languageID The language you want the descriptor in (if applicable, + as with string_descriptors). + \param[out] data The buffer in which the descriptor can be written. + \param[in] dataLength The size of the buffer (in bytes). + \param[out] actualLength A pointer to a variable in which the actual number + of bytes written can be stored. + \retval B_OK The request succeeded, and the descriptor is written. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. */ - + /*! - \fn status_t (*usb_module_info::send_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, size_t *actualLength) - \brief Send a generic, synchronous request over the default control pipe. - - See queue_request() for an asynchronous version of this method. - - Most of the standard values of a request are defined in USB_spec.h. - - \param[in] device The device you want to query. - \param[in] requestType The request type. - \param[in] request The request you want to perform. - \param[in] value The value of the request. - \param[in] index The index for the request. - \param[in] length The size of the buffer pointed by \a data - \param[out] data The buffer where to put the result in. - \param[out] actualLength The actual numbers of bytes written. - - \retval B_OK The request succeeded. - \retval B_DEV_INVALID_PIPE Invalid \a device parameter. - \retval "other errors" Request failed. + \fn status_t (*usb_module_info::send_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, size_t *actualLength) + \brief Send a generic, synchronous request over the default control pipe. + + See queue_request() for an asynchronous version of this method. + + Most of the standard values of a request are defined in USB_spec.h. + + \param[in] device The device you want to query. + \param[in] requestType The request type. + \param[in] request The request you want to perform. + \param[in] value The value of the request. + \param[in] index The index for the request. + \param[in] length The size of the buffer pointed by \a data + \param[out] data The buffer where to put the result in. + \param[out] actualLength The actual numbers of bytes written. + + \retval B_OK The request succeeded. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. */ /*! - \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue an interrupt transfer. - - \param pipe The id of the pipe you want to query. - \param data The data buffer you want to pass. - \param dataLength The size of the data buffer. - \param callback The callback function the stack should call after finishing. - \param callbackCookie A cookie that will be supplied to your callback - function when the transfer is finished. - - \return This will return a value indicating whether or not the queueing of - the transfer went well. The return value won't tell you if the transfer - actually succeeded. - \retval B_OK The interrupt transfer is queued. - \retval B_NO_MEMORY Error allocating objects. - \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe. + \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue an interrupt transfer. + + \param pipe The id of the pipe you want to query. + \param data The data buffer you want to pass. + \param dataLength The size of the data buffer. + \param callback The callback function the stack should call after finishing. + \param callbackCookie A cookie that will be supplied to your callback + function when the transfer is finished. + + \return This will return a value indicating whether or not the queueing of + the transfer went well. The return value won't tell you if the transfer + actually succeeded. + \retval B_OK The interrupt transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe. */ /*! - \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a bulk transfer. - - This method behaves like the queue_interrupt() method, except that it queues - a bulk transfer. + \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk transfer. + + This method behaves like the queue_interrupt() method, except that it queues + a bulk transfer. */ /*! - \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a bulk vector. - - This method behaves like the queue_interrupt() method, except that it queues - bulk transfers and that it is based on an (array of) io vectors. - - \param vector One or more io vectors. IO vectors are standard POSIX entities. - \param vectorCount The number of elements in the \a vector array. + \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk vector. + + This method behaves like the queue_interrupt() method, except that it queues + bulk transfers and that it is based on an (array of) io vectors. + + \param vector One or more io vectors. IO vectors are standard POSIX entities. + \param vectorCount The number of elements in the \a vector array. */ /*! - \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a isochronous transfer. Not implemented. - - This is not implemented in the current Haiku USB Stack. + \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a isochronous transfer. Not implemented. + + This is not implemented in the current Haiku USB Stack. */ /*! - \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a control pipe request. - - This method does roughly the same as send_request(), however, it works - asynchronously. This means that the method will return as soon as the - transfer is queued. - - \param callback The callback function for when the transfer is done. - \param callbackCookie The cookie that the stack should pass to your callback - function. - \return Whether or not the queueing of the transfer went well. The return - value won't tell you if the transfer actually succeeded. - \retval B_OK The control transfer is queued. - \retval B_NO_MEMORY Error allocating objects. - \retval B_DEV_INVALID_PIPE The \a device argument is invalid. + \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a control pipe request. + + This method does roughly the same as send_request(), however, it works + asynchronously. This means that the method will return as soon as the + transfer is queued. + + \param callback The callback function for when the transfer is done. + \param callbackCookie The cookie that the stack should pass to your callback + function. + \return Whether or not the queueing of the transfer went well. The return + value won't tell you if the transfer actually succeeded. + \retval B_OK The control transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a device argument is invalid. */ /*! - \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize) - \brief Set some pipe features. - - The USB standard specifies some properties that should be able to be set on - isochronous pipes. If your driver requires the properties to be changed, you - should use this method. - - \param pipe The id of the isochronous pipe you want to alter. - \param maxNumQueuedPackets The maximum number of queued packets allowed on - this pipe. - \param maxBufferDurationMS The maximum time in ms that the buffers are valid. - \param sampleSize The size of the samples through this pipe. - \retval B_OK Pipe policy changed. - \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an - isochronous pipe. + \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize) + \brief Set some pipe features. + + The USB standard specifies some properties that should be able to be set on + isochronous pipes. If your driver requires the properties to be changed, you + should use this method. + + \param pipe The id of the isochronous pipe you want to alter. + \param maxNumQueuedPackets The maximum number of queued packets allowed on + this pipe. + \param maxBufferDurationMS The maximum time in ms that the buffers are valid. + \param sampleSize The size of the samples through this pipe. + \retval B_OK Pipe policy changed. + \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an + isochronous pipe. */ /*! - \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe) - \brief Cancel pending transfers on a pipe. - - All the pending transfers will be cancelled. The stack will perform the - callback on all of them that are cancelled. - - \attention There might be transfers that are being executed the moment you - call this method. These will be executed, and their callbacks will be - performed. Make sure you don't delete any buffers that could still be used - by these transfers. - - \param pipe The id of the pipe to clear. - - \retval B_OK All the pending transfers on this pipe are deleted. - \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe. - \retval "other errors" There was an error clearing the pipe. + \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe) + \brief Cancel pending transfers on a pipe. + All the pending transfers will be cancelled. The stack will perform the + callback on all of them that are cancelled. + + \attention There might be transfers that are being executed the moment you + call this method. These will be executed, and their callbacks will be + performed. Make sure you don't delete any buffers that could still be used + by these transfers. + + \param pipe The id of the pipe to clear. + + \retval B_OK All the pending transfers on this pipe are deleted. + \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe. + \retval "other errors" There was an error clearing the pipe. */ /*! - \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize) - \brief Low level commands to the USB stack. - - This method is used to give lowlevel commands to the Stack. There are - currently no uses documented. + \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize) + \brief Low level commands to the USB stack. + + This method is used to give lowlevel commands to the Stack. There are + currently no uses documented. */ ///// B_USB_MODULE_NAME ///// /*! - \def B_USB_MODULE_NAME - \brief The identifier string for the USB Stack interface module. + \def B_USB_MODULE_NAME + \brief The identifier string for the USB Stack interface module. */ diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox index 12f24fbbe3..9c50e3b230 100644 --- a/docs/user/drivers/fs_interface.dox +++ b/docs/user/drivers/fs_interface.dox @@ -24,49 +24,6 @@ // TODO: These have been superseded by the B_STAT_* flags in . // Move the documentation there! -/*! - \enum write_stat_mask - \brief This mask is used in file_system_module_info::write_stat() to - determine which values need to be written. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_MODE - \brief The mode parameter should be updated. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_UID - \brief The UID field should be updated. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_GID - \brief The GID field should be updated. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_SIZE - \brief The size field should be updated. If the actual size is less than the - new provided file size, the file should be set to the new size and the - extra space should be filled with zeros. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_ATIME - \brief The access time should be updated. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_MTIME - \brief The 'last modified' field should be updated. -*/ - -/*! - \var write_stat_mask::FS_WRITE_STAT_CRTIME - \brief The 'creation time' should be updated. -*/ - /*! \def B_STAT_SIZE_INSECURE \brief Flag for the fs_vnode_ops::write_stat hook indicating that the FS @@ -249,46 +206,6 @@ //! @{ -/*! - \fn bool (*file_system_module_info::supports_defragmenting)(partition_data - *partition, bool *whileMounted) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_repairing)(partition_data *partition, - bool checkOnly, bool *whileMounted) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_resizing)(partition_data *partition, - bool *whileMounted) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_moving)(partition_data *partition, bool *isNoOp) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_setting_content_name)(partition_data *partition, - bool *whileMounted) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_setting_content_parameters)(partition_data *partition, - bool *whileMounted) - \brief Undocumented. TODO. -*/ - -/*! - \fn bool (*file_system_module_info::supports_initializing)(partition_data *partition) - \brief Undocumented. TODO. -*/ - /*! \fn bool (*file_system_module_info::validate_resize)(partition_data *partition, off_t *size) \brief Undocumented. TODO. @@ -638,11 +555,11 @@ \param volume The volume object. \param query The string that represents a query. \param flags Any combination of none or more of these flags: - - \c #B_LIVE_QUERY The query is live. When a query is live, it is + - \c B_LIVE_QUERY The query is live. When a query is live, it is constantly updated using the \a port. The FS must invoke the functions notify_query_entry_created() and notify_query_entry_removed() whenever an entry starts respectively stops to match the query predicate. - - \c #B_QUERY_NON_INDEXED Normally at least one of the attributes used + - \c B_QUERY_NON_INDEXED Normally at least one of the attributes used in the query string should be indexed. If none is, this hook is allowed to fail, unless this flag is specified. Usually an implementation will simply add a wildcard match for any complete @@ -1714,7 +1631,7 @@ \param vnode The node object. \param cookie The cookie you associated with this attribute. \param stat A pointer to the new stats you should write. - \param statMask One or more of the values of #write_stat_mask that tell you + \param statMask One or more of the values of write_stat_mask that tell you which fields of \a stat are to be updated. \return \c B_OK if everything went fine, another error code otherwise. */ diff --git a/docs/user/interface/Alert.dox b/docs/user/interface/Alert.dox new file mode 100644 index 0000000000..53d42cdc58 --- /dev/null +++ b/docs/user/interface/Alert.dox @@ -0,0 +1,389 @@ +/* + * Copyright 2011, Haiku inc. + * Distributed under the terms of the MIT Licence. + * + * Documentation by: + * John Scipione + * Corresponds to: + * /trunk/headers/os/interface/Alert.h rev 42274 + * /trunk/src/kits/interface/Alert.cpp rev 42274 + */ + + +/*! + \file Alert.h + \brief BAlert class definition and support enums. +*/ + + +/*! + \enum alert_type + Determines which icon (if any) is displayed in the alert dialog. + Choose one option. If the constructor doesn't include an + alert_type argument than \c B_EMPTY_ALERT is used. +*/ + +/*! + \var alert_type B_EMPTY_ALERT + No icon +*/ + +/*! + \var alert_type B_INFO_ALERT + \image html http://api.haiku-os.org/images/alert_info_32.png + Info icon +*/ + +/*! + \var alert_type B_IDEA_ALERT + \image html http://api.haiku-os.org/images/alert_idea_32.png + Idea icon +*/ + +/*! + \var alert_type B_WARNING_ALERT + \image html http://api.haiku-os.org/images/alert_warning_32.png + Warning icon +*/ + +/*! + \var alert_type B_STOP_ALERT + \image html http://api.haiku-os.org/images/alert_stop_32.png + Stop icon +*/ + +/*! + \enum button_spacing + Determines how the buttons on the alert dialog are spaced relative + to each other. Choose one option. If the constructor doesn't include a + button_spacing argument than \c B_EVEN_SPACING is used. +*/ + +/*! + \var button_spacing B_EVEN_SPACING + If the alert dialog has more than one button than the buttons are + spaced evenly across the bottom of the alert dialog. +*/ + +/*! + \var button_spacing B_OFFSET_SPACING + If the alert dialog has more than one button than the leftmost button + is offset to the left-hand side of the dialog while the rest of the + buttons are grouped on the right. This is useful to separate off a + leftmost "Cancel" or "Delete" button. +*/ + + +/*! + \class BAlert + \ingroup interface + \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. + + The alert can be configured with a set of one to three buttons. These + buttons are assigned indexes 0, 1, and 2 from right-to-left respectively + and are automatically positioned by the system. The user can either click + on one of the buttons or use a shortcut key to select a button. + + The layout of the buttons can be configured by setting the #button_width + and #button_spacing properties in the BAlert constructor. The icon displayed + in the alert can also be configured by setting the #alert_type property. The + right-most button (index 0) is the default button which can be activated + by pushing the \key{Enter} key. + + Below is an example of an unsaved changes alert dialog: + + \image html BAlert_example.png + + When the user responds by selecting one of the buttons the alert window is + removed from the screen. The index of the selected button is returned to + the calling application and the BAlert object is deleted. + + The code used to create and display an alert dialog like the one shown + above is shown below: + + \code +BAlert* alert = new BAlert("Close and save dialog", "Save changes to...", + "Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING, + B_WARNING_ALERT); +alert->SetShortcut(0, B_ESCAPE); +int32 button_index = alert->Go(); + \endcode + + The messaged displayed in the dialog window along with the button labels + are set by the strings in the contructor. The Cancel button is offset to + the left relative to the other buttons by setting the \c B_OFFSET_SPACING + flag. The \c B_WARNING_ALERT flag displays the exclamation mark icon in + the dialog. + + Any alert with a Cancel button should map the \key{Escape} key as shown in + the example above. You can setup additional shortcut keys for the buttons + with the SetShortcut() method. + + The Go() method does the work of loading up and removing the alert + window and returns the index of the button that the user selected. +*/ + + +/*! + \fn BAlert::BAlert(const char *title, const char *text, + const char *button1, const char *button2, const char *button3, + button_width width, alert_type type) + \brief Creates and initializes a BAlert dialog. + + \param title The title of the window. Since the alert window doesn't have + a title tab, the title is not actually displayed anywhere but is + useful for debugging purposes. + \param text The text that is displayed at the top of the window. + \param button1 Button 1 label + \param button2 Button 2 label + \param button3 Button 3 label + \param width A constant that describes how the button should be sized. + Options are + \li \c B_WIDTH_AS_USUAL + \li \c B_WIDTH_FROM_WIDEST + \li \c B_WIDTH_FROM_LABEL + + See button_width for details. + \param type Constant that determines which alert icon is displayed. + Options are + \li \c B_EMPTY_ALERT + \li \c B_INFO_ALERT + \li \c B_IDEA_ALERT + \li \c B_WARNING_ALERT + \li \c B_STOP_ALERT + + See alert_type for details. +*/ + +/*! + \fn BAlert::BAlert(const char *title, const char *text, const char *button1, + const char *button2, const char *button3, button_width width, + button_spacing spacing, alert_type type) + \brief Creates and initializes a BAlert dialog. + + You can also set the \a spacing with this constructor. + + \param title The title of the window. Since the alert window doesn't have + a title tab, the title is not actually displayed anywhere but is + useful for debugging purposes. + \param text The text that is displayed at the top of the window. + \param button1 Button 1 label + \param button2 Button 2 label + \param button3 Button 3 label + \param width A constant that describes how the button should be sized. + Options are + \li \c B_WIDTH_AS_USUAL + \li \c B_WIDTH_FROM_WIDEST + \li \c B_WIDTH_FROM_LABEL + + See button_width for details. + \param spacing Determines how the buttons are spaced. Options are + \li \c B_EVEN_SPACING + \li \c B_OFFSET_SPACING + + See button_spacing for details. + \param type Constant that determines which alert icon is displayed. + Options are + \li \c B_EMPTY_ALERT + \li \c B_INFO_ALERT + \li \c B_IDEA_ALERT + \li \c B_WARNING_ALERT + \li \c B_STOP_ALERT + + See alert_type for details. +*/ + +/*! + \fn BAlert::BAlert(BMessage* data) + \brief Unarchives an alert from a BMessage. + + \param data The archive. +*/ + +/*! + \fn BAlert::~BAlert() + \brief Destructor method. + + Standard Destructor method to delete a BAlert. +*/ + +/*! + \fn BArchivable* BAlert::Instantiate(BMessage* data) + \brief Instantiates a BAlert from a BMessage. + \param data The message to instantiate the BAlert. + \returns a BArchivable object of the BAlert. +*/ + +/*! + \fn status_t BAlert::Archive(BMessage* data, bool deep) const + \brief Archives the BAlert into \a archive. + + \param data The target archive which the BAlert \a data will go into. + \param deep Whether or not to recursively archive the BAlert's children. + \retval B_OK The archive operation was successful. + \retval B_BAD_VALUE The archive operation failed. +*/ + +/*! + \fn void BAlert::SetShortcut(int32 index, char key) + \brief Sets the shortcut character which is mapped to a button at the + specified \a index. + + A button can only have one shortcut except for the rightmost button which, + in addition to the shortcut you set, is always mapped to \c B_ENTER. + + If you create a "Cancel" button then you should set its shortcut to + \c B_ESCAPE. + + \param index The \a index of the button to set the shortcut to. + \param key The shortcut character to set. +*/ + +/*! + \fn char BAlert::Shortcut(int32 index) const + \brief Gets the shortcut character which is mapped to a button at the + specified \a index. + + \param index The \a index of the button to get the shortcut of. + + \return The shortcut character mapped to the button at the specified + \a index. +*/ + +/*! + \fn int32 BAlert::Go() + \brief Displays the alert window. + + This version of Go() that does not include an invoker is + synchronous. Go() returns once the user has clicked a button and + the panel has been removed from the screen. The BAlert object is + deleted before the method returns. + + If the BAlert is sent a \c B_QUIT_REQUESTED message while the alert + window is still on screen then Go() returns -1. + + \returns The index of the button clicked. +*/ + +/*! + \fn status_t BAlert::Go(BInvoker* invoker) + \brief Displays the alert window from a specified \a invoker. + + This version of Go() with an \a invoker is asynchronous. It returns + immediately with \c B_OK and the button \a index is set to the field + of the BMessage that is sent to the target of the \a invoker. + + Go() deletes the BAlert object after the message is sent. + + If you call Go() with a \c NULL invoker argument than the BMessage + is not sent. + + If the BAlert is sent a \c B_QUIT_REQUESTED method while the alert + window is still on screen then the message is not sent. + + \returns A status code. +*/ + +/*! + \fn void BAlert::MessageReceived(BMessage* msg) + \brief Initiates an action from a received message. + + \param msg The message + + \see BWindow::MessagedReceived() +*/ + +/*! + \fn void BAlert::FrameResized(float newWidth, float newHeight) + \brief Resizes the alert dialog. + + \param newWidth The new alert dialog width. + \param newHeight The new alert dialog height. + + \see BWindow::FrameResized() +*/ + +/*! + \fn BButton* BAlert::ButtonAt(int32 index) const + \brief Returns a pointer to the BButton at the specified \a index. + + The \a index of the buttons begins at \c 0 and counts from left to right. + If a BButton does not exist for the specified \a index then \c NULL is + returned. + + \param index The \a index of the desired button. + + \return A pointer to the BButton at the specified \a index. +*/ + +/*! + \fn BTextView* BAlert::TextView() const + \brief Returns a TextView containing the text of the Alert. +*/ + +/*! + \fn BHandler* BAlert::ResolveSpecifier(BMessage* msg, int32 index, + BMessage* specifier, int32 form, const char* property) + \brief Resolves specifiers for properties. + \see BHandler::ResolveSpecifier() +*/ + +/*! + \fn status_t BAlert::GetSupportedSuites(BMessage* data) + \brief Reports the suites of messages and specifiers that derived classes + understand. + + \param data The message to report the suite of messages and specifiers. + + \see BWindow::GetSupportedSuites() +*/ + +/*! + \fn void BAlert::DispatchMessage(BMessage* msg, BHandler* handler) + \brief Sends out a message. + + \see BWindow::DispatchMessage() +*/ + +/*! + \fn void BAlert::Quit() + \brief Quits the window closing it. + + \see BWindow::Quit() +*/ + +/*! + \fn bool BAlert::QuitRequested() + \brief Hook method that gets called with the window is closed. + + \returns \c true if the window closes. + + \see BWindow::QuitRequested() +*/ + +/*! + \fn BPoint BAlert::AlertPosition(float width, float height) + \brief Resizes the Alert window to the width and height specified and + return the Point of the top-left corner of the Alert window. + + \param width The desired \a width of the alert window. + \param height The desired \a height of the alert window. + + \returns The BPoint of the top-left corner of the Alert window. +*/ + +/*! + \fn status_t BAlert::Perform(perform_code code, void* _data) + \brief Performs an action give a perform_code and data + + Currently the only perform code available is \c PERFORM_CODE_SET_LAYOUT. + + \param code The perform code + \param _data A pointer to some data to perform on + + \return A status code. + + \see BWindow::Perform(). +*/ diff --git a/docs/user/interface/BAlert_example.png b/docs/user/interface/BAlert_example.png new file mode 100644 index 0000000000000000000000000000000000000000..28aba046dd6084eaa1bb23d5d612bf4a1a44459f GIT binary patch literal 8972 zcmXw;byQT}*T#n)LK=n`TDpdk?vn2APU-F#x}`%vk(LIfhY;zIMv!ihZbaVE@9+I% z?wWhoJ!{{4&a?OVJp0C}tIEH?Aj1Fv0523?%V+`s2)Xe8%0N{35k@nz3jkpFIY>*Z zD@aRIt9!WGIyl<^0DcH_S$6tb!(@Yd1?i^t2p04kt+V z5mo=6N2mZNLnbC*J4RLhQnQVjsYu>GniaPU0Z=5_W@nNIuz87Qqd?OxnUSz3;1XWF zClC;Bv}YB8STL1C2>=pe%afo1?zyUFcv{`?Gr8m9f+*iEnoj|XQuvVS_o$|bs`nDjsa3LsNLLNhW z$*%U*TYIW4_X1InL8^#ZlfP&*6}YwHvLrYNB&fSjRzDQMJ9xUtX|FMv?0aFboui#y zDiQ}yY0Dem1C^m6b9y++6_3)|4WdPHaC3h1S4dHDv*A2McQ`J!qpvwP{((OPY{cYb6O5%Ae$$Ezc**&lyvBUTbda_*}nq zd%Jgv`%>l3XsZ!WZ!do;y|+e2CHf_c7$BqbJkLAzkl=z=+@F-sF{VEhll$0*h>t7F z`VuoEjBE-ObzjgB(Wpm8Z64_^f*KcF7l9)djadRXAO6A|a|j8=9A^<{qzBIpOFMFA zoy{JxrkKJQ>5Bx;K3Yl-E(uCq5Aq$bj0V^ztsRRxEH#pf`VlQx3TuecBfPU1zyywu z*rXQAzRA>kwWn3ahY&fmW*sF5@x7F@`Y?WzsUTnb?D`D+5?o43M>Y z?N5lhI8Ko^R{izvi{6VO&gh>pmczQ@e+?#Eif_6JI1~_1VC*Gh4$^PVZ~1IsZydV6 zX*FE|y5Oe_j&5F``S_WMpcO?=_EUW=>NERxyCHvG1hkIe?#)yc&rWlFc*^`2JtnENRXK8lwDS1QZJx;?kR6`+TILcEWb0%g6IS?KY_|qv8&f(g`)#8s6v*U>}2FPEvkZ34tjVUD3eOCBn zd>pY@y!cT-WkqI1Pee8-`%dAUeA5cw4_yTvgkC69`;{w>6`zh5S|;cD!QElme$YYB zq2#TA0=vRz>kro9+YZAn!|2TD%$}9FmCBVKl?j^C)3MEEyhcI>?dlJouEMUeZQ@7u zM=i5{8S8%e0RamJ%L&T?i@Z*|PMJ=NcBIais`+X$4Z2FMS4Wc4-t1mm-lN{9`@I2K0q6lSR{_@z5AzQ}Pl`{HNbv}x)cwWt z=8Nh-rbgYWEz&p0>AXvTC0%kRa%+j~iRnoxn_h)3ku5ST6*f~C)wYP(-k`d&*97ko!ruh4a(tbtjca~l5ygr0NuLM*DmjvE;IeN+!{4BV9*J1L~IKpJaxUjvd z{af37yK1XJYmKjy=U{ta`>8jTHEUzrG1(0?CUa0OMO7`{uGlVjkB8HQ^SxdI|M9Pl zuF1!SlxUo_@?p?jWAN?0*!j$b(a~+S_{7>IY~|TMOra+_tX9Hs{jeuJoGKC=i4jSO z;)GU?<_nFDmWiH)Dn|*$5JzE0kw(42>LB6(72>Xf!&88974bR78;zFF@!wx340R5L zXBx8d=&kD0e_`>T8<_i0Em%D%Yf&OqqAEA;79^NiFl_JRC3}Uu5EmHs7(cj8botHd z*fQSI^y`lS;(_FWrGZ}wx)0~4@VF1< z$~}8gc4$*iYw<^OTafRI*>8*I!zX^lF{NZMHN|Uji1wk*k0AA@^}}v{J z%39$MejnF|vWxIT+Cyi5*;|#`+6;58G$dM0ro@0xA9Bwa?%QnI-o1_`kRGzT!>IwoD!3L|c29P%J?Z>* zACGD%9YQyoGbiw!aE*5syt)$DyCo%`@J6Y>E*e&7uj9ZDWAbh|!#~hGDP0;}%4S?f zep9!+^+R4r*H@$+-)G0PJk;)1XR>;suFbS#df>1<=;ukm(TjX?kPElVtDlXXbAHR4 zKK-u5Fg`CMAO6*b_L&u{pEJ`Powu4r(q@k)dmRfW4W~a3Zx2o>fRwG`B!U87MZTfO zk{6L*aCj(H#Yg-TgA1NzjunQrqRKO2N54(Qtp&Z@7ya*UntJR~UDyH>HYYggih7Y#aUPFVS>+~%erL(3xX2YC|A3+Ujdwt zf4-t!;!vcAq^pUS1r-#IJimObeBjygT*#i{u5g;KsWZpgew2|L`aR4 z=%X~?hZu+7S(|->762k@FrT>Y)LZ1ayAaC%82|C!p&ALJ$)Hbmm-$adC0l0Fe%#UyfW(wuAp&#+?9y zg?$piQm7II!oC~@=j-h}e{b&rA_EXAhnc$B>n2`o4TKxA} zqiD`PIzR^G{^&nLGf8*Jt zdUg)E6a4ZU6_k`pYK*>24^o9H>(!Z-9?n(IY^8{+dLPcd&&eSf$xg8;W{w4i{|ysv zoEXL~C5N7^CUy^v#v)Y~_W7#SurK9xwQr%QxFYQ&W+GKov&Iso^6N*7!T$Cp_E%Xe z__NCO5Fmc8zzBZ4DSbBPo?|Tx57g_k6RYKTCj(AW4lyu4-<*Mev(qf`KSZ=Hg9mn2I=v`BCWM* zp@>2Ws!kb3=|G5s!*i@qIe|@?&65l87F8CM^f3=7yW}~filOUC3Ps3sH_>LXKr}FG zcjBGWJ7Hf2d&P!^2F-PYECe18sh;?l6%0z%D2y#k*LrRD49r$972W1 zhTKbyKNm7-rC;lcTZ2`AdDULO)Dcad+(~yPmFMFNJWn?V5}4`fqZrf*m2E~c-irp_ zOa-2H$zLBWObUAL{#BtEjoW$;LeZuXsliSSG?w&Kr&{-WtNYe=!Fe8^ll_lohi0z> z%_eJ$;5A|uIod+z z558HlYKfB}k&=}+$nfr!2snDshL&RPY`zdOJ z&x}PuZ(q5rR5bc{5UI6}qyUFPpB}C?^PzI+;(f+xigw%Kt%Zm7x@cCWIjqJVJ~dxI z+KgsF1*PAOjT~2s>QH!v1d#mRk5tLyeXm<%_uN!}@2TqJP23)J!q_2- z>4}?$f1ggszyiiXQKycem)?Dn4R>{i0Xf2motGf}{ zarX*?l*XLenmZ~rym%OQw-M|7tpZHK%ZIVF$dH~~dIXdZrTnwq+hL+W&})B+Ci{h$ z(>$Bw{3lX&qtA)O*AlI4X5GeO8L|n)-all#29qhE5a1`*?)&H|^vCNX`ODq$lDj*< zds^SzIN(aBe-oiOWFh$Bpxo>3%%Z&FXuhW8d~0wNd<)*h=EJf4Dl(T;IPPA90>96yntT(-nBDs9YFu z$V?{SM*Rd|Xpf9UN!*7_TGzuJY>=8h%OAIEzkpW$kkHHdOYIP=5L<74CuutICMO;2 zovORgr)$s)5=fX_GPp8g(K|9MNlMNhNwZa=r^gxpJ2OTuPsP002 z`RcE}40ZNsq@!^QUG))jMCi=73KFNSi+f|Kc5SzRV<9KE&NI_0!bTck`VE#BHW8qa zI0D9x^IV?0$_{2ImnHHkiZAGBXu?CDpL`uCJGPRAt-B%bC7CSF0m?SZUtG%-(iw&W z1sD);5P-MEKjh`&?-}^7;N@MhsUUw@yTwswkp0uQ8If zec*2Vb7Ay9frP9BrJj)w7WO8KvMuf|%S;R1+#wg=wd&0!+ub%Iz(JKCTjg3+!-tH{ z`KvpsUuinjcyVn!e&PWZf4ng#&?3KwFyFe~`0nz*l)D({( z<5d476p71X(%wuc1K+)}P{MqWIt0g5a9`Gs(qci|(p`SGe=kW9W2qbelZvKH3mLyx zEF9T?!Pz-$Q5Zgqi5y;)ZeViKaVqAZ8Sx?rp4FP>00KQ|iX)BNb&AvbUTQUS^oXfT zXg(`t?ZtHe*kSQt6cri8Zr-eie})2M6L+BFB)n#i4lt0gg}JfSz_y*b67TOK>HUgp zx*t!3H761KAVYmi=DC<~wr1x)v$;WM^hAM1Eu_Zl4m4<-q zj0x2Cv>%%_Xas!&Z;qL%h!gvg!Gg4Wq{^nOeIq=H4CnnyXw_3*5&l@V+@E+g%D7iT z;iUkb43APINB9gsrr1NC1bw_n+$@V;P;jY4*J|5BSI#PEi_a8mh@4Xs*xuSIP|jrQ z-CH23sfll4frR{GH*rOyR57y=olDuCE_6HTJL7Mlr+lqnYeIG3_+jxTvmPhGNaPOfMR<20gGGY>E26+!6mLICOIIhxX0PXsgy6Exy4V1EI@u`E;v34QBKT(I@e z{|R5#Rk_+9Q~H#lbwAma&$7*!%A3^E@#vP9$&}}V5)A=iCZ3=cWzs57Np&)_pnI)1lqk%T)Oh|4zvJE$g_`}JFHR=m>(3PBNtslu2N!|FNdE(l8X*5!300O}kx=B74D-SfW z<3@(653?N(F|*3&yjeBk9$h}} zHuyOXp8-`9eJ0pp$+y;^UsQ;AmR_0YTHo6|_qK6fO~wQsh|K;vB>r8Fd!O!vUIWlBeJL zg+sXhLgqRSq5!E@HY17tk{ySZVS=$v*_gGZsvL(?_ZyCm((#o%uiNtJf^VXT1Pscl zyX0*B-v%qXb3|7>cZC0eB z-LRgNxPK5SL1SLhhGnRfwToy$_tdAHg{~r}4T_*Y0^x1^F-n&}=no?Ok8(Yd;kdaA z&(gBE=f}`y-)CkE3W7_nyJ<5=F8%pLMVs7FD9&yp4=8Hg!tyU?hT#o)0^u-NzqxLI z7_8m(ljTs*hw;rLvq3>3dJSq`B0lezdgZ&wic2GT3MG?EaG$aHKc4O*K`?@1WsOoU z!J>R>LJJvi{4=nr+N9W{T}pI}CZ=*dzd)7q+;mT9^BP5>unRaCVB+XoKATnla6gq1 zuij>pDln9uF{v28^aJzLq0M2)B&;$xA@HE%?uk&?hW|58=nDjBCF;2XC(Zo5SF2dE7N9hp}C*)65&#r+sf$`2hl5P zbU)vL<~THSTnfY_4=Ob*WAuWqi*Cbr$^Q8p++^V5?Sl`S5i!A^g9T<x@qLEfNWoLG+m*C~7qcJ#*3d&G33Y+Xfj#AZ3YYh47j_iw4@#JyV9spWq z8d<9M6BKU)e;NyQ$6Ux~c|B}WmCIX>dO0&VymS_dondZ3=@NPzAc?8_-$F+ugau16 zNC%PAiT8{dHahFKC!Rv)26G7At8*L))bwzlE+@r3%B`JClGDj(+-8?3YBwW6>3qNn z>Cc}wi1UnFVJNjG;}2BHinfiY;f*$<4`V~bG;jhU4Y-VqoNX~cuL|QSm^HO|scaVy z%}9I9(s&u1?v`8+%i@Pxh2v0)FqH)0bH|2Jl;?Ux13s62S9>!?`ejOW{Av8*=KAyV z)9=g4c{@s5u(0om@7<#Tguw4KAdWmqv*$=Xq{?65eull3v{V#UeEj;z+(GxZocWM+C4hHCRHG4=V z@qDvEn;Wz8+Z*f~gh~u+xNdx$yW}xvN#jrKdv8u%pRJCA2UpEL>8P&4;&d=De>(Ts zB12WG2w%ZomZ}%o&#NT2{XlAZ4gNga&daBZd15lCg2EKk(-};v1FqBGjwO15sXvlx2_wiAOq~i}w zYF?fqkKM$_`5GfF_=Z@aRjzvV>&x21Ae)S40|On|bk+A4-E1e{OVGTJ=96|Oi_}0I z#;I#>o1GRo^t?dThqZdp0+Je8`z{NJR*kFa8KnVA} z%9zA#ZrfpX$?_?b?0f|Q*N5MQPdn*Q(&EFcD*uB1UvE>TQ$2mQ(f{toK?(HO75wLZ zZ??rr5AIq}*$o`K z-USZy1eATHO4&l2C5*MkZJOQ6J*+G&irwbgOXdOj@OH}e=~~e%*HvXSY_QwMf$L>g z7`qB9RnS>D7=aEalejZ;4FmK$=eKkZR;U}_w{S@BMF>%HHYqCp)?i9DY#;$d@G4d3 zwzpr)OvwM@V+s_93J{fk|Z*6T+>_i+e2?^y@ zX;;!d)|ZP_-*tG{ynnj$92gy`f4DxHNhIa5fBy57EOhkySC8W48WoHRB1~^VvxO`_ z!Qpedsxnut=R0Z*_sbsqh$7ZREZW6fR^P0f7NjuyUgP*&yqAs{LDS%Z5?{g{(`XFE z8WMc6RepYe+pyOmaBXD@YgqB3^!5{y0gFv6q_m))WzFDfO#V&!h_UH^s1%>_A9(+&B+z`(G8d@?wVj>4Wb;18ss(h2MohFw+bd%P$K zFQD$mN4e(ExENyScZ@MRebm}%TI1WTykSb@P6sqAa5Lwa0SmYz$tuFYq~sL-9%JrF zdGIIwmd7gg&CNS0_z*G)B;ZV*30ne1;A~f#S&89u8jfido4G819{(QGb~6OOcV3OCpuVz!%K<9GvaoQH)tEi$#(v;&B_5z)OuSb;`A)_cQ8j^nAR z&&;vOcwalR=raL~ItpPYdLr5+)0;aH!E1@opV)sLev8wBPkZS!t@^F7>}EnS?YfFE z$(H%_^ZOV|k7kP+!xms3&&>hS)76Yxr*G12YPr}7u#L3>YCioEqGL;FqU*33+84c>s` z2Jw3YtV-`&%qJAgOvsY;;Z-i6Q>TRd6H~twiJLa_b?=v~RMC)s$(CN0O^(PA|EcU`w?6pl*b{~@{j%F`lJXww zLwE4QmHVt9r^SwT1K3z5Rxm43;kxf@?3s4)gy8#nQyn|$I^G>vAadGiD9E|UV+-ErC zbudl84)8=x43i3b%$K6QtL>hVIP=6g1^4R?5whwgiqm49c2mv%@C?OdSy9ckC`Z1= zdq4A{8;F6}+0MoU@nrb7g+mz;Evkp1cAlO!q~T|hJwN9eHzFlYDwv(P+e#=}3IDt4 zCA{q{)o9SB`R{Za8{TH#PWD;X{EsT%0_#)Jhi!Kh|GAS?VR+9vUHC`1Qt!XU_G{X8 z5AUT0t3l`LPw)JfbsZ*h{$Vh#Y>&dwy7q|qJ7v-jejY9Vz}_607r6k6^(xisf241Y z{7FgzgY=b#0Se=##eeiag~ybdlk@tH>tDRTT~l4Uv*&H$L#Z{^50dat3jhUKRhe2T H^N9ZgDq!gW literal 0 HcmV?d00001 diff --git a/docs/user/interface/BBox_example.png b/docs/user/interface/BBox_example.png new file mode 100644 index 0000000000000000000000000000000000000000..4e8b6361c3bc820f2a0498ee6315be1f445960ce GIT binary patch literal 3834 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

J{GUJFB(?2->q;@3h$6~ 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 YA5Gt(Z^A@Euft$~GAhzllHY><2Ukf$FaQ7m literal 0 HcmV?d00001 diff --git a/docs/user/interface/BButton_example.png b/docs/user/interface/BButton_example.png new file mode 100644 index 0000000000000000000000000000000000000000..581e708d12d269b02686098f24b819577fd823c2 GIT binary patch literal 4803 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 literal 0 HcmV?d00001 diff --git a/docs/user/interface/B_FANCY_BORDER.png b/docs/user/interface/B_FANCY_BORDER.png new file mode 100644 index 0000000000000000000000000000000000000000..4f05474f652fb8737601fb192aa5bd875d149168 GIT binary patch literal 3476 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 F{{h$Av6cV; literal 0 HcmV?d00001 diff --git a/docs/user/interface/B_PLAIN_BORDER.png b/docs/user/interface/B_PLAIN_BORDER.png new file mode 100644 index 0000000000000000000000000000000000000000..ab2abd581f343bebdc52788e39cdf517a29fce44 GIT binary patch literal 3369 zcmeHJ_dnE+1Ag0QbYy>Il_(h}kvkn{@4d74-612Kk#df+M`e}^pK!>E5Qm6lkBsAt zY$78hEBW^QGrq6a_lM_setCX+p67=r!Nf@W5)&U2005VCbu`TW>eIi#fT;g+DJ;bw z0GLA2>gp!C>gvKK5B)sRJ{|xNN;Q#%v@!4H>s}|MJEEwHIKp?OuqtY-tqP`$i~_DK zn(eWPjW~(Kcu=VX3G{m54d;Ce70#J!1=z=`+;qVXlJQJ^O6~Z=rr|liqyAU$J147% z-4>+m?u+#k8Wr?1h_?4FFChL~&IOw*q9h5&rAE>^V*yYP4HsC!vVH&Hfcj!e8C>uT z)$A>k{avW@&shuO&G}$1VEf%ZC(c8H)LO`N&->=zFFzael z>-UnPiWkdf8TEy2{TxREfzU7dFc_gx)bSYdP4DN&A;vPCyAk>zy?%gQ}%5*q2WdHt3 zjzxAcJb^#0>E+-$50QZu^3Y4Gp#K`On*lE^3;7(Tn`Y?m0oi0kZxtg&EBEZDY5eJ> z+nLWtqOQo$t+mtgmUOuj|NV{~<5SI&xhk!kGNd-&$op6^cUXSBB$qEYXTb1czOJdc z;VtFpXnmLMy5X_iaxL%{rM;`ZKF=ql^gfFl(6GE9%Z;2S`7#uArsPTw*!0A`IP0Kh zXVa9p&YXee8=Uy8aijzDb~LB%l<4D z(PImeDC)`r0ehPFDy-ia(%RX0>8jglk3qz%pbmA5c=}$ozNhp>3@_AJdITRvwG;q1 z`4e$V!pa%o2iOKxI+M#5^a6OV0;d9IlY2oln|MK$&JpNO@F}&33|&?Xmy6*P$g^E? ziUW+Z?g;o{3%xRg59uuS7mZ-@jhR`r^GCpG+i*87W1n6|YtY?R;f?25O41OniD#q4 ztcZx}h?>RK2|M&SxP!t{B0ew3$gv2xVQab?-Eg<<2W$t#2BZ!CA@YsIZ+x2VVsR6b znSX0hL2bqA9qr-P`8HrGcna>r*uXS{ZB5+nPIW~r`9skJ?jff2ROW8cCGs+65xlq= z@SxFg7UavG*4@8!_yZH_1ZT*P9qttRl;7d>`DjslFCXNNll_>npcgOvgVByrG$uVp zKSsHOxkJu0xm308>M48JCrQ_sibWE2OoGIXGIaD5Jrq`Hi&OTo`+0iBUS==GL0){p3iYw! z_|uG2-54>~n;qPX2|nE7JZR1hjxZ5D&IvY;gevwyZmG*kH^Q}l*7KSgm=EYCi!|s~ z*l*#c3Z{ynhO-*8)^N>;>|@=%D@$(dp^S!%JdAl7RiADrNU)2@#SpauUk9LPP~B*2 zbm4QTu9R+r`)l{86?Cs}FQYi4cwiY@nL*jZvLrM0(fB%|oSou*lF4bsPwdZZkHmhP ze%GvRd#m>qew2*l78Y|cEioseBhhIsNz#F=c~=)x?UTO60ZS%S5!z-In>rs_uR8YY z_s#SLt{$uo_aQ8>TtQsaoMZ`p^TtYEFkg1iE?2y=vkSIrLB?Qsr$_Iac?q|Z%c zl2POR#>x=yz;4nb(r&PjyF_i%7T>R!xXf;?G$Z3gWC8NU`W=V^ z$4}E;++C?%l&mZ>9qZvUz0P&0P1yp=(ct%n)1%getXs~>w`!itjcUP=e?M@Zcy7b2`rc|V8E2!qaRtWa7njtiY$#qMWgfpY{ zN3-S|`23`%PhIT3HDuX$%@SsxZTrr6A872yghk);3E@AXI#BOmox3-P5u81d%Fm8` z*WOrA#(eWetUy56m((I5vX+Fw&YjsVIBf;sn z%f;rog5H3BD!;IR4noFa({eh(LC{s*F6a$cn^Fi;3-&j?{#R= zLQi%+`x8>+_%_O|*wdr;_H0eE+i+SO|L*CFy+FfEdrQ@cNsiwf>JwBGujH-d{ zc+Ld$3+KGtIRDq#M<18fw38m_cUH%?<)JLmQf)VbYkshAnC%o(`YG8rW@sN&&n!=C zD_VuXN$i+a$C60ok>zmtWOb8c^Jv#5DPnFX{QITcD?GlkzIW$pTP8whmN1=u+->qf zb{K`PHKegwx4E&==9VL~e08TYhxO*kotoXb&7+N70gzxLf)@r2$`6U$Qr(Y!&w5AD z2+u$7li4E>2yt?70jbxv8S&s`?PPn;r*EqQE3z{1h>BKVamohx z`U=4Efq_ehT}2Ia5V#PP)Nx40zmZ3<6GZ4o$gp97AhpFBz&1oH+;|E5FhhPs8dodC zffW|R4i01~+Mvp6Jc$Ri&vH$?&1CPL2_D9V3IHF#LqkRigF{a$)s)WEfoWyw&>u~x z8goEK={`Am!TV!=;M!!Q!f$52-VOJyn4tW>SCr9T=YAjnFmwDDRKQCDF91+m>uRW4 zgi>vf-v;AU01Z?5U-nUF`KbO@Y6X*Ap}Klx2rl; b%&ox3pvytbT&bsjcL(Td8fjFiIph8VUsx@b literal 0 HcmV?d00001 diff --git a/docs/user/interface/Bitmap.dox b/docs/user/interface/Bitmap.dox new file mode 100644 index 0000000000..9180c21af6 --- /dev/null +++ b/docs/user/interface/Bitmap.dox @@ -0,0 +1,556 @@ +/* + * Copyright 2011, Haiku inc. + * Distributed under the terms of the MIT Licence. + * + * Documentation by: + * Axel Dörfler + * John Scipione + * Corresponds to: + * /trunk/headers/os/interface/Bitmap.h rev 42274 + * /trunk/src/kits/interface/Bitmap.cpp rev 42274 + */ + +/*! + \file Bitmap.h + \brief Defines the BBitmap class and global operators and functions for + handling bitmaps. +*/ + + +/*! + \class BBitmap + \ingroup interface + \ingroup libbe + \brief Access and manipulate digital images commonly known as bitmaps. + + A BBitmap is a rectangular map of pixel data. The BBitmap class allows you + to create a bitmap by specifying its pixel data and has operations for + altering and accessing the properties of bitmaps. + + To create a BBitmap object use one of the constructor methods below. You + can determine if initialization was successful by calling the InitCheck() + method. You can determine if a BBitmap object is valid at any time by + calling the IsValid() method. + + An example of creating a new 32x32 pixel BBitmap object and assigning the + icon of the current application looks like this: + \code +BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32)); +appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON); + \endcode + + You can access the properties of a bitmap by calling the Bounds(), + Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(), + and GetOverlayRestrictions() methods. + + To directly set the pixel data of a bitmap call the Bits() or SetBits() + methods or you can use the ImportBits() method to copy the bits from an + existing bitmap. + + You can also draw into a bitmap by attaching a child BView to the bitmap. + To add and remove child BView's to a bitmap call the AddChild() and + RemoveChild() methods respectively. You can access the child views of a + bitmap by calling the CountChildren(), ChildAt(), and FindView() methods. + + For off-screen bitmaps it is important to lock the bitmap before drawing + the pixels and then unlock the bitmap when you are done to prevent + flickering. To lock and unlock a bitmap call the LockBits() and UnLockBits() + methods respectively. To lock and unlock the off-screen window that a + bitmap resides in you should call the Lock() and UnLock() methods. To + determine is a bitmap is currently locked you can call the IsLocked() + method. +*/ + + +/*! + \fn BBitmap::BBitmap(BRect bounds, uint32 flags, color_space colorSpace, + int32 bytesPerRow, screen_id screenID) + \brief Creates and initializes a BBitmap object. + + \param bounds The bitmap dimensions. + \param flags Creation flags. + \param colorSpace The bitmap's color space. + \param bytesPerRow The number of bytes per row the bitmap should use. + \c B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate + value. + \param screenID ??? +*/ + + +/*! + \fn BBitmap::BBitmap(BRect bounds, color_space colorSpace, + bool acceptsViews, bool needsContiguous) + \brief Creates and initializes a BBitmap object. + + \param bounds The bitmap dimensions. + \param colorSpace The bitmap's color space. + \param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if + it shall be possible to attach BView to the bitmap and draw into + it. + \param needsContiguous If \c true a physically contiguous chunk of memory + will be allocated. +*/ + + +/*! + \fn BBitmap::BBitmap(const BBitmap* source, bool acceptsViews, + bool needsContiguous) + \brief Creates a BBitmap object as a clone of another bitmap. + + \param source The source bitmap. + \param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if + it shall be possible to attach BView to the bitmap and draw into + it. + \param needsContiguous If \c true a physically contiguous chunk of memory + will be allocated. +*/ + + +/*! + \fn BBitmap::BBitmap(const BBitmap& source, uint32 flags) + \brief Creates a BBitmap object as a clone of another bitmap. + + \param source The source bitmap. + \param flags Creation flags. +*/ + + +/*! + \fn BBitmap::BBitmap(const BBitmap& source) + \brief Creates a BBitmap object as a clone of another bitmap. + + \param source The source bitmap. +*/ + + +/*! + \fn BBitmap::~BBitmap() + \brief Destructor Method + + Frees all resources associated with this object. +*/ + + +/*! + \name Archiving +*/ + + +//! @{ + + +/*! + \fn BBitmap::BBitmap(BMessage* data) + \brief Unarchives a bitmap from a BMessage. + + \param data The archive. +*/ + + +/*! + \fn BArchivable* BBitmap::Instantiate(BMessage* data) + \brief Instantiates a BBitmap from an archive. + + \param data The archive. + \return A bitmap reconstructed from the archive or \c NULL, if an error + occurred. +*/ + + +/*! + \fn status_t BBitmap::Archive(BMessage* data, bool deep) const + \brief Archives the BBitmap object. + + \param data The archive. + \param deep if \c true, child object will be archived as well. + \return \c B_OK, if everything went fine, an error code otherwise. +*/ + + +//! @} + + +/*! + \fn status_t BBitmap::InitCheck() const + \brief Gets the status of the constructor. + + \returns B_OK if initialization succeeded, otherwise returns an + error status. +*/ + + +/*! + \fn bool BBitmap::IsValid() const + \brief Determines whether or not the BBitmap object is valid. + + \return \c true, if the object is properly initialized, \c false otherwise. +*/ + + +/*! + \name Locking +*/ + + +//! @{ + + +/*! + \fn status_t BBitmap::LockBits(uint32* state) + \brief Locks the bitmap bits so that they cannot be relocated. + + This is currently only used for overlay bitmaps; whenever you + need to access their Bits() you must lock them first. + On resolution change overlay bitmaps can be relocated in memory; + using this call prevents you from accessing an invalid pointer + and clobbering memory that doesn't belong you. + + \param state Unused + \returns \c B_OK on success or an error status code. +*/ + + +/*! + \fn void BBitmap::UnlockBits() + \brief Unlocks the bitmap's buffer. + + Counterpart to BBitmap::LockBits(). +*/ + + +/*! + \fn bool BBitmap::Lock() + \brief Locks the off-screen window that belongs to the bitmap. + + The bitmap must accept views, if locking should work. + + \returns \c true, if the lock was acquired successfully. +*/ + + +/*! + \fn void BBitmap::Unlock() + \brief Unlocks the off-screen window that belongs to the bitmap. + + The bitmap must accept views, if locking should work. +*/ + + +/*! + \fn bool BBitmap::IsLocked() const + \brief Determines whether or not the bitmap's off-screen window is locked. + + The bitmap must accept views, if locking should work. + + \return \c true, if the caller owns a lock , \c false otherwise. +*/ + + +//! @} + + +/*! + \name Accessors +*/ + + +//! @{ + + +/*! + \fn area_id BBitmap::Area() const + \brief Gets the ID of the area the bitmap data reside in. + + \return The ID of the area the bitmap data reside in. +*/ + + +/*! + \fn void* BBitmap::Bits() const + \brief Gets the pointer to the bitmap data. + + \return The pointer to the bitmap data. +*/ + + +/*! + \fn int32 BBitmap::BitsLength() const + \brief Gets the length of the bitmap data. + + \return The length of the bitmap data as an int32. +*/ + + +/*! + \fn int32 BBitmap::BytesPerRow() const + \brief Gets the number of bytes used to store a row of bitmap data. + + \return The number of bytes used to store a row of bitmap data. +*/ + + +/*! + \fn color_space BBitmap::ColorSpace() const + \brief Gets the bitmap's color space. + + \return The bitmap's color space. +*/ + + +/*! + \fn BRect BBitmap::Bounds() const + \brief Gets a BRect the size of the bitmap's dimensions. + + \return A BRect the size of the bitmap's dimensions. +*/ + + +/*! + \fn uint32 BBitmap::Flags() const + \brief Accesses the bitmap's creation flags. + + This method informs about which flags have been used to create the + bitmap. It would for example tell you wether this is an overlay + bitmap. If bitmap creation succeeded, all flags are fulfilled. + + \return The bitmap's creation flags. +*/ + + +/*! + \fn status_t BBitmap::GetOverlayRestrictions(overlay_restrictions* + restrictions) const + \brief Gets the overlay_restrictions structure for this bitmap. + + \note This function is not part of the BeOS R5 API. + + \param restrictions The overlay restrictions flag + + \retval B_OK The overlay restriction structure was found. + \retval B_BAD_TYPE The overlay restriction structure for the bitmap could + not be found. +*/ + + +//! @} + + +/*! + \name Setters +*/ + + +//! @{ + + +/*! + \fn void BBitmap::SetBits(const void* data, int32 length, int32 offset, + color_space colorSpace) + \brief Assigns data to the bitmap. + + Data are directly written into the bitmap's data buffer, being converted + beforehand, if necessary. Some conversions do not work intuitively: + - \c B_RGB32: The source buffer is supposed to contain \c B_RGB24_BIG + data without padding at the end of the rows. + - \c B_RGB32: The source buffer is supposed to contain \c B_CMAP8 + data without padding at the end of the rows. + - other color spaces: The source buffer is supposed to contain data + according to the specified color space being padded to int32 row-wise. + + The currently supported source/target color spaces are + B_RGB{32,24,16,15}[_BIG], \c B_CMAP8 and + B_GRAY{8,1}. + + \note Since this methods is a bit strange to use, Haiku has introduced + the ImportBits() method which is the recommended replacement. + + \param data The data to be copied. + \param length The length in bytes of the data to be copied. + \param offset The offset (in bytes) relative to beginning of the bitmap + data specifying the position at which the source data shall be + written. + \param colorSpace Color space of the source data. +*/ + + +/*! + \fn status_t BBitmap::ImportBits(const void* data, int32 length, int32 bpr, + int32 offset, color_space colorSpace) + \brief Assigns data to the bitmap. + + Data are directly written into the bitmap's data buffer, being converted + beforehand, if necessary. Unlike for SetBits(), the meaning of + \a colorSpace is exactly the expected one here, i.e. the source buffer + is supposed to contain data of that color space. \a bpr specifies how + many bytes the source contains per row. \c B_ANY_BYTES_PER_ROW can be + supplied, if standard padding to int32 is used. + + The currently supported source/target color spaces are + B_RGB{32,24,16,15}[_BIG], \c B_CMAP8 and + B_GRAY{8,1}. + + \note This function is not part of the BeOS R5 API. + + \param data The data to be copied. + \param length The length in bytes of the data to be copied. + \param bpr The number of bytes per row in the source data. + \param offset The offset (in bytes) relative to beginning of the bitmap + data specifying the position at which the source data shall be + written. + \param colorSpace Color space of the source data. + + \retval B_OK The bits were imported into the bitmap. + \retval B_BAD_VALUE \c NULL \a data, invalid \a bpr or \a offset, or + unsupported \a colorSpace. +*/ + + +/*! + \fn status_t BBitmap::ImportBits(const void* data, int32 length, + int32 bpr, color_space colorSpace, BPoint from, BPoint to, + int32 width, int32 height) + \brief Assigns data to the bitmap. + + Allows for a BPoint offset in the source and in the bitmap. The region + of the source at \a from extending \a width and \a height is assigned + (and converted if necessary) to the bitmap at \a to. + + The currently supported source/target color spaces are + B_RGB{32,24,16,15}[_BIG], \c B_CMAP8 and + B_GRAY{8,1}. + + \note This function is not part of the BeOS R5 API. + + \param data The data to be copied. + \param length The length in bytes of the data to be copied. + \param bpr The number of bytes per row in the source data. + \param colorSpace Color space of the source data. + \param from The offset in the source where reading should begin. + \param to The offset in the bitmap where the source should be written. + \param width The width (in pixels) to be imported. + \param height The height (in pixels) to be imported. + + \retval B_OK The bits were imported into the bitmap. + \retval B_BAD_VALUE: \c NULL \a data, invalid \a bpr, unsupported + \a colorSpace or invalid \a width or \a height. +*/ + + +/*! + \fn status_t BBitmap::ImportBits(const BBitmap* bitmap) + \brief Assigns another bitmap's data to this bitmap. + + The supplied bitmap must have the exactly same dimensions as this bitmap. + Its data is converted to the color space of this bitmap. + + The currently supported source/target color spaces are + B_RGB{32,24,16,15}[_BIG], \c B_CMAP8 and + B_GRAY{8,1}. + + \note This function is not part of the BeOS R5 API. + + \param bitmap The source bitmap. + + \retval B_OK The bits were imported into the bitmap. + \retval B_BAD_VALUE \c NULL \a bitmap, or \a bitmap has other dimensions, + or the conversion from or to one of the color spaces is not supported. +*/ + + +/*! + \fn status_t BBitmap::ImportBits(const BBitmap* bitmap, BPoint from, + BPoint to,int32 width, int32 height) + \brief Assigns data to the bitmap. + + Allows for a BPoint offset in the source and in the bitmap. The region + of the source at \a from extending \a width and \a height is assigned + (and converted if necessary) to the bitmap at \a to. The source bitmap is + clipped to the bitmap and they don't need to have the same dimensions. + + The currently supported source/target color spaces are + B_RGB{32,24,16,15}[_BIG], \c B_CMAP8 and + B_GRAY{8,1}. + + \note This function is not part of the BeOS R5 API. + + \param bitmap The source bitmap. + \param from The offset in the source where reading should begin. + \param to The offset in the bitmap where the source should be written. + \param width The width (in pixels) to be imported. + \param height The height (in pixels) to be imported. + + \retval B_OK The bits were imported into the bitmap. + \retval B_BAD_VALUE \c NULL \a bitmap, the conversion from or to one of + the color spaces is not supported, or invalid \a width or \a height. +*/ + + +//! @} + + +/*! + \name Child View Methods +*/ + + +//! @{ + + +/*! + \fn void BBitmap::AddChild(BView* view) + \brief Adds a BView to the bitmap's view hierarchy. + + The bitmap must accept views and the supplied view must not be child of + another parent. + + \param view The view to be added. +*/ + + +/*! + \fn bool BBitmap::RemoveChild(BView* view) + \brief Removes a BView from the bitmap's view hierarchy. + + \param view The view to be removed. +*/ + + +/*! + \fn int32 BBitmap::CountChildren() const + \brief Gets the number of BViews currently belonging to the bitmap. + + \returns The number of BViews currently belonging to the bitmap. +*/ + + +/*! + \fn BView* BBitmap::ChildAt(int32 index) const + \brief Gets the BView at a certain index in the bitmap's list of views. + + \param index The index of the BView to be returned. + \returns The BView at index \a index or \c NULL if the index is out of + range. +*/ + + +/*! + \fn BView* BBitmap::FindView(const char* viewName) const + \brief Accesses a bitmap's child BView with a the name \a viewName. + + \param viewName The name of the BView to be returned. + \returns The BView with the name \a name or \c NULL if the bitmap doesn't + know a view with that name. +*/ + + +/*! + \fn BView* BBitmap::FindView(BPoint point) const + \brief Accesses a bitmap's BView at a certain location. + + \param point The location. + \returns The BView with located at \a point or \c NULL if the bitmap + doesn't know a view at this location. +*/ + + +//! @} diff --git a/docs/user/interface/Box.dox b/docs/user/interface/Box.dox index 4eff31f53f..8382b45f82 100644 --- a/docs/user/interface/Box.dox +++ b/docs/user/interface/Box.dox @@ -3,166 +3,253 @@ * Distributed under the terms of the MIT Licence. * * Documentation by: - * Clark Gaeble - * Adrien Destugues + * Clark Gaeble + * Adrien Destugues + * John Scipione * Corresponds to: - * /trunk/headers/os/interface/Box.h rev 39685 - * /trunk/src/kits/interface/Box.cpp rev 39685 + * /trunk/headers/os/interface/Box.h rev 42274 + * /trunk/src/kits/interface/Box.cpp rev 42274 + /*! -\file Box.h -\brief Defines the BBox class + \file Box.h + \brief Defines the BBox class */ -/*! \class BBox + +/*! + \class BBox \ingroup interface - \brief Class just drawing a square box with a label in a window. - - A Box represents a square on the interface with dimensions, an optional - name, and no interactivity. + \brief The BBox class is used to draw a square box in a window with an + optional label to group related subviews. - This would be used to visually group elements together. + A BBox is an organizational interface element used to group related views + together 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 + as a checkbox or dropdown box. See SetLabel() for more details on setting + the label on a BBox. */ -/*! \fn BBox::BBox(BRect frame, const char *name = NULL, 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 Box from a set of dimensions. - 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. +/*! + \fn BBox::BBox(BRect frame, const char *name = NULL, + 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. - \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 + \note This is the only constructor that can be used if the BBox 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 box. See BView page for more - info. - \param border Sets the initial style of the border. See SetBorder for - more details. + \param flags Behavior flags for the BBox. See BView for details. + \param border The border_style of the BBox. */ -/*! \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 Box, with dimensions defined automatically by the +/*! + \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. - \param name The name of the box. - \param flags Behavior flags for the box. - \param border Defines the initial border style. - \param child Adds an initial child to the box. See: Layout Kit + \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. */ -/*! \fn BBox::BBox(border_style border, BView* child) - \brief Constructs an anonymous Box, with a defined border style and a child. +/*! + \fn BBox::BBox(border_style border, BView* child) + \brief Constructs an anonymous BBox, with a defined border style and + a child. - There can only be a single child view in the box. This view can, however, - act as a nesting container if you need more things to show inside the box. - - \param border The initial border style of the box. - \param child The child of the Box. + 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. */ -/*! \fn BBox::BBox(BMessage* archive) - \brief For archive restoration, allows a box to be constructed from an - archive message. +/*! + \fn BBox::BBox(BMessage* archive) + \brief For archive restoration, allows a BBox to be constructed from an + \a archive message. - You don't usually call this directly, if you want to build a BBox from a - message, prefer calling Instantiate, which can properly handle errors. + 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. - If the archive is a deep one, the box will also unarchive all of its - children recursively. + If the \a archive is a deep one, the BBox will also unarchive all + of its children recursively. - \param archive The archive to restore from. + \param archive The \a archive to restore from. */ -/*! \fn static BArchivable* BBox::Instantiate(BMessage* archive) - \brief Creates a new BBox from an archive. +/*! + \fn BBox::~BBox() + \brief Destructor method. - If the message is a valid box, an instance of BBox (created from the - archive) will be returned. Otherwise, this function will return NULL. + Calling the destructor will also free the memory used by the box's label + if it has one. */ -/*! \fn virtual status_t BBox::Archive(BMessage* archive, bool deep = true) const; - \brief Archives the box into archive. +/*! + \fn static BArchivable* BBox::Instantiate(BMessage* archive) + \brief Creates a new BBox from an \a archive. - \param archive The target archive which the box data will go into. - \param deep Whether or not to recursively archive the children. - \returns B_OK if the archive was successful. + If the message is a valid BBox then an instance of BBox 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. */ -/*! \fn virtual void BBox::SetBorder(border_style border) +/*! + \fn virtual status_t BBox::Archive(BMessage* archive, + bool deep = true) const; + \brief Archives the BBox into \a archive. + + \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. +*/ + + +/*! + \fn virtual void BBox::SetBorder(border_style border) \brief Sets the border style. - Possible values are B_PLAIN_BORDER (a single 1-pixel line border), - B_FANCY_BORDER (the default, slightly beveled look), and B_NO_BORDER, which - is used to make an invisible box. + 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. */ -/*! \fn border_style BBox::Border() const - \brief Gets the border style. +/*! + \fn border_style BBox::Border() const + \brief Gets the current border_style of a BBox. + + \returns The border_style flag that is currently set to the BBox. */ -/*! \fn float BBox::TopBorderOffset() - \brief Gets the distance from the very top of the Box to the top border - line, in pixels. +/*! + \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. + + \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. + 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. - You can use this value to line up two boxes visually, if one has a label and - the other has not. + \returns The distance offset of the BBox as a \c float. */ -/*! \fn BRect BBox::InnerFrame() - \brief Returns the rectangle just inside the border. +/*! + \fn BRect BBox::InnerFrame() + \brief Gets the rectangle just inside the border of the BBox as a BRect. + + \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. */ -/*! \fn void BBox::SetLabel(const char* string) - \brief Sets the label's text. +/*! + \fn void BBox::SetLabel(const char* string) + \brief Sets the box's label text. - This text is shown as the box title on screen, so the user can identify the - purpose of it. + Below is an example of a BBox with a simple text label: + + \image html BBox_example.png + + The code to create a BBox with a text label looks like this: + + \code +fIconBox = new BBox("Icon Box"); +fIconBox->SetLabel("Icon"); + \endcode + + \param string The label text string to set as the box's title. */ -/*! \fn status_t BBox::SetLabel(BView* viewLabel) +/*! + \fn status_t BBox::SetLabel(BView* viewLabel) \brief Sets the label from a pre-existing BView. - You can use any type of BView for this, such as a BPopupMenu. - This version of SetLabel is much more powerful than - SetLabel(const char* string). It allows building a box which contents can - be changed depending on the label widget. + 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: + + \image html BBox_with_checkbox.png + + The code to create such a BBox looks like this: + + \code +fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box", + "Enable virtual memory", new BMessage(kVirtualMemoryEnabled)); + +BBox* fVirtualMemoryBox = new BBox("Virtual memory box"); +fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox); + \endcode + + \param viewLabel A BView. + \returns \c B_OK */ -/*! \fn const char* BBox::Label() const +/*! + \fn const char* BBox::Label() const \brief Gets the label's text. 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 LabelView. + + \returns The label text of the BBox as a const char* if the BBox + 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. */ -/*! \fn virtual void BBox::Draw(BRect updateRect) - \brief Draws onto the parent window the part of the box that intersects +/*! + \fn virtual void BBox::Draw(BRect updateRect) + \brief Draws onto the parent window the part of the BBox that intersects the dirty area. - This is an hook function called by the interface kit. You don't have to call - it yourself. If you need to force redrawing of (part of) the box, consider + 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. \param updateRect The area that needs to be redrawn. Note the box may draw @@ -170,83 +257,95 @@ */ -/*! \fn virtual void BBox::AttachedToWindow() - \brief Hook called when the box is attached to a window. +/*! + \fn virtual void BBox::AttachedToWindow() + \brief Hook method called when the BBox is attached to a window. - This function sets the box background color to the parent's one. + This method sets the box's background color to the background of the + parent view. - If you are using the layout system, the box is also resized depending - on the layout of the parent view. + If you are using the layout system, the BBox is also resized according to + the layout of the parent view. */ -/*! \fn virtual void BBox::FrameResized(float width, float height) - \brief Called when the box needs to change its size. +/*! + \fn virtual void BBox::FrameResized(float width, float height) + \brief Called when the BBox needs to change its size. - This function may be called either because the window in which the box is + This method may be called either because the window in which the BBox is was resized, or because the window layout was otherwise altered. - It recomputes the layouting of the box (including label and contents) and - makes it redraw itself as needed. + It recomputes the layout of the BBox (including label and contents) and + makes it redraw as necessary. */ -/*! \fn virtual void BBox::ResizeToPreferred() - \brief Resizes the box to its preferred dimensions. +/*! + \fn virtual void BBox::ResizeToPreferred() + \brief Resizes the BBox to its preferred dimensions. 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 the box would prefer to be. +/*! + \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 box (which canbe done only in layouted mode). + for the BBox (which can be done only if the BBox is configured to + use the Layout Kit). - \note Either one of the parameters may be set to NULL if you only want to - get the other one. + \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 _width An output parameter. The width of the preferred size is - placed in here. - \param _height An output parameter. The height of the preferred size is - placed in here. + \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. */ -/*! \fn virtual BSize BBox::MinSize() - \brief Gets the minimum possible size of the Box. +/*! + \fn virtual BSize BBox::MinSize() + \brief Gets the minimum possible size of the BBox. - Drawing the box at this size ensures the label and the child view are + 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. */ -/*! \fn virtual BSize BBox::MaxSize() - \brief Gets the maximum possible size of the Box. +/*! + \fn virtual BSize BBox::MaxSize() + \brief Gets the maximum possible size of the BBox. The maximum size depends on the child view's one. + + \returns A BSize of the maximum possible size of the BBox. */ -/*! \fn virtual BSize BBox::PreferredSize() +/*! + \fn virtual BSize BBox::PreferredSize() \brief Returns the box's preferred size. This is the same as GetPreferredSize, but using the more convenient BSize struct. + + \returns A BSize of the minimum possible size of the BBox. */ -/*! \fn virtual void BBox::DoLayout() - \brief Lays out the box. Moves everything to its appropriate position. +/*! + \fn virtual void BBox::DoLayout() + \brief Lays out the BBox. Moves everything into its appropriate position. - This only works if the box uses the layout system, ie., was created with - one of the BRect-less constructors. + This only works if the BBox uses the layout system from the Layout Kit, + i.e. it was created with one of the BRect-less constructors. - Once the size of the box is known, from layouting of the parent views, this - function is called so the box 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 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. */ diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox new file mode 100644 index 0000000000..d3a510be38 --- /dev/null +++ b/docs/user/interface/Button.dox @@ -0,0 +1,456 @@ +/* + * Copyright 2011, Haiku inc. + * Distributed under the terms of the MIT Licence. + * + * Documentation by: + * John Scipione + * Corresponds to: + * /trunk/headers/os/interface/Button.h + * /trunk/src/kits/interface/Button.cpp + + +/*! + \file Button.h + \brief Describes the BButton class. +*/ + + +/*! + \class BButton Button.h + \ingroup interface + \brief A BButton is a labeled on-screen button. + + A BButton control is used to initiate an action. An action is activated + by clicking on the button with the mouse or by a keyboard button. + If the BButton is the default button for the active window then you can + activate it by pushing the Enter key. + + \image html BButton_example.png + + A BButton, unlike other user interface elements such as check boxes and + radio buttons has only a single state. During a click event the + BButton's value is set to \c 1, (\c B_CONTROL_ON) otherwise this value + is \c 0 (\c B_CONTROL_OFF). + + BButton inherits from the BControl class. +*/ + + +/*! + \fn BButton::BButton(BRect frame, const char* name, const char* label, + BMessage* message, uint32 resizingMode, uint32 flags) + \brief Creates and initializes a BButton control. + + \note A BButton created with a constructor that includes a frame + parameter does \b not utilize the Layout Kit to position and size the + control. + + BControl initializes the button's label and assigns it a message that + identifies the action that should be carried out when the button is + pressed. When the button is attached to a window it is resizes to the + height of the button's frame rectangle to fit the button's border and + label in the button's font. + + The \a frame, \a name, \a resizingMode, and \a flags parameters are + passed up the inheritance chain to the BView class. + + \param frame The frame rectangle that the button is draw into. + \param name The name of the button + \param label The button label text + \param message The BButtons's action message + \param resizingMode Mask sets the parameters by which the BButton can be + resized. It should be set to one option for vertical resizing combined + with one option for horizontal resizing. + \n\n Horizontal resizing options are + \li \c B_FOLLOW_LEFT + \li \c B_FOLLOW_RIGHT + \li \c B_FOLLOW_LEFT_RIGHT + \li \c B_FOLLOW_H_CENTER + + Vertical resizing options are + \li \c B_FOLLOW_TOP + \li \c B_FOLLOW_BOTTOM + \li \c B_FOLLOW_TOP_BOTTOM + \li \c B_FOLLOW_V_CENTER + + There are two other possibilities + \li \c B_FOLLOW_ALL_SIDES + \li \c B_FOLLOW_NONE + + See BView for more information on resizing options. + \param flags The flags mask sets what notifications the BButton can receive. + \n\n Any combination of the following options is allowed + \li \c B_WILL_DRAW + \li \c B_PULSE_NEEDED + \li \c B_FRAME_EVENTS + \li \c B_FULL_UPDATE_ON_RESIZE + \li \c B_NAVIAGBLE + \li \c B_NAVIAGBLE_JUMP + \li \c B_SUBPIXEL_PRECISE + + See BView for more information on \a flags. +*/ + + +/*! + \fn BButton::BButton(const char* name, const char* label, BMessage* message, + uint32 flags) + \brief Creates and initializes a BButton control. + + BControl initializes the button's label and assigns it a message that + identifies the action that should be carried out when the button is + pressed. When the button is attached to a window it is resizes to the + height of the button's frame rectange to fit the button's border and + label in the button's font. + + \param name The \a name of the button + \param label The button's \a label text + \param message The button's action \a message + \param flags The \a flags mask sets what notifications the button can + receive. Any combination of the following options is allowed: + \li \c B_WILL_DRAW + \li \c B_PULSE_NEEDED + \li \c B_FRAME_EVENTS + \li \c B_FULL_UPDATE_ON_RESIZE + \li \c B_NAVIAGBLE + \li \c B_NAVIAGBLE_JUMP + \li \c B_SUBPIXEL_PRECISE + + See BView for more information on \a flags. +*/ + + +/*! + \fn BButton::BButton(const char* label, BMessage* message) + \brief Creates and initializes a BButton control. + + Creates the button with the specified \a label. The action carried out + by the button is specified by the \a message. + + \param label The button's \a label text + \param message The buttons action \a message +*/ + + +/*! + \fn BButton::~BButton() + \brief Destructor method. + + Standard Destructor. +*/ + + +/*! \fn BButton::BButton(BMessage* archive) + \brief Creates a new BButton from an \a archive. + + 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. + + \returns An instance of BButton if the \a archive is valid or \c NULL. +*/ + + +/*! + \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. +*/ + + +/*! + \fn void BButton::Draw(BRect updateRect) + \brief Draws the button and sets its label. + + \param updateRect The BRect which the button is drawn into. +*/ + + +/*! + \fn void BButton::MouseDown(BPoint point) + \brief Hook method to respond to a MouseDown event. + + \param point The point on the screen that the mouse pointer is located at. +*/ + + +/*! + \fn void BButton::AttachedToWindow() + \brief Hook method that is called when the BButton view is attached + to the window. +*/ + + +/*! + \fn void BButton::KeyDown(const char *bytes, int32 numBytes) + \brief Hook method that is called when a keyboard key is pushed down. + to the window. + + \param bytes The key pressed. + \param numBytes The number of keys pressed. +*/ + + +/*! + \fn void BButton::MakeDefault(bool flag) + \brief Make the BButton the default button i.e. it will be activated + when the user pushes the \key{Enter} key. + + \param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned + by the Layout Kit. +*/ + + +/*! + \fn void BButton::SetLabel(const char *string) + \brief Sets the BButton's label. + + \param string The string to set the label to. +*/ + + +/*! + \fn bool BButton::IsDefault() const + \brief Returns whether or not the BButton is the default button or not, i.e. + it responds to the \key{Enter} key. + + \retval true The button is the default button. + \retval false The button is \b not the default button. +*/ + + +/*! + \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. + + \note This method can be overridden in order to take a different action + when the value changes. + + \param value The value to set to the BButton to. Options include: + \li \c 0 (\c B_CONTROL_OFF) + \li \c 1 (\c B_CONTROL_ON) + + \see BControl::SetValue() +*/ + + +/*! + \fn void BButton::GetPreferredSize(float *_width, float *_height) + \brief Gets the dimensions that the BButton would prefer to be. + + The size is computed from the children sizes, unless it was explicitly set + for the BButton (which can be done only if the BButton is configured to + use the Layout Kit). + + \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. +*/ + + +/*! + \fn void BButton::ResizeToPreferred() + \brief Resizes the BButton to its preferred size. + + \see BControl::ResizeToPreferred() +*/ + + +/*! + \fn status_t BButton::Invoke(BMessage *message) + \brief The BButton is invoked from a message. + + This method is used to post a message when the button is clicked or + activated by a keyboard button. You can set the object that will + handle the message by calling a BControl::SetTarget() from a + BInvoker inherited control. A model for the message is set by the + BButton constructor or by the BControl::SetMessage() method + inherited from BInvoker. + + \returns B_OK If the BButton was invoked, otherwise an error + \a status_t flag is returned. + + \see BControl::Invoke() +*/ + + +/*! + \fn void BButton::FrameMoved(BPoint newLocation) + \brief Move the frame of the BButton. + + \param newLocation The location on the screen that the BButton + is moved to. + + \see BControl::FrameMoved(); +*/ + + +/*! + \fn void BButton::FrameResized(float width, float height) + \brief Resize the BButton. + + \param width the new \a width of the BButton + \param height the new \a height of the BButton + + \see BControl::FrameResized(); +*/ + + +/*! + \fn void BButton::MakeFocus(bool focused) + \brief Focus or unfocus the BButton. + + \param focused If \c true focus the BButton, otherwise unfocus the BButton. + + \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. + + \param code The \a perform_code. One of the following: + \li \c PERFORM_CODE_MIN_SIZE + \li \c PERFORM_CODE_MAX_SIZE + \li \c PERFORM_CODE_PREFERRED_SIZE + \li \c PERFORM_CODE_LAYOUT_ALIGNMENT + \li \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH + \li \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH + \li \c PERFORM_CODE_SET_LAYOUT + \li \c PERFORM_CODE_INVALIDATE_LAYOUT + \li \c PERFORM_CODE_DO_LAYOUT + \param _data Data to use to act on. + + \returns \c B_OK if the action was successful or an error code if not. +*/ + + +/*! + \fn void BButton::InvalidateLayout(bool descendants) + \brief Redraws the BButton. + + \param descendants Redraw subviews as well. +*/ + + +/*! + \fn BSize BButton::MinSize() + \brief Returns the minimum size of the BButton. + + \returns The minimum BButton size as a BSize +*/ + + +/*! + \fn BSize BButton::MaxSize() + \brief Returns the maximum size of the BButton. + + \returns The maximum BButton size as a BSize +*/ + + +/*! + \fn BSize BButton::PreferredSize() + \brief Returns the preferred size of the BButton. + + \returns The preferred BButton size as a BSize +*/ + diff --git a/docs/user/interface/GridLayout.dox b/docs/user/interface/GridLayout.dox index bea3595786..f610cacd0b 100644 --- a/docs/user/interface/GridLayout.dox +++ b/docs/user/interface/GridLayout.dox @@ -1,3 +1,21 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + * Corresponds to: + * /trunk/headers/os/interface/GridLayout.h rev 38207 + * /trunk/src/kits/interface/GridLayout.cpp rev 38207 + */ + + +/*! + \file GridLayout.h + Provides the BGridLayout class. +*/ + + /*! \class BGridLayout \ingroup interface @@ -18,150 +36,199 @@ /*! \fn BGridLayout::BGridLayout(float horizontal = 0.0f, float vertical = 0.0f) - \brief Create a BGridLayout with \c horizontal space between columns and - \c vertical space between rows. + \brief Create a BGridLayout with \a horizontal space between columns and + \a vertical space between rows. */ /*! \fn BGridLayout::BGridLayout(BMessage* from) \brief Archive constructor. + + \param from The message to build the BGridLayout from. +*/ + + +/*! + \fn BGridLayout::~BGridLayout() + \brief Destructor method. + + Standard Destructor. */ /*! \fn int32 BGridLayout::CountColumns() const \brief Returns the number of active columns in this layout. + + \returns The number of active columns in the layout. */ /*! \fn int32 BGridLayout::CountRows() const \brief Returns the number of active rows in this layout. + + \returns the number of active rows in the layout. */ /*! \fn float BGridLayout::HorizontalSpacing() const \brief Returns the spacing between columns for this layout. + + \returns The spacing between columns for the layout. */ /*! \fn float BGridLayout::VerticalSpacing() const \brief Returns the spacing between rows for this layout. + + \returns The spacing between rows for the layout. */ /*! \fn void BGridLayout::SetHorizontalSpacing(float spacing); \brief Set the spacing between columns for this layout. + + \param spacing The number of pixels of spacing to set. */ /*! \fn void BGridLayout::SetVerticalSpacing(float spacing) \brief Set the spacing between rows for this layout. + + \param spacing The number of pixels of spacing to set. */ /*! \fn void BGridLayout::SetSpacing(float horizontal, float vertical) \brief Set the spacing between columns and rows for this layout. + + \param horizontal The number of \a horizontal pixels of spacing to set. + \param vertical The number of \a vertical pixels of spacing to set. */ /*! \fn float BGridLayout::ColumnWeight(int32 column) const - \brief Returns the weight for \c column. + \brief Returns the weight for the specified \a column. + + \returns The \a column weight as a float. */ /*! \fn void BGridLayout::SetColumnWeight(int32 column, float weight) - \brief Set the weight for \c column to \c weight. + \brief Set the weight for \a column to \a weight. + + \param column The column to set. + \param weight The weight to set. */ /*! \fn float BGridLayout::MinColumnWidth(int32 column) const - \brief Returns the minimum width for \c column. + \brief Returns the minimum width for \a column. + + \param column The column to get the minimum width of. + + \returns The minimum width for \a column as a float. */ /*! \fn void BGridLayout::SetMinColumnWidth(int32 column, float width) - \brief Sets the minimum width for \c column to \c width. + \brief Sets the minimum width for \a column to \a width. + + \param column The \a column to set the minimum width of. + \param width The \a width to set. */ /*! \fn float BGridLayout::MaxColumnWidth(int32 column) const - \brief Returns the maximum width for \c column. + \brief Returns the maximum width for \a column. + + \param column The column to get the maximum width of. + + \returns The maximum width for \a column as a float. */ /*! \fn void BGridLayout::SetMaxColumnWidth(int32 column, float width) - \brief Sets the maximum width for \c column to \c width. + \brief Sets the maximum width for \a column to \a width. + + \param column The column to set the maximum width of. + \param width The \a width to set. */ /*! \fn float BGridLayout::RowWeight(int32 row) const - \brief Returns the weight for \c row. + \brief Returns the weight of the specified \a row. + + \returns The weight of the \a row. */ /*! \fn void BGridLayout::SetRowWeight(int32 row, float weight) - \brief Set the weight for \c row to \c weight. + \brief Set the weight for \a row to \a weight. + + \param row The \a row number. + \param weight The \a */ /*! \fn float BGridLayout::MinRowHeight(int32 row) const - \brief Returns the minimum height for \c row. + \brief Returns the minimum height for \a row. */ /*! \fn void BGridLayout::SetMinRowHeight(int32 row, float height) - \brief Sets the minimum height for \c row to \c width. + \brief Sets the minimum height for \a row to \a width. */ /*! \fn float BGridLayout::MaxRowHeight(int32 row) const - \brief Returns the maximum height for \c row. + \brief Returns the maximum height for \a row. */ /*! \fn void BGridLayout::SetMaxRowHeight(int32 row, float height) - \brief Sets the maximum height for \c row to \c width. + \brief Sets the maximum height for \a row to \a width. */ /*! \fn BLayoutItem* BGridLayout::AddView(BView* child) - \brief Adds \c child to this layout in the first empty cell available, or + \brief Adds \a child to this layout in the first empty cell available, or in a new column in the first row if there are no emtpy cells. */ /*! \fn BLayoutItem* BGridLayout::AddView(int32 index, BView* child); - \copybrief BGridLayout::AddView(BView*) + \brief BGridLayout::AddView(BView*) */ /*! \fn BLayoutItem* BGridLayout::AddView(BView* child, int32 column, int32 row, int32 columnCount = 1, int32 rowCount = 1); - \brief Adds \c child to this layout at \c column and \c row. \c child may - also occupy additional cells if \c columnCount or \c rowCount are - greater than 1. + \brief Adds \a child to this layout at \a column and \a row. \a child may + also occupy additional cells if \a columnCount or \a rowCount are + greater than \c 1. Fails and returns NULL if the requested area is occupied, or if internal memory allocations fail. @@ -170,24 +237,24 @@ /*! \fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item) - \brief Adds \c item to this layout in the first empty cell available, or + \brief Adds \a item to this layout in the first empty cell available, or in a new column in the first row if there are no emtpy cells. */ /*! \fn BLayoutItem* BGridLayout::AddItem(int32 index, BLayoutItem* item); - \copybrief BGridLayout::AddItem(BLayoutItem*) + \brief BGridLayout::AddItem(BLayoutItem*) */ /*! \fn BLayoutItem* BGridLayout::AddItem(BLayoutItem* item, int32 column, int32 row, int32 columnCount = 1, int32 rowCount = 1); - \brief Adds \c item to this layout at \c column and \c row. \c item may - also occupy additional cells if \c columnCount or \c rowCount are + \brief Adds \a item to this layout at \a column and \a row. \a item may + also occupy additional cells if \a columnCount or \a rowCount are greater than 1. - Fails and returns NULL if the requested area is occupied, or if internal + Fails and returns \c NULL if the requested area is occupied, or if internal memory allocations fail. */ diff --git a/docs/user/interface/GroupLayout.dox b/docs/user/interface/GroupLayout.dox index 4d283d8e96..5562aa00b8 100644 --- a/docs/user/interface/GroupLayout.dox +++ b/docs/user/interface/GroupLayout.dox @@ -1,3 +1,20 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + * Corresponds to: + * /trunk/headers/os/interface/GroupLayout.h rev 38207 + * /trunk/src/kits/interface/GroupLayout.cpp rev 38207 + */ + + +/*! \file GroupLayout.h + Describes the BGroupLayout class +*/ + + /*! \class BGroupLayout \ingroup interface \ingroup layout @@ -29,118 +46,111 @@ */ -/*! - \fn BGroupLayout::BGroupLayout(enum orientation, float spacing) +/*! \fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing) \brief Creates a new BGroupLayout. - \param orientation The orientation of this BGroupLayout. + \param orientation The #orientation of this BGroupLayout. \param spacing The spacing between BLayoutItems in this BGroupLayout. */ -/*! - \fn BGroupLayout::BGroupLayout(BMessage* from) - \brief Archive constructor. +/*! \fn BGroupLayout::~BGroupLayout() + \brief Destructor method. + + Standard Destructor. */ -/*! - \fn float BGroupLayout::Spacing() const +/*! \fn BGroupLayout::BGroupLayout(BMessage* from) + \brief Archive constructor. + + \param from The message to construct the BGroupLayout from. +*/ + + +/*! \fn float BGroupLayout::Spacing() const \brief Get the amount of spacing (in pixels) between each item. */ -/*! - \fn void BGroupLayout::SetSpacing(float spacing) +/*! \fn void BGroupLayout::SetSpacing(float spacing) \brief Set the amount of spacing (in pixels) between each item. */ -/*! - \fn orientation BGroupLayout::Orientation() const - \brief Get the orientation of this BGroupLayout. +/*! \fn orientation BGroupLayout::Orientation() const + \brief Get the #orientation of this BGroupLayout. */ -/*! - \fn void BGroupLayout::SetOrientation(enum orientation) - \brief Set the orientation of this BGroupLayout. - \param orientation The new orientation of this BGroupLayout. +/*! \fn void BGroupLayout::SetOrientation(enum orientation orientation) + \brief Set the #orientation of this BGroupLayout. + \param orientation The new #orientation of this BGroupLayout. */ -/*! - \fn float BGroupLayout::ItemWeight(int32 index) const - \brief Get the weight of the item at \c index. +/*! \fn float BGroupLayout::ItemWeight(int32 index) const + \brief Get the weight of the item at \a index. */ -/*! - \fn void BGroupLayout::SetItemWeight(int32 index, float weight) - \brief Set the weight of the item at \c index. +/*! \fn void BGroupLayout::SetItemWeight(int32 index, float weight) + \brief Set the weight of the item at \a index. */ -/*! - \fn BLayoutItem* BGroupLayout::AddView(BView* child) +/*! \fn BLayoutItem* BGroupLayout::AddView(BView* child) \brief Adds \a child to this layout as the last item. In a vertical - BGroupLayout, \c child will be on the right, in a horizontal - BGroupLayout, \c child will be at the bottom. + BGroupLayout, \a child will be on the right, in a horizontal + BGroupLayout, \a child will be at the bottom. - \c child will have a weight of 1.0f. + \a child will have a weight of \c 1.0f. */ -/*! - \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child) - \brief Adds \c child to this layout at \c index. +/*! \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child) + \brief Adds \a child to this layout at \a index. - \c child will have a weight of 1.0f. + \a child will have a weight of \c 1.0f. */ -/*! - \fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight) - \brief Adds \c child to the end of this layout with a weight of - \c weight. +/*! \fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight) + \brief Adds \a child to the end of this layout with a weight of + \a weight. */ -/*! - \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child, +/*! \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child, float weight) - \brief Adds \c child this layout at \c index with a weight of - \c weight. + \brief Adds \a child this layout at \a index with a weight of + \a weight. */ -/*! - \fn bool BGroupLayout::AddItem(BLayoutItem* item) +/*! \fn bool BGroupLayout::AddItem(BLayoutItem* item) \brief Adds \a item to this layout as the last item. In a vertical - BGroupLayout, \c item will be on the right, in a horizontal - BGroupLayout, \c item will be at the bottom. + BGroupLayout, \a item will be on the right, in a horizontal + BGroupLayout, \a item will be at the bottom. - \c item will have a weight of 1.0f. + \a item will have a weight of \c 1.0f. */ -/*! - \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item) - \brief Adds \c item to this layout at \c index. +/*! \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item) + \brief Adds \a item to this layout at \a index. - \c item will have a weight of 1.0f. + \a item will have a weight of \c 1.0f. */ -/*! - \fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight) - \brief Adds \c item to the end of this layout with a weight of - \c weight. +/*! \fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight) + \brief Adds \a item to the end of this layout with a weight of + \a weight. */ -/*! - \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight) - \brief Adds \c item this layout at \c index with a weight of - \c weight. +/*! \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight) + \brief Adds \a item this layout at \a index with a weight of + \a weight. */ diff --git a/docs/user/interface/InterfaceDefs.dox b/docs/user/interface/InterfaceDefs.dox new file mode 100644 index 0000000000..dc6564a142 --- /dev/null +++ b/docs/user/interface/InterfaceDefs.dox @@ -0,0 +1,65 @@ +/* + * Copyright 2001-2011, Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + */ + +/*! \file InterfaceDefs.h + \brief Defines standard interface definitions for controls. +*/ + +/*! \enum border_style + Collection of flags that determine the border style drawn around a BBox. +*/ + +/*! \var border_style B_PLAIN_BORDER + + \image html B_PLAIN_BORDER.png + + The right and bottom sides of the box are darker than the top and + left sides to produce a shadow effect and make the box look like it + is raised slightly above the surrounding surface. +*/ + +/*! \var border_style B_FANCY_BORDER + + \image html B_FANCY_BORDER.png + + The border is a bevelled to give it a 3D effect. The border is uniform + in appearance on all four sides. This is the default appearance. +*/ + +/*! \var border_style B_NO_BORDER + No border. +*/ + +/*! \enum orientation +Orientation flag sets the layout to either horizontal or vertical + alignment. +*/ + +/*! \var orientation B_HORIZONTAL + Horizontal alignment +*/ + +/*! \var orientation B_VERTICAL + Vertical alignment +*/ + +/*! \enum button_width + Collection of flags that determine how wide to draw the buttons in a + BAlert dialog. +*/ + +/*! \var button_width B_WIDTH_AS_USUAL + Set the width of each button based on the standard width. +*/ + +/*! \var button_width B_WIDTH_FROM_WIDEST + Set the width of each button based on the width of the widest button. +*/ + +/*! \var button_width B_WIDTH_FROM_LABEL + Set the width of each button to accomidate the width of the button's + label. +*/ + diff --git a/docs/user/interface/Layout.dox b/docs/user/interface/Layout.dox index a346ae2cc2..4345797137 100644 --- a/docs/user/interface/Layout.dox +++ b/docs/user/interface/Layout.dox @@ -3,7 +3,7 @@ * Distributed under the terms of the MIT License. * * Documentation by: - * Alex Wilson + * Alex Wilson * Corresponds to: * /trunk/headers/os/interface/Layout.h rev 38207 * /trunk/src/kits/interface/Layout.cpp rev 38207 @@ -11,21 +11,22 @@ /*! -\file Layout.h -\brief Defines the BLayout class. + \file Layout.h + \brief Defines the BLayout class. */ -/*! \class BLayout +/*! + \class BLayout \ingroup interface \ingroup layout \ingroup libbe \brief The BLayout class provides an interface, and some basic - implementation to manage the positioning and sizing of BLayoutItems. + implementation to manage the positioning and sizing of BLayoutItem s. - BLayouts can be attached to a BView, managing the BLayoutItems and BViews - that reside in that view, or can be nested within another BLayout as a - BLayoutItem. + BLayouts can be attached to a BView, managing the BLayoutItem's and + BView's that reside in that view, or can be nested within another + BLayout as a BLayoutItem. Before adding a BLayoutItem to a BLayout, that layout must have a target view. When a BLayout is attached directly to a BView via BView::SetLayout() @@ -34,7 +35,7 @@ target of the layout it's nested in, if it does not have a target already. You can retrieve the target view for a layout with the TargetView() method. When adding a BLayoutItem to a BLayout, the item's view (as returned by - BLayoutItem::View()) is added to the layout's target view. + BLayoutItem::View()) is added to the BLayout's target view. \code BView* topView = new BGroupView(); @@ -64,97 +65,107 @@ topLayout->AddItem(nestedLayoutWithView); assume that it will break some time in the future. */ - -/*! \fn BLayout::BLayout() + +/*! + \fn BLayout::BLayout() \brief Default constructor. - After this constructor has finished, this BLayout holds no BLayoutItems and - does not have a target BView. + After this constructor has finished, this BLayout holds no + BLayoutItem's and does not have a target BView. \warning Because a new BLayout does not have a target BView, calls to the AddItem() and AddView() will fail methods will fail. */ -/*! \fn BLayout::BLayout(BMessage* archive) +/*! + \fn BLayout::BLayout(BMessage* archive) \brief Archive constructor. + + \param archive The archive message. */ -/*! \fn BLayout::~BLayout() - \brief Destructor, deletes all BLayoutItems that this layout manages, - and detaches from this BLayout's owner view if there is one. +/*! + \fn BLayout::~BLayout() + \brief Destructor, deletes all BLayoutItem's that this layout manages, + and detaches from this BLayout's owner view if there is one. - Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also + Each BLayoutItem's BView (as returned by BLayoutItem::View()) is also removed from their parent. - \note Because nested BLayouts are treated as BLayoutItems, any layouts - nested in this BLayout will be deleted. + \note Because nested BLayout's are treated as BLayoutItem's, + any layouts nested in this BLayout will be deleted. */ /*! \name BView targeting and attachment information. - - @{ */ -/*! \fn BView* BLayout::Owner() const +//! @{ + + +/*! + \fn BView* BLayout::Owner() const \brief Returns the Owner of this layout, i.e. the view this layout manages. */ -/*! \fn BView* BLayout::TargetView() const +/*! + \fn BView* BLayout::TargetView() const \brief Returns the target view of this layout. - The target view of a layout becomes the parent of any BViews in this layout, - as well as the BViews returned by BLayoutItem::View() for each BLayoutItem - in this layout. + The target view of a layout becomes the parent of any BView's in this + layout, as well as the BView's returned by BLayoutItem::View() for + each BLayoutItem in this layout. */ -/*! \fn BView* BLayout::View() - \brief Returns the same BView* as BLayout::Owner(), this method is inherited - from BLayoutItem. -*/ - - -//@} - - /*! - \name Adding, removing, counting and accessing BViews and BLayoutItems in \ - this BLayout. - - @{ + \fn BView* BLayout::View() + \brief Returns the same BView* as BLayout::Owner(), this method is + inherited from BLayoutItem. */ +//! @} + + +/*! + \name Adding, removing, counting and accessing BLayout children +*/ + + +//! @{ + + /*! \fn BLayoutItem* BLayout::AddView(BView* child) \brief Creates a BLayoutItem to represent a BView, and adds that item to this layout. - \a child is added to this layout's target view. + \a child is added to this BLayout's target view. - \returns The BLayoutItem created to represent \a child is, or NULL if there - was an error. + \returns The BLayoutItem created to represent \a child is, or \c NULL if + there was an error. \param child The BView to be added to this BLayout. */ -/*! \fn BLayoutItem* BLayout::AddView(int32 index, BView* child) +/*! + \fn BLayoutItem* BLayout::AddView(int32 index, BView* child) \brief Creates a BLayoutItem to represent \a child, and adds that item at - \a index to this layout. \a child is added to this layout's target view. + \a index to this layout. \a child is added to this BLayout's target view. */ /*! \fn bool BLayout::AddItem(BLayoutItem* item) \brief Adds a BLayoutItem to this layout, and adds the BView it represents - to this layout's target view. + to this BLayout's target view. \param item The BLayoutItem to be added. \retval true success @@ -165,7 +176,7 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn bool BLayout::AddItem(int32 index, BLayoutItem* item) \brief Adds \a item to this layout, and adds the BView \a item represents - to this layout's target view. + to this BLayout's target view. \param item The BLayoutItem to be added. \param index The index at which to add \c item. @@ -181,8 +192,8 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn bool BLayout::RemoveView(BView* child) - \brief Removes and deletes all BLayoutItems representing a BView from this - layout. + \brief Removes and deletes all BLayoutItem representing a BView from + this layout. \param child The BView to be removed. @@ -193,10 +204,10 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn bool BLayout::RemoveItem(BLayoutItem* item) - \brief Removes a BLayoutITem from this layout, and also removes the view - it represents from this layout's target view. + \brief Removes a BLayoutItem from this layout, and also removes the view + it represents from this BLayout's target view. - \param item The BLayoutitem to be removed + \param item The BLayoutItem to be removed \warning \a item is not deleted, you must delete it manually, or add it to another BLayout. @@ -206,7 +217,8 @@ topLayout->AddItem(nestedLayoutWithView); */ -/*! \fn BLayoutItem* BLayout::RemoveItem(int32 index) +/*! + \fn BLayoutItem* BLayout::RemoveItem(int32 index) \brief Remove the BLayoutItem at \a index. \see RemoveItem(BLayoutItem*) @@ -224,7 +236,7 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn int32 BLayout::CountItems() const - \brief Get the number of BLayoutItems in this layout. + \brief Get the number of BLayoutItem s in this layout. */ @@ -248,26 +260,28 @@ topLayout->AddItem(nestedLayoutWithView); */ -//@} +//! @} /*! \name Subclass helpers. \brief These methods are meant to ease the development of BLayout subclasses. - - @{ */ -/*! \fn bool BLayout::AncestorsVisible() +//! @{ + + +/*! + \fn bool BLayout::AncestorsVisible() \brief Get the visibility of the ancestors of this layout. If a BLayout is connected to a BView, this will always return \c true. If a BLayout is nested in another layout (it was passed to AddItem()), then - this will reflect the visibility of this layout's parent layout. If any - layout is hidden (by BLayout::SetVisible()) between this layout and its - target view's layout, then this method will return \c false. + this will reflect the visibility of this BLayout's parent layout. If + any layout is hidden (by BLayout::SetVisible()) between this layout and its + target BView's layout, then this method will return \c false. */ @@ -276,8 +290,8 @@ topLayout->AddItem(nestedLayoutWithView); \brief Returns the on-screen area this layout has received to lay out its items in. - The return value is in the coordinate space of this layout's target view. - If this BLayout is attached directly to a BView, then + The return value is in the coordinate space of this BLayout's target + view. If this BLayout is attached directly to a BView, then LayoutArea().LeftTop() == B_ORIGIN . */ @@ -287,27 +301,34 @@ topLayout->AddItem(nestedLayoutWithView); \brief Method to be called by derived classes in their SetVisible() implementation. Calls AncestorVisibilityChanged() on the items in this BLayout. + + \param show \c true to show, \c false to hide. */ -//@} +//! @} /*! \name Methods triggering or related to laying out this BLayout. - -//@{ */ -/*! \fn void BLayout::Relayout(bool immediate = false) +//! @{ + + +/*! + \fn void BLayout::Relayout(bool immediate = false) \brief Request this BLayout to reposition and resize its items as required. If \a immediate is \c false, and there is already a request to have the window this layout resides in re-laid-out, then the layout will happen at that time. If \a immediate is \c true, and there is no such pending - request, nor is this layout's parent layout in the process of laying out - its items, then this BLayout will now layout its items. + request, nor is this BLayout's parent layout in the process of laying + out its items, then this BLayout will now layout its items. + + \param immediate Whether or not to Relayout immediately or wait for pending + requests first. */ @@ -315,10 +336,12 @@ topLayout->AddItem(nestedLayoutWithView); \fn void BLayout::LayoutItems(bool force = false) \brief If there is no layout currently ongoing, and \a force is \c false, creates a new BLayoutContext and calls the DerivedLayoutItems() method - of this BLayout and any BLayouts nested in this BLayout. + of this BLayout and any BLayout s nested in this BLayout. If method also guarantees that the owner view of this layout (as returned by BLayout::Owner()) performs a layout as well (if it is suitable to do so). + + \param force Force the LayoutItems. */ @@ -329,16 +352,17 @@ topLayout->AddItem(nestedLayoutWithView); */ -//@} +//! @} /*! \name Invalidation and state mutators and accessors. - - @{ */ +//! @{ + + /*! \fn void BLayout::RequireLayout() \brief Flag this layout as stale, i.e. any cached data may still be valid, @@ -352,7 +376,7 @@ topLayout->AddItem(nestedLayoutWithView); to positioning and sizing of its items. Invalidating a BLayout also invalidates the view it is connected to - (if there is one) and the BLayout this layout (or this layout's view) + (if there is one) and the BLayout this layout (or this BLayout's view) resides in. This method should be called whenever the layout becomes invalid. This might @@ -379,7 +403,8 @@ topLayout->AddItem(nestedLayoutWithView); */ -/*! \fn void BLayout::DisableLayoutInvalidation() +/*! + \fn void BLayout::DisableLayoutInvalidation() \brief Disable layout invalidation notifications, i.e. calls to this object's InvalidateLayout() method. */ @@ -393,18 +418,19 @@ topLayout->AddItem(nestedLayoutWithView); */ -//@} +//! @} /*! \name Archiving methods \brief These methods relate to the archiving or unarchiving of this object - and the BLayoutItems it contains - - @{ + and the BLayoutItem's it contains */ - + +//! @{ + + /*! \fn status_t BLayout::Archive(BMessage* archive, bool deep = true) const \brief Archives this layout into \a archive. If deep is true, also archives @@ -414,8 +440,8 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn status_t BLayout::AllUnarchived(const BMessage* from) - \brief Unarchives the BLayoutItems for this layout, calling ItemUnarchived() - for each one. + \brief Unarchives the BLayoutItem's for this layout, calling + ItemUnarchived() for each one. */ @@ -442,16 +468,17 @@ topLayout->AddItem(nestedLayoutWithView); */ -//@} +//! @} /*! \name BLayout Hook methods - - @{ */ +//! @{ + + /*! \fn bool BLayout::ItemAdded(BLayoutItem* item, int32 atIndex) \brief Hook method called when \a item is added to this layout. @@ -490,23 +517,23 @@ topLayout->AddItem(nestedLayoutWithView); \fn void BLayout::OwnerChanged(BView* was) \brief Hook method called when this layout is attached to a BView. - \param was The previous owner of this BLayout, for new BLayouts, this will - be NULL. + \param was The previous owner of this BLayout, for new BLayout s, this + will be \c NULL. */ /*! \fn void BLayout::AttachedToLayout() - \brief Hook method inherited from BLayoutItem, classes derived from BLayout - must include the BLayout version of this method in their + \brief Hook method inherited from BLayoutItem, classes derived from + BLayout must include the BLayout version of this method in their implementation. */ /*! \fn void BLayout::DetachedFromLayout(BLayout* layout) - \brief Hook method inherited from BLayoutItem, classes derived from BLayout - must include the BLayout version of this method in their + \brief Hook method inherited from BLayoutItem, classes derived from + BLayout must include the BLayout version of this method in their implementation. \param layout The BLayout that this BLayout was detached from. @@ -515,11 +542,10 @@ topLayout->AddItem(nestedLayoutWithView); /*! \fn void BLayout::AncestorVisibilityChanged(bool shown) - \brief Hook method inherited from BLayoutItem, classes derived from BLayout - must include the BLayout version of this method in their + \brief Hook method inherited from BLayoutItem, classes derived from + BLayout must include the BLayout version of this method in their implementation. */ -//@} - +//! @} diff --git a/docs/user/interface/LayoutBuilder.Group.dox b/docs/user/interface/LayoutBuilder.Group.dox index fec1bbea41..94ae3527eb 100644 --- a/docs/user/interface/LayoutBuilder.Group.dox +++ b/docs/user/interface/LayoutBuilder.Group.dox @@ -1,3 +1,23 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * Ingo Weinhold, bonefish@cs.tu-berlin.de + * + * Corresponds to: + * /trunk/headers/os/interface/GroupLayoutBuilder.h rev 42274 + * /trunk/src/kits/interface/GroupLayoutBuilder.cpp rev 42274 + */ + + +/*! + \file GroupLayoutBuilder.h + \brief Provides the BLayoutBuilder::Group<> class. +*/ + + /*! \class BLayoutBuilder::Group<> \ingroup interface @@ -32,14 +52,16 @@ /*! \name Constructors - - @{ */ +//! @{ + + /*! - \fn BLayoutBuilder::Group::Group(BWindow* window, - enum orientation, float spacing) + \fn BLayoutBuilder::Group::Group(BWindow *window, + enum orientation orientation=B_HORIZONTAL, + float spacing=B_USE_DEFAULT_SPACING) \brief Creates a new BGroupLayout, and attaches it to a BWindow. \note The top BView* in \a window has its ViewColor set to @@ -71,8 +93,9 @@ /*! - \fn template BLayoutBuilder::Group::Group( - enum orientation, float spacing) + \fn BLayoutBuilder::Group::Group( + enum orientation orientation=B_HORIZONTAL, + float spacing=B_USE_DEFAULT_SPACING) \brief Creates a new BGroupView and targets it. Methods called on this builder will be directed to the new BGroupView's @@ -83,15 +106,16 @@ */ -//@} +//! @} /*! \name Adding BViews and BLayoutItems - - @{ */ + +//! @{ + /*! \fn ThisBuilder& BLayoutBuilder::Group::Add(BView* view) \brief Add a BView to the BGroupLayout this builder represents. @@ -133,7 +157,7 @@ */ -//@} +//! @} /*! @@ -142,14 +166,16 @@ BLayoutBuilder::Base subclass representing the newly added object. These methods push a new builder on top of the stack, you will not be using \c this builder again until you call End(). - - @{ */ +//! @{ + + /*! \fn GroupBuilder BLayoutBuilder::Group::AddGroup( - enum orientation, float spacing, float weight) + enum orientation orientation, float spacing=B_USE_DEFAULT_SPACING, + float weight=1.0f) \brief Construct and add a viewless BGroupLayout, then return a GroupBuilder representing the newly added layout. @@ -157,6 +183,7 @@ \param spacing The spacing to use for the new BGroupLayout. \param weight The weight for the new BGroupLayout in the BGroupLayout this builder represents. + \returns A GroupBuilder representing the newly created BGroupLayout. */ @@ -233,7 +260,8 @@ /*! \fn SplitBuilder BLayoutBuilder::Group::AddSplit( - enum orientation, float spacing, float weight) + enum orientation orientation, float spacing=B_USE_DEFAULT_SPACING, + float weight=1.0f) \brief Create and add a new BSplitView with a weight of \c weight, then return a SplitBuilder representing the new BSplitView. @@ -258,17 +286,18 @@ */ -//@} +//! @} /*! \name Adding BSpaceLayoutItems Some convenience methods for adding special BSpaceLayoutItems. - - @{ */ +//! @{ + + /*! \fn ThisBuilder& BLayoutBuilder::Group::AddGlue( float weight = 1.0f) @@ -305,11 +334,12 @@ /*! \name Accessors - - @{ */ +//! @{ + + /*! \fn BGroupLayout* BLayoutBuilder::Group::Layout() const \brief Get the BGroupLayout this builder represents. diff --git a/docs/user/interface/LayoutBuilder.dox b/docs/user/interface/LayoutBuilder.dox index ae899bb9ab..528a398827 100644 --- a/docs/user/interface/LayoutBuilder.dox +++ b/docs/user/interface/LayoutBuilder.dox @@ -1,5 +1,13 @@ -/*! - \class BLayoutBuilder::Base<> +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + */ + + +/*! \class BLayoutBuilder::Base<> \ingroup interface \ingroup layout \brief Base for all other layout builders in the BLayoutBuilder namespace. diff --git a/docs/user/interface/LayoutItem.dox b/docs/user/interface/LayoutItem.dox index bab2552507..57f82de96c 100644 --- a/docs/user/interface/LayoutItem.dox +++ b/docs/user/interface/LayoutItem.dox @@ -1,3 +1,21 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + * Corresponds to: + * /trunk/headers/os/interface/LayoutItem.h rev 38207 + * /trunk/src/kits/interface/LayoutItem.cpp rev 38207 + */ + + +/*! + \file LayoutItem.h + Describes the BLayoutItem class +*/ + + /*! \class BLayoutItem \ingroup interface @@ -20,7 +38,7 @@ \fn BLayoutItem::BLayoutItem(BMessage* archive) \brief Archive constructor. - Creates a Bunarchiver for \a archive and calls its Finish() method. + Creates a BLayoutItem from the \a archive message. */ @@ -31,10 +49,21 @@ /*! - \name Reporting size and alignment constraints to a BLayout - @{ + \fn BLayout::~BLayout() + \brief Destructor method. + + Standard Destructor. */ + +/*! + \name Reporting size and alignment constraints to a BLayout +*/ + + +//! @{ + + /*! \fn BSize BLayoutItem::MinSize() = 0 \brief Returns the minimum desirable size for this item. @@ -67,7 +96,7 @@ /*! \fn bool BLayoutItem::HasHeightForWidth() - \brief Returns whether or not this BLayoutItem's height constraints are + \brief Returns whether or not this BLayoutItem's height constraints are dependent on its width. \note By default, this method returns \c false. @@ -77,18 +106,18 @@ /*! \fn void BLayoutItem::GetHeightForWidth(float width, float* min, float* max, float* preferred) - \brief Get this BLayoutItem's height constraints for a given \a width. + \brief Get this BLayoutItem's height constraints for a given \a width. If a BLayoutItem does not have height for width constraints (HasHeightForWidth() returns \c false) it does not need to implement this method. - \note It is prudent to compare \a min, \a max, \a preferred to NULL before - dereferencing them. + \note It is prudent to compare \a min, \a max, \a preferred to \c NULL + before dereferencing them. */ -//@} +//! @} /*! @@ -100,11 +129,12 @@ in when reporting these constraints. It is recommended that all subclasses do this as well, the BAbstractLayoutItem class provides any easy way to include this behaviour in your class. - - @{ */ +//! @{ + + /*! \fn void BLayoutItem::SetExplicitMinSize(BSize size) = 0 \brief Set this item's explicit min size, to be used in MinSize(). @@ -130,7 +160,7 @@ */ -//@} +//! @} /*! @@ -138,11 +168,12 @@ These methods take into account only the local visibility of this item, not the visibility of its ancestors. \n - - @{ */ +//! @{ + + /*! \fn bool BLayoutItem::IsVisible() = 0 \brief Return the current local visibility of this item. If an item is not @@ -160,17 +191,17 @@ */ -//@} +//! @} /*! - \name Getting and setting the current on-screen positioning of \ - a BLayoutItem. - - @{ + \name Getting and setting the current on-screen positioning of a BLayoutItem. */ +//! @{ + + /*! \fn void BLayoutItem::AlignInFrame(BRect frame) \brief Position this BLayoutItem within \a frame, given the value returned @@ -191,21 +222,21 @@ \fn void BLayoutItem::SetFrame(BRect frame) = 0 \brief Set the bounding frame of this item. - \a frame is in the coordinate system of the target view of the - BLayout this item belongs to. + \a frame is in the coordinate system of the target view of the BLayout + that this item belongs to. */ -//@} +//! @} /*! \fn BView* BLayoutItem::View() - \brief Return the BView this item is representing, or NULL if it does not + \brief Return the BView this item is representing, or \c NULL if it does not represent any view. When a BLayoutItem is added to a BLayout, this method is called, and the - returned BView will be added to the BLayout's target view. + returned BView will be added to the BLayout's target view. */ @@ -216,11 +247,12 @@ BLayout. In some implementations they may be handled directly by this BLayoutItem, but many implementations will forward these events to another object. - - @{ */ +//! @{ + + /*! \fn void BLayoutItem::InvalidateLayout(bool children = false) \brief Invalidate the layout of this item, or the object it represents. @@ -237,18 +269,19 @@ */ -//@} +//! @} /*! \name Utility methods for BLayout subclasses \brief Utility methods for the BLayout class to attach and retrieve arbitrary data for a BLayoutItem. - - @{ */ +//! @{ + + /*! \fn void* BLayoutItem::LayoutData() const \brief Retrieve arbitrary data attached to this BLayoutItem. @@ -265,15 +298,17 @@ */ -//@} +//! @} -/*! \name Hook methods - - @{ +/*! + \name Hook methods */ +//! @{ + + /*! \fn void BLayoutItem::AttachedToLayout() \brief Hook called when this object is attached to a BLayout (via @@ -288,16 +323,17 @@ \fn void BLayoutItem::DetachedFromLayout(BLayout* layout) \brief Hook called when this object is attached to a BLayout (via BLayout::RemoveItem()) - \param layout The BLayout you were previously attached to. \warning You should not use this hook to reattach \c this to \a BLayout, doing so will cause undefined behaviour (probably a crash). + + \param layout The BLayout you were previously attached to. */ /*! \fn void BLayoutItem::AncestorVisibilityChanged(bool shown) - \brief Hook called when this BLayoutItem's ancestors change visibility, + \brief Hook called when this BLayoutItem's ancestors change visibility, effectively hiding or showing this item. Implementations of this method should alter the onscreen visibility of this @@ -306,7 +342,9 @@ \note This method should not effect the value returned by this object's IsVisible() method. + + \param shown \c true to show, \c false to hide. */ -//@} +//! @} diff --git a/docs/user/interface/TwoDimensionalLayout.dox b/docs/user/interface/TwoDimensionalLayout.dox index 97b13798c9..df46a08e16 100644 --- a/docs/user/interface/TwoDimensionalLayout.dox +++ b/docs/user/interface/TwoDimensionalLayout.dox @@ -1,3 +1,21 @@ +/* + * Copyright 2010, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Alex Wilson + * Corresponds to: + * /trunk/headers/os/interface/TwoDimensionalLayout.h rev 38207 + * /trunk/src/kits/interface/TwoDimensionalLayout.cpp rev 38207 + */ + + +/*! + \file TwoDimensionalLayout.h + \brief Defines the BTwoDimensionalLayout class. +*/ + + /*! \class BTwoDimensionalLayout \ingroup interface @@ -8,9 +26,9 @@ This class manages all the tricky work of actually positioning/resizing items, as well as calculating size constraints and providing extra features, - such as spacing/insets and alignment of multiple BTwoDimensionalLayouts. - Derived classes need only implement a few hook methods to get a working - layout. + such as spacing/insets and alignment of multiple + BTwoDimensionalLayout's. Derived classes need only implement a few hook + methods to get a working layout. \warning This class is not yet finalized, if you use it in your software assume that it will break some time in the future. @@ -35,23 +53,23 @@ /*! \fn void BTwoDimensionalLayout::AlignLayoutWith( - BTwoDimensionalLayout* other, enum orientation) - \brief Align the BLayoutItems in two BTwoDimensionalLayouts with each other - within a certain orientation. + BTwoDimensionalLayout* other, enum orientation orientation) + \brief Align the BLayoutItem's in the specified \a orientation within + two or more BTwoDimensionalLayout's. - When two (or more) BTwoDimensionalLayouts are aligned within a certain - orientation, then the BLayoutItems within those BTwoDimensionalLayouts will - have identical widths or heights (depending on how the - BTwoDimensionalLayouts are aligned). + When two (or more) BTwoDimensionalLayout's are aligned within a + certain \a orientation, then the BLayoutItem's within those + BTwoDimensionalLayout's will have identical widths or heights + (depending on how the BTwoDimensionalLayout's are aligned.) - If you align two BGroupLayouts horizontally, for example, then the - BLayoutItems at index 0 in both BGroupLayouts will be given the same - horizontal area. The same is true for the BLayoutItems at index 1, 2, etc.. - Not all BTwoDimensionalLayouts have to have an item at each index for the - alignment to proceed. + If you align two BGroupLayout's horizontally for example, then the + BLayoutItem at index 0 in both BGroupLayout's will be given the same + horizontal area. The same is true for the BLayoutItem at index 1, + 2, etc. Not all BTwoDimensionalLayout's have to have an item at each + index for the alignment to proceed. \param other The BTwoDimensionalLayout to be aligned with. - \param orientation The orientation on which to be aligned. + \param orientation The \a orientation on which to be aligned. */ @@ -61,7 +79,7 @@ \brief Set the insets for this BTwoDimensionalLayout (in pixels). Set the spacing around the edges of this BTwoDimensionalLayout. If you - pass B_USE_DEFAULT_SPACING for a certain parameter, that parameter will + pass \c B_USE_DEFAULT_SPACING for a certain parameter, that parameter will be replaced with the value returned by BControlLook::DefaultItemSpacing(). \see BTwoDimensionalLayout::GetInsets(); @@ -71,9 +89,9 @@ /*! \fn void BTwoDimensionalLayout::GetInsets(float* left, float* top, float* right, float* bottom) const - \brief Get the insets for this BTwoDimensionalLayout (in pixels). + \brief Get the insets for the BTwoDimensionalLayout (in pixels). - Passing NULL for any paramater is not an error, such parameters will + Passing \c NULL for any parameter is not an error, those parameters will be ignored. \see BTwoDimensionalLayout::SetInsets(); @@ -85,16 +103,17 @@ These methods are called automatically as needed during layout, and provide the BTwoDimensionalLayout class with the necessary information - to properly layout the BLayoutItems in this BTwoDimensionalLayout. - - @{ + to properly layout the BLayoutItem in this BTwoDimensionalLayout. */ +//! @{ + + /*! - \fn void BTwoDimensionalLayout::PrepareItems(enum orientation) - \brief Prepare the BLayoutItems in this BTwoDimensionalLayout subclass - for layout within a certain orientation. + \fn void BTwoDimensionalLayout::PrepareItems(enum orientation orientation) + \brief Prepare the BLayoutItem in this BTwoDimensionalLayout subclass + for layout within a certain \a orientation. This is a good place to update cache information that will be used in other hook methods, for example. @@ -104,7 +123,7 @@ /*! \fn bool BTwoDimensionalLayout::HasMultiColumnItems() \brief Tests whether or not this BTwoDimensionalLayout contains any - BLayoutItems spanning more than one column. + BLayoutItem's spanning more than one column. The BTwoDimensionalLayout implementation returns false. */ @@ -113,7 +132,7 @@ /*! \fn bool BTwoDimensionalLayout::HasMultiRowItems() \brief Tests whether or not this BTwoDimensionalLayout contains any - BLayoutItems spanning more than one row. + BLayoutItem's spanning more than one row. The BTwoDimensionalLayout implementation returns false. */ @@ -121,33 +140,37 @@ /*! \fn int32 BTwoDimensionalLayout::InternalCountColumns() - \brief Return the number of columns in this BTwoDimensionalLayout. + \brief Get the number of columns in the BTwoDimensionalLayout. + + \returns The number of columns in the BTwoDimensionalLayout. */ /*! \fn int32 BTwoDimensionalLayout::InternalCountRows() - \brief Return the number of rows in this BTwoDimensionalLayout. + \brief Get the number of rows in the BTwoDimensionalLayout. + + \returns The number of rows in the BTwoDimensionalLayout. */ /*! - \fn void BTwoDimensionalLayout::GetColumnRowConstraints(enum orientation, - int32 index, ColumnRowConstraints* constraints) + \fn void BTwoDimensionalLayout::GetColumnRowConstraints(enum orientation + orientation, int32 index, ColumnRowConstraints* constraints) \brief Fill in the ColumnRowConstraints for a certain column or row in - this BTwoDimensionalLayout. + the BTwoDimensionalLayout. This method is used to communicate the size constraints and weight for - a given row/column in this BTwoDimensionalLayout. + a given row/column in the BTwoDimensionalLayout. */ /*! \fn void BTwoDimensionalLayout::GetItemDimensions(BLayoutItem* item, Dimensions* dimensions) - \brief Tell the base class what column and row a BLayoutItem is in, as + \brief Tell the base class what column and row a BLayoutItem is in as well as how many columns and rows it covers. */ -//@} +//! @} diff --git a/docs/user/locale/Catalog.dox b/docs/user/locale/Catalog.dox index ed2ac31622..c5e3f3208e 100644 --- a/docs/user/locale/Catalog.dox +++ b/docs/user/locale/Catalog.dox @@ -1,221 +1,248 @@ -/*! -\class BCatalog -\ingroup locale -\brief Class handling string localization. +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Axel Dörfler, axeld@pinc-software.de + * John Scipione, jscipione@gmail.com + * Oliver Tappe, zooey@hirschkaefer.de + * + * Corresponds to: + * /trunk/headers/os/locale/Catalog.h rev 42274 + * /trunk/src/kits/locale/Catalog.cpp rev 42274 + */ -BCatalog is the class that allows you to perform string localization. This means -you give it a string in english, and it automatically returns the translation of -this string in the user's specified language, if available. - -Most of the time, you don't have to deal with BCatalog directly. You use the -translation macros instead. However, there are some cases where you will have to -use catalogs directly. These include : - \li Tools for managing catalogs : if you want to add, remove or edit -entries in a catalog, you need to do it using the BCatalog class. - \li Accessing catalogs other than your own : the macros only grant you -access to the catalog linked with your application. To access other catalogs -(for example if you create a script interpreter and want to localize the -scripts), you will have to open a catalog associated with your script. - -\section macros Using the macros -You don't have to do much in your program to handle catalogs. You must first -set the B_TRANSLATE_CONTEXT define to a string that identifies which part of the -application the strings you will translate are in. This allows the translators -to keep track of the strings in the catalog more easily, and find where they are -visible in the application. then, all you have to do, is enclose any string you -want to make translatable in the B_TRANSLATE() macro. This macro has two uses, -it will allow your text to be replaced at run-time by the proper localized one, -but it will also allow to build the base catalog, the one that you will send to -the translator team, from your sourcecode. - -\section chaining Chaining of catalogs -The catalogs you get from the locale kit are designed to use a fallback system -so that the user get strings in the language he's the most fluent with, -depending on what catalogs are available. - -For example, if the user sets his language preferences as french(France), -spanish, english, when an application loads a catalog, the following rules are -used : - \li Try to load a french(France) catalog. If it is found, this catalog - will automatically include strings from the generic french catalog. - \li Try to load a generic french catalog. - \li Try to load a generic spanish catalog. - \li Try to load a generic english catalog. - \li If all of them failed, use the strings that are in the source code. - -Note that french(France) will failback to french, but then directly to the -language in the source code. This avoids mixing 3 or more languages in the same -application if the catalogs are incomplete and avoids confusion. - -*/ /*! -\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. - -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. - -The fingerprint is a way to check that the catalog that will be loaded matches -the current version of the application. A catalog made for a different version -of the application can be loaded if you set the fingerprint to 0. This is -usually not a problem, it only means that some strings may not be translated -properly. But if you want to provide 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 settings -will be used. -\param fingerprint The fingerprint version-info for the catalog to load. If 0, -the fingerprint will not be checked,and any version of the catalog will be -loaded. -*/ - -/*! -\fn const char* BCatalog::GetString(const char* string, const char* context = NULL, const char* comment = NULL) -\brief Get a string from the catalog. - -This method access the data of the catalog and reeturns you the translated -version of the string. You must pass it the context where the string is, as -the same string may appear somewhere else and need a differnet translation. -The comment is optional. It is meant as an help to translators, when the string -alone is not helpful enough or there are special things to note. The comment is -also used as a way to uniquely identify a string, so if two identical strings -share the same context, it is still possible to provide different translations. - -\returns The translated string, or the one passed as a parameter if no -translation was found. -\param string The string to translate. -\param context The context where the string is located. -\param comment Supplementary comment for translators. -*/ - -/*! -\fn const char* BCatalog::GetString(uint32 id) -\brief Get a string by id from the catalog. - -The id based version of this method is slightly faster, as it doesn't have to -compute the hash from the 3 parameters. However, it will fail if there is an -hash collision, so you should still fallback to the first one in case of -problems. Also note that the hash value may be different from one catalog to -another, depending on the file format they are stored in, so you shouldn't rely -on this method unless you are sure you can keep all the catalog files under -control. - -\returns The translated string if found, or an empty string. -\param id The identifier of the string. -*/ - -/*! -\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const char* context = NULL, const char* comment = NULL) -\fn const char* GetStringNoAutoCollate(uint32 id) -\brief Get a string from the catalog, without registering it for collectcatkeys. - -This function does exactly the same thing as GetString, except it will not be -parsed by the collectcatkeys tool. This allows you, for example, to translate a -string constant that you declared at another place, without getting a warning -message from collectcatkeys. - -\returns The translated string, or the one passed as a parameter if no -translation was found. -\param string The string to translate. -\param context The context where the string is located. -\param comment Supplementary comment for translators. + \file Catalog.h + \brief Provides the BCatalog class. */ /*! -\fn status_t BCatalog::GetData(const char* name, BMessage* msg) -\brief Get custom data from the catalog. + \class BCatalog + \ingroup locale + \brief Class handling string localization. -This function allows you to localize something else than raw text. This may -include pictures, sounds, videos, or anything else. Note there is no support for -generatinga catalog with such data inside, and the current format may not -support it. If you need to localize data that is not text, it is advised to -handle it by yourself. + BCatalog is the class that allows you to perform string localization. This + means you give it a string in english, and it automatically returns the + translation of this string in the user's specified language, if available. -\returns An error code. -\param name The name of the data to retrieve. -\param msg The BMessage to fill in with the data. + Most of the time, you don't have to deal with BCatalog directly. You use + the translation macros instead. However, there are some cases where you + will have to use catalogs directly. These include : + \li Tools for managing catalogs : if you want to add, remove or edit + entries in a catalog, you need to do it using the BCatalog class. + \li Accessing catalogs other than your own : the macros only grant you + access to the catalog linked with your application. To access + other catalogs (for example if you create a script interpreter and + want to localize the scripts), you will have to open a catalog + associated with your script. + + \section macros Using the macros + You don't have to do much in your program to handle catalogs. You must + first set the B_TRANSLATE_CONTEXT define to a string that identifies which + part of the application the strings you will translate are in. This allows + the translators to keep track of the strings in the catalog more easily, + and find where they are visible in the application. then, all you have to + do, is enclose any string you want to make translatable in the + B_TRANSLATE() macro. This macro has two uses, it will allow your text to + be replaced at run-time by the proper localized one, but it will also + allow to build the base catalog, the one that you will send to the + translator team, from your sourcecode. + + \section chaining Chaining of catalogs + The catalogs you get from the locale kit are designed to use a fallback + system so that the user get strings in the language he's the most fluent + with, depending on what catalogs are available. + + For example, if the user sets his language preferences as french(France), + spanish, english, when an application loads a catalog, the following rules + are used : + \li Try to load a french(France) catalog. If it is found, this catalog + will automatically include strings from the generic french catalog. + \li Try to load a generic french catalog. + \li Try to load a generic spanish catalog. + \li Try to load a generic english catalog. + \li If all of them failed, use the strings that are in the source code. + + Note that french(France) will failback to french, but then directly to the + language in the source code. This avoids mixing 3 or more languages in the + same application if the catalogs are incomplete and avoids confusion. */ + /*! -\fn status_t BCatalog::GetData(uint32 id, BMessage* msg) -\brief Get custom data from the catalog. + \fn BCatalog::BCatalog(const char* signature, const char* language = NULL, + uint32 fingerprint = 0) + \brief Construct a catalog for the given application. -As for GetString, the id-based version may be subject to hash-collisions, but is -faster. + 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. -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 catalog add-on for -storing the data. + 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. + + The fingerprint is a way to check that the catalog that will be loaded + matches the current version of the application. A catalog made for a + different version of the application can be loaded if you set the + fingerprint to \c 0. This is usually not a problem, it only means that + some strings may not be translated properly. But if you want to provide + 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 + 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 + catalog will be loaded. */ + /*! -\fn status_t BCatalog::GetSignature(BString* sig) -\brief Get the catalog mime-signature. + \fn const char* BCatalog::GetString(const char* string, + const char* context = NULL, const char* comment = NULL) + \brief Get a string from the catalog. -This function fills the sig string with the mime-signature associated to the -catalog. + This method access the data of the catalog and reeturns you the translated + version of the string. You must pass it the context where the string is, as + the same string may appear somewhere else and need a differnet translation. + The comment is optional. It is meant as an help to translators, when the + string alone is not helpful enough or there are special things to note. + The comment is also used as a way to uniquely identify a string, so if two + identical strings share the same context, it is still possible to provide + different translations. -\param sig The string where to copy the signature. -\returns An error code. + \param string The string to translate. + \param context The context where the string is located. + \param comment Supplementary comment for translators. + + \returns The translated string, or the one passed as a parameter if no + translation was found. */ + /*! -\fn status_t BCatalog::GetLanguage(BString* lang) -\brief Get the catalog language. + \fn const char* BCatalog::GetString(uint32 id) + \brief Get a string by id from the catalog. -This function fills the lang string with the language name for the catalog. + The id based version of this method is slightly faster, as it doesn't + have to compute the hash from the 3 parameters. However, it will fail + if there is an hash collision, so you should still fallback to the first + one in case of problems. Also note that the hash value may be different + from one catalog to another, depending on the file format they are stored + in, so you shouldn't rely on this method unless you are sure you can keep + all the catalog files under control. -\param sig The string where to copy the language. -\returns An error code. + \param id The identifier of the string. + \returns The translated string if found, or an empty string. */ + /*! -\fn status_t BCatalog::GetFingerprint(uint32* fp) -\brief Get the catalog fingerprint. + \fn status_t BCatalog::GetData(const char* name, BMessage* msg) + \brief Get custom data from the catalog. -This function setsfp to the fingerprint of the catalog. This allows you to check -which version of the sourcecode this catalog was generated from. + This function 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, + it is advised to handle it by yourself. -\returns An error code. -\param fp The integer to set to the fingerprint value. + \param name The name of the data to retrieve. + \param msg The BMessage to fill in with the data. + + \returns An error code. */ + /*! -\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint) -\brief Reload the string data. + \fn status_t BCatalog::GetData(uint32 id, BMessage* msg) + \brief Get custom data from the catalog. -This function reloads the data for the given signature and fingerprint. + As for GetString, the id-based version may be subject to hash-collisions, + but is faster. -\returns An error code. -\param signature The signature of the catalog youwant to load -\param fingerprint The fingerprint of the catalog you want to load. + 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 + catalog add-on for storing the data. */ + /*! -\fn status_t BCatalog::InitCheck() const -\brief Check if the catalog is in an useable state. + \fn status_t BCatalog::GetSignature(BString* sig) + \brief Get the catalog mime-signature. -This function returns B_OK if the catalog is initialized properly. + This function fills the sig string with the mime-signature associated to the + catalog. + + \param sig The string where to copy the signature. + + \returns An error code. */ + /*! -\fn int32 BCatalog::CountItems() -\brief Returns the number of items in the catalog. + \fn status_t BCatalog::GetLanguage(BString* lang) + \brief Get the catalog language. -This function returns the number of strings in the catalog. + This function fills the lang string with the language name for the catalog. + + \param lang The string where to copy the language. + + \returns An error code. */ + /*! -\fn BCatalogaddOn* BCatalog::CatalogAddOn() -\brief Returns the internal storage for this catalog. + \fn status_t BCatalog::GetFingerprint(uint32* fp) + \brief Get the catalog fingerprint. -This function returns the internal storage class used by this catalog. -You should not have to use it. + This function 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. + + \returns An error code. +*/ + + +/*! + \fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint) + \brief Reload the string data. + + This function reloads the data for the given signature and fingerprint. + + \param signature The signature of the catalog youwant to load + \param fingerprint The fingerprint of the catalog you want to load. + + \returns An error code. +*/ + + +/*! + \fn status_t BCatalog::InitCheck() const + \brief Check if the catalog is in an useable state. + + \returns \c B_OK if the catalog is initialized properly. +*/ + + +/*! + \fn int32 BCatalog::CountItems() + \brief Returns the number of items in the catalog. + + \returns the number of strings in the catalog. +*/ + + +/*! + \fn BCatalogaddOn* BCatalog::CatalogAddOn() + \brief Returns the internal storage for this catalog. + + \returns the internal storage class used by this catalog. You should + not have to use it. */ diff --git a/docs/user/locale/Collator.dox b/docs/user/locale/Collator.dox index 2f47acaf0d..e1405759ce 100644 --- a/docs/user/locale/Collator.dox +++ b/docs/user/locale/Collator.dox @@ -1,154 +1,225 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Axel Dörfler, axeld@pinc-software.de + * Adrien Destugues + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/locale/Collator.h rev 42274 + * /trunk/src/kits/locale/Collator.cpp rev 42274 + */ + + /*! -\class BCollator -\ingroup locale -\brief Class for handling collation of string + \file Collator.h + \brief Provides the BCollator class. +*/ -BCatalog is designed to handle collations (sorting) of strings. -The collation is done using a set of rules that changes from a country to another. -For example, in spanish, 'ch' is consiidered as a letter and is sorted between 'c' and 'd'. -This class is alsoable to perform natural sorting, so that '2' is sorted before '10', -which is not the case when you do a simple ASCII sort. -\warning This class is not multithread-safe, as Compare() and GetKey() change -the ICUCollator (the strength). So if you want to use a BCollator from -more than one thread, you need to protect it with a lock. +/*! + \class BCollator + \ingroup locale + \brief Class for handling collation of string + BCatalog is designed to handle collations (sorting) of strings. + The collation is done using a set of rules that changes from a country + to another. For example, in spanish, 'ch' is consiidered as a letter + and is sorted between 'c' and 'd'. This class is alsoable to perform + natural sorting, so that '2' is sorted before '10', which is not the + case when you do a simple ASCII sort. + + \warning This class is not multithread-safe, as Compare() and GetKey() + change the ICUCollator (the strength). So if you want to use a + BCollator from more than one thread, you need to protect it with a lock. */ /*! -\fn BCollator::BCollator() -\brief Construct a collator for the default locale. + \fn BCollator::BCollator() + \brief Construct a collator for the default locale. + + Empty contructor. */ /*! -\fn BCollator::BCollator(const char* locale, int8 strength = B_COLLATE_PRIMARY, bool ignorePunctiation = false) -\brief Construct a collator for the given locale. + \fn BCollator::BCollator(const char* locale, + int8 strength = B_COLLATE_PRIMARY, bool ignorePunctuation = false) + \brief Construct a collator for the given locale. -This constructor loads the data for the given locale. You can also adjust the strength and -tell if the collator should take punctuation into account when sorting. + This constructor loads the data for the given locale. You can also + adjust the strength and tell if the collator should take punctuation + into account when sorting. + + \param locale The \a locale. + \param strength The collator class provide four level of strength. These + define the handling of various things. + \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, + \li \c B_COLLATE_SECONDARY takes letter accents into account, + \li \c B_COLLATE_TERTIARY is case sensitive, + \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you + shouldn't need to go that far. + \param ignorePunctuation Ignore punctuation in the Collator when sorting. */ /*! -\fn BCollator::BCollator(BMessage* archive) -\brief Unarchive a collator. + \fn BCollator::BCollator(BMessage* archive) + \brief Unarchive a collator from a message. + + \param archive The message to unarchive the BCollator from. */ /*! -\fn BCollator::BCollator(const BCollator& other) -\brief Copy constructor. + \fn BCollator::BCollator(const BCollator& other) + \brief Copy constructor. + + Constructs a BCollator by making a copy of another BCollator. + + \param other The BCollator to copy from. */ /*! -\fn BCollator::~Bcollator() -\brief Destructor. + \fn BCollator::~BCollator() + \brief Destructor. + + Standard destructor method. */ /*! -\fn Bcollator& BCollator::operator=(const BColltr& other) -\brief Assignment operator. + \fn Bcollator& BCollator::operator=(const BCollator& other) + \brief Assignment operator. + + \param other the BCollator to assign from. */ /*! -\fn void BCollator::SetDefaultStrength(int8 strength) -\brief Set the strength of the collator. + \fn void BCollator::SetDefaultStrength(int8 strength) + \brief Set the strength of the collator. -The collator class provide four level of strength. These define the handling of -various things. -\item B_COLLATE_PRIMARY doesn't differenciate e from é, -\item B_COLLATE_SECONDARY takes them into account, -\item B_COLLATE_TERTIARY is case sensitive, -\item B_COLLATE_QUATERNARY is very strict. Most of the time you shouldn't need -to go that far. + Note that the \a strength can also be given on a case-by-case basis + when calling other methods. -Note the strength can also be given on a case-by-case basis when calling other -methods. - -\param strength The strength the catalog should use as default. + \param strength The collator class provide four level of strength. + These define the handling of various things. + \li \c B_COLLATE_PRIMARY doesn't differentiate e from é, + \li \c B_COLLATE_SECONDARY takes letter accents into account, + \li \c B_COLLATE_TERTIARY is case sensitive, + \li \c B_COLLATE_QUATERNARY is very strict. Most of the time you + shouldn't need to go that far. */ /*! -\fn int8 BCollator::DefaultStrength() const -\brief Returns the current strength of this catalog. + \fn int8 BCollator::DefaultStrength() const + \brief Get the current strength of this catalog. + + \returns the current strength of this catalog. */ /*! -\fn void BCollator::SetIgnorePunctuation(bool ignore) -\brief Enable or disable punctuation handling + \fn void BCollator::SetIgnorePunctuation(bool ignore) + \brief Enable or disable punctuation handling -This function enables or disables the handling of punctuations. + This function enables or disables the handling of punctuations. -\param ignore Boolean telling if the punctuation should be ignored. + \param ignore Boolean telling if the punctuation should be ignored. */ /*! -\fn bool BCollator::IgnorePunctuation() const -\brief Return the behaviour ofthe collator regarding punctuation. + \fn bool BCollator::IgnorePunctuation() const + \brief Gets the behavior of the collator regarding punctuation. -This function returns true if the collator will take punctuation into account -when sorting. + This function returns \c true if the collator will take punctuation into + account when sorting. */ /*! -\fn satus_t BCollator::GetSortKey(const char* string, BString* key, int8 strength) const -\brief Compute the sortkey of a string + \fn satus_t BCollator::GetSortKey(const char* string, BString* key, + int8 strength) const + \brief Compute the sortkey of a string. -A sortkey is a modified version of the string that you can use for faster -comparison with other sortkeys, using strcmp or a similar ASCII comparison. If -you need to compare a string with other ones a lot of times, storing the sortkey -will allow you to do the comparisons faster. + A sortkey is a modified version of the string that you can use for faster + comparison with other sortkeys, using strcmp or a similar ASCII comparison. + If you need to compare a string with other ones a lot of times, storing + the sortkey will allow you to do the comparisons faster. -\param string String from which to compute the sortkey. -\param key The resulting sortkey. -\param strength The strength to use for computing the sortkey. + \param string String from which to compute the sortkey. + \param key The resulting sortkey. + \param strength The \a strength to use for computing the sortkey. -\returns B_OK if everything went well. + \returns B_OK if everything went well. */ /*! -\fn int BCollator::Compare(const char* s1, const char* s2, int8 strength) const -\brief Compare two strings. + \fn int BCollator::Compare(const char* s1, const char* s2, + int8 strength) const + \brief Compare two strings. -This function returns the difference betweens the two strings, in a way similar -to strcmp. + Returns the difference betweens the two strings similar to strcmp(). -\param s1,s2 The strings to compare. -\returns The comparison value. 0 if the strings are equal, negative if s1s2. + \param s1 The first string to compare. + \param s2 The second string to compare. + \param strength The \a strength to use for comparing the strings. + + \retval 0 if the strings are equal. + \retval <0 if s1 is less than s2. + \retval >0 if s1 is greater than s2. */ /*! -\fn bool BCollator::Equal(const char* s1, const char* s2, int8 strength) const -\brief Checks two strings for equality. + \fn bool BCollator::Equal(const char* s1, const char* s2, + int8 strength) const + \brief Checks two strings for equality. -Compares two strings for equality. Note that different strings may end up being -equal, for example if the differences are only in case and punctuation, -depending on the strenght used. Quaterary strength will make this function -return true only if the strings are byte-for-byte identical. + Compares two strings for equality. Note that different strings may end + up being equal, for example if the differences are only in case and + punctuation, depending on the strength used. Quaterary strength will + make this function return true only if the strings are byte-for-byte + identical. -\returns True if the two strings are identical. + \param s1 The first string to compare. + \param s2 The second string to compare. + \param strength The \a strength to use for comparing the strings. + + \returns \c true if the strings are identical, otherwise \c false. */ /*! -\fn bool BCollator::Greater(cosnt char* s1, const char* s2, int8 strength) const) -\brief Tell if a string is greater than another. + \fn bool BCollator::Greater(cosnt char* s1, const char* s2, + int8 strength) const + \brief Determine if a string is greater than another. -\returns True if s1 is greater (not equal) than s2. + \note !Greater(s1, s2) does the same thing as Greater(s2, s1) -\note !Greater(s1, s2) does the same thing as Greater(s2, s1) + \param s1 The first string to compare. + \param s2 The second string to compare. + \param strength The \a strength to use for comparing the strings. + + \returns \c true if s1 is greater than, but not equal to, s2. */ /*! -\fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, int8 strength) const) -\brief Tell if a string is greater than another. + \fn bool BCollator::GreaterOrEqual(cosnt char* s1, const char* s2, + int8 strength) const + \brief Tell if a string is greater than another. -\returns True if s1 is greater or equal to s2. + \param s1 The first string to compare. + \param s2 The second string to compare. + \param strength The \a strength to use for comparing the strings. + + \returns \c true if s1 is greater or equal than s2. */ /*! -\fn static BArchivable* BCollator::Instanciate(BMessage* archive) -\brief Unarchive the collator + \fn static BArchivable* BCollator::Instantiate(BMessage* archive) + \brief Unarchive the collator -Thif function allows you to restore a collator that you previously archived. It -is faster to do that than to buid a collator and set it up by hand every time -you need it with the same settings. + This function allows you to restore a collator that you previously + archived. It is faster to do that than to buid a collator and set + it up by hand every time you need it with the same settings. + + \param archive The message to restore the collator from. + + \returns A BArchivable object containing the BCollator or \c NULL. */ + diff --git a/docs/user/locale/Country.dox b/docs/user/locale/Country.dox index 0247af8894..80231ec1d5 100644 --- a/docs/user/locale/Country.dox +++ b/docs/user/locale/Country.dox @@ -1,70 +1,91 @@ -/*! -\class BCountry -\ingroup locale -\brief Class representing a country +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Axel Dörfler, axeld@pinc-software.de. + * Adrien Destugues, pulkomandy@gmail.com. + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/locale/Country.h rev 42274 + * /trunk/src/kits/locale/Country.cpp rev 42274 + */ -BCountry provides all the information about a particular country. -This includes the country flag (as an HVIF icon), the localized name of the -country, and the iso country code. - -Date, timeand numer formatting also depends to some extent of the language, -so they are done in the BLocale classinstead. +/*! \file Country.h + \brief BCountry class definition. */ -/*! -\fn BCountry::BCountry(const char* languageCode, const char* countryCode) -\brief Constructor. -Construct a BCountry from a language and a country code. +/*! \class BCountry + \ingroup locale + \brief Class representing a country + BCountry provides all the information about a particular country. + This includes the country flag (as an HVIF icon), the localized name + of the country, and the ISO country code. + + Date, time, and numer formatting also depends to some extent on the + language used, so they are found in the BLocale class instead. */ -/*! -\fn bool BCountry::GetName(BString& name) const -\brief Get the name of the country - -Fills in the name parameter with the name of the country, in the user's locale. -*/ /*! -\fn const char* BCountry::Code() const -\brief Returns the country code. + \fn BCountry::BCountry(const char* countryCode) + \brief Initialize a BCountry from a country code. + + \param countryCode The country code to initialize from. */ + /*! -\fn status_t BCountry::GetIcon(BBitmap* result) const; -\brief Render the country's flag to the given BBitmap + \fn BCountry::BCountry(const BCountry& other) + \brief Initialize a BCountry from another BCountry object. -This function renders the Country's flag to the given BBitmap. The bitmap -should already be set to the pixel format and size you want to use. - -The flag is stored in HVIF format and can be rendered atany size and color depth. - -\param result The BBitmap to drag the flag to. -\returns B_OK if the drawing was successful. + \param other The BCountry object to initialize from. */ + /*! -\fn const char* BCountry::GetLocalizedString(uint32 id) const; -\brief Get one of the default localized strings for this country. - -The strings include monetary symbols and other similar things. - + \fn BCountry& BCountry::operator=(const BCountry& other) */ + /*! -\fn int8 BCountry::Measurement() const -\brief Returrns the measurement used in this country. - -\returns B_METRIC for the metric system, or B_US for the USA's system. + \fn BCountry::~BCountry() + \brief Destructor method. */ + /*! -\fn int BCountry::GetTimeZones(BList& timezones) const -\brief Returns all the timeaones used in this country. + \fn bool BCountry::GetName(BString& name) const + \brief Get the name of the country. -The count may vary from 0 for countries where there is no data, to twelve, for Russia. - -\returns The number of timezones that were added to the list. + Fills in the name parameter with the name of the country in the + language set by the user's locale. +*/ + + +/*! + \fn const char* BCountry::Code() const + \brief Gets the ISO country code for the country. + + \returns The ISO country code for the country. +*/ + + +/*! + \fn status_t BCountry::GetIcon(BBitmap* result) const; + \brief Render the country's flag to the given BBitmap. + + This function renders the country's flag to the given BBitmap. The bitmap + should already be set to the pixel format and size you want to use. + + The flag is stored in HVIF format so it can be rendered at any size and + color depth. + + \param result The BBitmap to drag the flag into. + + \returns \c B_OK if the drawing was successful. */ diff --git a/docs/user/locale/Locale.dox b/docs/user/locale/Locale.dox index 4aa20fe1b9..93ace80d9a 100644 --- a/docs/user/locale/Locale.dox +++ b/docs/user/locale/Locale.dox @@ -1,154 +1,517 @@ -/*! -\class BLocale -\ingroup locale -\brief Class for representing a locale and its settings. +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Axel Dörfler, axeld@pinc-software.de. + * John Scipione, jscipione@gmail.com + * Oliver Tappe, zooey@hirschkaefer.de. + * + * Corresponds to: + * /trunk/headers/os/locale/Locale.h rev 42274 + * /trunk/src/kits/locale/Locale.cpp rev 42274 + */ -A locale is defined by the combination of a country and a language. Using these -two informations, it is possible to determine the format to use for date, time, -and number formatting. The BLocale class also provide collators, which allows -you to sort a list of strings properly depending on a set of rules about -accented chars and other special cases that vary over the different locales. - -BLocale is also the class to use when you want to perform formatting or parsing -of dates, times, and numbers, in the natural language of the user. - -*/ /*! -\fn const BCollator* BLocale::Collator() const -\brief Returns the collator associated to this locale. - -Returns the collator in use for this locale, allowing you to use it to sort a -set of strings. - + \file Locale.h + \brief Provides the BLocale class. */ + +/*! \class BLocale + \ingroup locale + \brief Class for representing a locale and its settings. + + A locale is defined by the combination of a country and a language. + Using these two informations, it is possible to determine the format + to use for date, time, and number formatting. The BLocale class also + provide collators, which allows you to sort a list of strings properly + depending on a set of rules about accented chars and other special + cases that vary over the different locales. + + BLocale is also the class to use when you want to perform formatting + or parsing of dates, times, and numbers, in the natural language of + the user. +*/ + + /*! -\fn const BCountry* BLocale::Country() const -\brief Returns the country associated to this locale. - -A locale is defined by the combination of a country and a language. This -method gets the country part of this information, so you can access the -data that is not language-dependant (such as the country flag). - + \fn BLocale::BLocale(const BLanguage* language, + const BFormattingConventions* conventions) + \brief Initializes a BLocale object corresponding to the passed in + \a language and \a conventions. */ + /*! -\fn const BLanguage* BLocale::Language() const -\brief Returns the language associated to this locale. - + \fn BLocale::BLocale(const BLocale& other) + \brief Initializes a BLocale object. */ + /*! -\fn const char* BLocale::Code() const -\brief Returns the locale code. + status_t BLocale::GetCollator(BCollator* collator) const + \brief Gets the collator associated to this locale. -This function returns the locale name (such as en_US for united states english). + Returns the collator in use for this locale, allowing you to use it + to sort a set of strings. */ + /*! -\fn bool BLocale::GetName(BString& name) const -\brief Get the name of the locale. - -This function fills the name string with the localized name of this locale. -For example, if the locale us en_US and the user language is french, this function will return "anglais (Etats-Unis)". + \fn BLocale& BLocale::operator=(const BLocale& other) */ + /*! -\fn void BLocale::SetCountry(const BCountry& newCountry) -\brief Set the country for this locale. + \fn BLocale::~BLocale() + \brief Destructor method. */ + /*! -\fn void BLocale::SetCollator(const BCollator& newCollator) -\brief Set the collator for this locale. + \fn status_t BLocale::GetCollator(BCollator* collator) const + \brief Sets \a collator object to the default collator for the BLocale. + + \param collator A pointer to a BCollator object to fill out. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE \c NULL \a collator object passed in. + \retval B_ERROR Unable to lock the BLocale. */ + /*! -\fn void BLocale::SetLanguage(const char* languageCode) -\brief Set the language for this locale. + \fn status_t BLocale::GetLanguage(BLanguage* language) const + \brief Sets \a language object to the default language for the BLocale. + + \param language A pointer to a BLanguage object to fill out. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE \c NULL \a language object passed in. + \retval B_ERROR Unable to lock the BLocale. */ + /*! -\fn status_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, bool longFormat) -\brief Format a date. + \fn status_t BLocale::GetFormattingConventions( + BFormattingConventions* conventions) const + \brief Sets \a conventions object to the default formatting conventions + for the BLocale. -Fills in the string with a formatted date. The longFormat parameter allows you -to select the short or the full format. + \param conventions A pointer to a BFormattingConventions object to fill out. -\param string The string buffer to fill with the formated date. -\param maxSize The size of the buffer. -\param time The time (in seconds since epoch) to format -\param longFormat If true, uses the long format (with day name, full month name). If false, use the short format, 08/12/2010 or similar. + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE \c NULL \a conventions object passed in. + \retval B_ERROR Unable to lock the BLocale. */ + /*! -\fn status_t BLocale::FormatDate(BString* string, time_t time, bool longFormat) -\brief Formats a date to a BString. + \fn const char* BLocale::GetString(uint32 id) const + \brief Gets the language string for the locale. + + \param id The locale \a id to get the language of. + + \internal Assumes a certain order of the string bases. + + \returns a blank string in the case of an error or the string "UTF-8" + if there is \a id is set to \a B_CODESET. */ + /*! -\fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, int& fieldCount, time_t time, bool longFormat) -\brief Format a date and get information about the different fields. + \fn void BLocale::SetFormattingConventions( + const BFormattingConventions& conventions) + \brief Sets the formatting convention for this locale. -This works the same way as the other FormatDatz methods, but also gives you the -offset of the beginning of each field in the date. This is useful if you need to -split the date in different parts for an user-modifiable area (see the Time -preflet for an example). - -To identify the content of each field, you can use GetDateFields. - -This function allocates the fieldPositions arrays, you have to free it when you -are finished with it. - -\sa GetDateFields + \param conventions The formatting convention to set. */ + /*! -\fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, bool longFormat) const -\brief Get the type of each field in this date format - -This function is most often used in combination with FormatDate. FormatDate -gives you the offset of each field in a formated string, anf GetDateFields gives -you the type of the field at a given offset. With these informations, you can -handle the formatted date string as a list of fields that you can split and -alter at will. + \fn void BLocale::SetCollator(const BCollator& newCollator) + \brief Set the collator for this locale. + \param newCollator The collator to set. */ + /*! -\fn status_t BLocale::GetDateFormat(BString& format, bool longFormat) const -\brief Get the date format string + \fn void BLocale::SetLanguage(const BLanguage& newLanguage) + \brief Set the language for this locale. -This function returns the string used internally to represent a date format. + \param newLanguage The code of the language to set to locale to. */ + /*! -\fn status_t BLocale::SetDateFormat(const char* formatString, bool longFormat) -\brief Set the date format for this locale + \fn ssize_t BLocale::FormatDate(char* string, size_t maxSize, time_t time, + BDateFormatStyle style) const + \brief Fills in \a string with a formatted date up to \a maxSize bytes for + the given \a time and \a style for the locale. -Thisfunction allows you to define your own date format for specific purposes. + \param string The string buffer to fill with the formatted date. + \param maxSize The size of the buffer. + \param time The time (in seconds since epoch) to format + \param style Specify the long format (with day name, full + month name) or the short format, 08/12/2010 or similar. + + \returns The number of bytes written during the date formatting. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + \retval B_BAD_VALUE CheckedArrayByteSink overflowed. + + \sa BLocale::FormatDateTime(char* target, size_t maxSize, + time_t time, BDateFormatStyle dateStyle, + BTimeFormatStyle timeStyle) const + \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, + BTimeFormatStyle style) const */ + /*! -\fn int BLocale::StartOfWeek() const -\brief Returns the day used as start of week in this locale. + \fn status_t BLocale::FormatDate(BString *string, time_t time, + BDateFormatStyle style, const BTimeZone* timeZone) const + \brief Fills in \a string with a formatted date for the given + \a time, \a style, and \a timeZone for the locale. + \param string The string buffer to fill with the formatted date. + \param time The time (in seconds since epoch) to format + \param style Specify the long format (with day name, full + month name) or the short format, 08/12/2010 or similar. + \param timeZone The time zone. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::FormatDateTime(BString* target, time_t time, + BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, + const BTimeZone* timeZone) const + \sa status_t BLocale::FormatTime(BString* string, time_t time, + BTimeFormatStyle style, const BTimeZone* timeZone) const */ + /*! -\fn int BLocale::StringCompare(const char* s1, const char* s2) const -\fn int BLocale::StringCompare(const BString* s1, const BString* s2) const -\brief Compares two strings using the locale's collator + \fn status_t BLocale::FormatDate(BString* string, int*& fieldPositions, + int& fieldCount, time_t time, BDateFormatStyle style) const + \brief Fills in \a string with a formatted date for the given + \a time and \a style for the locale. -These methods are short-hands to Collator()->StringCompare. + \param string The string buffer to fill with the formatted date. + \param fieldPositions ??? + \param fieldCount ??? + \param time The time (in seconds since epoch) to format + \param style Specify the long format (with day name, full + month name) or the short format, 08/12/2010 or similar. + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale or an error formatting the date. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::FormatTime(BString* string, int*& fieldPositions, + int& fieldCount, time_t time, BTimeFormatStyle style) const */ + /*! -\fn void BLocale::GetSortKey(const char* string, BString* key) const -\brief Computes the sort key of a string + \fn status_t BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, + BDateFormatStyle style) const + \brief Get the type of each field in the date format of the locale. -This method is a short-hand to Collator()->GetSortKey. + This function is most often used in combination with FormatDate(). + FormatDate() gives you the offset of each field in a formatted string, + and GetDateFields() gives you the type of the field at a given offset. + With these informations, you can handle the formatted date string as + a list of fields that you can split and alter at will. + \param fields Pointer to the fields object. + \param fieldCount The number of fields. + \param style Specify the long format (with day name, full + month name) or the short format, 08/12/2010 or similar. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale or an error getting the date + fields. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, + BTimeFormatStyle style) const +*/ + + +/*! + \fn int BLocale::StartOfWeek() const + \brief Returns the number of the day used as start of week in this locale. + + \returns a flag that indicates the day of the week that the week starts or + B_ERROR if there was an error. + \retval B_ERROR Unable to lock the BLocale. + \retval B_WEEK_START_SUNDAY If the beginning of the week starts on Sunday. + \retval B_WEEK_START_MONDAY If the beginning of the week starts on Monday. +*/ + + +/*! + \fn ssize_t BLocale::FormatDateTime(char* target, size_t maxSize, + time_t time, BDateFormatStyle dateStyle, + BTimeFormatStyle timeStyle) const + \brief Fills in \a string with a formatted datetime up to \a maxSize bytes + for the given \a time and \a style for the locale. + + \param target The string buffer to fill with the formatted datetime. + \param maxSize The size of the buffer. + \param time The time (in seconds since epoch) to format + \param dateStyle Specify the long format or the short format of the date. + \param timeStyle Specify the long format or the short format of the time. + + \returns The number of bytes written during the datetime formatting. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + \retval B_BAD_VALUE CheckedArrayByteSink overflowed. + + \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, + BDateFormatStyle style) const + \sa BLocale::FormatTime(char* string, size_t maxSize, time_t time, + BTimeFormatStyle style) const +*/ + + +/*! + \fn status_t BLocale::FormatDateTime(BString* target, time_t time, + BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, + const BTimeZone* timeZone) const + \brief Fills in \a string with a formatted datetime for the given + \a time, \a timeStyle, and \a timeZone for the locale. + + \param target The string buffer to fill with the formatted date. + \param time The time (in seconds since epoch) to format + \param dateStyle Specify the long format or the short format of the date. + \param timeStyle Specify the long format or the short format of the time. + \param timeZone The time zone. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::FormatDate(BString *string, time_t time, + BDateFormatStyle style, const BTimeZone* timeZone) const + \sa status_t BLocale::FormatTime(BString* string, time_t time, + BTimeFormatStyle style, const BTimeZone* timeZone) const +*/ + + +/*! + \fn ssize_t BLocale::FormatTime(char* string, size_t maxSize, time_t time, + BTimeFormatStyle style) const + \brief Fills in \a string with a formatted date up to \a maxSize bytes for + the given \a time and \a style for the locale. + + \param string The string buffer to fill with the formatted time. + \param maxSize The size of the buffer. + \param time The time (in seconds since epoch) to format + \param style Specify the long format or the short format. + + \returns The number of bytes written during the time formatting. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + \retval B_BAD_VALUE CheckedArrayByteSink overflowed. + + \sa BLocale::FormatDate(char* string, size_t maxSize, time_t time, + BDateFormatStyle style) const + \sa BLocale::FormatDateTime(char* target, size_t maxSize, + time_t time, BDateFormatStyle dateStyle, + BTimeFormatStyle timeStyle) const +*/ + + +/*! + \fn status_t BLocale::FormatTime(BString* string, time_t time, + BTimeFormatStyle style, const BTimeZone* timeZone) const + \brief Fills in \a string with a formatted time for the given + \a time, \a style, and \a timeZone for the locale. + + \param string The string buffer to fill with the formatted date. + \param time The time (in seconds since epoch) to format + \param style Specify the long format or the short format. + \param timeZone The time zone. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::FormatDate(BString *string, time_t time, + BDateFormatStyle style, const BTimeZone* timeZone) const + \sa BLocale::FormatDateTime(BString* target, time_t time, + BDateFormatStyle dateStyle, BTimeFormatStyle timeStyle, + const BTimeZone* timeZone) const +*/ + + +/*! + \fn status_t BLocale::FormatTime(BString* string, int*& fieldPositions, + int& fieldCount, time_t time, BTimeFormatStyle style) const + \brief Fills in \a string with a formatted time for the given + \a time and \a style for the locale. + + \param string The string buffer to fill with the formatted time. + \param fieldPositions ??? + \param fieldCount ??? + \param time The time (in seconds since epoch) to format. + \param style Specify the long format or the short format. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale or an error formatting the time. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::FormatDate(BString* string, int*& fieldPositions, + int& fieldCount, time_t time, BDateFormatStyle style) const +*/ + + +/*! + \fn status_t BLocale::GetTimeFields(BDateElement*& fields, int& fieldCount, + BTimeFormatStyle style) const + \brief Get the type of each field in the time format of the locale. + + This function is most often used in combination with FormatTime(). + FormatTime() gives you the offset of each field in a formatted string, + and GetTimeFields() gives you the type of the field at a given offset. + With these informations, you can handle the formatted date string as + a list of fields that you can split and alter at will. + + \param fields Pointer to the fields object. + \param fieldCount The number of fields. + \param style Specify the long format or the short format. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR Unable to lock the BLocale or an error getting the time + fields. + \retval B_NO_MEMORY Ran out of memory while creating the DateFormat object. + + \sa BLocale::GetDateFields(BDateElement*& fields, int& fieldCount, + BDateFormatStyle style) const +*/ + + +/*! + \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, + double value) const + \brief Format the \c double \a value as a string and put the result + into \a string up to \a maxSize bytes in the current locale. + + \param string The string to put the formatted number into. + \param maxSize The maximum of bytes to copy into \a string. + \param value The number that you want to get a formatted version of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(char* string, size_t maxSize, + int32 value) const + \sa ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, + double value) const +*/ + + +/*! + \fn status_t BLocale::FormatNumber(BString* string, double value) const + \brief \brief Format the \c double \a value as a string and put the result + into \a string in the current locale. + + \param string The string to put the formatted number into. + \param value The number that you want to get a formatted version of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(BString* string, int32 value) const + \sa BLocale::FormatMonetary(BString* string, double value) const +*/ + + +/*! + \fn ssize_t BLocale::FormatNumber(char* string, size_t maxSize, + int32 value) const + \brief Format the \c int32 \a value as a string and put the result + into \a string up to \a maxSize bytes in the current locale. + + \param string The string to put the formatted number into. + \param maxSize The maximum of bytes to copy into \a string. + \param value The number that you want to get a formatted version of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(char* string, size_t maxSize, + double value) const + \sa BLocale::FormatMonetary(char* string, size_t maxSize, + double value) const +*/ + + +/*! + \fn status_t BLocale::FormatNumber(BString* string, int32 value) const + \brief \brief Format the \c int32 \a value as a string and put the result + into \a string in the current locale. + + \param string The string to put the formatted number into. + \param value The number that you want to get a formatted version of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(BString* string, double value) const + \sa BLocale::FormatMonetary(BString* string, double value) const +*/ + + +/*! + \fn ssize_t BLocale::FormatMonetary(char* string, size_t maxSize, + double value) const + \brief Format the \c double \a value as a monetary string and put the + result into \a string up to \a maxSize bytes in the current locale. + + \param string The string to put the monetary formatted number into. + \param maxSize The maximum of bytes to copy into \a string. + \param value The number that you want to get a monetary formatted version + of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(char* string, size_t maxSize, + double value) const + \sa BLocale::FormatNumber(char* string, size_t maxSize, + int32 value) const +*/ + + +/*! + \fn status_t BLocale::FormatMonetary(BString* string, double value) const + \brief \brief Format the \c double \a value as a monetary string and put + the result into \a string in the current locale. + + \param string The string to put the monetary formatted number into. + \param value The number that you want to get a monetary formatted version + of. + + \returns The length of the string created or an error status code in + the case of an error. + + \sa BLocale::FormatNumber(BString* string, double value) const + \sa BLocale::FormatNumber(BString* string, int32 value) const */ diff --git a/docs/user/locale/LocaleRoster.dox b/docs/user/locale/LocaleRoster.dox index 685487cbaa..f65b404bed 100644 --- a/docs/user/locale/LocaleRoster.dox +++ b/docs/user/locale/LocaleRoster.dox @@ -1,92 +1,214 @@ -/*! -\class BLocaleRoster -\ingroup locale -\brief Main class for accessing the locale kit data +/* + * Copyright 2003-2010, Haiku. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Axel Dörfler, axeld@pinc-software.de + * John Scipione, jscipione@gmail.com + * Oliver Tappe, zooey@hirschkaefer.de + * + * Corresponds to: + * /trunk/headers/os/locale/LocaleRoster.h rev 42274 + * /trunk/src/kits/locale/LocaleRoster.cpp rev 42274 + */ -The Locale Roster is the central part of the locale kit. -It is a global object (be_locale_roster) storing all the useful locale -data. Other classes from the Locale Kit can be constructed on their own, -but only the Locale Roster allows you to do so while taking account of -the user's locale settings. -*/ /*! -\fn status_t BLocaleRoster::GetDefaultCollator(BCollator* collator) const -\brief Get the default collator. + \class BLocaleRoster + \ingroup locale + \brief Main class for accessing the locale kit data + + The Locale Roster is the central part of the locale kit. It is a global + object (\c be_locale_roster) storing all the useful locale data. Other + classes from the Locale Kit can be constructed on their own, but only the + Locale Roster allows you to do so while taking account of the user's locale + settings. */ + /*! -\fn status_t BLocaleRoster::GetDefaultLocale(BLocale* locale) const -\brief Get the default locale. + \fn BLocaleRoster::BLocaleRoster() + \brief Constructor. Does nothing. */ + /*! -\fn status_t BLocaleRoster::GetDefaultCountry(BCountry* country) const -\brief Get the default country. + \fn BLocaleRoster::~BLocaleRoster() + \brief Destructor. Does nothing. */ + /*! -\fn status_t BLocaleRoster::GetDefaultLanguage(BLanguage* language) const -\brief Get the default language. + \fn BLocaleRoster* BLocaleRoster::Default() + \brief Returns default BLocalRoster. */ + /*! -\fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const -\brief Get the default timezone. + \fn status_t BLocaleRoster::Refresh() + \brief Refreshes the BLocalRoster. */ + /*! -\fn status_t BLocaleRoster::GetLanguage(const char* languagecode, BLanguage** _language) const -\brief Instanciate a language from its code. + \fn status_t BLocaleRoster::GetDefaultTimeZone(BTimeZone* timezone) const + \brief Get the default timezone. */ + /*! -\fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const -\brief List the available languages - -This function fills the passed BMessage with one or more 'language' string -fields, containing the language(s) ID(s). - + \fn status_t BLocaleRoster::GetLanguage(const char* languagecode, + BLanguage** _language) const + \brief Instantiate a language from its code. */ + /*! -\fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const -\brief List the available countries - -This function filles the passed BMessage with one or more 'country' string -fields, containing the (ISO-639) code of each country. + \fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const + \brief Return the list of user preferred languages. + This function fills in the given message with one or more language string + fields. They constitute the ordered list of user-selected languages to use + for string translation. */ + /*! -\fn status_t BLocaleRoster::GetInstalledCatalogs(BMessage* message, const char* sigPattern = NULL, const char* langPattern = NULL, int32 fingerprint = 0) const -\brief Get the available locales and catalogs - -This function fills the passed BMessage with one or more 'locale' string -fields, containing the locale names. - -The optional parameters can be used to filter the list and only get the -locales for which a catalog is available for the given app (sigPattern, fingerprint), -or the locales with a given language. + \fn status_t BLocaleRoster::GetAvailableLanguages(BMessage* message) const + \brief Fills \c message with 'language'-fields containing the language + ID(s) of all available languages. */ + /*! -\fn BCatalog* BLocaleRoster::GetCatalog() -\brief Get the current image catalog. - -This function returns the catalog for the calling image (application, add-on, or shared -library). Note that it doesn't allow to specify a fingerprint. The language will be -selected from the user preferences. - -\returns The catalog, if it was loaded successfully. -\warning This function needs the image to be lined with liblocalestub.a + \fn status_t BLocaleRoster::GetAvailableCountries(BMessage* message) const + \brief Fills in the passed in \a message with one or more 'country' + string fields, containing the (ISO-639) code of each country. */ + /*! -\fn status_t BLocaleRoster::GetPreferredLanguages(BMessage* message) const -\brief Return the list of user preferred languages. + \fn status_t BLocaleRoster::GetAvailableTimeZones(BMessage* timeZones) const + \brief Fills in the passed in \a timeZones message with all time zone + strings for the locale. -This function fills in the given message with one or more language string -fields. They constitute the ordered list of user-selected languages to use for -string translation. + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in. + \retval B_ERROR An error occurred trying to retrieve the localized time zone + strings. +*/ + + +/*! + \fn status_t BLocaleRoster::GetAvailableTimeZonesForCountry( + BMessage* timeZones, const char* countryCode) const + \brief Fills in the passed in \a timeZones message with one or more + time zone strings containing the time zones for the + country specified by \a countryCode for the locale. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE A \c NULL \a timeZones message was passed in. + \retval B_ERROR An error occurred trying to retrieve the localized time + zones most likely due to an invalid \a countryCode. +*/ + + +/*! + \fn status_t BLocaleRoster::GetFlagIconForCountry(BBitmap* flagIcon, + const char* countryCode) + \brief Sets \a flagIcon to the flag for the passed in \a countryCode. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE A \c NULL or invalid \a countryCode was passed in. + \retval B_ERROR Error locking the default RosterData. + \retval B_NAME_NOT_FOUND The flag could not be found for the + \a countryCode. +*/ + + +/*! + \fn status_t BLocaleRoster::GetFlagIconForLanguage(BBitmap* flagIcon, + const char* languageCode) + \brief Sets \a flagIcon to the flag for the passed in \a languageCode. + + If a flag could not be located for the passed in \a languageCode then + GetFlagIconForLanguage() attempts to locate the default country's flag for + the \a languageCode instead. The default country flag for a language is + usually set to the country of the languages origin such as Germany for + German or Spain for Spanish. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE A \c NULL or invalid \a languageCode was passed in. + \retval B_ERROR Error locking the default RosterData. + \retval B_NAME_NOT_FOUND The flag could not be found for the + default country's flag for the \a languageCode. +*/ + + +/*! + \fn status_t BLocaleRoster::GetAvailableCatalogs(BMessage* languageList, + const char* sigPattern, const char* langPattern, + int32 fingerprint) const + \brief Get the available locales and catalogs. + + Fills the passed \a languageList message with one or more 'locale' string + fields containing the locale names. + + The optional parameters can be used to filter the list and only get the + locales for which a catalog is available for the given app (sigPattern, + fingerprint), or the locales with a given language. + + \returns A status code. + \retval B_OK Everything went well. + \retval B_BAD_VALUE A \c NULL \a languageList message was passed in. + \retval B_ERROR Error locking the default RosterData. +*/ + + +/*! + \fn bool BLocaleRoster::IsFilesystemTranslationPreferred() const + \brief Returns whether or not filesystem translation is preferred. + + \returns \c B_ERROR if there was an error locking the default RosterData. +*/ + + +/*! + \fn status_t BLocaleRoster::GetLocalizedFileName(BString& localizedFileName, + const entry_ref& ref, bool traverse) + \brief Looks up a localized filename from a catalog. + + Attribute format: "signature:context:string" + (no colon in any of signature, context and string) + + Lookup is done for the top preferred language only. + Lookup fails if a comment is present in the catalog entry. + + \param localizedFileName A pre-allocated BString object for the result + of the lookup. + \param ref An entry_ref with an attribute holding data for catalog lookup. + \param traverse Determines if symlinks should be traversed. + + \returns A status code. + \retval B_OK: success + \retval B_ENTRY_NOT_FOUND: failure. Attribute not found, entry not found + in catalog, etc. +*/ + + +/*! + \fn BCatalog* BLocaleRoster::_GetCatalog() + \brief Get the current image catalog. + + This function returns the catalog for the calling image (application, + add-on, or shared library). Note that it doesn't allow to specify a + fingerprint. The language will be selected from the user preferences. + + \warning This function needs the image to be lined with liblocalestub.a + + \returns The catalog, if it was loaded successfully. */ diff --git a/docs/user/locale/TimeZone.cpp b/docs/user/locale/TimeZone.cpp deleted file mode 100644 index 2836d4fb7f..0000000000 --- a/docs/user/locale/TimeZone.cpp +++ /dev/null @@ -1,72 +0,0 @@ -/*! -\class BTimeZone -\ingroup locale -\brief Class holding information for a time zone. - -*/ - -/*! -\fn BTimeZone::BTimeZone(const char* zoneCode) -\brief Construct a timezone from its code. - -The constructor only allows you to construct a timezone if you already know its -code. If you don't know the code, you can instead go through the BCountry class -which can enumerate all timezones in a country, or use the BLocaleRoster, which -knows the timezone selected by the user. -*/ - -/*! -\fn const BString& BTimeZone::Code() const -\brief Returns the timezone code. - -Note different time zones with different codes may have the same rules. -*/ - -/*! -\fn const BString& BTimeZone::Name() const -\brief Returns the localized name of the time zone - -Use this for displaying information to the user. -*/ - -/*! -\fn const BString& BTimeZone::DaylightSavingName() const -\brief Return the name of the daylight savings rules used in this timezone. -*/ - -/*! -\fn const BString& BTimeZone::ShortName() const -\brief Return the short name of the timezone, in the user's locale. -*/ - -/*! -\fn const BString& BTimeZone::DaylightSavingName() const -\brief Return the short name of the daylight savings rules used in this -timezone. -*/ - -/*! -\fn int BTimeZone::OffsetFromGMT() const -\brief Return the offset from GMT. - -The offset is a number of seconds, positive or negative. -*/ - -/*! -\fn bool BTimeZone::SupportsDaylightSaving() const -\brief Return true if the time zone has daylight saving rules -*/ - -/*! -\fn status_t BTimeZone::InitCheck() const -\brief Return false if there was an error creating the timezone (you called the -constructor or SetTo with an invalid code). -*/ - -/*! -\fn status_t BTimeZone::SetTo(const char* zoneCode) -\brief Set the timezone to another code. - -\returns false if there was an error (likely you given an invalid code) -*/ - diff --git a/docs/user/locale/TimeZone.dox b/docs/user/locale/TimeZone.dox new file mode 100644 index 0000000000..d100ef759e --- /dev/null +++ b/docs/user/locale/TimeZone.dox @@ -0,0 +1,110 @@ +/* + * Copyright 2011, Haiku inc. + * Distributed under the terms of the MIT Licence. + * + * Documentation by: + * Adrien Destugues + * John Scipione + * Oliver Tappe + * Corresponds to: + * /trunk/headers/os/locale/TimeZone.h rev 42274 + * /trunk/src/kits/locale/TimeZone.cpp rev 42274 + */ + + +/*! + \file TimeZone.h + \brief Provides for the BTimeZone class. +*/ + + +/*! + \class BTimeZone + \ingroup locale + \brief Provides information about time zones. +*/ + + +/*! + \fn BTimeZone::BTimeZone(const char* zoneID, const BLanguage* language) + \brief Construct a timezone from its \a zoneID and \a language. + + The constructor only allows you to construct a timezone if you already + know its code. If you don't know the code, you can instead go through the + BCountry class which can enumerate all timezones in a country, or use the + BLocaleRoster, which knows the timezone selected by the user. +*/ + + +/*! + \fn BTimeZone::BTimeZone(const BTimeZone& other) +*/ + + +/*! + \fn BTimeZone& BTimeZone::operator=(const BTimeZone& source) +*/ + + +/*! + \fn const BString& BTimeZone::ID() const + \brief Returns the ID of the time zone. +*/ + + +/*! + \fn const BString& BTimeZone::Name() const + \brief Returns the localized name of the time zone. + + Use this method to display the time zone's name to the user. +*/ + + +/*! + \fn const BString& BTimeZone::DaylightSavingName() const + \brief Returns the name of the daylight savings rules used in this timezone. +*/ + + +/*! + \fn const BString& BTimeZone::ShortName() const + \brief Returns the short name of the timezone, in the user's locale. +*/ + + +/*! + \fn const BString& BTimeZone::ShortDaylightSavingName() const + \brief Returns the short name of the daylight savings rules used in this + timezone. +*/ + + +/*! + \fn int BTimeZone::OffsetFromGMT() const + \brief Return the offset from GMT. + + The offset is a number of seconds, positive or negative. +*/ + + +/*! + \fn bool BTimeZone::SupportsDaylightSaving() const + \brief Return true if the time zone has daylight saving rules +*/ + + +/*! + \fn status_t BTimeZone::InitCheck() const + \brief Return \c false if there was an error creating the timezone + for instance if you called the constructor or SetTo() with an invalid + timezone code.) +*/ + + +/*! + \fn status_t BTimeZone::SetTo(const char* zoneCode) + \brief Set the timezone to another code. + + \returns \c false if there was an error (likely due to an invalid + timezone code.) +*/ diff --git a/docs/user/locale/UnicodeChar.dox b/docs/user/locale/UnicodeChar.dox index d7810a4e63..91709dc4ad 100644 --- a/docs/user/locale/UnicodeChar.dox +++ b/docs/user/locale/UnicodeChar.dox @@ -1,167 +1,245 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the OpenBeOS License. + * + * Authors: + * Axel Dörfler + * John Scipione + * + * Corresponds to: + * /trunk/headers/os/locale/UnicodeChar.h rev 42274 + * /trunk/src/kits/locale/UnicodeChar.cpp rev 42274 + */ + /*! -\class BUnicodeChar -\ingroup locale + \class BUnicodeChar + \ingroup locale -\brief Management of all information about characters. + \brief Management of all information about characters. -This class provide a set of tools for managing the whole set of characters -defined in unicode. This include informations such as knowing if the character is -whitespace, if it is alphanumeric, or solething else ; what is the uppercase -equivalent of a character ; or wether it can be ornamented with accents. + This class provide a set of tools for managing the whole set of characters + defined by unicode. This include information about special sets of + characters such as if the character is whitespace, or alphanumeric. It also + provides the uppercase equivalent of a character and determines whether a + character can be ornamented with accents. -This class consists entirely of static methods, which means you don't have to -instanciate it. Just call one of the methods with the char you want examinated. - -Note all the function work with chars encoded in utf-32. This is not the most usual -way to handle characters, but it is the faster. To convert an utf-8 string to an -utf-32 character, pass it to the FromUTF8 function. + This class consists entirely of static methods, so you do not have to + instantiate it. You can call one of the methods passing in the character + that you want to be examined. + Note all the function work with chars encoded in utf-32. This is not the + most usual way to handle characters, but it is the fastest. To convert an + utf-8 string to an utf-32 character use the FromUTF8() method. */ /*! -\fn static bool BUnicodeChar::IsAlpha(uint32 c) -\brief Tell if the character is alphabetic. + \fn static bool BUnicodeChar::IsAlpha(uint32 c) + \brief Determine if \a c is alphabetic. + + \returns \c true if the specified unicode character is an + alphabetic character. */ /*! -\fn static bool BUnicodeChar::IsAlNum(uint32 c) -\brief Tell if the character is alphanumeric. + \fn static bool BUnicodeChar::IsAlNum(uint32 c) + \brief Determine if \a c is alphanumeric. + + \returns \c true if the specified unicode character is a + alphabetic or numeric character. */ /*! -\fn static bool BUnicodeChar::IsDigit(uint32 c) -\brief Tell if the caracter is numeric. + \fn static bool BUnicodeChar::IsDigit(uint32 c) + \brief Determine if \a c is numeric. + + \returns \c true if the specified unicode character is a + number character. */ /*! -\fn static bool BUnicodeChar::IsHexDigit(uint32 c) -\brief Tell if the character is numeric in base 16. + \fn static bool BUnicodeChar::IsHexDigit(uint32 c) + \brief Determine if \a c is a hexadecimal digit. + + \returns \c true if the specified unicode character is a + hexadecimal number character. */ /*! -\fn static bool BUnicodeChar::IsUpper(uint32 c) -\brief Tell if the character is uppercase. + \fn static bool BUnicodeChar::IsUpper(uint32 c) + \brief Determine if \a c is uppercase. + + \returns \c true if the specified unicode character is an + uppercase character. */ /*! -\fn static bool BUnicodeChar::IsLower(uint32 c) -\brief Tell if the character is lowercase. + \fn static bool BUnicodeChar::IsLower(uint32 c) + \brief Determine if \a c is lowercase. + + \returns \c true if the specified unicode character is a + lowercase character. */ /*! -\fn static bool BUnicodeChar::IsSpace(uint32 c) -\brief Tell if the character is space. + \fn static bool BUnicodeChar::IsSpace(uint32 c) + \brief Determine if \a c is a space. -Unlike IsWhitespace, this function will return true for non-breakable -spaces. It is the one to use for determining if the character will render -as an empty space on screen and can be stretched to make the text look -nicer. + Unlike IsWhitespace() this function will return \c true for non-breakable + spaces. This method is useful for determining if the character will render + as an empty space which can be stretched on-screen. + + \returns \c true if the specified unicode character is some + kind of a space character. + + \sa IsWhitespace() */ /*! -\fn static bool BUnicodeChar::IsWhitespace(uint32 c) -\brief Tell if the character is whitespace. + \fn static bool BUnicodeChar::IsWhitespace(uint32 c) + \brief Determine if \a c is whitespace. -Unlike IsSpace, this method will return false for non-breakable spaces. -It is the one to use for selecting where to insert line breaks. + This method is essentially the same as IsSpace(), but excludes all + non-breakable spaces. + + \returns \c true if the specified unicode character is a whitespace + character. + + \sa IsSpace() */ /*! -\fn static bool BUnicodeChar::IsControl(uint32 c) -\brief Tell if the character is a control character. + \fn static bool BUnicodeChar::IsControl(uint32 c) + \brief Determine if \a c is a control character. -Example control characters are the non-printable ASCII characters 0 to 0x1F. + Example control characters are the non-printable ASCII characters from + 0x0 to 0x1F. + + \returns \c true if the specified unicode character is a control + character. + + \sa IsPrintable() */ /*! -\fn static bool BUnicodeChar::IsPunctuation(uint32 c) -\brief Tell if the character is a punctuation. + \fn static bool BUnicodeChar::IsPunctuation(uint32 c) + \brief Determine if \a c is punctuation character. + + \returns \c true if the specified unicode character is a + punctuation character. */ /*! -\fn static bool BUnicodeChar::IsPrintable(uint32 c) -\brief Tell if the character is printable. + \fn static bool BUnicodeChar::IsPrintable(uint32 c) + \brief Determine if \a c is printable. + + Printable characters are not control characters. + + \returns \c true if the specified unicode character is a printable + character. + + \sa IsControl() */ /*! -\fn static bool BUnicodeChar::IsTitle(uint32 c) -\brief Tell if the character is title case. + \fn static bool BUnicodeChar::IsTitle(uint32 c) + \brief Determine if \a c is title case. -Title case is usually a smaller version of upercase letters. + Title case characters are a smaller version of normal uppercase letters. + + \returns \c true if the specified unicode character is a title case + character. */ /*! -\fn static bool BUnicodeChar::IsDefined(uint32 c) -\brief Tell if the character is defined at all. + \fn static bool BUnicodeChar::IsDefined(uint32 c) + \brief Determine if \a c is defined. -In unicode, some codes are not valid, or not attributed yet. -For these, this method wil lreturn false. + In unicode some codes are not valid or not attributed yet. + For these codes this method will return \c false. + + \returns \c true if the specified unicode character is defined. */ /*! -\fn static bool BUnicodeChar::IsBase(uint32 c) -\brief Tell if the character can be used with a diacritic. + \fn static bool BUnicodeChar::IsBase(uint32 c) + \brief Determine if \a c can be used with a diacritic. + + \note IsBase() does not determine if a unicode character is distinct. + + \returns \c true if the specified unicode character is a base + form character that can be used with a diacritic. */ /*! -\fn static int8 BUnicodeChar::Type(uint32 c) -\brief Returns the type of the character. + \fn static int8 BUnicodeChar::Type(uint32 c) + \brief Gets the type of a character. -Return value is a member of the unicode_char_category enum. + \returns A member of the \c unicode_char_category enum. */ /*! -\fn static uint32 ToLower(uint32 c); -\brief Returns the lowercase version of a character. + \fn uint32 BUnicodeChar::ToLower(uint32 c) + \brief Transforms \a c to lowercase. + + \returns The lowercase version of the specified unicode character. */ /*! -\fn static uint32 ToUpper(uint32 c); -\brief Returns the uppercase version of a character. + \fn uint32 BUnicodeChar::ToUpper(uint32 c) + \brief Transforms \a c to uppercase. + + \returns The uppercase version of the specified unicode character. */ /*! -\fn static uint32 ToTitle(uint32 c); -\brief Returns the titlecase version of a character. + \fn uint32 BUnicodeChar::ToTitle(uint32 c) + \brief Transforms \a c to title case. + + \returns The title case version of the specified unicode character. */ /*! -\fn static int32 DigitValue(uint32 c); -\brief Returns the numeric value of the character. + \fn int32 BUnicodeChar::DigitValue(uint32 c) + \brief Gets the numeric value \a c. + + \returns The numeric version of the specified unicode character. */ /*! -\fn static void ToUTF8(uint32c, char ù**ou -\brief Convert a character to utf8 encoding. + \fn void BUnicodeChar::ToUTF8(uint32 c, char **out) + \brief Transform a character to utf-8 encoding. + + \returns The utf-8 encoding of the specified unicode character. */ /*! -\fn static uint32 FromUTF8(const char** in) -\brief Convert an utf-8 string to an utf-32 character. + \fn uint32 BUnicodeChar::FromUTF8(const char **in) + \brief Transform a utf-8 string to an utf-32 character. -If the string contains multiple characters, only the fist one is used. -This function updates the in pointer so that it points on the next -character for the following call. + If the string contains multiple characters, only the fist one is used. + This function updates the in pointer so that it points on the next + character for the following call. + + \returns The utf-32 encoded version of \a in. */ /*! -\fn static uint32 FromUTF8(const char* in) -\brief Convert an utfÃ-8 string to an utfÃ-32 character. + \fn size_t BUnicodeChar::UTF8StringLength(const char *str) + \brief Counts the characters in the given \c NUL terminated string. -If the string contains multiple characters, only the first one is used. -The in pointer is not modified. + \returns the number of utf-8 characters in the \c NUL terminated string. + + \sa BString::CountChars() */ /*! -\fn static size_t UTF8StringLength(const char* str) -\brief This function counts the characters in the given null-terminated string. + \fn size_t BUnicodeChar::UTF8StringLength(const char *str, size_t maxLength) + \brief Counts the characters in the given string up to \a maxLength + characters. -\sa BString::CountChars() -*/ - -/*! -\fn static size_t UTF8StringLength(const char* str, size_t maxLength) -\brief This function counts the characters in the given string. - -The string does not need to be null-terminated if you specify the length. + The string does not need to be \c NUL terminated if you specify a + \a maxLength that is shorter than the maximum length of the string. + + \returns the number of utf-8 characters in the \c NUL terminated string + up to \a maxLength characters. */ diff --git a/docs/user/media/Buffer.dox b/docs/user/media/Buffer.dox new file mode 100644 index 0000000000..71345f9d82 --- /dev/null +++ b/docs/user/media/Buffer.dox @@ -0,0 +1,113 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/media/Buffer.h rev 42274 + * /trunk/src/kits/media/Buffer.cpp rev 42274 + */ + + +/*! + \file Buffer.h + \brief Defines the buffer_clone_info struct and BBuffer class. +*/ + + +/*! + \struct buffer_clone_info + \brief A struct that stores where in memory a BBuffer object is in memory + as well as the buffer flags. +*/ + + +/*! + \class BBuffer + \ingroup media + \brief A reference to a chunk of memory useful for sharing media data + between applications and nodes. +*/ + + +/*! + \fn void* BBuffer::Data() + \brief Returns a pointer to the data of the buffer. +*/ + + +/*! + \fn size_t BBuffer::SizeAvailable() + \brief Returns the size of the buffer in bytes. Alias for Size(). +*/ + + +/*! + \fn size_t BBuffer::SizeUsed() + \brief Returns the size of the portion of the buffer that is currently in + use in bytes. +*/ + + +/*! + \fn void BBuffer::SetSizeUsed(size_t size_used) + \brief Sets the size of the buffer that is used in bytes. + + This method should be called after writing data to the buffer. +*/ + + +/*! + \fn uint32 BBuffer::Flags() + \brief Returns the flags of the buffer. +*/ + + +/*! + \fn void BBuffer::Recycle() + \brief Recycles the buffer so that it can be reused. +*/ + + +/*! + \fn buffer_clone_info BBuffer::CloneInfo() const + \brief Returns the buffer_clone_info struct that describes the buffer. +*/ + + +/*! + \fn media_buffer_id BBuffer::ID() + \brief Returns the app_server ID of the buffer. +*/ + + +/*! + \fn media_type BBuffer::Type() + \brief Returns the media type of the data in the buffer. +*/ + + +/*! + \fn media_header* BBuffer::Header() + \brief Returns a pointer to the header of the buffer. +*/ + + +/*! + \fn media_audio_header* BBuffer::AudioHeader() + \brief Returns a pointer to a header of the audio buffer. +*/ + + +/*! + \fn media_video_header* BBuffer::VideoHeader() + \brief Returns a pointer to a header of the video buffer. +*/ + + +/*! + \fn size_t BBuffer::Size() + \brief Returns the size of the buffer in bytes. Alias for SizeAvailable(). +*/ diff --git a/docs/user/storage/AppFileInfo.dox b/docs/user/storage/AppFileInfo.dox new file mode 100644 index 0000000000..d6c5d5374d --- /dev/null +++ b/docs/user/storage/AppFileInfo.dox @@ -0,0 +1,769 @@ +/* + * Copyright 2011, Haiku inc. + * Distributed under the terms of the MIT Licence. + * + * Documentation by: + * John Scipione + * Ingo Weinhold + * Corresponds to: + * /trunk/headers/os/storage/AppFileInfo.h rev 42274 + * /trunk/src/kits/storage/AppFileInfo.cpp rev 42274 + */ + + +/*! + \file AppFileInfo.h + \brief Provides the BAppFileInfo class. +*/ + + +/*! + \class BAppFileInfo + \ingroup storage + \brief Provides access to the metadata associated with executables, + libraries and add-ons. + + The BAppFileInfo class allows for information about an executable or + add-on to be accessed or set. Information about an executable that can be + accessed include the signature, catalog entry, supported MIME types, + application flags, icon(s), and version info. + + You should initialize the BAppFileInfo with a BFile object that represents + the executable or add-on that you want to access. If you only want to read + metadata from the file you do not have to open it for reading. However, if + you also want to write metadata then you should open the BFile for writing. + + To associate a BFile with a BAppFileInfo object you can either pass the + BFile object into the constructor or you can use the empty constructor and + then use the SetTo() method to set the BFile to the BAppFileInfo object. + + When accessing information from a BFileInfo object it will first look in the + attributes of the BFile. If the information is not found then the BFileInfo + object will next look at the resource of the BFile. You can tell the + BFileInfo object to look only in the attributes or resources with the + SetInfoLocation() method. +*/ + + +/*! + \fn BAppFileInfo::BAppFileInfo() + \brief Creates an uninitialized BAppFileInfo object. +*/ + + +/*! + \fn BAppFileInfo::BAppFileInfo(BFile* file) + \brief Creates an BAppFileInfo object and initializes it to the supplied + file. + + The caller retains ownership of the supplied BFile object. It must not + be deleted during the life time of the BAppFileInfo. It is not deleted + when the BAppFileInfo is destroyed. + + \param file The BFile object that the BAppFileInfo object shall be + initialized to. +*/ + + +/*! + \fn BAppFileInfo::~BAppFileInfo() + \brief Frees all resources associated with this object. + + The supplied BFile object is not deleted if one is specified. +*/ + + +/*! + \fn status_t BAppFileInfo::SetTo(BFile *file) + \brief Initializes the BAppFileInfo to the supplied file. + + The caller retains ownership of the supplied BFile object. It must not + be deleted during the life time of the BAppFileInfo. The BFile object + is not deleted when the BAppFileInfo is destroyed. + + \param file The BFile object that the BAppFileInfo object shall be + initialized to. + + \returns an status code. + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized. +*/ + + +/*! + \name MIME Type +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetType(char *type) const + \brief Gets the MIME type of the associated file. + + \param type A pointer to a pre-allocated character buffer of size + \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the + file will be written. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a type or the type string stored in the + attribute/resources is longer than \c B_MIME_TYPE_LENGTH. + \retval B_BAD_TYPE The attribute/resources the type string is stored in + has the wrong type. + \retval B_ENTRY_NOT_FOUND No type is set on the file. +*/ + + +/*! + \fn status_t BAppFileInfo::SetType(const char* type) + \brief Sets the MIME type of the associated file. + + If \a type is \c NULL if the file's MIME type is unset. + + \param type The MIME type to be assigned to the file. It must not be + longer than \c B_MIME_TYPE_LENGTH (including the terminating null). + The MIME type may be \c NULL. + + \returns a status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH. +*/ + + +//! @} + + +/*! + \name Signature +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetSignature(char* signature) const + \brief Gets the application signature of the associated file. + + \param signature A pointer to a pre-allocated character buffer of size + \c B_MIME_TYPE_LENGTH or larger into which the application + signature of the file will be written. + + \returns a status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a signature or the signature stored in the + attribute/resources is longer than \c B_MIME_TYPE_LENGTH. + \retval B_BAD_TYPE The attribute/resources the signature is stored in have + the wrong type. + \retval B_ENTRY_NOT_FOUND No signature is set on the file. +*/ + + +/*! + \fn status_t BAppFileInfo::SetSignature(const char* signature) + \brief Sets the application signature of the associated file. + + If \a signature is \c NULL the file's application signature is unset. + + \param signature The application signature to be assigned to the file. + Must not be longer than \c B_MIME_TYPE_LENGTH (including the + terminating \c NUL). The \a signature may be \c NULL. + + \returns a status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH. +*/ + + +//! @} + + +/*! + \name Catalog Entry +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetCatalogEntry(char *catalogEntry) const + \brief Gets the catalog entry of the associated file used for localization. + + \param catalogEntry A pointer to a pre-allocated character buffer of size + \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry + of the file will be written. + + \returns a status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a catalogEntry or the entry stored in the + attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3. + \retval B_BAD_TYPE The attribute/resources the entry is stored in have + the wrong type. + \retval B_ENTRY_NOT_FOUND No catalog entry is set on the file. +*/ + + +/*! + \fn status_t BAppFileInfo::SetCatalogEntry(const char* catalogEntry) + \brief Sets the catalog entry of the associated file used for localization. + + If \a catalogEntry is \c NULL the file's catalog entry is unset. + + \param catalogEntry The catalog entry to be assigned to the file. + Of the form "x-vnd.Haiku-app:context:name". Must not be longer than + \c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL). + The \a catalogEntry may be \c NULL. + + \returns a status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \a catalogEntry is longer than + \c B_MIME_TYPE_LENGTH * 3. +*/ + + +//! @} + + +/*! + \name Application Flags +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetAppFlags(uint32* flags) const + \brief Gets the application \a flags of the associated file. + + \param flags A pointer to a pre-allocated \c uint32 into which the + application flags of the file are written. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a flags. + \retval B_BAD_TYPE The attribute/resources the flags are stored in have + the wrong type. + \retval B_ENTRY_NOT_FOUND No application flags are set on the file. +*/ + + +/*! + \fn status_t BAppFileInfo::SetAppFlags(uint32 flags) + \brief Sets the application \a flags of the associated file. + + \param flags The application \a flags to be assigned to the file. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object was not properly initialized. +*/ + + +/*! + \fn status_t BAppFileInfo::RemoveAppFlags() + \brief Removes the application flags from the associated file. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object was not properly initialized. +*/ + + +//! @} + + +/*! + \name Supported MIME Types +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetSupportedTypes(BMessage* types) const + \brief Gets the MIME types supported by the application. + + The supported MIME types are added to a field "types" of type + \c B_STRING_TYPE in \a types. + + \param types A pointer to a pre-allocated BMessage into which the + MIME types supported by the application will be written. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a types. + \retval B_BAD_TYPE The attribute/resources that the supported types + are stored in have the wrong type. + \retval B_ENTRY_NOT_FOUND No supported types are set on the file. +*/ + + +/*! + \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types, + bool syncAll) + \brief Sets the MIME types that are supported by the application and allows + you to specify whether or not the no longer supported types shall be + updated as well. + + If \a types is \c NULL then the application's supported types are unset. + + The supported MIME types must be stored in a field "types" of type + \c B_STRING_TYPE in \a types. + + The method informs the registrar about this news. + For each supported type the result of BMimeType::GetSupportingApps() + will afterwards include the signature of this application. That is, + the application file needs to have a signature set. + + \a syncAll specifies whether the no longer supported types shall be + updated as well, i.e. whether or not this application shall be removed + from the list of supporting applications. + + \param types The supported types to be assigned to the file. + May be \c NULL. + \param syncAll \c true to also synchronize the no-longer supported + types, \c false otherwise. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. +*/ + + +/*! + \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types) + \brief Sets the MIME types supported by the application. + + This method is a short-hand for SetSupportedTypes(types, false). + \see SetSupportedType(const BMessage*, bool) for detailed information. + + \param types The supported types to be assigned to the file. + May be \c NULL. + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. +*/ + + +/*! + \fn bool BAppFileInfo::IsSupportedType(const char* type) const + \brief Returns whether the application supports the supplied MIME type. + + If the application supports the wildcard type "application/octet-stream" + then this method returns \c true for any MIME type. + + \param type The MIME type in question. + + \returns \c true if \a type is a valid MIME type and it is supported by + the application, \c false otherwise. +*/ + + +/*! + \fn bool BAppFileInfo::Supports(BMimeType* type) const + \brief Returns whether the application supports the supplied MIME type + explicitly. + + Unlike IsSupportedType(), this method returns \c true, only if the type + is explicitly supported, regardless of whether it supports + "application/octet-stream". + + \param type The MIME type in question. + + \returns \c true if \a type is a valid MIME type and it is explicitly + supported by the application, \c false otherwise. +*/ + + +//! @} + + +/*! + \name Application Icon +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const + \brief Gets the icon of the associated file and puts it into a pre-allocated + BBitmap. + + \param icon A pointer to a pre-allocated BBitmap of the correct dimension + to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32 + for the \c B_LARGE_ICON). + \param which Specifies the size of the icon to be retrieved: + \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. + For HVIF icons this parameter has no effect. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which or + bitmap dimensions (\a icon) and icon size (\a which) do not match. +*/ + + +/*! + \fn status_t BAppFileInfo::GetIcon(uint8** data, size_t* size) const + \brief Gets the icon of the associated file and puts it into a buffer. + + \param data The pointer in which the flat icon data will be returned. + \param size The pointer in which the size of the data found will be + returned. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a data or \c NULL size. +*/ + + +/*! + \fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which) + \brief Sets the icon of the associated file from a BBitmap. + + If \a icon is \c NULL then the icon of the file is unset. + + \param icon A pointer to the BBitmap containing the icon to be set. + May be \c NULL to specify no icon. + \param which Specifies the size of the icon to be set: \c B_MINI_ICON for + 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. + For HVIF icons this parameter has no effect. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions + (\a icon) and icon size (\a which) do not match. +*/ + + +/*! + \fn status_t BAppFileInfo::SetIcon(const uint8* data, size_t size) + \brief Sets the icon of the associated file from a buffer. + + If \a data is \c NULL then the icon of the file is unset. + + \param data A pointer to the data buffer containing the vector icon + to be set. May be \c NULL. + \param size Specifies the size of buffer pointed to by \a data. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL data. +*/ + + +/*! + \fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon, + icon_size size) const + \brief Gets the icon the application provides for a given MIME type and + puts it into a BBitmap. + + \note If \a type is \c NULL, the application's icon is retrieved. + + \param type The MIME type in question. May be \c NULL. + \param icon A pointer to a pre-allocated BBitmap of the correct dimension + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). + \param size Specifies the size of the icon to be retrieved: + \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size + \a which or bitmap dimensions (\a icon) and icon size (\a which) do + not match. +*/ + + +/*! + \fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data, + size_t* size) const + \brief Gets the icon the application provides for a given MIME type and + puts it into a buffer. + + \note If \a type is set to \c NULL the the application's icon is retrieved. + + \param type The MIME type in question. May be \c NULL. + \param data A pointer in which the icon data will be returned. When you + are done with the data, you should use free() to deallocate it. + \param size A pointer in which the size of the retrieved data is returned. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied + \a type is not a valid MIME type. +*/ + + +/*! + \fn status_t BAppFileInfo::SetIconForType(const char* type, + const BBitmap* icon, icon_size which) + \brief Sets the icon the application provides for a given MIME type from a + BBitmap. + + \note If \a type is \c NULL then the icon is set. + \note If \a icon is \c NULL then the icon is unset. + + If the file has a signature, then the icon is also set on the MIME type. + If the type for the signature has not been installed yet, it is installed + before. + + \param type The MIME type in question. May be \c NULL. + \param icon A pointer to the BBitmap containing the icon to be set. + May be \c NULL. + \param which Specifies the size of the icon to be set: \c B_MINI_ICON + for the mini and \c B_LARGE_ICON for the large icon. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE Either the icon size \a which is unknown, + the bitmap dimensions (\a icon) and icon size (\a which) do not + match, or the provided \a type is not a valid MIME type. +*/ + + +/*! + \fn status_t BAppFileInfo::SetIconForType(const char* type, + const uint8* data, size_t size) + \brief Sets the icon the application provides for a given MIME type from a + buffer. + + \note If \a type is \c NULL then the icon is set. + \note If \a data is \c NULL then the icon is unset. + + If the file has a signature, then the icon is also set on the MIME type. + If the type for the signature has not been installed yet, it is + installed before. + + \param type The MIME type in question. May be \c NULL. + \param data A pointer to the data containing the icon to be set. + May be \c NULL. + \param size Specifies the size of buffer provided in \a data. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE The provided \a type is not a valid MIME type. +*/ + + +//! @} + + +/*! + \name Version Info +*/ + + +//! @{ + + +/*! + \fn status_t BAppFileInfo::GetVersionInfo(version_info* info, + version_kind kind) const + \brief Gets the version info of the associated file. + + \param info A pointer to a pre-allocated version_info structure into + which the version info should be written. + \param kind Specifies the kind of the version info to be retrieved: + - \c B_APP_VERSION_KIND for the application's version info and + - \c B_SYSTEM_VERSION_KIND for the suite's info the application + belongs to. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. + \retval B_BAD_VALUE \c NULL \a info. +*/ + + +/*! + \fn status_t BAppFileInfo::SetVersionInfo(const version_info* info, + version_kind kind) + \brief Sets the version info of the associated file. + + \note If \a info is set to \c NULL then the file's version info is unset. + + \param info The version info to be set. May be \c NULL. + \param kind Specifies kind of version info to be set: + - \c B_APP_VERSION_KIND for the application's version info and + - \c B_SYSTEM_VERSION_KIND for the suite's info the application + belongs to. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT The object is not properly initialized. +*/ + + +//! @} + + +/*! + \name Attributes/Resources +*/ + + +//! @{ + + +/*! + \fn void BAppFileInfo::SetInfoLocation(info_location location) + \brief Specifies the location where the metadata shall be stored. + + The options for \a location are: + - \c B_USE_ATTRIBUTES: Store the data in the attributes. + - \c B_USE_RESOURCES: Store the data in the resources. + - \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources. + + \param location The location where the metadata shall be stored. +*/ + + +/*! + \fn bool BAppFileInfo::IsUsingAttributes() const + \brief Returns whether the object (also) stores the metadata in the + attributes of the associated file. + + \returns \c true if the metadata are (also) stored in the file's + attributes, \c false otherwise. +*/ + + +/*! + \fn bool BAppFileInfo::IsUsingResources() const + \brief Returns whether the object (also) stores the metadata in the + resources of the associated file. + + \returns \c true if the metadata are (also) stored in the file's + resources, \c false otherwise. +*/ + + +//! @} + + +/*! + \fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &) + \brief Privatized assignment operator to prevent usage. +*/ + + +/*! + \fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &) + \brief Privatized copy constructor to prevent usage. +*/ + + +/*! + \fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const + \brief Initializes a BMimeType to the signature of the associated file. + + \warning The parameter \a meta is not checked. + + \param meta A pointer to a pre-allocated BMimeType that shall be + initialized to the signature of the associated file. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \c NULL \a meta + \retval B_ENTRY_NOT_FOUND The file has not signature or the signature is + (not installed in the MIME database.) no valid MIME string. +*/ + + +/*! + \fn status_t BAppFileInfo::_ReadData(const char* name, int32 id, + type_code type, void* buffer, size_t bufferSize, + size_t &bytesRead, void** allocatedBuffer) const + \brief Reads data from an attribute or resource. + + \note The data is read from the location specified by \a fWhere. + + \warning The object must be properly initialized. The parameters are + \b NOT checked. + + \param name The name of the attribute/resource to be read. + \param id The resource ID of the resource to be read. It is ignored + when < 0. + \param type The type of the attribute/resource to be read. + \param buffer A pre-allocated buffer for the data to be read. + \param bufferSize The size of the supplied buffer. + \param bytesRead A reference parameter, set to the number of bytes + actually read. + \param allocatedBuffer If not \c NULL, the method allocates a buffer + large enough too store the whole data and writes a pointer to it + into this variable. If \c NULL, the supplied buffer is used. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ENTRY_NOT_FOUND The entry was not found. + \retval B_NO_MEMORY Ran out of memory allocating the buffer. + \retval B_BAD_VALUE \a type did not match. +*/ + + +/*! + \fn status_t BAppFileInfo::_WriteData(const char* name, int32 id, + type_code type, const void* buffer, size_t bufferSize, bool findID) + \brief Writes data to an attribute or resource. + + \note The data is written to the location(s) specified by \a fWhere. + + \warning The object must be properly initialized. The parameters are + \b NOT checked. + + \param name The name of the attribute/resource to be written. + \param id The resource ID of the resource to be written. + \param type The type of the attribute/resource to be written. + \param buffer A buffer containing the data to be written. + \param bufferSize The size of the supplied buffer. + \param findID If set to \c true use the ID that is already assigned to the + \a name / \a type pair or take the first unused ID >= \a id. + If \c false, \a id is used. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_ERROR An error occurred while trying to write the data. +*/ + + +/*! + \fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type) + \brief Removes an attribute or resource. + + \note The removal location is specified by \a fWhere. + + \warning The object must be properly initialized. The parameters are + \b NOT checked. + + \param name The name of the attribute/resource to be remove. + \param type The type of the attribute/resource to be removed. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_NO_INIT Not using attributes and not using resources. + \retval B_ENTRY_NOT_FOUND The attribute or resource was not found. +*/ diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox index f2b01a76d0..b47ce04c8d 100644 --- a/docs/user/support/Archivable.dox +++ b/docs/user/support/Archivable.dox @@ -16,15 +16,13 @@ */ -/*! - \file Archivable.h +/*! \file Archivable.h \brief Provides the BArchivable interface and declares the BArchiver and BUnarchiver classes. */ -/*! - \class BArchivable +/*! \class BArchivable \ingroup support \ingroup libbe \brief Interface for objects that can be archived into a BMessage. @@ -65,8 +63,7 @@ */ -/*! - \fn BArchivable::BArchivable(BMessage* from) +/*! \fn BArchivable::BArchivable(BMessage* from) \brief Constructor. Does important behind-the-scenes work in the unarchiving process. @@ -77,20 +74,17 @@ */ -/*! - \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. @@ -105,8 +99,7 @@ */ -/*! - \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 @@ -127,17 +120,15 @@ */ -/*! - \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) - \brief Internal method. +/*! \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) + \brief 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. */ -/*! - \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. @@ -146,32 +137,31 @@ Implementations of this method should call the implementation of their parent class, the same as for the Archive() method. - \note To guarantee that your AllUnarchived() method will be called during - unarchival, you must create a BUnarchiver object in your archive - constructor. + \warning To guarantee that your AllUnarchived() method will be called + during unarchival, you must create a BUnarchiver object in your + archive constructor. \see BUnarchiver, BUnarchiver::Finish() */ -/*! - \fn virtual status_t BArchivable::AllArchived(BMessage* into) const +/*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const \brief Method relating to the use of \c BArchiver. This hook function is called once the first BArchiver that was created in - an archiving session is either destroyed, or has its \c Finish() method + an archiving session is either destroyed, or has its Finish() method called. Implementations of this method can be used, in conjunction with BArchiver::IsArchived(), to reference objects in your archive that you do not own, depending on whether or not those objects were archived by their owners. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method. - \note To guarantee that your AllArchived() method will be called during - archival, you must create a BArchiver object in your Archive() - implementation. + \warning To guarantee that your AllArchived() method will be called + during archival, you must create a BArchiver object in your + Archive() implementation. - \note You should archive any objects you own in your Archive() method - implementation, \b NOT your AllArchived() method. + \warning You should archive any objects you own in your Archive() + method implementation, and \b NOT your AllArchived() method. \see BArchiver BArchiver::Finish() */ @@ -184,15 +174,13 @@ */ -/*! - \typedef typedef BArchivable* (*instantiation_func)(BMessage*) +/*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*) \brief Internal definition of a function that can instantiate objects that have been created with the BArchivable API. */ -/*! - \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. @@ -206,8 +194,7 @@ */ -/*! - \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 @@ -222,30 +209,26 @@ */ -/*! - \fn bool validate_instantiation(BMessage* from, const char* className) +/*! \fn bool validate_instantiation(BMessage* from, const char* className) \brief Internal function that checks if the \a className is the same as the one stored in the \a from message. */ -/*! - \fn instantiation_func find_instantiation_func(const char* className, +/*! \fn instantiation_func find_instantiation_func(const char* className, const char* signature) \brief Internal function that searches for the instantiation func with a specific signature. Use instantiate_object() instead. */ -/*! - \fn instantiation_func find_instantiation_func(const char* className) +/*! \fn instantiation_func find_instantiation_func(const char* className) \brief Internal function that searches for the instantiation func of a specific class. Use instantiate_object() instead. */ -/*! - \fn instantiation_func find_instantiation_func(BMessage* archive) +/*! \fn instantiation_func find_instantiation_func(BMessage* archive) \brief Internal function that searches for the instantiation func that works on the specified \a archive. Use instantiate_object() instead. */ diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox index a33895133a..c4a30c35ca 100644 --- a/docs/user/support/Beep.dox +++ b/docs/user/support/Beep.dox @@ -13,7 +13,7 @@ ///// and not completely implemented, so this needs revision if everything ///// is finished. - /*! +/*! \file Beep.h \brief Functions to generate sounds from the computer. */ @@ -24,34 +24,31 @@ //! @{ -/*! - \fn status_t beep() - \brief Invoke the standard system beep to alert users. +/*! \fn status_t beep() + \brief Invoke the standard system beep to alert users. - From Beep.h and in libbe.so. - - \see system_beep() and add_system_beep_event() + From Beep.h and in libbe.so. + + \see system_beep() and add_system_beep_event() */ -/*! - \fn status_t system_beep(const char* eventName) - \brief Invokes the sound for event \a eventName. - - You can add the events using add_system_beep_event(). +/*! \fn status_t system_beep(const char* eventName) + \brief Invokes the sound for event \a eventName. - From Beep.h and in libbe.so. + You can add the events using add_system_beep_event(). + + From Beep.h and in libbe.so. */ -/*! - \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0) - \brief Adds an event to the media server. - - Call this method to add a specific event to the media server. +/*! \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0) + \brief Adds an event to the media server. - From Beep.h and in libbe.so. - - \param eventName The name of the event. - \param flags Currently unused. Pass \c 0. + Call this method to add a specific event to the media server. + + From Beep.h and in libbe.so. + + \param eventName The name of the event. + \param flags Currently unused. Pass \c 0. */ -//! @} \ No newline at end of file +//! @} diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index 645129c70a..75deacb4d3 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -26,7 +26,7 @@ \class BList \ingroup support \ingroup libbe - \brief An ordered container that is designed to hold generic \c void * + \brief An ordered container that is designed to hold generic \c void* objects. This class is designed to be used for a variety of tasks. Unlike similar @@ -399,7 +399,7 @@ A C D E F G B H I J If one of the actions on the items fails it means that the \a func function returned \c false and the processing of the list will be stopped. - \param func A function that takes a \c void * argument and returns a + \param func A function that takes a \c void* argument and returns a boolean. \see DoForEach(bool (*func)(void* item, void* arg2), void *arg2) */ @@ -412,8 +412,8 @@ A C D E F G B H I J If one of the actions on the items fails it means that the \a func function returned \c false and the processing of the list will be stopped. - \param func A function with the first \c void * argument being the item - and the second \c void * being the argument that you supply. It should + \param func A function with the first \c void* argument being the item + and the second \c void* being the argument that you supply. It should return a boolean value on whether it succeeded or not. \param arg2 An argument to supply to \a func. \see DoForEach(bool (*func)(void* item)) diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox index 3adaeb2ff3..104e600d9c 100644 --- a/docs/user/support/SupportDefs.dox +++ b/docs/user/support/SupportDefs.dox @@ -21,7 +21,7 @@ //! @{ /*! - \typedef typedef __haiku_int8 int8 + \typedef typedef __haiku_int8 int8 */ /*! @@ -29,7 +29,7 @@ */ /*! - \typedef typedef __haiku_int16 int16 + \typedef typedef __haiku_int16 int16 */ /*! @@ -37,7 +37,7 @@ */ /*! - \typedef typedef __haiku_int32 int32 + \typedef typedef __haiku_int32 int32 */ /*! @@ -45,7 +45,7 @@ */ /*! - \typedef typedef __haiku_int64 int64 + \typedef typedef __haiku_int64 int64 */ /*! @@ -137,9 +137,7 @@ //! @} -/*! - \name Character Type Formats -*/ +/*! \name Character Type Formats */ //! @{ @@ -153,20 +151,18 @@ //! @} -/*! - \name Descriptive Type Formats -*/ +/*! \name Descriptive Type Formats */ //! @{ /*! - \typedef typedef int32 status_t - \brief Represents one of the status codes defined in Error.h + \typedef typedef int32 status_t + \brief Represents one of the status codes defined in Error.h */ /*! - \typedef typedef int64 bigtime_t - \brief Represents time. The unit depends on the context of the function. + \typedef typedef int64 bigtime_t + \brief Represents time. The unit depends on the context of the function. */ /*! @@ -175,23 +171,21 @@ */ /*! - \typedef typedef uint32 type_code - \brief Represents a certain type of data. See TypeConstants.h for possible - values. + \typedef typedef uint32 type_code + \brief Represents a certain type of data. See TypeConstants.h for + possible values. */ /*! - \typedef typedef uint32 perform_code - \brief Unused. Defined by Be to support 'hidden' commands or - extensions to classes. The Haiku API has none of these. + \typedef typedef uint32 perform_code + \brief Unused. Defined by Be to support 'hidden' commands or + extensions to classes. The Haiku API has none of these. */ //! @} -/*! - \name Format strings for printf()/scanf() -*/ +/*! \name Format strings for printf()/scanf() */ //! @{ @@ -374,9 +368,7 @@ //! @} -/*! - \name Format strings for several standard types -*/ +/*! \name Format strings for several standard types */ //! @{ @@ -474,41 +466,35 @@ //////////////// Odds and ends -/*! - \var const char *B_EMPTY_STRING - \brief Defines an empty string. Currently defined as the C-string "". +/*! \var const char *B_EMPTY_STRING + \brief Defines an empty string. Currently defined as the string "". */ -/*! - \def min_c(a,b) - \brief Returns the minimum of the values a and b. +/*! \def min_c(a,b) + \brief Returns the minimum of the values a and b. - \note When including this header in a C file, use the C equivalent called - \c min(a,b). + \note When including this header in a C file, use the C equivalent called + \c min(a,b). */ -/*! - \def max_c(a,b) - \brief Returns the maximum of values a and b. +/*! \def max_c(a,b) + \brief Returns the maximum of values a and b. - \note When including this header in a C file, use the C equivalent called - \c max(a,b). + \note When including this header in a C file, use the C equivalent called + \c max(a,b). */ -/*! - \def NULL - \brief Defines the constant \c NULL if it hasn't been defined anywhere before. +/*! \def NULL + \brief Defines the constant \c NULL if it hasn't been defined + anywhere before. */ -/*! - \addtogroup support_globals -*/ +/*! \addtogroup support_globals */ //! @{ -/*! - \fn int32 atomic_set(vint32 *value, int32 newValue) - \brief Atomically set the variable \a value to \a newvalue. +/*! \fn int32 atomic_set(vint32 *value, int32 newValue) + \brief Atomically set the variable \a value to \a newvalue. This is a thread-safe way of performing the \c *value \c = \c newValue operation. You should use these function when two or more threads might @@ -518,29 +504,28 @@ \return The original value of \c value. \sa atomic_set64() for a version that works on \c long \c long - \sa atomic_test_and_set(), atomic_add(), atomic_and(), - atomic_or(), atomic_get() + \sa atomic_test_and_set(), atomic_add(), atomic_and(), atomic_or(), + atomic_get() */ -/*! - \fn int32 atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst) - \brief Atomically set the variable \a value to \a newValue if the current +/*! \fn int32 atomic_test_and_set(vint32 *value, int32 newValue, + int32 testAgainst) + \brief Atomically set the variable \a value to \a newValue if the current value is \a testAgainst. This is a thread-safe way of conditionally performing the \c *value \c += - \c newValue operation. You should use these function when two or more threads - might access the variable simultaneously. You don't have to use a semaphore - or a mutex in this case. + \c newValue operation. You should use these function when two or more + threads might access the variable simultaneously. You don't have to use + a semaphore or a mutex in this case. \return The original value of \c value. - \sa atomic_test_and_set64() for a version that works on \c long \c long - \sa atomic_set(), atomic_add(), atomic_and(), - atomic_or(), atomic_get() + + \sa atomic_test_and_set64() for a version that works on \c long \c long + \sa atomic_set(), atomic_add(), atomic_and(), atomic_or(), atomic_get() */ -/*! - \fn int32 atomic_add(vint32 *value, int32 addValue) - \brief Atomically add the value of \a addValue to \a value. +/*! \fn int32 atomic_add(vint32 *value, int32 addValue) + \brief Atomically add the value of \a addValue to \a value. This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might @@ -548,14 +533,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_add64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_and(), - atomic_or(), atomic_get() + + \sa atomic_add64() for a version that works on \c long \c long + \sa atomic_set(), atomic_test_and_set(), atomic_and(), atomic_or(), + atomic_get() */ -/*! - \fn int32 atomic_and(vint32 *value, int32 andValue) - \brief Atomically perform a bitwise AND operation of \a andValue to the +/*! \fn int32 atomic_and(vint32 *value, int32 andValue) + \brief Atomically perform a bitwise AND operation of \a andValue to the variable \a andValue. This is a thread-safe way of performing the \c *value \c &= \c andValue @@ -564,15 +549,15 @@ mutex in this case. \return The original value of \c value. - \sa atomic_and64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), - atomic_or(), atomic_get() + + \sa atomic_and64() for a version that works on \c long \c long + \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_or(), + atomic_get() */ -/*! - \fn int32 atomic_or(vint32 *value, int32 orValue) - \brief Atomically perform a bitwise OR operation of \a orValue to the +/*! \fn int32 atomic_or(vint32 *value, int32 orValue) + \brief Atomically perform a bitwise OR operation of \a orValue to the variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue @@ -581,14 +566,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_or64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), - atomic_get() + + \sa atomic_or64() for a version that works on \c long \c long + \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), + atomic_get() */ -/*! - \fn int32 atomic_get(vint32 *value) - \brief Atomically return the value of \c value. +/*! \fn int32 atomic_get(vint32 *value) + \brief Atomically return the value of \c value. This is a thread-safe way of reading the contents of the \c value operation. You should use these function when two or more threads might @@ -596,14 +581,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_get64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), - atomic_or() + + \sa atomic_get64() for a version that works on \c long \c long + \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), + atomic_or() */ -/*! - \fn int64 atomic_set64(vint64 *value, int64 newValue) - \brief Atomically set the variable \a value to \a newvalue. +/*! \fn int64 atomic_set64(vint64 *value, int64 newValue) + \brief Atomically set the variable \a value to \a newvalue. This is a thread-safe way of performing the \c *value \c = \c newValue operation. You should use these function when two or more threads might @@ -612,30 +597,30 @@ \return The original value of \c value. - \sa atomic_set() for a version that works on an \c int32 - \sa atomic_test_and_set64(), atomic_add64(), atomic_and64(), - atomic_or64(), atomic_get64() + \sa atomic_set() for a version that works on an \c int32 + \sa atomic_test_and_set64(), atomic_add64(), atomic_and64(), + atomic_or64(), atomic_get64() */ -/*! - \fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst) - \brief Atomically set the variable \a value to \a newValue if the current +/*! \fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, + int64 testAgainst) + \brief Atomically set the variable \a value to \a newValue if the current value is \a testAgainst. - This is a thread-safe way of conditionally performing the \c *value \c += - \c newValue operation. You should use these function when two or more threads - might access the variable simultaneously. You don't have to use a semaphore - or a mutex in this case. - + This is a thread-safe way of conditionally performing the \c *value + \c += \c newValue operation. You should use these function when two + or more threads might access the variable simultaneously. You don't + have to use a semaphore or a mutex in this case. + \return The original value of \c value. - \sa atomic_test_and_set() for a version that works on an \c int32 - \sa atomic_set64(), atomic_add64(), atomic_and64(), - atomic_or64(), atomic_get64() + + \sa atomic_test_and_set() for a version that works on an \c int32 + \sa atomic_set64(), atomic_add64(), atomic_and64(), + atomic_or64(), atomic_get64() */ -/*! - \fn int64 atomic_add64(vint64 *value, int64 addValue) - \brief Atomically add the value of \a addValue to \a value. +/*! \fn int64 atomic_add64(vint64 *value, int64 addValue) + \brief Atomically add the value of \a addValue to \a value. This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might @@ -643,14 +628,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_add() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_and64(), - atomic_or64(), atomic_get64() + + \sa atomic_add() for a version that works on an \c int32 + \sa atomic_set64(), atomic_test_and_set64(), atomic_and64(), + atomic_or64(), atomic_get64() */ -/*! - \fn int64 atomic_and64(vint64 *value, int64 andValue) - \brief Atomically perform a bitwise AND operation of \a andValue to the +/*! \fn int64 atomic_and64(vint64 *value, int64 andValue) + \brief Atomically perform a bitwise AND operation of \a andValue to the variable \a andValue. This is a thread-safe way of performing the \c *value \c &= \c andValue @@ -659,14 +644,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_and() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), - atomic_or64(), atomic_get64() + + \sa atomic_and() for a version that works on an \c int32 + \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), + atomic_or64(), atomic_get64() */ -/*! - \fn int64 atomic_or64(vint64 *value, int64 orValue) - \brief Atomically perform a bitwise OR operation of \a orValue to the +/*! \fn int64 atomic_or64(vint64 *value, int64 orValue) + \brief Atomically perform a bitwise OR operation of \a orValue to the variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue @@ -675,14 +660,14 @@ mutex in this case. \return The original value of \c value. - \sa atomic_or() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), - atomic_get64() + + \sa atomic_or() for a version that works on an \c int32 + \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), + atomic_get64() */ -/*! - \fn int64 atomic_get64(vint64 *value) - \brief Atomically return the value of \c value. +/*! \fn int64 atomic_get64(vint64 *value) + \brief Atomically return the value of \c value. This is a thread-safe way of reading the contents of the \c value operation. You should use these function when two or more threads might @@ -690,33 +675,30 @@ mutex in this case. \return The original value of \c value. - \sa atomic_get() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), - atomic_or64() + + \sa atomic_get() for a version that works on an \c int32 + \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), + atomic_and64(), atomic_or64() */ //! @} -/*! - \fn void* get_stack_frame(void) +/*! \fn void* get_stack_frame(void) \brief Internal function. \internal */ -/*! - \name Deprecated defines -*/ +/*! \name Deprecated defines */ //! @{ -/*! - \def FALSE - \brief Obsolete. Use \c false. +/*! \def FALSE + \brief Obsolete. Use \c false. */ -/*! - \def TRUE - \brief Obsolete. Use \c true. +/*! \def TRUE + \brief Obsolete. Use \c true. */ //! @} + diff --git a/docs/user/support/Unarchiver.dox b/docs/user/support/Unarchiver.dox index de6b6b26d7..1eca4db9e9 100644 --- a/docs/user/support/Unarchiver.dox +++ b/docs/user/support/Unarchiver.dox @@ -11,12 +11,11 @@ */ -/*! -\class BUnarchiver -\ingroup support -\ingroup libbe -\brief A class that simplifies the unarchiving of complicated BArchivable - hierarchies. +/*! \class BUnarchiver + \ingroup support + \ingroup libbe + \brief A class that simplifies the unarchiving of complicated BArchivable + hierarchies. The BUnarchiver class is a small class used to recover BArchivable objects that have been archived with the BArchiver class. It also provides ownership @@ -40,8 +39,7 @@ */ -/*! - \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 @@ -57,74 +55,87 @@ */ -/*! - \fn BUnarchiver::~BUnarchiver() - \brief Destroys a BUnarchiver object. Calls this objects Finish() method, - if it has not yet been called. +/*! \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) - \brief Ensure the object represented by \c token is unarchived and +/*! \fn status_t BUnarchiver::EnsureUnarchived(int32 token) + \brief Ensure the object represented by \a token is unarchived and instantiated. + + \param token the object \a token */ -/*! - \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 \c name at \c index is unarchived + \brief Ensure the object archived under \a name at \a index is unarchived and instantiated. + + \param name The archive \a name. + \param index The archive \a index. */ -/*! - \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. + + \param token The object \a token */ -/*! - \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0) - \brief Checks whether the object archived under \c name at \c index has been +/*! \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. + + \param name The archive \a name. + \param index The arcive \a token. */ -/*! - \fn template status_t BUnarchiver::GetObject(int32 token, +/*! \fn template status_t BUnarchiver::GetObject(int32 token, ownership_policy owning, T*& object) \brief Recover an object by token that was archived by a BArchiver object. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now. - If the retrieved object is not of the type \c T, then this method will fail. + 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 matter what you specified in \c owning. - \tparam T The type of object you wish to find. + \tparam T The type of \a object you wish to find. - \param token The token you got for this object from + \param token The \a token you got for this object from BArchiver::GetTokenForArchivable() during archival. \param owning Whether or not you wish to take ownership of the retrieved object. - \param object Return parameter for the retrieved object of type \c T. + \param object Return parameter for the retrieved object of type T. - \retval B_BAD_TYPE The object retrieved was not of type \c T. + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ -/*! - \fn template status_t BUnarchiver::GetObject(int32 token, +/*! \fn template status_t BUnarchiver::GetObject(int32 token, T*& object) - \brief Recover and take ownership of an object represented by \c token. + \brief Recover and take ownership of an object represented by \a token. - Equivalent to calling GetObject(token, BUnarchiver::B_ASSUME_OWNERSHIP, - object) + Equivalent to calling GetObject(token, \c B_ASSUME_OWNERSHIP, object) + + \tparam T The type of \a object you wish to find. + + \param token The \a token you got for this object from + BArchiver::GetTokenForArchivable() during archival. + \param object The return parameter for the retrieved object of type T. + + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -137,7 +148,7 @@ 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 \c T, then this method will fail. + 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 matter what you specified in \c owning. @@ -145,61 +156,90 @@ \param name The name that was passed to BArchiver::AddArchivable() when adding this object. - \param index The index of the object you wish to recover (0 based, like - BMessage::FindData(). + \param index The index of the object you wish to recover (\c 0-based, + like BMessage::FindData(). \param owning Dictates whether or not you wish to take ownership of the retrieved object. - \param object Return parameter for the retrieved object of type \c T. + \param object Return parameter for the retrieved object of type T. - \retval B_BAD_TYPE The object retrieved was not of type \c T. + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ -/*! - \fn template status_t BUnarchiver::FindObject(const char* name, +/*! \fn template status_t BUnarchiver::FindObject(const char* name, int32 index, T*& object) \brief Recover and take ownership of an object that had previously been archived using the BArchiver::AddArchivable() method. + + \tparam T The type of object you wish to find. + + \param name The name that was passed to BArchiver::AddArchivable() when + adding this object. + \param index The index of the object you wish to recover (\c 0-based, + like #BMessage::FindData(). + \param object Return parameter for the retrieved object of type T. + + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ -/*! - \fn template status_t BUnarchiver::FindObject(const char* name, +/*! \fn template status_t BUnarchiver::FindObject(const char* name, ownership_policy owning, T*& object) - \brief Recover an object at index 0 that had previously been archived using - the BArchiver::AddArchivable() method. + \brief Recover an object at index \c 0 that had previously been + archived using the BArchiver::AddArchivable() method. - Equivalent to calling FindObject(name, 0, owning, object). + Equivalent to calling FindObject(name, \c 0, owning, object). + + \tparam T The type of \a object you wish to find. + + \param name The name that was passed to BArchiver::AddArchivable() when + adding this object. + \param owning Dictates whether or not you wish to take ownership of the + retrieved object. + \param object Return parameter for the retrieved object of type T. + + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ -/*! - \fn template status_t BUnarchiver::FindObject(const char* name, +/*! \fn template status_t BUnarchiver::FindObject(const char* name, T*& object) - \brief Recover and take ownership of an object at index 0 that had + \brief Recover and take ownership of an object at index \c 0 that had previously been archived using the BArchiver::AddArchivable() method. - Equivalent to calling FindObject(name, 0, BUnarchiver::B_ASSUME_OWNERSHIP, - object). + Equivalent to calling FindObject(name, \c 0, + BUnarchiver::B_ASSUME_OWNERSHIP, object). + + \tparam T The type of \a object you wish to find. + + \param name The name that was passed to BArchiver::AddArchivable() when + adding this object. + \param object Return parameter for the retrieved \a object of type T. + + \retval B_OK The \a object retrieved was of type T. + \retval B_BAD_TYPE The \a object retrieved was not of type T. */ -/*! - \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. - \return The first error reported in this unarchiving session, or B_OK. This method may finish an unarchiving session (triggering the call of all instantiated objects' AllUnarchived() methods) if the following conditions are true: - \li No errors have been reported to this or any other BUnarchiver object - within this session. - \li This is the last remaining BUnarchiver that has not had its Finish() - method invoked. + + \li No errors have been reported to this or any other BUnarchiver + object within this session. + \li This is the last remaining BUnarchiver that has not had its + Finish() method invoked. + If you call this method with an error code not equal to B_OK, then this unarchiving session has failed, instantiated objects will not have their AllUnarchived() methods called, and any subsequent calls to this method @@ -207,22 +247,22 @@ Furthermore, any objects that have been instantiated, but have not had their ownership assumed by another object will now be deleted (excluding the root object). + + \return The first error reported in this unarchiving session, or \c B_OK. */ /*! \fn const BMessage* BUnarchiver::ArchiveMessage() const - \brief Returns the BMessage* used to construct this BUnarchiver. This is - the archive that FindObject() uses. + \brief Returns the BMessage* used to construct this BUnarchiver. + + This is the archive that FindObject() uses. */ -/*! - \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive) +/*! \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive) - \brief Checks whether \c archive was managed by a BArchiver object. - \retval true if \c archive was managed by a BArchiver object. - \retval false otherwise. + \brief Checks whether \a archive was managed by a BArchiver object. This method can be used to maintain archive backwards-compatibility for a class that has been updated to use the BArchiver class. If there is a @@ -231,7 +271,7 @@ object. Here is an example of how you might use this method. Note that you - must still call BUnarchiver::PrepareArchive(archive), either way. + must still call PrepareArchive(archive) either way. \code MyArchivableClas::MyArchivableClass(BMessage* archive) @@ -247,14 +287,14 @@ MyArchivableClas::MyArchivableClass(BMessage* archive) } } \endcode + + \retval true if \a archive was managed by a BArchiver object. + \retval false otherwise. */ -/*! - \fn static BMessage* BUnarchiver::PrepareArchive(BMessage*& archive) +/*! \fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive) \brief Prepares \c archive for use by a BUnarchiver. - \param archive The archive you wish to have prepared. - \return The same BMessage as is passed in. This method must be called if you plan to use a BUnarchiver on an archive. It must be called once for each class an object inherits from that @@ -272,33 +312,45 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) // ... } \endcode + + \param archive The archive you wish to have prepared. + + \return The same #BMessage as is passed in. */ -/*! - \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable) - \brief Become the owner of \c archivable. +/*! \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable) + \brief Become the owner of \a archivable. - After calling this method, you are responsible for the deletion - of \c archivable. + After calling this method you are responsible for deleting the + \a archivable. + + \param archivable The \a archivable object. */ -/*! - \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable) - \brief Relinquish ownership of \c archivable. If \c archivable remains +/*! \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). + + \param archivable The \a archivable object. */ -/*! - \fn template status_t BUnarchiver::InstantiateObject( +/*! \fn template status_t BUnarchiver::InstantiateObject( BMessage* from, T*& object) - \brief Attempt to instantiate an object of type \c T from BMessage* \c from. + \brief Attempt to instantiate an object of type T from BMessage* + \a from. - If the instantiated object is not of type \c T, then it will be deleted, + If the instantiated object is not of type T, then it will be deleted, and this method will return \c B_BAD_TYPE. This method is similar to the instantiate_object() function, but provides error reporting and protection from memory leaks. + + \param from The #BMessage to instantiate from. + \param object Return parameter for the retrieved object of type T. + + \retval B_OK The object retrieved was of type T. + \retval B_BAD_TYPE The object retrieved was not of type T. */ diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox index 066dfb8603..ac935cd794 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/string.dox @@ -10,1411 +10,1792 @@ */ /*! -\file String.h -\brief Defines the BString class and global operators and functions for handling strings. + \file String.h + \brief Defines the BString class and global operators and functions for + handling strings. */ /*! -\class BString String.h -\ingroup support -\ingroup libbe -\brief String class supporting common string operations. + \class BString String.h + \ingroup support + \ingroup libbe + \brief String class supporting common string operations. -BString is a string allocation and manipulation class. The object -takes care to allocate and free memory for you, so it will always be -"big enough" to store your strings. - -\author Marc Flerackers \ -\author Stefano Ceccherini \ -\author Oliver Tappe \ + BString is a string allocation and manipulation class. The object + takes care to allocate and free memory for you, so it will always be + "big enough" to store your strings. + + \author Marc Flerackers \ + \author Stefano Ceccherini \ + \author Oliver Tappe \ */ /*! -\var char* BString::fPrivateData -\brief BString's storage for data. + \var char* BString::fPrivateData + \brief BString's storage for data. -This member is deprecated and might even go \c private in future releases. + This member is deprecated and might even go \c private in future releases. -If you are planning to derive from this object and you want to manipulate the raw -string data, please have a look at LockBuffer() and UnlockBuffer(). + If you are planning to derive from this object and you want to manipulate + the raw string data, please have a look at LockBuffer() and UnlockBuffer(). */ /*! -\fn BString::BString() -\brief Create an uninitialized BString. + \fn BString::BString() + \brief Creates an empty BString. */ /*! -\fn BString::BString(const char* str) -\brief Create a BString and initializes it to the given string. -\param str Pointer to a NULL terminated string. + \fn BString::BString(const char* string) + \brief Creates and initializes a BString from a \a string. */ /*! -\fn BString::BString(const BString &string) -\brief Create a BString and makes it a copy of the supplied one. -\param string the BString object to be copied. + \fn BString::BString(const BString &string) + \brief Creates and initializes a BString from another BString. */ /*! -\fn BString::BString(const char *str, int32 maxLength) -\brief Create a BString and initializes it to the given string. -\param str Pointer to a NULL terminated string. -\param maxLength The amount of characters you want to copy from the original -string. + \fn BString::BString(const char *string, int32 maxLength) + \brief Creates and initializes a BString from a \a string up to + \a maxLength characters. + + If \a maxLength is greater than the length of the source \a string then the + entire source \a string is copied. If \a maxLength is less than or equal + to 0 then the result is an empty BString. + + \warning In BeOS R5 passing in a negative \a maxLength argument will copy + the entire \a string. */ /*! -\fn BString::~BString() -\brief Free all resources associated with the object. - -The destructor frees the internal buffer associated with the string. + \fn BString::~BString() + \brief Free all resources associated with the object. + + The destructor also frees the internal buffer associated with the string. */ -/*! -\name Access Methods +/*! + \name Access Methods */ //! @{ /*! -\fn const char* BString::String() const -\brief Return a pointer to the object string, NULL terminated. + \fn const char* BString::String() const + \brief Return a pointer to the object string, \c NUL terminated. -The pointer to the object string is guaranteed to be NULL -terminated. You can't modify or free the pointer. Once the BString -object is deleted, the pointer becomes invalid. + The pointer to the object string is guaranteed to be \c NUL + terminated. You can't modify or free the pointer. Once the BString + object is deleted, the pointer becomes invalid. -If you want to manipulate the internal C-string of the object directly, have -a look at LockBuffer(). - -\return A pointer to the object string. + If you want to manipulate the internal string of the object directly, + have a look at LockBuffer(). + + \return A pointer to the object string. */ /*! -\fn int32 BString::Length() const -\brief Get the length of the string in bytes. + \fn int32 BString::Length() const + \brief Get the length of the string in bytes. -\return An integer with the length of the string, measured in bytes. -\sa CountChars() + \return An integer with the length of the string, measured in bytes. + \sa CountChars() */ /*! -\fn int32 BString::CountChars() const -\brief Returns the length of the object measured in characters. - -BString is somewhat aware of UTF8 characters, so this method will count -the actual number of characters in the string. + \fn int32 BString::CountChars() const + \brief Returns the length of the object measured in characters. + + BString is somewhat aware of UTF8 characters, so this method will count + the actual number of characters in the string. -\return An integer which is the number of characters in the string. -\sa Length() + \return An integer which is the number of characters in the string. + \sa Length() */ //! @} /*! -\name Assignment Methods + \name Assignment Methods -To assign a string to the object, thus overriding the previous string -that was stored, there are different methods to use. Use one of the -overloaded Adopt() methods to take over data from another object. Use -one of the assignment operators to copy data from another object, or -use one of the SetTo() methods for more advanced copying. + To assign a string to the object, thus overriding the previous string + that was stored, there are different methods to use. Use one of the + overloaded Adopt() methods to take over data from another object. Use + one of the assignment operators to copy data from another object, or + use one of the SetTo() methods for more advanced copying. */ //! @{ /*! -\fn BString& BString::operator=(const BString &string) -\brief Re-initialize the object to a copy of the data of a BString. -\param string The string object to copy. -\return The function always returns \c *this . -\sa Adopt(BString &from) -\sa SetTo(const BString &string, int32 length) + \fn BString& BString::operator=(const BString &string) + \brief Re-initialize the object to a copy of the data of a BString. + + \param string The string object to copy. + + \return The function always returns \c *this . + + \sa Adopt(BString &from) + \sa SetTo(const BString &string, int32 length) */ /*! -\fn BString& BString::operator=(const char *str) -\brief Re-initialize the object to a copy of the data of a C-string. -\param str Pointer to a C-string. -\return The function always returns \c *this . -\sa SetTo(const char *str, int32 maxLength) + \fn BString& BString::operator=(const char *str) + \brief Re-initialize the object to a copy of the data of a string. + + \sa SetTo(const char *str, int32 maxLength) */ /*! -\fn BString& BString::operator=(char c) -\brief Re-initialize the object to a character. -\param c The character which you want to initialize the string to. -\return The function always returns \c *this . + \fn BString& BString::operator=(char c) + \brief Re-initialize the object to a character. + + \param c The character which you want to initialize the string to. */ /*! -\fn BString& BString::SetTo(const char *str, int32 maxLength) -\brief Re-initialize the object to a copy of the data of a C-string. -\param str Pointer to a string. -\param maxLength Amount of characters to copy from the original string. -\return The function always returns \c *this . -\sa operator=(const char *str) + \fn BString& BString::SetTo(const char *str, int32 maxLength) + \brief Re-initialize the object to a copy of the data of a string. + + \param str The string to copy. + \param maxLength Amount of characters to copy from the string. + + \sa operator=(const char *str) */ /*! -\fn BString& BString::SetTo(const BString &from) -\brief Re-initialize the object to a copy of the data of a BString. -\param from The string object to copy. -\return The function always returns \c *this . -\sa SetTo(const BString &string, int32 length) -\sa Adopt(BString &from) + \fn BString& BString::SetTo(const BString &from) + \brief Re-initialize the object to a copy of the data of a BString. + + \param from The string object to copy. + + \return The function always returns \c *this . + + \sa SetTo(const BString &string, int32 length) + \sa Adopt(BString &from) */ /*! -\fn BString& BString::SetTo(const char *str) -\brief Re-initialize the object to a copy of the data of a C-string. + \fn BString& BString::SetTo(const char *str) + \brief Re-initialize the object to a copy of the data of a string. -This method calls operator=(const char *str). + This method calls operator=(const char *str). -\param str Pointer to a C-string. -\return The function always returns \c *this . -\sa SetTo(const char *str, int32 maxLength) + \sa SetTo(const char *str, int32 maxLength) */ /*! -\fn BString& BString::Adopt(BString &from) -\brief Adopt the data of the given BString object. + \fn BString& BString::Adopt(BString &from) + \brief Adopt the data of the given BString object. -This method adopts the data. Please note that the object that is adopted -from is not deleted, only its private data is initialized to a null -string. So if the from object was created on the heap, you need to -clean it up yourself. + This method adopts the data from a BString. -\param from The string object to adopt. -\return The function always returns \c *this . -\sa operator=(const BString &string) -\sa SetTo(const BString &string, int32 length) + \note The object that is adopted from is not deleted, only its private + data is initialized to a \c NULL string. So if the from object was + created on the heap, you need to clean it up yourself. + + \param from The string object to adopt. + + \return The function always returns \c *this . + + \sa operator=(const BString &string) */ /*! -\fn BString& BString::SetTo(const BString &string, int32 length) -\brief Re-initialize the string to a copy of the given BString object. -\param string The string object to copy. -\param length Amount of characters to copy from the original BString. -\return The function always returns \c *this . -\sa operator=(const BString &string) -\sa Adopt(BString &from, int32 length) + \fn BString& BString::Adopt(BString &from, int32 maxLength) + \brief Adopt the data of the given BString object up to \a maxLength + characters. + + \param from The string object to adopt. + \param maxLength Number of characters to adopt from the original BString. + + \return The function always returns \c *this . + + \sa SetTo(const BString &string, int32 maxLength) */ /*! -\fn BString& BString::Adopt(BString &from, int32 length) -\brief Adopt the data of the given BString object. + \fn BString& BString::SetTo(const BString &string, int32 maxLength) + \brief Re-initialize the string to a copy of the given BString object. -This method adopts the data. Please note that the object that is adopted -from is not deleted, only its private data is initialized to a null -string. So if the from object was created on the heap, you need to -clean it up yourself. + \param string The BString object to copy. + \param maxLength Amount of characters to copy from the original BString. -\param from The string object to adopt. -\param length Amount of characters to get from the original BString. -\return The function always returns \c *this . -\sa operator=(const BString &string) -\sa SetTo(const BString &string, int32 length) + \return The function always returns \c *this . + + \sa operator=(const BString &string) + \sa Adopt(BString &from, int32 maxLength) */ /*! -\fn BString& BString::SetTo(char c, int32 count) -\brief Re-initialize the object to a string composed of a character you specify. + \fn BString& BString::SetTo(char c, int32 count) + \brief Re-initialize the object to a string composed of a character you + specify. -This method lets you specify the length of a string and what character you want the -string to contain repeatedly. + This method lets you specify the length of a string and what character + you want the string to contain repeatedly. -\param c The character you want to initialize the BString. -\param count The length of the string. -\return The function always returns \c *this . -\sa operator=(char c) + \param c The character you want to initialize the BString. + \param count The length of the string. + + \return The function always returns \c *this . + + \sa operator=(char c) */ //! @} /*! -\name Substring Copying + \name Substring Copying */ //! @{ /*! -\fn BString &BString::CopyInto(BString &into, int32 fromOffset, int32 length) const -\brief Copy the object's data (or part of it) into another BString. + \fn BString &BString::CopyInto(BString &into, int32 fromOffset, + int32 length) const + \brief Copy the object's data (or part of it) into another BString. -This methods makes sure you don't copy more bytes than are available in the string. If -the length exceeds the length of the string, it only copies the number of characters that -are actually available. + This methods makes sure you don't copy more bytes than are available + in the string. If the length exceeds the length of the string, it only + copies the number of characters that are actually available. -\param into The BString to where to copy the object. -\param fromOffset The zero-based offset where to begin the copy. -\param length The amount of bytes to copy. -\return This method always returns a pointer to the string passed as the \c into parameter. + \param into The BString to where to copy the object. + \param fromOffset The (zero-based) offset where to begin the copy. + \param length The amount of bytes to copy. + + \return This method always returns a pointer to the string passed as the + \c into parameter. */ /*! -\fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const -\brief Copy the BString data (or part of it) into the supplied buffer. + \fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const + \brief Copy the BString data (or part of it) into the supplied buffer. -This methods makes sure you don't copy more bytes than are available in the string. If -the length exceeds the length of the string, it only copies the number of characters that -are actually available. + This methods makes sure you don't copy more bytes than are available + in the string. If the length exceeds the length of the string, it only + copies the number of characters that are actually available. -It's up to you to make sure your buffer is large enough. + It's up to you to make sure your buffer is large enough. -\param into The buffer where to copy the object. -\param fromOffset The zero-based offset where to begin the copy. -\param length The amount of bytes to copy. + \param into The buffer where to copy the object. + \param fromOffset The (zero-based) offset where to begin the copy. + \param length The amount of bytes to copy. */ //! @} -/*! -\name Appending Methods +/*! + \name Appending Methods */ //! @{ /*! -\fn BString& BString::operator+=(const char *str) -\brief Append the given string to the object. -\param str A pointer to the NULL-terminated C-string to append. -\return This method always returns \c *this . -\sa Append(const char *str, int32 length) + \fn BString& BString::operator+=(const char *str) + \brief Append the given string to the object. + + \param str A pointer to the NULL-terminated string to append. + + \return This method always returns \c *this . + + \sa Append(const char *str, int32 length) */ /*! -\fn BString& BString::operator+=(char c) -\brief Append the given character to the object. -\param c The character to append. -\return This method always returns \c *this . -\sa Append(char c, int32 count) + \fn BString& BString::operator+=(char c) + \brief Append the given character to the object. + + \param c The character to append. + + \return This method always returns \c *this . + + \sa Append(char c, int32 count) */ /*! -\fn BString & BString::operator+=(const BString &string) -\brief Append the given string to the object -\param string The string to append -\return This method always returns \c *this . -\sa Append(const BString &string, int32 length) + \fn BString & BString::operator+=(const BString &string) + \brief Append the given string to the object + + \param string The string to append + + \return This method always returns \c *this . + + \sa Append(const BString &string, int32 length) */ /*! -\fn BString &BString::Append(const BString &string) -\brief Append the given string to the object -\param string The string to append -\return This method always returns \c *this . -\sa Append(const BString &string, int32 length) + \fn BString &BString::Append(const BString &string) + \brief Append the given string to the object + + \param string The string to append + + \return This method always returns \c *this . + + \sa Append(const BString &string, int32 length) */ /*! -\fn BString &BString::Append(const char *str) -\brief Append the given string to the object. + \fn BString &BString::Append(const char *str) + \brief Append the given string to the object. -This method calls operator+=(const char *str). -\sa Append(const char *str, int32 length) + This method calls operator+=(const char *str). + + \sa Append(const char *str, int32 length) */ /*! -\fn BString& BString::Append(const BString &string, int32 length) -\brief Append a part of the given BString to the object. -\param string The BString to append. -\param length The maximum number ofbytes to get from the original object. -\return This method always returns \c *this . -\sa operator+=(const BString &string) + \fn BString& BString::Append(const BString &string, int32 length) + \brief Append a part of the given BString to the object. + + \param string The BString to append. + \param length The maximum number ofbytes to get from the original object. + + \return This method always returns \c *this . + + \sa operator+=(const BString &string) */ /*! -\fn BString& BString::Append(const char *str, int32 length) -\brief Append a part of the given string to the object. -\param str A pointer to the string to append. -\param length The maximum bytes to get from the original string. -\return This method always returns \c *this . -\sa operator+=(const char *str) + \fn BString& BString::Append(const char *str, int32 length) + \brief Append a part of the given string to the object. + + \param str A pointer to the string to append. + \param length The maximum bytes to get from the original string. + + \return This method always returns \c *this . + + \sa operator+=(const char *str) */ /*! -\fn BString& BString::Append(char c, int32 count) -\brief Append the given character repeatedly to the object. -\param c The character to append. -\param count The number of times this character should be appended. -\return This method always returns \c *this . -\sa operator+=(char c) + \fn BString& BString::Append(char c, int32 count) + \brief Append the given character repeatedly to the object. + + \param c The character to append. + \param count The number of times this character should be appended. + + \return This method always returns \c *this . + + \sa operator+=(char c) */ //! @} /*! -\name Prepending Methods + \name Prepending Methods */ //! @{ /*! -\fn BString& BString::Prepend(const char *str) -\brief Prepend the given string to the object. -\param str A pointer to the string to prepend. -\return This method always returns \c *this . -\sa Prepend(const char *str, int32 length) + \fn BString& BString::Prepend(const char *str) + \brief Prepend the given string to the object. + + \param str A pointer to the string to prepend. + + \return This method always returns \c *this . + + \sa Prepend(const char *str, int32 length) */ /*! -\fn BString& BString::Prepend(const BString &string) -\brief Prepend the given BString to the object. -\param string The BString object to prepend. -\return This method always returns \c *this . -\sa Prepend(const BString &string, int32 len) + \fn BString& BString::Prepend(const BString &string) + \brief Prepend the given BString to the object. + + \param string The BString object to prepend. + + \return This method always returns \c *this . + + \sa Prepend(const BString &string, int32 len) */ /*! -\fn BString& BString::Prepend(const char *str, int32 length) -\brief Prepend the given string to the object. -\param str A pointer to the string to prepend. -\param length The maximum amount of bytes to get from the string. -\return This method always returns \c *this . -\sa Prepend(const char *str) + \fn BString& BString::Prepend(const char *str, int32 length) + \brief Prepend the given string to the object. + + \param str A pointer to the string to prepend. + \param length The maximum amount of bytes to get from the string. + + \return This method always returns \c *this . + + \sa Prepend(const char *str) */ /*! -\fn BString& BString::Prepend(const BString &string, int32 len) -\brief Prepend the given BString to the object. -\param string The BString object to prepend. -\param len The maximum amount of bytes to get from the BString. -\return This method always returns \c *this . -\sa Prepend(const BString &string) + \fn BString& BString::Prepend(const BString &string, int32 len) + \brief Prepend the given BString to the object. + + \param string The BString object to prepend. + \param len The maximum amount of bytes to get from the BString. + + \return This method always returns \c *this . + + \sa Prepend(const BString &string) */ /*! -\fn BString& BString::Prepend(char c, int32 count) -\brief Prepend the given character repeatedly to the object. -\param c The character to prepend. -\param count The number of times this character should be prepended. -\return This method always returns \c *this . + \fn BString& BString::Prepend(char c, int32 count) + \brief Prepend the given character repeatedly to the object. + + \param c The character to prepend. + \param count The number of times this character should be prepended. + + \return This method always returns \c *this . */ //! @} /*! -\name Inserting Methods + \name Inserting Methods */ //! @{ /*! -\fn BString& BString::Insert(const char *str, int32 pos) -\brief Insert the given string at the given position into the object's data. -\param str A pointer to the string to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const char *str, int32 length, int32 pos) -\sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) + \fn BString& BString::Insert(const char *str, int32 pos) + \brief Insert the given string at the given position into the object's + data. + + \param str A pointer to the string to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const char *str, int32 length, int32 pos) + \sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(const char *str, int32 length, int32 pos) -\brief Inserts the given string at the given position into the object's data. -\param str A pointer to the string to insert. -\param length The amount of bytes to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const char *str, int32 pos) -\sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) + \fn BString& BString::Insert(const char *str, int32 length, int32 pos) + \brief Inserts the given string at the given position into the object's + data. + + \param str A pointer to the string to insert. + \param length The amount of bytes to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const char *str, int32 pos) + \sa Insert(const char *str, int32 fromOffset, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(const char *str, int32 fromOffset, int32 length, int32 pos) -\brief Insert the given string at the given position into the object's data. -\param str A pointer to the string to insert. -\param fromOffset The offset in the string that is to be inserted -\param length The amount of bytes to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const char *str, int32 pos) -\sa Insert(const char *str, int32 length, int32 pos) + \fn BString& BString::Insert(const char *str, int32 fromOffset, + int32 length, int32 pos) + \brief Insert the given string at the given position into the object's + data. + + \param str A pointer to the string to insert. + \param fromOffset The offset in the string that is to be inserted + \param length The amount of bytes to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const char *str, int32 pos) + \sa Insert(const char *str, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(const BString &string, int32 pos) -\brief Insert the given BString at the given position into the object's data. -\param string The BString object to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const BString &string, int32 length, int32 pos) -\sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) + \fn BString& BString::Insert(const BString &string, int32 pos) + \brief Insert the given BString at the given position into the object's + data. + \param string The BString object to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const BString &string, int32 length, int32 pos) + \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(const BString &string, int32 length, int32 pos) -\brief Insert the given BString at the given position into the object's data. -\param string The BString object to insert. -\param length The amount of bytes to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const BString &string, int32 pos) -\sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) + \fn BString& BString::Insert(const BString &string, int32 length, int32 pos) + \brief Insert the given BString at the given position into the object's + data. + \param string The BString object to insert. + \param length The amount of bytes to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const BString &string, int32 pos) + \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(const BString &string, int32 fromOffset, int32 length, int32 pos) -\brief Insert the given string at the given position into the object's data. -\param string The BString object to insert. -\param fromOffset The offset in the string that is to be inserted -\param length The amount of bytes to insert. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . -\sa Insert(const BString &string, int32 pos) -\sa Insert(const BString &string, int32 length, int32 pos) + \fn BString& BString::Insert(const BString &string, int32 fromOffset, + int32 length, int32 pos) + \brief Insert the given string at the given position into the object's + data. + + \param string The BString object to insert. + \param fromOffset The offset in the string that is to be inserted + \param length The amount of bytes to insert. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . + + \sa Insert(const BString &string, int32 pos) + \sa Insert(const BString &string, int32 length, int32 pos) */ /*! -\fn BString& BString::Insert(char c, int32 count, int32 pos) -\brief Insert the given character repeatedly at the given position into the object's data. -\param c The character to insert. -\param count The number of times to insert the character. -\param pos The offset in bytes into the BString's data where to insert the string. -\return This method always returns \c *this . + \fn BString& BString::Insert(char c, int32 count, int32 pos) + \brief Insert the given character repeatedly at the given position + into the object's data. + + \param c The character to insert. + \param count The number of times to insert the character. + \param pos The offset in bytes into the BString's data where to insert + the string. + + \return This method always returns \c *this . */ //! @} /*! -\name Removing Methods + \name Removing Methods */ //! @{ /*! -\fn BString& BString::Truncate(int32 newLength, bool lazy) -\brief Truncate the string to the new length. -\param newLength The new length of the string. -\param lazy If true, the memory-optimization is postponed to later -\return This method always returns \c *this . + \fn BString& BString::Truncate(int32 newLength, bool lazy) + \brief Truncate the string to the new length. + + \param newLength The new length of the string. + \param lazy If true, the memory-optimization is postponed to later + + \return This method always returns \c *this . */ /*! -\fn BString& BString::Remove(int32 from, int32 length) -\brief Remove some bytes, starting at the given offset -\param from The offset from which you want to start removing -\param length The number of bytes to remove -\return This function always returns \c *this . + \fn BString& BString::Remove(int32 from, int32 length) + \brief Remove some bytes, starting at the given offset + + \param from The offset from which you want to start removing + \param length The number of bytes to remove + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveFirst(const BString &string) -\brief Remove the first occurrence of the given BString. -\param string The BString to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveFirst(const BString &string) + \brief Remove the first occurrence of the given BString. + + \param string The BString to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveLast(const BString &string) -\brief Remove the last occurrence of the given BString. -\param string The BString to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveLast(const BString &string) + \brief Remove the last occurrence of the given BString. + + \param string The BString to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveAll(const BString &string) -\brief Remove all occurrences of the given BString. -\param string The BString to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveAll(const BString &string) + \brief Remove all occurrences of the given BString. + + \param string The BString to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveFirst(const char *string) -\brief Remove the first occurrence of the given string. -\param string A pointer to the string to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveFirst(const char *string) + \brief Remove the first occurrence of the given string. + + \param string A pointer to the string to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveLast(const char *string) -\brief Remove the last occurrence of the given string. -\param string A pointer to the string to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveLast(const char *string) + \brief Remove the last occurrence of the given string. + + \param string A pointer to the string to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveAll(const char *str) -\brief Remove all occurrences of the given string. -\param str A pointer to the string to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveAll(const char *str) + \brief Remove all occurrences of the given string. + + \param str A pointer to the string to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::RemoveSet(const char *setOfCharsToRemove) -\brief Remove all the characters specified. -\param setOfCharsToRemove The set of characters to remove. -\return This function always returns \c *this . + \fn BString& BString::RemoveSet(const char *setOfCharsToRemove) + \brief Remove all the characters specified. + + \param setOfCharsToRemove The set of characters to remove. + + \return This function always returns \c *this . */ /*! -\fn BString& BString::MoveInto(BString &into, int32 from, int32 length) -\brief Move the BString data (or part of it) into another BString. -\param into The BString where to move the object. -\param from The offset (zero based) where to begin the move -\param length The amount of bytes to move. -\return This method always returns \c into . + \fn BString& BString::MoveInto(BString &into, int32 from, int32 length) + \brief Move the BString data (or part of it) into another BString. + + \param into The BString where to move the object. + \param from The offset (zero-based) where to begin the move. + \param length The amount of bytes to move. + + \return This method always returns \c into . */ /*! -\fn void BString::MoveInto(char *into, int32 from, int32 length) -\brief Move the BString data (or part of it) into the given buffer. -\param into The buffer where to move the object. -\param from The offset (zero based) where to begin the move. -\param length The amount of bytes to move. + \fn void BString::MoveInto(char *into, int32 from, int32 length) + \brief Move the BString data (or part of it) into the given buffer. + + \param into The buffer where to move the object. + \param from The offset (zero-based) where to begin the move. + \param length The amount of bytes to move. */ //! @} /*! -\name Comparison Methods + \name Comparison Methods -There are two different comparison methods. First of all there -is the whole range of operators that return a boolean value, secondly -there are methods that return an integer value, both case sensitive -and case insensitive. + There are two different comparison methods. First of all there + is the whole range of operators that return a boolean value, secondly + there are methods that return an integer value, both case sensitive + and case insensitive. -There are also global comparison operators and global compare functions. -You might need these in case you have a sort routine that takes a generic -comparison function, such as BList::SortItems(). -See the String.h documentation file to see the specifics, though basically -there are the same as implemented in this class. + There are also global comparison operators and global compare functions. + You might need these in case you have a sort routine that takes a generic + comparison function, such as BList::SortItems(). + See the String.h documentation file to see the specifics, though basically + there are the same as implemented in this class. */ //! @{ /*! -\fn bool BString::operator<(const char *string) const -\brief Lexographically compare if this string is less than a given string. + \fn bool BString::operator<(const char *string) const + \brief Lexographically compare if this string is less than a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator<(const BString &string) const -\brief Lexographically compare if this string is less than a given string. + \fn bool BString::operator<(const BString &string) const + \brief Lexographically compare if this string is less than a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator<=(const char *string) const -\brief Lexographically compare if this string is less than or equal to a given string. + \fn bool BString::operator<=(const char *string) const + \brief Lexographically compare if this string is less than or equal to + a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator<=(const BString &string) const -\brief Lexographically compare if this string is less than or equal to a given string. + \fn bool BString::operator<=(const BString &string) const + \brief Lexographically compare if this string is less than or equal to + a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator==(const char *string) const -\brief Lexographically compare if this string is equal to a given string. + \fn bool BString::operator==(const char *string) const + \brief Lexographically compare if this string is equal to a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator==(const BString &string) const -\brief Lexographically compare if this string is equal to a given string. + \fn bool BString::operator==(const BString &string) const + \brief Lexographically compare if this string is equal to a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator>=(const char *string) const -\brief Lexographically compare if this string is more than or equal to a given string. + \fn bool BString::operator>=(const char *string) const + \brief Lexographically compare if this string is more than or equal + to a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator>=(const BString &string) const -\brief Lexographically compare if this string is more than or equal to a given string. + \fn bool BString::operator>=(const BString &string) const + \brief Lexographically compare if this string is more than or equal + to a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator>(const char *string) const -\brief Lexographically compare if this string is more than a given string. + \fn bool BString::operator>(const char *string) const + \brief Lexographically compare if this string is more than a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator>(const BString &string) const -\brief Lexographically compare if this string is more than a given string. + \fn bool BString::operator>(const BString &string) const + \brief Lexographically compare if this string is more than a given string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator!=(const BString &string) const -\brief Lexographically compare if this string is not equal to a given string. + \fn bool BString::operator!=(const BString &string) const + \brief Lexographically compare if this string is not equal to a given + string. + + \param string The string to compare with. */ /*! -\fn bool BString::operator!=(const char *str) const -\brief Lexographically compare if this string is not equal to a given string. + \fn bool BString::operator!=(const char *string) const + \brief Lexographically compare if this string is not equal to a given + string. + + \param string The string to compare with. */ /*! -\fn int BString::Compare(const BString &string) const -\brief Lexographically compare this string to another. + \fn int BString::Compare(const BString &string) const + \brief Lexographically compare this string to another. -\param string The string to compare to. -\retval >0 The object sorts lexographically after \c string. -\retval =0 The object is equal to \c string. -\retval <0 The object sorts lexographically before \c string. + \param string The string to compare to. + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. */ /*! -\fn int BString::Compare(const char *str) const -\brief Lexographically compare this string to another. + \fn int BString::Compare(const char *str) const + \brief Lexographically compare this string to another. -\sa Compare(const BString &string) const + \param str The string to compare to. + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string) const */ /*! -\fn int BString::Compare(const BString &string, int32 n) const -\brief Lexographically compare a number of characters of this string to another. + \fn int BString::Compare(const BString &string, int32 n) const + \brief Lexographically compare a number of characters of a string to + another. -\param string The string to compare to. -\param n The number of characters to compare -\retval >0 The object sorts lexographically after \c string. -\retval =0 The object is equal to \c string. -\retval <0 The object sorts lexographically before \c string. + \param string The string to compare to. + \param n The number of characters to compare + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. */ /*! -\fn int BString::Compare(const char *str, int32 n) const -\brief Lexographically compare a number of characters of this string to another. + \fn int BString::Compare(const char *string, int32 n) const + \brief Lexographically compare a number of characters of a string to + another. -\sa Compare(const BString &string, int32 n) const + \param string The string to compare to. + \param n The number of characters to compare. + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string, int32 n) const */ /*! -\fn int BString::ICompare(const BString &string) const -\brief Lexographically compare this string to another in a case-insensitive way. + \fn int BString::ICompare(const BString &string) const + \brief Lexographically compare a string to another in a + case-insensitive way. -\sa Compare(const BString &string) const + \param string The string to compare to. + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string) const */ /*! -\fn int BString::ICompare(const char *str) const -\brief Lexographically compare this string to another in a case-insensitive way. + \fn int BString::ICompare(const char *str) const + \brief Lexographically compare this string to another in a + case-insensitive way. -\sa Compare(const BString &string) const + \param str The string to compare to. + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string) const */ /*! -\fn int BString::ICompare(const BString &string, int32 n) const -\brief Lexographically compare a number of characters of this string to another. + \fn int BString::ICompare(const BString &string, int32 n) const + \brief Lexographically compare a number of characters of this string + to another. -\sa Compare(const BString &string, int32 n) const + \param string The string to compare to. + \param n The number of characters to compare + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string, int32 n) const */ /*! -\fn int BString::ICompare(const char *str, int32 n) const -\brief Lexographically compare a number of characters of this string to another. + \fn int BString::ICompare(const char *str, int32 n) const + \brief Lexographically compare a number of characters of this string + to another. -\sa Compare(const BString &string, int32 n) const + \param str The string to compare to. + \param n The number of characters to compare + + \retval >0 The object sorts lexographically after \c string. + \retval =0 The object is equal to \c string. + \retval <0 The object sorts lexographically before \c string. + + \sa Compare(const BString &string, int32 n) const */ //! @} /*! -\name Searching Methods + \name Searching Methods */ //! @{ /*! -\fn int32 BString::FindFirst(const BString &string) const -\brief Find the first occurrence of the given BString. -\param string The BString to search for. -\return The offset(zero based) into the data - where the given BString has been found. -\retval B_ERROR Could not find \c string. -\sa IFindFirst(const BString &string) const + \fn int32 BString::FindFirst(const BString &string) const + \brief Find the first occurrence of the given BString. + + \param string The BString to search for. + + \return The offset (zero-based) into the data where the given BString + has been found. + + \retval B_ERROR Could not find \c string. + + \sa IFindFirst(const BString &string) const */ /*! -\fn int32 BString::FindFirst(const char *str) const -\brief Find the first occurrence of the given string. -\param str The string to search for. -\return The offset(zero based) into the data - where the given string has been found. -\retval B_BAD_VALUE The \c str pointer is invalid. -\retval B_ERROR Could not find \c str. -\sa IFindFirst(const char *str) const + \fn int32 BString::FindFirst(const char *str) const + \brief Find the first occurrence of the given string. + + \param str The string to search for. + + \return The offset (zero-based) into the data where the given string + has been found. + + \retval B_BAD_VALUE The \c str pointer is invalid. + \retval B_ERROR Could not find \c str. + + \sa IFindFirst(const char *str) const */ /*! -\fn int32 BString::FindFirst(const BString &string, int32 fromOffset) const -\brief Find the first occurrence of the given BString, - starting from the given offset. -\param string The BString to search for. -\param fromOffset The offset where to start the search. -\return An integer which is the offset(zero based) into the data - where the given BString has been found. -\retval B_ERROR Could not find \c string. -\sa IFindFirst(const BString &string, int32 fromOffset) const + \fn int32 BString::FindFirst(const BString &string, int32 fromOffset) const + \brief Find the first occurrence of the given BString, starting from + the given offset. + + \param string The BString to search for. + \param fromOffset The offset where to start the search. + + \return An integer which is the offset (zero-based) into the data + where the given BString has been found. + + \retval B_ERROR Could not find \c string. + + \sa IFindFirst(const BString &string, int32 fromOffset) const */ /*! -\fn int32 BString::FindFirst(const char *str, int32 fromOffset) const -\brief Find the first occurrence of the given string, - starting from the given offset. -\param str The string to search for. -\param fromOffset The offset where to start the search. -\return The offset(zero based) into the data - where the given string has been found. -\retval B_BAD_VALUE The \c str pointer is invalid. -\retval B_ERROR Could not find \c str. -\sa IFindFirst(const char *str, int32 fromOffset) const + \fn int32 BString::FindFirst(const char *str, int32 fromOffset) const + \brief Find the first occurrence of the given string, + starting from the given offset. + + \param str The string to search for. + \param fromOffset The offset where to start the search. + + \return The offset (zero-based) into the data where the given string + has been found. + + \retval B_BAD_VALUE The \c str pointer is invalid. + \retval B_ERROR Could not find \c str. + + \sa IFindFirst(const char *str, int32 fromOffset) const */ /*! -\fn int32 BString::FindFirst(char c) const -\brief Find the first occurrence of the given character. -\param c The character to search for. -\return The offset(zero based) into the data - where the given character has been found. -\retval B_ERROR Could not find \c c. + \fn int32 BString::FindFirst(char c) const + \brief Find the first occurrence of the given character. + + \param c The character to search for. + + \return The offset (zero-based) into the data + where the given character has been found. + + \retval B_ERROR Could not find \c c. */ /*! -\fn int32 BString::FindFirst(char c, int32 fromOffset) const -\brief Find the first occurrence of the given character, - starting from the given offset. -\param c The character to search for. -\param fromOffset The offset where to start the search. -\return The offset(zero based) into the data - where the given character has been found. -\retval B_ERROR Could not find \c c. + \fn int32 BString::FindFirst(char c, int32 fromOffset) const + \brief Find the first occurrence of the given character, + starting from the given offset. + + \param c The character to search for. + \param fromOffset The offset where to start the search. + + \return The offset (zero-based) into the data + where the given character has been found. + + \retval B_ERROR Could not find \c c. */ /*! -\fn int32 BString::FindLast(const BString &string) const -\brief Find the last occurrence of the given BString. -\param string The BString to search for. -\return The offset(zero based) into the data - where the given BString has been found. -\retval B_ERROR Could not find \c string. -\sa IFindLast(const BString &string) const + \fn int32 BString::FindLast(const BString &string) const + \brief Find the last occurrence of the given BString. + + \param string The BString to search for. + + \return The offset (zero-based) into the data where the given BString + has been found. + + \retval B_ERROR Could not find \c string. + \sa IFindLast(const BString &string) const */ /*! -\fn int32 BString::FindLast(const char *str) const -\brief Find the last occurrence of the given string. -\param str The string to search for. -\return The offset(zero based) into the data - where the given string has been found. -\retval B_BAD_VALUE The \c str pointer is invalid. -\retval B_ERROR Could not find \c str. -\sa IFindLast(const char *str) const + \fn int32 BString::FindLast(const char *str) const + \brief Find the last occurrence of the given string. + + \param str The string to search for. + + \return The offset (zero-based) into the data where the given string + has been found. + + \retval B_BAD_VALUE The \c str pointer is invalid. + \retval B_ERROR Could not find \c str. + + \sa IFindLast(const char *str) const +/*! /*! -\fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const -\brief Find the last occurrence of the given BString, - starting from the given offset, and going backwards. -\param string The BString to search for. -\param beforeOffset The offset where to start the search. -\return An integer which is the offset(zero based) into the data - where the given BString has been found. -\retval B_ERROR Could not find \c string. -\sa IFindLast(const BString &string, int32 beforeOffset) const + \fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const + \brief Find the last occurrence of the given BString, + starting from the given offset, and going backwards. + + \param string The BString to search for. + \param beforeOffset The offset where to start the search. + + \return An integer which is the offset (zero-based) into the data + where the given BString has been found. + + \retval B_ERROR Could not find \c string. + + \sa IFindLast(const BString &string, int32 beforeOffset) const */ /*! -\fn int32 BString::FindLast(const char *str, int32 beforeOffset) const -\brief Find the last occurrence of the given string, - starting from the given offset, and going backwards. -\param str The string to search for. -\param beforeOffset The offset where to start the search. -\return The offset(zero based) into the data - where the given string has been found. -\retval B_BAD_VALUE The \c str pointer is invalid. -\retval B_ERROR Could not find \c str. -\sa IFindLast(const char *str, int32 beforeOffset) const + \fn int32 BString::FindLast(const char *str, int32 beforeOffset) const + \brief Find the last occurrence of the given string, + starting from the given offset, and going backwards. + + \param str The string to search for. + \param beforeOffset The offset where to start the search. + + \return The offset (zero-based) into the data + where the given string has been found. + + \retval B_BAD_VALUE The \c str pointer is invalid. + \retval B_ERROR Could not find \c str. + + \sa IFindLast(const char *str, int32 beforeOffset) const */ /*! -\fn int32 BString::FindLast(char c) const -\brief Find the last occurrence of the given character. -\param c The character to search for. -\return The offset(zero based) into the data - where the given character has been found. -\retval B_ERROR Could not find \c c. + \fn int32 BString::FindLast(char c) const + \brief Find the last occurrence of the given character. + + \param c The character to search for. + \return The offset (zero-based) into the data where the given character + has been found. + + \retval B_ERROR Could not find \c c. */ /*! -\fn int32 BString::FindLast(char c, int32 beforeOffset) const -\brief Find the last occurrence of the given character, - starting from the given offset and going backwards. -\param c The character to search for. -\param beforeOffset The offset where to start the search. -\return The offset(zero based) into the data - where the given character has been found. -\retval B_ERROR Could not find \c c. + \fn int32 BString::FindLast(char c, int32 beforeOffset) const + \brief Find the last occurrence of the given character, + starting from the given offset and going backwards. + + \param c The character to search for. + \param beforeOffset The offset where to start the search. + + \return The offset (zero-based) into the data where the given character + has been found. + + \retval B_ERROR Could not find \c c. */ /*! -\fn int32 BString::IFindFirst(const BString &string) const -\brief Find the first occurrence of the given BString case-insensitively. + \fn int32 BString::IFindFirst(const BString &string) const + \brief Find the first occurrence of the given BString case-insensitively. -\sa FindFirst(const BString &string) const + \sa FindFirst(const BString &string) const */ /*! -\fn int32 BString::IFindFirst(const char *str) const -\brief Find the first occurrence of the given BString case-insensitively. + \fn int32 BString::IFindFirst(const char *str) const + \brief Find the first occurrence of the given BString case-insensitively. -\sa FindFirst(const char *str) const + \sa FindFirst(const char *str) const */ /*! -\fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) const -\brief Find the first occurrence of the given BString case-insensitively, - starting from the given offset. + \fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) const + \brief Find the first occurrence of the given BString case-insensitively, + starting from the given offset. -\sa FindFirst(const BString &string, int32 fromOffset) const + \sa FindFirst(const BString &string, int32 fromOffset) const */ /*! -\fn int32 BString::IFindFirst(const char *str, int32 fromOffset) const -\brief Find the first occurrence of the given string case-insensitively, - starting from the given offset. + \fn int32 BString::IFindFirst(const char *str, int32 fromOffset) const + \brief Find the first occurrence of the given string case-insensitively, + starting from the given offset. -\sa FindFirst(const char *str, int32 fromOffset) const + \sa FindFirst(const char *str, int32 fromOffset) const */ /*! -\fn int32 BString::IFindLast(const BString &string) const -\brief Find the last occurrence of the given BString case-insensitively. + \fn int32 BString::IFindLast(const BString &string) const + \brief Find the last occurrence of the given BString case-insensitively. -\sa FindLast(const BString &string) const + \sa FindLast(const BString &string) const */ /*! -\fn int32 BString::IFindLast(const char *str) const -\brief Find the last occurrence of the given string case-insensitively. - -\sa FindLast(const char *str) const + \fn int32 BString::IFindLast(const char *str) const + \brief Find the last occurrence of the given string case-insensitively. + + \sa FindLast(const char *str) const */ /*! -\fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) const -\brief Find the last occurrence of the given BString case-insensitively, - starting from the given offset, and going backwards. + \fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) const + \brief Find the last occurrence of the given BString case-insensitively, + starting from the given offset, and going backwards. -\sa FindLast(const BString &string, int32 beforeOffset) const + \sa FindLast(const BString &string, int32 beforeOffset) const */ /*! -\fn int32 BString::IFindLast(const char *str, int32 beforeOffset) const -\brief Find the last occurrence of the given string case-insensitively, - starting from the given offset, and going backwards. + \fn int32 BString::IFindLast(const char *str, int32 beforeOffset) const + \brief Find the last occurrence of the given string case-insensitively, + starting from the given offset, and going backwards. -\sa FindLast(const char *str, int32 beforeOffset) const + \sa FindLast(const char *str, int32 beforeOffset) const */ //! @} /*! -\name Replacing Methods + \name Replacing Methods */ //! @{ /*! -\fn BString& BString::ReplaceFirst(char replaceThis, char withThis) -\brief Replace the first occurrence of a character with another character. -\param replaceThis The character to replace. -\param withThis The character to put in that place -\return This method always returns \c *this. -\sa IReplaceFirst(char replaceThis, char withThis) + \fn BString& BString::ReplaceFirst(char replaceThis, char withThis) + \brief Replace the first occurrence of a character with another character. + + \param replaceThis The character to replace. + \param withThis The character to put in that place + + \return This method always returns \c *this. + + \sa IReplaceFirst(char replaceThis, char withThis) */ /*! -\fn BString& BString::ReplaceLast(char replaceThis, char withThis) -\brief Replace the last occurrence of a character with another character. -\param replaceThis The character to replace. -\param withThis The character to put in that place -\return This method always returns \c *this. -\sa ReplaceLast(char replaceThis, char withThis) + \fn BString& BString::ReplaceLast(char replaceThis, char withThis) + \brief Replace the last occurrence of a character with another character. + + \param replaceThis The character to replace. + \param withThis The character to put in that place + + \return This method always returns \c *this. + + \sa ReplaceLast(char replaceThis, char withThis) */ /*! -\fn BString& BString::ReplaceAll(char replaceThis, char withThis, int32 fromOffset) -\brief Replace all occurrences of a character with another character. -\param replaceThis The character to replace. -\param withThis The character to put in that place -\param fromOffset The offset where to start looking for the character -\return This method always returns \c *this. -\sa IReplaceAll(char replaceThis, char withThis, int32 fromOffset) + \fn BString& BString::ReplaceAll(char replaceThis, char withThis, + int32 fromOffset) + \brief Replace all occurrences of a character with another character. + + \param replaceThis The character to replace. + \param withThis The character to put in that place + \param fromOffset The offset where to start looking for the character. + + \return This method always returns \c *this. + + \sa IReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ /*! -\fn BString& BString::Replace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) -\brief Replace a number of occurrences of a character with another character. -\param replaceThis The character to replace. -\param withThis The character to put in that place -\param maxReplaceCount The maximum number of characters that should be replaced. -\param fromOffset The offset where to start looking for the character -\return This method always returns \c *this. -\sa IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) + \fn BString& BString::Replace(char replaceThis, char withThis, + int32 maxReplaceCount, int32 fromOffset) + \brief Replace a number of occurrences of a character with another + character. + + \param replaceThis The character to replace. + \param withThis The character to put in that place + \param maxReplaceCount The maximum number of characters that should be + replaced. + \param fromOffset The offset where to start looking for the character + + \return This method always returns \c *this. + + \sa IReplace(char replaceThis, char withThis, int32 maxReplaceCount, + int32 fromOffset) */ /*! -\fn BString& BString::ReplaceFirst(const char *replaceThis, const char *withThis) -\brief Replace the first occurrence of a string with another string. -\param replaceThis The C-string to replace. -\param withThis The C-string to put in that place -\return This method always returns \c *this. -\sa IReplaceFirst(const char *replaceThis, const char *withThis) + \fn BString& BString::ReplaceFirst(const char *replaceThis, + const char *withThis) + \brief Replace the first occurrence of a string with another string. + + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \return This method always returns \c *this. + + \sa IReplaceFirst(const char *replaceThis, const char *withThis) */ /*! -\fn BString& BString::ReplaceLast(const char *replaceThis, const char *withThis) -\brief Replace the last occurrence of a string with another string. -\param replaceThis The C-string to replace. -\param withThis The C-string to put in that place -\return This method always returns \c *this. -\sa IReplaceLast(const char *replaceThis, const char *withThis) + \fn BString& BString::ReplaceLast(const char *replaceThis, + const char *withThis) + \brief Replace the last occurrence of a string with another string. + + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \return This method always returns \c *this. + + \sa IReplaceLast(const char *replaceThis, const char *withThis) */ /*! -\fn BString& BString::ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) -\brief Replace all occurrences of a string with another string. -\param replaceThis The string to replace. -\param withThis The string to put in that place -\param fromOffset The offset where to start looking for the string. -\return This method always returns \c *this. -\sa IReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) + \fn BString& BString::ReplaceAll(const char *replaceThis, + const char *withThis, int32 fromOffset) + \brief Replace all occurrences of a string with another string. + + \param replaceThis The string to replace. + \param withThis The string to put in that place + \param fromOffset The offset where to start looking for the string. + + \return This method always returns \c *this. + + \sa IReplaceAll(const char *replaceThis, const char *withThis, + int32 fromOffset) */ /*! -\fn BString& BString::Replace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) -\brief Replace a number of occurrences of a string with another string. -\param replaceThis The string to replace. -\param withThis The string to put in that place -\param maxReplaceCount The maximum number of occurences that should be replaced. -\param fromOffset The offset where to start looking for the string -\return This method always returns \c *this. -\sa IReplace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) + \fn BString& BString::Replace(const char *replaceThis, + const char *withThis, int32 maxReplaceCount, int32 fromOffset) + \brief Replace a number of occurrences of a string with another string. + + \param replaceThis The string to replace. + \param withThis The string to put in that place + \param maxReplaceCount The maximum number of occurences that should + be replaced. + \param fromOffset The offset where to start looking for the string + + \return This method always returns \c *this. + + \sa IReplace(const char *replaceThis, const char *withThis, + int32 maxReplaceCount, int32 fromOffset) */ /*! -\fn BString& BString::IReplaceFirst(char replaceThis, char withThis) -\brief Replace the first occurrence of a character with another character. Case insensitive. -\sa ReplaceFirst(char replaceThis, char withThis) + \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) + \brief Replace the first occurrence of a character with another + character. Case insensitive. + + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \sa ReplaceFirst(char replaceThis, char withThis) */ /*! -\fn BString& BString::IReplaceLast(char replaceThis, char withThis) -\brief Replace the last occurrence of a character with another character. Case-insensitive. + \fn BString& BString::IReplaceLast(char replaceThis, char withThis) + \brief Replace the last occurrence of a character with another + character. Case-insensitive. -\sa ReplaceLast(char replaceThis, char withThis) + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \sa ReplaceLast(char replaceThis, char withThis) */ /*! -\fn BString& BString::IReplaceAll(char replaceThis, char withThis, int32 fromOffset) -\brief Replace all occurrences of a character with another character. Case-insensitive. + \fn BString& BString::IReplaceAll(char replaceThis, char withThis, + int32 fromOffset) + \brief Replace all occurrences of a character with another character. + Case-insensitive. -\sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) + \param replaceThis The string to replace. + \param withThis The string to put in that place + \param fromOffset The offset where to start looking for the string + + \sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ /*! -\fn BString& BString::IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) -\brief Replace a number of occurrences of a character with another character. Case-insensive. + \fn BString& BString::IReplace(char replaceThis, char withThis, + int32 maxReplaceCount, int32 fromOffset) + \brief Replace a number of occurrences of a character with another + character. Case-insensive. -\sa Replace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) + \param replaceThis The char to replace. + \param withThis The char to put in that place + \param maxReplaceCount The maximum number of occurences that should + be replaced. + \param fromOffset The offset where to start looking for the string + + \sa Replace(char replaceThis, char withThis, int32 maxReplaceCount, + int32 fromOffset) */ /*! -\fn BString& BString::IReplaceFirst(const char *replaceThis, const char *withThis) -\brief Replace the first occurrence of a string with another string. Case-insensitive. + \fn BString& BString::IReplace(const char *replaceThis, + const char *withThis, int32 maxReplaceCount, int32 fromOffset) + \brief Replace a number of occurrences of a string with another string. + Case-insensitive. -\sa ReplaceFirst(const char *replaceThis, const char *withThis) + \param replaceThis The string to replace. + \param withThis The string to put in that place + \param maxReplaceCount The maximum number of occurences that should + be replaced. + \param fromOffset The offset where to start looking for the string + + \sa Replace(const char *replaceThis, const char *withThis, + int32 maxReplaceCount, int32 fromOffset) */ /*! -\fn BString& BString::IReplaceLast(const char *replaceThis, const char *withThis) -\brief Replace the last occurrence of a string with another string. Case-insensitive. + \fn BString& BString::IReplaceFirst(const char *replaceThis, + const char *withThis) + \brief Replace the first occurrence of a string with another string. + Case-insensitive. -\sa ReplaceLast(const char *replaceThis, const char *withThis) + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \sa ReplaceFirst(const char *replaceThis, const char *withThis) */ /*! -\fn BString& BString::IReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) -\brief Replace all occurrences of a string with another string. Case-insensitive. + \fn BString& BString::IReplaceLast(const char *replaceThis, + const char *withThis) + \brief Replace the last occurrence of a string with another string. Case-insensitive. -\sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) + \param replaceThis The string to replace. + \param withThis The string to put in that place + + \sa ReplaceLast(const char *replaceThis, const char *withThis) */ /*! -\fn BString& BString::IReplace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) -\brief Replace a number of occurrences of a string with another string. Case-insensitive. + \fn BString& BString::IReplaceAll(const char *replaceThis, + const char *withThis, int32 fromOffset) + \brief Replace all occurrences of a string with another string. + Case-insensitive. -\sa Replace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) + \param replaceThis The string to replace. + \param withThis The string to put in that place + \param fromOffset The offset where to start looking for the string + + \sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) */ /*! -\fn BString& BString::ReplaceSet(const char *setOfChars, 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 with The character to replace the occurences with. -\return This method always returns \c *this. + \fn BString& BString::ReplaceSet(const char *setOfChars, 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 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) -\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 with The string to replace the occurences with. -\return This method always returns \c *this. + \fn BString& BString::ReplaceSet(const char *setOfChars, 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 with The string to replace the occurences with. + + \return This method always returns \c *this. */ // @} /*! -\name Character Access + \name Character Access */ //! @{ /*! -\fn char & BString::operator[](int32 index) -\brief Return a reference to the data at the given offset. + \fn char & BString::operator[](int32 index) + \brief Return a reference to the data at the given offset. -This function can be used to read a byte. -There is no bounds checking though, so make sure the \c index -you supply is valid. -\param index The index (zero based) of the byte to get. -\return Returns a reference to the specified byte. -\sa ByteAt(int32 index) for a safer version. + This function can be used to read a byte. + There is no bounds checking though, so make sure the \c index + you supply is valid. + + \param index The index (zero-based) of the byte to get. + + \return Returns a reference to the specified byte. + + \sa ByteAt(int32 index) for a safer version. */ /*! -\fn char BString::operator[](int32 index) const -\brief Returns the character in the string at the given offset. + \fn char BString::operator[](int32 index) const + \brief Returns the character in the string at the given offset. -This function can be used to read a byte. There is no bound checking -though, use ByteAt() if you don't know if the \c index parameter is -valid. -\param index The index (zero based) of the byte to get. -\return Returns a reference to the specified byte. + This function can be used to read a byte. There is no bound checking + though, use ByteAt() if you don't know if the \c index parameter is + valid. + + \param index The index (zero-based) of the byte to get. + + \return Returns a reference to the specified byte. */ /*! -\fn char BString::ByteAt(int32 index) const -\brief Returns the character in the string at the given offset. + \fn char BString::ByteAt(int32 index) const + \brief Returns the character in the string at the given offset. -This function can be used to read a byte. -\param index The index (zero based) of the byte to get. -\return Returns a reference to the specified byte. If you are out of bounds, - it will return 0. + This function can be used to read a single byte. + + \param index The index (zero-based) of the byte to get. + + \return Returns a reference to the specified byte. If you are out of + bounds, it will return 0. */ //! @} /*! -\name Low-Level Manipulation + \name Low-Level Manipulation */ //! @{ /*! -\fn char* BString::LockBuffer(int32 maxLength) -\brief Locks the buffer and return the internal C-string for manipulation. + \fn char* BString::LockBuffer(int32 maxLength) + \brief Locks the buffer and return the internal string for manipulation. -If you want to do any lowlevel string manipulation on the internal buffer, -you should call this method. This method includes the possibility to grow the -buffer so that you don't have to worry about that yourself. + If you want to do any lowlevel string manipulation on the internal buffer, + you should call this method. This method includes the possibility to grow + the buffer so that you don't have to worry about that yourself. -Make sure you call UnlockBuffer() when you're done with the manipulation. + Make sure you call UnlockBuffer() when you're done with the manipulation. -\param maxLength The size of the buffer. If you don't want a bigger buffer, passing - anything under the length of the string will simply return it as is. -\return A pointer to the buffer you may manipulate. -\sa UnlockBuffer() + \param maxLength The size of the buffer. If you don't want a biggerx + buffer, passing anything under the length of the string will simply + return it as is. + + \return A pointer to the buffer you may manipulate. + + \sa UnlockBuffer() */ /*! -\fn BString& BString::UnlockBuffer(int32 length) -\brief Unlocks the buffer after you are done with lowlevel manipulation. + \fn BString& BString::UnlockBuffer(int32 length) + \brief Unlocks the buffer after you are done with lowlevel manipulation. -\param length The length to trim the string to in order to keep the internal - buffer sane. If you don't pass a value in it, a \c strlen call will be used to - determine the length. -\return This method always returns \c *this. + \param length The length to trim the string to in order to keep the + internal buffer sane. If you don't pass a value in it, a \c strlen + call will be used to determine the length. + + \return This method always returns \c *this. */ //! @} /*! -\name Case Manipulation + \name Case Manipulation */ //! @{ /*! -\fn BString& BString::ToLower() -\brief Convert the BString to lowercase. -\return This method always returns \c *this . + \fn BString& BString::ToLower() + \brief Convert the BString to lowercase. + \return This method always returns \c *this . */ /*! -\fn BString& BString::ToUpper() -\brief Convert the BString to uppercase. -\return This method always returns \c *this . + \fn BString& BString::ToUpper() + \brief Convert the BString to uppercase. + \return This method always returns \c *this . */ /*! -\fn BString& BString::Capitalize() -\brief Convert the first character to uppercase, rest to lowercase -\return This method always returns \c *this . + \fn BString& BString::Capitalize() + \brief Convert the first character to uppercase, rest to lowercase + \return This method always returns \c *this . */ /*! -\fn BString& BString::CapitalizeEachWord() -\brief Convert the first character of every word to uppercase, rest to lowercase. + \fn BString& BString::CapitalizeEachWord() + \brief Convert the first character of every word to uppercase, rest + to lowercase. -Converts the first character of every "word" (series of alphabetical characters -separated by non alphabetical characters) to uppercase, and the rest to lowercase. -\return This method always returns \c *this . + Converts the first character of every "word" (series of alphabetical + characters separated by non alphabetical characters) to uppercase, and + the rest to lowercase. + + \return This method always returns \c *this . */ //! @} /*! -\name Escaping and Deescaping Methods + \name Escaping and Deescaping Methods -This class contains some methods to help you with escaping and de-escaping -certain characters. Note that this is the C-style of escaping, where you place a character -before the character that is to be escaped, and not HTML style escaping, -where certain characters are replaced by something else. + This class contains some methods to help you with escaping and + de-escaping certain characters. Note that this is the C-style of + escaping, where you place a character before the character that is + to be escaped, and not HTML style escaping, where certain characters + are replaced by something else. */ //! @{ /*! -\fn BString& BString::CharacterEscape(const char *original, const char *setOfCharsToEscape, char escapeWith) -\brief Escape selected characters on a given string. + \fn BString& BString::CharacterEscape(const char *original, + const char *setOfCharsToEscape, char escapeWith) + \brief Escape selected characters on a given string. -This version sets itself to the string supplied in the \c original paramater, and -then escapes the selected characters with a supplied character. + This version sets itself to the string supplied in the \c original + paramater, and then escapes the selected characters with a supplied + character. -\param original The string to be escaped. -\param setOfCharsToEscape The set of characters that need to be escaped. -\param escapeWith The character to escape with. -\return This method always returns \c *this. -\sa CharacterDeescape(char escapeChar) -\sa CharacterDeescape(const char *original, char escapeChar) + \param original The string to be escaped. + \param setOfCharsToEscape The set of characters that need to be escaped. + \param escapeWith The character to escape with. + + \return This method always returns \c *this. + + \sa CharacterDeescape(char escapeChar) + \sa CharacterDeescape(const char *original, char escapeChar) */ /*! -\fn BString& BString::CharacterEscape(const char *setOfCharsToEscape, char escapeWith) -\brief Escape selected characters of this string. -\param setOfCharsToEscape The set of characters that need to be escaped. -\param escapeWith The character to escape with. -\return This method always returns \c *this. -\sa CharacterDeescape(char escapeChar) + \fn BString& BString::CharacterEscape(const char *setOfCharsToEscape, + char escapeWith) + \brief Escape selected characters of this string. + + \param setOfCharsToEscape The set of characters that need to be escaped. + \param escapeWith The character to escape with. + + \return This method always returns \c *this. + + \sa CharacterDeescape(char escapeChar) */ /*! -\fn BString& BString::CharacterDeescape(const char *original, char escapeChar) -\brief Remove the character to escape with from a given string. + \fn BString& BString::CharacterDeescape(const char *original, + char escapeChar) + \brief Remove the character to escape with from a given string. -This version sets itself to the string supplied in the \c original parameter, and -then removes the escape characters. + This version sets itself to the string supplied in the \c original + parameter, and then removes the escape characters. -\param original The string to be escaped. -\param escapeChar The character that was used to escape with. -\return This method always returns \c *this. -\sa CharacterEscape(const char *original, const char *setOfCharsToEscape, char escapeWith) + \param original The string to be escaped. + \param escapeChar The character that was used to escape with. + + \return This method always returns \c *this. + + \sa CharacterEscape(const char *original, const char *setOfCharsToEscape, + char escapeWith) */ /*! -\fn BString& BString::CharacterDeescape(char escapeChar) -\brief Remove the character to escape with from this string. -\param escapeChar The character that was used to escape with. -\return This method always returns \c *this. -\sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) + \fn BString& BString::CharacterDeescape(char escapeChar) + \brief Remove the character to escape with from this string. + + \param escapeChar The character that was used to escape with. + + \return This method always returns \c *this. + + \sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) */ //! @} -/*! -\name Simple sprintf Replacement Methods +/*! + \name Simple sprintf Replacement Methods -These methods may be slower than sprintf(), but they are overflow safe. + These methods may be slower than sprintf(), but they are overflow safe. */ //! @{ /*! -\fn BString& BString::operator<<(const char *str) -\brief Append the string \c str to the object. + \fn BString& BString::operator<<(const char *str) + \brief Append the string \a str. */ /*! -\fn BString& BString::operator<<(const BString &string) -\brief Append the string \c string to the object. + \fn BString& BString::operator<<(const BString &string) + \brief Append the BString \a string. */ /*! -\fn BString& BString::operator<<(char c) -\brief Append the character \c c to the object. + \fn BString& BString::operator<<(char c) + \brief Append the \c char \a c. */ /*! -\fn BString& BString::operator<<(int i) -\brief Convert the integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(int i) + \brief Convert the \c int \a i to a string and append it. */ /*! -\fn BString& BString::operator<<(unsigned int i) -\brief Convert the unsigned integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(unsigned int i) + \brief Convert the \c unsigned \c int \a i to a string and append it. */ /*! -\fn BString& BString::operator<<(uint32 i) -\brief Convert the unsigned integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(unsigned long i) + \brief Convert the \c unsigned \c long \a i to a string and append it. */ /*! -\fn BString& BString::operator<<(int32 i) -\brief Convert the integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(long i) + \brief Convert the \c long \a i to a string and append it. */ /*! -\fn BString& BString::operator<<(uint64 i) -\brief Convert the unsigned integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(unsigned long long i) + \brief Convert the \c unsigned \c long \c long \a i to a string and + append it. */ /*! -\fn BString& BString::operator<<(int64 i) -\brief Convert the integer \c i to a string and append it to the object. + \fn BString& BString::operator<<(long long i) + \brief Convert the \c long \c long \a i to a string and append it. */ /*! -\fn BString& BString::operator<<(float f) -\brief Convert the float \c f to a string and append it to the object. + \fn BString& BString::operator<<(float f) + \brief Convert the \c float \a f to a string and append it. */ //! @} -/************************ end of class BString, start of general operators ************/ + +/************* end of class BString, start of general operators ************/ /*! -\addtogroup support_globals -@{ + \addtogroup support_globals */ +//! @{ /*! -\fn bool operator<(const char *a, const BString &b) -\brief Lexographically compare if \c a is less than a given BString. + \fn bool operator<(const char *a, const BString &b) + \brief Lexographically compare if \c a is less than a given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator<(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator<(const char *string) const */ /*! -\fn bool operator<=(const char *a, const BString &b) -\brief Lexographically compare if \c a is less than or equal to a given BString. + \fn bool operator<=(const char *a, const BString &b) + \brief Lexographically compare if \c a is less than or equal to a + given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator<=(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator<=(const char *string) const */ /*! -\fn bool operator==(const char *a, const BString &b) -\brief Lexographically compare if \c a is equal to a given BString. + \fn bool operator==(const char *a, const BString &b) + \brief Lexographically compare if \c a is equal to a given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator==(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator==(const char *string) const */ /*! -\fn bool operator>(const char *a, const BString &b) -\brief Lexographically compare if \c a is more than a given BString. + \fn bool operator>(const char *a, const BString &b) + \brief Lexographically compare if \c a is more than a given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator>(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator>(const char *string) const */ /*! -\fn bool operator>=(const char *a, const BString &b) -\brief Lexographically compare if \c a is more than or equal to a given BString. + \fn bool operator>=(const char *a, const BString &b) + \brief Lexographically compare if \c a is more than or equal to a + given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator>=(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator>=(const char *string) const */ /*! -\fn bool operator!=(const char *a, const BString &b) -\brief Lexographically compare if \c a is not equal to given BString. + \fn bool operator!=(const char *a, const BString &b) + \brief Lexographically compare if \c a is not equal to given BString. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::operator!=(const char *string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::operator!=(const char *string) const */ /*! -\fn int Compare(const BString &, const BString &) -\brief Lexographically compare two strings. + \fn int Compare(const BString &a, const BString &b) + \brief Lexographically compare two strings. -This function is useful if you need a global compare function to feed to -BList::SortItems() for example. + This function is useful if you need a global compare function to feed to + BList::SortItems() for example. -From String.h and in libbe.so. + \param a The first string to compare. + \param b The second string to compare. -\sa BString::Compare(const BString &string) const + From String.h and in libbe.so. + + \sa BString::Compare(const BString &string) const */ /*! -\fn int ICompare(const BString &, const BString &) -\brief Lexographically compare two strings in a case insensitive way. + \fn int ICompare(const BString &a, const BString &b) + \brief Lexographically compare two strings in a case insensitive way. -This function is useful if you need a global compare function to feed to -BList::SortItems() for example. + This function is useful if you need a global compare function to feed to + BList::SortItems() for example. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::Compare(const BString &string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::Compare(const BString &string) const */ /*! -\fn int Compare(const BString *, const BString *) -\brief Lexographically compare two strings. + \fn int Compare(const BString *a, const BString *b) + \brief Lexographically compare two strings. -This function is useful if you need a global compare function to feed to -BList::SortItems() for example. + This function is useful if you need a global compare function to feed to + BList::SortItems() for example. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::Compare(const BString &string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::Compare(const BString &string) const */ /*! -\fn int ICompare(const BString *, const BString *) -\brief Lexographically compare two strings in a case insensitive way. + \fn int ICompare(const BString *a, const BString *b) + \brief Lexographically compare two strings in a case insensitive way. -This function is useful if you need a global compare function to feed to -BList::SortItems() for example. + This function is useful if you need a global compare function to feed to + BList::SortItems() for example. -From String.h and in libbe.so. + From String.h and in libbe.so. -\sa BString::Compare(const BString &string) const + \param a The first string to compare. + \param b The second string to compare. + + \sa BString::Compare(const BString &string) const */ //! @} +