Introduction to EPOC Connect
by Richard Bloor
EPOC Connect In Action
This example use of EPOC connect involves reading details from a EPOC word file and converting it into an HTML file by detecting and adding HTML commands for:
headings
paragraphs
bulleted paragraphs which are considered as HTML lists
text in clear and greyed tables
bold and italicised text and
centred paragraphs.
The example has been prepared in Visual Basic. A copy of the Visual Basic 6 project can be obtained here.
Incidentally, this is a little more than a simple demonstration application. The author wrote this article on a Psion 5mx using the Word application and this code was used to create the HTML file you are now reading.
Finally as the COM interface actually accesses the EPOC word file while it is resident on a PC it can be run with only the Connect SDK installed. A test EPOC word file is available here.
Set up
The first task before this application could be developed was to add the PSIWORD.TLB type library file to the references in Visual Basic. The WORDOCX.OCX should already be registered.
User Interface
The user interface is very simple and provides for the selection of the file to convert, its destination and a button to start the process.
HTML "Converter" User Interface
Setting up the Path
If the executable is installed in the Connect folder or the Connect folder in the system path then updating the path is, obviously, not necessary. However to accommodate running from elsewhere the following code finds and sets up the path:
res = RegCreateKeyEx(HKEY_LOCAL_MACHINE, "Software\Psion\PsiWin32", 0, "", 0, KEY_ALL_ACCESS, SA, hKey, opened)
If res = ERROR_SUCCESS Then
res = RegQueryValueEx(hKey, "Installation Directory", 0, _
REG_SZ, szBuffer, szBufferlen)
If Len(Left(szBuffer, szBufferlen - 1)) > 0 Then
EPOCconnectInstallPath = (Left(szBuffer, szBufferlen))
End If
End If
envvar = "Path"
length = 2000
res = GetEnvironmentVariableA(envvar, Path, length)
' Add EPOC Connect installation path to the PATH
If InStr(Path, EPOCconnectInstallPath) = 0 Then
resstring = Left(Path, InStr(Path, Chr$(0)) - 1) + ";" _
+ EPOCconnectInstallPath
Debug.Print "Amended Path"
Debug.Print resstring
res = SetEnvironmentVariableA(envvar, resstring)
End If
|
The author originally coded this example in VBA (Visual Basic for Applications) and noted that without the Connect path being defined at boot time, e.g. in AUTOEXEC.BAT, Excel and Word produced a fatal exception when the module was run even with this code in place.
Obtaining details on the file content
In this example only a subset of objects from the EPOC Word OCX are being used as illustrared in the following diagram:
The first step is to create an EPOC word object and attempt to open the EPOC Word document:
Set myEPOCWord = New ObjEpocWord
On Error GoTo EPOCOpenFailed
Set myEPOCDoc = myEPOCWord.Open(SourceFile, 0)
On Error GoTo 0
|
Once the document has been opened the output file is created, checking first whether to replace any existing file or abort the conversion:
' Create temporary file to output converted text
FileNo = FreeFile
If Dir(DestinationFile) <> "" Then
temp = MsgBox("The output file " + DestinationFile _
+ " already exists" + Chr$(10) _
+ "Do you wish to replace it?", vbYesNo)
If temp = vbYes Then
Kill DestinationFile
Else
Exit Sub
End If
End If
Open DestinationFile For Output As FileNo
|
Now the rich text is reference from the document object and its paragraphs collection obtained:
Set theRichText = myEPOCDoc.GetRichText
Set theParaList = theRichText.Paragraphs
|
Then each paragraph in the paragraph collection is increment through and its position and length details (which we use to control phrase access) obtained:
LastParaStyleName = ""
' Process each paragraph in the document
For i = 0 To theParaList.GetCount - 1
Set thePara = theParaList.Item(i)
start = thePara.ParagraphStart
length = start + thePara.ParagraphLength
|
Now the paragraph output variable is reset and the paragraph format details obtained:
theParaToOutput = ""
' Obtain the paragraph format details, to allow code sections to be identified
Set theParaFormat = thePara.ParaFormat
theParaStyleName = thePara.StyleName
|
Using the Phrase object the EPOC word text is parsed converting or discarding special characters. Also note that in sections formatted to appear in tables any HTML control codes (< or >) are translated to characters:
' process each phrase looking for phases formatted in bold or italics
While (start < length)
thePhraseToOutput = ""
Set thePhrase = theRichText.GetText(start)
' Parse the text to convert EPOC word special characters to plain text
For index = 1 To Len(thePhrase.Text)
mycharacter = Mid$(thePhrase.Text, index, 1)
Select Case mycharacter
Case Chr$(6): ' para delimiter
' remove
Case Chr$(7): ' Line break
' remove
Case Chr$(8): ' page break
' remove
Case Chr$(9): ' tab
thePhraseToOutput = thePhraseToOutput + " "
Case Chr$(10): ' non-breaking tab
thePhraseToOutput = thePhraseToOutput + " "
Case Chr$(11): ' non-breaking hyphen
thePhraseToOutput = thePhraseToOutput + "-"
Case Chr$(12): ' potential hyphen
' remove
Case Chr$(15): ' visible space
thePhraseToOutput = thePhraseToOutput + " "
Case Chr$(16): ' non-breaking space
thePhraseToOutput = thePhraseToOutput + " "
Case "<"
If theParaStyleName = "Code Table" Or _
theParaStyleName = "Comment Table" Then
thePhraseToOutput = thePhraseToOutput + "<"
Else
thePhraseToOutput = thePhraseToOutput + "<"
End If
Case ">"
If theParaStyleName = "Code Table" Or _
theParaStyleName = "Comment Table" Then
thePhraseToOutput = thePhraseToOutput + ">"
Else
thePhraseToOutput = thePhraseToOutput + ">"
End If
Case Else
thePhraseToOutput = thePhraseToOutput + mycharacter
End Select
Next index
|
Now the phrase formatting is examined to find whether it has bold or italic formatting:
' If the phase has italic of bold formatting add HTML codes
If thePhrase.CharFormat.Italic Then
If Not (LastPhraseInItalics) Then
thePhraseToOutput = "<i>" + thePhraseToOutput
LastPhraseInItalics = True
End If
Else
If LastPhraseInItalics Then
thePhraseToOutput = "</i>" + thePhraseToOutput
End If
LastPhraseInItalics = False
End If
If thePhrase.CharFormat.Bold Then
If Not (LastPhraseInBold) Then
thePhraseToOutput = "<b>" + thePhraseToOutput
LastPhraseInBold = True
End If
Else
If LastPhraseInBold Then
thePhraseToOutput = "</b>" + thePhraseToOutput
End If
LastPhraseInBold = False
End If
start = start + thePhrase.length
theParaToOutput = theParaToOutput + thePhraseToOutput
Wend
|
Having completed processing the phrases in the paragraph any bold or italic formatting on the last phrase is closed. This somewhat verbose coding for italics and bold takes into account the fact that phrases may share some formatting elements (in fact examples can be found where phases share the same formatting). In particular it prevents italic or bold formatting appearing within HTML coding written into the original document (for example references in the index text).
' Complete any bold or italics formatting
If LastPhraseInBold Then
theParaToOutput = theParaToOutput + "</b>"
LastPhraseInBold = False
End If
If LastPhraseInItalics Then
theParaToOutput = theParaToOutput + "</i>"
LastPhraseInBold = False
End If
|
Having processed the text in the paragraph the paragraphs format is examined and acted upon (here we assume that if the paragraph has a bullet we process it identically to a paragraph with the Bullet style):
' Now process the converted paragraph
If theParaFormat.Alignment = EWORD_A_Centred Then
theParaToOutput = "<center>" + theParaToOutput + "</center>"
End If
If theParaFormat.HasBullet = True Then
theParaStyleName = "Bullet"
End If
' Now add formatting for paragraph styles
Select Case theParaStyleName
Case "Heading 1"
theParaToOutput = "<h4>" + theParaToOutput + "</h4>"
Case "Heading 2"
theParaToOutput = "<h5>" + theParaToOutput + "</h5>"
Case "Heading 3"
theParaToOutput = "<h6>" + theParaToOutput + "</h6>"
Case "Bullet"
' Deal with bulleted items
If LastParaStyleName = "Bullet" Then
theParaToOutput = "<LI>" + theParaToOutput
Else
theParaToOutput = "<LU>" + Chr$(13) + Chr$(10) + _
"<LI>" + theParaToOutput
End If
Case "Code Table"
If LastParaStyleName = "Code Table" Then
theParaToOutput = theParaToOutput + "<BR>"
Else
theParaToOutput = "<table border=""1"" width=""90%"" align=center><tr><td bgcolor=#BFBFBF><code>" + Chr$(13) + Chr$(10) + theParaToOutput + "<br>"
End If
Case "Comment Table"
If LastParaStyleName = "Comment Table" Then
theParaToOutput = theParaToOutput + "<BR>"
Else
theParaToOutput = "<table border=""1"" width=""90%"" align=center><tr><td>" + Chr$(13) + Chr$(10) + theParaToOutput + "<BR>"
End If
Case "Index"
If LastParaStyleName = "Index" Then
theParaToOutput = ">" + theParaToOutput + "<BR>"
Else
theParaToOutput = "<table width=""90%"" cellpadding=""5"" cellspacing=""0""><tr><td><font size=""2"" face=""verdana,arial,helvetica"">" + Chr$(13) + Chr$(10) + "<table border=0 cellpadding=8 cellspacing=0 align=right><tr><td bgcolor=#cccccc><font face=Arial,Helvetica size=2>" + Chr$(13) + Chr$(10) + "<b>INDEX</b>" + Chr$(13) + Chr$(10) + "</font></td></tr>" + Chr$(13) + Chr$(10) + "<tr><td bgcolor=#eeeeee><font face=Verdana,Arial,Helvetica size=1>" + Chr$(13) + Chr$(10) + ">" + theParaToOutput + "<BR>"
End If
Case "Preformatted"
' Do no further formatting on this paragraph
Case Else
theParaToOutput = "<p>" + theParaToOutput + "</p>"
End Select
|
As the document may contain blocks of similarly styled paragraphs changes in style are detected and the closing HTML control added when the style changes:
' Deal with ending of tables and bullet lists
If Not (theParaStyleName = "Bullet") And LastParaStyleName = "Bullet" Then
theParaToOutput = "</LU>" + Chr$(13) + Chr$(10) + theParaToOutput
End If
If Not (theParaStyleName = "Code Table") And LastParaStyleName = "Code Table" Then
theParaToOutput = "</code></td></tr></table>" + Chr$(13) + Chr$(10) + theParaToOutput
End If
If Not (theParaStyleName = "Comment Table") And LastParaStyleName = "Comment Table" Then
theParaToOutput = "</td></tr></table>" + Chr$(13) + Chr$(10) + theParaToOutput
End If
If Not (theParaStyleName = "Index") And LastParaStyleName = "Index" Then
theParaToOutput = "</font></td></tr></table>" + Chr$(13) + Chr$(10) + theParaToOutput
End If
LastParaStyleName = theParaStyleName
|
Having completed the processing of the paragraph it is added to the HTML file before continuing with the next paragraph:
Print #FileNo, theParaToOutput
Next i
|
Having processed the EPOC Word document the HTML file is closed, the objects cleaned up and the procedure exited:
Close FileNo
myEPOCWord.Close
Exit Sub
|
Conclusion
The EPOC Connect COM-Based architecture allows experienced Windows developers to build synchronization solutions for EPOC using
familiar development tools. For more information EPOC development, visit other WirelessDevNet
EPOC articles or the Symbian Developer's Network.
About The Author
Richard Bloor is the Mobile Applications Specialist at Equinox (www.equinox.co.nz)
who are based in Wellington, New Zealand. Richard can be reached at sherpa@netlink.co.nz.
|
