Editor window documentation complete.

fluid/autodoc.cxx

@@ -423,6 +423,10 @@ void run_autodoc(const Fl_String &target_dir) {
   // explain selection, multiple selection, keyboard shortcuts
   // explain mouse functionality and alignment
   // explain live resize
+  // arrow: move by 1
+  // shift: resize by one
+  // Meta: move by Widget Gap
+  // Shift Meta: resize by Widget Increment
 
   // ---- widget bin
   // show grouping

fluid/custom_widgets.cxx

@@ -55,7 +55,7 @@ int Widget_Bin_Button::handle(int inEvent)
         // fake a drag outside of the widget
         Fl::e_x = x()-1;
         Fl_Button::handle(inEvent);
-        // fake a buttton release
+        // fake a button release
         Fl_Button::handle(FL_RELEASE);
         // make it into a dnd event
         const char *type_name = (const char*)user_data();

fluid/documentation/Doxyfile.in

@@ -785,6 +785,7 @@ WARN_LOGFILE           =
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/index.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_main_window.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_widgetbin_panel.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_edit_window.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_functional_nodes.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_widget_panel.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_setting_dialog.dox \

fluid/documentation/src/index.dox

@@ -96,13 +96,22 @@
 
  \subpage page_widgetbin_panel
 
+ \subpage page_edit_window
+ - \ref edit_selection
+ - \ref edit_layout
+ - \ref edit_snap
+ - \ref edit_resize
+
  \subpage page_widget_panel
  - \ref widget_panel_gui
  - \ref widget_panel_style
  - \ref widget_panel_cpp
  - \ref widget_panel_grid
  - \ref widget_panel_gridc
 
+ </TD>
+ <TD ALIGN="LEFT" VALIGN="TOP">
+
  \subpage page_functional_nodes
  - \ref functional_function
  - \ref functional_code
@@ -114,9 +123,6 @@
  - \ref functional_comment
  - \ref functional_data
 
- </TD>
- <TD ALIGN="LEFT" VALIGN="TOP">
-
  \subpage page_sourceview_panel
  - \ref codeview_find
  - \ref codeview_settings

fluid/documentation/src/page_edit_window.dox

@@ -0,0 +1,170 @@
+/**
+
+ \page page_edit_window Layout Editor Window
+
+ \tableofcontents
+
+ \image html edit_window.jpg "Layout Editor Window"
+ \image latex edit_window.jpg "Layout Editor Window"
+
+ The Layout Editor window is used to interactively add groups and widgets, and
+ resize and align them. The editor window already looks very much like the
+ final product that will be built by the FLUID generated C++ source code.
+
+ To create a user interface, first add a function to the project tree by either
+ clicking the Function icon in the widget bin, or by selecting *New* > *Code* >
+ *Function/Method* from the main menu.
+
+ Now just drag the Window icon from the widget bin onto the desktop. Running
+ the above function will create this window. The return value is a pointer
+ that `Fl_Window` class. More group widgets can be added by dragging them from
+ the widget bin. If a widget is dropped on a group, it will automatically
+ become a child of that group.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section edit_selection Selecting and Moving Widgets
+
+ To move are resize a widget, it must be selected first by clicking on it.
+ Multiple widgets can be selected by holding down the Shift key when selecting,
+ or by dragging a selection box around widgets.
+
+ \image html edit_select_multiple.jpg
+ \image latex edit_select_multiple.jpg
+
+ Menu items are selected by clicking on the menu button and selecting it from
+ the popup menu. Multiple menu items can only be selected in the widget browser
+ in the main application window.
+
+ Once selected, widgets can be moved by clicking and dragging from the center
+ of the selection box. The outer edges allow resizing in one direction, and
+ clicking the corners resize widgets horizontally and vertically.
+
+ Widgets can also be repositioned with the arrow keys. Without a shift key,
+ the selection moves by a single pixel. With the Meta key held down, they
+ move by the amount indicated in the *Gap* field in the *Widget* section of
+ the *Layout* setting panel.
+
+ Holding down the Shift key resizes a selected widget by moving the bottom
+ right corner of the widget. Holding Shift and Meta while pressing arrow keys
+ resizes by the amount in the *Widget* *Gap* layout setting.
+
+ Children of groups that reposition their contained widgets may behave
+ differently. Pressing the arrow keys on children of `Fl_Grid` will move
+ the widget from grid cell to grid cell instead. Resizing a child of `Fl_Flex`
+ will also mark the child size as `fixed`.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section edit_layout Layout Helpers
+
+ \image html edit_overlap.jpg
+ \image latex edit_overlap.jpg
+
+ In FLTK, the behavior of overlapping children of a group is undefined. If
+ enabled in the settings, FLUID will show overlapping widget in a group
+ with a green hash pattern.
+
+ \image html edit_outside.jpg
+ \image latex edit_outside.jpg
+
+ The behavior of widgets that reach outside the bound of their parent group
+ is also undefined. They may be visible, but confuse the user when they don't
+ react to mouse clicks or don't redraw as expected. Outside widgets are marked
+ with a red hash pattern.
+
+ Note that `Fl_Tile` requires that all children exactly fill the area of the
+ tile group to function properly. The hash patterns are great helpers to align
+ children correctly.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section edit_snap Layout Alignment
+
+ FLUID Layouts are a handful of rules that help creating a clean and consistent
+ user interface. When repositioning widgets, the mouse pointer snaps to the
+ closes position based on those rules. A guide line is drawn for rule that was
+ applied. Guides and snaps can be disables with `Ctrl-Shift-G` or via the
+ *Edit* > *Hide Guides* menu.
+
+ \image html edit_snap_group.jpg
+ \image latex edit_snap_group.jpg
+
+ If a horizontal or vertical outline snaps to the group, the
+ border of that group will highlight. If the outline snaps to the margin
+ of the parent window or group, an additional arrow is drawn.
+
+ Children of the `Fl_Tabs` use the top and bottom margin from the *Tabs*
+ section. If all children use this rule, the mergin height will also be the
+ height of all tabs.
+
+ \image html edit_snap_sibling.jpg
+ \image latex edit_snap_sibling.jpg
+
+ The selection can also snap to the outline of other widgets in the same group,
+ or to the outline plus the Widget Gap. The outline that triggers the snap
+ action is highlighted.
+
+ Note that only the first snap guide found is drawn for horizontal and vertical
+ movement. Multiple rules may apply, but are not highlighted.
+
+ \image html edit_snap_size.jpg
+ \image latex edit_snap_size.jpg
+
+ Widget size rules define a minimum size, and an increment value that may
+ be applied multiple times to the size. For example, with a minimum width of 25
+ and an increment of 10, the widget will snap horizontally to 25, 35, 45,
+ 55, etc. .
+
+ \image html edit_snap_grid.jpg
+ \image latex edit_snap_grid.jpg
+
+ The grid rule is the easiest to explain. All corners of a selection snap to
+ a fixed grid. If the selected widgets are children of a window, they will snap
+ to the window grid. If they are in a group, they snap to the group grid.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section edit_resize Live Resize
+
+ \image html edit_select_group.jpg
+ \image latex edit_select_group.jpg
+
+ The Resizable system within FLTK is smart, but not always obvious. When
+ constructing a sophisticated GUI, it is helpful to organize widgets into
+ multiple levels of nested groups. Sometimes, incorporating an invisible
+ resizable box can improve the behavior of a group. FLUID offers a Live Resize
+ feature, allowing designers to experiment with resizing at each level within
+ the hierarchy independently.
+
+ To test the resizing behavior of a group, begin by selecting it:
+
+ \image html edit_live_resize.jpg
+ \image latex edit_live_resize.jpg
+
+ Click on *Live Resize* in the widget panel. FLUID will generate a new window
+ with all the resizing attributes inherited from the original design. This
+ enables the designer to thoroughly test the behavior and limitations,
+ making adjustments until they are satisfied. This streamlined process makes
+ it significantly easier to address resizing behavior at a higher level,
+ particularly once the lower levels are behaving as anticipated.
+
+ In the example above, the radio buttons are not fixed to the left side of
+ the group and the text snippet "of the bed" does not stay aligned
+ to "right side". To fix this, a thin hidden box could be added to the right
+ edge of the group that holds the radio button which is then marked `resizable`.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section edit_limits Limitations
+
+ Almost all FLTK widgets can be edited with FLUID. Notable exceptions include
+
+ - FLUID does not support `Fl_Window` inside and `Fl_Window`
+ - widgets inside `Fl_Scroll` can not be created in the hidden areas of the
+   scrollable rectangle. It is recommended to organize the children in
+   a separate Widget Class that is derived from `Fl_Scroll` and then inserted
+   as a single custom widget.
+ - children of `Fl_Pack` are not automatically reorganized to fit the packing
+   group. Again, a Widget Class is recommended here.
+ - if children of `Fl_Grid` are again some kind of group, their internal layout
+   may not follow changes in the grid widgets. It's best to first complete the
+   grid, and the add children to the grid cells later, size them correctly, and
+   the finally lay out the grid cell children.
+
+*/

fluid/documentation/src/page_widgetbin_panel.dox

@@ -22,6 +22,9 @@
  The Window and Widget Class icons can be dragged onto the desktop,
  creating a new window at the drop position.
 
+ \image html widgetbin_action.jpg
+ \image latex widgetbin_action.jpg
+
  All other widget types can be dragged from the bin into a window, or a group
  inside a window. When dropped, they will be positioned close to the drop point
  and inserted into the widget tree as the last child of the chosen group.

fluid/fluid.cxx

@@ -2275,7 +2275,7 @@ int main(int argc,char **argv) {
   // check if the user wants FLUID to generate image for the user documentation
   if (!g_autodoc_path.empty()) {
     run_autodoc(g_autodoc_path);
-//    return 0;
+    return 0;
   }
 #endif