## Class DrawingPanel

- java.lang.Object
- - DrawingPanel

- All Implemented Interfaces:
    ImageObserver

      public final class DrawingPanel
      extends Object
      implements ImageObserver

  DrawingPanel is a simplified Java drawing window class to accompany Building Java Programs textbook and associated materials.

  Authors: Marty Stepp (Stanford University) and Stuart Reges (University of Washington).

  Version: 4.01, 2016/03/08 (to accompany BJP 4th edition).

  You can always download the latest `DrawingPanel` from http://www.buildingjavaprograms.com/drawingpanel/DrawingPanel.java .

  For more information and related materials, please visit www.buildingjavaprograms.com .

  COMPATIBILITY NOTE: This version of DrawingPanel requires Java 8 or higher. To make this file work on Java 7 and lower, you must make two small modifications to its source code. Search for the two occurrences of the annotation @FunctionalInterface and comment them out or remove those lines. Then the file should compile and run properly on older versions of Java.

  ### Description:

  The `DrawingPanel` class provides a simple interface for drawing persistent images using a `Graphics` object. An internal `BufferedImage` object is used to keep track of what has been drawn. A client of the class simply constructs a `DrawingPanel` of a particular size and then draws on it with the `Graphics` object, setting the background color if they so choose.

  The intention is that this custom library will mostly "stay out of the way" so that the client mostly interacts with a standard Java `java.awt.Graphics` object, and therefore most of the experience gained while using this library will transfer to Java graphics programming in other contexts. `DrawingPanel` is not intended to be a full rich graphical library for things like object-oriented drawing of shapes, animations, creating games, etc.

  ### Example basic usage:

  Here is a canonical example of creating a `DrawingPanel` of a given size and using it to draw a few shapes.

       // basic usage example
       DrawingPanel panel = new DrawingPanel(600, 400);
       Graphics g = panel.getGraphics();
       g.setColor(Color.RED);
       g.fillRect(17, 45, 139, 241);
       g.drawOval(234, 77, 100, 100);
       ...

  To ensure that the image is always displayed, a timer calls repaint at regular intervals.

  ### Pixel processing (new in BJP 4th edition):

  This version of `DrawingPanel` allows you to loop over the pixels of an image. You can process each pixel as a `Color` object (easier OO interface, but takes more CPU and memory to run) or as a 32-bit RGB integer (clunkier to use, but much more efficient in runtime and memory usage). Look at the methods get/setPixel(s) to get a better idea.

       // example of horizontally flipping an image
       public static void flipHorizontal(DrawingPanel panel) {
           int width  = panel.getWidth();
           int height = panel.getHeight();
           int[] pixels = panel.getPixelsRGB();
           for (int row = 0; row < height; row++) {
               for (int col = 0; col < width / 2; col++) {
                   // swap this pixel with the one opposite it
                   int col2 = width - 1 - col;
                   int temp = pixels[row][col];
                   pixels[row][col] = pixels[row][col2];
                   pixels[row][col2] = temp;
               }
           }
           panel.setPixels(pixels);
       }

  ### Event listeners and lambdas (new in BJP 4th edition):

  With Java 8, you can now attach event handlers to listen to keyboard and mouse events that occur in a `DrawingPanel` using a lambda function. For example:

       // example of attaching a mouse click handler using Java 8
       panel.onClick( (x, y) -> System.out.println(x + " " + y) );

  ### Debugging facilities (new in BJP 4th edition):

  This version now includes an inner class named `DebuggingGraphics` that keeps track of how many times various drawing methods are called. It includes a `showCounts` method for the `DrawingPanel` itself that allows a client to examine this. The panel will record basic drawing methods performed by a version of the `Graphics` class obtained by calling `getDebuggingGraphics` :

       // example of debugging counts of graphics method calls
       Graphics g = panel.getDebuggingGraphics();

  Novices will be encouraged to simply print it at the end of `main`, as in:

       System.out.println(panel.getCounts());

  ### History and recent changes:

  2016/03/07 - Code cleanup and improvements to JavaDoc comments for BJP4 release.

  2015/09/04 - Now includes methods for get/setting individual pixels and all pixels on the drawing panel. This helps facilitate 2D array-based pixel-processing exercises and problems for Building Java Programs, 4th edition. - Code cleanup and reorganization. Now better alphabetization/formatting of members and encapsulation. Commenting also augmented throughout code.

  2015/04/09 - Now includes a DebuggingGraphics inner class that keeps track of how many times various drawing methods are called. All additions are commented (search for "DebuggingGraphics")

  2011/10/25 - save zoomed images (2011/10/25)

  2011/10/21 - window no longer moves when zoom changes - grid lines

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `DrawingPanel.DPKeyEventHandler` This functional interface is provided to allow Java 8 clients to write lambda functions to handle key events that occur in a DrawingPanel.
    `static interface` | `DrawingPanel.DPMouseEventHandler` This functional interface is provided to allow Java 8 clients to write lambda functions to handle mouse events that occur in a DrawingPanel.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ANIMATED_PROPERTY` An internal constant for setting system properties; clients should not use this.
    `static String` | `ANIMATION_FILE_NAME` An internal constant for setting system properties; clients should not use this.
    `static String` | `AUTO_ENABLE_ANIMATION_ON_SLEEP_PROPERTY` An internal constant for setting system properties; clients should not use this.
    `static int` | `DEFAULT_HEIGHT` The default height of a DrawingPanel in pixels, if none is supplied at construction (400 pixels).
    `static int` | `DEFAULT_WIDTH` The default width of a DrawingPanel in pixels, if none is supplied at construction (500 pixels).
    `static String` | `DIFF_PROPERTY` An internal constant for setting system properties; clients should not use this.
    `static String` | `HEADLESS_PROPERTY` An internal constant for setting system properties; clients should not use this.
    `static String` | `MULTIPLE_PROPERTY` An internal constant for setting system properties; clients should not use this.
    `static int` | `PIXEL_ALPHA` An RGB integer representing alpha at 100% opacity (0xff000000).
    `static int` | `PIXEL_BLUE` An RGB integer representing 100% blue (0x000000ff).
    `static int` | `PIXEL_GREEN` An RGB integer representing 100% green (0x0000ff00).
    `static int` | `PIXEL_RED` An RGB integer representing 100% red (0x00ff0000).
    `static String` | `SAVE_PROPERTY` An internal constant for setting system properties; clients should not use this.

    - ### Fields inherited from interface java.awt.image.ImageObserver

      `ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DrawingPanel()` Constructs a drawing panel with a default width and height enclosed in a window.
    `DrawingPanel(int width, int height)` Constructs a drawing panel of given width and height enclosed in a window.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addKeyListener(KeyListener listener)` Adds the given event listener to respond to key events on this panel.
    `void` | `addMouseListener(MouseListener listener)` Adds the given event listener to respond to mouse events on this panel.
    `void` | `clear()` Erases all drawn shapes/lines/colors from the panel.
    `static int` | `getAlpha(int rgb)` Returns the alpha (opacity) component of the given RGB pixel from 0-255.
    `static int` | `getBlue(int rgb)` Returns the blue component of the given RGB pixel from 0-255.
    `Map<String,Integer>` | `getCounts()` Returns a map of counts of occurrences of calls of various drawing methods.
    `Graphics` | `getDebuggingGraphics()` A variation of getGraphics that returns an object that records a count for various drawing methods.
    `Graphics2D` | `getGraphics()` Obtain the Graphics object to draw on the panel.
    `static int` | `getGreen(int rgb)` Returns the green component of the given RGB pixel from 0-255.
    `int` | `getHeight()` Returns the drawing panel's height in pixels.
    `Color` | `getPixel(int x, int y)` Returns the color of the pixel at the given x/y coordinate as a Color object.
    `int` | `getPixelRGB(int x, int y)` Returns the color of the pixel at the given x/y coordinate as an RGB integer.
    `Color[][]` | `getPixels()` Returns the colors of all pixels in this DrawingPanel as a 2-D array of Color objects.
    `int[][]` | `getPixelsRGB()` Returns the colors of all pixels in this DrawingPanel as a 2-D array of RGB integers.
    `static int` | `getRed(int rgb)` Returns the red component of the given RGB pixel from 0-255.
    `Dimension` | `getSize()` Returns the drawing panel's pixel size (width, height) as a Dimension object.
    `int` | `getWidth()` Returns the drawing panel's width in pixels.
    `int` | `getZoom()` Returns the drawing panel's current zoom factor.
    `boolean` | `imageUpdate(Image img, int infoflags, int x, int y, int width, int height)` Internal method; notifies the panel when images are loaded and updated.
    `Image` | `loadImage(String filename)` Loads an image from the given file on disk and returns it as an Image object.
    `static boolean` | `mainIsActive()` Internal method; returns whether the 'main' thread is still running.
    `void` | `onClick(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse clicks.
    `void` | `onDrag(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse drags.
    `void` | `onEnter(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse enters.
    `void` | `onExit(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse exits.
    `void` | `onKeyDown(DrawingPanel.DPKeyEventHandler e)` Adds an event handler for key presses.
    `void` | `onKeyUp(DrawingPanel.DPKeyEventHandler e)` Adds an event handler for key releases.
    `void` | `onMouseClick(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse clicks.
    `void` | `onMouseDown(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse button down events.
    `void` | `onMouseDrag(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse drags.
    `void` | `onMouseEnter(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse enters.
    `void` | `onMouseExit(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse exits.
    `void` | `onMouseMove(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse movement.
    `void` | `onMouseUp(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse button up events.
    `void` | `onMove(DrawingPanel.DPMouseEventHandler e)` Adds an event handler for mouse movement.
    `void` | `save(String filename)` Takes the current contents of the drawing panel and writes them to the given file.
    `void` | `saveAnimated(String filename)` Takes the current contents of the drawing panel and writes them to the given file.
    `void` | `setAlwaysOnTop(boolean alwaysOnTop)` Sets whether the panel will always cover other windows (default false).
    `void` | `setAntiAlias(boolean antiAlias)` Sets whether the panel should use anti-aliased / smoothed graphics (default true).
    `void` | `setBackground(Color c)` Sets the background color of the drawing panel to be the given color.
    `void` | `setBackground(int rgb)` Sets the background color of the drawing panel to be the color represented by the given RGB integer.
    `void` | `setGridLines(boolean gridLines)` Enables or disables the drawing of grid lines on top of the image to help with debugging sizes and coordinates.
    `void` | `setGridLines(boolean gridLines, int pxGap)` Enables or disables the drawing of grid lines on top of the image to help with debugging sizes and coordinates.
    `void` | `setHeight(int height)` Sets the drawing panel's height in pixels to the given value.
    `void` | `setPixel(int x, int y, Color color)` Sets the color of the pixel at the given x/y coordinate to be the given color.
    `void` | `setPixel(int x, int y, int rgb)` Sets the color of the pixel at the given x/y coordinate to be the color represented by the given RGB integer.
    `void` | `setPixelRGB(int x, int y, int rgb)` Sets the color of the pixel at the given x/y coordinate to be the color represented by the given RGB integer.
    `void` | `setPixels(Color[][] pixels)` Sets the colors of all pixels in this DrawingPanel to the colors in the given 2-D array of Color objects.
    `void` | `setPixels(int[][] pixels)` Sets the colors of all pixels in this DrawingPanel to the colors represented by the given 2-D array of RGB integers.
    `void` | `setPixelsRGB(int[][] pixels)` Sets the colors of all pixels in this DrawingPanel to the colors represented by the given 2-D array of RGB integers.
    `void` | `setSize(int width, int height)` Sets the drawing panel's pixel size (width, height) to the given values.
    `void` | `setVisible(boolean visible)` Show or hide the drawing panel on the screen.
    `void` | `setWidth(int width)` Sets the drawing panel's width in pixels to the given value.
    `void` | `sleep(int millis)` Causes the program to pause for the given amount of time in milliseconds.
    `void` | `toFront()` Moves the drawing panel window on top of other windows so it can be seen.
    `static int` | `toRgbInteger(int r, int g, int b)` Returns an RGB integer made from the given red, green, and blue components from 0-255.
    `static int` | `toRgbInteger(int alpha, int r, int g, int b)` Returns an RGB integer made from the given alpha, red, green, and blue components from 0-255.
    `void` | `zoom(int zoomFactor)` Zooms the drawing panel in/out to the given factor.

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

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

- - ### Field Detail

    - #### PIXEL_ALPHA

          public static final int PIXEL_ALPHA

      An RGB integer representing alpha at 100% opacity (0xff000000).
      See Also:
        Constant Field Values

    - #### PIXEL_BLUE

          public static final int PIXEL_BLUE

      An RGB integer representing 100% blue (0x000000ff).
      See Also:
        Constant Field Values

    - #### PIXEL_GREEN

          public static final int PIXEL_GREEN

      An RGB integer representing 100% green (0x0000ff00).
      See Also:
        Constant Field Values

    - #### PIXEL_RED

          public static final int PIXEL_RED

      An RGB integer representing 100% red (0x00ff0000).
      See Also:
        Constant Field Values

    - #### DEFAULT_WIDTH

          public static final int DEFAULT_WIDTH

      The default width of a DrawingPanel in pixels, if none is supplied at construction (500 pixels).
      See Also:
        Constant Field Values

    - #### DEFAULT_HEIGHT

          public static final int DEFAULT_HEIGHT

      The default height of a DrawingPanel in pixels, if none is supplied at construction (400 pixels).
      See Also:
        Constant Field Values

    - #### ANIMATED_PROPERTY

          public static final String ANIMATED_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### ANIMATION_FILE_NAME

          public static final String ANIMATION_FILE_NAME

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### AUTO_ENABLE_ANIMATION_ON_SLEEP_PROPERTY

          public static final String AUTO_ENABLE_ANIMATION_ON_SLEEP_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### DIFF_PROPERTY

          public static final String DIFF_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### HEADLESS_PROPERTY

          public static final String HEADLESS_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### MULTIPLE_PROPERTY

          public static final String MULTIPLE_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

    - #### SAVE_PROPERTY

          public static final String SAVE_PROPERTY

      An internal constant for setting system properties; clients should not use this.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DrawingPanel

          public DrawingPanel()

      Constructs a drawing panel with a default width and height enclosed in a window. Uses DEFAULT_WIDTH and DEFAULT_HEIGHT for the panel's size.

    - #### DrawingPanel

          public DrawingPanel(int width,
                              int height)

      Constructs a drawing panel of given width and height enclosed in a window.
      Parameters:
        `width` - panel's width in pixels
        `height` - panel's height in pixels

  - ### Method Detail

    - #### getRed

          public static int getRed(int rgb)

      Returns the red component of the given RGB pixel from 0-255. Often used in conjunction with the methods getPixelRGB, setPixelRGB, etc.
      Parameters:
        `rgb` - RGB integer with alpha in bits 0-7, red in bits 8-15, green in bits 16-23, and blue in bits 24-31
      Returns:
        red component from 0-255

    - #### getGreen

          public static int getGreen(int rgb)

      Returns the green component of the given RGB pixel from 0-255. Often used in conjunction with the methods getPixelRGB, setPixelRGB, etc.
      Parameters:
        `rgb` - RGB integer with alpha in bits 0-7, red in bits 8-15, green in bits 16-23, and blue in bits 24-31
      Returns:
        green component from 0-255

    - #### getBlue

          public static int getBlue(int rgb)

      Returns the blue component of the given RGB pixel from 0-255. Often used in conjunction with the methods getPixelRGB, setPixelRGB, etc.
      Parameters:
        `rgb` - RGB integer with alpha in bits 0-7, red in bits 8-15, green in bits 16-23, and blue in bits 24-31
      Returns:
        blue component from 0-255

    - #### getAlpha

          public static int getAlpha(int rgb)

      Returns the alpha (opacity) component of the given RGB pixel from 0-255. Often used in conjunction with the methods getPixelRGB, setPixelRGB, etc.
      Parameters:
        `rgb` - RGB integer with alpha in bits 0-7, red in bits 8-15, green in bits 16-23, and blue in bits 24-31
      Returns:
        alpha component from 0-255

    - #### mainIsActive

          public static boolean mainIsActive()

      Internal method; returns whether the 'main' thread is still running. Used to determine whether to exit the program when the drawing panel is closed by the user. This is an internal method not meant to be called by clients.
      Returns:
        true if main thread is still running

    - #### toRgbInteger

          public static int toRgbInteger(int r,
                                         int g,
                                         int b)

      Returns an RGB integer made from the given red, green, and blue components from 0-255. The returned integer is suitable for use with various RGB integer methods in this class such as setPixel.
      Parameters:
        `r` - red component from 0-255 (bits 8-15)
        `g` - green component from 0-255 (bits 16-23)
        `b` - blue component from 0-255 (bits 24-31)
      Returns:
        RGB integer with full 255 for alpha and r-g-b in bits 8-31
      Throws:
        `IllegalArgumentException` - if r, g, or b is not in 0-255 range

    - #### toRgbInteger

          public static int toRgbInteger(int alpha,
                                         int r,
                                         int g,
                                         int b)

      Returns an RGB integer made from the given alpha, red, green, and blue components from 0-255. The returned integer is suitable for use with various RGB integer methods in this class such as setPixel.
      Parameters:
        `alpha` - alpha (transparency) component from 0-255 (bits 0-7)
        `r` - red component from 0-255 (bits 8-15)
        `g` - green component from 0-255 (bits 16-23)
        `b` - blue component from 0-255 (bits 24-31)
      Returns:
        RGB integer with the given four components
      Throws:
        `IllegalArgumentException` - if alpha, r, g, or b is not in 0-255 range

    - #### addKeyListener

          public void addKeyListener(KeyListener listener)

      Adds the given event listener to respond to key events on this panel.
      Parameters:
        `listener` - the key event listener to attach

    - #### addMouseListener

          public void addMouseListener(MouseListener listener)

      Adds the given event listener to respond to mouse events on this panel.
      Parameters:
        `listener` - the mouse event listener to attach

    - #### clear

          public void clear()

      Erases all drawn shapes/lines/colors from the panel.

    - #### getCounts

          public Map<String,Integer> getCounts()

      Returns a map of counts of occurrences of calls of various drawing methods. You can print this map to see how many times your graphics methods have been called to aid in debugging.
      Returns:
        map of {method name, count} pairs

    - #### getDebuggingGraphics

          public Graphics getDebuggingGraphics()

      A variation of getGraphics that returns an object that records a count for various drawing methods. See also: getCounts
      Returns:
        debug Graphics object

    - #### getGraphics

          public Graphics2D getGraphics()

      Obtain the Graphics object to draw on the panel.
      Returns:
        panel's Graphics object

    - #### getHeight

          public int getHeight()

      Returns the drawing panel's height in pixels.
      Returns:
        drawing panel's height in pixels

    - #### getPixel

          public Color getPixel(int x,
                                int y)

      Returns the color of the pixel at the given x/y coordinate as a Color object. If nothing has been explicitly drawn on this particular pixel, the panel's background color is returned.
      Parameters:
        `x` - x-coordinate of pixel to retrieve
        `y` - y-coordinate of pixel to retrieve
      Returns:
        pixel (x, y) color as a Color object
      Throws:
        `IllegalArgumentException` - if (x, y) is out of range

    - #### getPixelRGB

          public int getPixelRGB(int x,
                                 int y)

      Returns the color of the pixel at the given x/y coordinate as an RGB integer. The individual red, green, and blue components of the RGB integer can be extracted from this by calling DrawingPanel.getRed, getGreen, and getBlue. If nothing has been explicitly drawn on this particular pixel, the panel's background color is returned. See also: getPixel.
      Parameters:
        `x` - x-coordinate of pixel to retrieve
        `y` - y-coordinate of pixel to retrieve
      Returns:
        pixel (x, y) color as an RGB integer
      Throws:
        `IllegalArgumentException` - if (x, y) is out of range

    - #### getPixels

          public Color[][] getPixels()

      Returns the colors of all pixels in this DrawingPanel as a 2-D array of Color objects. The first index of the array is the y-coordinate, and the second index is the x-coordinate. So, for example, index [r][c] represents the RGB pixel data for the pixel at position (x=c, y=r).
      Returns:
        2D array of colors (row-major)

    - #### getPixelsRGB

          public int[][] getPixelsRGB()

      Returns the colors of all pixels in this DrawingPanel as a 2-D array of RGB integers. The first index of the array is the y-coordinate, and the second index is the x-coordinate. So, for example, index [r][c] represents the RGB pixel data for the pixel at position (x=c, y=r). The individual red, green, and blue components of each RGB integer can be extracted from this by calling DrawingPanel.getRed, getGreen, and getBlue.
      Returns:
        2D array of RGB integers (row-major)

    - #### getSize

          public Dimension getSize()

      Returns the drawing panel's pixel size (width, height) as a Dimension object.
      Returns:
        panel's size

    - #### getWidth

          public int getWidth()

      Returns the drawing panel's width in pixels.
      Returns:
        panel's width

    - #### getZoom

          public int getZoom()

      Returns the drawing panel's current zoom factor. Initially this is 1 to indicate 100% zoom, the original size. A factor of 2 would indicate 200% zoom, and so on.
      Returns:
        zoom factor (default 1)

    - #### imageUpdate

          public boolean imageUpdate(Image img,
                                     int infoflags,
                                     int x,
                                     int y,
                                     int width,
                                     int height)

      Internal method; notifies the panel when images are loaded and updated. This is a required method of ImageObserver interface. This is an internal method not meant to be called by clients.
      Specified by:
        `imageUpdate` in interface `ImageObserver`
      Parameters:
        `img` - internal method; do not call
        `infoflags` - internal method; do not call
        `x` - internal method; do not call
        `y` - internal method; do not call
        `width` - internal method; do not call
        `height` - internal method; do not call
      Returns:
        `false` if the infoflags indicate that the image is completely loaded; `true` otherwise.
      See Also:
        `ImageObserver.WIDTH`, `ImageObserver.HEIGHT`, `ImageObserver.PROPERTIES`, `ImageObserver.SOMEBITS`, `ImageObserver.FRAMEBITS`, `ImageObserver.ALLBITS`, `ImageObserver.ERROR`, `ImageObserver.ABORT`, `Image.getWidth(java.awt.image.ImageObserver)`, `Image.getHeight(java.awt.image.ImageObserver)`, `Graphics.drawImage(java.awt.Image, int, int, java.awt.image.ImageObserver)`

    - #### loadImage

          public Image loadImage(String filename)

      Loads an image from the given file on disk and returns it as an Image object.
      Parameters:
        `filename` - name/path of the file to load
      Returns:
        loaded image object
      Throws:
        `NullPointerException` - if filename is null
        `RuntimeException` - if the given file is not found

    - #### onClick

          public void onClick(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse clicks. You can pass a lambda function here to be called when a mouse click event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onDrag

          public void onDrag(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse drags. You can pass a lambda function here to be called when a mouse drag event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onEnter

          public void onEnter(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse enters. You can pass a lambda function here to be called when a mouse enter event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onExit

          public void onExit(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse exits. You can pass a lambda function here to be called when a mouse exit event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onKeyDown

          public void onKeyDown(DrawingPanel.DPKeyEventHandler e)

      Adds an event handler for key presses. You can pass a lambda function here to be called when a key press event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onKeyUp

          public void onKeyUp(DrawingPanel.DPKeyEventHandler e)

      Adds an event handler for key releases. You can pass a lambda function here to be called when a key release event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseClick

          public void onMouseClick(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse clicks. You can pass a lambda function here to be called when a mouse click event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseDown

          public void onMouseDown(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse button down events. You can pass a lambda function here to be called when a mouse button down event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseDrag

          public void onMouseDrag(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse drags. You can pass a lambda function here to be called when a mouse drag event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseEnter

          public void onMouseEnter(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse enters. You can pass a lambda function here to be called when a mouse enter event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseExit

          public void onMouseExit(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse exits. You can pass a lambda function here to be called when a mouse exit event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseMove

          public void onMouseMove(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse movement. You can pass a lambda function here to be called when a mouse move event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMouseUp

          public void onMouseUp(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse button up events. You can pass a lambda function here to be called when a mouse button up event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### onMove

          public void onMove(DrawingPanel.DPMouseEventHandler e)

      Adds an event handler for mouse movement. You can pass a lambda function here to be called when a mouse move event occurs.
      Parameters:
        `e` - event handler function to call
      Throws:
        `NullPointerException` - if event handler is null

    - #### save

          public void save(String filename)
                    throws IOException

      Takes the current contents of the drawing panel and writes them to the given file.
      Parameters:
        `filename` - name/path of the file to save
      Throws:
        `NullPointerException` - if filename is null
        `IOException` - if the given file cannot be written

    - #### saveAnimated

          public void saveAnimated(String filename)
                            throws IOException

      Takes the current contents of the drawing panel and writes them to the given file.
      Parameters:
        `filename` - name/path of the file to save
      Throws:
        `NullPointerException` - if filename is null
        `IOException` - if the given file cannot be written

    - #### setAlwaysOnTop

          public void setAlwaysOnTop(boolean alwaysOnTop)

      Sets whether the panel will always cover other windows (default false).
      Parameters:
        `alwaysOnTop` - true if the panel should always cover other windows

    - #### setAntiAlias

          public void setAntiAlias(boolean antiAlias)

      Sets whether the panel should use anti-aliased / smoothed graphics (default true).
      Parameters:
        `antiAlias` - true if the panel should be smoothed

    - #### setBackground

          public void setBackground(Color c)

      Sets the background color of the drawing panel to be the given color.
      Parameters:
        `c` - color to use as background
      Throws:
        `NullPointerException` - if color is null

    - #### setBackground

          public void setBackground(int rgb)

      Sets the background color of the drawing panel to be the color represented by the given RGB integer.
      Parameters:
        `rgb` - RGB integer to use as background color (full alpha assumed/applied)

    - #### setGridLines

          public void setGridLines(boolean gridLines)

      Enables or disables the drawing of grid lines on top of the image to help with debugging sizes and coordinates. By default the grid lines will be shown every 10 pixels in each dimension.
      Parameters:
        `gridLines` - whether to show grid lines (true) or not (false)

    - #### setGridLines

          public void setGridLines(boolean gridLines,
                                   int pxGap)

      Enables or disables the drawing of grid lines on top of the image to help with debugging sizes and coordinates. The grid lines will be shown every pxGap pixels in each dimension.
      Parameters:
        `gridLines` - whether to show grid lines (true) or not (false)
        `pxGap` - number of pixels between grid lines

    - #### setHeight

          public void setHeight(int height)

      Sets the drawing panel's height in pixels to the given value. After calling this method, the client must call getGraphics() again to get the new graphics context of the newly enlarged image buffer.
      Parameters:
        `height` - height, in pixels
      Throws:
        `IllegalArgumentException` - if height is negative or exceeds MAX_SIZE

    - #### setPixel

          public void setPixel(int x,
                               int y,
                               Color color)

      Sets the color of the pixel at the given x/y coordinate to be the given color. If the color is null, the call has no effect.
      Parameters:
        `x` - x-coordinate of pixel to set
        `y` - y-coordinate of pixel to set
        `color` - Color to set the pixel to use
      Throws:
        `IllegalArgumentException` - if x or y is out of bounds
        `NullPointerException` - if color is null

    - #### setPixel

          public void setPixel(int x,
                               int y,
                               int rgb)

      Sets the color of the pixel at the given x/y coordinate to be the color represented by the given RGB integer. The passed RGB integer's alpha value is ignored and a full alpha of 255 is always used here, to avoid common bugs with using a 0 value for alpha. See also: setPixel. See also: setPixelRGB.
      Parameters:
        `x` - x-coordinate of pixel to set
        `y` - y-coordinate of pixel to set
        `rgb` - RGB integer representing the color to set the pixel to use
      Throws:
        `IllegalArgumentException` - if x or y is out of bounds

    - #### setPixelRGB

          public void setPixelRGB(int x,
                                  int y,
                                  int rgb)

      Sets the color of the pixel at the given x/y coordinate to be the color represented by the given RGB integer. The passed RGB integer's alpha value is ignored and a full alpha of 255 is always used here, to avoid common bugs with using a 0 value for alpha. See also: setPixel.
      Parameters:
        `x` - x-coordinate of pixel to set
        `y` - y-coordinate of pixel to set
        `rgb` - RGB integer representing the color to set the pixel to use
      Throws:
        `IllegalArgumentException` - if x or y is out of bounds

    - #### setPixels

          public void setPixels(Color[][] pixels)

      Sets the colors of all pixels in this DrawingPanel to the colors in the given 2-D array of Color objects. The first index of the array is the y-coordinate, and the second index is the x-coordinate. So, for example, index [r][c] represents the RGB pixel data for the pixel at position (x=c, y=r). If the given array's dimensions do not match the width/height of the drawing panel, the panel is resized to match the array. If the pixel array is null or size 0, the call has no effect. If any rows or colors in the array are null, those pixels will be ignored. The 2-D array passed is assumed to be rectangular in length (not jagged).
      Parameters:
        `pixels` - 2D array of pixels (row-major)
      Throws:
        `NullPointerException` - if pixels array is null

    - #### setPixels

          public void setPixels(int[][] pixels)

      Sets the colors of all pixels in this DrawingPanel to the colors represented by the given 2-D array of RGB integers. The first index of the array is the y-coordinate, and the second index is the x-coordinate. So, for example, index [r][c] represents the RGB pixel data for the pixel at position (x=c, y=r). If the given array's dimensions do not match the width/height of the drawing panel, the panel is resized to match the array. If the pixel array is null or size 0, the call has no effect. The 2-D array passed is assumed to be rectangular in length (not jagged).
      Parameters:
        `pixels` - 2D array of pixels (row-major)
      Throws:
        `NullPointerException` - if pixels array is null

    - #### setPixelsRGB

          public void setPixelsRGB(int[][] pixels)

      Sets the colors of all pixels in this DrawingPanel to the colors represented by the given 2-D array of RGB integers. The first index of the array is the y-coordinate, and the second index is the x-coordinate. So, for example, index [r][c] represents the RGB pixel data for the pixel at position (x=c, y=r). If the given array's dimensions do not match the width/height of the drawing panel, the panel is resized to match the array. If the pixel array is null or size 0, the call has no effect. The 2-D array passed is assumed to be rectangular in length (not jagged).
      Parameters:
        `pixels` - 2D array of pixels (row-major)
      Throws:
        `NullPointerException` - if pixels array is null

    - #### setSize

          public void setSize(int width,
                              int height)

      Sets the drawing panel's pixel size (width, height) to the given values. After calling this method, the client must call getGraphics() again to get the new graphics context of the newly enlarged image buffer.
      Parameters:
        `width` - width, in pixels
        `height` - height, in pixels
      Throws:
        `IllegalArgumentException` - if width/height is negative or exceeds MAX_SIZE

    - #### setVisible

          public void setVisible(boolean visible)

      Show or hide the drawing panel on the screen.
      Parameters:
        `visible` - true to show, false to hide

    - #### setWidth

          public void setWidth(int width)

      Sets the drawing panel's width in pixels to the given value. After calling this method, the client must call getGraphics() again to get the new graphics context of the newly enlarged image buffer.
      Parameters:
        `width` - width, in pixels
      Throws:
        `IllegalArgumentException` - if height is negative or exceeds MAX_SIZE

    - #### sleep

          public void sleep(int millis)

      Causes the program to pause for the given amount of time in milliseconds. This allows for animation by calling pause in a loop. If the DrawingPanel is not showing on the screen, has no effect.
      Parameters:
        `millis` - number of milliseconds to sleep
      Throws:
        `IllegalArgumentException` - if a negative number of ms is passed

    - #### toFront

          public void toFront()

      Moves the drawing panel window on top of other windows so it can be seen.

    - #### zoom

          public void zoom(int zoomFactor)

      Zooms the drawing panel in/out to the given factor. A zoom factor of 1, the default, indicates normal size. A zoom factor of 2 would indicate 200% size, and so on. The factor value passed should be at least 1; if not, 1 will be used.
      Parameters:
        `zoomFactor` - the zoom factor to use (1 or greater)