inc/FGrpCanvas.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FGrpCanvas.h
  20  * @brief       This is the header file for the %Canvas class.
  21  *
  22  * This header file contains the declarations of the %Canvas class.
  23  *
  24  */
  25
  26 #ifndef _FGRP_CANVAS_H_
  27 #define _FGRP_CANVAS_H_
  28
  29 #include <FBase.h>
  30 #include <FBaseObject.h>
  31 #include <FBaseColArrayListT.h>
  32 #include <FGrpRectangle.h>
  33 #include <FGrpColor.h>
  34 #include <FGrpPixelFormat.h>
  35 #include <FGrpBufferInfo.h>
  36 #include <FGrpBitmap.h>
  37 #include <FGrpCanvasCommon.h>
  38
  39 namespace Tizen { namespace Graphics
  40 {
  41 class Font;
  42 class EnrichedText;
  43
  44 /**
  45  * @class       Canvas
  46  * @brief       This class provides methods for drawing objects.
  47  *
  48  * @since       2.0
  49  *
  50  * @final       This class is not intended for extension.
  51  *
  52  * The %Canvas class provides a rectangular region to draw objects on the display device. The %Canvas instance is
  53  * associated with a specific context.
  54  * @n
  55  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/canvas.htm">Canvas</a>.
  56  *
  57  */
  58 class _OSP_EXPORT_ Canvas
  59         : public Tizen::Base::Object
  60 {
  61 public:
  62         /**
  63          * This is the default constructor for this class.
  64          *
  65          * @since               2.0
  66          * @remarks             After creating an instance of this class, one of the Construct() methods must be
  67          *                              called explicitly to initialize this instance.
  68          */
  69         Canvas(void);
  70
  71         /**
  72          * This is the destructor for this class.
  73          *
  74          * @since       2.0
  75          */
  76         virtual ~Canvas(void);
  77
  78         /**
  79          * Initializes this instance of %Canvas to create a canvas control of the same size as that of the
  80          * device screen.
  81          *
  82          * @since               2.0
  83          *
  84          * @return              An error code
  85          * @exception   E_SUCCESS                       The method is successful.
  86          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
  87          */
  88         result Construct(void);
  89
  90         /**
  91          * Initializes this instance of %Canvas with the specified parameter.
  92          *
  93          * @since               2.0
  94          *
  95          * @return              An error code
  96          * @param[in]   rect                    The location and size of the canvas control on the device screen @n
  97          *                                                              The width and height of the rectangle must be greater than @c 0.
  98          *                                                              If this condition is not satisfied, the E_OUT_OF_RANGE exception is returned.
  99          * @exception   E_SUCCESS               The method is successful.
 100          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 101          */
 102         result Construct(const Rectangle& rect);
 103
 104         /**
 105          * Initializes this instance of %Canvas with the buffer information.
 106          *
 107          * @since 2.0
 108          *
 109          * @return              An error code
 110          * @param[in]   bufferInfo           The information of the buffer to be used by the canvas.
 111          * @exception   E_SUCCESS            The method is successful.
 112          * @exception   E_INVALID_ARG        The buffer information is invalid.
 113          * @exception   E_UNSUPPORTED_FORMAT The given buffer information is a format unsupported by the canvas.
 114          * @exception   E_SYSTEM             An unknown operating system error has occurred
 115          * @remarks Only PIXEL_FORMAT_ARGB8888 is supported.
 116          */
 117         result Construct(const BufferInfo& bufferInfo);
 118
 119 public:
 120         /**
 121          * Clears the current instance of %Canvas with the background color.
 122          *
 123          * @since               2.0
 124          *
 125          * @return              An error code
 126          * @exception   E_SUCCESS                       The method is successful.
 127          */
 128         result Clear(void);
 129
 130         /**
 131          * Clears a rectangular region of the current instance of %Canvas with the background color.
 132          *
 133          * @since               2.0
 134          *
 135          * @return              An error code
 136          * @param[in]   rect                    The location and size of the rectangular region @n
 137          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 138          *                                                              The rectangular region must not fall outside the edges of the
 139          *                                                              current instance of %Canvas entirely.If these conditions are not
 140          *                                                              satisfied, the E_OUT_OF_RANGE exception is returned.
 141          * @exception   E_SUCCESS               The method is successful.
 142          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 143          */
 144         result Clear(const Rectangle& rect);
 145
 146         /**
 147          * Copies the specified rectangular region from the specified instance of %Canvas to the current instance of
 148          * %Canvas at the specified location.
 149          *
 150          * @since               2.0
 151          *
 152          * @return              An error code
 153          * @param[in]   destPoint                       The location to copy the rectangular region
 154          * @param[in]   srcCanvas                       The source %Canvas
 155          * @param[in]   srcRect                         The location and size of the rectangular region on the source %Canvas @n
 156          *                                                                      The rectangular region must not fall outside the edges of
 157          *                                                                      the current instance of %Canvas entirely. If this condition is
 158          *                                                                      not satisfied, the E_OUT_OF_RANGE exception is returned.
 159          * @exception   E_SUCCESS                       The method is successful.
 160          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 161          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 162          */
 163         result Copy(const Point& destPoint, const Canvas& srcCanvas, const Rectangle& srcRect);
 164
 165         /**
 166          * Copies the scaled image of the specified rectangular region from the specified instance of
 167          * %Canvas to the current instance of %Canvas.
 168          *
 169          * @since               2.0
 170          *
 171          * @return              An error code
 172          * @param[in]   destRect                        The location and size of the destination image @n
 173          *                                                                      The value of @c destRect must not fall outside the edges of
 174          *                                                                      the current instance of %Canvas entirely. If this condition is
 175          *                                                                      not satisfied, the E_OUT_OF_RANGE exception is returned.
 176          * @param[in]   srcCanvas                       The source %Canvas
 177          * @param[in]   srcRect                         The location and size of the source image @n
 178          *                                                                      The value of @c srcRect must not fall outside the edges of
 179          *                                                                      the current instance of %Canvas entirely. If this condition is
 180          *                                                                      not satisfied, the E_OUT_OF_RANGE exception is returned.
 181          * @exception   E_SUCCESS                       The method is successful.
 182          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 183          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 184          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of this operation.
 185          */
 186         result Copy(const Rectangle& destRect, const Canvas& srcCanvas, const Rectangle& srcRect);
 187
 188         /**
 189          * Gets the line style set for the current instance of %Canvas.
 190          *
 191          * @since               2.0
 192          *
 193          * @return              An instance of %LineStyle
 194          * @remarks The default value is LINE_STYLE_SOLID.
 195          */
 196         LineStyle GetLineStyle(void) const;
 197
 198         /**
 199          * Gets the line width of the current instance of %Canvas.
 200          *
 201          * @since               2.0
 202          *
 203          * @return              The line width, @n
 204          *                              else @c -1 if the method fails
 205          * @remarks The default value is 1.
 206          */
 207         int GetLineWidth(void) const;
 208
 209         /**
 210          * Sets the line style for the current instance of %Canvas.
 211          *
 212          * @since               2.0
 213          *
 214          * @return              An error code
 215          * @param[in]   style                           The new line style for the %Canvas control
 216          * @exception   E_SUCCESS                       The method is successful.
 217          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 218          */
 219         result SetLineStyle(LineStyle style);
 220
 221         /**
 222          * Sets the line width for the current instance of %Canvas.
 223          *
 224          * @since               2.0
 225          *
 226          * @return              An error code
 227          * @param[in]   width                           The new width for the %Canvas control @n
 228          *                                                                      The width for the %Canvas control must be greater than @c 0.
 229          * @exception   E_SUCCESS                       The method is successful.
 230          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 231          */
 232         result SetLineWidth(int width);
 233
 234         /**
 235          * Gets the dash pattern of the current instance of %Canvas.
 236          *
 237          * @since 2.0
 238          *
 239          * @return              An error code
 240          * @param[out]  pattern                 The list containing the information of dash pattern.
 241          * @param[out]  offset                  The offset into the dash pattern at which the stroke must start
 242          * @exception   E_SUCCESS               The method is successful.
 243          * @exception   E_INVALID_ARG   A specific input parameter is invalid.
 244          */
 245         result GetDashPattern(Tizen::Base::Collection::IListT<int>& pattern, int& offset) const;
 246
 247         /**
 248          * Sets the dash pattern for the current instance of %Canvas.
 249          *
 250          * @since 2.0
 251          *
 252          * @return              An error code
 253          * @param[in]   pattern                 The list containing the information of dash pattern.
 254          * @param[in]   offset                  The offset into the dash pattern at which the stroke must start
 255          * @exception   E_SUCCESS               The method is successful.
 256          * @exception   E_INVALID_ARG   A specific input parameter is invalid.
 257          */
 258         result SetDashPattern(const Tizen::Base::Collection::IListT<int>& pattern, int offset);
 259
 260         /**
 261          * Gets the color information at the specified point.
 262          *
 263          * @since               2.0
 264          *
 265          * @return              An error code
 266          * @param[in]   point                   The location of the point relative to the upper-left corner of the current instance of %Canvas @n
 267          *                                                              The point must not fall outside the edges of %Canvas. If this
 268          *                                                              condition is not satisfied, the E_OUT_OF_RANGE exception is returned.
 269          * @param[out]  color                   An instance of Color
 270          * @exception   E_SUCCESS               The method is successful.
 271          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 272          */
 273         result GetPixel(const Point& point, Color& color) const;
 274
 275         /**
 276          * Sets a point at the specified coordinate.
 277          *
 278          * @since               2.0
 279          *
 280          * @return              An error code
 281          * @param[in]   point                   The location of the point relative to the upper-left corner of the current instance of %Canvas @n
 282          *                                                              The point must not entirely fall outside the edges of %Canvas.
 283          *                                                              If this condition is not satisfied, the E_OUT_OF_RANGE exception
 284          *                                                              is returned.
 285          * @exception   E_SUCCESS               The method is successful.
 286          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 287          */
 288         result SetPixel(const Point& point);
 289
 290         /**
 291          * Draws a line between the two specified points.
 292          *
 293          * @since               2.0
 294          *
 295          * @return              An error code
 296          * @param[in]   point1                          The starting point
 297          * @param[in]   point2                          The end point
 298          * @exception   E_SUCCESS                       The method is successful.
 299          */
 300         result DrawLine(const Point& point1, const Point& point2);
 301
 302         /**
 303          * Draws a rectangle.
 304          *
 305          * @since               2.0
 306          *
 307          * @return              An error code
 308          * @param[in]   rect                            The rectangle to be drawn on the %Canvas control @n
 309          *                                                                      The width and height of the rectangle must be greater than or equal to @c 0.
 310          *                                                                      The rectangle must not entirely fall outside the edges of
 311          *                                                                      the %Canvas control. If these conditions are not satisfied,
 312          *                                                                      the E_OUT_OF_RANGE exception is returned.
 313          * @exception   E_SUCCESS                       The method is successful.
 314          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 315          */
 316         result DrawRectangle(const Rectangle& rect);
 317
 318         /**
 319          * Fills a rectangular region of the current instance of %Canvas with the specified color.
 320          *
 321          * @since               2.0
 322          *
 323          * @return              An error code
 324          * @param[in]   color                   The fill color
 325          * @param[in]   rect                    The rectangular region on the %Canvas control @n
 326          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 327          *                                                              The rectangle must not entirely fall outside the edges of the
 328          *                                                              %Canvas control. If these conditions are not satisfied, the
 329          *                                                              E_OUT_OF_RANGE exception is returned.
 330          * @exception   E_SUCCESS               The method is successful.
 331          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 332          */
 333         result FillRectangle(const Color& color, const Rectangle& rect);
 334
 335         /**
 336          * Draws a round-edged rectangle.
 337          *
 338          * @since               2.0
 339          *
 340          * @return              An error code
 341          * @param[in]   rect                    The location and size of the rectangle @n
 342          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 343          *                                                              The rectangle must not entirely fall outside the edges of the
 344          *                                                              %Canvas control. If these conditions are not satisfied, the
 345          *                                                              E_OUT_OF_RANGE exception is returned.
 346          * @param[in]   arcDim                  The width and height of the round edge @n
 347          *                                                      The width and height in the @c arcDim parameter must be greater than or equal to @c 0.
 348          * @exception   E_SUCCESS               The method is successful.
 349          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 350          */
 351         result DrawRoundRectangle(const Rectangle& rect, const Dimension& arcDim);
 352
 353         /**
 354          * Draws a filled rectangle.
 355          *
 356          * @since               2.0
 357          *
 358          * @return              An error code
 359          * @param[in]   color                   The fill color
 360          * @param[in]   rect                    The location and size of the rectangle @n
 361          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 362          *                                                              The rectangle must not entirely fall outside the edges of the
 363          *                                                              %Canvas control. If these conditions are not satisfied, the
 364          *                                                              E_OUT_OF_RANGE exception is returned.
 365          * @param[in]   arcDim                  The width and height of the round edge @n
 366          *                                                      The width and height mentioned in the @c arcDim parameter must be greater than or equal to @c 0.
 367          * @exception   E_SUCCESS               The method is successful.
 368          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 369          */
 370         result FillRoundRectangle(const Color& color, const Rectangle& rect, const Dimension& arcDim);
 371
 372         /**
 373          * Draws an ellipse.
 374          *
 375          * @since               2.0
 376          *
 377          * @return              An error code
 378          * @param[in]   rect                    The location and size of the bounding rectangle @n
 379          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 380          *                                                              The rectangle must not entirely fall outside the edges of the
 381          *                                                              %Canvas control. If these conditions are not satisfied, the
 382          *                                                              E_OUT_OF_RANGE exception is returned.
 383          * @exception   E_SUCCESS               The method is successful.
 384          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 385          */
 386         result DrawEllipse(const Rectangle& rect);
 387
 388         /**
 389          * Draws a filled ellipse with the specified color.
 390          *
 391          * @since               2.0
 392          *
 393          * @return              An error code
 394          * @param[in]   color                   The fill color
 395          * @param[in]   rect                    The location and size of the bounding rectangle @n
 396          *                                                              The width and height of the rectangle must be greater than or equal to @c 0. @n
 397          *                                                              The rectangle must not entirely fall outside the edges of the
 398          *                                                              %Canvas control. If these conditions are not satisfied, the
 399          *                                                              E_OUT_OF_RANGE exception is returned.
 400          * @exception   E_SUCCESS               The method is successful.
 401          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 402          */
 403         result FillEllipse(const Color& color, const Rectangle& rect);
 404
 405         /**
 406          * Draws a circular arc.
 407          *
 408          * @since               2.0
 409          *
 410          * @return              An error code
 411          * @param[in]   rect                    The location and size of the bounding rectangle @n
 412          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 413          *                                                              The rectangle must not entirely fall outside the edges of the
 414          *                                                              %Canvas control. If these conditions are not satisfied, the
 415          *                                                              E_OUT_OF_RANGE exception is returned.
 416          * @param[in]   startAngle              The starting angle
 417          * @param[in]   endAngle                The ending angle
 418          * @param[in]   arcStyle                The arc style
 419          * @exception   E_SUCCESS               The method is successful.
 420          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 421          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 422          */
 423         result DrawArc(const Rectangle& rect, int startAngle, int endAngle, ArcStyle arcStyle);
 424
 425         /**
 426          * Draws a triangle.
 427          *
 428          * @since               2.0
 429          *
 430          * @return              An error code
 431          * @param[in]   point1                          The location of the first vertex
 432          * @param[in]   point2                          The location of the second vertex
 433          * @param[in]   point3                          The location of the third vertex
 434          * @exception   E_SUCCESS                       The method is successful.
 435          */
 436         result DrawTriangle(const Point& point1, const Point& point2, const Point& point3);
 437
 438         /**
 439          * Draw a filled triangle with the specified color.
 440          *
 441          * @since               2.0
 442          *
 443          * @return              An error code
 444          * @param[in]   color                           The fill color
 445          * @param[in]   point1                          The location of the first vertex
 446          * @param[in]   point2                          The location of the second vertex
 447          * @param[in]   point3                          The location of the third vertex
 448          * @exception   E_SUCCESS                       The method is successful.
 449          */
 450         result FillTriangle(const Color& color, const Point& point1, const Point& point2, const Point& point3);
 451
 452         /**
 453          * Draws a poly-line.
 454          *
 455          * @since               2.0
 456          *
 457          * @return              An error code
 458          * @param[in]   points                          A list containing the location of points @n
 459          *                                                                      The number of points must be greater than or equal to @c 0.
 460          * @exception   E_SUCCESS                       The method is successful.
 461          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 462          */
 463         result DrawPolyline(const Tizen::Base::Collection::IList& points);
 464
 465         /**
 466          * Draws a polygon.
 467          *
 468          * @since               2.0
 469          *
 470          * @return              An error code
 471          * @param[in]   points                          A list containing the locations of the vertices of the polygon @n
 472          *                                                                      The number of points must be greater than or equal to @c 0.
 473          * @exception   E_SUCCESS                       The method is successful.
 474          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 475          */
 476         result DrawPolygon(const Tizen::Base::Collection::IList& points);
 477
 478         /**
 479          * Draws a filled polygon with the specified color.
 480          *
 481          * @since               2.0
 482          *
 483          * @return              An error code
 484          * @param[in]   color                           The fill color
 485          * @param[in]   points                          A list containing the locations of the vertices of the polygon @n
 486          *                                                                      The number of points must be greater than or equal to @c 0.
 487          * @exception   E_SUCCESS                       The method is successful.
 488          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 489          */
 490         result FillPolygon(const Color& color, const Tizen::Base::Collection::IList& points);
 491
 492         /**
 493          * Sets a font to the %Canvas control.
 494          *
 495          * @since               2.0
 496          *
 497          * @return              An error code
 498          * @param[in]   font                            The font @n
 499          *                                                                      It must be constructed before being passed to this method.
 500          * @exception   E_SUCCESS                       The method is successful.
 501          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 502          */
 503         result SetFont(const Font& font);
 504
 505         /**
 506          * Gets a font of the %Canvas control.
 507          *
 508          * @since               2.0
 509          *
 510          * @return              The font of the %Canvas control, @n
 511          *                              else @c null if the method fails
 512          * @exception           E_SUCCESS                       The method is successful.
 513          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 514          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 515          * @remarks             If a font is not set with the SetFont() method, this method returns the system default font.
 516          */
 517         Font* GetFontN(void) const;
 518
 519         /**
 520          * Draws a text at the specified location.
 521          *
 522          * @since               2.0
 523          *
 524          * @return              An error code
 525          * @param[in]   point                           The location to draw the text
 526          * @param[in]   text                            The text to draw
 527          * @exception   E_SUCCESS                       The method is successful.
 528          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 529          * @exception   E_OPERATION_FAILED  The operation has failed.
 530          * @remarks     The foreground color (RGB value only) of the %Canvas control is used as the text color.
 531          * @remarks     The em square has a defined font size. As a result, if the font's glyph exceeds its em square, it will be scaled down when it is drawn.
 532          */
 533         result DrawText(const Point& point, const Tizen::Base::String& text);
 534
 535         /**
 536          * Draws a text at the specified location and length.
 537          *
 538          * @since               2.0
 539          *
 540          * @return              An error code
 541          * @param[in]   point                           The location to draw the text
 542          * @param[in]   text                            The text to draw
 543          * @param[in]   length                          The number of characters in the string @n
 544          *                                                                      It must be greater than or equal to @c 0.
 545          * @exception   E_SUCCESS                       The method is successful.
 546          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 547          * @exception   E_OUT_OF_RANGE          The value of the argument is outside the valid range defined by the method.
 548          * @exception   E_OPERATION_FAILED  The operation has failed.
 549          * @remarks     The foreground color (RGB value only) of the %Canvas control is used as the text color.
 550          * @remarks     The em square has a defined font size. As a result, if the font's glyph exceeds its em square, it will be scaled down when it is drawn.
 551          */
 552         result DrawText(const Point& point, const Tizen::Base::String& text, int length);
 553
 554         /**
 555          * Draws a text with an outline rendering at the specified location.
 556          *
 557          * @since        2.0
 558          *
 559          * @return       An error code
 560          * @param[in]    point               The location to draw the text
 561          * @param[in]    text                The text to draw @n
 562          * @param[in]    outlineColor        The color that is set as outline color
 563          * @exception    E_SUCCESS           The method is successful.
 564          * @exception    E_INVALID_ARG       A specified input parameter is invalid.
 565          * @exception    E_OUT_OF_RANGE      The value of the argument is outside the valid range defined by the method.
 566          * @exception    E_OPERATION_FAILED  The operation has failed.
 567          * @remarks     The foreground color (RGB value only) of the %Canvas control is used as the text color.
 568          * @remarks     The em square has a defined font size. As a result, if the font's glyph exceeds its em square, it will be scaled down when it is drawn.
 569          */
 570         result DrawText(const Point& point, const Tizen::Base::String& text, const Color& outlineColor);
 571
 572         /**
 573          * Draws a text with an outline rendering at the specified location and length.
 574          *
 575          * @since        2.0
 576          *
 577          * @return       An error code
 578          * @param[in]    point               The location to draw the text
 579          * @param[in]    text                The text to draw
 580          * @param[in]    length              The number of characters in the string @n
 581          *                                   It must be greater than or equal to @c 0.
 582          * @param[in]    outlineColor        The color that is set as outline color
 583          * @exception    E_SUCCESS           The method is successful.
 584          * @exception    E_INVALID_ARG       A specified input parameter is invalid.
 585          * @exception    E_OUT_OF_RANGE      The value of the argument is outside the valid range defined by the method.
 586          * @exception    E_OPERATION_FAILED  The operation has failed.
 587          *
 588          * @remarks     The foreground color (RGB value only) of the %Canvas control is used as the text color.
 589          * @remarks     The em square has a defined font size. As a result, if the font's glyph exceeds its em square, it will be scaled down when it is drawn.
 590          */
 591         result DrawText(const Point& point, const Tizen::Base::String& text, int length, const Color& outlineColor);
 592
 593         /**
 594          * Draws an enriched text at the specified area.
 595          *
 596          * @since               2.0
 597          *
 598          * @return              An error code
 599          * @param[in]   point                                   The location to draw the text
 600          * @param[in]   enrichedText                    The TextElement to draw
 601          * @exception   E_SUCCESS                               The method is successful.
 602          * @exception   E_DEVICE_UNAVAILABLE    A specified device is invalid.
 603          *
 604          * @remarks  The foreground color (RGB value only) of the %Canvas control is used as the text color.
 605          * @remarks  The em square has a defined font size. As a result, if the font's glyph exceeds its em square, it will be scaled down when it is drawn.
 606          */
 607         result DrawText(const Point& point, const EnrichedText& enrichedText);
 608
 609         /**
 610          * Draws a bitmap image at the specified location.
 611          *
 612          * @since               2.0
 613          *
 614          * @return              An error code
 615          * @param[in]   point                           The location of the upper-left corner of the bitmap
 616          * @param[in]   bitmap                          The bitmap to draw @n
 617          *                                                                      It must be constructed before being passed into this
 618          *                                                                      method. BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is
 619          *                                                                      not applicable for this method. The bitmap must not
 620          *                                                                      entirely fall outside the edges of the %Canvas control. If
 621          *                                                                      this condition is not satisfied, the E_OUT_OF_RANGE exception
 622          *                                                                      is returned.
 623          * @exception   E_SUCCESS                       The method is successful.
 624          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 625          */
 626         result DrawBitmap(const Point& point, const Bitmap& bitmap);
 627
 628         /**
 629          * Draws a bitmap image at the specified location.
 630          *
 631          * @since               2.0
 632          *
 633          * @return              An error code
 634          * @param[in]   rect                    The location and size of the scaled bitmap @n
 635          *                                                              The rectangle must not entirely fall outside the edges of the
 636          *                                                              %Canvas control. If this condition is not satisfied, the
 637          *                                                              E_OUT_OF_RANGE exception is returned.
 638          * @param[in]   bitmap                  The bitmap to draw @n
 639          *                                                              It must be constructed well before being passed into this
 640          *                                                              method.
 641          * @exception   E_SUCCESS               The method is successful.
 642          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 643          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 644          * @remarks BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 645          */
 646         result DrawBitmap(const Rectangle& rect, const Bitmap& bitmap);
 647
 648         /**
 649          * Draws a color data corresponding to a rectangle of pixels from the specified bitmap onto %Canvas.
 650          *
 651          * @since               2.0
 652          *
 653          * @return              An error code
 654          * @param[in]   destRect                        The destination rectangle of %Canvas @n
 655          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 656          *                                                              The rectangle defined by @c destRect will be clipped at the edges
 657          *                                                              of the %Canvas control to prevent the rectangle from falling
 658          *                                                              outside the edges of the %Canvas control. The destination
 659          *                                                              rectangle of a %Canvas control must not fall outside the edges
 660          *                                                              of the %Canvas control entirely. If these conditions are not
 661          *                                                              satisfied, the E_OUT_OF_RANGE exception is returned.
 662          * @param[in]   srcBitmap               The bitmap to draw
 663          * @param[in]   srcRect                 The source rectangle of a bitmap @n
 664          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 665          *                                                              The rectangle defined by @c srcRect will be clipped at the edges
 666          *                                                              of the bitmap to prevent the rectangle from falling outside the
 667          *                                                              edges of the bitmap. The source rectangle of a bitmap must not
 668          *                                                              fall outside the edges of the bitmap entirely. If these
 669          *                                                              conditions are not satisfied, the E_OUT_OF_RANGE exception is
 670          *                                                              thrown.
 671          * @exception   E_SUCCESS               The method is successful.
 672          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 673          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 674          * @remarks             If the source and destination rectangles are not of the same size,
 675          *                              the source bitmap is stretched to match the destination rectangle. @n
 676          *                              BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 677          */
 678         result DrawBitmap(const Rectangle& destRect, const Bitmap& srcBitmap, const Rectangle& srcRect);
 679
 680         /**
 681          * Draws a flipped bitmap image at the specified location.
 682          *
 683          * @since               2.0
 684          *
 685          * @return      An error code
 686          * @param[in]   point                   The location to draw the bitmap
 687          * @param[in]   bitmap          The bitmap to draw @n
 688          *                              It must be constructed before being passed to this method.
 689          * @param[in]   dir             The flip direction
 690          * @exception   E_SUCCESS       The method is successful.
 691          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 692          * @remarks             BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 693          */
 694         result DrawBitmap(const Point& point, const Bitmap& bitmap, FlipDirection dir);
 695
 696         /**
 697          * Draws a rotated bitmap image at the specified location.
 698          *
 699          * @since               2.0
 700          *
 701          * @return              An error code
 702          * @param[in]   point                   A location to draw a bitmap image @n
 703          *                              This location is relatively defined from the origin (upper-left
 704          *                                                              corner) of the %Canvas control.
 705          * @param[in]   bitmap           The bitmap to draw @n
 706          *                               It must be constructed before being passed to this method.
 707          * @param[in]   pivot            The center of rotation of a bitmap image @n
 708          *                               This center is relatively defined from the origin (upper-left
 709          *                                                              corner) of the bitmap.
 710          * @param[in]   degree           The amount of rotation in degrees
 711          * @exception   E_SUCCESS        The method is successful.
 712          * @exception   E_INVALID_ARG    A specified input parameter is invalid.
 713          * @remarks     BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method.
 714          * @image               html    graphics_rotatebitmap.PNG
 715          */
 716         result DrawBitmap(const Point& point, const Bitmap& bitmap, const Point& pivot, int degree);
 717
 718         /**
 719          * Draws a nine-patched bitmap at the specified location.
 720          *
 721          * @since               2.0
 722          *
 723          * @return              An error code
 724          * @param[in]   rect                    The location and size of the nine-patched bitmap @n
 725          *                                                              The rectangle must not entirely fall outside the edges of the
 726          *                                                              %Canvas control. If this condition is not satisfied, the
 727          *                                                              E_OUT_OF_RANGE exception is returned.
 728          * @param[in]   bitmap                  The bitmap to draw @n
 729          *                                                              It must be constructed before being passed to this method.
 730          * @exception   E_SUCCESS       The method is successful.
 731          * @exception   E_INVALID_ARG   A specified input parameter is invalid.
 732          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 733          *
 734          * @remarks    BitmapPixelFormat::BITMAP_PIXEL_FORMAT_R8G8B8A8 is not applicable for this method. @n
 735          *             The nine-patched bitmap must have a stretchable section by drawing one (or more) 1-pixel-wide black line(s) in the
 736          *             left and top part of the border.
 737          * @image                       html    graphics_ninepatchedbitmap.PNG
 738          *
 739          */
 740         result DrawNinePatchedBitmap(const Rectangle& rect, const Bitmap& bitmap);
 741
 742         /**
 743          * Shows the current instance of %Canvas on the device screen.
 744          *
 745          * @if OSPCOMPAT
 746          * @brief       <i> [Compatibility] </i>
 747          * @endif
 748          * @since                       2.0
 749          * @if OSPCOMPAT
 750          * @compatibility       This method has compatibility issues with OSP compatible applications @n
 751          *                                      For more information, see the issue description for @ref CompCanvasShowPage "here".
 752          * @endif
 753          *
 754          * @return              An error code
 755          * @exception   E_SUCCESS                                       The method is successful.
 756          * @exception   E_UNSUPPORTED_OPERATION         This operation is not supported.
 757          *
 758          */
 759         result Show(void);
 760
 761         /**
 762          * @if OSPCOMPAT
 763          * @page                        CompCanvasShowPage Compatibility for Show().
 764          * @section                     CompCanvasShowPageIssueSection Issues
 765          *                                      In Tizen, memory canvas is not fully supported, and we cannot guarantee that Show() for memory canvas of Tizen does the same operation with that of OSP.
 766          *
 767          * -# In OSP, when Show() is called for a Memory Canvas, the canvas was copied to the screen and E_SUCCESS was returned, but the canvas is not guaranteed to be displayed properly.
 768          * -# In Tizen, Show() does not function for a Memory Canvas, so E_UNSUPPORTED_OPERATION is returned. Memory Canvases cannot be used to directly show its content on screen.
 769          *
 770          * @endif
 771          */
 772
 773
 774         /**
 775          * @if OSPDEPREC
 776          * Shows the specified rectangle of the current instance of %Canvas on the device screen.
 777          *
 778          * @brief       <i> [Deprecated] </i>
 779          * @deprecated  This method is deprecated. Instead of this method, use the Show().
 780          * @since               2.0
 781          *
 782          * @return              An error code
 783          * @param[in]   rect                    The bounds of the %Canvas control to display @n
 784          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 785          *                                                              The rectangle must not entirely fall outside the edges of the
 786          *                                                              %Canvas control. If these conditions are not satisfied, the
 787          *                                                              E_OUT_OF_RANGE exception is returned.
 788          * @exception   E_SUCCESS               The method is successful.
 789          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 790          *
 791          * @remark      If you use Show(Rectangle&) in Tizen, this method works differently. @n
 792          *              This method shows the screen entirely not partially in Tizen.
 793          * @endif
 794          */
 795         result Show(const Rectangle& rect);
 796
 797         /**
 798          * Gets the location and size of the current %Canvas instance on the device screen.
 799          *
 800          * @since       2.0
 801          *
 802          * @return      The Rectangle instance containing the location and size of the current %Canvas instance
 803          * @remarks If this %Canvas instance is a Window %Canvas, it returns Rectangle(0, 0, w, h).
 804          */
 805         Rectangle GetBounds(void) const;
 806
 807         /**
 808          * Sets the clip rectangle for a %Canvas control. @n
 809          * When a clip rectangle is set, any drawing is restricted within the specified rectangular area. The
 810          * rectangular area defined is clipped at the edges of the %Canvas control so as to prevent the clipped rectangle
 811          * from falling outside the %Canvas control.
 812          *
 813          * @since               2.0
 814          *
 815          * @return              An error code
 816          * @param[in]   rect                    The bounds of the clip rectangle @n
 817          *                                                              The width and height of the rectangle must be greater than or equal to @c 0.
 818          *                                                              The clip rectangle for a %Canvas control must not entirely fall
 819          *                                                              outside the edges of the %Canvas control. If these conditions are
 820          *                                                              not satisfied, the E_OUT_OF_RANGE exception is returned.
 821          * @exception   E_SUCCESS               The method is successful.
 822          * @exception   E_OUT_OF_RANGE  The value of the argument is outside the valid range defined by the method.
 823          */
 824         result SetClipBounds(const Rectangle& rect);
 825
 826         /**
 827          * Gets the bounds of the clip rectangle of a %Canvas control.
 828          *
 829          * @since               2.0
 830          *
 831          * @return              An instance of Rectangle indicating the bounds of the clip rectangle
 832          */
 833         Rectangle GetClipBounds(void) const;
 834
 835         /**
 836          * Locks the %Canvas control for direct pixel access. @n
 837          * This sets up a %Canvas control for accessing the pixels directly. Between the calls to the
 838          * Canvas::Lock() and Canvas::UnLock() methods, the data can be written to and read from the
 839          * Canvas control's pixels. Once the operations on the %Canvas control's pixels are finished, the
 840          * Canvas::Unlock() method must be called to release the lock.
 841          *
 842          * @since               2.0
 843          *
 844          * @return              An error code
 845          * @param[out]  info                    The information of the %Canvas control
 846          * @param[in]   timeout                 The time, in milliseconds, that the caller waits for the lock to be obtained @n
 847          *                                                              If the lock attempt fails, E_TIMEOUT is returned. The default value
 848          *                                                              is INFINITE, which means that the method does not return until the lock
 849          *                                                              is acquired.
 850          * @exception   E_SUCCESS               The method is successful.
 851          * @exception   E_TIMEOUT               The operation cannot be completed within the specified time period.
 852          * @exception   E_SYSTEM                An unknown operating system error has occurred.
 853          *
 854          * @remarks     BufferInfo contains a valid physical memory information, regardless of the
 855          *                              logical position and size of the %Canvas control.
 856          */
 857         result Lock(BufferInfo& info, long timeout = INFINITE);
 858
 859         /**
 860          * Unlocks the %Canvas control.
 861          *
 862          * @since               2.0
 863          *
 864          * @return              An error code
 865          * @exception   E_SUCCESS                       The method is successful.
 866          * @exception   E_SYSTEM                        An unknown operating system error has occurred.
 867          * @remarks             The %Canvas control must be unlocked as soon as possible.
 868          */
 869         result Unlock(void);
 870
 871         /**
 872          * Sets the foreground color.
 873          *
 874          * @since               2.0
 875          *
 876          * @param[in]   color   The color that is set as foreground color
 877          */
 878         void SetForegroundColor(const Color& color);
 879
 880         /**
 881          * Gets the foreground color.
 882          *
 883          * @since               2.0
 884          *
 885          * @return              The foreground color
 886          */
 887         Color GetForegroundColor(void) const;
 888
 889         /**
 890          * Sets the background color.
 891          *
 892          * @since               2.0
 893          *
 894          * @param[in]   color   The color that is set as background color
 895          */
 896         void SetBackgroundColor(const Color& color);
 897
 898         /**
 899          * Gets the background color.
 900          *
 901          * @since               2.0
 902          *
 903          * @return              The background color
 904          */
 905         Color GetBackgroundColor(void) const;
 906
 907         /**
 908          * Sets the current instance of %Canvas to the specified point.
 909          *
 910          * @since               2.0
 911          *
 912          * @return              An error code
 913          * @param[in]   point                                   The new position
 914          * @exception   E_SUCCESS                               The method is successful.
 915          * @exception   E_UNSUPPORTED_OPERATION Window %Canvas does not support moving the position.
 916          */
 917         result SetPosition(const Point& point);
 918
 919         /**
 920          * Sets the current instance of %Canvas to the specified point.
 921          *
 922          * @since               2.0
 923          *
 924          * @return              An error code
 925          * @param[in]   x                                               The new x-coordinate
 926          * @param[in]   y                                               The new y-coordinate
 927          * @exception   E_SUCCESS                               The method is successful.
 928          * @exception   E_UNSUPPORTED_OPERATION Window %Canvas does not support moving the position.
 929          */
 930         result SetPosition(int x, int y);
 931
 932 private:
 933         //
 934         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 935         //
 936         Canvas(const Canvas& rhs);
 937
 938         //
 939         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 940         //
 941         Canvas& operator =(const Canvas& rhs);
 942
 943         friend class Bitmap;
 944         friend class TextElement;
 945
 946 private:
 947         friend class _CanvasImpl;
 948
 949         //
 950         // This variable is for internal use only.
 951         // Using this variable can cause behavioral, security-related, and consistency-related issues in the application.
 952         //
 953         // @since 2.0
 954         //
 955         class _CanvasImpl* __pImpl;
 956
 957 }; // Canvas
 958
 959 }} // Tizen::Graphics
 960
 961 #endif //_FGRP_CANVAS_H_