39. insertCharByName
Prev | Chapter 6. Commands written in the Java™ programming language | Next

## 39. insertCharByName

Parameter syntax:

    [ '[DocBook]'|'[$property_name]'|'[DocBookIfNone]' ]? [ S entity_name ]?

Inserts at caret position a character specified using its entity name. If the entity name is not specified, this command displays a dialog box (supporting auto-completion) which allows to choose it interactively.

### Important

This command does not insert a reference to a character entity, it inserts a character. It must be considered as an alternative to using the Characters tool of XMLmind XML Editor.

The character entities listed in the dialog box displayed by this command are determined as follows:

1. If a `[DocBook]` parameter has been specified, use the character entities defined in the DocBook 4.4+ DTD[4] and this, whatever the schema the document being edited is conforming to.

2. If a `[$`property_name`]` parameter has been specified, use the character entities defined in the Java™ properties file which is the value of Java™ property `property_name`.

3. Use the character entities defined in the DTD to which the document being edited is conforming to.

4. Use the character entities defined in the Java™ properties file which is the value of Java™ property ``configuration_name`.characterEntities`, where `configuration_name` is the name of the configuration associated to the document being edited.

5. If a `[DocBookIfNone]` parameter has been specified, use the character entities defined in the DocBook 4.4+ DTD.

The above steps are tried in order until a step succeeds. If all steps fail, this command cannot be executed and therefore, displays no dialog box at all.

Examples:

    insertCharByName
    insertCharByName Beta
    insertCharByName [DocBook]
    insertCharByName [DocBook] lambda
    insertCharByName [$my_favorite_chars]
    insertCharByName [DocBookIfNone]

Example 6.1. MathML example

Let's suppose that the MathML configuration is based on `mathml2.xsd` and not on `mathml2.dtd`. Even without a DTD, you want to be able to insert math characters specified using their entity names (`CircleDot`, `sum`, `it`, etc). Here's how to do that:

1. Create a Java™ properties file defining all the character entities you need (`mathml_chars.properties`):

       ...
       CircleDot=\u2299
       CircleMinus=\u2296
       CirclePlus=\u2295
       CircleTimes=\u2297
       ...

2. Add this property configuration element to the `mathml.xxe` configuration file:

       <property name="MathML.characterEntities"
                 url="true">mathml_chars.properties</property>

3. When editing a MathML document, use command `insertCharByName` without any special option. Examples:

       insertCharByName
       insertCharByName InvisibleTimes
       insertCharByName af

[4] That is, the character entities defined in XML Entity Declarations for Characters.

Prev | Up | Next
38. insert | Home | 40. insertCharSequence