<cat>Dev.UI</cat> <title>VGUI Creating Custom Elements</title> # Why Create Custom VGUI Elements? Creating custom VGUI elements helps with many things, the biggest being code readability and maintainability. These new elements don't always have to be some brand new element from the ground up, in fact many custom elements are just derivatives from the games base panels with customizations that fit that project better. Think of something like a <page>DButton</page> the default styling may not suit the look and feel of your project, so instead of having to restyle every <page>DButton</page> you create, you can create a new custom VGUI element that is derived from the standard <page>DButton</page>. Then apply your styling to that the new element once. This means that each time you create this new custom element you wont need to reapply the same styling, you'll only need to add what makes that button unique. Now you _could_ create panels in the same file you want to use them with <page>vgui.CreateFromTable</page> however using this method to create panels usually leads to a very long file that becomes hard to read and maintain once your no longer activity working on it. Therefor while acceptable under specific circumstances this shouldn't be the main way of creating your custom elements. # Creating Custom Elements The first and most fundamental thing you should know about any <page>Panel</page> is that it consists of four fundamental components: - The Table - The <page>PANEL:Init</page> Function - The <page>PANEL:Paint</page> Function - the <page>vgui.Register</page> Function There are other hooks available like the <page>PANEL:Think</page> hook, but this is not required the panel to operate. Also some hooks are only available to specific panels, and for the sake of simplicity we will skip over those here and just point you to <page>PANEL_Hooks</page> to see all the hooks available to panels. ## Setting up your workspace Hopefully you have a basic understanding of the filesystem in Garry's Mod but as a crash course, all you need to know is that everything included in your addon folder gets """merged""" with the existing folder structure in your copy of the game. Now these don't actually move any files around, but its important to remember that the engine sees your `*myAddonName*/lua/autorun/client/example.lua` in the same spot as: `*garrysmod*/lua/autorun/client/example.lua` I wanted to emphasis that because we will be leveraging that functionality to help organize our custom VGUI elements. Using the <page>Lua Folder Structure</page> we can see that there is `lua/vgui` this folder is loaded whenever the game loads its VGUI elements. This means any custom VGUI elements we create for out addon will be loaded automatically when we enter the game instead of needing to manually include them in our autorun script. ## Coding the new Element Now that you understand the basics of how panels work, we can start writing out own. to start working on a new panel create a new file under `lua/vgui/{nameOfElement}.lua` and make sure to write in the four fundamental elements from before like so: ``` -- Creating the Table our panel will use PANEL = PANEL or {} --Creating our Init Function function PANEL:Init() end --Creating the Paint Function function PANEL:Paint() end --Registering our new VGUI element, giving it a name, the table to use, and if it derives methods from another element vgui.Register("NewElementName",PANEL,"OptionalNameOfPanelItsDerivedFrom") ``` Now that we the essential outline of our panel created lets start by seeing if one of the premade elements from <page>VGUI Element List</page> has similar functionality to what we already need. Its important to look at the methods these panels already have, for example we are going to create a custom button. So we should derive our new panel from the `DButton` panel since that will give us access to methods like `PANEL:DoClick`. Lets do that now by updating our <page>vgui.Register</page> function in our code ``` vgui.Register("WikiButton",PANEL,"DButton") ``` ### So what exactly did that do? All the premade panels in Garry's Mod are derived from one of the engine panels, these engine panels can be found on the <page>VGUI Element List</page> page. Most of the Panels that start with a "D" are derivatives of these engine panels with functionality and <page>PANEL:Paint</page> functions applied to them to be easier to work with. ⤶ Most of the time you will never need to derive directly from an engine panel unless your creating a whole new type of element from scratch. Instead its commonly easier to derive your panel from one the "D" Panels which gives you access to more convivence functions instead of needing to recode basic functionalities into your panel every time. ⤶ When we set our new `WikiButton` element to derive from the `DButton` we get every method that `DButton` has access to and everything that it also derives from. Here is a tree that shows the chain of derivatives: ⤶ ```⤶ > All the premade panels in Garry's Mod are derived from one of the engine panels, these engine panels can be found on the <page>VGUI Element List</page> page. Most of the Panels that start with a "D" are derivatives of these engine panels with functionality and <page>PANEL:Paint</page> functions applied to them to be easier to work with. ⤶ > Most of the time you will never need to derive directly from an engine panel unless your creating a whole new type of element from scratch. Instead its commonly easier to derive your panel from one the "D" Panels which gives you access to more convivence functions instead of needing to recode basic functionalities into your panel every time. ⤶ > When we set our new `WikiButton` element to derive from the `DButton` we get every method that `DButton` has access to and everything that it also derives from. Here is a tree that shows the chain of derivatives: ```⤶ Panel - Label - DLabel - DButton - WikiButton <-- this being our custom element⤶ ```⤶ ⤶ # Using your Custom VGUI Component ⤶ Using the components you've created is the same as using any other premade element (seeing as we just created an element in the same way)⤶ ⤶ all you need is the <page>vgui.Create</page> function with the name you gave the <page>vgui.Register</page> function.⤶ for our `WikiButton` our create function would look like:⤶ ``` ⤶ ⤶ ⤶ ⤶ ⤶ #Uploading Images⤶ ⤶ I can drag and drop images and videos here to upload them.⤶ ⤶ #Links⤶ ⤶ I can link to [external pages](http://www.google.com) and <page>Internal Pages</page>VarName = vgui.Create("WikiButton") ```⤶ ⤶ <note>This page did not cover anything about customizing this new panel we created. This page was created to be more informative about the process of creating custom VGUI elements instead of customizing them. The wiki button mentioned in this article will look identical to a `DButton` because nothing in this article covered changing anything about it (yet?) </note>⤶