Editing WoW:Creating GUI configuration options (section)

=== config frame .xml ===

==== Basic Frame with Backdrop ====

Let's flesh out a basic config frame:

'''myClockConfigFrame.xml'''
  <Ui ...>
  <Script file="myClockConfigFrame.lua"/>
  <Frame name="myClockConfigFrame" 
     toplevel="true" parent="UIParent" frameStrata="DIALOG" 
     hidden="true" enableMouse="true">
 	<Size><AbsDimension x="260" y="280"/></Size>
 	<Anchors><Anchor point="CENTER"/></Anchors>
 	<!-- A nice backdrop -->
 	<Backdrop bgFile="Interface\DialogFrame\UI-DialogBox-Background" 
 		edgeFile="Interface\DialogFrame\UI-DialogBox-Border" tile="true">
 		<BackgroundInsets>
 			<AbsInset left="11" right="12" top="12" bottom="11"/>
 		</BackgroundInsets>
 		<TileSize><AbsValue val="32"/></TileSize>
 		<EdgeSize><AbsValue val="32"/></EdgeSize>
 	</Backdrop>
  </Frame>
  </Ui>

We now have a config frame, and if you go in-game you can see it in all it's splendor.  Feel free to make it any size, and the ANCHOR point="CENTER" will make sure it is dead center on the screen no matter the resolution.

You'll probably want some kind of title on it to say what mod's options it is, so here's some Layers info to do that:

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Backdrop ...>
 	 	...
 	</Backdrop>
 	<Layers>
 		<Layer level="ARTWORK">
 			<Texture file="Interface\DialogFrame\UI-DialogBox-Header">
 				<Size><AbsDimension x="256" y="64"/></Size>
 				<Anchors>
 					<Anchor point="TOP">
 					<Offset><AbsDimension x="0" y="12"/></Offset>
 					</Anchor>
 				</Anchors>
 			</Texture>
 		</Layer>
 		<Layer level="OVERLAY">
 			<FontString inherits="GameFontNormal" text="Clock Config">
 				<Anchors>
 					<Anchor point="TOP" relativeTo="$parent"></Anchor>
 				</Anchors>
 			</FontString>
 		</Layer>
 	</Layers>
  </Frame>
  ...

==== Adding Close and Default Buttons ====

That should make a small title box appear, and you'll notice the FontString's text attribute is set to "Clock Config" -- you can change this to anything you want.  If you're doing [[localization (ui)]], maybe even a constant!  You might notice that once you display your config frame, there's no way to get rid of it!  Let's fix that right away by adding a `Close' button:

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Frames>
 		...
 		<Button name="$parentButtonClose" inherits="OptionsButtonTemplate" text="Close">
 			<Anchors>
 				<Anchor point="BOTTOMRIGHT">
 				<Offset><AbsDimension x="-12" y="16"/></Offset>
 				</Anchor>
 			</Anchors>
 			<Scripts>
 				<OnClick> myClockConfigFrame:Hide(); </OnClick>
 			</Scripts>
 		</Button>
 		...
 	</Frames>
  	...
  </Frame ...>
  ...

This button, which you'll notice is anchored at the bottom right of the config frame, simply tells our configuration frame to hide.

While we're at it, let's add a defaults button in the bottom left of the frame.

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Frames>
 		...
 		<Button name="$parentButtonToDefault" inherits="OptionsButtonTemplate" text="Defaults">
 			<Anchors>
 				<Anchor point="BOTTOMLEFT">
 				<Offset><AbsDimension x="13" y="16"/></Offset>
 				</Anchor>
 			</Anchors>
 			<Scripts>
 				<OnClick> grokClock_ConfigToDefault(); </OnClick>
 			</Scripts>
 		</Button>
  		...
  	</Frames>
  	...
  </Frame ...>
  ...

You'll notice all we really had to do here was call our ConfigToDefault function we made in 'myClockIndicatorFrame.lua' -- it will take care of updating our addon for us!  Now we should be able to undo any damage should we mess around with our mod's config settings.

==== Checkboxes and Sliders ====

With most of the graphical frame stuff out of the way, it's time to add our checkboxes, and a slider for the offset (Dropdown menus are a lot more complicated, so this HOWTO won't be covering that).

Your basic checkbox config will look like:

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Frames>
 		...
 		<CheckButton name="$parentCheckButtonOn" inherits="OptionsCheckButtonTemplate">
 			<Anchors>
 				<Anchor point="TOPLEFT" relativeTo="$parent">
 				<Offset><AbsDimension x="20" y="-30"/></Offset>
 				</Anchor>
 			</Anchors>
 			<Scripts>
 				<OnLoad> getglobal(this:GetName().."Text"):SetText("On"); </OnLoad>
 				<OnClick> myClockConfigFrameOption_OnClick(); </OnClick>
 			</Scripts>
 		</CheckButton>
 		...
 	</Frames>
  	...
  </Frame ...>
  ...

You'll notice I'm using the '$parent' and 'this' variables here to make this code generic, able to be used anywhere.  If this was the 2nd checkbox, my Anchor relativeTo would be '$parentCheckButtonOn', and so forth, so that each item in the config dialog was just a bit bellow the others.  Of course you could use absolute positioning by just getting rid of the 'relativeTo' altogether.

You should also see that the CheckButton has a OnLoad to set its text, since this will be an automatically created FontString.  Again I use 'this:GetName().."Text"' to make this code generic.  I've set the text to "On" in this case, but you can change this to whatever you want, even a [[localized (ui)]] variable!

The OnClick simply loads a lua function, but it is important to note that we will use this function for '''ALL''' our CheckButtons.  That's right, we can use the same function for all our CheckButton's!

In our case we'll need to repeat this CheckButton xml code twice, once for 'on' and again for 'time24'.  So go ahead and try to create another checkbox.  Watch out for the offset!  Look at the slider example bellow for how the offset should look after the 1rst item.

Here's what our slider code might look like:

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Frames>
 		...
 		<Slider name="$parentSliderOffset" inherits="OptionsSliderTemplate">
 			<Size>
 				<AbsDimension x="220" y="16"/>
 			</Size>
 			<Anchors>
 				<Anchor point="TOPLEFT" relativeTo="$parentCheckButtonTime24">
 			<Offset><AbsDimension x="0" y="-40"/></Offset>
 			</Anchor>
 			</Anchors>
 			<Scripts>
 				<OnLoad>
 					getglobal(this:GetName().."Text"):SetText("Offset");
 					getglobal(this:GetName().."High"):SetText("12");
 					getglobal(this:GetName().."Low"):SetText("-12");
 					this:SetMinMaxValues(-12,12);
 					this:SetValueStep(1);
 				</OnLoad>
 				<OnValueChanged> grokClockConfigFrameOption_OnClick();  </OnValueChanged>
 			</Scripts>
 		</Slider>
  		...
 	</Frames>
  	...
  </Frame>
  ...

You'll again notice that we're using the Anchor relativeTo on the last checkbox, which will be $parentCheckButtonTime24.  We're again dynamically getting the FontStrings that WoW will create for us, like the 'Text' one set to "Offset".  As well, because this is a slider, we have "High" and "Low" FontStrings, have to set the minimum and maximum values the slider has, and how many values are added or subtracted when you move the slider.  What will most surprise you is that.. yes... we can still use that option function for our slider too!  One function for all the basic config options!

==== Frame Scripts ====

It's also important that all our current settings are loaded into our config frame, and since they might change when we use a slash command or something, the best way would be to use a OnShow event.

'''within myClockConfigFrame.xml'''
  ...
  <Frame ...>
 	...
 	<Scripts>
 	 	<OnShow> myClockConfigFrame_OnShow(); </OnShow>
 	</Scripts>
 	...
  </Frame>
  ...