Getting started with DCSHelper

Before you can use DCSHelper, you need to initialise it by using dcshelper_initialise. DCSHelper needs to know the Toolbox Object IDs of both the DCS object and a SaveAs object. It also needs to know how to proceed to quit your app once the data has been saved or discarded.     

You will often call dcshelper_initialise from a Toolbox_ObjectAutoCreated event once you have the relevant IDs. For example:

#include "dcshelper.h"
ObjectId DCS;
ObjectId SaveAs;

int toolbox_objectautocreated_event(int event_code, ToolboxEvent *event, IdBlock *id_block, void *handle)
{
	ToolboxObjectAutoCreatedEvent *evt = (ToolboxObjectAutoCreatedEvent *)event;
	if (strcmp(evt->template_name, "DCS") == 0)
	{
		DCS = id_block->self_id;
	}
	else if (strcmp(evt->template_name, "SaveAs") == 0)
	{
		SaveAs = id_block->self_id;
	}
	if (DCS && SaveAs)
	{
		dcshelper_initialise(DCS, SaveAs, quit);
	}
	return 1;
}

void quit(void)
{
	exit(EXIT_SUCCESS);
}

Once DCSHelper has been initialised, there are two different ways to trigger it. The first way is to explicitly show it by using dcshelper_show.

You may want to call this when the user chooses to quit your application. Note that despite having a quit function set up in dcshelper_initialise, DCSHelper will not automatically quit your app when it has been called via dcshelper_show. This allows you to call dcshelper_show at any time, without necessarily quitting your app. If you do want to quit your app, then simply pass in the same function as you did with dcshelper_initialise. For example:

int quit_menuitem_event(int event_code, ToolboxEvent *event, IdBlock *id_block, void *handle)
{
	if (document_is_unsaved)
	{
		dcshelper_show(quit);
	}
	else
	{
		quit();
	}
	return 1;
}

The other way to use DCSHelper is to notify it that there is unsaved data by using dcshelper_set_dirty, and then let it trigger itself. It will do this when your app receives a Wimp_PreQuit message (such as if the app is quit from Task Manager or when the system is shut down) but not when the user selects Quit from the application's icon bar menu.

For example, when new data has been entered:

dcshelper_set_dirty(true);