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.***

* Allow map on tablet

*If disabled the map app won't appear in the 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:

* A stopwatch

*You can start, stop, restart and reset the stopwatch. Closing the interface won't stop the stopwatch.*

* A timer/countdown alarm

*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.*

* A regular alarm

*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.*

### 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

```
<br/>

```

Will insert a line break

```
<img size = '15' image ='pathToYourPicture.jpg'/>

```

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 <br/> and also include pictures  <img size = '15' image ='pathToYourPicture.jpg'/>"; //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 <img size = '15' image ='pic1.jpg'/>";
  		};

  	};
  	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
     0 - <OBJECT> receiver (player)
     1 - <ARRAY> 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
    0 - <OBJECT> receiver (player)
    1 - <ARRAY> 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> object to add the action to
   1 - <ARRAY>- Optionnal -Array of strings of data entries to give to the player (defined in MRH_SoldierTabData config entry)
   2 - <ARRAY>-Optionnal -Array of pictures to give to the player (defined in MRH_SoldierTabIntelPictures)
   3 - <BOOLEAN> -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.