Karma Home Page
Next: Advanced Examples Up: Karma Programming Manual Previous: Multi-Threading

# Widget Library

# Purpose

The Karma widgets library is a set of Xt Intrinsics widgets which is intended to tie the Karma graphics library into a Graphical User Interface implemented by one or more third-party widget libraries. The tedious details of geometry management and event insertion into the Karma graphics library is solved by a range of display widgets. Advanced dynamic colourmap control and other user interface widgets are also provided.

# Related documents

The documentation on image display, communications support, colourmap support and image editing support are highly recommended. The reader may also want to become familiar with Xt Intrinsics and widget libraries in general. The reference manual is also required.

# Architecture

The Karma widgets library is distinct from the rest of the library in that it is not so clearly layered. There is no naming convention to determine the level a package/routine is in, and hence it's power. Furthermore, widgets are free to draw upon the resources of packages at any level in the rest of the library. Basic information about what each widget provides is given below. The reference manual lists all the resources for each widget, giving the name, class, representation type and default value.

# AnimateControl widget

The AnimateControl widget provides various buttons, sliders and value widgets to assist an application to animate through a sequence of images or graphics. Used in the ImageDisplay widget.

## Resources

- XkwNnumFrames The number of frames in the movie
- XkwNstartFrame The starting frame number
- XkwNendFrame The end frame number
- XkwNcurrentFrame The current frame number
- XkwNnewFrameCallback The callback when a new frame should be displayed

## User Description

This widget controls movie loops. It allows the user to control the speed and direction of movies, as well as the ability to skip frames. The following controls are provided:

- Close close the window
- Previous Frame show the previous frame
- Next Frame show the next frame
- Start Movie start the movie
- Stop Movie stop the movie
- Sync wait for each frame to be drawn before sending the next draw request. Normally, this is enabled. You can make movies run a little bit faster (not much) by disabling this, but you run the risk of developing a backlog of display requests in the display machinary. A large backlog will make the interactive response extremely poor
- Spin Mode you can select forward or backward spin, or alternatively spin forwards->backwards->forwards->...
- Anti Flicker remove the flicker observed when overlays (i.e. contours and/or annotations) and/or axis labels are shown. This is normally disabled because it slows down movie playing and interactive display updates. Also, flicker is only noticeable under some conditions (complex overlays and/or slow display hardware)
- Frame Interval the time interval between between frame draws. A low interval will give fast movies
- Skip Factor allows you to skip frames. A skip factor of 2 would skip every second frame
- Goto Frame jump to the frame number shown in the Current Frame control
- Current Frame the current frame number
- Starting Frame the starting frame number in the movie loop
- End Frame the end frame number in the movie loop

You can also step through the cube by clicking (left) for the previous frame or click (right) for the next frame in the black rectangle which appears below the Goto Frame button. In addition, you can click (middle) and drag in this black rectangle, allowing you to dynamically slide through the movie.

A screen snapshot is available here.

# Canvas widget

The Canvas widget is the fundamental link between Xt Intrinsics and the Karma graphics library. It provides geometry management and event insertion from the Xt world into a Karma pixel canvas. The pixel canvas is managed by the widget. The visual type of the underlying X window (and hence the pixel canvas) may be specified at creation (the default is to copy the parent window visual). On display hardware which supports stereoscopic display, a stereo canvas may be created if requested, rather than a regular canvas. A stereo canvas has a left and right pixel canvas created, rather than a monoscopic (normal) pixel canvas. A set of Canvas widgets may be created by creating one MultiCanvas widget. Please read the section on the MultiCanvas widget.

## Resources

- XtNvisual The visual type
- XkwNstereoMode The desired stereo mode
- XkwNverticalSplit If TRUE use a vertical split for split stereo mode
- XkwNsplitSeparation Separation between the split stereo canvasses
- XkwNmonoPixCanvas The monoscopic pixel canvas
- XkwNleftPixCanvas The stereoscopic left pixel canvas
- XkwNrightPixCanvas The stereoscopic right pixel canvas
- XkwNclipEvents If TRUE clip events to pixel canvas boundary
- XkwNsilenceUnconsumed If TRUE do not report unconsumed events
- XtNforeground The foreground pixel
- XkwNforceNewCmap If TRUE force a new colourmap
- XkwNretainFgBg If TRUE copy the foreground and background colours
- XkwNrealiseCallback The realise callback
- XtNfont The font
- XkwNverbose If TRUE verbose messages are displayed

## User Description

All drawing operations in Karma tools are performed on a ``canvas'', which is usually a big plain black or white rectangle.

The canvas allows you to freeze ``mouse move'' operations (i.e. things which happen in response to your moving the mouse over the window, but not while pressing any mouse buttons or keyboard keys). This is useful when you have pointed at a certain place, and want to maintain a position or profile display while you move the mouse to some other window (perhaps to print the window). All you need to do is press the spacebar, and any further mouse moves are ignored. If you press the spacebar again the mouse moves once again do something. So that you don't forget that mouse moves are disabled, you will hear a quiet beep every time you move the mouse into the window.

Similar to above, except that when pressing any mouse buttons or keyboard keys the freeze position is used, rather than the real position of the mouse.

# ChoiceMenu widget

The ChoiceMenu widget is an easy to construct non-exclusive menu widget. There is no state associated with the widget. This widget is most useful for grouping together a set of related functions.

## Resources

- XkwNmenuTitle The title to appear above the menu
- XkwNitemStrings The array of menu item strings (the choices)
- XkwNnumItems The number of items (choices) in the menu
- XkwNselectCallback The callback when a choice is selected

# ContourSimpleControl widget

The ContourSimpleControl wigdet allows the user to manipulate the display of a contour image.

## Resources

- XkwNiarray The Intelligent Array

# Cmapwin widget

The Cmapwin wigdet is a colourmap manipulation widget for PseudoColour visuals. Very handy for applications which require dynamic colourmap control. This widget is really a building block for the Cmapwinpopup (section 13.9.2) widget.

## Resources

- XkwNcolourbarVisual The visual for the colourbar
- XkwNcolourCallback The callback when the thumb is moved
- XkwNkarmaColourmap The Karma colourmap (<-kcmap->) object
- XkwNregenerateColourmap Set to TRUE to regenerate the colourmap
- XkwNsimpleColourbar If TRUE, a colourbar without a thumb is drawn
- XkwNdisableScaleSliders If TRUE, do not show the RGB scale sliders

# Cmapwinpopup widget

The Cmapwinpopup is the real colourmap widget that people use: it comes in it's own popup window. Hence it's name.

## Resources

- XkwNcolourbarVisual The visual for the colourbar
- XkwNkarmaColourmap The Karma colourmap (<-kcmap->) object
- XkwNsimpleColourbar If TRUE, a colourbar without a thumb is drawn

## User Description

This widget controls a colourtable for a ``PseudoColour'' display canvas. Data values are used to index into a table of colours. This is typically used for ``false colour'' image display. The following controls are provided:

- Close close the window
- Reverse this reverses the colour table; the colours of the minimum and maximum are swapped
- Invert this inverts every colour (e.g. white becomes black, green becomes purple, blue becomes yellow and so on)
- Save this brings up a popup window which allows you to save a colourtable
- Load this brings up a file browser popup which allows you to load a previously saved colourtable

You can manipulate the colours in the colourtable by moving the round dot in the big square box (left mouse button). Usually moving the dot horizontally changes the apparent position of the colours, while moving it vertically changes the range of colours.

There are many ``colour functions'' available to set the colourmap, the default one being ``Greyscale1''. Some colour functions produce smoothly-varying colourtables, while others have sharp boundaries.

A final way of manipulating the colourtable is provided by the Red Scale, Green Scale and Blue Scale sliders. With these you can turn down the amount of each primary colour for all the colours in the colourtable.

A screen snapshot is available here.

# DataBrowser widget

The DataBrowser widget manages the display configuration for multiple datasets.

## Resources

- XtNx The horizontal position to place the widget at
- XtNy The vertical position to place the widget at

## User Description

This widget provides controls for managing the display of multiple datasets.

A screen snapshot is available here.

The controls provided are:

### Browser Controls

- Close this will close the window
- Destroy the blink-state that the browser is showing is destroyed. It is not possible to destroy the first blink-state for the display window
- Copy create a new blink-state (and browser) which has the same configuration as the currently viewed blink-state. In `all` mode, the browser for the new blink-state is popped up
- Show menu gives control over how the various blink-states are displayed. The following modes are available:
  - all each blink-state is viewed in its own browser
  - some each display window has a single browser, which can be switched to display any blink-state for the display window
- Data menu selects which kind of data is displayed in the browser. The choices are:
  - Arrays gridded array data (can be viewed as images or contours)
  - Annotations text and geometric figures which can be overlaid for annotation purposes
- Advanced this will raise the advanced control panel
- Make Data this will raise the make data control panel

### Data List

Beneath these general controls, the list of loaded data appears. Each line shows the name and a summary of the configuration settings for that dataset. The list section is different for each data type. There are common operations that may be performed irrespective of data type, which are described here.

There is always a highlighted line, which shows which entry you can make changes to (using either the mouse buttons or the keyboard). The highlighted line is shown by a slightly different background colour. You can change the highlighted line by using the mouse or up/down arrow keys.

There is also a selected line, which shows which entry has more detail shown in the section(s) below. The list section only shows a summary of the current configuration for each dataset. The selected line is shown by using reverse video.

If the browser is in active mode (the default), then the selected line is locked to the highlighted line. If in passive mode, the selected line does not move until you explicitly select an entry.

If you select an entry while in active mode, the browser switches to passive mode. If in passive mode and you select the already selected entry, the browser switches to active mode.

As the mouse is moved over the data names, one of the names will be highlighted. The mouse and keyboard may be pressed to control the settings of the highlighted data. The following bindings are available:

- Left Mouse select the highlighted dataset for display in the sections below, and disable active mode. If the data is already selected and active mode is disabled, active mode is enabled
- Spacebar same effect as left mouse button
- Up Arrow highlight and select the previous data
- Down Arrow highlight and select the next data
- = (equals sign) selects this dataset for replacement, copying all data attributes
- (tilde sign) selects this dataset for replacement without attribute copying

There are other key bindings which are independent of which dataset the mouse is highlighting:

- Left Arrow cycle backwards in the list of blink-states for the same window (in `Some` or `One` modes). Has no effect in `All` mode)
- Right Arrow as above, but cycle forwards
- Shift Left Arrow similar to `Left Arrow`, but also make the blink-state active
- Shift Right Arrow similar to `Right Arrow`, but also make the blink-state active
- Control Left Arrow cycle backwards to the last browser for the previous display window (`One` mode). Has no effect in other modes
- Control Right Arrow cycle forwards to the first browser for the next display window (`One` mode). Has no effect in other modes
- Shift Control Left Arrow similar to `Control Left Arrow`, but also make the blink-state active
- Shift Control Right Arrow similar to `Control Right Arrow`, but also make the blink-state active
- b key blink the display window to the next browser for this display window
- B key make the currently viewed blink-state active
- > key blink the display window to the next browser for this display window
- < key blink the display window to the next browser for this display window

The list section will show single character codes in a number of columns to the left of the data entry names. Different data types will show a different number of columns, and the character codes have different meanings as well. However following convention is followed:

- = (equals sign) this dataset has been selected for replacement with data attribute copying
- (tilde sign) this dataset has been selected for replacement without attribute copying
- uppercase this is an exclusive option: only one entry may have this option set per blink-state
- lowercase non-inclusive option. Any number of entries may have this option set

Below the list of data, more detailed information and configuration settings are shown. The appearance depends on the kind of data being shown.

The configuration controls for the different data types are described below.

### Data Replacement

As discussed above, a dataset may be selected for replacement. When a new dataset is loaded, the list of already loaded datasets is scanned for a dataset which has been selected for replacement, and was loaded from the same data source. A typical data source is a file browser, but may also include network connections. When a dataset is replaced with a new one, either all the old settings (such as intensity range, contour levels, etc.) are retained or none of the settings are retained, depending on which replacement mode was selected.

If more than one dataset is selected for replacement, and these datasets were loaded from the same data source, the selected dataset closest to the top of the list is replaced.

Note that if a data source is removed (e.g. a file browser is destroyed), then datasets loaded via that data source can no longer be replaced. These datasets can still be explicitly unloaded, however.

### Array List

There are several columns used to display a summary of the configuration, using a simple legend. These are described below:

- Image Column shows which dataset(s) contribute to the displayed image. These are exclusive settings. The legend is:
  - I show this array as the image
  - A this array is the "alternate image" for intensity-intensity scatter plot computation hue-intensity
- Contour Column shows which datasets are displayed as contours. These are non-exclusive settings. The legend is:
  - c show this array as a normal contour map
  - r show this array as a Renzogram (only for cubes)
- Movie Column shows which datasets can be shown as a movie. The legend is:
  - M enable movie controls for this array
  - m slave this array to the movie controls
- Profile Column shows which datasets can be shown as profiles. The legend is:
  - P display line profiles of this array (this array controls the axis labelling and is drawn on top)
  - p display line profiles of this array

The following keyboard and mouse bindings are available to quickly control the configuration:

- Middle Mouse show as the image, the previous image becomes the "alternate image". If already displayed as the image, disable image display
- Right Mouse toggle between enabling and disabling contour display
- i key same effect as the middle mouse button
- control-i make the next dataset in the list the currently displayed image. This will cycle back to the top of the list when the end is reached
- control-shift-i make the previous dataset in the list the currently displayed image. This will cycle back to the end of the list when the top is reached
- a key make this image the "alternate image"
- c key same effect as the right mouse button
- r key toggle between enabling and disabling Renzogram display
- control-c enable contours and apply levels
- control-r enable Renzogram and apply level
- M key enable movie controls for this array
- m key slave this array to the movie controls
- P key display line profiles of this array (this array controls the axis labelling and is drawn on top)
- p key display line profiles of this array

### Detailed Array Information

This shows information about the array, such as the directory from where the array was loaded, the format of the data (i.e. FITS, AIPS, Miriad, Gipsy and many more), the size and dimensionality and the range of data values. The following control buttons are available:

- Histogram pop up a histogram for this array. The histogram display can be used to control the intensity range for this array
- Clone create a virtual copy of the array, which will have independent configuration settings. Note that the data are not copied, instead a reference is made
- Unload unload the array

Note that these operations affect all browsers/blink-states and all display windows.

### Array Configuration

How to display an array is controlled via this section. Some controls are per blink-state, while others are global and apply to all blink-states and all display windows. The following controls are per blink-state:

- Image menu. The choices are:
  - off the array is not selected for image display
  - main the array is selected for normal image display
  - alt the array is the ``alternate'' image for computing intensity-intensity scatter plots
- Contour menu. The choices are:
  - off the array is not displayed as contours
  - map the array is shown as normal contours
  - renzo the array is shown as a ``Renzogram''
- Movie menu. The choices are:
  - off the array will not be shown as a movie
  - master the array is shown as a movie and controls the frames
  - slave the array is shown as a movie and is slaved to the master

The following controls are global to the application, and affect all blink-states and display windows:

- Low the low end of the intensity range
- High the high end of the intensity range
- Map Contour Levels the contour levels for normal contours. The syntax for the contour levels is as follows:

  - just type the levels you want e.g. `0.001 0.002 0.003 0.004`
  - levels with a constant increment: `0.001:0.004+0.001` means that the first level is `0.001`, that this level is incremented with `0.001` until `0.004` is reached. So this example gives the same levels as in the first case
  - levels incremented by a factor: `0.001:0.016*2`. This gives levels `0.001 0.002 0.004 0.008 0.016`
  - levels as percentage of the peak: first character should be %, numbers are taken as percentage, the rest of the syntax is as above, e.g. %10:40+10 gives 10, 20, 30 and 40 % of the maximum of the data
  - the special values `min` and `max` indicate the minimum and maximum value

  These options can be mixed, i.e. `-0.03:-0.01+0.01 0.003:0.1+0.02 0.2 0.3` is interpreted correctly. You should press the enter key for your changes to take effect

- -ve Cont. Width the width of negative contour levels
- +ve Cont. Width the width of positive contour levels
- -Colour the colour of negative contour levels
- +Colour the colour of positive contour levels
- Renzo Contour Levels the contour levels for Renzograms. The syntax is the same as for the contour levels
- Renzogram Channels the channels (along the unseen axis) to display in the Renzogram. The syntax is similar as for the contour levels, except that a leading ``I'' or ``W'' must be given. Again, press the enter key for your changes to take effect. These leading characters have the following meaning:
  - I specify channel Indices. Thus `Imin:max+1` selects channels between channel 0 (the first) and the last channel, in single channel increments (i.e. all channels). For example, if you wanted to display channels 10 to 20 inclusive, type: `I10:20+1`
  - W specify World co-ordinates (i.e. velocity in m/s or frequency in Hz). For example, if you wanted to show channels between 1418 and 1420 MHz, in 100 KHz steps, type: `W1418e6:1420e6+1e5`
- Profile menu. The choices are:
  - off the array will not be shown as a profile
  - master the array is shown as a profile, is drawn on top and controls the axis labels
  - slave the array is shown as a profile and is slaved to the master
- Dark the colour to use for profile display. This must be a dark colour, appropriate for display on light backgrounds (i.e. white paper)
- Light the colour to use for profile display. This must be a light colour, appropriate for display on dark backgrounds (i.e. a computer monitor)

### Advanced Control Panel

This control panel allows you to control some extra aspects of the behaviour of all data browsers. The following controls are available:

- Close this will close the window
- Clip Mode menu controls how changes in the low and high clip levels affect display windows. The following modes are available:
  - Image and Profiles the image intensity range and profile vertical range are synchronised and clip level changes affect both
  - Images only only the image intensity range is affected by clip level changes
  - Profiles only only the profile vertical range is affected by clip level changes
  - Both later the image intensity range and profile vertical range are affected by subsequent clip level changes, but they are not immediately synchronised
- Range changes affect all arrays if this is turned on, an attempt to change the clip levels of any array dataset will change the clip levels for all array datasets
- Make slaved movie on load if this is turned on, an array dataset with three or more dimensions will be automatically marked as a movie slave when loaded
- Activate annotations on load if this is turned on, an annotation dataset is automatically made active (i.e. displayed) when loaded
- Slave Profile H-range to image window if this is turned on, the horizontal range of the profile window is set to the same as the horizontal range of the image window if the the axes correspond
- Show new data as Image if this is turned on, an array dataset is marked as the active image when loaded

### Make Data Control Panel

This control panel allows you to create new array data from existing array data. This is useful if you want to combine data together. The following controls are available:

- Close this will close the window
- Algorithm menu controls how data arrays are combined. The following modes are available:
  - RGB combine one, two or three datasets into an RGB (red, green and blue) array. Each colour component is 8 bits, yielding a 24 bit array. The input values between the low and high clip are linearly scaled into the output. If the clip values on an input array are subsequently changed, the RGB image is rescaled. The following bindings are available:
    - R use this dataset as the red colour component
    - G use this dataset as the green colour component
    - B use this dataset as the blue colour component
    - Left Mouse use this dataset as the red colour component
    - Middle Mouse use this dataset as the green colour component
    - Right Mouse use this dataset as the blue colour component
    - # use this dataset as the grid template
  - Arithmetic combine multiple datasets using simple arithmetic (addition, subtraction, multiplication or division). The output dataset is computed by processing the list of datasets from top to bottom, applying the specified arithmetic operations for selected datasets. Before processing any datasets, the output dataset is initialised to either zeros (if the first operator is addition or subtraction) or ones (if the first operator is multiplication or division). The following bindings are available:
    - + add this dataset to the output dataset
    - - subtract this dataset from the output dataset
    - * multiply the output dataset by this dataset
    - / divide the output dataset by this dataset
  - Hue Intensity combine two datasets into a Hue-Intensity array. The two datasets may be directly mapped to intensity and hue, or they can represent a complex image. The real and imaginary components will be in separate datasets and they are converted to amplitude and phase values, which are then mapped to intensity and hue. The following bindings are available:
    - B use this dataset as the brightness (intensity) component
    - H use this dataset as the hue (colour) component
    - R use this dataset as the real component
    - I use this dataset as the imaginary component
    - Left Mouse use this dataset as the brightness component
    - Middle Mouse use this dataset as the hue component
    - Right Mouse use this dataset as the grid template
    - # use this dataset as the grid template
- the dataset list shows the available datasets. This is used to mark which datasets are used as inputs to the combining process. This list has a similar interface as the dataset list in the data browser. Note that in most cases, a dataset can only be marked once. If you need to mark a dataset for multiple purposes (such as to use it for both red and green inputs), you will need to clone the dataset first
- Name this allows you to specify the name for the new dataset. A default name is provided
- Make this will create the new dataset, based on the selections you have made. This could take some time, depending on how large the input datasets are

### Annotation List

There is just one column used to display a summary of the configuration. The `a` character is used to indicate whether a annotation file is active (visible) or not. The `a` key may be used to switch between the two states. The middle mouse button has the same effect of switching between the two states.

### Detailed Annotation Information

This shows where directory from which the annotation file was loaded. the `Unload` button may be used to unload the annotation file. This affects all blink-states and display windows.

### Annotation Configuration

The `Active` toggle may be used to switch between active (visible) and inactive settings for this annotation file.

# Dataclip widget

The Dataclip widget computes and displays the histogram of a n-dimensional Intelligent Array. The user may then define a region on that widget and have the co-ordinates of the region passed to a callback function. Handy for segmenting data by value, rather than position.

## Resources

- XkwNmaxDataRegions The maximum number of data regions
- XkwNregionCallback The callback when regions change
- XkwNshowBlankControl If TRUE show the "Blank" button
- XkwNfixedOutputType Specify a fixed output type
- XkwNverbose If TRUE verbose messages are enabled
- XkwNautoPopdown If TRUE widget is popped down on array deallocation

## User Description

This widget allows the user to specify a number of data ``regions'' (ranges). It it most often used to give control over a single region, so that an intensity range may be specified. The widget displays a histogram of the data values in the array, with the vertical axis being logarithmic. The following controls are provided:

- Close close the window
- Blank enable to blank data outside specified region (not all applications will show this toggle)
- Zoom zoom the histogram display to the range of the current region
- Unzoom unzoom the histogram display to the full range of the data
- Apply apply any changes made to the regions (most applications will then rescale and display their main image)
- Auto Apply enable this to automatically apply every change as they are made
- Subset enable this to use only a subset of the input data. This will speed up the histogram computation, and may avoid unwanted outlier values
- Full Range set the region to the full range of the data
- 95% set the region to clip to the inner 95% of the data values (i.e. clip the lower 5% and upper 5% of the data values). This is very handy when your data contains ``outliers'' (small numbers of data values which lie far away from the real data)
- 98% set the region to clip to the inner 98% of the data values
- 99% set the region to clip to the inner 99% of the data values
- 99.5% set the region to clip to the inner 99.5% of the data values
- 99.9% set the region to clip to the inner 99.9% of the data values
- 99.99% set the region to clip to the inner 99.99% of the data values
- Save save a new file which has been clipped to the specified range
- Output Type Menu change the output type of the array to save (not all applications will show this menu)
- Filename string the name of the file which will be saved. This may be changed prior to saving

If you click with the left mouse button in the histogram display, you define the lower boundary of a region. If no region exists, one is created. If you then click with the right mouse button, the upper boundary is defined. Once the lower and upper boundaries are defined, you will see two vertical lines depicting the boundaries, with two diagonal lines joining them. You will also see a circle, the height of which indicates the width of the region relative to the width of the entire histogram. If you click with the middle mouse button, the horizontal cursor position will control the midpoint of the region (i.e. change the lower and upper boundaries at the same time), and the vertical cursor position changes the width of the region. You can drag any of the three mouse buttons to see things continuously change.

If you have not yet defined a region, you may first click with the right button to define the upper boundary. The lower boundary is automatically set to the data minimum. This is a convenience facility when you want to set the lower boundary to the data minimum and set the upper boundary manually. You can get the same effect by pressing Full Range first and then clicking with the right button.

A screen snapshot is available here.

# Dialogpopup widget

The Dialogpopup widget is a simple dialog widget (text entry) which has it's own window. Good for implementing a last-minute filename query before doing something (like saving data to a file). The widget can choose filenames which do not already exist.

## Resources

- XtNcallback The callback when the "ok" button is pressed
- XtNlabel The filename dialog label
- XkwNdefaultName The default filename
- XkwNextension The filename extension
- XkwNshowAutoIncrement If TRUE show the "Auto Increment" toggle

# DirectCmapwin widget

The DirectCmapwin widget is a colourmap manipulation widget for DirectColour visuals. Very handy for applications which require dynamic colourmap control. This widget is really a building block for the Cmapwinpopup (section 13.9.2) widget.

## Resources

- XkwNcolourbarVisual The visual for the colourbar
- XkwNkarmaColourmap The Karma colourmap (<-kcmap->) object
- XkwNregenerateColourmap Set to TRUE to regenerate the colourmap

# DressingControl widget

The DressingControl widget controls the axis labelling for a number of world canvases (see the canvas package).

## Resources

- XkwNcanvases The NULL-terminated array of <-canvas-> objects

## User Description

This widget controls the way axis labels are drawn onto a canvas. The following controls are available:

- Close this will close the window
- Enable if enabled, the axis labels are displayed
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Show Labels if enabled, the axis names are displayed
- Show Scale if enabled, the scale values corresponding to major tick marks are displayed
- Show Top Tick Marks if enabled, the tick marks at the top of the window are displayed
- Show Bottom Tick Marks if enabled, the tick marks at the bottom of the window are displayed
- Show Left Tick Marks if enabled, the tick marks at the left of the window are displayed
- Show Right Tick Marks if enabled, the tick marks at the right of the window are displayed
- Internal Ticks if enabled (the default), the tick marks are placed inside the bounding box, otherwise they are placed outside
- Grid Lines if enabled, the co-ordinate grid is shown
- Screen Colours pressing this will set the background colour of the window to black and the colour of the axis labels to green. If a colourmap is associated with the window, it's Reverse option is turned off
- Paper Colours pressing this will set the background colour of the window to white and the colour of the axis labels to black. If a colourmap is associated with the window, it's Reverse option is turned on
- Change Colourmap if enabled, the Reverse option for the window colourmap Cmapwinpopup widget (section 13.9.2) is set when you press either Screen Colours or Paper Colours
- Show Colourbar if enabled, a colourbar is displayed. This shows the mapping between data value and colour. Note that currently only linear intensity scales are supported
- Font scale this slider allows you to enlarge or shrink the font scale for the labels

A further set of controls is provided under the red line (most of the time you will not need to use these):

- Background Colour the background colour of the window. You need to press the Apply button for your changes to take effect
- Label Colour the colour the labels are drawn in. You need to press the Apply button for your changes to take effect
- Grid Colour the colour the grid is drawn in

Note that the axis labelling currently does not handle co-ordinate systems which have rotations close to 90 degrees or 270 degrees.

A screen snapshot is available here.

# ExclusiveMenu widget

The ExclusiveMenu widget is another menu widget, but the choices are exclusive: i.e. only one choice is allowed at a time. Good for implementing a mode menu. The current choice is displayed at all times.

## Resources

- XkwNchoiceName The name of the choice menu
- XkwNitemStrings The array of menu item strings (the choices)
- XkwNnumItems The number of items (choices) in the menu
- XkwNselectCallback The callback when a choice is selected
- XkwNvaluePtr A value pointer to which the choice index is written
- XkwNsetChoice Set the current choice
- XkwNcallCallbacksOnSet If TRUE call callbacks on setting with setChoice
- XkwNcaseInsensitive If TRUE, setChoice is case insensitive

# ExportMenu widget

The ExportMenu widget is a widget to simplfy exporting of data from applications. A building block for the ImageDisplay widget.

## Resources

- XkwNiarray The Intelligent Array to export
- XkwNworldCanvas The KWorldCanvas (<-canvas->) to export from
- XkwNsupportSubsets If TRUE subset choices are shown
- XkwNlabel The label in the export button

## User Description

This widget allows you to export the currently displayed data to some other format. The following options are available:

- PostScript generate hardcopy output of the contents of the drawing canvas. This will pop up the Postscript widget (section 13.32.2)
- SunRasterfile export the currently viewed image to Sun Rasterfile format
- PPM Data Image export the currently viewed image data to PPM format. Non-image data (i.e. axis labels and annotations) are not exported. The output is at the resolution of the image data
- PPM Data Movie export the currently viewed cube data to PPM format, similar to `PPM Data Image`. One PPM file is written for each image along the unseen axis
- PPM Data Window export the contents of the window to PPM format. Non-image data (i.e. axis labels and annotations) are also exported. The output is at the resolution of the window, and yields higher quality than using a separate screen-capture tool
- Karma (whole dataset) export the currently viewed dataset to Karma format
- FITS (whole dataset) export the currently viewed dataset to FITS format
- Miriad (whole dataset) export the currently viewed dataset to Miriad Image format
- GIPSY (whole dataset) export the currently viewed dataset to GIPSY format
- Karma (subset) export the currently viewed (sub)image to Karma format. If the subimage being viewed is a cube, the subcube will be saved
- FITS (subset) export the currently viewed (sub)image to FITS format. If the subimage being viewed is a cube, the subcube will be saved
- Miriad Image (subset) export the currently viewed (sub)image to Miriad Image format. If the subimage being viewed is a cube, the subcube will be saved
- GIPSY (subset) export the currently viewed (sub)image to GIPSY format. If the subimage being viewed is a cube, the subcube will be saved

# Filepopup widget

The Filepopup widget is a directory browser and file selector widget. You can specify a filename pattern matching/rejecting routine. A callback is called when the user selects a file. The user can also navigate up and down the directory tree. This widget has it's own window.

## Resources

- XkwNautoPopdown If TRUE, the window is closed upon file selection
- XkwNfileSelectCallback Callbacks for file selection
- XkwNfilenameTester Callbacks to test filenames
- XkwNloadFiles If TRUE, files are automatically loaded upon selection
- XkwNpreferFloat If TRUE, try to convert files to type K_FLOAT
- XtNx The horizontal position to place the widget at
- XtNy The vertical position to place the widget at

## User Description

This widget allows the user to browse a directory tree and select files. All the files and directories the application wants the user to see are displayed. Any one of these may be selected by clicking the left mouse button over the filename. The ``D'' character is used to denote directories, while the ``F'' character is used to denote ordinary files. Above the list of files and directories is shown the current directory for the browser. If you edit the text and press return the current directory is changed appropriately. The ``'' notation is supported, as well as other simple Bourne Shell-like expansions of environment variables using the `$variable`, `${variable}` and `${variable:-word}` notations. The following controls are provided:

- close close the window
- rescan rescan the directory in case a new file has appeared
- pin enable to force the fileselector window to stay ``pinned'' up even if files are selected. The default is to close the window once a file is selected
- new create a new file browser. The current directory will be independent of the original file browser
- filter if enabled, selected files are not automatically loaded, rather, the LoadAndDecimate widget (section 13.25.2) is displayed

- partial if enabled, support loading of partial files. This is useful if you want to see a preview of a dataset that is currently being written by another process. See the section on partialdata data in the Karma User Manual
- writable if enabled, the file may be modified later (i.e. by the image editing facility)
- pull change the directory in this browser to match the most recent directory change in any browser (i.e. pull the most recent directory change)
- push change the directory in all other browsers to match the directory for this browser (i.e. push this directory to others)

Convenience buttons for jumping to commonly-used directories may be configured by the local Karma administrator or by the user. The following files are searched:

- `$KARMABASE/share/browser-dirbuttons`
- `$KARMABASE/site/share/browser-dirbuttons`
- `$HOME/.karma/browser-dirbuttons`

in that order. The format of this file is a sequence of ASCII lines, with each line containing the name of the button followed by the directory to jump to. For example:

    survey  /nfs/survey
    mydata  /nfs/data1/users/fred

A screen snapshot is available here.

This widget supports the following extensions:

- WidgetInitialise

# Filewin widget

The Filewin widget is the building block for the Filepopup (section 13.17.2) widget: it needs a window around it.

## Resources

- XkwNfileSelectCallback Callbacks for file selection
- XkwNfilenameTester Callbacks to test filenames
- XtNforeground The foreground pixel
- XkwNforwardSyntheticEvents Forward synthetic events
- XkwNtrapDirectoryDatasets Trap directories which are known dataset types

# Hdial widget

The Hdial widget is made to look a bit like an old-style tuning knob.

## Resources

- XtNforeground The foreground pixel
- XtNlabelForeground The foreground pixel for the label
- XtNfont The font to use
- XtNminimum The minimum value
- XtNmaximum The maximum value
- XtNvalue The current value
- XtNincrementCallback Callbacks when the value increments
- XtNdecrementCallback Callbacks when the value decrements
- XtNvalueChangeCallback Callbacks when the the value is changed
- XtNmargin The margin in pixels

# ImageDisplay widget

The ImageDisplay widget is the all singing, all dancing display widget. It does practically everything but choose the data you want to display. It comes with the following widgets: Filepopup (section 13.17.2), Cmapwinpopup (section 13.9.2), Postscript (section 13.32.2), AnimateControl (section 13.4.2) and Dataclip (section 13.11.2). It also has zoom controls.

## Resources

- XkwNpseudoColourCanvas The PseudoColour world canvas
- XkwNdirectColourCanvas The DirectColour world canvas
- XkwNtrueColourCanvas The TrueColour world canvas
- XkwNpseudoColourLeftCanvas The PseudoColour left world canvas
- XkwNpseudoColourRightCanvas The PseudoColour right world canvas
- XkwNdirectColourLeftCanvas The DirectColour left world canvas
- XkwNdirectColourRightCanvas The DirectColour right world canvas
- XkwNtrueColourLeftCanvas The TrueColour left world canvas
- XkwNtrueColourRightCanvas The TrueColour right world canvas
- XkwNvisibleCanvas The visible world canvas
- XkwNmagnifier The magnifier popup
- XkwNimageName The name of the image being shown
- XkwNenableAnimation If TRUE the <-AnimateControl-> widget is created
- XkwNshowAnimateButton If TRUE the "Movie" button is created
- XkwNshowQuitButton If TRUE the "Quit" button is created
- XkwNcmapSize The size of the PseudoColour colourmap
- XkwNcmapMaster The location of a colourmap master (server)
- XkwNfullscreen If TRUE the main window should be fullscreen
- XkwNnumTrackLabels The number of track labels
- XkwNview2Datasets If TRUE the <-View2Datasets-> widget is created
- XkwNnumDatasets The number of datasets
- XkwNmainRealisedCallback Callbacks when all main canvases are realised
- XkwNafterMainRealisedCallback Callbacks after <<XkwNmainRealisedCallback>> called
- XkwNdatasetNames The names of each dataset
- XkwNnewVisibleCanvasCallback Callbacks for when the visible canvas changes
- XkwNpanner The panner popup
- XkwNverbose If TRUE verbose output is generated

## User Description

Many of the visualisation tools have one or two very similar main windows. This is because they are all derived from the ImageDisplay widget, which provides most of the common functionality. Most of the tools which use this widget provide the following controls:

- Set1 sometimes labelled as Files, or Cubes this will popup up the Filepopup widget (section 13.17.2)
- Intensity menu, this will popup widgets to control the colourmap
  (Cmapwinpopup), intensity policy (IntensityPolicy) and intensity scaling (section 13.11.2)
- Zoom menu, this allows you to popup a magnifier or a panner, zoom the image in or out 2x or 4x, unzoom, or popup the ZoomPolicy widget (section 13.43.2)
- Overlays menu, this allows you to popup various control panels to control overlay display. The following choices are available:
  - Axis Labels this will popup controls for the axis labelling (section 13.14.2)
  - Load Annotations this will bring up a file browser to load a file of ASCII overlay commands. The file format is described in an appendix to the User Manual
  - Editor this will popup the OverlayEditorControl widget (section 13.29.2) which allows you to interactively draw overlays
  - Remove Last (connection) this will remove the last overlay object sent via a network connection
  - Remove All (connection) this will remove all overlay objects sent via a network connection
  - Contours this will pop up a file browser which allows you to load an image and display it as contours. You can load an unlimited number of images this way
- Export menu, you can export data in a variety of formats. See section 13.16.2
- View this will popup a control panel used for displaying two datasets (section 13.42.2). This is only available in tools like <kvis> and <MultibeamView>
- Edit this will popup the ImageEditorControl widget (section 13.21.2) which allows you to interactively edit image data
- Quit this will quit the application
- Set2 sometimes labelled as Images this will popup up the Filepopup widget (section 13.17.2)

You will also see a few lines of display under the control buttons, which gives information about the data under the current cursor position.

A screen snapshot is available here.

### The Magnifier

Wherever you move the mouse over the main image, you will see a magnified portion of that part of the image (the magnification is 4x the data resolution). You can resize the magnifier window.

### The Panner

Simply click with the left mouse button in the panner window and the main window will pan to the desired location. The panner window will display a green rectangle showing you where you have panned to, relative to the entire image. You can resize the panner window. When you select the panner from the Intensity menu, the panner is popped up and the main window is set to panning mode.

### Zooming in the ImageDisplay Widget

To zoom an image, click (left) and drag the mouse (still keeping the left button down) across the window. You will see a ``rubber-banded'' box stretching between the first point and the current mouse cursor position. When you release the button the section of the image within the box will be zoomed. To unzoom, choose the Unzoom option in the Zoom menu, or press the ``u'' key while the cursor is in the image window. This will show the entire image.

You can also press the ``i'' key (zoom in) and the image is zoomed 2x, with the new centre of the image being the position of the mouse when the ``i'' key was pressed. You can zoom in as many times as you like. To unzoom 2x, press the ``o'' key (zoom out). When unzooming it doesn't matter where the mouse is.

If you press and release the left mouse button without moving the mouse in between, the image will be panned so that what is under the mouse cursor is moved to the centre of the image. An extra facility in <kvis> and <MultibeamView> is the ability to zoom in and out using the middle and right mouse buttons, respectively, in a similar fashion to using the ``i'' and ``o'' keys.

Note that these zoom controls are not available when you place the main window in panning mode.

Another key you can press is ``r'' which simply refreshes the window, without changing the zoom area.

### Image Statistics in the ImageDisplay Widget

Many programmes have a facility to compute and display the statistics of the current (sub)image being viewed. Simply press the ``s'' key in the display window and you will see a summary of the image statistics in the terminal window. This summary includes the number of (non-blank) values, the standard deviation, the mean, minimum, maximum and sum value. Alternatively, you can click (left) and drag the mouse to a new position (still holding the mouse down!) and press the ``s'' key. The statistics are computed over the boxed area. After you press ``s'' you may release the mouse button. This feature saves you from having to zoom in and unzoom every time you wish to compute statistics on a sub-image. Note that the old box remains on the image until something clears it (this is useful when you want to know which regions you have already computed statistics over).

The ``v'' key allows you to see the individual image pixel values, rather than their statistics. This works in a similar fashion to the ``s'' key. The ``V'' key is a variation which shows raw image pixel values. Note that if you press ``v'' or ``V'' without the mouse, all the pixels in the subimage being viewed would be printed. Since this can take a long time with a large number of pixels, a warning message is issued if you attempt this with many pixels. If you definately want to display a large number of pixels, press the control key at the same time.

### Viewing Header Information in the ImageDisplay Widget

Many programmes allow you to inspect the header of the dataset you are currently viewing as an image. Simply press the ``h'' key and the header will be displayed in the terminal window. If you press the ``H'' key, you will get the header without the history.

### Capturing Co-ordinate positions in the ImageDisplay Widget

Many programmes allow you to capture the current world co-ordinate position of the mouse, by pressing the ``l'' key in the image window. The output is set to the standard output, which you may redirect to a file prior to starting the programme.

# ImageEditorControl widget

The ImageEditorControl widget is a control panel for interactively editing an image. It uses a simple painting model.

## Resources

- Xdummy Ignore

## User Description

This widget allows you to interactively edit images. It uses the iedit package which maintains a list of geometric figures which can be drawn and then applied to data.

The following controls are provided:

- Close this will close the window
- Undo Last will undo the last edit object that you drew from the list
- Undo All will undo all edit objects from the list
- Apply apply the edit objects to the data (after this you can no longer undo previous edits)
- Brush Width the width of the paint brush in pixels
- Paint Value the data value to paint with
- Minimum set the data value to paint with to the current minimum (clip) value for the display canvas
- Middle set the data value to paint with to halfway between the current minimum and maximum (clip) values for the display canvas
- Maximum set the data value to paint with to the current maximum (clip) value for the display canvas

This widget uses the middle mouse button for its drawing functions. Some tools may already be using this button for other purposes, in which case the tool should provide a control which allows you to disable the normal use of the middle mouse button. For instance, the <kvis> programme provides such a control through the ZoomPolicy widget (section 13.43.2).

The drawing interface is the same as for the OverlayEditorControl widget (section 13.29.2).

# Increment widget

The Increment widget is a simple widget with a ``+'', ``-'' buttons and a value display.

## Resources

- XkwNvalueChangeCallback Callbacks when value changes
- XkwNlist The list
- XkwNindex The index
- XkwNlabel The label

# IntensityPolicy widget

The IntensityPolicy widget controls the intensity policy of a set of KWorldCanvas objects (see the canvas package).

## Resources

- XkwNcanvases The NULL-terminated array of canvases
- XkwNautoIntensityScale The default state of "Auto Intensity Scale"
- XkwNshowIntensityReset If TRUE create the intensity reset toggle

## User Description

This widget controls the intensity policy to be used for displaying image data on a drawing canvas. The following controls are provided:

- Close this will close the window
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Auto Intensity Scale if enabled, the intensity range of the (sub)image being viewed is mapped onto the colourmap, otherwise the intensity range of the entire image/movie is mapped onto the colourmap
- Reset Intensity Upon File Load if enabled, the intensity scale is reset when a new dataset is loaded (it is reset to the full data range). If disabled, the intensity scale is not changed on file load
- Intensity Scale Menu this menu allows you to change between different intensity scales. By default, the intensity scale is linear, but you can select a logarithmic intensity scale or a square-root intensity scale. If you are using a logarithmic intensity scale, you can set the Log Cycles value to control the visible dynamic range in powers of 10

A screen snapshot is available here.

# Ktoggle widget

The Ktoggle widget is a nice toggle widget which can show a cross or a tick to show it's state.

## Resources

- XtNstate The state of the toggle
- XtNradioGroup The radio group
- XtNradioData Data for the radio group
- XkwNcrosses If TRUE the off cross is shown
- XkwNcallCallbacksOnSet If TRUE call callbacks on setting with XtNstate

# LoadAndDecimate widget

The LoadAndDecimate widget allows you to load and decimate datacubes on the fly.

## Resources

- XkwNverbose If TRUE verbose messages are displayed

## User Description

This widget controls the process of loading and decimating a datacube. The user can skip/average data values along each dimension as well as extract a subcube. The following controls are provided:

- Cancel close the window
- Load load the file using the specified parameters
- Abort abort the loading process
- Auto Save if enabled, the decimated subcube is automatically saved to disc
- X Start select the starting position of the subcube in the X dimension
- Y Start select the starting position of the subcube in the Y dimension
- Z Start select the starting position of the subcube in the Z dimension
- X End select the end position of the subcube in the X dimension
- Y End select the end position of the subcube in the Y dimension
- Z End select the end position of the subcube in the Z dimension
- X Skip select the skip factor along the X dimension. The default value of 2 will make every 2 input values along X averaged together
- Y Skip select the skip factor along the Y dimension. The default value of 2 will make every 2 input values along Y averaged together
- Z Skip select the skip factor along the Z dimension. The default value of 2 will make every 2 input values along Z averaged together
- Output filename change this to select the name of the file which is saved to disc

Under the first row of buttons, the size of the file (in data elements) is displayed and the memory size required by the decimated subcube is displayed. Underneath these, the subcube bottom-left corner (BLC) and top-right corner (TRC) co-ordinates are displayed, and also the pixel increment (INC).

As you change the slider parameters, the memory requirement changes, as do the BLC, TRC and INC values, and these are reported to you. It is wise to not use more than about half the physical RAM (Random Access Memory) available in your machine.

As the file is loaded and decimated, a simple progress meter shows you how much longer you have to wait. Remember: you can always abort.

A screen snapshot is available here.

# MagnifierPopup widget

The MagnifierPopup widget is subclassed from the SlaveImageDisplayPopup widget. It will monitor mouse movement events on the canvases in the ancestor ImageDisplay widget and uses these events to control the display inside the magnifier window. It is the responsibility of the application to ensure display objects such as viewable images are maintained for the magnifier canvases.

This widget does not define any resources of its own, however it overrides the XkwNfastPanner resource of the SlaveImageDisplayPopup widget to set a default value of `False`.

This widget supports the following extensions:

- all_realised

## User Description

This widget is a subclass of the SlaveImageDisplayPopup widget.

# MomentGenerator widget

The MomentGenerator widget controls the generation of moment maps (the 0th and 1st moments are computed). You supply a 3-dimensional Intelligent Array and you get two 2-dimensional moment maps. The user can control clip levels and the type of algorithm used.

## Resources

- XkwNverbose If TRUE verbose messages are displayed
- XkwNmom0Array The internally created 0th moment Intelligent Array
- XkwNmom1Array The internally created 1st moment Intelligent Array
- XkwNmomentCallback Callbacks when the moment maps are (re)computed

## User Description

This widget allows the user to generate the 0th (total intensity) and 1st (velocity field) moment maps from a cube. The following controls are available:

- Close this will close the window
- Apply Parameters this will apply the parameters and compute the moment maps
- 1st Moment Algorithm Menu this allows you to choose between a simple ``weighted mean'' algorithm or a more robust ``median'' algorithm
- Lower Clip Level values in the cube lower than this value are not used in the computation of the moments
- Sum Clip Level values in the computed 0th moment map lower than this value are not used in the computation of the 1st moment map
- Start Channel the first channel that will be used in the computation
- End Channel the last channel that will be used in the computation

A screen snapshot is available here.

# MultiCanvas widget

The MultiCanvas widget allows you to create many Canvas widgets in one fell swoop. All the Canvas widgets occupy the same area in the window: only one can be visible at a time. You can ask for canvases with any of the following visuals: PseudoColour, Directcolour, TrueColour. You can also ask for stereo canvases. The widget will try to create all the canvas types you requested possible on your display hardware. At any time the application can switch which type of canvas is visible (i.e. when switching from an 8bit PseudoColour display to a 24bit TrueColour display). Saves an awful lot of code trying to work out what visuals the display can support. This is used in the ImageDisplay (section 13.20.2) widget.

## Resources

- XkwNrequestMask Mask of requested canvas types to attempt to create
- XkwNallowedMask Mask of allowed canvas types
- XkwNsplitStereo If TRUE use a split stereo mode
- XkwNverbose If TRUE verbose messages are displayed

# OverlayEditorControl widget

The OverlayEditorControl widget is a control panel for interactively drawing overlays over an image.

## Resources

- Xdummy Ignore

## User Description

This widget allows you to interactively draw overlays on top of an image. It uses the overlay package which maintains a list of geometric figures which should be drawn.

The following controls are provided:

- Close this will close the window
- Remove Last will remove the last overlay that you drew from the list
- Remove All will remove all overlays from the list
- Object Menu allows you to choose between the different types of object that you can draw
- First Coordinate Type Menu sets the co-ordinate type of the first defining point for a geometric object
- Remaining Coordinate Types Menu sets the co-ordinate types of the remaining points which define a geometric object

A screen snapshot is available here.

This widget uses the middle mouse button for its drawing functions. Some tools may already be using this button for other purposes, in which case the tool should provide a control which allows you to disable the normal use of the middle mouse button. For instance, the <kvis> programme provides such a control through the ZoomPolicy widget (section 13.43.2).

### Drawing Rectangles

You click down the mouse button to define one corner of the rectangle and move the mouse (keeping the button down) until you have a rectangle to your liking. Once you are happy, release the button and the rectangle will be added to the overlay list.

### Drawing Ellipses

Click the mouse button to define the centre of the ellipse and move the mouse (keeping the button down) to change the size and shape of the ellipse. If you press and release the 'r' key (still with the button down), this will toggle rotation mode, so that now as you move the mouse the ellipse will rotate. To leave rotate mode, just press the 'r' key again, and you will be back to changing the size and shape of the ellipse. Once you have an ellipse you are happy with, release the mouse button and it will be added to the overlay list.

### Drawing Polygons

Click and release the mouse button to define the first and subsequent vertices of the polygon. To close (terminate) the polygon, click and release the button twice without moving the mouse. Once you have closed the polygon it is added to the overlay list.

# Palette widget

The Palette widget is a building block for the Cmapwin (section 13.8) widget: a simple colour palette, allowing the user to choose a colour (such as when drawing).

## Resources

- XtNforeground The foreground pixel
- XkwNminimum The minimum value
- XkwNmaximum The maximum value
- XtNvalue The current value
- XkwNkarmaColourmap The Karma colourmap for the colourbar
- XkwNvalueChangeCallback Callbacks when the thumb value changes
- XkwNorientation The orientation to use

# PannerPopup widget

The PannerPopup widget is subclassed from the SlaveImageDisplayPopup widget. When popped up it will enable panning mode for the ancestor ImageDisplay widget canvas (the main window). Once popped down the main window reverts back to its original (non panning) mode. It is the responsibility of the application to ensure display objects such as viewable images are maintained for the magnifier canvases.

## User Description

This widget is a subclass of the SlaveImageDisplayPopup widget.

# Postscript widget

The Postscript widget, given a Karma pixel canvas, allows the user to specify page size, orientation and whether to generate a PostScript file (or EPS) or to queue directly to a printer.

## Resources

- XkwNportraitOrientation If TRUE portrait orientation is the default
- XkwNpageHorizontalOffset The default horizontal page offset
- XkwNpageVerticalOffset The default vertical page offset
- XkwNpageHorizontalSize The default horizontal page size
- XkwNpageVerticalSize The default vertical page size
- XkwNautoIncrement If TRUE, show the "Auto Increment" toggle
- XtNcallback Callbacks when printing is started

## User Description

This widget provides controls for generating PostScript hardcopy. It supports different orientations and trays and allows you to queue directly to a printer. The following controls are available:

- close this will close the window
- save .ps save a PostScript file
- save .eps save an Encapsulated PostScript file
- print queue directly to a printer
- Tray Menu you can choose between default, paper or transparency trays
- Size Menu you can choose between a variety of media sizes (A3, A4, A5, letter and so on). The ```A4/letter`'' size will fit on both A4 and letter size media. If you select ```user defined`'' then you can define the bounding box using the offset and size controls described below. The default is taken from the ```PAPER_SIZE`'' environment variable
- Keep Aspect if enabled, screen pixels will always be drawn square in the PostScript output
- Orientation Menu you can choose between portrait and landscape orientation, or you can let the choice be automatic so that a best fit is made (e.g. a display window that is much wider than it is high would be displayed in landscape mode on A4 size media)
- hoffset controls the horizontal offset of the output
- voffset controls the vertical offset of the output
- hsize controls the horizontal size of the output
- vsize controls the vertical size of the output
- Auto Increment when enabled, existing PostScript files are not overwritten, rather, the outfile filename has an incrementing sequence number added to it
- Lock Filename when enabled, the application will never automatically change the suggested output filename
- Output file controls the basename of the output file
- Printer queue controls which printer queue to print to. The default is taken from the ```PRINTER`'' environment variable

A screen snapshot is available here.

# Repeater widget

The Repeater widget is a fixed version of the Repeater widget from the Athena widget library. Does the right thing when the widget is set insensitive. Holding down the mouse button over this widget will result in periodic invocation of the registered callbacks.

See the Xt reference manual for widget resources.

# SimpleColourbar widget

The SimpleColourbar widget is another building block for the Cmapwin (section 13.8) widget: a simple colour palette. Unlike the Palette widget, this widget does not allow the user to choose a colour. While less functional, it is also more streamlined (most applications don't need the colour-picking feature).

## Resources

- XtNvisual The visual
- XkwNkarmaColourmap The Karma colourmap for the colourbar
- XkwNmaskRed If TRUE mask the red component
- XkwNmaskGreen If TRUE mask the green component
- XkwNmaskBlue If TRUE mask the blue component

# SimpleSlider widget

The SimpleSlider widget is slider with a nicer user interface than the Value widget, and with a few more resources.

## Resources

- XkwNvalueChangeCallback Callbacks when the value changes
- XtNlabel The label
- XkwNminimum The minimum value
- XkwNmaximum The maximum value
- XkwNwrap If TRUE the values wrap around
- XtNvalue The current value
- XkwNvaluePtr A pointer to a value which is automatically changed
- XkwNscaledValuePtr A pointer to a scaled value (also updated)
- XkwNmodifier The minimum increment/decrement
- XtNorientation The orientation
- XkwNshowRange If TRUE show the range of values
- XkwNshowValue If TRUE show the current value
- XkwNvalueBesideLabel If TRUE show the value beside the label
- XkwNscaledFormat Format string for scaled data
- XkwNscaledUnit Units string for scaled data
- XkwNcallbackOnDrag If TRUE callbacks are called on drag
- XtNdecay The timer decay
- XtNinitialDelay The initial timer delay
- XtNminimumDelay The minimum timer delay
- XtNrepeatDelay The repeat delay

# SlaveImageDisplayPopup widget

The SlaveImageDisplayPopup widget will create a popup shell which contains a Close button and a set of stacked Canvas widgets, similar to the stacking by the MultiCanvas widget. Each canvas that is created is a clone of the canvases in an ancestor ImageDisplay widget. This means that colourmaps, visuals, foreground and background colours are all copied. Finally, world canvases are created for each pixel canvas. The benefit of this widget is that it allows you to create a secondary window which has the same types of canvases as your main window. This is useful when creating a magnifier or panner window. Note that this widget must be created before the ancestor ImageDisplay widget is realised.

## Resources

- XkwNpseudoColourCanvas The PseudoColour world canvas
- XkwNdirectColourCanvas The DirectColour world canvas
- XkwNtrueColourCanvas The TrueColour world canvas
- XkwNpseudoColourLeftCanvas The PseudoColour left world canvas
- XkwNpseudoColourRightCanvas The PseudoColour right world canvas
- XkwNdirectColourLeftCanvas The DirectColour left world canvas
- XkwNdirectColourRightCanvas The DirectColour right world canvas
- XkwNtrueColourLeftCanvas The TrueColour left world canvas
- XkwNtrueColourRightCanvas The TrueColour right world canvas
- XkwNvisibleCanvas The visible world canvas
- XkwNfastPanner If TRUE use a fast, large memory panner
- XkwNenablePanning If TRUE enable panning mode for the canvas
- XkwNrealisedCallback Callbacks when all canvases are realised
- XkwNverbose If TRUE verbose output is generated

## User Description

This widget creates slave display canvases by attaching to an ImageDisplay widget (section 13.20.2). A single Close button is provided which allows you to close the window.

# ThreeDeeSlice widget

The ThreeDeeSlice widget will display the three orthogonal primary planes of a 3-dimensional array, where those planes intersect in a 3-D point. This point may be interactively changed. Nice for slicing through a cube of data.

## Resources

- XkwNiarray The Intelligent Array to display
- XkwNkarmaColourmap The Karma colourmap
- XkwNminPtr A pointer to the minimum array value
- XkwNmaxPtr A pointer to the maximum array value
- XkwNcanvasVisual The visual for the canvas
- XkwNcanvasColourmap The X colourmap for the canvas
- XkwNcursorCallback Callbacks when the 3D cursor position changes
- XkwNverbose If TRUE verbose output is displayed

# TracePopup widget

The TracePopup widget will compute and display a 1-dimensional trace from a multi-dimensional Intelligent Array. You provide the co-ordinates of the trace and the dimension number of the trace and it does the rest.

## Resources

- XkwNverbose If TRUE verbose output is displayed
- XkwNcanvasVisual The visual for the canvas
- XkwNworldCanvas The world canvas that is created
- XkwNrealiseCallbacks Callbacks when the canvas is realised
- XkwNkarmaColourmap The Karma colourmap

## User Description

This widget will display a line plot of a single trace of one-dimensional data. It is fast, allowing dynamic display of data, and provides zooming and smoothing controls, as well as having the ability to display axis labels. The controls available are:

- Close this will close the window
- Auto Zoom if enabled, the vertical scale is automatically zoomed to the range of the data in the profile
- Unzoom this will unzoom the window
- Smooth menu, to select what kind of smoothing to apply to the data, prior to display. Both hanning and uniform smoothing kernels are available, with a range of sizes
- Print this will pop up the Postscript widget (section 13.32.2)
- Overlay this allows you to popup various control panels to control overlay display, including axis labelling (section 13.14.2)

- Save Data this will pop up a dialog widget which allows you to save the data to a file. The data is saved in a simple ASCII format with a few comment lines followed by two columns of numbers. The first column is for the horizontal axis and the second column is for the vertical axis
- Style menu, to select the drawing style for the data points. The following choices are available:
  - join a straight line is drawn from each point to the next
  - hist a centred column is drawn for each point (aka. ``histogram'' style)
  - cross a small crosshair is drawn for each point

### Zooming in TracePopup Widget

To zoom a profile, click (left) and drag the mouse (still keeping the left button down) across the window. You will see a ``rubber-banded'' box stretching between the first point and the current mouse cursor position. When you release the button the section of the profile within the box will be zoomed. To unzoom, choose the Unzoom option in the Zoom menu, or press the ``u'' key while the cursor is in the profile window. This will show the entire image.

A screen snapshot is available here.

# Twodpos widget

The Twodpos widget is another building block for the Cmapwin (section 13.8) widget. This allows the user to move around a 2-dimensional point in a plane, which can be used to control something else in the application.

## Resources

- XtNforeground The foreground pixel
- XkwNminimum_x The minimum horizontal value
- XkwNmaximum_x The maximum horizontal value
- XkwNvalue_x The current horizontal value
- XkwNminimum_y The minimum vertical value
- XkwNmaximum_y The maximum vertical value
- XkwNvalue_y The current vertical value
- XkwNvalueChangeCallback Callbacks when the position changes

# Value widget

The Value is a sort-of slider widget, except that the value is incremented and decremented with slow and fast Repeater (section 13.33) widgets.

## Resources

- XkwNvalueChangeCallback Callbacks when the value changes
- XtNlabel The label
- XkwNminimum The minimum value
- XkwNmaximum The maximum value
- XtNvalue The current value
- XkwNmodifier The minimum increment/decrement
- XkwNwrap If TRUE the values wrap around
- XtNorientation The orientation
- XkwNvaluePtr A pointer to a value which is automatically changed

# ViewDatasets widget

The ViewDatasets widget will manage the display of multiple datasets.

## Resources

- XkwNcursorChangeCallback Callbacks when cursor moves
- XkwNwmtitle The base title string to place above the window
- XkwNverbose If TRUE verbose output is displayed

## User Description

This widget provides controls for a display window to manage the display of multiple datasets. Most of the controls for data display management are in the DataBrowser widget.

The controls provided are:

- Close this will close the window
- Browsers this will pop up the data browser window(s) for this display window
- Movie this will pop up the AnimateControl widget (section 13.4.2), which will allow you to play movies and step through frames. In addition, the following key bindings are defined for the main display window:
  - PgDn go to previous frame
  - PgUp go to next frame
  - Home go to start frame
  - End go to end frame
  On some keyboards, `PgDn` is marked as `Next` and `PgUp` is marked as `Prev`.
- Profile Mode Menu this allows you to pop up the TracePopup widget (section 13.38.2) and choose the profile mode. The following modes are available:

  - None will pop down the TracePopup widget

  - Line will show a single profile in the selected direction

  - Box Sum lets you draw a box over the image window (using the middle mouse button, in a similar way as using the left mouse button to zoom) and then the sum of all the profiles in that region is displayed. Box mode only works for 3-dimensional datasets, and will always display a profile along the unseen dimension

  - Box Average is like the box sum mode except that the average of all profiles is displayed rather than the sum

  - Radial will azimuthally average the image plane data and produce a plot of average value versus radius. A gaussian is then fitted to the radial profile and over-plotted in red and the FWHM (full width half max) of the gaussian is displayed over the profile. You must click the middle mouse button to define the centre of the object of interest, then, keeping the mouse button down, drag out to define the maximum radius of the profile and release the button to display. The algorithm automatically adjusts the centre position using a centroiding operation, so you don't have to be too careful about picking the centre of your object. More information on the centroidingalgorithm can be found in the Karma User Manual.

    The programme should also work with a photographic negative. The centroiding algorithm is automatically modified to look for a trough rather than a peak

  - Boxed Horiz will produce a horizontal profile which is averaged vertically. The box is drawn the same way as for the box sum mode. The horizontal centroid of the profile is computed and a gaussian is fitted and displayed
  - Boxed Vert will produce a vertical profile which is averaged horizontally. The box is drawn the same way as for the box sum mode. The vertical centroid of the profile is computed and a gaussian is fitted and displayed
- Slice Direction Menu this allows you to choose how you want to slice your cube. You can view XY, XZ or ZY planes
- Profile Axis Menu this allows you to choose along which axis you want the profile to be displayed (valid only for line profile mode)
- Freeze Displayed Intensity Range if unset (the default), the intensity range specified for a dataset is used when that dataset is displayed as an image. If set, switching from one dataset to the next will not change the displayed intensity range (however, changing the intensity range for the image dataset will change the displayed intensity range)
- Track Cursor if set, the corresponding image display window will ``listen'' for cursor moves which occur in other image display windows, and will draw a red circle at the same world co-ordinate position
- Show Frame in Line Profile if this is set the current frame displayed in the main image window is shown as a vertical red line in the profile window. This marker is only drawn if the profile axis is the unseen axis
- Auto Title if enabled, the axis labelling title is automatically generated. Whenever this is disabled, the string specified by Axis Labelling Title is used instead
- Show Beam if enabled, the dataset headers are searched for ``BPA'', ``BMAJ'' and ``BMIN'' FITS-style keywords. If these keywords are present, a representation of the telescope beam is overlaid on the image
- Show Beam Name if enabled, the name of the dataset is placed near the beam representation
- Beam Xpos controls the horizontal position of the the beam
- Beam Ypos controls the vertical position of the the beam

In addition, if you click the left mouse button in the display window without moving it in between the press and release, the image will pan across. If you click the middle mouse button, the image will zoom in 2x (the new centre of the image will be the place where you clicked). Click the right mouse button to zoom out 2x. If the profile mode is ``box'' then you can't use the middle mouse button to zoom.

Pressing the `c` key in the display window will compute and display a scatter plot of intensity values in the image dataset versus intensity values in the ``alternate'' dataset. This is useful for seeing if there is a correlation between the values in two images. You can use the left mouse button to define a sub-image (similarly to zooming in) from which the scatter plot is computed.

A screen snapshot is available here.

# View2Datasets widget

The View2Datasets widget will manage the display of two datasets.

## Resources

- XkwNcursorChangeCallback Callbacks when cursor moves
- XkwNwmtitle The base title string to place above the window
- XkwNverbose If TRUE verbose output is displayed

## User Description

This widget provides an advanced control for two datasets (either two-dimensional or three-dimensional). It allows the user to display one dataset or the other, overlay contours of one over the other, show profiles along any axis, and much more. The controls provided are:

- Close this will close the window
- Movie this will pop up the AnimateControl widget (section 13.4.2), which will allow you to play movies and step through frames. In addition, the following key bindings are defined for the main display window:
  - PgDn go to previous frame
  - PgUp go to next frame
  - Home go to start frame
  - End go to end frame
  On some keyboards, `PgDn` is marked as `Next` and `PgUp` is marked as `Prev`.

- Blink if enabled, dataset 2 is displayed (if the display mode is set to blink), if disabled, dataset 1 is displayed. By repeatedly clicking this, the user can blink between the two datasets. You can also press the ``b'' key in the image window and get the same effect. Note that when blinking between two images with non-linear co-ordinate systems, the linear (data pixel) co-ordinates of the canvas boundary are preserved, not the non-linear world co-ordinates. This is especially noticable when blinking between two images with a different pixel scale
- Profile Mode Menu this allows you to pop up the TracePopup widget (section 13.38.2) and choose the profile mode. The following modes are available:

  - None will pop down the TracePopup widget

  - Line will show a single profile in the selected direction

  - Box Sum lets you draw a box over the image window (using the middle mouse button, in a similar way as using the left mouse button to zoom) and then the sum of all the profiles in that region is displayed. Box mode only works for 3-dimensional datasets, and will always display a profile along the unseen dimension

  - Box Average is like the box sum mode except that the average of all profiles is displayed rather than the sum

  - Radial will azimuthally average the image plane data and produce a plot of average value versus radius. A gaussian is then fitted to the radial profile and overplotted in red and the FWHM (full width half max) of the gaussian is displayed over the profile. You must click the middle mouse button to define the centre of the object of interest, then, keeping the mouse button down, drag out to define the maximum radius of the profile and release the button to display. The algorithm automatically adjusts the centre position using a centroiding operation, so you don't have to be too careful about picking the centre of your object. More information on the centroidingalgorithm can be found in the Karma User Manual.

    The programme should also work with a photographic negative. The centroiding algorithm is automatically modified to look for a trough rather than a peak

  - Boxed Horiz will produce a horizontal profile which is averaged vertically. The box is drawn the same way as for the box sum mode. The horizontal centroid of the profile is computed and a gaussian is fitted and displayed
  - Boxed Vert will produce a vertical profile which is averaged horizontally. The box is drawn the same way as for the box sum mode. The vertical centroid of the profile is computed and a gaussian is fitted and displayed
- Slice Direction Menu this allows you to choose how you want to slice your cube. You can view XY, XZ or ZY planes
- Profile Axis Menu this allows you to choose along which axis you want the profile to be displayed (valid only for line profile mode)
- Display Mode Menu this allows you to choose how you want to view your two datasets. The following choices are available:

  - Set 1->image view dataset 1 as an image
  - Set 2->image view dataset 2 as an image
  - Set 1->image, Set 2->contour view dataset 1 as an image and overlay dataset 2 as contours
  - Set 1->contour, Set 2->image view dataset 2 as an image and overlay dataset 1 as contours
  - Blink between Set 1 and Set 2 enable blinking between the two datasets
- Link Intensity Scales if this is set then if the intensity scale for either dataset is modified using the Dataclip (section 13.11.2) widget then the intensity scaling for both datasets is changed. This can be useful when blinking between two images
- Link Frames if this is set then whenever the the current frame number for the image dataset is changed, the frame number for the other dataset is also updated to have the same value. If the two frame dimensions have the same co-ordinate type, then the co-ordinate values are matched, rather than co-ordinate indices. This feature is often used when displaying a movie of both datasets, one as images and one as contours
- Show Frame in Line Profile if this is set the current frame displayed in the main image window is shown as a vertical red line in the profile window. This marker is only drawn if the profile axis is the unseen axis
- Contour Levels this controls the contour levels. Be careful not to hit return after filling in the levels!!! The syntax for the contour levels is as follows:

  - just type the levels you want eg. `0.001 0.002 0.003 0.004`
  - levels with a constant increment: `0.001:0.004+0.001` means that the first level is `0.001`, that this level is incremented with `0.001` until `0.004` is reached. So this example gives the same levels as in the first case
  - levels incremented by a factor: `0.001:0.016*2`. This gives levels `0.001 0.002 0.004 0.008 0.016`
  - levels as percentage of the peak: first character should be %, numbers are taken as percentage, the rest of the syntax is as above, e.g. %10:40+10 gives 10, 20, 30 and 40 % of the maximum of the data

  These options can be mixed, i.e. `-0.03:-0.01+0.01 0.003:0.1+0.02 0.2 0.3` is interpreted correctly.

- Contour Colour specifies the colour the contours should be drawn in
- Apply Levels this will apply the contour levels and colour
- Reset Levels will reset the contour levels to the default
- Auto Apply if this is on, then if you load a new dataset over one that is currently being displayed as contours, the old contour levels are automatically applied. The reason this is off by default is because the contour levels for one dataset may be incorrect for another. An inappropriate set of contours can take a long time to display, so mistakes are costly
- Axis Labelling Title this allows you to change the title placed above the image when axis labelling is enabled. Normally, the title is automatically generated
- -ve Contour Width this controls the width of negative contours
- +ve Contour Width this controls the width of positive contours
- Auto Title if enabled, the axis labelling title is automatically generated. Whenever this is disabled, the string specified by Axis Labelling Title is used instead
- Show Beam if enabled, the dataset headers are searched for ``BPA'', ``BMAJ'' and ``BMIN'' FITS-style keywords. If these keywords are present, a representation of the telescope beam is overlaid on the image
- Show Beam Name if enabled, the name of the dataset for each beam is placed near the beam representation
- Set 1 Beam Xpos controls the horizontal position of the the beam for dataset 1
- Set 1 Beam Ypos controls the vertical position of the the beam for dataset 1
- Set 2 Beam Xpos controls the horizontal position of the the beam for dataset 2
- Set 2 Beam Ypos controls the vertical position of the the beam for dataset 2

In addition, if you click the left mouse button in the display window without moving it in between the press and release, the image will pan across. If you click the middle mouse button, the image will zoom in 2x (the new centre of the image will be the place where you clicked). Click the right mouse button to zoom out 2x. If the profile mode is ``box'' then you can't use the middle mouse button to zoom.

Pressing the `c` key in the display window will compute and display a scatter plot of intensity values in one image versus intensity values in the other image. This is useful for seeing if there is a correlation between the values in the two images. You can use the left mouse button to define a sub-image (similarly to zooming in) from which the scatter plot is computed.

A screen snapshot is available here.

# ZoomPolicy widget

The ZoomPolicy widget controls the zooming policy of a set of KWorldCanvas objects (see the canvas package).

## Resources

- XkwNcanvases The NULL-terminated array of canvases
- XkwNintegerXZoom The default state of the "Integer X Zoom" toggle
- XkwNintegerYZoom The default state of the "Integer Y Zoom" toggle
- XkwNfixAspect The default state of the "Fix Aspext" toggle

## User Description

This widget controls the policy to be used for displaying image data on a drawing canvas. The following controls are provided:

- Close this will close the window
- Apply apply control changes and refresh the window
- Auto Refresh if enabled, each control change is automatically applied and the window refreshed
- Fix Aspect if enabled, the image will be expanded/shrunk with the same factor in both dimensions to fill the window. If disabled, the factors are not necessarily the same (i.e. the pixels will not be square, but the image will fill the window better)
- Allow Truncation if enabled, and the image is too big for the window and integer zooming is enforced, a few rows or columns of data may be discarded to allow the image to be shrunk
- Integer X Zoom if enabled, force zooming in the horizontal dimension do be done in integer multiples. Turning this off allows you to fill the window, but can introduce artefacts
- Integer Y Zoom if enabled, force zooming in the vertical dimension do be done in integer multiples. Turning this off allows you to fill the window, but can introduce artefacts
- Zoom In on Middle Mouse Click if enabled, clicking the middle mouse button will zoom in 2x using the mouse click position as the new centre
- Zoom Out on Right Mouse Click if enabled, clicking the right mouse button will zoom out 2x

A screen snapshot is available here.

# Tutorial

A quite powerful image display tool is <kview>. The power user is urged to use this module and then read the source code to see how much functionality may be packed into so few lines of code, using the image display support in the Karma library and the ImageDisplay widget. A smaller version of <kview> is described in detail in the image display tool chapter.

A simple example is provided below.

## Example 1

This is a complete application (97 lines) which will display a parabola on the screen. It also displays a lot of buttons/menus which you can happily ignore (or explore).

    /*----------------------------------------------------------*/
    /*  Parabola display sample programme                       */
    /*----------------------------------------------------------*/

    #include <stdio.h>
    #include <unistd.h>
    #include <X11/Xatom.h>
    #include <X11/Intrinsic.h>
    #include <X11/StringDefs.h>
    #include <karma.h>
    #include <k_version.h>
    #include <karma_overlay.h>
    #include <karma_xtmisc.h>
    #include <karma_im.h>
    #include <Xkw/ImageDisplay.h>

    #define VERSION "1.1"
    #define NUM_SEGMENTS 100

    STATIC_FUNCTION (void draw_parabola, (KOverlayList olist) );

    /*  Private data  */
    String fallback_resources[] =
    {
        "Kparabola*Canvas*background:                        black",
        "Kparabola*Command*background:                       grey70",
        "Kparabola*Toggle*background:                        grey80",
        "Kparabola*ImageDisplay*quit*background:             orange",
        "Kparabola*background:                               aquamarine",
        "Kparabola*font:                                     9x15bold",
        NULL
    };

    int main (int argc, char **argv)
    {
        KWorldCanvas wc_pseudo, wc_true;
        KViewableOverlayList vlist;
        KOverlayList olist;
        XtAppContext app_context;
        Widget main_shell, image_display;
        /*static char function_name[] = "main";*/

        /*  Initialise module  */
        im_register_module_name ("kparabola");
        im_register_module_version_date (VERSION);
        im_register_lib_version (KARMA_VERSION);
        /*  Start up Xt  */
        main_shell = xtmisc_init_app_initialise (&app_context, "Kparabola",
                                                 NULL, 0,
                                                 &argc, argv, fallback_resources,
                                                 XTMISC_INIT_ATT_COMMS_SETUP, TRUE,
                                                 XTMISC_INIT_ATT_END,
                                                 NULL);
        image_display = XtVaCreateManagedWidget ("topForm",
                                                 imageDisplayWidgetClass,
                                                 main_shell,
                                                 XtNborderWidth, 0,
                                                 XkwNnumDatasets, 0,
                                                 XkwNcreateFilepopup, FALSE,
                                                 NULL);
        XtRealizeWidget (main_shell);
        XtVaGetValues (image_display,
                       XkwNpseudoColourCanvas, &wc_pseudo,
                       XkwNtrueColourCanvas, &wc_true,
                       NULL);
        if (wc_pseudo == NULL) wc_pseudo = wc_true;
        XtVaSetValues (image_display, XkwNvisibleCanvas, wc_pseudo, NULL);
        olist = overlay_va_create_list (NULL, NULL,
                                        OVERLAY_ATT_END);
        overlay_specify_canvas (olist, wc_pseudo);
        vlist = overlay_create_viewable (olist, wc_pseudo);
        overlay_set_active (vlist, TRUE, FALSE, TRUE, FALSE, 0);
        draw_parabola (olist);
        XtAppMainLoop (app_context);
        return (RV_OK);
    }   /*  End Function main   */

    static void draw_parabola (KOverlayList olist)
    /*  [PURPOSE] This routine will draw a parabola into an overlay list.
        <olist> The overlay list.
        [RETURNS] Nothing.
    */
    {
        int count;
        double x_factor, x;
        double x_arr[NUM_SEGMENTS];
        double y_arr[NUM_SEGMENTS];

        /*  Generate array of points  */
        x_factor = 2.0 / (double) (NUM_SEGMENTS);
        for (count = 0; count < NUM_SEGMENTS; ++count)
        {
            x = (double) (count - NUM_SEGMENTS / 2) * x_factor;
            x_arr[count] = x / 2.0 + 0.5;
            y_arr[count] = x * x;
        }
        /*  Draw lines  */
        overlay_lines (olist, NUM_SEGMENTS, NULL, x_arr, y_arr, "yellow");
    }   /*  End Function draw_parabola  */

Karma Home Page
Next: Advanced Examples Up: Karma Programming Manual Previous: Multi-Threading