system_extensions/dialogues/
filebox.rs

1use std::path::{Path, PathBuf};
2
3/**
4    This stores information for the filters.
5*/
6#[derive(Clone, Debug)]
7pub struct Filter {
8    pub title: String,
9    pub file_ending: String,
10}
11
12impl Filter {
13    /**
14       Construct a new File Filter.
15
16       ## Params
17       title: String -> The title of the filter. (ex: Text)<br>
18       file_ending: String -> The file ending to filter. (ex: *.txt)
19
20       ## Example
21       ```rust
22       use system_extensions::dialogues::filebox::Filter;
23       Filter::new("Text".to_string(), "*.txt".to_string());
24       ```
25    */
26    pub fn new(title: String, file_ending: String) -> Filter {
27        Filter {
28            title,
29            file_ending,
30        }
31    }
32}
33
34/**
35   Represents a Save or Open File Dialog.<br><br>
36   This is a builder struct, all functions return self, except the open or save method.
37
38   # Examples
39   Generic open file:
40   ```rust
41   use system_extensions::dialogues::filebox::FileBox;
42   use std::path::Path;
43
44   let result = FileBox::new().open();
45
46   println!("{}", result.expect("The file was not opened!").to_str().unwrap());
47   ```
48   Generic save file:
49   ```rust
50   use system_extensions::dialogues::filebox::FileBox;
51   use std::path::Path;
52
53   let result = FileBox::new().save("example.txt");
54
55   println!("{}", result.expect("The file was not saved!").to_str().unwrap());
56   ```
57   Filters:
58   ```rust
59   use system_extensions::dialogues::filebox::FileBox;
60   use std::path::Path;
61
62   let result = FileBox::new()
63            .filter("PNG", "*.png")
64            .filter("JPG", "*.jpg")
65            .filter("GIF", "*.gif")
66            .open();
67
68   println!("{}", result.expect("The file was not opened!").to_str().unwrap());
69   ```
70   Save a file with a default directory:
71   ```rust
72   use system_extensions::dialogues::filebox::FileBox;
73   use std::path::Path;
74
75   let result = FileBox::new()
76            .filter("Text", "*.txt")
77            .directory(Path::new("D:\\"))
78            .save("example.txt");
79
80   println!("{}", result.expect("The file was not saved!").to_str().unwrap());
81   ```
82*/
83#[derive(Clone, Debug)]
84pub struct FileBox {
85    pub(crate) filters: Vec<Filter>,
86    pub(crate) directory: Option<&'static Path>,
87}
88
89// TODO:: This is probably implemented pretty poorly.
90// TODO::       fix this.
91impl FileBox {
92    /**
93        Create a new FileBox to open or save files.
94
95        ## Default Values
96        By default the Filter is set to a Vector with the all filter inside. ('All', '*.*')
97        By default there is not default directory.
98    */
99    pub fn new() -> FileBox {
100        FileBox {
101            filters: vec![Filter::new("All".to_string(), "*.*".to_string())],
102            directory: None,
103        }
104    }
105
106    /**
107        Clear the current filters. This is useful if you don't want the 'All' filter.
108    */
109    pub fn clear_filters(mut self) -> Self {
110        self.filters.clear();
111        self
112    }
113
114    /**
115        Set the vector of filters.
116
117        # Params
118        filters: Vec<[`Filter`]> -> The vector of filters to be used. (Replaces any existing filters).
119    */
120    pub fn set_filters(mut self, filters: Vec<Filter>) -> Self {
121        self.filters = filters;
122        self
123    }
124
125    /**
126        Add a filter to the file box. You may want to clear the filters first if
127        you don't want the Any filter.
128
129        # Params
130        name: &str -> The name of the filter.<br>
131        ending: &str -> The ending of the filter.<br>
132
133        # Example
134        ```rust
135        use system_extensions::dialogues::filebox::FileBox;
136        FileBox::new().filter("Text", "*.*").open();
137        ```
138    */
139    pub fn filter(mut self, name: &str, ending: &str) -> Self {
140        self.filters.push(Filter::new(name.to_string(), ending.to_string()));
141        self
142    }
143
144    /**
145        Set the default directory for the save or open dialog to display.
146        <br>
147        Not setting this causes the dialog to open the last displayed directory or
148        the documents folder.
149        # Params
150        path: &`static Path -> The path of the directory to display.
151    */
152    pub fn directory(mut self, path: &'static Path) -> Self {
153        self.directory = Some(path);
154        self
155    }
156
157    /**
158        Display the open file dialog.
159
160        # Returns
161        `Option<PathBuf>` -> The Path to the opened file. An empty Option means that the window was closed
162        without opening anything.
163    */
164    pub fn open(self) -> Option<PathBuf> {
165        use crate::internal::filebox::open_file_dialogue;
166        open_file_dialogue(self)
167    }
168
169    /**
170        Display the save file dialog.
171
172        # Params
173        suggested_name: &str -> The default name that is given when the dialog is displayed.
174
175        # Returns
176        `Option<PathBuf>` -> The path to the saved file. An empty Option means that the window was
177        closed without saving anything.
178    */
179    pub fn save(self, suggested_name: &str) -> Option<PathBuf> {
180        use crate::internal::filebox::save_file_dialogue_filter;
181        save_file_dialogue_filter(self, suggested_name)
182    }
183}
system_extensions/dialogues/filebox.rs

system_extensions/dialogues/
filebox.rs
