A custom ErrorSource implementation would need to send the appropriate EditBus message when an error arrives, and then provide implementations of various "getter" methods that the ErrorList plugin would later call to obtain the error. Using DefaultErrorSource makes the task much easier. In fact, all that is involved is calling a single method on the appropriate DefaultErrorSource instance:
public void addError
(DefaultErrorSource.DefaultError error);
The constructor of the DefaultErrorSource.DefaultError class is as follows:
public DefaultError
(int type, String path, int line, int start, int end, String message);
type - this should be either ErrorSource.ERROR or ErrorSource.WARNING.
path - the path name or URL of the file containing the error. If this is a relative path, it will be qualified relative to the current working directory (user.dir system property). However, it is best to qualify it beforehand, using the MiscUtilities.constructPath() method.
line - the line number in the file where the error occurred. Lines are numbered starting from zero; since most tools and compilers report line numbers starting from 1, you might need to subtract 1 from the number before passing it to this method.
start - an offset in the line where the error begins.
end - an offset in the line where the error ends. These two values are only used to give a more exact display for error highlighting, and if both are zero, the entire line will be highlighted.
message - the error message itself, as shown in the error list window and error highlighting tooltips.
This method is fully thread safe; if your plugin generates errors from another thread, it can call this method without having to use any of the usual SwingUtilities.invokeLater() tricks required when calling non-thread safe methods.
Here are two examples of addError() calls. The first adds a warning, covering the entire line, the second adds an error that only applies to a subset of the specified line:
errorSource.addError(new ErrorSource.DefaultError( ErrorSource.WARNING,path,line,0,0, "Are you sure this is what you intended?")); errorSource.addError(new ErrorSource.DefaultError( ErrorSource.WARNING, MiscUtilities.constructPath(directory,"input.src"), line,0,5,"First five characters of line are bad")); |
Multiple-line messages can be created by calling the following method on the DefaultError instance before it is added to the error source (the last part is important, otherwise the extra messages will not be shown):
public void addExtraMessage
(String extra);
That's basically all there is to it. There is one more method in the DefaultErrorSource class that needs to be mentioned:
public void clear
This method removes all errors from the error source. It is typically called before each invocation of the operation that generates errors; for example, the Console plugin clears its error source before each new command is run.
This method reveals a limitation of the DefaultErrorSource class; errors cannot be removed selectively. The main reason this hasn't been implemented is lack of demand. If your plugin needs a means of only removing a subset of errors in an error source, feel free to modify the source for this class and contribute the changes back to the jEdit project.