DIALOG Objects +
Updated: July 10, 2012

OPENDIALOG SAVEDIALOG FONTDIALOG COLORDIALOG FINDDIALOG REPLACEDIALOG
PAGEDIALOG PRINTDIALOG

Overview:

These dialogs provide a wide range of configuration options in read/write
string and integer variables utilizing Microsoft Windows "common dialogs".

After a dialog is dimensioned (e.g., Dim Open As OPENDIALOG), the application
may set or read the following property variables. Since the .Flags property
may be used to return a dialog result, it should be set with the desired value
prior to each use of the .Execute method. To get and save the default .Flags
value, simple read .Flags after DIM/CREATE of the dialog.

Then, the .Execute method is a numeric function that displays the dialog box
and returns True or False and further results in the dialog property variables.

MESSAGEBOX is a numeric function in this family.  The OPEN, SAVE, FONT, COLOR,
PAGE and PRINT DIALOG objects work in both CONSOLE and GUI programs.

Use string constants (e.g., "hello") or variables (e.g., DIM MyStr$ As String),
not string functions (e.g., CURDIR$) or expressions (e.g., "C:\"+"hot") for
arguments when writing (W) to dialog string properties.


======================
EVENTS

The dialogs described below all have an .OnDialog event trapping messages to
the dialog, mostly from user keyboard and mouse input.  Four case-sensitive
variables contain message information: hDlg, mDlg, wDlg and lDlg similar to
hWnd, uMsg, wParam and lParam respectively.  The OPEN, SAVE, FONT, COLOR, PAGE
and PRINT dialogs are "modal", meaning results are returned upon dialog close,
and therefore, user .OnDialog routines are often not needed.

However, the FIND and REPLACE dialogs are "modeless" and the .OnDialog event
may be more useful to control program flow.

EVENTS     Defines subroutine called on event
~~~~~~     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
OnDialog   Name of SUB or LABEL followed by RETURN

  DIM MyFindDlg as FINDDIALOG  'create it
  MyFindDlg.OnDialog = OnFind
  MyResult = MyFindDlg.Execute  'show it
  'code
  OnFind:
  IF mDlg = &H100 AND wDlg = 13 THEN 'user pressed enter key
    'code to examine dialog properties and/or to close dialog
    BEEP 'for debugging
    RETVAL ONE   'message processed by OnFind hook routine.
  ELSE
    RETVAL ZERO  'message not processed by OnFind hook routine.
  END IF
  RETURN

  Note: .OnDialog hook functions as above may change the behavior of the dialog
  and may require careful study to return appropriate values.


======================
HOW TO DISPLAY A DIALOG?

Each dialog object has the same method to display the dialog box:

NUMERIC FUNCTIONS:

Name       Description
~~~~       ~~~~~~~~~~~
Execute    Display dialog box and return True/False and results in the
           object properties

  Since properties may be changed by .Execute, some properties may have to be
  initialized or "reset" for each .Execute call.

  Examples:

  dim MyFile As FILE, Open As OPENDIALOG, MyResult As LONG
  MyResult = Open.Execute 'returns True or False
  IF MyResult THEN MyFile.Open(Open.FileName,2) 'open in read/write mode
  'or
  IF Open.Execute THEN SHOWMESSAGE "A file was selected"


======================
The OPENDIALOG and SAVEDIALOG Objects facilitate selection of full path names
for files to be opened or saved by an application program.

STRING VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
Caption    Title of dialog box

  MyOpen.Caption = "File to edit"
  MyOpen.Caption = "Select program to run"
  MyStr = MyOpen.Caption 'what is the title of this dialog?

DefExt     Default file extension (three characters without ".")

  MySave.DefExt = "txt" 'save as .txt file if no extension specified
           
FileName   Full pathname(s) of file(s) selected by user in the dialog

  Dim s As STRING, Open As OPENDIALOG
  IF Open.Execute THEN
    s.LoadFromFile(Open.FileName)
  ELSE
    PRINT "user did not select a file"
  END IF

  Note that .FileName is used (or saved to a user STRING) immediately after
  .Execute, since the returned .FileName data does not have permanence.

  Note: If the OFN_ALLOWMULTISELECT .Flags is set, .FileName contains a string
  starting with the path followed by the individual file names.  If the
  OPN_EXPLORER flag bit was set, this string is 0-byte-delimited, else it is
  space-delimited.  Here is a space-delimited parsing example:

  NumberFiles = TALLY(Open.FileName,space) - 2
  Path$ = FIELD$(Open.FileName,space,1)
  IF NumberFiles>zero THEN
    FOR i = 1 to NumberFiles
    File$(i) = FIELD$(Open.FileName,space,i+1)
    Next i
  END IF

  The 0-byte delimiter is used with the OPN_EXPLORER flag, since the result may
  contain embedded spaces.  Parsing this case may use:

  defstr z1=chr$(0)
  defstr z2=z1+z1
  Opn$ = left$(OpnBuf$,instr(OpnBuf$,z2)-1)  'look for z2!

  With luck, Opn$ will now be a z1-delimited string.  Then
  
  IF Opn$.length THEN OpnList.Clear: OpnList.Parse(Opn$,z1)

  Now .item(0) of OpnList is the path; next items are the file names.
  Note: OpnBuf$, Opn$ and OpnList dimensioned as STRING and LIST.

Filter     String specifying filters to use in dialog

  Important: If .Filter is specified, .DefExt should also be defined.

  Microsoft's win32.hlp states:

  'Points to a buffer containing pairs of null-terminated filter strings.
  The first string in each pair describes a filter (for example, "Text Files"),
  and the second specifies the filter pattern (for example, "*.TXT"). Multiple
  filters can be specified for a single item by separating the filter pattern
  strings with a semicolon (for example, "*.TXT;*.DOC;*.BAK"). The last string
  in the buffer must be terminated by two NULL characters. If this member is
  NULL, the dialog box will not display any filters. The filter strings are
  assumed to be in the proper order -- the operating system does not change the
  order.'

  For either OPENDIALOG or SAVEDIALOG,

  defstr B0 = CHR$(0)
  defstr F1 = "Text Files"+B0+"*.TXT"+B0
  defstr F2 = "Souce Code"+B0+"*.BAS;*.INC"+B0
  defstr filter1 = F1+F2
  'a string expression is not used below, so .Filter will have permanence
  Open.Filter = filter1

  A ";" character used in the "description" string for an item may cause
  confusion since it is a delimiter in the item "pattern" string.

InitialDir Start directory for the dialog; default = current directory

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
BufferSize Size of application buffer containing .FileNane

  Default = 260 bytes.  .BufferSize can be increased as needed.  For example,
  if multiple files may be selected with OPENDIALOG, a substantially larger
  buffer may be needed for the selected file data.

FilterIndex
           1-based index of .Filter string to use in .Execute

  Default = 0, .Filter string not used or all filters used           

  Open.FilterIndex = 1 'filter item F1 will be used in dialog

Flags      Flags controlling behavior of dialog box

  An application can examine the .Flags value after use of .Execute, since
  results of this method may alter .Flags bits.  Notice that it may be
  necessary to "reset" .Flags for a subsequent .Execute.

  Default = &H205800 for OPENDIALOG and &H202806 for SAVEDIALOG obtained by OR
  combination of these values:  

  $DEFINE OFN_READONLY                &H1
  $DEFINE OFN_SHARENOWARN             &H1
  $DEFINE OFN_OVERWRITEPROMPT         &H2
  $DEFINE OFN_SHAREFALLTHROUGH        &H2
  $DEFINE OFN_HIDEREADONLY            &H4
  $DEFINE OFN_NOCHANGEDIR             &H8
  $DEFINE OFN_SHOWHELP               &H10
  $DEFINE OFN_ENABLEHOOK             &H20
  $DEFINE OFN_NOVALIDATE            &H100
  $DEFINE OFN_ALLOWMULTISELECT      &H200
  $DEFINE OFN_EXTENSIONDIFFERENT    &H400
  $DEFINE OFN_PATHMUSTEXIST         &H800
  $DEFINE OFN_FILEMUSTEXIST        &H1000
  $DEFINE OFN_CREATEPROMPT         &H2000
  $DEFINE OFN_SHAREAWARE           &H4000
  $DEFINE OFN_NOREADONLYRETURN     &H8000
  $DEFINE OFN_NOTESTFILECREATE    &H10000
  $DEFINE OFN_NONETWORKBUTTON     &H20000
  $DEFINE OFN_NOLONGNAMES         &H40000
  $DEFINE OFN_EXPLORER            &H80000
  $DEFINE OFN_NODEREFERENCELINKS &H100000
  $DEFINE OFN_LONGNAMES          &H200000


======================
FONTDIALOG

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
Alignment  Set or get font alignment

Color      Set or get color of font

DC         Device context handle for active printer

Flags      Set font dialog behavior and return results

  Default = &H10103

  $DEFINE CF_SCREENFONTS          &H1
  $DEFINE CF_PRINTERFONTS         &H2
  $DEFINE CF_BOTH                 &H3 'CF_SCREENFONTS + CF_PRINTERFONTS
  $DEFINE CF_SHOWHELP             &H4
  $DEFINE CF_ENABLEHOOK           &H8
  $DEFINE CF_INITTOLOGFONTSTRUCT &H40
  $DEFINE CF_USESTYLE            &H80
  $DEFINE CF_EFFECTS            &H100
  $DEFINE CF_APPLY              &H200
  $DEFINE CF_ANSIONLY           &H400
  $DEFINE CF_NOVECTORFONTS      &H800
  $DEFINE CF_NOOEMFONTS         CF_NOVECTORFONTS
  $DEFINE CF_NOSIMULATIONS     &H1000
  $DEFINE CF_LIMITSIZE         &H2000
  $DEFINE CF_FIXEDPITCHONLY    &H4000
  $DEFINE CF_WYSIWYG           &H8000
  $DEFINE CF_FORCEFONTEXIST   &H10000
  $DEFINE CF_SCALABLEONLY     &H20000
  $DEFINE CF_TTONLY           &H40000
  $DEFINE CF_NOFACESEL        &H80000
  $DEFINE CF_NOSTYLESEL      &H100000
  $DEFINE CF_NOSIZESEL       &H200000

Font       Set or get address of FONT object (must be "initialized").

  Dim MyFont As FONT, FontSel As FONTDIALOG
  MyForm.font = MyFont  'cause system to fill in MyFont data
  FontSel.Flags = FontSel.Flags OR &H40  'enable use of MyFont structue
  FontSel.font = MyFont 'use/update this data in the font dialog box

  Set the .Flags &H40 bit if you have assigned a FONT to dialog .Font as shown
  above so that the dialog will initialize to that selection.

FontType   Set or get font type bits

MinFontSize
           Minimum font size in dialog

MaxFontSize
           Maximum font size in dialog

PointSize  Point size of font x 10


======================
COLORDIALOG

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
CC         0-based array of 16 custom color values; default = 0

  MyRGB = MyColorDialog.CC(0) 'read first value
  MyColorDialog.CC(7) = RGB(MyRed, MyGreen, MyBlue) 'write eigth value

Color      RGB value of selected or pre-selected color

CustomColors Set alternate address for custom color array

  Dim MyCC(15) As LONG  'my custom colors
  MyColorDlg.CustomColors = @MyCC

Flags      Set color behavior and return results; default = 1

  $DEFINE CC_RGBINIT         &H1
  $DEFINE CC_FULLOPEN        &H2
  $DEFINE CC_PREVENTFULLOPEN &H4
  $DEFINE CC_SHOWHELP        &H8
  $DEFINE CC_ENABLEHOOK     &H10


======================
FINDDIALOG and REPLACEDIALOG

STRING VARIABLES (R only):

Name       Description
~~~~       ~~~~~~~~~~~
Find       Search string.  MyFind$ = MyFindDlg.Find   

Replace    Replace string.  MyRep$ = MyRepDlg.Replace

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
Flags      Set dialog behavior and return results

  Default = 1

  $DEFINE FR_DOWN              &H1
  $DEFINE FR_WHOLEWORD         &H2
  $DEFINE FR_MATCHCASE         &H4
  $DEFINE FR_FINDNEXT          &H8
  $DEFINE FR_REPLACE          &H10
  $DEFINE FR_REPLACEALL       &H20
  $DEFINE FR_DIALOGTERM       &H40
  $DEFINE FR_SHOWHELP         &H80
  $DEFINE FR_ENABLEHOOK      &H100
  $DEFINE FR_NOUPDOWN        &H400
  $DEFINE FR_NOMATCHCASE     &H800
  $DEFINE FR_NOWHOLEWORD    &H1000
  $DEFINE FR_HIDEUPDOWN     &H4000
  $DEFINE FR_HIDEMATCHCASE  &H8000
  $DEFINE FR_HIDEWHOLEWORD &H10000


======================
The PAGEDIALOG Object facilitates setup of page properties in printing.

STRING VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
DlgName    Set/get dialog title

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
Flags      Set dialog behavior and return results

  Default = 0

  $DEFINE PSD_DEFAULTMINMARGINS           &H0
  $DEFINE PSD_INWININIINTLMEASURE         &H0
  $DEFINE PSD_MINMARGINS                  &H1
  $DEFINE PSD_MARGINS                     &H2
  $DEFINE PSD_INTHOUSANDTHSOFINCHES       &H4
  $DEFINE PSD_INHUNDREDTHSOFMILLIMETERS   &H8
  $DEFINE PSD_DISABLEMARGINS             &H10
  $DEFINE PSD_DISABLEPRINTER             &H20
  $DEFINE PSD_NOWARNING                  &H80
  $DEFINE PSD_DISABLEORIENTATION        &H100
  $DEFINE PSD_DISABLEPAPER              &H200
  $DEFINE PSD_RETURNDEFAULT             &H400
  $DEFINE PSD_SHOWHELP                  &H800
  $DEFINE PSD_ENABLEPAGESETUPHOOK      &H2000
  $DEFINE PSD_ENABLEPAGESETUPTEMPLATE  &H8000
  $DEFINE PSD_ENABLEPAGESETUPTEMPLATEHANDLE &H20000
  $DEFINE PSD_ENABLEPAGEPAINTHOOK     &H40000
  $DEFINE PSD_DISABLEPAGEPAINTING     &H80000

MarginLeft  Margin left

MarginTop   Margin top

MarginRight  Margin right

MarginBottom  Margin bottom

MinMarginLeft  Minumum margin left

MinMarginTop  Minumum margin top

MinMarginRight  Minumum margin right

MinMarginBottom  Minumum margin bottom

PaperWidth  Paper width in units set by .Flags or by system default

PaperHeight Paper height in units set by .Flags or by system default


======================
The PRINTDIALOG Object facilitates document printing.

INTEGER VARIABLES (RW):

Name       Description
~~~~       ~~~~~~~~~~~
Copies     Number of copies to print

DC         (R only) Device context handle for selected printer device

DevMode    Sets/gets ram handle to DEVMODE structure

DevNames   Sets/gets ram handle to DEVNAMES structure

Flags      Set dialog behavior and return results

  Default = &H100

  $DEFINE PD_ALLPAGES           &H0
  $DEFINE PD_SELECTION          &H1
  $DEFINE PD_PAGENUMS           &H2
  $DEFINE PD_NOSELECTION        &H4
  $DEFINE PD_NOPAGENUMS         &H8
  $DEFINE PD_COLLATE           &H10
  $DEFINE PD_PRINTTOFILE       &H20
  $DEFINE PD_PRINTSETUP        &H40
  $DEFINE PD_NOWARNING         &H80
  $DEFINE PD_RETURNDC         &H100
  $DEFINE PD_RETURNIC         &H200
  $DEFINE PD_RETURNDEFAULT    &H400
  $DEFINE PD_SHOWHELP         &H800
  $DEFINE PD_ENABLEPRINTHOOK &H1000
  $DEFINE PD_ENABLESETUPHOOK &H2000
  $DEFINE PD_ENABLEPRINTTEMPLATE &H4000
  $DEFINE PD_ENABLESETUPTEMPLATE &H8000
  $DEFINE PD_ENABLEPRINTTEMPLATEHANDLE &H10000
  $DEFINE PD_ENABLESETUPTEMPLATEHANDLE &H20000
  $DEFINE PD_USEDEVMODECOPIES   &H40000
  $DEFINE PD_DISABLEPRINTTOFILE &H80000
  $DEFINE PD_HIDEPRINTTOFILE   &H100000

FromPage   First page to print

MaxPage    Maximum number of pages to print

MinPage    Minimum number of pages to print

ToPage     Last page to print


###########
Please see hotdlg.bas in the HotDialog download for an example and tutorial
on common dialogs coding.


+ PentHouse (registered) version

Copyright 2004-2012 James J Keene PhD
Original Publication: Feb 10, 2004