diff --git a/README.md b/README.md new file mode 100644 index 0000000..280b44b --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# LiteRyzJS/Timeline + +> LiteRyzJS/Timeline is a basic timeline control written in pure JavaScript with the Canvas API. Formerly, BBTimeline. + +--- + +## Features + +- Basic timeline with JavaScript and Canvas API + +## Screenshots + +[![screenshot](wiki/screenshot-1-h240.png)](wiki/screenshot-1.png) + +--- + +## Releases & Builds + +See [Releases](/Ray/literyzjs-timeline/releases) + +## Documentation + +See [Usage](wiki/USAGE.md) diff --git a/wiki/USAGE.md b/wiki/USAGE.md new file mode 100644 index 0000000..903d8ed --- /dev/null +++ b/wiki/USAGE.md @@ -0,0 +1,345 @@ +# Usage: v0.2.0.121 alpha + +This is the usage guide for [LiteRyzJS/Timeline](/literyzjs-timeline), version 0.2.0.121 alpha. + +## Usage + +### LiteRyzJS.Timeline(el) + +Creates a timeline. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| el | string | Identifier of canvas element | + +#### Examples + +```javascript + + +var timeline1 = new LiteRyzJS.Timeline("myCanvas"); +``` + +### Clear() + +Clear timeline and blank canvas. + +#### Examples + +```javascript +timeline1.Clear(); +``` + +### Invalidate(redrawAxis, redrawMarkers) + +Invalidates and redraws the canvas. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| redrawAxis | bool | Redraw the whole canvas (with the axis and labels only) | +| redrawMarkers | bool | Clear the the contents of the graph and redrawn the markers | + +#### Examples + +```javascript +timeline1.Invalidate(true, true); +``` + +### Load(date) + +Set the start date of the timeline and load the start date. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The start date of the timeline | + +#### Examples + +```javascript +timeline1.Load("2023-10-08"); +``` + +### Show(date) + +Load the timeline starting with the date. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date of the timeline | + +#### Examples + +```javascript +timeline1.Show("2023-10-08"); +``` + +### DateToString(date, pattern) + +Convert a JavaScript date to string using the .NET standard format for date-time. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The start date of the timeline | + +#### Result + +Returned a string of the date-time. + +#### Examples + +```javascript +timeline1.DateToString(new Date(), "yyyy-MM-dd"); +``` + +### ConvertToDate(date) + +Convert a date string "yyyy-MM-dd" into a JavaScript date object. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | + +#### Result + +Returned a JavaScript date object. + +#### Examples + +```javascript +timeline1.ConvertToDate("2023-10-08"); +``` + +### CalcEndDate() + +Calculates the end date displayed on the current view of the timeline. + +#### Result + +Returns a string of the laste date on-screen in "yyyy-MM-dd" format. + +#### Examples + +```javascript +timeline1.DateToString(new Date(), "yyyy-MM-dd"); +``` + +### AddEvent(date, label, options) + +Add an event marker to the timeline. A marker can contain multiple events. + +#### Options + +```javascript +{ + Title: "", + Description: "", + Link: "", + Tag: null +} +``` + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date ("yyyy-MM-dd") | The date of the marker | +| label | string | The label of the marker, null to leave unchanged otherwise update existing label | +| Title | string | Title of the event | +| Description | string | Description of the event | +| Link | string | Link to the event | +| Tag | string | Extra data object for this event | + +#### Examples + +```javascript + const markerName = "Random Marker #" + GetRandy(10000, 99999); + + timeline1.AddEvent(markerDate, markerName, { Title: markerName, Description: "This is a randomly generated marker" }); +``` + +### DeleteMarker(date) + +Delete marker and all events on a date. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | + +#### Examples + +```javascript +timeline1.DeleteMarker("2023-10-08"); +``` + +### UpdateLabel(date, label) + +Update the label on a marker. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | +| label | string | Label text | + +#### Examples + +```javascript +timeline1.UpdateLabel("2023-10-08", "New Label"); +``` + +### UpdateMarker(date, borderColour, backColour) + +Update the style of a marker. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | +| borderColour | Hex colour | Colour of the marker's border | +| backColour | Hex colour | Fill colour of the marker | + +#### Examples + +```javascript +timeline1.UpdateMarker("2023-10-08", "#E68422", "#FAE7D3"); +``` + +### FindDatePosition(date) + +Find the position of the date on the timeline chart. Date must be within the display range of the chart. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | + +#### Result + +Null, if date not found or is not currently visible. + +```javascript +{ + Date: "yyyy-MM-dd", + X: 0 +} +``` + +| Property | Type | Description | +|----------|------|-------------| +| Date | Date (yyyy-MM-dd) | The date | +| X | integer | The horizontal locaton of the marker | + +#### Examples + +```javascript +const coords = timeline1.FindDatePosition("2023-10-08"); +``` + +### FindVisibleEvents() + +Find all markers/events that are within the current visible date range. + +#### Result + +Null, if no markers found. + +```javascript +[{ + Date: date, + Label: "", + Position: { X: 0, Y: 0 }, + Events: [], + HitBox: null, + BorderColour: "#3A5D9C", + BackColour: "#D4DEEF" +}] +``` + +| Property | Type | Description | +|----------|------|-------------| +| Date | Date (yyyy-MM-dd) | The date | +| Label | string | Text label of the marker | +| Position | Point { X: float, Y: float } | The location of the marker | +| Events | Array of Events | An array of events, see *FindEvent*. | +| HitBox | Rectangle { X: float, Y: float, W: float, H: float } | The hitbox or rectangle that repersents the marker and label | +| BorderColour | Hex colour | Colour of the marker border | +| BackColour | Hex colour | Fill colour of the marker | + +#### Examples + +```javascript +const visibleEvents = timeline1.FindVisibleEvents(); +``` + +### FindEvent(date) + +Find a list of events by date (yyyy-MM-dd). + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | + +#### Result + +Null, if no events found. + +```javascript +[{ + Title: "", + Description: "", + Link: "", + Tag: null +}] +``` + +| Property | Type | Description | +|----------|------|-------------| +| Title | string | Title of the event | +| Description | string | Description of the event | +| Link | string | Link to the event | +| Tag | string | Extra data object for this event | + +#### Examples + +```javascript +const events = timeline1.FindEvent("2023-10-08"); +``` + +### FindEventsByCoords(x, y) + +Find a list of events by a point (x, y) on the chart. + +#### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| date | Date (yyyy-MM-dd) | The date | + +#### Result + +Null, if no events found. For results, see *FindEvent*. + +#### Examples + +```javascript +const events = timeline1.FindEventsByCoords(400, 280); +``` diff --git a/wiki/screenshot-1-h240.png b/wiki/screenshot-1-h240.png new file mode 100644 index 0000000..e6bc0cc Binary files /dev/null and b/wiki/screenshot-1-h240.png differ diff --git a/wiki/screenshot-1.png b/wiki/screenshot-1.png new file mode 100644 index 0000000..e57bede Binary files /dev/null and b/wiki/screenshot-1.png differ