Skip to Content
API ReferenceEvents

🎯 Events API

The Events API provides callbacks for handling chart events, including trading actions, alerts, data downloads, and UI interactions.

📋 Event Callbacks

The GoCharting SDK provides three main event callbacks:

appCallback

Handles all chart events including trading, alerts, data downloads, and UI interactions.

Signature:

appCallback?: (event: {
	eventType: AppCallbackEventType,
	message: AppCallbackMessage,
	onClose?: () => void
}) => void;

Parameters:

  • event.eventType (AppCallbackEventType): Type of event (see Event Types below)
  • event.message (AppCallbackMessage): Event data/payload (structure varies by event type)
  • event.onClose (() => void, optional): Callback to close dialogs or UI elements

onReady

Called when the chart is ready and initialized.

Signature:

onReady?: (chartInstance: ChartInstance) => void;

Parameters:

  • chartInstance (ChartInstance): The chart instance with all control methods
Note

This receives the ChartInstance (React component), NOT the ChartWrapper returned by createChart().

onError

Called when an error occurs during chart initialization or operation.

Signature:

onError?: (error: Error | string) => void;

Parameters:

  • error (Error | string): Error object or message

🎭 Event Types

Trading Events

PLACE_ORDER

Triggered when a user places an order.

Message Type: PlaceOrderMessage

{
	order: Order;           // Order details
	securityInfo: SecurityInfo; // Symbol information
}

Example:

appCallback: ({ eventType, message, onClose }) => {
	if (eventType === "PLACE_ORDER") {
		const { order, securityInfo } = message;
		console.log("Place order:", order);
 
		// Place order via your broker API
		placeOrder(order).then(() => {
			onClose(); // Close order dialog
		});
	}
}

MODIFY_ORDER

Triggered when a user modifies an existing order.

Message Type: ModifyOrderMessage

{
	order: Order;           // Modified order details
	securityInfo: SecurityInfo;
}

CANCEL_ORDER

Triggered when a user cancels an order.

Message Type: CancelOrderMessage

{
	orderId: string;        // Order ID to cancel
	securityInfo: SecurityInfo;
}

MODIFY_POSITION

Triggered when a user modifies a position (e.g., adds stop loss or take profit).

Message Type: ModifyPositionMessage

{
	position: Position;     // Position details
	securityInfo: SecurityInfo;
}

EXIT_ALL_POSITIONS

Triggered when a user requests to exit all positions.

Message Type: ExitAllPositionsMessage

{
	accountId: string;      // Account ID
}

CANCEL_ALL_ORDERS

Triggered when a user requests to cancel all orders.

Message Type: CancelAllOrdersMessage

{
	accountId: string;      // Account ID
}

Alert Events

CREATE_ALERT

Triggered when a user creates an alert.

Message Type: AlertMessage

{
	alert: {
		symbol: string;
		price: number;
		condition: "above" | "below";
		message?: string;
	};
}

DELETE_ALERT

Triggered when a user deletes an alert.

MODIFY_ALERT

Triggered when a user modifies an alert.

Data Events

DOWNLOAD_MORE_DATA

Triggered when a user requests to download more historical data.

Message Type: DownloadDataMessage

{
	symbol: string;
	interval: string;
	from: Date;
	to: Date;
}

DOWNLOAD_MORE_DATA_BY_DATE

Triggered when a user requests to download data for a specific date range.

UI Events

OPEN_SETTINGS

Triggered when a user opens the settings dialog.

OPEN_LAYERS

Triggered when a user opens the layers panel.

OPEN_OBJECT_PROPERTIES

Triggered when a user opens object properties dialog.

OPEN_INDICATORS_MODAL

Triggered when a user opens the indicators modal.

Chart Events

CHART_SELECTED

Triggered when a user selects a chart in multi-chart mode, or on initialization in single chart mode.

Message Type: ChartSelectedMessage

{
	id: string;        // Chart ID
	chartId: string;   // Chart ID
	idx: number;       // Chart index
	symbol: string;    // Symbol
	interval: string;  // Interval
}

CHART_MODE_CHANGED

Triggered when multi-charting is enabled or disabled (i.e., when the layout switches between single-chart and multi-chart mode).

Message Type: MultiChartInfo

{
	isMultichartingEnabled: boolean;   // Whether multi-charting is now enabled
	charts: ChartSelectedMessage[];   // Array of all chart details
}

Example:

appCallback: (eventType, message) => {
	if (eventType === "CHART_MODE_CHANGED") {
		if (message.isMultichartingEnabled) {
			console.log(`Multi-charting enabled with ${message.charts.length} charts`);
			message.charts.forEach(chart => {
				console.log(`  Chart ${chart.idx}: ${chart.symbol} @ ${chart.interval}`);
			});
		} else {
			console.log("Switched to single chart mode");
		}
	}
}

💡 Usage Examples

Example 1: Basic Event Handling

import { createChart } from "@gocharting/chart-sdk";
 
const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
 
	appCallback: ({ eventType, message, onClose }) => {
		console.log("Event:", eventType, message);
	},
 
	onReady: (chartInstance) => {
		console.log("Chart ready");
	},
 
	onError: (error) => {
		console.error("Chart error:", error);
	},
});

Example 2: Trading Event Handling

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
	trading: {
		enableTrading: true,
	},
 
	appCallback: async ({ eventType, message, onClose }) => {
		switch (eventType) {
			case "PLACE_ORDER":
				const { order, securityInfo } = message;
				try {
					await brokerAPI.placeOrder(order);
					showNotification("Order placed successfully");
					onClose(); // Close order dialog
				} catch (error) {
					showError("Failed to place order: " + error.message);
				}
				break;
 
			case "MODIFY_ORDER":
				await brokerAPI.modifyOrder(message.order);
				onClose();
				break;
 
			case "CANCEL_ORDER":
				await brokerAPI.cancelOrder(message.orderId);
				onClose();
				break;
 
			case "MODIFY_POSITION":
				await brokerAPI.modifyPosition(message.position);
				onClose();
				break;
		}
	},
 
	onReady: (chartInstance) => {
		// Set broker accounts when ready
		chartInstance.setBrokerAccounts({
			accountList: accounts,
			orderBook: orders,
			tradeBook: trades,
			positions: positions,
		});
	},
});

Example 3: Alert Event Handling

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
 
	appCallback: ({ eventType, message, onClose }) => {
		if (eventType === "CREATE_ALERT") {
			const { alert } = message;
			console.log("Alert created:", alert);
 
			// Save alert to your backend
			saveAlert(alert).then(() => {
				showNotification("Alert created successfully");
				onClose();
			});
		} else if (eventType === "DELETE_ALERT") {
			// Handle alert deletion
			deleteAlert(message.alertId);
		}
	},
});

Example 4: Data Download Event Handling

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
 
	appCallback: ({ eventType, message, onClose }) => {
		if (eventType === "DOWNLOAD_MORE_DATA") {
			const { symbol, interval, from, to } = message;
			console.log(`Download data: ${symbol} ${interval} from ${from} to ${to}`);
 
			// Trigger data download
			downloadData(symbol, interval, from, to);
		}
	},
});

Example 5: Complete Event Handling

const chart = createChart("#chart", {
	symbol: "AAPL",
	interval: "1D",
	datafeed: myDatafeed,
	licenseKey: "YOUR_LICENSE_KEY",
	trading: {
		enableTrading: true,
	},
 
	appCallback: async ({ eventType, message, onClose }) => {
		console.log("Event:", eventType, message);
 
		// Trading events
		if (eventType === "PLACE_ORDER") {
			await handlePlaceOrder(message, onClose);
		} else if (eventType === "MODIFY_ORDER") {
			await handleModifyOrder(message, onClose);
		} else if (eventType === "CANCEL_ORDER") {
			await handleCancelOrder(message, onClose);
		}
 
		// Alert events
		else if (eventType === "CREATE_ALERT") {
			await handleCreateAlert(message, onClose);
		}
 
		// Data events
		else if (eventType === "DOWNLOAD_MORE_DATA") {
			await handleDownloadData(message);
		}
 
		// UI events
		else if (eventType === "OPEN_SETTINGS") {
			console.log("Settings opened");
		}
	},
 
	onReady: (chartInstance) => {
		console.log("Chart ready");
		// Initialize trading features
		chartInstance.setBrokerAccounts(brokerData);
	},
 
	onError: (error) => {
		console.error("Chart error:", error);
		showErrorNotification(error);
	},
});

🔗 Related Documentation

For complete working examples, see the Examples section.

Last updated on
Data FeedTime Marks