# GetFrameworkElementByName

## Introduction

`GetFrameworkElementByName` is a generic method which returns an instance of a framework element with the matching name. This method can be used if your project does not use generated code, or if the controls with in a `GraphicalUiElement` are dynamically created.

`GetFrameworkElementByName` is an extension method so it requires the following using statement:

```csharp
using MonoGameGum.Forms;
```

`GetFrameworkElementByName` searches recursively so it will return the first instance with a matching name even if that instance is nested within other components.

## Code Example - Getting a Button from a Screen

The following code shows how to get a Button instance from a screen which is loaded from a Gum project.

```csharp
// Initialize
var project = GumUI.Initialize(this, "GumProject/GumProject.gumx");

var screen = project.Screens.Find(item => item.Name == "MainMenu");
var screenRuntime = screen.ToGraphicalUiElement();
screenRuntime.AddToRoot();

var button = screenRuntime.GetFrameworkElementByName<Controls.Button>("PlayButton");
button.Click += (_, _) => System.Diagnostics.Debug.WriteLine("Play was clicked");
```

As mentioned above, Gum performs recursive searches for an item by name. If your project potentially includes multiple items with the same name, you can qualify the name of an object by including the name of its parents. For example, consider a situation where `PlayButton` is contained in a parent named `MenuContainer`.

<figure><img src="/files/YZLqZ84opOFsYYw4UFb9" alt=""><figcaption><p>PlayButton as a child of MenuContainer</p></figcaption></figure>

The button can be obtained by qualified name as shown in the following code block:

```csharp
// Initialize
var button = screenRuntime.GetFrameworkElementByName<Controls.Button>("MenuContainer.PlayButton");
button.Click += (_, _) => System.Diagnostics.Debug.WriteLine("Play was clicked");
```

## Exceptions

GetFrameworkElementByName throws informative exceptions if it encounters an error when trying to find a `FrameworkElement`. Exceptions occur in the following situations:

* No item is found with a matching name
* An item is found, but it is a visual that does not have a FrameworkElement associated with it
* An item is found but the type does not match the generic type

If your code expects that these items may not exist, you can call `TryGetFrameworkElementByName` instead, which returns `null` instead of throwing exceptions when encountering any of the problems above.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flatredball.com/gum/code/gum-code-reference/graphicaluielement/getframeworkelementbyname.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.