WwPreview Procedure

Creates an ASCII data preview widget.

Usage

WwPreview, parent, confirmCallback, clearCallback

Input Parameters

parent — The widget ID of the parent widget.

confirmCallback — A procedure called when an area selection is confirmed.

clearCallback — A procedure called when an area selection is cleared.

Keywords

AutoDefine — If nonzero, the header, record, and field areas are automatically defined after the file is loaded.

Filename — A string containing the name of the file from which column-oriented ASCII data is read.

Format — A string specifying the format used to process the data when the AutoDefine keyword is set. Format choices are: 'FIXED' or 'FREE'. (Default: 'FIXED')

Name — A string containing the name of the preview widget. (Default: preview)

Nlines — Specifies the number of lines to read from the data file.

Position — If set, specifies a two-element vector containing the x, y coordinates for the widget within a bulletin board layout.

Selection — A string specifying the type of area to select initially in the preview window. The cursor changes to an H, R, or F to reflect the type of area to be selected: Header, Record, or Field. The choices for this keyword are: 'ANY', 'HEADER', 'RECORD', or 'FIELD'.

Visible — A two-element vector specifying the number of rows and columns displayed. If the data file size is bigger than the number of visible rows and columns in the preview window, scrollbars are placed at the right and bottom edges of the window. (Default: [5, 5])

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text. Only nonproportional (fixed-width) fonts are supported.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the widget is attached to the bottom of the parent widget.

Left — If a widget ID is specified (for example, Left=wid), then the left side of the widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the widget is attached to the left side of the parent widget.

Right — If a widget ID is specified (for example, Right=wid), then the right side of the widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the widget is attached to the right side of the parent widget.

Top — If a widget ID is specified (for example, Top=wid), then the top of the widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the widget is attached to the top of the parent widget.

Get/Set Value

getvalue — Gets the contents of the ASCII data file.

setvalue — Sets the contents of the ASCII data file.

Confirm Callback Parameters

An area selection is committed after it is confirmed by the user. Usually, confirmation occurs when the user clicks MB3. When the user confirms an area selection, a callback routine is called. This callback must have the following parameters:

wid — The preview widget ID.

object — A string containing the type of area to be committed. Valid areas are: 'HEADER', 'RECORD', 'FIELD'.

status — Indicates whether WtPreview has already flagged an error. If status is nonzero, an error detection has occurred. For example, if the area selected by the user is invalid, status is nonzero.

area — A four-element vector specifying the exact lines and columns of the preview window to commit. This vector specifies the following positions: the starting line, starting column, ending line, and ending column.

doit — An output parameter that gives the go-ahead to commit the selection. A value of 0 indicates that the selection should be refused; a nonzero value means the selection is accepted.

Clear Callback Parameters

A routine that is called when an area selection is cleared must have the following parameters:

wid — The preview widget ID.

object — The type of area — 'HEADER', 'RECORD', or 'FIELD' — to be cleared.

area — A four-element vector specifying the exact lines and columns of the preview window to clear. This vector specifies the following positions: the starting line, starting column, ending line, and ending column.

Discussion

WwPreview lets you create PV‑WAVE Widget tools that allow the user to look at the structure of a column-oriented ASCII data file and interactively select specific regions of the file. The three primary parts of a file that can be selected are the header, records, and fields.

Header — One or more lines at the beginning of the data file that are ignored because they do not contain meaningful data.

Record — The smallest portion of the file that contains a set of data (one value from each field). A record can be defined to be exactly one line, less than one line, or more than one line of the data file. A record must start in the first column of the data file and must be on the line immediately following the header.

Field — A specific area in the file that contains a value and is contained in the record.

The preview widget also allows these regions to be defined automatically when the file is opened, via the AutoDefine keyword.

WwPreview provides the following mechanisms to select headers, records, and fields:

StartSelection — Marks the beginning of the specific area. By default, a selection is started when the user clicks MB1.

EndSelection — Marks the end of the specific area. By default, a selection is ended when the user clicks MB2.

ConfirmSelection — Confirms the current selection. By default, a selection is confirmed when the user clicks MB3.

Example

This example application uses the preview widget to create a tool to read a data file and allow the user to select the header, record, and field regions of the data file. The data file can be any column-oriented ASCII file. This example program automatically loads the following data file into the preview window:

<wavedir>/data/air_qual.dat
<wavedir>\data\air_qual.dat

Where <wavedir> is the main PV‑WAVE directory.

Note:

The application in this example uses the PV‑WAVE Widgets function WwPreviewUtils to provide some additional functionality not available with WwPreview, such as clearing previously defined areas and setting characters used for filtering and data separation.

Preview WIndow shows the preview window created in this example. The preview window created in this example displays a data file and allows the user to select header, record, and field regions using the mouse.

Preview WIndow

PRO ConfirmSelected, wid, object, status, area, doit
   PRINT, 'object confirmed:', object, 'status:', status
   PRINT, 'area:', area
   PRINT, 'doit:', doit
END
PRO ClearSelected, wid, object, area
   PRINT, 'object cleared:', object
   PRINT, 'area:', area
END
PRO FileOK, wid, fsshell
   COMMON PREVIEW_Widgets, top, shell, preview
   filename = WwGetValue(wid)
   OPENR, /Get_Lun, unit, filename
   source = ''
   line = ''
   WHILE NOT eof(unit) DO BEGIN
      READF, unit, line
      source = source + line + '\012'
   ENDWHILE
   FREE_LUN, unit
   status = WwSetValue(preview, source)
   status = WwSetValue(fsshell, /Close)
END
PRO FileDone, wid, fsshell
   status = WwSetValue(fsshell, /Close)
END
PRO FileMenuCB, wid, index
   @wtxmconsts
   COMMON PREVIEW_Widgets, top, shell, preview
   CASE index OF
      1: BEGIN
         file = WwFileSelection(wid, 'FileOK', 'FileDone', $
            TITLE='Search', Dir=!Dir+'/data/')
         END
      2: BEGIN
         status = WwSetValue(top, /Close)
         END
   ENDCASE
END
PRO EditMenuCB, wid, index
   COMMON PREVIEW_Widgets, top, shell, preview
   @wtxmconsts
   CASE index OF
      1: BEGIN
         status = WwPreviewUtils(preview, /Clear, /All)
         END
      2: BEGIN
         status = WwPreviewUtils(preview, 'RECORD', $
            1, [0, 54, 3, 3], /Clear)
         END
      3: BEGIN
         header = [0,53,0,2]
         status = WwPreviewUtils(preview, 'HEADER',1,$
            header, /Commit)
         record = [0,54,3,3]
         status = WwPreviewUtils(preview, 'RECORD', $
            record, /Commit)
         END
   ENDCASE
END
PRO SeparatorsOK, wid, index
   COMMON PREVIEW_Widgets, top, shell, preview
   status = WtSet(preview, {, $
      separatorChars:WwGetValue(wid)})
END
PRO FiltersOK, wid, index
   COMMON PREVIEW_Widgets, top, shell, preview
   status = WtSet(preview, {, filterChars:WwGetValue(wid)})
END
PRO OptionsMenuCB, wid, index
   COMMON PREVIEW_Widgets, top, shell, preview
   CASE index OF
      2: BEGIN
         separ = WtGet(preview, 'separatorChars')
         status = WwDialog(preview, 'Separators:', $
            'SeparatorsOK', Text=separ)
         END
      3: BEGIN
         filter = WtGet(preview, 'filterChars')
         status = WwDialog(preview, 'Filters:',$
            'FiltersOK', Text = filter)
         END
   ENDCASE
END
PRO FormatMenuCB, wid, index
   @wtxmconsts
   COMMON PREVIEW_Widgets, top, shell, preview
   CASE index OF
      1: BEGIN
         status = WtSet(preview, {, $
            formatType:XmFORMAT_FIXED})
         END
      2: BEGIN
         status = WtSet(preview, {, $
            formatType:XmFORMAT_FREE})
         END
   ENDCASE
END
PRO ButtonCB, wid, data
   @wtxmconsts
   COMMON PREVIEW_Widgets, top, shell, preview
   CASE data OF
      1: BEGIN
         status = WwPreviewUtils(preview, /AutoDefine)
         END
      2: BEGIN
         status = WtSet(preview, {, $
            selectionMode:XmHEADER_PW_OBJECT})
         END
      3: BEGIN
         status = WtSet(preview, {, $
            selectionMode:XmRECORD_PW_OBJECT})
         END
      4: BEGIN
         status = WtSet(preview, {, $
            selectionMode:XmFIELD_PW_OBJECT})
         END
      5: BEGIN
         status = WtSet(preview, {, $
            selectionMode:XmANY_PW_OBJECT})
         END
   ENDCASE
END
PRO wwpreview_ex1
   @wtxmclasses
   @wtxmconsts
   COMMON PREVIEW_Widgets, top, shell, preview
   top = WwInit('preview', 'Preview', layout, $
      Title='Preview', Background='White', $
      Foreground='red', $
      /Form, Border=3, Position=[100, 100])
   menus = {, menubutton:'File', $
      menu:{, callback:'FileMenuCB', $
      button:'Open', button:'Quit'}, $
      menubutton:'Edit', menu:{, callback:'EditMenuCB', $
      button:'Clear All', button:'Clear', $
      button:'Set areas'}, menubutton:'Options', $
      menu:{, callback:'OptionsMenuCB', $
      menubutton:'Format', menu:{, callback:'FormatMenuCB', $
      button:'Fixed', button:'Free'}, $
      button:'Separators...', button:'Filter...'} $
      }
   bar = WwMenuBar(layout, menus, /Left, /Right, /Top, $
      Font = '-adobe-times-bold-r-normal--14*')
   preview = WwPreview(layout, 'ConfirmSelected', $
      'ClearSelected', /Auto, File=!data_dir + 'air_qual.dat', $
      Top = bar, /Left, /Right, $
      Visible = [20, 60], Font = font, $
      Foreground = 'Blue', Background = 'LightGrey')
      labels = ['Auto Define', 'Header', 'Record', $
      'Fields', 'Any']
   bbox = WwButtonBox(layout, labels, 'ButtonCB', $
      /Horizontal, Spacing=5, $
      Top=preview, /Left, /Right, /Bottom)
   status = WwSetValue(top, /Display)
   WwLoop
END

See Also

WtPreview, WwPreviewUtils