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