606 lines
20 KiB
C++
606 lines
20 KiB
C++
//
|
|
// Standard dialog functions for the Fast Light Tool Kit (FLTK).
|
|
//
|
|
// Copyright 1998-2022 by Bill Spitzak and others.
|
|
//
|
|
// This library is free software. Distribution and use rights are outlined in
|
|
// the file "COPYING" which should have been included with this file. If this
|
|
// file is missing or damaged, see the license at:
|
|
//
|
|
// https://www.fltk.org/COPYING.php
|
|
//
|
|
// Please see the following page on how to report bugs and issues:
|
|
//
|
|
// https://www.fltk.org/bugs.php
|
|
//
|
|
|
|
/**
|
|
\addtogroup group_comdlg
|
|
@{
|
|
*/
|
|
|
|
/**
|
|
\file fl_ask.cxx
|
|
|
|
\brief Utility functions for common dialogs.
|
|
|
|
This file defines the functions
|
|
|
|
- fl_alert()
|
|
- fl_beep()
|
|
- fl_message()
|
|
- fl_ask()
|
|
- fl_choice()
|
|
- fl_input()
|
|
- fl_input_str()
|
|
- fl_password()
|
|
- fl_password_str()
|
|
|
|
and some more functions to change their behavior (positioning,
|
|
window title, and more).
|
|
|
|
Since FLTK 1.4.0 a big part of these functions is
|
|
implemented in class Fl_Message.
|
|
*/
|
|
|
|
#include <FL/Fl.H>
|
|
#include <FL/Fl_Box.H>
|
|
#include <FL/Fl_Input_.H>
|
|
#include "flstring.h"
|
|
#include "Fl_Screen_Driver.H"
|
|
#include <FL/fl_ask.H>
|
|
#include "Fl_Message.h" // intentionally "hidden" in src/...
|
|
|
|
#include <stdio.h>
|
|
#include <stdarg.h>
|
|
|
|
// static, configurable variables
|
|
|
|
Fl_Font fl_message_font_ = FL_HELVETICA;
|
|
Fl_Fontsize fl_message_size_ = -1;
|
|
|
|
// pointers you can use to change FLTK to another language:
|
|
const char *fl_no = "No"; ///< string pointer used in common dialogs, you can change it to another language
|
|
const char *fl_yes = "Yes"; ///< string pointer used in common dialogs, you can change it to another language
|
|
const char *fl_ok = "OK"; ///< string pointer used in common dialogs, you can change it to another language
|
|
const char *fl_cancel = "Cancel"; ///< string pointer used in common dialogs, you can change it to another language
|
|
const char *fl_close = "Close"; ///< string pointer used in common dialogs, you can change it to another language
|
|
|
|
// fltk functions:
|
|
|
|
/**
|
|
Emits a system beep.
|
|
|
|
This function is platform specific. Depending on the input \p type a different
|
|
sound may be played or the system speaker may beep with a different volume.
|
|
|
|
On X the system speaker is used which may not work at all on newer systems
|
|
that don't have a speaker. Since 1.4.0 \c FL_BEEP_DEFAULT and other types
|
|
honor the system or user settings whereas \c FL_BEEP_ERROR uses 100% volume.
|
|
This may be changed in a future version.
|
|
|
|
On Wayland an ASCII \p BEL (0x07) is output to stderr.
|
|
|
|
On Windows the \c MessageBeep() function is used to play different sounds
|
|
depending on the \p type argument.
|
|
|
|
On macOS the system beep function \c NSBeep() is used for \c FL_BEEP_DEFAULT
|
|
and \c FL_BEEP_ERROR. Other types are ignored.
|
|
|
|
On other platforms the behavior is undefined and may change in the future.
|
|
|
|
\param[in] type The beep type from the \ref Fl_Beep enumeration (optional)
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
*/
|
|
void fl_beep(int type) {
|
|
Fl::screen_driver()->beep(type);
|
|
}
|
|
|
|
/** Shows an information message dialog box.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
*/
|
|
void fl_message(const char *fmt, ...) {
|
|
|
|
Fl_Message msg("i");
|
|
va_list ap;
|
|
|
|
va_start(ap, fmt);
|
|
msg.innards(fmt, ap, 0, fl_close, 0);
|
|
va_end(ap);
|
|
}
|
|
|
|
/** Shows an alert message dialog box.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
*/
|
|
void fl_alert(const char *fmt, ...) {
|
|
|
|
Fl_Message msg("!");
|
|
va_list ap;
|
|
|
|
va_start(ap, fmt);
|
|
msg.innards(fmt, ap, 0, fl_close, 0);
|
|
va_end(ap);
|
|
}
|
|
|
|
/** Shows a dialog displaying the \p fmt message,
|
|
this dialog features 2 yes/no buttons.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\retval 0 if the no button is selected
|
|
\retval 1 if yes is selected
|
|
|
|
\deprecated fl_ask() is deprecated since it uses "Yes" and "No" for the buttons which
|
|
does not conform to the current FLTK Human Interface Guidelines.
|
|
Use fl_choice() with the appropriate verbs instead.
|
|
*/
|
|
int fl_ask(const char *fmt, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
va_list ap;
|
|
|
|
va_start(ap, fmt);
|
|
int r = msg.innards(fmt, ap, fl_no, fl_yes, 0);
|
|
va_end(ap);
|
|
|
|
return r;
|
|
}
|
|
|
|
/** Shows a dialog displaying the printf style \p fmt message.
|
|
|
|
This dialog features up to 3 customizable choice buttons
|
|
which are specified in order of *right-to-left* in the dialog, e.g.
|
|
\image html fl_choice_left_middle_right.png
|
|
\image latex fl_choice_left_middle_right.png "fl_choice() button ordering" width=4cm
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
Three choices with printf() style formatting:
|
|
\image html fl_choice_three_fmt.png
|
|
\image latex fl_choice_three_fmt.png "fl_choice() three choices with printf formatting" width=4cm
|
|
\code
|
|
int num_msgs = GetNumberOfMessages();
|
|
switch ( fl_choice("What to do with %d messages?", "Send", "Save", "Delete", num_msgs) ) {
|
|
case 0: .. // Send
|
|
case 1: .. // Save (default)
|
|
case 2: .. // Delete
|
|
..
|
|
}
|
|
\endcode
|
|
|
|
Three choice example:
|
|
\image html fl_choice_three.png
|
|
\image latex fl_choice_three.png "fl_choice() three choices" width=4cm
|
|
\code
|
|
switch ( fl_choice("How many bedrooms?", "Zero", "One", "Two") ) {
|
|
case 0: .. // "Zero"
|
|
case 1: .. // "One" (default)
|
|
case 2: .. // "Two"
|
|
}
|
|
\endcode
|
|
|
|
Two choice example:
|
|
\image html fl_choice_two.png
|
|
\image latex fl_choice_two.png "fl_choice() two choices" width=4cm
|
|
\code
|
|
switch ( fl_choice("Empty trash?", "Yes", "No", 0) ) {
|
|
case 0: .. // Yes
|
|
case 1: .. // No (default)
|
|
}
|
|
\endcode
|
|
|
|
One choice example:
|
|
\image html fl_choice_one.png
|
|
\image latex fl_choice_one.png "fl_choice() one choice" width=4cm
|
|
\code
|
|
fl_choice("All hope is lost.", "OK", 0, 0); // "OK" default
|
|
\endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] b0 text label for right button 0
|
|
\param[in] b1 text label for middle button 1 (can be 0)
|
|
\param[in] b2 text label for left button 2 (can be 0)
|
|
\retval 0 if the button with \p b0 text is pushed
|
|
\retval 1 if the button with \p b1 text is pushed
|
|
\retval 2 if the button with \p b2 text is pushed
|
|
*/
|
|
int fl_choice(const char *fmt, const char *b0, const char *b1, const char *b2, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
va_list ap;
|
|
|
|
va_start(ap, b2);
|
|
int r = msg.innards(fmt, ap, b0, b1, b2);
|
|
va_end(ap);
|
|
return r;
|
|
}
|
|
|
|
/** Shows a dialog displaying the printf style \p fmt message.
|
|
|
|
This function is like fl_choice() but returns \c -1 if the dialog window
|
|
was closed by pressing the \c Escape key or the window close button
|
|
rather than pushing one of the dialog buttons.
|
|
|
|
\see fl_choice()
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] b0 text label for right button 0
|
|
\param[in] b1 text label for middle button 1 (can be 0)
|
|
\param[in] b2 text label for left button 2 (can be 0)
|
|
|
|
\retval -3 reserved, FLTK 1.3 only: another dialog is still open (not possible in 1.4)
|
|
\retval -2 if the dialog was closed by pushing the window close button
|
|
\retval -1 if the dialog was closed by hitting Escape
|
|
\retval 0 if the button with \p b0 text is pushed
|
|
\retval 1 if the button with \p b1 text is pushed
|
|
\retval 2 if the button with \p b2 text is pushed
|
|
*/
|
|
int fl_choice_n(const char *fmt, const char *b0, const char *b1, const char *b2, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
va_list ap;
|
|
|
|
va_start(ap, b2);
|
|
int r = msg.innards(fmt, ap, b0, b1, b2);
|
|
va_end(ap);
|
|
if (msg.window_closed() != 0)
|
|
return msg.window_closed();
|
|
return r;
|
|
}
|
|
|
|
/**
|
|
Gets the Fl_Box icon container of the current default dialog used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password().
|
|
|
|
The return value cannot be Null. The object pointed to is an Fl_Box widget.
|
|
The returned pointer (Fl_Widget *) can be safely cast to an Fl_Box* pointer.
|
|
|
|
\note You can set some attributes of this \b default icon box. These attributes
|
|
are sticky, i.e. they will be used in all subsequent common dialogs unless
|
|
overridden by specific "one shot" variables. Setting any attribute except
|
|
those mentioned below causes undefined behavior.
|
|
|
|
Supported icon attributes:
|
|
|
|
- box()
|
|
- labelfont()
|
|
- labelsize()
|
|
- color()
|
|
- labelcolor()
|
|
- image()
|
|
- align()
|
|
|
|
The icon size can not be changed. If you set an image() you should scale it
|
|
to the available size, i.e. \p w() and \p h() of the icon box.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
*/
|
|
Fl_Widget *fl_message_icon() {
|
|
return Fl_Message::message_icon();
|
|
}
|
|
|
|
/** Shows an input dialog displaying the \p fmt message with variable arguments.
|
|
|
|
This version of fl_input() is deprecated. The return value points
|
|
to an internal allocated string that may be changed later. You must
|
|
copy the string immediately after return from this method - at least
|
|
before the next execution of the event loop.
|
|
|
|
\deprecated Please use
|
|
fl_input_str(int maxchar, const char *fmt, const char *defstr, ...) instead.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] defstr defines the default returned string if no text is entered
|
|
|
|
\return the user string input if OK was pushed
|
|
\retval NULL if Cancel was pushed or the window was closed by the user
|
|
*/
|
|
const char *fl_input(const char *fmt, const char *defstr, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
va_list ap;
|
|
va_start(ap, defstr);
|
|
const char *r = msg.input_innards(fmt, ap, defstr, FL_NORMAL_INPUT, -1);
|
|
va_end(ap);
|
|
return r;
|
|
}
|
|
|
|
/** Shows an input dialog displaying the \p fmt message with variable arguments.
|
|
|
|
Like fl_input(), but this method has an additional (first) argument \p maxchar
|
|
that limits the number of \b characters that can be input. Since the
|
|
string is encoded in UTF-8 it is possible that the number of bytes
|
|
in the string is larger than \p maxchar.
|
|
|
|
Other than the deprecated fl_input() method w/o the \p maxchar argument, this one
|
|
returns the string in an Fl_String object that must be released after use. This
|
|
can be a local/automatic variable.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
Example:
|
|
\code
|
|
{ Fl_String str = fl_input_str(0, "Enter text:", "");
|
|
printf("Text is: '%s'\n", str.value() ? str.value() : "<cancelled>");
|
|
} // (str goes out of scope)
|
|
\endcode
|
|
|
|
If the user hits \c Escape or closes the window \c str.value() returns NULL.
|
|
|
|
\param[in] maxchar input size limit in characters (not bytes), use 0 for no limit
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] defstr defines the default returned string if no text is entered
|
|
|
|
\return the user string input if OK was pushed or NULL in Fl_String::value()
|
|
\retval Fl_String::value() == NULL if Cancel was pushed or the window was closed by the user
|
|
|
|
\since 1.4.0
|
|
*/
|
|
Fl_String fl_input_str(int maxchar, const char *fmt, const char *defstr, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
if (maxchar < 0)
|
|
maxchar = 0;
|
|
va_list ap;
|
|
va_start(ap, defstr);
|
|
const char *r = msg.input_innards(fmt, ap, defstr, FL_NORMAL_INPUT, maxchar);
|
|
va_end(ap);
|
|
return r; // Fl_String(r)
|
|
}
|
|
|
|
/** Shows an input dialog displaying the \p fmt message with variable arguments.
|
|
|
|
Like fl_input() except the input text is not shown,
|
|
'*' or similar replacement characters are displayed instead.
|
|
|
|
\deprecated Please use
|
|
fl_password_str(int maxchar, const char *fmt, const char *defstr, ...) instead.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] defstr defines the default returned string if no text is entered
|
|
|
|
\return the user string input if OK was pushed
|
|
\retval NULL if Cancel was pushed or the window was closed by the user
|
|
*/
|
|
const char *fl_password(const char *fmt, const char *defstr, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
va_list ap;
|
|
va_start(ap, defstr);
|
|
const char *r = msg.input_innards(fmt, ap, defstr, FL_SECRET_INPUT);
|
|
va_end(ap);
|
|
return r;
|
|
}
|
|
|
|
/** Shows an input dialog displaying the \p fmt message with variable arguments.
|
|
|
|
Like fl_input_str() except the input text is not shown,
|
|
'*' or similar replacement characters are displayed instead.
|
|
|
|
Other than the deprecated fl_password() method w/o the \p maxchar argument, this
|
|
one returns the string in an Fl_String object that must be released after use.
|
|
This can be a local/automatic variable.
|
|
|
|
For an example see fl_input_str()
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] maxchar input size limit in characters (not bytes); use 0 for no limit
|
|
\param[in] fmt can be used as an sprintf-like format and variables for the message text
|
|
\param[in] defstr defines the default returned string if no text is entered
|
|
|
|
\return the user string input if OK was pushed or NULL in Fl_String::value()
|
|
\retval Fl_String::value() == NULL if Cancel was pushed or the window was closed by the user
|
|
|
|
\since 1.4.0
|
|
*/
|
|
Fl_String fl_password_str(int maxchar, const char *fmt, const char *defstr, ...) {
|
|
|
|
Fl_Message msg("?");
|
|
if (maxchar < 0)
|
|
maxchar = 0;
|
|
va_list ap;
|
|
va_start(ap, defstr);
|
|
const char *r = msg.input_innards(fmt, ap, defstr, FL_SECRET_INPUT, maxchar);
|
|
va_end(ap);
|
|
return r; // Fl_String(r)
|
|
}
|
|
|
|
/** Sets the preferred position for the message box used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password().
|
|
|
|
The position set with this method overrides the hotspot setting,
|
|
i.e. setting a position has higher priority than the hotspot mode
|
|
set by fl_message_hotspot(int).
|
|
|
|
The preferred position set by any of the fl_message_position() variants
|
|
affects only the next call of one of the common dialogs. The preferred
|
|
position is reset to 0 (unset) as soon as the dialog is shown.
|
|
|
|
If the optional argument \p center is non-zero (true) the message box
|
|
will be centered at the given coordinates rather than using the X/Y
|
|
position as the window position (top left corner).
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] x Preferred X position
|
|
\param[in] y Preferred Y position
|
|
\param[in] center 1 = centered, 0 = absolute
|
|
|
|
\see int fl_message_position(int *x, int *y)
|
|
*/
|
|
void fl_message_position(const int x, const int y, const int center) {
|
|
Fl_Message::message_position(x, y, center);
|
|
}
|
|
|
|
/** Sets the preferred position for the message box used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password().
|
|
|
|
The message box will be centered over the given widget
|
|
or window extensions.
|
|
|
|
Everything else is like fl_message_position(int, int, int) with
|
|
argument 'center' set to 1.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] widget Widget or window to position the message box over.
|
|
|
|
\see int fl_message_position(int x, int y, int center)
|
|
*/
|
|
void fl_message_position(Fl_Widget *widget) {
|
|
Fl_Message::message_position(widget);
|
|
}
|
|
|
|
/** Gets the preferred position for the message box used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password().
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
The position set with this method overrides the hotspot setting,
|
|
i.e. setting a position has higher priority than the hotspot mode
|
|
set by fl_message_hotspot(int).
|
|
|
|
The preferred position set by any of the fl_message_position() variants
|
|
affects only the next call of one of the common dialogs. The preferred
|
|
position is reset to 0 (unset) as soon as the dialog is shown.
|
|
|
|
\param[out] x Preferred X position, returns -1 if not set
|
|
\param[out] y Preferred Y position, returns -1 if not set
|
|
|
|
\returns whether position is currently set or not
|
|
\retval 0 position is not set (hotspot may be enabled or not)
|
|
\retval 1 position is set (window position)
|
|
\retval 2 position is set (message box centered)
|
|
|
|
\see fl_message_hotspot()
|
|
\see fl_message_hotspot(int)
|
|
\see fl_message_position(int, int)
|
|
\see fl_message_position(const int x, const int y, const int center)
|
|
\see fl_message_position(Fl_Widget *)
|
|
*/
|
|
int fl_message_position(int *x, int *y) {
|
|
return Fl_Message::message_position(x, y);
|
|
}
|
|
|
|
/** Sets whether or not to move the message box used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password() to follow
|
|
the mouse pointer.
|
|
|
|
The default is \e enabled, so that the default button is the
|
|
hotspot and appears at the mouse position.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] enable non-zero enables hotspot behavior,
|
|
0 disables hotspot
|
|
*/
|
|
void fl_message_hotspot(int enable) {
|
|
Fl_Message::message_hotspot(enable);
|
|
}
|
|
|
|
/** Gets whether or not to move the message box used in
|
|
many common dialogs like fl_message(), fl_alert(),
|
|
fl_ask(), fl_choice(), fl_input(), fl_password() to follow
|
|
the mouse pointer.
|
|
|
|
This is a permanent setting. It remains active and affects the window
|
|
position unless overridden by an explicit positioning request by means
|
|
of one of the fl_message_position() variants.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\return 0 if disabled, non-zero otherwise
|
|
|
|
\see void fl_message_hotspot(int)
|
|
\see int fl_message_position(int *x, int *y)
|
|
\see void fl_message_position(Fl_Widget *)
|
|
\see fl_message_position()
|
|
*/
|
|
int fl_message_hotspot() {
|
|
return Fl_Message::message_hotspot();
|
|
}
|
|
|
|
/** Sets the title of the dialog window used in many common dialogs.
|
|
|
|
This window \p title will be used in the next call of one of the
|
|
common dialogs like fl_message(), fl_alert(), fl_ask(), fl_choice(),
|
|
fl_input(), fl_password().
|
|
|
|
The \p title string is copied internally, so that you can use a
|
|
local variable or free the string immediately after this call. It
|
|
applies only to the \b next call of one of the common dialogs and
|
|
will be reset to an empty title (the default for all dialogs) after
|
|
that call.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
\param[in] title window label, string copied internally
|
|
*/
|
|
void fl_message_title(const char *title) {
|
|
Fl_Message::message_title(title);
|
|
}
|
|
|
|
/** Sets the default title of the dialog window used in many common dialogs.
|
|
|
|
This window \p title will be used in all subsequent calls of one of the
|
|
common dialogs like fl_message(), fl_alert(), fl_ask(), fl_choice(),
|
|
fl_input(), fl_password(), unless a specific title has been set
|
|
with fl_message_title(const char *title).
|
|
|
|
The default is no title. You can override the default title for a
|
|
single dialog with fl_message_title(const char *title).
|
|
|
|
The \p title string is copied internally, so that you can use a
|
|
local variable or free the string immediately after this call.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
|
|
\param[in] title default window label, string copied internally
|
|
*/
|
|
void fl_message_title_default(const char *title) {
|
|
Fl_Message::message_title_default(title);
|
|
}
|
|
|
|
/** Sets the icon label of the dialog window used in many common dialogs.
|
|
|
|
This icon label will be used in the next call of one of the
|
|
common dialogs like fl_message(), fl_alert(), fl_ask(), fl_choice(),
|
|
fl_input(), fl_password().
|
|
|
|
The label \p str is stored internally as a reference, it must be
|
|
in scope until the dialog function (e.g. fl_choice) is called.
|
|
|
|
It applies only to the \b next call of one of the common dialogs and
|
|
will be reset after that call so the next dialog will use its default
|
|
label unless set again.
|
|
|
|
\note This label string must be short, usually only one character so
|
|
it fits in the icon box. You can use any valid UTF-8 character, e.g.
|
|
the Euro sign ("€") which is three bytes in UTF-8 encoding.
|
|
|
|
\code #include <FL/fl_ask.H> \endcode
|
|
\param[in] str icon label
|
|
*/
|
|
void fl_message_icon_label(const char *str) {
|
|
Fl_Message::icon_label(str);
|
|
}
|
|
|
|
/** @} */
|