# How to Add New Frames

When adding new features to the GUI, you'll likely either need to add new Widgets to existing Frames or you'll need to create and place whole new Frames. Adding a Widget to an existing Frame is fairly simple (just find the custom Frame's file, build and place the widget in the Frame's `__init__()` method, and add any new logic or callbacks necessary as private methods on the custom Frame class). In this article, we'll instead go over how to add an entirely new custom Frame to the GUI, which will be necessary when adding completely new features to the GUI. 

We'll use our custom `DecoderFrame` defined in `python/src/gui/frames/content_frames/decoder_frame.py` as an example, so inspect that file if you struggle through any of these steps.

## Implementing your custom `tk.Frame` class
To create your new Frame, we will create a new class that implements `tk.Frame`. To do this, create a new file for your Frame class in the `python/src/gui/frames/content_frames/` directory. Add these imports to the top of your file:
```python
import tkinter as tk
from tkinter import ttk
from gui.app import GUI
```
Next, define your class with an `__init__()` as shown below. This is copied from our custom `DecoderFrame` class. Make sure your `__init__()` has the same signature as the one shown. 
```python
class DecoderFrame(tk.Frame):

    # build the interface
    def __init__(self, master: tk.Frame, gui: GUI, **kwargs):
        super().__init__(master=master, **kwargs)
        self.gui = gui
```
Next, define any private instance variables your widgets will need. For example, a dropdown will require a `tk.StringVar` and a list of options that starts with a blank string, a checkbox will require a `tk.IntVar`, etc. Here are the variables that the `DecoderFrame` uses for its Decoder dropdown selector and its align checkbox:
```python
        self.decoder_selected = tk.StringVar()
        decoder_types = ['']
        decoder_types.extend([item.value for item in DecoderType])

        self.align = tk.IntVar()
```
You can see that the values of the dropdown are pulled directly from the `DecoderType` Enum values. Note that the currently selected enum value can be retrieved with `self.decoder_selected.get()`. Similarly, the value of the align checkbox can be retrieved with `self.align.get()`. 

Next, we add any validation functions if necessary. These are not used in `DecoderFrame`, but you can use these in your Frame if you must ensure that a text Entry box only allows ints or floats. See our `OutputSettingsFrame` for an example of how to use these. 
```python
        # register the validation for entry floats
        val_float = (self.register(self._validate_float), '%P')
        val_int = (self.register(self._validate_int), '%P')
```

Next, configure the layout grid for your Frame. This is not necessary unless you want specific rows or columns of your layout to have a specific padding. In the case of `DecoderFrame`, we add the line `self.grid_rowconfigure(1, pad=5)` to vertically pad the second row by 5 pixels. Note that all our Frames use Tk's grid layout. More info on this layout type can be found online. We use the grid layout because it is the most customizable layout; however, this does make the layout code a bit more verbose. 

Finally, we can begin adding Widgets to your Frame. This typically starts with a Title Label, as shown before for the `DecoderFrame`. Note that we must (1) create the Widget and then (2) add it to the grid layout. The first argument of all the Widget constructors is the parent Frame, which is `self` in this case. Also note that the we are using the GUI's predefined `label_style_bold` as the style and the GUI's predefined `sizes.DECODER_TITLE_WIDTH` as the width of the label. Please see Tk's or Tkinter's online documentation on how to use the grid layout and the `grid` function. 
```python
        self.title_label = tk.Label(self, text='Decoders', **gui.label_style_bold, width=gui.sizes.DECODER_TITLE_WIDTH)
        self.title_label.grid(row=0, column=0, sticky='w', padx=(0, 5))
```

Continue adding all your widgets using whichever code organization you like. Depending on the Frame, I like to organize the code by either rows or columns. See the rest of `DecoderFrame.__init__()` and any of our other predefined Frames for examples of how to create other Widgets such as `Entry`, `OptionMenu`, `Button`, and `Checkbutton`. You can define callbacks either as lambda functions or as private methods on your custom `Frame` class.

After adding all your widgets inside `__init__()`, the last thing to do is add any right click menus or tooltips. To add right click menus, use `self.gui.build_right_click_menu()` and to add a tooltip use `self.gui.tooltip.bind()`. See `DecoderFrame` for examples on their usage. 

Now we are done with your Frame's layout and the `__init__()` method! There are still a few last things to implement in your custom `Frame` class though. 

Firstly, implement any custom private methods you need for logic or callbacks. 

And lastly, implement the `update_ui(self, kwargs)` method. This method gets called whenever the GUI has new data from the Backend to update all its Frames with. The `kwargs` argument in this case is a dict whose keys are either custom strings or names of the `UpdateType` Enum. Use these keys to access any data from the Backend you need to update your custom Frame. Note that this data comes from the `Backend.get()` method, so if you aren't getting all the data you need, you'll need to edit that Backend method to add that data to the returned `dict`. And for your assistance, `DecoderFrame` has a few good examples of ways to update your Frame in its `update_ui()` method. 

Now you are done implementing your custom Frame! Let's continue

## Adding your custom `tk.Frame` to the GUI
Now that you've implemented your custom Frame, let's go back to `python/src/gui/app.py` to add your new Frame to the main GUI window. 

Firstly, import your custom Frame at the BOTTOM of `python/src/gui/app.py`. This is to make sure Python linters still work. 

Secondly, inside `GUI._build_ui()` initialize your Frame object and place in the GUI using the grid layout. Note that most of the content Frames in the GUI are placed inside the main tabbed window of the GUI, which corresponds to the `self.tabbed_content` variable. To add a new tab, create a Frame whose parent is `self.tabbed_content` and add that Frame to the tabbed window. The order the Frames are added to the tabbed Notebook is the order of the displayed tabs. Here's some example code of just that:
```python
        self.raw_processing_tab_frame = tk.Frame(self.tabbed_content, **self.frame_style)
        
        self.tabbed_content.add(self.raw_processing_tab_frame, text="Raw Processing")
```
You can use that dummy Frame (`self.raw_processing_tab_frame` in this case), as the parent Frame for your custom Frame when you initialize it at the bottom of `GUI._build_ui()`. Just follow the existing code layout inside `GUI._build_ui()` and you should be fine. 

Finally, inside `GUI.update_ui_callback(self, kwargs)`, call your new Frame's `update_ui()` method as we already do for all the existing Frames. 

Now if you've done everything correctly, your new Frame should show up in the GUI!

## Sending Backend Commands
The last step you might need to complete to get your new Frame working is to add any necessary methods to the GUI class to send commands to Backend. To send a command to the Backend, use the `GUI._send_command()`. We typically do this from within GUI methods - not from within methods in your custom Frame class. See the [[GUI]] overview article to get more info on commonly used GUI methods.