The Battle for Wesnoth  1.15.1+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  /** Inherited from modal_dialog, implemented by REGISTER_DIALOG. */
208  virtual const std::string& window_id() const override;
209 
210  /** Inherited from modal_dialog. */
211  virtual void pre_show(window& window) override;
212 
213  /** Handles dialog exit events and decides whether to proceed or not. */
214  bool on_exit(window& window);
215  /** Handles file/directory selection on single-click. */
217  /** Handles selection or deselection of bookmarks. */
219  /** Handles Add Bookmark button press events. */
221  /** Handles Remove Bookmark button press events. */
223  /** Handles New Folder button press events. */
225  /** Handles Delete button press events. */
227 
228  /**
229  * Processes file view selection in reaction to row double-click events.
230  *
231  * It takes care of synchronizing the state, browsing to the new selection,
232  * and/or displaying an error message if appropriate
233  *
234  * @returns Whether to exit the dialog successfully (@a true) or continue
235  * (@a false).
236  */
238 
239  /**
240  * Processes textbox input in reaction to OK button/Enter key events.
241  *
242  * It takes care of synchronizing the state, browsing to the new selection,
243  * and/or displaying an error message if appropriate
244  *
245  * @returns Whether to exit the dialog successfully (@a true) or continue
246  * (@a false).
247  */
249 
250  bool process_submit_common(window& window, const std::string& name);
251 
252  /**
253  * Updates the bookmarks bar state to reflect the internal state.
254  */
256 
257  std::string get_filelist_selection(class listbox& filelist);
258 
260  {
265  };
266 
267  /**
268  * Returns whether the given selection type is acceptable for closing the dialog.
269  *
270  * @todo This currently never returns @a true for SELECTION_IS_DIR, awaiting
271  * a need to implement a directory selection mode.
272  */
274 
275  /**
276  * Prompts the user before overwriting an existing file.
277  *
278  * This only makes sense in save mode.
279  *
280  * @returns @a true if the selection does not refer to an existing file or the
281  * user accepted the overwrite prompt; @a false otherwise.
282  */
284 
285  /**
286  * Updates the internal state and returns the type of the selection.
287  *
288  * If the given @a name refers to a non-existent object, the internal state is
289  * unchanged.
290  */
291  SELECTION_TYPE register_new_selection(const std::string& name);
292 
293  void set_input_text(class text_box& t, const std::string& value);
294  void clear_input_text(class text_box& t);
295 
296  /**
297  * Updates the dialog contents to match the internal state.
298  */
300 
301  /**
302  * Row building helper for refresh_fileview().
303  *
304  * @param filelist Target for adding the new row.
305  * @param name Label, assumed to be a file name if
306  * check_selection = true.
307  * @param icon Row icon.
308  * @param check_selection Whether to set the row to selected if the current
309  * file name in the internal state matches the row's
310  * label/name.
311  */
312  void push_fileview_row(class listbox& filelist, const std::string& name, const std::string& icon, bool check_selection = true);
313 };
314 
315 } // namespace dialogs
316 } // 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 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.
void on_file_delete_cmd(window &window)
Handles Delete button press events.
bool process_fileview_submit(window &window)
Processes file view selection in reaction to row double-click events.
void on_bookmark_add_cmd(window &window)
Handles Add Bookmark button press events.
file_dialog & set_save_mode(bool value)
Sets the dialog&#39;s behavior on non-existent file name inputs.
bool process_submit_common(window &window, const std::string &name)
void on_bookmark_selected(window &window)
Handles selection or deselection of bookmarks.
Class for a single line text area.
Definition: text_box.hpp:121
Generic file dialog.
Definition: field-fwd.hpp:22
void sync_bookmarks_bar(window &window)
Updates the bookmarks bar state to reflect the internal state.
std::string path() const
Gets the current file selection.
The listbox class.
Definition: listbox.hpp:40
static const char * name(const std::vector< SDL_Joystick *> &joysticks, const std::size_t index)
Definition: joystick.cpp:48
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 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.
bool confirm_overwrite(window &window, SELECTION_TYPE stype)
Prompts the user before overwriting an existing file.
void refresh_fileview(window &window)
Updates the dialog contents to match the internal state.
Various uncategorised dialogs.
void on_row_selected(window &window)
Handles file/directory selection on single-click.
bool on_exit(window &window)
Handles dialog exit events and decides whether to proceed or not.
void on_bookmark_del_cmd(window &window)
Handles Remove Bookmark button press events.
file_dialog & set_message(const std::string &value)
Sets the current dialog instructions/message text.
Definition: file_dialog.hpp:75
std::vector< std::string > bookmark_paths_
void on_dir_create_cmd(window &window)
Handles New Folder button press events.
const std::string & message() const
Gets the current dialog instructions/message text.
Definition: file_dialog.hpp:65
double t
Definition: astarsearch.cpp:64
Abstract base class for all modal dialogs.
base class of top level items, the only item which needs to store the final canvases to draw on ...
Definition: window.hpp:63
virtual void pre_show(window &window) override
Inherited from modal_dialog.
bool is_selection_type_acceptable(SELECTION_TYPE stype) const
Returns whether the given selection type is acceptable for closing the dialog.
bool process_textbox_submit(window &window)
Processes textbox input in reaction to OK button/Enter key events.
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
Inherited from modal_dialog, implemented by REGISTER_DIALOG.