org.spearce.jgit/src/org/spearce/jgit/revplot/AbstractPlotRenderer.java

   1 /*
   2  * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
   3  *
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or
   7  * without modification, are permitted provided that the following
   8  * conditions are met:
   9  *
  10  * - Redistributions of source code must retain the above copyright
  11  *   notice, this list of conditions and the following disclaimer.
  12  *
  13  * - Redistributions in binary form must reproduce the above
  14  *   copyright notice, this list of conditions and the following
  15  *   disclaimer in the documentation and/or other materials provided
  16  *   with the distribution.
  17  *
  18  * - Neither the name of the Git Development Community nor the
  19  *   names of its contributors may be used to endorse or promote
  20  *   products derived from this software without specific prior
  21  *   written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  24  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  25  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  26  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  28  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  29  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  30  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  33  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  35  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38 package org.spearce.jgit.revplot;
  39
  40 import org.spearce.jgit.lib.Ref;
  41 import org.spearce.jgit.revwalk.RevFlag;
  42
  43 /**
  44  * Basic commit graph renderer for graphical user interfaces.
  45  * <p>
  46  * Lanes are drawn as columns left-to-right in the graph, and the commit short
  47  * message is drawn to the right of the lane lines for this cell. It is assumed
  48  * that the commits are being drawn as rows of some sort of table.
  49  * <p>
  50  * Client applications can subclass this implementation to provide the necessary
  51  * drawing primitives required to display a commit graph. Most of the graph
  52  * layout is handled by this class, allowing applications to implement only a
  53  * handful of primitive stubs.
  54  * <p>
  55  * This class is suitable for us within an AWT TableCellRenderer or within a SWT
  56  * PaintListener registered on a Table instance. It is meant to rubber stamp the
  57  * graphics necessary for one row of a plotted commit list.
  58  * <p>
  59  * Subclasses should call {@link #paintCommit(PlotCommit, int)} after they have
  60  * otherwise configured their instance to draw one commit into the current
  61  * location.
  62  * <p>
  63  * All drawing methods assume the coordinate space for the current commit's cell
  64  * starts at (upper left corner is) 0,0. If this is not true (like say in SWT)
  65  * the implementation must perform the cell offset computations within the
  66  * various draw methods.
  67  *
  68  * @param <TLane>
  69  *            type of lane being used by the application.
  70  * @param <TColor>
  71  *            type of color object used by the graphics library.
  72  */
  73 public abstract class AbstractPlotRenderer<TLane extends PlotLane, TColor> {
  74         private static final int LANE_WIDTH = 14;
  75
  76         private static final int LINE_WIDTH = 2;
  77
  78         private static final int LEFT_PAD = 2;
  79
  80         /**
  81          * Paint one commit using the underlying graphics library.
  82          *
  83          * @param commit
  84          *            the commit to render in this cell. Must not be null.
  85          * @param h
  86          *            total height (in pixels) of this cell.
  87          */
  88         protected void paintCommit(final PlotCommit<TLane> commit, final int h) {
  89                 final int dotSize = computeDotSize(h);
  90                 final TLane myLane = commit.getLane();
  91                 final int myLaneX = laneC(myLane);
  92                 final TColor myColor = laneColor(myLane);
  93
  94                 int maxCenter = 0;
  95                 for (final TLane passingLane : (TLane[]) commit.passingLanes) {
  96                         final int cx = laneC(passingLane);
  97                         final TColor c = laneColor(passingLane);
  98                         drawLine(c, cx, 0, cx, h, LINE_WIDTH);
  99                         maxCenter = Math.max(maxCenter, cx);
 100                 }
 101
 102                 final int nParent = commit.getParentCount();
 103                 for (int i = 0; i < nParent; i++) {
 104                         final PlotCommit<TLane> p;
 105                         final TLane pLane;
 106                         final TColor pColor;
 107                         final int cx;
 108
 109                         p = (PlotCommit<TLane>) commit.getParent(i);
 110                         pLane = p.getLane();
 111                         if (pLane == null)
 112                                 continue;
 113
 114                         pColor = laneColor(pLane);
 115                         cx = laneC(pLane);
 116
 117                         if (Math.abs(myLaneX - cx) > LANE_WIDTH) {
 118                                 if (myLaneX < cx) {
 119                                         final int ix = cx - LANE_WIDTH / 2;
 120                                         drawLine(pColor, myLaneX, h / 2, ix, h / 2, LINE_WIDTH);
 121                                         drawLine(pColor, ix, h / 2, cx, h, LINE_WIDTH);
 122                                 } else {
 123                                         final int ix = cx + LANE_WIDTH / 2;
 124                                         drawLine(pColor, myLaneX, h / 2, ix, h / 2, LINE_WIDTH);
 125                                         drawLine(pColor, ix, h / 2, cx, h, LINE_WIDTH);
 126                                 }
 127                         } else {
 128                                 drawLine(pColor, myLaneX, h / 2, cx, h, LINE_WIDTH);
 129                         }
 130                         maxCenter = Math.max(maxCenter, cx);
 131                 }
 132
 133                 final int dotX = myLaneX - dotSize / 2 - 1;
 134                 final int dotY = (h - dotSize) / 2;
 135
 136                 if (commit.getChildCount() > 0)
 137                         drawLine(myColor, myLaneX, 0, myLaneX, dotY, LINE_WIDTH);
 138
 139                 if (commit.has(RevFlag.UNINTERESTING))
 140                         drawBoundaryDot(dotX, dotY, dotSize, dotSize);
 141                 else
 142                         drawCommitDot(dotX, dotY, dotSize, dotSize);
 143
 144                 int textx = Math.max(maxCenter + LANE_WIDTH / 2, dotX + dotSize) + 8;
 145                 int n = commit.refs == null ? 0 : commit.refs.length;
 146                 for (int i = 0; i < n; ++i) {
 147                         textx += drawLabel(textx + dotSize, h/2, commit.refs[i]);
 148                 }
 149
 150                 final String msg = commit.getShortMessage();
 151                 drawText(msg, textx + dotSize + n*2, h / 2);
 152         }
 153
 154         /**
 155          * Draw a decoration for the Ref ref at x,y
 156          *
 157          * @param x
 158          *            left
 159          * @param y
 160          *            top
 161          * @param ref
 162          *            A peeled ref
 163          * @return width of label in pixels
 164          */
 165         protected abstract int drawLabel(int x, int y, Ref ref);
 166
 167         private int computeDotSize(final int h) {
 168                 int d = (int) (Math.min(h, LANE_WIDTH) * 0.50f);
 169                 d += (d & 1);
 170                 return d;
 171         }
 172
 173         /**
 174          * Obtain the color reference used to paint this lane.
 175          * <p>
 176          * Colors returned by this method will be passed to the other drawing
 177          * primitives, so the color returned should be application specific.
 178          * <p>
 179          * If a null lane is supplied the return value must still be acceptable to a
 180          * drawing method. Usually this means the implementation should return a
 181          * default color.
 182          *
 183          * @param myLane
 184          *            the current lane. May be null.
 185          * @return graphics specific color reference. Must be a valid color.
 186          */
 187         protected abstract TColor laneColor(TLane myLane);
 188
 189         /**
 190          * Draw a single line within this cell.
 191          *
 192          * @param color
 193          *            the color to use while drawing the line.
 194          * @param x1
 195          *            starting X coordinate, 0 based.
 196          * @param y1
 197          *            starting Y coordinate, 0 based.
 198          * @param x2
 199          *            ending X coordinate, 0 based.
 200          * @param y2
 201          *            ending Y coordinate, 0 based.
 202          * @param width
 203          *            number of pixels wide for the line. Always at least 1.
 204          */
 205         protected abstract void drawLine(TColor color, int x1, int y1, int x2,
 206                         int y2, int width);
 207
 208         /**
 209          * Draw a single commit dot.
 210          * <p>
 211          * Usually the commit dot is a filled oval in blue, then a drawn oval in
 212          * black, using the same coordinates for both operations.
 213          *
 214          * @param x
 215          *            upper left of the oval's bounding box.
 216          * @param y
 217          *            upper left of the oval's bounding box.
 218          * @param w
 219          *            width of the oval's bounding box.
 220          * @param h
 221          *            height of the oval's bounding box.
 222          */
 223         protected abstract void drawCommitDot(int x, int y, int w, int h);
 224
 225         /**
 226          * Draw a single boundary commit (aka uninteresting commit) dot.
 227          * <p>
 228          * Usually a boundary commit dot is a light gray oval with a white center.
 229          *
 230          * @param x
 231          *            upper left of the oval's bounding box.
 232          * @param y
 233          *            upper left of the oval's bounding box.
 234          * @param w
 235          *            width of the oval's bounding box.
 236          * @param h
 237          *            height of the oval's bounding box.
 238          */
 239         protected abstract void drawBoundaryDot(int x, int y, int w, int h);
 240
 241         /**
 242          * Draw a single line of text.
 243          * <p>
 244          * The font and colors used to render the text are left up to the
 245          * implementation.
 246          *
 247          * @param msg
 248          *            the text to draw. Does not contain LFs.
 249          * @param x
 250          *            first pixel from the left that the text can be drawn at.
 251          *            Character data must not appear before this position.
 252          * @param y
 253          *            pixel coordinate of the centerline of the text.
 254          *            Implementations must adjust this coordinate to account for the
 255          *            way their implementation handles font rendering.
 256          */
 257         protected abstract void drawText(String msg, int x, int y);
 258
 259         private int laneX(final PlotLane myLane) {
 260                 final int p = myLane != null ? myLane.getPosition() : 0;
 261                 return LEFT_PAD + LANE_WIDTH * p;
 262         }
 263
 264         private int laneC(final PlotLane myLane) {
 265                 return laneX(myLane) + LANE_WIDTH / 2;
 266         }
 267 }