Step 2: Supporting Setup Strings

OK, so your minimal widget from step 1 is running.

You probably have figured out already that even though the minimal widget does react to fonts and colors dropped on it, those fonts and colors are not saved when the &xcenter; is closed and then re-opened.

Similarly, if you changed the minimal widget to be sizeable (by setting the WGTF_SIZEABLE flag in the ulClassFlags field of XCENTERWIDGETCLASS, you will find out that the widget's size will not be remembered either.

Of course, the &xcenter; could have implemented saving these settings for your widget. But then, where would your widget store additional data that the &xcenter; would not know of? Using the profile functions to store the widget data in OS2.INI would not be a good idea because there can be several instances of your widget, which should all store their data independently.

As a result, I figured that storing widgets data together with the data of the &xcenter; that the widget belongs to would be the best idea.

To make this most flexible and easy to use, the widgets can have setup strings associated with them. If you look at the "Widgets" page in the properties notebook of an &xcenter;, you will see that each widget can have its own setup string to store any data it wants.

Even though the widgets are not Desktop objects themselves, for simplicity, I chose to use the WPS setup string format for the widgets also. That is, your widget can understand, for example, a BACKGROUNDCOLOR=00FF00; setup string, which would set the widget's background color to green.

Your widget class must now implement two things:

Parse a setup string and convert it into binary data that your widget can use. In the above example, for the background color, you could say that the BACKGROUNDCOLOR string would have to be followed by a six-digit RGB hex value. The definition is up to your widget class.
Create a setup string from a set of binary values. This is needed when the data of your widget is about to be saved.

When your widget is created, it receives a previously stored setup string in the pcszSetupString field of its XCENTERWIDGET structure that comes with WM_CREATE. You can then allocate your own structure and store it in XCENTERWIDGET.pUser, parse the setup string, and store the values in there. Of course, you should set up safe defaults if a setup string is missing because there won't be any when your widget is initially created by the user.

Reversely, when your widget's data has changed (e.g. because a new background color has been dropped on it), it should compose a new full setup string. After the new setup string is composed, the widget must send the XCM_SAVESETUP message to its parent window (which is either the &xcenter; client or a tray widget window, if the widget resides in a tray), which will cause the new setup string to be stored together with the other widget data in the &xcenter;'s private data. See center.h for details.

In order to encapsulate the setup string functionality, I recommend that you create a new structure definition for "saveable instance data". This could, for example, contain fields for background, foreground color, and font to be used. For sizeable widgets, this could also include the current size.

This encapsulation allows your widget class to work on setup strings with setup dialogs later also, which can even be invoked when no instance of your widget presently exists.

The minimal sample has no provisions for setup strings. Download the &xwp; source code and look into the src\widgets directory, which has more examples for how this works. XFLDR.DLL also exports a couple of handy functions that you can use to parse setup strings more easily.