The Environment.RightScreenTime property returns a DateTime value with the date and time coordinate from the very right of the current chart window (PowerLanguage .NET Help, n.d.). This property returns its value in indicator, signal, and function scripts.

The date and time value from the chart’s very right that Environment.RightScreenTime returns can be a timestamp of a price bar (when there’s a bar in that utmost right area) or some future time and date in case there’s a ‘Chart Shift’ between the last price bar and the chart’s price axis:

Example of the value returned by MultiCharts .NET's Environment.RightScreenTime property

Example: drawing a vertical trend line in the chart’s right margin

When we scroll the chart to the right (so that it shows the current price bar), Environment.RightScreenTime helps to determine if some future time and date value already appears on the chart. With this we can have our script ‘wait’ till some future date and time appears on the chart, and then place the drawing at that chart location.

By first seeing if the future date and time appears on the chart, we ensure that the chart can actually display the drawing at that location. And so in the example indicator below we check the value of Environment.RightScreenTime before placing a vertical trend line 4 hours past the last price bar on the chart.

using System;
using System.Drawing;
using System.Linq;
using PowerLanguage.Function;

namespace PowerLanguage.Indicator
{
    [SameAsSymbol(true), RecoverDrawings(false)]
    public class TradingCode_Reference_Indicator : IndicatorObject
    {
        public TradingCode_Reference_Indicator(object _ctx) : base(_ctx) { }

        private ITrendLineObject verticalLine;

        protected override void StartCalc()
        {
            verticalLine = null;
        }

        protected override void CalcBar()
        {
            // To prevent making several trend lines, we only draw one
            // when `verticalLine` is `null`.
            if (Bars.LastBarOnChart && (verticalLine == null) && 
                (Bars.Close[0] < Bars.Close[2]))
            {
                // The intended location is 4 hours past the last bar on the chart
                DateTime futureTime = Bars.Time[0].AddHours(4);

                // Only draw the line when that future time is within
                // the visible chart area; otherwise, generate an error
                if (futureTime < Environment.RightScreenTime)
                {
                    verticalLine = DrwTrendLine.Create(
                        new ChartPoint(Bars.Time[0].AddHours(4), Bars.High[0]),
                        new ChartPoint(Bars.Time[0].AddHours(4), Bars.Low[0]));

                    // Change the line's appearance and extend it in both ways
                    verticalLine.Size     = 2;
                    verticalLine.Color    = Color.RoyalBlue;
                    verticalLine.ExtLeft  = true;
                    verticalLine.ExtRight = true;
                }
                else
                {
                    ExecControl.Abort(
                        "The trend line cannot accurately display on the chart.");
                }
            }
        }
    }
}

When we add this example indicator to the chart, that vertical trend line in the future looks like:

MultiCharts .NET chart with a trend line drawn into the future

If the chart’s ‘Chart Shift’ option (see Environment.ChartShiftBars and Environment.ChartShiftPcnt) isn’t set to a value high enough to display that future time and date, we trigger a custom error message with ExecControl.Abort(). This way we’re notified that the script cannot draw its trend line due to our chart setting.

Custom error message: the trend line cannot appear on the MultiCharts .NET chart

Notes for Environment.RightScreenTime

The value returned by Environment.RightScreenTime depends on the values that currently display on the chart’s time axis. And so anything that changes which values show on the time axis (like scrolling the chart, zooming in or out, and changing the size of the chart window itself) also alters the value returned by Environment.RightScreenTime.


Environment.RightScreenTime returns a date and time value of December 30, 1899 at 0:00:00 o’clock in the Portfolio Trader and Scanner/Watchlist. We can use the Environment.ApplicationCode property to determine where the script currently runs.


The value of Environment.RightScreenTime is very right timestamp of the current chart window. To get the time and date of the instrument’s last price bar, use the Bars.FullSymbolData.Time[] property like this:

int indexLastBar = Bars.FullSymbolData.Count - Bars.FullSymbolData.Current;

DateTime timeLastBar = Bars.FullSymbolData.Time[-indexLastBar];

Besides Environment.RightScreenTime, there are three other properties with extreme values from the chart’s axes.

Those are Environment.LeftScreenTime (for the time and date of the leftmost price bar in the current chart window), Environment.HighestScaleValue and Environment.LowestScaleValue. These latter two return the highest and lowest value that currently shows on the chart’s price axis (PowerLanguage .NET Help, n.d.).


In terms of script calculation phase, we can use Environment.RightScreenTime in the StartCalc(), CalcBar(), StopCalc(), and Destroy() override methods (MultiCharts, 2014).


Tips for Environment.RightScreenTime

As mentioned above, anything that affects the chart’s time axis (like scrolling and new price bars) also changes the value of Environment.RightScreenTime. If we use this property to position drawings on the chart and update their location, we best recalculate our script periodically.

That way when the instrument’s trading is closed and we do something like scrolling or zooming the chart, the script’s periodic calculations can still update the drawing to the then-current Environment.RightScreenTime value. We create those time-based recalculations with the ExecControl.RecalcLastBarAfter() and OnRecalcLastBarAfterEvent() methods.


Summary

Features of Environment.RightScreenTime
Name Environment.RightScreenTime
Description Returns the date and time of the current chart window’s very right.
Category Environment information
Type property
Returns A DateTime value
Usable in Indicator, signal, and function scripts
Available since (beta release date) MultiCharts .NET 8.0 (July 31, 2012)
Related code elements
Environment.BGColor Returns a Color value with either the background colour of the chart or the Scanner/Watchlist row.
Environment.BarSpacing Returns the chart’s current bar spacing in pixels.
Environment.ChartShiftBars Returns the price chart’s current ‘Chart Shift’ setting in number of price bars.
Environment.ChartShiftPcnt Returns the price chart’s current ‘Chart Shift’ setting as a percentage of the chart window’s size.
Environment.HighestScaleValue Returns the highest value of the price axis from the currently displayed chart area.
Environment.LeftScreenTime Returns the date and time value of the current chart window’s very left price bar.
Environment.LowestScaleValue Returns the lowest value of the price axis from the currently displayed chart area.

References

MultiCharts (2014). MultiCharts .NET Programming Guide (version 1.1). Retrieved from http://www.multicharts.com/downloads/MultiCharts.NET-ProgrammingGuide-v1.1.pdf

PowerLanguage .NET Help (n.d.). Retrieved on September 27, 2016, from http://www.multicharts.com/downloads/PowerLanguage.NET.chm