43. insertCharByName

43. insertCharByName
	Chapter 6. Commands written in the Java™ programming language

Parameter syntax:

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

Inserts at caret position a character specified by char_spec. If char_spec is not specified, this command displays a dialog box (supporting auto-completion) which lets the user specify it interactively.

This command honors the Overwrite Mode (OVR) in XMLmind XML Editor - Online Help when this mode has been turned on.


	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.

Parameter char_spec is normally the name of the corresponding character entity. However character representations other than entity names are also supported. For example, character TAB may now be specified as any of the following: "\t", "\11", "\x9", "\u0009", "U+0009" ,"	", "	", "011", "0x9".

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

If a [DocBook] parameter has been specified, use the character entities defined in the DocBook 4.4+ DTD^[2] and this, whatever the schema the document being edited is conforming to.
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.
Use the character entities defined in the DTD to which the document being edited is conforming to.
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.
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 U+03B2
insertCharByName [DocBook]
insertCharByName [DocBook] lambda
insertCharByName [$my_favorite_chars]
insertCharByName [DocBookIfNone]

Example 6.9. 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:

Create a Java™ properties file defining all the character entities you need (mathml_chars.properties):
```
...
CircleDot=\u2299
CircleMinus=\u2296
CirclePlus=\u2295
CircleTimes=\u2297
...
```

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

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

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

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


42. insert		44. insertCharSequence