FLTK 1.4.5: Common Dialog Classes and Functions

FLTK 1.4.5

Loading...
Searching...
No Matches
Common Dialog Classes and Functions

Common dialog functions for file selection, message output, and more. More...

## Files
file | fl_ask.cxx
| Utility functions for common dialogs.

## Classes
class | Fl_Color_Chooser
| The Fl_Color_Chooser widget provides a standard RGB color chooser. More...
class | Fl_File_Chooser
| The Fl_File_Chooser widget displays a standard file selection dialog that supports various selection modes. More...

## Functions
void | fl_alert (const char *fmt,...)
| Shows an alert message dialog box.
int | fl_ask (const char *fmt,...)
| Shows a dialog displaying the `fmt` message, this dialog features 2 yes/no buttons.
void | fl_beep (int type)
| Emits a system beep.
int | fl_choice (const char *fmt, const char *b0, const char *b1, const char *b2,...)
| Shows a dialog displaying the printf style `fmt` message.
int | fl_choice_n (const char *fmt, const char *b0, const char *b1, const char *b2,...)
| Shows a dialog displaying the printf style `fmt` message.
int | fl_color_chooser (const char *name, double &r, double &g, double &b, int cmode)
| Pops up a window to let the user pick an arbitrary RGB color.
int | fl_color_chooser (const char *name, uchar &r, uchar &g, uchar &b, int cmode)
| Pops up a window to let the user pick an arbitrary RGB color.
char * | fl_dir_chooser (const char *message, const char *fname, int relative)
| Shows a file chooser dialog and gets a directory.
char * | fl_file_chooser (const char *message, const char *pat, const char *fname, int relative)
| Shows a file chooser dialog and gets a filename.
void | fl_file_chooser_callback (void(*cb)(const char *))
| Set the file chooser callback.
void | fl_file_chooser_ok_label (const char *l)
| Set the "OK" button label.
const char * | fl_input (const char *fmt, const char *defstr,...)
| Shows an input dialog displaying the `fmt` message with variable arguments.
const char * | fl_input (int maxchar, const char *fmt, const char *defstr,...)
| Shows an input dialog displaying the `fmt` message with variable arguments.
void | fl_message (const char *fmt,...)
| Shows an information message dialog box.
int | fl_message_hotspot ()
| 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.
void | fl_message_hotspot (int enable)
| 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.
Fl_Widget * | fl_message_icon ()
| 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().
void | fl_message_icon_label (const char *str)
| Sets the icon label of the dialog window used in many common dialogs.
void | fl_message_position (const int x, const int y, const int 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().
void | fl_message_position (Fl_Widget *widget)
| 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().
int | fl_message_position (int *x, int *y)
| 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().
void | fl_message_title (const char *title)
| Sets the title of the dialog window used in many common dialogs.
void | fl_message_title_default (const char *title)
| Sets the default title of the dialog window used in many common dialogs.
const char * | fl_password (const char *fmt, const char *defstr,...)
| Shows an input dialog displaying the `fmt` message with variable arguments.
const char * | fl_password (int maxchar, const char *fmt, const char *defstr,...)
| Shows an input dialog displaying the `fmt` message with variable arguments.

## Variables
static void(* | Fl::error )(const char *,...) = Fl_System_Driver::error
| FLTK calls Fl::error() to output a normal error message.
static void(* | Fl::fatal )(const char *,...) = Fl_System_Driver::fatal
| FLTK calls Fl::fatal() to output a fatal error message.
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
Fl_Font | fl_message_font_ = FL_HELVETICA
Fl_Fontsize | fl_message_size_ = -1
const char * | fl_no = "No"
| 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_yes = "Yes"
| string pointer used in common dialogs, you can change it to another language
static void(* | Fl::warning )(const char *,...) = Fl_System_Driver::warning
| FLTK calls Fl::warning() to output a warning message.

## Detailed Description

Common dialog functions for file selection, message output, and more.

## Function Documentation

## ◆ fl_alert()

void fl_alert | ( | const char * | fmt,
|  |  | ... )

Shows an alert message dialog box.

#include <FL/fl_ask.H>
fl_ask.H
API for common dialogs.

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text

## ◆ fl_ask()

int fl_ask | ( | const char * | fmt,
|  |  | ... )

Shows a dialog displaying the `fmt` message, this dialog features 2 yes/no buttons.

#include <FL/fl_ask.H>

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text

Return values

  0 | if the no button is selected
  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.

## ◆ fl_beep()

void fl_beep | ( | int | type | ) |

Emits a system beep.

This function is platform specific. Depending on the input `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 `FL_BEEP_DEFAULT` and other types honor the system or user settings whereas `FL_BEEP_ERROR` uses 100% volume. This may be changed in a future version.

On Wayland an ASCII `BEL` (0x07) is output to stderr.

On Windows the `MessageBeep()` function is used to play different sounds depending on the `type` argument.

On macOS the system beep function `NSBeep()` is used for `FL_BEEP_DEFAULT` and `FL_BEEP_ERROR`. Other types are ignored.

On other platforms the behavior is undefined and may change in the future.

Parameters

  [in] | type | The beep type from the Fl_Beep enumeration (optional)

#include <FL/fl_ask.H>

## ◆ fl_choice()

int fl_choice | ( | const char * | fmt,
|  | const char * | b0,
|  | const char * | b1,
|  | const char * | b2,
|  |  | ... )

Shows a dialog displaying the printf style `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.

#include <FL/fl_ask.H>

Three choices with printf() style formatting:

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
..
}
fl_choice
int fl_choice(const char *fmt, const char *b0, const char *b1, const char *b2,...)
Shows a dialog displaying the printf style fmt message.
Definition fl_ask.cxx:217

Three choice example:

switch ( fl_choice("How many bedrooms?", "Zero", "One", "Two") ) {
case 0: .. // "Zero"
case 1: .. // "One" (default)
case 2: .. // "Two"
}

Two choice example:

switch ( fl_choice("Empty trash?", "Yes", "No", 0) ) {
case 0: .. // Yes
case 1: .. // No (default)
}

One choice example:

fl_choice("All hope is lost.", "OK", 0, 0); // "OK" default

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | b0 | text label for right button 0
  [in] | b1 | text label for middle button 1 (can be 0)
  [in] | b2 | text label for left button 2 (can be 0)

Return values

  0 | if the button with `b0` text is pushed or the user pressed the `Escape` key or clicked the window close button
  1 | if the button with `b1` text is pushed or the user pressed the `Return` key
  2 | if the button with `b2` text is pushed

## ◆ fl_choice_n()

int fl_choice_n | ( | const char * | fmt,
|  | const char * | b0,
|  | const char * | b1,
|  | const char * | b2,
|  |  | ... )

Shows a dialog displaying the printf style `fmt` message.

This function is like fl_choice() but returns `-1` if the dialog window was closed by pressing the `Escape` key or the window close button rather than pushing one of the dialog buttons.

See also
  fl_choice()

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | b0 | text label for right button 0
  [in] | b1 | text label for middle button 1 (can be 0)
  [in] | b2 | text label for left button 2 (can be 0)

Return values

  -3 | reserved, FLTK 1.3 only: another dialog is still open (not possible in 1.4)
  -2 | if the dialog was closed by pushing the window close button
  -1 | if the dialog was closed by hitting Escape
  0 | if the button with `b0` text is pushed
  1 | if the button with `b1` text is pushed
  2 | if the button with `b2` text is pushed

## ◆ fl_color_chooser() [1/2]

int fl_color_chooser | ( | const char * | name,
|  | double & | r,
|  | double & | g,
|  | double & | b,
|  | int | cmode )
| related

Pops up a window to let the user pick an arbitrary RGB color.

Note
  #include <FL/Fl_Color_Chooser.H>

Parameters

  [in] | name | Title label for the window
  [in,out] | r,g,b | Color components in the range 0.0 to 1.0.
  [in] | cmode | Optional mode for color chooser. See mode(int). Default -1 if none (rgb mode).

Return values

  1 | if user confirms the selection
  0 | if user cancels the dialog

## ◆ fl_color_chooser() [2/2]

int fl_color_chooser | ( | const char * | name,
|  | uchar & | r,
|  | uchar & | g,
|  | uchar & | b,
|  | int | cmode )
| related

Pops up a window to let the user pick an arbitrary RGB color.

Note
  #include <FL/Fl_Color_Chooser.H>

Parameters

  [in] | name | Title label for the window
  [in,out] | r,g,b | Color components in the range 0 to 255.
  [in] | cmode | Optional mode for color chooser. See mode(int). Default -1 if none (rgb mode).

Return values

  1 | if user confirms the selection
  0 | if user cancels the dialog

## ◆ fl_dir_chooser()

char * fl_dir_chooser | ( | const char * | message,
|  | const char * | fname,
|  | int | relative )
| related

Shows a file chooser dialog and gets a directory.

Note
  #include <FL/Fl_File_Chooser.H>

Parameters

  [in] | message | title bar text
  [in] | fname | initial/default directory name
  [in] | relative | 0 for absolute path return, relative otherwise

Returns
  the directory path string chosen by the user or NULL if user cancels

## ◆ fl_file_chooser()

char * fl_file_chooser | ( | const char * | message,
|  | const char * | pat,
|  | const char * | fname,
|  | int | relative )
| related

Shows a file chooser dialog and gets a filename.

Note
  #include <FL/Fl_File_Chooser.H>

Parameters

  [in] | message | text in title bar
  [in] | pat | filename pattern filter
  [in] | fname | initial/default filename selection
  [in] | relative | 0 for absolute path name, relative path name otherwise

Returns
  the user selected filename, in absolute or relative format or NULL if user cancels

## ◆ fl_file_chooser_callback()

void fl_file_chooser_callback | ( | void(* | cb )(const char *) | ) |
| related

Set the file chooser callback.

Note
  #include <FL/Fl_File_Chooser.H>

## ◆ fl_file_chooser_ok_label()

void fl_file_chooser_ok_label | ( | const char * | l | ) |
| related

Set the "OK" button label.

Note
  #include <FL/Fl_File_Chooser.H>

## ◆ fl_input() [1/2]

const char * fl_input | ( | const char * | fmt,
|  | const char * | defstr,
|  |  | ... )

Shows an input dialog displaying the `fmt` message with variable arguments.

Returns the string in an internally allocated buffer 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.

#include <FL/fl_ask.H>

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | defstr | defines the default returned string if no text is entered

Returns
  the user string input if OK was pushed

Return values

  NULL | if Cancel was pushed or the window was closed by the user

## ◆ fl_input() [2/2]

const char * fl_input | ( | int | maxchar,
|  | const char * | fmt,
|  | const char * | defstr,
|  |  | ... )

Shows an input dialog displaying the `fmt` message with variable arguments.

This is the same as const char *fl_input(const char *fmt, const char *defstr, ...) except that it has an additional parameter to limit the number of characters the user can input.

Returns the string in an internally allocated buffer 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.

#include <FL/fl_ask.H>

Parameters

  [in] | maxchar | maximum number of characters the user can input (UTF-8 aware)
  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | defstr | defines the default returned string if no text is entered

Returns
  the user string input if OK was pushed

Return values

  NULL | if Cancel was pushed or the window was closed by the user

## ◆ fl_message()

void fl_message | ( | const char * | fmt,
|  |  | ... )

Shows an information message dialog box.

#include <FL/fl_ask.H>

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text

## ◆ fl_message_hotspot() [1/2]

int fl_message_hotspot | ( | void |  | ) |

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.

#include <FL/fl_ask.H>

Returns
  0 if disabled, non-zero otherwise

See also
  void fl_message_hotspot(int)
  int fl_message_position(int *x, int *y)
  void fl_message_position(Fl_Widget *)
  fl_message_position()

## ◆ fl_message_hotspot() [2/2]

void fl_message_hotspot | ( | int | enable | ) |

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 enabled, so that the default button is the hotspot and appears at the mouse position.

#include <FL/fl_ask.H>

Parameters

  [in] | enable | non-zero enables hotspot behavior, 0 disables hotspot

## ◆ fl_message_icon()

Fl_Widget * fl_message_icon | ( |  | ) |

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 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. `w()` and `h()` of the icon box.

#include <FL/fl_ask.H>

## ◆ fl_message_icon_label()

void fl_message_icon_label | ( | const char * | str | ) |

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 `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 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.

#include <FL/fl_ask.H>

Parameters

  [in] | str | icon label

## ◆ fl_message_position() [1/3]

void fl_message_position | ( | const int | x,
|  | const int | y,
|  | const int | 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 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 `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).

#include <FL/fl_ask.H>

Parameters

  [in] | x | Preferred X position
  [in] | y | Preferred Y position
  [in] | center | 1 = centered, 0 = absolute

See also
  int fl_message_position(int *x, int *y)

## ◆ fl_message_position() [2/3]

void fl_message_position | ( | Fl_Widget * | widget | ) |

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.

#include <FL/fl_ask.H>

Parameters

  [in] | widget | Widget or window to position the message box over.

See also
  int fl_message_position(int x, int y, int center)

## ◆ fl_message_position() [3/3]

int fl_message_position | ( | int * | x,
|  | int * | y )

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().

#include <FL/fl_ask.H>

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.

Parameters

  [out] | x | Preferred X position, returns -1 if not set
  [out] | y | Preferred Y position, returns -1 if not set

Returns
  whether position is currently set or not

Return values

  0 | position is not set (hotspot may be enabled or not)
  1 | position is set (window position)
  2 | position is set (message box centered)

See also
  fl_message_hotspot()
  fl_message_hotspot(int)
  fl_message_position(int, int)
  fl_message_position(const int x, const int y, const int center)
  fl_message_position(Fl_Widget *)

## ◆ fl_message_title()

void fl_message_title | ( | const char * | title | ) |

Sets the title of the dialog window used in many common dialogs.

This window `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 `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 next call of one of the common dialogs and will be reset to an empty title (the default for all dialogs) after that call.

#include <FL/fl_ask.H>

Parameters

  [in] | title | window label, string copied internally

## ◆ fl_message_title_default()

void fl_message_title_default | ( | const char * | title | ) |

Sets the default title of the dialog window used in many common dialogs.

This window `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 `title` string is copied internally, so that you can use a local variable or free the string immediately after this call.

#include <FL/fl_ask.H>

Parameters

  [in] | title | default window label, string copied internally

## ◆ fl_password() [1/2]

const char * fl_password | ( | const char * | fmt,
|  | const char * | defstr,
|  |  | ... )

Shows an input dialog displaying the `fmt` message with variable arguments.

Like fl_input() except the input text is not shown, '*' or similar replacement characters are displayed instead.

#include <FL/fl_ask.H>

Parameters

  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | defstr | defines the default returned string if no text is entered

Returns
  the user string input if OK was pushed

Return values

  NULL | if Cancel was pushed or the window was closed by the user

## ◆ fl_password() [2/2]

const char * fl_password | ( | int | maxchar,
|  | const char * | fmt,
|  | const char * | defstr,
|  |  | ... )

Shows an input dialog displaying the `fmt` message with variable arguments.

Like fl_input() except the input text is not shown, '*' or similar replacement characters are displayed instead.

#include <FL/fl_ask.H>

Parameters

  [in] | maxchar | input lenght limit in chars, 0 = no limit
  [in] | fmt | can be used as an sprintf-like format and variables for the message text
  [in] | defstr | defines the default returned string if no text is entered

Returns
  the user string input if OK was pushed

Return values

  NULL | if Cancel was pushed or the window was closed by the user

## Variable Documentation

## ◆ error

void(* Fl::error)(const char *format,...) = Fl_System_Driver::error
| static

FLTK calls Fl::error() to output a normal error message.

The default version on Windows displays the error message in a MessageBox window.

The default version on all other platforms prints the error message to stderr.

You can override the behavior by setting the function pointer to your own routine.

Fl::error() means there is a recoverable error such as the inability to read an image file. The default implementation returns after displaying the message.

Note
  #include <FL/Fl.H>

## ◆ fatal

void(* Fl::fatal)(const char *format,...) = Fl_System_Driver::fatal
| static

FLTK calls Fl::fatal() to output a fatal error message.

The default version on Windows displays the error message in a MessageBox window.

The default version on all other platforms prints the error message to stderr.

You can override the behavior by setting the function pointer to your own routine.

Fl::fatal() must not return, as FLTK is in an unusable state, however your version may be able to use longjmp or an exception to continue, as long as it does not call FLTK again. The default implementation exits with status 1 after displaying the message.

Note
  #include <FL/Fl.H>

## ◆ warning

void(* Fl::warning)(const char *format,...) = Fl_System_Driver::warning
| static

FLTK calls Fl::warning() to output a warning message.

The default version on Windows returns without printing a warning message, because Windows programs normally don't have stderr (a console window) enabled.

The default version on all other platforms prints the warning message to stderr.

You can override the behavior by setting the function pointer to your own routine.

Fl::warning() means that there was a recoverable problem, the display may be messed up, but the user can probably keep working - all X protocol errors call this, for example. The default implementation returns after displaying the message.

Note
  #include <FL/Fl.H>