Draggable Symbols I

For many applications in design, modeling, games, and so on, it is important for the user to be able to drag symbols from one part of the display screen to another. For example, in touchscreen Android phones it is common to move application icons to different positions or different folders by long-pressing (holding down longer than a tap) on the icon with a finger, dragging it to the new location, and then raising your finger. In this project we develop some techniques for dragging arbitrary user-defined symbols around the screen. The primary technology that we shall use involves

1. The MotionEvent class, which detects and manages events on the device touchscreen.


2. The Canvas class, which manages draws and redraws on the screen (see the Canvas and Drawables developer guide).


3. The Paint class, which holds the style and color information about objects to be drawn on the screen.


4. Drawable, which provides a generic API for dealing with visual resources.


5. The class Display, which provides information about the size and pixel density of the device screen to enable a screen layout that adapts to different devices.

Although the examples that we shall discuss here and in the following Draggable Symbols II are relatively simple, they provide an introduction to implementing motion events and screen animation that can be the basis for much more sophisticated applications.

Creating the Project in Android Studio

Following the general procedure in Creating a New Project, either choose Start a new Android Studio project from the Android Studio homepage, or from the Android Studio interface choose File > New > New Project. Fill out the fields in the resulting screens as follows,

where your namespace should be substituted for <YourNamespace> (com.lightcone in my case) and <ProjectPath> is the path to the directory where you will store this Android Studio Project (/home/guidry/StudioProjects/ in my case). If you have chosen to use version control for your projects, go ahead and commit this project to version control.

Setting Up the Problem

Rather than putting this example together piece by piece, we shall give the complete listing for the two classes to be used and then dissect the functionality of each. In this example, the complete layout will be done using Java (there will be no XML files needed at all in the res/layout directory), so all the action will involve just two Java classes and some Drawable image resource files that they interact with.

Copying Resources

Let's first copy some resources that will be needed. Open the course images directory and copy the files green_square.png, red_square.png, and yellow_square.png to the res/drawable directory of the DraggableSymbols project. You may then need to left-click on res/drawable in the Android Studio package explorer pane and select Refresh to get these files to appear in Android Studio. Alternatively, you can copy the files with a mouse and paste them directly into res/drawable in the project pane of Android Studio.

The Class SymbolDragger

The primary purpose of the MainActivity class will be to set up some resource arrays and then to pass them to an instance of the class SymbolDragger, which will do all the work. So let's create SymbolDragger. Right-click on java/<namespace>/draggablesymbols and select New > Java Class. In the resulting popup give the name SymbolsDragger and select Class as the kind. This will create the new class file SymbolDragger.java. Edit this file so that it has the content

package <YourNamespace>.draggablesymbols;

import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.drawable.Drawable;
import android.os.Build;
import android.view.MotionEvent;
import android.view.View;

/*
Demonstration of one way to put a set of draggable symbols on screen.
Adapted loosely from material discussed in
http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html
See also
http://android-developers.blogspot.com/2010/07/how-to-have-your-cupcake-and-eat-it-too.html .   
*/

public class SymbolDragger extends View {

      // Colors for background and text
      private static final int BACKGROUND_COLOR = Color.argb(255, 230, 230, 230);
      private static final int HEADER_COLOR = Color.argb(255, 210, 210, 210);
      private static final int TEXT_COLOR = Color.argb(255, 0, 0, 0);

      private int numberSymbols; // Total number of symbols to use
      private Drawable[] symbol; // Array of symbols (dimension numberSymbols)
      private float[] X; // Current x coordinate, upper left corner of symbol
      private float[] Y; // Current y coordinate, upper left corner of symbol
      private int[] symbolWidth; // Width of symbol
      private int[] symbolHeight; // Height of symbol
      private float[] lastTouchX; // x coordinate of symbol at last touch
      private float[] lastTouchY; // y coordinate of symbol at last touch
      private int symbolSelected; // Index of symbol last touched (-1 if none)
      private Paint paint;

      // Following define upper left and lower right corners of display stage rectangle
      private int stageX1 = 0;
      private int stageY1 = MainActivity.topMargin;
      private int stageX2 = MainActivity.screenWidth;
      private int stageY2 = MainActivity.screenHeight;

      private boolean isDragging = false; // True if some symbol is being dragged

      // Simplest default constructor. Not used, but prevents a warning message.
      public SymbolDragger(Context context) {
               super(context);
      }

      public SymbolDragger(Context context, float[] X, float[] Y,
                        int[] symbolIndex) {

               // Call through to simplest constructor of View superclass
               super(context);

               // Set up local arrays defining symbol positions with the initial
               // positions passed as arguments in the constructor

               this.X = X;
               this.Y = Y;

               numberSymbols = X.length;
               symbol = new Drawable[numberSymbols];
               symbolWidth = new int[numberSymbols];
               symbolHeight = new int[numberSymbols];
               lastTouchX = new float[numberSymbols];
               lastTouchY = new float[numberSymbols];

               // Fill the symbol arrays with data
               for (int i = 0; i < numberSymbols; i++) {
               
                        // Handle method getDrawable deprecated as of API 22
                        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                           // Theme required but set to null since no styling for it
                           symbol[i] = context.getResources().getDrawable(symbolIndex[i],null);
                        } else {
                           symbol[i] = context.getResources().getDrawable(symbolIndex[i]);
                        }
  
                        symbolWidth[i] = symbol[i].getIntrinsicWidth();
                        symbolHeight[i] = symbol[i].getIntrinsicHeight();
                        symbol[i].setBounds(0, 0, symbolWidth[i], symbolHeight[i]);
               }

               // Set up the Paint object that will control format of screen draws
               paint = new Paint();
               paint.setAntiAlias(true);
               paint.setTextSize(36);
               paint.setStrokeWidth(0);
      }

      /*
         * Process MotionEvents corresponding to screen touches and drags.
         * MotionEvent reports movement (mouse, pen, finger, trackball) events. The
         * MotionEvent method getAction() returns the kind of action being performed
         * as an integer constant of the MotionEvent class, with possible values
         * ACTION_DOWN, ACTION_MOVE, ACTION_UP, and ACTION_CANCEL. Thus we can
         * switch on the returned integer to determine the kind of event and the
         * appropriate action.
         */

      @Override
      public boolean onTouchEvent(MotionEvent ev) {

               final int action = ev.getAction();

               switch (action) {

               // MotionEvent class constant signifying a finger-down event

               case MotionEvent.ACTION_DOWN: {

                        isDragging = false;

                        // Get coordinates of touch event
                        final float x = ev.getX();
                        final float y = ev.getY();

                        // Initialize. Will be -1 if not within the current bounds of some
                        // symbol.

                        symbolSelected = -1;

                        // Determine if touch within bounds of one of the symbols

                        for (int i = 0; i < numberSymbols; i++) {
                              if ((x > X[i] && x < (X[i] + symbolWidth[i]))
                                                && (y > Y[i] && y < (Y[i] + symbolHeight[i]))) {
                                       symbolSelected = i;
                                       break;
                              }
                        }

                        // If touch within bounds of a symbol, remember start position for
                        // this symbol

                        if (symbolSelected > -1) {
                              lastTouchX[symbolSelected] = x;
                              lastTouchY[symbolSelected] = y;
                        }
                        break;
               }

               // MotionEvent class constant signifying a finger-drag event

               case MotionEvent.ACTION_MOVE: {

                        // Only process if touch selected a symbol
                        if (symbolSelected > -1) {
                              isDragging = true;
                              final float x = ev.getX();
                              final float y = ev.getY();

                              // Calculate the distance moved
                              final float dx = x - lastTouchX[symbolSelected];
                              final float dy = y - lastTouchY[symbolSelected];

                              // Move the object selected. Note that we are simply
                              // illustrating how to drag symbols. In an actual application,
                              // you would probably want to add some logic to confine the symbols
                              // to a region the size of the visible stage or smaller.

                              X[symbolSelected] += dx;
                              Y[symbolSelected] += dy;

                              // Remember this touch position for the next move event of this object
                              lastTouchX[symbolSelected] = x;
                              lastTouchY[symbolSelected] = y;

                              // Request a redraw
                              invalidate();

                        }
                        break;
               }

               // MotionEvent class constant signifying a finger-up event

               case MotionEvent.ACTION_UP:
                        isDragging = false;
                        invalidate(); // Request redraw
                        break;

               }
               return true;
      }

      // This method will be called each time the screen is redrawn. The draw is
      // on the Canvas object, with formatting controlled by the Paint object.
      // When to redraw is under Android control, but we can request a redraw
      // using the method invalidate() inherited from the View superclass.

      @Override
      public void onDraw(Canvas canvas) {
               super.onDraw(canvas);

               // Draw backgrounds
               drawBackground(paint, canvas);

               // Draw all draggable symbols at their current locations
               for (int i = 0; i < numberSymbols; i++) {
                        canvas.save();
                        canvas.translate(X[i], Y[i]);
                        symbol[i].draw(canvas);
                        canvas.restore();
               }
               isDragging = false;
      }

      // Method to draw the background for the screen. Invoked from onDraw each
      // time the screen is redrawn.

      private void drawBackground(Paint paint, Canvas canvas) {

               // Draw header bar background
               paint.setColor(HEADER_COLOR);
               canvas.drawRect(0, 0, stageX2, stageY2, paint);

               // Draw main stage background
               paint.setColor(BACKGROUND_COLOR);
               canvas.drawRect(stageX1, stageY1, stageX2, stageY2, paint);

               // If dragging a symbol, display its x and y coordinates in a readout
               if (isDragging) {
                        paint.setColor(TEXT_COLOR);
                        canvas.drawText("X = " + X[symbolSelected],
                                       MainActivity.screenWidth / 2,
                                       MainActivity.topMargin / 2 - 10, paint);
                        canvas.drawText("Y = " + Y[symbolSelected],
                                       MainActivity.screenWidth / 2,
                                       MainActivity.topMargin / 2 + 20, paint);
               }
      }
}

There will be some errors (things marked in red and wiggly-underlined in red) as Android studio compiles this on the fly. Ignore them. They are because the class just defined is referencing variables that have not been inserted yet in the class MainActivity.java, and that will be fixed in the next step.

The Class MainActivity

Now edit the file MainActivity.java in src/<namespace>/draggablesymbols so that it reads

package <YourPackageIdentifier>.draggablesymbols;

import android.os.Build;
import android.os.Bundle;
import android.graphics.Point;
import android.util.Log;
import android.view.Display;
import android.view.ViewGroup;
import android.support.v7.app.AppCompatActivity;

public class MainActivity extends AppCompatActivity {

      private static final String TAG = "Dragger";

      // Screen dimensions and positioning offsets
      public static int screenWidth;
      public static int screenHeight;
      public static int topMargin = 0;
      private static final int xoff = 2;
      private static final int yoff = 2;
      private static final int xgap = 1;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
               super.onCreate(savedInstanceState);

               // Get the screen dimensions
               Display display = getWindowManager().getDefaultDisplay();
               Point size = new Point();
               display.getSize(size);
               screenWidth = size.x;
               screenHeight = size.y;

               Log.i(TAG, "Screen width=" + screenWidth + " height=" + screenHeight);

               // Put the reference to the symbols to be used in an array.
               // The Drawable corresponds to the symbol. R.drawable.file refers to
               // file.png, .jpg, or .gif stored in res/drawable (referenced
               // from code without the extension).

               int[] symbolIndex = { R.drawable.red_square, R.drawable.green_square,
                              R.drawable.yellow_square };

               int numberSymbols = symbolIndex.length; // Total number of symbols to use
               int[] symbolWidth = new int[numberSymbols]; // Width of symbol in pixels
               int[] symbolHeight = new int[numberSymbols]; // Height of symbol in pixels

               // Determine the height and width of the symbols for positioning issues

               for (int i = 0; i < numberSymbols; i++) {

                  // getDrawable(int id) is deprecated as of API version 22 in favor of
                  // getDrawable(int id, Theme theme).  See
                  // https://developer.android.com/reference/android/content/res/Resources.html.
                  // Handle as follows.
      
                  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                     symbolWidth[i] = this.getResources().getDrawable(symbolIndex[i],this.getTheme())
                              .getIntrinsicWidth();
                     symbolHeight[i] = this.getResources().getDrawable(symbolIndex[i], this.getTheme())
                              .getIntrinsicHeight();
                  } else {
                     symbolWidth[i] = this.getResources().getDrawable(symbolIndex[i])
                              .getIntrinsicWidth();
                     symbolHeight[i] = this.getResources().getDrawable(symbolIndex[i])
                              .getIntrinsicHeight();
                  }
      
                  Log.i(TAG, "Symbol width=" + symbolWidth[i] + " height=" + symbolHeight[i]);
      
                  // Set top margin (header) area equal to height of tallest symbol
                  if (topMargin < symbolHeight[i]) topMargin = symbolHeight[i];
                }

               // Initial location of symbols. Coordinates are measured from the upper
               // left corner of the screen, with x increasing to the right and y
               // increasing downward.

               // Initial x coord in pixels for upper left corner of symbol
               float[] X = new float[numberSymbols];
               X[0] = xoff;
               X[1] = xoff + xgap + symbolWidth[0];
               X[2] = xoff + 2 * xgap + symbolWidth[0] + symbolWidth[1];

               // Initial y coord in pixels for upper left corner of symbol
               float[] Y = new float[numberSymbols];
               Y[0] = Y[1] = Y[2] = yoff;

               /*
               * Instantiate a SymbolDragger instance (which subclasses View), passing
               * to it in the constructor the context (this) and the above arrays.
               * Then set the content view to this instance of SymbolDragger (so the
               * layout is being specified entirely by SymbolDragger, with no XML
               * layout file). The resulting view should then place draggable symbols
               * with initial content and position defined by the above arrays on the
               * screen.
               */

               SymbolDragger view = new SymbolDragger(this, X, Y, symbolIndex);
               view.setLayoutParams(new ViewGroup.LayoutParams(
                              ViewGroup.LayoutParams.MATCH_PARENT,
                              ViewGroup.LayoutParams.MATCH_PARENT));
               setContentView(view);
      }
}

This class also should compile without error.

Take It Out for a Spin

If you now execute on an emulator or device, you should get screens like the following figures,

The left figure corresponds to the initial state, before anything has been dragged. In the right figure the yellow and red symbols already have been dragged to new positions by touching with the finger on a touchscreen and dragging to the new position. The green symbol is in the process of being dragged to a new position, so a dynamically updated readout of its position in pixels is being displayed as it is being dragged. Also, you should find that nothing happens if you press or drag on the screen background instead of one of the symbols.

How It Works

The two classes defined in this project are heavily commented, so you should be able to understand what the code is doing by reading through it with systematic attention to the documentation. But some of the comments are a little terse, so let's give a somewhat less abridged version here.

MainActivity

The class MainActivity is the entry point for the app (notice in AndroidManifest.xml that it is the only Activity registered), and extends Activity, as is normal. However, we have replaced the usual specification of the initial screen layout through an XML resource file by the SymbolDragger instance view, which is subclassed from View, in the last lines of the onCreate() method. Thus our layout is going to be defined by the Java class SymbolDragger described below.

We also have set up some arrays in MainActivity that will hold the initial positions of the draggable symbols that we wish to place on the screen (the arrays X and Y, which hold pixel coordinates as floats). Finally, we have set up an array symbolIndex that holds the integer references to the Drawable image resources that we placed in the res/drawable folder. For example, the integer R.drawable.red_square is a reference to the file res/drawable/red_square.png that the class SymbolDragger will use to access this image resource. These arrays of data are passed as arguments to the constructor of SymbolDragger that is instantiated as the screen view.

SymbolDragger

The Java class SymbolDragger, through the view instance created by MainActivity, does most of the work. It

• Defines the screen layout.


• Listens for finger gestures on the touch screen (no, not that kind of finger gesture!).


• Implements the appropriate actions in response to the detected gestures.

Let's now describe briefly the main blocks of code that accomplish these tasks in SymbolDragger.

1. The SymbolDragger constructor copies the arrays passed to it from MainActivity into its own local arrays and uses that information to construct additional arrays of information like the dimensions of images, and then uses that to produce the array symbols, which contains objects of type Drawable that will correspond to the visual representation of symbols to be displayed and manipulated onscreen. Finally the constructor sets up the Paint object that will control formatting during screen redraws.


2. The processing of events is implemented by overriding the onTouchEvent(MotionEvent ev) method inherited from View, which processes touch-screen motion events. These correspond to objects of the MotionEvent class, which are used to report movement (mouse, pen, finger, trackball) events. TheMotionEvent method getAction() returns the kind of action being performed as an integer constant of the MotionEvent class, with possible values ACTION_DOWN, ACTION_MOVE, ACTION_UP, and ACTION_CANCEL:
   
   
   • ACTION_DOWN indicates that a pressed gesture has started, with the motion containing the initial starting location. The MotionEvent methods getX() and getY() can be used to retrieve the x and y coordinates.
   
   
   • ACTION_MOVE indicates that a change has happened during a press gesture between ACTION_DOWN and ACTION_UP. Again, the methods getX() and getY() can be used to retrieve the x and y coordinates after the change. Although we won't use this functionality here, intermediate points between the initial down and up events can also be retrieved (see the getHistorySize() and the various getHistorical...() methods of MotionEvent).
   
   
   • ACTION_UP indicates that a pressed gesture has finished; the motion contains the final release location, as well as any intermediate points since the last down or move event.
   
   
   • ACTION_CANCEL indicates that the action has been canceled. We shall not worry about these events.


3. The class then uses a switch statement on these possible MotionEvent constants returned by getAction() to process the different possibilities.
   
   
   • For ACTION_DOWN (press events) the coordinates of the touch event are retrieved using getX() and getY() and compared with the bounding boxes for the symbols onscreen to see which (if any) of the symbols was touched. If the touch was on a symbol (symbolSelected not equal to -1), the initial coordinates for that symbol are recorded for future reference.
   
   
   • An ACTION_MOVE (dragging) event is processed only if the press event preceding it corresponded to touching a symbol and not the background. In that case the boolean isDragging is set to true, enabling the onscreen position readout defined in the method drawBackground, the new position is retrieved using getX() and getY(), and the corresponding symbol position is updated. Finally, the method invalidate() inherited from View is called to request a redraw of the screen.
   
   
   • If the constant returned is ACTION_UP (finger-up event), isDragging is set to false to halt the display of position and invalidate() is called to request a redraw.


4. The onDraw(Canvas) method inherited from View is overriden to define the look of the screen. This method will be called each time the screen is redrawn. The draw is on the Canvas object, with formatting controlled by the Paint object. Basically, onDraw calls drawBackground to draw all of the screen except the draggable symbols, and then draws all the onscreen draggable symbols at their current positions by using the translate(dx,dy) method of Canvas to translate by dx in the x coordinate and dy in the y coordinate from their previous position.


5. The drawBackground(canvas, paint) method has the task of drawing everything except the draggable symbols. It first draws the header bar and then the background for the main stage, and finally draws a coordinate readout on the screen if one of the symbols is currently being dragged. Since drawBackground is called before any draggable symbols are drawn, the symbols will always be above anything in the background.

When to redraw the screen is under the control of Android, but the invalidate() method of View requests a redraw (through a call to onDraw(Canvas), if the screen is visible) as soon as possible.

This completes the basic demonstration of how to drag some symbols around the screen. We shall now go on in Draggable Symbols II to add some additional features.

Last modified: July 1, 2016