Simplified access to the DCS Toolbox object from C

I’ve been meaning to make a post about this for months! :)

When writing Seasonal earlier this year I became frustrated with the amount of “plumbing” code required for the DCS (Discard/Cancel/Save) Toolbox object. I had to manually show DCS when the window was closed, or when a user selected to quit my app, or when it was quit through the Task Manager, or when the user shut down the system… and then I had to abort or resume the shutdown… as you can tell, this quickly became a bit of a mess.

My solution to this was to write a C library that handles most of the work automatically. You include DCSHelper in your app and perform some simple initial setup, and then you indicate whether the document is “dirty” (i.e. has unsaved changes). DCSHelper will automatically fire when it sees Wimp_PreQuit, or you can easily pop up the DCS object manually.

I should note right off the bat that DCSHelper currently only works with single-document apps. I’d love to extend it to support multiple documents, but that support doesn’t currently exist. It makes use of the Toolbox (naturally) and Eventlib.

If you’re still interested, the library is available on my site for free (click on the green arrow). I’ve written up some basic documentation but I know that it’s a bit lacking, so feel free to ask any questions here :)

A quick summary of what to do:

• Call dcshelper_initialise and pass in the IDs of the DCS and SaveAs objects, plus the name of a function that makes your app quit. This is so that DCSHelper can trigger a “clean” quit once a save or discard is complete.
• Call dcshelper_set_dirty to indicate whether or not there are unsaved changes. With this set to true, DCSHelper will automatically pop up on quit or shutdown, and will abort and resume the shutdown process as required.
• Call dcshelper_show to manually show the DCS window. You’ll need to do this when the document is closed, or when the user quits your app from its icon bar icon, as DCSHelper doesn’t otherwise know that either of these actions are taking place.