BIS fnc addStackedEventHandler: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
No edit summary
m (Fix SQF)
 
(63 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Function|= Comments
{{RV|type=function
____________________________________________________________________________________________


| arma3 |= Game name
|game1= arma3
|version1= 1.00


|1.00|= Game version
|gr1= Event Handlers
____________________________________________________________________________________________


| Stack an event handler. Possible event handlers are:
|eff= local
* "onEachFrame"
* "onPlayerConnected"
* "onPlayerDisconnected"
* "onMapSingleClick"
* "onPreloadStarted"
* "onPreloadFinished" |= Description
____________________________________________________________________________________________


| [key, event, code, arguments] call [[BIS_fnc_addStackedEventHandler]]; |= Syntax
|mp= This command has the same locality as [[addMissionEventHandler]].


|p1= key: [[String]] - unique identifier|= Parameter 1
|descr= {{Feature|obsolete|[[Arma 3: Mission Event Handlers]] should be used instead.|arma3|1.58}}
Stacks an event handler.  All event handlers accept user arguments, which are passed to the EH code in {{hl|_this}} variable. If the EH has own params returned in {{hl|_this}} variable as well, user arguments are appended to the end of {{hl|_this}} array. Note that if you try to add an empty EH, i.e. with empty code, it will simply be ignored.


|p2= event: [[String]] - event handler type, see Description|= Parameter 2
{{{!}} class="wikitable"
{{!}}+ Supported Event Handlers
! Scripted Event Handler
! Mission EH Equivalent
! Description
{{!}}-
{{!}} "[[onEachFrame]]"
{{!}} [[Arma 3: Mission Event Handlers#EachFrame|EachFrame]]
{{!}} {{n/a}}
{{!}}-
{{!}} "[[onPlayerConnected]]"
{{!}} [[Arma 3: Mission Event Handlers#PlayerConnected|PlayerConnected]]
{{!}} rowspan="2" {{!}}Special variables {{hl|_id}}, {{hl|_uid}}, {{hl|_name}}, {{hl|_jip}}, {{hl|_owner}} are provided and are available in {{hl|_this}} array as well.
<sqf>params ["_id", "_uid", "_name", "_jip", "_owner"];</sqf>
{{!}}-
{{!}} "[[onPlayerDisconnected]]"
{{!}} [[Arma 3: Mission Event Handlers#PlayerDisconnected|PlayerDisconnected]]
{{!}}-
{{!}} "[[onMapSingleClick]]"
{{!}} [[Arma 3: Mission Event Handlers#MapSingleClick|MapSingleClick]]
{{!}} Special variables {{hl|_units}}, {{hl|_pos}}, {{hl|_alt}}, {{hl|_shift}} are provided and are available in {{hl|_this}} array as well.
<sqf>params ["_units", "_pos", "_alt", "_shift"];</sqf>
{{!}}-
{{!}} "[[onPreloadStarted]]"
{{!}} [[Arma 3: Mission Event Handlers#PreloadStarted|PreloadStarted]]
{{!}} {{n/a}}
{{!}}-
{{!}} "[[onPreloadFinished]]"
{{!}} [[Arma 3: Mission Event Handlers#PreloadFinished|PreloadFinished]]
{{!}} {{n/a}}
{{!}}}


|p3= code: [[String]] or [[Code]] |= Parameter 3
|s1= [id, event, code, arguments] call [[BIS_fnc_addStackedEventHandler]]


|p4= arguments: [[Anything]] - arguments to make available in code|= Parameter 4
|p1= id: [[String]] - custom id, a unique identifier. Adding same type of EH with the same id will overwrite existing


| [[String]] |= Return value
|p2= event: [[String]] - event handler name, see description for supported EHs
____________________________________________________________________________________________
 
|x1= <code>["someId", "onEachFrame", {
[[hintSilent]] [[str]] [[time]];
}] [[call]] [[BIS_fnc_addStackedEventHandler]];</code> |=


|x2= <code>["someId", "onEachFrame", {
|p3= code: [[Code]] or [[String]]. The [[String]] is treated as function name
[[hintSilent]] [[str]] [[Magic Variables|_this]];
}, "Hello world!"] [[call]] [[BIS_fnc_addStackedEventHandler]];</code> |=
____________________________________________________________________________________________


| [[BIS_fnc_removeStackedEventHandler]] |= SEEALSO
|p4= arguments: [[Array]] of [[Anything]] - arguments to make available in code in {{hl|_this}} array


}}
|r1= [[String]] - custom id on success or "" on failure
 
|x1= <sqf>["someId", "onEachFrame", { hintSilent str time }] call BIS_fnc_addStackedEventHandler;</sqf>


<h3 style="display:none">Notes</h3>
|x2= <sqf>["someId", "onEachFrame", {hintSilent str position (_this select 0)}, [player]] call BIS_fnc_addStackedEventHandler;</sqf>
<dl class="command_description">
<!-- Note Section BEGIN -->


<dd class="notedate">Posted on November 1, 2013
|x3= <sqf>
<dt class="note">[[User:neokika|neokika]]<dd class="note">
private _eventName = "OnEachFrame";
More info at: http://forums.bistudio.com/showthread.php?167822-Stacked-event-handlers-OnEachFrame-OnPlayerConnected-etc
missionNamespace getVariable [format ["BIS_stackedEventHandlers_%1", _eventName], []]; // gets an array with all existing ids
</sqf>


<dd class="notedate">Posted on February 11, 2014
|seealso= [[addMissionEventHandler]] [[BIS_fnc_removeStackedEventHandler]]
}}


<dd class="notedate">Posted on 25 Jun, 2014
{{Note
<dt class="note">[[User:ffur2007slx2_5|ffur2007slx2_5]]<dd class="note">
|user= ffur2007slx2_5
(ArmA3 1.22) Stack all codes into one PFH will be less demanding than separated calling within multiple PFH. E.g.
|timestamp= 20140625120800
<code>
|text= Stacking all the code into one PFH will be less demanding than separated calling within multiple PFH, e.g:
<sqf>
{
{
[([[format]] [“%1”,_forEachIndex]),”[[onEachFrame]]”,_code,[_x]] [[call]] [[BIS_fnc_addStackedEventHandler]];
[format ["%1", _forEachIndex], "onEachFrame", _code, [_x]] call BIS_fnc_addStackedEventHandler;
} [[forEach]] [var0…var100]; //pretty demanding
} forEach [var0, var1, varN, var100]; // pretty demanding
</code>
</sqf>
<code>
<sqf>
[_id, ”[[onEachFrame]]”,{
[_id, "onEachFrame", {
  {_x [[call]] _code} [[forEach]] [var0…var100];
{ _x call _code } forEach [var0, var1, varN, var100];
}] [[call]] [[BIS_fnc_addStackedEventHandler]]; //faster
}] call BIS_fnc_addStackedEventHandler; // faster, only one event
</code>
</sqf>
<!-- Note Section END -->
}}
</dl>
 
<h3 style="display:none">Bottom Section</h3>
[[Category:Function Group: Misc|{{uc:addStackedEventHandler}}]]
[[Category:Functions|{{uc:addStackedEventHandler}}]]
[[Category:{{Name|arma3}}: Functions|{{uc:addStackedEventHandler}}]]
 
<!-- CONTINUE Notes -->
<dl class="command_description">
<dd class="notedate">Posted on December 8, 2014 - 08:21 (UTC)</dd>
<dt class="note">[[User:DreadedEntity|DreadedEntity]]</dt>
<dd class="note">
It is not possible to override default engine behavior with stacked event handlers. This is because [[BIS_fnc_executeStackedEventHandler]], a function that is called inside [[BIS_fnc_addStackedEventHandler]], '''always''' returns false.
</dd>
</dl>
<!-- DISCONTINUE Notes -->
 
<!-- CONTINUE Notes -->
<dl class="command_description">
<dd class="notedate">Posted on December 8, 2014 - 20:56 (UTC)</dd>
<dt class="note">[[User:DreadedEntity|DreadedEntity]]</dt>
<dd class="note">
You cannot use stacked EH's and non-stacked EH's (just the normal commands, [[onEachFrame]]/[[onMapSingleClick]]/etc.) of the same event together because [[BIS_fnc_addStackedEventHandler]] utilizes these commands in it's code, overwriting a non-stacked EH. Redefining a non-stacked EH will also overwrite all stacked EH's (in that particular event).
 
Stacked Event Handlers are saved to [[missionNamespace]] whenever a new one is added, to view them use:
<code>[[hint]] [[str]] ([[missionNamespace]] [[getVariable]] ["BIS_stackedEventHandlers_XXX",[]]);
where "XXX" is each event name ("[[onEachFrame]]", "[[onPreloadStarted]]", "[[onPreloadFinished]]", "[[onMapSingleClick]]", "[[onPlayerConnected]]", "[[onPlayerDisconnected]]")</code>
</dd>
</dl>
<!-- DISCONTINUE Notes -->

Latest revision as of 17:06, 1 November 2022

Arma 3 logo black.png1.00
LELocal
Hover & click on the images for description

Description

Description:
🕖
This information is obsolete as of Arma 3 v1.58. Reason: Arma 3: Mission Event Handlers should be used instead.

Stacks an event handler. All event handlers accept user arguments, which are passed to the EH code in _this variable. If the EH has own params returned in _this variable as well, user arguments are appended to the end of _this array. Note that if you try to add an empty EH, i.e. with empty code, it will simply be ignored.

Supported Event Handlers
Scripted Event Handler Mission EH Equivalent Description
"onEachFrame" EachFrame N/A
"onPlayerConnected" PlayerConnected Special variables _id, _uid, _name, _jip, _owner are provided and are available in _this array as well.

params ["_id", "_uid", "_name", "_jip", "_owner"];

"onPlayerDisconnected" PlayerDisconnected
"onMapSingleClick" MapSingleClick Special variables _units, _pos, _alt, _shift are provided and are available in _this array as well.

params ["_units", "_pos", "_alt", "_shift"];

"onPreloadStarted" PreloadStarted N/A
"onPreloadFinished" PreloadFinished N/A
Execution:
call
Multiplayer:
This command has the same locality as addMissionEventHandler.
Groups:
Event Handlers

Syntax

Syntax:
[id, event, code, arguments] call BIS_fnc_addStackedEventHandler
Parameters:
id: String - custom id, a unique identifier. Adding same type of EH with the same id will overwrite existing
event: String - event handler name, see description for supported EHs
code: Code or String. The String is treated as function name
arguments: Array of Anything - arguments to make available in code in _this array
Return Value:
String - custom id on success or "" on failure

Examples

Example 1:
["someId", "onEachFrame", { hintSilent str time }] call BIS_fnc_addStackedEventHandler;
Example 2:
["someId", "onEachFrame", {hintSilent str position (_this select 0)}, [player]] call BIS_fnc_addStackedEventHandler;
Example 3:
private _eventName = "OnEachFrame"; missionNamespace getVariable [format ["BIS_stackedEventHandlers_%1", _eventName], []]; // gets an array with all existing ids

Additional Information

See also:
addMissionEventHandler BIS_fnc_removeStackedEventHandler

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note
ffur2007slx2_5 - c
Posted on Jun 25, 2014 - 12:08 (UTC)
Stacking all the code into one PFH will be less demanding than separated calling within multiple PFH, e.g:
{ [format ["%1", _forEachIndex], "onEachFrame", _code, [_x]] call BIS_fnc_addStackedEventHandler; } forEach [var0, var1, varN, var100]; // pretty demanding
[_id, "onEachFrame", { { _x call _code } forEach [var0, var1, varN, var100]; }] call BIS_fnc_addStackedEventHandler; // faster, only one event
Retrieved from "https://community.bistudio.com/wiki?title=BIS_fnc_addStackedEventHandler&oldid=330780"