guk.editIM
Class AssignObject

java.lang.Object
  |
  +--guk.editIM.AssignObject

public class AssignObject
extends java.lang.Object

Helper class to represent keystroke sequence to glyph sequence assignments. Supports various import/export formats and is the main cleverness part for highlighting and file read write functionality. 2003 by Eric Auer.


Field Summary
static int ASCII_HTML
          As UNICODE_HTML, but only uses ISO-8859-1 characters.
static int ASCII_HUMAN
          As UNICODE_HUMAN, but only uses ISO-8859-1 characters.
(package private) static java.awt.Canvas canvas
          key events need some non-null component as origin, we use this canvas for that.
(package private)  java.lang.String comments
          Here we store comments
static boolean FONTbyTAG
          set to true to enable the use of HTML font name tags
static int GIM_FILE
          THE important format for importing and exporting .gim files (GUK IM keymaps).
(package private)  java.lang.String glyphs
          Here we keep our glyph sequence
(package private)  java.lang.String htmlFooter
           
(package private)  java.lang.String htmlHeader
          Used for creating HTML locally.
(package private)  KeyStrokeParser htmlizer
          used as an HTML highlighting helper for the HTML modes.
(package private)  java.util.List keys
          Here we keep our keystroke sequence
static int U8_FILE
          The ad-hoc file format that MPI IM keymaps use.
static int UNICODE_HTML
          Basically as UNICODE_HUMAN, but uses HTML for highlighting.
static int UNICODE_HUMAN
          Ad hoc format for human readers.
static int XGIM_FILE
          A possible future expansion of GIM where \\k+pressed HOME+ and similar things are allowed.
static int YUDIT_FILE
          The keymap data format of Yudit.
 
Constructor Summary
AssignObject()
          The constructor creates a new empty object.
AssignObject(java.awt.Font font)
          The constructor creates a new empty object (now with Font setting, which affects the HTML generation, if the FONTbyTAG flag is on).
 
Method Summary
static java.util.List escapedStringToKeys(java.lang.String str, boolean xgim)
          Helper method to generate a List of KeyEvents from a String describing them.
static java.lang.String escapeGlyph(char ch)
          Helper method to convert a char to an escaped \\u1234 string.
static java.lang.String escapeString(java.lang.String str, boolean html)
          Obvious function returning the string with all non- ASCII-printables replaced by \\u1234 form or \\n.
static java.lang.String escapeToHTML(char ch)
          Helper to convert a char to HTML only when needed.
 java.lang.String exportGlyphs(int format)
          Export the glyph part in a certain format.
 java.lang.String exportKeys(int format)
          Export the key part in a certain format.
 java.lang.String exportString(int format)
          Export the whole object in a certain format.
 java.lang.String getComments()
          obvious function returning the comments
 java.lang.String getGlyphs()
          obvious function returning the glyphs
 java.util.Collection getKeys()
          obvious function returning Iterator for keys
 void importGlyphs(java.lang.String str, int format)
          Import glyphs (no multiple choice! no GIM digit toggle!) in given format.
 void importKeys(java.lang.String str, int format)
          Import keys from string in given format, including COMMENTS if at end of line.
 void importString(java.lang.String str, int format)
          Main method to read one line of data from a file.
static java.lang.String keyToString(java.awt.event.KeyEvent key, boolean escapeUnicode)
          Helper function to convert a key event into a string.
static java.lang.String parseYuditEscapes(java.lang.String str)
          Helper method to replace all numbers by their glyphs (hex, octal and dec) and removes whitespace.
 void setComments(java.lang.String comS)
          obvious function setting the comments
 void setGlyphs(java.lang.String glyS)
          obvious function setting the glyphs
 void setKeys(java.util.Collection keyColl)
          obvious function setting the keys
static java.util.List stringToKeys(java.lang.String str)
          Helper method to translate a String into something that will type that String, in form of a KeyEvent Vector.
static java.lang.String toHex(int i)
          Helper method to convert an int to an 0x1234 fixed length string.
 java.lang.String toString()
          We override toString(), of course.
static java.awt.event.KeyEvent typedKeyEvent(char ch, int modifiers)
          Helper method to create simple typed KeyEvents.
static java.lang.String unEscape(java.lang.String str)
          Helper method to replace all \\u1234 by their glyphs and all \\\\ and \\r and \\n and \\- as well.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait
 

Field Detail

UNICODE_HUMAN

public static final int UNICODE_HUMAN
Ad hoc format for human readers. Most useful when only single fields are exported.

ASCII_HUMAN

public static final int ASCII_HUMAN
As UNICODE_HUMAN, but only uses ISO-8859-1 characters.

UNICODE_HTML

public static final int UNICODE_HTML
Basically as UNICODE_HUMAN, but uses HTML for highlighting. Escape Unicode glyphs as Ӓ.

ASCII_HTML

public static final int ASCII_HTML
As UNICODE_HTML, but only uses ISO-8859-1 characters.

GIM_FILE

public static final int GIM_FILE
THE important format for importing and exporting .gim files (GUK IM keymaps). Most important modes are importing and exporting whole lines, but parts are okay, too. Headers and empty / comment only lines must be processed by the caller, as we only process data lines. GUK IM are made by GATE.
See Also:
GATE Unicode Toolkit

XGIM_FILE

public static final int XGIM_FILE
A possible future expansion of GIM where \\k+pressed HOME+ and similar things are allowed. The editor and the HTML formats allow those, but GUK IM does not. Probably it is not even useful for normal users at all.

U8_FILE

public static final int U8_FILE
The ad-hoc file format that MPI IM keymaps use. This is plain UTF-8 text. First column is a key sequence, then a tab follows, then one or more tab-separated glyph strings form the rest of the line. No comments can be stored! Only ONE glyph string is allowed by design: The caller has to split up lines with multiple glyph strings, because one AssignObject is for editing exactly one mapping of a key sequence to a glyph string. MPI IM are used by ELAN, EUDICO.
See Also:
MPI Psycholinguistics Nijmegen

YUDIT_FILE

public static final int YUDIT_FILE
The keymap data format of Yudit. Yudit is a free Unicode editor that can run on otherwise not Unicode enabled systems. Notice that a few Yudit files (currently only Hangul and the "Type Unicode glyphs by typing u1234" map use this) are not one line per mapping but have sections that are multiplied with each other. We cannot handle this, as one AssignObject only holds one key sequence and one glyph string, by design. You have to multiply out sections BEFORE processing a file with this class.
See Also:
Yudit Unicode editor

htmlizer

KeyStrokeParser htmlizer
used as an HTML highlighting helper for the HTML modes.

FONTbyTAG

public static final boolean FONTbyTAG
set to true to enable the use of HTML font name tags

htmlHeader

java.lang.String htmlHeader
Used for creating HTML locally.

htmlFooter

java.lang.String htmlFooter

keys

java.util.List keys
Here we keep our keystroke sequence

canvas

static java.awt.Canvas canvas
key events need some non-null component as origin, we use this canvas for that.

glyphs

java.lang.String glyphs
Here we keep our glyph sequence

comments

java.lang.String comments
Here we store comments
Constructor Detail

AssignObject

public AssignObject()
The constructor creates a new empty object.

AssignObject

public AssignObject(java.awt.Font font)
The constructor creates a new empty object (now with Font setting, which affects the HTML generation, if the FONTbyTAG flag is on).
Parameters:
font - A Font to be mentioned in a font name HTML tag if FONTbyTAG is configured as true.
Method Detail

getGlyphs

public java.lang.String getGlyphs()
obvious function returning the glyphs

getKeys

public java.util.Collection getKeys()
obvious function returning Iterator for keys

getComments

public java.lang.String getComments()
obvious function returning the comments

setComments

public void setComments(java.lang.String comS)
obvious function setting the comments

setGlyphs

public void setGlyphs(java.lang.String glyS)
obvious function setting the glyphs

setKeys

public void setKeys(java.util.Collection keyColl)
obvious function setting the keys

escapeGlyph

public static java.lang.String escapeGlyph(char ch)
Helper method to convert a char to an escaped \\u1234 string. The string will have a fixed length of 6 characters.

escapeToHTML

public static java.lang.String escapeToHTML(char ch)
Helper to convert a char to HTML only when needed. Applies to quotes, amp, lt, gt, non-ASCII. (Unicode needs HTML 4.0 to render, JLabels only render ISO-8859-1 HTML 3.2)
Parameters:
ch - An arbitrary Unicode character.
Returns:
A version of the character that can be safely included in HTML files. Also hardens space to underlined nonbreakable space.

toHex

public static java.lang.String toHex(int i)
Helper method to convert an int to an 0x1234 fixed length string.

escapeString

public static java.lang.String escapeString(java.lang.String str,
                                            boolean html)
Obvious function returning the string with all non- ASCII-printables replaced by \\u1234 form or \\n. Meant for human readable formats and HTML escaping.
Parameters:
str - The string to be escaped
html - If true, create HTML Ӓ escapes, otherwise create \\u1234 escapes visible to the user. Also escapes HTML chars (quotes, lt, gt, amp) in HTML mode.

keyToString

public static java.lang.String keyToString(java.awt.event.KeyEvent key,
                                           boolean escapeUnicode)
Helper function to convert a key event into a string. This tries to keep the resulting string as short as possible: Space, newline, quotes, - and backslash are escaped with a backslash. Control and Alt are represented by prefixing C- and A-. Characters beyond ISO-8859-1 are escaped, too. More complex key events are converted into XGIM syntax (and therefore likely to be useless for most file formats!).
Parameters:
key - A key event that should be stringified.
escapeUnicode - Set this if you want characters beyond ISO-8859-1 to be escaped.

toString

public java.lang.String toString()
We override toString(), of course. The output is an ISO-8859 version of all important object contents in human readable form.
Overrides:
toString in class java.lang.Object

exportString

public java.lang.String exportString(int format)
                              throws java.lang.UnsupportedOperationException
Export the whole object in a certain format.
Parameters:
format - One of the constant values of this class. Some formats may not allow all features to be exported.
Returns:
Returns a string version of this object, typically one line that can be displayed or inserted into a file of the requested format directly.
Throws:
java.lang.UnsupportedOperationException - Whenever some feature cannot be exported, an exception is thrown (and nothing is returned). The exception contains the error message.

exportGlyphs

public java.lang.String exportGlyphs(int format)
                              throws java.lang.UnsupportedOperationException
Export the glyph part in a certain format.
Parameters:
format - One of the constant values of this class. Some formats may not allow all features to be exported.
Returns:
Returns a string version of the glyph string, for example enriched with highlighting or escaped to avoid certain characters.
Throws:
java.lang.UnsupportedOperationException - Whenever some feature cannot be exported, an exception is thrown (and nothing is returned). The exception contains the error message.

exportKeys

public java.lang.String exportKeys(int format)
                            throws java.lang.UnsupportedOperationException
Export the key part in a certain format.
Parameters:
format - One of the constant values of this class. Some formats may not allow all features to be exported.
Returns:
Returns a string version of the key sequence in the particular file format requested.
Throws:
java.lang.UnsupportedOperationException - Whenever some feature cannot be exported, an exception is thrown (and nothing is returned). The exception contains the error message. Only GIM can handle Ctrl and Alt, and only XGIM can handle even more complicated key events.

unEscape

public static java.lang.String unEscape(java.lang.String str)
Helper method to replace all \\u1234 by their glyphs and all \\\\ and \\r and \\n and \\- as well. Leaves \\octal and \\k style escapes as is.
Parameters:
str - A string possibly containing escapes.
Returns:
A string with only octal and XGIM escapes left, which is possibly shorter than the input string.

parseYuditEscapes

public static java.lang.String parseYuditEscapes(java.lang.String str)
Helper method to replace all numbers by their glyphs (hex, octal and dec) and removes whitespace. Needs other stuff to be parsed before by unEscape. This is used for the particular way in which Yudit allows Unicode glyphs to be escaped. Note that Yudit does NOT allow Java style \\u12ab escapes.
Parameters:
A - string with text and numbers, separated by whitespace.
Returns:
The translated string, where all numbers are replaced by their corresponding glpyhs and all whitespace that was in the input string has been removed.

stringToKeys

public static java.util.List stringToKeys(java.lang.String str)
Helper method to translate a String into something that will type that String, in form of a KeyEvent Vector.
Parameters:
str - An Unicode string for which key events will be generated.
Returns:
A List of KeyEvent objects that, when sent to some target in sequence, will cause the input string to be "typed in".

typedKeyEvent

public static java.awt.event.KeyEvent typedKeyEvent(char ch,
                                                    int modifiers)
                                             throws java.lang.UnsupportedOperationException
Helper method to create simple typed KeyEvents. Quite useful wrapper that generates a key event for a given glyph. Note that neither the wrapper nor Java tries to figure out a corresponding key code!
Parameters:
ch - The character which the event should type.
modifiers - The modifiers, as defined for KeyEvent objects, representing things like shift states.
Returns:
A key event corresponding to the requested char. It will be timestamped to the current time and originate from a dummy canvas. The key code will be VK_UNDEFINED.
Throws:
java.lang.UnsupportedOperationException - If no translation into a key event can be found, an exception is thrown (which will contain a simple error message).

escapedStringToKeys

public static java.util.List escapedStringToKeys(java.lang.String str,
                                                 boolean xgim)
Helper method to generate a List of KeyEvents from a String describing them. Only accepts xgim escapes when xgim is true. Central point of string to event list translation: This does the chunking, while translation of each chunk into a key event is done elsewhere. Strange: KeyEvents only allow Shift/Ctrl/Alt/Meta, but KeyStrokes also allow buttons and AltGr. All GIM parsing should match GIM LocaleHandler style in general. Uses unEscape for simple and \\u1234 escapes (!?).
Parameters:
str - A string of glyphs, possibly enriched with special escapes like the C- prefix for Ctrl. See the other parsing methods for details.
xgim - Only when this is true, XGIM style escapes are allowed.
Throws:
java.lang.UnsupportedOperationException - When the string cannot be parsed or contains XGIM escapes while xgim is false, an exception with a detailed error message is thrown.

importString

public void importString(java.lang.String str,
                         int format)
                  throws java.lang.UnsupportedOperationException
Main method to read one line of data from a file. Import whole entry in given format, including COMMENTS. Cannot import HTML formats. Cannot parse alternatives (GIM digit toggle, MPI U8 choicelists), so you have to split them up yourself before calling importString. Cannot parse headers or comment-only lines either, so you must throw away (or store elsewhere) comments before calling this.
Parameters:
str - A string, typically a line of text from the body of a keymap file in the selected format.
format - One of the format constants of this class, selecting which file format the parser has to process.
Throws:
java.lang.UnsupportedOperationException - Whenever something turns out to be unparseable or unstorable here or in one of the helper methods, an exception with a detailed error message is thrown.

importGlyphs

public void importGlyphs(java.lang.String str,
                         int format)
                  throws java.lang.UnsupportedOperationException
Import glyphs (no multiple choice! no GIM digit toggle!) in given format.
Parameters:
str - A string containing only one glyph string and no comments, in the selected format. When there are choices like U8 choice lists or GIM digit (choice between 2), you have to split them into several single values yourself before calling this.
format - One of the format constants of this class, selecting which file format the parser has to process.
Throws:
java.lang.UnsupportedOperationException - Whenever something turns out to be unparseable or unstorable here or in one of the helper methods, an exception with a detailed error message is thrown.

importKeys

public void importKeys(java.lang.String str,
                       int format)
                throws java.lang.UnsupportedOperationException
Import keys from string in given format, including COMMENTS if at end of line.
Parameters:
str - A string containing a key sequence description in the selected format. No keywords or quotes are allowed, and this is not recommended to use this for FILES. However, this IS recommended for importing user input that should become a new key sequence. Notice that no error will be thrown if you accidentally include additional text like keywords or quotes: It will become part of the key sequence.
format - One of the format constants of this class, selecting which file format the parser has to process.
Throws:
java.lang.UnsupportedOperationException - Whenever something turns out to be unparseable or unstorable here or in one of the helper methods, an exception with a detailed error message is thrown.