docs/user/interface/IconUtils.dox

   1 /*
   2  * Copyright 2011 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Adrien Destugues, pulkomandy@pulkomandy.ath.cx
   7  *
   8  * Corresponds to:
   9  *              headers/os/interface/IconUtils.h        rev 42600
  10  *              src/kits/interface/IconUtils.cpp        rev 42600
  11  */
  12
  13
  14 /*!
  15         \file IconUtils.h
  16         \ingroup interface
  17         \ingroup libbe
  18         \brief Vector icon handling utility class
  19 */
  20
  21
  22 /*!
  23         \class BIconUtils
  24         \ingroup interface
  25         \ingroup libbe
  26         \brief The BIconUtils class provide utility methods for managing and
  27                 drawing vector icons.
  28
  29         Haiku icons are stored in the HVIF (Haiku Vector Icon Format). This format
  30         was designed specifically for this purpose, and allows the icon data to be
  31         small enough to fit in file's inodes. This way, the icon can be displayed
  32         like any other file attribute, without extra disk access.
  33
  34         This class provide only static methods to allow access to the icon data and
  35         rendering to BBitmaps for later use in an application. It also supports
  36         older icons in bitmap format. These may still be useful at very small
  37         sizes. Note you can't create an instance of BIconUtils, just call the
  38         static methods.
  39
  40         \since Haiku R1
  41 */
  42
  43
  44 /*!
  45         \fn static status_t BIconUtils::GetIcon(BNode* node,
  46                 const char* vectorIconAttrName, const char* smallIconAttrName,
  47                 const char* largeIconAttrName, icon_size size, BBitmap* result)
  48         \brief Utility function to import an icon from a node.
  49
  50         Utility function to import an icon from the node that
  51         has either of the provided attribute names. Which icon type
  52         is preferred (vector, small or large B_CMAP8 icon) depends
  53         on the colorspace of the provided bitmap.
  54
  55         \note If the colorspace is B_CMAP8, B_CMAP8 icons are preferred. In that
  56                 case, the bitmap size must also match the provided icon_size "size"!
  57
  58         \since Haiku R1
  59 */
  60
  61
  62 /*!
  63         \fn static status_t BIconUtils::GetVectorIcon(BNode* node,
  64                 const char* attrName, BBitmap* result)
  65         \brief Utility function to import a vector icon in "flat icon" format.
  66
  67         Utility function to import a vector icon in "flat icon"
  68         format from a BNode attribute into the preallocated BBitmap \a result.
  69         The colorspace of result needs to be B_RGBA32 or at
  70         least B_RGB32 (though that makes less sense). The icon
  71         will be scaled from its "native" size of 64x64 to the
  72         size of the bitmap.
  73
  74         \note The scale is derived from the bitmap width, the bitmap should have
  75                 square dimension, or the icon will be cut off at the bottom (or have
  76                 room left).
  77
  78         \since Haiku R1
  79 */
  80
  81
  82 /*!
  83         \fn static status_t BIconUtils::GetVectorIcon(const uint8* buffer,
  84                 size_t size, BBitmap* result)
  85         \brief Utility function to import a vector icon in "flat icon" format.
  86
  87         Utility function to import a vector icon in "flat icon"
  88         format from the given \a buffer into the preallocated BBitmap \a result.
  89         The colorspace of result needs to be B_RGBA32 or at
  90         least B_RGB32 (though that makes less sense). The icon
  91         will be scaled from its "native" size of 64x64 to the
  92         size of the bitmap.
  93
  94         \note The scale is derived from the bitmap width, the bitmap should have
  95                 square dimension, or the icon will be cut off at the bottom (or have
  96                 room left).
  97
  98         \since Haiku R1
  99 */
 100
 101
 102 /*!
 103         \fn static status_t BIconUtils::GetCMAP8Icon(BNode* node,
 104                 const char* smallIconAttrName, const char* largeIconAttrName,
 105                 icon_size size, BBitmap* icon)
 106         \brief Utility function to import an "old" BeOS icon in B_CMAP8 colorspace.
 107
 108         Utility function to import an "old" BeOS icon in B_CMAP8 colorspace from
 109         either the small icon attribute or the large icon attribute as given in
 110         \a smallIconAttrName and \a largeIconAttrName. Which icon is loaded depends
 111         on the given \a size.
 112
 113         \since Haiku R1
 114 */
 115
 116
 117 /*!
 118         \fn static status_t BIconUtils::ConvertFromCMAP8(BBitmap* source,
 119                 BBitmap* result)
 120         \brief Converts an old-style icon to another colorspace.
 121
 122         Utility function to convert from old icon colorspace into colorspace of
 123         BBitmap \a result
 124
 125         \note result should be in B_RGBA32 colorspace, and source in B_CMAP8.
 126
 127         \since Haiku R1
 128 */
 129
 130
 131 /*!
 132         \fn static status_t BIconUtils::ConvertToCMAP8(BBitmap* source,
 133                 BBitmap* result)
 134         \brief Converts a true-color icon to CMAP8 colorspace.
 135
 136         Utility function to convert data from source into \a result colorspace.
 137         Call this to convert a picture to a format suitable for storage as an
 138         old-style icon.
 139
 140         \note result should be in B_CMAP8 colorspace, and source in B_RGBA32.
 141
 142         \since Haiku R1
 143 */
 144
 145
 146 /*!
 147         \fn static status_t BIconUtils::ConvertFromCMAP8(const uint8* data,
 148                 uint32 width, uint32 height, uint32 bytesPerRow, BBitmap* result);
 149         \brief Convert raw data in B_CMAP8 colorspace to a B_RGBA32 BBitmap.
 150
 151         \since Haiku R1
 152 */
 153
 154
 155 /*!
 156         \fn static status_t BIconUtils::ConvertToCMAP8(const uint8* data,
 157                 uint32 width, uint32 height, uint32 bytesPerRow, BBitmap* result);
 158         \brief Convert B_RGBA32 raw data into a B_CMAP8 BBitmap.
 159
 160         \since Haiku R1
 161 */