Skip to content

Ghidra is a software reverse engineering (SRE) framework

12.5 KB
Raw Blame
/* ###
 * IP: GHIDRA
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package help.screenshot;

import static org.junit.Assert.*;

import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.File;
import java.io.FileFilter;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

import org.apache.commons.lang3.StringUtils;
import org.junit.After;
import org.junit.Assert;

import docking.*;
import docking.action.DockingActionIf;
import generic.jar.ResourceFile;
import generic.theme.GThemeDefaults.Colors.Palette;
import generic.util.WindowUtilities;
import ghidra.framework.Application;
import ghidra.framework.main.FrontEndTool;
import ghidra.util.Msg;
import ghidra.util.exception.AssertException;

/**
 * Extend this class to create screen shot images for help. The name of the class determines the
 * topic directory where the captured image will be stored. So if the class name is
 * XyzShreenShots, the resulting captured image will appear in help topic directly "Xyz", regardless
 * of which module has that topic.  The test name will determine the name of the image file
 * that is generated. So if the test name is testHappyBirthday, the filename will be
 * HappyBirthday.png.
 */
public abstract class GhidraScreenShotGenerator extends AbstractScreenShotGenerator {

	private static final Color FG_COLOR_TEXT = Palette.getColor("cornflowerblue");
	private static final String CAPTURE = "Capture";

	protected GhidraScreenShotGenerator() {
	}

	@Override
	@After
	public void tearDown() throws Exception {

		super.tearDown();

		showResults();
	}

	protected void showResults() {
		if (!hasTestFailed()) {
			saveOrDisplayImage();
		}
		else {
			Msg.error(this, "Not showing screenshot results--test failed " + getName());
		}
	}

	/**
	 * Generally, you shouldn't use this.  This is only visible for those who do not directly
	 * extend this class.
	 */
	public void saveOrDisplayImage() {
		String name = testName.getMethodName();
		saveOrDisplayImage(name);
	}

	public void saveOrDisplayImage(String name) {

		// strip off the initial 'test'
		name = name.substring(4);

		// we allow also the form 'testCapture...'
		if (name.startsWith(CAPTURE)) {
			name = name.substring(CAPTURE.length());
		}

		// validate our name matches an existing image
		File topic = getHelpTopic();
		File imageFile = getImageFile(topic, name);
		finished(topic, imageFile.getName());
	}

	private File getImageFile(File helpTopic, String name) {
		File potentialFile = new File(helpTopic, "images/" + name + ".png");
		if (potentialFile.exists()) {
			return potentialFile;
		}

		// next, try the .gif extension
		File imageDir = new File(helpTopic, "images");
		imageDir.mkdirs();
		potentialFile = new File(imageDir, name + ".gif");
		if (potentialFile.exists()) {
			handleGIFImage(potentialFile);
		}

		// next, how about jpg?
		potentialFile = new File(imageDir, name + ".jpg");
		if (potentialFile.exists()) {
			handleJPGImage(potentialFile);
		}

		// next, look for any matching image, ignoring case
		final String nameLowerCase = name.toLowerCase();
		File[] matchingFiles = imageDir.listFiles((FileFilter) f -> {
			String filename = f.getName();
			String filenameLowerCase = filename.toLowerCase();
			return nameLowerCase.equals(filenameLowerCase);
		});

		if (matchingFiles == null || matchingFiles.length == 0) {
			return new File("ImageNotFound/" + name + ".png");
		}

		if (matchingFiles.length == 1) {
			return matchingFiles[0];
		}

		Assert.fail("Found multiple files, ignoring case, that match name: " + name +
			" for test case: " + testName.getMethodName());
		return null;// can't get here
	}

	protected void handleGIFImage(File gifFile) {
		String gifName = gifFile.getName();
		String pngName = gifName.replace(".gif", ".png");
		File pngFile = new File(gifFile.getParentFile(), pngName);

		// write the png out, so that we can replace the gif, if we wish
		writeFile(pngFile);

		Image gifImage = getGIFImage(gifFile);
		showGIFImage(pngFile, gifImage);

		Assert.fail("No PNG, but did find ** GIF ** for test case: " + testName.getMethodName() +
			"\nWriting png image: " + pngFile);
	}

	private void handleJPGImage(File jpgFile) {
		String gifName = jpgFile.getName();
		String pngName = gifName.replace(".jpg", ".png");
		File pngFile = new File(jpgFile.getParentFile(), pngName);

		// write the png out, so that we can replace the gif, if we wish
		writeFile(pngFile);

		Image gifImage = getJPGImage(jpgFile);
		showGIFImage(pngFile, gifImage);

		Assert.fail("No PNG, but did find ** JPG ** for test case: " + testName.getMethodName() +
			"\nWriting png image: " + pngFile);
	}

	protected File getHelpTopic() {
		String moduleName = getHelpTopicModuleName();
		String topicName = getHelpTopicName();
		File helpTopicDir = getHelpTopicDir(moduleName, topicName);
		assertNotNull("Unable to find help topic for test file: " + getClass().getName(),
			helpTopicDir);
		return helpTopicDir;
	}

	public void loadDefaultTool() {
		env.launchDefaultTool();
	}

	/**
	 * Returns an optional module.  The default value is null, which signals to find the help topic
	 * name in any module.  This needs to be overridden when a given help topic name is in more than
	 * one module.
	 * @return the module name (e.g., Base)
	 */
	protected String getHelpTopicModuleName() {
		return null; // null means to use the first matching help topic found in any module
	}

	protected String getHelpTopicName() {
		Class<? extends GhidraScreenShotGenerator> clazz = getClass();
		String simpleName = clazz.getSimpleName();
		return simpleName.replace("ScreenShots", "");
	}

	/**
	 * Call when you are finished generating a new image.  This method will either show the
	 * newly created image or write it to disk, depending upon the value of
	 * {@link #SAVE_CREATED_IMAGE_FILE}, which is a system property.
	 *
	 * @param helpTopic The help topic that contains the image
	 * @param oldImageName  The name of the image
	 */
	public void finished(File helpTopic, String oldImageName) {
		if (SAVE_CREATED_IMAGE_FILE) {
			maybeSaveToHelp(helpTopic, oldImageName);
		}
		else {
			doShowImage(helpTopic, oldImageName);
		}
	}

	private void doShowImage(File helpTopic, String oldImageName) {
		if (SAVE_CREATED_IMAGE_FILE) {
			Msg.error(this, "Do not call showImage() directly");
			return;
		}

		assertNotNull("No new image found", image);

		Image oldImage = getOldImage(helpTopic, oldImageName);
		File imageDir = new File(helpTopic, "images");
		imageDir.mkdirs();
		File imageFile = new File(imageDir, oldImageName + DEFAULT_FILENAME_SUFFIX);
		ImageDialogProvider dialog = new ImageDialogProvider(imageFile, oldImage, image);
		dialog.setTitle("help/topics/" + helpTopic.getName() + "/images/" + oldImageName);
		showDialog(dialog);
	}

	private void showGIFImage(File imageFile, Image gifImage) {
		ImageDialogProvider dialog = new ImageDialogProvider(imageFile, gifImage, image);
		showDialog(dialog);
	}

	private void showDialog(DialogComponentProvider dialogComponent) {
		runSwing(() -> {
			DockingDialog dialog = DockingDialog.createDialog(null, dialogComponent, null);
			dialog.setLocation(WindowUtilities.centerOnScreen(dialog.getSize()));
			dialog.setVisible(true);
		});
	}

	protected Image getOldImage(File helpTopicDir, String imageName) {
		if (helpTopicDir == null) {
			throw new AssertException("Invalid help topic name - null");
		}

		File imageFile = new File(helpTopicDir, "/images/" + imageName);
		if (!imageFile.exists()) {
//			throw new AssertException("Cannot find image " + imageName + " in help topic " +
//				helpTopicDir);
			return createEmptyImage(10, 10);
		}

		return readImage(imageFile);
	}

	private Image getGIFImage(File imageFile) {
		BufferedImage gifImage = readImage(imageFile);
		Graphics2D g = (Graphics2D) gifImage.getGraphics();

		int width = gifImage.getWidth();
		int height = gifImage.getHeight();

		Font font = g.getFont().deriveFont((float) (height * .3));
		g.setFont(font);

		String text = "GIF!";
		FontMetrics fontMetrics = g.getFontMetrics(font);
		Rectangle bounds = fontMetrics.getStringBounds(text, g).getBounds();
		int stringWidth = (int) bounds.getWidth();
		int stringHeight = (int) bounds.getHeight();

		int x = (width / 2) - (stringWidth / 2);
		int y = (height / 2) + (stringHeight / 2);
		g.setColor(FG_COLOR_TEXT);
		g.drawString(text, x, y);

		return gifImage;
	}

	private Image getJPGImage(File imageFile) {
		BufferedImage gifImage = readImage(imageFile);
		Graphics2D g = (Graphics2D) gifImage.getGraphics();

		int width = gifImage.getWidth();
		int height = gifImage.getHeight();

		Font font = g.getFont().deriveFont((float) (height * .3));
		g.setFont(font);

		String text = "JPG!";
		FontMetrics fontMetrics = g.getFontMetrics(font);
		Rectangle bounds = fontMetrics.getStringBounds(text, g).getBounds();
		int stringWidth = (int) bounds.getWidth();
		int stringHeight = (int) bounds.getHeight();

		int x = (width / 2) - (stringWidth / 2);
		int y = (height / 2) + (stringHeight / 2);
		g.setColor(FG_COLOR_TEXT);
		g.drawString(text, x, y);

		return gifImage;
	}

	/**
	 * @deprecated use instead {@link #finished(File, String)}.
	 *
	 * @param helpTopic The help topic that contains the image
	 * @param oldImageName  The name of the image
	 */
	@Deprecated
	public void showImage(String helpTopic, String oldImageName) {
		doShowImage(getHelpTopicDir(helpTopic), oldImageName);
	}

	/**
	 * @deprecated use instead {@link #finished(File, String)}.
	 *
	 * @param helpTopic The help topic that contains the image
	 * @param imageName  The name of the image
	 */
	@Deprecated
	public void saveToHelp(String helpTopic, String imageName) {
		maybeSaveToHelp(getHelpTopicDir(helpTopic), imageName);
	}

	private void maybeSaveToHelp(File helpTopicDir, String imageName) {
		if (!SAVE_CREATED_IMAGE_FILE) {
			Msg.error(this, "Do not call saveToHelp() directly");
			return;
		}

		reallySaveToHelp(helpTopicDir, imageName);
	}

	protected void reallySaveToHelp(File helpTopicDir, String imageName) {
		Msg.debug(this, "\n\n\t\tWARNING!!!!\nOnly call this method if you need an " +
			"'out of band' help image saved.  If you don't know what that means, then don't!");

		if (helpTopicDir == null) {
			throw new AssertException("Invalid help topic name - null");
		}

		File imageFile = new File(helpTopicDir, "/images/" + imageName + NEW_FILENAME_SUFFIX);
		writeFile(imageFile);
	}

	protected File getHelpTopicDir(String topicName) {
		return getHelpTopicDir(null, topicName);
	}

	protected File getHelpTopicDir(String moduleName, String helpTopic) {
		List<File> helpTopicDirs = getHelpTopicDirs();
		for (File file : helpTopicDirs) {
			File potential = new File(file, helpTopic);
			if (!potential.exists()) {
				continue;
			}

			if (StringUtils.isBlank(moduleName)) {
				return potential; // any module will do
			}

			// Module/src/main/help/help/topics/TopicName
			File topics = potential.getParentFile();
			File help = topics.getParentFile();
			File helpParent = help.getParentFile();
			File main = helpParent.getParentFile();
			File src = main.getParentFile();
			File module = src.getParentFile();
			String actualModuleName = module.getName();
			if (actualModuleName.equals(moduleName)) {
				return potential;
			}
		}
		return null;
	}

	protected List<File> getHelpTopicDirs() {
		List<File> helpTopicDirs = new ArrayList<>();
		Collection<ResourceFile> modules = Application.getModuleRootDirectories();
		for (ResourceFile file : modules) {
			File potential = new File(file.getFile(false), "src/main/help/help/topics");
			if (potential.exists()) {
				helpTopicDirs.add(potential);
			}
		}
		return helpTopicDirs;
	}

	protected FrontEndTool getFrontEndTool() {
		final FrontEndTool frontEndTool = env.getFrontEndTool();
		runSwing(() -> frontEndTool.setVisible(true));
		return frontEndTool;
	}

	public void performFrontEndAction(String actionName, String owner, boolean wait) {
		FrontEndTool frontEnd = getFrontEndTool();

		DockingActionIf action = getAction(frontEnd, owner, actionName);
		ComponentProvider compProvider =
			(ComponentProvider) getInstanceField("compProvider", frontEnd);
		performAction(action, compProvider, wait);
	}
}