DCSHelper Reference

dcshelper_initialise

void dcshelper_initialise(ObjectId dcs, ObjectId save_as, QuitEvent evt);

This function is used for initial setup of DCSHelper. Your application needs to provide DCS and SaveAs objects in its resource file. You then use dcshelper_initialise to make DCSHelper aware of the objects' IDs.

In addition to the object IDs, you also need to provide a QuitEvent function. This is so that DCSHelper is able to cleanly quit your app when required (such as after data has been saved).

void evt(void);

dcshelper_show

void dcshelper_show(DCSCompletedCallback cb);

This function is used to show the DCS object. You may wish to use this function when a document window is closed.

The function passed into DCSCompletedCallback will be called once the DCS operation is complete. For the example of closing a window, cb should actually perform the close. It will be called if the data is saved or discarded, but not if the operation is cancelled.

void cb(void);

dcshelper_set_dirty

void dcshelper_set_dirty(bool value);

This function allows you to inform DCSHelper of whether the data is "dirty", that is whether it has any unsaved changes. If this flag is set then DCSHelper will automatically trigger when your application receives a Wimp_PreQuit message (such as when the application is quit from Task Manager or when the system is shut down).

dcshelper_get_dirty

bool dcshelper_get_dirty(void);

This function allows you to determine the current state of DCSHelper's "dirty" flag. It was added in DCSHelper 1.10.

dcshelper_register_savecompleted_event

void dcshelper_register_savecompleted_event(SaveCompletedEvent evt);

This function allows you to register your own event handler on the SaveAs object's SaveCompleted event. Your handler will be called immediately upon receiving a SaveCompleted event, before DCSHelper does anything of its own. This handler could potentially be used to perform post-save cleanup work.

It is preferable to use this function instead of the standard event_register_toolbox_handler function, as otherwise it may conflict.

You can register a single function. Calling dcshelper_register_savecompleted_event a subsequent time will replace the existing handler.

void evt(int event_code, ToolboxEvent *event, IdBlock *id_block, void *handle);

dcshelper_register_prequit_event

void dcshelper_register_prequit_event(PreQuitEvent evt);

This function allows you to register your own event handler on the Wimp_PreQuit message. Your handler will be called immediately upon receiving a Wimp_PreQuit message, before DCSHelper does anything of its own. This handler could potentially be used to get your app into a "quittable" state, but please note that the actual DCS prompt will not yet have appeared when your handler is called.

It is preferable to use this function instead of the standard wimp_register_message_handler function, as otherwise it may conflict.

You can register a single function. Calling dcshelper_register_prequit_event a subsequent time will replace the existing handler.

void evt(WimpMessage *message, void *handle);