Meta Tags-Platform

Description:
Description: The XMLTree Viewer application is a Visual Basic application that reads an XML file and displays the contents in a TreeView control.

More Details

The project does not use any classes or sophisticated design. It simply prompts the user for an XML file to parse and display. The goal of this application is to demonstrate how to work with the XML DOM and to get an understanding of the hierarchy of an XML document.

Once a file is referenced the application uses an XML DOM reference, declared using the WithEvents keyword, to trap the ondataavailable and onreadystatechange events. The ondataavailable event is used to display a count of the nodes. The onreadystatechange event is used to check for errors and to call the DisplayDomNode routine. The DisplayDomNode routine does all the real work and loads the XML data into the TreeView.

Browser/Platform Compatibility

This sample requires Internet Explorer 5.0 and Windows 98, Windows NT 4.0, or Windows 2000.

Usage

Simply run the application click on the ellipses to locate any XML file. Then click the Load button. The XML file should be displayed in the TreeView control.

Complete Article

*********************************************************************
*
frmParser.frm
*********************************************************************
*

VERSION 5.00
Object = "{F9043C88-F6F2-101A-A3C9-08002B2F49FB}
#1.2#0"; "comdlg32.ocx"
Object = "{6B7E6392-850A-101B-AFC0-4210102A8DA7}
#1.3#0"; "comctl32.ocx"
Begin VB.Form frmParser
   Caption         =   "XML Tree View"
   ClientHeight    =   4884
   ClientLeft      =   60
   ClientTop       =   348
   ClientWidth     =   6516
   Icon            =   "frmParser.frx":0000
   LinkTopic       =   "Form1"
   ScaleHeight     =   4884
   ScaleWidth      =   6516
   StartUpPosition =   3 'Windows Default
   Begin VB.CommandButton cmdFont
      Caption         =   "Font..."
      Height          =   255
      Left            =   5760
      TabIndex        =   5
      Top             =   240
      Width           =   735
   End
   Begin ComctlLib.TreeView tvwXMLData
      Height          =   3735
      Left            =   0
      TabIndex        =   4
      Top             =   720
      Width           =   6495
      _ExtentX        =   11451
      _ExtentY        =   6583
      _Version        =   327682
      Style           =   7
      Appearance      =   1
      BeginProperty Font {0BE35203-8F91-11CE-9DE3-00AA004BB851}
         Name            =   "MS Sans Serif"
         Size            =   9.6
         Charset         =   0
         Weight          =   700
         Underline       =   0   'False
         Italic          =   0   'False
         Strikethrough   =   0   'False
      EndProperty
   End
   Begin VB.CommandButton cmdParse
      Caption         =   "Load"
      Height          =   255
      Left            =   4920
      TabIndex        =   3
      Top             =   240
      Width           =   735
   End
   Begin VB.CommandButton cmdBrowse
      Caption         =   "..."
      Height          =   255
      Left            =   4440
      TabIndex        =   2
      Top             =   240
      Width           =   375
   End
   Begin VB.TextBox txtFileName
      Height          =   375
      Left            =   480
      TabIndex        =   0
      Text            =   "sample.xml"
      Top             =   240
      Width           =   3855
   End
   Begin MSComDlg.CommonDialog cmnd
      Left            =   5040
      Top             =   720
      _ExtentX        =   847
      _ExtentY        =   847
      _Version        =   393216
   End
   Begin VB.Label Status
      BeginProperty Font
         Name            =   "MS Sans Serif"
         Size            =   9.6
         Charset         =   0
         Weight          =   700
         Underline       =   0   'False
         Italic          =   0   'False
         Strikethrough   =   0   'False
      EndProperty
      Height          =   255
      Left            =   120
      TabIndex        =   6
      Top             =   4560
      Width           =   6375
   End
   Begin VB.Label Label1
      Caption         =   "URL:"
      Height          =   255
      Left            =   60
      TabIndex        =   1
      Top             =   270
      Width           =   375
   End
End
Attribute VB_Name = "frmParser"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = False
Attribute VB_PredeclaredId = True
Attribute VB_Exposed = False
'--------------------------------------------------------------------
-
----
'
'   Module Name: frmParser
'
'   Description: This form displays the data from the XML file in a
'                tree view control
'
'--------------------------------------------------------------------
-
----
Option Explicit

'--------------------------------------------------------------------
-
----
' DOM Constants
'--------------------------------------------------------------------
-
----
Const READYSTATE_COMPLETE = 4

'--------------------------------------------------------------------
-
----
' Private Attributes
'--------------------------------------------------------------------
-
----
Dim WithEvents xml_document As DOMDocument
Attribute xml_document.VB_VarHelpID = -1

'--------------------------------------------------------------------
-
----
'   Public Methods
'--------------------------------------------------------------------
-
----
Public Sub DisplayDomNode(ByVal int_ancestor As Integer, ByRef
xml_node As MSXML.IXMLDOMNode, ByVal int_level As Integer)
    On Error Resume Next

    Dim str_line As String
    Dim int_index
    Dim obj_treeNode As Node
    Dim lng_loop As Long

    'check if the provided node is nothing
    If xml_node Is Nothing Then
        Exit Sub
    End If

    'determine the type of node to get the correct formatting
    str_line = FormatNodeString(xml_node)

    'don't display anything if the line is NULL
    If str_line = "" Then
        Exit Sub
    End If

    'handle any attributes in the node
    If (xml_node.nodeType = NODE_ELEMENT) Then
        str_line = str_line & FormatAttributes(xml_node.Attributes)
    End If

    'check if the node is the root
    If int_ancestor = 0 Then
        Set obj_treeNode = tvwXMLData.Nodes.Add(, , , str_line)
    Else
        Set obj_treeNode = tvwXMLData.Nodes.Add(int_ancestor,
tvwChild, , str_line)
    End If
    int_index = obj_treeNode.index

    'call this function recursively to display the child nodes
    If Not (xml_node.childNodes Is Nothing) Then
        For lng_loop = 0 To xml_node.childNodes.length - 1
            Call DisplayDomNode(int_index, xml_node.childNodes.Item
(lng_loop), int_level & 1)
        Next lng_loop
    End If
End Sub

'--------------------------------------------------------------------
-
----
'   Private Methods
'--------------------------------------------------------------------
-
----
Private Function FormatNodeString(ByRef xml_node As IXMLDOMNode) As
String
    Dim xml_entity As IXMLDOMEntity
    Dim xml_notation As IXMLDOMNotation
    Dim str_line As String

If xml_node.nodeType = NODE_COMMENT Then
        'format the code comment line
        str_line = ""
    ElseIf xml_node.nodeType = NODE_CDATA_SECTION Or
xml_node.nodeType = NODE_TEXT Then
        'format the node value
        str_line = xml_node.nodeValue
    ElseIf xml_node.nodeType = NODE_DOCUMENT_TYPE Then
        'format the doc type line
        str_line = "DOCTYPE " & xml_node.nodeName
    ElseIf xml_node.nodeType = NODE_PROCESSING_INSTRUCTION Then
        'format the processing instruction
        str_line = "<?" & xml_node.nodeName & " " &
xml_node.nodeValue & "?>"
    ElseIf xml_node.nodeType = NODE_ENTITY Then
        'get the entity reference
        Set xml_entity = xml_node

        'format the beginning of the entity line
        str_line = "<!ENTITY " & xml_node.nodeName

        'check if public and system IDs exist
        If (xml_entity.publicId <> "") Then
            'format the public ID part of the line
            str_line = str_line & " PUBLIC '" & xml_entity.publicId
& "' '" & xml_entity.systemId & "'"
        ElseIf (xml_entity.systemId <> "") Then
            'format the system ID part of the line
            str_line = str_line & " SYSTEM '" & xml_entity.systemId
& "'"
        End If

        'check if a notation name exists
        If (xml_entity.notationName <> "") Then
            'format the notation name part of the line
            str_line = str_line & " NDATA " & xml_entity.notationName
        End If

        'append the closing string
        str_line = str_line & ">"
    ElseIf xml_node.nodeType = NODE_NOTATION Then
        'get the notation reference
        Set xml_notation = xml_node

        'format the beginning of the notation line
        str_line = "<!NOTATION " & xml_node.nodeName

        'check if public and system IDs exist
        If (xml_notation.publicId <> "") Then
            'format the public ID part of the line
            str_line = str_line & " PUBLIC '" &
xml_notation.publicId
& "' '" & xml_notation.systemId & "'"
        ElseIf (xml_notation.systemId <> "") Then
            'format the system ID part of the line
            str_line = str_line & " SYSTEM '" &
xml_notation.systemId
& "'"
        End If

        'append the closing string
        str_line = str_line & ">"
    ElseIf xml_node.nodeType = NODE_ENTITY_REFERENCE Then
        'format the entity reference line
        str_line = "&" & xml_node.nodeName & ";"
    ElseIf xml_node.nodeType = NODE_DOCUMENT Then
        'format the document line
        str_line = txtFileName
    Else
        'format the line for all the rest of the node types
        str_line = xml_node.nodeName
    End If

    'return the string
    FormatNodeString = str_line
End Function

Private Function FormatAttributes(ByRef xml_namedNodeMap As
IXMLDOMNamedNodeMap) As String
    Dim xml_attribute As IXMLDOMAttribute
    Dim str_line As String
    Dim lng_loop As Long

    'iterate through the attributes
    For lng_loop = 0 To xml_namedNodeMap.length - 1
        'get a reference to the attribute
        Set xml_attribute = xml_namedNodeMap.Item(lng_loop)

        'format the return string
        str_line = " " & xml_attribute.Name & "='" &
xml_attribute.Value & "'"
    Next lng_loop

    'return the string
    FormatAttributes = str_line
End Function

'--------------------------------------------------------------------
-
----
'   Button Event Handlers
'--------------------------------------------------------------------
-
----
Private Sub cmdBrowse_Click()
    'use the common open dialog to get a filename
    cmnd.Filter = "XML (*.xml)|*.xml|All (*.*)|*.*"
    cmnd.ShowOpen

    'set the URL line
    txtFileName = cmnd.FileName
End Sub

Private Sub cmdFont_Click()
    'populate the common font dialog with the current fonts
    cmnd.FontName = tvwXMLData.Font.Name
    cmnd.FontItalic = tvwXMLData.Font.Italic
    cmnd.FontSize = tvwXMLData.Font.Size
    cmnd.FontBold = tvwXMLData.Font.Bold
    cmnd.Flags = cdlCFScreenFonts

    'display the common font dialog
    cmnd.ShowFont

    'set the treeview with the new fonts
    tvwXMLData.Font.Name = cmnd.FontName
    tvwXMLData.Font.Italic = cmnd.FontItalic
    tvwXMLData.Font.Size = cmnd.FontSize
    tvwXMLData.Font.Bold = cmnd.FontBold
End Sub

Private Sub cmdParse_Click()
    'clear the tree view
    tvwXMLData.Nodes.Clear

    'load the DOM document from the provided URL
    On Error Resume Next
    xml_document.async = True
    xml_document.Load txtFileName.Text
End Sub

'--------------------------------------------------------------------
-
----
'   DOM Event Handlers
'--------------------------------------------------------------------
-
----
Private Sub xml_document_ondataavailable()
    Dim xml_node As IXMLDOMNode
    Dim int_count As Integer

    'get a reference to an XML node
    Set xml_node = xml_document.documentElement

    'get the count of nodes loaded
    int_count = xml_document.childNodes.length
    If (TypeName(xml_node) <> "Nothing") Then
        int_count = int_count + xml_node.childNodes.length
    End If

    'display the count in the status bar
    Status.Caption = "Loaded " & int_count & " nodes..."
End Sub

Private Sub xml_document_onreadystatechange()
    Dim xml_parseError As MSXML.IXMLDOMParseError
    Dim xml_node As MSXML.IXMLDOMNode

    'check if the document reference's status is complete
    If (xml_document.readyState = READYSTATE_COMPLETE) Then

        'get a reference to the parseerror object
        Set xml_parseError = xml_document.parseError

        'check if an error occured
        If TypeName(xml_document.documentElement) = "Nothing" Then
            'display the error
            MsgBox xml_parseError.reason, vbOKOnly
        Else
            'get a reference to the document
            Set xml_node = xml_document

            'display the nodes
            Call DisplayDomNode(0, xml_node, 0)

            'expand the first node in the tree
            tvwXMLData.Nodes.Item(1).Expanded = True
        End If
    End If
End Sub

'--------------------------------------------------------------------
-
----
'   Form Event Handlers
'--------------------------------------------------------------------
-
----
Private Sub Form_Load()
    'create the DOM document
    Set xml_document = CreateObject("Microsoft.XMLDOM")
End Sub

Private Sub Form_Resize()
    On Error Resume Next

    'set the width of the tree view based on the form size
    tvwXMLData.Width = Me.ScaleWidth - tvwXMLData.Left - 60
    tvwXMLData.Height = Me.ScaleHeight - tvwXMLData.Top - 60 -
Status.Height
End Sub

*********************************************************************
*
readme.htm
*********************************************************************
*

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>

<HEAD>

<TITLE>XML Tree Viewer</TITLE>

</HEAD>

<H1>XML Tree Viewer</H1>

<P>December 1st 1998</P>

<P>It is simple VB application that populates a Tree Control
from a loaded XML Document. The user can then navigate the
XML document by expanding and collapsing nodes of the tree.

<H2>Installation</H2>
You must have VB6.0 installed already and a version of IE5 <b>newer
than bld 1102.</b>.
It depends on some POST IE5 Beta2 DOM changes.
Then copy <A href="xmltree.exe">xmltree.exe</A> to your machine and
launch it.

<P>
<HR>
<FONT FACE="MS SANS SERIF" SIZE="1" COLOR="BLACK">
© <A HREF="http://msdn.microsoft.com/isapi/gomscom.asp?
TARGET=/misc/cpyright.htm"
TARGET="_top">2000 Microsoft Corporation. All rights reserved.
Terms
of use</A>.
</FONT>

</BODY>
</HTML>

*********************************************************************
*
Readme.txt
*********************************************************************
*

================================
XML -- XML Tree Viewer (VB)
================================
Last Updated: October 18, 1999.

SUMMARY
========
The XMLTree Viewer application is a Visual Basic application that
reads
an XML file and displays the contents in a TreeView control.

DETAILS
========
The project does not use any classes or sophisticated design. It
simply
prompts the user for an XML file to parse and display. The goal of
this
application is to demonstrate how to work with the XML DOM and to
get
an
understanding of the hierarchy of an XML document.

Once a file is referenced the application uses an XML DOM reference,
declared using the WithEvents keyword, to trap the ondataavailable
and
onreadystatechange events. The ondataavailable event is used to
display
a count of the nodes. The onreadystatechange event is used to check
for
errors and to call the DisplayDomNode routine. The DisplayDomNode
routine
does all the real work and loads the XML data into the TreeView.

USAGE
======
Simply run the application click on the ellipses to locate any XML
file.
Then click the Load button. The XML file should be displayed in the
TreeView control. The user can then navigate the XML document by
expanding
and collapsing nodes of the tree.

BROWSER/PLATFORM COMPATIBILITY
===============================
This sample requires Internet Explorer 5.0 and Windows 98, Windows
NT
4.0,
or Windows 2000.

SOURCE FILES
=============
XMLTree.exe
sample.dtd
sample.ent
frmParser.frx
frmParser.frm
XMLTree.vbp
XMLTree.vbw
sample.xml

OTHER FILES
============
XMLTree.ico
XMLTreeViewer.doc
readme.htm

SEE ALSO
=========
MSDN Online Web Workshop - XML:
http://msdn.microsoft.com/workshop/xml/index.asp

MSDN Online - XML Developer Center:
http://msdn.microsoft.com/xml/default.asp

*********************************************************************
*
sample.dtd
*********************************************************************
*

<!ELEMENT description (#PCDATA | foo)*>
<!ELEMENT foo (#PCDATA)>
<!ELEMENT dsig (#PCDATA)>
<!ATTLIST dsig value CDATA #IMPLIED>
<!ATTLIST dsig crypt CDATA "128">
<!ENTITY bar SYSTEM "sample.ent">

---------------------------------------------------------------------
-
----------

*********************************************************************
*
sample.xml
*********************************************************************
*

<?xml version="1.0"?>
<!DOCTYPE root SYSTEM "sample.dtd" [
<!ELEMENT root (description,dsig)>
<!ATTLIST root photoid ENTITY #REQUIRED>
<!NOTATION gif SYSTEM "http://www.compuserve.com">
<!ENTITY chris SYSTEM "chris.gif" NDATA gif>
]>
<root photoid="chris">
    
    <description>
        <?foo is a PI node?>
        This is a XML DOM document...
        <foo>&bar;</foo>
    </description>
    <dsig value="172631"/>
</root>

CVS Blame for input-method-spec.html (1.2)
... iso-8859-1"> 5 <meta name="Author" content="Tague Griffith"> 6 <meta name="GENERATOR ...
tr> 269 </table> 270 </ul> 271 272 <h3> 273 <a NAME="Platform Protocols"></a ...
cvs-www.mozilla.org/.../html/projects/intl/input-method-spec.html&rev=&cvsroot=/cvsroot - 48k - Supplemental Result - Cached - Similar pages

CVS Blame
mozilla-org/ html/ projects/ intl/ input-method-spec.html (1.2)

  1 tague 1.1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
  2           <html>
  3           <head>
  4              <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  5              <meta name="Author" content="Tague Griffith">
  6              <meta name="GENERATOR" content="Mozilla/4.5 [en] (WinNT; I) [Netscape]">
  7              <title>Seamonkey Input Method Specification</title>
  8           <!-- saved from url=(0056)http://xpnav.mcom.com/composer/alchemykeyboardinput.html -->
  9           </head>
 10           <body>
 11           
 12           <center>
 13           <h1>
 14           <b><font face="Arial,Helvetica"><font size=+2>Seamonkey Input Method Specification</font></font></b></h1></center>
 15           
 16           <address>
 17           <b>Author: </b><a href="mailto: tague@netscape.com">Tague Griffith</a></address>
 18           
 19           <br><b>Date: </b>1998 May 18
 20           <br><b>Version: Draft 0.1</b>
 21           <br>
 22 tague 1.1 <hr width="100%">
 23           <h3>
 24           Document History:</h3>
 25           
 26           <ul>
 27           <li>
 28           Version Draft 0.1: Initial Release</li>
 29           </ul>
 30           Table Of Contents:
 31           <ul>
 32           <li>
 33           <a href="#Input Method Editing Styles">Input Method Editing Styles</a></li>
 34           
 35           <li>
 36           <a href="#Platform Protocols">Platform Protocols</a></li>
 37           
 38           <li>
 39           <a href="#Editor Functions">Editor Functions</a></li>
 40           
 41           <li>
 42           <a href="#Refernces">References</a></li>
 43 tague 1.1 </ul>
 44           
 45           <h3>
 46           <a NAME="Input Method Editing Styles"></a>Input Method Editing Styles</h3>
 47           Each platform (Macintosh, Windows, Unix/X) supports the input of several
 48           Asian languages (e.g. Japanese, Chinese, Korean) through a special system
 49           service called an Input Method.&nbsp; An input method is a software component
 50           that converts key presses into text input which can't be typed directly.&nbsp;
 51           Input methods are normally used to input text for languages which have
 52           more characters than can fit on a standard keyboard.&nbsp; Input methods
 53           are commonly used for Japanese, Chinese and Korean but also show up in
 54           other languages like Thai and Hindi.
 55           <p>There are four basic style of input method editing: on-the-spot, over-the-spot,
 56           off-the-spot, and root-window.&nbsp; Only two of the styles (on-the-spot
 57           and root window) are supported on Macintosh and Windows.&nbsp; The XIM
 58           (X Input Method) standard defines all four styles, but does not require
 59           an application or input method to support a particular set of them.&nbsp;
 60           The style used is negotiated from the set of common styles supported by
 61           the application and the input method.
 62           <p><b>On-The-Spot</b>
 63           <p>The composed text is rendered inside the text window by the application,
 64 tague 1.1 by maintaining a special editing area "between" the text before the insertion
 65           point and the text after the insertion point. The composed text looks like
 66           text part of the document, however, different stylistic attributes are
 67           applied to the text into indicate that it is part of the input method composition
 68           string.&nbsp; Different parts of the input method composing string will
 69           have different styles applied to them, which indicates that they are in
 70           different stages of editing.&nbsp; Once the composition text is finalized
 71           by the user, it merges into the original document and is indistinguishable
 72           from the surrounding text. The on-the-spot style is also know as inline
 73           input on some platforms.
 74           <br>&nbsp;
 75           <ul>&nbsp;
 76           <table COLS=2 WIDTH="100%" >
 77           <caption><b><u>Example of On-The-Spot Composition Style</u></b></caption>
 78           
 79           <tr VALIGN=TOP>
 80           <td VALIGN=TOP WIDTH="40%">The user types some English text prior to inputting
 81           Japanese text. Using the arrow keys, the user moves the insertion position
 82           between "Spot " and "Example" and switches his keyboard into Japanese Mode.
 83           (This can be done through a hot key or a system menu)</td>
 84           
 85 tague 1.1 <td><img SRC="onthespot1.jpg" height=165 width=296></td>
 86           </tr>
 87           
 88           <tr VALIGN=TOP>
 89           <td>The user begins to type some Japanese phonetically into the edit area.&nbsp;
 90           The user types the series [n,i,h,o,n] which the input method automatically
 91           translates into the two Japanese syllables displayed on the right.&nbsp;
 92           The Romanized "n" remains because it's conversion is still ambiguous. As
 93           the user typed, the editor automatically expand the composition area by
 94           moving the text "Example" as it inserted the Japanese text. The Japanese
 95           text is displayed displayed with a dotted underline to indicate that it
 96           is unconverted text and still has additional input steps to go through.</td>
 97           
 98           <td><img SRC="onthespot2.jpg" height=165 width=296></td>
 99           </tr>
100           
101           <tr VALIGN=TOP>
102           <td>Now that the user has entered the pronunciation of the word they want
103           to add into the document ("nihon" or the Japanese word for Japanese), the
104           user selects the appropriate Kanji conversion for the syllables.&nbsp;
105           Since a single syllable has multiple possible conversions, the input method
106 tague 1.1 will bring up a list of possible candidates.&nbsp; The user selects the
107           appropriate conversion which is then displayed in the document window.&nbsp;
108           Once the user selects the appropriate conversion, the underline style of
109           the text changes.</td>
110           
111           <td><img SRC="onthespot3.jpg" height=165 width=296></td>
112           </tr>
113           
114           <tr VALIGN=TOP>
115           <td>Finally, the User performs some action (usually pressing the return
116           key) which commits the final text.&nbsp; The Japanese text is merged into
117           the document and is indistinguishable from the surrounding text.</td>
118           
119           <td><img SRC="onthespot4.jpg" height=165 width=296></td>
120           </tr>
121           </table>
122           </ul>
123           
124           <h3>
125           Over-The-Spot composition style</h3>
126           The composed text is rendered over the insertion point in a "layer" above
127 tague 1.1 the document window.. The document text doesn't change until the after
128           the user has committed the text, so the composed text ends up obscuring
129           part of the document during editing.
130           <br>&nbsp;
131           <ul>&nbsp;
132           <table COLS=2 WIDTH="100%" >
133           <caption><b><u>Example of Over-The-Spot Composition Style</u></b></caption>
134           
135           <tr VALIGN=TOP>
136           <td VALIGN=TOP WIDTH="40%">The user types some English text prior to inputting
137           Japanese text. Using the arrow keys, the user moves the insertion position
138           between "Spot " and "Example" and switches his keyboard into Japanese Mode.
139           (This can be done through a hot key or a system menu)</td>
140

141 tague 1.2 <td><img SRC="overthespot1.jpg" BORDER=0 height=108 width=301></td>
142 tague 1.1 </tr> 143 144 <tr VALIGN=TOP> 145 <td>The user begins to type some Japanese phonetically into the edit area.  146 The user types the series [n,i,h,o,n] which the input method automatically 147 translates into the two Japanese syllables displayed on the right.  148 As the user typed, in this style the editor draws the composing text over 149 the the text "Example" in the document. </td> 150
151 tague 1.2 <td><img SRC="overthespot2.jpg" BORDER=0 height=108 width=244></td>
152 tague 1.1 </tr> 153 154 <tr VALIGN=TOP> 155 <td>Next the user selects the appropriate Kanji conversion for the syllables.  156 Since a single syllable has multiple possible conversions, the input method 157 will bring up a list of possible candidates.  The user selects the 158 appropriate conversion which replaces the phonetic syllables.  The 159 new candidate text is still drawn over the original document text.</td> 160
161 tague 1.2 <td><img SRC="overthespot3.jpg" BORDER=0 height=108 width=244></td>
162 tague 1.1 </tr> 163 164 <tr VALIGN=TOP> 165 <td>When the user commits the composed text, it is inserted into the document. 166 Unlike on-the-spot input the new text is inserted as a single operation, 167 instead of a series of changing strings.</td> 168
169 tague 1.2 <td><img SRC="overthespot4.jpg" BORDER=0 height=109 width=288></td>
170 tague 1.1 </tr> 171 </table> 172 </ul> 173 <b>Off-the-Spot composition style</b> 174 <p>The off-the-spot composition style is very similar to the root window 175 style.  These two styles are distinguished only by the position of 176 the editing region.  The off-the-spot style draws the editing region 177 in a status bar attached to the bottom of the active window.  Each 178 application window has a status and editing bar, instead of having a single 179 independent window. 180 <ul>  181 <table COLS=2 WIDTH="100%" > 182 <caption><b><u>Example of Off-The-Spot Composition Style</u></b></caption> 183 184 <tr VALIGN=TOP> 185 <td VALIGN=TOP WIDTH="40%">The user types some English text prior to inputting 186 Japanese text. Using the arrow keys, the user moves the insertion position 187 between "Spot " and "Example" and switches his keyboard into Japanese Mode. 188 (This can be done through a hot key or a system menu)</td> 189 190 <td><img SRC="offthespot1.jpg" BORDER=0 height=176 width=279></td> 191 tague 1.1 </tr> 192 193 <tr VALIGN=TOP> 194 <td>The user begins to type some Japanese phonetically into the edit area.  195 The user types the series [n,i,h,o,n] which the input method automatically 196 translates into the two Japanese syllables displayed on the right.  197 As the user typed, in this style the editor draws the composing text in 198 a status bar at the bottom of the document. </td> 199 200 <td><img SRC="offthespot2.jpg" BORDER=0 height=176 width=279></td> 201 </tr> 202 203 <tr VALIGN=TOP> 204 <td>Next the user selects the appropriate Kanji conversion for the syllables.  205 Since a single syllable has multiple possible conversions, the input method 206 will bring up a list of possible candidates.  The user selects the 207 appropriate conversion which replaces the phonetic syllables.  The 208 new candidate text is still drawn in the status bar.</td> 209 210 <td><img SRC="offthespot3.jpg" BORDER=0 height=176 width=279></td> 211 </tr> 212 tague 1.1 213 <tr VALIGN=TOP> 214 <td>When the user commits the composed text, it is inserted into the document. 215 Unlike on-the-spot input the new text is inserted as a single operation, 216 instead of a series of changing strings.</td> 217 218 <td><img SRC="offthespot4.jpg" BORDER=0 height=173 width=278></td> 219 </tr> 220 </table> 221 </ul> 222 223 <p><br><b>Root Window composition style</b> 224 <p>The composed text is rendered in an entirely separate window which has 225 no relationship to the application window.  Once the input is committed, 226 it is then inserted into the document at the insertion point.  The 227 Root window style is also know as bottom line or floating window on some 228 platforms. 229 <ul>  230 <table COLS=2 WIDTH="100%" > 231 <caption><b><u>Example of Root Window Composition Style</u></b></caption> 232 233 tague 1.1 <tr VALIGN=TOP> 234 <td VALIGN=TOP WIDTH="40%">The user types some English text prior to inputting 235 Japanese text. Using the arrow keys, the user moves the insertion position 236 between "Spot " and "Example" and switches his keyboard into Japanese Mode. 237 (This can be done through a hot key or a system menu)</td> 238 239 <td><img SRC="rootwindow1.jpg" height=186 width=329></td> 240 </tr> 241 242 <tr VALIGN=TOP> 243 <td>The user begins to type some Japanese phonetically.  The user 244 types the series [n,i,h,o,n] which the input method automatically translates 245 into the two Japanese syllables displayed on the right.  As the user 246 typed, the input method brings up a new window and displays the content 247 in that window.  This process is transparent to the application.</td> 248 249 <td><img SRC="rootwindow2.jpg" height=192 width=453></td> 250 </tr> 251 252 <tr VALIGN=TOP> 253 <td>Now that the user has entered the pronunciation of the word they want 254 tague 1.1 to add into the document ("nihon" or the Japanese word for Japanese), the 255 user selects the appropriate Kanji conversion for the syllables.  256 This causes the text in the root window to change, but is transparent to 257 the application.</td> 258 259 <td><img SRC="rootwindow3.jpg" height=190 width=454></td> 260 </tr> 261 262 <tr VALIGN=TOP> 263 <td>Finally, the User performs some action (usually pressing the return 264 key) which commits the final text.  The Japanese text is merged into 265 the document and is indistinguishable from the surrounding text.</td> 266 267 <td><img SRC="rootwindow4.jpg" height=185 width=333></td> 268 </tr> 269 </table> 270 </ul> 271 272 <h3> 273 <a NAME="Platform Protocols"></a>Platform Protocols</h3> 274 On each platform, input methods are supported by a protocol defined by 275 tague 1.1 the platform's windowing system. The following sections give an overview 276 of the protocols used on each of the major platforms which Seamonkey supports.  277 Consult the platform documentation for more detailed information. 278 <p><b>Windows</b> 279 <p>The windows input method protocol involves sending four different messages 280 to the event handler of a particular window.  To support the root 281 window style, the input method sends WM_CHAR events to the application.  282 Support for the on-the-spot (called inline in the Window's documentation) 283 is done through the WM_IME_STARTCOMPOSITION, WM_IME_COMPOSITION, WM_IME_ENDCOMPOSITION 284 messages.  Windows does not use the off-the-spot or over-the-spot 285 styles of input. 286 <p>Root window support is handled by the system transparent to the application.  287 The input method and the operating system handle displaying the various 288 stages of composition input until the user confirms the composition string. 289 The operating system handles confirmation by sending the application a 290 sequence of WM_CHAR messages representing the final composition string. 291 <p>Handling on-the-spot input is a bit more complex, in that the application 292 must respond to three additional methods: WM_IME_STARTCOMPOSITION, WM_IME_ENDCOMPOSITION, 293 and WM_IME_COMPOSITION.   The WM_IME_STARTCOMPOSITION and WM_IME_ENDCOMPOSITION 294 methods are used to bracket a single on-the-spot editing session.  295 The application needs to respond to WM_IME_STARTCOMPOSITION by creating 296 tague 1.1 whatever internal state is necessary for maintaining the on-the-spot composition 297 buffer.  Conversely, the application responds to WM_IME_ENDCOMPOSITION 298 by deleting the composition buffer and merging that text into the document. 299 <p>The WM_IME_COMPOSITION method contains a string which represents the 300 current state of the composition buffer.  The application needs to 301 extract this string (using ImmGetCompositionString) along with the associated 302 composition state data and render it in the document.  The application 303 will receive a sequence of WM_IME_COMPOSITION events as the status of the 304 composition buffer changes.  In windows, the WM_IME_COMPOSITION buffer 305 always contains the complete state of the composition buffer, it is not 306 additive like on other platforms. 307 <p><b>Macintosh</b> 308 <p>The Macintosh uses a protocol composed of four different AppleEvents 309 as well as standard events to support on-the-spot input, while root window 310 input is sent to the application through Get/WaitNextEvent event loop. 311 Like Windows, macintosh does not support off-the-spot or over-the-spot 312 styles. 313 <p>Root window support is again virtually transparent to the application.  314 The input method and the operating system handle the display of the composition 315 window and it's contents.  Once the composition string is confirmed, 316 the operating system sends the application a series of events.  An 317 tague 1.1 important point to note here is that the Macintosh will send Asian characters 318 as two events with the high byte of the character code in the first event 319 and the low byte in the second event. 320 <p>On-the-spot input is accomplished through the TSM AppleEvent suite: 321 Position2Offset, Offset2Position, Update, and GetText. The Position2Offset 322 and Offset2Position events are used to map between the document/application's 323 text buffer and global screen coordinates. 324 <p>The Position2Offset event requests a "hit test" of a particular point 325 in the global screen coordinates.  The application responds to this 326 event by constructing a AppleEvent reply consisting of the buffer offset 327 and region class of that particular point.  The region class indicates 328 if the point is outside the applications windows, inside one of the applications 329 windows or inside the active composition area.  The offset is a fixed 330 (linear) offset from the beginning of the document text buffer or a relative 331 offset (from the start of the active input area) depending on the region 332 class of the point.  Offset2Position does the reverse mapping taking 333 an offset and converting it into a global screen coordinate.  The 334 offset is relative to the start of the composition region, if it exists; 335 otherwise, it is relative to the start of the text buffer. 336 <p>The Update event is used to change the status of the composition buffer. 337 The Update event contains a string of characters that need to be drawn 338 tague 1.1 in the composition area.  Unlike windows, the Macintosh Update event 339 is additive so not all Update events will contain the complete string to 340 draw.  The application receives a sequence of Update events as the 341 composition buffer changes.  There is no special event like WM_IME_STARTCOMPOSITION

342           signaling beginning of a composition sequence. Ending composition is signaled
343           by a -1 in the composition buffer length.
344           <p>GetText is used to reverse a commit operation.&nbsp; A user selects
345           some text then does a special Undo operation.&nbsp; The selected text is
346           then converted into a composition area.&nbsp; The application creates a
347           new composition editing area and the composition buffer is initialized
348           the the selected string.
349           <br>&nbsp;
350           <p><b>Unix/X-Windows</b>
351           <p>Unix/X-Windows XIM, X Input Method protocol, uses a callback mechanism
352           to support all four styles of input; however the application and the input
353           method aren't required to support any particular styles.&nbsp; The application
354           selects a style to use by comparing the styles that are supported by both
355           the application and the input method and applying some algorithm to determine
356           which style is the best for that particular language.
357           <p>Once a style is selected, the application registers the appropriate
358           callbacks with the system and provides (through system calls on the XIC
359 tague 1.1 - X Input Context) what ever font or geometry information is required for
360           that style.&nbsp; Root window style requires a minimal amount of work for
361           the application, all it needs to appropriately convert key presses into
362           Input Method input using XwcLookupString or XmbLookupString.
363           <p>Over-the-Spot style requires the application to provide the input method
364           with information about about the current font and the location (coordinates)
365           of the spot.&nbsp; The application must change the font and spot location
366           information (through XSetICValue) as the document editing progresses.
367           <p>Off-the-Spot requires the application to provide the same information
368           as Over-the-Spot, but it also must handle geometry negotiation with the
369           input method.&nbsp; Since the input method needs to draw text in an area
370           of the applications window, the application needs to register a Geometry
371           negotiation callback with the system so that the input method can request
372           a larger area if necessary, or can be informed of changes to the application
373           window's geometry.
374           <p>On-the-Spot style requires the application to register a set of callbacks
375           of similar complexity to the events used in Windows and MacOS.&nbsp; To
376           support On-the-Spot, the application must register the following callbacks:
377           PreeditStart, PreeditDone, PreeditDraw, and PreeditCaret.&nbsp; PreeditStart
378           and PreeditDone are called at the beginning and end of preedit (i.e. input
379           method) input.&nbsp; PreeditDraw is called when the input method wants
380 tague 1.1 the application to display the preedit region or changing some of the highlighting
381           or the various input method clauses.&nbsp; PreeditCaret is called when
382           the input method wants the application to move the position of the inserton
383           point within the predit area.
384           <br>&nbsp;
385           <h3>
386           <a NAME="Editor Functions"></a>Editor Functions</h3>
387           The approach that we plan to take for supporting Input Methods in Seamonkey
388           is to find a common set of primitive operations which can be implemented
389           in cross platform code and can be combined in appropriate ways to support
390           a specific platform input method protocol.
391           <p>To support input method editing in Seamonkey, we need to add the following
392           methods to the editor component:
393           <ul>
394           <li>
395           Start Composition</li>
396           
397           <li>
398           EndComposition</li>
399           
400           <li>
401 tague 1.1 SetCompositionString</li>
402           
403           <li>
404           SetCompositionHilighting</li>
405           
406           <li>
407           SetcaretPosition</li>
408           
409           <li>
410           GetCaretCoordinates</li>
411           
412           <li>
413           GetOffsetFromCoordinates</li>
414           
415           <li>
416           GetRegionCoordinatesFromOffset</li>
417           </ul>
418           These actions should support the input method functionality required for
419           the various input method protocols.
420           <p><b>Start Composition</b>
421           <p>The Start Composition method is used to signal the beginning of a composition
422 tague 1.1 operation.&nbsp; In response to this method, the editor needs to set up
423           any context information and state to handle input method editing.&nbsp;
424           The editor needs to create the initial, empty preedit area.
425           <p>The preedit area needs to be implemented differently from a raw selection
426           since it is not hilighted and the user must be able to move the insertion
427           point around inside the preedit area.&nbsp; The editor needs to remember
428           the location and size of the preedit area, which can expand and contract
429           as the user types.
430           <p>The transaction manager should not record the intermediate transactions
431           in-between a Start Composition and an EndComposition operation.&nbsp; The
432           composition operation should be represented as a single transaction moving
433           from the state before the Start Composition to the state just prior to
434           the EndComposition.
435           <p>Only a single preedit area can be active at one time.
436           <p><b>EndComposition</b>
437           <p>The EndComposition method is used to close a preedit area and permanently
438           commit the predit text into the content buffer.&nbsp; The typing changes
439           between Start Composition and EndComposition should be represented as a
440           single transaction.
441           <p><b>SetCompositionString</b>
442           <p>The SetCompositionString method is used to set the current text of the
443 tague 1.1 preedit area.&nbsp; SetCompositionString can only be used when there is
444           an active preedit area (i.e. in between Start/EndComposition calls) in
445           the input buffer.&nbsp; Each call to SetCompositionString needs to set
446           the entire Preedit text (unlike some platforms which make use of additive
447           changes).
448           <p><b>SetCompositionHilighting</b>
449           <p>The SetCompositionHilighting method is used to apply application private
450           CSS style attributes to the text in the preedit area, so that it is hilighted
451           according to the platform's UI requirements.&nbsp; The CSS style attributes
452           are symbolic representations for the various different highlight states
453           (confirmed, raw, unconfirmed) used by input methods to provide the user
454           with feedback on the text conversion.
455           <p><b>SetCaretPosition</b>
456           <p>The SetCaretPostion method is used to position the insertion point (caret)
457           at a particular offset within the preedit area.&nbsp; This method will
458           not move that caret outside of the preedit area.&nbsp; The offset is relative
459           to the beginning of the preedit area and is specified in terms of Unicode
460           characters.
461           <p><b>GetCaretCoordinates</b>
462           <p>The GetCaretCoordinates returns the global screen coordinates of the
463           current Caret position, if there is no caret the method returns the appropriate
464 tague 1.1 status code.
465           <p><b>GetCoordinatesOfOffset</b>
466           <p>The GetCoordinatesOfOffset method returns the global screen coordinates
467           of the given offset into preedit area.&nbsp; The offset is relative to
468           the start of the preedit area and is specified in terms of Unicode characters.
469           <p><b>GetOffsetFromCoordinates</b>
470           <p>The GetOffsetFromCoordinates method does the reverse of GetCoordinatesOfOffset.&nbsp;
471           It returns the offset into the preedit area based on the character positioned
472           at the particular set of coordinates.&nbsp; The offset is specified in
473           terms of Unicode characters.
474           <p><b>GetRegionClassFromCoordinates</b>
475           <p>The GetRegionClassFromCoordinates returns the region class (inside a
476           document window, inside preedit area, outside application windows) of a
477           particular set of global screen coordinates.
478           <p>Note: this is a general function which needs to be supported by more
479           components than the editor.
480           <br>&nbsp;
481           <h3>
482           <a NAME="Refernces"></a>References</h3>
483           
484           <ul>
485 tague 1.1 <li>
486           <a href="http://java.sun.com/products/jdk/1.2/docs/guide/intl/spec.html">Java
487           Input Method Framework Specification (JavaSoft)</a></li>
488           
489           <li>
490           <a href="http://developer.apple.com/techpubs/mac/Text/Text-2.html">Inside
491           Macintosh: Text (Addison Wesley/Apple Computer)</a></li>
492           
493           <li>
494           <a href="http://msdn.microsoft.com/library">Developing International Software
495           For Windows 95 and NT (Nadine Kano)</a></li>
496           
497           <li>
498           X Windows on The World (Tom McFarland)</li>
499           
500           <li>
501           Xlib Programming Manual (Adrian Nye)</li>
502           
503           <li>
504           <a href="http://www.devworld.apple.com/dev/techsupport/develop/issue29/griffith.html">Gearing
505           Up for Asia With the Text Services Manager and TSMTE (Tague Griffith)</a></li>
506 tague 1.1 </ul>
507           
508           </body>
509           </html>