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.
|
|
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
