Skip to content

CrypAnalysisViewControl

Jump to bottom
Nils Kopal edited this page Feb 15, 2022 · 1 revision

Table of Contents

CrypAnalysisViewControl

Purpose

The purpose of the WPF component `CrypAnalysisViewControl` is to simplify development and to enforce a consistent look and feel of all visual components in CrypTool 2 which have the need to show the progress and / or results of a cryptographic analysis process. The component aims at combining convenience in programming with freedom of content declaration.

The component comes with the following features:

  • Enabling consistent look and feel across analysis components of CrypTool 2
  • Requiring minimum amount of XAML code while still being flexible
  • Zooming capabilities on the CrypTool 2 workspace
  • Displaying of "standard" sections, whichs content and caption can be defined by the programmer
  • Displaying of "additional" sections (if needed)
  • Providing additional displaying components to be used in sections
This page describes the usage of the `CrypAnalysisViewControl` for developers. Some basic knowledge about WPF is required to understand the description.

Standard sections

The component consists of three standard sections, namely:

  • Result Header (Contains flat status labels which should represent the overall status)
  • Result List (Lists information about the intermediate and final analysis results)
  • Result Progress (Contains flat status labels which should represent further information about the analysis progress)
The developer can chose on his own which of those section should be visible and what its caption should be. The reason for this freedom in section declaration is that the need for certain sections and their content often depend on the analysis procedure and its implementation in question.

The content style and layout of the header and progress sections are predefined by the component, because they can only consist of label grids with two columns.

The colors of all three sections are predefined by the component.

The content of the result list section is not predefined and can therefore be customized as needed. The library of `CrypAnalysisViewControl` does however contain another component named `CrypAnalysisResultListView`, which can be used for conveniant definition of a result table display with predefined functionalities (see section below).

In addition to these standard sections, custom sections can be defined (see below).

Usage of "CrypAnalysisViewControl"

To use component `CrypAnalysisViewControl` in a WPF XAML file, it is necessary to add a project reference to the project library "CrypAnalysisViewControl" first, which is already included in the CT2 solution.

Furthermore, the namespace of the component needs to be declared in the WPF XAML file by adding the following attribute to the root element: 

      xmlns:analysisView="clr-namespace:Cryptool.CrypAnalysisViewControl;assembly=CrypAnalysisViewControl"

Now the component can be declared at some place in the XAML file like this: 

      <analysisView:CrypAnalysisViewControl />

Defining standard section's captions

This declaration would not affect the display, because the control does not declare any sections yet. To do so, the caption of each standard section to show needs to be declared in order to make the section visible. Captions can be declared using the attributes `ResultHeaderCaption`, `ResultListCaption` and `ResultProgressCaption`: 

      <analysisView:CrypAnalysisViewControl ResultHeaderCaption="Analysis" ResultListCaption="Top 10" ResultProgressCaption="Progress" />
The reason why even for standard sections the captions need to be defined is that the section's content often depend on the analysis procedure and implementation in question.

Note that all captions which are set in the `CrypAnalysisViewControl` can also be localized by using the CT2 XAML localization mechanism.

This declaration would result in all three sections being shown, but without any content.

Defining standard section's label content

The content of the header and progress section, which can only consist of labels, can be defined by setting component's properties "ResultHeaderLabels" and "ResultProgressLabels" respectively. These elements can only consist of child objects of type `ViewLabel`, which is also defined in the component's library:

The following codes demonstrates how labels can be defined in those two sections: 

      <analysisView:CrypAnalysisViewControl ResultHeaderCaption="Analysis" ResultListCaption="Top 10" ResultProgressCaption="Progress">
          <analysisView:CrypAnalysisViewControl.ResultHeaderLabels>
              <analysisView:ViewLabel Caption="First Label" Value="123" />
              <analysisView:ViewLabel Caption="Second Label" x:Name="SecondLabel" />
              <analysisView:ViewLabel Caption="Third Label" Value="{Binding TestProp}" />
          </analysisView:CrypAnalysisViewControl.ResultHeaderLabels>
		
          <analysisView:CrypAnalysisViewControl.ResultProgressLabels>
              <analysisView:ViewLabel Caption="Progress Label" Value="123" />
          </analysisView:CrypAnalysisViewControl.ResultProgressLabels>
      </analysisView:CrypAnalysisViewControl>

As can be seen from the example, labels consist of a static caption property and a value. The value can be set in a variety of ways, according to the common WPF approach:

  • Set value to a static value (see first label)
  • Set value in code behind by assigning a name to the label (see second label)
  • Set value by using binding (see third label)
All labels are automatically layed out by the component into two columns of equal size. It is possible to define empty labels to "skip" a cell in this grid.

Defining content of result list section

In contrast to the other two standard sections, the result list can contain arbitrary content. It can be defined by setting the main content of the component, like this: 

      <analysisView:CrypAnalysisViewControl ResultListCaption="Top 10">
          <Label>My result list content goes here.</Label>
      </analysisView:CrypAnalysisViewControl>

It is very common to show some kind of table or list in this section. It is good practice to set the background color of those components to "transparent" in order to show the default section color.

Using "CrypAnalysisResultListView" for listing results

Due to the fact that a particular kind of result table for showing the best analysis results is used very often, the component's library offers a table component with some standard functionality and layout. The name of this component is `CrypAnalysisResultListView` and can be used exactly as a standard WPF `ListView` component. It features the following additions to the normal `ListView` component:

  • Style adjusted for usage in the result section
  • Standard context menu with standard functionality (for copying values to clipboard)
  • Customizable event handler for performing actions on result entries (currently only triggered when user double clicks an entry row. Additional trigger possibilities may be added in the future)
The following code shows a basic example of this component in the result list section with only one column: 
      <analysisView:CrypAnalysisViewControl ResultListCaption="Top 10">
          <analysisView:CrypAnalysisResultListView ItemsSource="{Binding MyResultList}" ResultItemAction="CrypAnalysisResultListView_ResultItemActionEvent">
              <analysisView:CrypAnalysisResultListView.View>
                  <GridView>
                      <GridViewColumn Header="Test Column" DisplayMemberBinding="{Binding TestValue}" />
                  </GridView>
              </analysisView:CrypAnalysisResultListView.View>                
          </analysisView:CrypAnalysisResultListView>
      </analysisView:CrypAnalysisViewControl>

The only thing here which is not in the standard `ListView` component is the attribute `ResultItemAction`. It can be set to a handler method which gets triggered when an "action" is performed on an table's entry.

The developer can only make use of the integrated functionalities if the item objects are derived from interface `ICrypAnalysisResultListEntry`, which can be used to control the source values of the clipboard actions through the properties `ClipboardValue`, `ClipboardKey`, `ClipboardText` and `ClipboardEntry`.

Defining additional sections

The developer should always try to use the standard sections for basic information in order to help CrypTool 2 to have a consistent look and feel. However, it might happen that the need for additional sections arises, which are used for very specific information. The definition of additional sections is possible, but comes with two constraints:

  • Section colors need to be defined by the developer (no enforcement of a standard)
  • Additional sections can only be added to the bottom of the component (i.e.: after the three standard sections)
Additional sections can be defined by adding objects of type `SectionControl` to the control's property `AdditionalSections`: 
      <analysisView:CrypAnalysisViewControl>
          <analysisView:CrypAnalysisViewControl.AdditionalSections>
              <analysisView:SectionControl SectionHeaderCaption="OpenCL" SectionBackground="Aqua" SectionHeaderBackground="Orange">
                  <Label>Section's content goes here</Label>
              </analysisView:SectionControl>
          </analysisView:CrypAnalysisViewControl.AdditionalSections>
      </analysisView:CrypAnalysisViewControl>

As can be seen, arbitrary content is allowed in additional sections.

Using component "SectionViewLabelsControl"

As has been described above, two of the standard sections only allow label content, using an automatic layouting mechanism for the defined labels. This mechanism is internally implemented by using the component `SectionViewLabelsControl`, which is also included in the component's library.

This component can also be used in sections which allow arbitrary content, by defining it explicitly like this: 

      <analysisView:SectionViewLabelsControl>
              <analysisView:ViewLabel Caption="Test" />
                      ...
      </analysisView:SectionViewLabelsControl>

List of CT2 plugins using "CrypAnalysisViewControl"

The following CT2 plugins are using `CrypAnalysisViewControl`:

  • ADFGVX Analyzer
  • Monoalphabetic Substitution Analyzer
  • Enigma Analyzer
  • Homophone Substitution Analyzer
  • IDP Analyzer
  • KeySearcher (uses multiple instances of the control for different scenarios. Defines custom sections for OpenCL and cloud computation)
  • M-138 Analyzer
  • Network Receiver (does not use "Result List" section)
  • Network Sender (does not use "Result List" section)
  • Playfair Analyzer (uses result columns which can be hidden by plugin's settings)
  • Quadratic Sieve (does not use `CrypAnalysisViewControl`, because analysis result is not a table)
  • Transposition Analyzer
  • Vigenere Analyzer

Example images of plugins using "CrypAnalysisViewControl"

Clone this wiki locally