1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qbitmap.h"

    43 #include "qpixmapdata_p.h"

    44 #include "qimage.h"

    45 #include "qvariant.h"

    46 #include <qpainter.h>

    47 #include <private/qgraphicssystem_p.h>

    48 #include <private/qapplication_p.h>

    49 

    50 QT_BEGIN_NAMESPACE

    51 

    52 /*!

    53     \class QBitmap

    54     \brief The QBitmap class provides monochrome (1-bit depth) pixmaps.

    55 

    56     \ingroup painting

    57     \ingroup shared

    58 

    59     The QBitmap class is a monochrome off-screen paint device used

    60     mainly for creating custom QCursor and QBrush objects,

    61     constructing QRegion objects, and for setting masks for pixmaps

    62     and widgets.

    63 

    64     QBitmap is a QPixmap subclass ensuring a depth of 1, except for

    65     null objects which have a depth of 0. If a pixmap with a depth

    66     greater than 1 is assigned to a bitmap, the bitmap will be

    67     dithered automatically.

    68 

    69     Use the QColor objects Qt::color0 and Qt::color1 when drawing on a

    70     QBitmap object (or a QPixmap object with depth 1).

    71 

    72     Painting with Qt::color0 sets the bitmap bits to 0, and painting

    73     with Qt::color1 sets the bits to 1. For a bitmap, 0-bits indicate

    74     background (or transparent pixels) and 1-bits indicate foreground

    75     (or opaque pixels). Use the clear() function to set all the bits

    76     to Qt::color0. Note that using the Qt::black and Qt::white colors

    77     make no sense because the QColor::pixel() value is not necessarily

    78     0 for black and 1 for white.

    79 

    80     The QBitmap class provides the transformed() function returning a

    81     transformed copy of the bitmap; use the QTransform argument to

    82     translate, scale, shear, and rotate the bitmap. In addition,

    83     QBitmap provides the static fromData() function which returns a

    84     bitmap constructed from the given \c uchar data, and the static

    85     fromImage() function returning a converted copy of a QImage

    86     object.

    87 

    88     Just like the QPixmap class, QBitmap is optimized by the use of

    89     implicit data sharing. For more information, see the {Implicit

    90     Data Sharing} documentation.

    91 

    92     \sa  QPixmap, QImage, QImageReader, QImageWriter

    93 */

    94 

    95 /*! \typedef QBitmap::DataPtr

    96   \internal

    97  */

    98 

    99 /*!

   100     Constructs a null bitmap.

   101 

   102     \sa QPixmap::isNull()

   103 */

   104 QBitmap::QBitmap()

   105     : QPixmap(QSize(0, 0), QPixmapData::BitmapType)

   106 {

   107 }

   108 

   109 /*!

   110     \fn QBitmap::QBitmap(int width, int height)

   111 

   112     Constructs a bitmap with the given \a width and \a height. The pixels

   113     inside are uninitialized.

   114 

   115     \sa clear()

   116 */

   117 

   118 QBitmap::QBitmap(int w, int h)

   119     : QPixmap(QSize(w, h), QPixmapData::BitmapType)

   120 {

   121 }

   122 

   123 /*!

   124     Constructs a bitmap with the given \a size.  The pixels in the

   125     bitmap are uninitialized.

   126 

   127     \sa clear()

   128 */

   129 

   130 QBitmap::QBitmap(const QSize &size)

   131     : QPixmap(size, QPixmapData::BitmapType)

   132 {

   133 }

   134 

   135 /*!

   136     \fn QBitmap::clear()

   137 

   138     Clears the bitmap, setting all its bits to Qt::color0.

   139 */

   140 

   141 /*!

   142     Constructs a bitmap that is a copy of the given \a pixmap.

   143 

   144     If the pixmap has a depth greater than 1, the resulting bitmap

   145     will be dithered automatically.

   146 

   147     \sa QPixmap::depth(), fromImage(), fromData()

   148 */

   149 

   150 QBitmap::QBitmap(const QPixmap &pixmap)

   151 {

   152     QBitmap::operator=(pixmap);

   153 }

   154 

   155 /*!

   156     \fn QBitmap::QBitmap(const QImage &image)

   157 

   158     Constructs a bitmap that is a copy of the given \a image.

   159 

   160     Use the static fromImage() function instead.

   161 */

   162 

   163 /*!

   164     Constructs a bitmap from the file specified by the given \a

   165     fileName. If the file does not exist, or has an unknown format,

   166     the bitmap becomes a null bitmap.

   167 

   168     The \a fileName and \a format parameters are passed on to the

   169     QPixmap::load() function. If the file format uses more than 1 bit

   170     per pixel, the resulting bitmap will be dithered automatically.

   171 

   172     \sa QPixmap::isNull(), QImageReader::imageFormat()

   173 */

   174 

   175 QBitmap::QBitmap(const QString& fileName, const char *format)

   176     : QPixmap(QSize(0, 0), QPixmapData::BitmapType)

   177 {

   178     load(fileName, format, Qt::MonoOnly);

   179 }

   180 

   181 /*!

   182     \overload

   183 

   184     Assigns the given \a pixmap to this bitmap and returns a reference

   185     to this bitmap.

   186 

   187     If the pixmap has a depth greater than 1, the resulting bitmap

   188     will be dithered automatically.

   189 

   190     \sa QPixmap::depth()

   191  */

   192 

   193 QBitmap &QBitmap::operator=(const QPixmap &pixmap)

   194 {

   195     if (pixmap.isNull()) {                        // a null pixmap

   196         QBitmap bm(0, 0);

   197         QBitmap::operator=(bm);

   198     } else if (pixmap.depth() == 1) {                // 1-bit pixmap

   199         QPixmap::operator=(pixmap);                // shallow assignment

   200     } else {                                        // n-bit depth pixmap

   201         QImage image;

   202         image = pixmap.toImage();                                // convert pixmap to image

   203         *this = fromImage(image);                                // will dither image

   204     }

   205     return *this;

   206 }

   207 

   208 

   209 #ifdef QT3_SUPPORT

   210 QBitmap::QBitmap(int w, int h, const uchar *bits, bool isXbitmap)

   211 {

   212     *this = fromData(QSize(w, h), bits, isXbitmap ? QImage::Format_MonoLSB : QImage::Format_Mono);

   213 }

   214 

   215 

   216 QBitmap::QBitmap(const QSize &size, const uchar *bits, bool isXbitmap)

   217 {

   218     *this = fromData(size, bits, isXbitmap ? QImage::Format_MonoLSB : QImage::Format_Mono);

   219 }

   220 #endif

   221 

   222 /*!

   223   Destroys the bitmap.

   224 */

   225 QBitmap::~QBitmap()

   226 {

   227 }

   228 

   229 /*!

   230    Returns the bitmap as a QVariant.

   231 */

   232 QBitmap::operator QVariant() const

   233 {

   234     return QVariant(QVariant::Bitmap, this);

   235 }

   236 

   237 /*!

   238     \fn QBitmap &QBitmap::operator=(const QImage &image)

   239     \overload

   240 

   241     Converts the given \a image to a bitmap, and assigns the result to

   242     this bitmap. Returns a reference to the bitmap.

   243 

   244     Use the static fromImage() function instead.

   245 */

   246 

   247 /*!

   248     Returns a copy of the given \a image converted to a bitmap using

   249     the specified image conversion \a flags.

   250 

   251     \sa fromData()

   252 */

   253 QBitmap QBitmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags)

   254 {

   255     if (image.isNull())

   256         return QBitmap();

   257 

   258     QImage img = image.convertToFormat(QImage::Format_MonoLSB, flags);

   259 

   260     // make sure image.color(0) == Qt::color0 (white)

   261     // and image.color(1) == Qt::color1 (black)

   262     const QRgb c0 = QColor(Qt::black).rgb();

   263     const QRgb c1 = QColor(Qt::white).rgb();

   264     if (img.color(0) == c0 && img.color(1) == c1) {

   265         img.invertPixels();

   266         img.setColor(0, c1);

   267         img.setColor(1, c0);

   268     }

   269 

   270     QGraphicsSystem* gs = QApplicationPrivate::graphicsSystem();

   271     QScopedPointer<QPixmapData> data(gs ? gs->createPixmapData(QPixmapData::BitmapType)

   272                 : QGraphicsSystem::createDefaultPixmapData(QPixmapData::BitmapType));

   273 

   274     data->fromImage(img, flags | Qt::MonoOnly);

   275     return QPixmap(data.take());

   276 }

   277 

   278 /*!

   279     Constructs a bitmap with the given \a size, and sets the contents to

   280     the \a bits supplied.

   281 

   282     The bitmap data has to be byte aligned and provided in in the bit

   283     order specified by \a monoFormat. The mono format must be either

   284     QImage::Format_Mono or QImage::Format_MonoLSB. Use

   285     QImage::Format_Mono to specify data on the XBM format.

   286 

   287     \sa fromImage()

   288 

   289 */

   290 QBitmap QBitmap::fromData(const QSize &size, const uchar *bits, QImage::Format monoFormat)

   291 {

   292     Q_ASSERT(monoFormat == QImage::Format_Mono || monoFormat == QImage::Format_MonoLSB);

   293 

   294     QImage image(size, monoFormat);

   295     image.setColor(0, QColor(Qt::color0).rgb());

   296     image.setColor(1, QColor(Qt::color1).rgb());

   297 

   298     // Need to memcpy each line separatly since QImage is 32bit aligned and

   299     // this data is only byte aligned...

   300     int bytesPerLine = (size.width() + 7) / 8;

   301     for (int y = 0; y < size.height(); ++y)

   302         memcpy(image.scanLine(y), bits + bytesPerLine * y, bytesPerLine);

   303     return QBitmap::fromImage(image);

   304 }

   305 

   306 /*!

   307     Returns a copy of this bitmap, transformed according to the given

   308     \a matrix.

   309 

   310     \sa QPixmap::transformed()

   311  */

   312 QBitmap QBitmap::transformed(const QTransform &matrix) const

   313 {

   314     QBitmap bm = QPixmap::transformed(matrix);

   315     return bm;

   316 }

   317 

   318 /*!

   319   \overload

   320   \obsolete

   321 

   322   This convenience function converts the \a matrix to a QTransform

   323   and calls the overloaded function.

   324 */

   325 QBitmap QBitmap::transformed(const QMatrix &matrix) const

   326 {

   327     return transformed(QTransform(matrix));

   328 }

   329 

   330 #ifdef QT3_SUPPORT

   331 /*!

   332     \fn QBitmap QBitmap::xForm(const QMatrix &matrix) const

   333 

   334     Returns a copy of this bitmap, transformed according to the given

   335     \a matrix.

   336 

   337     Use transformed() instead.

   338 */

   339 

   340 /*!

   341     \fn QBitmap::QBitmap(const QSize &size, bool clear)

   342 

   343     Constructs a bitmap with the given \a size. If \a clear is true,

   344     the bits are initialized to Qt::color0.

   345 

   346     Use the corresponding QBitmap() constructor instead, and then call

   347     the clear() function if the \a clear parameter is true.

   348 */

   349 

   350 /*!

   351     \fn QBitmap::QBitmap(int width, int height, bool clear)

   352 

   353     Constructs a bitmap with the given \a width and \a height.  If \a

   354     clear is true, the bits are initialized to Qt::color0.

   355 

   356     Use the corresponding QBitmap() constructor instead, and then call

   357     the clear() function if the \a clear parameter is true.

   358 */

   359 

   360 /*!

   361     \fn QBitmap::QBitmap(int width, int height, const uchar *bits, bool isXbitmap)

   362 

   363     Constructs a bitmap with the given \a width and \a height, and

   364     sets the contents to the \a bits supplied. The \a isXbitmap flag

   365     should be true if \a bits was generated by the X11 bitmap

   366     program.

   367 

   368     Use the static fromData() function instead. If \a isXbitmap is

   369     true, use the default bit order(QImage_FormatMonoLSB) otherwise

   370     use QImage::Format_Mono.

   371 

   372     \omit

   373     The X bitmap bit order is little endian.  The QImage

   374     documentation discusses bit order of monochrome images. Opposed to

   375     QImage, the data has to be byte aligned.

   376 

   377     Example (creates an arrow bitmap):

   378     \snippet doc/src/snippets/code/src_gui_image_qbitmap.cpp 0

   379     \endomit

   380 */

   381 

   382 

   383 /*!

   384   \fn QBitmap::QBitmap(const QSize &size, const uchar *bits, bool isXbitmap)

   385 

   386     \overload

   387 

   388     Constructs a bitmap with the given \a size, and sets the contents

   389     to the \a bits supplied. The \a isXbitmap flag should be true if

   390     \a bits was generated by the X11 bitmap program.

   391 

   392     \omit

   393     The X bitmap bit order is little endian.  The QImage documentation

   394     discusses bit order of monochrome images.

   395     \endomit

   396 

   397     Use the static fromData() function instead. If \a isXbitmap is

   398     true, use the default bit order(QImage_FormatMonoLSB) otherwise

   399     use QImage::Format_Mono.

   400 */

   401 #endif

   402 

   403 QT_END_NAMESPACE