Changeset 1060


Ignore:
Timestamp:
Jan 11, 2010, 12:56:41 AM (12 years ago)
Author:
Sebastian Przybylski
Message:

Removed the right chapter titles; Fixed wrong image positions; fixed wrong chapter references; fixed and complete some text passages; changed abstract page

Location:
trunk/Documentation
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/Documentation/Developer/PluginHowTo/HowToDeveloper.tex

    r1053 r1060  
    4747\fancyhead[L]{\leftmark} %Kopfzeile links
    4848\fancyhead[C]{\AddToShipoutPicture*{\BackgroundHeaderPic}} %zentrierte Kopfzeile
    49 \fancyhead[R]{\rightmark} %Kopfzeile rechts
     49%\fancyhead[R]{\rightmark} %Kopfzeile rechts --> Removed because it's overflowing on the leftmark if the text is too long
    5050
    5151\fancyfoot[C]{\thepage\AddToShipoutPicture*{\BackgroundFooterPic}} %zentrierte Fußzeile
     
    115115
    116116\title{CrypTool 2.0}
    117 \subtitle{Developer Manual}
    118 \author{S.\ Przybylski, A.\ Wacker, M\ Wander and F\ Enkler}
     117\subtitle{\Huge Developer Manual\\\normalsize How to build your own plugins for CT2?}
     118\author{S.\ Przybylski, A.\ Wacker, M.\ Wander and F.\ Enkler}
    119119\email{\{przybylski$|$wacker$|$wander$|$enkler\}@cryptool.org}
    120120\version{0.1}
     
    159159\begin{document}
    160160        \maketitle
     161       
     162        \begin{abstract}
     163    \textbf{''Abstract.} CrypTool 2 is the modern successor of the well known e-learning platform for cryptography and cryptanalysis \htmladdnormallink{CrypTool 1}{http://www.cryptool.org}, which is used world-wide for educational purposes at school and universities and in companies and agencies.\\\\Since the first launch of CrypTool 1 in 1999 the art of software development has changed dramatically. So the CrypTool 2 team started in 2008 to develop a completely new e-learning application, embracing the newest trends in both didactics and software architecture to delight the end-user with an entirely new experience.\\\\CT 2 is build using
     164\renewcommand{\labelitemi}{-}
     165\begin{itemize}
     166        \item .NET (modern software framework with solutions to common programming problems form Microsoft),
     167        \item C\# (modern object-oriented programming language, comparable to Java) and
     168 \item WPF (modern purely vector-based graphical subsystem for rendering user interfaces in Windows-based applications) plus
     169 \item VisualStudio2008 (development environment) and
     170        \item Subversion (source code and documentation version management system).
     171\end{itemize}\\
     172This document is intended for plugin developers, who want to contribute new visual or mathematical functionality to CT2.\\Currently (January 2010) the code exists of about 7000 lines of C\# code in the Core system and about 240,641 lines of C\# code in the 115 plugins.\\\\For further news and more screenshots please see the developer page \htmladdnormallink{http://www.cryptool2.vs.uni-due.de}{http://www.cryptool2.vs.uni-due.de}.''
     173    \end{abstract}
    161174
    162175        \tableofcontents
    163176
    164177   
    165     \AddToShipoutPicture{\WaterMarkPic}
    166 
    167 
    168     \begin{abstract}
    169     \textbf{Abstract.} This document is intended for plugin developers.
    170     \end{abstract}
     178    \AddToShipoutPicture{\WaterMarkPic} 
    171179
    172180        \include{part1}
  • trunk/Documentation/Developer/PluginHowTo/part2.tex

    r1053 r1060  
    44\label{sec:CreateANewProjectInVS2008ForYourPlugin}
    55Open Visual Studio 2008 or C\# 2008 Express Edition and create a new project:\\
    6 \begin{figure}[h]
     6\begin{figure}[h!]
    77        \centering
    88                \includegraphics[width=1.00\textwidth]{figures/vs_create_new_project.jpg}
     
    1111\end{figure}\\
    1212Select ''.NET-Framework 3.5'' as the target framework (the Visual Studio Express edition don't provide this selection because it automatically chooses the actual target framework), and ''Class Library'' as default template to create a DLL file. Give the project a unique and significant name (here: ''Caesar''), and choose a location where to save (the Express edition will ask later for a save location when you close your project or your environment). Select the subdirectory ''CrypPlugins'' from your SVN trunk as location. Finally confirm by pressing the ''OK'' button.
    13 \begin{figure}[h]
     13\begin{figure}[h!]
    1414        \centering
    1515                \includegraphics[width=0.80\textwidth]{figures/save_solution_csharp_express.JPG}
     
    1818\end{figure}\\
    1919Now your Visual Studio/C\# Express solution should look like this:\\
    20 \begin{figure}[h]
     20\begin{figure}[h!]
    2121        \centering
    2222                \includegraphics[width=1.00\textwidth]{figures/solution_start_up.jpg}
     
    3333\end{figure}\\
    3434Make a right click in the Solution Explorer on the ''Reference'' item and choose ''Add Reference''.\\
    35 \begin{figure}[h]
     35\begin{figure}[h!]
    3636        \centering
    3737                \includegraphics{figures/add_pluginbase_source.jpg}
     
    4040\end{figure}\\
    4141Select the project ''CrypPluginBase''. If you don't have the CrypPluginBase source code, it's also possible to add a reference the the binary DLL. In this case browse to the path where the library file ''CrypPluginBase.dll'' is located e.g. ''C:\textbackslash Documents and Settings \textbackslash $<$Username$>$ \textbackslash My Documents\textbackslash Visual Studio  2008\textbackslash Projects\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug'') and select the library by double clicking the file or pressing the "OK" button.\\
    42 \begin{figure}[h]
     42
     43\textit{\small Note: You can also take the binary DLL which is located in the folder where the ''CrypWin.exe'' is placed when you download CrypTool2.}
     44
     45\clearpage
     46\begin{figure}[h!]
    4347        \centering
    4448                \includegraphics{figures/browse_reference.jpg}
     
    5155    \item PresentationFramework
    5256    \item WindowsBase
    53 \end{itemize}
     57\end{itemize}\clearpage
    5458Afterwards your reference tree view should look like this:
    5559\begin{figure}[h!]
     
    6872        \item Rename the existent class
    6973        \item Delete the existent class and create a new one.
    70 \end{itemize}
     74\end{itemize}\clearpage
    7175Which one you choose is up to you. We choose the second way as you can see in the next screenshot:
    7276\begin{figure}[h!]
     
    7579        \caption{Create new class}
    7680        \label{fig:new_class}
    77 \end{figure}\\
     81\end{figure}\clearpage
    7882Now make a right click on the project item "Caesar" and select "Add-$>$Class...":
    7983\begin{figure}[h]
     
    8286        \caption{Add a new class}
    8387        \label{fig:add_new_class}
    84 \end{figure}\\
    85 Now give your class a unique name. We call the class as mentioned above "Caesar.cs" and make it public to be available to other classes.\\
     88\end{figure}\clearpage
     89Now give your class a unique name. We call the class as mentioned above "Caesar.cs" and make it public to be available to other classes.
    8690\begin{figure}[h!]
    8791        \centering
     
    8993        \caption{Name the new class}
    9094        \label{fig:name_new_class}
    91 \end{figure}\\
     95\end{figure}
    9296\subsection{Create the class for the settings (CaesarSettings)}\label{sec:CreateTheClassForTheSettingsCaesarSettings}
    93 Add a second public class for ISettings in the same way. We call the class "CaesarSettings". The settings class provides the necessary information about controls, captions and descriptions and default parameters for e.g. key settings, alphabets, key length and action to build the \textbf{TaskPane} in CrypTool. How a \textbf{TaskPane} could look like you can see below for the example of a Caesar encryption.\\
     97Add a second public class for ISettings in the same way. We call the class "CaesarSettings". The settings class provides the necessary information about controls, captions and descriptions and default parameters for e.g. key settings, alphabets, key length and action to build the \textbf{TaskPane} in CrypTool.\clearpage
     98How a \textbf{TaskPane} could look like you can see below for the example of a Caesar encryption.\\
    9499\begin{figure}[h!]
    95100        \centering
     
    104109        \item Cryptool.PluginBase = interfaces like IPlugin, IHash, ISettings, attributes, enumerations, delegates and extensions.
    105110        \item Cryptool.PluginBase.Analysis = interface for the crypto analysis plugins like ''Stream Comparator''
    106         \item Cryptool.PluginBase.Control = ?
     111        \item Cryptool.PluginBase.Control = contains global interfaces for the IControl feature to define own controls
    107112        \item Cryptool.PluginBase.Cryptography = interface for all encryption and hash algorithms like AES, DES or MD5 hash
    108113        \item Cryptool.PluginBase.Editor = interface for editors you want to implement for CrypTool 2.0 like the default editor
     
    110115        \item Cryptool.PluginBase.IO = interface for CryptoolStream, input and output plugins like text input, file input, text output and file output
    111116        \item Cryptool.PluginBase.Miscellaneous = provides all event helper like GuiLogMessage or PropertyChanged
    112         \item Cryptool.PluginBase.Resources = ?
     117        \item Cryptool.PluginBase.Resources = used by CrypWin and the editor. Not required for plugin developers
    113118        \item Cryptool.PluginBase.Tool = interface for all foreign tools which CrypTool 2.0 has to provide and which does not exactly support the CrypTool 2.0 API
    114119        \item Cryptool.PluginBase.Validation = interface which provides method for validation like regular expression
     
    121126        \item ''Cryptool.PluginBase.Miscellaneous'' to use the entire CrypTool event handler
    122127\end{itemize}
    123 It is important to define a new default namespace of our public class (''Caesar''). In CrypTool the default namespace is presented by ''Cryptool.[name of class]''. Therefore our namespace has to be defined as follows: ''Cryptool.Caesar''.\\
     128It is important to define a new default namespace of our public class (''Caesar''). In CrypTool the default namespace is presented by ''Cryptool.[name of class]''. Therefore our namespace has to be defined as follows: ''Cryptool.Caesar''.\clearpage
    124129Up to now the source code should look as you can see below:
    125130\begin{lstlisting}
     
    633638Before we go back to the code of the Caesar class, we have to add an icon image to our project, which will be shown in the CrypTool \textbf{ribbon bar} or/and \textbf{navigation pane}. As there is no default, using an icon image is mandatory.\\\\
    634639\textit{\small Note: This will be changed in future. A default icon will be used if no icon image has been provided.}\\\\
    635 For testing purposes you may create a simple black and white PNG image with MS Paint or Paint.NET. As image size you can use 40x40 pixels for example, but as the image will be scaled when required, any size should do it. Place the image file in your project directory or in a subdirectory. Then make a right click on the project item "Caesar" or any subdirectory within the Solution Explorer, and select ''Add-$>$Existing Item...'':
     640For testing purposes you may create a simple black and white PNG image with MS Paint or Paint.NET. As image size you can use 40x40 pixels for example, but as the image will be scaled when required, any size should do it. Place the image file in your project directory or in a subdirectory.\clearpage
     641Then make a right click on the project item "Caesar" or any subdirectory within the Solution Explorer, and select ''Add-$>$Existing Item...'':
    636642\begin{figure}[h!]
    637643        \centering
     
    639645        \caption{Add existing item}
    640646        \label{fig:add_existing_item}
    641 \end{figure}\\
    642 As you can see, in our solution we create an new folder named ''Images'' (make a right click on the project item ''Caesar'' and select ''Add-$>$New Folder'') and placed there the new icon by clicking right on the folder as mentioned aboved.
     647\end{figure}
     648As you can see, in our solution we create an new folder named ''Images'' (make a right click on the project item ''Caesar'' and select ''Add-$>$New Folder'') and placed there the new icon by clicking right on the folder as mentioned aboved.\clearpage
    643649Then select ''Image Files'' as file type, and choose the icon for your plugin:
    644650\begin{figure}[h!]
     
    647653        \caption{Choose the right icon}
    648654        \label{fig:choose_icon}
    649 \end{figure}\\
    650 Finally we have to set the icon as a ''Resource'' to avoid providing the icon as a separate file. Make a right click on the icon and select the item ''Properties'':
     655\end{figure}
     656Finally we have to set the icon as a ''Resource'' to avoid providing the icon as a separate file. Make a right click on the icon and select the item ''Properties'':\clearpage
    651657\begin{figure}[h!]
    652658        \centering
     
    654660        \caption{Icon properties}
    655661        \label{fig:icon_properties}
    656 \end{figure}\\
     662\end{figure}
    657663In the ''Properties'' panel you have to set the ''Build Action'' to ''Resource'' (not embedded resource):
    658664\begin{figure}[h!]
     
    663669\end{figure}
    664670\section{Set the attributes for the class Caesar}\label{sec:SetTheAttributesForTheClassCaesar}
    665 Now let's go back to the code of the Caesar class ("Caesar.cs" file). First we have to set the necessary attributes for our class. This attributes are used to provide additional information for the CrypTool 2.0 environment. If not set, your plugin won't show up in the GUI, even if everything else is implemented correctly.\\\\
    666 Attributes are used for \textbf{declarative} programming and provide meta data, that can be attached to the existing .NET meta data , like classes and properties. Cryptool provides a set of custom attributes, that are used to mark the different parts of your plugin.\\\\
     671Now let's go back to the code of the Caesar class (''Caesar.cs'' file). First we have to set the necessary attributes for our class. This attributes are used to provide additional information for the CrypTool 2.0 environment. If not set, your plugin won't show up in the GUI, even if everything else is implemented correctly.\\\\
     672Attributes are used for \textbf{declarative} programming and provide meta data, that can be attached to the existing .NET meta data , like classes and properties. CrypTool provides a set of custom attributes, that are used to mark the different parts of your plugin.\\\\
    667673\textit{[Author]}\\
    668674The first attribute called ''Author'' is optional, which means we are not forced to define this attribute. It provides the additional information about the plugin developer. This informations you can see for example in the TaskPane as shown on a screenshot above. We set this attribute to demonstrate how it has to look in case you want to provide this attribute.
     
    744750        \label{fig:attribute_plugininfo_icon}
    745751\end{figure}\\
    746 The detailed description could now look like this in CrypTool (right click plugin icon on workspace and select ''Show description''):
    747 \begin{figure}[h]
     752The detailed description could now look like this in CrypTool (right click plugin icon on workspace and select ''Show description''):\clearpage
     753\begin{figure}[h!]
    748754        \centering
    749755                \includegraphics[width=1.00\textwidth]{figures/xaml_description.jpg}
     
    789795        #endregion
    790796\end{lstlisting}
    791 Please notice if there is a sinuous line at the code you type for example at the ''CryptoolStream'' type of the variable listCryptoolStreamsOut. ''CryptoolStream'' is a data type for input and output between plugins and is able to handle large data amounts. To use the CrypTool own stream type, include the namespace ''Cryptool.PluginBase.IO'' with a ''using'' statement as explained in chapter 3.3. Check the other code entries while typing and update the missing namespaces.\\
     797Please notice if there is a sinuous line at the code you type for example at the ''CryptoolStream'' type of the variable listCryptoolStreamsOut. ''CryptoolStream'' is a data type for input and output between plugins and is able to handle large data amounts. To use the CrypTool own stream type, include the namespace ''Cryptool.PluginBase.IO'' with a ''using'' statement as explained in chapter \ref{sec:AddNamespaceForTheClassCaesarAndThePlaceFromWhereToInherit}. Check the other code entries while typing and update the missing namespaces.\\
    792798The following private variables are being used in this example:
    793799\begin{itemize}
     
    826832}
    827833\end{lstlisting}
    828 Thirdly we have to define five properties with their according attributes. This step is necessary to tell Cryptool that these properties are input/output properties used for data exchange with other plugins or to provide our plugin with external data.\\
     834Thirdly we have to define five properties with their according attributes. This step is necessary to tell CrypTool that these properties are input/output properties used for data exchange with other plugins or to provide our plugin with external data.\\
    829835The attribute is named ''PropertyInfo'' and consists of the following elements:
    830836\begin{itemize}
     
    11231129}
    11241130\end{lstlisting}
    1125 It is important to make sure that all changes of output properties will be announced to the CrypTool environment. In this example this happens by calling the setter of OutputData which in turn calls ''OnPropertyChanged'' for both output properties ''OutputData'' and ''OutputDataStream''. Instead of calling the property's setter you can as well call ''OnPropertyChanged'' directly within the ''Execute()'' method.\\\\
     1131It is important to make sure that all changes of output properties will be announced to the CrypTool environment. In this example this happens by calling the setter of OutputData which in turn calls ''OnPropertyChanged'' for both output properties ''OutputData'' and ''OutputDataStream''. Instead of calling the property's setter you can as well call ''OnPropertyChanged'' directly within the ''Execute()'' method.\clearpage
    11261132Certainly you have seen the unknown method ''ProgressChanged'' which you can use to show the current algorithm process as a progress on the plugin icon.
    11271133To use this method you also have to declare this method to afford a successful compilation:
     
    11541160        Dispose();
    11551161}
    1156 \end{lstlisting}
     1162\end{lstlisting}\clearpage
    11571163\section{Finish implementation}\label{sec:FinishImplementation}
    11581164When adding plugin instances to the CrypTool workspace, CrypTool checks whether the plugin runs without any exception. If any IPlugin method throws an exception, CrypTool will show an error and prohibit using the plugin. Therefore we have to remove the ''NotImplementedException'' from the methods ''Initialize()'', ''Pause()'' and ''Stop()''. In our example it's sufficient to provide empty implementations.
     
    11821188}
    11831189\end{lstlisting}
    1184 Your plugin should compile without errors at this point.
    1185 \section{Sign the created plugin}\label{sec:SignTheCreatedPlugin}
    1186 \section{Import the plugin to Cryptool and test it}\label{sec:ImportThePluginToCryptoolAndTestIt}
     1190Your plugin should compile without errors at this point.\clearpage
     1191\section{Import the plugin to CrypTool and test it}\label{sec:ImportThePluginToCryptoolAndTestIt}
    11871192After you have built the plugin, you need to move the newly created plugin DLL to a location, where CrypTool can find it. To do this, there are the following ways:
    11881193\begin{itemize}
     
    11941199        \label{fig:copy_dll_global_storage}
    11951200\end{figure}\\
    1196 This folder is called ''Global storage'' in the CrypTool architecture. Changes in this folder will take effect for all users on a multi user Windows. Finally restart CrypTool.
     1201This folder is called ''Global storage'' in the CrypTool architecture. Changes in this folder will take effect for all users on a multi user Windows. Finally restart CrypTool.\clearpage
    11971202\begin{figure}[h]
    11981203        \centering
     
    12021207\end{figure}\\
    12031208        \item Copy your plugin DLL file in the folder ''CrypPlugins'' which is located in your home path in the folder ''ApplicationData'' and restart CrypTool.  This home folder path is called ''Custom storage'' in the CrypTool architecture. Changes in this folder will only take effect for current user.  On a German Windows XP the home folder path could look like:
    1204 ''C:\textbackslash Dokumente und Einstellungen\textbackslash $<$User$>$\textbackslash Anwendungsdaten\textbackslash CrypPlugins'' and in Vista/Windows7 the path will look like ''C:\textbackslash Users\textbackslash $<$user$>$\textbackslash Application Data\textbackslash CrypPlugins''.
     1209''C:\textbackslash Dokumente und Einstellungen\textbackslash $<$User$>$\textbackslash Anwendungsdaten\textbackslash CrypPlugins'' and in Vista/Windows7 the path will look like ''C:\textbackslash Users\textbackslash $<$user$>$\textbackslash Application Data\textbackslash CrypPlugins''.\clearpage
    12051210\begin{figure}[h]
    12061211        \centering
     
    12121217Notice, that this plugin importing function only accepts \textbf{signed} plugins.
    12131218
    1214 \textit{\small Note: This option is a temporary solution for importing new plugins. In the future this will be done online by a web service.}
     1219\textit{\small Note: This option is a temporary solution for importing new plugins. In the future this will be done online by a web service.}\clearpage
    12151220
    12161221        \item Use post-build in your project properties to copy the DLL automatically after building it in Visual Studio with other plugins. Right-click on your plugin project and select ''Properties'':
     
    12201225        \caption{Solution Properties}
    12211226        \label{fig:solution_properties}
    1222 \end{figure}\\
     1227\end{figure}\clearpage
    12231228Select ''Build Events'':
    12241229\begin{figure}[h]
     
    12411246password: not required\\}
    12421247\htmladdnormallink{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
    1243 Here you can download the Visual Studio plugin \textbf{template} to begin with the development of a new Cryptool plugin:\\\\
    1244 \htmladdnormallink{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
     1248Here you can download the Visual Studio plugin \textbf{template} to begin with the development of a new CrypTool plugin:\\\\
     1249\htmladdnormallink{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}\clearpage
    12451250\section{Provide a workflow file of your plugin}\label{ProvideAWorkflowFileOfYourPlugin}
    12461251Every plugin developer should provide a workflow file which shows his algorithm working in CrypTool2. You will automatically create a workflow file by saving your project which was created on CrypTool2 work space. Here is an example how a workflow could look like:
Note: See TracChangeset for help on using the changeset viewer.