Editing WoW:Creating GUI configuration options (section)

== Load config from SavedVariables ==
: '''Reference Material''' (optional reading) : [[Saving variables between game sessions]]
Using the SavedVariable 'myClockConfig' we declared in the .toc file, we can now load and save our addon's configuration between game sessions.  Remember that SavedVariable is per-account, not per-realm and not per-character, so we will need to use tables to store individual settings.

=== Main frame: .xml ===
We will be modifying the main addon frame, in this case 'myClockIndicatorFrame.xml' which is used to display the current time.

We need to:
* Add a OnLoad Script action
* Add a OnEvent Script action

The OnLoad is needed to start watching the 'VARIABLES_LOADED' event (when myClockConfig will have its saved values set).  Next, we use OnEvent to actually do something when the event fires.

'''myClockIndicatorFrame.xml'''
  <Ui ...>
  <Frame name="myClockIndicatorFrame" ...>
  ...
  <Scripts>
    <OnLoad> myClockIndicatorFrame_OnLoad(); </OnLoad>
    <OnEvent> myClockIndicatorFrame_OnEvent(); </OnEvent>
    ...
  </Scripts>
  </Frame>
  </Ui>

=== Main frame: .lua ===

==== Globals ====

We need to:
* Get the Realm and Character names for later
* Ensure SavedVariable 'myClockConfig' exists
* Create addon details for myAddOns
* Create default config settings

'''myClockIndicatorFrame.lua'''
  ...
  -- Globals
    -- so we know when our configuration is loaded
  myClock_variablesLoaded = false;
    -- for configuration saving
  myClockRealm = GetCVar("realmName");
  myClockChar = UnitName("player");
    -- details used by myAddOns
  myClock_details = {
 	name = "myClock",
 	frame = "myClockIndicatorFrame",
 	optionsframe = "myClockConfigFrame"
  };
    -- default config settings
  local myClockConfig_defaultOn = true;		-- addon enabled?
  local myClockConfig_defaultTime24 = true; 	-- 24 hour format?
  local myClockConfig_defaultOffset = 0; 	-- time offset?
  ...

;myClock_variablesLoaded, myClock_realm, myClock_char : These are needed to create a table of settings, per-realm, per-character.  By default a SavedVariable is only per-account.  This way changing configuration options on one character does not change them for all your characters!
;myClock_details : [[myAddOns]] will display information about your AddOn, and needs the name of your main and config frames to display the configuration dialog properly.
; myClockConfig_default : Each of these variables is a default setting for a configuration option the user will be able to change in our config dialog.  They are also used the first time a character uses our addon, as they have no saved settings yet.

==== Registering Events ====
Since we will use the VARIABLES_LOADED event to know when it is safe to use our SavedVariable,

We need to:
* Register the VARIABLES_LOADED event
* Call a function when the event fires

'''myClockIndicatorFrame.lua: anywhere inside'''
  ...
  -- OnLoad
  function myClockIndicatorFrame_OnLoad()
 	-- register events
 	this:RegisterEvent("VARIABLES_LOADED"); -- eventually will call OnEvent
        ...
  end
  ...

'''myClockIndicatorFrame.lua: anywhere inside'''
  ...
  -- OnEvent
  function myClockIndicatorFrame_OnEvent()
 	-- VARIABLES_LOADED event
 	if ( event == "VARIABLES_LOADED" ) then
 		-- execute event code in this function
 		myClockIndicatorFrame_VARIABLES_LOADED();
 	end
  end
  ...

==== Custom Update Functions ====

We now have a function that will be called when our variables are loaded.

It will need to:
* load default SavedVariable values
* register addon with [[myAddOns]]
* record that configuration was loaded

'''within myClockIndicatorFrame.lua'''
  ...
  function myClockIndicatorFrame_VARIABLES_LOADED()
 	-- initialize our SavedVariable
 	if ( not myClockConfig ) then 
 	 	myClockConfig = {}; 
 	end
 	if ( not myClockConfig[myClockRealm] ) then 
 	 	myClockConfig[myClockRealm] = {}; 
 	end
 	if ( not myClockConfig[myClockRealm][myClockChar] ) then 
 	 	myClockConfig[myClockRealm][myClockChar] = {}; 
 	end
 	-- load each option, set default if not there
 	if ( not myClockConfig[myClockRealm][myClockChar].on ) then 
 		myClockConfig[myClockRealm][myClockChar].on = myClockConfig_defaultOn; 
 	end
 	if ( not myClockConfig[myClockRealm][myClockChar].time24 ) then 
 		myClockConfig[myClockRealm][myClockChar].time24 = myClockConfig_defaultTime24; 
 	end
 	if ( not myClockConfig[myClockRealm].offset ) then 
 		myClockConfig[myClockRealm].offset = myClockConfig_defaultOffset; 
 	end
 	-- record that we have been loaded
 	myClock_variablesLoaded = true;
 	-- we know other addons have been "loaded" now
 	   -- optional dependance on myAddOns, leads to our config panel
 	if( myAddOnsFrame_Register ) then
 		myAddOnsFrame_Register( myClock_details );
 	end
 	-- configuration might have changed
 	myClock_ConfigChange();
  end
  ...

So this function is very simple, it created a new table for storing our configuration on a addon-wide, realm-wide and character basis, then checked for every config option and made sure it was loaded, if not then set it to the default.  We added myAddons support, telling myAddons what our mod's name, main frame, and config frame was using a table declared in our globals.  

The last line is interesting, we make a call to myClock_ConfigChange().  This is the function that will actually change our mod based on our settings.  In the case of a clock most of those options ('time24', 'offset') are actually in OnUpdate, but we would handle the 'on' in this function.

Our config change should:
* Turn the mod on and off

'''within myClockIndicatorFrame.lua'''
  ...
  function myClock_ConfigChange()
 	-- make sure that our profile has been loaded before allowing this function to be called
 	if ( not myClock_variablesLoaded ) then -- config not loaded
 		myClockIndicatorFrame:Hide(); -- turn our mod off
 		return;
 	end
 	-- make sure to use the frame's name here, cannot rely on 'this' to mean the main frame
 	if ( myClockConfig[myClockRealm][myClockChar].on ) then
 		myClockIndicatorFrame:Show(); -- show our mod frame
 	else
 		myClockIndicatorFrame:Hide(); -- hide our mod frame
 	end
  end
  ...

It can also be useful to have a function to set everything back to defaults... here is one you might use in this case

'''within myClockIndicatorFrame.lua'''
  ...
  -- reset to defaults
  function grokClock_ConfigToDefault()
 	-- make sure that our profile has been loaded before allowing this function to be called
 	if ( not myClock_variablesLoaded  ) then -- config not loaded
 		myClockIndicatorFrame:Hide(); -- turn our mod off
 		return;
 	end
 	-- set our profile to defaults
 	myClockConfig[myClockRealm][myClockChar].on = myClockConfig_defaultOn;
 	myClockConfig[myClockRealm][myClockChar].time24 = myClockConfig_defaultTime24;
 	myClockConfig[myClockRealm][myClockChar].offset = myClockConfig_defaultOffset;
 	-- frame name used since called from various places
 	-- set the location of the frame... in case they dragged it away
 	myClockIndicatorFrame:SetPoint("TOPLEFT", "MinimapCluster", "TOPLEFT", 122, -28);
 	  -- wow automatically saves the location of frames on the screen!
 	-- make sure the defaults are loaded onto our mod frame
 	myClock_ConfigChange();
  end
  ...