Editing getOpenFileName - FilterMeisterWiki

When saving, enter the following:

  _____            ##     __          __  _   _ 
 |__  /|\     /|  #  #    \ \        / / | | | |
   / / | )   ( | #    #    \ \  /\  / /  | | | |
  / /_ | |   | | ######     \ \/  \/ /   | |_| |
 /____|( (   ) ) #    #      \  /\  /     \___/ 
        \ \_/ /  #    #       \/  \/            
         \   /   #    #                         
          \_/

Visit Preferences to set your user name

= getOpenFileName =

== Syntax ==
:{{int getOpenFileName(int flags, string *file, int maxFile, int *fileOffset, int *extensionOffset, string *fileTitle, int nMaxFileTitle, string *filter, string *customFilter, int maxCustFilter, int *filterIndex, string initialDir, string dialogTitle, string defExt, int *outputflags)}}

== Arguments ==
:'''flags'''
::A set of bit flags that can be chosen to modify the behavior of the dialog. Available flags include OFN_HIDEREADONLY to hide the user-selectable "Read Only" option in the dialog, and OFN_FORCESHOWHIDDEN to force hidden files to be shown to the user. A full list of the available bit flags is in the [https://docs.microsoft.com/en-us/windows/win32/api/commdlg/ns-commdlg-openfilenamea OPENFILENAME structure] Win32 documentation.
:'''file'''
::A string containing the prefilled value for the File Name edit control. This string will be overwritten with the name of the file that the user has chosen on return of the function.
:'''maxFile'''
::The maximum length of the string buffer ''file'' that contains the initial File Name
:'''fileOffset'''
::The offset in bytes to the beginning of the actual filename (after the path) in the string ''file''.
:'''extensionOffset'''
::The offset in bytes to the beginning of the filename extension (after the dot) in the string ''file''.
:'''fileTitle'''
::The filename and file extension (without path) of the file the user has chosen. Can be set to NULL to ignore.
:'''maxFileTitle'''
::The maximum length of the string buffer ''fileTitle'' that receives the filename & file extension the user chose.
:'''filter'''
::A string buffer containing pairs of null terminated strings, defining file extension filters the user can choose from to narrow their choices, together with a caption for each filter set. These typically show up next to the File Name edit field in the Open File dialog window.
:'''customFilter'''
::A string buffer to store a file extension filter the user might have typed in manually
:'''maxCustFilter'''
::The maximum length of the string buffer ''customFilter'', storing the user's own custom entered extension filter.
:'''filterIndex'''
::The number of the file extension filter the user has chosen from the provided list in ''filter''. Numbering starts from 1. If 0, the user has entered a custom filter of their own.
:'''initialDir'''
::A string containing the path of the initial directory to be displayed in the dialog. Can be set to NULL, in which case the current directory will likely be used. For the full rules and behavior of which folder will be chosen when the dialog is invoked, see the Win32 documentation for the [https://docs.microsoft.com/en-us/windows/win32/api/commdlg/ns-commdlg-openfilenamea OPENFILENAME structure].
:'''dialogTitle'''
::A string containing the caption to be used for the Open File dialog window
:'''defExt'''
::A string containing the default file extension for the user to choose from (not containing periods or asterisks)
:'''outputflags'''
::An integer DWORD containing the flags as may have been modified by the Open File dialog after the user interacted with it.

== Return ==
:Returns 0 if the user specified a file name and clicked the OK button, otherwise it returns an error code as returned by the Win32 [https://docs.microsoft.com/en-us/windows/win32/api/commdlg/nf-commdlg-commdlgextendederror CommDlgExtendedError] API function.

== Description ==
: This function displays the Windows "Open File" common dialog to the user, letting them choose a file to open.
: Internally, this function is mostly a wrapper around the Win32 API function [https://docs.microsoft.com/en-us/windows/win32/api/commdlg/nf-commdlg-getopenfilenamea GetOpenFileName].

== Example ==
<code>
%fml

// The following will ask the user to choose a TXT file that
// will be loaded and displayed on the filter interface

ctl[3]: STATICTEXT, Text="Test", Pos=(250,20), Size=(200,130)

void *TEXT_FILE;
int status;

status = getOpenFileName(OFN_HIDEREADONLY,      //flags
                         str0, 256,             //set, receive file name
                         NULL, NULL,            //file/extension offsets
                         NULL, 0,               //file title for display
                                                //file filters...
                         "Text Files (*.txt;*.md)\0*.txt;*.md\0"
                         "All Files (*.*)\0*.*\0",
                         NULL, 0,               //no custom filter
                         NULL,                  //filter index
                         filterInstallDir,      //initial dir
                         "Open Text File",      //dialog title
                         "txt",                 //default extension
                         NULL                   //output flags
                         );

if (status == 0) {
  // User has clicked on OK and chosen a file

// Attempt to open file
  TEXT_FILE = fopen(str0, "rb");
  if (TEXT_FILE) {

// Get the filesize
    unsigned int filesize;
    fseek(TEXT_FILE, 0L, SEEK_END);
    filesize = ftell(TEXT_FILE);
    fseek(TEXT_FILE, 0, SEEK_SET);

// Allocate memory block as big as file
    void* textmemblock = calloc(filesize, 1);

// Read entire text file into memory
    if (textmemblock) {
      fread(textmemblock, 1, filesize, TEXT_FILE);
      setCtlText(3, textmemblock);
    }

// Close the file
    fclose(TEXT_FILE);
  }
  else msgBox(MB_OK | MB_ICONWARNING, "Error", "Can't find that file.");
}
</code>

== See Also ==
:((getSaveFileName))

== Comments ==
:Everyone can add their comments about their experiences with this function here. Tips for using it are welcome, too.

Summary of change:
Add document to category: