Tech Note 03b: Using Common Dialog Objects

October 08, 2003

© NSB Corporation. All rights reserved.

For more information on this control, see Microsoft's documentation.

The Common Dialog Objects are a set of objects supplied by Microsoft that can be used in NS BASIC/CE programs. They are included as part of the "ActiveX Control Objects 1.0" download, available at Microsoft's web site. See Tech Note 01 for more information on how to load this module onto your system.

For more information on loading the ActiveX Control Objects, go to Tech Note 01.

The Common Dialog Objects are:

Color Picker
Font Picker
"Save As" dialog
"Select File" dialog
Show Help

All of these are initialized by a single call:

addObject "dialog"

1. The Color Picker

Open the color picker with the command

dialog.ShowColor

The method is not supported for Palm-size PC's.

The following properties can be set before calling:

	dialog.Color [= initial color] 'sets/returns the color 
	dialog.CancelError = True 	'trigger error on cancel?
	dialog.Flags [= value] 'sets flags defining appearance

The value for flags is as follows:

Constant	Value	Description
`cdCClFullOpen`	`&H2`	Entire dialog box is displayed, including the Define Custom Colors section.
`cdlCCHelpButton`	`&H8`	Causes the dialog box to display a Help button.
`cdlCCPreventFullOpen`	`&H4`	Disables the Define Custom Colors command button and prevents the user from defining custom colors.
`cdlCCRGBInit`	`&H1`	Sets the initial color value for the dialog box

You can also define combination values by settingmore than one flag for a dialog box using the Or operator. For example:

dialog.Flags = &H10& Or &H200&

2. The Font Picker

Open the font picker with the command:

Dialog.ShowFont

The following properties can be set before calling:

	Dialog.Max [=int] 'the maximum font size
Dialog.Min [=int] 'the minimun font size
Dialog.CancelError = True 'trgger error on cancel?
Dialog.Flags [=value]

The value for flags is as follows:

Constant	Value	Description
`cdlCFANSIOnly`	`&H400`	Specifies that the dialog box allows only a selection of the fonts that use the Window character set. If this flag is set, the user won't be able to select a font that contains only symbols.
`cdlCFApply`	`&H200`	Enables the Apply button on the dialog box.
`cdlCFBoth`	`&H3`	Causes the dialog box to list the available printer and screen fonts. The hDC property identifies the device context associated with the printer.
`cdlCFEffects`	`&H100`	Specifies that the dialog box enables strikethrough, underline, and color effects.
`cdlCFFixedPitchOnly`	`&H4000`	Specifies that the dialog box selects only fixed pitch fonts.
`cdlCFForceFontExist`	`&H10000`	Specifies that an error message box is displayed if the user attempts to select a font or style that doesn't exist.
`cdlCFHelpButton`	`&H4`	Causes the dialog box to display a Help button.
`cdlCFLimitSize`	`&H2000`	Specifies that the dialog box selects only font sizes within the range specified by the Min and Max properties.

The following properties are set by ShowFont:

Dialog.Color
Dialog.FontBold
Dialog.FontItalic
Dialog.FontName
Dialog.FontSize
Dialog.FontStrikethru
Dialog.FontUnderline

3. The "Save As" Dialog

Open the Save As Dialog with the command:

Dialog.ShowSave
Notes

It returns in dialog.filename an extra leading '\' that must be removed with
the following code:

fn=right(dialog.filename,len(dialog.filename)-1)

Also, even though the dialog is set to dialog.defaultext="cdb", if you don't specifically add in the extension to the file in 'File Name', then you must click on the 'Options' button and Select from Type (set by
dialog.filter="Data (*.cdb)|*.cdb") or it will NOT append the extension to dialog.filename!

Setting dialog.defaultext="cdb" and using dialog.showopen will automatically
add the extension.  Dialog.showopen also returns the correct path without
the extra leading '\'" -- Greg Kelly

On Pocket PC 2003 devices, the Save dialog in the Common Dialog control does not work properly. There is an updated version of this control in the Installers folder on the distribution CD (after Oct, 2003). Copy it into the Windows folder of your device and execute this statement in NS Basic on the device:

shellExecute "open","regsvrce","mscecomdlg.dll"

If this file is not on your CD, email us a support@nsbasic.com and we will send it to you.

 
Properties
The following properties can be set before calling:
Dialog.DialogTitle = "Save As File"
Dialog.InitDir = "\"
Dialog.Flags = 0
Dialog.Filter = "Text|*.txt"
Dialog.DefaultExt = "txt"
Dialog.filename = "" 'initialize
Dialog.Flags [=value]

 


The value for flags follows. Note that the same flags are used for Select File dialog. Also, not all flags work in the current release.
 


Constant

Value

Description


cdlOFNAllowMultiselect

&H200

Specifies that the File Name list box allows multiple selections.The user can select more than one file at run time by pressing the SHIFT key and using the UP ARROW and DOWN ARROW keys to select the desired files. When this is done, the FileName property returns a string containing the names of all selected files. The names in the string are delimited by spaces.


cdlOFNCreatePrompt

&H2000 

Specifies that the dialog box prompts the user to create a file that doesn't currently exist. This flag automatically sets the cdlOFNPathMustExist and cdlOFNFileMustExist flags.


cdlOFNExtensionDifferent

&H400

Indicates that the extension of the returned filename is different from the extension specified by the DefaultExt property. This flag isn't set if the DefaultExt property is Null, if the extensions match, or if the file has no extension. This flag value can be checked upon closing the dialog box.


cdlOFNFileMustExist 

&H1000

Specifies that the user can enter only names of existing files in the File Name text box. If this flag is set and the user enters an invalid filename, a warning is displayed. This flag automatically sets the cdlOFNPathMustExist flag.


cdlOFNHelpButton 

&H10

Causes the dialog box to display the Help button.


cdlOFNHideReadOnly 

&H4

Hides the Read Only check box.


cdlOFNLongNames 

&H200000

Use long filenames.


cdlOFNNoChangeDir 

&H8

Forces the dialog box to set the current directory to what it was when the dialog box was opened.


cdlOFNNoLongNames 

&H40000

No long file names.


cdlOFNNoReadOnlyReturn 

&H8000

Specifies that the returned file won't have the Read Only attribute set and won't be in a write protected directory.


cdlOFNNoValidate 

&H100

Specifies that the common dialog box allows invalid characters in the returned filename.


cdlOFNOverwritePrompt 

&H2

Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.


cdlOFNPathMustExist 

&H800

Specifies that the user can enter only valid paths. If this flag is set and the user enters an invalid path, a warning message is displayed.


cdlOFNReadOnly 

&H1

Causes the Read Only check box to be initially checked when the dialog box is created. This flag also indicates the state of the Read Only check box when the dialog box is closed.


cdlOFNShareAware 

&H4000

Specifies that sharing violation errors will be ignored.



 
 
You can also define selected flags. For example:
Const ReadOnly = &H00000001&
Const Effects = &H00000100&
Dialog.Flags = &H10& Or &H200&
 
The following properties are set by ShowOpen:
Dialog.FileName
 
 
4. The "Select File" Dialog

 
Open the Select File Dialog with the command:
Dialog.ShowOpen
 
The following properties can be set before calling:
Dialog.DialogTitle = "Pick a text file to open"
Dialog.InitDir = "\"
Dialog.Filter = "Text|*.txt"
Dialog.FilterIndex = 1
Dialog.Flags = &H1000 Or &H800 'path and file must exist
Dialog.filename = "" 'initialize

See "Open File" Dialog for information on flag settings.
 
The following properties are set by ShowOpen:
Dialog.FileName
 
 
5. Help Dialog

Open the Help Dialog with the command:
Dialog.ShowHelp
 
The following properties can be set before calling:
Dialog.HelpCommand [ = value]
Dialog.HelpContext [ = string]
Dialog.HelpFile [ = filename]

Values for HelpCommand are as follows:
 


Constant 

Value

Description


cdlHelpCommand 

&H102&

Executes a Help macro.


cdlHelpContents 

&H3&

Displays the Help contents topic as defined by the Contents option in the [OPTION] section of the .hpj file.


cdlHelpContext 

&H1&

Displays Help for a particular context. When using this setting, you must also specify a context using the HelpContext property.


cdlHelpContextPopup 

&H8&

Displays in a pop up window a particular Help topic identified by a context number defined in the [MAP] section of the .hpj file.


cdlHelpForceFile 

&H9&

Ensures WinHelp displays the correct Help file. If the correct Help file is currently displayed, no action occurs. If the incorrect Help file is displayed, WinHelp opens the correct file.


cdlHelpHelpOnHelp 

&H4&

Displays Help for using the Help application itself.


cdlHelpIndex 

&H3&

Displays the index of the specified Help file. An application should use this value only for a Help file with a single index.


cdlHelpKey 

&H101&

Displays Help for a particular keyword. When using this setting, you must also specify a keyword using the HelpKey property.


cdlHelpPartialKey 

&H105&

Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter if there is one exact match. If more than one match exists, the Search dialog box with the topics found listed in the Go To list box is displayed. If no match exists, the Search dialog box is displayed. To bring up the Search dialog box without passing a keyword, use a long pointer to an empty string.


cdlHelpQuit 

&H2&

Notifies the Help application that the specified Help file is no longer in use.


cdlHelpSetContents

&H5&

Determines which contents topic is displayed when a user presses the F1 key.


cdlHelpSetIndex 

&H5&

Sets the context specified by the HelpContext property as the current index for the Help file specified by the HelpFile property. This index remains current until the user accesses a different Help file. Use this value only for Help files with more than one index.



 
If you've created a Windows Help file for your application and set the application's HelpFile property, Help is called when a user presses the Help button. If there is a context number in the HelpContextID property for either the active control or the active form, Help displays a topic corresponding to the current Help context; otherwise it displays the main contents screen. The default location of the file is the \windows directory.
You can also use the HelpFile property to determine which Help file is displayed when a user requests Help from the Object Browser for an ActiveX component.
Simple help files can be normal html: Microsoft notes that building more complex Help files can require the Microsoft Windows Help Compiler, which is available with Visual Basic, Professional Edition.
 
 
 
 
Sample Code

 
Option Explicit

addObject "dialog"

'Color Constants
Private Const cdlCCIFullOpen = &H2
Private Const cdlCCPreventFullOpen = &H4
Private Const cdlCCRGBInit = &H1
    
'Help Constants
Private Const cdlHelpContext = &H1
    
'Font Constants
Private Const cdlCFScreenFonts = &H1
Private Const cdlCFEffects = &H100
Private Const cdlCFLimitSize = &H2000
Private Const cdlCFForceFontExist = &H10000
dim selection
selection=0

while selection<>9
  selection=inputbox("Choose Common Dialog Operation:" & chr(13) & "1. Color" & chr(13) & "2. Font" & chr(13) & "3. Save As " & chr(13) & "4. Select File" & chr(13) & "5. Show Help" & chr(13) &  "9. End Program", "COMM Demo")
  select case selection
  case 1
    cmdColor_click
  case 2
    cmdFont_click
  case 3
    cmdSaveAs_click
  case 4
    cmdSelectFile_click
  case 5
    cmdShowHelp_click
  case else
    selection=9
  end select
wEnd

Private Sub cmdColor_Click()
  dim txtcolorRGB
  txtColorRGB=output.backcolor  
  'On Error Resume Next
        
  'Generate error if cancel is pressed
  dialog.CancelError = True

  'Check if the text in the text box is a number,
  'if so, use it as our initial color

  If IsNumeric(txtColorRGB) then
    dialog.Color = txtColorRGB.Text
    dialog.Flags = cdlCCRGBInit
  End If
  'Ensure Full Open
  dialog.Flags = dialog.Flags + cdlCCIFullOpen
  'Show the dialog
  dialog.ShowColor
       
  'Determine action to take after dialog is dismissed
  If Err.Number = 0 Then 
  txtColorRGB = dialog.Color 'everything OK
  output.BackColor = dialog.Color
ElseIf Err.Number = 32755 Then
  'The user canceled the dialog, so do nothing
Else
  MsgBox "Error in Common Dialog ShowColor" & vbCrLf & vbCrLf & _
    Err.Number & ": " & Err.Description, vbCritical, "Common Dialog ShowColor"
End If

End Sub

Private Sub cmdFont_Click()
  'Set minimum and maximum font sizes
  dialog.Max = 30
  dialog.Min = 8
        
  'Generate error if cancel is pressed
  dialog.CancelError = True
        
  'Setup flags for what we want to show
  dialog.Flags = cdlCFForceFontExist Or cdlCFLimitSize Or cdlCFEffects Or cdlCFScreenFonts
        
  On Error Resume Next
  'Show the font dialog
  dialog.ShowFont
        
  'Determine action to take after dialog is dismissed
  If Err.Number = 0 Then
    on error goto 0
    output.ForeColor = dialog.Color
    output.FontBold = dialog.FontBold
    output.FontItalic = dialog.FontItalic
    output.FontName = dialog.FontName
    output.FontSize = dialog.FontSize
    output.FontStrikethru = dialog.FontStrikethru
    output.FontUnderline = dialog.FontUnderline
  ElseIf Err.Number = 32755 Then
    'The user canceled the dialog, so do nothing
  Else
    MsgBox "Error in Common Dialog ShowFont" & vbCrLf & vbCrLf & _
      Err.Number & ": " & Err.Description, vbCritical, "Common Dialog ShowFont"
  End If
  output.drawtext "This is the new font"
End Sub

Private Sub cmdSaveAs_Click()
  dialog.DialogTitle = "Save As File"
  dialog.InitDir = "\"
  dialog.Flags = 0
  dialog.Filter = "Text|*.txt"
  dialog.DefaultExt = "txt"
  dialog.filename = ""   'initialize
        
  'Generate error if cancel is pressed
  dialog.CancelError = True
  On Error Resume Next
        
  'Show the Save As Dialog
  dialog.ShowSave
        
  'Determine action to take after dialog is dismissed
  If Err.Number = 0 Then
    txtFileName = dialog.filename
  ElseIf Err.Number = 32755 Then
    'The user canceled the dialog, so do nothing
  Else
    MsgBox "Error in Common Dialog ShowSave" & vbCrLf & vbCrLf & _
      Err.Number & ": " & Err.Description, vbCritical, "Common Dialog ShowSave"
  End If
End Sub

Private Sub cmdSelectFile_Click()
  dialog.DialogTitle = "Pick a text file to open"
  dialog.InitDir = "\"
  dialog.Filter = "Text|*.txt"
  dialog.FilterIndex = 1
  dialog.Flags = &H1000 Or &H800  'path and file must exist
  dialog.filename = ""   'initialize
        
  'Generate error if cancel is pressed
  dialog.CancelError = True
  On Error Resume Next
        
  dialog.ShowOpen
      
  'Determine action to take after dialog is dismissed
  If Err.Number = 0 Then
    txtFileName = dialog.filename
  ElseIf Err.Number = 32755 Then
    'The user canceled the dialog, so do nothing
  Else
    MsgBox "Error in Common Dialog ShowOpen" & vbCrLf & vbCrLf & _
      Err.Number & ": " & Err.Description, vbCritical, "Common Dialog ShowOpen"
  End If  
End Sub

Private Sub cmdShowHelp_Click()
  dialog.HelpFile = "nsbasic.htc"
  'dialog.HelpCommand = cdlHelpContext
  'dialog.HelpContext = "adjusting_memory_and_power_settings"
  dialog.ShowHelp    
End Sub

Constant	Value	Description
`cdlHelpCommand`	`&H102&`	Executes a Help macro.
`cdlHelpContents`	`&H3&`	Displays the Help contents topic as defined by the Contents option in the [OPTION] section of the .hpj file.
`cdlHelpContext`	`&H1&`	Displays Help for a particular context. When using this setting, you must also specify a context using the HelpContext property.
`cdlHelpContextPopup`	`&H8&`	Displays in a pop up window a particular Help topic identified by a context number defined in the [MAP] section of the .hpj file.
`cdlHelpForceFile`	`&H9&`	Ensures WinHelp displays the correct Help file. If the correct Help file is currently displayed, no action occurs. If the incorrect Help file is displayed, WinHelp opens the correct file.
`cdlHelpHelpOnHelp`	`&H4&`	Displays Help for using the Help application itself.
`cdlHelpIndex`	`&H3&`	Displays the index of the specified Help file. An application should use this value only for a Help file with a single index.
`cdlHelpKey`	`&H101&`	Displays Help for a particular keyword. When using this setting, you must also specify a keyword using the HelpKey property.
`cdlHelpPartialKey`	`&H105&`	Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter if there is one exact match. If more than one match exists, the Search dialog box with the topics found listed in the Go To list box is displayed. If no match exists, the Search dialog box is displayed. To bring up the Search dialog box without passing a keyword, use a long pointer to an empty string.
`cdlHelpQuit`	`&H2&`	Notifies the Help application that the specified Help file is no longer in use.
`cdlHelpSetContents`	`&H5&`	Determines which contents topic is displayed when a user presses the F1 key.
`cdlHelpSetIndex`	`&H5&`	Sets the context specified by the HelpContext property as the current index for the Help file specified by the HelpFile property. This index remains current until the user accesses a different Help file. Use this value only for Help files with more than one index.