SRP Controls – When Methods are Better than Properties

As any developer knows, end users are often teaching us programmers a few things from time to time. They instruct us to better understand their work flow. They point out flaws in our assumptions, especially regarding what we think is easy to use. They also help to expose gaps in our documentation.

Such became the case in a recent discussion forum thread involving the SRP Schedule control. In this case, the end user (i.e., a developer programming the control) found out that she could crash OpenInsight or produce some interesting visual anomalies through the repeated use of the TimeBlockList property. This certainly revealed a bug within the SRP Schedule control’s inner workings which we were quick to fix. However, it begged an important question: why had this gone unnoticed before, especially during our own internal testing?

The simple answer was because we never attempt to use the TimeBlockList property more than once during the same session. The TimeBlockList property is intended to populate multiple time blocks at once, being ideal for when the software is launched and pre-existing time blocks needed to be displayed quickly. Any new time blocks were intended to be created using the AddTimeBlocks method. Even the documentation for the AddTimeBlocks method notes that “this is also more efficient than updating the TimeBlockList property, since that property will remove all time blocks and re-add them.” This was all meant to follow a standard SRP practice of using properties to handle the heavy lifting during an initialization process and then use methods to handle the smaller changes during run-time use of the software.

So how is the end user, a developer using the SRP controls, supposed to have known this? Therein lies the dilemma. Without the gift of mind reading or perhaps having read (and remembered) every property and method on our wiki, no developer could have been expected to know this. This revealed both a gap and a false assumption on our part within our own documentation. We won’t be too hard on ourselves. Documentation is a challenging effort. We strive hard to keep the technical bits accurate and current. The real deficit exists in the how-to and best practices department. While we are aware of this, we also find ourselves overlooking these gaps since we ourselves are rather familiar with our own products.

So with this article we will begin to offer best practice advice when using SRP ActiveX Controls. In this piece we will focus upon the aforementioned relationship between certain properties and methods. As many of our customers know, some controls can contain large amounts of complex application data. This is evident in controls like the SRP EditTable and SRP ReportTable. A standard approach we have developed is to give developers a single property that takes a complex multivalue array to initialize the control. For example, the SRP EditTable control provides a single LIST or ARRAY property (like the native OpenInsight edit table control). These are ideal for populating the SRP EditTable when the record is read. But when the end user is allowed to add or remove data via a separate UI (e.g., a dialog box, as opposed to directly within the control), then reusing the LIST or ARRAY properties to refresh the display becomes rather inefficient. Thus, methods like AddNewRecords, DeleteRecords, and INSERT were created to simplify the task and optimize the performance.

Some controls blur the lines between what is considered application data and what is considered configuration parameters. The SRP Tree control and the SRP Popup controls are good examples of this. For instance, both have an ItemList property that developers can use to populate both the content (e.g., text) and the visual formatting of that content (among other things.) If the SRP Tree’s ItemList property were repopulated this would force the default properties to be activated, thus causing unexpected visual behavior as well (such as collapsing or expanding items.) Therefore, both controls have their respective AddItems method which allows the developer to discretely add items while leaving the existing ones alone.

Our last bit of advice on this topic is to pay attention to the properties and/or methods which are listed under the “See Also” label at the bottom of most documentation articles. These should always refer the reader to the associated method (if viewing the property) or associated property (if viewing the method). Of course, if the documentation appears to be out of sync please don’t hesitate to let us know. Happy programming.