Programming Controls

Requirements for Controls

Input Storage and Input Validation

Firstly, the number in our edit box is in a string form and must therefore be converted to a number. The number conversion may fail due to an invalid syntax, or the converted number may lie outside a pre-defined valid input range, in which case the dialog box must not close. Instead, focus should be set to the edit control and an error message displayed. This validation process is conveniently and automatically handled through defining and implementing the virtual method canApply(). This method is called by the standard keyboard navigation code when the OK or Apply buttons are pressed. The canApply() method returns true or false depending upon if the input data is valid. In the case of failure (false), the canApply() method will set the pFailedWindow pointer reference (passed in as an argument to canApply()) to itself. By doing so the navigation code will then know which window to set input focus to. During this checking process canApply() should also build an error message describing the problem. When a canApply() failure occurs the standard navigation code will call the virtual showError() method to display the error message. Therefore you will have to implement the showError() method along side canApply() when implementing controls that receive input data. As an example, consider the case of the GuiRealEditBox control. This control implements these methods as,

bool GuiRealEditBox::canApply(GuiWindow*& pFailedWindow)
{
  bool bCanApply = this->apply(true);

  if (!bCanApply && pFailedWindow == 0)
  {
    pFailedWindow = this;
  }

  return (bCanApply);
}

void GuiRealEditBox::showError() const
{
  GuiApp  App;

  ::MessageBox(handleWindow(),
               ApplyErrorMessage,
               App.applicationName(),
               MB_ICONEXCLAMATION);
}

The conversion work is actually done in the apply() method call which does the conversion and builds the error message which it stores in the class attribute ApplyErrorMessage. When true is specified in the apply() method call it means that a test apply operation will be carried out. By test we mean that the data will be validated but not stored. 

What happens if canApply() succeeds? If canApply() succeeds standard navigation code will continue to query all child controls of the dialog until all children have returned true to the canApply() call. If that happens then the standard navigation code will call the virtual apply() method for all children of the dialog box. When this happens the control should do the conversion (which should always succeed) and store the result somewhere. In AtOne this is customarily supported through the concept of an "associated storage". All this essentially means is that the control maintains a pointer to a destination buffer where it will write the control input to. By convention this pointer is initialised through a method called associateStorage(), which takes as its argument, a reference to the result buffer. In the GuiRealEditBox control this method is,

void GuiRealEditBox::associateStorage(double& rStorage)
{
  OsiString Default;

  Storage = &rStorage;

  Default.sprintf(_T("%.*g"), Precision, *Storage);
  caption(Default);
  notifyParent(EN_CHANGE);
}

and is used to initialise the storage location attribute (Storage) and to synchronise the edit box text with the value currently in the storage buffer. The apply() method is,

bool GuiRealEditBox::apply()
{
  GuiWindow::apply();

  return (apply(false));
}

and is used to convert the data and write the result into the buffer specified in associateStorage(). Note that for the apply method we always call the parent apply()  method that we have over-ridden to ensure correct behaviour. The data conversion and storage is done in the call to the local apply() method, passing false as its parameter to indicate that we are doing the apply operation. This method has been ommitted for brevity. It is implemented in guictrl.cpp should you wish to refer to it. 

In summary then you will typically have to implement an associateStorage() method and the canApply(), apply() and showError() virtual methods for every control written. Exceptions to this rule will occur depending upon the nature and purpose of the control. The pre-existing code in guictrl.hpp and guictrl.cpp serve as a good reference to these requirements and exceptions. 
 

Style Issues

Likewise the WIN32 messages that are used to interface with the control are given method wrappers for largely the same reasoning. Interfacing through methods is safer than through messaging as it is type safe. Once the method is correctly coded you can never use it incorrectly, whereas sending messages directly may result in erroneous casting. Although building methods for each message is initially time consuming it is time well spent and will make programming with that control that much easier. The look and feel of your code will benefit also and in the case of completely new controls you need not use messaging at all since you can use your control methods directly. 

To get the best feel for the style study the class definitions for the common WIN32 controls in guictrl.hpp and compare them with the styles and messages of the corresponding WIN32 controls. 
 

In Summary

State Management

Paavo Jumppanen
Creator of AtOne Application Framework