Changeset 1541


Ignore:
Timestamp:
May 31, 2010, 4:03:30 PM (12 years ago)
Author:
Patrick Vacek
Message:

HowTo: Lots of little fixes:

  • Fixed link to plugin template
  • CT watermark now only appears on cover page.
  • Resource and XAML files somewhat better explained. That topic will have to be looked into further when that functionality changes.
  • "region" and "endregion" now appear blue in the code listing, but the # doesn't, and "in" still does in the one special case where it shouldn't.
  • Custom storage and Direct Import removed from PDF (but remain commented out in LaTeX document in case they return in the future)
  • The post-build event command highlighting issue is resolved.
  • Workflow files are more clearly explained.
Location:
trunk/Documentation/Developer/PluginHowTo
Files:
3 edited

Legend:

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

    r1325 r1541  
    1717\usepackage{textcomp}
    1818\usepackage[T1]{fontenc}
    19 
     19\usepackage{color,soul}
    2020
    2121%\usepackage[automark]{scrpage2}
    2222%\usepackage[absolute]{textpos}
     23
    2324
    2425\lstset{language=[Sharp]C, % base language is C and dialect is Sharp (C#)
     
    4041% emph={double,bool,int,unsigned,char,true,false,void},emphstyle=\color{blue},
    4142emph={Assert,Test}, emphstyle=\color{BrickRed},
    42 emph={[2]double,bool,int,unsigned,char,true,false,void,using,\#define,\#ifdef,\#endif,\#region,\#endregion},
     43emph={[2]double,bool,int,unsigned,char,true,false,void,using,\# ,region,endregion},
    4344emphstyle={[2]\color{blue}}
    4445}
     
    127128
    128129% Metadata and configuration of the pdf output:
    129 % Do not forget to enter the correct title, author, subject und keywords
     130% Do not forget to enter the correct title, author, subject, and keywords
    130131
    131132% For screen viewing it is nice to have references marked in a slightly different
     
    159160\newcommand{\todo}[1]{\marginpar{\textcolor{red}{ToDo:} #1}}
    160161
    161 
     162% Only prints on title page:
     163\AddToShipoutPicture*{\WaterMarkPic}
    162164
    163165%\AtBeginDocument{\markboth{\@author}{\@title}}
     
    188190    \listoffigures
    189191
    190     \AddToShipoutPicture{\WaterMarkPic}
     192%    \AddToShipoutPicture{\WaterMarkPic}
    191193
    192194        \include{part1}
  • trunk/Documentation/Developer/PluginHowTo/part2.tex

    r1325 r1541  
    1010password:} (not required)\\
    1111\url{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
    12 We have also created a Visual Studio plugin \textbf{template} to help with the development of new plugins. Using this template is strongly recommended over copying and pasting code from this document! The template can be found here:\\\\
    13 \url{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
     12We have also created a Visual Studio plugin \textbf{template} to help with the development of new plugins. Using this template is strongly recommended over copying and pasting code from this document! The template and a short readme can be found here:\\\\
     13\url{http://cryptool2.vs.uni-due.de/index.php?page=33&lm=3}
     14\clearpage
    1415
    1516\section{Creating a new project}
     
    825826\label{sec:ThePluginInfoAttribute}
    826827
    827 The second attribute, \textit{[PluginInfo]}, provides necessary information about the plugin, and is therefore mandatory. This information appears in the caption and tool tip window. The attribute is defined as follows:
     828The second attribute, \textit{[PluginInfo]}, provides necessary information about the plugin, and is therefore mandatory. The information defined in this attribute appears in the caption and tool tip window. The attribute is defined as follows:
    828829
    829830\begin{figure}[h]
     
    837838
    838839\begin{itemize}
    839         \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.
     840        \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, although this is currently a work in progress. This element is optional.
    840841        \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.
    841842        \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.
     
    847848\noindent Unused elements should be set to \texttt{null} or an empty string.
    848849
    849 (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.)
     850There are a few limitations and bugs that still exist in the \textit{[PluginInfo]} attribute that will be resolved in a future version. First, it is possible to use the plugin without setting a caption, although this is not recommended, and future versions of the plugin will fail to load without a caption. Second, a zero-length toolTip string currently causes the toolTip to appear as an empty box in the application. Third, the toolTip and description do not currently support internationalization and localization. Since the precise formulation and functionality of this attribute is still being developed, it is recommended to view other plugins for examples.
    850851
    851852In 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.
     
    11221123\label{sec:SendingMessagesToTheCrypTool2Core}
    11231124
    1124 The 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.
     1125The CrypTool 2 API provides two methods to send messages from the plugin to the CrypTool 2 core. \textit{GuiLogMessage} is used to send messages to the CrypTool 2 status bar. This method is a nice mechanism to inform the user as to what your plugin is currently doing. \textit{OnPropertyChanged} is used to inform the core application of changes to any plugin properties and data. This may not affect the user interface, but is important to keep the core appraised of the plugin's current state.
    11251126
    11261127\begin{figure}[h]
     
    13931394\label{sec:ImportingAndTestingThePlugin}
    13941395
    1395 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. 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}.
    1396 
    1397 \subsection{Global storage}
    1398 \label{sec:GlobalStorage}
    1399 
    1400 The 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.
    1401 
    1402 \begin{figure}[h]
    1403         \centering
    1404                 \includegraphics{figures/copy_dll_global_storage.jpg}
    1405         \caption{Copying the plugin to the global storage folder}
    1406         \label{fig:copy_dll_global_storage}
    1407 \end{figure}
    1408 
    1409 This folder is known as ``global storage'' in the CrypTool 2 architecture. Changes in this folder will affect all users on a multi-user Windows platform. You should now restart CrypTool 2.
    1410 \clearpage
    1411 
    1412 \begin{figure}[h]
    1413         \centering
    1414                 \includegraphics{figures/global_storage.jpg}
    1415         \caption{Inside the CrypPlugins folder (the global storage).}
    1416         \label{fig:global_storage}
    1417 \end{figure}
     1396After 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 currently a couple 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}.
     1397
     1398% Global Storage does not currently function - but presumably will be brought back in at another time.
     1399
     1400%\subsection{Global storage}
     1401%\label{sec:GlobalStorage}
     1402
     1403%The 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.
     1404
     1405%\begin{figure}[h]
     1406%       \centering
     1407%               \includegraphics{figures/copy_dll_global_storage.jpg}
     1408%       \caption{Copying the plugin to the global storage folder}
     1409%       \label{fig:copy_dll_global_storage}
     1410%\end{figure}
     1411
     1412%This folder is known as ``global storage'' in the CrypTool 2 architecture. Changes in this folder will affect %all users on a multi-user Windows platform. You should now restart CrypTool 2.
     1413%\clearpage
     1414
     1415%\begin{figure}[h]
     1416%       \centering
     1417%               \includegraphics{figures/global_storage.jpg}
     1418%       \caption{Inside the CrypPlugins folder (the global storage).}
     1419%       \label{fig:global_storage}
     1420%\end{figure}
    14181421
    14191422\subsection{Custom storage}
    14201423\label{sec:CustomStorage}
    14211424
    1422 The 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.
    1423 \clearpage
     1425The first 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.
    14241426
    14251427\begin{figure}[h]
     
    14291431        \label{fig:custom_storage}
    14301432\end{figure}
    1431 
    1432 \subsection{Importing directly}
    1433 \label{sec:ImportingDirectly}
    1434 
    1435 Alternatively, 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.
    1436 \clearpage
     1433\clearpage
     1434
     1435% Direct import is currently not supported - but presumably it will return again in some form.
     1436
     1437%\subsection{Importing directly}
     1438%\label{sec:ImportingDirectly}
     1439
     1440%Another option is to 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 option is just a temporary solution: in the future this will be done online by a web service.
     1441%\clearpage
    14371442
    14381443\subsection{Using build settings}
    14391444\label{sec:UsingBuildSettings}
    14401445
    1441 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 \textit{Properties}:
     1446Alternatively, you can 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}:
    14421447
    14431448\begin{figure}[h]
     
    14621467cd ..\textbackslash ..\textbackslash CrypWin\textbackslash bin\textbackslash Debug\\
    14631468if not exist ".\textbackslash CrypPlugins" mkdir ".\textbackslash CrypPlugins"\\
    1464 del /F /S /Q /s /q "\colorbox{yellow}{Caesar}*.*"\\
    1465 copy "\$(TargetDir)\colorbox{yellow}{Caesar}*.*" ".\textbackslash CrypPlugins"\\\\
     1469%del /F /S /Q /s /q "\colorbox{yellow}{Caesar}*.*"\\
     1470%copy "\$(TargetDir)\colorbox{yellow}{Caesar}*.*" ".\textbackslash CrypPlugins"\\\\
     1471% Colorbox is ugly and creates spaces around the box. Highlighting via the Soul package is much better!
     1472del /F /S /Q /s /q "\hl{Caesar}*.*"\\
     1473copy "\$(TargetDir)\hl{Caesar}*.*" ".\textbackslash CrypPlugins"\\\\
    14661474You will need to change the highlighted fields to your particular plugin's name.
    14671475\clearpage
     
    14701478\label{DrawingTheWorkfloweOfYourPlugin}
    14711479
    1472 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:
     1480Each plugin should have an associated workflow file to show the algorithm in action in CrypTool 2. These workflow files are saved with the special \textit{.cte} file extension. You can view the example files from other plugins by opening any of the files in the \textit{\textbackslash ProjectSamples} folder with CrypTool 2. Below is a sample workflow for our Caesar example:
    14731481
    14741482\begin{figure}[h]
     
    14781486        \label{fig:sample}
    14791487\end{figure}
     1488
     1489As your last step of development, once your plugin runs smoothly, you should also create one of these sample workflow files for your plugin. Such a file can be automatically created by simply saving a CrypTool 2 workspace project featuring your plugin. You should store the workflow file in the \textit{\textbackslash ProjectSamples} folder and make sure to commit the file to the SVN repository (see Section \ref{CommitingYourChanges}).
Note: See TracChangeset for help on using the changeset viewer.