1.1 --- a/doc-src/isac/CTP-userinterfaces.tex Mon Jan 10 10:31:29 2011 +0100
1.2 +++ b/doc-src/isac/CTP-userinterfaces.tex Mon Jan 10 11:54:16 2011 +0100
1.3 @@ -313,39 +313,46 @@
1.4 \subsection{Add a plug-in to jEdit}\label{plugin}
1.5 % file structure, copied from example project ...
1.6 %Die von jEdit verfolgte Strategie im Bezug auf Plugin-Management und natürlich generell die totale Offenlegegung des Codes ist für ein Projekt wie Isabelle und auch für das Isac-Project an der TU ideal. Plugins lassen sich sehr einfach anfügen und durch die riesige Vielfalt von bereits bestehenden Plugins ist auch die Adaption von Plugins möglich bzw. zu empfehlen, denn warum sollte nicht bereits funktionierender Code verwendet werden?\\
1.7 -The importance of connecting the ML-world with the world of user interfaces has been is discussed in Sect.\ref{ml-users}. jEdit follows these lines, it is an open-source, Java-based text editor that works on Windows, Mac OS X, and Linux. A big advantage of jEdit is, that there is a very good and also simple way to use and write a Plugin. There are a lot of useful and powerful Plugins available in the net and it is also possible to use a existing Plugin as part of a new one. Because of this facts, jEdit is very suitable for a project like Isabelle and also for the Isac-project at TU-Graz. \\\\
1.8 -Each jEdit-Plugin basically consists of source files, written in Java or Scala, XML-files and property files. The XML-Files are important for the administration of a Plugin and provides information like the name, author, ... of the Plugin. They are also containing small pieces of BeanShell code which is executed upon a user request. (Like pressing the 'start plugin' button.) So the XML-files provide the “glue” between user input and specific Plugin routines located in the source files. As you see, this files are used as interface between the Plugin and the jEdit engine itself.\\
1.9 +The importance of connecting the ML-world with the world of user interfaces has been is discussed in Sect.\ref{ml-users}. jEdit follows these lines, it is an open-source, Java-based text editor that works on Windows, Mac OS X, and Linux. A big advantage of jEdit is, that there is a very good and also simple way to use and write a Plugin. There are a lot of useful and powerful Plugins available in the net and it is also possible to use a existing Plugin as part of a new one. Because of this facts, jEdit is very suitable for a project like Isabelle and also for the \sisac-project at TU-Graz.
1.10 +
1.11 +Each jEdit-Plugin\footnote{To get more information about the jEdit infrastructure see: http://jedit.org/users-guide/plugin-intro} basically consists of source files, written in Java or Scala, XML-files and property files. The XML-Files are important for the administration of a Plugin and provides information like the name, author, ... of the Plugin. They are also containing small pieces of BeanShell code which is executed upon a user request. (Like pressing the 'start plugin' button.) So the XML-files provide the “glue” between user input and specific Plugin routines located in the source files. As you see, this files are used as interface between the Plugin and the jEdit engine itself.
1.12 +
1.13 Based on the jEdit API, you are allowed to design your code quit freely and don't have to use a prescribed way to implement your ideas.
1.14 -To get more information about the jEdit infrastructure see: http://jedit.org/users-guide/plugin-intro
1.15 -\\\\
1.16 +
1.17 +
1.18 %isabell plugin beschreiben!!!!!!!!
1.19 The Isabelle-team also follow use this Plugin-structure. In the next paragraph the involved files will be described. The jEdit-Isabelle-Plugin consists of:
1.20 \begin{itemize}
1.21 +\item one property file
1.22 +\item three XML-files
1.23 \item 14 Scala-source-files
1.24 -\item three XML-files
1.25 -\item one property file
1.26 \end{itemize}
1.27 %Das vom Isabelle-Team erstellte jEdit-Plugin folgt natürlich auch dem oben erklärten Muster. Es wird nun genauer auf dieses Plugin eingegangen. The plugin consits of 14 scala-source-files, three xml-files and one property-file.
1.28 -The property-file \textit{Isabelle.props} contains general informations about the Isabelle-Plugin and the needed dependencies between Isabelle and the other used Plugins like sidekick. \\
1.29 -The XML-file \textit{dockables.xml} is used to create the needed dock-able windows which are important to set up the GUI of the Plugin.\\
1.30 -In the file \textit{actions.xml}, the dockable windows are added to the window-manager \textit{wm} and there is also some Beanshell-code to activate the Isabelle-GUI.\\
1.31 -The last XML-file is \textit{services.xml} and is used to create instances of needed jEdit-Plugins.\\
1.32 -This four files are located in the folder \textit{plugin}.\\\\
1.33 -The more interesting files, the scala-files of the Plugin, can be found in the 'src/jedit'-directory. In this directory you can find the file \textit{Dummy.java} which is a dummy class and is simply used to make javadoc work. Just forget about this file. Also there is a folder/package \textit{jedit} which contains all Scala-source-files. Now it is time to take a closer look on the source-files: \\
1.34 -The file \textit{plugin.scala} is the main-file of the Isabelle-Plugin and there are two important parts. First the \textit{Isabelle object}. This object contains data like name and path and also few basic functions. The second part is the \textit{class Plugin} which is derived from EBPlugin. Here the basic methods \textit{handleMessage}, \textit{start} and \textit{stop} are implemented. Each jEdit-Plugin should have this methods because they are very important for the handling of the Plugin! \\
1.35 -jEdit and also the Isabelle Plugin work with dock-able windows. This means that you can move around each single window and dock it somewhere on the screen. So it is possible to individualize the jEdit-GUI. To support this, the file \textit{dockable.scala} is needed. The file \textit{output-dockable.scala} is derived from \textit{dockable.scala} and is used to print the result/output in a dock-able window. The same thing with \textit{protocol-dockable.scala} and \textit{raw-output-dockable.scala}.\\
1.36 -The next interesting file is \textit{scala-console.scala} with the main-class Scala-Console. This class is used to expand the Console-Plugin in a way, that it is possible to interpret Scala-code with a Shell inside of jEdit.\\
1.37 -The file \textit{isabelle-sidekick.scala} is related to the file \textit{scala-console.scala} because it is also used to adapt the Plugin Sidekick for Isabelle.\\
1.38 -The files \textit{document-model.scala} and \textit{document-view.scala1} are used to connect the jEdit-buffer/the text-area to Isabelle. Both classes offer, upon others, methods to activate and deactivate this features.\\
1.39 -There also some other source-files but they aren’t discussed here, because the main goal of this paragraph is to give a basic idea how a jEdit-Plugin should be set up and the remaining files are not as important for the Isabelle-Plugin-structure:
1.40 -\begin{itemize}
1.41 -\item $html_panel.scala$
1.42 -\item $isabelle_encoding.scala$
1.43 -\item $isabelle_hyperlinks.scala$
1.44 -\item $isabelle_options.scala$
1.45 -\item $isabelle_token_maker.scala$
1.46 -\item $isabelle_hyperlinks.scala$
1.47 -\end{itemize}
1.48 +\begin{description}
1.49 +\item[Isabelle.props] The property-file \textit{Isabelle.props} contains general informations about the Isabelle-Plugin and the needed dependencies between Isabelle and the other used Plugins like sidekick.
1.50 +\item[dockables.xml] The XML-file \textit{dockables.xml} is used to create the needed dock-able windows which are important to set up the GUI of the Plugin.
1.51 +\item[actions.xml] In the file \textit{actions.xml}, the dockable windows are added to the window-manager \textit{wm} and there is also some Beanshell-code to activate the Isabelle-GUI.
1.52 +\item[services.xml] The last XML-file is \textit{services.xml} and is used to create instances of needed jEdit-Plugins.
1.53 +\end{description}
1.54 +This four files are located in the folder \textit{plugin}.\\
1.55 +
1.56 +The more interesting files, the scala-files of the Plugin, can be found in the 'src/jedit'-directory. In this directory you can find the file \textit{Dummy.java} which is a dummy class and is simply used to make javadoc work. Just forget about this file. Also there is a folder/package \textit{jedit} which contains all Scala-source-files. Now it is time to take a closer look on the source-files:
1.57 +\begin{description}
1.58 +\item[plugin.scala] The file \textit{plugin.scala} is the main-file of the Isabelle-Plugin and there are two important parts. First the \textit{Isabelle object}. This object contains data like name and path and also few basic functions. The second part is the \textit{class Plugin} which is derived from EBPlugin. Here the basic methods \textit{handleMessage}, \textit{start} and \textit{stop} are implemented. Each jEdit-Plugin should have this methods because they are very important for the handling of the Plugin!
1.59 +\item[dockable.scala] jEdit and also the Isabelle Plugin work with dock-able windows. This means that you can move around each single window and dock it somewhere on the screen. So it is possible to individualize the jEdit-GUI. To support this, the file \textit{dockable.scala} is needed. The file \textit{output-dockable.scala} is derived from \textit{dockable.scala} and is used to print the result/output in a dock-able window. The same thing with \textit{protocol-dockable.scala} and \textit{raw-output-dockable.scala}.
1.60 +\item[scala-console.scala] The next interesting file is \textit{scala-console.scala} with the main-class Scala-Console. This class is used to expand the Console-Plugin in a way, that it is possible to interpret Scala-code with a Shell inside of jEdit.
1.61 +\item[isabelle-sidekick.scala] The file \textit{isabelle-sidekick.scala} is related to the file \textit{scala-console.scala} because it is also used to adapt the Plugin Sidekick for Isabelle.
1.62 +\item[document-model.scala, document-view.scala] The files \textit{document-model.scala} and \textit{document-view.scala} are used to connect the jEdit-buffer/the text-area to Isabelle. Both classes offer, upon others, methods to activate and deactivate this features.
1.63 +\end{description}
1.64 +There also some other source-files but they aren’t discussed here, because the main goal of this paragraph is to give a basic idea how a jEdit-Plugin should be set up and the remaining files are not as important for the Isabelle-Plugin-structure.
1.65 +%\begin{itemize}
1.66 +%\item $html_panel.scala$
1.67 +%\item $isabelle_encoding.scala$
1.68 +%\item $isabelle_hyperlinks.scala$
1.69 +%\item $isabelle_options.scala$
1.70 +%\item $isabelle_token_maker.scala$
1.71 +%\item $isabelle_hyperlinks.scala$
1.72 +%\end{itemize}
1.73
1.74
1.75 % Like each other jEdit-Plugin also this
1.76 @@ -354,13 +361,14 @@
1.77
1.78 \subsection{Details of NetBeans projects}\label{netbeans}
1.79 % Scala + Java: html project files
1.80 -As described in the last paragraph, jEdit is a open-source-project. The jEdit-developers use a NetBeans-project to produce the source-code and so it is beneficial to use a NetBeans project too, because there is a quite good documentation about setting up a NetBeans-project with the jEdit-source. See http://wiki.netbeans.org/NetbeansedJEdit for further information.\\\\
1.81 +As described in the last paragraph, jEdit is a open-source-project. The jEdit-developers use a NetBeans-project to produce the source-code and so it is beneficial to use a NetBeans project too, because there is a quite good documentation about setting up a NetBeans-project with the jEdit-source.\footnote{See http://wiki.netbeans.org/NetbeansedJEdit for further information.}
1.82 +
1.83 If you want to set up a new jEdit-Plugin-project you have to attend that you have to create some source-files and that there must be a connection to the jEdit-source because you will need to exchange data with the jEdit engine. This could probably look like: \textit{jEdit.getProperty("options.isabelle.isabelle")}\\
1.84 As shown above, the jEdit-source is needed to compile and build your Plugin. There are two ways to organize your project:
1.85 -\begin{itemize}
1.86 -\item with jEdit source code - two projects in one
1.87 -\item with jedit.jar library
1.88 -\end{itemize}
1.89 +%\begin{itemize}
1.90 +%\item with jEdit source code - two projects in one
1.91 +%\item with jedit.jar library
1.92 +%\end{itemize}
1.93 \subsubsection{Plugin with jEdit-source}
1.94 It is a good way to download the jEdit source as Netbeans project because then it is possible to add another subproject to the existing jEdit-NetBeans-project. As you see it is also possible to mix Scala and Java. A big advantage is, that debugging will now work really fine. If you want to set up a project like this, you should complete the following steps.
1.95 \begin{enumerate}
1.96 @@ -390,15 +398,21 @@
1.97 \end{itemize}
1.98 %* kurze aufzählung der xml-netbeans-files + erklärung\\
1.99 \subsubsection{NetBeans project files}
1.100 -As you see in the paragraph above, it is also important to have basic knowledge about NetBeans, the project structure and how to change the operational sequences. A typical NetBeans-project consist of the source- and library-files and administrative XML- and property-files. In this paragraph the administrative part of the project is of note. The most important file is \textit{build.xml}. This file can be found in the project directory. There is also a folder \textit{nbproject} which contains the remaining XML- and property-files and also a folder \textit{private}, where individual user informations about the project is stored. The files in this \textit{private} folder are not important to describe (and they should not be pushed on the repository!).\\
1.101 -A build-file like \textit{build.xml} contains one project and at least one (default) target. Targets contain task elements. Each task element of the build-file can have an id attribute and can later be referred to by the value supplied to this. So the id has to be unique. Such targets can be "run", "debug", "build", ... and can have dependencies to other targets. Tasks define what should happen, if a target is executed. So like in the example above, the target is \textit{pre-jar}, that means that this things will happen before the jar-package is packed. The tasks of this target are copying some files into the package.\\
1.102 +As you see in the paragraph above, it is also important to have basic knowledge about NetBeans, the project structure and how to change the operational sequences. A typical NetBeans-project consist of the source- and library-files and administrative XML- and property-files. In this paragraph the administrative part of the project is of note. The most important file is \textit{build.xml}. This file can be found in the project directory. There is also a folder \textit{nbproject} which contains the remaining XML- and property-files and also a folder \textit{private}, where individual user informations about the project is stored. The files in this \textit{private} folder are not important to describe (and they should not be pushed on the repository!).
1.103 +
1.104 +A build-file like \textit{build.xml} contains one project and at least one (default) target. Targets contain task elements. Each task element of the build-file can have an id attribute and can later be referred to by the value supplied to this. So the id has to be unique. Such targets can be "run", "debug", "build", ... and can have dependencies to other targets. Tasks define what should happen, if a target is executed. So like in the example above, the target is \textit{pre-jar}, that means that this things will happen before the jar-package is packed. The tasks of this target are copying some files into the package.
1.105 +
1.106 The files inside the \textit{nbproject}-folder are not so important because some of it are generated from \textit{build.xml} and changes in this files are useless. Just the file project.properties is really interesting because this file gives a nice and tight overview about the project settings.
1.107
1.108 \subsection{Use interfaces between Java and Scala}\label{java-scala}
1.109 % how are data exchanged between Scala and Java ...
1.110 -jEdit is completely written in Java and the required plugin(s) for Isac will be coded in Scala - so there must be ways to exchange data between Java and Scala. One way is to connect this two worlds with the in 4.2 described XML-files. Here you need to use a third type of code to get an interface between Java and Scala code. But there is also a way to get a direct connection.\\
1.111 -This link should be shown on the graphic-library \textit{Swing}. In both languages it is possible to use Swing which provides a lot of different shapes and useful functionality. So there is a Java-Swing and also a Scala-Swing-library. Now it is interesting to examine the connection between this two libraries.\\
1.112 -In Scala a direct use of Java-Libs (like Java-Swing) is possible. So if you are Java-Programmer and want to use Java-Swing in Scala, you can simply type \textit{import javax.swing.JButton} to work with a Java-button. But you can also use the Scala-equivalent \textit{scala.swing.Button}. This two button-types will provide nearly the same functionality.\\So what is the idea of creating a nearly similar library a second time? Why have the Scala-developers done such extra work? The answer is, that they have tried to improve and simplify the usage of the Swing-library(and many other libs too!). So big parts of this Scala-Libraries are just Wrapper-objects, Wrapper-Classes and Wrapper-Methods of already existing parts in Java-Libraries. Needless to say that they also added new useful shapes and functionality.\\
1.113 +jEdit is completely written in Java and the required plugin(s) for \sisac{ }will be coded in Scala - so there must be ways to exchange data between Java and Scala. One way is to connect this two worlds with the in 4.2 described XML-files. Here you need to use a third type of code to get an interface between Java and Scala code. But there is also a way to get a direct connection.
1.114 +
1.115 +This link should be shown on the graphic-library \textit{Swing}. In both languages it is possible to use Swing which provides a lot of different shapes and useful functionality. So there is a Java-Swing and also a Scala-Swing-library. Now it is interesting to examine the connection between this two libraries.
1.116 +
1.117 +In Scala a direct use of Java-Libs (like Java-Swing) is possible. So if you are Java-Programmer and want to use Java-Swing in Scala, you can simply type\\ \textit{import javax.swing.JButton}\footnote{http://download.oracle.com/javase/1.4.2/docs/api/javax/swing/JButton.html} to work with a Java-button. But you can also use the Scala-equivalent \textit{scala.swing.Button}\footnote{http://www.scala-lang.org/api/current/scala/swing/Button.html}. This two button-types will provide nearly the same functionality.
1.118 +
1.119 +So what is the idea of creating a nearly similar library a second time? Why have the Scala-developers done such extra work? The answer is, that they have tried to improve and simplify the usage of the Swing-library(and many other libs too!). So big parts of this Scala-Libraries are just Wrapper-objects, Wrapper-Classes and Wrapper-Methods of already existing parts in Java-Libraries. Needless to say that they also added new useful shapes and functionality.
1.120 But there is one important question left: Is it possible to mix Scala- and Java-objects? And yes, it is possible. There is a really easy way to convert a Scala-object to the Java-equivalent:
1.121 \begin{enumerate}
1.122 \item \textit{import javax.swing.JButton}
1.123 @@ -409,9 +423,6 @@
1.124 \end{enumerate}
1.125 As the example above illustrates, a conversion of Scala- to Java-objects is possible. It looks easy but also a little bit useless. Why should you need this? Just imagine that there is a Plugin written in Scala and one coded in Java. With this connection between Scala and Java, it would be easy to connect this two Plugins!
1.126 %Diesen direkten Zusammenhang zwischen Java und Scala soll anhand der Grafik-Bibliotheken Swing. Beide Sprachen stellen diese Grafik-Bibliotheken zur Verfügung (und darin auch eigene Shapes und Funktionalität). Es ist jedoch möglich, Java-Bibliotheken, wie eben auch Java-Swing in Scala zu verwenden. Ein JButton kann zum Beispiel mittels \textit{import javax.swing.JButton} eingebunden und damit sofort auch verwendet werden. Auch Scala stellt in seiner Swing-Bibliothek zur Verfügung: \textit{scala.swing.Button}. Es wird nahezu die selbe Funktionalität angeboten und teilweise die Erzeugung bzw. Verwendung vereinfacht(???). Man kann sich nun fragen, warum sich die Scala-Entwickler einerseit die Mühe gemacht haben die Verwendung Java-Swing, wie in Java selbst, möglich zu machen und andererseits mit Scala-Swing eine nahezu idente Alternative geschaffen haben. Die Antwort darauf zeigt wie der objektorientierte Teil von Scala in vielen Bereichen aufgebaut wurden. Es wurde kein neues Konzept für diese Grafikklassen entworfen sondern Wrapper-Objekte/Methoden/Klassen erstellt, die das Arbeiten mit diesen Grafikkomponenten erleichtern soll. Ein Letztes Problem bleibt noch: Es ist zwar sehr einfach ein Java-Swing-Objekt an einen Scala-Swing-Container (zb. Frame) anzubinden, da eine Konvertierung von Java-Komponente in ein Scala-Äquivalent ist problemlos möglich. ...
1.127 -http://www.scala-lang.org/api/current/scala/swing/Button.html\\
1.128 -http://download.oracle.com/javase/1.4.2/docs/api/javax/swing/JButton.html
1.129 -
1.130 \section{Conclusion and future work}
1.131
1.132