Package ej.microui.display

## Class GraphicsContext

- java.lang.Object
- - ej.microui.display.GraphicsContext

-     public class GraphicsContext
      extends Object

  A `GraphicsContext` provides access to a modifiable pixel buffer.

  For example, a graphics context can be used to read or write the pixels of the `Display` or of a `BufferedImage`.

  Painting classes such as `Painter` provide utility methods to draw specific shapes and objects using a graphics context.

  Colors are interpreted as 24-bit RGB colors. If the display or image associated with the graphics context does not support such color depth, its implementation is in charge of mapping the desired colors to the most appropriate supported colors.

  A graphics context defines a translation vector in order to change the position of subsequent drawings.

  It also defines a clipping rectangle which restricts the pixels that will be modified by subsequent drawings. Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed. The position of this clipping area is relative to the origin of this graphics context, regardless of the value of the translation vector.

  A graphics context uses the following coordinate system:

  - its origin is the top-left corner of the top-left pixel of the destination.
  - its x axis is positive towards the right.
  - its y axis is positive towards the bottom.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `DRAWING_LOG_CLIP_MODIFIED` | Flag stating that the clip area of a graphics context was modified by the low-level side.
    `static int` | `DRAWING_LOG_ERROR` | Flag stating that an error occurred during a drawing.
    `static int` | `DRAWING_LOG_FORBIDDEN` | Flag stating that a function was called in a context that does not allow that operation.
    `static int` | `DRAWING_LOG_LIBRARY_INCIDENT` | Flag describing incidents occurring in a drawing library.
    `static int` | `DRAWING_LOG_MISSING_CHARACTER` | Flag stating that an undefined character was drawn.
    `static int` | `DRAWING_LOG_NOT_IMPLEMENTED` | Flag stating that a drawing function is lacking an implementation.
    `static int` | `DRAWING_LOG_OUT_OF_MEMORY` | Flag stating that the system ran out of memory while attempting to perform a drawing.
    `static int` | `DRAWING_LOG_UNKNOWN_INCIDENT` | Flag describing incidents that do not match other values.
    `static int` | `DRAWING_SUCCESS` | Value used when no incident occurred.
    `static int` | `OPAQUE` | Maximum opacity.
    `static int` | `TRANSPARENT` | Minimum opacity.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GraphicsContext()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `checkDrawingLogFlags()` | Throws an exception if the error flag is currently set.
    `void` | `disableEllipsis()` | Disables ellipsis.
    `void` | `enableEllipsis​(int width)` | Enables ellipsis when drawing characters.
    `static int` | `getAlpha​(int opacityPercent)` | Returns the alpha level for the given opacity percentage.
    `int` | `getAndClearDrawingLogFlags()` | Gets and clears the drawing log flags from a graphics context.
    `int` | `getBackgroundColor()` | Returns the background color of this graphics context.
    `int` | `getClipHeight()` | Returns the height of the clipping area of this graphics context.
    `int` | `getClipWidth()` | Returns the width of the clipping area of this graphics context.
    `int` | `getClipX()` | Returns the x coordinate of the clipping area of this graphics context.
    `int` | `getClipY()` | Returns the y coordinate of the clipping area of this graphics context.
    `int` | `getColor()` | Returns the color of this graphics context.
    `int` | `getEllipsisWidth()` | Returns the width limit before applying the ellipsis.
    `int` | `getHeight()` | Returns the height of this graphics context.
    `int` | `getTranslationX()` | Returns the x coordinate of the translation vector of this graphics context.
    `int` | `getTranslationY()` | Returns the y coordinate of the translation vector of this graphics context.
    `int` | `getWidth()` | Returns the width of this graphics context.
    `boolean` | `hasBackgroundColor()` | Returns whether this graphics context has a background color.
    `void` | `intersectClip​(int x, int y, int width, int height)` | Combines the given clipping rectangle with the clipping area of this graphics context.
    `void` | `notifyDrawingRegion()` | Notifies that the current clip will be considered as a completely repainted region by subsequent drawings.
    `int` | `readPixel​(int x, int y)` | Returns the color of a pixel of this graphics context.
    `void` | `readPixels​(int[] array, int offset, int scanLength, int x, int y, int width, int height)` | Retrieves the color of the pixels of a region of this graphics context.
    `void` | `removeBackgroundColor()` | Removes the background color of this graphics context.
    `void` | `reset()` | Resets this graphics context to its initial configuration.
    `void` | `resetClip()` | Resets the clipping area of this graphics context to its entire bounds.
    `void` | `resetTranslation()` | Resets the translation vector of this graphics context to the `(0,0)` vector.
    `void` | `setBackgroundColor​(int color)` | Sets the background color of this graphics context.
    `void` | `setClip​(int x, int y, int width, int height)` | Sets the clipping area of this graphics context to the given rectangle.
    `void` | `setColor​(int color)` | Sets the color of this graphics context.
    `void` | `setTranslation​(int x, int y)` | Sets the translation vector of this graphics context to the `(x,y)` vector.
    `void` | `translate​(int x, int y)` | Adds a given translation vector to the translation vector of this graphics context.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### OPAQUE

          public static final int OPAQUE

      Maximum opacity.

      The opacity level (called `alpha`) is used by some `Painter` drawing methods to specify the drawing global opacity. When the opacity is maximal, the drawing is fully opaque. When opacity is a value between `TRANSPARENT` and `OPAQUE`, the drawing is merging the foreground color with the destination pixel color or with the global background color. When the opacity is `TRANSPARENT`, the drawing is fully transparent (nothing is drawn).

      The opacity is an unsigned byte value between 0 (fully transparent) and 255 (fully opaque). All other values are meaningless.

      The method `getAlpha(int)` allows to convert an opacity expressed in percentage (0% means fully transparent and 100% fully opaque) in an opacity understandable by the `Painter` drawing methods.

      Since:
        2.0
      See Also:
        `getAlpha(int)`, `Painter.drawImage(GraphicsContext, Image, int, int, int)`, Constant Field Values

    - #### TRANSPARENT

          public static final int TRANSPARENT

      Minimum opacity.

      See `OPAQUE` comment.

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### DRAWING_SUCCESS

          public static final int DRAWING_SUCCESS

      Value used when no incident occurred.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_ERROR

          public static final int DRAWING_LOG_ERROR

      Flag stating that an error occurred during a drawing. This flag will cause an exception to be thrown when checking the flags in the application. No exception will be thrown if this flag is not set, although other flags will keep their state and be readable in the application. This flag is to be combined with other flags describing the error.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_NOT_IMPLEMENTED

          public static final int DRAWING_LOG_NOT_IMPLEMENTED

      Flag stating that a drawing function is lacking an implementation. This flag is typically set when the format of the graphics context is not supported by the implementation.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_FORBIDDEN

          public static final int DRAWING_LOG_FORBIDDEN

      Flag stating that a function was called in a context that does not allow that operation. This flag is typically set when a drawing function has been disabled for a specific format, like a vector drawing function called on a raster-only graphics context.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_OUT_OF_MEMORY

          public static final int DRAWING_LOG_OUT_OF_MEMORY

      Flag stating that the system ran out of memory while attempting to perform a drawing.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_CLIP_MODIFIED

          public static final int DRAWING_LOG_CLIP_MODIFIED

      Flag stating that the clip area of a graphics context was modified by the low-level side. This flag merely warns the user that the clip values returned by `getClipX()`, `getClipY()`, `getClipWidth()` and `getClipHeight()`` may not be identical to the clip values used in the low-level side, notably if the modified low-level values were not properly restored. It is meant to be used as a debugging hint if a drawing seems incorrect.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_MISSING_CHARACTER

          public static final int DRAWING_LOG_MISSING_CHARACTER

      Flag stating that an undefined character was drawn. This happens when drawing a string that contains a character that is not included in the font used.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_LIBRARY_INCIDENT

          public static final int DRAWING_LOG_LIBRARY_INCIDENT

      Flag describing incidents occurring in a drawing library. Refer to the MicroUI implementation in the VEE port for more information about this incident.
      See Also:
        Constant Field Values

    - #### DRAWING_LOG_UNKNOWN_INCIDENT

          public static final int DRAWING_LOG_UNKNOWN_INCIDENT

      Flag describing incidents that do not match other values.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### GraphicsContext

          public GraphicsContext()

  - ### Method Detail

    - #### getAlpha

          public static int getAlpha​(int opacityPercent)

      Returns the alpha level for the given opacity percentage.

      The returned value may be used in some painting methods such as `Painter.drawImage(GraphicsContext, Image, int, int, int)`.

      Parameters:
        `opacityPercent` - the opacity, in percents.
      Returns:
        the alpha level.
      Since:
        2.0

    - #### getWidth

          public int getWidth()

      Returns the width of this graphics context.
      Returns:
        the width of this graphics context, in pixels.

    - #### getHeight

          public int getHeight()

      Returns the height of this graphics context.
      Returns:
        the height of this graphics context, in pixels.

    - #### reset

          public void reset()

      Resets this graphics context to its initial configuration.

      This methods

      - resets both the translation and the clip to their initial state,
      - sets the color to `Colors.BLACK`,
      - removes the background color,
      - resets the ellipsis.

    - #### resetTranslation

          public void resetTranslation()

      Resets the translation vector of this graphics context to the `(0,0)` vector.

    - #### setTranslation

          public void setTranslation​(int x,
                                     int y)

      Sets the translation vector of this graphics context to the `(x,y)` vector.
      Parameters:
        `x` - the x coordinate of the translation vector, in pixels.
        `y` - the y coordinate of the translation vector, in pixels.

    - #### translate

          public void translate​(int x,
                                int y)

      Adds a given translation vector to the translation vector of this graphics context.

      The new translation vector is equal to the sum of the given translation vector and the current translation vector.

      Parameters:
        `x` - the x coordinate of the translation vector to add, in pixels.
        `y` - the y coordinate of the translation vector to add, in pixels.

    - #### getTranslationX

          public int getTranslationX()

      Returns the x coordinate of the translation vector of this graphics context.
      Returns:
        the x coordinate of the translation vector of this graphics context, in pixels.

    - #### getTranslationY

          public int getTranslationY()

      Returns the y coordinate of the translation vector of this graphics context.
      Returns:
        the y coordinate of the translation vector of this graphics context, in pixels.

    - #### setColor

          public void setColor​(int color)

      Sets the color of this graphics context.

      The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

      Parameters:
        `color` - the color to set.

    - #### setBackgroundColor

          public void setBackgroundColor​(int color)

      Sets the background color of this graphics context.

      The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

      The background color is only used by some drawing methods. If the background color is not set, these algorithms have to read the destination pixel color and blend it with the desired color.

      The background color is irrelevant for black and white displays.

      Parameters:
        `color` - the color to set.

    - #### removeBackgroundColor

          public void removeBackgroundColor()

      Removes the background color of this graphics context.

    - #### getColor

          public int getColor()

      Returns the color of this graphics context.

      The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

      Returns:
        the color of this graphics context.

    - #### getBackgroundColor

          public int getBackgroundColor()

      Returns the background color of this graphics context.

      The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

      Returns:
        the background color of this graphics context.

    - #### hasBackgroundColor

          public boolean hasBackgroundColor()

      Returns whether this graphics context has a background color.
      Returns:
        `true` if a background color has been set, `false` otherwise.

    - #### intersectClip

          public void intersectClip​(int x,
                                    int y,
                                    int width,
                                    int height)

      Combines the given clipping rectangle with the clipping area of this graphics context.

      This method sets the clipping area to be the intersection of the given rectangle with the current clipping area.

      Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

      Given clip origin is translated according current graphics context translation.

      Parameters:
        `x` - the x coordinate of the rectangle, in pixels.
        `y` - the y coordinate of the rectangle, in pixels.
        `width` - the width of the rectangle, in pixels.
        `height` - the height of the rectangle, in pixels.

    - #### setClip

          public void setClip​(int x,
                              int y,
                              int width,
                              int height)

      Sets the clipping area of this graphics context to the given rectangle.

      Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

      Given clip origin is translated according current graphics context translation.

      Parameters:
        `x` - the x coordinate of the rectangle, in pixels.
        `y` - the y coordinate of the rectangle, in pixels.
        `width` - the width of the rectangle, in pixels.
        `height` - the height of the rectangle, in pixels.

    - #### resetClip

          public void resetClip()

      Resets the clipping area of this graphics context to its entire bounds.

      The current graphics context translation is not taken into account.

      This is equivalent to calling `gc.setClip(-gc.getTranslationX(), -gc.getTranslationY(), gc.getWidth(), gc.getHeight())`.

    - #### getClipX

          public int getClipX()

      Returns the x coordinate of the clipping area of this graphics context.

      Returned clip origin is translated according current graphics context translation.

      Returns:
        the x coordinate of the clipping area of this graphics context, in pixels.

    - #### getClipY

          public int getClipY()

      Returns the y coordinate of the clipping area of this graphics context.

      Returned clip origin is translated according current graphics context translation.

      Returns:
        the y coordinate of the clipping area of this graphics context, in pixels.

    - #### getClipWidth

          public int getClipWidth()

      Returns the width of the clipping area of this graphics context.
      Returns:
        the width of the clipping area of this graphics context, in pixels.

    - #### getClipHeight

          public int getClipHeight()

      Returns the height of the clipping area of this graphics context.
      Returns:
        the height of the clipping area of this graphics context, in pixels.

    - #### notifyDrawingRegion

          public void notifyDrawingRegion()

      Notifies that the current clip will be considered as a completely repainted region by subsequent drawings. A clip is already considered as a fully repainted region before each drawing. This method allows a larger region to be notified even if the first drawing in this region uses a smaller clip. This may avoid unnecessary restoration of the contents of this region (in whole or in part). This call has no effect when the graphics context does not target the display.

    - #### enableEllipsis

          public void enableEllipsis​(int width)

      Enables ellipsis when drawing characters.

      When ellipsis is enabled, characters are truncated if their rendering width is higher than the specified width limit. In this case, the last visible character is replaced by the ellipsis character (three dots).

      To configure ellipsis using the clipping area as text limit, the given width should be equal to `getClipX() + getClipWidth() - x`, where `x` is the x coordinate of the drawing.

      The ellipsis is only used by the methods drawing characters.

      Parameters:
        `width` - the width limit, in pixels.
      Throws:
        `IllegalArgumentException` - if `width` is negative or zero.

    - #### getEllipsisWidth

          public int getEllipsisWidth()

      Returns the width limit before applying the ellipsis.

      If ellipsis is disabled, this method returns zero.

      Returns:
        the width limit, in pixels.

    - #### disableEllipsis

          public void disableEllipsis()

      Disables ellipsis.

    - #### readPixel

          public int readPixel​(int x,
                               int y)

      Returns the color of a pixel of this graphics context.

      For more information on the format of the color value returned by this method, refer to the first paragraphs of the `centralized pixel reading documentation`.

      Given position is translated according to the current graphics context translation.

      Parameters:
        `x` - the x coordinate of the pixel.
        `y` - the y coordinate of the pixel.
      Returns:
        the color of the pixel, in ARGB format.
      Throws:
        `IllegalArgumentException` - if the given pixel coordinates are out of the bounds of this graphics context.
        `MicroUIException` - if this graphics context is associated with a resource which has been closed.

    - #### readPixels

          public void readPixels​(int[] array,
                                 int offset,
                                 int scanLength,
                                 int x,
                                 int y,
                                 int width,
                                 int height)

      Retrieves the color of the pixels of a region of this graphics context.

      Each pixel color is stored in 32-bit ARGB format, where the high-order byte contains the alpha channel and the remaining bytes contain the red, green and blue channels, respectively. This is relevant regardless of the format in which the pixels are stored internally. The alpha channel specifies the opacity of the pixel, ranging between `TRANSPARENT` and `OPAQUE`.

      The retrieved colors are not guaranteed to be identical to the colors from the original source. Indeed, color values may be resampled to reflect the display capabilities of the device. For example, red, green and blue pixels may all be represented by the same color value on a grayscale device.

      On displays which do not support alpha blending, the alpha component will be equal to `OPAQUE` for opaque pixels and `TRANSPARENT` for every other pixel. On displays that support alpha blending, alpha channel values may be resampled to reflect the number of levels of opacity supported by the display.

      The data is stored in the given `int` array, which should be big enough to hold the color of all the pixels of the region.

      The scan length specifies the relative offset within the array between two pixels of consecutive rows. In order to prevent rows of stored pixels from overlapping, the absolute value of the scan length should be greater than or equal to the width of the region. Negative values of scan length are allowed if the order of rows is inverted in the array.

      If an exception occurs during this method, the contents of the given array will remain unchanged.

      Given position is translated according to the current graphics context translation.

      Parameters:
        `array` - the array in which the pixel data should be stored.
        `offset` - the index of the array at which the first pixel color should be stored.
        `scanLength` - the relative offset in the array between two corresponding pixels in consecutive rows.
        `x` - the x-coordinate of the top-left pixel of the region.
        `y` - the y-coordinate of the top-left pixel of the region.
        `width` - the width of the region.
        `height` - the height of the region.
      Throws:
        `ArrayIndexOutOfBoundsException` - if the array is not big enough to hold the color of all the pixels of the region.
        `IllegalArgumentException` - if a part of the region is out of the bounds of this graphics context.
        `IllegalArgumentException` - if the absolute value of `scanLength` is lower than `width`.
        `MicroUIException` - if this graphics context is associated with a resource which has been closed.

    - #### getAndClearDrawingLogFlags

          public int getAndClearDrawingLogFlags()

      Gets and clears the drawing log flags from a graphics context. The flags are reset to their success value after retrieving their value. This method is identical to `checkDrawingLogFlags()`, except it does not throw an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.
      Returns:
        the drawing log flags

    - #### checkDrawingLogFlags

          public int checkDrawingLogFlags()

      Throws an exception if the error flag is currently set. The drawing log flags are reset to their success value after retrieving their value. This method is identical to `getAndClearDrawingLogFlags()`, except it throws an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.
      Returns:
        the drawing log flags
      Throws:
        `MicroUIException` - if the error flag was set
      See Also:
        `Error flag`