This README describes the contents of this dir and their file structure.

Last Edited, Feb 2nd 09:00 AM

	Inside this dir "Gui", contains several files with a ".glade" and a 
".datamap" extension.  The .glade files are glade GUI description files 
written in XML and generated by the glade-2 gui designer. The author used 
Glade-2.0.1.  They describe the gui layout of a tab.  All widgets are 
named unique names and that is where the datamap file comes from.  The 
datamap is laid out in .ini file format using the common "section",
"key","value" layout as shown below.


[section]
key=value

What MegaTunix does, is that after it starts it checks to make sure an ECU
is present by issuing a comms test. (sends a "C" and checks for a response)
If that succeeds, Mtx then procedes to interrogate the ECU.  It does this
by reading a list of tests from a config file. This configuration file is
stored by default in /usr/local/share/MegaTunix/Interrogator/tests. After
reading and validating the file MegaTunix will send the commands
to the ECU in turn and record the responses.  Once all the responses are 
gathered, MegaTunix will load each interrogation profile in sequence, and 
attempt to match what it recorded with the profile,  once an exact match is 
found it will read a list of tab names to load from the interrogation profile 
and load those tabs followed by calling the "bind_data()" function for each
widget in the glade definition.  bind_data() looks inside the datamap file 
for a section named after the widget, and proceeds to read the "keys"
field from that section.  and then each one of the keys
are loaded and bound to the widget using the g_object_set_data() call.  This
is done because all of the signal handlers throughout megatunix extract that
data to make apprpriate decisions about handling data.

NEW:
 New functionality has been done to reduce the redundancy of keys needing
to be set on a large range of variables that share common settings. This 
is done in the form of "groups".  If you have a group or multiple groups
of controls that share flags and don't want to set those flags for each
and every widget.  In the [global] section ad a key called "groups". This
key is a comma seperated list of section names.  These group sections are
the exact same format as any normal section below.  In widget sections where
you want to inherit the group settings, just add a key/value pair 
like "group=groupname". If you want to override a group setting the setting
defnied in the widget section WILL OVERRIDE the grop setting if you want to.

NOTES regarding the datamap files:

1. The value names are CaSe SeNsItIvE, so be warned.  Ironically the
keys themselves are not, as the string compare functions are case insensitive.

2. There is no limit to the number of keys that you can bind to a widget.

3. Most commonly used keys are:
	group		(string) Points to a section to get additional 
			params from. See notes above regarding groups
	page		(integer) page in ecu that this control refers to
	offset		(integer) offset from the beginning of said page that
			this control refers to. 
	table_num	(integer) Table number that this control applies to.
			The table number comes from the interrogation profile
			This is ONLY used for interdependant controls that
			have special handlers (required_fuel and all the things
			that depend onf it, like cyls, injs, squirts, etc..)
	spconfig_offset	(integer) Offset of the corresponding spark trigger 
			config bitfield (linked to the control that uses this
			parameter)
	oddfire_bit_offset	(integer) Offset of the corresponding oddfire
			config bitfield (linked to the control that uses this
			parameter)
	bitval		(integer) the value of part of a bitfield (see below)
	bitmask		(integer) the bitmask of bitval..
	temp_dep	(boolean) Temperature dependant widget (flag)
	label		(string)  normal label to use (See "swap_labels")
	alt_label	(string)  alternate label to use (See "swap_labels")
	c_label		(string)  Celsius label for temp dependant widgets
	f_label		(string)  Fahrenheit label for temp dependant widgets
	alt_c_label	(string)  Celsius label for temp dependant widget when
			another widget is at a specific state (see depend_on)
	alt_f_label	(string)  Celsius label for temp dependant widget when
			another widget is at a specific state (see depend_on)
	precision	(integer) number of decimal places to show
	reverse_keys	(boolean) Reverses the action of the +/- PgDn/PgUp 
			logic, for controls that use weird conversions.
	depend_on	(string) Name used to prepend the following vars (*)
	*_type		(enum) Types of vars to depend on
	*_page		(integer) Page in ve_vars
	*_offset	(integer) Offset in ve_Vars)
	*_bitmask	(integer) bitmask to mask value at page,offset
	*_bitval	(integer) value to match against for above 4 params
	swap_labels	(comma seperated string list). List of widget names OR
			GROUPNAMES (created with bind_to_list) to
			swap the labels based on the state of this widget. 
			Widget names and groups can be intermixed
			Currently applies to BITFIELD widgets ONLY. The target
			widget IF IT IS NOT TEMP DEPENDANT should have "label"
			and "alt_label" defined, otherwise it needs 4 keys
			defined: f_label, c_label, alt_f_label and alt_c_label.
			to handle all the possible states. The widget named
			must have the "depend_on" flag set and all the required
			keys for this to work as intended.. 
	bind_to_list	(string)  A list of strings (keys) of lists that this
			widget is bound to.  Used mainly to bind related 
			controls together for combined operations on them with
			some signal handler
	handler		(enum) A string representation of a signal handler
			choice, uses translate_string() to convert to an integer
	toggle_groups	(string) List of groups of widgets to enable/disable
			based on the state of this control.
	dl_type		(enum) Normal values are IMMEDIATE (means send the 
			value right away) and DEFERRED, meaning that the
			control is usually dependant on some calculation or
			interdependancy with other variables.  Not having
			a dl_type is OK, but is usually only used for controls
			that display something but don't directly map to an
			ECU location.
	ign_parm	(bool) Used to flag an ignition var for ONLY the 
			MSnS (NOT Extra series) and MSnEDIS, as they used a
			different command to write ignition variables to the
			ECU.
	ul_complex	(bool) A Flag signaling that the upload conversion is
			"complex" meaning that and extended parser is called to
			load the data. Required strings are ul_conv_expr,
			expr_symbols, and expr_types.  
	dl_complex	(bool) A Flag signalling that the download conversion 
			is "complex" (same rules as ul_complex)
	dl_conv_expr	(string)  A string representation of a mathematical
			expression. (something like x*60)  Used when a control
			is modified and the value needs conversion BEFORE
			sending to the ECU.
	ul_conv_expr	(string)  A string representation of a mathematical
			expression. (something like x*60)  Used when reading a
			variable FROM the ecu and converting it to a value for
			the on-screen control. USUALLY a converse function to
			"dl_conv_expr" above.
	expr_symbols	(string, comma delimited) Names of strings in the 
			{ud}l_conv_expr (ONLY used when {ud}l_complex is 
			defined as true) Lists the string names of all 
			variables in the expression, comma delimited.
	expr_types	(enums, comma delimited) Types of variables, goes hand
			in hand with expr_symbols above,  the number of 
			variables in this line and expr_symbols must be the
			same otherwise an eror is thrown. Valid types are
			_VE_EMB_BIT_ (meaning a bitfield imbedded into the VE
			Variables, can be in any page), _VE_VAR_ menaing just
			a VE variable, at any page offset.
	source		(string) string name of the source that this widget's
			state relies upon (bitfields ONLY).  The source names
			are defined in a RealTimeMap file that is firmware
			specific. (Specified in the interrogation profile)
			Used primarily for status indicators using data 
			from the realtime variables datasources...
	post_functions	(string) This is the textual list of pre-existing 
			functions within megatunix that will be ran after the
			tab is loaded and the datamap has been processed. The
			function will take no arguments and return nothing.
			This is used mainly for hybrid tabs that have their
			basic layout done in glade and are populated with 
			additional widgets in a more efficient manner by a 
			function. (see memory_gui.c for details )
	sub-notebook	(string) Special purpose key used so that the page
			change detector can extract the active table number 
			from the notebook tabs.  Used as a CPU saver to avoid
			updating windows that are not visible

NOTE: regaring expr_symbols and expr_types:
	The expr_types in combination of expr_symbols determine what following
keys will be present in the section.  IF expr_symbols contains "cyls,reqfuel"
and expr_types contains "_VE_EMB_BIT_,_VE_VAR_" then the following fields will
be searched for. "cyls_page","cyls_offset","cyls_bitmask".
"reqfuel_page" and "reqfuel_offset". (Embedded bitfields need, the page,offset
and bitmask to be resolved completely), VE_VAR's ony need the page 
and offset to be resolved.
completely.

HOW Bitfields are used:
	Controls that associate to a bitfield can either be a button, 
which is either a toggle (two choices) or radio (multiple choices) 
or a spinbutton in which a numerical value is stored into a bitfield 
(num_cylinders, etc..)  For buttons, in the datamap file we use bitval, 
and bitmask.

When clicking a button, what megatunix  does is retrieve the byte at the 
page/offset set by that control, mask off the other bits in that byte with
the bitmask. (byte & bitmask)and set the new bits appropriately

When updating the button after reading the data from the ECU, we mask it and 
then shift it.  
	if((value%bitmask) >> bitshift) == bitval)
		Set button clicked
	else
		set button NOT clicked
i.e.
IF this value EQUALS bitval we set the buttons state to 
TRUE (clicked), otherwise we set it to FALSE.

For spinbuttons we use "convert_after_upload" which checks for a simple or
complex conversion. (bitfield embedded values are considered a complex 
conversion due to handling the bit masking/shifting). See handle_complex_expr()
in the sourcecode.

