From ca2c99c2ca940f16d97e55d59113b0b19a0d7b5a Mon Sep 17 00:00:00 2001 From: Adrien Destugues Date: Tue, 9 Aug 2011 19:31:46 +0000 Subject: [PATCH] * Add BIconUtils documentation to the Haiku Book * Remove comments from the header itself. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42606 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- docs/user/interface/IconUtils.dox | 127 ++++++++++++++++++++++++++++++ headers/os/interface/IconUtils.h | 27 ------- 2 files changed, 127 insertions(+), 27 deletions(-) create mode 100644 docs/user/interface/IconUtils.dox diff --git a/docs/user/interface/IconUtils.dox b/docs/user/interface/IconUtils.dox new file mode 100644 index 0000000000..15d838f70f --- /dev/null +++ b/docs/user/interface/IconUtils.dox @@ -0,0 +1,127 @@ +/* + * Copyright 2011, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Adrien Destugues + * Corresponds to: + * /trunk/headers/os/interface/IconUtils.h rev 42600 + * /trunk/src/kits/interface/IconUtils.cpp rev 42600 + */ + + +/*! +\file IconUtils.h +\brief Vector icon handling utility class +*/ + + +/*! \class BIconUtils + \ingroup interface + \ingroup libbe + \brief The BIconUtils class provide utility methods for managing and + drawing vector icons. + + Haiku icons are stored in the HVIF (Haiku Vector Icon Format). This format + was designed specifically for this purpose, and allows the icon data to be + small enough to fit in file's inodes. This way, the icon can be displayed + like any other file attribute, without extra disk access. + + This class provide only static methods to allow access to the icon data and + rendering to BBitmaps for later use in an application. It also supports + older icons in bitmap format. These may still be useful at very small + sizes. Note you can't create an instance of BIconUtils, just call the + static methods. +*/ + + +/*! \fn static status_t BIconUtils::GetIcon(BNode* node, + const char* vectorIconAttrName, const char* smallIconAttrName, + const char* largeIconAttrName, icon_size size, BBitmap* result) + \brief Utility function to import an icon from a node. + + Utility function to import an icon from the node that + has either of the provided attribute names. Which icon type + is preferred (vector, small or large B_CMAP8 icon) depends + on the colorspace of the provided bitmap. + + \note If the colorspace is B_CMAP8, B_CMAP8 icons are preferred. In that + case, the bitmap size must also match the provided icon_size "size"! +*/ + + +/*! \fn static status_t BIconUtils::GetVectorIcon(BNode* node, + const char* attrName, BBitmap* result) + \brief Utility function to import a vector icon in "flat icon" format. + + Utility function to import a vector icon in "flat icon" + format from a BNode attribute into the preallocated BBitmap \a result. + The colorspace of result needs to be B_RGBA32 or at + least B_RGB32 (though that makes less sense). The icon + will be scaled from it's "native" size of 64x64 to the + size of the bitmap. + + \note The scale is derived from the bitmap width, the bitmap should have + square dimension, or the icon will be cut off at the bottom (or have + room left). +*/ + + +/*! \fn static status_t BIconUtils::GetVectorIcon(const uint8* buffer, + const char* attrName, BBitmap* result) + \brief Utility function to import a vector icon in "flat icon" format. + + Utility function to import a vector icon in "flat icon" + format from the given \a buffer into the preallocated BBitmap \a result. + The colorspace of result needs to be B_RGBA32 or at + least B_RGB32 (though that makes less sense). The icon + will be scaled from it's "native" size of 64x64 to the + size of the bitmap. + + \note The scale is derived from the bitmap width, the bitmap should have + square dimension, or the icon will be cut off at the bottom (or have + room left). +*/ + + +/*! \fn static status_t BIconUtils::GetCMAP8Icon(BNode* node, + const char* smallIconAttrName, const char* largeIconAttrName, + icon_size size, BBitmap* icon) + \brief Utility function to import an "old" BeOS icon in B_CMAP8 colorspace. + + Utility function to import an "old" BeOS icon in B_CMAP8 colorspace from + either the small icon attribute or the large icon attribute as given in + \a smallIconAttrName and \a largeIconAttrName. Which icon is loaded depends + on the given \a size. +*/ + + +/*! \fn static status_t BIconUtils::ConvertFromCMAP8(BBitmap* source, BBitmap* result) + \brief Converts an old-style icon to another colorspace. + + Utility function to convert from old icon colorspace into colorspace of + BBitmap \a result + + \note result should be in B_RGBA32 colorspace, and source in B_CMAP8. +*/ + + +/*! \fn static status_t BIconUtils::ConvertToCMAP8(BBitmap* source, BBitmap* result) + \brief Converts a true-color icon to CMAP8 colorspace. + + Utility function to convert data from source into \a result colorspace. + Call this to convert a picture to a format suitable for storage as an + old-style icon. + + \note result should be in B_CMAP8 colorspace, and source in B_RGBA32. +*/ + +/*! \fn static status_t BIconUtil::ConvertFromCMAP8(const uint8* data, uint32 width, + uint32 height, uint32 bytesPerRow, BBitmap* result); + \brief Convert raw data in B_CMAP8 colorspace to a B_RGBA32 BBitmap. +*/ + +/*! \fn static status_t BIconUtils::ConvertToCMAP8(const uint8* data, uint32 width, + uint32 height, uint32 bytesPerRow, BBitmap* result); + \brief Convert B_RGBA32 raw data into a B_CMAP8 BBitmap. +*/ diff --git a/headers/os/interface/IconUtils.h b/headers/os/interface/IconUtils.h index fdcfbd946f..cbb3a030f0 100644 --- a/headers/os/interface/IconUtils.h +++ b/headers/os/interface/IconUtils.h @@ -12,9 +12,6 @@ class BBitmap; class BNode; -// This class is a little different from many other classes. -// You don't create an instance of it; you just call its various -// static member functions for utility-like operations. class BIconUtils { BIconUtils(); ~BIconUtils(); @@ -22,47 +19,23 @@ class BIconUtils { BIconUtils& operator=(const BIconUtils&); public: - - // Utility function to import an icon from the node that - // has either of the provided attribute names. Which icon type - // is preferred (vector, small or large B_CMAP8 icon) depends - // on the colorspace of the provided bitmap. If the colorspace - // is B_CMAP8, B_CMAP8 icons are preferred. In that case, the - // bitmap size must also match the provided icon_size "size"! static status_t GetIcon(BNode* node, const char* vectorIconAttrName, const char* smallIconAttrName, const char* largeIconAttrName, icon_size size, BBitmap* result); - // Utility functions to import a vector icon in "flat icon" - // format from a BNode attribute or from a flat buffer in - // memory into the preallocated BBitmap "result". - // The colorspace of result needs to be B_RGBA32 or at - // least B_RGB32 (though that makes less sense). The icon - // will be scaled from it's "native" size of 64x64 to the - // size of the bitmap, the scale is derived from the bitmap - // width, the bitmap should have square dimension, or the - // icon will be cut off at the bottom (or have room left). static status_t GetVectorIcon(BNode* node, const char* attrName, BBitmap* result); static status_t GetVectorIcon(const uint8* buffer, size_t size, BBitmap* result); - // Utility function to import an "old" BeOS icon in B_CMAP8 - // colorspace from either the small icon attribute or the - // large icon attribute as given in "smallIconAttrName" and - // "largeIconAttrName". Which icon is loaded depends on - // the given "size". static status_t GetCMAP8Icon(BNode* node, const char* smallIconAttrName, const char* largeIconAttrName, icon_size size, BBitmap* icon); - // Utility functions to convert from old icon colorspace - // into colorspace of BBitmap "result" (should be B_RGBA32 - // to make any sense). static status_t ConvertFromCMAP8(BBitmap* source, BBitmap* result); static status_t ConvertToCMAP8(BBitmap* source,