Skip to content

Commit f82306e

Browse files
sco1sco1
committed
Update documentation
1 parent 1b9df6d commit f82306e

1 file changed

Lines changed: 72 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,84 @@ This utility was inspired by: [Making a dialog where the user can choose either
1616

1717
`___ = uiget(basepath)`
1818

19-
`___ = uiget(___, Name, Value)`
19+
`___ = uiget(basepath, Name, Value)`
2020

2121

22+
## Description
23+
24+
`file = uiget()` opens a modal dialog box that lists files and folders in the current folder. It enables a user to select or enter the name of a file. `uiget` returns the file name when the user clicks **Open**. If the user clicks **Cancel** or the window close button (X), uigetfile returns `""`.
25+
26+
**NOTE:** If the user intends to choose a directory, they must specify a second output argument to `uiget`. If a directory is chosen in the single-output case, an empty string is returned and the user is presented with a warning. This is true for both a single selection and when using `'MultiSelect'`.
27+
28+
`[file, path] = uiget()` returns the file name and path to a file or folder when the user clicks **Open**. If the user clicks **Cancel** or the window close button (X), then `uiget` returns `""` for both output arguments.
29+
30+
`___ = uiget(basepath)` specifies the start path in which the dialog box opens. If path is empty or is not a valid path, then the dialog box opens in the current working directory.
31+
32+
`___ = uiget(basepath, Name, Value)` specifies dialog box parameters using one or more `Name, Value` pair arguments. See below for a list of valid `Name, Value` pairs.
33+
2234
## Examples
2335

36+
### Select a single file
37+
38+
```
39+
>> file = uiget()
40+
41+
file =
42+
43+
"uiget.m"
44+
```
45+
46+
Selecting a directory provides the behavior described above:
47+
```
48+
>> file = uiget()
49+
Warning: One or more paths have been selected without requesting the path output.
50+
Please specify a second output to uiget to receive these paths.
51+
> In uiget (line 96)
52+
53+
file =
54+
55+
""
56+
```
57+
58+
### Select a File and Display Full File Specification
59+
60+
```
61+
function runtest()
62+
[file, path] = uiget();
63+
fprintf('User Selected: %s\n', fullfile(path, file))
64+
end
65+
66+
>> runtest
67+
User Selected: C:\uiget\uiget.m
68+
```
69+
70+
### Set a Custom Dialog Title
71+
72+
```
73+
>> [file, path] = uiget(pwd, 'Title', 'Please Select 42 Files')
74+
```
75+
76+
### Specify Filters and Filter Descriptions
77+
78+
```
79+
function runtest()
80+
filterspec = {'*.m;*.mlx;*.fig;*.mat;*.slx;*.mdl', 'MATLAB Files (*.m,*.mlx,*.fig,*.mat,*.slx,*.mdl)';
81+
'*.m;*.mlx','Code files (*.m,*.mlx)'; ...
82+
'*.fig','Figures (*.fig)'; ...
83+
'*.mat','MAT-files (*.mat)'; ...
84+
'*.mdl;*.slx','Models (*.slx, *.mdl)' ...
85+
};
86+
[file, path] = uiget(pwd, 'ExtensionFilter', filterspec);
87+
fprintf('User Selected: %s\n', fullfile(path, file))
88+
end
89+
90+
>> runtest
91+
User Selected: C:\uiget\uiget.m
92+
```
93+
2494

2595
## Name, Value Pairs
96+
2697
| Parameter | Description | Type | Default Value |
2798
| :--: | :--: | :--: | :--: |
2899
| `'MultiSelect'` | Specify whether a user can select multiple files or folders | `logical` | `false` |

0 commit comments

Comments
 (0)