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.

⇾Home ⇾Contents ⇾more Input_Output ⇾ Examples

⇾append_row ⇾callback_subroutine ⇾change_column_order ⇾column_headers ⇾controls ⇾default_numerical_format ⇾delete_row ⇾disk_file_and_internal_arrays ⇾example ⇾interactive ⇾matrix_element_type_and_width ⇾mixed_numerical_and_string_arrays ⇾modify_calling_control ⇾multi_column_controls ⇾multi_matrices ⇾numerical_columns ⇾read_element ⇾row_headers ⇾sort_columns ⇾string_columns ⇾string_controls ⇾write_element

Optional keywords:
(Syntax of optional keywords)
Button CALLback CHeckbox COL CoNtrols ColSel ColTitle DNum DefHeight Edit Format Height Line MAx MIn ProgressBar ROW ReturnCode RowSel RowTitle ScrollBar TItle Text TrackBar UPDAte UpDown WINdowhandle Width ZeroBlank
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 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 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
    • 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
    • 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)
  • 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
  • num_or_txt = filename(row,column) ! the direct read is analogous to write
  • EDIT(MatriX=filename, APpenTo=n) ! appends n rows to filename
  • EDIT(MatriX=filename, Delete=row_nr [, DO=n]) ! deletes n-times the row row_nr (i.e. row_nr...row_nr+n-1)
(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 :
  • 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.
  • DLG(Edit=name)
Open a spreadsheet-like editor.
  • DLG(Text=name)
Display only. No mark and copy possible as with DLG(Edit=name, ReadOnly)
  • DLG(Button=mtx, ROW=y, COL=x)
Array of pushbuttons. Index of last activated button is in x and y.
ProgressBar Array of progress bars for visualization
  • DLG(TrackBar=name)
Array of track bars to visualize and change
  • DLG(ScrollBar=name)
Array of scroll bars to visualize and change
  • DLG(UpDown=name)
Array of up-down controls to change
CHeckbox Array of check boxes
  • 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)
  • DLG(Text=sample, Format=" ,")
this displays 26 rows in 1 column with 1 word each
Edit MatrixExplorer-string.png
  • 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(...):
  • 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
. 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 *
  • 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
  • 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 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
  • 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
  • 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
  • DLG(..., COL=col, ...)
col is the column number of the most recently visited matrix element
  • DLG(..., ROW=row, ...)
row is the row number of the most recently visited matrix element
  • 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
  • DLG(..., ColTitle="CNTL:COL:TITLE,", ColSel=cs)
  • CNTL (optional): is either of Text, Button-, CHeckbox-, or RADiobutton (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
  • DLG(Edit=name, Format="F9.2,i12,i4", DNum, cntr="2:TrackBar,MAx=100,DNum=20, 3:Text", ColTitle="Edit+ spinner,TrackBar,Text,")
(Edit) for selected columns (2: and 3:) to a new control (TrackBar and Text) MatrixExplorer-Controls.png
  • Possible modifications for all types: Edit, Text, Button
  • for numerical columns:
    • ProgressBar, TrackBar, ScrollBar, UpDown
    • MIn, MAx, DNum
  • 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.
  • DLG(..., DNum=n, ...)
edit spinner change digit number n. For n=0 the edited value is changed by +- 1
  • DLG(..., Height=h, ...)
displays h rows, default is 10, more can be scrolled with vertical scrollbar
  • DLG(..., Line[=delta], ...)
skip delta lines in the DLG design for preceeding control
  • DLG(..., MAx=hi, ...)
upper bound for edit spinners, progressbars, trackbars, scrollbars, updowns
  • DLG(..., MIn=low, ...)
lower bound for edit spinners, progressbars, trackbars, scrollbars, updowns
  • CNTL (optional): is either of Text, Button-, CHeckbox-, or RADiobutton (default: Text) ⇾ CHeckbox example
  • TITLE (optional), define the row titles displayed (default: row numbers)
  • DLG(..., TItle=tit, ...)
dialog caption
  • DLG(..., UPDAte, ...)
update DLG controls
  • DLG(TrackBar=xy, Text=xy, UPDAte) ! update Text when TrackBar causes a change
  • DLG(..., Width=w, ...)
displays w columns, more can be scrolled with horizontal scrollbar
  • 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)
  • DLG(..., ZeroBlank, ...)
to blank out zeros for better readability in a numerical matrix display
: 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=' ,')

Support HicEst   ⇾ Impressum
©2000-2019 Georg Petrich, HicEst Instant Prototype Computing. All rights reserved.