org.eclipse.photran-dev-docs/dev-guide/cha-editor.ltx-inc

% Fortran Editors
\vspace{-0.5in}

{\scriptsize Revision: \footnotesize \$Id: cha-editor.ltx-inc,v 1.1 2010/05/21 20:12:20 joverbey Exp $ $ - based on 2008/08/08 nchen}

\section{Fortran Text Editor}

The Fortran code editor is implemented in a class called, not surprisingly,
\textit{FortranEditor}. In general, \textit{FortranEditor} closely follows
the standard implementation of text editors in Eclipse (see \textit{The
Java Developer's Guide to Eclipse,} Chapter ?? or another reference for more
information.)  This chapter highlights some of the Photran-specific details
of the text editor implementation.

\section{Contributed \textit{SourceViewerConfiguration}}

Text editors in Eclipse rely on a \textit{SourceViewerConfiguration} to enhance
the current editor with features such as auto indenting, syntax highlighting and
formatting. By default, most of these features are already provided by the
concrete \textit{SourceViewerConfiguration} class. However, it is possible to
provide a custom implementation of a \textit{SourceViewerConfiguration}. This is
done by calling the
\textit{setSourceViewerConfiguration(SourceViewerConfiguration
sourceViewerConfiguration)} method in an Eclipse text editor.

Photran's text editor is contained in the org.eclipse.photran.ui plug-in.
However, several of the features contributed by the
\textit{SourceViewerConfiguration} require the Fortran parser, which is
contained in the org.eclipse.photran.ui.vpg plug-in.  Therefore, the
ui.vpg plug-in \textit{contributes} a \textit{SourceViewerConfiguration}
to the org.eclipse.photran.ui plug-in via an extension point.  Specifically,
it contributes the class \textit{FortranVPGSourceViewerConfigurationFactory}
to the \textit{org.eclipse.photran.ui.sourceViewerConfig} extension point,
and that class is responsible for creating the actual
\textit{SourceViewerConfiguration}.

\section{Fortran Editor Tasks: VPG \& AST Tasks}

When the user modifies the text in an editor, often several other data
structures and views need to be updated as well.  For example, the Outline
view should summarize the current text in the editor, and the list of choices
in the content assistant (auto-completion) should be consistent with the
current text in the editor.  Both of these need to be updated as the user
types---not just when the file is saved.

Eclipse editors can have a \emph{reconciler.}  When the user has stopped typing
for a brief period of time (usually 500ms), the reconciler is run in a background
thread.  This when these things should be synchronized with the
editor.\footnote{Exercise for the reader: think about (1)~why this should be done
after a 500ms ``break'' rather than after every keystroke, and (2)~why it should
be done in a background thread\dots}

Photran maintains a list of ``tasks'' that are run when the editor is reconciled.
The list of tasks to run is stored in the singleton \textit{FortranEditorTasks}
object, and the tasks are actually run by the \textit{FortranVPGReconcilingStrategy}
class.

Currently, there are two kinds of tasks that can be run: Abstract Syntax Tree
(AST) editor tasks and Virtual Program Graph (VPG) editor tasks. AST editor tasks
depend on information from the AST of the current source file; and VPG editor
tasks depend on information from the VPG of the current source file.
\textit{FortranEditorTasks} automatically schedules the VPG editor tasks using
an instance of \textit{VPGSchedulingRule} to synchronize access to the
\textit{PhotranVPG} singleton object. The AST of the current file is computed
on-the-fly as the user modifies the source file. The VPG of the current file is
based off its previous saved version (so it is less up-to-date). For more
information about the AST and VPG, see Chapter~\ref{cha:ast-vpg}.

AST editor tasks must implement the \textit{IFortranEditorASTTask} interface and
VPG editor tasks must implement the \textit{IFortranEditorVPGTask} interface.
Additionally, each task has to register itself with the
\textit{FortranEditorTasks} object. A task that no longer needs to run should
also be unregistered. Since these tasks run asynchronously, it is important to
use proper Java concurrency practices i.e. \textbf{synchronized} methods and statements.

Below is the API of the \textit{FortranEditorTasks} class:

\begin{code}
\begin{lstlisting}
public class FortranEditorTasks
{
	public static FortranEditorTasks instance(AbstractFortranEditor editor)

	public synchronized void addASTTask(IFortranEditorASTTask task)

	public synchronized void addVPGTask(IFortranEditorVPGTask task)

	public synchronized void removeASTTask(IFortranEditorASTTask task)

	public synchronized void removeVPGTask(IFortranEditorVPGTask task)

	public Runner getRunner()
	
	...
} 
\end{lstlisting}
\caption{API of \textit{FortranEditorTasks} (see FortranEditorTasks.java)}  
\end{code}

It is possible for a class to implement both the \textit{IFortranEditorASTTask}
and \textit{IFortranEditorVPGTask} interfaces. For example, the
\textit{DeclarationView} class registers itself for both kinds of editor tasks
and makes use of the information from both as it attempts to present the
declaration for the currently selected token of the text editor.

For more information on implementation details, please refer to the following
classes:

\begin{itemize}
	\item \textit{DeclarationView}
	\item \textit{FortranCompletionProcessorASTTask}
	\item \textit{FortranCompletionProcessorVPGTask}
	\item \textit{OpenDeclarationASTTask}
\end{itemize}