| Header file: | opendialog.h |
| Object name: | fOPENDIALOG |
| Object index: | 1 of 1 Object |
The fOPENDIALOG class is a wrapper for the open common dialog. This dialog is the one that you will see when you click on File->Open in a lot of programs.
Those who have dealt with open dialogs before will know that creating a filter list string can sometimes be a pain - especially if you don't want to hard code one. For this reason, I have created a utility function to generate one of these strings. It's prototype is as follows:
void MakeFilter(bstring* Result, bstring* FilterNames, bstring* FilterWildcards, int NumberParts);Result is a pointer to a bstring in which the result will be placed. FilterNames and FilterWildcards are pointers to arrays of bstrings that contain the Filter names and filter wildcards, respectively. That is, Filter name is what is shown to the user, and FilterWildcard is what Windows uses to generate the file list. NumberParts is the number of filter strings in total.
Here's an example.
bstring Filter;
bstring FilterNames[2];
bstring FilterWC[2];
FilterNames[0] = "All Files (*.*)";
FilterWC[0] = "*.*"
FilterNames[1] = "Executables (*.exe,*.com)"
FilterWC[1] = "*.exe;*.com";
//Remember: MakeFilter(OutputString, FilterNames, FilterWildCards, NumberFilters)
MakeFilter(&Filter, &(FilterNames[0]), &(FilterWC[0]), 2);
//Now assign the filter.
OpenDialog.SetFilter(Filter.data);
There, now wasn't that easier? Sort of...
| Prototype | Description |
| void SetMutliSelect(bool Set); | This function sets whether or not the dialog can allow the user to select multiple files. When you return the names of the files, each seperate filename will be enclosed inside quotation marks, and then seperated by a space. This option is disabled by default, meaning that you can only select one file at a time. |
| void SetFileMustExist(bool Set); | This function sets whether or not the dialog will allow the user to specify a file that does not exist. If it is TRUE, then the user must specify a file that does exist. Otherwise, the user can specify a file that does not exist (and to what purpose this serves, I do not know). This option is TRUE by default. |
| void SetShowReadOnlyCheck(bool Set); | This function sets whether or not the dialog should show an extra checkbox on the dialog called "Open Read Only". When the user selects the file, they can also check this box. Your program needs to read this data back again, and if appropriate, do something about it. This option is FALSE by default. You can set the default state of this check with the next function, and retrieve the state of the checkbox with the GetReadOnlyChecked() function. |
| void SetReadOnlyChecked(bool Set); | This function sets whether or not the Read Only Checkbox is checked when the dialog is shown. Pass TRUE to make it checked, or FALSE to uncheck it. By default, the box is unchecked. |
| void SetRestoreDir(bool Set); | This function sets whether or not the dialog should reset the current directory if the user changed the directory when they were searching for files. Pass TRUE to make the dialog reset the directory, or FALSE to make it keep the directory that the user changed to. By default this is FALSE. |
| void SetHideNetworkBtn(bool Set); | This functions sets whether the dialog should hide the network button on the toolbar. Pass TRUE to make it hide the button, or FALSE to make it show the button. By default, this is FALSE. |
| void SetValidation(void); | This function sets whether or not the dialog can accept invalid characters in the filename. I can not really see why you'd want this, but hey, here it is. Pass TRUE to make the dialog validate the filename, or FALSE to make it look past the dodgy characters. By default, this is TRUE. |
| void SetFilter(char* Filter); | This function sets the filter list for the dialog box. Normally at the bottom of the dialog there is a combobox allowing you to select between several filetypes. With this function, you can set those filters. Now this string isn't your normal string - it has a specific syntax, which must be carefully done. If you fail to construct this string properly, then you will most likely crash the program with an access violation! Well, it's not that serious, provided that you terminate the string correctly. So why don't I get on with how to do it? Ok, a sample filter string would look like this: "Text Files (*.txt)\0*.TXT\0Text and Word Files (*.txt; *.doc)\0*.TXT;*.DOC\0All Files (*.*)\0*.*\0\0" Now in this string, you can see that the first string is the name of that filter, followed by a NULL character. After that is the filter. You can continue to add filters in this two-string combination to your hearts content. When you are finished, please terminate the string with a double-NULL. Failing to add the double NULL will crash your program! You do not need to add the filter in brackets on the end of the name of the filter, but generally this is a good practice, so the user knows exactly what filter is applied. Hint: you can use the MakeFilter() function to generate this string - see the documentation at the top of this document about it. |
| void SetFilterIndex(int Index); | This function sets the index of the filter that is selected by default. The first filter is 1, and the next is 2, and so forth through the list. Please do not try to enter 0 (Zero) - the results will be rather unexpected! |
| void SetFileName(char* Name); | This function sets the default filename for the dialog - the file that will be already on the dialog. |
| bool Execute(HWND Parent, char* Title); | This function actually shows the dialog with all the settings that you have carefully specified. The user can then select a file and open that file. Parent is the handle of a window that can act as the dialog's parent - but this can be NULL if you want a parentless dialog (an orphan, the poor thing...). Also, you should specify a title for the dialog - make it something descriptive to help the user. This function will return TRUE if the user properly selected a file and clicked 'Open', otherwise it will return FALSE. |
| char* GetFile(void); | This function returns the full filename of the file that was selected - the drive letter, path name, filename, and extention, all in one big package. |
| char* GetFileName(void); | This function returns the file that was selected - but only the filename and the extention portion of that filename. The pathname, drive letter, and all else are chopped off. |
| int GetFilterIndex(void); | This function returns the filter that was selected - as an index. 1 is the first filter in the list, 2 is the second, and so forth. From this you may be able to determine the type of file that the user attempted to open. |
| bool GetReadOnlyChecked(void); | This function returns whether or not the Read Only Checkbox was checked or not. If you chose to show this checkbox, then you can get it's value with this function, and do something about it. This function will return TRUE if the checkbox was checked, or FALSE if it was not checked. |
The following snippet gives a basic idea of how to use this component.
//Create an instance of this object...
fOPENDIALOG OpenDlg;
//Set up a few options...
OpenDlg.SetFilter("Text Files (*.txt)\0*.txt\0All Files (*.*)\0*.*\0\0");
OpenDlg.SetFilterIndex(2);
OpenDlg.SetFileName("C:\Dev\C++\My New Foundation Classes\opendialog.h");
//Now run the dialog...
if (OpenDlg.Execute(Window.GetHandle(), "Choose a file, please!"))
{
//Ok, the user selected a file...
//Get the whole filename...
... = OpenDlg.GetFile();
} else {
//The user clicked cancel. Oh well!
}
| Back to index | The FreeFoote Foundation Classes Documentation |