summaryrefslogtreecommitdiff
path: root/canvas/inc/canvas/canvastools.hxx
blob: 6c9fdfee484a593a1425784c7520df839fbb6292 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/

#ifndef INCLUDED_CANVAS_CANVASTOOLS_HXX
#define INCLUDED_CANVAS_CANVASTOOLS_HXX

#include <rtl/math.hxx>
#include <com/sun/star/uno/Reference.hxx>
#include <com/sun/star/uno/Sequence.hxx>
#include <com/sun/star/uno/RuntimeException.hpp>
#include <com/sun/star/lang/IllegalArgumentException.hpp>
#include <com/sun/star/lang/IndexOutOfBoundsException.hpp>
#include <osl/diagnose.h>
#include <rtl/ustring.hxx>

#include <string.h> // for strcmp
#include <vector>
#include <limits>
#include <algorithm>


namespace basegfx
{
    class B2DHomMatrix;
    class B2DRange;
    class B2IRange;
    class B2IPoint;
    class B2DPolyPolygon;
}

namespace com { namespace sun { namespace star { namespace geometry
{
    struct RealSize2D;
    struct IntegerSize2D;
    struct AffineMatrix2D;
    struct Matrix2D;
} } } }

namespace com { namespace sun { namespace star { namespace rendering
{
    struct RenderState;
    struct ViewState;
    struct IntegerBitmapLayout;
    class  XCanvas;
    struct Texture;
    class  XIntegerBitmapColorSpace;
    class  XPolyPolygon2D;

    bool operator==( const RenderState& rLHS,
                     const RenderState& rRHS );

    bool operator==( const ViewState& rLHS,
                     const ViewState& rRHS );
} } } }

namespace com { namespace sun { namespace star { namespace awt
{
    struct Rectangle;
    class  XWindow2;
} } } }

class Color;

namespace canvas
{
    namespace tools
    {
        /** Compute the next highest power of 2 of a 32-bit value

            Code devised by Sean Anderson, in good ole HAKMEM
            tradition.

            @return 1 << (lg(x - 1) + 1)
        */
        inline sal_uInt32 nextPow2( sal_uInt32 x )
        {
            --x;
            x |= x >> 1;
            x |= x >> 2;
            x |= x >> 4;
            x |= x >> 8;
            x |= x >> 16;

            return ++x;
        }

        /**
         *
         * Count the number of 1-bits of an n-bit value
         *
         */

        // mickey's math tricks...
        inline unsigned int pow2( unsigned int c ) { return 0x1 << c; }
        inline unsigned int mask( unsigned int c ) { return ((unsigned int)(-1)) / (pow2(pow2(c)) + 1); }
        inline unsigned int count( unsigned int x, unsigned int c ) { return ((x) & mask(c)) + (((x) >> (pow2(c))) & mask(c)); }
        template<typename T>
        inline unsigned int bitcount( T c ) {
            unsigned int nByteIndex = 0;
            unsigned int nNumBytes = sizeof(T)<<2;
            do {
                c=count(c,nByteIndex++);
                nNumBytes >>= 1;
            } while(nNumBytes);
            return c;
        }
        inline sal_uInt32 bitcount32( sal_uInt32 c ) {
            c=count(c,0);
            c=count(c,1);
            c=count(c,2);
            c=count(c,3);
            c=count(c,4);
            return c;
        }

        /** Round given floating point value down to next integer
         */
        inline sal_Int32 roundDown( const double& rVal )
        {
            return static_cast< sal_Int32 >( floor( rVal ) );
        }

        /** Round given floating point value up to next integer
         */
        inline sal_Int32 roundUp( const double& rVal )
        {
            return static_cast< sal_Int32 >( ceil( rVal ) );
        }

        /** Create a RealSize2D with both coordinate values set to +infinity
         */
        ::com::sun::star::geometry::RealSize2D createInfiniteSize2D();


        // View- and RenderState utilities
        // ===================================================================

        ::com::sun::star::rendering::RenderState&
            initRenderState( ::com::sun::star::rendering::RenderState&                      renderState );

        ::com::sun::star::rendering::ViewState&
            initViewState( ::com::sun::star::rendering::ViewState&                          viewState );

        ::basegfx::B2DHomMatrix&
            getViewStateTransform( ::basegfx::B2DHomMatrix&                                 transform,
                                   const ::com::sun::star::rendering::ViewState&            viewState );

        ::com::sun::star::rendering::ViewState&
            setViewStateTransform( ::com::sun::star::rendering::ViewState&                  viewState,
                                   const ::basegfx::B2DHomMatrix&                           transform );

        ::basegfx::B2DHomMatrix&
            getRenderStateTransform( ::basegfx::B2DHomMatrix&                               transform,
                                     const ::com::sun::star::rendering::RenderState&        renderState );

        ::com::sun::star::rendering::RenderState&
            setRenderStateTransform( ::com::sun::star::rendering::RenderState&              renderState,
                                     const ::basegfx::B2DHomMatrix&                         transform );

        ::com::sun::star::rendering::ViewState&
            appendToViewState( ::com::sun::star::rendering::ViewState&                      viewState,
                               const ::basegfx::B2DHomMatrix&                               transform );

        ::com::sun::star::rendering::RenderState&
            appendToRenderState( ::com::sun::star::rendering::RenderState&                  renderState,
                                 const ::basegfx::B2DHomMatrix&                             transform );

        ::com::sun::star::rendering::ViewState&
            prependToViewState( ::com::sun::star::rendering::ViewState&                     viewState,
                                const ::basegfx::B2DHomMatrix&                              transform );

        ::com::sun::star::rendering::RenderState&
            prependToRenderState( ::com::sun::star::rendering::RenderState&                 renderState,
                                  const ::basegfx::B2DHomMatrix&                            transform );

        ::basegfx::B2DHomMatrix&
            mergeViewAndRenderTransform( ::basegfx::B2DHomMatrix&                           transform,
                                         const ::com::sun::star::rendering::ViewState&      viewState,
                                         const ::com::sun::star::rendering::RenderState&    renderState );

        ::com::sun::star::rendering::ViewState&
            mergeViewAndRenderState( ::com::sun::star::rendering::ViewState&                resultViewState,
                                     const ::com::sun::star::rendering::ViewState&          viewState,
                                     const ::com::sun::star::rendering::RenderState&        renderState,
                                     const ::com::sun::star::uno::Reference<
                                         ::com::sun::star::rendering::XCanvas >&            xCanvas );


        // Matrix utilities
        // ===================================================================

        ::com::sun::star::geometry::AffineMatrix2D&
            setIdentityAffineMatrix2D( ::com::sun::star::geometry::AffineMatrix2D&  matrix );

        ::com::sun::star::geometry::Matrix2D&
            setIdentityMatrix2D( ::com::sun::star::geometry::Matrix2D&              matrix );


        // Special utilities
        // ===================================================================

        /** Calc the bounding rectangle of a transformed rectangle.

            The method applies the given transformation to the
            specified input rectangle, and returns the bounding box of
            the resulting output area.

            @param o_Rect
            Output rectangle

            @param i_Rect
            Input rectangle

            @param i_Transformation
            Transformation to apply to the input rectangle

            @see calcRectToRectTransform()

            @return a reference to the resulting rectangle
         */
        ::basegfx::B2DRange& calcTransformedRectBounds( ::basegfx::B2DRange&            o_Rect,
                                                        const ::basegfx::B2DRange&      i_Rect,
                                                        const ::basegfx::B2DHomMatrix&  i_Transformation );

        /** Calc a transform that maps one rectangle on top of
            another.

            The method is a kissing cousin to
            calcTransformedRectBounds(). It can be used to modify the
            given transformation matrix, such that it transforms the
            given input rectangle to the given output rectangle,
            changing only translation and scale (if necessary). Thus,
            if you've calculated an output rectangle via
            calcTransformedRectBounds(), you can move and scale that
            rectangle as you like, and have this method calculate the
            required total transformation for it.

            @param o_transform
            Output parameter, to receive the resulting transformation
            matrix.

            @param i_destRect
            Input parameter, specifies the requested destination
            rectangle. The resulting transformation will exactly map
            the source rectangle to the destination rectangle.

            @param i_srcRect
            Input parameter, specifies the original source
            rectangle. The resulting transformation will exactly map
            the source rectangle to the destination rectangle.

            @param i_transformation
            The original transformation matrix. This is changed with
            translations and scalings (if necessary), to exactly map
            the source rectangle to the destination rectangle.

            @return a reference to the resulting transformation matrix

            @see calcTransformedRectBounds()
        */
        ::basegfx::B2DHomMatrix& calcRectToRectTransform( ::basegfx::B2DHomMatrix&          o_transform,
                                                          const ::basegfx::B2DRange&        i_destRect,
                                                          const ::basegfx::B2DRange&        i_srcRect,
                                                          const ::basegfx::B2DHomMatrix&    i_transformation );

        /** Calc a transform that maps the upper, left corner of a
             rectangle to the origin.

            The method is a specialized version of
            calcRectToRectTransform(), mapping the input rectangle's
            the upper, left corner to the origin, and leaving the size
            untouched.

            @param o_transform
            Output parameter, to receive the resulting transformation
            matrix.

            @param i_srcRect
            Input parameter, specifies the original source
            rectangle. The resulting transformation will exactly map
            the source rectangle's upper, left corner to the origin.

            @param i_transformation
            The original transformation matrix. This is changed with
            translations (if necessary), to exactly map the source
            rectangle to the origin.

            @return a reference to the resulting transformation matrix

            @see calcRectToRectTransform()
            @see calcTransformedRectBounds()
        */
        ::basegfx::B2DHomMatrix& calcRectToOriginTransform( ::basegfx::B2DHomMatrix&        o_transform,
                                                            const ::basegfx::B2DRange&      i_srcRect,
                                                            const ::basegfx::B2DHomMatrix&  i_transformation );

        /** Check whether a given rectangle is within another
            transformed rectangle.

            This method checks for polygonal containedness, i.e. the
            transformed rectangle is not represented as an axis-alignd
            rectangle anymore (like calcTransformedRectBounds()), but
            polygonal. Thus, the insideness test is based on tight
            bounds.

            @param rContainedRect
            This rectangle is checked, whether it is fully within the
            transformed rTransformRect.

            @param rTransformRect
            This rectangle is transformed, and then checked whether it
            fully contains rContainedRect.

            @param rTransformation
            This transformation is applied to rTransformRect
         */
        bool isInside( const ::basegfx::B2DRange&       rContainedRect,
                       const ::basegfx::B2DRange&       rTransformRect,
                       const ::basegfx::B2DHomMatrix&   rTransformation );

        /** Clip a scroll to the given bound rect

            @param io_rSourceArea
            Source area to scroll. The resulting clipped source area
            is returned therein.

            @param io_rDestPoint
            Destination point of the scroll (upper, left corner of
            rSourceArea after the scroll). The new, resulting
            destination point is returned therein.q

            @param o_ClippedAreas
            Vector of rectangles in the <em>destination</em> area
            coordinate system, which are clipped away from the source
            area, and thus need extra updates (i.e. they are not
            correctly copy from the scroll operation, since there was
            no information about them in the source).

            @param rBounds
            Bounds to clip against.

            @return false, if the resulting scroll area is empty
         */
        bool clipScrollArea( ::basegfx::B2IRange&                  io_rSourceArea,
                             ::basegfx::B2IPoint&                  io_rDestPoint,
                             ::std::vector< ::basegfx::B2IRange >& o_ClippedAreas,
                             const ::basegfx::B2IRange&            rBounds );

        /** Clip a blit between two differently surfaces.

            This method clips source and dest rect for a clip between
            two differently clipped surfaces, such that the resulting
            blit rects are fully within both clip areas.

            @param io_rSourceArea
            Source area of the blit. Returned therein is the computed
            clipped source area.

            @param io_rDestPoint
            Dest area of the blit. Returned therein is the computed
            clipped dest area.

            @param rSourceBounds
            Clip bounds of the source surface

            @param rDestBounds
            Clip bounds of the dest surface

            @return false, if the resulting blit is empty, i.e. fully
            clipped away.
         */
        bool clipBlit( ::basegfx::B2IRange&       io_rSourceArea,
                       ::basegfx::B2IPoint&       io_rDestPoint,
                       const ::basegfx::B2IRange& rSourceBounds,
                       const ::basegfx::B2IRange& rDestBounds );

        /** Return range of integer pixel, which will cover the sprite
            given by the floating point range.

            This method assumes that sprite sizes are always integer,
            and that the sprite position (top, left edge of the
            sprite) is rounded to the nearest integer before
            rendering.

            @param rRange
            Input range. Values must be within the representable
            bounds of sal_Int32

            @return the integer range, which is covered by the sprite
            given by rRange.
         */
        ::basegfx::B2IRange spritePixelAreaFromB2DRange( const ::basegfx::B2DRange& rRange );

        /** Retrieve various internal properties of the actual canvas implementation.

            This method retrieves a bunch of internal, implementation-
            and platform-dependent values from the canvas
            implementation. Among them are for example operating
            system window handles. The actual layout and content of
            the returned sequence is dependent on the component
            implementation, undocumented and subject to change.

            @param i_rxCanvas
            Input parameter, the canvas representation for which the device information
            is to be retrieveds

            @param o_rxParams
            Output parameter, the sequence of Anys that hold the device parameters. Layout is as described above

            @return A reference to the resulting sequence of parameters
        */
        ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& getDeviceInfo(
            const ::com::sun::star::uno::Reference< ::com::sun::star::rendering::XCanvas >& i_rxCanvas,
            ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& o_rxParams );

        /** Return a color space for a default RGBA integer format

            Use this method for dead-simple bitmap implementations,
            that map all their formats to 8888 RGBA color.
         */
        ::com::sun::star::uno::Reference< ::com::sun::star::rendering::XIntegerBitmapColorSpace> getStdColorSpace();

        /** Return a memory layout for a default RGBA integer format

            Use this method for dead-simple bitmap implementations,
            that map all their formats to 8888 RGBA color.
         */
        ::com::sun::star::rendering::IntegerBitmapLayout getStdMemoryLayout(
            const ::com::sun::star::geometry::IntegerSize2D& rBitmapSize );

        /// Convert standard 8888 RGBA color to vcl color
        ::Color stdIntSequenceToColor( const ::com::sun::star::uno::Sequence<sal_Int8>& rColor );

        /// Convert standard 8888 RGBA color to vcl color
        ::com::sun::star::uno::Sequence<sal_Int8> colorToStdIntSequence( const ::Color& rColor );

        // Modeled closely after boost::numeric_cast, only that we
        // issue some trace output here and throw a RuntimeException

        /** Cast numeric value into another (numeric) data type

            Apart from converting the numeric value, this template
            also checks if any overflow, underflow, or sign
            information is lost (if yes, it throws an
            uno::RuntimeException.
         */
        template< typename Target, typename Source > inline Target numeric_cast( Source arg )
        {
            // typedefs abbreviating respective trait classes
            typedef ::std::numeric_limits< Source > SourceLimits;
            typedef ::std::numeric_limits< Target > TargetLimits;

            if( ( arg<0 && !TargetLimits::is_signed) ||                     // loosing the sign here
                ( SourceLimits::is_signed && arg<TargetLimits::min()) ||    // underflow will happen
                ( arg>TargetLimits::max() ) )                               // overflow will happen
            {
#if defined(VERBOSE) && defined(DBG_UTIL)
                OSL_TRACE("numeric_cast detected data loss");
#endif
                throw ::com::sun::star::uno::RuntimeException(
                    ::rtl::OUString(RTL_CONSTASCII_USTRINGPARAM( "numeric_cast detected data loss" )),
                    NULL );
            }

            return static_cast<Target>(arg);
        }

        ::com::sun::star::awt::Rectangle getAbsoluteWindowRect(
            const ::com::sun::star::awt::Rectangle&                                    rRect,
            const ::com::sun::star::uno::Reference< ::com::sun::star::awt::XWindow2 >& xWin  );

        /** Retrieve for small bound marks around each corner of the given rectangle
         */
        ::basegfx::B2DPolyPolygon getBoundMarksPolyPolygon( const ::basegfx::B2DRange& rRange );

        /** Calculate number of gradient "strips" to generate (takes
           into account device resolution)

           @param nColorSteps
           Maximal integer difference between all color stops, needed
           for smooth gradient color differences
         */
        int calcGradientStepCount( ::basegfx::B2DHomMatrix&                        rTotalTransform,
                                   const ::com::sun::star::rendering::ViewState&   viewState,
                                   const ::com::sun::star::rendering::RenderState& renderState,
                                   const ::com::sun::star::rendering::Texture&     texture,
                                   int                                             nColorSteps );

        /** A very simplistic map for ASCII strings and arbitrary value
            types.

            This class internally references a constant, static array of
            sorted MapEntries, and performs a binary search to look up
            values for a given query string. Note that this map is static,
            i.e. not meant to be extented at runtime.

            @tpl ValueType
            The value type this map should store, associated with an ASCII
            string.
        */
        template< typename ValueType > class ValueMap
        {
        public:
            struct MapEntry
            {
                const char*     maKey;
                ValueType       maValue;
            };

            /** Create a ValueMap for the given array of MapEntries.

                @param pMap
                Pointer to a <em>static</em> array of MapEntries. Must
                live longer than this object! Make absolutely sure that
                the string entries passed via pMap are ASCII-only -
                everything else might not yield correct string
                comparisons, and thus will result in undefined behaviour.

                @param nEntries
                Number of entries for pMap

                @param bCaseSensitive
                Whether the map query should be performed case sensitive
                or not. When bCaseSensitive is false, all MapEntry strings
                must be lowercase!
            */
            ValueMap( const MapEntry*   pMap,
                      ::std::size_t     nEntries,
                      bool              bCaseSensitive ) :
                mpMap( pMap ),
                mnEntries( nEntries ),
                mbCaseSensitive( bCaseSensitive )
            {
#ifdef DBG_UTIL
                // Ensure that map entries are sorted (and all lowercase, if this
                // map is case insensitive)
                const ::rtl::OString aStr( pMap->maKey );
                if( !mbCaseSensitive &&
                    aStr != aStr.toAsciiLowerCase() )
                {
                    OSL_TRACE("ValueMap::ValueMap(): Key %s is not lowercase",
                              pMap->maKey);
                    OSL_ENSURE( false, "ValueMap::ValueMap(): Key is not lowercase" );
                }

                if( mnEntries > 1 )
                {
                    for( ::std::size_t i=0; i<mnEntries-1; ++i, ++pMap )
                    {
                        if( !mapComparator(pMap[0], pMap[1]) &&
                            mapComparator(pMap[1], pMap[0]) )
                        {
                            OSL_TRACE("ValueMap::ValueMap(): Map is not sorted, keys %s and %s are wrong",
                                      pMap[0].maKey,
                                      pMap[1].maKey);
                            OSL_ENSURE( false,
                                        "ValueMap::ValueMap(): Map is not sorted" );
                        }

                        const ::rtl::OString aStr2( pMap[1].maKey );
                        if( !mbCaseSensitive &&
                            aStr2 != aStr2.toAsciiLowerCase() )
                        {
                            OSL_TRACE("ValueMap::ValueMap(): Key %s is not lowercase",
                                      pMap[1].maKey);
                            OSL_ENSURE( false, "ValueMap::ValueMap(): Key is not lowercase" );
                        }
                    }
                }
#endif
            }

            /** Lookup a value for the given query string

                @param rName
                The string to lookup. If the map was created with the case
                insensitive flag, the lookup is performed
                case-insensitive, otherwise, case-sensitive.

                @param o_rResult
                Output parameter, which receives the value associated with
                the query string. If no value was found, the referenced
                object is kept unmodified.

                @return true, if a matching entry was found.
            */
            bool lookup( const ::rtl::OUString& rName,
                         ValueType&             o_rResult ) const
            {
                // rName is required to contain only ASCII characters.
                // TODO(Q1): Enforce this at upper layers
                ::rtl::OString aKey( ::rtl::OUStringToOString( mbCaseSensitive ? rName : rName.toAsciiLowerCase(),
                                                               RTL_TEXTENCODING_ASCII_US ) );
                MapEntry aSearchKey =
                    {
                        aKey.getStr(),
                        ValueType()
                    };

                const MapEntry* pRes;
                const MapEntry* pEnd = mpMap+mnEntries;
                if( (pRes=::std::lower_bound( mpMap,
                                              pEnd,
                                              aSearchKey,
                                              &mapComparator )) != pEnd )
                {
                    // place to _insert before_ found - is it equal to
                    // the search key?
                    if( strcmp( pRes->maKey, aSearchKey.maKey ) == 0 )
                    {
                        // yep, correct entry found
                        o_rResult = pRes->maValue;
                        return true;
                    }
                }

                // not found
                return false;
            }

        private:
            static bool mapComparator( const MapEntry& rLHS,
                                       const MapEntry& rRHS )
            {
                return strcmp( rLHS.maKey,
                               rRHS.maKey ) < 0;
            }

            const MapEntry*     mpMap;
            ::std::size_t       mnEntries;
            bool                mbCaseSensitive;
        };
    }
}

#endif /* INCLUDED_CANVAS_CANVASTOOLS_HXX */
// eof