Lib GUI - Revision history

Svengali: Added handled GUIs and custom IDs

2016-08-23T16:06:46Z

Added handled GUIs and custom IDs

Svengali at 11:33, 21 August 2016

2016-08-21T11:33:11Z

Svengali: Added suffixes

2016-08-21T10:17:51Z

Added suffixes

Svengali at 18:02, 14 August 2016

2016-08-14T18:02:08Z

Svengali: Note about 'Big' suffix for hudAllowsBigGui

2016-08-14T14:41:03Z

Note about 'Big' suffix for hudAllowsBigGui

Svengali: Documentation

2016-08-04T11:02:16Z

Documentation

New page

[[Image:IconLib.png|100px|right]]
==Overview==
Lib_GUI (part of [[Library]]) is an attempt to manage multiple background-image AddOns, as far as JavaScript can do the job. It works in a relative simple way - AddOns can just write their Sets to the Objects $guis, $IDs and AddOns with missionscreens can declare rules in $IDRules. As only one Set is in use, players won't get style mixtures anymore (for full Sets). The inserted full Sets are user-selectable at runtime through [[Lib_Config]].

But JavaScript can handle it only when it is executed. If the application starts or the game is paused, you'll still need to declare a few images in screenbackgrounds.plist.

==Preparation==
===manifest.plist===
Add to your manifest.plist
requires_oxps = (
{
identifier = "oolite.oxp.Svengali.Library";
version = "1.0";
description = "Depends on Library 1.0.";
}
);

===screenbackgrounds.plist===
Use these keys in screenbackgrounds.plist
{
intro = guiTextureSpecifier;
keyboardsettings = guiTextureSpecifier;
load_save = guiTextureSpecifier;
newgame = guiTextureSpecifier;
oxz-manager = guiTextureSpecifier;
settings = guiTextureSpecifier;
shiplibrary = guiTextureSpecifier;
long_range_chart_mission = "lib_black.png"; // any full black texture
short_range_chart_mission = "lib_black.png";
}

==Full Sets==
===Registering a GUI-Set===
{{CodeEx|codeex= worldScripts.Lib_GUI.$guis[this.name] = object;}}
Register a data set for standard GUIs (all screens without screenID) on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUp]].

Example:
worldScripts.Lib_GUI.$guis[this.name] = {
generic: {pic:guiTextureSpecifier},
GUI_SCREEN_EQUIP_SHIP: {pic:"xyz.png", ov:"xyz.png", snd:"xyz.ogg"},
...
};

The Object members are:
:;pic: guiTextureSpecifier.
:;picFlight: guiTextureSpecifier. Inflight only.
:;picNova: guiTextureSpecifier. On GUI_SCREEN_SYSTEM_DATA only.
:;picRed: guiTextureSpecifier. Inflight only.
:;picVoid: guiTextureSpecifier. Docked only if station.script has $guiVoid set.
:;ov: guiTextureSpecifier.
:;snd: sound declaration.
:;sndRef: any other Set (e.g. "BGS").

If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding ''scale: {x:pixel,y:pixel,zoom:level}''.

As you can see an additional member is used: "generic". This is used to catch all GUIs which are not declared.

===Registering an ID-Set===
{{CodeEx|codeex= worldScripts.Lib_GUI.$IDs[this.name] = object;}}
Register a data set for screens with screenID on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUp]].

Example:
worldScripts.Lib_GUI.$IDs[this.name] = {
generic: {pic:"xyz.png", mpic:"xyz.png", ov:"xyz.png"},
"oolite-contracts-cargo-none": {pic:"xyz.png", snd:"xyz.ogg"},
"oolite-contracts-cargo-details": {mpic:"xyz.png", snd:"xyz.ogg"}, //!!!
...
"my_oxp_custom_screen": {pic:"xyz.png", snd:"xyz.ogg"}
};

The object members are (all optional):
:;mpic: guiTextureSpecifier. For screens which are using backgroundSpecial.
:;pic: guiTextureSpecifier.
:;ov: guiTextureSpecifier.
:;snd: sound declaration.
:;sndRef: any other Set (e.g. "BGS").

If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding ''scale: {x:pixel,y:pixel,zoom:level}''.

As you can see one additional member is used: "generic". This is used if an OXP has registered a screenID rule, but is not defined in the current IDSet. It's optional.

'''Note''': Another important thing is the details screens in Oolites cargo, parcel and passenger screens (mpic). If an OXP would set an background on these screens the map will disappear. This means that these screens need to be done via overlay! Sooo. The used image needs an alpha channel with the map area cut out (or alpha <0.5).

==Extensions==
===Setting rules for custom IDs===
{{CodeEx|codeex= worldScripts.Lib_GUI.$IDRules["MY_OXP_SCREEN_ID"] = object;}}
Custom rules for your screenIDs can be set, but rules are shared, so do not change existing ones if they are not yours.

Example:
worldScripts.Lib_GUI.$IDRules["MY_OXP_SCREEN_ID"] = {pic:1,snd:1,mus:1};

The object members are:
:;mpic: 0 disallow, 1 allow - Set this to 1 if you are using backgroundSpecial.
:;pic: 0 disallow, 1 allow - Image. Ignored if mpic is set.
:;ov: 0 disallow, 1 allow - Image. Ignored if mpic is set.
:;snd: 0 disallow, 1 allow - If a GUI sound is still playing.
:;mus: 0 disallow, 1 allow - Continue music in Lib_Music.js.

===Temporary GUI override===
{{CodeEx|codeex= worldScripts.Lib_GUI.$guisExt.GUI_SCREEN_REPORT.push(object);}}
AddOns which are meant as replacements for single GUI screens (e.g. hdbg) can write to $guisExt. If content is available the first entry will be used instead of the full Set until the Array is empty. After display the first entry gets removed. In the end a FIFO system (first-in, first out). See [[#Registering a GUI-Set|Registering a GUI-Set]] for the object members.

[[Category:OXPDoc]]

@@ Line 37: / Line 37: @@
 {{CodeEx|codeex= worldScripts.Lib_GUI.$guis[this.name] = object;}}
 Register a data set for standard GUIs (all screens without screenID) on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUp|.startUp]].
 Example:
@@ Line 116: / Line 120: @@
 AddOns which are meant as replacements for single GUI screens (e.g. [[HDBG]]) can write to $guisExt. If content is available the first entry will be used instead of the full Set until the Array is empty. After display the first entry gets removed. In the end a FIFO system (first-in, first out). See [[#Registering a GUI-Set|Registering a GUI-Set]] for the object members.
-===Temporary ID override===
+===Global custom IDs===
 {{CodeEx|codeex= worldScripts.Lib_GUI.$IDsExt["MY_OXP_SCREEN_ID"] = {pic:"xyz.png"};}}
-Temporary declarations for specific screenIDs can be written to $IDsExt. Like any other missionscreen it will need a [[#Setting rules for custom IDs|rule]] defined. See [[#Registering an ID-Set|Registering an ID-Set]] for the object members.
+Declarations for custom screenIDs can be written to $IDsExt. Like any other missionscreen it will need a [[#Setting rules for custom IDs|rule]] defined. See [[#Registering an ID-Set|Registering an ID-Set]] for the object members.
--->
 [[Category:OXPDoc]]

@@ Line 109: / Line 109: @@
 :;ov:  0 disallow, 1 allow - Image. Ignored if mpic is set.
 :;snd: 0 disallow, 1 allow - If a GUI sound is still playing.
-:;mus: 0 disallow, 1 allow - Continue music in Lib_Music.js.
+:;mus: 0 disallow, 1 allow - Continue music in [[Lib_Music]].
 ===Temporary GUI override===
 {{CodeEx|codeex= worldScripts.Lib_GUI.$guisExt.GUI_SCREEN_REPORT.push(object);}}
-AddOns which are meant as replacements for single GUI screens (e.g. hdbg) can write to $guisExt. If content is available the first entry will be used instead of the full Set until the Array is empty. After display the first entry gets removed. In the end a FIFO system (first-in, first out). See [[#Registering a GUI-Set|Registering a GUI-Set]] for the object members.
+AddOns which are meant as replacements for single GUI screens (e.g. [[HDBG]]) can write to $guisExt. If content is available the first entry will be used instead of the full Set until the Array is empty. After display the first entry gets removed. In the end a FIFO system (first-in, first out). See [[#Registering a GUI-Set|Registering a GUI-Set]] for the object members.
 [[Category:OXPDoc]]

@@ Line 55: / Line 55: @@
 :;sndRef: any other Set (e.g. "BGS").
 If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding ''scale: {x:pixel,y:pixel,zoom:level}''.
@@ Line 82: / Line 85: @@
 :;sndRef: any other Set (e.g. "BGS").
-All "mpic", "pic" and "ov" members can use the suffix "Big" for HUDs which are designed to allow big screens (hudAllowsBigGui). It is required though to set both, e.g. "pic" and "picBig".
+All "mpic", "pic" and "ov" members can use suffixes to handle additional stuff:
 If your are using Objects for guiTextureSpecifier, e.g. {name:"xyz.png"} you can use Norbys scaling by adding ''scale: {x:pixel,y:pixel,zoom:level}''.

@@ Line 36: / Line 36: @@
 ===Registering a GUI-Set===
 {{CodeEx|codeex= worldScripts.Lib_GUI.$guis[this.name] = object;}}
-Register a data set for standard GUIs (all screens without screenID) on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUp]].
+Register a data set for standard GUIs (all screens without screenID) on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUp|.startUp]].
 Example:
@@ Line 64: / Line 64: @@
 ===Registering an ID-Set===
 {{CodeEx|codeex= worldScripts.Lib_GUI.$IDs[this.name] = object;}}
-Register a data set for screens with screenID on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUpComplete|.startUp]].
+Register a data set for screens with screenID on [[Oolite_JavaScript_Reference:_World_script_event_handlers#startUp|.startUp]] or later.
 Example: