Designing Forms

Designing PAMGuard Logger Forms

Creating a Form

Key to designing Logger forms in PAMGuard is the generation of one or more UDF_ tables in the PAMGuard database.

The easiest way to generate a blank UDF table is to start PAMGuard, ensure that the database and Logger forms modules have been loaded, then from the Detection menu select “Detection/Logger forms/Create new form …”. A dialog box will then appear asking for the name of the form. Enter the name of the form you want to appear on the display (i.e. don’t include UDF_ at the beginning)

PAMGuard will then generate a new UDF table in the PAMGuard database prefixed with the characters “UDF_”. i.e. if you enter a form name “Effort”, PAMGuard will create a form UDF_Effort

You should then be able to open the database and view the new UDF_ form which will currently be empty

At this point, nothing will appear on the display. To see the form on the display, go to the PAMGuard Detection menu and select “Detection/Logger forms/Regenerate all forms”. An empty form should now appear on the display.

If you look again in the database, you will see that a new output data table has been created with the table name you typed in (i.e. without UDF_). This will currently contain the following columns which are included in all data tables:

  1. Id
  2. UTC
  3. UTCMilliseconds
  4. PCLocalTime
  5. PCTime

Make sure you now close this table since PAMGuard will need to modify it when you start adding additional controls to the form.

Adding Controls

There are two ways of adding controls to the form. The old method is to edit the UDF table directly. This can be quick and efficient if you know what you are doing and is useful if you have several similar controls since you can copy and modify entire rows in the UDF table.

A much more simple method is to use to the built in form editing functions which can be accessed directly from the logger forms menus: Settings/Logger Forms/Edit Forms/[]Your form name].

The built in form editor is modifying the same underlying information in the UDF tables in the database so it is normally possible to use a combination of direct editing of the UDF tables and the in built form editor.

Editing the UDF Table

To add controls to the form, you simply type lines of instructions into the UDF_ table. PAMGuard will interpret these and generate the appropriate input fields on the display and output columns in the output database table.

Although there are many different columns in the UDF_ tables, generally only a few of them need to be filled in for basic functionality with most control types.

Now go back to the UDF_ table in the database and start to add controls. Whenever you want to see these changes on the display simply execute the menu command “Detection/Logger forms/Regenerate all forms”

Using the Inbuilt Forms Editor

To access the forms editor, from the PAMGuard menu select Settings/Logger Forms/Edit Forms/[]Your form name] to show the forms editing dialog:

Use the buttons to the left of the dialog to add, delete and change the order of controls. When a control is selected in the controls list, it’s properties will appear in th erigh thad side of the dialog. Enter appropriate values as required for each control type.

At any point you can preview the form. Pressing OK will cause the dialog to close and the form to be updated on the PAMGuard user interface.

Select the “Form Properties” tab to change form properties such as colour, alerts, etc.

See below for further informaton on Control and Property types.

Control Types

There are two types of control which can be added to the form: Data controls and Property controls.

Active controls are something that handles data, i.e. will have something to type into on the display and will have an column for output data in the output database table.

Property controls don’t control data in any way, but affect the appearance or general behaviour of the form.

NMEA Input

All controls can now receive NMEA input, no just NMEACHAR, NMEAFLOAT and NMEAINT.

To set up NMEA input on a control, fill in the three fields of the UDF_ table NMEA_Module, NMEA_String and NMEA_Position.

NMEA_Moduleshoud be the name of the NMEA module you expect to find data in, e.g. “NMEA Data Collection”. If you leave this empty it will search for data in the first NMEA module it finds.

NMEA_String is the name of the NMEA string containing the data, e.g. “GPRMC”.

NMEA_Position is the index of the data item within the NMEA string (0 is the string name, 1 the first data item, etc).

Further details are provided in individual Data Control descriptions below:

Data Control Types

  • CHAR for character data
  • CHECKBOX for logical data
  • COUNTER for auto incrementing counters
  • DOUBLE for double precision data
  • INTEGER for integer data
  • LOOKUP for drop down lists
  • LATLONG to Lat Long information
  • NMEACHAR for NMEA character data
  • NMEAFLOAT for NMEA floating point data
  • NMEAINT for NMEA integer data
  • SHORT for short integer (16 bit) data
  • SINGLE for single precision floating point data
  • TIME for time data
  • TIMESTAMP for date and time data
  • NEWLINE forces the next control to appear at the start of the next line

Property Control Types

  • AUTOALERT Issues a warning when the form is due to be filled in
  • AUTORECORD Not yet implemented
  • BEARING Selects a Data Control which contains bearing information which will be used on the map display
  • RANGE Selects a Data Control which contains range information which will be used on the map display
  • HEADING Selects a Data Control which contains heading information which will be used on the map display
  • PLOT Indicates that the data from these forms can be plotted on the PAMGuard map (note that there are also options with many Data Controls which give finer control over plot options)
  • NOCLEAR The clear button will be removed from a form
  • NOCANCEL The clear button will be removed from a form
  • READONTIMER The form will be read automatically and saved on a timer
  • READONGPS The form will be read automatically and saved whenever new GPS data arrive (not yet implemented)
  • READONMEA The form will be read automatically and saved whenever new NMEA data arrive
  • SUBTABS Forms will be displayed on sub-tabs (allowing multiple forms of the same type to be open simultaneously)
  • SYMBOLTYPE The type of symbol used for plotting on the map