Customize the GUI interaction of a radio button

This sample shows how one can create a custom radio button interactor that responds to other key strokes than just the space bar.

Custom Annotation Interactor

In PDFControls.NET, interactive GUI elements that deal with PDF elements are called interactors. They are similar to Controls in WinForms. If one needs to have some special kind of handling in the GUI for some PDF element, the best way to do this is often to install a custom interactor for that element.

Below, we have defined a custom radio button interactor. It is a subclass of the standard RadioButtonInteractor that PDFControls.NET creates for all radio buttons in a PDF document. It overrides the OnKeyUp() method, so that it implements additional behavior when pressing the enter key. In this case, it will toggle the value of the radio box when the enter key goes up. If other keys are pressed the default behavior gets invoked by calling base.OnKeyUp().

Radio buttons in PDF are basically implemented as a number of radio button widgets that all refer to the same radio button field. The appearance of each widget depends on the value of the field. Each widget has an ExportName associated with it. Only when this name matches the value of the field, the widget will appear ‘checked’. This means that if one sets the value of the field to the export name of a particular widget, all the other radio button widgets will be cleared.

It is also possible to clear all radio button widgets by setting the value of the radio button field to null.

class MyRadioButtonInteractor : RadioButtonInteractor
{
  public MyRadioButtonInteractor(RadioButtonWidget widget)
      : base(widget)
  {
  }

  protected override void 
    OnKeyUp(TallComponents.Interaction.WinForms.Events.KeyboardEventArgs e)
  {
    if (e.KeyData == System.Windows.Forms.Keys.Enter)
    {
      RadioButtonField radioButtonField = Widget.Field as RadioButtonField;
      RadioButtonWidget radioButtonWidget = Widget as RadioButtonWidget;

      if (radioButtonField != null && radioButtonWidget != null)
      {
        if (radioButtonField.RadioButtonValue == null ||
            radioButtonField.RadioButtonValue.ExportName != radioButtonWidget.Option.ExportName)
        {
          radioButtonField.RadioButtonValue = radioButtonWidget.Option;
        }
        else
        {
          radioButtonField.RadioButtonValue = null;
        }
      }
    }
    else
    {
      base.OnKeyUp(e);
    }
  }
}

Custom Interactor Factory

Installing such a special interactor goes via a custom factory. In this case one needs a custom annotation factory, as a radio button is basically a special kind of annotation in PDF. The modified factory takes the standard annotation factory as its base and just overrides the CreateRadioButtonInteractor method, as that is the only type of annotation that we need a special interactor for. It simply returns an instance of the custom interactor that we have defined above.

public class MyAnnotationFactory : AnnotationInteractorFactory
{
   protected override WinFormsInteractor CreateRadioButtonInteractor(RadioButtonWidget radioButtonWidget)
   {
      return new MyRadioButtonInteractor(radioButtonWidget);
   }
}

It is possible to create custom interactors for many types of PDF annotations in this way. The base AnnotationFactory currently defines the following overridable create methods:

• CreateCheckBoxInteractor
• CreateDateTimeTextBoxInteractor
• CreateDropDownListInteractor
• CreateFreeTextInteractor
• CreateImageFieldInteractor
• CreateLineInteractor
• CreateLinkInteractor
• CreateListBoxInteractor
• CreateMultiLineTextBoxInteractor
• CreateNoteInteractor
• CreateNumericTextBoxInteractor
• CreatePasswordTextBoxInteractor
• CreatePopupInteractor
• CreatePushButtonInteractor
• CreateRadioButtonInteractor
• CreateSignatureInteractor
• CreateSingleLineTextBoxInteractor
• CreateSquareInteractor
• CreateStampMarkupInteractor
• CreateStampMarkupInteractor
• CreateTextMarkupInteractor
• CreateUnknownMarkupInteractor

This custom annotation factory in turn can be installed by assigning it to the AnnotationInteractorFactory property of the pages viewer, as shown below. This will make sure that the appropriate annotation interactors get created each time that a page becomes visible that has some annotations on it

   public partial class Form1 : Form
   {
      public Form1()
      {
         InitializeComponent();
         pagesViewer1.AnnotationInteractorFactory = new MyAnnotationFactory();
      }

      protected override void OnLoad(EventArgs e)
      {
         base.OnLoad(e);
         document1.Open(@"..\..\radio.pdf");
      }
  }

Please note that an interactor can be created multiple times for the same PDF annotation. If a page becomes invisible, the interactors on it may be removed at some point to conserve memory. If then later the page becomes visible again, the appropriate create methods of the annotation factory will be called again to create new interactors for the annotations.