How to: Create a Checkbox
- 2 minutes to read
Follow the steps below to create a CheckBox object in code:
Access the document’s form fields collection using the SubDocument.FormFields property and call the FormFieldCollection.InsertCheckBox method to create a CheckBox object at the specified document position. In the example below, the checkbox is created at the caret’s position.
Note
Checkboxes cannot be inserted to the document header, footer, comments or floating objects (text boxes or shapes). Otherwise, an FormFieldIncorrectSubDocumentException occurs.
- Define the name of the bookmark associated with the current CheckBox object using the FormField.Name property.
- Specify the checkbox’s state using the CheckBox.State property.
- Use the CheckBox.SizeMode property to define the checkbox’s size. Selecting the CheckBoxSizeMode.Auto mode resizes the checkbox according to the current font size value (returned by the CharacterPropertiesBase.FontSize property). Set the SizeMode property to CheckBoxSizeMode.Exact and specify the CheckBox.Size value to specify the checkbox’s size.
You can add instructional text to the checkbox. This text can be displayed in the status bar or when focusing the checkbox and pressing F1. Specify the help text type and the text using the following members:
- Help text displayed on the status bar: FormField.StatusTextType and FormField.StatusText.
- Help text displayed on pressing F1: FormField.HelpTextType and FormField.HelpText.
When setting the HelpTextType or StatusTextType property to FormFieldTextType.Auto, make sure that the provided HelpText or StatusText value is equal to one of the AutoText gallery’s entries (stored as the Normal.dotm file in the system’s Templates folder). Otherwise, the help text is not displayed.
Note
Currently, the RichEditControl cannot display any instructional text.
- Set the FormField.CalculateOnExit property to true to update the checkbox’s value on exit.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/word-processing-document-api-examples-t418535
DocumentPosition currentPosition = server.Document.CaretPosition;
DevExpress.XtraRichEdit.API.Native.CheckBox checkBox = server.Document.FormFields.InsertCheckBox(currentPosition);
checkBox.Name = "check1";
checkBox.State = CheckBoxState.Checked;
checkBox.SizeMode = CheckBoxSizeMode.Auto;
checkBox.HelpTextType = FormFieldTextType.Custom;
checkBox.HelpText = "help text";