==============================
JF Software VB Modules
By Joshua Foster - JF Software
http://www.jfsoftware.net
jfsoftware@jfsoftware.net
June 12, 2002
==============================
CommonDialog class module
=========================
Description: Calls the Common Dialog boxes Open File, Save File, Choose Color, Choose Font, Print, and Print Setup.


Procedures:
===========
---------
ShowColor
---------
Syntax:       ShowColor(frmObject As Form, [lngRGBInit As Long]) As Long
Description:  Shows the Choose Color dialog box.
Return Value: The color chosen. (-1 if error occured)
Parameters:   frmObject    - The form calling the dialog box.
              [lngRGBInit] - The default color (optional; if not specified, 0).
Properties:   Name:        CPAnyColor
              Type:        Boolean
              Description: Allow the user to select any color.

              Name:        CPFullOpen
              Type:        Boolean
              Description: Automatically display the Define Custom Colors half of the dialog box.

              Name:        CPDisableFullOpen
              Type:        Boolean
              Description: Disable the button that displays the Define Custom Colors half of the dialog box.

              Name:        CPSolidColorsOnly
              Type:        Boolean
              Description: Only allow the user to select solid colors. If the user attempts to select a non-solid color,
                           convert it to the closest solid color.

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog  'Load the cComDlg object
cComDlg.CPAnyColor = True       'Allow user to select any color.
MsgBox cComDlg.ShowColor(Me, RGB(255, 0, 0))   'MsgBox the color chosen (red color default)
End Sub


--------
ShowFont
--------
Syntax:            ShowFont(frmObject As Form, strDefaultFontName As String, intDefaultFontSize As Integer, bBold As _
                   Boolean, bItalic As Boolean, bUnderline As Boolean, bStrikeThru As Boolean) As Boolean
Description:       Shows the Choose Font dialog box.
Return Value:      Returns true if successful, false if an error occured.  Also, sets the return properties listed below with
                   the returned values.
Parameters:        frmObject          - The form calling the dialog box.
                   strDefaultFontName - The default font name.
                   intDefaultFileSize - The default font size. (Doesn't work)
                   bBold              - The default bold setting.
                   bItalic            - The default italic setting.
                   bUnderline         - The default underline setting.
                   bStrikethru        - The default strikethru setting.
Return Properties: Name:        FontName
                   Type:        String (Read-only)
                   Description: The selected font name.

                   Name:        FontSize
                   Type:        Integer (Read-only)
                   Description: The selected font size.

                   Name:        FontBold
                   Type:        Boolean (Read-only)
                   Description: The selected bold setting.

                   Name:        FontItalic
                   Type:        Boolean (Read-only)
                   Description: The selected italic setting.

                   Name:        FontUnderline
                   Type:        Boolean (Read-only)
                   Description: The selected underline setting.

                   Name:        FontStrikeThru
                   Type:        Boolean (Read-only)
                   Description: The selected strikethru setting.

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog  'Load the cComDlg object
Call cComDlg.ShowFont Me, "Times New Roman", 12, False, False, False, False  'Open the Choose Font box with Times New Roman 12
' MsgBox the results of the Choose Font window.
With cComDlg
    MsgBox "Font Name: " & .FontName & vbCrLf & "Font Size: " & .FontSize & vbCrLf & "Bold: " & .FontBold & vbCrLf & _
           "Italic: " & .FontItalic & vbCrLf & "Strikethru: " & .FontStrikeThru & vbCrLf & "Underline: " & .FontUnderline
End With
End Sub


--------
ShowOpen
--------
Syntax:            ShowOpen(frmObject As Form, strDefaultFileName As String, strDefaultFolder As String, strFilterNames() _
                   As String, strFilterTypes() As String, intFilterIndex As Integer, strDefaultExt As String, strDialogTitle _
                   As String, blnMulti As Boolean) As Boolean
Description:       Shows the Open File dialog box.
Return Value:      Returns true if successful, false if an error occured.  Also, sets the OSR properties listed below with the
                   returned values.
Parameters:        frmObject          - The form calling the dialog box.
                   strDefaultFileName - The default file name. (Example: "tester.txt")
                   strDefaultFolder   - The default path. (Example: "C:\MyApp\")
                   strFilterNames()   - An array of filter item names
                   strFilterTypes()   - An array of filter item types
                                        ***NOTE***: If the dimensions and sizes of these two arrays are different, you will
                                                    get an object error!
                   intFilterIndex     - The default filter item (1 is the first, 2 is the second, etc.)
                   strDefaultExt      - The default file extension (Example: "txt")
                   strDialogTitle     - The title of the dialog box.
                   blnMulti           - Set as true to allow selection of multiple files, false to allow single selection only

Properties:        Name:        OSPCheckReadOnly
                   Type:        Boolean
                   Description: Check the Open As Read Only box.

                   Name:        OSPFileMustExist
                   Type:        Boolean
                   Description: Only allow the selection of existing files.

                   Name:        OSPHideNetworkButton
                   Type:        Boolean
                   Description: Hide and disable the Network button in the dialog box.

                   Name:        OSPHideReadOnly
                   Type:        Boolean
                   Description: Hide the Open As Read Only check box.

                   Name:        OSPIgnoreSharing
                   Type:        Boolean
                   Description: Ignore any file sharing violations.

                   Name:        OSPNoTestFile
                   Type:        Boolean
                   Description: Do not create a test file before the box closes. Normally, this check is done to verify that
                                the disk exists, that there is sufficient disk space, etc. However, this check should not be
                                used on a create-nonmodify network share. Setting this flag to True prevents this test from
                                being done.

                   Name:        OSPNoValidate
                   Type:        Boolean
                   Description: Don't check the filename for invalid characters.

                   Name:        OSPPathMustExist
                   Type:        Boolean
                   Description: Only allow the selection of existing paths.

                   Name:        OSPPreserveCurrentDirectory
                   Type:        Boolean
                   Description: Don't change Windows's current directory to match the one chosen in the dialog box.

                   Name:        OSPPromptCreateIfNotExists
                   Type:        Boolean
                   Description: Prompt if a non-existing file is chosen.

                   Name:        OSPPromptIfExists
                   Type:        Boolean
                   Description: Prompt the user if the chosen file already exists.

                   Name:        OSPReturnShortcutFile
                   Type:        Boolean
                   Description: If a shortcut file (.lnk or .pif) is chosen, return the shortcut file itself instead of the
                                file or directory it points to.

Return Properties: Name:        OSR83File
                   Type:        Boolean (Read-only)
                   Description: The 8.3 file name and extension only of the selected file. (blank if blnMulti is true)

                   Name:        OSR83PathFile
                   Type:        Boolean (Read-only)
                   Description: The 8.3 path name, file name, and extension of the selected file. (blank if blnMulti is true)

                   Name:        OSRExtension
                   Type:        Boolean (Read-only)
                   Description: The extension only of the selected file. (blank if blnMulti is true)

                   Name:        OSRFile
                   Type:        Boolean (Read-only)
                   Description: The file name and extension only of the selected file. (a list of files if blnMulti is true)

                   Name:        OSRPath
                   Type:        Boolean (Read-only)
                   Description: The path name only of the selected file. (a list of files if blnMulti is true)

                   Name:        OSRPathFile
                   Type:        Boolean (Read-only)
                   Description: The path name, file name, and extension of the selected file. (a list of files if blnMulti is
                                true)

                   Name:        OSRReadOnly
                   Type:        Boolean (Read-only)
                   Description: The read-only attribute of the selected file. (false if blnMulti is true)

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog        'Load the cComDlg object
Dim temparraynames(1 To 3) As String  'Create a 3-item array for the filter names
Dim temparraytypes(1 To 3) As String  'Create a 3-item array for the filter types
temparraynames(1) = "Text files"      'Set the first filter item for text files
temparraytypes(1) = "*.txt"
temparraynames(2) = "Word files"      'Set the second filter item for Word files
temparraytypes(2) = "*.doc"
temparraynames(3) = "All files"       'Set the third filter item for all files
temparraytypes(3) = "*.*"
With cComDlg  'Set up the properties of the Open File box.
    .OSPPromptCreateIfNotExists = True
    .OSPReturnShortcutFile = True
    .OSPPathMustExist = True
    .OSPFileMustExist = True
End With
'Open the Open File box with a default filename of "default.txt" in the "C:\MyApp" directory, using the filters created above
'(first one being default), with a default extension of "txt", and the title "Open a Text File", only single selection
Call cComDlg.ShowOpen(Me, "default.txt", "C:\MyApp", temparraynames(), temparraytypes(), 1, "txt", "Open a Text File", False)
MsgBox cComDlg.OSRPathFile  'MsgBox the path name, file name, and extension
End Sub


--------
ShowSave
--------
Syntax:            ShowSave(ByVal frmObject As Form, ByVal strDefaultFileName As String, strDefaultFolder As String, _
                   strFilterNames() As String, strFilterTypes() As String, ByVal intFilterIndex As Integer, ByVal _
                   strDefaultExt As String, ByVal strDialogTitle As String) As Boolean
Description:       Shows the Save File dialog box.
Return Value:      Returns true if successful, false if an error occured.  Also, sets the OSR properties listed below with the
                   returned values.
Parameters:        frmObject          - The form calling the dialog box.
                   strDefaultFileName - The default file name. (Example: "tester.txt")
                   strDefaultFolder   - The default path. (Example: "C:\MyApp\")
                   strFilterNames()   - An array of filter item names
                   strFilterTypes()   - An array of filter item types
                                        ***NOTE***: If the dimensions and sizes of these two arrays are different, you will
                                                    get an object error!
                   intFilterIndex     - The default filter item (1 is the first, 2 is the second, etc.)
                   strDefaultExt      - The default file extension (Example: "txt")
                   strDialogTitle     - The title of the dialog box.

Properties:        Name:        OSPCheckReadOnly
                   Type:        Boolean
                   Description: Check the Open As Read Only box.

                   Name:        OSPFileMustExist
                   Type:        Boolean
                   Description: Only allow the selection of existing files.

                   Name:        OSPHideNetworkButton
                   Type:        Boolean
                   Description: Hide and disable the Network button in the dialog box.

                   Name:        OSPHideReadOnly
                   Type:        Boolean
                   Description: Hide the Open As Read Only check box.

                   Name:        OSPIgnoreSharing
                   Type:        Boolean
                   Description: Ignore any file sharing violations.

                   Name:        OSPNoTestFile
                   Type:        Boolean
                   Description: Do not create a test file before the box closes. Normally, this check is done to verify that
                                the disk exists, that there is sufficient disk space, etc. However, this check should not be
                                used on a create-nonmodify network share. Setting this flag to True prevents this test from
                                being done.

                   Name:        OSPNoValidate
                   Type:        Boolean
                   Description: Don't check the filename for invalid characters.

                   Name:        OSPPathMustExist
                   Type:        Boolean
                   Description: Only allow the selection of existing paths.

                   Name:        OSPPreserveCurrentDirectory
                   Type:        Boolean
                   Description: Don't change Windows's current directory to match the one chosen in the dialog box.

                   Name:        OSPPromptCreateIfNotExists
                   Type:        Boolean
                   Description: Prompt if a non-existing file is chosen.

                   Name:        OSPPromptIfExists
                   Type:        Boolean
                   Description: Prompt the user if the chosen file already exists.

                   Name:        OSPReturnShortcutFile
                   Type:        Boolean
                   Description: If a shortcut file (.lnk or .pif) is chosen, return the shortcut file itself instead of the
                                file or directory it points to.

Return Properties: Name:        OSR83File
                   Type:        Boolean (Read-only)
                   Description: The 8.3 file name and extension only of the selected file.

                   Name:        OSR83PathFile
                   Type:        Boolean (Read-only)
                   Description: The 8.3 path name, file name, and extension of the selected file.

                   Name:        OSRExtension
                   Type:        Boolean (Read-only)
                   Description: The extension only of the selected file.

                   Name:        OSRFile
                   Type:        Boolean (Read-only)
                   Description: The file name and extension only of the selected file.

                   Name:        OSRPath
                   Type:        Boolean (Read-only)
                   Description: The path name only of the selected file.

                   Name:        OSRPathFile
                   Type:        Boolean (Read-only)
                   Description: The path name, file name, and extension of the selected file.

                   Name:        OSRReadOnly
                   Type:        Boolean (Read-only)
                   Description: The read-only attribute of the selected file.

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog        'Load the cComDlg object
Dim temparraynames(1 To 3) As String  'Create a 3-item array for the filter names
Dim temparraytypes(1 To 3) As String  'Create a 3-item array for the filter types
temparraynames(1) = "Text files"      'Set the first filter item for text files
temparraytypes(1) = "*.txt"
temparraynames(2) = "Word files"      'Set the second filter item for Word files
temparraytypes(2) = "*.doc"
temparraynames(3) = "All files"       'Set the third filter item for all files
temparraytypes(3) = "*.*"
cComDlg.OSPPromptIfExists = True  'Set up the properties of the Save File box.
'Open the Save File box with a default filename of "default.txt" in the "C:\MyApp" directory, using the filters created above
'(first one being default), with a default extension of "txt", and the title Save a Text File"
Call cComDlg.ShowSave(Me, "default.txt", "C:\MyApp", temparraynames(), temparraytypes(), 1, "txt", Save a Text File")
MsgBox cComDlg.OSRPathFile  'MsgBox the path name, file name, and extension
End Sub


---------
ShowPrint
---------
Syntax:       ShowPrint(frmObject As Form) As Boolean
Description:  Shows the Print dialog box.
Return Value: Returns true if successful, false if an error occured.
Parameters:   frmObject - The form calling the dialog box.

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog  'Load the cComDlg object
MsgBox cComDlg.ShowPrint(Me)  'Show the Print dialog box
End Sub


--------------
ShowPrintSetup
--------------
Syntax:       ShowPrintSetup(frmObject As Form) As Boolean
Description:  Shows the Print Setup dialog box.
Return Value: Returns true if successful, false if an error occured.
Parameters:   frmObject - The form calling the dialog box.

Example:
--------
Private cComDlg As CommonDialog  'Define a CommonDialog object

Private Sub Form_Load()
Set cComDlg = New CommonDialog  'Load the cComDlg object
MsgBox cComDlg.ShowPrintSetup(Me)  'Show the Print Setup dialog box
End Sub
