Lots of refactoring docs

vchelaru · vchelaru · commit 023b70343056 · 2025-03-17T17:16:26.000-06:00
diff --git a/docs/code/gum-code-reference/component-runtimes.md b/docs/code/gum-code-reference/component-runtimes.md
@@ -15,8 +15,10 @@ Once you have instantiated your project, you can create a component as shown in
 
 ```csharp
 // This assumes that your project has at least 1 component
-ObjectFinder.Self.GumProjectSave.Components.First()
-    .ToGraphicalUiElement(SystemManagers.Default, addToManagers:true);
+var componentRuntime = ObjectFinder.Self.GumProjectSave.Components.First()
+    .ToGraphicalUiElement();
+
+// Add this component to the desired container
 ```
 
 The Components property contains a list of all components, so you can also access components by name or other property. For example, the First method can be used to find a component by name as shown in the following code:
@@ -25,8 +27,8 @@ The Components property contains a list of all components, so you can also acces
 var componentSave = ObjectFinder.Self.GumProjectSave.Components
     .First(item => item.Name == "ColoredRectangleComponent");
 
-var componentRuntime = componentSave.ToGraphicalUiElement(SystemManagers.Default, addToManagers: true);
-// the componentRuntime can be modified here
+var componentRuntime = componentSave.ToGraphicalUiElement();
+// the componentRuntime can be modified here, and added to the desired container
 ```
 
 Note that the name passed to the First method should match the name given in Gum. For example, in this case the code searches for a component named ColoredRectangleComponent.
@@ -37,21 +39,6 @@ If a component is in a folder, then use the qualified name relative to the Compo
 
 <figure><img src="../../.gitbook/assets/image (42).png" alt=""><figcaption><p>StandardButton component in the Buttons folder in Gum</p></figcaption></figure>
 
-The ToGraphicalUiElement method can automatically add the component to the root for rendering, or alternatively it can be added to an existing container. If adding to an existing container, then the ToGraphicalUiElement's addToManagers parameter should be false as shown in the following code:
-
-```csharp
-var component = var componentSave = ObjectFinder.Self.GumProjectSave.Components
-    .First(item => item.Name == "MyComponent");
-    
-var componentRuntime = componentSave.ToGraphicalUiElement(
-    SystemManagers.Default, addToManagers: false);
-// This assumes that container has been directly added to managers, or is a 
-// child of a root container which has been added to managers:
-container.Children.Add(componentRuntime);
-```
-
-For more information about how to add a newly-created component runtime to managers or to a container, see the next section.
-
 ## Adding a Component Runtime to a Parent
 
 A newly-created component must be added directly or indirectly to managers. The following are the possible ways to add to managers:
@@ -62,8 +49,7 @@ The newly instantiated component can be added to a container in the screen. This
 
 ```csharp
 // do not add to managers, since it will be added to a container
-var newComponentRuntime = componentSave.ToGraphicalUiElement(
-    SystemManagers.Default, addToManagers:false);
+var newComponentRuntime = componentSave.ToGraphicalUiElement();
 // assuming ScreenRoot is a valid root
 var container = ScreenRoot.GetGraphicalUiElementByName("DesiredContainer");
 container.Children.Add(newComponentRuntime);
@@ -83,8 +69,7 @@ The following code shows how to create a Toast instance to display a message to
 
 ```csharp
 // assumes toastComponent is a valid component
-var newToastRuntime = toastComponent.ToGraphicalUiElement(
-    SystemManagers.Default, addToManagers:false);
+var newToastRuntime = toastComponent.ToGraphicalUiElement();
 FrameworkElement.PopupRoot.Children.Add(newToastRuntime);
 // the newToastRuntime needs to be removed from PopupRoot later
 ```
@@ -93,8 +78,7 @@ The following code shows how to create a MessageBox instance and add it to the M
 
 ```csharp
 // assumes toastComponent is a valid component
-var newMessageBoxRuntime = messageBoxComponent.ToGraphicalUiElement(
-    SystemManagers.Default, addToManagers:false);
+var newMessageBoxRuntime = messageBoxComponent.ToGraphicalUiElement();
 FrameworkElement.ModalRoot.Children.Add(newMessageBoxRuntime);
 // the newMessageBoxRuntime needs to be removed from ModalRoot later
 ```
@@ -105,23 +89,23 @@ To destroy the component, remove it from its parent, or set its parent to null:
 newMessageBoxRuntime.Parent = null;
 ```
 
-### Adding to Managers
+### Adding to GumService Root
 
-Components can be added directly to managers. Usually items are only added directly to managers in the following situations:
+Components can be added directly to the GumService Root. Usually items are only added directly to GumService Root in the following situations:
 
-* If they are the root runtime. Usually this is a Screen, but it can be a component if your project is not using screens.
+* If they are a Screen, or will not be contained by any other object, such as if your project is not using screens.
 * For testing/debugging.
 * If your game has multiple roots, you can add instances to a list of GraphicalUiElements which are passed to Update. This is considered an advanced scenario.
 
 ```csharp
-var newComponentRuntime = componentSave.ToGraphicalUiElement(
-    SystemManagers.Default, addToManagers:true);
+var newComponentRuntime = componentSave.ToGraphicalUiElement();
+newComponentRuntime.AddToRoot();
 ```
 
-To destroy the component, call RemoveFromManagers:
+To destroy the component, call RemoveFromRoot:
 
 ```csharp
-newComponentRuntime.RemoveFromManagers();
+newComponentRuntime.RemoveFromRoot();
 ```
 
 ## Troubleshooting Component Creation
diff --git a/docs/code/gum-code-reference/elementsave/tographicaluielement.md b/docs/code/gum-code-reference/elementsave/tographicaluielement.md
@@ -4,7 +4,7 @@
 
 ToGraphicalUiElement creates a new GraphicalUiElement (visual Gum object) from the calling ElementSave. This method is typically used to create new Screen or Component instances from a Gum project.
 
-The conversion of a GraphicalUiElement can optionally add the resulting GraphicalUiElement to managers. This value should be true if the object is not going to be added as a child of any other GraphicalUiElement.
+The conversion of a GraphicalUiElement can optionally add the resulting GraphicalUiElement to manager, but this is considered an advance approach. Almost all cases should use the no-argument version of ToGraphicalUiElement.
 
 ## Code Example
 
@@ -15,40 +15,6 @@ The following code can be used to convert a Screen named "MainMenu" to a Graphic
 
 var screen = gumProject.Screens.Find(item => item.Name == "MainMenu");
 // Calling GraphicalUiElement creates the visuals for the screen
-var graphicalUiElement = screen.ToGraphicalUiElement(
-    RenderingLibrary.SystemManagers.Default, addToManagers: true);
+var graphicalUiElement = screen.ToGraphicalUiElement();
+graphicalUiElement.AddToRoot();
 ```
-
-### addToManagers Parameter
-
-The `addToManagers` parameter determined whether the GraphicalUiElement is automatically added to managers so that it is directly drawn. This can be called after the element is created, so the following code shows two ways of adding the element to managers:
-
-```csharp
-screen.ToGraphicalUiElement(
-    RenderingLibrary.SystemManagers.Default, addToManagers: true);
-// is the same as:
-var graphicalUiElement = screen.ToGraphicalUiElement(
-    RenderingLibrary.SystemManagers.Default, addToManagers: false);
-graphicalUiElement.AddToManagers();
-```
-
-All GraphicalUiElements need to either be added to managers directly or indirectly. Elements added directly to managers are drawn by `GumService.Default.Draw();` . Any item that is added to managers automatically draws its children, so only root-most objects should be added to managers.&#x20;
-
-Let's look at common scenarios and and discuss when to set `addToManagers` to true.
-
-#### Setting addToManagers to true
-
-Elements should have `addToManagers` set to `true` if any of the following are true:
-
-1. The GraphicalUiElement serves as the root for all other elements. Typically this would be when a Gum project is loaded, the Screen is obtained from the Gum project's `Screens` property and its `ToGraphicalUiElement` method is called.
-2. You are performing simple tests such as adding a Gum component to screen for testing, you may want to set addToManagers to true so that it shows up on screen. Note that if this is an object with events (such as a Gum Forms object), it must either be passed to the `GumService.Default.Update` call or it will not respond to the mouse, keyboard, or gamepads.
-
-The most common case for setting AddToManagers to true is if you are creating a Gum screen from a loaded Gum project.
-
-#### Setting addToManagers to false
-
-Elements should have `addToManagers` set to `false` if any of the following are true:
-
-1. If the GraphicalUiElement is being added as a child of another element which has already been added to managers. For example, if a new element is being created and added to an existing Screen or one of its children.
-2. If the GraphicalUiElement is being added as a child to existing _root_ containers, such as `FrameworkElement.PopupRoot` or `FrameworkElement.ModalRoot` .
-3. If the GraphicalUiElement is being added to managers on a dedicated layer. For example, a Screen could be created and added to a dedicated UI layer to control sorting of all elements in the Screen relative to other manually-created GraphicalUiElements.
diff --git a/docs/code/gum-code-reference/graphicaluielement/removefrommanagers.md b/docs/code/gum-code-reference/graphicaluielement/removefrommanagers.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-RemoveFromManagers removes the calling GraphicalUiElement from the SystemManagers. This method should be called on GraphicalUiElements which need to be destroyed but do not have parents. To remove a GraphicalUiElement which has parents, remove it from its Parent's Children.
+RemoveFromManagers removes the calling GraphicalUiElement from the SystemManagers. This method is typically not called, and instead RemoveFromRoot should be called in most cases.
 
 ## Code Example
 
@@ -11,8 +11,10 @@ The following code shows how to add and remove a GraphicalUiElement.
 ```csharp
 // You can create a GrahicalUiElement from an ElementSave.
 // Assume elementSave is valid, such as a Screen obtained from a Gum project
-var graphicalUiElement = elementSave.ToGraphicalUiElement(
-    RenderingLibrary.SystemManagers.Default, addToManagers: true);
+var graphicalUiElement = elementSave.ToGraphicalUiElement();
+
+graphicalUiElement.AddToManagers();
+
 // alternatively, could pass addToManagers:false, and explicitly call
 // AddToManagers
 
diff --git a/docs/code/monogame/gum-forms/README.md b/docs/code/monogame/gum-forms/README.md
@@ -125,12 +125,7 @@ Your project is now referenced in your game. Modify the Game file to initialize
 public class Game1 : Game
 {
     private GraphicsDeviceManager _graphics;
-
-    // Gum renders and updates using a hierarchy. At least
-    // one object must have its AddToManagers method called.
-    // If not loading from-file, then the easiest way to do this
-    // is to create a ContainerRuntime and add it to the managers.
-    GraphicalUiElement Root;
+    GumService Gum => GumService.Default;
 
     public Game1()
     {
@@ -141,28 +136,28 @@ public class Game1 : Game
 
     protected override void Initialize()
     {
-        var gumProject = MonoGameGum.GumService.Default.Initialize(
+        var gumProject = Gum.Initialize(
             this,
             // This is relative to Content:
             "GumProject/GumProject.gumx");
 
         // This assumes that your project has at least 1 screen
-        Root = gumProject.Screens.First().ToGraphicalUiElement(
-            SystemManagers.Default, addToManagers: true);
+        var screen = gumProject.Screens.First().ToGraphicalUiElement();
+        screen.AddToRoot();
 
         base.Initialize();
     }
 
     protected override void Update(GameTime gameTime)
     {
-        MonoGameGum.GumService.Default.Update(this, gameTime, Root);
+        Gum.Update(this, gameTime);
         base.Update(gameTime);
     }
 
     protected override void Draw(GameTime gameTime)
     {
         GraphicsDevice.Clear(Color.CornflowerBlue);
-        MonoGameGum.GumService.Default.Draw();
+        Gum.Draw();
         base.Draw(gameTime);
     }
 }
diff --git a/docs/code/monogame/gum-forms/controls/frameworkelement/modalroot-and-popuproot.md b/docs/code/monogame/gum-forms/controls/frameworkelement/modalroot-and-popuproot.md
@@ -4,7 +4,7 @@
 
 The static ModalRoot and PopupRoot properties provide an InteractiveGue which serve as the root for any element which should appear on top of other elements. These properties have the following characteristics:
 
-* Automatically created by `FormsUtilities.InitializeDefaults`
+* Automatically created by `Gum.Initialize`
 * Automatically resized to fit the entire screen, including if the `GraphicalUiElement.CanvasHeight` and `GraphicalUiElement.CanvasWidth` change.
 * Both Remains on top of all other elements for its given layer. ModalRoot appears on top of PopupRoot.
 
@@ -70,11 +70,8 @@ private void ShowPopup(string text, bool isModal)
 Popups can also be created if your game is loading a Gum project. Since the GraphicalUiElement will be added to either ModalRoot or PopupRoot, it should not also be added to managers.
 
 ```csharp
-// Don't add to managers because it will be contained in a container
-// which has already been added to managers
-bool addToManagers = false;
 var popupComponent = gumProject.Components.First(item => item.Name == "MyPopup")
-    .ToGraphicalUiElement(SystemManagers.Default, addToManagers);
+    .ToGraphicalUiElement();
 
 popupComponent.Parent = FrameworkElement.ModalRoot;
 
@@ -86,16 +83,11 @@ popupComponent.Parent = null;
 If you are going to add a Screen to a ModalRoot, then the Screen must have a renderable contained object so that it can have its Parent assigned. You can do this by creating a Screen runtime which inherits from ContainerBase, or you can optionally add an InvisibleRenderable as shown in the following code:
 
 ```csharp
-// Don't add to managers because it will be contained in a container
-// which has already been added to managers
-bool addToManagers = false;
 var popupScreen = gumProject.Screens.First(item => item.Name == "MyScreen")
-    .ToGraphicalUiElement(SystemManagers.Default, addToManagers);
-// Give the Screen a ContainedObject so that it can have its parent assigned
-popupScreen.SetContainedObject (new InvisibleRenderable());
+    .ToGraphicalUiElement();
 popupScreen.Parent = FrameworkElement.ModalRoot;
 
 // later, the popup can be removed:
 popupScreen.RemoveFromManagers();
 popupScreen.Parent = null;
-```
+```
diff --git a/docs/code/monogame/loading-.gumx-gum-project.md b/docs/code/monogame/loading-.gumx-gum-project.md
@@ -77,8 +77,7 @@ protected override void Initialize()
         "GumProject/GumProject.gumx");
 
     // This assumes that your project has at least 1 screen
-    var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement(
-        SystemManagers.Default, addToManagers:false);
+    var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
     screenRuntime.AddToRoot();
     
     base.Initialize();
@@ -96,7 +95,7 @@ Gum.Initialize(
 
 Once a Gum project is loaded, all of its screens and components can be accessed through the object returned from the Initialize method. The code above stores the project in a variable called `gumProject`. Any screen or component can be converted to a GraphicalUiElement, which is the visual object that displays in game.
 
-The code in the previous section creates a `GraphicalUiElement` from the first screen in the project. Note that the `ToGraphicalUiElement` method has an `addToManagers` parameter which determines whether the GraphicalUiElement is added to managers. This is almost always set to false since we add the created screen to the root container, which in turn has already been added to managers.
+The code in the previous section creates a `GraphicalUiElement` from the first screen in the project.
 
 For an example of a Game1.cs file which loads a project file, see the MonoGameGumFromFile: [https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/Game1.cs#L76-L82](https://github.com/vchelaru/Gum/blob/0e266942560e585359f019ac090a6c1010621c0b/Samples/MonoGameGumFromFile/MonoGameGumFromFile/Game1.cs#L76-L82)
 
@@ -106,9 +105,7 @@ You can get a reference to elements within the screen by calling `GetGraphicalUi
 
 ```csharp
 // Load the gum project (see code above)
-var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement(
-  SystemManagers.Default, 
-  addToManagers:false);
+var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
 screenRuntime.AddToRoot();
 
 // Items in the screen can be accessed using the GetGraphicalUiElementByName method:
@@ -141,8 +138,7 @@ public class Game1 : Game
         var gumProject = Gum.Initialize(
             this, "GumProject/GumProject.gumx");
         // This assumes that your project has at least 1 screen
-        var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement(
-            SystemManagers.Default, addToManagers: false);
+        var screenRuntime = gumProject.Screens.First().ToGraphicalUiElement();
         screenRuntime.AddToRoot();
 
         base.Initialize();
diff --git a/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/gum-forms.md b/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/gum-forms.md
@@ -45,8 +45,7 @@ public class Game1 : Game
             
         var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
         
-        var screenRuntime = screen.ToGraphicalUiElement(
-            RenderingLibrary.SystemManagers.Default, addToManagers: false);
+        var screenRuntime = screen.ToGraphicalUiElement();
         screenRuntime.AddToRoot();
         
         base.Initialize();
@@ -101,8 +100,7 @@ protected override void Initialize()
         
     var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
         
-    var screenRuntime = screen.ToGraphicalUiElement(
-        RenderingLibrary.SystemManagers.Default, addToManagers: false);
+    var screenRuntime = screen.ToGraphicalUiElement();
     screenRuntime.AddToRoot();
 
 +    var listBox = screenRuntime.GetFrameworkElementByName<ListBox>("ListBoxInstance");
diff --git a/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/gum-screens.md b/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/gum-screens.md
@@ -52,8 +52,7 @@ To show the screen in game, modify the Initialize method as shown in the followi
 <strong>+    // the Screens list contains all screens. Find the screen you want
 </strong>+    var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
 +    // Calling GraphicalUiElement creates the visuals for the screen
-<strong>+    var screenRuntime = screen.ToGraphicalUiElement(
-</strong><strong>+        RenderingLibrary.SystemManagers.Default, addToManagers: false);
+<strong>+    var screenRuntime = screen.ToGraphicalUiElement();
 </strong><strong>+    screenRuntime.AddToRoot();
 </strong>
     base.Initialize();
@@ -91,8 +90,7 @@ We can modify the displayed string by getting an instance of the Text and modify
         
     var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
         
-    var screenRuntime = screen.ToGraphicalUiElement(
-        RenderingLibrary.SystemManagers.Default, addToManagers: false);
+    var screenRuntime = screen.ToGraphicalUiElement();
         
     screenRuntime.AddToRoot();
 
@@ -120,8 +118,7 @@ protected override void Initialize()
         
     var screen = gumProject.Screens.Find(item => item.Name == "TitleScreen");
         
-    var screenRuntime = screen.ToGraphicalUiElement(
-        RenderingLibrary.SystemManagers.Default, addToManagers: false);
+    var screenRuntime = screen.ToGraphicalUiElement();
         
     screenRuntime.AddToRoot();
 
diff --git a/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/multiple-screens.md b/docs/code/monogame/tutorials/gum-project-.gumx-tutorial/multiple-screens.md
diff --git a/docs/gum-tool/code-tab/runtime-generation-details.md b/docs/gum-tool/code-tab/runtime-generation-details.md

Original file line number	Diff line number	Diff line change
`@@ -125,12 +125,7 @@ Your project is now referenced in your game. Modify the Game file to initialize`
`125`	`125`	`public class Game1 : Game`
`126`	`126`	`{`
`127`	`127`	`private GraphicsDeviceManager _graphics;`
`128`		`-`
`129`		`- // Gum renders and updates using a hierarchy. At least`
`130`		`- // one object must have its AddToManagers method called.`
`131`		`- // If not loading from-file, then the easiest way to do this`
`132`		`- // is to create a ContainerRuntime and add it to the managers.`
`133`		`- GraphicalUiElement Root;`
	`128`	`+ GumService Gum => GumService.Default;`
`134`	`129`
`135`	`130`	`public Game1()`
`136`	`131`	`{`
`@@ -141,28 +136,28 @@ public class Game1 : Game`
`141`	`136`
`142`	`137`	`protected override void Initialize()`
`143`	`138`	`{`
`144`		`- var gumProject = MonoGameGum.GumService.Default.Initialize(`
	`139`	`+ var gumProject = Gum.Initialize(`
`145`	`140`	`this,`
`146`	`141`	`// This is relative to Content:`
`147`	`142`	`"GumProject/GumProject.gumx");`
`148`	`143`
`149`	`144`	`// This assumes that your project has at least 1 screen`
`150`		`- Root = gumProject.Screens.First().ToGraphicalUiElement(`
`151`		`- SystemManagers.Default, addToManagers: true);`
	`145`	`+ var screen = gumProject.Screens.First().ToGraphicalUiElement();`
	`146`	`+ screen.AddToRoot();`
`152`	`147`
`153`	`148`	`base.Initialize();`
`154`	`149`	`}`
`155`	`150`
`156`	`151`	`protected override void Update(GameTime gameTime)`
`157`	`152`	`{`
`158`		`- MonoGameGum.GumService.Default.Update(this, gameTime, Root);`
	`153`	`+ Gum.Update(this, gameTime);`
`159`	`154`	`base.Update(gameTime);`
`160`	`155`	`}`
`161`	`156`
`162`	`157`	`protected override void Draw(GameTime gameTime)`
`163`	`158`	`{`
`164`	`159`	`GraphicsDevice.Clear(Color.CornflowerBlue);`
`165`		`- MonoGameGum.GumService.Default.Draw();`
	`160`	`+ Gum.Draw();`
`166`	`161`	`base.Draw(gameTime);`
`167`	`162`	`}`
`168`	`163`	`}`