home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmrepo.zip / MANUAL.DOC next >
Text File  |  1994-08-22  |  9KB  |  257 lines
  1. Very Important note: Please don't display this file in the report control
  2. as it contains embeded codes used only for illustration and can render
  3. the document unreadable.
  4.  
  5.  
  6.                                Summary
  7.                                =======
  8.  
  9. Report is a Presentation Manager control that eases the process of creating
  10. formatted output reports. This control takes its input from an ASCII
  11. text file, and produces a report on screen or sends it to the printer. The
  12. input file can have many formatted styles. To center a line, a simple
  13. command like {align_center} will cause the line to be centered.
  14.  
  15. Report treats each input line as a paragraph. A paragraph is defined as
  16. any input line terminated by a CR/LF combination. The paragraph can not
  17. exceed 4096 characters. This relieves the programmer from having to write
  18. to the GPI and provides him/her with very powerful text formatting options
  19. available only in major word processors.
  20.  
  21. Usage
  22. =====
  23. The programmer typically creates the report mechanically thru a series
  24. of printf statements and embeds all necessary control codes in the file.
  25. A window of the report class is then created and the text file is passed to it.
  26. The report control paginates and displays the text to the screen or prints it
  27. to the printer.
  28.  
  29. Control Styles
  30. ==============
  31. Upon control creation several styles can be specified. The RS_DRAFTMODE
  32. ignores all character formatting embedded in the file and uses the default
  33. printer font and point size. This leads to maximum printing speed. This style
  34. effects screen previewing which displays the file ignoring all embedded
  35. fonts,styles and point sizes.
  36.  
  37. Embedded Codes
  38. ==============
  39. The following is a list and the explanation of all the codes that can be
  40. embedded in the text file. Note that embedded codes are case insensitive. They
  41. must be surrounded by braces {code <parameters>} They also carry on to the
  42. next paragraph. If bold_on is specified on the first paragraph, the whole
  43. file will be bold unless it was turned off by inserting a bold_off code.
  44.  
  45.  Paragraph settings                Default
  46.  ------------------                -------
  47.  align_right                       align_left
  48.  align_left
  49.  align_center
  50.  
  51.  
  52.  Tabs
  53.  ====
  54.  This control supports four different styles of tabs. left, Right, Center and
  55.  decimal tabs. Up to 10 different tab positions can be set for a paragraph.
  56.  The tab definitions are carried over to the next paragraph. Tab positions are
  57.  defined using the {def_tabpos position,type} token where position is the number
  58.  of inches from the left margin. Type can have four different values:
  59.  1,2,3,4 for Left,Right,Centered and Decimal tabs respectively.
  60.  
  61.  The following demonstrates a left tab at 2.5":
  62.  {def_tabpos 2.5,1}
  63.  
  64.  The following demonstrates a Centered tab at 4.5":
  65.  {def_tabpos 4.5,3}
  66.  
  67.  It is very important to note that tabs carry over to the next paragraph.
  68.  To delete a tab stop, the (delete_tabstop tab position) must be used.
  69.  
  70.  Fonts
  71.  =====
  72.   This control supports the fonts built into any printer specified. In addition,
  73.   support for screen and downloadable fonts. There are several commands that
  74.   can be specified to manipulate fonts and syles.
  75.  
  76.   {font facename}
  77.   ---------------
  78.   This command sets the current font. The parameter should be a Face name
  79.   string that does not contain any compound styles. For example,
  80.   {font Helvetica} sets the current font to Helvetica. Whereas specifying
  81.   {font Helvetica Bold}, the results will be UNPREDICTABLE. In order to obtain
  82.   the Bold Style, use the {bold_on}/{bold_off} styles. To specify Helvetica Bold,
  83.   use : {font Helvetica}{bold_on}. The Control defaults to "Times New Roman"
  84.   if an invalid font was supplied or no matching screen font exist.
  85.  
  86.   The following styles can be used:
  87.  
  88.   Styles
  89.   ------
  90.   {underline_on/off}
  91.   {bold_on/off}
  92.   {italic_on/off}
  93.   {strikeout_on/off}
  94.  
  95.  Point Size
  96.  ==========
  97.    This control allows yopu to set the point size from 1 to 255 points.
  98.    It uses scalable fonts to display text on the screen and render them to the
  99.    printer. The fonts are scaled on the fly and can be printed to any
  100.    printer supported by PM. A point is 1/72 of an inch or 20 twips.
  101.    {pointsize 48} will scale the current font to 48 points
  102.    {pointsize 12} will restore the point size to 12 points.
  103.  
  104. Position Commnads
  105. =================
  106.  
  107.      {pagebreak}
  108.      -----------
  109.      If a paragraph contains this token, a new page is inserted and the current
  110.      paragraph is made the first one on the new page. For example in the
  111.      following input:
  112.  
  113.      Tester
  114.      Hello Word{pagebreak}
  115.  
  116.      "Tester" is placed in a separate page from "Hello World".
  117.  
  118.  
  119.                               Control Messages
  120.                               ================
  121.  
  122. RM_SETFILE
  123. ----------
  124. This message loads the file specified in mp1. If mp1 is NULL, the contents
  125. of the control are cleared.
  126.  
  127. RM_QUERYFILE
  128. ------------
  129. Returns the currently loaded filename in the buffer pointerd to by mp1.
  130.  
  131. RM_SETMARGINS
  132. -------------
  133. Low word of  mp1 has left margin size
  134. High word of mp1 has Right margin size
  135. Low word of  mp2 has Top margin size
  136. High word of mp2 has Bottom margin size
  137.  
  138. This messages sets the margins of the document pages. All these measurments
  139. are in twips. An inch is 1440 twips. Repagination of the document is
  140. invoked whenever the margins are altered. The default margin size is 1/2"
  141. an inch. If the margins exceed the page width a FALSE will be returned.
  142. Otherwise a TRUE will be returned.
  143.  
  144. RM_QUERYMARGINS
  145. ---------------
  146. Caller should pass a pointer to an array of 4 elements of USHORT size.
  147. The call returns the margins in the following order:
  148.  
  149.     1) Left margin
  150.     2) Right margin
  151.     3) Top margin
  152.     4) Bottom margin
  153.  
  154. Please note that all measurments are in twips. This message always returns
  155. TRUE.
  156.  
  157. RM_SETPRINTER
  158. -------------
  159. This call resets the printer to the one specified by caller. If caller
  160. passed a DevOpenStruc in mp1, then the window will use that information
  161. and sets the page size according to the form currently set by the
  162. printer driver. If NULL was specified, then the default installed printer is
  163. used. Repagination is invoked after printer has been changed.
  164. If the printer info passed is not valid a FALSE will be returned.
  165. Otherwise a TRUE will be returned.
  166.  
  167. RM_SETMARGINVIEW
  168. ----------------
  169. Toggles margin view state. If mp1 is TRUE, margins are made visible otherwise
  170. they are made invisible. Note that margins are never printed.
  171.  
  172. RM_QUERYMARGINVIEW
  173. ------------------
  174. Returns the current margin view. TRUE is enabled FALSE otherwise.
  175.  
  176. RM_SETCURRENTPAGE
  177. -----------------
  178. Brings into view the page specified in Low word of mp1. Several predefined
  179. constants can be used in place of the page number.
  180.  
  181. PAGE_TOP,PAGE_BOTTOM,PAGE_NEXT,PAGE_PREVIOUS. This function returns the
  182. current visible page or -1 if an error occured.
  183.  
  184. RM_QUERYCURRENTPAGE
  185. -----------------
  186. This message returns the current visible page.
  187.  
  188. RM_QUERYPAGECOUNT
  189. -----------------
  190. This message returns the number of pages.
  191.  
  192. RM_QUERYPAGESIZE
  193. -----------------
  194. This message returns the page dimention. mp1 and mp2 should contain pointers
  195. to ULONGS. *mp1 and *mp2 will be filled with the page width and height
  196. respectively.
  197.  
  198.  
  199.                             WM_CONTROL
  200.                             ----------
  201.  
  202. Many WM_CONTROL notification mesages are sent to the owner of the control.
  203. These are used to signal the owner of some event. The following are
  204. events:
  205.  
  206. mp1 has Control ID in Low word of mp1 and notification code in the high
  207. word.
  208.  
  209. mp2 has a certain value depending on the notification code.
  210.  
  211. Notification codes
  212. ==================
  213.  
  214. RN_ERROR
  215. --------
  216. This notification code is usualy generated by the helper threads. This is their
  217. way of communicating error messages with invoker. mp2 has the error ID.
  218.  
  219. ERROR_MEMORY     Memory Error
  220. ERROR_SYSTEM     System Errors. Win/Gpi/Dos errors
  221. ERROR_TAB        Can not insert more Tabs
  222. ERROR_POINTSIZE  Point size is 0
  223.  
  224. Control Creation:
  225. ----------------
  226.  
  227. PM Report is a regular PM control. It needs to be registered and then
  228. created using WinCreateWindow. The following Code demonstrate creation:
  229.  
  230.   // Register the control Class
  231.  
  232.     RptRegisterClass(hab);
  233.  
  234.   // Create the window
  235.  
  236.     hwndReport = WinCreateWindow(hwnd,
  237.                                   szReportClass,
  238.                                   (PSZ) "",
  239.                                   WS_VISIBLE,
  240.                                   0,
  241.                                   0,
  242.                                   0,
  243.                                   0,
  244.                                   hwnd,
  245.                                   HWND_TOP,
  246.                                   10,
  247.                                   NULL,
  248.                                   NULL);
  249.  
  250.   // Load a text file into it
  251.  
  252.    WinSendMsg(hwndReport,
  253.               RPM_SETFILE,
  254.               MPFROMP("report.doc"),
  255.               NULL);
  256.  
  257.