Customize the UI interaction of a check box

This sample shows how one can create a custom check box 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 check box interactor. It is a subclass of the standard CheckBoxInteractor that PDFControls.NET creates for all check boxes 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 check box when the enter key goes up. If other keys are pressed the default behavior gets invoked by calling base.OnKeyUp().

   class MyCheckBoxInteractor : CheckBoxInteractor
   {
      public MyCheckBoxInteractor(CheckBoxWidget widget)
         : base(widget)
      {
      }

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

            if (checkBoxField != null)
            {
               switch (checkBoxField.CheckBoxValue)
               {
                  case CheckState.On:
                     checkBoxField.CheckBoxValue = CheckState.Off;
                     break;
                  default:
                     checkBoxField.CheckBoxValue = CheckState.On;
                     break;
               }
            }
         }
         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 check box is basically a special kind of annotation in PDF. The modified factory takes the standard annotation factory as its base and just overrides the CreateCheckBoxInteractor 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 CreateCheckBoxInteractor(CheckBoxWidget checkBoxWidget)
      {
         return new MyCheckBoxInteractor(checkBoxWidget);
      }
   }

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(@"..\..\check.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.