Changeset 1243


Ignore:
Timestamp:
Mar 16, 2010, 5:21:26 PM (12 years ago)
Author:
Patrick Vacek
Message:

HowTo: finished second round of thorough editing. Changed up some images, made countless small and not-so-small changes.

Several issues remain unresolved:

  • Developer guidlines != wiki
  • Should we be using American or British English?
  • Figures with German text should probably be anglicized
  • CrypTool vs. CrypTool 2 vs. CrypTool 2.0
  • Abstract claims 115 plugins; I count 90
  • Chapter 1 recommends only VS 2008 Pro but Chapter 2 suddenly speaks of C# Express
  • Copying code from output is difficult due to line numbers and strange extra spaces
  • Watermark can be selected in output
  • Section 2.6.2 contradicts itself in terms of multilingual support / internationalization / localization
  • #region and #endregion should be blue, 'in' should only be in certain cases
  • Custom storage plugin loading does not work.
  • Download/manage plugin buttons do not work.
  • Signed plugins are never explained (Section 2.12.3)
  • The post-build event commands in 2.12.4 have extra spaces around the highlighting in the output
  • Where do you save the workflow image?
Location:
trunk/Documentation/Developer/PluginHowTo
Files:
4 added
13 deleted
7 edited

Legend:

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

    r1236 r1243  
    3535breaklines=true, % Wordwrap activated
    3636showstringspaces=false,
     37morestring=[b]', % counts single quote pairs as strings (and thus also colors them red)
    3738upquote=true, % changes smart single quotes to straight ' marks
    3839% emph defines certain colors for specific words
    39 emph={double,bool,int,unsigned,char,true,false,void},
    40 emphstyle=\color{blue},
    41 emph={Assert,Test},
    42 emphstyle=\color{BrickRed},
    43 emph={[2]\using,\#define,\#ifdef,\#endif}, emphstyle={[2]\color{blue}}
     40% emph={double,bool,int,unsigned,char,true,false,void},emphstyle=\color{blue},
     41emph={Assert,Test}, emphstyle=\color{BrickRed},
     42emph={[2]double,bool,int,unsigned,char,true,false,void,using,\#define,\#ifdef,\#endif,\#region,\#endregion},
     43emphstyle={[2]\color{blue}}
    4444}
    4545
  • trunk/Documentation/Developer/PluginHowTo/part1.tex

    r1236 r1243  
    4343\begin{figure}[h!]
    4444        \centering
    45                 \includegraphics[width=0.60\textwidth]{figures/tortoise_svn_checkout2.jpg}
     45                \includegraphics[width=0.60\textwidth]{figures/tortoise_svn_checkout_window.jpg}
    4646        \caption{Checking out the CrypTool 2 repository.}
    4747        \label{fig:tortoise_svn_checkout2}
     
    103103\begin{figure}[h!]
    104104        \centering
    105                 \includegraphics[width=0.70\textwidth]{figures/tortoise_svn_commit2.jpg}
     105                \includegraphics[width=0.70\textwidth]{figures/tortoise_svn_commit_window.jpg}
    106106        \caption{Providing comments for a commit.}
    107107        \label{fig:tortoise_svn_commit2}
  • trunk/Documentation/Developer/PluginHowTo/part2.tex

    r1236 r1243  
    147147\end{figure}
    148148
    149 Note that Visual Studio will automatically generate a very basic code outline for the new class. In our example, we will not use the all the namespaces that are automatically imported, so you can delete the lines \texttt{using System;} and \texttt{using System.Linq;}.
     149Note that Visual Studio will automatically generate a very basic code outline for the new class. In our example, we will not use the all the namespaces that are automatically imported, so you can delete the line \texttt{using System.Linq;}.
    150150
    151151\subsection{Creating a settings class}
     
    198198
    199199\begin{lstlisting}
     200using System;
    200201using System.Collections.Generic;
    201202using System.Text;
     
    230231\label{sec:AddingInterfaceFunctionsToTheCaesarClass}
    231232
    232 You may notice an underscore underneath the ``I'' in ``IEncryption''. Move your mouse over it, or place the cursor on it and press ``Shift+Alt+F10'' and the following submenu should appear:
     233You may notice an underscore underneath the \textit{I} in \textit{IEncryption}. Move your mouse over it, or place the cursor on it and press \textit{Shift+Alt+F10} and the following submenu should appear:
    233234
    234235\begin{figure}[h!]
     
    239240\end{figure}
    240241
    241 Select the item ``Implement interface `IEncryption'\,''. Visual Studio will automatically generate all the interface members necessary for interaction with the CrypTool 2 core. (This step will save you a lot of typing!)
     242Select the item \textit{Implement interface `IEncryption'}. Visual Studio will automatically generate all the interface members necessary for interaction with the CrypTool 2 core. (This step will save you a lot of typing!)
    242243\clearpage
    243244
     
    245246
    246247\begin{lstlisting}
     248using System;
    247249using System.Collections.Generic;
    248250using System.Text;
     
    329331\label{sec:AddingTheNamespaceAndInterfacesToTheCaesarSettingsClass}
    330332
    331 Let's now take a look at the second class in our example, ``CaesarSettings'', by double-clicking on the ``CaesarSettings.cs'' file in the Solution Explorer. First, we need to again include the ``Cryptool.PluginBase'' namespace to the class header. Then we must let the settings class inherit from ``ISettings'' in the same manner as was done with the Caesar class. Visual Studio will again automatically generate code from the CrypTool interface as seen below. (We can again remove the lines \texttt{using System;} and \texttt{using System.Linq;}, as we do not need those references.)\\
    332 
    333 \begin{lstlisting}
    334 using System.Collections.Generic;
    335 using System.Text;
     333Let's now take a look at the second class in our example, \textit{CaesarSettings}, by double-clicking on the \textit{CaesarSettings.cs} file in the Solution Explorer. First, we need to again include the \textit{Cryptool.PluginBase} namespace to the class header. Then we must let the settings class inherit from \textit{ISettings} in the same manner as was done with the Caesar class. Visual Studio will again automatically generate code from the CrypTool interface as seen below. (In this case, we can remove the using \texttt{System.Collections.Generic;}, \texttt{using System.Linq;}, and \texttt{using System.Text;} lines, as we will not use those references.)
     334\clearpage
     335
     336\begin{lstlisting}
     337using System;
    336338
    337339using Cryptool.PluginBase;
     
    369371\label{sec:AddingControlsToTheCaesarSettingsClass}
    370372
    371 The settings class is used to populate the TaskPane in the CrypTool 2 application so that the user can modify settings at will. To meet these ends we will need to implement some controls such as buttons and text boxes. If you will be implementing an algorithm that does not have any user-defined settings (i.e.\ a hash function), then this class can be left empty; you will, however, still have to modify the ``HasChanges'' property to avoid a ``NotImplementedException''. The following code demonstrates the modifications necessary to create the backend for the TaskPane for our Caesar algorithm. You can also look at the source code of other algorithms in the subversion repository for examples of how to create the TaskPane backend.\\
     373The settings class is used to populate the TaskPane in the CrypTool 2 application so that the user can modify the plugin settings at will. Thus we will need to implement some controls, such as buttons and text boxes, to allow for the necessary interaction. If you will be implementing an algorithm that does not have any user-defined settings (i.e.\ a hash function), then this class can be left mostly empty; you will, however, still have to modify the \textit{HasChanges} property to avoid a \textit{NotImplementedException}. The following code demonstrates the modifications necessary to create the backend for the TaskPane for our Caesar algorithm. You can also look at the source code of other CrypTool 2 plugins for examples of how to create the TaskPane backend.\\
    372374
    373375\begin{lstlisting}
     
    375377using System.ComponentModel;
    376378using System.Windows;
     379using System.Windows.Controls;
     380
    377381using Cryptool.PluginBase;
    378 using System.Windows.Controls;
    379382
    380383namespace Cryptool.Caesar
     
    385388
    386389        /// <summary>
    387         /// We use this delegate to send log messages from
     390        /// This delegate is ued to send log messages from
    388391        /// the settings class to the Caesar plugin.
    389392        /// </summary>
     
    435438                   // some form of set method to prevent problems.
    436439        }
    437 
    438440
    439441        /// <summary>
     
    561563            set
    562564            {
    563                 if (value != selectedAction) HasChanges = true;
    564                 this.selectedAction = value;
    565                 OnPropertyChanged("Action");
    566 
    567                 if (ReExecute != null) ReExecute();
     565                if(value != selectedAction)
     566                {
     567                        HasChanges = true;
     568                        this.selectedAction = value;
     569                    OnPropertyChanged("Action");
     570                }
     571                if(ReExecute != null)
     572                {       ReExecute();    }
    568573            }
    569574        }
     
    577582            {
    578583                setKeyByValue(value);
    579                 if (ReExecute != null) ReExecute();
     584                if (ReExecute != null)
     585                {       ReExecute();    }
    580586            }
    581587        }
     
    589595            {
    590596                setKeyByCharacter(value);
    591                 if (ReExecute != null) ReExecute();
     597                if (ReExecute != null)
     598                        {   ReExecute();    }
    592599            }
    593600        }
     
    601608            set
    602609            {
    603                 if ((UnknownSymbolHandlingMode)value != unknownSymbolHandling) HasChanges = true;
    604                 this.unknownSymbolHandling = (UnknownSymbolHandlingMode)value;
    605                 OnPropertyChanged("UnknownSymbolHandling");
    606 
    607                 if (ReExecute != null) ReExecute();
     610                if((UnknownSymbolHandlingMode)value != unknownSymbolHandling)
     611                {
     612                        HasChanges = true;
     613                        this.unknownSymbolHandling = (UnknownSymbolHandlingMode)value;
     614                    OnPropertyChanged("UnknownSymbolHandling");
     615                                }
     616                if (ReExecute != null)
     617                {       ReExecute();    }
    608618            }
    609619        }
     
    627637              this.alphabet = a;
    628638              setKeyByValue(shiftValue); // reevaluate if the shiftvalue is still within the range
    629               LogMessage("Accepted new alphabet from user: \" + alphabet + "\" (" + alphabet.Length.ToString() + " Symbols)", NotificationLevel.Info);
     639              LogMessage("Accepted new alphabet from user: \"" + alphabet + "\" (" + alphabet.Length.ToString() + " Symbols)", NotificationLevel.Info);
    630640              OnPropertyChanged("AlphabetSymbols");
    631641
    632               if (ReExecute != null) ReExecute();
     642              if (ReExecute != null)
     643              { ReExecute();    }
    633644            }
    634645          }
     
    639650        /// 0 = case-insentive, 1 = case-sensitive
    640651        /// </summary>
    641         //[SettingsFormat(1, "Normal")]
    642652        [PropertySaveOrder(8)]
    643653        [ContextMenu("Alphabet case sensitivity", "Should upper and lower case be treated as the same (so that 'a' = 'A')?", 7, DisplayLevel.Expert, ContextMenuControlType.ComboBox, null, new string[] { "Case insensitive", "Case sensitive" })]
     
    648658            set
    649659            {
    650                 if (value != caseSensitiveAlphabet) HasChanges = true;
     660                if (value != caseSensitiveAlphabet)
     661                {       HasChanges = true;      }
    651662                this.caseSensitiveAlphabet = value;
    652663                if (value == 0)
     
    681692                }
    682693                OnPropertyChanged("AlphabetCase");
    683                 if (ReExecute != null) ReExecute();
     694                if (ReExecute != null)
     695                {       ReExecute();    }
    684696            }
    685697        }
     
    732744\label{sec:AddingAnIconToTheCaesarClass}
    733745
    734 Before we go back to the code of the Caesar class, we have to add an icon to our project, which will be shown in the CrypTool \textbf{ribbon bar} and \textbf{navigation pane}. As there is currently no default, it is mandatory to add an icon. (It is planned to include a default icon in future versions.)
    735 
    736 For testing purposes you can just create a simple black and white PNG image with MS Paint or Paint.NET. The proper image size is 40x40 pixels, but since the image will be rescaled if necessary, any size is technically acceptable.
    737 
    738 Once you have saved your icon, you should add it directly to the project or to a subdirectory. In the project solution, we created a new folder named ``Images''. This can be done by right-clicking on the project item (``Caesar'' in our example) and selecting ``Add $\rightarrow$ New Folder''. The icon can be added to this folder (or to the project directly, or to any other subdirectory) by right-clicking on the folder and selecting ``Add $\rightarrow$ Existing Item''.
     746Before we go back to the code of the Caesar class, we have to add an icon to our project, which will be shown in the CrypTool 2 \textbf{ribbon bar} and \textbf{navigation pane}. As there is currently no default, it is mandatory to add an icon. (It is planned to include a default icon in future versions.)
     747
     748For testing purposes you can just create a simple black and white PNG image with any graphics editing program, such as MS Paint or Paint.NET. The proper image size is 40x40 pixels, but since the image will be rescaled if necessary, any size is technically acceptable.
     749
     750Once you have saved your icon, you should add it directly to the project or to a subdirectory with it. In the project solution, we created a new folder named \textit{Images}. This can be done by right-clicking on the project item (\textit{Caesar} in our example) and selecting \textit{Add $\rightarrow$ New Folder}. The icon can be added to this folder (or to the project directly, or to any other subdirectory) by right-clicking on the folder and selecting \textit{Add $\rightarrow$ Existing Item}.
    739751
    740752\begin{figure}[h!]
     
    746758\clearpage
    747759
    748 A new window will then appear. Select ``Image Files'' as the file type and select your newly-created icon for your plugin.
     760A new window will then appear. Select \textit{Image Files} as the file type and select your newly-created icon for your plugin.
    749761
    750762\begin{figure}[h!]
     
    756768\clearpage
    757769
    758 Finally, we must set the icon as a ``Resource'' to avoid including the icon as a separate file. Right-click on the icon and select ``Properties'' as seen below.
     770Finally, we must set the icon as a \textit{Resource} to avoid including the icon as a separate file. Right-click on the icon and select \textit{Properties} as seen below.
    759771
    760772\begin{figure}[h!]
     
    765777\end{figure}
    766778
    767 In the ``Properties'' panel, set the ``Build Action'' to ``Resource''.
     779In the \textit{Properties} panel, set the \textit{Build Action} to \textit{Resource}.
    768780
    769781\begin{figure}[h!]
     
    778790\label{sec:DefiningTheAttributesOfTheCaesarClass}
    779791
    780 Now let's go back to the code of the Caesar class (the ``Caesar.cs'' file in our example). The first thing we will do is define the attributes of our class. These attributes are used to provide additional information for the CrypTool 2.0 environment. If they are not properly defined, your plugin won't show up in the application display, even if everything else is implemented correctly.
    781 
    782 Attributes are used for \textbf{declarative} programming and provide metadata that can be added to the existing .NET metadata. CrypTool provides a set of custom attributes that are used to mark the different parts of your plugin.
    783 
    784 These attributes can be defined anywhere within the ``Cryptool.Caesar'' namespace, but customarily they are defined right before the class declaration.
     792Now let's go back to the code of the Caesar class (the \textit{Caesar.cs} file in our example). The first thing we will do is define the attributes of our class. These attributes are used to provide additional information for the CrypTool 2 environment. If they are not properly defined, your plugin won't show up in the application user interface, even if everything else is implemented correctly.
     793
     794Attributes are used for declarative programming and provide metadata that can be added to the existing .NET metadata. CrypTool 2 provides a set of custom attributes that are used to mark the different parts of your plugin.
     795
     796These attributes can be defined anywhere within the \textit{Cryptool.Caesar} namespace, but customarily they are defined right before the class declaration.
    785797
    786798\subsection{The \protect\textit{[Author]} attribute}
    787799\label{sec:TheAuthorAttribute}
    788800
    789 The \textit{[Author]} attribute is optional, and thus we are not required to define it. The attribute can be used to provide additional information about the plugin developer. This information will appear in the TaskPane, as for example in Figure \ref{fig:task_pane}. We will define the attribute to demonstrate how it should look in case you want to use it in your plugin.
    790 
    791 \begin{figure}[h!]
    792         \centering
    793                 \includegraphics[width=.90\textwidth]{figures/attribute_author_new.jpg}
     801The \textit{[Author]} attribute is optional, meaning that we are not required to define it. The attribute can be used to provide additional information about the plugin developer (or developers, as the case may be). This information will appear in the TaskPane, as for example in Figure \ref{fig:task_pane}. We will define the attribute to demonstrate how it should look in case you want to use it in your plugin.
     802
     803\begin{figure}[h!]
     804        \centering
     805                \includegraphics[width=.90\textwidth]{figures/attribute_author.jpg}
    794806        \caption{The defintion for the \textit{[Author]} attribute.}
    795807        \label{fig:attribute_author}
     
    799811
    800812\begin{itemize}
    801         \item Author --- the name of the plugin developer(s).
    802         \item Email --- the email address of the plugin developer(s), should they wish to be available for contact.
    803         \item Institute --- the organization, company or university with which the developer(s) are affiliated.
    804         \item URL --- the website of the developer(s) or their institution.
     813        \item \textit{Author} --- the name of the plugin developer.
     814        \item \textit{Email} --- the email address of the plugin developer, should he or she wish to be available for contact.
     815        \item \textit{Institute} --- the organization, company or university with which the developer is affiliated.
     816        \item \textit{URL} --- the website of the developer or of his or her institution.
    805817\end{itemize}
    806818
    807 All of these elements are optional; the developer(s) can choose what information will be published. Unused elements should be set to null or an empty string.
    808 \clearpage
    809 
    810 %Our author attribute should look now as you can see below:
    811 %\begin{figure}[h!]
    812 %       \centering
    813 %               \includegraphics[width=1.00\textwidth]{figures/attribute_author_filled.jpg}
    814 %       \caption{Filled author auttribute}
    815 %       \label{fig:attribute_author_filled}
    816 %\end{figure}
     819All of these elements are optional; the developer can choose what information will be published. Unused elements should be set to \texttt{null} or an empty string.
     820\clearpage
    817821
    818822\subsection{The \protect\textit{[PluginInfo]} attribute}
     
    823827\begin{figure}[h]
    824828        \centering
    825                 \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_new.jpg}
     829                \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo.jpg}
    826830        \caption{The defintion for the \textit{[PluginInfo]} attribute.}
    827831        \label{fig:attribute_plugininfo}
     
    831835
    832836\begin{itemize}
    833         \item Resource File --- defines where to find the associated resource file, if one is to be implemented. These are used, for example, to provide multilingual support for the plugin. This element is optional.
    834         \item Startable --- a flag that should be set to true only if the plugin is an input generator plugin (i.e.\ if your plugin only has outputs and no inputs). In all other cases this should be set to false. This flag is important --- setting it incorrectly will result in unpredictable results. This element is mandatory.
    835         \item Caption --- the name of the plugin or, if the caption is specified in a resource file, the name of the appropriate field in the resource file. This element is mandatory.
    836         \item ToolTip --- a description of the plugin or, if the tool tip is specified in a resource file, the name of the appropriate field in the resource file. This element is optional.
    837         \item DescriptionURL --- defines where to find the description file (e.g.\ XAML file). This element is optional.
    838         \item Icons --- an array of strings to define all the paths for the icons to be used in the plugin (i.e.\ the plugin icon described in Section \ref{sec:AddingAnIconToTheCaesarClass}). This element is mandatory.
     837        \item \textit{Resource File} --- the relative path of the associated resource file (if the plugin makes use of one). These files are used primarily to provide multilingual support for the plugin. This element is optional.
     838        \item \textit{Startable} --- a flag that should be set to \texttt{true} only if the plugin is an input generator (i.e.\ if your plugin only has outputs and no inputs). In all other cases this should be set to \texttt{false}. This flag is important --- setting it incorrectly will result in unpredictable results. This element is mandatory.
     839        \item \textit{Caption} --- the name of the plugin, or, if using a resource file, the name of the field in the file with the caption data. This element is mandatory.
     840        \item \textit{ToolTip} --- a description of the plugin, or, if using a resource file, the name of the field in the resource file with the toolTip data. This element is optional.
     841        \item \textit{DescriptionURL} --- the local path of the description file (e.g.\ XAML file). This element is optional.
     842        \item \textit{Icons} --- an array of strings to define all the paths of the icons used in the plugin (i.e.\ the plugin icon described in Section \ref{sec:AddingAnIconToTheCaesarClass}). This element is mandatory.
    839843\end{itemize}
    840844
    841 \noindent Unused elements should be set to null or an empty string.
     845\noindent Unused elements should be set to \texttt{null} or an empty string.
    842846
    843847(There are a few limitations and bugs that still exist in the \textit{[PluginInfo]} attribute that will be resolved in a future version. Firstly, it is possible to use the plugin without setting a caption, although this is not recommended. In the future the plugin will fail to load without a caption. Secondly, a zero-length toolTip string currently causes the toolTip to appear as an empty box in the application. Lastly, the toolTip and description do not currently support internationalization and localization.)
    844848
    845 In our example, the ``resourceFile'' parameter should be set to ``Cryptool.Caesar.Resource.res''. This file will be used to store the label and caption text to support multilingualism.
    846 
    847 %\begin{figure}[h]
    848 %       \centering
    849 %               \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_resourceFile.JPG}
    850 %       \caption{Attribute PluginInfo element resourceFile}
    851 %       \label{fig:attribute_plugininfo_resourceFile}
    852 %\end{figure}
    853 
    854 The second parameter, ``startable'' should be set to ``false'', because our encryption algorithm is not an input generator plugin.
    855 
    856 %\begin{figure}[h!]
    857 %       \centering
    858 %               \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_startable.jpg}
    859 %       \caption{Attribute PluginInfo startable}
    860 %       \label{fig:attribute_plugininfo_startable}
    861 %\end{figure}
    862 
    863 The next two parameters are necessary to define the plugin's name and description. Since we are using a resource file, we should place here the names of the resource fields that contain the description and caption.  (We call also just write simple text strings instead of using outsourced references.)
    864 
    865 %\begin{figure}[h!]
    866 %       \centering
    867 %               \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_description.jpg}
    868 %       \caption{Attribute PluginInfo name and description}
    869 %       \label{fig:attribute_plugininfo_description}
    870 %\end{figure}
    871 
    872 The next element defines the location path of the description file. The parameter is composed in the format \textit{$<$assembly name$>$/$<$file name$>$} or, if you want to store your description files in a separate folder (as in our case), \textit{$<$assembly name$>$/$<$path$>$/$<$file name$>$}. The description file must be an XAML file. In our case, we shall create a folder named ``DetailedDescription'' in which to store our XAML file with any necessary images. Our folder structure looks as follows:
    873 
    874 \begin{figure}[h!]
    875         \centering
    876                 \includegraphics[width=.30\textwidth]{figures/attribute_plugininfo_detailed_descr_path.jpg}
     849In our example, the \textit{resourceFile} parameter should be set to \textit{Cryptool.Caesar.Resource.res}. This file will be used to store the label and caption text to support multilingualism.
     850
     851The second parameter, \textit{startable}, should be set to \texttt{false}, because our encryption algorithm is not an input generator.
     852
     853The next two parameters are necessary to define the plugin's name and description. Since we are using a resource file, we should place here the names of the resource fields that contain the caption and toolTip. (We could also just write simple text strings instead of using outsourced references.)
     854
     855The \textit{DescriptionURL} element defines the location path of the description file. The parameter is composed in the format \textit{$<$assembly name$>$/$<$file name$>$} or, if you want to store your description files in a separate folder (as in our case), \textit{$<$assembly name$>$/$<$path$>$/$<$file name$>$}. The description file must be an XAML file. In our case, we shall create a folder named \textit{DetailedDescription} in which to store our XAML file with any necessary images. Our folder structure now looks as follows:
     856
     857\begin{figure}[h!]
     858        \centering
     859                \includegraphics[width=.30\textwidth]{figures/detailed_description.jpg}
    877860        \caption{The folder structure as seen in the Solution Explorer.}
    878861        \label{fig:attribute_plugininfo_icon_path}
    879862\end{figure}
    880863
    881 %Accordingly the attribute parameter has to be set to:
    882 %\begin{figure}[h!]
    883 %       \centering
    884 %               \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_detailed_descr.jpg}
    885 %       \caption{Attribute PluginInfo description file}
    886 %       \label{fig:attribute_plugininfo_icon}
    887 %\end{figure}
    888 
    889 Once a detailed description has been written in the XAML file, it can be accessed in the CrypTool 2 application by right-clicking on the plugin icon in the workspace and selecting ``Show description''.
     864Once a detailed description has been written in the XAML file, it can be accessed in the CrypTool~2 application by right-clicking on the plugin icon in the workspace and selecting \textit{Show description}.
    890865
    891866\begin{figure}[h!]
     
    897872\clearpage
    898873
    899 The last parameter tells CrypTool 2 the names of the provided icons. This parameter is an array composed of strings in the format \textit{$<$assembly name$>$/$<$file name$>$} or \textit{$<$assembly name$>$/$<$path$>$/$<$file name$>$}.
    900 
    901 The first and most important icon is the plugin icon, which will be shown in CrypTool 2 in the ribbon bar and navigation pane. Once the icon has been added to the project as described in Section \ref{sec:AddingAnIconToTheCaesarClass}, we must accordingly tell CrypTool 2 where to find the icon. This can be seen above in Figure \ref{fig:attribute_plugininfo}.
    902 
    903 %\begin{figure}[h!]
    904 %       \centering
    905 %               \includegraphics[width=1.00\textwidth]{figures/attribute_plugininfo_icons.jpg}
    906 %       \caption{Attribute PluginInfo icons}
    907 %       \label{fig:attribute_plugininfo_icons}
    908 %\end{figure}
    909 
    910 If your plugin will use additional icons, you should define the paths to each of them by adding the path strings to the \textit{[PluginInfo]} attribute parameter list, each separated by a comma. We have added two further icons for the context menu in the CrypTool 2 workspace. (If you do choose to add more icons, don't forget to add the icons to your solution.)
     874The last parameter tells CrypTool 2 the names of the provided icons. This parameter is an array composed of strings in the format \textit{$<$assembly name$>$/$<$file name$>$} or \textit{$<$assembly name$>$/$<$path$>$/\linebreak $<$file~name$>$}.
     875
     876The first and most important icon is the plugin icon, which will be shown in CrypTool 2 in the ribbon bar and navigation pane. Once the icon has been added to the project as described in Section~\ref{sec:AddingAnIconToTheCaesarClass}, we must accordingly tell CrypTool 2 where to find the icon. This can be seen above in Figure \ref{fig:attribute_plugininfo}.
     877
     878If your plugin will use additional icons, you should define the paths to each of them by adding the path strings to the \textit{[PluginInfo]} attribute parameter list, each separated by a comma. We have added two further icons for the context menu in the CrypTool 2 workspace. (If you choose to add more icons, don't forget to add the icons to your solution.)
    911879
    912880\subsection{The \protect\textit{[EncryptionType]} attribute}
    913881\label{sec:TheEncryptionTypeAttribute}
    914882
    915 The third and last attribute, \textit{[EncryptionType]}, is needed to tell CrypTool 2 what type of plugin we are creating. CrypTool 2 uses this information to place the plugin in the correct group in the navigation pane and ribbon bar. In our example, since Caesar is a classical algorithm, we will define the follows:
     883The third and last attribute, \textit{[EncryptionType]}, is needed to tell CrypTool 2 what type of plugin we are creating. CrypTool 2 uses this information to place the plugin in the correct group in the navigation pane and ribbon bar. In our example, since Caesar is a classical algorithm, we will define the attribute as follows:
    916884
    917885\begin{figure}[h]
    918886        \centering
    919                 \includegraphics[width=.90\textwidth]{figures/attribute_encryptiontype_new.jpg}
    920         \caption{A fully-defined \textit{[EncryptionType]} attribute.}
     887                \includegraphics[width=.90\textwidth]{figures/attribute_encryptiontype.jpg}
     888        \caption{A defined \textit{[EncryptionType]} attribute.}
    921889        \label{fig:attribute_encryption_type}
    922890\end{figure}
     
    925893
    926894\begin{itemize}
    927         \item Asymmetric --- for asymmetrical encryption algorithms, such as RSA.
    928         \item SymmetricBlock --- for block cipher algorithms, such as DES, AES and Twofish.
    929         \item SymmetricStream --- for stream cipher algorithms, such as RC4, Rabbit and SEAL.
    930         \item Hybrid --- for algorithms which are actually a combination of several algorithms, such as algorithms in which the data is encrypted symmetrically and the encryption key asymmetrically.
    931         \item Classic --- for classical encryption or hash algorithms, such as Caesar or MD5.
     895        \item \textit{Asymmetric} --- for asymmetrical encryption algorithms, such as RSA.
     896        \item \textit{SymmetricBlock} --- for block cipher algorithms, such as DES, AES and Twofish.
     897        \item \textit{SymmetricStream} --- for stream cipher algorithms, such as RC4, Rabbit and SEAL.
     898        \item \textit{Hybrid} --- for algorithms which are actually a combination of several algorithms, such as algorithms in which the data is encrypted symmetrically and the encryption key asymmetrically.
     899        \item \textit{Classic} --- for classical encryption or hash algorithms, such as Caesar or MD5.
    932900\end{itemize}
    933901
     
    950918
    951919\ \\ % ugly but functional
    952 If your algorithm works with longs strings of code, it is recommended to use the ``CryptoolStream'' data type. This was designed for input and output between plugins and to handle large amounts of data. To use the native CrypTool stream type, include the namespace ``Cryptool.PluginBase.IO'' with a ``using'' statement as explained in Section \ref{sec:AddingTheNamespacesAndInheritanceSourcesForTheCaesarClass}.
    953 
    954 The following private variables will be used in our example:
     920If your algorithm deals with long strings of code, it is recommended to use the \textit{CryptoolStream} data type. This was designed for input and output between plugins and to handle large amounts of data. To use the native CrypTool stream type, include the namespace \textit{Cryptool.PluginBase.IO} with a \texttt{using} statement as explained in Section \ref{sec:AddingTheNamespacesAndInheritanceSourcesForTheCaesarClass}.
     921
     922Our example makes use of the following private variables:
    955923
    956924\begin{itemize}
    957         \item CaesarSettings settings --- required to implement the IPlugin interface properly.
    958         \item string inputString --- string from which to read the input data.
    959         \item string outputString --- string to which to save the output data.
    960         \item enum CaesarMode --- used to select either encryption or decryption.
    961         \item List$<$CryptoolStream$>$ listCryptoolStreamsOut --- a list of all streams created by the plugin, which helps to perform a clean dispose.
     925        \item \texttt{CaesarSettings settings} --- required to implement the IPlugin interface properly.
     926        \item \texttt{string inputString} --- string from which to read the input data.
     927        \item \texttt{string outputString} --- string to which to save the output data.
     928        \item \texttt{enum CaesarMode} --- used to select either encryption or decryption.
     929        \item \texttt{List$<$CryptoolStream$>$ listCryptoolStreamsOut} --- a list of all streams created by the plugin, which helps to perform a clean dispose.
    962930\end{itemize}
    963931
     
    965933\label{sec:ImplementingTheInterfacesInTheCaesarClass}
    966934
     935\subsection{Connecting the settings class}
     936\label{sec:ConnectingTheSettingsClass}
     937
    967938The next major step is to write out our implementations of the interfaces. First we will add a constructor to our class. We will use this to create an instance of our settings class and a function to handle events:
    968939
    969940\begin{lstlisting}
    970 public class Caesar : IEncryption
    971 {
    972         #region Private variables
    973         private CaesarSettings settings;
    974         private string inputString;
    975         private string outputString;
    976         private enum CaesarMode { encrypt, decrypt };
    977         private List<CryptoolStream> listCryptoolStreamsOut = new List<CryptoolStream>();
    978         #endregion
    979        
    980         public Caesar()
    981         {
    982                 this.settings = new CaesarSettings();
    983                 this.settings.LogMessage += Caesar_LogMessage;
    984         }
     941public Caesar()
     942{
     943        this.settings = new CaesarSettings();
     944        this.settings.LogMessage += GuiLogMessage;
     945}
    985946\end{lstlisting}
    986947
    987948\ \\
    988 \indent Secondly, we must implement the ``Settings'' property declared in the interface. An outline of this property should have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}); just edit it appropriately to communicate with your settings class as we have done here:
     949\indent Secondly, we must implement the \textit{Settings} property declared in the interface. An outline of this property should have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}); just edit it appropriately to communicate with your settings class as we have done here:
    989950
    990951\begin{lstlisting}
     
    995956}
    996957\end{lstlisting}
    997 
    998 \ \\
    999 \indent Thirdly, we must define five properties, each with an appropriate attribute. This step is necessary to tell CrypTool 2 if the properties are used for input our output and to provide the plugin with external data.
     958\clearpage
     959
     960\subsection{The input/output attributes}
     961\label{sec:TheInputOutputAttributes}
     962
     963%\ \\
     964\indent Next we will define five properties, each with an appropriate attribute, to be used for input and output. Th attributes are necessary to tell CrypTool 2 whether the properties are used for input or output and to provide the plugin with external data.
    1000965
    1001966The attribute that we will use for each proprerty is called \textit{[PropertyInfo]} and it consists of the following elements:
    1002967
    1003968\begin{itemize}
    1004         \item direction --- defines whether this property is an input or output property, e.g.\ whether it reads input data or writes output data. The possible values are:
     969        \item \textit{direction} --- defines whether this property is an input or output property, e.g.\ whether it reads input data or writes output data. The possible values are:
    1005970        \begin{itemize}
    1006                 \item Direction.Input
    1007                 \item Direction.Output
     971                \item \texttt{Direction.Input}
     972                \item \texttt{Direction.Output}
    1008973        \end{itemize}
    1009         \item caption --- the caption for the property displayed over the input of the icon after it has been placed in the editor), as seen below:
     974        \item \textit{caption} --- the caption for the property displayed over the input or output arrow of the icon after it has been placed in the editor; ``Input stream'' in the example below:
    1010975       
    1011 \begin{figure}[h]
     976\begin{figure}[h!]
    1012977        \centering
    1013978                \includegraphics[width=.55\textwidth]{figures/property_caption.jpg}
     
    1016981\end{figure}
    1017982
    1018         \item toolTip --- the toolTip for the property displayed over the input arrow of the icon after it has been placed in the editor, as seen above.
    1019         \item descriptionUrl --- currently not used; fill it with null or an empty string.
    1020         \item mandatory --- this flag determines whether an input must be attached by the user to use the plugin. If set to true, an input connection will be required or else the plugin will not be executed in the workflow chain. If set to false, connecting an input is optional. As this only applies to input properties, if the direction has been set to ``output'', this flag will be ignored.
    1021         \item hasDefaultValue --- if this flag is set to true, CrypTool 2 will assume that the property has a default input value that does not require user input.
    1022         \item displayLevel --- determines in which display levels your property will be shown in CrypTool 2. These are used to hide more advanced item from less-experienced users; a beginner using the corresponding display level will not see the properties marked as any other level, but a professional using the appropriate display level will have access to everything. These levels are as follows:
     983        \item \textit{toolTip} --- the toolTip for the property displayed over the input or output arrow of the icon after it has been placed in the editor; ``Input data to be hashed'' in the example above.
     984        \item \textit{descriptionUrl} --- currently not used; fill it with \texttt{null} or an empty string.
     985        \item \textit{mandatory} --- this flag determines whether an input must be attached by the user to use the plugin. If set to \texttt{true}, an input connection will be required or else the plugin will not be executed in the workflow chain. If set to \texttt{false}, connecting an input is optional. As this only applies to input properties, if the direction has been set to \texttt{Direction.Output}, this flag will be ignored.
     986        \item \textit{hasDefaultValue} --- if this flag is set to \texttt{true}, CrypTool 2 will assume that the property has a default input value that does not require user input.
     987        \item \textit{displayLevel} --- determines in which display levels your property will be shown in CrypTool~2. These are used to hide more advanced item from less-experienced users; a beginner using the corresponding display level will not see the properties marked as any other level, but a professional using the appropriate display level will have access to everything. These levels are as follows:
    1023988       
    1024989        \begin{itemize}
    1025                 \item DisplayLevel.Beginner
    1026                 \item DisplayLevel.Experienced
    1027                 \item DisplayLevel.Expert
    1028                 \item DisplayLevel.Professional
     990                \item \texttt{DisplayLevel.Beginner}
     991                \item \texttt{DisplayLevel.Experienced}
     992                \item \texttt{DisplayLevel.Expert}
     993                \item \texttt{DisplayLevel.Professional}
    1029994        \end{itemize}
    1030995\clearpage
    1031996       
    1032         \item quickWatchFormat --- determines how the content of the property will be shown in the quickwatch perspective. CrypTool accepts the following quickwatch formats:
     997        \item \textit{quickWatchFormat} --- determines how the content of the property will be shown in the quickwatch perspective. CrypTool 2 accepts the following quickwatch formats:
    1033998       
    1034999        \begin{itemize}
    1035                 \item QuickWatchFormat.Base64
    1036                 \item QuickWatchFormat.Hex
    1037                 \item QuickWatchFormat.None
    1038                 \item QuickWatchFormat.Text
     1000                \item \texttt{QuickWatchFormat.Base64}
     1001                \item \texttt{QuickWatchFormat.Hex}
     1002                \item \texttt{QuickWatchFormat.None}
     1003                \item \texttt{QuickWatchFormat.Text}
    10391004        \end{itemize}
    10401005
     
    10461011\end{figure}
    10471012       
    1048         \item quickWatchConversionMethod --- this is used to indicate a conversion method; most plugins do not ned to convert their data and thus should use a null value here. The quickwatch function uses the ``default'' system encoding to display data, so if your data is in another other format, such as Unicode or UTF-8, you should provide here the name of a conversion method as string. The method header for such a method should look something like the following:
     1013        \item \textit{quickWatchConversionMethod} --- this is used to indicate a conversion method; most plugins do not ned to convert their data and thus should use a \texttt{null} value here. The quickwatch function uses the default system encoding to display data, so if your data is in another format, such as UTF-16 or Windows-1250, you should provide here the name of a conversion method as string. The header for such a method should look something like the following:
    10491014
    10501015\begin{lstlisting}
     
    10541019\end{itemize}
    10551020
    1056 The first of the five properties that we will define is ``InputString''. This is used to provide our plugin with the data to be encrypted or decrypted:
     1021\subsection{Defining the input/output properties}
     1022\label{sec:DefiningTheInputOutputProperties}
     1023
     1024The first of the five properties that we will define is \textit{InputString}. This is used to provide our plugin with the data to be encrypted or decrypted:
    10571025
    10581026\begin{lstlisting}
     
    10721040\end{lstlisting}
    10731041
    1074 In the get method we simply return the value of the input data. The set method checks if the input value has changed, and, if so, sets the new input data and announces the change to the CrypTool 2 environment by calling the function ``OnPropertyChanged(\textit{$<$Property name$>$})''. This step is necessary for input properties to update the quickwatch view.
     1042\ \\
     1043In the get method we simply return the value of the input data. The set method checks if the input value has changed, and, if so, sets the new input data and announces the change to the CrypTool 2 environment by calling the function \textit{OnPropertyChanged(\textit{$<$Property name$>$})}. This step is necessary for input properties to update the quickwatch view.
    10751044\clearpage
    10761045
     
    10941063
    10951064\ \\
    1096 \indent CrypTool 2 does not require implementing output set methods, as they will never be called from outside the plugin. Nevertheless, in our example the plugin accesses the property itself, and therefore we have chosen to implement the set method.
    1097 
    1098 You can provide additional output data types if you so desire. In our example, we will also offer output data of type CryptoolStream, input data for external alphabets, and input data for the shift value of our Caesar algorithm. Note that for the first of these, the set method is not implemented since it will never be called. We shall define these properties as follows:
    1099 
    1100 \begin{lstlisting}
    1101 [PropertyInfo(Direction.OutputData, "propStreamOutputToolTip", "propStreamOutputDescription", "", false, false, DisplayLevel.Beginner, QuickWatchFormat.Text, null)]
     1065\indent CrypTool 2 does not require implementing set methods for output properties, as they will never be called from outside the plugin. Nevertheless, in our example the plugin itself accesses the property, and therefore we have chosen to implement the set method.
     1066
     1067You can provide additional output data types if you so desire. In our example, we will also offer output data of type \textit{CryptoolStream}, input data for external alphabets, and input data for the shift value of our Caesar algorithm. Note that for the first of these, the set method is not implemented since it will never be called. We shall define these properties as follows:
     1068
     1069\begin{lstlisting}
     1070[PropertyInfo(Direction.OutputData, "CryptoolStream output", "The raw CryptoolStream data after processing with the Caesar cipher", "", false, false, DisplayLevel.Beginner, QuickWatchFormat.Text, null)]
    11021071public CryptoolStream OutputData
    11031072{
     
    11281097                {
    11291098                        ((CaesarSettings)this.settings).AlphabetSymbols = value;
    1130                         OnPropertyChanged(''InputAlphabet'');
     1099                        OnPropertyChanged("InputAlphabet");
    11311100                }
    11321101        }
     
    11471116\end{lstlisting}
    11481117
    1149 \ \\
    1150 \indent The CrypTool 2 API provides two methods to send messages from the plugin to the CrypTool 2 core: ``GuiLogMessage'' (used to send messages to the CrypTool 2 status bar) and ``OnPropertyChanged'' (used to inform the core of changes to the plugin data). The ``GuiLogMessage'' method is a nice mechanism to inform the user as to what your plugin is currently doing.
     1118
     1119\subsection{Sending messages to the CrypTool 2 core}
     1120\label{sec:SendingMessagesToTheCrypTool2Core}
     1121
     1122The CrypTool 2 API provides two methods to send messages from the plugin to the CrypTool 2 core: \textit{GuiLogMessage} (used to send messages to the CrypTool 2 status bar) and \textit{OnPropertyChanged} (used to inform the core of changes to the plugin data). The \textit{GuiLogMessage} method is a nice mechanism to inform the user as to what your plugin is currently doing.
    11511123
    11521124\begin{figure}[h]
     
    11581130\clearpage
    11591131
    1160 The method takes two parameters:
     1132The \textit{GuiLogMessage} method takes two parameters:
    11611133
    11621134\begin{itemize}
    1163         \item Message --- the text (of type string) to be shown in the status bar.
    1164         \item NotificationLevel --- the type of message, that is, its alert level:
     1135        \item \textit{Message} --- the text to be shown in the status bar.
     1136        \item \textit{NotificationLevel} --- the type of message, that is, its alert level:
    11651137        \begin{itemize}
    1166                 \item NotificationLevel.Error
    1167                 \item NotificationLevel.Warning
    1168                 \item NotificationLevel.Info
    1169                 \item NotificationLevel.Debug
     1138                \item \texttt{NotificationLevel.Error}
     1139                \item \texttt{NotificationLevel.Warning}
     1140                \item \texttt{NotificationLevel.Info}
     1141                \item \texttt{NotificationLevel.Debug}
    11701142        \end{itemize}
    11711143\end{itemize}
    11721144
    1173 Outlines of both of the related events will have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}), but we must define appropriate methods as follows:
     1145Both of these notification methods also have associated events. Outlines of both related events will have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}), but we must define the appropriate methods as follows:
    11741146
    11751147\begin{lstlisting}
    11761148public event GuiLogNotificationEventHandler OnGuiLogNotificationOccured;
     1149
    11771150private void GuiLogMessage(string message, NotificationLevel logLevel)
    11781151{
     
    11891162
    11901163\ \\
    1191 \indent Note that to use ``PropertyChangedEventHandler'' you must include the namespace ``System.\linebreak ComponentModel''. Our collection of included namespaces should now look as follows:
    1192 
    1193 \begin{lstlisting}
     1164\indent Note that to use \textit{PropertyChangedEventHandler} you must include the namespace \textit{System.\linebreak ComponentModel}. Our collection of included namespaces should now look as follows:
     1165
     1166\begin{lstlisting}
     1167using System;
    11941168using System.Collections.Generic;
     1169using System.ComponentModel;
    11951170using System.Text;
    1196 using System.ComponentModel;
    1197 using System.Windows.Controls;
    11981171
    11991172using Cryptool.PluginBase;
     
    12071180\label{sec:CompletingTheAlgorithmicCodeOfTheCaesarClass}
    12081181
    1209 At this point, the plugin should be ready to be read by and shown correctly in the CrypTool 2 application. However, we haven't actually implemented the algorithm yet. This should be done in the ``Execute()'' function, as this is what CrypTool 2 will always call first. The actual functionality of your algorithm, as well as the structure thereof, is up to you. Note that an outline of the ``Execute()'' function will have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}).
    1210 
    1211 We have chosen to split our algorithm's encryption and decryption into two separate functions, which will both ultimately call the ``ProcessCaesar()'' function. Below is our implementation of the Execute() function:
     1182At this point, the plugin should be ready to be read by and shown correctly in the CrypTool 2 application. However, we haven't actually implemented the algorithm yet; we have just implemented interfaces and constructed a thorough set of properties. Algorithmic processing should be done in the \textit{Execute()} function, as this is what CrypTool 2 will always call first. The actual functionality of your algorithm, as well as the structure thereof, is up to you. Note that an outline of the \textit{Execute()} function will have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}).
     1183
     1184We have chosen to split our algorithm's encryption and decryption processes into two separate functions, which will both ultimately call the \textit{ProcessCaesar()} function. Below is our implementation of the Caesar algothmic processing and the \textit{Execute()} function:
    12121185
    12131186\begin{lstlisting}
     
    12181191        string alphabet = cfg.AlphabetSymbols;
    12191192
    1220         // In case we are working in case-insensitive mode, we will use
    1221         // only capital letters, hence we must transform the whole alphabet
     1193        // If we are working in case-insensitive mode, we will use only
     1194        // capital letters, hence we must transform the whole alphabet
    12221195        // to uppercase.
    12231196        if (!cfg.CaseSensitiveAlphabet)
     
    13221295        {
    13231296                case 0:
    1324                         Caesar_LogMessage("Encrypting", NotificationLevel.Debug);
     1297                        GuiLogMessage("Encrypting", NotificationLevel.Debug);
    13251298                        Encrypt();
    13261299                        break;
    13271300                case 1:
    1328                         Caesar_LogMessage("Decrypting", NotificationLevel.Debug);
     1301                        GuiLogMessage("Decrypting", NotificationLevel.Debug);
    13291302                        Decrypt();
    13301303                        break;
     
    13351308\end{lstlisting}
    13361309
    1337 It is important to make sure that all changes to the output properties will be announced to the CrypTool 2 environment. In our example this happens by calling the set method of OutputData, which in turn calls ``OnPropertyChanged'' for both output properties ``OutputData'' and ``OutputDataStream''. Instead of calling the property's set method you can instead call ``OnPropertyChanged'' directly within the ``Execute()'' method.\clearpage
    1338 
    1339 You have probably noticed that the ``ProgressChanged'' method is undefined. This can be used to show the current algorithm process as a progress bar in the plugin icon. To use this method and compile successfully, you must declare this method, as we have done for our example below:
     1310\ \\
     1311It is important to make sure that all changes to the output properties will be announced to the CrypTool 2 environment. In our example this happens by calling the set method of \textit{OutputData}, which in turn calls \textit{OnPropertyChanged} to indicate that both output properties \textit{OutputData} and \textit{OutputDataStream} have changed. Instead of calling the property's set method you could instead call \textit{OnPropertyChanged} directly within the \textit{Execute()} method.
     1312\clearpage
     1313
     1314You may have noticed that the \textit{ProgressChanged} method is undefined. This method can be used to show the current algorithm process as a progress bar in the plugin icon. To use this method and compile successfully, you must declare this method, which we have done for our example below. Note that the \textit{OnPluginProgressChanged} event will have been automatically generated by implementing the interface (see Section \ref{sec:AddingInterfaceFunctionsToTheCaesarClass}).
    13401315
    13411316\begin{lstlisting}
    13421317public event PluginProgressChangedEventHandler OnPluginProgressChanged;
     1318
    13431319private void ProgressChanged(double value, double max)
    13441320{
     
    13551331public void Dispose()
    13561332{
    1357         foreach(CryptoolStream stream in listCryptoolStreamOut)
     1333        foreach(CryptoolStream stream in listCryptoolStreamsOut)
    13581334        {
    13591335                stream.Close();
    13601336        }
    1361         listCryptoolStreamOut.Clear();
     1337        listCryptoolStreamsOut.Clear();
    13621338}
    13631339
     
    13771353\label{sec:FinishingTheImplementation}
    13781354
    1379 When adding plugin instances to the CrypTool 2 workspace, the application core checks whether the plugin runs without any exceptions. If any method inherited from IPlugin throws an exception, CrypTool 2 will display an error message and prohibit use of the plugin. Therefore, we must remove the ``NotImplementedException'' from the automatically generated methods ``Initialize()'', ``Pause()'' and ``Stop()''. In our example it will be sufficient to provide empty implementations.
     1355When adding plugin instances to the CrypTool 2 workspace, the application core checks whether the plugin runs without any exceptions. If any method inherited from IPlugin throws an exception, CrypTool 2 will display an error message and prohibit use of the plugin. Therefore, we must remove the \textit{NotImplementedException} from the automatically generated methods \textit{Initialize()}, \textit{Pause()} and \textit{Stop()}. In our example it will be sufficient to provide empty implementations:
    13801356
    13811357\begin{lstlisting}
     
    13931369\end{lstlisting}
    13941370
    1395 The methods ``Presentation()'' and ``QuickWatchPresentation()'' can be used to provide a specialized visualization of the plugin algorithm to be shown in CrypTool. Take a look at the ``PRESENT'' plugin to see how a custom visualization can be realized. For our Caesar example, we have chosen not to implement a custom visualization. Therefore we will simply return ``null'':
     1371\ \\
     1372The methods \textit{Presentation()} and \textit{QuickWatchPresentation()} can be used to provide a specialized visualization of the plugin algorithm to be shown in CrypTool 2. Take a look at the \textit{PRESENT} plugin to see how a custom visualization can be realized. For our Caesar example, we have chosen not to implement a custom visualization. Therefore we will simply return \texttt{null}:
    13961373
    13971374\begin{lstlisting}
     
    14071384\end{lstlisting}
    14081385
     1386\ \\
    14091387Your plugin should compile without errors at this point.
    14101388\clearpage
     
    14131391\label{sec:ImportingAndTestingThePlugin}
    14141392
    1415 After you have built the plugin, you need to move the newly created plugin DLL to a location where CrypTool 2 can find it. There are a few different ways to accomplish this. You can find the DLL file in \textit{\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug}.
     1393After you have built the plugin, you need to move the newly created plugin DLL to a location where CrypTool 2 can find it. There are a few different ways to accomplish this. First, though, you need to locate the DLL. Once you have successfully compiled the plugin, the DLL should be in \textit{\mbox{\textbackslash CrypPluginBase\textbackslash }bin\textbackslash Debug}.
    14161394
    14171395\subsection{Global storage}
    14181396\label{sec:GlobalStorage}
    14191397
    1420 The first option is to copy your plugin's DLL file to the ``CrypPlugins'' folder in which the CrypTool 2 executable (``CrypWin.exe'') can be found. %If necessary, create the folder ''CrypPlugins''.
     1398The first option is to copy your plugin's DLL file to the \textit{CrypPlugins} folder in which the CrypTool 2 executable (\textit{CrypWin.exe}) can be found.
    14211399
    14221400\begin{figure}[h]
     
    14401418\label{sec:CustomStorage}
    14411419
    1442 The second possibility is to copy your plugin's DLL file to the ``CrypPlugins'' folder located in the ``Application Data'' folder in your home folder. In Windows XP, the home folder path should be as follows: \textit{C:\textbackslash Documents and Settings\textbackslash $<$user name$>$\textbackslash Application Data\textbackslash CrypPlugins}, and in Vista and Windows 7 the path should look like: \textit{C:\textbackslash Users\textbackslash $<$user name$>$\textbackslash Application Data\textbackslash CrypPlugins}. This home folder path is called ``custom storage'' in the CrypTool architecture. Changes in this folder will only take effect for current user. After copying the file, you must restart CrypTool 2.
     1420The second possibility is to copy your plugin's DLL file to the \textit{CrypPlugins} folder located in the \textit{Application Data} folder in your home folder. In Windows XP, the home folder path should be as follows: \textit{C:\textbackslash Documents and Settings\textbackslash $<$user name$>$\textbackslash Application Data\textbackslash CrypPlugins}, and in Vista and Windows 7 the path should look like: \textit{C:\textbackslash Users\textbackslash $<$user name$>$\textbackslash Application Data\textbackslash CrypPlugins}. This home folder path is called ``custom storage'' in the CrypTool architecture. Changes in this folder will only take effect for current user. After copying the file, you must restart CrypTool 2.
    14431421\clearpage
    14441422
     
    14531431\label{sec:ImportingDirectly}
    14541432
    1455 Alternatively, you can import new plugins directly from the CrypTool 2 interface. Just run \mbox{CrypWin.exe} and select the ``Download Plugins'' button. An ``Open File Dialog'' window will open and ask where the new plugin is located. After selecting the new plugin, CrypTool 2 will automatically import the plugin to the custom storage folder. With this option you will not have to restart the program. All corresponding menu entries will be updated automatically. Note that this import function only accepts \textbf{signed} plugins, and also that this option is just a temporary solution: in the future this will be done online by a web service.
     1433Alternatively, you can import new plugins directly from the CrypTool 2 interface. Just run \mbox{CrypWin.exe} and select the \textit{Download Plugins} button. An \textit{Open File Dialog} window will open and ask where the new plugin is located. After selecting the new plugin, CrypTool 2 will automatically import the plugin to the custom storage folder. With this option you will not have to restart the program. All corresponding menu entries will be updated automatically. Note that this import function only accepts \textbf{signed} plugins, and also that this option is just a temporary solution: in the future this will be done online by a web service.
    14561434\clearpage
    14571435
     
    14591437\label{sec:UsingBuildSettings}
    14601438
    1461 Yet another option is to use the build settings in your plugin's project properties to copy the DLL automatically after building it in Visual Studio. To set this up, right-click on your plugin project and select ``Properties'':
     1439Yet another option is to use the build settings in your plugin's project properties to copy the DLL automatically after building it in Visual Studio. To set this up, right-click on your plugin project and select \textit{Properties}:
    14621440
    14631441\begin{figure}[h]
     
    14691447\clearpage
    14701448
    1471 \noindent Then select ``Build Events'':
     1449\noindent Then select \textit{Build Events}:
    14721450
    14731451\begin{figure}[h]
     
    14781456\end{figure}
    14791457
    1480 \noindent And finally, enter the following text into ``Post-build event command line'':\\\\
     1458\noindent And finally, enter the following text into the \textit{Post-build event command line} field:\\\\
    14811459cd "\$(ProjectDir)" \\
    1482 cd ..\textbackslash ..\textbackslash CrypWin\$(OutDir)\\
    1483 if not exist "./CrypPlugins" mkdir "./CrypPlugins"\\
    1484 del /F /S /Q /s /q "\fcolorbox{yellow}{yellow}{Caesar}*.*"\\
    1485 copy "\$(TargetDir)\fcolorbox{yellow}{yellow}{Caesar}*.*" "./CrypPlugins"\\\\
    1486 You will need to change the marked fields to your particular plugin's name.
     1460cd ..\textbackslash ..\textbackslash CrypWin\textbackslash bin\textbackslash Debug\\
     1461if not exist ".\textbackslash CrypPlugins" mkdir ".\textbackslash CrypPlugins"\\
     1462del /F /S /Q /s /q "\colorbox{yellow}{Caesar}*.*"\\
     1463copy "\$(TargetDir)\colorbox{yellow}{Caesar}*.*" ".\textbackslash CrypPlugins"\\\\
     1464You will need to change the highlighted fields to your particular plugin's name.
     1465\clearpage
     1466
     1467\section{Drawing the workflow of your plugin}
     1468\label{DrawingTheWorkfloweOfYourPlugin}
     1469
     1470Each plugin should have an associated workflow file to show the algorithm in action in CrypTool 2. Such a file can be automatically created by simply saving a CrypTool 2 workspace project featuring your plugin. Below is a possible workflow for our Caesar example:
     1471
     1472\begin{figure}[h]
     1473        \centering
     1474                \includegraphics{figures/sample.jpg}
     1475        \caption{A sample workflow diagram for the Caesar algorithm.}
     1476        \label{fig:sample}
     1477\end{figure}
    14871478
    14881479\section{Downloading the example and template}
    14891480\label{sec:DownloadingTheExampleAndTemplate}
    14901481
    1491 If you didn't download the entire CrypTool 2 source code as described in Section \ref{TheCrypTool2SVNURL}, but you want a copy of the source code for the Caesar algorithm that was used as an example in this guide, you can download it as a Visual Studio \textbf{solution} from the following location:\\\\
     1482If you chose not to download the entire CrypTool 2 source code as described in Section \ref{CheckingOutTheSources}, but you want a copy of the source code for the Caesar algorithm that was used as an example in this guide, you can download it as a Visual Studio solution from the following location:\\\\
    14921483\textit{username: anonymous\\
    14931484password:} (not required)\\
    14941485\url{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
    1495 We have also created a Visual Studio plugin template to help with the development of new plugins. This can be found here:\\\\
     1486We have also created a Visual Studio plugin \textbf{template} to help with the development of new plugins. This can be found here:\\\\
    14961487\url{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
    1497 \clearpage
    1498 
    1499 \section{Drawing the workflow of your plugin}
    1500 \label{DrawingTheWorkfloweOfYourPlugin}
    1501 
    1502 Each plugin should have an associated workflow file to show the algorithm in action in CrypTool 2. Such a file can be automatically created by simply saving a CrypTool 2 workspace project featuring your plugin. Below is a possible workflow for our Caesar example:
    1503 
    1504 \begin{figure}[h]
    1505         \centering
    1506                 \includegraphics{figures/sample.jpg}
    1507         \caption{A sample workflow diagram for the Caesar algorithm.}
    1508         \label{fig:sample}
    1509 \end{figure}
Note: See TracChangeset for help on using the changeset viewer.