/**
\page page_setting_dialog Settings Dialog
\tableofcontents
\image latex w_settings.png "Settings Dialog" width=7cm
The *Settings* dialog combines application preferences
and project settings in a compact set of six tabs.
The *General* tab contains a collection of application wide settings. They are
stored as user preferences.
The *Project* tab holds settings for the current project. They are saved with
the `.fl` file.
The *Layout* tab manages databases of preferred widget alignment. These
preferences can be saved per user, or as part of the project, or exported for
use in other projects.
The *Shell* tab manages a database of quick access shell commands and scripts.
Shell commands can be saved as a user preference and also as part of the
`.fl` project file.
The *Locale* tab sets the method of internationalizing texts in the project,
commonly used for labels and tooltips.
The *User* tab manages customization of fonts and colors in the widget browser.
These settings are stored as user preferences.
\section setting_general Application Settings
\image latex w_settings_general_tab.png "General Settings Tab" width=7cm
__Scheme__:
Select one of the graphics schemes built into FLTK. It's helpful
to verify the look of various schemes for an application design.
__Options__:
Various options to make life as a developer more convenient.
__Recent Files__:
FLUID keeps track of recently opened files.
__External Editor__:
Users that don't like the built-in FLUID code editor can enter a shell command
here that opens the content of Code nodes in an external editor. FLUID does
its best to pick up on changed content or when the editor is closed.
__Overlays__:
The *Position Guides* are little red arrows that indicate if snap points are
found. See the *Layout* tab for details. *Restricted Areas* are areas where
widgets from within the same group overlap. They are visible in the project
window as a diagonally hashed pattern. *Ghosted Group Outlines* show faint
frames around groups that would otherwise be invisible in the project window.
\section setting_project Project Settings
\image latex w_settings_project_tab.png "Project Settings Tab" width=7cm
__Header File__, __Code File__:
These fields are used to build the file path and name of the generated header
and source file. If one field is empty the value defaults to `.h` and `.cxx`
respectively. If a name starts with a `.`, FLUID assumes that the rest of the
text is a file extension. The code file name is then generated by replacing
the extension of the `.fl` project file name.
\todo Document the exact way the source and header file paths are calculated
for interactive FLUID, and for FLUID launched from the command line.
__Include Header from Code__:
If checked, the statement to include the header file is automatically
generated in one of the first lines of the source file.
__Menu shortcuts use FL_COMMAND__:
Setting this option will replace FL_CTRL and FL_META as a modifier for
shortcuts with the platform aware modifiers FL_COMMAND and FL_CONTROL, making
shortcuts more portable between macOS and Windows/Linux.
__allow Unicode__:
If unchecked, Unicode characters in strings are escaped. If checked, the Unicode
character is stored in the source code in UTF-8 encoding.
__avoid early include__:
FLUID by default includes `` early in the header file. If this option
is checked, users can include other files before including the FL header. The
user must then include `` later using a Declaration node.
\section setting_layout Layout Preferences
\image latex w_settings_layout_tab.png "Layout Settings Tab" width=7cm
Layouts are a collection of hints that help when interactively positioning and
resizing widgets in the project window. Layouts come in a set of three for
the application window, for dialog boxes, and for toolboxes.
__Layout__:
The layout pulldown menu lets users choose from a list of existing layouts.
The plus button creates a new set of layouts based on the currently selected
layout.
The pulldown menu has items to rename, load, and save layouts. It can also
change the location where the layout is stored. The FLUID beaker is for
layouts that are predefined in FLUID, the portrait icon stores as user
preference, the document
icon stores the layout in the `.fl` file, and the disk icon lets users store
layout in external files.
__Window Margin and Grid__:
Snap widget position to that margin in relation to the window. The grid
snaps widgets to fixed intervals.
__Group Margin and Grid__:
Snap widget position to that margin in relation to the group. The grid
snaps widgets to fixed intervals relative to the top left of the group.
__Tabs Margin__:
Snap the tab inside `Fl_Tabs` to the tab border and the offset given in
Margins.
__Widget Minimum, Increment, and Gap__:
_Minimum_ sets the minimal width of a widget. _Increment_ is the size multiplier
added to the _Minimum_ value. _Gap_ is the preferred distance to other widgets
in the same group.
__Label Font__, __Text Font__:
The preferred label and text font and size for new widgets.
\section setting_shell Shell Commands
\image latex w_settings_shell_tab.png "Shell Settings Tab" width=7cm
__Shell Command List__:
A list of all currently available shell commands. The portrait symbol in front
of the name indicates that the script is stored in the user preferences. The
document symbol saves them within the `.fl` project file.
`[+]` adds a fresh new script to the list, `[++]` duplicates the currently
selected script. `[DEL]` deletes it, and `[v]` offers import and export
functionality. The `[T]` button shows the terminal window, and finally the
`[Run]` button runs the selected shell script.
Selecting a shell script will fill in the bottom half of the dialog.
__Name__:
This is the name of the script as it appears in the Shell Command List.
__Menu Label__:
Shell scripts that match the *Condition* flag are also available for quick
access in the *Shell* menu in the main window and via shortcut key
combinations. This is the text that is used for the menu entry.
__Shortcut__:
Assign a keyboard shortcut to this shell script for even faster access. FLUID
does not check if a shortcut is already used elsewhere. Try to avoid
collisions, especially when the script is part of a project file.
__Store__:
Choose where to store the settings of this shell script, either in the user
preferences or as part of the `.fl` project file.
__Condition__:
Shell scripts can be quite different for different platforms hosting FLUID.
This choice limits scripts to specific platforms. Multiple scripts can have
the same shortcut if they have different conditions.
__Shell Script__:
This is a text field for the shell script. The `[v]` pulldown menu has a list
of variables that are replaced with the corresponding value before running
the script. The zoom button gives access to a much larger shell script editor.
The options below are a list of actions that can be executed before running
the script.
\section setting_i18n Internationalization
The *Locale* tab can be used to configure optional internationalization.
FLUID supports GNU `gettext` and POSIX `catgets`.
FLUID supports internationalization (I18N for short) of label
strings and tooltips used by widgets. The GNU gettext option also
supports deferred translation of statically initialized menu item
labels. The setting panel (`Alt+p`) provides access
to the I18N options.
\image html w_settings_i18n_gnu.png
\image latex w_settings_i18n_gnu.png "I18N With GNU gettext" width=7cm
FLUID supports three methods of I18N: none, GNU
gettext, and POSIX catgets. The "none" method is the
default and just passes the label strings as-is to the widget
constructors.
The "GNU gettext" method uses GNU gettext (or a similar
text-based I18N library) to retrieve a localized string before
calling the widget constructor.
The GNU gettext option adds some preprocessor code to the source file:
```
#include
#ifndef gettext_noop
# define gettext_noop(text) text
#endif
```
and the gettext call around strings in the source code:
```
new Fl_Button(50, 50, 54, 40, "Button");
// ->
new Fl_Button(50, 50, 54, 40, gettext("Button"));
```
FLUID's code support for GNU gettext is limited to calling a
function or macro to retrieve the localized label; you still
need to call \p setlocale() and \p textdomain() or
\p bindtextdomain() to select the appropriate language and
message file.
__Include__: controls the header file to include for
I18N; by default this is \b , the
standard I18N file for GNU gettext.
__Conditional__: If this field contains a macro name, i18n will only be
compiled into the product if this macro is defined. The build system should
define the macro only if all required headers and libraries are available. If
the macro is not defined, no headers are included and `gettext` passes text
through untranslated.
__Function__: controls the function (or macro) that will retrieve the localized
message; by default the \p gettext function will be called.
__Static Function__: names a macro that will mark static text fields for
extraction with the `xgettext` tool. The default macro name is
\p gettext_noop and will be defined as `#define gettext_noop(text) text`
right after the `#include` statement. FLUID will call `gettext` on static
texts later, after the textdomain was set by the user.
\see [GNU gettext special cases](https://www.gnu.org/software/gettext/manual/html_node/Special-cases.html)
\image html w_settings_i18n_psx.png
\image latex w_settings_i18n_psx.png "I18N With POSIX catgets" width=7cm
The "POSIX catgets" method uses the POSIX catgets function to
retrieve a numbered message from a message catalog before
calling the widget constructor.
FLUID's code support for POSIX catgets allows you to use a
global message file for all interfaces or a file specific to
each .fl file; you still need to call
\p setlocale() to select the appropriate language.
This option adds some preprocessor code to the source file:
```
#include
// Initialize I18N stuff now for menus...
#include
static char *_locale = setlocale(LC_MESSAGES, "");
static nl_catd _catalog = catopen("", 0);
```
and the catgets call around strings in the source code:
```
new Fl_Button(50, 50, 54, 40, "Button");
// ->
new Fl_Button(50, 50, 54, 40, catgets(_catalog,1,6,"Button"));
```
__Include__: controls the header file to include for
I18N; by default this is \b , the
standard I18N file for POSIX catgets.
__Conditional__: include the header file only if this preprocessor macro is
defined.
__Catalog__: controls the name of the catalog file
variable to use when retrieving localized messages; by default
the file field is empty which forces a local (static) catalog
file to be used for all of the windows defined in your
.fl file.
__Set__: controls the set number in the catalog file.
The default set is 1 and rarely needs to be changed.
\section setting_user User Interface Preferences
\image latex w_settings_user_tab.png "User Settings Tab" width=7cm
This tab lets users change the font and color of text in the widget browser.
The settings are stored in the user preferences.
All changes are directly visible in the widget browser.
*/