The Battle for Wesnoth  1.17.0-dev
file_dialog.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2011 - 2021
3  by Iris Morelle <shadowm2006@gmail.com>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
19 
20 /**
21  * Generic file dialog.
22  *
23  * This provides UI elements for browsing the filesystem and choosing a file
24  * path to open or create, and optionally allows creating new directories or
25  * deleting existing files and directories.
26  *
27  * Because of the sheer amount of unrelated options provided by this dialog,
28  * no parameter-based constructors or static @a execute() functions are
29  * provided. Use individual property setters after construction and before
30  * invoking show(), instead.
31  */
32 namespace gui2
33 {
34 
35 class listbox;
36 class text_box;
37 
38 namespace dialogs
39 {
40 
41 class file_dialog : public modal_dialog
42 {
43 public:
44  file_dialog();
45 
46  /**
47  * Gets the current dialog title text.
48  */
49  const std::string& title() const
50  {
51  return title_;
52  }
53 
54  /**
55  * Sets the current dialog title text.
56  */
57  file_dialog& set_title(const std::string& value)
58  {
59  title_ = value;
60  return *this;
61  }
62 
63  /**
64  * Gets the current dialog instructions/message text.
65  */
66  const std::string& message() const
67  {
68  return msg_;
69  }
70 
71  /**
72  * Sets the current dialog instructions/message text.
73  *
74  * The message text may contain Pango markup.
75  */
76  file_dialog& set_message(const std::string& value)
77  {
78  msg_ = value;
79  return *this;
80  }
81 
82  /**
83  * Gets the current file selection.
84  *
85  * @returns An absolute path to the selected file.
86  */
87  std::string path() const;
88 
89  /**
90  * Sets the initial file selection.
91  *
92  * If the path is found to refer to a file (more specifically, any
93  * non-directory object), that file is initially selected on the directory
94  * contents view and the file name box is set to contain its name. If the file
95  * does not exist, but the path leading up to it does, the directory contents
96  * view displays that path and there isn't an initial file selection or name
97  * set unless set_filename() is used first.
98  *
99  * If you want to set an initial file name hint/template, use set_filename()
100  * <b>after</b> calling this method.
101  */
102  file_dialog& set_path(const std::string& value);
103 
104  /**
105  * Sets the initial file name input but not the path.
106  *
107  * The file name needs not exist in the initial path selected with set_path().
108  *
109  * If this is used before set_path() and the path passed there points to a
110  * file, that file name will replace the one given here.
111  */
112  file_dialog& set_filename(const std::string& value);
113 
114  /**
115  * Sets the default file extension for file names in save mode.
116  *
117  * When this is set to a non-empty string and save mode is active, selecting
118  * file entries will cause their name portions to be highlighted in the name
119  * text box if their extensions match the provided template, and any time the
120  * text box is cleared it will position the cursor before the extension as a
121  * hint for the user.
122  *
123  * The value provided to this method should be preceded by a dot if
124  * applicable (e.g. ".cfg").
125  */
126  file_dialog& set_extension(const std::string& value)
127  {
128  extension_ = value;
129  return *this;
130  }
131 
132  /**
133  * Whether user interface elements for manipulating existing objects are provided.
134  */
135  bool read_only() const
136  {
137  return read_only_;
138  }
139 
140  /**
141  * Whether to provide user interface elements for manipulating existing objects.
142  *
143  * This is initially disabled.
144  */
146  {
147  read_only_ = value;
148  return *this;
149  }
150 
151  /**
152  * Returns whether save mode is enabled.
153  *
154  * See set_save_mode() for more information.
155  */
156  bool save_mode() const
157  {
158  return save_mode_;
159  }
160 
161  /**
162  * Sets the dialog's behavior on non-existent file name inputs.
163  *
164  * This is initially disabled.
165  *
166  * When save mode is enabled, file names entered into the dialog by the user
167  * need not exist already (but their parent directories still do). Otherwise,
168  * the user is only able to select existing files.
169  */
171  {
172  save_mode_ = value;
173  return *this;
174  }
175 
176  /**
177  * Sets the OK button label.
178  *
179  * By default, "Save" is used when save_mode is enabled, and "Open" otherwise.
180  * Calling this method with an empty string will reset the label to the
181  * default.
182  */
183  file_dialog& set_ok_label(const std::string& value)
184  {
185  ok_label_ = value;
186  return *this;
187  }
188 
189 private:
190  std::string title_;
191  std::string msg_;
192  std::string ok_label_;
193 
194  std::string extension_;
195  std::string current_entry_;
196  std::string current_dir_;
197 
200 
201  std::vector<std::string> dir_files_;
202  std::vector<std::string> dir_subdirs_;
203 
204  std::vector<std::string> bookmark_paths_;
207 
208  virtual const std::string& window_id() const override;
209 
210  virtual void pre_show(window& window) override;
211 
212  /** Handles dialog exit events and decides whether to proceed or not. */
213  bool on_exit(window& window);
214  /** Handles file/directory selection on single-click. */
215  void on_row_selected();
216  /** Handles selection or deselection of bookmarks. */
217  void on_bookmark_selected();
218  /** Handles Add Bookmark button press events. */
219  void on_bookmark_add_cmd();
220  /** Handles Remove Bookmark button press events. */
221  void on_bookmark_del_cmd();
222  /** Handles New Folder button press events. */
223  void on_dir_create_cmd();
224  /** Handles Delete button press events. */
225  void on_file_delete_cmd();
226 
227  /**
228  * Processes file view selection in reaction to row double-click events.
229  *
230  * It takes care of synchronizing the state, browsing to the new selection,
231  * and/or displaying an error message if appropriate
232  *
233  * @returns Whether to exit the dialog successfully (@a true) or continue
234  * (@a false).
235  */
237 
238  /**
239  * Processes textbox input in reaction to OK button/Enter key events.
240  *
241  * It takes care of synchronizing the state, browsing to the new selection,
242  * and/or displaying an error message if appropriate
243  *
244  * @returns Whether to exit the dialog successfully (@a true) or continue
245  * (@a false).
246  */
247  bool process_textbox_submit();
248 
249  bool process_submit_common(const std::string& name);
250 
251  /**
252  * Updates the bookmarks bar state to reflect the internal state.
253  */
254  void sync_bookmarks_bar();
255 
256  std::string get_filelist_selection(class listbox& filelist);
257 
259  {
264  };
265 
266  /**
267  * Returns whether the given selection type is acceptable for closing the dialog.
268  *
269  * @todo This currently never returns @a true for SELECTION_IS_DIR, awaiting
270  * a need to implement a directory selection mode.
271  */
273 
274  /**
275  * Prompts the user before overwriting an existing file.
276  *
277  * This only makes sense in save mode.
278  *
279  * @returns @a true if the selection does not refer to an existing file or the
280  * user accepted the overwrite prompt; @a false otherwise.
281  */
282  bool confirm_overwrite(SELECTION_TYPE stype);
283 
284  /**
285  * Updates the internal state and returns the type of the selection.
286  *
287  * If the given @a name refers to a non-existent object, the internal state is
288  * unchanged.
289  */
290  SELECTION_TYPE register_new_selection(const std::string& name);
291 
292  void set_input_text(class text_box& t, const std::string& value);
293  void clear_input_text(class text_box& t);
294 
295  /**
296  * Updates the dialog contents to match the internal state.
297  */
298  void refresh_fileview();
299 
300  /**
301  * Row building helper for refresh_fileview().
302  *
303  * @param filelist Target for adding the new row.
304  * @param name Label, assumed to be a file name if
305  * check_selection = true.
306  * @param icon Row icon.
307  * @param check_selection Whether to set the row to selected if the current
308  * file name in the internal state matches the row's
309  * label/name.
310  */
311  void push_fileview_row(class listbox& filelist, const std::string& name, const std::string& icon, bool check_selection = true);
312 };
313 
314 } // namespace dialogs
315 } // namespace gui2
void push_fileview_row(class listbox &filelist, const std::string &name, const std::string &icon, bool check_selection=true)
Row building helper for refresh_fileview().
void on_bookmark_add_cmd()
Handles Add Bookmark button press events.
void set_input_text(class text_box &t, const std::string &value)
std::vector< std::string > dir_subdirs_
file_dialog & set_extension(const std::string &value)
Sets the default file extension for file names in save mode.
std::string get_filelist_selection(class listbox &filelist)
file_dialog & set_path(const std::string &value)
Sets the initial file selection.
void clear_input_text(class text_box &t)
file_dialog & set_ok_label(const std::string &value)
Sets the OK button label.
file_dialog & set_save_mode(bool value)
Sets the dialog&#39;s behavior on non-existent file name inputs.
void refresh_fileview()
Updates the dialog contents to match the internal state.
Class for a single line text area.
Definition: text_box.hpp:141
Generic file dialog.
Definition: field-fwd.hpp:23
void on_bookmark_del_cmd()
Handles Remove Bookmark button press events.
std::string path() const
Gets the current file selection.
The listbox class.
Definition: listbox.hpp:43
file_dialog & set_read_only(bool value)
Whether to provide user interface elements for manipulating existing objects.
const std::string & title() const
Gets the current dialog title text.
Definition: file_dialog.hpp:49
file_dialog & set_filename(const std::string &value)
Sets the initial file name input but not the path.
bool read_only() const
Whether user interface elements for manipulating existing objects are provided.
std::vector< std::string > dir_files_
bool confirm_overwrite(SELECTION_TYPE stype)
Prompts the user before overwriting an existing file.
bool save_mode() const
Returns whether save mode is enabled.
SELECTION_TYPE register_new_selection(const std::string &name)
Updates the internal state and returns the type of the selection.
Various uncategorised dialogs.
bool process_fileview_submit()
Processes file view selection in reaction to row double-click events.
bool on_exit(window &window)
Handles dialog exit events and decides whether to proceed or not.
file_dialog & set_message(const std::string &value)
Sets the current dialog instructions/message text.
Definition: file_dialog.hpp:76
void on_bookmark_selected()
Handles selection or deselection of bookmarks.
std::vector< std::string > bookmark_paths_
void on_row_selected()
Handles file/directory selection on single-click.
bool process_textbox_submit()
Processes textbox input in reaction to OK button/Enter key events.
const std::string & message() const
Gets the current dialog instructions/message text.
Definition: file_dialog.hpp:66
double t
Definition: astarsearch.cpp:65
void sync_bookmarks_bar()
Updates the bookmarks bar state to reflect the internal state.
Abstract base class for all modal dialogs.
bool process_submit_common(const std::string &name)
void on_dir_create_cmd()
Handles New Folder button press events.
void on_file_delete_cmd()
Handles Delete button press events.
base class of top level items, the only item which needs to store the final canvases to draw on...
Definition: window.hpp:65
virtual void pre_show(window &window) override
Actions to be taken before showing the window.
bool is_selection_type_acceptable(SELECTION_TYPE stype) const
Returns whether the given selection type is acceptable for closing the dialog.
file_dialog & set_title(const std::string &value)
Sets the current dialog title text.
Definition: file_dialog.hpp:57
virtual const std::string & window_id() const override
The id of the window to build.