VS.Timeline()

You can create a timeline by adding an instance of a VS.Timeline() to a VS.Shape() object:

myTimeline=myShape.AddTimeline(Arrangement);

A timeline divides a shape up into rows and columns (like a VS.Table()) in order to represent a section of time along a bar or line. A timeline may also have an array of VS.Event() objects linked to it.

There are two types of Timeline: Row and Grid. The type is set by the Arrangement value passed to the AddTimeline() method. It can be one of two values:

VS.Timeline_Arrangements =
{
Row1: "Row-1",
Grid1:"Grid-1"
};

Adding a grid row to the Timeline using the AddGridRow() method sets the Arrangement to Grid1 if the Timeline is not a grid already.

If no Arrangement is specified, the timeline is Row1 by default.

The Arrangement also sets default colors, spacing, fonts, event types and so on for the timeline. These can be overridden, but the defaults create a visually appealing style conceived by a designer.

Row Timelines have one row that events link to.

VisualScript timeline

Grid Timelines have multiple rows that events link to.

VisualScript timeline

Any shape can contain a Timeline as long as it doesn't already contain a table. You can think of a Timeline as a special case of a Table object.

You can have as many Timelines on a page as you can have shapes.

A Timeline object will start out as 12 inches long by default and will be formatted automatically to make sure it expands to accommodate any time frame and events added. Events will be positioned to avoid overlapping each other.

VS.Timeline() Methods

These methods return the objects they add:

  • AddDefaultShape() - Adds a DefaultShape object that defines the defaults for all the event shapes added to the Timeline
  • AddEvent() - Adds a VS.Event() object to the Timeline
  • AddGridRow() - Adds a VS.GridRow() to the Timeline

The following methods return the Timeline object and can be chained together:

  • SetAuto() - Overrides the Auto setting for a Timeline
  • SetBubbleLineLength() - Overrides the default length of 1" for a bubble event line.
  • SetDuration() - Sets the length of the timeline in days when there are no events or Auto duration is set to false
  • SetEventPosition() - Overrides the default position setting for Events added to the Timeline
  • SetEventType() - Overrides the default EventType setting for Events added to the Timeline
  • SetStart() - Sets the start date for the Timeline when there are no events or Auto is set to false
  • SetStartTime() - Sets the start time on the start date for the Timeline when there are no events or Auto is set to false
  • SetUnits() - Sets the units for the Timeline when there are no events or Auto is set to false

AddDefaultShape()

Example

myDefaultShape=myTimeline.AddDefaultShape();

Syntax

myDefaultShape=myTimeline.AddDefaultShape();

Usage

This method adds a DefaultShape to a Timeline. The DefaultShape returned is an instance of VS.Shape() and you can use the Shape methods to set the default properties like ShapeType, FillColor and so on for any event shape added to the Timeline. Individual events added with AddEvent() can override these defaults.

AddEvent()

Example

myEvent=myTimeline.AddEvent("2019-1-31");

Syntax

myEvent=myTimeline.AddEvent(datestring);

Usage

This method adds a VS.Event() object to the Timeline. The datestring formatted as YYYY-MM-DD is required otherwise the event is ignored.

AddGridRow()

Example

myGridRow=myTimeline.AddGridRow("Developers");

Syntax

myGridRow=myTimeline.AddGridRow(label);

Usage

This method adds a VS.GridRow() object to the Timeline. The label is the text you want inserted into the first column of the row. The order in which the rows are added defines their index. The first row is 1, not 0. This is important if you later want to assign events to a row using position.

SetAuto()

Example

myTimeline=myTimeline.SetAuto(false);

Syntax

myTimeline=myTimeline.SetAuto(bool);

Usage

By default all timelines have auto formatting set to true. This method allows you to turn off auto formatting and set a fixed range for the timeline.

When Auto is set to true, the starting and ending dates for the timeline are calculated based on the date range for the events and the scale of the timeline. The scale of the timeline is calculated so that

  • All the events will show
  • The column width of a division is wide enough to show it label
  • Enough columns (divisions) will fit in the width of the timeline

If the events occur within a few days of each other, the timeline will format in days. If they are months or years apart, it may format in months, quarters, or years.

If Auto is set false, the start and end dates as well as the divisions or units are set using the properties of the Timeline. Events that fall before or after the timeline's range will be hidden.

SetBubbleLineLength()

Example

myTimeline=myTimeline.SetBubbleLineLength(50);

Syntax

myTimeline=myTimeline.SetBubbleLineLength(length);

Usage

The length of a bubble event line is the length of the line that connects the bubble shape with the timeline. the length parameter is in 1/100". Setting this at the timeline level makes the new length the default for all bubble events added to the timeline.

SetDuration()

Example

myTimeline=myTimeline.SetDuration(365);

Syntax

myTimeline=myTimeline.SetDuration(ndays);

Usage

The duration of a timeline is the number of days between the start date and the end date. You can specify fractions of a day because ndays is a decimal quantity. This value only applies to timelines with no events or with any Timeline whose auto formatting is set to false.

SetEventPosition()

Example

myTimeline=myTimeline.SetEventPosition(VS.Timeline_BubbleEventPositions.AlternateCenter);

Syntax

myTimeline=myTimeline.SetEventPosition(position);

Usage

This method sets the default position for each event linked to the Timeline. An event may override this setting.

Bubble events can have any of the following positions:

VS.Timeline_BubbleEventPositions =
{
Above: "above",
AboveCenter: "above-center",
Below: "below",
BelowCenter: "below-center",
Alternate: "alternate",
AlternateCenter: "alternate-center",
};

Above and Below place the events so they connect at the top or bottom edge of the Timeline. AboveCenter and BelowCenter both connect to the center position of the timeline.

VisualScript timeline above and below

The Alternate option switches the position from Above to Below for every other event. The AlternateCenter option takes turns between AboveCenter to BelowCenter for every other event.

For Grid Timelines the position passed to the method is the index of the row that event should be linked to.

SetEventType()

Example

myTimeline=myTimeline.SetEventType(VS.Timeline_EventTypes.BubbleVertical);

Syntax

myTimeline=myTimeline.SetEventType(eventtype);

Usage

This method sets the default EventType for each event linked to the timeline. An event may override this setting. The following types are supported:

VS.Timeline_EventTypes =
{
Bubble: "Bubble",
BubbleVertical: "Bubble-Vertical",
BubbleTextOnly: "TextOnly",
GridBullet: "Grid-Bullet",
GridBar: "Grid-Bar",
};

VisualScript timeline bubble

Bubble is the default setting where the text appears horizontally inside the shape attached to the Timeline. BubbleVertical makes the text appear perpendicular to the timeline. BubbleTextOnly means that the outline of the shape disappears and you'll only see the text appear, printed vertically above the Timeline.

You can control the shape attached to the timeline using the SetShapeType() method of the event: Circle, Rectangle, Oval, and so on. This can be applied at the DefaultShape level for the entire Timeline.

myDefaultShape=myDefaultShape.SetShapeType(VS.ShapeTypes.Rectangle);

VisualScript grid timeline

Bullet and bar events are designed for a Grid Timeline.

SetStart()

Example

myTimeline=myTimeline.SetStart("2019-2-12");

Syntax

myTimeline=myTimeline.SetStart(datestring);

Usage

This method sets the start date of a Timeline using a YYYY-MM-DD format. This value only applies to a Timeline with no events or with Auto set to false.

SetStartTime()

Example

myTimeline=myTimeline.SetStartTime("10:40:12");

Syntax

myTimeline=myTimeline.SetStartTime(timestring);

Usage

This method lets you get more granular with the start of the Timeline by supplying an hour, minute and second on the previously specified start data. The format is HH:MM:SS. This value only applies to a Timeline with no events or with Auto set to false. If no start time is specified, the time will be 00:00:00 by default.

SetUnits()

Example

myTimeline=myTimeline.SetUnits(VS.TimelineUnit.Month);

Syntax

myTimeline=myTimeline.SetUnits(units);

Usage

The units of a Timeline is the unit of time represented by each column. This value only applies to a Timeline with no events or with Auto set to false. The units possible are:

VS.TimelineUnits =
{
HundredYear: 100, // 100 years in days
FiftyYear: 50, // 50 years in days
TenYear: 10, // Ten years in days
FiveYear: 5, // Five years in days
TwoYear: 2, // Two years in days
Year: 365, // One year in days
Quarter: 92, // one quarter
Month: 31, // one month
Week: 7, // one week
Day: 1, // one day
TwelveHour: -12, // 12 hours
SixHour: -6, // six hours
FourHour: -4, // four hours
TwoHour: -2, // two hours
Hour: -1, // hour
};

VS.Event()

An instance of a VS.Event() is created by adding one to a VS.Timeline() object:

myEvent=myTimelne.AddEvent(Start);

When adding an Event object, you have to specify a start date in a date string formatted as "YYYY-MM-DD".

Events have their own unique methods in addition to many of the methods supported by VS.Shape() including SetShapeType(), SetFillColor(), SetTextFont() and so on.

There are two main types of event: Bubble events and Grid events. Bubble events appear as a shape above or below the Timeline marking their start date and have a line connecting them to it. This works best with traditional timelines that appear as a single row. Grid events appear on the Timeline itself spread out in rows and can show their duration using lines or their width. Grid events work best with grid type timelines.

Bubble Events

VisualScript timeline bubble events

Grid Events

VisualScript grid events

VS.Event() Methods

All of the Event methods return the Event and so can be chained together:

SetBorderThickness()

Example

myEvent=myEvent.SetBorderThickness(5);

Syntax

myEvent=myEvent.SetBorderThickness(thickness);

Usage

Using the SetLineThickness() method of an event (or a Timeline.DefaultShape) sets the thickness of both the line and shape components of an event object. SetBorderThickness() sets only the thickness of the shape border.

SetBubbleLineLength()

Example

myEvent=myEvent.SetBubbleLineLength(50);

Syntax

myEvent=myEvent.SetBubbleLineLength(length);

Usage

The length of a bubble event line is the length of the line that connects the bubble shape with the timeline. the length parameter is in 1/100". Setting this at the event level overrides the default value for this event.

SetDuration()

Example

myEvent=myEvent.SetDuration(7);

VisualScript timeline duration

Syntax

myEvent=myEvent.SetDuration(ndays);

Usage

The duration of an event is the number of days between its start and end. Bubble type events ignore this value and position themselves based only on their start date. Grid events use the duration to control the length of their lines.

SetEventPosition()

Example

myEvent=myEvent.SetEventPosition(VS.Timeline_BubbleEventPositions.Below);

Syntax

myEvent=myEvent.SetEventPosition(position);

Usage

This method overrides the position for an event. The default is set by the Timeline.SetEventPosition() method. The default is Above for bubble events and position 1 (row 1) for grid events.

Bubble events can have any of the following positions:

VS.Timeline_BubbleEventPositions =
{
Above: "above",
AboveCenter: "above-center",
Below: "below",
BelowCenter: "below-center",
};

VisualScript timeline event position

For Grid events, positioning is based on the index of the row. The first row is position 1.

myEvent=myEvent.SetEventPosition(2);

VisualScript timeline event position grid

SetEventType()

Example

myEvent=myEvent.SetEventType(VS.Timeline_EventTypes.BubbleVertical);

Syntax

myEvent=myEvent.SetEventType(eventtype);

Usage

This method overrides the default EventType for the event. The following types are supported:

VS.Timeline_EventTypes =
{
Bubble: "Bubble",
BubbleVertical: "Bubble-Vertical",
BubbleTextOnly: "TextOnly",
GridBullet: "Grid-Bullet",
GridBar: "Grid-Bar",
};

VisualScript timeline event type VisualScript timeline grid event type

You can control the shape of the bubble using the SetShapeType() method of the event. You can choose Circle, Rectangle, Oval, Diamond, or RRect (rounded rectangle).

myEvent=myEvent.SetShapeType(VS.ShapeTypes.Rectangle);

VisualScript timeline bubble shape

SetStart()

Example

myEvent=myEvent.SetStart("2019-2-12");

Syntax

myEvent=myTimeline.myEvent(datestring);

Usage

This method sets the start date of the event formatted as "YYYY-MM-DD".

SetStartTime()

Example

myEvent=myEvent.SetStartTime("10:40:12");

Syntax

myEvent=myTimeline.myEvent(timestring);

Usage

This method sets the start time of event on the start date formatted as "HH:MM:SS". It is optional. If not specified, the time is set to 00:00:00 on the start date.

VS.Shape Methods Supported by Events

Events support the following VS.Shape() events. These control the appearance of the shape and line that make up the Event.

Example

myEvent.SetHyperlink("https://www.visualscript.com");

Syntax

myEvent=myEvent.SetHyperlink(urlstring);

Usage

This method applies a hyperlink to an Event. This appears as a link icon in the bottom right of the bubble. Clicking on the icon opens the hyperlink.

SetFillColor()

Example

myEvent.SetFillColor("#80FF0000");

Syntax

myEvent=myEvent.SetFillColor(color);

Usage

This method overrides the fill color of the Event's shape.

A color can be:

    A string specifying an RGB literal in HTML format - "#FF00FF"

    A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity

    A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetID()

Example

myEvent.SetID(19);

Syntax

myEvent=myEvent.SetID(ID);

Usage

This assigns an Event an arbitrary numeric ID for later use in defining the Event as the start or the end of a VS.Return() object. The ID assigned to each Event should be unique.

SetImage()

Example

myEvent.SetImage("https://wcs.smartdraw.com/working-smarter/img/how-to-write-a-desktop-quality-cloud-app.png");

Syntax

myEvent=myEvent.SetImage(url);

Usage

This places an image inside the Event shape that is loaded from the URL passed.

SetLabel()

Example

myEvent.SetLabel("This is my event");

Syntax

myEvent=myEvent.SetLabel(label);

Usage

This adds text inside the Event. The text automatically wraps inside the shape and may make the shape grow to accommodate it all. You can use the VS.Event.Truncate() method to restrict the length of text that will display and add a tooltip that shows all of the text.

SetLineColor()

Example

myEvent.SetLineColor("#00FF00");

Syntax

myEvent=myEvent.SetLineColor(color);

Usage

This method overrides the border color of the Event as well as set the color of the line connecting it to the Timeline.

A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetLinePattern()

Example

myEvent.SetLinePattern(VS.LinePatterns.Dotted);

Syntax

myEvent=myEvent.SetLinePattern(linepattern);

Usage

This method overrides the pattern of the border of the Event as well as the line connecting it to the Timeline. You can use Dashed, Dotted, or Solid.

SetLineThickness()

Example

myEvent.SetLineThickness(4);

Syntax

myEvent=myEvent.SetLineThickness(thickness);

Usage

This method overrides the thickness of the border and connecting line of the Event which is 1/100" by default. The thickness parameter is in units of 1/100 inch.

SetMinHeight()

Example

myEvent.SetMinHeight(100);

Syntax

myEvent=myEvent.SetMinHeight(height);

Usage

This method overrides the minimum height for an Event which is 75/100" by default. The height parameter is in units of 1/100 inch. Adding text may grow the height or width (or both) to accommodate all of the text. The minimum height is just the smallest height the Event can have even with no text.

SetMinWidth()

Example

myEvent.SetMinWidth(100);

Syntax

myEvent=myEvent.SetMinWidth(width);

Usage

This method overrides the minimum width for an Event, which is 150/100" by default. The width parameter is in units of 1/100 inch. Adding text may grow the Event's height or width (or both) to accommodate all of the text. The minimum width is the smallest height the Event can have even with no text.

SetNote()

Example

myEvent.SetNote("This is a note");

Syntax

myEvent=myEvent.SetNote(label);

Usage

This method adds a note to an Event. A note is a tool tip accessed by hovering or clicking on the note icon.

SetNoteIcon()

Example

myEvent.SetNoteIcon(VS.NoteIcons.Info);

Syntax

myEvent=myEvent.SetNoteIcon(noteicon);

Usage

This method allows you to change the default icon for a note from the yellow note icon to a blue info icon.

SetShapeDataRow()

Example

myEvent.SetShapeDataRow(1,12);

Syntax

myEvent=myEvent.SetShapeDataRow(TableID,RowID);

Usage

An Event may be assigned a row of column values from a VS.DataTable() object. A VS.DataTable() object is added to a document using the VS.Document.AddDataTable() method. DataTables have an array of rows of values for each column in the table. Each row has a unique ID that is assigned as the row is added to the table. SetShapeDataRow() assigns a row in the table to an event using the ID of the row and the table.

SetShapeType()

Example

myEvent.SetShapeType(VS.ShapeTypes.Oval);

Syntax

myEvent=myEvent.SetShapeType(shapetype);

Usage

This method overrides the default shape type for an Event (a rectangle). The supported shape types are:

VS.ShapeTypes =
{
RoundedRectangle: "RRect",
Oval: "Oval",
Circle: "Circle",
Square: "Square",
Diamond: "Diamond",
};

SetTextAlignH()

Example

myEvent.SetTextAlignH(VS.TextAlignH.Left);

Syntax

myEvent=myEvent.SetTextAlignH(textalignh);

Usage

This method sets the horizontal text alignment inside the Event: left, center, right.

SetTextAlignV()

Example

myEvent.SetTextAlignV(VS.TextAlignV.Top);

Syntax

myEvent=myEvent.SetTextAlignV(textalignv);

Usage

This method sets the vertical text alignment inside the Event: top, middle, bottom.

SetTextBold()

Example

myEvent.SetTextBold(true);

Syntax

myEvent=myEvent.SetTextBold(bold);

Usage

This method sets the text inside an Event to bold when true.

SetTextColor()

Example

myEvent.SetTextColor("#0000FF");

Syntax

myEvent=myEvent.SetTextColor(color);

Usage

This method overrides the color of the text inside an Event.

A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetTextFont()

Example

myEvent.SetTextFont("Copperplate");

Syntax

myEvent=myEvent.SetTextFont(fontname);

Usage

This method overrides the font setting of the text inside an Event.

SetTextGrow()

Example

myEvent.SetTextGrow(VS.TextGrow.Horizontal);

Syntax

myEvent=myEvent.SetTextGrow(grow);

Usage

This method sets the way the shape representing the Event grows as text is added. There are three values possible:

VS.TextGrow = {
Proportional:"Proportional",
Horizontal: "Horizontal",
Vertical: "Vertical",
};

Example

myEvent.SetTextHyperlink("https://www.visualscript.com");

Syntax

myEvent=myEvent.SetTextHyperlink(url);

Usage

This method adds a hyperlink to the text inside an Event.

SetTextItalic()

Example

myEvent.SetTextItalic(true);

Syntax

myEvent=myEvent.SetTextItalic(italic);

Usage

This makes the text inside an Event italic when set to true.

SetTextMargin()

Example

myEvent.SetTextMargin(10);

Syntax

myEvent=myEvent.SetTextMargin(margin);

Usage

This method overrides the spacing between the edge of the Event's shape and the text inside.

SetTextSize()

Example

myEvent.SetTextSize(18);

Syntax

myEvent=myEvent.SetTextBold(textsize);

Usage

This method overrides the default text size inside an Event using points.

SetTextTruncate()

Example

myEvent.SetTextTruncate(30);

Syntax

myEvent=myEvent.SetTextTruncate(nchar);

Usage

This method restricts the number of characters that can appear inside an Event bubble to the value passed. If this is less than the actual number of characters, a note with the full text is automatically added to the Event that you can access by hovering over the icon.

SetTextUnderline()

Example

myEvent.SetTextUnderline(true);

Syntax

myEvent=myEvent.SetTextUnderline(underline);

Usage

This method underlines any text inside an Event when set to true.