タイマーにテキスト、プロセスバーなどを表示するコンポーネントを提供するプラグイン – SRCrazy_TimerDisplay.js

============================================================================
S_Rank_Crazy's Timer Display Plugin
============================================================================
This plugin provides a timer display that can be customised either through
the Plugin Manager, or when created through a Script Call.

If you're using the MVCommons or PluginManagement plugins then any dependency
issues will be output as errors when the game loads.

All SRCrazy plugins are rename safe - you can rename the file and it'll still
work. All parameters and commands are case-safe (no need to worry about
case-sensitive input) unless specifically stated. This doesn't include
Comment Tags or file names/paths; they are still case sensitive.

MVCommons supported but not required for use.

============================================================================
USAGE

The TimerDisplay can be set up in the Plugin Manager to be configured in
many different ways, which allows for script calls to be relatively easy to
implement in the Event Editor for displays that are consistent in their
appearance and/or behaviour. However, if you need to have different "types"
of displays you have all of the same configuration settings available to
you for the creation of each individual TimerDisplay.


-----------------
Creating Timers
-----------------

The plugin can be accessed through the SRCrazy global namespace at:

SRCrazy.Plugins.TimerDisplay

The plugin has a `construct` method which can be used to create a timer
by supplying a descriptor to the function call:

SRCrazy.Plugins.TimerDisplay.construct({ duration: 10 });

The above call will create a TimeDisplay with the default settings that will
be removed after 10 seconds. The descriptor can contain a number of different
options which will customise how it looks and behaves. If any of the options
are omitted, the plugin's defaults (as found in the Plugin Manager) will be
used.

Here's a list of all of the options that can be used:

name - The name of the TimerDisplay, can be used to destroy the timer at a
later point
duration - The amount of time (or number of frames) to run the timer for
useFrames - Indicates whether the timer uses seconds (real time) or frames

x - The position of the TimerDisplay on the x-axis
y - The position of the TimerDisplay on the y-axis
width - The width of the TimerDisplay
height - The height of the TimerDisplay

switchId - Triggers the switch when the timer completes. If the switch is
on, switch is turned off and vice versa.
variableId - Sets the current progress of the timer in the specified
variable
commonEventId - Triggers a Common Event when the timer completes

showWindow - Indicates whether hte display shows a Window
showBar - Indicates whether the display shows a timer bar

barX - The position of the bar on the x-axis
barY - The position of the bar on the y-axis
barWidth - The width of the bar
barHeight - The height of the bar
barColour1 - The colour used for the left side of the bar
barColour2 - The colour used for the right side of the bar
barColourBg - The colour used for the background of the bar

showBackgroundImage - Indicates whether an image is to be displayed behind
the bar
backroundImage - The path to the image to display

showForegroundImage - Indicates whether an image is to be displayed in front
of the bar
foregroundImage - The path to the image to display


----------------------------
Creation through Shorthand
----------------------------

1. The Shorthand Function

The plugin provides a customisable function that is made available in the
global scope of the window. In short, you can (re)name a function and decide
what it's parameters are (from a support list, see below) and then use that
function in a Script Call to create TimerDisplays more easily.

By default the Shorthand Function (SHF) is set up to be:
timedbar(x, y, duration, useFrames);

`timedbar` is the name of the function, and the function's parameters are
set to be `x, y, duration, useFrames`. To use this default set-up, use the
following in a Script Call:

timedbar(10, 10, 5, false);

The above example will display a window at position [10,10] and will be
removed after 5 seconds. Passing true or to the `useFrames` parameter will
translate the `duration` value as the number of frames to count. If any
parameters are omitted then their values will default to the values
specified in the Plugin Manager.

Additional methods can be called once the timedbar function has been called
in order to update a variable, switch or trigger an event. These methods are:

assignToVariable(variableId);
This sets the current progress of the bar the specified variable

assignToSwitch(switchId);
This flips a switch when timer is complete. If the switch is on, switch is
turned off and vice versa.

assignToCommonEvent(commonEventId);
This calls a Common Event when the timer is complete.

These methods can be chained in order to use a combination of them.

Eg:
timedbar(10, 10, 5).assignToVariable(1).assignToSwitch(1);

This will create the display as before but also update variable with ID 1
every frame, and then change switch with ID 1 when complete.



2.Shorthand Function Parameters

The SHF's parameters don't always have to be `x, y, duration, useFrames`,
you can customise what properties you want to control and in which order they
are passed in to the SHF. For exmaple, if you wanted to only ever set the
duration and the colour(s) use for the bar when calling the SHF you can set it
up to look like this:

timedbar(duration, barColour1, barColour2);

For a full list of the supported values for the "Shorthand function parameters"
parameter in the Plugin Manager, see the above section on "Creating Timers".


-----------------
Managing Timers
-----------------

If the timer is provided with a name upon creation, it can be manually
managed through other Script Calls to pause/unpause and destroy it...

SRCrazy.Plugins.TimerDisplay.pause(timerName, hide);
This pauses the named timer (if found), and optionally hides it.

SRCrazy.Plugins.TimerDisplay.unpause(timerName, show);
This unpauses the named timer (if found), and optionally shows it.

SRCrazy.Plugins.TimerDisplay.destroy(timerName);
This destroys the named timer (if found).

Similarly to the Shorthand function (see above), these three methods can
also been added to the global scope to make calling them less cumbersome.
These are also set up in the SCRIPT CALL section of the Plugin PArameters
section of the Plugin Manager.

============================================================================
TERMS OF USE

Free for commercial and non-commercial use. No credit need be given, but
always appreciated.

============================================================================
COMPATIBILITY

Requires SRCrazy_Core and SRCrazy_Timer plugins.

============================================================================