Label Generation

Mailing Labels
ddoc contains a number of functions designed to expedite the printing of mailing labels. ddoc reads a template for the mailing labels (description of rows and columns that make up a label) from an .ini file. This .ini file is called ddocml.ini and is located in the ddoc\include directory. In this file I have defined a couple mailing labels for your use (Avery 5260 (3 columns x 10 rows) and Avery 5162 (2 columns x 10 rows). I encourage you to develop your own labels. The .ini file is fully documented, so you should be able to define your own labels with little trouble. If you wish to share your label definition with others, please email them to me and I will keep them posted on my web site for all to download.

Note that the label engine respects calls to dpFont. This means that if you want the first line of any label to be bold and rest to be italic, all you need to do is insert dpFont calls appropriately between the dpLabelText calls and the engine will print accordingly.

Initializing the label engine
The first step in printing mailing labels is telling ddoc which label definition you wish to use. To do this, the programmer calls dpMailInit. dpMailInit takes the name of the .ini file that defines your labels and the name of the section describing the label you want to use. It also takes an alignment parameter to let the engine know if you want your labels centered or left justified (it also will right align labels, although I can't think of a reason you would want to do this.)
Note: When you specify the mailing label .ini file, be sure to specify the full path to the file. If you just specify the file, the .ini file will not be found unless it is in the \windows directory on that machine. ddoc uses the standard windows api .ini file handling routines which assume that .ini files will be in the \windows directory.

Label basics
Once the engine is initialized, calls to print text on the label can be made. There are really only two calls that are usually used … dpLabelText and dpNextLabel. The engine takes care of the details of knowing where to print the text and which label you're currently on as well as inserting new pages, all you need to worry about is what text you want to print and when you're ready to move on to the next label. 

hPreview% = dpStartDoc( . . . )
if hPreview% > 0 then
   if dpMailInit(hPreview, "c:\ddocml.ini", "Avery5260", DDOC_LEFT) = 0 then
   
      '- Print out 100 labels.
      For a% = 1 to 100
         dpFont hPreview, DDOC_FONTNORMAL, 10, vbBlack, "Arial"
         dpLabelText hPreview, "Label #" + str($a%) + ", Line # 1"
         dpLabelText hPreview, "Label #" + str($a%) + ", Line # 2"
         dpLabelText hPreview, "Label #" + str($a%) + ", Line # 3"
         dpLabelText hPreview, "Label #" + str($a%) + ", Line # 4"
         dpNextLabel
      Next a%
   end if
   dpEndDoc hPreview%, DDOC_END_VIEW + DDOC_END_DELETE
end if

Advanced label techniques
Although the built in automatic label functions, dpLabelText and dpNextLabel, are very powerful and make the job of label printing easy, it may be necessary to have more control over the label output. ddoc's label engine has a few helper functions to give the programmer that control.

  1. dpLabelX and dpLabelY return the coordinates of the upper-left corner of the current label, so if you want to add specially positioned text, lines, or even graphics to a label, you can calculate the correct positions.
  2. dpLabelLines lets you know how many lines of text a label can hold and dpLabelsPerPage tells how many labels are on a page.
  3. The dpSetLabel lets you tell the engine which label to use next. All labels on a page are numbered. The numbering starts in the upper-left corner with #1. The label directly below #1 is #2 (labels are numbered vertically). If there are 10 labels in a column (like Avery 5260's), the 11th label is located just to the right of #1. dpSetLabelLine will let you start printing on a certain line on the Page.
  4. Finally, ddoc provides a built in mechanism to preview what any label definition will look like without actually writing code to print the labels. Call dpPrintTemplate to automatically print a page of labels. The sample programs installed on your system contain examples of how to do this.