Ghidra is a software reverse engineering (SRE) framework
/* ###
* 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;
import java.awt.Desktop;
import java.awt.Image;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.io.*;
import java.net.*;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.swing.JEditorPane;
import javax.swing.event.HyperlinkEvent;
import javax.swing.event.HyperlinkListener;
import javax.swing.text.*;
import javax.swing.text.html.*;
import javax.swing.text.html.HTML.Tag;
import generic.jar.ResourceFile;
import generic.theme.GColor;
import generic.theme.Gui;
import ghidra.framework.preferences.Preferences;
import ghidra.util.Msg;
import resources.*;
import utilities.util.FileUtilities;
/**
* A class that allows Ghidra to intercept JavaHelp navigation events in order to resolve them
* to Ghidra's help system. Without this class, contribution plugins have no way of
* referencing help documents within Ghidra's default help location.
* <p>
* This class is currently installed by the {@link GHelpSet}.
*
* @see GHelpSet
*/
public class GHelpHTMLEditorKit extends HTMLEditorKit {
private static final String G_HELP_STYLE_SHEET = "DefaultStyle.css";
private static final String DARK_G_HELP_STYLE_SHEET = "DarkStyle.css";
private static final Pattern EXTERNAL_URL_PATTERN = Pattern.compile("https?://.*");
/** A pattern to strip the font size value from a line of CSS */
private static final Pattern FONT_SIZE_PATTERN = Pattern.compile("font-size:\\s*(\\d{1,2})");
private static final String HELP_WINDOW_ZOOM_FACTOR = "HELP.WINDOW.FONT.SIZE.MODIFIER";
private static int fontSizeModifier;
/**
* A mapping of known style sheet colors to convert from the values in the style sheet to colors
* defined in the system theme.
*/
private static final Map<String, GColor> colorsById = new HashMap<>();
static {
colorsById.put("h1", new GColor("color.fg.help.selector.h1"));
colorsById.put("h2", new GColor("color.fg.help.selector.h2"));
colorsById.put("h3", new GColor("color.fg.help.selector.h3"));
colorsById.put("p.providedbyplugin",
new GColor("color.fg.help.selector.p.provided.by.plugin"));
colorsById.put("p.relatedtopic", new GColor("color.fg.help.selector.p.related.topic"));
colorsById.put("th", new GColor("color.fg.help.selector.th"));
colorsById.put("code", new GColor("color.fg.help.selector.code"));
colorsById.put("code.path", new GColor("color.fg.help.selector.code.path"));
}
private static final Pattern COLOR_PATTERN = Pattern.compile("(color:\\s*#{0,1}\\w+;)");
private HyperlinkListener[] delegateListeners = null;
private HyperlinkListener resolverHyperlinkListener;
public GHelpHTMLEditorKit() {
fontSizeModifier =
Integer.valueOf(Preferences.getProperty(HELP_WINDOW_ZOOM_FACTOR, "0", true));
}
@Override
public ViewFactory getViewFactory() {
return new GHelpHTMLFactory();
}
@Override
public void install(JEditorPane c) {
super.install(c);
delegateListeners = c.getHyperlinkListeners();
for (HyperlinkListener listener : delegateListeners) {
c.removeHyperlinkListener(listener);
}
resolverHyperlinkListener = new ResolverHyperlinkListener();
c.addHyperlinkListener(resolverHyperlinkListener);
// add a listener to report trace information
c.addPropertyChangeListener(new PropertyChangeListener() {
@Override
public void propertyChange(PropertyChangeEvent evt) {
String propertyName = evt.getPropertyName();
if ("page".equals(propertyName)) {
Msg.trace(this, "Page loaded: " + evt.getNewValue());
}
}
});
}
@Override
public void deinstall(JEditorPane c) {
c.removeHyperlinkListener(resolverHyperlinkListener);
for (HyperlinkListener listener : delegateListeners) {
c.addHyperlinkListener(listener);
}
super.deinstall(c);
}
private class ResolverHyperlinkListener implements HyperlinkListener {
@Override
public void hyperlinkUpdate(HyperlinkEvent e) {
if (delegateListeners == null) {
return;
}
if (e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) {
if (isExternalLink(e)) {
browseExternalLink(e);
return;
}
Msg.trace(this, "Link activated: " + e.getURL());
e = validateURL(e);
Msg.trace(this, "Validated event: " + e.getURL());
}
for (HyperlinkListener listener : delegateListeners) {
listener.hyperlinkUpdate(e);
}
}
}
private boolean isExternalLink(HyperlinkEvent e) {
String description = e.getDescription();
return description != null && EXTERNAL_URL_PATTERN.matcher(description).matches();
}
private void browseExternalLink(HyperlinkEvent e) {
String description = e.getDescription();
if (!Desktop.isDesktopSupported()) {
Msg.info(this, "Unable to launch external browser for " + description);
return;
}
try {
// use an external browser
URI uri = e.getURL().toURI();
Desktop.getDesktop().browse(uri);
}
catch (URISyntaxException | IOException e1) {
Msg.error(this, "Error browsing to external URL " + description, e1);
}
}
/**
* Tests the URL of the given event. If the URL is invalid, a new event may be created if
* a new, valid URL can be created. Creates a new event with a patched URL if
* the given event's URL is invalid.
*/
private HyperlinkEvent validateURL(HyperlinkEvent event) {
URL url = event.getURL();
if (url == null) {
Msg.trace(this, "No URL for link: " + event);
return maybeCreateNewHyperlinkEventWithUpdatedURL(event);
}
try {
url.openStream();// assume that this will fail if the file does not exist
}
catch (IOException ioe) {
// assume this means that the url is invalid
Msg.trace(this, "URL of link is invalid: " + url.toExternalForm());
return maybeCreateNewHyperlinkEventWithUpdatedURL(event);
}
return event;// url is fine
}
/** Generates a new event with a URL based upon Ghidra's resources if needed. */
private HyperlinkEvent maybeCreateNewHyperlinkEventWithUpdatedURL(HyperlinkEvent event) {
Element element = event.getSourceElement();
if (element == null) {
return event;// this shouldn't happen since we were triggered from an A tag
}
AttributeSet a = element.getAttributes();
AttributeSet anchor = (AttributeSet) a.getAttribute(HTML.Tag.A);
if (anchor == null) {
return event;// this shouldn't happen since we were triggered from an A tag
}
String HREF = (String) anchor.getAttribute(HTML.Attribute.HREF);
Msg.trace(this, "HREF of <a> tag: " + HREF);
URL newUrl = getURLForHREFFromResources(HREF);
if (newUrl == null) {
return event;// unable to locate a resource by the name--bad link!
}
return new HyperlinkEvent(event.getSource(), event.getEventType(), newUrl,
event.getDescription(), event.getSourceElement());
}
private URL getURLForHREFFromResources(String originalHREF) {
int anchorIndex = originalHREF.indexOf("#");
String HREF = originalHREF;
String anchor = null;
if (anchorIndex != -1) {
HREF = HREF.substring(0, anchorIndex);
anchor = originalHREF.substring(anchorIndex);
}
// look for a URL using an installation environment setup...
URL newUrl = ResourceManager.getResource(HREF);
if (newUrl != null) {
return createURLWithAnchor(newUrl, anchor);
}
//
// The item was not found by the ResourceManager (i.e., it is not in a 'resources'
// directory). See if it may be a relative link to a build's installation root (like
// a file in <install dir>/docs).
//
newUrl = HelpBuildUtils.findApplicationUrl(HREF);
return newUrl;
}
private URL createURLWithAnchor(URL anchorlessURL, String anchor) {
if (anchorlessURL == null) {
return anchorlessURL;
}
if (anchor == null) {
// nothing to do
return anchorlessURL;
}
try {
// put the anchor back into the URL
return new URL(anchorlessURL, anchor);
}
catch (MalformedURLException e) {
// shouldn't happen, since the file exists
Msg.showError(this, null, "Unexpected Error",
"Unexpected error creating a valid URL: " + anchorlessURL + "#" + anchor);
return null;
}
}
@Override
public void read(Reader in, Document doc, int pos) throws IOException, BadLocationException {
super.read(in, doc, pos);
HTMLDocument htmlDoc = (HTMLDocument) doc;
loadGHelpStyleSheet(htmlDoc);
}
private void loadGHelpStyleSheet(HTMLDocument doc) {
Reader reader = getGStyleSheetReader();
if (reader == null) {
return;
}
StyleSheet ss = doc.getStyleSheet();
try {
ss.loadRules(reader, null);
}
catch (IOException e) {
// shouldn't happen
Msg.debug(this, "Unable to load help style sheet");
}
}
private Reader getGStyleSheetReader() {
URL url = getGStyleSheetURL();
if (url == null) {
return null;
}
StringBuilder buffy = new StringBuilder();
try {
List<String> lines = FileUtilities.getLines(url);
for (String line : lines) {
StringBuilder lineBuilder = new StringBuilder();
changePixels(line, fontSizeModifier, lineBuilder);
String updatedLine = lineBuilder.toString();
lineBuilder.delete(0, lineBuilder.length());
changeColor(updatedLine, lineBuilder);
buffy.append(lineBuilder.toString());
buffy.append('\n');
}
}
catch (IOException e) {
// shouldn't happen
Msg.debug(this, "Unable to read the lines of the help style sheet: " + url);
}
StringReader reader = new StringReader(buffy.toString());
return reader;
}
private void changeColor(String line, StringBuilder buffy) {
int blockStart = line.indexOf("{");
if (blockStart == -1) {
buffy.append(line);
return;
}
String cssSelector = line.substring(0, blockStart).trim();
cssSelector = cssSelector.toLowerCase(); // normalize
GColor gColor = colorsById.get(cssSelector);
if (gColor == null) {
buffy.append(line);
return;
}
Matcher matcher = COLOR_PATTERN.matcher(line);
if (matcher.find()) {
matcher.appendReplacement(buffy, "color: " + gColor.toHexString() + ";");
}
matcher.appendTail(buffy);
}
private void changePixels(String line, int amount, StringBuilder buffy) {
Matcher matcher = FONT_SIZE_PATTERN.matcher(line);
while (matcher.find()) {
String oldFontSize = matcher.group(1);
String adjustFontSize = adjustFontSize(oldFontSize);
matcher.appendReplacement(buffy, "font-size: " + adjustFontSize);
}
matcher.appendTail(buffy);
}
private String adjustFontSize(String sizeString) {
try {
int size = Integer.parseInt(sizeString);
String adjusted = Integer.toString(size + fontSizeModifier);
return adjusted;
}
catch (NumberFormatException e) {
Msg.debug(this, "Unable to parse font size string '" + sizeString + "'");
}
return sizeString;
}
private URL getGStyleSheetURL() {
if (Gui.isDarkTheme()) {
return findStyleSheet(DARK_G_HELP_STYLE_SHEET);
}
return findStyleSheet(G_HELP_STYLE_SHEET);
}
private URL findStyleSheet(String name) {
URL url = ResourceManager.getResource("help/shared/" + name);
if (url != null) {
return url;
}
ResourceFile file = HelpBuildUtils.findModuleFile("help/shared/" + name);
if (file != null) {
try {
return file.toURL();
}
catch (MalformedURLException e) {
Msg.showError(this, null, "Unexpected Error",
"Unexpected error parsing file to URL: " + file);
return null;
}
}
return null;
}
public static void zoomOut() {
fontSizeModifier -= 2;
saveZoomFactor();
}
public static void zoomIn() {
fontSizeModifier += 2;
saveZoomFactor();
}
private static void saveZoomFactor() {
Preferences.setProperty(HELP_WINDOW_ZOOM_FACTOR, Integer.toString(fontSizeModifier));
Preferences.store();
}
//==================================================================================================
// Inner Classes
//==================================================================================================
private class GHelpHTMLFactory extends HTMLFactory {
@Override
public View create(Element e) {
AttributeSet attributes = e.getAttributes();
Object elementName = attributes.getAttribute(AbstractDocument.ElementNameAttribute);
if (elementName != null) {
// not an HTML element
return super.create(e);
}
Object html = attributes.getAttribute(StyleConstants.NameAttribute);
if (html instanceof HTML.Tag) {
HTML.Tag tag = (Tag) html;
if (tag == HTML.Tag.IMG) {
return new GHelpImageView(e);
}
}
return super.create(e);
}
}
/**
* Overridden to allow us to find images that are defined as constants in places like
* {@link Icons}
*/
private class GHelpImageView extends ImageView {
/*
* Unusual Code Alert!
* This class exists to enable our help system to find custom icons defined in source
* code. The default behavior herein is to supply a URL to the base class to load. This
* works fine.
*
* There is another use case where we wish to have the base class load an image of our
* choosing. Why? Well, we modify, in memory, some icons we use. We do this for things
* like overlays and rotations.
*
* In order to have our base class use the image that we want (and not the one
* it loads via a URL), we have to play a small game. We have to allow the base class
* to load the image it wants, which is done asynchronously. If we install our custom
* image during that process, the loading will throw away the image and not render
* anything.
*
* To get the base class to use our image, we override getImage(). However, we should
* only return our image when the base class is finished loading. (See the base class'
* paint() method for why we need to do this.)
*
* Note: if we start seeing unusual behavior, like images not rendering, or any size
* issues, then we can revert this code.
*/
private Image image;
private float spanX;
private float spanY;
public GHelpImageView(Element elem) {
super(elem);
}
@Override
public Image getImage() {
Image superImage = super.getImage();
if (image == null) {
// no custom image
return superImage;
}
if (isLoading()) {
return superImage;
}
return image;
}
private boolean isLoading() {
return spanX < 1 || spanY < 1;
}
@Override
public float getPreferredSpan(int axis) {
float span = super.getPreferredSpan(axis);
if (axis == View.X_AXIS) {
spanX = span;
}
else {
spanY = span;
}
return span;
}
@Override
public URL getImageURL() {
AttributeSet attributes = getElement().getAttributes();
Object src = attributes.getAttribute(HTML.Attribute.SRC);
if (src == null) {
return null;
}
String srcString = src.toString().trim();
IconProvider iconProvider = HelpBuildUtils.getRuntimeIcon(srcString);
if (iconProvider != null && !iconProvider.isInvalid()) {
// note: store the image off for later use; the url will not be used by us
this.image = iconProvider.getImage();
return iconProvider.getOrCreateUrl();
}
return doGetImageURL(srcString);
}
private URL doGetImageURL(String srcString) {
HTMLDocument htmlDocument = (HTMLDocument) getDocument();
URL context = htmlDocument.getBase();
try {
URL url = new URL(context, srcString);
if (FileUtilities.exists(url.toURI())) {
// it's a good one, let it through
return url;
}
}
catch (MalformedURLException | URISyntaxException e) {
// check below
}
// Try the ResourceManager. This will work for images that start with GHelp
// relative link syntax such as 'help/', 'help/topics/' and 'images/'
URL resource = ResourceManager.getResource(srcString);
return resource;
}
}
}