This is part of the HicEst documentation

DLG: Interactive Screen Input and Output with HicEst

Commands like DLG(Button=my_button, Edit=my_variable, ListBox=my_words, ...) make the use of Windows common dialogs an easy thing.

⇾Home ⇾Contents ⇾more Input_Output ⇾ Examples

⇾alternate_syntax ⇾an_example ⇾bitmap_button ⇾breakpoint ⇾button_details ⇾calling_a_subroutine ⇾checkbox_details ⇾combobox_details ⇾dialog_management ⇾draw_attention ⇾dynamically_generate_dialogs ⇾edit_details ⇾font-size_and_font ⇾force_button_return ⇾full_screen_edit ⇾hotkey ⇾icon_buttons ⇾label_jump ⇾linewrap ⇾listbox_details ⇾mail_client ⇾modal_dialog ⇾modeless_dialog ⇾no_caption_bar ⇾numerical_modifiers ⇾open_browser ⇾position_individual_control ⇾positional_modifiers ⇾prefixed_dialog_item ⇾print_dialog ⇾radio-button_details ⇾run_mode_button ⇾sorting_a_dialog_list ⇾step_mode ⇾stop_program_execution ⇾undo_in_edit_controls ⇾visual_support

Optional keywords:
(Syntax of optional keywords)
Align BLAck BORder BaCkcolor BiTteXt Button CALLback CHIld CHanGed CHeckbox CenterAlign ColS ComBobox DEFault DNum DefHeight DefWidth Edit EnAble FONt FRAMe FixedFont FocuS ForeColor GRAY Group GroupEnd Height HelpFile Jumpto KiLl LeftAlign Line ListBox MAx MIn NameEdit NoClose Owner PassWord PoinT ProgressBar RADio REct ReadOnly ReturnCode RightAlign SEParators SHOW SOrt SPace ScrollBar SelIdx SelTxt SetMemory TItle Text TrackBar UPDAte UpDown Vertical WHIte WINdowhandle WRap Width X X0 XMemoryadd Y Y0 YMemoryadd
control effect (√ is MatrixExplorer supported) most useful modifiers
√ rectangle with text, causes action when clicked CALLback, ReturnCode
  • DLG(Text=num)
  • √ for a num argument its symbolic name is prefixed ( ⇾ example)
  • positions are as for the other controls (unlike Align)
CenterAlign, LeftAlign , RightAlign
positions a text of arbitrary length to the right of previous control (Text=txt is shown with DefWidth) Line
  • DLG(Edit=num)
√ text or number for display and change DNum, Height, ReadOnly, Width, WRap
  • DLG(NameEdit=num)
prefixes an Edit control with its symbolic name (1 DefWidth) Line
select from a list of texts SelIdx, SelTxt, Height
combines Edit and ListBox: enter new text or select and edit SelIdx, SelTxt, Height
√ square with text, toggled 0/1 when clicked BiTteXt
circle with text, other circles unselected when clicked BiTteXt
√ partially paints a rectangle MAx, MIn, DNum, Vertical, Width
√ arrow in a bar to be moved with mouse or arrow keys. Shows tooltip window (scaled to 0...100) with num value when mouse is clicked on the thumb. MAx, MIn, DNum, Vertical, Width
√ updown with thumb MAx, MIn, DNum, Vertical, Width
√ stand-alone very short scroll bar without thumb MAx, MIn, DNum
group the following controls with a frame title of txt. Either the last control or an explicit GroupEnd terminate the group
filled rectangle, default is BLAck BLAck, GRAY, WHIte
unfilled rectangle, default is BLAck BLAck, GRAY, WHIte
  • _the_following_buttons_close_a_ (the program waits until the dialog is closed
  • rc = DLG(Button='OK')
  • rc is set to itemnr+1000 (here == 1001)
  • : script waits until button (or ESCape) is hit
  • rc = DLG(B="5:action 1", B="23:action 2")
: rc is set to 5 or 23 for the buttons "action 1" or "action 2" resp.
  • rc = DLG(B="1: !", B="2:i", B="3:X", B="4:?")
can be used instead of texts
  • DLG(B='&OK')
  • "&OK" is the default button
  • & defines a , here the key "O" will close the dialog
  • DLG(B='0:Cancel')
a "0:" prefix to (same as ESCape)
  • DLG(B='test.bmp')
: the button displays a bitmap file in its full size
increase button height, line wrap button text
  • DLG(B='>123:name') ! or:
  • DLG(B="jump", Jumpto=123)
: jump to label 123 of current procedure. If not found continue with next statement.
  • DLG(B="chapter5:show &5", B="chapter6:show &6")
  • DLG(B='STEP:&Step')
to continue execution in single steps
  • DLG(B='RUN:&Run')
to continue execution
  • DLG(B='$Print:print this dialog')
  • DLG(B='')
to URL =
  • DLG(B="shell:c:\Hicest\Web\ FAQ.HTM")
"local file browser button"
  • DLG(B=' ?subject=hello &&BODY=something important')
open (no send) with
  • mail address ("")
  • subject (hello)
  • text body (something important)
  • DLG(HelpFile='Hicest.hlp', B='DLG.Button:&show')
A "show" button. When hit, the Appendix-item of the current HelpFile opens (here DLG.button)
A includes the WINdowhandle=handle option:
  • DLG(B='5:KEEP', ReturnCode=rtn, WINdowhandle=handle)
  • a modeless dialog stays on the screen while the script continues running. It is closed when button is hit, or a DLG( KiLl=handle) is executed
  • , the DLG(Edit=argument) can be numerical or textual:
Without a Button the explicit return value (e.g. "rc") of the DLG function is itemnr+1000 (here == 1001), else it is the default-button ID
  • rc = DLG(Edit=x)
is via ESCape or Cntl+Z
  • rc = DLG(Edit=num_array)
MatrixExplorer is called when the argument to Edit is a numerical array
  • DLG(Edit=num, DNum=delta)
⇾ see example
numeric edit with a spinner (2 small arrows):
  • delta <= 0 or absent: num changes by +- 1
  • > 0: num changes +- 1 in its n-th significant digit
  • default limits: -1E300...1E300 ⇾ see MIn, MAx
  • DLG(E='text is too long but may be scrolled')
text that is too long for the default width can be horizontally scrolled
  • DLG(E=num_or_txt, RightAlign)
as for the Text-option CenterAlign and LeftAlign are also possible
↵ on edit control will not close DLG. Useful to
input appears as ***
input is rejected, sometimes preferable to Text option
  • _on_output_ are equivalent to checkbox_details
  • on input only the most recently activated radio button is set
  • DLG(CHeckbox=num)
with a scalar variable num this acts as a simple 0/1 switch
  • CHARACTER names="alfa beta gamma delta "
  • DLG(BiTteXt=names, CHeckbox=num)
  • DLG(BiTteXt=names, RADio=num)
  • BiTteXt as prefix to CHeckbox or RADio generates a series of up to 32 check boxes or radio buttons named as the words in its argument.
  • num is the sum of 2^(namenr-1), e.g. for num == 5 the boxes alfa and gamma are checked, beta and delta are unchecked
  • the optional keyword ColS=n breaks the series of checkboxes after n columns and starts a new row
  • DLG(CHeckbox=array)
  • DLG(RADio=array)
  • MatrixExplorer is called when the argument to CHeckbox or RADio is a numerical array and no BiTteXt is prefixed.
  • With BiTteXt single array elements are set/unset.
  • DLG(ComBobox=names, SelIdx=si, SelTxt=string)
  • DLG(ListBox=names, SelIdx=si, SelTxt=string)
⇾ see example
  • si selects the initial index
  • si receives the selected index. si == 0 when some new text is entered
  • string gets the selected or the newly entered text
  • without the Height option:
    • combobox shows edit area only without dropdown list
    • listbox shows maximum height possible
  • DLG(ComBobox=names, Width=0)
  • DLG(ListBox=names, Width=0)
Width=0 adjusts the width to the maximum length of a line
  • DLG(ComBobox=names, Height=3, B="&OK", Line)
  • with the Height option a combobox shows a dropdown list only when another control follows below it
  • DLG(listb=names, SOrt=log)
: SOrt with log /= 0. SelIdx=si will have the sorted index
  • DLG(lbox="Example.hic")
if "Example.hic" is a valid file name, the file will be listed.
if the listbox or combobox argument is not a valid file name:
  • lists start with the 1st occurrence of the listbox or combobox argument in column 1 of the
    • HelpFile argument
    • current script file without HelpFile option
  • the list is terminated with the next line that has a non-blank in column 1
if above fails:
  • DLG(combo="duck,dog,donkey,")
"duck,dog,donkey," is a string with non-alfanumeric characters as separators
  • DLG(HeLP="topic")
to open a HicEst help window for "topic" from the script
  • DLG(Edit=num,MIn=min,MAx=max,DNum=dn, ProgressBar=num,MIn=min,MAx=max,DNum=dn, TrackBar=num,MIn=min,MAx=max,DNum=dn, ScrollBar=num,MIn=min,MAx=max,DNum=dn, UpDown=num,MIn=min,MAx=max,DNum=dn, TItle="Edit, Progress, Track, Scroll, UpDown", UPDAte)
  • Vertical is possible after ScrollBar, ProgressBar, TrackBar
option type (missing [num] evaluates to o default setting
MIn , MAx num set lower and upper bound of numerical controls
  • TrackBar -32768...32767
  • ScrollBar: 0...65535
  • ProgressBar: 0...32767
  • UpDown: 0...32767
  • Edit ⇾ Edit details
DNum [num] DNum = dn sets the step size of a numerical control
  • TrackBar, ScrollBar, UpDown: page up/down keys
  • TrackBar: scale tic difference
  • Edit ⇾ Edit details
UPDAte --- to repaint the dialog when a control modified its argument value ---
: modify all subsequent controls of this DLG statement W=dialog font width, H=height
BORder [num] spacing between box edges and controls 1.75 * W
DefHeight num default height DH of controls 1.5 * H
DefWidth num default width DW of controls 10 * W
SPace [num] spacing between controls W
by modifying default position of preceding control
  • num ≥ 1: multiples of DW or DH
  • num < 0: multiples of W or H
  • 0.01...0.999: screen portions
  • if missing: same as num=0
default values:
  • DH = current DefHeight
  • DW = current DefWidth
  • H = character height
  • W = character width
Height num height of control 1 * DH
Width num width of control 1 * DW
X [num] x-position of control
left border: X=0 or simply X
1 * SPace right of preceding control
Y [num] y-position of control
top border: Y=0 or simply Y
if for preceding control
  • default H: Y unchanged
  • H set: 1 SPace below preceding control
Line [num] add to current Y and reset X to 0 1 * DH
SetMemory remember X and Y of next control ---
XMemoryadd [num] add to X of preceding SetMemory, use instead X 0
YMemoryadd [num] add to Y of preceding SetMemory, use instead Y 0
X0 num horizontal position of dialog (> 1: script font character widths) script window right aligned
Y0 num vertical position of dialog (> 1:script font character heights) script window center aligned
  • call SUB after ↵ on Button, numeric Edit, TrackBar, ScrollBar
  • CALLback is inherited by all subsequent items
  • use ReturnCode to tell which item caused SUB to be invoked
  • controls can be postfixed by different CALLback options to call different SUBs
  • CALLback=' ' will cancel callbacks following the preceding control
no default
to a particular control
FocuS --- preceding control gets initial focus 1st control
DEFault --- preceding Button becomes default ↵ regardless of actual focus "&OK" is always DEFault
EnAble log 0 to disable (gray-out) and 1 to enable preceding control 1 (enabled)
SHOW log 0 to hide and 1 to show preceding control 1 (show)
ForeColor num foreground ⇾ color of preceding control 0 (black)
BaCkcolor num background ⇾ color of
  • preceding control
  • of DLG window if prefixed to 1st control
11 (bright cyan)
FONt n/c or set in HicEst Menu → Options → Fonts →3
PoinT num font size for this DLG
FixedFont --- use fixed font for this DLG
TItle txt title caption ⇾ example. To have a DLG with set txt=" " "..."
CHanGed NUM Gets the sum of 2^itemNR of changed Edit, TrackBar, ScrollBar, UpDown controls
  • DLG(E=x, NameE=y, TrackB=z, ID=tbID, CHanGed=chg)
  • in this example: itemNR=1 for x, =3 for y (Name counted also), =4 for z
  • if y is edited AND z changed by the trackbar, chg is set to 2^3 + 2^4 = 24
  • DLG(KiLl=otherhandle, ...)
close a DLG or WINDOW with handle == otherhandle
Owner NUM
  • DLG(..., WINdowhandle=win2, Owner=win1)
  • create modeless dialog with handle win2
  • with Owner=win1 the new window win2 will always be in front of the owner window win1.
  • If not specified, or if specified as constant 0, then the new window can be overlapped by any window in your program.
  • Owned dialogs or windows are closed when the owner is closed
Main window
CHIld ---
  • DLG(..., WINdowhandle=win2, CHIld, Owner=win1)
Creates a child dialog box. When used with a modeless dialog box, the dialog box will maintain its position relative to the owner window.
not a child
SEParators txt to replace the default separators ( ⇾ alternate syntax DLG only) enter txt as a 8-byte replacement string for (1) Space " ", (2) Colon ":", (3) Equals "=", (4) Asterisk "*", (5) Semicolon ";", (6) Goto ">", (-) Minus "-", (8) newline "|"
  • " :=*;>-|"

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