Category : C Source Code
Archive   : CWORD.ZIP
Filename : CWORD.DOC

C-WORD
A library of C functions to create Microsoft WORD documents





INTRODUCTION



Most application programs can redirect printer output into
a text file for further processing. Since these ASCII files
do not contain any formatting information, the user has to
take care of layout and graphic design manually. If a
complex layout with tables and different fonts is needed,
this formatting process takes up a considerable amount of
time.

With C-WORD, the programmer can easily create formatted
documents for Microsoft WORD from any application written
in C. The end user can now concentrate on text revision
instead of wasting his time correcting the layout. The
resulting documents can be printed on all printers
supported by Microsoft WORD.

C-WORD supports:

- all available fonts, font sizes and colors

- all of WORD's character formats: bold, italic, underline,
strikethrough, uppercase, small caps, super- and
subscripts, hidden text

- all of WORD's paragraph formats: left, centered, right
and justified alignment, indention and line spacing,
headers and footers

- tab positions and alignment, graphical elements like
lines and borders

- all of WORD's page formats: margins, page layout, multi-
column text, page numbering styles

- working with style sheets (available after registration)















C-WORD manual 1/92 (c) tesuji software page 1

NOTICE


Microsoft, MS and MS-WORD are registered trademarks of
Microsoft Corporation.























































C-WORD manual 1/92 (c) tesuji software page 2

USING C-WORD IN C PROGRAMS


Programming with C-WORD is very straightforward. Look at
the following minimal example to see how it is done. You
can find a more complex example EXAMPLE.C on your
distribution disk





#include

main ()

{
mw_open ("EXAMPLE.TXT");
mw_printf ("Hallo, Word\n");
mw_close ();
}



The header file mw.h contains all neccesary constants. It
has to be included in every module calling C-WORD
functions.

C-WORD is available as a library for Microsoft C and
Zortech C++. The supported memory models are small,
compact, medium and large. Software and manual are
available in English and German.

To compile the little example program with MSC you type

cl test.c mws.lib (small model) rsp.
cl /AL test.c mwl.lib (large model) etc.



The following function summary demonstrates the power of C-
WORD. A detailed description of each function is given
later.

















C-WORD manual 1/92 (c) tesuji software page 3

FUNCTION SUMMARY


mw_open () opens a new WORD document. This function
must be called before any operation on the
document can be performed.

mw_close () closes the current WORD document and writes
it to disk.

mw_printf () output of text into the current WORD
document. Works like the standard C function
printf ().

mw_putchar () output of single characters.

mw_font () selects a font for text output.

mw_fontsize () selects the size of the font.

mw_char () selects the character formats bold, italic,
underline, strikethrough, capitals, small
caps, double underline, super- and
subscripts, hidden text and text colors.

mw_paragraph() alignment of paragraphs (left, right,
centered, justified), headers, footers,
frames and lines.

mw_spacing () defines line and paragraph spacing, left,
right and 1st line indention.

mw_tab () setting and resetting of tab stops and
alignments (left, center, right, decimal,
vertical) and leader chars.


mw_division () sets division breaks, page and line
numbering, footnote layout and number of
colums.

mw_page () sets page length and width, margins and
running head positions, line and page number
positions.

mw_sty_open () opens a style sheet. This must be done
before any of the other style sheet
functions can be used.

mw_sty_char () selects a character format from the style
sheet.

mw_sty_paragraph() selects a paragraph format from the
style sheet.







C-WORD manual 1/92 (c) tesuji software page 4

mw_sty_division () selects a division format from the
style sheet.




























































C-WORD manual 1/92 (c) tesuji software page 5

FORMATTING IN MICROSOFT WORD


Microsoft WORD has three levels of formatting:

- character formats control the appearance of single
characters, words or other portions of text

- paragraph formats effect whole paragraphs, i.e. text
blocks between paragraph markers

- division formats normally control the layout of the whole
document



To write text into the currently opened document, you use
the functions mw_printf () or mw_putchar (). These
functions correspond exactly to the standard C functions.
Formatting information can be inserted into the flow of
output text. Depending on the formatting level this is done
as follows:

- Character formats are inserted immediately before the
text to be formatted. They remain in effect until
explicitely reset or changed. This applies to the
functions mw_char (), mw_font (), mw_fontsize () and
mw_sty_char ().

- Paragraph formatting commands can be given anywhere
during the active paragraph. They must only appear before
the newline character terminating the paragraph. They
remain active until you change them explicitely. You can
follow the simple rule to give all paragraph formatting
commands as soon as you start a paragraph that has to be
formatted differently. Paragraph formatting is done with
the functions mw_paragraph (), mw_spacing (), mw_tab ()
and mw_sty_paragraph ().

- Documents created with C-WORD only have one division
format, i.e. these formatting commands control the
appearance of the whole document. Therefore you can give
division formatting commands anywhere in your text. The
functions mw_division(), mw_page() und mw_sty_division ()
are used for division formatting.



The following list of character combinations shows how you
can insert WORD special characters in your text. You use
these characters like the printable ones in the functions
mw_printf () and mw_putchar ().








C-WORD manual 1/92 (c) tesuji software page 6

\n paragraph marker \t TAB character
\x0b NEWLINE character (SHIFT-ENTER)
\x0c page break
\x1f nonrequired hyphen
\xc4 nonbreaking hyphen
\xff nonbreaking blank






















































C-WORD manual 1/92 (c) tesuji software page 7

WORKING WITH FONTS


Fonts in Microsoft WORD are designed for the destination
printer. But WORD stores the fonts you use in a text in a
printer independant format. This allows you to change the
printer and still keep a similarly formatted document.

To give you the same functionality in C-WORD, fonts are
defined not by name (which would change from printer to
printer), but by a font number.

To see the correspondance between font names and numbers on
a specific printer you can use the utility program DF.EXE.
This program takes the pathname of your printer driver as
parameter and displays a list of available font names and
numbers.

For example: calling

df hp3.dbs


gives you the following output:

Font 0: Courier
Font 1: CourierPC
Font 3: Univers
Font 6: LinePrinterPC
Font 7: LinePrinter
Font 10: UniversCd
Font 16: CGTimes
Font 60: ZapfDingbats


You use these font numbers with mw_font () to set the
desired font.























C-WORD manual 1/92 (c) tesuji software page 8

WORKING WITH STYLE SHEETS


Formatting text by style sheets is one of the most
important features of advanced text processing with WORD.
C-WORD supports style sheets in a very straightforward way.

Before using any style sheet formats you tell C-WORD the
name of your style sheet. This is done with mw_sty_open ().

After that all formats defined in the style sheet are
available to you. You use these formats like direct
formatting commands with the functions mw_sty_char (),
mw_sty_paragraph () and mw_sty_division ().





LIST OF FUNCTIONS



mw_close ()

The creation of every WORD document must be completed with
this function. It writes text and formatting information to
disk. Unlike the standard C functions close () and fclose
() this operation will not be done automatically when you
exit your application. After closing a document with
mw_close () you can use mw_open () to create another one.



mw_open (char *path)

This function creates a new WORD document. If you give no
extension in the path parameter, ".TXT" will be used. An
existent document of the same name is deleted.

mw_open () must be called before any other function of this
package. Before you can open another document, you must
close the current one with mw_close ().

A return value different from zero indicates an error.
MWE_FILE means that the given file couldn't be created,
MWE_MEMORY means you are out of memory.



mw_printf (char *format, ...)

transfers text into the current document in the currently
selected format. Works like printf ().






C-WORD manual 1/92 (c) tesuji software page 9


mw_putchar (char c)

transfers a character into the current document in the
currently selected format. Works like putchar ().



mw_font (int font_number)

This function selects the given font. For the printer
specific correspondance of font numbers and font names
please refer to chapter "Working with Fonts".



mw_fontsize (float size)

This function selects the font size. The parameter gives
the desired font size in points. Since WORD can use
fractional point sizes, it is passed as a float variable.



mw_char (int opcode, int mode)

This function selects character formats. They remain in
effect until explicitely changed.

Together with the following opcode values the mode
parameter is either ON or OFF and activates rsp.
deactivates the given format:

MW_BOLD, MW_ITALIC, MW_UNDERLINE, MW_STRIKETHROUGH,
MW_UPPERCASE, MW_SMALLCAPS, MW_DOUBLE_UNDERLINE, MW_HIDDEN,
MW_SUPERSCRIPT, MW_SUBSCRIPT.

Another opcode MW_COLOR can be used with the color value as
mode parameter, it selects the given text color.



mw_paragraph (int opcode, int mode)

You use this function to select paragraph formats. They
effect the current and all following paragraphs. Other
paragraph formatting commands can be done with mw_spacing
(). The different subfunctions depend on the parameters in
the following way:

opcode MW_ALIGNMENT
mode MW_LEFT, MW_RIGHT, MW_CENTER, MW_JUSTIFIED:
controls the paragraph alignment.







C-WORD manual 1/92 (c) tesuji software page 10

opcode MW_KEEP_TOGETHER
mode ON or OFF:
If ON, there will be no page break before the current
paragraph.

opcode MW_KEEP_FOLLOW
mode ON or OFF:
If ON, there will be no page break after the current
paragraph.

opcode MW_SIDE_BY_SIDE
mode ON or OFF:
If ON, paragraphs will be printed side by side on the page.

opcode MW_HEADER
mode MW_EVEN_PAGES, MW_ODD_PAGES, MW_FIRST_PAGE:
formats the current paragraph as running head on top of the
page. The three possible mode values can be combined with
the binary OR operator (|).

opcode MW_FOOTER
mode MW_EVEN_PAGES, MW_ODD_PAGES, MW_FIRST_PAGE:
formats the current paragraph as running head at the bottom
of the page. The three possible mode values can be combined
with the binary OR operator (|).

opcode MW_NOMARGIN
mode is ignored:
Header rsp. footer is aligned without respecting the left
and rigth page margins.

opcode MW_WITHMARGIN
mode is ignored:
Header rsp. footer is aligned with respect to the left and
rigth page margins.

opcode MW_BOX
mode ON or OFF:
turns the box around a paragraph on or off.

opcode MW_SHADING
mode 0 to 100:
sets the background shading to the given percentage.

opcode MW_LINES
mode MW_LINE_LEFT, MW_LINE_RIGTH, MW_LINE_ABOVE,
MW_LINE_BELOW, OFF:
selects the given paragraph border lines. The listes mode
values can be combined by the binary OR operator (|).
Setting mode to OFF resets all border lines.

opcode MW_LINE_STYLE
mode MW_NORMAL, MW_BOLD, MW_DOUBLE, MW_STRONG:
selects the given border line style.







C-WORD manual 1/92 (c) tesuji software page 11

opcode MW_LINE_COLOR mode = color value:
selects the given border line color.



mw_spacing (int opcode, float par)

This function defines paragraph related indentions and
spacing. They effect the current and all following
paragraphs. The first parameter selects the subfunction,
the second parameter is a floating point value.

opcode MW_LINE_SPACING
par = line spacing in lines or MW_AUTO:
sets the line spacing to the given value, which also can be
a fractional value (like 1.5 for one and a half lines).
Using MW_AUTO adapts the line spacing to the largest font
used in the line.

opcode MW_SPACE_BEFORE
par = space in lines:
sets the space before the paragraph to the given value.

opcode MW_SPACE_AFTER
par = space in lines:
sets the space after the paragraph to the given value.

opcode MW_LEFT
par = indention in inches:
sets the left indention of the paragraph to the given
value.

opcode MW_RIGHT
par = indention in inches:
sets the right indention of the paragraph to the given
value.

opcode MW_FIRST_LINE
par = indention in inches:
sets the indention of the first line to the given value.



mw_division (int opcode, int mode)

This function selects division formats. It effects the
whole document. Further division formats are available with
mw_page (). The subfunctions are selected by the first
parameter.

opcode MW_PAGE_NUMBERS
mode ON or OFF:
turns page numbering on or off.







C-WORD manual 1/92 (c) tesuji software page 12

opcode MW_PAGE_NUMBER_FORMAT
mode '1', 'I', 'i', 'A' oder 'a':
selects the given page number format.

opcode MW_PAGE_NUMBER_START
mode = first page number:
starts page numbering at the given number.

opcode MW_MIRROR_PAGE
mode ON or OFF:
If ON, left and right margins are exchanged on even pages.

opcode MW_FOOTNOTES_AT_END
mode ON or OFF:
if ON, footnotes are printed at the end of the document, if
OFF they appear on the bottom of every page.

opcode MW_COLUMNS
mode = number of columns:
formats a multi column text with the given number of
columns.

opcode MW_LINE_NUMBERS
mode ON or OFF:
sets line numbering on or off.

opcode MW_LINE_NUMBER_RESTART
mode MW_PAGE, MW_DIVISION, MW_CONTINUOUS:
when should line numbering restart ?

opcode MW_LINE_NUMBER_INCREMENT
mode = increment value:
selects the increment for the printing of line numbers.



mw_page (int opcode, float par)

This function defines document related sizes and margins.
The second parameter is always a floating point variable
and holds the desired space in inches. Further division
related formats can be given with mw_division ().

opcode MW_LENGTH
par = page legth in inches

opcode MW_WIDTH
par = page width in inches

opcode MW_MARGIN_TOP
par = top margin in inches

opcode MW_MARGIN_BOTTOM
par = bottom margin in inches







C-WORD manual 1/92 (c) tesuji software page 13

opcode MW_MARGIN_LEFT par = left margin in inches

opcode MW_MARGIN_RIGHT
par = right margin in inches

opcode MW_HEADER_POS
par = running-head position from top in inches

opcode MW_FOOTER_POS
par = running-head position from bottom in inches

opcode MW_COLUMN_SPACE
par = space between columns in inches

opcode MW_GUTTER_MARGIN
par = gutter margin in inches

opcode MW_PAGE_NUMBERS_FROM_TOP
par = top margin for page numbers in inches

opcode MW_PAGE_NUMBERS_FROM_LEFT
par = left margin for page numbers in inches

opcode MW_LINE_NUMBERS_FROM_TEXT
par = distance of line numbers from text in inches



mw_tab (int opcode, float position, int alignment, char
fill)

This function sets or clears tab stops.

opcode: MW_SET, MW_CLEAR, MW_RESETALL

position: tab position in inches als floating point number
(not used with opcode MW_RESETALL)

alignment: MW_LEFT, MW_CENTER, MW_RIGHT, MW_DECIMAL,
MW_VERTICAL (only used with opcode MW_SET)

fill: ' ', '.', '-' oder '_' (fill character only used with
opcode MW_SET)



mw_dfv_paragraph (char *code)

This function selects a paragraph format of the previously
with mw_sty_open () selected style sheet. You pass the two-
letter key code as parameter to this function (in uppercase
!).








C-WORD manual 1/92 (c) tesuji software page 14

mw_dfv_division (char *code)
This function selects a division format of the previously
with mw_sty_open () selected style sheet. You pass the two-
letter key code as parameter to this function (in uppercase
!).



mw_dfv_open (char *path)

You use this function to select and open a style sheet for
the use with mw_sty_char (), mw_sty_paragraph () and
mw_sty_division (). If the path parameter doesn't contain
an extension, ".STY" will be appended.

A return value different from zero indicates an error.
MWE_FILE means that the given file couldn't be found,
MWE_MEMORY means you are out of memory.



mw_dfv_char (char *code)

This function selects a character format of the previously
with mw_sty_open () selected style sheet. You pass the two-
letter key code as parameter to this function (in uppercase
!).

































C-WORD manual 1/92 (c) tesuji software page 15