diff options
Diffstat (limited to 'fluid/documentation/src/page_mergeback.dox')
| -rw-r--r-- | fluid/documentation/src/page_mergeback.dox | 84 |
1 files changed, 84 insertions, 0 deletions
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. +*/ |