This is part of the HicEst documentation

MatrixExplorer: Spreadsheet-like String, Array, File Dialog

HicEst MatrixExplorer is an extension of the standard DLG function to display or edit numeric arrays or text strings or any file of known structure.

MatrixExplorer is not an independent function.
programmed access to the components of matrix explorer is possible via:
- ⇾ interactive display and edit of in-memory data or disk file data in a spreadsheet-like dialog
- ⇾ open a disk file to filter rows
- ⇾ filename(row,column) = uvw
- ⇾ xyz = filename(row,column)
- ⇾ to sort along disk file columns
- ⇾ to search along disk file columns

example	Example of a file mix = "myfile.txt" with only the 2 lines: this is line 1 with 7 words average word length 4.428571429 +- 0.8046777863 estimated the file is opened for matrix explorer i/o: OPEN(FIle=mix, Format="7 ,") ! each line is parsed in 7 space separated elements DLG(Edit=mix, Format="7A", Width=3) ! to display 3 scrollable columns of "mix" OPEN and DLG Formats define only string_columns in this example. the Width option reduces the columns shown from 7 to 3 and creates a horizontal scroll bar Edit fields can be scrolled horizontally, with a DefHeight option vertically Actual width is slightly increased to account for variable pitch fonts the "More" button provides for an interactive matrix exploring Edit: Append, Insert, Delete, Copy, Paste, Undo, Redo Find and Filter: Standard, Case, Word, RegEx, Scan, Delta, with numerical tolerance Sort, Goto, Magnify, Reset, Export, Help the OPEN format defines whether a column is num or txt: OPEN(FIle=mix, Format="3 ,N , ,N , ,") the "N" OPEN format item prefix denote numerical_columns DLG( Text=mix, Format="3A5,F4,A2,EN10.2,A8", CoNtrols="4:ProgressBar,MAx=5, 5:Edit") ! to display "mix" OPEN and DLG Formats both define columns 4 and 6 as numeric column widths are set individually sort_columns with the column header buttons (toggle sorts) CoNtrols changes the calling Text control to ProgressBar in column 4 and Edit controls (columns 5-7) With "More" > "Export" the file can be output in the shown format (ProgressBar etc printed as num element)
write_element	a disk file OPENed as filename can be written directly by the script: filename(row,column) = num_or_txt on error jump to a label: filename(row,column,*999) = num_or_txt this will suppress the standard error dialog. If label 999 cannot be found, the script proceeds to the next line WRITE(FIle=mix, Row=2, ERRor=999) string1, string2, string3, x this overwrites the 1st 4 columns of row 2 in a single statement
read_element	num_or_txt = filename(row,column) ! the direct read is analogous to write
append_row	EDIT(MatriX=filename, APpenTo=n) ! appends n rows to filename
delete_row	EDIT(MatriX=filename, Delete=row_nr [, DO=n]) ! deletes n-times the row row_nr (i.e. row_nr...row_nr+n-1)

controls (see also DLG)	name in the samples below is either of a vector n x m matrix disk file . This needs an OPEN with file format fileFMT, and ⇾ a dialog format dlgFMT. Note: fileFMT and dlgFMT are usually different, they are defined by the Format options in OPEN and in DLG. OPEN(FIle=name, Format=fileFMT) DLG(...=name, Format=dlgFMT) Disk files may have both numerical and text columns. This is defined in the fileFMT and in DLGfmt	The following examples work with default_numerical_format : 10 digits wide, maximum information presentation ⇾ MIn=0 and ⇾ MAx=100 for ProgressBar and TrackBar. options to change display defaults: Height: default is 10 rows Width: default number of columns displayed depend on column number m, font ( ⇾ FONt, ⇾ PoinT), and window size Format: set individual column formats and controls, default is 10 characters and the control calling the array.
Edit	DLG(Edit=name)	Open a spreadsheet-like editor.
Text	DLG(Text=name)	Display only. No mark and copy possible as with DLG(Edit=name, ReadOnly)
Button	DLG(Button=mtx, ROW=y, COL=x)	Array of pushbuttons. Index of last activated button is in x and y.
ProgressBar	DLG(ProgressBar=name) ! ⇾ example	Array of progress bars for visualization
TrackBar	DLG(TrackBar=name)	Array of track bars to visualize and change
ScrollBar	DLG(ScrollBar=name)	Array of scroll bars to visualize and change
UpDown	DLG(UpDown=name)	Array of up-down controls to change
CHeckbox	DLG(CHeckbox=name) ! ⇾ example	Array of check boxes

string_controls Options:	CHARACTER sample= "Controls to display string or text-file segments can be of type Text, Edit, or Button. Column and Row headers can be Text, Button, CHeck, or RADio " To work with "sample" needs the OPEN-format keyword option to define (varying) item lengths consider also ListBox and ComboBox, e.g. DLG(ListBox=sample, SelIdx=row)	Format can be fixed (like "A20") floating like: " ," where the 1st format character is the token separator in name here: " " and the 2nd character is to separate format specifiers (needed even if there is only one)
Text	DLG(Text=sample, Format=" ,")	this displays 26 rows in 1 column with 1 word each
Edit	DIMENSION rows(30) DLG(Edit=sample, Format='3 ,', BackColor=14, ColTitle="RADio:select,only 1,column,", ColSel=cs, RowTitle="CHeck:mark,as,many,rows,as,you,like,", RowSel=rows) if sample is the name of a disk file with a maximum of say 100 words per line, then DLG(...) has to be preceeded by an OPEN(...): CHARACTER sample="myfile.txt" OPEN(FIle=sample, Format='100 ,') with DLG(...Format="3 ,") only the first 3 columns are displayed scroll bars appear if the horizontal or vertical dimensions exceed the settings or defaults or screen size	multi_column_controls . Shows also some column and row header options. 26/3 rows element(9,3) is hidden (only 26 words in sample) Column titles are separated by kommas and prefixed by RADio: the column selected is in the variable cs (initial and output). For more then 32 columns a vector argument has to be used instead of the scalar cs. row titles are separated by kommas and prefixed by CHeck: the vector "rows" has the individual checkbox values title values are truncated or blanked if required the titles of the active cell is postfixed by *
Button	DLG(Button=sample, fmt="2A10, A20") column 1 and 2 have 10 characters each, column 3 has 20 characters.	3 columns of pushbutton controls in 3 rows

change_column_order

DLG(Text=sample, Format='3 ,', ColSel=selected, ColTitle='CHeck:3:Column3,1:Column1,')

prefix column title by column number and colon
optionally prefix with control type as well
initial and output of CHeck or RADio is in "selected" (can be scalar or vector)

option (see also DLG)

name can be either a disk file with preceeding OPEN, a string, a vector, or a matrix. This is controlled by the choice of Format.

CALLback

callback_subroutine

to extend MatrixExplorer features

DLG(Edit=filename, Format="4A4", CALLback="mysub", RowTitle="Button:,", ReturnCode=rc, ROW=row, COL=col, RowSel=rs, ColSel=cs) ! numbered buttons as row headers

mysub is a user written subroutine that is called when

a column or row header control is activated
an Edit or CHeckbox matrix element is changed
Button matrix element is hit

subroutine mysub ! without arguments and USE all symbols are global
USE calling_procedure : rc, row, col, rs, cs ! only needed if the calling procedure is local (with arguments or USE)
....... ! do whatever needs to be done
END

options	to tell mysub the triggering action
ColSel	DLG(..., ColSel=cs, ...) cs has the last activated Button/CHeckbox/RADiobutton column number: scalar cs: column# for Button and RADio, bitpattern for CHeck-columns 1..32 vector cs: 0 is not selected, /= 0: selected
RowSel	DLG(..., RowSel=rs, ...) rs has the last activated Button/CHeckbox/RADiobutton row number: scalar cs: row# for Button and RADio, bitpattern for CHeck-rows 1..32 vector cs: 0 row is not selected, /= 0: row is selected
COL	DLG(..., COL=col, ...) col is the column number of the most recently visited matrix element
ROW	DLG(..., ROW=row, ...) row is the row number of the most recently visited matrix element
ReturnCode	DLG(..., RetCod=rc, ...) rc = displayed (n rows, m columns) DLG sequence number of matrix : 1001: the OK button 1002: the More button 1002+1...1002+n: the displayed column headers 1002+n+1...1002+n+m: the displayed row headers 1002+n+m+1...1002+n+m+n*m: the displayed matrix elements row by row

ColTitle

DLG(..., ColTitle="CNTL:COL:TITLE,", ColSel=cs)

CNTL (optional): is either of Text, Button-, CHeckbox-, or RADiobutton
column_headers
(default: Text for arrays, Button for disk files) ⇾ RADio example
COL (optional): column numbers to rearrange columns (default: natural order), ⇾ column order
TITLE (optional), define the column titles displayed (default: column numbers), ⇾ title only

CoNtrols

DLG(Edit=name, Format="F9.2,i12,i4", DNum, cntr="2:TrackBar,MAx=100,DNum=20, 3:Text", ColTitle="Edit+ spinner,TrackBar,Text,")

modify_calling_control

(Edit) for selected columns (2: and 3:) to a new control (TrackBar and Text)

Possible modifications for all types: Edit, Text, Button
for numerical columns:
- ProgressBar, TrackBar, ScrollBar, UpDown
- MIn, MAx, DNum

DefHeight

DLG(DefHeight=newH, Edit=..., ...)

change default height of all controls in multiples of default height. For newH >= 2 this will make Edit fields vertically scrollable.

DNum

DLG(..., DNum=n, ...)

edit spinner change digit number n. For n=0 the edited value is changed by +- 1

Format

DLG(...=string_or_array, Format=fmt) !
matrix_element_type_and_width

Height

DLG(..., Height=h, ...)

displays h rows, default is 10, more can be scrolled with vertical scrollbar

Line

DLG(..., Line[=delta], ...)

skip delta lines in the DLG design for preceeding control

MAx

DLG(..., MAx=hi, ...)

upper bound for edit spinners, progressbars, trackbars, scrollbars, updowns

MIn

DLG(..., MIn=low, ...)

lower bound for edit spinners, progressbars, trackbars, scrollbars, updowns

RowTitle

DLG(..., RowTitle="CNTL:TITLE,", RowSel=rs)

CNTL (optional): is either of Text, Button-, CHeckbox-, or RADiobutton
row_headers
(default: Text) ⇾ CHeckbox example
TITLE (optional), define the row titles displayed (default: row numbers)

TItle

DLG(..., TItle=tit, ...)

dialog caption

UPDAte

DLG(..., UPDAte, ...)

update DLG controls

DLG(TrackBar=xy, Text=xy, UPDAte) ! update Text when TrackBar causes a change

Width

DLG(..., Width=w, ...)

displays w columns, more can be scrolled with horizontal scrollbar

WINdowhandle

DLG(..., win=wh, ...)

to continue program execution after opening the dialog. Without WIN: the script waits until DLG is closed (Note: MatrixExplorer dialogs are always modeless)

ZeroBlank

DLG(..., ZeroBlank, ...)

to blank out zeros for better readability in a numerical matrix display

multi_matrices : more than one array can be displayed in one single DLG, here 2 vectors chk and random, and the character array sample	Position matrices e.g. with the Line option
REAL :: random(30), chk(30) ! define 2 vectors random = RAN(100) chk = random > 75 ! is 1 for random elements > 75 DLG(CHeckbox=chk, BaCkcolor=14, Format="i2", ProgressBar=random, Fmt="F20", Edit=sample, F=' ,')	instead internal arrays this could also be disk file arrays (needs OPEN) allows mixed_numerical_and_string_arrays _ _allows disk_file_and_internal_arrays in a single DLG 1 common scroll bar controls all arrays note the width of numerical columns can be controlled by Format