[Library] GXML

//--------------------------------------------------------------------------------------------------
// Library: GXML Documentation, For the lazy - by FuzzYD
//--------------------------------------------------------------------------------------------------
// Description
// GXML Library by FuzzYD.609 @ SEA
// Hosted by SC2Mapster
// If you have questions,suggestions or find bugs, feel free to mail me at guan.chuan.siong@gmail.com
// Version: B02
// Requires: QuickLib - A02 or later

//--------------------------------------------------------------------------------------------------
// Changelog - B02
//--------------------------------------------------------------------------------------------------
// - Ported to .galaxy

//--------------------------------------------------------------------------------------------------
// Introduction
//--------------------------------------------------------------------------------------------------
// GXML is a scripting tool based on classic XML syntax. It is coded entirely with custom script in 
// Galaxy. Its purpose is to quick creation of dialogs and dialog items with XML code. This library
// is not intended for GUI users as GUI already contains many of the functions required for creating
// dialogs.

//--------------------------------------------------------------------------------------------------
// Motivation
//--------------------------------------------------------------------------------------------------
// I personally use dialogs a lot, Almost all my scripting is done with dialogs and I found it was
// really mundane having to create dialogs and set their properties with a multitude of functions
// each time. Sometimes, I would only need to set dialog positions, sometimes only size, or images.
// It didn't seem very efficient to have to have one function for every purpose. I wanted a function
// that allows me the freedom to specify whatever properties I want, in whatever sequence I choose.
// Thus I was inspired to write GXML.

//--------------------------------------------------------------------------------------------------
// Installation
//--------------------------------------------------------------------------------------------------
// 1) Open your editor and open the import menu (F9).
// 2a) Right click the import (Ctrl+I) interface and GXML.galaxy.
// 2b) Optional step - Move (Ctrl+M) GXML.galaxy to TriggerLib.
// 3) Open the trigger editor (F6), Create a new customscript (Ctrl+Alt+T).
// 4) Insert the following line, without paranthesis, and you're good to go!
//	  'include "TriggerLibs/GXML"'
//    Note: This path will differ depending on your actions during step 2b
// 5) Set the optional initializer function to 'InitGXML'. This will initialize the variables needed
//	  for it to function correctly.

//--------------------------------------------------------------------------------------------------
// Features
//--------------------------------------------------------------------------------------------------
// - 9 supported dialog types (See Supported dialog types below)
// - Parameter input freedom. Set whatever properties you want, wherever you want.
// - Parameters that have no effect on the selected dialog/dialog item are ignored.
// - Error detection: GXML will output errors if it detects parameters that are missing, exclusive
//	 to different dialog items
// - Easily set the target dialog for dialog item creationg with SetDialog(int d);

//--------------------------------------------------------------------------------------------------
// Known caveats
//--------------------------------------------------------------------------------------------------
// - Tips with '</n>' within them are currently broken. Hope to fix this in a future update.

//--------------------------------------------------------------------------------------------------
// Supported dialog types
//--------------------------------------------------------------------------------------------------
//Dialog
// - Dialog
//Dialog controls
// - Button
// - Check box
// - Edit box
// - Images
// - Labels
// - List box
// - Progress bar
// - Pulldown menu
// - Slider

//--------------------------------------------------------------------------------------------------
// Unsupported dialog types
//--------------------------------------------------------------------------------------------------
// The following dialog types are unsupported for reasons stated below.
// - f = flash (Blizzard only)
// - a = achievement (Can't get it working)
// - p = panel (Can't get it working)

//--------------------------------------------------------------------------------------------------
// Unsupported functions
//--------------------------------------------------------------------------------------------------
// There are currently no plans to support the following functions as they are too situational
// - Set dialog image type: The default is normal image type
// - Render priority: Believed to be rarely used in basic implementations
// - Text styles: Too many different styles
// - Text writeout: Situational


//--------------------------------------------------------------------------------------------------
// Accepted identifier
//--------------------------------------------------------------------------------------------------
// Identifier tag inputs
// Important Note: These must be declared immediately after first "<" in your GXML string
// * d = dialog
//Dialog controls
// * b = button 
// * c = check box 
// * e = edit box 
// * i = image 
// * l = label 
// * lb = listbox 
// * pb = progress bar 
// * pd = pulldown 
// * s = slider 

//--------------------------------------------------------------------------------------------------
// Accepted parameters
//--------------------------------------------------------------------------------------------------
// Compulsory inputs
// * w = width (Int)
// * h = height (Int)
// Optional inputs (All dialog/dialog item types)
// * c = color (Hex color, Example: FF0000)
// * a = anchor (0// * 8, Top left to bottom right, row by row)
// * x = x offset (Int, used with anchors)
// * y = y offset (Int, used with anchors)
// * f = fade (Fixed,%)
// * tip='YourTip' dialog item tooltip (String)
// * txt= text display (concealed from user, declared in between <...> and </...>) 
// Image dialog items only
// * r = rotation (Int)
// Image and Button dialog items only
// * img= dialog item image (String)
// Image, Button, Progress bar and slider only
// * min= minimum dialog value (Fixed)
// * max = maximum dialog value (Fixed)
// * val = current dialog value (Fixed)
// Boolean Inputs (No arguments required)
// +check = For checkbox, initial check state
// +tiled = For image/button, defines if image is tiled
// +hide = For dialog, not to be confused with visible, hides dialog background
// +full = For dialog/dialog item, forces dialog/dialog item to be fullscreen/full dialog
// +off = Initially disable dialog/dialog item

//--------------------------------------------------------------------------------------------------
// How to use
//--------------------------------------------------------------------------------------------------
// Optional settings:
// GXML has a constant 'c_DefaultFullDialog' which is set to false. You may set this to true with
// any text editor before importing GXML into your map. By setting this to true, GXML will force
// all dialogs and dialog items that are missing the compulsory width and height parameters to 
// '+full'
//
// The GXML function takes on the following form
// * int GXML(string GXMLString);
// Alternatively, the following function performs the same action (It's quicker)
// * int qd(string GXMLString);
// Notice that the return type for GXML is int. This int is actually an identifier to the dialog or
// dialog item that it creates. If you store this value into an array, you can easily callback your
// created dialog/dialog item for modification later!
//
// Using GXML
// 1) Open your trigger editor (F6) and add a new custom script (Ctrl+Alt+T)
// 2) Set the optional initializer function to a function of your choice
// 3) Declare your initializer function, Example below
//
//	  void InitHelloWorld(){
//			//GXML Call
//	  }
//
// 4) Insert a GXML Call with a string in the following format, without any apostrophes ('):
//
//	  GXML("<'id' 'param1' 'param2' 'param3' ... 'paramN'>'Insert text here'</'id'>");
//
//	  The only exception to this rule is the insertion of a tip parameter which must be done as
//	  follows: 
//
//	  'tip='This is a tip''
//
//	  Notice that all parameters and id's are always separated by a space, similar to whart you see
//	  in XML.
//
// The full list of accepted identifiers and parameters can be seen in the two blocks preceding
// the How to use section. For examples of usage, take a look below. Alternatively, you may import
// "GXMLDoc.galaxy" into your map and include it in custom script to see how it works.
// The Example initializer function is GXML_Example. This will need to be set as the custom script
// Initializer where you include GXMLDoc.