The Battle for Wesnoth  1.19.0-dev
message.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2024
3  by Mark de Wever <koraq@xs4all.nl>
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 #include "gui/widgets/widget.hpp"
20 
21 namespace gui2
22 {
23 
24 class button;
25 
26 namespace dialogs
27 {
28 
29 /**
30  * Main class to show messages to the user.
31  *
32  * It can be used to show a message or ask a result from the user. For the
33  * most common usage cases there are helper functions defined.
34  */
35 class message : public modal_dialog
36 {
37  friend struct message_implementation;
38 
39 public:
40  message(const std::string& title,
41  const std::string& message,
42  const bool auto_close,
43  const bool message_use_markup,
44  const bool title_use_markup)
46  , title_(title)
47  , image_()
48  , message_(message)
50  , message_use_markup_(message_use_markup)
51  , title_use_markup_(title_use_markup)
52  , buttons_(count)
53  {
54  }
55 
56  enum button_id {
57  left_1 = 0,
59  ok,
61  count
62  };
63 
64  /**
65  * Selects the style of the buttons to be shown.
66  *
67  * These values are not directly implemented in this class but are used
68  * by our helper functions.
69  */
70  enum button_style {
71  auto_close /**< Enables auto close. */
72  ,
73  ok_button /**< Shows an ok button. */
74  ,
75  close_button /**< Shows a close button. */
76  ,
77  ok_cancel_buttons /**< Shows an ok and cancel button. */
78  ,
79  cancel_button /**< Shows a cancel button. */
80  ,
81  yes_no_buttons /**< Shows a yes and no button. */
82  };
83 
85  const std::string& caption);
86 
88  const widget::visibility visible);
89 
90  void set_button_retval(const button_id button, const int retval);
91 
92  /***** ***** ***** setters / getters for members ***** ****** *****/
93 
94  void set_title(const std::string& title)
95  {
96  title_ = title;
97  }
98 
99  void set_image(const std::string& image)
100  {
101  image_ = image;
102  }
103 
104  void set_message(const std::string& message)
105  {
106  message_ = message;
107  }
108 
109  void set_auto_close(const bool auto_close)
110  {
112  }
113 
114 protected:
115  virtual void pre_show(window& window) override;
116 
117  virtual void post_show(window& window) override;
118 
119 private:
120  /** The title for the dialog. */
121  std::string title_;
122 
123  /**
124  * The image which is shown in the dialog.
125  *
126  * This image can be an icon or portrait or any other image.
127  */
128  std::string image_;
129 
130  /** The message to show to the user. */
131  std::string message_;
132 
133  /**
134  * Does the window need to use click_dismiss when the dialog doesn't need a
135  * scrollbar.
136  */
138 
139  /** Whether to enable formatting markup for the dialog message. */
141 
142  /** Whether to enable formatting markup for the dialog title. */
144 
146  {
147  button_status();
148 
150  std::string caption;
152  int retval;
153  };
154 
155  /** Holds a pointer to the buttons. */
156  std::vector<button_status> buttons_;
157 
158  virtual const std::string& window_id() const override;
159 };
160 } // namespace dialogs
161 
162 /**
163  * Shows a message to the user.
164  *
165  * Normally the dialog won't have a button only when the text doesn't fit in
166  * the dialog and a scrollbar is used the button will be shown.
167  *
168  * @param title The title of the dialog.
169  * @param message The message to show in the dialog.
170  * @param button_caption The caption of the close button.
171  * @param auto_close When true the window will hide the ok button
172  * when the message doesn't need a scrollbar to
173  * show itself.
174  * @param message_use_markup Use markup for the message?
175  * @param title_use_markup Use markup for the title?
176  */
177 void show_message(const std::string& title,
178  const std::string& message,
179  const std::string& button_caption = "",
180  const bool auto_close = true,
181  const bool message_use_markup = false,
182  const bool title_use_markup = false);
183 
184 /**
185  * Shows a message to the user.
186  *
187  * @note this function is rather untested, and the API might change in the
188  * near future.
189  *
190  * @param title The title of the dialog.
191  * @param message The message to show in the dialog.
192  * @param button_style The style of the button(s) shown.
193  * @param message_use_markup Use markup for the message?
194  * @param title_use_markup Use markup for the title?
195  *
196  * @returns The retval of the dialog shown.
197  */
198 int show_message(const std::string& title,
199  const std::string& message,
200  const dialogs::message::button_style button_style,
201  bool message_use_markup = false,
202  bool title_use_markup = false);
203 
204 /**
205  * Shows an error message to the user.
206  *
207  * @param message The message to show in the dialog.
208  * @param message_use_markup Use markup for the message?
209  */
210 void show_error_message(const std::string& message,
211  bool message_use_markup = false);
212 
213 } // namespace gui2
Simple push button.
Definition: button.hpp:36
Main class to show messages to the user.
Definition: message.hpp:36
bool message_use_markup_
Whether to enable formatting markup for the dialog message.
Definition: message.hpp:140
message(const std::string &title, const std::string &message, const bool auto_close, const bool message_use_markup, const bool title_use_markup)
Definition: message.hpp:40
void set_auto_close(const bool auto_close)
Definition: message.hpp:109
std::string title_
The title for the dialog.
Definition: message.hpp:121
void set_title(const std::string &title)
Definition: message.hpp:94
void set_message(const std::string &message)
Definition: message.hpp:104
std::string message_
The message to show to the user.
Definition: message.hpp:131
button_style
Selects the style of the buttons to be shown.
Definition: message.hpp:70
@ yes_no_buttons
Shows a yes and no button.
Definition: message.hpp:81
@ close_button
Shows a close button.
Definition: message.hpp:75
@ ok_button
Shows an ok button.
Definition: message.hpp:73
@ ok_cancel_buttons
Shows an ok and cancel button.
Definition: message.hpp:77
@ auto_close
Enables auto close.
Definition: message.hpp:71
@ cancel_button
Shows a cancel button.
Definition: message.hpp:79
void set_button_caption(const button_id button, const std::string &caption)
Definition: message.cpp:112
virtual void pre_show(window &window) override
Actions to be taken before showing the window.
Definition: message.cpp:67
std::vector< button_status > buttons_
Holds a pointer to the buttons.
Definition: message.hpp:156
std::string image_
The image which is shown in the dialog.
Definition: message.hpp:128
bool title_use_markup_
Whether to enable formatting markup for the dialog title.
Definition: message.hpp:143
void set_button_visible(const button_id button, const widget::visibility visible)
Definition: message.cpp:121
bool auto_close_
Does the window need to use click_dismiss when the dialog doesn't need a scrollbar.
Definition: message.hpp:137
void set_image(const std::string &image)
Definition: message.hpp:99
virtual const std::string & window_id() const override
The ID of the window to build.
virtual void post_show(window &window) override
Actions to be taken after the window has been shown.
Definition: message.cpp:104
void set_button_retval(const button_id button, const int retval)
Definition: message.cpp:130
Abstract base class for all modal dialogs.
visibility
Visibility settings done by the user.
Definition: widget.hpp:63
base class of top level items, the only item which needs to store the final canvases to draw on.
Definition: window.hpp:63
Various uncategorised dialogs.
Generic file dialog.
void show_error_message(const std::string &msg, bool message_use_markup)
Shows an error message to the user.
Definition: message.cpp:203
void show_message(const std::string &title, const std::string &msg, const std::string &button_caption, const bool auto_close, const bool message_use_markup, const bool title_use_markup)
Shows a message to the user.
Definition: message.cpp:150
retval
Default window/dialog return values.
Definition: retval.hpp:30
Functions to load and save images from/to disk.
Helper to implement private functions without modifying the header.
Definition: message.cpp:42