10/14/01 - CFOAPI - Custom File Open for VEE 5.01
                    Application Programming Interface documentation

Copyright (C) 2001 by Creative Systems Software, all rights reserved.
Written by Shawn Fessenden
  shawn@oswegosw.com		Old Oswego Software, Inc. address.
  shawnf@intersurfer.com	Personal.
  shawn@step2000.net		New OSI Systems, Inc. address.

You are free to use, copy and distribute CFO.dll and CFO.c as you see fit.
Please retain original copyright notice in all modified versions.

CFO.dll implements an interface to VEE 5.01 for customizing the Common File
Open Dialog distributed with Windows. SelectFile can be used by itself
without any setup. Default parameters are as follows:

Dialog title is Select File.
Dialog is centered in screen.
List view is switched to Details option, a.k.a. report mode.
List items are sorted decending by date, a.k.a. last modified time.
Dialog flags are OFN_ENABLEHOOK + OFN_EXPLORER. See SDK for more info.
Dialog is not initialized with a file name.
No filters are defined.
No initial directory is defined.
No default extension is defined.

All internal string buffers are 260 characters in length, plus one character
for zero-termination. Any strings passed to the CFOAPI that are greater than
260 characters in length are rejected. In this case, the API returns a value
of BOOL 0 (VEE int 0) to indicate the call failed.

Where cbBufSize parameters are indicated, these are the length of [out]
string buffers (for strings being returned to VEE). If a GetXXX call is made
with a buffer of insufficient length to return the complete string, the
CFOAPI returns a count of copied characters of 0 (VEE int 0) to indicate the
return buffer is too short.

NOTE: it is recommended to use VEE's strLen function as the input to any
      cbBufSize parameter. This guarantees that the cbBufSize parameter
      exactly reflects the length of the string buffer.

To allocate a string buffer in VEE, use a Formula object containing the
formula: "*" * nChars where 'nChars' is the number of characters to allocate.
The Result pin of the Formula object can be connected to the buffer input pin
(or substituted for the buffer parameter) of any CFOAPI call.

Windows types are shown in this API reference. A VEE 5.01 compatible
definition is listed after Parameters and before Returns.

-----------------------------------------------------------------------------

BOOL SelectFile(PCHAR pTitle, PCHAR pFilename, INT cbBufSize)

Description:
  SelectFile opens a Common File Open dialog box and customizes it in various
  ways as specified by other calls.

Parameters:
  [in]  PCHAR pTitle     Title displayed on dialog.

  [out] PCHAR pFilename  Selected file returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pFilename.

VEE Definition:
  int SelectFile(char *pTitle, char *pFilename, int cbBufSize);

Returns:
  Returns 0 if Cancel button clicked. Returns non-zero if OK button clicked.

Remarks:
  The default title for the dialog is "Select File". If you wish to display
  a different title, call the SetTitle function and pass 0 for pTitle in your
  call to this function.

-----------------------------------------------------------------------------

VOID InitMembers(VOID)

Description:
  InitMembers re-initializes all parameters to default values.

Parameters:
  None.

VEE Definition:
  void InitMembers(void);

Returns:
  Nothing.

-----------------------------------------------------------------------------

BOOL SetTitle(PCHAR pTitle)

Description:
  Sets title to appear on dialog box.

Parameters:
  [in]  PCHAR pTitle     Title displayed on dialog.

VEE Definition:
  int SetTitle(char *pTitle);

Returns:
  This function returns 0 if the length of the passed string is greater than
  260 characters. It returns non-zero if the function succeedes.

-----------------------------------------------------------------------------

BOOL SetInitFile(PCHAR pFile)

Description:
  Sets the file name initially displayed in the File name edit control of the
  File Open dialog box.

Parameters:
  [in]  PCHAR pFile      Initial file name displayed in the File name edit
                         control of the File Open dialog box.

VEE Definition:
  int SetInitFile(char *pFile);

Returns:
  This function returns 0 if the length of the passed string is greater than
  260 characters. It returns non-zero if the function succeedes.

-----------------------------------------------------------------------------

INT  GetFilename(PCHAR pFilename, INT cbBufSize)

Description:
  Gets the full path and file name of the file selected by the user.

Parameters:
  [out] PCHAR pFilename  Selected file returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pFilename.

VEE Definition:
  int GetFilename(char *pFilename, int cbBufSize);

Returns:
  This function returns the number of characters copied to the output string
  buffer, or 0 if the user supplied buffer is of insufficient length to
  return the complete string.

Remarks:
  If the function returns 0 and the pFilename parameter is still what
  it was set to before the call, then the length of the buffer is
  insufficient to return the complete string. If the function returns 0 and
  the pFilename parameter is a zero-length string after the call, then there
  is no selected file name to return.

-----------------------------------------------------------------------------

INT  GetFiletitle(PCHAR pFiletitle, INT cbBufSize)

Description:
  Gets the title of the selected file.

Parameters:
  [out] PCHAR pFiletitle Selected file returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pFilename.

VEE Definition:
  int GetFiletitle(char *pFiletitle, int cbBufSize);

Returns:
  This function returns the number of characters copied to the output string
  buffer, or 0 if the user supplied buffer is of insufficient length to
  return the complete string.

Remarks:
  If the function returns 0 and the pFiletitle parameter is still what
  it was set to before the call, then the length of the buffer is
  insufficient to return the complete string. If the function returns 0 and
  the pFilename parameter is a zero-length string after the call, then there
  is no selected file title to return.

-----------------------------------------------------------------------------

BOOL SetFilter(PCHAR pFilter)

Description:
  Sets the lpcstrFilter member of the OPENFILENAME structure.

Parameters:
  [in]  PCHAR pFilter    Filename filter string.

VEE Definition:
  int SetFilter(char *pFilter);

Returns:
  This function returns 0 if the length of the passed string is greater than
  260 characters. It returns non-zero if the function succeedes.

Remarks:
  File filters are the strings displayed in the "Files of type" dropdown list
  shown below the "File name" edit control on the File Open dialog box. A
  filter string is composed of pairs of descriptions and filters. The
  description component is displayed in the "Files of type" dropdown. The
  filter component is used to filter the list of files displayed in the list
  view control. To specify multiple filter patterns for a single discription,
  separate the patterns with a semi-colon. Pairs of descriptions and filters
  are separated with a vertical bar character (|).

Examples:
  "Text Files (*.txt)|*.txt" 
  This example contains one description / filter pair.

  "VEE Files (*.vee)|*.vee|All Files|*.*"
  This example contains two description / filter pairs.

  "Picture Files (bmp, gif, tif)|*.bmp;*.gif;*.tif|VEE Files|*.vee"
  This example contains two description / filter pairs, one of which has
  multiple filter patterns.

-----------------------------------------------------------------------------

INT  GetFilter(PCHAR pFilter, INT cbBufSize)

Description:
  Gets the currently defined filter string.

Parameters:
  [out] PCHAR pFilter    Current filter string returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pFilename.

VEE Definition:
  int GetFilter(char *pFilter, int cbBufSize);

Returns:
  This function returns the number of characters copied to the output string
  buffer, or 0 if the user supplied buffer is of insufficient length to
  return the complete string.

Remarks:
  If the function returns 0 and the pFilter parameter is still what it was
  set to before the call, then the length of the buffer is insufficient to
  return the complete string. If the function returns 0 and the pFilter
  parameter is a zero-length string after the call, then there is no filter
  string to return. See SetFilter above for filter string details.
  
-----------------------------------------------------------------------------

VOID SetFilterIndex(INT iFilterIndex)

Description:
  This function sets the default filter to display when the Open File dialog
  box is displayed.

Parameters:
  [in]  INT   iFilterIndex Default filter.

VEE Definition:
  void SetFilterIndex(int iFilterIndex);

Returns:
  Nothing.

Remarks:
  The first description / filter pair is numbered 1. If the default filter
  index is set to 0, then no filter is displayed in the "Files of type"
  dropdown and no filtering is performed on the files listed in the list
  view control. However if a filter string has been set then it's
  descriptions are displayed in the "Files of type" dropdown. If the default
  filter index is set to a number greater than the number of description /
  filter pairs in the current filter string, then the behavior of the File
  Open dialog box is undefined.

-----------------------------------------------------------------------------

BOOL SetInitDir(PCHAR pInitDir)

Description:
  Sets the initial directory for the File Open dialog box.

Parameters:
  [in]  PCHAR pInitDir   Initial directory.

VEE Definition:
  int SetInitDir(char *pInitDir);

Returns:
  This function returns 0 if the length of the passed string is greater than
  260 characters. It returns non-zero if the function succeedes.

-----------------------------------------------------------------------------

INT  GetInitDir(PCHAR pInitDir, INT cbBufSize)

Parameters:
  [out] PCHAR pInitDir   Initial directory returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pInitDir.

VEE Definition:
  int GetInitdir(char *pInitDir, int cbBufSize);

Returns:
  This function returns the number of characters copied to the output string
  buffer, or 0 if the user supplied buffer is of insufficient length to
  return the complete string.

-----------------------------------------------------------------------------

BOOL SetDefExt(PCHAR pDefExt)

Parameters:
  [in]  PCHAR pDefExt    Default extension.

VEE Definition:
  int SetDefExt(char *pDefExt);

Returns:
  This function returns 0 if the length of the passed string is greater than
  3 characters. It returns non-zero if the function succeedes.

Remarks:
  This is the default file extension appended to the filename if the user
  does not supply an extension. This extension should not contain a period.

-----------------------------------------------------------------------------
  
INT  GetDefExt(PCHAR pDefExt, INT cbBufSize)

Parameters:
  [out] PCHAR pDefExt    Default extension string returned to caller.

  [in]  INT   cbBufSize  Size of buffer pointed to by pDefExt.

VEE Definition:
  int GetDefExt(char *pDefExt, int cbBufSize);

Returns:
  This function returns the number of characters copied to the output string
  buffer, or 0 if the user supplied buffer is of insufficient length to
  return the complete string.

-----------------------------------------------------------------------------

VOID SetFlags(UINT uFlags)

Parameters:
  [in]  UINT  uFlags     Flags used to control the behavior and appearance
                         of the Open File dialog box.

VEE Definition:
  void SetFlags(int uFlags);

Returns:
  Nothing.

Remarks:
  There are flags defined to control just about every aspect of the dialog
  box, except of course what view to use for the list view and how to sort
  the list of files (which is why we're doing this of course). This is the
  list of flags from the January 2001 SDK:

OFN_ALLOWMULTISELECT = &H200
  Specifies that the File Name list box allows multiple selections. If you
  also set the OFN_EXPLORER flag, the dialog box uses the Explorer-style user
  interface; otherwise, it uses the old-style user interface.

  If the user selects more than one file, the lpstrFile buffer returns the
  path to the current directory followed by the file names of the selected
  files. The nFileOffset member is the offset, in bytes or characters, to the
  first file name, and the nFileExtension member is not used. For Explorer-
  style dialog boxes, the directory and file name strings are NULL separated,
  with an extra NULL character after the last file name. This format enables
  the Explorer-style dialog boxes to return long file names that include
  spaces. For old-style dialog boxes, the directory and file name strings
  are separated by spaces and the function uses short file names for file
  names with spaces. You can use the FindFirstFile function to convert
  between long and short file names. 

  If you specify a custom template for an old-style dialog box, the
  definition of the File Name list box must contain the LBS_EXTENDEDSEL
  value. 

OFN_CREATEPROMPT = &H2000
  If the user specifies a file that does not exist, this flag causes the
  dialog box to prompt the user for permission to create the file. If the
  user chooses to create the file, the dialog box closes and the function
  returns the specified name; otherwise, the dialog box remains open. If you
  use this flag with the OFN_ALLOWMULTISELECT flag, the dialog box allows
  the user to specify only one nonexistent file.  

OFN_DONTADDTORECENT = 
  Windows 2000: Prevents the system from adding a link to the selected file
  in the file system directory that contains the user's most recently used
  documents. To retrieve the location of this directory, call the
  SHGetSpecialFolderLocation function with the CSIDL_RECENT flag.  

OFN_ENABLEHOOK = &H20
  Enables the hook function specified in the lpfnHook member. 

OFN_ENABLEINCLUDENOTIFY l= &H400000
  Windows 2000: Causes the dialog box to send CDN_INCLUDEITEM notification
  messages to your OFNHookProc hook procedure when the user opens a folder.
  The dialog box sends a notification for each item in the newly opened
  folder. These messages enable you to control which items the dialog box
  displays in the folder's item list.  

OFN_ENABLESIZING = &H800000
  Windows 2000, Windows 98: Enables the Explorer-style dialog box to be
  resized using either the mouse or the keyboard. By default, the
  Explorer-style Open and Save As dialog boxes allow the dialog box to be
  resized regardless of whether this flag is set. This flag is necessary
  only if you provide a hook procedure or custom template. The old-style
  dialog box does not permit resizing. 

OFN_ENABLETEMPLATE = &H40
  Indicates that the lpTemplateName member is a pointer to the name of a
  dialog template resource in the module identified by the hInstance member.
  If the OFN_EXPLORER flag is set, the system uses the specified template to
  create a dialog box that is a child of the default Explorer-style dialog
  box. If the OFN_EXPLORER flag is not set, the system uses the template to
  create an old-style dialog box that replaces the default dialog box.

OFN_ENABLETEMPLATEHANDLE = &H80
  Indicates that the hInstance member identifies a data block that contains
  a preloaded dialog box template. The system ignores the lpTemplateName if
  this flag is specified. If the OFN_EXPLORER flag is set, the system uses
  the specified template to create a dialog box that is a child of the
  default Explorer-style dialog box. If the OFN_EXPLORER flag is not set,
  the system uses the template to create an old-style dialog box that
  replaces the default dialog box.

OFN_EXPLORER = &H80000
  Indicates that any customizations made to the Open or Save As dialog box
  use the new Explorer-style customization methods. For more information,
  see Explorer-Style Hook Procedures and Explorer-Style Custom Templates. By
  default, the Open and Save As dialog boxes use the Explorer-style user
  interface regardless of whether this flag is set. This flag is necessary
  only if you provide a hook procedure or custom template, or set the
  OFN_ALLOWMULTISELECT flag. If you want the old-style user interface, omit
  the OFN_EXPLORER flag and provide a replacement old-style template or hook
  procedure. If you want the old style but do not need a custom template or
  hook procedure, simply provide a hook procedure that always returns FALSE.

OFN_EXTENSIONDIFFERENT = 
  Specifies that the user typed a file name extension that differs from the
  extension specified by lpstrDefExt. The function does not use this flag if
  lpstrDefExt is NULL. 

OFN_FILEMUSTEXIST = &H1000
  Specifies that the user can type only names of existing files in the File
  Name entry field. If this flag is specified and the user enters an invalid
  name, the dialog box procedure displays a warning in a message box. If this
  flag is specified, the OFN_PATHMUSTEXIST flag is also used. 

OFN_FORCESHOWHIDDEN = 
  Windows 2000: Forces the showing of system and hidden files, thus
  overriding the user setting to show or not show hidden files. However, a
  file that is marked both system and hidden is not shown. 

OFN_HIDEREADONLY = 
  Hides the Read Only check box. 

OFN_LONGNAMES = &H200000
  For old-style dialog boxes, this flag causes the dialog box to use long
  file names. If this flag is not specified, or if the OFN_ALLOWMULTISELECT
  flag is also set, old-style dialog boxes use short file names (8.3 format)
  for file names with spaces. Explorer-style dialog boxes ignore this flag
  and always display long file names.
 
OFN_NOCHANGEDIR = &H8
  Restores the current directory to its original value if the user changed
  the directory while searching for files. 

OFN_NODEREFERENCELINKS = &H100000
  Directs the dialog box to return the path and file name of the selected
  shortcut (.LNK) file. If this value is not specified, the dialog box
  returns the path and file name of the file referenced by the shortcut. 

OFN_NOLONGNAMES = &H40000
  For old-style dialog boxes, this flag causes the dialog box to use short
  file names (8.3 format). Explorer-style dialog boxes ignore this flag and
  always display long file names.

OFN_NONETWORKBUTTON = &H20000
  Hides and disables the Network button. 

OFN_NOREADONLYRETURN = &H8000
  Specifies that the returned file does not have the Read Only check box
  selected and is not in a write-protected directory. 

OFN_NOTESTFILECREATE = &H10000
  Specifies that the file is not created before the dialog box is closed.
  This flag should be specified if the application saves the file on a
  create-nonmodify network share. When an application specifies this flag,
  the library does not check for write protection, a full disk, an open drive
  door, or network protection. Applications using this flag must perform
  file operations carefully, because a file cannot be reopened once it is
  closed. 

OFN_NOVALIDATE = &H100
  Specifies that the common dialog boxes allow invalid characters in the
  returned file name. Typically, the calling application uses a hook
  procedure that checks the file name by using the FILEOKSTRING message. If
  the text box in the edit control is empty or contains nothing but spaces,
  the lists of files and directories are updated. If the text box in the
  edit control contains anything else, nFileOffset and nFileExtension are
  set to values generated by parsing the text. No default extension is added
  to the text, nor is text copied to the buffer specified by lpstrFileTitle.
  If the value specified by nFileOffset is less than zero, the file name is
  invalid. Otherwise, the file name is valid, and nFileExtension and
  nFileOffset can be used as if the OFN_NOVALIDATE flag had not been
  specified.

OFN_OVERWRITEPROMPT = &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. 

OFN_PATHMUSTEXIST = &H800
  Specifies that the user can type only valid paths and file names. If this
  flag is used and the user types an invalid path and file name in the File
  Name entry field, the dialog box function displays a warning in a message
  box. 

OFN_READONLY = &H1
  Causes the Read Only check box to be selected initially when the dialog box
  is created. This flag indicates the state of the Read Only check box when
  the dialog box is closed. 

OFN_SHAREAWARE = &H4000
  Specifies that if a call to the OpenFile function fails because of a
  network sharing violation, the error is ignored and the dialog box returns
  the selected file name. If this flag is not set, the dialog box notifies
  your hook procedure when a network sharing violation occurs for the file
  name specified by the user. If you set the OFN_EXPLORER flag, the dialog
  box sends the CDN_SHAREVIOLATION message to the hook procedure. If you do
  not set OFN_EXPLORER, the dialog box sends the SHAREVISTRING registered
  message to the hook procedure. 

OFN_SHOWHELP = &H10
  Causes the dialog box to display the Help button. The hwndOwner member
  must specify the window to receive the HELPMSGSTRING registered messages
  that the dialog box sends when the user clicks the Help button. An Explorer
  style dialog box sends a CDN_HELP notification message to your hook
  procedure when the user clicks the Help button. 
 
-----------------------------------------------------------------------------

UINT GetFlags(VOID)

Parameters:
  None.

VEE Definition:
  int GetFlags(void);

Returns:
  An integer specifying the current flags that are set.

Remarks:
  See the SetFlags function for a list of flag names, their values and
  meanings.

-----------------------------------------------------------------------------

BOOL SetView(INT iView)

Parameters:
  [in]  INT   iView      Specifies view to switch to.

VEE Definition:
  int SetView(int iView);

Returns:
  Returns 0 if the function fails. It returns non-zero if the function
  succeedes.

Remarks:
  The iView parameter is the zero-based index of the view to be selected from
  the toolbar's view-button menu:
    0 = Large Icon
    1 = Small Icon
    2 = List
    3 = Details
    4 = Thumbnails

-----------------------------------------------------------------------------

BOOL SetSort(INT iSort)

Parameters:
  [in]  INT   iSort      Specifies what column to sort on in Details view.

VEE Definition:
  int SetSort(int iSort);

Returns:
  Returns 0 if the function fails. It returns non-zero if the function
  succeedes.

Remarks:
  The iSort parameter is the zero-based index of the column to sort on if the
  view is switched to detail view (SetView(3)).

-----------------------------------------------------------------------------

VOID SetCenter(BOOL bCenterWindow)

Parameters:
  [in]  BOOL  bCenterWindow If true, centers dialog on screen.

VEE Definition:
  void SetCenter(int bCenterWindow);

Returns:
  Nothing.

Remarks:
  Set this member to false to let the dialog pop up where ever Windows thinks
  it should. The default behavior is to center the dialog.

