Soldier PDA use and framework guide

Introduction
The mod features a soldier PDA, provided a player has the pda in their inventory, they will be able to access it through the ACE3>>self-interactions>>Equipment menu. (CTRL+ Left Windows key) The pda can be found in the arsenal under the [+] miscellaneous items.

Its classname for scripts is: MRH_SoldierTab

Settings
Currently, only one setting is available found in settings>>controls>>configure addons>>show: MRH_Milsim Tools -  Tablet settings. If disabled the map app won't appear in the tablet.
 * Allow map on tablet

Features
The tablet has several apps accessible through the icons on the left hand side of the screen. The tablet shows the time in real game time.

Home page
On the home page players will find their basic information (role, rank, group, radio frequency.) See Customized player intel for a guide on these. They will also have a view of their avatar and a roster for their group.

Group page
The group page displays the team roster, the settings applied to the team roster are also applicable here.

Map
The map app can be hidden from the settings (see above). Otherwise it will show a map with the player's position marked.

Pictures gallery
The pictures gallery show the pictures 'owned' by the player. For more information on how to define and add pictures see the framework section below. By default the gallery doesn't contain any picture, they have to be added by mission makers. Pictures thumbnails are displayed on the left and the caption for the picture is displayed as a tooltip of the pic as well as under the full screen image.

Timer app
The tablet includes a timer app, like any modern tablet. The timer app includes: ''You can start, stop, restart and reset the stopwatch. Closing the interface won't stop the stopwatch.'' ''You can set a duration in hours, minutes and seconds (you can only define one if you don't need all values). The countdown will show. At the end of the countdown the tablet will buzz and ring quietly. Alarm can be heard by nearby players. Closing the interface won't stop or reset the countdown and the tablet will still ring at the end of the countdown. Of course you can cancel it by clicking the 'stop' button.'' ''You can set and alarm for the desired time of the day, at the given time the tablet will buzz and ring. You don't need to have the interface opened to hear the alarm.''
 * A stopwatch
 * A timer/countdown alarm
 * A regular alarm

Files
An infinite amount of files can be added to the tablet. The files appear as folders and subfolders they can contain structured text and pictures. By default the tablet doesn't contain any file, they have to be added by the mission maker. See the framework below for a full tutorial.

File & picture transfer
Players can share files with anyone within a ten meters distance from them via the share button. ALL owned files and pictures will be transferred to the selected player, yes, that's how powerful MRH Tech proprietary bluetooth protocol is, suck it up Apple!



Framework
To provide content for the PDA in your missions the following steps are necessary.

Setting up config in mission's description.ext
Pictures and data must be listed in your mission's description.ext file (directly or via #include). There are two classes to create: MRH_SoldierTabIntelPictures and MRH_SoldierTabData You will find templates and examples in the mod's folder.

Adding pictures
To add pictures to the tablet you need to create a class MRH_SoldierTabIntelPictures, this class will contain a list of subclasses listing your pictures. Picture sub classes names must be unique and will be used as a reference in the associated functions.

Each picture class must contain two config entries:

1) captionText captionText = "Your text here"; contains the caption text for your picture. Leave ""; if you do not want the picture to have a caption.

2) picture picture = "pathtoyourpicture"; contains the path to the associated picture

Below are some templates and examples

Template

class MRH_SoldierTabIntelPictures //cannot be changed {              	//you can have as many pictures as you want class MyPictureClassName //must be unique, can be anything,good practice is to tag with your handle. {              	captionText = "yourCaptionTextHere"; //simple caption text, mandatory, leave "" if you do not want a caption picture = "pathToYourPicture.jpg"; //mandatory must be .jpg or .paa };              };

Example class MRH_SoldierTabIntelPictures {             		class pic1 {             	captionText = "A drone view of the zone"; picture = "pic1.jpg"; };             		class pic2 {             	captionText = "Some shady spec ops guys"; picture = "pic2.jpg"; };             		class pic3 {             	captionText = "Some dead soldier"; picture = "pic3.jpg"; };             		class pic4 {             	captionText = "Civilians having the strangest flashmob"; picture = "pic4.jpg"; };             	class pic5 {             	captionText = "On board your heli"; picture = "pic5.jpg"; };             		class pic6 {             	captionText = "A VIP target"; picture = "pic6.jpg"; };             };

Adding data
Data must be listed in a class: MRH_SoldierTabData There are two types of data entries: Entry and sub entry. Each one of them must have a unique class name. Entry class names will be used in functions to add the data to the PDA (you cannot add a sub data on the fly).

Main entries appear in the PDA as "folders" while sub entries appear as sub directories to these folders: 1) Main entries.

Main entries do not necessarily have to contain sub classes entries. You can have as many of them as you want. They must contain two config lines:

a) Title title = "YourTitleHere"; Will be the title displayed in your entry.

b) Text text = "YourTextHere"; Will be the text associated with your config. It accepts structured text so you can change its size and color etc. with structured text operators. For example Will insert a line break  Will insert a picture (size 15 is the biggest recommanded size).

2) Sub entries

Sub entries are not mandatory, if you use them they must be placed WITHIN a main entry class. They must contain two config lines:

a) Title: titleSub = "YourTitleHere"; b) Text textSub = "YourTextHere"; The text accepts structured text, similarly to main entry, see above.

Below are templates and examples.

Data template
class MRH_SoldierTabData //mandatory, do not change {          	//you can have as many entries as you want class MyFirstData //must be unique, can be anything {          	title = "YourTitleHere"; // simple text text = "YourTextHere";// accepts structured text, DO NOT use double quotes("") inside. };          	class MySecondData //must be unique,can be anything {          	title = "YourTitleHere"; text = "YourTextHere";// accepts structured text, DO NOT use double quotes("") inside. //you can have as many sub entries as you want class MyFirstSubEntry //must be unique,can be anything {          		titleSub = "YourTitleHere"; textSub = "YourTextHere";// accepts structured text, DO NOT use double quotes("") inside. };          		class MySecondSubEntry {          		titleSub = "YourTitleHere"; textSub = "YourTextHere You can use and also include pictures "; //after thorough testing 15 seems to be the most appropriate size for pictures. Smaller is OK, bigger might not be fully displayed. };          	};           };

Data example
class MRH_SoldierTabData {  	class dataEntry1 {  	title = "This is a parent main entry"; text = "insert main text here, text accepts structured text"; class subEntry1 {  		titleSub = "this is a first child entry"; textSub = "text accepts structured text "; };  	};   	class dataEntry2 {  	title = "Mission: save your ass"; text = "If you accept this mission please read the subentries"; class subEntry1 {  		titleSub = "part 1: save"; textSub = "run!"; };  		class subEntry2 {  		titleSub = "Part 2 your arse"; textSub = "hide!"; };  	};   };

Companion functions
Even if you have defined correctly your data and pictures in your description.ext they will not show up straight away in the PDA, each data and picture can and must be given separately to players. The three following functions allow you to do just that. Please note that in the current's version of the mod you can 'give' players data and pictures but not remove them.

Attribute data function
This function allows you to attribute data to a given player.

Here's the function's header: Function name: MRH_fnc_MilsimTools_SoldierTab_attributeData Author: Mr H.    Description: "adds" given data (referenced by classnames) to player's data Return value:none Public: Parameters: 0 -  receiver (player) 1 -  of data classnames Example(s): [player,["dataEntry1","dataEntry2"]]call MRH_fnc_MilsimTools_SoldierTab_attributeData;

Be aware of locality when you use this function. If you call it from a trigger for example, by default trigger effects are global and so once the trigger is activated the data will be given to all players. Upon receiving data players will receive a notification.

Attribute pictures function
This function allows you to attribute pictures to the given player.

Here's the function header: Function name: MRH_fnc_MilsimTools_SoldierTab_attributePictures Author: Mr H.   Description: "adds" given pictures (referenced by classnames) to player's data Return value:none Public: Parameters: 0 -  receiver (player) 1 -  of pictures classnames Example(s): [player,["pic1","pic2"]]call MRH_fnc_MilsimTools_SoldierTab_attributePictures; Same limitation as above apply. Players will receive a notification upon receiving data.

Data collection point function
This function allows you to turn any object into a data collection point. It will add an ACE3 interaction to the object. Function name: MRH_fnc_MilsimTools_SoldierTab_isDataCollectPoint Author: Mr H.  Description: turns any item into a data collect point (ace action) Return value: none Public: yes Parameters: 0- object to add the action to  1 - - Optionnal -Array of strings of data entries to give to the player (defined in MRH_SoldierTabData config entry) 2 - -Optionnal -Array of pictures to give to the player (defined in MRH_SoldierTabIntelPictures) 3 -  -optionnal - true to remove action after the data is collected, default false Example(s): [this,["dataEntry1","dataEntry2"],[],true]call MRH_fnc_MilsimTools_SoldierTab_isDataCollectPoint; or  [this,["dataEntry2"],["pic1"],true]call MRH_fnc_MilsimTools_SoldierTab_isDataCollectPoint; or  [this,[],["pic2"],false]call MRH_fnc_MilsimTools_SoldierTab_isDataCollectPoint;

Attribute data at startup
If you want to make certain data available to everyone at mission start, the simpler method is to call the functions in your initplayerlocal.sqf

It might we necessary to wait for the player to initialize before giving them data

for example //initplayerlocal.sqf

[] spawn { 	waitUntil {player == player}; [player,["dataEntry1","dataEntry2"]]call MRH_fnc_MilsimTools_SoldierTab_attributeData; [player,["pic1","pic2"]]call MRH_fnc_MilsimTools_SoldierTab_attributePictures; };

Caveats
At the moment all variables associated with data and pictures are attributed to the player, not the PDA object itself. Which means that giving another player your tablet won't pass the data and pictures to the other player.