From fc91880faf7968432710e439e77ef067759d16fc Mon Sep 17 00:00:00 2001
From: Matthias Melcher <github@matthiasm.com>
Date: Tue, 15 Apr 2025 14:47:24 +0200
Subject: Reactivating Mergeback functionality. (#1226)

Reactivated code.
Various fixes.
New documentation.
---
 fluid/documentation/Doxyfile.in            |  1 +
 fluid/documentation/src/index.dox          |  2 +
 fluid/documentation/src/page_mergeback.dox | 84 ++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)
 create mode 100644 fluid/documentation/src/page_mergeback.dox

(limited to 'fluid/documentation')

diff --git a/fluid/documentation/Doxyfile.in b/fluid/documentation/Doxyfile.in
index f625dd52a..8e9bee234 100644
--- a/fluid/documentation/Doxyfile.in
+++ b/fluid/documentation/Doxyfile.in
@@ -792,6 +792,7 @@ INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/index.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_widget_panel.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_setting_dialog.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_codeview_panel.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_mergeback.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_tutorial.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_appendices.dox
                          
diff --git a/fluid/documentation/src/index.dox b/fluid/documentation/src/index.dox
index 7a2808207..94c47b4c5 100644
--- a/fluid/documentation/src/index.dox
+++ b/fluid/documentation/src/index.dox
@@ -96,6 +96,8 @@
  - \ref setting_i18n
  - \ref setting_user
 
+ \subpage page_mergeback
+
  \subpage page_tutorial
  - \ref fluid_hello_world_tutorial
  - \ref fluid_1of7guis_tutorial
diff --git a/fluid/documentation/src/page_mergeback.dox b/fluid/documentation/src/page_mergeback.dox
new file mode 100644
index 000000000..20c0026c9
--- /dev/null
+++ b/fluid/documentation/src/page_mergeback.dox
@@ -0,0 +1,84 @@
+/**
+
+ \page page_mergeback Fluid Mergeback
+
+ \tableofcontents
+
+ # Introduction to Mergeback #
+
+ Fluid has introduced an experimental feature called **MergeBack** in version 1.5. 
+ This feature allows developers to edit the C++ source files generated by Fluid and 
+ then merge those changes back into the corresponding Fluid project file (.fl). This 
+ can streamline the development process by reducing the need to switch between Fluid
+ and your code editor for minor adjustments.
+
+ **Important Note:** MergeBack is currently experimental and may not handle all 
+ scenarios perfectly. It's advisable to back up your project files before using this
+ feature to prevent potential data loss.
+
+ **Enabling MergeBack:**
+
+ 1. **Open Your Project in Fluid:**
+   - Launch Fluid and load your existing `.fl` project file.
+
+ 2. **Enable MergeBack:**
+   - Navigate to the **Settings Panel**.
+   - In the **Project Settings**, locate and enable the **MergeBack** option.
+
+ Once enabled, Fluid assigns a unique ID to each node in your project. 
+ Additionally, user-editable code sections in the generated source files will 
+ be marked with special divider lines, indicating areas that can be edited 
+ and later merged back.
+
+ **Understanding the Code Markers:**
+
+ In the generated `.cxx` files, editable sections are demarcated as follows:
+
+ ```cpp
+ static void cb_script_panel(Fl_Double_Window*, void*) {
+    //fl ▼ ---------------------- callback ~~----~~~~=-=~~~~=-~~~ ▼ fl//
+    if (Fl::event() == FL_SHORTCUT && Fl::event_key() == FL_Escape) return;
+    script_panel->hide();
+    //fl ▲ ----------=~-~~=-=--=~-----------~-==--~=~-~~--~=-~=~- ▲ fl//
+ }
+ ```
+
+ The lines beginning with `//fl ▼` and `//fl ▲` are markers that Fluid 
+ uses to identify editable sections. These markers contain encoded information 
+ about the code block, including a CRC32 checksum and a unique node ID. Fluid 
+ uses this information during the merge process to detect changes and associate 
+ them with the correct nodes in your project.
+
+ **Editing and Merging Back:**
+
+ 1. **Edit the Source Code:**
+   - Open the generated `.cxx` file in your preferred code editor.
+   - Make your desired changes within the marked sections.
+
+ 2. **Merge Changes Back into Fluid:**
+   - After saving your edits, return to Fluid.
+   - Select **File > MergeBack** from the main menu or press `Ctrl+Shift+M`.
+   - Fluid will analyze the `.cxx` file, detect changes within the marked 
+     sections, and offer to merge them back into the `.fl` project file.
+
+ **Things to Keep in Mind:**
+
+ - **Scope of MergeBack:** Currently, MergeBack supports merging changes 
+   made to code blocks and widget callbacks. Other modifications might 
+   not be recognized or merged correctly.
+
+- **Conflict Detection:** Fluid calculates checksums (CRC32) for the 
+  code blocks to detect changes. If discrepancies are found, Fluid 
+  will prompt you with options to merge or cancel the changes.
+
+- **Undo Functionality:** In case of unintended merges, Fluid provides 
+  an undo feature to revert the project to its previous state.
+
+**Caution:** Given the experimental nature of MergeBack, unexpected 
+behaviors may occur. Always ensure you have backups of your project 
+files before using this feature.
+
+\note The MergeBack feature is still under development. It's recommended 
+      to use it cautiously and provide feedback to the FLTK development 
+      team to help improve its functionality and reliability.
+*/
-- 
cgit v1.2.3