# Tools

## Overview

&okteta; brings some tools, some to analyze and manipulate the byte arrays and some with more general purpose. These tools can be activated or deactivated from the Tools entry in the menu bar. Each tool has a small view, which docks either in one of the sidebars or freely floats as a window. You can dock, undock, rearrange and also stack the tool views with the mouse, by pressing the &LMB; on the title bar of a tool view, moving it as you like and releasing the &LMB; to complete the action, otherwise cancel it by pressing the &Esc; key.

### Analyzers and Manipulators

Byte Table

  The table lists all possible byte values, both as character and numerical value.

  The selected value can be inserted at the cursor position for a defined number of bytes. This can be achieved by using the Insert button or double-clicking the line in the table.

Binary Filter

  The filter performs binary operations on the selected bytes. After choosing the operation (AND, OR, ROTATE..) the parameters, if any, can be set in the box below. The filter is executed on the use of the Filter button.

Strings

  This tool locates the strings in the selected bytes. After choosing the minimum string length, the strings are grepped for on the use of the Extract button. The list of the strings displayed can be narrowed by entering a filter term.

Statistics

  This tool builds a statistic for the selected bytes. The statistic gives the frequency of the occurrence of each byte value in the selection. It can be calculated by using the Build button.

Checksum

  This tool calculates various checksums or hashsums for the selected bytes. After choosing the algorithm and setting the parameter, if any, the sum is computed on the use of the Calculate button.

Decoding Table

  The table displays the values of the byte or the bytes starting at the cursor for some common simple data types like Integer or Float, but also UTF-8. Double-clicking on a line in the table opens an editor, so the value can be edited and changed.

Structures

  This tool enables investigating and editing of byte arrays based on user-creatable structure definitions. Detailed instructions are in an own section.

### General tools

Filesystem

  This tool offers an embedded file browser which can be used to select files to open.

Documents

  This tool shows all currently created or loaded files. Symbols mark the file with the currently active view and also show which files have unsaved changes or which storage copy has been modified by another program.

Bookmarks

  This tool can be used to manage the bookmarks, alternatively to the Bookmarks menu.

  Bookmarks are currently only transient and not saved if you close a byte array or the whole program.

File Info

  This tool displays some information about the current file, including its type, the location of storage and the size.

## Structures Tool

### General

The Structures tool enables analysing and editing of byte arrays based on user-creatable structure definitions, which can be built from arrays, unions, primitive types and enum values.

It has an own settings dialog, which can be reached by using the Settings button. There are various options that can be configured, like the style (decimal, hexadecimal or binary) in which the values are displayed. Moreover it is possible to choose which structure definitions get loaded and which structures are shown in the view.

Structures are defined in &okteta; Structure Definition files (based on &XML;, with the file extension `.osd`). Additionally a `.desktop` file contains metadata about that structure description file, such as author, homepage and license.

Currently there is no built-in support for creating, editing or installing structure definitions, so this must be done manually as described in the next sections.

### Installing structure definitions

The Structures tool looks for structure descriptions in the subdirectory `share/apps/okteta/structures/` of the user's directory for program data (find that by executing ``kde4-config` `--localprefix``). You may need to create this directory if there are not any structure definitions installed yet.

In that subdirectory there is an own subdirectory for each structure definition, which contains both the `.desktop` file and the `.osd` file of that definition.

E.g. with the program data directory `.kde` and a structure definition named ExampleStructure there is the directory `.kde/share/apps/okteta/structures/ExampleStructure`, which contains a file `ExampleStructure.desktop` and a file `ExampleStructure.osd`.

If you have installed a new structure definition by creating such a subdirectory with the two files or edited them, you need to restart &okteta; and open the settings dialog of the Structure tool. There select the Structures Management tab and make sure the relevant structure definition is checked. Then use the button Apply Changes, switch to the Structures tab and make sure the desired element is listed on the right-hand side.

### Sharing structure definitions

For common structures you may not need to create a definition yourself, but instead can reuse an already existing definition from places like kde-files.org.

You also may want to share a definition yourself. To do so, create a file archive (e.g. a zipped tar archive, `.tgz`) containing just the subdirectory with the `.osd` file and the `.desktop` file. From the example in the last section this would be the subdirectory `ExampleStructure`. If you adhere to this format future versions of the Structure tool will be able to provide automatical download and install of these definitions.

### Creating your own structure definitions

#### A first structure definition

To start we create a definition for a very simple test structure containing only integral data types (one char and one 32-bit int). They would be expressed in C/C++ as:

              struct simple {
                char aChar;
                int anInt;
              };

The first step is writing the `.osd` file, which we will call `simplestruct.osd`:

              <?xml version="1.0" encoding="UTF-8"?>
              <data>
                <struct name="simple">
                  <primitive name="aChar" type="Char"/>
                  <primitive name="anInt" type="Int32"/>
                </struct>
              </data>

which is fairly similar to the C/C++ definition. The type attribute can be any of the following:

- Char
- Int8
- UInt8
- Int16
- UInt16
- Int32
- UInt32
- Int64
- UInt64
- Float
- Double
- Bool8
- Bool16
- Bool32
- Bool64

The next step is writing the `.desktop` file for the metadata, which is just a set of key-value pairs. It should be named `simplestruct.desktop`. In this example it looks as such:

              [Desktop Entry]
              Encoding=UTF-8
              Icon=arrow-up
              Type=Service
              ServiceTypes=KPluginInfo

              Name=Simple test structure
              Comment=A very simple test structure containing only two items

              X-KDE-PluginInfo-Author=Alex Richardson
              X-KDE-PluginInfo-Email=alex.richardson@gmx.de
              X-KDE-PluginInfo-Name=simplestruct
              X-KDE-PluginInfo-Version=1.0
              X-KDE-PluginInfo-Website=http://www.plugin.org/
              X-KDE-PluginInfo-Category=structure
              X-KDE-PluginInfo-License=LGPL
              X-KDE-PluginInfo-EnabledByDefault=false

These fields should all be pretty much self-explanatory, except for `X-KDE-PluginInfo-Name`. This one must have the name of the `.osd` file as its value (without the `.osd` suffix).

Now create a subdirectory `simplestruct` as described above, copy the two files to this directory, and restart &okteta;.

#### More complex structures

Next we create a definition of a more complex structure which we will call "complex" and save in a file named `complex.osd`. This structure will contain two arrays (one with fixed length and one where the length is determined at runtime) as well as a nested structure and a union.

              <?xml version="1.0" encoding="UTF-8"?>
              <data>
                <struct name="complex">
                  <primitive name="size" type="UInt8" />
                  <union name="aUnion">
                    <array name="fourBytes" length="4">
                      <primitive type="Int8" />
                    </array>
                  </union>
                  <struct name="nested">
                    <array name="string" length="size"> <!-- references the field size above -->
                      <primitive type="Char" />
                    </array>
                  </struct>
                </struct>
              </data>

This would correspond to the following in pseudo C/C++

              struct complex {
                uint8_t size;
                union aUnion {
                  int8_t fourBytes[4];
                };
                struct nested {
                  char string[size] //not valid C++, references value of the uint8 size
                };
              };

You can obviously only have dynamic length arrays reference fields before the array.

Next we create the `complex.desktop` file just as in the example before (make sure you set `X-KDE-PluginInfo-Name` correctly) and also do the same to install both files.

#### Further information

A few example structure definitions can be found here. This include for example the file header for PNG files. An &XML; schema describing the structure of the `.osd` file can be found here. If more information is needed feel free to contact me at &Alex.Richardson.email;