# Working with Views

## View Objects Overview

### View Object Concepts

We will call &kst; objects which are painted onto the screen View Objects. These include windows, annotations, plots, curves, and images. A diagram of the relationship between these objects is displayed below:

&kst; Window, Plot, and Curve relationships

As can be seen from the diagram, the most fundamental views are windows, which act as containers for plots and annotation objects. Plots, however, are the most important view objects of &kst; as they perform its chief function of displaying data.

Annotations are objects like labels, arrows, etc. which can be used to display information about plots, or highlight areas of interest. The annotation objects currently implemented in &kst; are Labels, Boxes, Ellipses, Lines, Arrows, Pictures and Legends. They are very useful when preparing plots for presentation or publication.

Instances of the various view objects in &kst; are hierarchically grouped - annotations, for example, are often deemed children of a specific plot based on their location. Moving and resizing a plot then resizes the annotation also. A good way to work directly with the view object hierarchy is to use the View Manager. It can be accessed by selecting Data View Manager.

All view objects can be created by selecting their corresponding draw tools. You can edit their options by double clicking on them in Layout mode.

Here is a sample use of view objects in &kst;, where we have used a Plot, Labels, Arrows, Lines, and a transparent PNG Picture to mark up an astronomical color magnitude diagram.

View objects example
View objects example

### The View Manager

The View Manager is a tree list view which allows you to copy and delete view objects. It also allows you to access their edit dialogs.

View Manager
View Manager

- Edit/Delete View Object: Select a view object (window, plot, curve, etc.) to edit and click the Edit button, or right click on the view object's entry and select the Edit... option in the context menu which appears.

- Copy view objects: Select the view object which you would like to copy and click-drag it over the name of the parent which you would like to copy it into.

The view manager can be accessed by clicking view manager icon on the toolbar.

### Context Menus

When working with plots and other view objects, right-clicking will bring up a context menu which provides commonly used functions. In general, the context menu which is presented depends on which mouse mode you are in and which object you are centered on, but there are four basic options common to all view objects. The title of the context menu which appears gives the name of the view object which you have clicked on.

Edit...

  Brings up the edit dialog for the underlying view object. See the View Object Types sections for more information on these settings.

Delete

  Deletes the view object.

Rename

  Presents a dialog to modify the unique name assigned to the view object.

Cleanup Layout

  Arranges the plots in the current window in a tile type pattern, with no overlap between plots. Selecting Default Tile from this sub-menu rearranges the plots according to an aesthetically pleasing algorithm. Selecting the Custom option allows you to manually specify how many columns to tile the plots into. This action applies to all plots in the current window.

There are additional context menu options specific to the Zoom mouse modes and the Data Layout mode.

### Switching among Different Modes

Kst has various mode choices. Each mode has it own specific usages. The following are available modes in Kst:

- Mouse Zoom Mode

- Graphics Mode

- Layout Mode

- Data Mode

You can enable any of the modes from the Plot menu. plotsmenu plotsmenu

Note that when you open a new session of Kst, it will be in XY Mouse Zoom mode by default. The following summarizes major usages for each mode.

Mouse Zoom Modes

  The primary usage of mouse zoom modes is to access various zooming functions provided in the context menu. See the section: Zoom Mode Context Menu for detail. There are three mouse zoom modes available in Kst.

  - XY Mouse Zoom

  - X Mouse Zoom

  - Y Mouse Zoom

Graphics Mode

  Graphics Mode is used to insert various view objects including all of the annotation objects, plots and legends. To enable graphics mode, choose the object you want to insert from the Graphics Mode menu in the Plots menu. See the image below. graphic_mode graphic_mode Once a view object has been selected from the Graphics Mode menu, you can insert it anywhere on the current window. Also, you can insert this type of object as many times as you want until you choose another view object or switch to a different mode. The context menu for graphics mode is the same as for data mode.

Layout Mode

  Layout Mode is chosen whenever you want to change the size of or move an object. See Moving and Resizing View Objects.

  You can also change the layer of an object or group multiple objects together through the context menu under layout mode. See the Layout Mode Context Menu for detail.

Data Mode

  Data Mode has already been introduced in Chapter 3. See details in the corresponding section. Note that data mode can only be enabled when Kst is in one of the mouse zoom modes.

The rightmost icon in the toolbar indicates which mode the current &kst; session is in. To quickly switch to another mode, click on that icon; the menu below will appear, and you can choose the mode you want.

modemenu modemenu

In the above example, Kst is in XY Mouse Zoom mode, and it is going to change into Layout Mode.

## View Object Types

### Plots

Plots allow you to display curves and images in &kst;. The Edit Plot dialog is used to change a plot's content, appearance, axes, and markers. To access it, right click on a plot and select the Edit... menu item from the context menu, or use the View Manager. There are several tabs:

- Content

- Appearance

- X/Y Axis

- Range

- Markers

#### Content Tab

This tab allows you to select which of the available plot objects (curves, images, etc.) will be displayed in the plot. Move objects between the Available and Displayed object lists using the left and right arrow buttons. Change the order in which the objects are plotted with the up and down arrow buttons.

Edit Plot - Content Tab
Edit Plot - Content Tab

#### Appearance Tab

This tab allows you to adjust the colors, fonts, legend, and labels of a plot.

Edit Plot - Appearance Tab
Edit Plot - Appearance Tab

##### Colors and Line Weights

Axis and Background

  The colors for the axes (foreground) and background of the plot.

Line Weight

  The line width in pixels.

Major/Minor Grid

  The line width and colour of the lines marking out the major/minor grid lines. To enable these grid lines for the axes, use the X Axis/Y Axis tabs.

##### Labels

Scalar list

  A list of the current scalars defined in &kst;. This list is used to quickly insert values in the label texts. Choosing an item from this list will insert the item at the current text cursor position.

Top label

  The label located at the top of the plot. Select a font size and enter the text for the label using the controls in this row. These labels can use all of the formatting options of true label objects.

Justification

  This drop-box controls whether the top label will be located at the Left, Right, or Center of the plot's title space. The justification for the X and Y axis labels of a plot is always the center.

X/Y axis

  The label located vertically next to the X/Y axis of the plot. Select a font size and enter the text for the label using the controls in this row. These labels can use all of the formatting options of true label objects.

Numbers, Rotation X and Rotation Y

  The numbers used to label both the X axis and the Y axis of the plot. The size and angles of the numbers can be specified. Positive angles rotate the text clockwise, while negative angles rotate the text counter-clockwise.

Auto Label

  Click this button to automatically generate label texts for all labels on the plot. The text for Top label will be a list of paths to the data files used in the plot. The text for Y axis will be a list of the dependent variable descriptions (e.g. Number in Bin for a histogram). The text for X axis will be the name of the vector used as the independent variable.

Font

  The font used for all labels of the plot. Select an available font using the drop-down list.

##### Legend

Show

  Check this box if you would like the plot to display a legend.

Match Contents to Plot

  Check this box if you would like the plot to automatically adjust its legend to reflect its contents.

Edit...

  This button displays the Edit Legend dialog, shown below.

  Legend Edit

  The available options are:

  Title

    The text for the top of the legend.

  Available / Displayed Objects

    This allows you to choose a set of objects to display in the legend which differs from the ones displayed on the plot.

  Allow plot dialog to reset legend contents

    If Match Contents to Plot was not selected in the Edit Plot Dialog, and this option is selected, then the Plot can enforce that its legend matches its true contents.

  Font / Size / Color

    The formatting options for the legend text.

  Box (Transparent / Colors / Margin / Border Width)

    The properties of the legend outline and fill.

##### Edit Multiple

Click on the Edit Multiple button, the dialog allows you to apply modifications of the selected plot to other plots as well. Besides manually choosing the objects you want to edit in the dialog, you can type objects' name in the Filter textbox. The use of wildcards is supported.

#### X/Y Axis Tabs

Edit Plot - X Axis Tab
Edit Plot - X Axis Tab

##### Placement

Suppress top/bottom border and label

  Check this box to remove the white space at the top/bottom of the plot.

##### Scale

Logarithmic

  Enable this checkbox if you wish to use a logarithmic scale for the axis.

Base and offset mode

  Enabling this option causes the axis to be labelled by displacements from an initial position, where the initial position is displayed in the lower left of the plot. The displacement labels are printed inside square brackets to avoid confusion.

Reverse

  Causes the axis direction to be reversed.

Interpret as: / Display as:

  If your axis contains date/time information encoded in a difficult to read form (e.g. Julian Date), this option allows you to have &kst; automatically convert it to something more legible. Note: The time data has to be in one of the formats listed in Table 4.1.

  ###### Date Format in &kst;

  Date Format | Description | Online Reference
  Julian Year | a time interval of exactly 365.25 days in astronomy | See definition in wikipedia
  Standard C time | The amount of time that has elapsed since midnight at the beginning of January 1st 1970 |
  JD | Julian Date | See definition for Julian Date
  MJD | Modified Julian Day: the number of days that have elapsed since midnight at the beginning of Wednesday November 17th 1858 | See more details in wikipedia
  RJD | Reduced Julian Day | See the details in wikipedia
  TAI | Temps Atomique International (International Atomic Time) | For more details, see this webpage.
  KDE Short Date and Time | It has the following format: YYYY-MM-DD HH:MM:SS[seconds]. e.g. 1958-01-29 10:05:58[seconds] |
  KDE Long Date and Time | It has the following format: day date Month Year HH:MM:SS[seconds]. e.g. Wednesday 29 January 1958 10:05:58[seconds] |

Transform top axis

  Checking this box causes the top axis of the plot to be labelled following the contents of the expression field. The variable x can be used in the expression field to refer to the value on the lower X axis. To plot the top axis as the lower axis scaled by a factor of 2, for example, enter `2*x` in the expression field.

##### Tick Marks

Spacing

  Select Course, Default, Fine, or Very Fine from this drop down menu to determine which algorithm &kst; will use to determine the number of Major and Minor tick marks which will be plotted.

Minor Ticks / Auto Minor

  Unchecking Auto Minor allows you to tell &kst; how many minor ticks to place between each pair of major ticks. The number of major ticks cannot be set manually.

Place marks:

  Select Inside plot, Outside plot, or Inside and outside plot to determine the location of the tick marks with respect to the axes.

##### Grid Lines

Show major/minor lines

  Select these boxes if you would like lines to be drawn through the plot connecting the major/minor tick marks on opposing axes.

##### Edit Multiple

#### Range Tab

The settings for the plot axes are specified on this tab. The axis settings are split into two identical sections — an X axis section and a Y axis section.

Edit Plot - Range Tab
Edit Plot - Range Tab

##### X/Y Axis

Auto

  Select this option to let &kst; automatically choose a scale for this axis based on the highest and lowest values for this axis found in the plotted objects.

Auto border

  This option behaves similarly to Auto, but the axis is padded with a small amount of extra space. This can sometimes improve the appearance of plots, and make it easier to see features near the range limits.

Auto up

  This option behaves similarly to Auto, but the upper axis limit will only increase, and the lower axis limit will only decrease.

Spike insensitive auto scale

  Select this option to let &kst; automatically choose a scale for this axis that is based on the values found in the plotted objects. In general, spikes, or sudden short increases or decreases in the value, will be ignored when determining the scale. This option is usually for the dependent (Y) axis.

Mean-centered

  Select this option to center the axis around the mean of the values found in the plot (X values are used to calculate the mean for the X axis, and Y values are used to calculate the mean for the Y axis). Specify the length of the axis in the Range text box.

Expression

  Manually specify lower and upper limits for the axis. Enter the expression for the limits in the From: and To: textboxes. These can be numerical values, or equations based on the scalars maintained by &kst;. These scalars can be quickly added to the expressions by selecting them from the pull-down menus to the right of the textboxes.

##### Edit multiple

#### Markers

Below is a screenshot of the Markers tab.

Edit Plot - Markers Tab
Edit Plot - Markers Tab

Plot markers provide an easy means of flagging areas of interest on a plot. The Markers tab provides full access to plot marker settings and options. Navigation functions for plot markers are described in the Scroll Menu section.

To quickly create plot markers on a plot, place the mouse cursor over the plot and press the Insert key. A vertical line should appear indicating the position of the plot marker.

New and Add

  Use the New text field to manually enter a plot marker value. Values can be entered in floating point or scientific notation. Values in scientific notation must be entered in the form `mEx` or `mex`, where `m` is the mantissa and `x` is the exponent. For example, one way to enter the value 15000 in scientific notation is by typing `1.5e4`.

  Click the Add button to create a new plot marker with the specified value. You will be warned if duplicate plot markers already exist, or if the entered value is not valid. Note that plot marker additions or removals made from the Markers tab are not applied unless the plot dialog settings are applied.

Defined plot markers, Remove, and Remove All

  The list of existing plot markers for this plot are listed under Defined plot markers. To remove plot markers, highlight the desired markers in the list and click the Remove button. Multiple markers can be selected for removal by clicking and dragging within the list, or by holding down the Shift or Ctrl key and clicking on items in the list. To remove all plot markers for this plot, click the Remove All button. Note that plot marker additions or removals made from the Markers tab are not applied unless the plot dialog settings are applied.

Automatic Marker Generation

  In addition to individually defined plot markers, it is also possible to generate plot markers based on a curve. To use a curve object for plot marker generation, check the Use data object as marker source checkbox and select a curve from the drop down list. Then select the criteria for creating plot markers. Selecting Rising edge causes plot markers to be created when the Y value of the selected curve changes from zero to non-zero. Selecting Falling edge causes plot markers to be created when the Y value of the selected data object changes from non-zero to zero. Selecting Both causes plot markers to be created on both rising edges and falling edges of the data object. In all cases, the X value of the point in the data object with the non-zero X value is used to create the new plot marker.

  If the selected curve is subsequently updated, additional plot markers will be created if necessary. However, plot markers will never be removed as a consequence of data object changes, so manually created plot markers will never be affected.

  It is also possible to create plot markers from a vector. Enable the Use vector as marker source checkbox and select a data vector from the drop down menu. The values of this vector will now be used as markers

Appearance

  These options allow you to select the colour, line type, and weight (thickness) of the plot markers.

#### Using the Plot Class in KstScript

Plots in &kst; can also be manipulated by KstScript. You can change the view of a plot by modifying its properties defined in the Plot Class, such as legend, topLabel, x/yAxis, etc.

See the Plot Class of the Script Chapter for detail. In order to change the view of a plot, you often need to use the Plot Class with other classes, such as the Axis Class, or the Curve Class.

The example below is to show how to use the Plot Class and the TimeInterpretation Class to interpret various date formats for a plot.

##### Example of Using the Plot Class to interpret date format for x Axis

    w = new Window(); 		//construct a new window
    p = new Plot(w);            	// place a plot on the window
    c = new Curve("time","Y"); 	// use vector time and Y to construct a new curve
    c.tagName = "time vs Y";
    p.curves.append(c); 		   	//to show the curve on the plot
    p.xAxis.interpretation.input = 2; 	// the input time vector is in Julian Date.
    				 	 //2 stands for Julian Date in the TimeInterpretation Class.
    p.xAxis.interpretation.output = 0; 	//  the time vector needs to be shown in
    				   	//the format: DD/MM/YY HH:MM:SS.

    p.xAxis.interpretation.active = true; 	//Active the interpretation

### Annotation Objects

Annotation objects are Labels, Boxes, Ellipses, Lines, Arrows and Pictures. They can be easily created by choosing the Graphic mode in the Plots menu.

annotationmenu
annotationmenu

To edit an annotation object, right click on the object and choose the Edit... menu item in the context menu.

To move or resize an annotation object, you must be in Layout mode.

### Labels

Custom labels can be displayed in arbitrary locations in &kst; plot windows.

Edit Label
Edit Label

The following are explanations of the dialog box elements.

Scalars

  A list of scalars currently defined in &kst;. Selecting an item from the dropdown list inserts a reference to the scalar's value at the current cursor position in the label text.

Strings

  A list of strings currently defined in &kst;. Selecting an item from the dropdown list inserts a reference to the string's contents at the current cursor position in the label text.

Label text

  The text displayed by the label. You may enter text manually in this dialog, or insert references into it using the scalar and string drop down menus. &kst; labels support many LaTeX formatting and symbol commands, prefixed with the usual \. A list of supported commands is given in the table below:

  #### LaTeX Commands Supported in Label Text

  Command |  | Result
  --- | --- | ---
  \Greeklettername |  | Uppercase Greek letters. E.g. \Gamma.
  \greeklettername |  | Lowercase Greek letters. E.g. \gamma, \delta.
  \approx |  | Approximately equal to.
  \cdot |  | Center dot- dot product.
  \geq, \ge |  | Greater than or equal to.
  \leq, \le |  | Greater than or equal to.
  \t |  | Tab space.
  \n |  | Newline.
  \partial |  | Partial difference.
  \sqrt |  | Square root.
  \inf |  | Infinity.
  \int |  | Integral.
  \pm |  | Plus-minus sign.
  \[, \] |  | Square-brackets.
  \sum |  | Summation sign.
  \prod |  | N-ary product.
  y^{x} |  | Write x as superscript.
  y_{x} |  | Write x as subscript.
  \textit{'text'} |  | Write 'text' in italics.
  \textbf{'text'} |  | Write 'text' in bold font.
  \underline{'text'} |  | Write 'text' with underline.
  \textcolor{'color'}{'text'} |  | Write 'text' in 'color'.

Font

  The font to use for the label text. Select a font from the dropdown list.

Size

  The size of the label text. 0 (the default value) roughly corresponds to a 12pt size.

Rotation

  The number of degrees to rotate the label text. Positive values rotate the label clockwise, while negative values rotate the text counter-clockwise.

Font Color

  Select the color to use for the label text. Clicking the button displays the standard &kde; color chooser.

Precision

  When scalar variables are included in labels, Precision dictates the number of digits which are displayed.

Box

  Select the color to use for the label text. Clicking the button displays the standard &kde; color chooser.

Once you are satisfied with the label settings, click the Apply button to view the label settings without closing the Edit Label dialog. Click the OK button to apply the label settings and close the dialog. Alternatively, you can click the Close button to close the Edit Label dialog without applying any label settings.

### Boxes / Ellipses

Box and ellipse annotation objects are usually used to outline important features on a plot.

The following are explanations of the dialog box elements.

Border Color

  The color of the outline of the box/ellipse object. Clicking the button displays the standard &kde; color chooser.

Border Width

  The width of the annotation's line/border (in pixels).

Fill Color / Transparent Fill

  The color of the contents of the box/ellipse. Clicking the button displays the standard &kde; color chooser. If you select Transparent Fill then the box/ellipse will be see-through.

X/Y Roundness

  These options are for boxes only. They determine the fractional rounding of the box's corners. Values of 0 result in standard corners (right angles), while values of 99 result in a maximally rounded box (an ellipse). For more information on these options, see the Qt documentation on QPainter::drawRoundRect.

### Lines / Arrows

Line and Arrow annotation objects are usually used to highlight important features on a plot (by pointing to a particular peak, for example.).

The following are explanations of the dialog box elements.

Line Color

  The color of the line/arrow object. Clicking the button displays the standard &kde; color chooser.

Line Style

  Here you can chose to make the line solid, dashed, dot-dashed, etc.

Line Width

  The width of the line (in pixels). This will also change the head size for an arrow object.

Arrow at start/end

  Determines where to place the arrow heads. The heads will always point away from the line.

Start arrow scaling

  A scaling factor for the arrow head sizes. This can be useful if your line width leads to a head size which is larger than you would like.

### Pictures

Picture objects can be used to easily add an external graphic to your plot. More popular image formats are supported, depending on the libraries installed on your system.

Edit Line
Edit Line

The following are explanations of the dialog box elements.

Border Color

  The color of the outline of the box/ellipse object. Clicking the button displays the standard &kde; color chooser.

Border Width

  The width of the annotation's line/border (in pixels).

Maintain Aspect Ratio

  If this box is checked, then when resizing the picture object &kst; will maintain the ratio between the width and height of the picture. You can temporarily disable (or enable) this option by holding down the Shift key as you resize the picture.

File Path

  The location of the image you would like to display.

Refresh Timer

  Set this to the period (in seconds) with which you would like &kst; to check the image file for updates, and reload it if necessary. If the refresh timer is set to 0 then the image will only be reloaded after restarting &kst; or opening and closing the picture object's edit dialog.

### Using KstScript to manipulate Annotation objects

You can construct and edit annotation objects from the corresponding classes in KstScript. See details in

- Label Class

- Box Class

- Ellipse Class

- Line Class

- Arrow Class

- Picture Class

To change a general property of an annotation object, such as moving or resizing an object, you may use methods and properties defined in the ViewObject Class, the super class of all annotation objects.

#### Function for Creating and Resizing Annotation Objects

If you use the code below to create an annotation object, for example, a box, in tab W1:

    b = new Box("W1");

You may notice that there is nothing in W1. However, the new box is actually created. It has a very small size and is sitting in the position (0,0), the upper left corner of the &kst; window; therefore, it is necessary to move and resize it in order to make it visible. Notice that you will need to change the default settings for every annotation object you create, so it may be more convenient to use a KstScript function to do that. The following is an example function which will create a user specified annotation object, and then resize and move this object to the position (250,250) on the user specified window.

    //annotation.js
    //A(string) is the name of an annotation object
    //W(string) is the name of a window
    function createAnot(A, W)
    {
    //declare strings to hold names of possible annotation objects
    lb = new String();
    lb.value = "Label";
    b  = new String();
    b.value = "Box";
    e = new String();
    e.value = "Ellipse";
    l = new String();
    l.value = "Line";
    a = new String();
    a.value = "Arrow";
    input = new String();//declare a string to hold the name of the user specified annotation object
    input.value = A;
    //create the user specified annotation object and resize it to let it become visible
    if(input.value==lb.value)
    {
    anot = new Label(W);
    anot.tagName = "new Label";
    anot.resize(new Size(100,100));
    anot.text = "Enter Text Here";
    }
    else if(input.value==b.value)
    {
    anot = new Box(W);
    anot.tagName = "new Box";
    anot.resize(new Size(100,100));
    }
    else if(input.value==e.value)
    {
    anot = new Ellipse(W);
    anot.tagName = "new Ellipse";
    anot.resize(new Size(100,100));
    }
    else if(input.value==l.value)
    {
    anot = new Line(W);
    anot.tagName = "new Line";
    anot.to = new Point(100,100);
    anot.width = 2;
    }
    else
    {
    anot = new Arrow(W);
    anot.tagName = "new Arrow";
    anot.toArrow = true;
    anot.to= new Point(100,100);
    }
    //move this annotation object to the position (250,250)
    anot.move(new Point(250,250));
     }

After loading this function script in Kst, you can create an edited annotation object like this:

    createAnot("Label","W1");

## Zooming and Scrolling

Zooming and scrolling in plots is easy and intuitive with &kst;. The following sections explain the different zooming and scrolling modes.

### Mouse Zoom Modes

To access the different zoom modes, choose one of XY Mouse Zoom, X Mouse Zoom, or Y Mouse Zoom from the Plots menu. The different modes are described below.

#### XY Mouse Zoom

In XY Mouse Zoom mode, you can zoom into a specific rectangular area of the plot by simply clicking and dragging to draw a rectangle where desired. The x and y axes of the plot will change to reflect the new scale. This mode is often useful for quickly looking at an interesting area of the plot without having to specify exact axis scales.

#### X Mouse Zoom

In X Mouse Zoom mode, the y axis is fixed. Zooming in is performed by clicking and dragging a rectangular area; however, the upper and lower limits of the rectangle will always be equal to the current upper and lower limits of the y axis. This mode is often useful for looking at a certain time range, if the x axis happens to represent a time vector.

You can quickly switch to X Mouse Zoom mode by holding down Ctrl. The mouse cursor will change to indicate the new mode. Releasing Ctrl will return you to the previous mouse zoom mode.

#### Y Mouse Zoom

In Y Mouse Zoom mode, the x axis is fixed. Zooming in is performed by clicking and dragging a rectangular area; however, the left and right limits of the rectangle will always be equal to the current left and right limits of the x axis. This mode is often useful for zooming in on data that is concentrated around a horizontal line.

You can quickly switch to Y Mouse Zoom mode by holding down Shift. The mouse cursor will change to indicate the new mode. Releasing Shift will return you to the previous mouse zoom mode.

### Zoom Mode Context Menu

When in any of the mouse zoom modes, right clicking on a plot brings up some special zoom options, in addition to the basic context menu options.

zoomContextMenu
zoomContextMenu

Maximize

  Temporarily expands the plot so that it takes up the entire area of the window. Uncheck this option to return the plot to its previous size.

Pause

  Pauses automatic update of live data. This menu item duplicates the functionality of Pause from the Range menu.

Match Axes

  These options allow you to quickly change the axes of a plot to match those of another plot. Both the X and Y axes scales of the current plot will change to match those of plot which you choose from the submenu. Note that this does not permanently tie the axes scales together; changing the zoom on either plot will unmatch the axes scales again. To tie the axis scales of two or more plots together, use the Tied Zoom feature.

Match X Axis

  This option allows you to quickly change the X axis of a plot to match that of another plot, similarly to the Match Axes submenu.

Zoom (submenu)

  The Zoom submenu is described in the section entitled The Zoom Menu.

Scroll (submenu)

  This menu is described in the section entitled The Scroll Menu.

Edit (submenu)

  This submenu displays a list of objects available for editing in the underlying plot. Clicking on an object name from the submenu displays the Edit dialog for the object.

Fit (submenu)

  This submenu displays a list of curves which can be fit. Selecting a name from the submenu displays a New Plugin dialog which allows you to choose a fit plugin. The input vectors are prechosen based on the curve selected.

Filter (submenu)

  This submenu displays a list of data objects that can be filtered. Selecting a name from the submenu displays a New Plugin dialog which allows you to choose a filter plugin. The input vector to be filtered is selected based on the curve. In addition, curve appearance properties can be changed, as the Filter function creates vectors, and curves based on the vectors.

Remove (submenu)

  This submenu displays a list of curves currently in the plot. Clicking on a curve name from the submenu removes the curve from the plot (the curve itself, however, is not removed as a data object).

### The Zoom Menu

The Zoom menu can be accessed by right-clicking on a plot and selecting the Zoom submenu from the context menu. A list of zoom actions and their corresponding keyboard shortcuts will be displayed. These actions are described below.

Zoom Action | Keyboard Shortcut | Description
--- | --- | ---
Zoom Maximum | M | Sets both the x axis and the y axis scales so that all data points are displayed. This is equivalent to the AutoScale setting of the Plot Dialog.
Zoom Max Spike Insensitive | S | Sets both the x axis and the y axis scales so that most data points are displayed. Spikes, or sudden increases or decreases in x or y values, are excluded from the plot display.
Zoom Previous | R | Returns to the most recent zoom setting used.
Y-Zoom Mean-centered | A | Sets the Y axis so that the mean of the y values in the plot is centered vertically. The actual zoom level is not changed.
X-Zoom Maximum | Ctrl M | Sets the x axis scale such that the x values for all data points are between the minimum and maximum of the x axis. The y axis scale is unaltered.
X-Zoom Out | Shift Right | For a non-logarithmic x axis, increases the length of the x axis by a factor of approximately 0.5, without changing the midpoint of the x axis. The y axis scale is unaltered.
X-Zoom In | Shift Left | For a non-logarithmic x axis, decreases the length of the x axis by a factor of approximately 0.5, without changing the midpoint of the x axis. The y axis scale is unaltered.
Normalize X Axis to Y Axis | N | Sets the length of the X Axis to be equal to that of the Y Axis, maintaining the current center.
Toggle Log X Axis | G | Enables or disables using a logarithmic scale for the x axis.
Y-Zoom Maximum | Shift M | Sets the y axis scale such that the y values for all data points are between the minimum and maximum of the y axis. The x axis scale is unaltered.
Y-Zoom Out | Shift Up | For a non-logarithmic y axis, increases the length of the y axis by a factor of approximately 0.5, without changing the midpoint of the y axis. The x axis scale is unaltered.
Y-Zoom In | Shift Down | For a non-logarithmic y axis, decreases the length of the y axis by a factor of approximately 0.5, without changing the midpoint of the y axis. The x axis scale is unaltered.
Normalize Y Axis to X Axis | Shift+N | Sets the height of the Y Axis to be equal to that of the X Axis, maintaining the current center.
Toggle Log Y Axis | L | Enables or disables using a logarithmic scale for the y axis.
Scale | I | Only has any effect on an image; cycle through the extreme values of the image matrix to redefine the threshold values of the image scale every time; its purpose is to let the user better view the intermediate values of an image

Many of the zoom actions are best used in conjunction with the various mouse zoom modes.

### The Scroll Menu

Functions for scrolling a plot are available by right-clicking a plot and selecting the Scroll submenu from the context menu. Most scrolling functions and their keyboard shortcuts should be self-explanatory. To quickly jump to a plot marker, select Next Plot Marker (to jump right) or Previous Plot Marker (to jump left). For more information on plot markers, see the documentation on the Markers section of the Edit Plot Dialog.

Assuming non-logarithmic axis scales are used, each function scrolls the plot in the indicated direction by 0.1 of the current length of the x axis (when scrolling left or right), or 0.25 of the current length of the y axis (when scrolling up or down).

You can also scroll left or right in a plot by using the mouse wheel (if available).

To quickly go forwards or backwards along the x axis, select Back 1 Screen or Advance 1 Screen from the Range menu. The keyboard shortcuts, Ctrl Left and Ctrl Right respectively, can be used as well.

### Tied Zoom

When looking at two or more related plots (for example, two curves on separate plots both dependent on the same time vector), it can sometimes be useful to zoom or scroll the plots simultaneously. This is possible using &kst;'s tied zoom feature. To activate tied zoom, click the small square at the top-right corner of the plots you wish to tie together. The squares will change colour to indicate the plots are tied, as shown below.

Top of Plot Dialog
Top of Plot Dialog

Zooming and scrolling actions performed on one plot in a group of tied plots will be performed on all the plots in the group. To remove a plot from the tied group, simply click on the small square at the top-right corner of the plot again. The square will become transparent to indicate that the plot is not tied.

To quickly tie or untie all plots (including plots in other windows), select Tied Zoom from the Plots menu, or the corresponding icon tied ZoomIcon on the &kst;toolbar.

## Manipulating Plot Layout

View objects in a &kst; window are arranged in layers. Each object is positioned on one layer, and each layer contains only one object. Thus, view objects can overlap, with plots in higher layers taking precedence in visibility over those in lower ones. To change the layout of plots in &kst;, layout mode must be activated. Layout mode can be toggled by selecting Layout Mode from the Plots menu.

### Moving and Resizing View Objects

Moving and resizing view objects in layout mode is analogous to moving and resizing regular windows. To move a plot, simply click anywhere on the desired plot and drag the plot. An outline of the plot will appear, indicating where the plot will be placed, as shown in the following image.

moving_outline

You can drag plots anywhere within the current window. To resize a plot, move the mouse cursor to any edge or corner of the plot. The cursor will change to indicate that the plot can be resized. Click and drag the outline of the plot until the plot is the desired shape and size.

### Layout Mode Context Menu

While layout mode is activated, right-clicking on any view object displays the basic context menu with several additional options. The selections available in this menu are listed below.

layout ContextMenu
layout ContextMenu

Raise

  Raises the plot one layer up.

Lower

  Lowers the plot one layer down.

Raise to Top

  Raises the plot to the top-most layer, guaranteeing that it will be visible.

Lower to Bottom

  Lowers the plot to the bottom-most layer.

Move To

  Selecting a window name from this submenu moves the plot to the window with the corresponding name.

Copy To

  Selecting a window name from this submenu copies the plot to the window with the corresponding name.

If multiple view objects are selected in data mode, additional context menu items become available.

### Selecting Multiple View Objects and Grouping

Two or more view objects can be selected together in layout mode. To select the objects, hold down the Shift key and either sequentially click on each you wish to select, or drag to draw a dotted rectangle around a group of view objects. The selected objects will be indicated by corner highlights, as shown below. Multiple selection allows you to move several view objects simultaneously by dragging any single object that is part of the selection. In addition, the layout mode context menu contains three additional items when multiple objects are selected. These items are described below.

select_multiple
select_multiple

Condense Selected

  This option is available if the view objects which are selected are all plots. Selecting the X-axis or Y-axis options from this submenu removes either the X axis of the upper plot(s) or the Y axis of the rightmost plot(s) respectively. Note: this option does not rescale the plot data, so make sure that the original axes scales for all the plots are identical.

Make Same

  Resizes all the selected objects in the chosen dimension(s) to match the dimension(s) of the view object from which the context menu was invoked. For example, right-clicking on a plot in the group and selecting Make Same Width will match the width of all the plots in the group to the width of the first plot. If Size is chosen, both the width and height of each object in the selection will change.

Align

  Aligns all objects in the selection to the object directly underneath the context menu. Select from Left, Right, Top, or Bottom.

Pack (submenu)

  The Pack submenu contains two functions. Pack Horizontally divides the entire width of the object group evenly between the individual object widths, while Pack Vertically divides the entire height of the group evenly between the individual heights. Packing plots usually results in a staggered or checkered pattern. To align the plots in a grid, use the Cleanup Layout function of the layout mode context menu.

Group Objects

  Groups all the selected objects together. A group of view objects can be resized or moved as a whole in the same way the layout of a object can be changed. Grouped plots remain grouped even when not in layout mode, so the Maximize or Delete functions of the plot context menu can be used on an entire group of plots.

  To dissociate a group, simply right-click on the group and select Ungroup.

## View Tools

### Window Tabs

&kst; allows the use of tabs to organize plots into separate windows for efficient viewing and manipulation.

To switch between plot windows in tab page mode, you can click on the tabs corresponding to each window, as shown below.

Switching windows in tab page mode
Switching windows in tab page mode

- To create a new tab, select File New Tab, or right click on the tab bar and select New... from the tab context menu which appears.

- The tab context menu allows you to create, delete and rename tabs, as well as shift their order.

  Switching windows in tab page mode

### The Toolbar

The toolbar provides quick access to commonly used menu functions in &kst;. To toggle the toolbar, select Settings Show Toolbar.

Toolbar

The toolbar menu, accessible by right-clicking anywhere on the toolbar, contains options for modifying the appearance and location of the toolbar.

### Assign Curve Color From File

This dialog allows you to assign colors to curves based on the file from which their data originates. You can access it by selecting the Tools Assign Curve Color From File...

The dialog will present a list of currently used data files and colour choices. Select the colours you would like, and choose the X Vector/Y Vector radio button based on whether you would like the curves colored based on the data file of their X or Y vector if the X and Y vectors for a curve come from two different data files. Then click OK.

If Apply to new curves is checked, then the chosen color pattern will also apply to curves that will be constructed later form those data files.

### Differentiate Between Curves

This dialog allows you to easily make plotted curves visually differentiable by cycling through their style, color, and width properties. You can access it by selecting the Tools Differentiate Between Curves...

To use this dialog, move some subset of the curve properties into the selected list. They will be cycled through in the order they appear in the selected list.

When cycling through Line Width, a maximum Line width must be set. The curves will then cycle through width 1 and this maximum width.

The Repeat Across options allows you to have the differentiation performed separately for each plot (Single Plot), separately for each window (Single Window), or continuously through All Windows.

The Apply to options allow you to determine whether the differentiation will be performed in All Windows, or only the Current Window.

Click OK or Apply to perform the differentiation, or Cancel to abort.