History of 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 [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 [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 [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 [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.