fltk/fluid/documentation/src/page_setting_dialog.dox

/**

 \page page_setting_dialog Settings Dialog

 \tableofcontents

 <img src="w_settings.png" align="left" hspace="10" vspace="10" />
 \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.

 <div style="clear:both;"></div>

 <!-- ---------------------------------------------------------------------- -->
 \section setting_general Application Settings

 <img src="w_settings_general_tab.png" align="left" hspace="10" vspace="10" />
 \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.

 <div style="clear:both;"></div>

 <!-- ---------------------------------------------------------------------- -->
 \section setting_project Project Settings

 <img src="w_settings_project_tab.png" align="left" hspace="10" vspace="10" />
 \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 `<FL/Fl.H>` 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 `<FL/Fl.H>` later using a Declaration node.

  <div style="clear:both;"></div>

 <!-- ---------------------------------------------------------------------- -->
 \section setting_layout Layout Preferences

 <img src="w_settings_layout_tab.png" align="left" hspace="10" vspace="10" />
 \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.

  <div style="clear:both;"></div>

 <!-- ---------------------------------------------------------------------- -->
 \section setting_shell Shell Commands

 <img src="w_settings_shell_tab.png" align="left" hspace="10" vspace="10" />
 \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.

  <div style="clear:both;"></div>

 <!-- ---------------------------------------------------------------------- -->
 \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 <libintl.h>
 #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 <libintl.h>, 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 <tt>.fl</tt> file; you still need to call
 \p setlocale() to select the appropriate language.

 This option adds some preprocessor code to the source file:
 ```
 #include <nl_types.h>
 // Initialize I18N stuff now for menus...
 #include <locale.h>
 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 <nl_types.h>, 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
<tt>.fl</tt> 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

 <img src="w_settings_user_tab.png" align="left" hspace="10" vspace="10" />
 \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.

 <div style="clear:both;"></div>

 */