Notes on RichText() Class for Xbase++ 27 may 2003 Version 1.50 Author: Paul C. Laney Internet: pclaney@cs.com Original idea: Tom Marchione, Internet: tmarchione@cs.com SHORT DESCRIPTION Add-on to create RTF-Files, which can be opened and modified by most popular wordprocessors, for viewing and printing. It can be used as a report generator. RIGHTS/RESTRICTIONS 1. All source code is Copyright ¸ 2003 Paul C. Laney and Tom Marchione. All rights reserved, except as specifically indicated in this document. 2. As a Xbase++ user, you are granted the right to modify, compile and link the code for end- user application work, under the following conditions: a. You do not redistribute the code without permission from the author. b. All file headers are kept intact. c. The source code and/or object modules are not offered for sale. d. You do not port the code to another language, for other than personal use. e. You do not offer a substantially competitive language product for sale or distribution. f. You do not use the code in any kind of general purpose database management, reporting or computer language application. g. You do not use the code in any type of auditing or emergency response application (NOTE: This restriction is based on the fact that the author has business interests in these markets. If you have an application in one of these markets, but would still like to use the RichText() class, please contact the author. Depending on the application and the market, it may be possible to make alternate arrangements). h. You accept complete responsibility for the use of the code and any effects that it might have. I. You understand that future versions of the code may not be offered for free (although you may continue to use this version for as long as you like). CONTENTS OF VERSION 1.50 System Files: README.RTF This file README.TXT Plain text version of this file ALASKRTF.PRG Source code for RichText() class RICHTEXT.CH Header file for RichText() class Sample Files: ADDON.PRG Some extra functions which are used by the RichText()-class DEMRTF.PRG Sample application to add to the TopDown-Demo FLOWERS.DBF Database file used by sample application FLOWERS.DBT Memo file associated with FLOWERS.DBF VEGGIES.DBF Database file used by sample application RTFDEMO.RTF Output file from sample application MERGEIN.RTF Input file for sample application mailmerge MERGEOUT.RTF Output file from sample application mailmerge NOTOK.BMP Sample bitmap for RTFDEMO.RTF OK.BMP Sample bitmap for RTFDEMO.RTF PAUL.BMP Sample bitmap for RTFDEMO.RTF RTFTEST.BMP Sample bitmap for RTFDEMO.RTF GETTING STARTED RichText() has been primarily developed using the TopDown Library of Clayton Jones, but it can be perfectly used without it. It works fine in DOS-mode (See DOS-MODE), Hybrid-mode (See HYBRID-MODE) and GUI-mode (See GUI-MODE). If you're really curious about what this thing does, just go to the GUI-Mode map, and if you have Xbase++ 1,80, just execute "........EXE". If you have another version of Xbase++, just recompile it, by executing "start.bat". Then open the output file (RTFDEMO.RTF and MERGEOUT.RTF) in an RTF-capable word processor. If you don't have time to compile and run the app, I've included unedited copies of the output files in the package. REQUIREMENTS RichText() was written for use in Xbase++ applications. So as long as you have a legal copy of Xbase++ you can use it. Thanks to the Xbase++ pre-processor, you don't need to understand object-oriented programming to use the code. However, if you decide to fiddle with the source code of the underlying class, you will need to have a basic understanding of object-orientation. TOPDOWN Which files you have to add to the TopDown-Demo. Those files are: demRtf.prg alaskrtf.prg richtext.ch and to the DATA subdirectory: flowers.dbf flowers.dbt veggies.dbf rtfdemo.rtf mergein.rtf mergeout.rtf notok.bmp ok.bmp paul.bmp rtftest.bmp Those files are located in the TopDown Map. Furthermore add the following lines to the bottom of your Project.xpj: // Richtext demRtf.prg alaskrtf.prg Last, but not least, add the following lines to demoMenu.prg at the end of the MAINTANANCE section, just before the HELP section (see demoMenu.prg) : // ********** RICHTEXT ********** oMM:addSubMenu('mainbar','~Richtext', 'Rich', " RichTextMenu" ) oMM:addMenuItem( 'Rich', 'x1', { "~RichText", {|| demRtf() } }, " RichText Demo" ) That's all NOTE: As indicated in the RTFDEMO.RTF file, this file includes support for an automated table of contents. However, to see it, you need to insert it. Consult your word processor documentation for instructions, if you have never generated an automated table of contents. HYBRID-MODE Just look into the Hybrid_Xbase map, and execute "PROJECT.EXE". The file "addon.prg" contains Hybrid-replacements for some TD-Functions used by the TopDown library. DOS-MODE NOTE: By changing the user interface function tdGetSaveFile() in the file addon.prg, which is located in the Hybrid_Xbase Map, it should be possible to use the class in pure DOS-based Xbase++ applications. You have to change it by yourself. GUI-MODE Just look into the GUI_Xbase map, and execute "PROJECT.EXE". The file "addon.prg" contains GUI replacements for some TD-Functions used by the TopDown library. OVERVIEW RichText() is a class written for Xbase++, designed to export formatted data directly to Rich Text Format (RTF) files from within an application. RichText() allows you to leverage the power of common word processors as report formatting engines. Version 1.50 of the class includes: (1) the source code, build and README files, (2) Xbase++ directives for xBASE-style command implementation, and (3) a small sample prg. Version 1.50 of the class is being offered at no charge. This version implements a small subset of the RTF specification, as taken from Microsoft documentation. RTF is a very detailed specification, and the intent of Version 1.50 is to provide easy access to the most basic and useful features of RTF, including attributes such as page setup, fonts, paragraph formatting, character formatting, headers & footers, tables, etc. To date, most of my testing has been done with Microsoft Word. WHAT IS RTF? RTF is an open Microsoft file specification for transferring formatted text between applications. As such, it it's a great way to move formatted database information into word processors, in a true word processing format. HOW CAN RTF HELP ME? RTF is a great solution in at least three situations: 1. When there is a need to manipulate output in word processors, or integrate database information into other formatted documents. 2. When there is a requirement to build a custom report that must meet strict, detailed formatting guidelines. 3. When there is a need to publish a "turnkey" report that might include different formats, page orientations, fonts, etc. in a single document (my personal favorite.). The RichText() class is a simple, low-overhead solution for any of these situations. You can produce one-of-a kind, free-form word-processing documents (for a good example, see the sample provided with the class). The class is inherently oriented toward paragraphs, bullets, hanging indents, page orientation, etc., not standard database reporting fare such as column headers, subtotals, etc. (although you can easily dump data into nicely-formatted tables). Moreover, the output files are true word-processing files, without extraneous spaces, carriage returns, and other "lint" that makes life difficult in a word processing context. If you have ever tried to pass off a flat text output file (or even some RTF files produced by third party report generators) as "word processor compatible", you'll know what I mean. Compatible? Yes. Usable? Hardly. ESSENTIAL FEATURES OF RTF For detailed information about RTF, consult the Microsoft specification, which is available on the Internet. It is also helpful to analyze the contents of RTF files generated from word processors. Although the xBASE layer of RichText() makes many of the technical details transparent, it will be helpful to clarify a few issues here. Like many "open" file formats, RTF files are text files. RTF uses 7-bit ASCII characters (0-127) to represent formatting codes and data (higher-order ASCII characters must be represented in hexadecimal, which is handled transparently by RichText()). The two essential formatting characters in RTF are "\" (backslash) and "{}" (curly braces). All formatting commands are preceded by a backslash, and all "groups" are enclosed in curly braces. Groups delineate portions of a document to which combinations of formatting information may apply. Groups can be nested; the RTF file itself is considered a group, so all RTF files have at least one pair of curly braces, which encloses the entire contents of the file. All RTF files have an RTF header (which is to be distinguished from the headers and footers that you may place in an RTF document). The RTF header appears at the top of the file and contains information about fonts, colors, styles, etc. For example, the font table within the RTF header contains a list of all of the fonts that are used in the document. To switch fonts later the document, an index into this font table must be used. A similar system is used for colors. The RichText() class creates a basic RTF header for you. An application that reads RTF files is called an "RTF viewer", which, for our purposes, is usually a word processor. For the most part, data items that you write to an RTF file appear within RTF viewers in the sequence that you write them. However certain RTF commands implement alternate "destinations", such as headers and footers. RTF also supports the "sections" that are found in Microsoft Word, with section-specific layouts and formats. FINAL NOTES As I use the class more and more, it has become obvious to me that the class is more useful than I had originally imagined. As a result, I have spent a lot more time developing it than I had originally imagined. . In deference to the costs of adding new features, and improving the usability of existing ones, I probably will not be able to distribute future versions of the class for free. However, the cost should be insignificant relative to the benefits that you can offer to your end users, and your improved ability to give them exactly what they want for output. Some additional features that are either planned for the future, or that are partially implemented already, include. Improved Control Over Table Output Improved Control Over Paragraph Formatting Improved Application-Level Components Colors Lines and graphic objects Embedded Pictures Styles Language Support Footnotes/Endnotes Positioned Objects and Frames Index Entries Bookmarks Anything else in the RTF spec that seems useful. I greatly appreciate the feedback that I have received to date. If you have any ideas or suggestions, I'd love to hear them. Have fun! Paul C. Laney VERSION 1.50 FEATURE ADDITIONS 1. Pictures Support You can add one or more pictures via the ..... command. Note that pictures are not embedded in the RTF-file. Only the link to the picture-file is embedded. So be sure to distribute the pictures too. You can use all picture formats supported by your RTF-Reader. VERSION 1.00 FEATURE ADDITIONS 1. Page Number Support You can add a simple page number via the INSERT PAGENUMBER command. Typically, this is most useful when defined within a header or footer. 2. File Checking When defining the RTF, the WARNOVERWRITE clause will cause the class to generate a warning message if an existing file will be over-written. In addition, you can use the GETFILENAME and FORCEPATH clauses to allow the user to specify a file name, as well as to force the file to be written to a specific path. 3. Table of Contents Support You can generate an automated table of contents. You can mark any paragraph for inclusion in a table of contents at a particular level by specifying the TOCLEVEL clause. Refer to the sample application for a simple example. VERSION 0.91 FEATURE ADDITIONS Merge Away! I added a crude subsystem and demonstration of how one could exploit RTF files for defining report formats and merging database information into them. With this system, you can embed Xbase++ expressions throughout the "primary" merge file (which can be any old RTF), and then run a relatively tiny Xbase++ program to merge your database info into it. It's very much like a standard "mail-merge" that you might do from a word processor, but with the sophistication and flexibility of Xbase++. For a simple, silly example, see files MERGEIN.RTF and MERGEOUT.RTF. MERGEIN.RTF is a "primary" merge file, and MERGEOUT.RTF is the actual file that is produced by the example program. Notice that MERGEIN.RTF contains a number of delimited Xbase++ expressions. Most of these are intended to return text, but I also threw in a couple examples to demonstrate how you might control the record pointer from the merge file itself. In other words, any valid, macro- compilable Xbase++ expression is fair game. Of course, any functions that you call in the primary merge file must be linked into your program (if this doesn't ring a bell, see the Xbase++ documentation regarding "REQUEST"). The wonderful advantage of this approach is that you can effectively use a word processor (!) to design a report format (for certain types of applications). If you need to tweak the look of the output, or even change it drastically, you just load up MS-Word and make the change to the primary file -- no clumsy report writer, and no code changes. And, of course, you get all of the power of a true, word-processor based report. The downside of the system, as it currently exists, is that it is very slow. My algorithm is not particularly efficient, and there are inherent speed limitations. Not only does it have to macro compile every Xbase++ expression that it encounters, it does it repeatedly for each record. Arrrgh! In addition, I have not yet included an error handler to trap bad Xbase++ expressions, though this would be simple to do. The system seems to work OK with the example, but be warned that I have not tested it with anything else yet. I imagine that it would be easy to make it self-destruct in its current incarnation...