Generalized the method structure in FXMLPropertiesDisabler to enable

future use. Corrected multiple spelling mistakes. Added javadoc.

kit/src/main/java/com/oracle/javafx/scenebuilder/kit/fxom/FXMLPropertiesDisabler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, Gluon and/or its affiliates.
+ * Copyright (c) 2022, Gluon and/or its affiliates.
  * All rights reserved. Use is subject to license terms.
  *
  * This file is available and licensed under the following license:
@@ -31,16 +31,32 @@
  */
 package com.oracle.javafx.scenebuilder.kit.fxom;
 
-class FXMLPropertiesDisabler {
+import java.util.Objects;
+
+import com.oracle.javafx.scenebuilder.kit.editor.EditorPlatform;
 
+class FXMLPropertiesDisabler {
     /**
+     * In some cases, during FXML Loading, certain properties must be disabled.
+     * This method modifies the FXML source accordingly.
      * 
+     * @param fxmlText FXML source to be modified
+     * @return FXML source with all properties disabled (=false) where WYSIWYG editing is not suitable.
+     * @throws NullPointerException in case of fxmlText is null
+     */
+    public String disableProperties(String fxmlText) {
+        Objects.requireNonNull(fxmlText, "fxmlText must not be null");
+        String modifiedFxml = disableUseSystemMenuBarProperty(fxmlText);
+        return modifiedFxml;
+    }
+
+    /**
      * On MacOS, when loading a FXML with a menu bar where useSystemMenuBarProperty()
-     * is enabled, the menu in the FXML will hide the menu of SceneBuilder. 
-     * In this case, SceneBuilder becomes unusable.
+     * is enabled, the menu in the FXML will hide the menu of Scene Builder. 
+     * In this case, Scene Builder becomes unusable.
      * 
      * Setting the property here to false has the advantage, that the FXML to be saved
-     * will still contain the defined property BUT the SceneBuilder menu bar will remain 
+     * will still contain the defined property BUT the Scene Builder menu bar will remain 
      * visible.
      * 
      * The modification of properties which are not desired to be active while
@@ -51,10 +67,14 @@ class FXMLPropertiesDisabler {
      * 
      * @param fxmlText FXML source to be modified
      * @return FXML source with all properties disabled (=false) where WYSIWYG editing is not suitable.
-     * 
+     * @throws NullPointerException in case of fxmlText is null
      */
-    public String disableUseSystemMenuBarProperty(String fxmlText) {
-        return fxmlText.replace("useSystemMenuBar=\"true\"",
-                                "useSystemMenuBar=\"false\"");
+    private String disableUseSystemMenuBarProperty(String fxmlText) {
+        Objects.requireNonNull(fxmlText, "fxmlText must not be null");
+        if (EditorPlatform.IS_MAC) {
+            return fxmlText.replace("useSystemMenuBar=\"true\"",
+                                    "useSystemMenuBar=\"false\"");
+        }
+        return fxmlText;
     }
 }

kit/src/main/java/com/oracle/javafx/scenebuilder/kit/fxom/FXOMDocument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2019, 2021, Gluon and/or its affiliates.
+ * Copyright (c) 2017, 2022, Gluon and/or its affiliates.
  * Copyright (c) 2012, 2014, Oracle and/or its affiliates.
  * All rights reserved. Use is subject to license terms.
  *
@@ -81,22 +81,34 @@ public class FXOMDocument {
 
     private List<Class<?>> initialDeclaredClasses;
 
+    /**
+     * Creates a new {@link FXOMDocument} from given FXML source. Depending on the
+     * use case, the {@link FXOMDocumentSwitch} items can be used to configure the
+     * document creation process according to specific needs.
+     * 
+     * @param fxmlText    FXML source
+     * @param location    {@link URL} describing the actual document location
+     * @param classLoader {@link ClassLoader} to be used
+     * @param resources   {@link ResourceBundle} to be used
+     * @param switches    {@link FXOMDocumentSwitch} configuration options to enable
+     *                    or disable certain steps in {@link FXOMDocument} creation
+     *                    (e.g. disabling normalization)
+     * @throws IOException when the fxmlText cannot be loaded
+     */
     public FXOMDocument(String fxmlText, URL location, ClassLoader classLoader, ResourceBundle resources, FXOMDocumentSwitch... switches) throws IOException {
         this.glue = new GlueDocument(fxmlText);
         this.location = location;
         this.classLoader = classLoader;
         this.resources = resources;
         initialDeclaredClasses = new ArrayList<>();
         if (this.glue.getRootElement() != null) {
-
             String fxmlTextToLoad = fxmlText;
             if (!Set.of(switches).contains(FXOMDocumentSwitch.FOR_PREVIEW)) {
                 final FXMLPropertiesDisabler fxmlPropertiesDisabler = new FXMLPropertiesDisabler();
-                fxmlTextToLoad = fxmlPropertiesDisabler.disableUseSystemMenuBarProperty(fxmlText);
+                fxmlTextToLoad = fxmlPropertiesDisabler.disableProperties(fxmlText);
             }
             final FXOMLoader loader = new FXOMLoader(this);
             loader.load(fxmlTextToLoad);
-
             if (!Set.of(switches).contains(FXOMDocumentSwitch.NON_NORMALIZED)) {
                 final FXOMNormalizer normalizer = new FXOMNormalizer(this);
                 normalizer.normalize();
@@ -446,8 +458,24 @@ public static interface SceneGraphHolder {
         public void fxomDocumentDidRefreshSceneGraph(FXOMDocument fxomDocument);
     }
 
+    /**
+     * Depending on where the {@link FXOMDocument} shall be used, 
+     * it is necessary to configure the {@link FXOMDocument} creation process.
+     * The switches here can be used to configure the creation process in the desired way.
+     * This enum replaces the previously used boolean arguments in the {@link FXOMDocument} constructor.
+     */
     public enum FXOMDocumentSwitch {
+        /**
+         * If this switch is defined, the {@link FXOMDocument} will not be normalized (see {@link FXOMNormalizer}).
+         */
         NON_NORMALIZED,
+
+        /**
+         * When this flag is present during {@link FXOMDocument} creation,
+         * the {@link FXMLPropertiesDisabler} will be used to prepare the FXML source in a way, 
+         * so that settings defined in the FXML will not interfere Scene Builders configuration.
+         * One possible example here is the option to use the MacOS system menu bar.  
+         */
         FOR_PREVIEW;
     }
 }

kit/src/main/java/com/oracle/javafx/scenebuilder/kit/fxom/FXOMLoader.java

@@ -287,7 +287,7 @@ public void readPropertyAttribute(String name, Class<?> staticClass, String fxml
         } else if (currentTransientNode instanceof TransientProperty) {
             final TransientProperty transientProperty = (TransientProperty) currentTransientNode;
             transientProperty.getCollectedProperties().add(fxomProperty);
-        } else if(currentTransientNode instanceof TransientIntrinsic) {
+        } else if (currentTransientNode instanceof TransientIntrinsic) {
             final TransientIntrinsic transientIntrinsic = (TransientIntrinsic) currentTransientNode;
             transientIntrinsic.getProperties().add(fxomProperty);
         }

kit/src/test/java/com/oracle/javafx/scenebuilder/kit/fxom/FXMLPropertiesDisablerTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, Gluon and/or its affiliates.
+ * Copyright (c) 2022, Gluon and/or its affiliates.
  * All rights reserved. Use is subject to license terms.
  *
  * This file is available and licensed under the following license:
@@ -47,7 +47,7 @@ public void that_property_value_is_set_to_false() throws Exception {
         String fxmlText = readResourceText("ContainerWithMenu_SystemMenuBarEnabled.fxml");
         assertTrue("ensures that test resource is correct",
                 fxmlText.contains("<MenuBar useSystemMenuBar=\"true\" VBox.vgrow=\"NEVER\" fx:id=\"theMenuBar\">"));
-        String modfiedFxmlText = classUnderTest.disableUseSystemMenuBarProperty(fxmlText);
+        String modfiedFxmlText = classUnderTest.disableProperties(fxmlText);
         assertTrue(modfiedFxmlText.contains("<MenuBar useSystemMenuBar=\"false\" VBox.vgrow=\"NEVER\" fx:id=\"theMenuBar\">"));
     }