NewLeaf for Dyalog12: Concepts

Concepts

NewLeaf is a Causeway product which provides the APL developer with a set of page-layout and reporting tools which generate high-quality printed output from simple APL arrays.

Installation | Installing NewLeaf
New1998 | Features Added in 1998
New1999 | Features Added in 1999
New2000 | Features Added in 2000
New2001 | Features added in 2001-4
Frames | Frames on a Page
Para | Paragraphs in a Frame
Styles | Paragraph Styles
Text | Text within a Paragraph
Spooler | Preview and Printing
Viewer | Viewing Reports
Acrobat | Web and Intranet Publishing

The NewLeaf workspace has many examples of simple reports which can be copied and extended as required.


NewLeaf for Dyalog12: Installing NewLeaf

Installing NewLeaf

What you get

NewLeaf is shipped as a Dyalog APL workspace, a help file, a collection of phrasebook files for the viewer, a handy reference, and this manual. You can simply copy the workspace to your normal development directory, along with the help file. If you have CausewayPro installed, you might prefer to put the help file with the other Causeway tools, for example in \dyalog\outprods\causeway. Make sure that the [Paths] section in causeway.ini points to the correct directory if you do this (causeway.ini is in the Windows directory).

Checking it out

To ensure your copy is correctly installed, load the workspace and type Test. This will build quite a complex report, with an embedded chart and table. When it completes, run View PG to see the result. You might like to try some of the other examples listed in the welcome message, for example Caps (to check Drop Caps) and John (to check for scandics). You can also check the page designer – run Layout.Design 'xx' and press F1 to make sure the help file can be located.

What you need in your application

The essential NewLeaf code is all held in two namespaces, so to make it available to your application code, simply copy them:

)xload myapp

)copy newleaf leaf PostScrp

A simple health check would be to run a short report:

leaf.Init

leaf.Use ''

leaf.Place 234 12⍴'Fat cat. '

leaf.Rule 3

View leaf.Close

This will make a default layout, and should have 1” margins all around, with page numbers centred at the foot. Use the Print Page button in the viewer to print it on your default printer, and check that all the elements appear correctly. If this all worked, you are clear to start working through the tutorials!


NewLeaf for Dyalog12: Features Added in 1998

Features Added in 1998

Here are some of the additions to NewLeaf from January 1998:

  • Groups (of paragraphs, tables, charts etc.) as logical units which will be kept together if possible
  • Soft Hyphens in text and table headers
  • Overlays to allow arbitrarily complex master pages
  • Fixed text can now be written at any angle
  • New classes for wrapping text and edged or shaded rectangles
  • Metafiles are supported as master page classes, or in-line in text with optional wraparound
  • Cell shading supported by List as well as by Spread
  • Table Gridlines may now be set for each row of data (List and Spread)

Some other interesting changes are:

  • Much faster setting of simple tabular data
  • HTML and CSV output in parallel with main report
  • Option to have NewLeaf generate unique names for the spool files (essential for Windows NT Server applications)


NewLeaf for Dyalog12: Features Added in 1999

Features Added in 1999

Here are some of the additions to NewLeaf from January 1999:

  • Frames can be added (and used) on the fly – see PushFrame and PopFrame
  • Simple line-drawing capability for flowcharts and diagrams
  • Spread will now accept tables wider than the frame and generate extra pages working across.
  • Fit to page capability added to Spread – reports can be scaled to a single page or constrained to occupy no more than n pages wide.
  • Tables now have headings, subheads, captions and footnotes (scaled correctly if fitted to page)
  • Internet-style colours supported by all text elements
  • Cell background colouring added to List and Spread

For full details, see the release notes in the workspace or on the internet.


NewLeaf for Dyalog12: Features Added in 2000

Features Added in 2000

Here are some of the additions to NewLeaf from January 2000:

  • Bookmarks can now be set on any text object. They are shown in the ‘jump to page’ dialogue in the viewer and may be used to build a hierarchical table of contents in a PDF built from a NewLeaf document.
  • All menus and captions in the viewer are now translatable using external text files. Viewer settings are saved in the registry.
  • Simple tab support is now available in leaf.Flow. Left and Right tabs may be set in a tabrack, and tab characters embedded in the text stream will jump to the next available tabstop.
  • Emphasis styles ‘underline’ and ‘strikethrough’ are now available. Underline may also be specified by an HTML tag.
  • RTF from the RichEdit control may be printed using leaf.Richtext (this is not a full RTF parser – it is limited to the RTF parameters supported by the RichEdit, or WordPad).
  • Cell by cell indenting of any column in a table.
  • Optional left argument to List and Spread to set any cell property as a matrix matching the table data.

See the release notes (in the workspace or on the website) for full details.


NewLeaf for Dyalog12: Features added in 2001-4

Features added in 2001-4

  • PDF documents may be created directly from NewLeaf reports. This capability can be used to make files suitable for attaching to emails (PDFs are known to be virus-safe) or just for electronic distribution via the internet. See How to make a PDF for more details.
  • A table of contents can now be generated automatically from the style settings for various heading levels.
  • The designer can now take a left argument of the zoom factor, which allows you to work easily on very large paper sizes.
  • Blocks may be used to mark a section of any report which may be bordered and edged with specified gutter and border.
  • Rounded corners on tables – the rounding property sets the corner-rounding for the outer frame of the table.
  • Page references – support added for XML-style tag to resolve references to bookmarks as page numbers. The placeholder &n on the master-page resolves to the total number of pages.
  • HTML generation – the completed NewLeaf report may now be saved in HTML format for inclusion as part of a web-page or for publishing in its own right as a complete HTML file.
  • Wraparound bitmaps may be placed at the right margin.


NewLeaf for Dyalog12: Frames on a Page

Frames on a Page

NewLeaf is a frame-based publishing tool. Frames are rectangular areas on the paper where you want your text to be printed. You will always need at least one frame, so if you start a new printing job with a completely empty page definition, NewLeaf assumes that you want 1-inch margins all round, and a page number centred at the bottom. In the thumbnail, you can see the paper (in grey) with an outer rectangle showing the printable area (which will vary depending on your printer driver) and an inner rectangle (the frame) where some text has been printed. All measurements are in Points (one point = 1/72 of an inch), in an (x,y) co-ordinate system based on an origin at the bottom left corner of the paper.

Note that in NewLeaf, measurements are always from the edge of the paper, so your reports will come out exactly the same, even if you change printers.

You can have as many frames on the page as you need – by default the text simply flows to the next available frame when it fills the first one, but you can give names to your frames and control the way text flows using these names.

As well as frames, a page-definition may have other elements such as a company logo, a page number, vertical and horizontal rules, the date and time of printing, and so on. These will repeat on every subsequent page, with the page number incrementing automatically.

Finally, it is possible to define a sequence of page definitions, which could be used to alternate left/right layouts for double-sided printing.


NewLeaf for Dyalog12: Paragraphs in a Frame

Paragraphs in a Frame

Here you can see a frame with three paragraphs of text written into it. The first has normal line spacing, and is aligned at the left margin; it has a little extra space after it. The second is indented, and has a bullet character to mark the first line. The third is again ranged left, but has a higher interline spacing, or perhaps is printed in a larger type size.

You can pre-set any of these properties by using paragraph styles – these are described in the next section.

This is typical of the way NewLeaf handles free text – the APL application supplies a set of text vectors (one per paragraph) and some formatting instructions, for example to treat each paragraph as a numbered indent with a given margin and spacing. NewLeaf then flows the text into the width of the frame, and will automatically move to a new page when the frame is full.

If you have some pre-formatted text (such as a function listing) you can place a text matrix rather than flowing a text vector. In this case NewLeaf does not attempt any wrapping, and any lines that do not fit the frame overflow to the right.

Some of the paragraph properties which you may like to investigate in more detail are: Font (typestyle, size and spacing); Colour; Indents; Keep Together; Minimum Space After; Alignment. These are all set initially to reasonable defaults, so that you can ignore the more advanced properties until you need them.


NewLeaf for Dyalog12: Paragraph Styles

Paragraph Styles

NewLeaf is designed to help the APL programmer to produce smart text output with a minimum of application code. The best way to cut down the amount of fussy detail is to set up a table of style definitions (called a Gallery) and re-use these as you need them.

For example, for a major heading, you might want a larger font, centred on the page, possibly with a page break before. For an APL function listing you will need your APL font, perhaps a small indent and some control over page-breaking. By setting up appropriate styles, you can hold all the necessary paragraph properties in one place, which make it easy to change (for example) your APL font.

For details on setting up and using styles, see ...

  • Defining Styles
  • Setting and Unsetting a particular Style
  • Using Styles with Flow and Place


NewLeaf for Dyalog12: Text within a Paragraph

Text within a Paragraph

HTML tags

Normally, NewLeaf handles a complete paragraph as a unit, and assumes that there is no variation of typestyle, size or line-spacing within it. However a small number of HTML-style tags are supported if you need to add emphasis or footnote references within a table or the body text. These are:

<b>Here is some Bold Text</b>
<i>This will be in italics</i>
<code>Code is fixed-pitch courier</code>
<sup>This is a footnote reference (small superscript)</sup>
<sub>This is small and sub-scripted</sup>
<font face=symbol>This would be in Symbol font</font>

Bookmark references

You can refer to a bookmark with an XML-style tag such as <pageref “mybookmark” /> which will be resolved to the page-number where the bookmark is located. If the report is completed and the bookmark has not been defined, the string “ERR” is shown in-place of the page number. This may be used to refer to other topics in the document by page-number, or to build a simple Table of Contents at the beginning.

Hyphenation

NewLeaf does not attempt any automatic hyphenation, however the ‘tilde’ character is taken by default as a ‘soft hyphen’ so you can include it in long words such as super~cali~frag~ilistic as many times as you like. If necessary, NewLeaf will take one of these as a line-break opportunity and then eliminate the remaining tildes from the broken word. This applies wherever text is wrapped, for example in paragraphs output by leaf.Flow, in table cells formatted by leaf.table.Spread and in table column headings.

See also – leaf.SoftHyphen


NewLeaf for Dyalog12: Preview and Printing

Preview and Printing

NewLeaf is shipped with a simple print-preview tool, which you can use to browse long reports, zoom in on details, and print selected pages. There are two ways of using this, suitable for short reports (less than 10 pages) or volume output.

Small reports

The simple way to handle low volume output is to have NewLeaf return the entire completed report to the workspace as a simple vector:

leaf.Use mylayout     ⍝ Start
leaf.Place ....
leaf.table.Spread ...
rpt1←leaf.Close      ⍝ retrieve entire report
PostScrp.View rpt1   ⍝ Preview it
PostScrp.Print rpt1  ⍝ Print it to default printer

The preview tool allows you to page up and down, and you will find that the <Home> and <End> keys go to the beginning and end of the report. To zoom in, drag a ‘rubber-band’ rectangle enclosing the area to be magnified. Click anywhere to zoom out, or use the right-mouse menu.

High-volume output

The above method is not suitable for reports of more than 20 or so pages, as the data volume can get quite large and the algorithm for selecting pages can easily give WS FULL. It is much better to leave the report on the external spool file (which NewLeaf builds as it goes) and browse it from there. Because the spool file holds one page per component, there is no workspace overhead in selecting (say) page 567 from a 5000 page report!

leaf.Use rpt2
leaf.table.ColTitles 'Jan' 'Feb' ...
leaf.table.List ?12345 12⍴100
fn←leaf.Spool ''      ⍝ Close file but leave on disk
PostScrp.View fn      ⍝ Preview as before
PostScrp.Print fn     ⍝ Print entire report

By default, the spool file is called ‘newleaf.spl’. Alternatively you can use the right argument to name this file and thus save several reports on disk at the same time.

To jump straight to a specific page, or run the print from a page to the end:

leaf.NumPages 'newleaf.spl'     ⍝ How many pages are there?
567 PostScrp.View 'newleaf.spl'      ⍝ go in at page 567
23 45 PostScrp.RunOff 'newleaf.spl'  ⍝ run pages 23,45 only

You can safely delete the spool file as soon as you have finished with it.


NewLeaf for Dyalog12: Viewing Reports

Viewing Reports

This shows the viewer toolbar, which you can use to copy the page to the clipboard, print the current page (or all pages if you are viewing a report made up of several pages), or return to full-screen view if you zoom in. Multi-page reports can be navigated from the keyboard (PgUp/PgDn) or you can use the ‘VCR-style’ tool buttons. The rightmost button activates the ‘Go to page ...’ dialogue, which is also invoked with the F5 key, or by double-clicking the status field where the current page number is shown.

To magnify part of the report, drag a rectangle around it with the left mouse button. The area shown will be based on the top edge of the area you enclose, keeping the correct aspect ratio.

When you have zoomed in, you can ‘walk’ around the page using the arrow keys, or zoom out with the ‘-’ key. You will notice that the (x,y) co-ordinates in the status field at the lower right track the mouse, using the points co-ordinate system, with the origin at the lower left corner of the page.

This shows the right-mouse menu, which duplicates the toolbar functions, and also allows you to clipboard the page to a bitmap at normal size or enlarged for printing. If you select the PostScript or EPS options, you will be prompted for a suitable device (such as ‘prn’) or filename. The entire report will be printed, but only the current page is saved as an EPS file.


NewLeaf for Dyalog12: Web and Intranet Publishing

Web and Intranet Publishing

As well as producing excellent results on paper, NewLeaf is ideal for generating online reports for viewing as PDFs with the Adobe Acrobat viewer. It also supports HTML generation, so that simple text reports and tables can be published on the World Wide Web and viewed in any standard browser.

Saving reports as HTML

Any NewLeaf report may be saved as HTML using the utilities in the MakeHTM workspace (a free download from the website) but please be aware that this can never be totally ‘what you see is what they get’ as the final rendering depends on the user’s web-browser, their personal choice of CSS style sheet, and so on. However for simple reports and tables, this is a very lightweight and useful publishing technique.

Saving reports for Acrobat Viewer

You can output directly to PDF with the utility functions:

'mydoc.pdf' pdf.PS PG

You will need to copy in the supporting functions from the pdf namespace which is included with the NewLeaf workspace.

You can now take the .PDF and copy it to your Web server or mail it to your customers. Anyone with the Acrobat viewer (available free from Adobe’s web site) will be able to download it very quickly, and zoom in on the detail just as you can with the NewLeaf preview tool.


NewLeaf for Dyalog12: How to ...

How to ...

This section has a set of simple examples to show how a basic report can be constructed in very few lines of APL.

Report | How to Print a Simple Report
Headers | How to Add Headers and Footers
Listings | How to Make an Intelligent Function Lister
Graphics | How to Include Graphs
Tags | How to Mark Text as Bold or Italic
Tables | How to Format a Table
Form | How to Design a Form Letter
Specials | How to Add Special Effects
Columns | How to use Multiple Columns
Masters | How to Alternate Master Pages
HTML | How to generate a simple web page
PDFs | How to Create Adobe PDFs


NewLeaf for Dyalog12: How to Print a Simple Report

How to Print a Simple Report

This is a typical report structure. It has a heading, a paragraph or so of introductory text, a table of data (perhaps with left and right aligned columns) and some extra notes at the foot. It may well flow over several pages, in which case the report titles should repeat at the top of each new page.

To make this kind of report in NewLeaf, you can simply use the default page layout (one frame, with page-number centred at the bottom) and output text directly to it. For example:

leaf.Use ''                        ⍝ Default page layout
leaf.Style 'Heading'               ⍝ Take the supplied style
leaf.Place 'Here is the Heading'   ⍝ Assume it will not wrap
leaf.PopStyle                      ⍝ Revert to previous style
leaf.Flow (text)(text)(more text)  ⍝ Wrap paragraphs of text
leaf.table.Set ('Coltitles' 'text' 'text')  ⍝ Set up table header
leaf.table.Spread matrix           ⍝ Do the report
PostScrp.View leaf.Close           ⍝ Preview the result

If you want to send the report directly to the printer, use PostScrp.Print in place of PostScrp.View. However you can use the right-mouse menu on the preview screen to print the report, or send it to an EPS file.


NewLeaf for Dyalog12: How to Add Headers and Footers

How to Add Headers and Footers

Most reports have recurring elements which ‘top and tail’ the page. In the thumbnail we have a company name (printed in a bold font), some kind of logo, and a page number at the foot. The body of the report will fit in the frame which occupies the rest of the page.

A page such as this can easily be set up by hand, but a better way might be to use the NewLeaf page-design tool to lay out the elements visually:

Layout.Design 'mypage'   ⍝ Create a new layout

When you exit the Designer, you will find a variable mypage in your workspace which defines your design. This is a 5-column table, where the first 4 columns are standard for all NewLeaf objects: type; id or caption; position; size. Column-5 lists any other relevant properties, for example the font for the fixed text used to place the word ‘Company’ or the scan resolution used to make the bitmap for the logo.

To try out your report, simply ...

leaf.Use mypage   ⍝ Note that no quotes are needed here

and flow some text into the frame ...

leaf.Flow 'This is a really interesting report ...' 'and so on'

Finally PostScrp.View leaf.Close to see how it looks.

You can modify the elements of the page definition by hand from APL (for example to change the page number to show ‘Page nn’) or you can simply redesign the form by calling Layout.Design again.


NewLeaf for Dyalog12: How to Make an Intelligent Function Lister

How to Make an Intelligent Function Lister

When listing APL functions, most people are anxious to avoid getting the odd lonely line at the top or bottom of a page. On the other hand, simply setting a paragraph as ‘keep together’ can result in huge amounts of white space if you are dealing with long functions.

In NewLeaf this is handled by two paragraph properties:

MinAfter – space in points
Keep – number of lines

These work together to keep subheadings attached to the paragraph they refer to, and to prevent blocks of text from being split in unfortunate places.

Typically, a function listing would be run using a paragraph style with Keep set to a number between 6 and 10. This would result in a function of (say) 12 lines skipping to a new frame if it found itself about to be placed within 6 lines of the end of the frame. If each listing was accompanied by a subheading, this could be set to MinAfter sufficient for 8 lines of listing, or around 96 points assuming our listings are running at 12-point line spacing.

Note that for normal text, the default value of MinAfter is 0, but that Keep is initially set to 2 to prevent ‘widows’ at the bottom of pages.


NewLeaf for Dyalog12: How to Include Graphs

How to Include Graphs

If you also use the RainPro graphics software from Causeway, you might like to include high-quality graphs as part of the finished report. NewLeaf can include a completed Rain graphic, either with a text wrap-around, or scaled to the full width or height of the frame. If the chart does not fit completely into the remaining vertical space, NewLeaf will move automatically to the next frame.

Assuming that you have the charting functions available:

ch.Set ('heading' 'My Chart')('style' 'nomarkers')
ch.Plot mydata
chart←ch.Close
leaf.Use ''
leaf.Place 'Here comes a chart'
leaf.Include chart            ⍝ Scale to frame width
page←leaf.Close
leaf.View page

The completed chart has been saved in the variable chart, which includes information such as the fonts used and the bounding box. This is automatically merged into the report, which can be viewed or printed as normal. To have text wrapped around a small chart, set the chart size with ch.New 0 0 x y and use leaf.IncludeLeft to place it.

Note that you canalso include one completed NewLeaf report in another, and so on ad infinitum. This can be used for thumbnails, or to construct booklets from spooled reports.


NewLeaf for Dyalog12: How to Mark Text as Bold or Italic

How to Mark Text as Bold or Italic

When emphasis is required in a table or as part of a paragraph, you can mark the appropriate elements with the HTML-style tags <b> for bold and <i> for italics. Another tag you can use is <sup> for superscript which adjusts the baseline and font size appropriately.

<b>Here is some Bold Text</b>
<i>This will be in italics</i>
<sup>This is a footnote reference (small superscript)</sup>

Typically this would be used to emphasise a name or address in a form letter such as ...

leaf.Flow 'Dear Mr ',∆name
leaf.Flow 'What a surprise to see the <i>',∆prize,' </i> at ...'

... and so on.

Similarly, you could use ∆Item<sup>1</sup>∇ to make a footnote reference from within a table. Note that it is good practice to ‘escape’ the characters < and > as &lt; and &gt; when they occur within bold or italic sections. Otherwise there is a possibility that these characters will be misinterpreted as closing tags, and will not show in your output.

See also ...

leaf.Flow – flow text into frames


NewLeaf for Dyalog12: How to Format a Table

How to Format a Table

Formatting tables is one of the main strengths of NewLeaf, in particular its ability to wrap text within cells and provide exact control over column spacing and alignment. These are all tasks which have become very much harder now that we must work with proportionally spaced fonts, possibly in a variety of sizes. You can use leaf.table.List for simple columnar reports or leaf.table.Spread if you need detailed control over cell wrapping and formatting.

Tables can be formatted very precisely, but an easy start is just to take all the defaults and let NewLeaf do it for you:
leaf.Use ''                 ⍝ Default page definition
leaf.table.List 3 4⍴⍳12     ⍝ Tabulate some data
pg←leaf.Close
PostScrp.View pg            ⍝ To preview it

This will divide the frame width evenly into 4 columns, border the table, rule vertically and add horizontal hairline rules between rows. Note that there is no need to format the data if you are happy with APL’s default format.

In this example, all columns are left aligned (the default) and there are no headings. To set these properties on the table:

leaf.table.Align 'left' 'right' 'decimal2'    ⍝ Columns
leaf.table.Titles 'Name' 'Age' 'Salary'

or ...

leaf.table.Set ('al' 'le' 'ri' 'd2')('co' 'Name' 'Age' 'Salary')

Note that all column properties are reshaped to match the data, so to alternate left and right, just give two alignments.

Typically, tables are best fitted automatically into the frame width, but you will want to specify exactly the majority of the cell widths. For example:

leaf.table.CellWidths  ¯1 72 72

Here the rightmost columns (age, salary) are both 1” wide (remember that all dimensions are in points) and any spare space in the frame is given to the name. If you only give widths for some of the columns, the remainder share the available space evenly. Of course if you specify all the columns explicitly, then the overall size of the table is simply the sum of the cell widths, as long as this is less than or equal to the frame width. If it is greater, you will find that both List and Spread will fold the entire table, using as many pages as necessary.

Note that Spread wraps cell contents automatically into the grid, and that a cell is never broken across a page boundary. List only accepts one line of data per cell, and can be set to clip at cell boundaries if required.

Using tree-structured headings

A common requirement is to span several columns with a top-level heading, then break down into more detail:

  ┌─────────────────────────────────────────────────┐
  │            Salaries Report 1996                 │
  ├─────────────────────────────┬────────┬──────────┤
  │ Name                        │    Age │   Salary │
  ├─────────────────────────────┼────────┼──────────┤
  │ Adrian Smith                │     42 │    5,678 │
  │ And so on                   │     21 │  123,000 │
  └─────────────────────────────┴────────┴──────────┘

Assuming column widths of 300, 100, 100, this could be set up with the following NewLeaf commands:

leaf.table.CellWidths 300 100 100
leaf.table.Titles 'Salaries Report 1996' 'Name' 'Age' 'Salary'
leaf.table.TDepth 0 1 1 1
leaf.table.Spread ∆data
PostScrp.View leaf.Close

The TDepth property defines a tree-structure – it should have the same number of entries as there are titles, and (of course) there should be as many ‘leaf’ entries as there are columns. To give multi-line titles, simply enclose the relevant elements ...

leaf.table.Titles 'Name' ('Age' 'at entry')('Salary paid' 'to date' '1996')

... and the title row will automatically expand to accommodate 3 lines. You may also want to use soft hyphens in long column names to allow NewLeaf the flexibility to line-break at sensible points.

Controlling the grid lines

There are three line weights associated with the table: the outer border, the vertical rules, and horizontal hairlines. These default to 1pt, 0.8pt and .01 pt (hairline) respectively. To get a heavy border and no horizontal lines:

leaf.table.Set 'Grid' 3 1 0 ⍝ weight in points

The 1st element is always scalar, but you may need to rule vertically between some columns and not others (or separate some with a heavier line), and similarly for the horizontal separators. To do this, you specify a vector of line weights as the middle or last element of the set:

leaf.table.Set 'Grid' 1 (0 .5) .01

... which will alternate on/off between cells.

If you want a heavy horizontal separator, you can simply call the table’s Rule function which rules horizontally between the table edges:

leaf.Use ''
leaf.table.Spread ∆mat95
leaf.table.Rule 2           ⍝ Rule across table
leaf.table.Spread ∆mat96
leaf.Close

Alternatively, you can specify a vector of weights for the horizontal lines as the third element of the Gridlines.

Checking the space available

NewLeaf will report exactly how much space is left in the current frame, so that you can check this and skip manually to a new frame if the space cannot accommodate sufficient rows. See Info in the functions reference for more detail.

Handling wide tables

In NewLeaf you have two approaches to formatting a table which does not fit comfortably on one page:

  • use table.List which will generate part-pages, working down the rows, then stepping across the columns.
  • use table.Spread which will step across the columns, then work down the rows.

In general, you will find that List is faster (it has fewer formatting options, for example it cannot wrap text automatically to create multi-line cells) but Spread is more flexible (it allows you to specify font and colour by cell, rather than by column). Both options allow you to hold an arbitrary selection of columns, so that they repeat on every part-page (see the keystyle property) and Spread additionally allows you to specify an upper limit to the number of pages wide (see the fit to page property), in which case the finished report is uniformally reduced to fit on the paper.

For example, to fit a 52-week sales summary across no more than 3 pages, with the first 2 columns repeated on each part-page:

leaf.Use ''
leaf.table.Titles ('Item' 'Name','W',¨⍕¨⍳52)
leaf.table.Fit 3
leaf.table.CellWidths 72 144,52⍴56
leaf.table.Heading 'Sales Report for 1999'
leaf.table.KeyStyle 1 1,52⍴0
leaf.table.Align 2 52/'left' 'right'
leaf.table.Spread ('X101' 'Y234','Jam' 'Cake',?2 52⍴1000)
PostScrp.View PG←leaf.Close

Note that if you are using the ‘fit to page’ capability you should set the heading as a property of the table so that it repeats at the head of the ‘first’ page and is reduced by the same factor as the table body.


NewLeaf for Dyalog12: How to Design a Form Letter

How to Design a Form Letter

Form letters are typically used by direct mail houses, or financial institutions. The layout always contains an address box (which must align correctly with the window in an envelope), and then usually has free text wrapped into the available width.

In the thumbnail above, there is a single frame for the text, an address box and a company logo. If you look carefully, you will also see a very short light rule near the left edge; this is to mark the fold point on the paper. To position the address box, measure carefully from the edge of the envelope to the address window, and note the dimensions. Then use the NewLeaf page design tool to make a frame at approximately the right spot, and set the exact co-ordinates in the Properties Box.

If you name the frames ‘Address’ and ‘Body’ you can produce your finished letter as follows:

leaf.Use formletter
leaf.NewFrame 'Address'     ⍝ Select the frame
leaf.Place ∆address         ⍝ Text matrix
leaf.NewFrame 'Body'        ⍝ Skip to body text
leaf.Flow ∆letter           ⍝ Flow the text
leaf.NewPage                ⍝ on to the next!

Note that it is better to use ‘Place’ for the address, as you will want to determine where the line-breaks come, and that you should set the address frame to (‘Overflow’ 1) so that if an address overflows the frame it simply continues out of the bottom of the frame, rather than skipping automatically into the body text area.


NewLeaf for Dyalog12: How to Add Special Effects

How to Add Special Effects

ewleaf can improve the impact of your text with two simple special effects. Drop caps can be used to highlight the first letter of a section so that the eye is naturally drawn to the correct starting point. This is particularly useful in multi-column layouts to give a clear starting point for a new section.

Sometimes you need to wrap text around a bitmap – typically a screen shot – which is handled similarly. The BitmapLeft function takes the name of a bitmap file and an optional scan resolution (default 96dpi for screen shots) and places it at the left indent point in the current frame. The next paragraph(s) will wrap around the rectangular region made by the bitmap.

Drop Caps

To print the first character of a section oversize:

leaf.DropCap 1↑para
leaf.Flow 1↓para

The default is to use the current font, and to span 2 lines of normal text at the current pitch. To use a different number of lines, optionally in a different font:

leaf.DropCap 'T' 5 'heb'  ⍝ 5 line drop, Helvetica bold

Wrapping around bitmaps

To add a screen snap or scanned image at the left margin:

leaf.BitmapLeft 'shot5.bmp'
leaf.BitmapLeft 'artwork.bmp' 300

... assuming your scanner was set at 300dpi for the artwork.


NewLeaf for Dyalog12: How to use Multiple Columns

How to use Multiple Columns

Because NewLeaf is entirely frame-based, all you need to do to work in multiple columns is to draw a master page with a number of side-by-side frames. Text will first flow down the left-hand frame and will then wrap automatically to the top of the second, and so on.

You can use Info to find out which column you are in, and how many lines are left. To skip manually to the next column, call NewFrame '' which will take the next available frame.

If you skip to a new page, NewLeaf will always start to flow text into the first frame in the page layout. You can override this with leaf.FlowList to set a specific running order for the frames.


NewLeaf for Dyalog12: How to Alternate Master Pages

How to Alternate Master Pages

If you are preparing output for double-sided printing, you may require different layouts for left and right pages, for example to leave a large inside margin for spiral binding of the finished report.

To set up a sequence of pages, first design them as normal, being careful to get the measurements balanced:
Layout.Design 'left'
Layout.Design 'right'

Then set up a sequence of pages:

leaf.Use left right  ⍝ NB no quotes here!!

If you set up a list of two pages, NewLeaf will simply alternate them. If you provide a longer list NewLeaf will use them from the left until only two remain, which will then alternate as before. This allows the possibility of a set of custom opening pages, perhaps for contents or copyright details, followed by alternating masters.

Of course you can simply supply a vector of layouts to accommodate the entire report, if you know exactly how much space your text will require and are willing to do all page throws under application control. Otherwise, call leaf.Switch to change layout ‘in flight’ when you need to.

Booklets

If you need to prepare a report for duplex printing as a booklet (e.g. pages 8-9 facing, backed by pages 10-7 and so on) you can spool the report and use leaf.Include with leaf.Fetch to assemble it. See the Booklet example in the NewLeaf workspace.

     leaf.Use ''
     leaf.Place 645⍴⊂⊃txt
     leaf.NumPages  ''
13
     qq←leaf.Spool 'temp'  ⍝ NOT the default name!
     PostScrp.View qq
OK
     Booklet qq     ⍝ Generates 2 new spool files


NewLeaf for Dyalog12: How to generate a simple web page

How to generate a simple web page

When you save a report as HTML, you are relying on the user’s browser to format it approximately as you see it in your preview, however the exact layout will always vary a little. NewLeaf uses CSS1 styles to get the ‘look and feel’ of the report as similar as possible – you should experimant with the results in a variety of different browsers to be sure this format is adequate for your needs.

You will need the functions in the html namespace which is included in the NewLEaf workspace. You might also like to grab the CSSEdit utility from the freestuff area at the same time (see below).

Preparing to create HTML

NewLeaf needs to store extra formatting information to enable HTML output, so before you generate you report, you must turn on ‘mirroring’ by calling:

leaf.Mirror 1

This setting will be saved with the workspace, and is not reset when NewLeaf is next initialised.

Designing a Style Sheet

NewLeaf is shipped with a default CSS1 stylesheet (supplied in the workspace and as newleaf.css) which will be used to map from the standard styles (Heading, Subhead etc.) to similarly named paragraphs in the generated HTML. If you have made any custom styles with leaf.DefineStyle, you will need to add these to the style sheet. You may do this using the workspace copy with the APL editor, or you can use the CSSEdit utility from the freestuf/cssedit page on our website to edit the copy on file. This approach will be much easier if you are not familiar with the CSS terminology.

Saving your report as HTML

The procedure is very similar to printing or publishing a report, except that you may wish to name your own CSS style-sheet. You also need to append some HTML ‘boilerplate’ to the core of the report – this is to allow you to include the NewLeaf part of the output into a predesigned webpage to co-ordinate with the rest of your site.

The first stage is to create the report in the normal way, and save it in the workspace or on a spooled file:

leaf.Use mylayout
leaf.Place 'Hello, world'
PG←leaf.Close

It is likely that some elements in mylayout will be required on the HTML page (for example a company name at the top) but not all elements are relevant (page numbers are usually meaningless here). Accordingly, you should edit the layout and explicitly mark any page elements you want to appear in the HTML content as ‘Top of Report’ and so on. You can mark elements as ‘Top of Page’ or ‘End of Page’ but note that only hard page-breaks (created with leaf.Newpage) will be mirrored in the HTML (as heavy horizontal rules) so these are unlikely to be useful.

The next stage is to convert your report to HTML format:

htm←MakeHTM PG

This creates valid HTML content, bracketed top and bottom with <div>....</div> tags to mark it out clearly. However it is not a complete web-page – it requires a header section and <body> .... </body> delimiters at a minimum. You can have NewLeaf create a valid HTML wrapper for you with the utility call:

head←CSS1 MakeHeader PG

This takes a sample stylesheet as the optional left argument and returns the header portion of the HTML page. If you have used leaf.Titlebar to give your report an explicit title, this will be set as the title for the web-page so that it appears in the titlebar of the web-browser.

Finally, you will want to write the completed page as a native text file:

 page←head,htm,⎕tcnl,'</body></html>'
 'c:\temp\leaf.htm' htmPut page

You can now open the html file in Internet Explorer to check the results. Note that when you are testing a new report, you can leave the file open in Explorer and simply overwrite it repeatedly (as above), using the ‘Refresh’ button on the browser to check the results.

See also ...

leaf.Mirror – enable HTML and other formats


NewLeaf for Dyalog12: How to Create Adobe PDFs

How to Create Adobe PDFs

The Adobe ‘Portable Document Format’ is an ideal way to format printed output so that it can be distributed electronically, and viewed or printed on any computer, whether Unix, Mac or Windows. NewLeaf can be used to create PDFs in two ways:

  1. by preparing a PostScript print file for the Acrobat Distiller
  2. directly, using the functions in the pdf namespace

You will need to use Distiller if your document contains any pictures in Windows Metafile or EPS format. Simply save the result of a NewLeaf report to any file in Distiller’s inbound directory with:

filename PostScrp.WritePDF PG

... and Distiller will do the rest.

Writing PDFs directly

If your document is composed entirely in the base fonts, and you only have RainPro charts and bitmap or JPEG pictures, you can create the PDF directly with the functions supplied in the pdf namespace. You will need to copy this into your application in addition to the normal NewLeaf code, then you can use it as follows:

'mydoc.pdf' pdf.PS PG

This will take a NewLeaf document, or the name of a spool file, on the right and the name of the output file on the left. If you omit the left argument, the PDF document is returned as a simple text vector. To assemble a collection of reports into a single PDF, create each one as a spool file and pass a vector of file names here. You may mix portrait and landscape paper orientations this way, but you must take care of the page numbering yourself.

For either method of PDF production, you may use leaf.Bookmark or the TOC property to create an outline tree in the PDF document.


NewLeaf for Dyalog12: The Page Designer

The Page Designer

NewLeaf can handle complex master-pages. This secion shows you how to create them in the visual page-design tool.

Designer | Introducing the Designer
Props | Setting Properties
Toolbars | The Designer Toolbars
Designing | Adding and Arranging Objects
Dsr_Summary | Summary


NewLeaf for Dyalog12: Introducing the Designer

Introducing the Designer

What is a page layout?

NewLeaf holds your page definitions in a 5-column APL matrix, where each page is composed of a set of ∆objects∇, starting with a ∆pg∇ object to define the paper size and orientation. A typical layout, with a default frame, and a page number object, could look something like:

┌──┬───────────┬───────┬───────┬─────────────────┐
│pg│Page Layout│201 101│595 842│┌──────┬────────┐│
│  │           │       │       ││Paper │A4      ││
│  │           │       │       │├──────┼────────┤│
│  │           │       │       ││Orient│Portrait││
│  │           │       │       │└──────┴────────┘│
├──┼───────────┼───────┼───────┼─────────────────┤
│fr│Text       │36 74  │516 732│┌────────┬─┐     │
│  │           │       │       ││Autoflow│1│     │
│  │           │       │       │├────────┼─┤     │
│  │           │       │       ││Clip    │1│     │
│  │           │       │       │└────────┴─┘     │
├──┼───────────┼───────┼───────┼─────────────────┤
│tx│Page #     │216 14 │144 48 │┌────┬─────┐     │
│  │           │       │       ││Font│ti,14│     │
│  │           │       │       │└────┴─────┘     │
└──┴───────────┴───────┴───────┴─────────────────┘

All objects have data in the first four columns, giving the object type, caption/id, position (ignored for the paper!) and size. Values are measured in points (72 points = 1 inch), with the origin at the lower left corner of the paper. Any non-default properties you set for the objects are recorded in column-5 as a two-column matrix of property-value pairs.

To start the designer with a new layout ...

Layout.Design  'myrpt'

This will allow you to construct the various objects visually, and to check the appearance of your finished page by filling the frames with sample text. The completed layout will be saved in the APL variable myrpt. You can, of course, modify or copy this matrix using APL in the normal way:

newrpt←myrpt
Layout.Design 'newrpt'

... and so on. The Designer makes a quick check of your screen resolution and sets the scale of the layout to accommodate A4 paper (portrait) of A3 (landscape). If you need to work on a larger size you can override this setting with an optional left argument such as:

2 Layout.Design 'newrpt'

This will display the page at half the normal size and would allow you to work on A3 paper in portrait orientation.

The next few pages will walk you through the main components in the page designer, so that you are able to make simple reports quickly, and understand how to set about building a complex multi-column design with additional elements such as artworks and rules.


NewLeaf for Dyalog12: Setting Properties

Setting Properties

Objects and properties in the Designer

When you start the Designer with a new variable, it automatically adds one frame (centred horizontally and vertically on the paper) and a page number at the foot of the page. Here is what you will see if you type:

Layout.Design 'pg1'

The paper is shown with a lightly-ruled grid. As objects are added to the page, they are drawn as frames or lines with handles at the upper left and lower right corners. Here you can see the default frame (with 1” margins all round) and the page number (represented as &p) ⍴” from the foot of the paper. The grid/rulers are always marked in inches and halves.

Beside the main ∆paper∇ window you will see the ⍒Property Watcher⍋ which displays the detailed information about the object you most recently clicked on. In this case, it is showing the information related to the paper itself – click anywhere on the ∆body∇ frame and you will see it change to look like:

The titlebar shows the name of your layout variable, and the object type in view. Then you have a text field where you can change the caption or id of any object. If you type something here, you will see the changes reflect immediately into the page window.

You will also notice that the caption field is always given focus as soon as you click on an object in the page window – this allows you to enter fixed text quickly and easily.

The position and size fields show the location in points of the object, measured from the lower left of the paper. Note that for text, the numbers measure to the baseline of the characters. You may be puzzled by the negative numbers here – they relate to the ∆attach∇ property which is explained in the next section.

Using the Attach Buttons

Below the position/size fields is a bank of six toggling buttons which control how the object is attached to the edges of the paper. Think of them as ∆suckers∇ which fix the corresponding edge to that edge of the paper! In this example, a frame is attached both to height and to width, so that it will maintain its margins whatever you do to the paper size or orientation. When you add a new object, it always attaches to the left edge and the bottom of the paper – you change this simply by clicking the appropriate button, but watch carefully what happens to the numbers in the pos/size fields as you do this! Experiment with the ∆body∇ frame to see the effect.

What you will see is that positive positions measure the distance from the left (bottom) of the paper to the left (bottom) of the object; negative positions measure from the right (top) to the right (top) edge of the object. You can type negative numbers directly in to the fields if you prefer – as soon as you <Enter> or quit the field you will see the appropriate button go down to reflect your change. This gives you an easy way of placing some text 1” from the top right of the page – just set the position to (-72 -72).

The size fields behave in a similar way, only here negatives give the total remaining space (the sum of the margins) left+right (bottom+top) around the object. A centred frame will always show exactly double (minus) the value in the position fields here. Here is another example:

This is the page-number text, which is attached to the width of the paper (this also has the effect of centring the text in the object) but has a fixed distance of 32 points from the bottom. It is not to be included in any HTML output which may be generated from this report.

If you want to know more about this, or any other component, press the ? button which will bring up a summary of the help information held as part of the component∇s class definition.

Any other properties which the object may have are listed in the body of the form – here you can modify the colour and font (pull-down choices) and type in the size in points. Note that this (and any other number fields) have ∆spin∇ behaviour so that you can simply tab to the field and use the up/down arrows to modify the value.


NewLeaf for Dyalog12: The Designer Toolbars

The Designer Toolbars

The Upper Toolbar

The leftmost buttons exit the Designer, either saving your layout or discarding any changes. You can use Ctrl+E to exit (and save) or Ctrl+Q to quit. The centre two buttons walk the Property Watcher around the objects (in the order you defined them) and are operated by PgUp/PgDn so that you can move easily between objects without using the mouse. If you try this, you will see that the selected object is always shown with bright cyan handles in the page window.

The ? button makes a ∆Cue Card∇ for the selected object and is activated with the F1 key. Finally, you can press the last button or hit F5 to ∆zoom in∇ on your design for an exact facsimile of the design, with all the master-page elements in place, and any frames filled with generated text.

The Lower Toolbar

The easy way to see what these tools do is to pull the ∆body∇ frame into a corner of the paper and then press them one by one, starting at the left. The leftmost tool will mirror the frame, i.e. will leave the left edge where it is and make the right margin the same. The second is very similar, but leaves the size fixed and moves the frame to be centred on the paper; the third centres vertically in the same way. All these tools have hot keys – hold the mouse over the tool for a pop-up tip.

You can duplicate objects (the copy will be offset slightly) with the fourth button (or the + key on the numeric pad). Hitting Ctrl+Del or the rightmost button will delete all selected objects. That leaves the two alignment tools, which will only function when more than one object is selected – what you might like to do is to make your frame quite small, duplicate it several times, move the copies around the screen, then select them in groups (using the mouse to drag a rectangle around them) and experiment.

Selecting and aligning objects

When you drag a rectangle around several objects, all those you select will have solid-coloured handles, but only one is bright cyan – this is the ∆master∇ object of the set and is the one to which the others will be aligned. If you want to align to a specific object, click this one first, then use Ctrl+Click to select the others one at a time.

The way the align tools work depends on how the master object is attached. If you press ∆align to sides∇ and the master object is attached to the right-hand side of the paper, any other objects will move so that their right edges align with its right edge. They will also be given the same attachment. The same applies if you have attached the master object to width or height – in this case any other objects will be stretched to the same size and attached similarly.


NewLeaf for Dyalog12: Adding and Arranging Objects

Adding and Arranging Objects

Use the right mouse button on the paper to add a new element with its top left corner at that point. You will find that as you move the mouse you are stretching a line (or rectangle) over the paper which shows you the extent of your new object. Click again to fix the other corner.

When you add the object, it is given a default caption (such as ∆Rule1∇) and the properties are set to those defined in its class table. It will also be selected automatically, so you can overtype the caption and tab round to the other properties quickly.

Setting the sizing grid

The Designer has three alternative settings for the underlying grid, accessed with the right-mouse menu on the paper. As all measurements are held to the nearest point, a 1-point snap is effectively ∆no grid∇ and objects will move smoothly and stay exactly where you put them. However it is often easier to work with a small degree of ∆snap∇ so that objects can be aligned with the mouse more easily. A 6-point snap (1/12”) works well in practice and is acceptable for most normal layouts. If you set this (or even a 12-point snap to make the effect very obvious) you will notice that as you drag the sizing handles the dotted rectangle stretches in jumps to show you exactly how the object will look when you place it. If you want this behaviour temporarily disabled, hold down Ctrl while dragging and you will find that smooth movement is restored.

Note that the same applies to the spinning behaviour of the position and size fields – these spin by default in grid units, but you can hold Ctrl down and use the arrows to nudge objects in 1-point increments.

Using the Object Sorter

Objects are saved in the order you define them, which can be a nuisance if you have several frames and want a sensible flow between them. You can always use leaf.FlowList to set the order explicitly, but a better option is to arrange the frames so that the natural sequence takes the text flow around them in the correct order.

If you use the right-mouse menu to bring up the ∆Object Sorter∇ window, you can move any object up/down the list so that frames are created in a convenient order. This may also help to make the PgUp/PgDn buttons walk around the objects in a more reasonable way, so it is probably worth arranging all the objects on a complex page into a ∆top-down∇ sequence just to make editing a little easier.


NewLeaf for Dyalog12: Summary

Summary

You should now be able to make simple master-page definitions suitable for most normal reporting needs. Remember that the definitions are simply held in a normal APL matrix, so you can quickly assemble a library of ∆templates∇ which hold common elements such as company details or a corporate logo – to make a new report just assign the appropriate template and add the frames you need. Similarly, if you need left/right masters for double-sided binding, just make the left hand page, duplicate it and change the necessary elements on the right-hand version.


NewLeaf for Dyalog12: Viewing NewLeaf Documents

Viewing NewLeaf Documents

The built-in viewer can be used to preview printed documents, save them in various formats and navigate bookmarks.

View_Intro | Introducing the Viewer
View_tb | The Viewer Toolbar
View_Document | The Document Area
View_sbar | The Status Bar
View_popup | The Popup Menu
VFStd | Basic Viewer Functions


NewLeaf for Dyalog12: Introducing the Viewer

Introducing the Viewer

The Viewer allows you or a user to display each page of a NewLeaf document on-line, and then to print it or save it to file. You can move easily between pages, magnify or reduce the size of the page image, and copy the currently displayed page to the clipboard. Although the document can be manipulated in a variety of ways, all of these procedures (magnifying, exporting as a PostScript file, etc.) use a copy and the original document is unchanged.

Any viewer settings you change are saved in the Windows Registry, by default under the key ‘Software\Causeway\NewLeaf\Viewer’ within HKEY_CURRENT_USER. You can use PostScrp.SetRegPath to set your own registry path, so that the settings will be specific to your own application. If you set this path to null, no settings will be saved to or loaded from the registry.

The Viewer is itself an application with a fixed-size form. Probably you will make a simple cover function, such as View, with the same calling syntax. The Viewer is invoked directly as follows:

PostScrp.View doc

where doc is a simple text vector containing either a NewLeaf document description as returned by leaf.Close, or the full path and name of a file containing such a text vector. Where doc is a four-page document, you see:

Invoked monadically, the Viewer initially displays the first page of the document. If the Viewer is invoked with a left argument consisting of a positive integer scalar:

5 PostScrp.View doc

it displays that page of the document first.

The Viewer has four main components:

  1. Tool Bar
  2. Document Area
  3. Status Bar
  4. Popup Menu

These are described in the following sections. Note that all text items in the viewer (including tooltips, pop-up menus and dialogue boxes) are translatable using external phrasebook files.

See also ...

Translating the Viewer Text


NewLeaf for Dyalog12: The Viewer Toolbar

The Viewer Toolbar

The tool bar appears along the top of the Viewer. It contains buttons to copy, print, etc., the document. For a multi-page document, it looks like this:

... the 5 navigation buttons will not appear if you view a single-page document. The leftmost buttons will:

  • Copy as Metafile (Ctrl+C). Create a copy of the displayed page in Windows Metafile format and place it on the clipboard.
  • Print this page. Print only the displayed page on the current printer.
  • Print all pages (Ctrl+P). Print all pages in this document on the current printer.
  • Zoom to full page (- on the keyboard). Reduce the size of the displayed page so that the entire page is visible in the document area.
  • Zoom to page width. Reduce or magnify the size of the displayed page so it occupies the full width of the document area.

The rightmost button (in a multi-page document) will display a simple popup dialogue to jump to a selected page by number or by bookmark (if there are any bookmarks in the document). Hit F5 to shortcut to this dialogue.


NewLeaf for Dyalog12: The Document Area

The Document Area

The document area is the central part of the Viewer in which the current page is displayed. By default, the Viewer sets the page size so that it occupies the full width of the document area:

Alternatively, selecting the Zoom full page button on the toolbar, or the Zoom full page item in the popup menu, reduces the page size so that the entire page is visible within the document area:

When the mouse pointer is anywhere within the document area, its (x,y) coordinates are continually updated in the Pointer Coordinates status field located at the bottom right of the Viewer. Clicking the left mouse button when the mouse pointer is in the document area reduces or magnifies the size of the displayed page so it occupies the full width of the document area.

Moving around the current page

The four arrow keys (up, down, left, right) move the viewing window in the corresponding direction over the page image in the document area. For example, to see further down a page, press the down arrow key, and to see to the right of what is currently visible, press the right arrow key.

Magnifying or reducing the page image size

The Viewer allows you to reduce the size of the page image (zoom out) to check the overall layout of the displayed page, and to magnify any part of it (zoom in) to examine the detail. By default, the page is displayed so it occupies the full width of the document area. The Viewer automatically switches to this level of magnification if you click on the Zoom page width button on the tool bar or on the left mouse button when the mouse pointer is in the document area. The second standard size displays the entire page in the document area. This level of magnification occurs if you click on the Zoom full page button on the tool bar or you select the Zoom Full Page item from the popup menu (click the right mouse button when the mouse pointer is in the document area to make the popup menu appear).

In addition, you can magnify any part of the page by using the mouse to outline a rectangular area. Move the mouse pointer to one corner of the area of interest on the page, then press and hold down the left mouse button. Drag the pointer to the diagonally opposite corner of the area of interest and release the mouse button. The Viewer then displays the outlined area. Because the Viewer always displays the top edge and the full width of the area of interest, it is best to drag-select from the top left or top right corner of the area. Any part of the page lying outside the magnified image can be brought into view by using the arrow keys as described above.


NewLeaf for Dyalog12: The Status Bar

The Status Bar

The status bar is located along the bottom edge of the Viewer. It contains two status fields: the Current Page field is on the left and the Pointer Coordinates field on the right.

The Current Page field contains the ordinal number of the currently displayed page together with the total number of pages in the document. (This may differ from the page number on the document if leaf.CurrentPage has been used to alter the page numbering.) When the pointer is in this field and you are viewing a multi-page document, double-clicking either mouse button brings up the Go to Page dialogue box.

The Pointer Coordinates field contains the (x,y) coordinates of the mouse pointer on the page. The coordinate system has its origin at the bottom left corner of the paper; x-values increase to the right and y-values increase towards the top of the document area. The figures displayed are the distances in points from the left and bottom edges, respectively, of the paper to the current location of the tip of the pointer. If you track the cursor across an embedded RainPro chart, you will see that the co-ordinate system changes automatically to allow you to read off the data values from the chart.


NewLeaf for Dyalog12: The Popup Menu

The Popup Menu

The popup menu provides ready access to the document manipulation procedures available within the Viewer. It appears when the pointer is anywhere in the document area and you click the right mouse button once. The menu disappears after you select a menu item, or click outside the menu.

In general, the menu simply duplicates the toolbar buttons, but you also have the extra options:

  • Clipboard as Bitmap (sized as shown)
  • Clipboard as Bitmap (custom size) – this will prompt for a scaling factor
  • Direct PostScript – use this if you have a genuine PostScript printer attached to your PC, or would like to save the report on file in PostScript format. It will prompt for a file name – just enter ‘prn’ for a locally attached printer.
  • EPS file – use this to save your report in ‘Encapsulated PostScript Format’ which will allow it to be included in any high-end DTP document by tools such as Adobe PageMaker.
  • Windows Metafile – this will prompt for a file name and save the report as a standard Windows metafile, with a ‘placeable header’ so that it will be sized correctly when included in a document.

Note that all these menu prompts are translatable using an external .PHB file, and that you can selectively exclude menu items by giving them a text caption of ‘~’.


NewLeaf for Dyalog12: Basic Viewer Functions

Basic Viewer Functions

The PostScrp namespace contains the functions necessary to convert your NewLeaf report into a wide variety of graphics formats. You can view the report on screen, print it to your Windows printer, direct it to any PostScript device, and so on. All the examples shown below assume you have saved the intermediate format of your report in a character variable PG. The available functions are:

View the Report

To see the report on screen, zoom in on any selected region, read off data values from the mouse cursor etc. ...

PostScrp.View PG

The right-mouse menu in the viewer supports many of the facilities listed below. All the text captions in the viewer may be loaded from a phrasebook file with PostScrp.GetPhraseBook phbfile. The workspace is shipped with a UK-English phrasebook (uk-en.phb) and phrasebooks for other languages will be shipped as they become available. You might choose to load your local phrasebook once and ship your product with a permanent phrase table, or you might have the application load it on startup depending on your user’s choice of language for the application.

Print the Report

To have the report printed on your standard Windows printer ...

PostScrp.Print PG

This will orient the paper automatically to match the orientation of the chart. You can preset the target printer with:

PostScrp.OpenPrinter 'Tektronix 840,\\SERVER\Tek840'

which will route all prints to this destination until you call PostScrp.ClosePrinter.

A null argument to OpenPrinter will open the Windows default printer.

Output to PostScript Devices

NewLeaf reports can be written directly to any PostScript printer, or saved on file in PostScript format.

'\\server\tek840' PostScrp.Write PG    ⍝ Direct to printer
'C:\temp\RAIN.PS' PostScrp.Write PG    ⍝ Write to PS file

If you omit the file name, the default is ‘prn’ which will output to your default printer. If you have a colour printer (such as the Tektronix-840) set PostScrp.∆rgb←1 which allows full-colour output. Otherwise the results will be better if the chart is forced to use a black&white colour map with PostScrp.∆rgb←0.

file PostScrp.WritePDF PG    ⍝ for Distiller

The files saved in this format are ideal for use with Acrobat Distiller to generate PDF documents; there is a sample function ToPDF in the NewLeaf workspace which you can change to route the PostScript data directly to Distiller’s inbound directory. To add your own outline tree to a PDF document, please refer to inserting a bookmarks with leaf.Bookmark.

Extracting header comments

You can use PostScrp.ReadHeader to read any of the header comments (such as the page bounding box) which you may find useful in your own event handlers or rendering code.

Checking the bookmark table

If you want to construct your own viewer, with a tree-structured table of contents, you can check the page-count, title and bookmarks table with info←PostScrp.Info spl. The bookmarks table is a 3-column matrix giving the bookmark name, page number and indent level.


NewLeaf for Dyalog12: Working with Tables: Tutorial

Working with Tables: Tutorial

Tables are the most complex NewLeaf component. This section walks through the basics of building a progressively more sophisticated report.

Tutintro | Introducing the Table Tutorial
Testdata | Setting up the Tutorial Test Data
TabIntro | An Introduction to Tables
DefTbl | Default Table Handling
RowTtl | Table Row Titles
TblFmt | Formatting Data in a Table
TblAlgn | Horizontal Alignment within Table Columns
TblFont | Table Font
TblCol | Column Width
TblRules | Table Border and Gridlines
TblSpc | Row Height and Spacing
TblColTtl | Simple Column Titles
TblColAln | Horizontal Alignment of Column Titles
TblTtlFont | Column Titles Font
TblSpan | Titles Spanning More Than One Column
TblCap | Adding Table Headings and Captions
TblWide | Tables Wider Than One Page


NewLeaf for Dyalog12: Introducing the Table Tutorial

Introducing the Table Tutorial

This tutorial is designed to introduce most of the table-handling capabilities of NewLeaf. Each topic includes both text and a number of code segments to explain and illustrate one feature. The topics are linked by a block of code that is designed to produce a report. Each topic concludes by adding a line or two to this code to incorporate the feature that has just been described. This way, you have the opportunity to observe the combined effects of the features at each point. As this block of code can exceed ten lines, it will be easier to edit if you manipulate the code in the form of a defined function.

While it may be sufficient merely to read through the tutorial topics, you are likely to arrive at a better understanding of NewLeaf if you work through the examples by typing the code segments or editing and running a function in the NewLeaf workspace loaded into an APL session. Such a hands-on approach also provides plenty of scope for experimentation; don∇t be afraid to try values other than those used in the examples.

Note that all measurements are in points, where there are exactly 72 points to 1 inch, and approximately 28 to 1 centimetre.


NewLeaf for Dyalog12: Setting up the Tutorial Test Data

Setting up the Tutorial Test Data

The examples in this and subsequent topics use a number of APL arrays:

sales | a 4 by 21 by 6 numeric array containing quarterly sales revenue in thousands of dollars by product by district for the ACME Intergalactic Shoe Corporation Inc. The bottom row and the rightmost column of each plane are totals. Each district is associated with one of two geographic regions.
salesQ1 | the sales revenue for the first quarter, the first plane of sales.
salesTot | the total sales revenue for all quarters.
products | is a vector of text vectors, the names of the products.
districts | is a vector of text vectors, the names of the sales districts.
regions | is a vector of text vectors, one per district, the names of the regions.

To create them, type:

sales←4.1×?4 20 5⍴1000
sales←sales,+/sales
sales←sales,[2]+/[2]sales
salesTot←+⌿sales
salesQ1←sales[1;;]
products←((⊂'Product '),¨⍕¨⍳20),⊂'Total'
districts←((⊂'District '),¨⍕¨⍳5),⊂'Total'
regions←2 3 1/'North' 'South' ''

Correcting errors

If execution stops within a NewLeaf function, type:

→
leaf.Close

Then, try to locate the reason for the error by comparing your code with that in the tutorial topic. If you are experimenting with code not found in a tutorial, ensure that the shape and depth of the variable arguments correspond to those in the examples.


NewLeaf for Dyalog12: An Introduction to Tables

An Introduction to Tables

NewLeaf has several features that simplify the handling of tables. These generally involve setting properties that are applied to the entire table or to specific rows or columns. Each of these table properties is introduced here as a separate topic. Within each topic are several examples that demonstrate how to set the value of the property and to illustrate its effect when it is applied on its own to a simple numeric matrix. One or more additional examples within each topic show the effect of combining several properties as you construct the body of a one-page sales report. Be sure you have created the variables as described in the Tutorial Introduction if you intend to work through the examples.

The code segments in each topic of this tutorial follow a simple procedure:

  1. Initialise the page and text style properties to their default values.
  2. Initialise the table properties to their default values.
  3. Open a document using the default page description. This creates a portrait-oriented, single-page template containing a single frame with its border located one inch (2.54 cm) from the edge of the paper on all sides, and a centred page number located 1/2 inch (1.27 cm) above the bottom edge of the paper.
  4. Change none or more table properties.
  5. Put one (or more) table(s) in the document.
  6. Close the document, leaving the document in a variable in the workspace.
  7. View the document.

Within this structure, you will explore the properties that can be changed in step 4 and observe their effects on a simple numeric matrix.


NewLeaf for Dyalog12: Default Table Handling

Default Table Handling

First, note how NewLeaf handles a table by default, and how each step of the procedure corresponds to a function call:

 leaf.Init

 leaf.Use''

⍝ Change any table properties here

 leaf.table.List salesQ1

 doc←leaf.Close

 View doc

Note that NewLeaf initialises the table properties automatically when it runs leaf.Init, and when it closes a document. It is not necessary to initialise the table properties explicitly except to return to a known starting point, as in the case of writing several differently formatted tables to the same document.

In general, you can change as few or as many table properties as you want; only when a matrix is put on a page by table.List are the values of the properties used. As the preceding code segments set no properties, you can see the effects of their default values on a table:

  • Formatting. No special formatting is applied to the data.
  • Horizontal Alignment. The content of each cell is left-aligned within the cell.
  • Table Font. The table appears in 12-point Times font with a line spacing of 14.4 points.
  • Column WidthAll of the columns in the table have the same width, and the table extends from the left edge of the frame to the right edge.
  • Table Border and Rules. A solid 1 point line forms a border around the outer edge. Solid lines, known as vertical rules, 0.8 point thick separate adjacent columns. Solid lines, or horizontal rules, 0.01 point thick separate adjacent rows.
  • Row Height and Spacing. The contents of each cell are set three points below the top of the cell and three points above the bottom. The height of each row is 20.4 (14.4 + 3 + 3) points.

In the remainder of this tutorial, you will learn how to change these default settings individually and to combine them to achieve different effects. At the end of the tutorial, you will have a firm grounding in the options available to you through NewLeaf to manipulate the appearance of an individual table.


NewLeaf for Dyalog12: Table Row Titles

Table Row Titles

NewLeaf treats row titles like any other column of data. In this case, the row titles are contained in a vector of text vectors where each text vector is a product name. Simply concatenate the product names to the sales data:
leaf.Init ⋄ leaf.Use''
leaf.table.List products,salesQ1
View doc←leaf.Close

Although the row titles are text, NewLeaf uses the same default settings for the font, line spacing, alignment and borders as are applied to the numeric data. The table itself still occupies the full width of the frame and all of the columns in the table have the same width.


NewLeaf for Dyalog12: Formatting Data in a Table

Formatting Data in a Table

By default, NewLeaf applies the primitive thorn function (⍕) to each element of a table to ensure that it is text. It is possible to format the contents of one or more columns by providing NewLeaf with a vector of format specifications. Each of these must be a valid left argument to the ⎕FMT system function. Format the sales data table by typing:
leaf.Init ⋄ leaf.Use''
leaf.table.Qfmt 'CF8.1'
leaf.table.List salesQ1
View doc←leaf.Close

NewLeaf treats a simple format specification as if it were a one-element vector of vectors. It reshapes the vector of format specifications to match the number of columns in the table; try the previous example using (⊂''),⊂'CF8.1'. NewLeaf does not override the behaviour of ⎕FMT. For example, where a value overflows the number of characters allowed by the format specification, a series of asterisks appears in that cell of the table. You are likely to find that this has occurred to the grand total in the bottom right corner of the table. To correct this, provide a separate format specification for each column and increase the field width in the format specification for the rightmost column:

leaf.Init ⋄ leaf.Use''
leaf.table.Qfmt ((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.List salesQ1
View doc←leaf.Close

For columns containing alphanumeric strings, it is best to ensure that each string is a vector and to allow NewLeaf to apply the default formatting. Whenever an empty vector is found in the vector of format specifications, NewLeaf applies the thorn function to the contents of the corresponding column. Now you can begin to write the code that will create the body of the one-page sales report:

leaf.Init ⋄ leaf.Use''
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.List products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Horizontal Alignment within Table Columns

Horizontal Alignment within Table Columns

NewLeaf aligns the contents of each cell in a column along the left edge by default.

To align the sales data along the right edge of each column, type:

leaf.Init ⋄ leaf.Use''
leaf.table.Align 'right'
leaf.table.List salesQ1
View doc←leaf.Close

Repeat the previous example using 'centre' or 'center' instead of 'right' alignment.

Then, to right- and left-align alternate columns, type:

leaf.Init ⋄ leaf.Use''
leaf.table.Align 'Right' 'Left'
leaf.table.List salesQ1
View doc←leaf.Close

There are three things to note here. First, the alignment is not case sensitive, so 'right' has the same effect as 'Right' or 'RIGHT'. Second, the vector of alignment settings is always reshaped to match the number of columns in the table. Thirdly, you can reduce any of the words to two-letter abbreviations, such as 'ce' 'ri' 'ri'.

NewLeaf is also able to align the decimal points in numeric data, and to reserve sufficient space to the right of the decimal for a specified number of digits to appear.

As the sales data have been calculated to one decimal place, try typing:

leaf.Init ⋄ leaf.Use''
leaf.table.Align 'decimal1'
leaf.table.List salesQ1
View doc←leaf.Close

The figures in each column are now aligned according to the position of the decimal place, but they are a mixture of integers and floating-point numbers. Try combining an appropriate format specification with the decimal alignment to produce a more consistent appearance:

leaf.Init ⋄ leaf.Use''
leaf.table.Align 'decimal1'
leaf.table.Qfmt ((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.List salesQ1
View doc←leaf.Close

Continuing with the sales report, left-align the row titles and decimal-align the data:

leaf.Init ⋄ leaf.Use''
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.List products,salesQ1
View doc←leaf.Close

Note that the order in which you set the alignments and the format specifications in this example was the reverse of the order in the previous example. The NewLeaf table properties are mutually independent, so an APL application can set them in whichever order is appropriate to the processing.


NewLeaf for Dyalog12: Table Font

Table Font

As installed, NewLeaf uses 12-point Times as the default font for all printing. A font is specified by a three-part description: the typeface, the character height in points and the line-spacing in points. For example, ∆TI,12∇ corresponds to 12-point Times with default line-spacing (120% of the character height); ∆HEB,10/11∇ corresponds to 10-point Helvetica bold with 11-point line-spacing. See Customising NewLeaf for a detailed discussion of fonts. So, to produce the table in 10-point Helvetica with default (12-point) line-spacing, type:

leaf.Init ⋄ leaf.Use''
leaf.table.Font 'HE,10'
leaf.table.List salesQ1
View doc←leaf.Close

Note how many rows you can see in the Viewer. Now, squeeze them together by including an explicit value for the line-spacing in the font specification that is less than the calculated default and note how many rows you can see:

leaf.Init ⋄ leaf.Use''
leaf.table.Font 'HE,10/11'
leaf.table.List salesQ1
View doc←leaf.Close

In common with many other table-handling features of NewLeaf, the font can be set by column. For example, to emphasise the totals in the rightmost column, specify a bold version of the same font:

leaf.Init ⋄ leaf.Use''
leaf.table.Font ((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.List salesQ1
View doc←leaf.Close

Next, include product names in 10-point Times and combine this with the appropriate alignment and formatting in the sales report:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.List products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Column Width

Column Width

By default, NewLeaf divides the space between the sides of the frame equally among the columns of a table. You can set the column widths to a specific number of points – to display the table of sales data in column widths of 3/4 inch (54 points), type:
leaf.Init ⋄ leaf.Use''
leaf.table.CellWidths (¯1↑⍴salesQ1)⍴54
leaf.table.List salesQ1
View doc←leaf.Close

Note that the vector of cell widths contains one element per column in the table. Any column or columns that do not have an explicit cell width, or which have a cell width of ¯1, will be allocated an equal share of the space remaining in the frame after any explicit column widths are allocated.

To illustrate this, note what happens when you set the width explicitly for all but the rightmost column:

leaf.Init ⋄ leaf.Use''
leaf.table.CellWidths (¯1+¯1↑⍴salesQ1)⍴54
leaf.table.List salesQ1
View doc←leaf.Close

It is also simple to allocate the remaining space to the row titles. Set the width of the first column to ¯1 and the width of each of the sales data columns to 3/4 inch (remember to multiply by 72):

leaf.Init ⋄ leaf.Use''
leaf.table.CellWidths ¯1,(¯1↑⍴salesQ1)⍴72×0.75
leaf.table.List products,salesQ1
View doc←leaf.Close

Having decided on the font, numeric data formatting and alignment, you can now set the columns in the sales report to the appropriate widths. The following example also uses column widths measured in inches, and wider columns for the row titles and row totals:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.List products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Table Border and Gridlines

Table Border and Gridlines

All of the tables created so far have appeared with several solid lines, also called rules. The entire table is surrounded by a one-point line, adjacent columns are separated by 0.8≡point vertical rules, and adjacent rows by 0.01≡point horizontal rules. Collectively, these are known as gridlines, and they are all part of the same NewLeaf property. You can suppress all of these lines by setting all three gridlines values to zero:

leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 0 0 0
leaf.table.List salesQ1
View doc←leaf.Close

The three values indicate the line thickness, in points, of the box that surrounds the table, the vertical rules and the horizontal rules respectively. Any value not explicitly supplied is assumed to be a zero, that is, no line. Drawing only a two-point border around the table is straightforward:

leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 2
leaf.table.List salesQ1
View doc←leaf.Close

As you can see, NewLeaf treats any missing gridline value as if it were a zero. To draw a one-point line around the table and a 0.5 point line between the columns:

leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 1 0.5 0
leaf.table.List salesQ1
View doc←leaf.Close

Alone among the three parameters, the vertical rule can be a nested vector which NewLeaf reshapes to suit the number of columns in the table. This allows you to put a vertical rule of a specific width between any pair of columns. For example, to indicate that the rightmost column is different (i.e., it contains totals) from the other columns, put a 0.5 point vertical rule to its left:
leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 1,(⊂(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.List salesQ1
View doc←leaf.Close

The third gridline value is the height, in points, of the horizontal rule that is drawn between each pair of adjacent rows in the table. To produce a comparable effect horizontally, that is, a line only above the last row in the table, requires a different technique. Set the horizontal rule to a width of zero, put all but the last row of the table on the page, then draw a 0.5 point horizontal rule before adding the last row of the table:

leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 1 0 0
leaf.table.List ¯1↓[1]salesQ1
leaf.table.Rule 0.5
leaf.table.List ¯1↑[1]salesQ1
View doc←leaf.Close

Now, add the row titles and separate them from the sales figures with a 0.5 point vertical rule. As in the two previous examples, put lines of this same width above the bottom row and to the left of the rightmost column:

leaf.Init ⋄ leaf.Use''
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close

Now, combine this with the other properties in the sales report:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Row Height and Spacing

Row Height and Spacing

The height of a row in a NewLeaf table is the sum of two properties. The first is the largest value of the line-spacing property of all of the fonts in the row (remember, a different font specification can apply to each column). The second is the spacing property. This sets the amount, in points, of additional white space to be left above and below the largest line-spacing value of all of the fonts in the row. By default, these spacing property values are 3 and 3 points respectively. These combine with a default line height of 14.4 points to give a default row height of 20.4 points. To maintain this row height and to position the sales data along bottom edge of the row, specify a spacing of six points from the top and zero points from the bottom of each cell:

leaf.Init ⋄ leaf.Use''
leaf.table.Spacing 6 0
leaf.table.List salesQ1
View doc←leaf.Close

In the sales report, you may have found that removing all but one of the horizontal rules left the report looking somewhat spread out. Squeeze the rows together by setting the spacing above and below each row to zero:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.Spacing 0 0
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close

Unfortunately, this produces a table that appears cramped. Try spacing one point above and below each row of the product sales data and, to make the column totals stand out, increase the spacing to three points above and below the totals data in the final row:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.Spacing 1 1
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5 ⋄ leaf.table.Spacing 3 3
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close

This concludes the introduction to the NewLeaf table-handling features. If you are planning to take a break, save your work as the following topics continue to develop the sales report.


NewLeaf for Dyalog12: Simple Column Titles

Simple Column Titles

The preceding topics introduced several of the table-handling features of NewLeaf, and showed how to apply these to a single table, both individually and in combination to produce the desired output. The tutorial continues with some topics which demonstrate how to add column titles and captions to a table, and how to position a table horizontally on a page. The examples that follow are a continuation of the work you have already done.

Column titles are treated separately from a table although they inherit some of its properties. In its basic form, a set of simple column titles is a vector of text vectors containing one text string for each column in the table:
leaf.Init ⋄ leaf.Use''
leaf.table.Titles districts
leaf.table.List salesQ1
View doc←leaf.Close

Any elements in the vector of column titles that lie beyond the number of columns in the table are ignored. If there are fewer column titles than columns in the table, NewLeaf reshapes the vector of vectors as required:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles 'Odd' 'Even'
leaf.table.List salesQ1
View doc←leaf.Close

Column titles can occupy more than one row. Where a column title exceeds the width of the corresponding table column, NewLeaf automatically word-wraps the text string. Useful column titles for the sales report would have each district name beneath its associated region. You can construct the appropriate text string for each column by concatenating each district name to the end of its corresponding region name, then allow NewLeaf to word-wrap individual text strings. If a column title requires fewer lines than any others, it is centred vertically within the row of column titles (see the rightmost column):

leaf.Init ⋄ leaf.Use''
leaf.table.Titles regions,¨(⊂,' '),¨districts
leaf.table.List salesQ1
View doc←leaf.Close

Alternatively, it is possible to control this word-wrap to some extent by specifying an individual column title as a vector of text vectors. NewLeaf starts each separate text string on a new row, although individual text strings are still subject to word-wrap if their length exceeds the width of the column:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles ⊂[1]regions,[0.5]districts
leaf.table.List salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Horizontal Alignment of Column Titles

Horizontal Alignment of Column Titles

By default, NewLeaf centres each line of a column title in its cell. As with a table, you can specify a single horizontal alignment to be applied to all column titles:
leaf.Init ⋄ leaf.Use''
leaf.table.Titles districts
leaf.table.TAlign 'right'
leaf.table.List salesQ1
View doc←leaf.Close

You can align each column title independently by specifying a vector of one or more horizontal alignment settings. NewLeaf reshapes this vector as required to match the number of columns. For example, to left- and right-align alternate columns of a table and its column titles:

leaf.Init ⋄ leaf.Use''
leaf.table.Align 'left' 'right'
leaf.table.Titles districts
leaf.table.TAlign 'left' 'right'
leaf.table.List salesQ1
View doc←leaf.Close

Finally, look at the effect of right-aligning the titles of all but the first and last columns of the sales report. As there is no title for the first column, the horizontal alignment setting has no effect:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.Spacing 1 1
leaf.table.Titles (⊂''),(¯1↓⊂[1]regions,[0.5]districts),¯1↑districts
leaf.table.TAlign (⊂'centre'),((¯1+¯1↑⍴salesQ1)⍴⊂'right'),⊂'centre'
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.Spacing 3 3
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Column Titles Font

Column Titles Font

As installed, NewLeaf uses 13-point bold Helvetica (Arial) as the default font for column titles. A font is specified by a three-part description: the typeface, the character height in points and the line-spacing in points. For example, ∆TI,12∇ corresponds to 12-point Times with default line-spacing (120% of the character height); ∆HEB,10/11∇ corresponds to 10-point Helvetica bold with 11-point line-spacing. See Fonts for a detailed discussion of fonts, and the preceding tutorial for a discussion of changing table fonts. The column titles appear in 10-point Helvetica if you type:

leaf.Init ⋄ leaf.Use''
leaf.table.TFont 'HE,10'
leaf.table.Titles districts
leaf.table.List salesQ1
View doc←leaf.Close

There are three points to note here. First, the column title font can be specified before or after the column titles are set. Second, NewLeaf accepts only one font specification for the column titles, and this is used for all of the column titles. Third, NewLeaf always uses the default line-spacing for the column title font, and it ignores the third part, if present, of any font specification. To prove this, try the previous example with a font specification of ∆HE,10/20∇ and you will see that there is no difference in the line height of the column titles.

Turning to the sales report, specify 10-point Times as the column title font, the same as the font used for the row titles:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.Spacing 1 1
leaf.table.TFont 'TI,10'
leaf.table.Titles (⊂''),(¯1↓⊂[1]regions,[0.5]districts),¯1↑districts
leaf.table.TAlign (⊂'centre'),((¯1+¯1↑⍴salesQ1)⍴⊂'right'),⊂'centre'
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.Spacing 3 3
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Titles Spanning More Than One Column

Titles Spanning More Than One Column

The data in a table are frequently part of some hierarchical structure. One way of indicating this structure is through the column titles. For example, the relationship of districts to regions in the sales report was made explicit by combining each district name with its associated region atop the appropriate column in the table. Ignoring the row titles and row totals for the moment, this produces:

North       North       South       South       South
District 1  District 2  District 3  District 4  District 5  Total

However, the hierarchy becomes more visible by centring each region name above all of its constituent districts:

        North                          South
District 1  District 2   District 3  District 4  District 5  Total

NewLeaf supports the grouping and arrangement of column titles in this manner by means of the Depth property of the column titles. By default, each column title is assumed to be at the top level of a hierarchical tree structure that contains only one node, itself, that is located at a depth of 0 within the hierarchy. This is analogous to a number of directories that exist at the root level of a disk operating system.

To describe a hierarchical structure, the column titles, or nodes, of each tree in the structure are ordered from top to bottom (depth≡0 to depth≡n) and from left to right. The value of the depth property of each node is then set to indicate its relationship to the node immediately to its left in the list.

Each tree has one depth-0 node, and the depth of the first column title in the list is always zero. The column titles for the sales data have three trees: North region, containing two depth-1 nodes (Districts 1 and 2); South region, containing three depth-1 nodes (Districts 3, 4 and 5); and the totals, with no nodes other than itself. Observe how NewLeaf arranges the column titles to reflect the implied hierarchy:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles (⊂'North'),(2↑districts),(⊂'South'),2↓districts
leaf.table.TDepth 0 1 1 0 1 1 1 0
leaf.table.List salesQ1
View doc←leaf.Close

NewLeaf always resets the depth of the column titles to the default value whenever you specify the content of the column titles. NewLeaf also reshapes the depth vector to match the number of column titles. Because the title alignments correspond to the order of the title vector, you can right-align the district names while leaving the regions and total centre-aligned:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles (⊂'North'),(2↑districts),(⊂'South'),2↓districts
leaf.table.TDepth 0 1 1 0 1 1 1 0
leaf.table.TAlign('centre' 'right')[1 + 0 1 1 0 1 1 1 0]
leaf.table.List salesQ1
View doc←leaf.Close

NewLeaf can handle column title structures containing trees that extend to different depths. Assume that South region is divided into two areas, East and West. These are depth-1 nodes. East contains one depth-2 node, District 3, and West contains two depth-2 nodes, Districts 4 and 5. Note also what happens to the vertical space allocated for the three nodes in the North tree:

salesTitles←(⊂'North'),(2↑districts),('South' 'East'),1↑2↓districts
salesTitles←salesTitles,(⊂'West'),3↓districts
leaf.Init ⋄ leaf.Use''
leaf.table.Titles salesTitles
leaf.table.TDepth 0 1 1 0 1 2 1 2 2 0
leaf.table.List salesQ1
View doc←leaf.Close

Now, compare the North tree in the previous example to the following, where the district nodes are designated depth-2 nodes:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles salesTitles
leaf.table.TDepth 0 2 2 0 1 2 1 2 2 0
leaf.table.List salesQ1
View doc←leaf.Close

So, for the deepest level column titles to appear at the same height immediately above the table, they must all have the same depth. In this case, it means that all nodes corresponding to districts are depth-2.

If there is no node at a particular depth within a tree, NewLeaf simply takes the vertical space that it would occupy and allocates it to the next node higher up the tree. If uniform spacing is important (for example, to keep the region names at the same level), use an empty text vector and an appropriate depth value for the column title of a non-existent node:

salesTitles←('North' ''),(2↑districts), ('South' 'East'),1↑2↓districts
salesTitles←salesTitles,(⊂'West'),3↓districts
leaf.Init ⋄ leaf.Use''
leaf.table.Titles salesTitles
leaf.table.TDepth 0 1 2 2 0 1 2 1 2 2 0
leaf.table.List salesQ1
View doc←leaf.Close

The final modification to the sales report involves re-ordering the column titles, and setting the depth and alignment properties to put the appropriate districts beneath each of the two regions as described at the beginning of this topic:

leaf.Init ⋄ leaf.Use''
leaf.table.Font (⊂'TI,10'),((¯1+¯1↑⍴salesQ1)⍴⊂'HE,10'),⊂'HEB,10'
leaf.table.Qfmt (⊂''),((¯1+¯1↑⍴salesQ1)⍴⊂'CF8.1'),⊂'CF9.1'
leaf.table.Align (⊂'left'),(¯1↑⍴salesQ1)⍴⊂'decimal1'
leaf.table.CellWidths 72×0.9,((¯1+¯1↑⍴salesQ1)⍴0.75),0.8
leaf.table.Gridlines 1,(⊂0.5,(1-¯1↑⍴salesQ1)↑0.5),0
leaf.table.Spacing 1 1
leaf.table.TFont 'TI,10'
leaf.table.Titles ('' 'North'),(2↑districts),(⊂'South'),2↓districts
leaf.table.TDepth 0 0 1 1 0 1 1 1 0
leaf.table.TAlign ('centre' 'right')[1+ 0 0 1 1 0 1 1 1 0]
leaf.table.List ¯1↓[1]products,salesQ1
leaf.table.Rule 0.5
leaf.table.Spacing 3 3
leaf.table.List ¯1↑[1]products,salesQ1
View doc←leaf.Close


NewLeaf for Dyalog12: Adding Table Headings and Captions

Adding Table Headings and Captions

At this point, the content of the table is complete but it would benefit from the addition of a caption. You have considerable flexibility in associating text with the table, using any or all of the following properties:

  • Heading: this is written at the top of the table, centred by default, in a larger font. It repeats across the part-pages if the table spans more than one page wide.
  • Subheading: this is written under the heading, with the same alignment, in a smaller font. It is also repeated across part-pages.
  • Caption: this is written at the top left of the table, and repeats on every part-page both across and down. It is left-aligned and written in a bold font.
  • Footnote: this is written at the very end of the entire table. It defaults to left-aligned and a smaller font.

You can set the font and colour of any of these elements, and the alignment (left, centre, right) of the headers and footnote.

For now, set a standard heading, centred above the table:

leaf.Use''
leaf.table.Heading'Table 1. First Quarter Sales ($000''s)'
leaf.table.List salesQ1
View doc←leaf.Close

Observe what happens when the left and right indents are set to one inch:

leaf.Init ⋄ leaf.Use''
leaf.Indent 72 × 1 1 0
leaf.Align 'centre'
leaf.table.Heading'Table 1. First Quarter Sales ($000''s)'
leaf.table.List salesQ1
View doc←leaf.Close

Now, try setting each of the first two indents separately to one inch to see what happens to the width and the position of the table and caption.

Completing the Sales Report

By default, a table will occupy the entire frame width, but if you give the all the cell widths explicitly it may be less wide than the frame (in which case it will be aligned using the current paragraph alignment) or some columns may be dropped from the right-hand edge. So, to centre the complete sales report, together with its heading and a footnote:

leaf.Init ⋄ leaf.Use''
 ncol←¯1↑⍴products,salesQ1 ⋄ cw←72×0.9,((ncol-2)⍴0.75),0.8
 leaf.Align'centre'
 leaf.table.Font(⊂'TI,10'),((ncol-2)⍴⊂'HE,10'),⊂'HEB,10'
 leaf.table.Qfmt(⊂''),((ncol-2)⍴⊂'CF8.1'),⊂'CF9.1'
 leaf.table.Align(⊂'left'),(ncol-1)⍴⊂'decimal1'
 leaf.table.CellWidths cw
 leaf.table.Gridlines 1,(⊂0.5,(2-ncol)↑0.5),0
 leaf.table.Spacing 1 1
 leaf.table.TFont'TI,10'
 leaf.table.Titles('' 'North'),(2↑districts),(⊂'South'),2↓districts
 leaf.table.TDepth 0 0 1 1 0 1 1 1 0
 leaf.table.TAlign('centre' 'right')[1+0 0 1 1 0 1 1 1 0]
 leaf.table.Heading'Table 1. First Quarter Sales ($000''s)'
 leaf.table.Footnote'Printed on 25/12/1999' 'by Adrian'
 leaf.table.List ¯1↓[1]products,salesQ1
 leaf.table.Rule 0.5
 leaf.table.Spacing 3 3
 leaf.table.List ¯1↑[1]products,salesQ1
 View doc←leaf.Close


NewLeaf for Dyalog12: Tables Wider Than One Page

Tables Wider Than One Page

Version 1.5 of NewLeaf adds the capability to take data which is much too wide to fit on the page, and split the table both horizontally and vertically on to as many pages as necessary. To set up some suitable test data ...

wks←(⊂'Wk'),¨⍕¨⍳52
sku←'P',¨⍕¨⍳8
sales←?((⍴sku),(⍴wks))⍴1000

We can start with some very simple code to set up the column widths and run the report:

 leaf.Use''
 leaf.table.Titles(⊂'Product'),wks
 leaf.table.CellWidths 72,(⍴wks)⍴60
 leaf.table.Align(⊂'Cen'),(⍴wks)⍴⊂'Right'
 leaf.table.List sku,sales
 PostScrp.View leaf.Close

You can see that NewLeaf has fitted three folds of the short table into the available space, but it would clearly be better to repeat the product id at the left-hand side of each repeat.

The new property which you will use to control this is called KeyStyle, and can be used to force repeating columns, blank out repeated rows, rule when a key changes, and so on.

In this case, we can set the first column to repeat on every fold of the report:

 leaf.Use''
 leaf.table.Titles(⊂'Product'),wks
 leaf.table.CellWidths 72,(⍴wks)⍴60
 leaf.table.Align(⊂'Cen'),(⍴wks)⍴⊂'Right'
 leaf.table.KeyStyle 1,(⍴wks)⍴0
 leaf.table.List sku,sales
 PostScrp.View leaf.Close

Now we have a much better structured table – it would be interesting to extend it by adding a product category column to the left, and having the horizontal rules shown only when the category changes.

The next example adds more products, and groups them into 4 categories. The normal gridlines are suppressed, and the KeyStyle is set to 11 (1+2+8) which forces the column to repeat (1) and also blanks repeated rows (2) and rules across the grid when ever the value of this column changes (8).

 wks←(⊂'Wk'),¨⍕¨⍳52
 sku←'P',¨⍕¨⍳11
 type←3 2 4 2/'One' 'Two' 'Three' 'Four'
 sales←?((⍴sku),(⍴wks))⍴1000
 leaf.Use''
 leaf.table.Titles(⊂'Product'),wks
 leaf.table.CellWidths 72 72,(⍴wks)⍴60
 leaf.table.Align('Left' 'Cen'),(⍴wks)⍴⊂'Right'
 leaf.table.Gridlines 1 0.2 0
 leaf.table.KeyStyle 11 1,(⍴wks)⍴0
 leaf.table.List type,sku,sales
 PostScrp.View leaf.Close

You might like to continue to experiment with more held columns, shading, forced column breaks and so on. There is an example function Folder in the NewLeaf workspace which shows most of the possibilities.


NewLeaf for Dyalog12: NewLeaf Reference

NewLeaf Reference

This section explains the components which you can use on any master-page, the functions which you call to write text and graphics to the paper, and all the properties which you can set to alter the appearance of the final output.

  • The object catalogue – to review the master page elements
  • The Function list – for the complete function reference
  • The Property list – for all the settable options
  • Customisations – things you can change in the underlying engine


NewLeaf for Dyalog12: Object Catalogue

Object Catalogue

The page design elements you can use are:

  • The Page – to set up paper size, orientation, chosen printer
  • The Frame – region(s) where text will be added to the page
  • The Rule – decoration which appears on every page
  • The Box – decoration which appears on every page
  • Static Text – repeating text, optionally angled
  • Wrapping Text – repeating text, wrapped into a defined space
  • The Bitmap – decoration which appears on every page
  • The Metafile – for logos or background fills

For more information, click any element in this list.


NewLeaf for Dyalog12: The Page

The Page

This is used to set up the overall shape of the report. By default it will use the current Windows printer, the selected paper size and orientation.

However you can override any of these, for example to route a report to a particular printer, or force a ‘Landscape’ orientation whatever the current Windows settings.

Properties

Paper ... A4;Letter;Fanfold ... etc.
Orientation ... Portrait;Landscape
Printer ... (default);Installed Printers

You can choose paper sizes from a preset list – see Customising NewLeaf for more details on adding special papers to this list.


NewLeaf for Dyalog12: The Frame

The Frame

The Frame is the basic element of page-layout in NewLeaf. It defines a rectangular region into which text can be placed or flowed.

By default, frames are borderless with no gutter (text wraps to the full width of the frame) and no background fill. The basic frame properties are an id, position and size (measured from the lower left corner of the paper in x,y co-ordinates), and optionally:

Properties

Border | line-weight in points
Gutter | inner margin in points all round
Shadow | drop shadow behind frame (should be bordered)
Colour | colour of border
Fill | grey-scale value from 1 (feint) to 7 (solid), also 8=solid white
Overflow | 0 (autoskip) will skip to next frame on filling this one; 1 (spill) allows text to run out of the frame; (discard) eliminates any text which would otherwise skip or spill.
Clip | trims placed text at right edge of frame. Default is to over-run.

Normally, a gutter is only necessary for bordered frames, as the border is drawn entirely inside the frame dimensions. The default for Overflow is 0 which forces automatic continuation of text to the next frame. It may sometimes be better to allow text to over-run the frame, for example in an address box, in which case Overflow should be set to 1. If overflowing text is an error, it is best to discard it completely with overflow=2. Note that setting overflow>0 cancels all automatic frame-skipping for the frame in question.

Similarly Clip should be left at 0 for an address box, but for function listings it might look more tidy to clip wide lines (usually just the header) rather than let them run to the edge of the paper.


NewLeaf for Dyalog12: The Rule

The Rule

In a complex page layout with several columns, it is often preferable to separate columns vertically with a fine rule. Similarly, many letterheads require a quite heavy horizontal rule below the company name, or above the address details at the foot.

If you have worked through the Designer Exercises, you will have added several rules to a typical master page. They were used to separate the header and footer, and also to add a ‘fold mark’ to the left edge of the paper as a coloured hairline.

Properties

Colour ... (from leaf.∆colours)
Style ... one of Solid, Dash, Dot, Dot-Dash
Weight ... line weight in points
HTML ... is the rule required in HTML output

If you want to enclose a rectangle, it is much more efficient to use the ‘Box’ which has some additional properties such as background shading.


NewLeaf for Dyalog12: The Box

The Box

This component may be used to box other frames, or to assist in drawing up a complex form layout such as an invoice. It may be edged, shaded or shadowed.

Properties

Border ... draw border, or not
Shadow ... add drop shadow
Colour ... choose from standard colours
Pattern ... choose from list of fill patterns
Weight ... line weight in points


NewLeaf for Dyalog12: Fixed Text

Fixed Text

This object is used to add fixed text to appear on every page of output. It would normally be added to the layout as a simple horizontal line (the baseline for the text), however if you draw out a rectangle the text will be written along the diagonal of the rectangle you draw, with no clipping or wrapping. The baseline (or diagonal) is extended as necessary.

The default diagonal (for rotated text) runs from top left to bottom right of the containing rectangle; you can select any of the four alternative diagonal directions with the ‘Direction’ property. Most of these work best if you also centre the text with the ‘attach to width’ button.

If you need to wrap horizontal text into a given rectangle, use the Wrapping Text object instead.

Properties

Colour ... (from leaf.∆colours)
Font ... (from the current font list)
Size ... font size in points
Direction ... selected diagonal for angled text
HTML ... is the text required in HTML output

Substitution parameters

You can substitute any number of parameters (marked with %1 to %99 as in DOS batch files), the current page number (&p), the total number of pages (&n), or the date and time of printing (&d &t). If the parameters are all known when you begin the report, simply give them as the left arguments to leaf.Use, for example to have %1 replaced by your current file name:

∆file leaf.Use rpt_name

To substitute parameters ‘in flight’, for example to thumb-index a workspace listing with the function name that starts the page:

1 leaf.Subst fname

Note that this must also be passed to leaf.Use for the very first page as the fixed text is defined when the layout is opened, i.e. before the first call to leaf.Place or leaf.Flow.

Customising the page numbers

NewLeaf can automatically number pages for you, starting from 1 by default. The NewLeaf text object can be captioned with any simple string of text such as:

Page &p of &n
Section 1.3.&p
(&r)

The current page will be substituted for the &p placeholder, or you can use Roman numbers with &r. To set the page counter to a specific value:

leaf.Set 'currentpage' n

Adding date and time

Many organisations routinely add “date and time of printing” to all official documents. The NewLeaf text object can be captioned with any simple string of text such as:

Printed on &d at &t

The current date (in the Windows short-date format) will be substituted for the &d placeholder, and the current time (in 24hr format) will replace the &t marker.


NewLeaf for Dyalog12: Wrapping Text

Wrapping Text

This object is used to add wrapping text to appear on every page of output. You can substitute parameters (marked with %1 to %99 as in DOS batch files), or the date and time of printing into the text, which will then re-wrap into the rectangle defined in the Designer. Hard linebreaks may be included as ‘pipe’ characters in the text, or as newlines, in either the fixed part of the content or in any of the parameters being substituted.

Properties

Colour ... (from leaf.∆colours)
Font ... (from the current font list)
Size ... font size in points
Pitch ... vertical spacing in points
HTML ... is the text required in HTML output

For more details on the properties and parameter substitution, see Fixed Text.

Note that the text will wrap when entered as the object’s caption in the Designer, but due to the inaccuracy of Windows’ font scaling, the wrap points might not reflect the true line-break positions when you print the document. Use the Preview tool in the Designer for a final check.


NewLeaf for Dyalog12: The Image

The Image

The Image object is used on page layouts to add a constant element (typically a bitmap of a company logo) to the page definition. The caption property holds the name of the required bitmap file (include the full path name if necessary) and in addition you might need to specify the dpi (dots per inch) at which it was scanned.

When you first add an image to the page layout, it is shown at a notional size of 96 by 48 pixels. When you overtype the caption with a valid file name (bitmap or JPEG are usual) the placeholder will snap to the correct shape and size. For a large image, you may well want to adjust the Scan property to (say) 300dpi to reduce the image size as drawn on the page.

Note that PDF output from NewLeaf supports bitmaps (uncompressed) and JPEGs.

Properties

Scan ... DPI image should render at
HTML ... is the picture required in HTML output

The default is 96dpi, which is correct for screen snaps, but high-resolution scans suitable for printing might be 300dpi or higher. For HTML output, if you omit the extension the default will be to include a link to a GIF file of the same name as the bitmap.

If your logo appears much too large or much too tiny, you probably have the wrong scan frequency.


NewLeaf for Dyalog12: The Metafile

The Metafile

The Metafile object is used on page layouts to add a constant element (such as a company logo) or to make a background fill for the entire page. Normally you would save the metafile with a ‘placeable header’ included, which holds the size information. In this case, NewLeaf will normally use the defined size, and simply place the image with the top left corner at the top left of the box you draw.

However you can set ‘Stretch to Fit’ in which case the image will be scaled to cover the entire rectangle you draw out. This would be appropriate for graded fills, such as are used in PowerPoint backgrounds.

Properties

Stretch ... Resize to fit drawn area

N.B. Metafiles will not appear on reports printed using the ‘Direct PostScript’ option from the viewer. They print normally on a standard Windows printer.


NewLeaf for Dyalog12: Function Reference

Function Reference

All the NewLeaf functions, with detailed examples.

BeginBlock | leaf.BeginBlock – open a named block
Bitmap | leaf.Bitmap – placing bitmaps
BitmapLeft | leaf.BitmapLeft – wrap around bitmaps
BitmapRight | leaf.BitmapRight – wrap around bitmaps
Bookmark | leaf.Bookmark – mark TOC entry
Bump | leaf.Bump – add extra vertical space
CharSep | leaf.CharSep – add a character rule
Close | leaf.Close – return completed report
CopyFit | leaf.CopyFit – copy fitting
DefineFont | leaf.DefineFont – defining new font codes
DefinePaper | leaf.DefinePaper – defining new paper sizes
DefineStyle | leaf.DefineStyle – define custom style
DropCap | leaf.DropCap – setting drop caps
EndBlock | leaf.EndBlock – complete a named block
Flow | leaf.Flow – flow text into frames
FlowList | leaf.FlowList – set frame sequence
FrameWidth | leaf.FrameWidth – query frame width
Gallery | leaf.Gallery – list style gallery
Include | leaf.Include – include chart from RainPro
IncludeLeft | leaf.IncludeLeft – include at left margin
Info | leaf.Info – return current position
Init | leaf.Init – clear all settings
Measure | leaf.Measure – measure any text
Metafile | leaf.Metafile – add metafile image
MetafileLeft | leaf.MetafileLeft – wraparound metafile
Mirror | leaf.Mirror – enable HTML and other formats
NewFrame | leaf.NewFrame – jump to a new frame
NewPage | leaf.NewPage – jump to a new page
NumPages | leaf.NumPages – query number of pages
Overlay | leaf.Overlay – overlay a previous report
Place | leaf.Place – place text into frame
PopFrame | leaf.PopFrame – revert to previous frame
PopStyle | leaf.PopStyle – undo paragraph style
PushFrame | leaf.PushFrame – define temporary frame
Query | leaf.Query – check property settings
Reset | leaf.Reset – reset paragraph properties
Richtext | leaf.Richtext – including RTF from a RichEdit control
Rule | leaf.Rule – rule across frame
Set | leaf.Set – set any properties
SkipToPage | leaf.SkipToPage – reset page number
Spool | leaf.Spool – save report on file
Style | leaf.Style – set paragraph style
Subst | leaf.Subst – parameter substitution
Switch | leaf.Switch – change layout in flight
TCharSep | leaf.table.CharSep – apply character rule
TEndgrid | leaf.table.EndGrid – ending a table explicitly
TList | leaf.table.List – simple column-based reports
TMeasure | leaf.table.Measure – measure table cells
TQuery | leaf.table.Query – check table properties
TReset | leaf.table.Reset – reset table properties
TRule | leaf.table.Rule – rule across table
TSet | leaf.table.Set – setting table properties
TSpread | leaf.table.Spread – spread matrix into a table
Use | leaf.Use – using master pages
Vcolour | leaf.vml.Colour – set line colour
Vfill | leaf.vml.Fill – set fill pattern
Vnib | leaf.vml.Nib – set line weight
Vpolybar | leaf.vml.PolyBar – draw multiple boxes
Vpolyline | leaf.vml.Polyline – line drawing
Vstyle | leaf.vml.Style – set line style
Vgsave | leaf.vml.GSave – save co-ordinate system
Vgrestore | leaf.vml.GRestore – restore co-ordinate system
Vtranslate | leaf.vml.Translate – translate co-ordinate origin
Vscale | leaf.vml.Scale – scale co-ordinates


NewLeaf for Dyalog12: leaf.BeginBlock – open a named block

leaf.BeginBlock – open a named block

Mark a section of any report which may be bordered and edged with specified gutter and border properties.

⍝ 2pt border, colour=9, gutter=12pts
 leaf.BeginBlock'Secondblock' 2 9 12

The argument gives ...

  • Block name (required if we want to use it in a RainPro chart)
  • Edge weight (default 0 for unedged) in pts
  • Border colour (black is default) as a number
  • Gutter (default half current typesize) to be allowed to the left and right of the text. Use the normal paragraph spacing (or call leaf.Bump explicitly) to allow space top and bottom. Note that the gutter is allowed outside the normal frame width, so be careful with multi-column layouts. You may use indenting to ensure the gutter stays inside the frame width.
  • Rounding in pts (default square corners) in both (x,y) directions

Named blocks get included as anchors in HTML/PDF output. The may also be included as ‘notes’ in any RainPro chart which allows you to make chart annotations of any complexity in NewLeaf and have them scaled to fit into a given region in your charts.

Once opened, a block remains open until closed with leaf.EndBlock. This draws the borders and marks the block as complete. If a block crosses a page boundary, it is automatically completed at the bottom of the page and re-opened at the top of the new page.

See also ...

leaf.EndBlock – complete a named block


NewLeaf for Dyalog12: leaf.Bitmap – placing bitmaps

leaf.Bitmap – placing bitmaps

To add a Windows bitmap or JPEG image to a report as an independent paragraph (using the current settings for alignment and spacing):

leaf.Bitmap 'screen.bmp'

This will assume a 96dpi screenshot unless you add the second argument to give the scan frequency of the original, for example for a 300dpi scanned image:

leaf.Bitmap 'photo.jpg' 300
'pics' leaf.Bitmap 'photo.jpg' 300

The second example shows that you can give a temporary paragraph style as the optional left argument.

If this function gives the first content for a new frame, NewLeaf will not skip to a new frame however big the picture is. It will be scaled down to the frame-size (preserving aspect ratio) to ensure it always fits. If the bitmap follows other content, it will be scaled down to frame width, and will force a frame-skip if it does not fit into the remaining vertical space.


NewLeaf for Dyalog12: leaf.BitmapLeft – wrap around bitmaps

leaf.BitmapLeft – wrap around bitmaps

NewLeaf has a simple BitmapLeft function to place a screen snap or scanned image at the left margin and mark the area for text wrap-around. This takes as argument a two-element vector giving the name of the bitmap file (this assumes .BMP if no extension is given) and an optional scan frequency (default 96dpi).

leaf.BitmapLeft 'myscreen'       ⍝ Screen snap
leaf.BitmapLeft 'artwork' 300    ⍝ Scanned image

The bitmap will be scaled to the width of the frame (or the lesser of width and depth if it is the first element in the frame) if it is to wide or tall to fit. Any following text should be added with leaf.Flow or leaf.Richtext if it is to be wrapped around the picture. To have NewLeaf skip down below the picture (equivalent to the ‘clear=all’ command in HTML) you can use leaf.Place rather than leaf.Flow – typcally with a subheading for a new section.


NewLeaf for Dyalog12: leaf.BitmapRight – wrap around bitmaps

leaf.BitmapRight – wrap around bitmaps

The BitmapRight function places a screen snap or scanned image at the right margin and marks the area for text wrap-around. This takes as argument a two-element vector giving the name of the bitmap file (this assumes .BMP if no extension is given) and an optional scan frequency (default 96dpi).

leaf.BitmapRight 'myscreen'       ⍝ Screen snap
leaf.BitmapRight 'artwork' 300    ⍝ Scanned image

Any following text should be added with leaf.Flow or leaf.Richtext if it is to be wrapped around the picture. You may call both BitmapLeft and this function on successive lines to have text flowed in a narrow column between two pictures.


NewLeaf for Dyalog12: leaf.Bookmark – mark TOC entry

leaf.Bookmark – mark TOC entry

This function is to help you manage the production of long documents, where extra navigation information is helpful in either the NewLeaf viewer or in a finished document published as a PDF file with Adobe Acrobat. You may also use page-references to resolve bookmark references to page numbers when the report is completed.

The simple form of the command is ...

leaf.Bookmark 'Recognising Trees'
'subhead' leaf.Place 'Tree Recognition'

The bookmark will be placed on the next item of text to be generated, using leaf.Flow, leaf.Place or any of the table commands. Bookmarks generated in this form are shown in alphabetic order in the ‘Go to page ...’ dialogue in the viewer.

Making an indented outline for Adobe Acrobat

Bookmark information is included in the PostScript file generated for Distiller using PostScrp.WritePDF. In this case it will be helpful to indicate the outline level of the bookmark, with major sections at level-1 and subsidiary sections indented to form a contents tree.

leaf.Bookmark 'Recognising Trees' 1
'subhead' leaf.Place 'Tree Recognition'
leaf.Bookmark 'The Larch' 2
'subhead' leaf.Place 'No.1 The Larch'
leaf.Bookmark 'In winter' 3
'subhead' leaf.Place 'The Larch in Winter'

... and so on. This structure will then appear in the Acrobat Viewer outline bar to the left of the document. By default, sections will be closed on opening the document – you can force the Acrobat Viewer to open a section automatically by appending 1 as the final parameter to the bookmark call:

leaf.Bookmark 'Recognising Trees' 1 1
'subhead' leaf.Place 'Tree Recognition'
leaf.Bookmark 'The Larch' 2

Documents including outline information will automatically show the outline bar when opened in the Acrobat viewer.

Linking to external resources

You may add an optional 4th argument which simply creates an entry in the contents tree to point to an external resource, such as a webpage or another PDF file.

leaf.Bookmark 'External links ...' 1 1
leaf.Bookmark 'Home page' 2 0 'http://www.causeway.co.uk/'

leaf.Bookmark 'Manual' 2 0 'c:\docs\manual.pdf'

These bookmarks will be ignored by the APL document viewer.

Checking the bookmark table

If you want to construct your own viewer, with a tree-structured table of contents, you can check the page-count, title and bookmarks table with info←PostScrp.Info spl. The bookmarks table is a 3-column matrix giving the bookmark name, page number and indent level. Dummy entries (links to webpages or other PDFs) have a page number of 0 and you would probably screen these out.


NewLeaf for Dyalog12: leaf.Bump – add extra vertical space

leaf.Bump – add extra vertical space

To add a specified amount of vertical space into a report or table:

leaf.Bump 12      ⍝ spaces down 12 points
leaf.table.Bump 6  ⍝ 6 points above next table row

Typically this might be used after an included chart or table.

Note that you must use leaf.table.Bump to add space within a table; if you call leaf.Bump this will complete the current table and begin a new one, with a new set of headings.

leaf.table.List mat[block1;]
leaf.table.Bump 12
leaf.table.List subtot     ⍝ etc


NewLeaf for Dyalog12: leaf.CharSep – add a character rule

leaf.CharSep – add a character rule

LaserJet II printers are very slow at drawing lines and grids. If you simply want to rule across under a section, it is much faster to do this with line-drawing characters. All TrueType fonts have an ‘emdash’ which will make a continuous line when appropriately reshaped. APL normally maps the ‘upstile’ character to the emdash, but check the fonts in CharMap to be sure!

leaf.Flow txt
leaf.CharSep '⌈'    ⍝ Check the mapping!


NewLeaf for Dyalog12: leaf.Close – return completed report

leaf.Close – return completed report

As you build up your report, each page is held internally in the NewLeaf namespace as a simple text vector of PostScript code. When the report is complete, you should run the leaf.Close function, which adds header details (for example it enumerates the fonts used in the document), to have the complete report returned to your application:

     rpt←leaf.Close
     ⍴rpt
21453

This can be printed with the PostScript .Print function, or you might wish to preview it first with PostScrp.View:

PostScrp.View rpt      ⍝ View starting from the first page
5 PostScrp.View rpt    ⍝ Start at the 5th page
PostScrp.Print rpt     ⍝ Write to the default Windows printer
'file' PostScrp.WriteEPS rpt  ⍝ Output as file.EPS

Note that the right-mouse menu on the viewer allows you to print the report or save it to file as EPS.

If you use CausewayPro for your application programming, there is a PostScript viewer object which takes as its data the current page, and as its reference a PostScript definition such as rpt. If you make a simple form definition (probably including a VCR control to set the page number) which includes this you have a very simple and effective print-preview mechanism with full pan and zoom already built in. There are some examples in the CausewayPro Tutor namespace which you can copy and adapt.

See also Using the PostScript Viewer.


NewLeaf for Dyalog12: leaf.CopyFit – copy fitting

leaf.CopyFit – copy fitting

Sometimes it is helpful to know how many lines your text will take up before you ask NewLeaf to wrap it into the current frame. You could use this to manage your own widow/orphan control, or even to change the page layout dynamically, for example to set a header paragraph in a boxed frame that exactly fitted it.

The syntax of this call is:

lines←fw CopyFit para

... where fw is the width of the frame you want to check. Remember to subtract any gutters and indents from this. To calculate the exact frame depth, simply multiply by the font pitch, e.g. 14.4 for default 12-point Times.


NewLeaf for Dyalog12: leaf.DefineFont – defining new font codes

leaf.DefineFont – defining new font codes

To make a temporary short code for a non-standard TrueType font:

leaf.DefineFont 'uncl' 'Uncial'

... which will set up the association between the short code ‘uncl’ and the TrueType font ‘Uncial’. If you give a two-character short code, DefineFont will automatically define a full set of four fonts so that:

leaf.DefineFont 'ga' 'Garamond MT'
leaf.Font 'gai'

... will set the working font to italic Garamond. If you have the font loaded on a PostScript printer, you can add the PostScript font name as the third element:

leaf.DefineFont 'ga' 'Garamond MT' 'Monotype-Garamond'

If you do not give a PostScript font name, all fonts default to Times-Roman on PostScript devices. Note that NewLeaf assumes that all the required fonts have been pre-loaded into the printer.

NB This method assumes that your PostScript fonts will be suffixed ‘Bold’ ‘Italic’ and ‘BoldItalic’ – if this is not the case you must add each font variant individually.

You can make the changes permanent by specifying 1 as the left argument and saving the workspace, but please note that you will need to re-apply your changes every time you upgrade NewLeaf.


NewLeaf for Dyalog12: leaf.DefinePaper – defining new paper sizes

leaf.DefinePaper – defining new paper sizes

NewLeaf is shipped with a table defining most of the standard paper sizes recognised by Windows. You can make permanent additions to this table, but please retain a copy of the code you use, as you will need to re-apply these changes every time you install a new version of NewLeaf.

leaf.DefinePaper 'Tall' (200 1100)

The second argument gives the (x,y) size of the paper in points. Use the same function with the paper-name only to un-define an existing paper. Save the workspace to make your changes permanent.


NewLeaf for Dyalog12: leaf.DefineStyle – define custom style

leaf.DefineStyle – define custom style

NewLeaf is supplied with a small set of built-in styles for major and minor headings, body text, and APL listings. To list these ...

leaf.Gallery  ⍝ lists current styles

You can add new styles, or over-write any of the existing set at any time. Probably it would be best to put all your style definitions together at the top of your report like this:

'h1=Major Heading' leaf.DefineStyle ('font' 'Tib,18')('align' 'cen')
'h2=subhead' leaf.DefineStyle ('font' 'tib,13')('minafter' 72)
'body=body text' leaf.DefineStyle ('font' 'he,9/11')('keep' 3)

Then set the base style to body text with:

leaf.Style 'body'

... so that it becomes the base style for your document.

Note that you must give the style name in full here (but matches are case-insensitive) but that it is OK to abbreviate the property names down to the initial 2 characters. If you run leaf.Gallery again, it will show the properties with their full names.

Styles are reset to shipped defaults whenever you run leaf.Init or leaf.Close. To make your changes permanent, set:

leaf.∆defgallery←leaf.∆gallery

... and save the workspace. Remember to re-apply the changes whenever you upgrade your copy of NewLeaf.


NewLeaf for Dyalog12: leaf.DropCap – setting drop caps

leaf.DropCap – setting drop caps

The DropCap function takes a single character or short (enclosed) text vector and places it at the left margin, sized to cover a specified number of lines of normal text. The default height is 2 lines, and the default font is the current text font.

leaf.DropCap 'T'            ⍝ Simple initial capital
leaf.DropCap 'N' 5          ⍝ Span 5 lines of text
leaf.DropCap 'H' 3 'Heb'    ⍝ 3 line span, Helvetica bold

Note that you can specify a short text vector, but this must be enclosed unless you also set the height or the font:

leaf.DropCap ⊂'THIS'
leaf.Flow 'is an interesting page of text ...'

Newleaf will wrap as many paragraphs as necessary around the rectangle defined by the DropCap.


NewLeaf for Dyalog12: leaf.EndBlock – complete a named block

leaf.EndBlock – complete a named block

Completes the current block, and draws the specified border.

leaf.EndBlock

If a block spans a page or column boundary, it will be closed and re-opened at the top of the new frame with the same attributes. BorderedBlocks is the testbed function which illustrates most of the possibilities.

See also ...

leaf.BeginBlock – open a named block


NewLeaf for Dyalog12: leaf.Flow – flow text into frames

leaf.Flow – flow text into frames

To flow one or more paragraphs of free text into the current frame:

r←leaf.Flow vtv  ⍝ Vector of text vectors

A simple vector is treated as one paragraph, and has the current values of <before> and <after> spacing applied. It is wrapped into the frame using the current Font and Pitch. Any indents are also applied, and if automatic numbered indents are in effect, the counter will be incremented appropriately.

Returns (shyly) the number of lines remaining in the frame (assuming the current type size).

A vector of vectors is treated as a sequence of paragraphs, so this can be used to write an entire set of indented blocks at a single call. To use an existing style, pass the style name as the left argument:

'indent' leaf.Flow mytext

The style will be applied only to the text in this particular call.

Using HTML to enhance formatted text

NewLeaf supports a selection of HTML tags which can be used to change the appearance of text within a paragraph. These are:

  • Bold text is surrounded by <b>text</b>
  • Italic text is surrounded by <i>text</i>
  • Superscript text is surrounded by <sup>text</sup> and is useful for footnote references or mathematical expressions
  • Subscript text is surrounded by <sub>text</sub> and again is useful when setting formulae
  • Underlined text is surrounded by <u>text</u>
  • Font changes may be achieved by <font face=Arial>text</font>
  • Tabs are skipped to with <tab> or embedded tab characters

Note that heavy use of these tags substantially increases printing time. If you simply want to underline a subheading, set its style to include ‘emphasis’ ‘underline’ and use leaf.Place rather than surrounding it with HTML tags and calling leaf.Flow.

See also ...

How to Mark Text as Bold or Italic | leaf.Tabrack – set up tabstops

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.FlowList – set frame sequence

leaf.FlowList – set frame sequence

By default, NewLeaf uses all the frames in your page layout in the order they appear in the definition. If you want to take them in a different order (possibly missing out some frames entirely):

leaf.FlowList 3 2 4

In this example, NewLeaf will ignore frame 1, start with frame 3, then use 2 and 4 before moving on to the next page.


NewLeaf for Dyalog12: leaf.FrameWidth – query frame width

leaf.FrameWidth – query frame width

To find out the width (in points) of the current frame:

 ww←leaf.FrameWidth

Note that this may vary depending on the paper size if you use anchored frames, i.e. a fixed margin. It will not change if you simply change printer, as all margins are relative to the edge of the paper, not the printable area.


NewLeaf for Dyalog12: leaf.Gallery – list style gallery

leaf.Gallery – list style gallery

This command lists the current style table:

      leaf.Gallery   ⍝ list style gallery
 Body      Normal Paragraph    Font     Ti,12
                               Pitch       15
                               Align     Left
                               Spacing   0 12
 Indent    Simple Indent       Font    Ti,11/14
                               Indent  36 0
 Code      APL Listings        Font     APL,9/11
                               Spacing      6 12
                               Keep            8
 Heading   Major heading       Font     Ti,18
                               Spacing  24 6
                               Align    centre
 Subhead   Minor heading       Font     Heb,14
                               Spacing  18 6

Note that the style table reverts to ‘factory defaults’ whenever you run leaf.Init. To save your definitions permanently, you could assign your table to the default table with leaf.∆defgallery←leaf.∆gallery or (better) run your own function to replace the standard styles at the head of each set of reports.


NewLeaf for Dyalog12: leaf.Include – include chart from RainPro

leaf.Include – include chart from RainPro

A NewLeaf report can include any other section of PostScript output from a compatible Causeway product such as the RainPro presentation graphics tool. The chart will be scaled to fit exactly into the width or height (whichever is the tighter constraint) of the current frame, preserving the aspect of the chart. For example (assuming you have copied the charting namespace as ch):

ch.Bar 3 4⍴⍳12
bars←ch.Close
leaf.Place 'Barchart ...'
leaf.Include bars

Note that it is quite OK to include one completed NewLeaf report inside another – it will simply scale so that the entire page fits inside the current frame. This might be an appropriate way of ‘thumbnailing’ a set of report options.


NewLeaf for Dyalog12: leaf.IncludeLeft – include at left margin

leaf.IncludeLeft – include at left margin

Similar to the Include function, but rather than scaling the chart it simply places it at the left margin, and sets a ‘wraparound’ area so that text flows around the graphic.

ch.New 0 0 216 144   ⍝ 3" by 2" chart
ch.Plot data
leaf.IncludeLeft ch.Close

Note the need to set the chart size explicitly in Rain – this will be used by NewLeaf to define the text wraparound.


NewLeaf for Dyalog12: leaf.Info – return current position

leaf.Info – return current position

Although NewLeaf will attempt to make good decisions about page-throws and new frames, it is sometimes necessary for the application program to check exactly where it is on the page, how many lines are left, and possibly how many pages have been used. The leaf.Info function returns the current page (counting from 1 regardless of ⎕IO or your page-numbering counter); the current frame; how many frames there are on this page; how many lines remain at the font pitch in use at the time of the call.

For example:

leaf.Info
3 1 2 22
leaf.Pitch 18 ⍝ Increase the spacing
leaf.Info
3 1 2 12      ⍝ fewer lines now available

Here we are on the 3rd page, and text is being written into the 1st frame of a double-column layout. At normal spacing the frame has room for 22 more lines. If the line spacing is increased the number of available lines decreases, so (without writing anything) we are nearer the bottom of the page!

Some uses of this command might be:

  • to check for odd/even page count and skip an extra page
  • to compress vertical spacing to ensure a table fits on one page
  • to do manual widow/orphan control

Consider setting the MinAfter or Keep paragraph properties as simpler alternatives to fully manual control.


NewLeaf for Dyalog12: leaf.Init – clear all settings

leaf.Init – clear all settings

This function is called automatically when you first run any NewLeaf function, but you may like to include it in your application to make it clear that you are ‘cold starting’ at this point:

leaf.Init

All settings are returned to default, and the spool file is cleared ready for fresh output. This may be helpful if you are recovering from an application crash, and want to scrap any output generated so far.

See also ...

leaf.table.Reset – reset table properties


NewLeaf for Dyalog12: leaf.Measure – measure any text

leaf.Measure – measure any text

To find the actual size (in points) of a simple text vector or a text string:

     leaf.Measure 'Fat cat'
32.328
     'TI,18' leaf.Measure 'Hello' 'World'
39.996 45.99

The left argument defaults to the current font, as set by leaf.Font.

If you use this to determine the best size for table cells, be sure to allow for the ‘cellpadding’ which NewLeaf adds to space cell text away from the vertical gridlines. The algorithm used to compute cell padding is:

2×6⌊2⌈⌈0.4×fontsize ⍝ Cell padding

... so you should add this value to the computed width.

See also: leaf.table.Measure


NewLeaf for Dyalog12: leaf.Metafile – add metafile image

leaf.Metafile – add metafile image

To add a Windows metafile to a report as an independent paragraph (using the current settings for alignment and spacing):

leaf.Metafile 'backdrop'

This will check the defined size of the metafile (assuming it has been saved with a placeable header) and add it to the report at this size. If you require a different size:

leaf.Metafile 'artwork'  (100 200)

This will force the artwork to stretch to occupy a space 100 by 200 points. You can pass a temporary paragraph style as the optional left argument.

N.B. Metafiles will not appear on reports printed using the ‘Direct PostScript’ option from the viewer. They print normally on a standard Windows printer.


NewLeaf for Dyalog12: leaf.MetafileLeft – wraparound metafile

leaf.MetafileLeft – wraparound metafile

To add a Windows metafile to a report at the left margin, and set text wraparound:

leaf.MetafileLeft 'logo'

This will check the defined size of the metafile (assuming it has been saved with a placeable header) and add it to the report at this size. If you require a different size:

leaf.MetafileLeft 'artwork'  (100 200)

This will force the artwork to stretch to occupy a space 100 by 200 points and set the wraparound region appropriately.

N.B. Metafiles will not appear on reports printed using the ‘Direct PostScript’ option from the viewer. They print normally on a standard Windows printer.


NewLeaf for Dyalog12: leaf.Mirror – enable HTML and other formats

leaf.Mirror – enable HTML and other formats

In order for NewLeaf to create HTML output from the completed report, a significant amount of extra information must be stored in the intermediate spool file or ‘PG’ variable. For example the structure of HTML tables cannot be determined from the intermediate form otherwise. By default, this mirroring is turned off to save space and processing time. To enable it:

leaf.Mirror 1

This returns the old value for reference. The state is saved in a global switch which is not reset by leaf.Init, so you may make this change once and save the state in the workspace if you intend to use HTML output frequently.

See also ...

How to generate a simple web page


NewLeaf for Dyalog12: leaf.NewFrame – jump to a new frame

leaf.NewFrame – jump to a new frame

Skip to the next available frame, or to a frame identified by given ‘caption’ in the Designer:

leaf.NewFrame ''       ⍝ Next frame
leaf.NewFrame 'Chart'  ⍝ Specific frame

In the Designer, frames show their ids in the top left corner of the frame.


NewLeaf for Dyalog12: leaf.NewPage – jump to a new page

leaf.NewPage – jump to a new page

To jump to the first frame on a new page:

leaf.NewPage

Use leaf.Info to check the current page number if you need to force a jump to an odd-numbered page.


NewLeaf for Dyalog12: leaf.NumPages – query number of pages

leaf.NumPages – query number of pages

To check the number of completed pages on a spooled report:

pgct←leaf.NumPages spl

... where spl is the name returned by leaf.Spool ''. If there is no spooled report, this returns 0. If you call this with a null argument while a print file is open, it will return the number of pages completed to date.


NewLeaf for Dyalog12: leaf.Overlay – overlay a previous report

leaf.Overlay – overlay a previous report

Normally, the report definition gives sufficient flexibility and this function will not be required. However if you require complex elements (such as tables) in the master-page definition, you will need to define these as an overlay and tell NewLeaf to run it whenever it throws a new page.

First you should run the commands to build the overlay page, and save the completed definition in a suitable variable ...

 leaf.Use rpt.ovl  ⍝ Overlay page
 'sub'leaf.Place'Repeating Header for all pages'
 leaf.table.List 2 4⍴'This' 'Will' 'Repeat'
 ovl←leaf.Close

Now you can open your normal layout and tell NewLeaf to superimpose the saved definition on every page (including the first) ...

⍝ Choose a layout which leaves space for the repeating part
 leaf.Use rpt.follow
 leaf.Overlay ovl  ⍝ Must run AFTER Use/Switch!
 'head'leaf.Place'Main Report Starts Here'

You can pass a vector of (enclosed) overlays which will be used in turn for odd/even pages in the same way as normal page-layouts.

Note that no substitution takes place in the overlay process. This means that it is not a suitable place to define a field such as a page number, but it might be appropriate to use it for a date/time field if you want the time to stay the same on every page of a report which takes several minutes to produce.


NewLeaf for Dyalog12: leaf.Place – place text into frame

leaf.Place – place text into frame

This is the most basic routine for adding one or more lines of text to a frame. It does not attempt any wrapping, but will respect the frame edges if you have set ‘Clip’ to 1 as a property of the frame.

leaf.Place 'Hello, world'

Returns (shyly) the number of lines remaining in the frame (assuming the current vertical pitch).

You can pass the abbreviation of a style as the optional left argument, for example to place a major heading:

'Heading' leaf.Place 'Main Title'

This will apply the style, place the text, and reverse the style.

Placing several lines

If you already know exactly where the line breaks should come (for example in a function listing) you should use this function to place a matrix of text into the current frame. For example:

leaf.Place ⎕CR 'myfn'

It will be written at the current left margin, but note that no check is made on the width, so over-long lines will simply overflow the frame to the right (unless the frame has been set to clip). No wrapping is attempted, but right or centred alignment will work normally. Naturally, it is much faster to place text than to flow it with leaf.Flow.

Often this will be used with a specific style, for example to control unfortunate breaks in function listings:

'code' leaf.DefineStyle ('Font' 'APL,9/11')('keep' 12)
   ⍝ ... later
'code' leaf.Place ⎕CR 'myfn'

Note that HTML <b>tags</b> such as this are not supported by this function. If you need these, you must use leaf.Flow.


NewLeaf for Dyalog12: leaf.PopFrame – revert to previous frame

leaf.PopFrame – revert to previous frame

Having added a temporary frame definition to the frame stack with PushFrame, you revert to the previous layout with

leaf.PopFrame

All previous attributes are restored, so that text will be continued from the correct place in the restored frame.


NewLeaf for Dyalog12: leaf.PopStyle – undo paragraph style

leaf.PopStyle – undo paragraph style

Paragraph styles can be successively applied and undone in a stack, for example:

leaf.Style 'body'    ⍝ base style
leaf.Style 'indent'  ⍝ add indenting
leaf.Style 'ind2'    ⍝ next level
leaf.PopStyle        ⍝ back up
leaf.PopStyle        ⍝ revert to base

This allows you to overlay a set of new properties easily, and undo the changes without checking exactly which properties need to be backed out.

There is no limit on the depth of the style stack.


NewLeaf for Dyalog12: leaf.PushFrame – define temporary frame

leaf.PushFrame – define temporary frame

This allows a new frame to be defined on the fly anywhere within the page area. All output created with Place, Flow, Include etc. will be targeted into this frame until you revert to the underlying page with PopFrame.

The argument may be a simple vector of (x,y,width,height) in points, or a frame definition with the 5th element being a 2-column matrix of property-value pairs. All dimensions are relative to the paper, not to the previous frame.

leaf.PushFrame 4⍴100    ⍝ posn, size, w,h (x,y)
leaf.Flow'hello world in a pushed frame'
leaf.PushFrame(400 600)(120 80)(2 2⍴'Shadow' 1 'Gutter' 6)

There is no limit on the depth of the frame stack.


NewLeaf for Dyalog12: leaf.Query – check property settings

leaf.Query – check property settings

To check the current value of any paragraph property:

     leaf.Query 'sp' 'pi'  ⍝ Spacing and Pitch
0 12  14.4

This returns a vector result with one element for each property queried. You must give at least the first two letters of the property name, but the abbreviations are case-insensitive.


NewLeaf for Dyalog12: leaf.Reset – reset paragraph properties

leaf.Reset – reset paragraph properties

This function will reset all the paragraph properties to their initial values.

leaf.Reset

This may be a safer call than just ‘unsetting’ particular properties, such as indenting.


NewLeaf for Dyalog12: leaf.Richtext – including RTF from a RichEdit control

leaf.Richtext – including RTF from a RichEdit control

This command will run vector of ‘WordPad’ richtext into the frame:

leaf.Richtext rtf

Note that this is quite specific to the ‘old style’ RTF used by WordPad and the RichEdit control, and is not a general RTF parser. It will process any properties which the RichEdit supports, including tabs, paragraph alignment and simple font decorations such as bolding and colours. The text may run over more than one page, and you may include the pagebreak command in your richtext vector as \page if you wish. Note that neither WordPad nor the RichEdit have any capability to insert pagebreaks for you.

See also ...

leaf.Tabrack – set up tabstops


NewLeaf for Dyalog12: leaf.Rule – rule across frame

leaf.Rule – rule across frame

To rule across the entire frame (from left indent to right indent if these are specified):

leaf.Rule w    ⍝ where <w> is the line weight in points
leaf.Rule 1.5  ⍝ a solid black line

A vector of values gives: (line-gap-line-gap .... ) so that:

leaf.Rule 1 3 2

is ‘thin-gap-thick’.

In this release, rules are always solid and black. Possible future enhancements would be colour and line-style.


NewLeaf for Dyalog12: leaf.Set – set any properties

leaf.Set – set any properties

In NewLeaf you have two equivalent ways of setting any property. You can call leaf.Set with a short (case-independent) code for the property, or you can run a property-setting function directly. In this case you must get the function name exactly correct! See the Property Reference for details.

leaf.Set ('font' 'ti,12')('sp' 0 18)
leaf.Font 'ti,12' ⋄ leaf.Spacing 0 18

The two lines above are exactly equivalent; note that at least two characters are required to identify the property. To query the current value, you should use leaf.Query with a vector of property names.

The properties are all held in leaf.∆proplist, so to see a quick display of the available names, just type this variable to the APL session.

Whichever method you use, you will find that whenever you set a property you will be returned the previous value. This can be used to reverse a setting easily.


NewLeaf for Dyalog12: leaf.SkipToPage – reset page number

leaf.SkipToPage – reset page number

To jump to the first frame on a new page and reset the page number:

leaf.SkipToPage 123

Typically, this would be used to reset numbering to 1 at the start of a new section. You can suppress the page throw with the optional left argument, for example:

0 leaf.SkipToPage 1
leaf.Switch rpt_new

This allows you to restart page numbering and switch to a different page layout without generating a spurious blank page.

See also ...

leaf.Switch – change layout in flight


NewLeaf for Dyalog12: leaf.Spool – save report on file

leaf.Spool – save report on file

As you build up your report, completed pages are saved to file. When the report is finished, you can run the leaf.Spool function, which adds header details (for example it enumerates the fonts used in the document) and closes the file, returning the name to your application. You can check the number of pages, or preview/print the file as normal:

     spl←leaf.Spool ''   ⍝ Retain default name
     leaf.NumPages spl
47

This can be printed with the Print function in the PostScript namespace, or you might wish to preview it first with the View function:

PostScrp.View spl     ⍝ View starting from the first page
5 PostScrp.View spl   ⍝ Start at the 5th page
  PostScrp.Print spl  ⍝ Entire report
3 4 5 101 PostScrp.Print spl     ⍝ Selected pages

In general it makes sense to use Spool rather than Close for reports of more than 10 pages, as the time taken to read from file is less than the time to check the full report for a particular page. Also there is no danger of WS FULL!

If you need to retain the spool file for further processing (for example to make into booklets in a duplex layout) call leaf.Spool with a file name as right argument:

spl←leaf.Spool 'c:\temp\run1'  ⍝ returns full name

By default, NewLeaf holds the spool file in the TEMP directory. If this causes problems, set the global ∆spoolpath to the file path of your choice:

leaf∆spoolpath←'s:\temp'  ⍝ Spool on network drive

If you require system-generated unique names for the spool files, set:

leaf.∆spoolname←''

... which will make the filename from the system time in the form ‘~1234567.spl’.


NewLeaf for Dyalog12: leaf.Style – set paragraph style

leaf.Style – set paragraph style

To run a set of paragraphs in a particular style:

leaf.Style 'indent' ⍝ Set up indents
leaf.Flow txt1      ⍝ First para
leaf.Flow txt2      ⍝ Next para
leaf.PopStyle       ⍝ Back out

Note the use of leaf.PopStyle to back out the last call to leaf.Style; you can stack styles to any depth with these, but it is hard to see the value of going more than two deep!

This allows you to ‘superimpose’ styles effectively, for example an indent might add indents (obviously), reduce the font size, and increase the ‘keep’ value. By using PopStyle to back out you automatically reverse all the changes, so your normal ‘body text’ style does not need to mention these properties explicitly.

Styles are matched ignoring case; you only need to give enough of the name to ensure an unambiguous choice.

Using in-line styles with Flow and Place

Often, you will want to set a style, output one paragraph, and then immediately reverse it ...

leaf.Style 'subhead'
leaf.Place 'Introduction'
leaf.PopStyle

A shortcut for these three lines is:

'subhead' leaf.Place 'Introduction'

... which uses the optional left argument to set the style, then immediately reverses it. Because NewLeaf can take vectors of text vectors at a single call, it is possible to set an entire block of numbered indents in a single call:

'ct' leaf.DefineStyle ('ind' 36)('bullet' '#.')
⍝ ... later
'ct' leaf.Flow ∆sections

To delete an unwanted style, just call leaf.DefineStyle with an empty right argument.


NewLeaf for Dyalog12: leaf.Subst – parameter substitution

leaf.Subst – parameter substitution

Master pages may include placeholders %1 to %9 which are substituted at runtime with up to nine parameters. You can set these with leaf.Use as the report is defined, or you can update them as you go (for example to provide a ‘thumb-index’ for a workspace lister):

1 leaf.Subst flist[ct]   ⍝ current function shows in header

This will take effect at the next page throw. If you intend to manage your own page throws, substitute the parameters before you call leaf.NewPage to throw the page.


NewLeaf for Dyalog12: leaf.Switch – change layout in flight

leaf.Switch – change layout in flight

Sometimes you do not know in advance when to change page layout. For example a function lister (see Lister in the NewLeaf workspace) might start with a contents page and then switch to thumb-indexed pages for the function catalogue. You probably don’t know how many of the initial (plain) pages the contents will take.

To overcome this problem, start with the plain layout, then switch to the headed paper when you need it:

leaf.Use rpt.plain
leaf.Place contents  ⍝ may be several pages
leaf.Switch rpt.flist
... continue

Note that you cannot change page orientation or paper size using Switch.


NewLeaf for Dyalog12: leaf.table.CharSep – apply character rule

leaf.table.CharSep – apply character rule

LaserJet II printers are very slow at drawing lines and grids. If you simply want to rule across under a section, it is much faster to do this with line-drawing characters. All TrueType fonts have an ‘emdash’ which will make a continuous line when appropriately reshaped. This is normally mapped to the ‘upstyle’ character in your APL font.

leaf.table.List mat
leaf.table.CharSep '⌈'    ⍝ Check the mapping!


NewLeaf for Dyalog12: leaf.table.EndGrid – ending a table explicitly

leaf.table.EndGrid – ending a table explicitly

You can make a sequence of calls to leaf.table.List or leaf.table.Spread – NewLeaf will simply continue from where the last section ended, and will box around the whole table when you end the report, or run any non-table function such as leaf.Bump or leaf.Place.

If you want to run two tables back to back, you will need to complete the first one explicitly to get them boxed separately:

leaf.table.List mat1   ⍝ first table
leaf.table.Endgrid     ⍝ End table
leaf.table.List mat2
leaf.Close

It is harmless to run this function after every complete table, as it will do nothing unless a table is in progress.


NewLeaf for Dyalog12: leaf.table.List – simple column-based reports

leaf.table.List – simple column-based reports

This function is designed for simplicity and speed. It expects to be able to format a column of data as a single object, so the majority of properties apply to columns only. Cell data may be clipped or spilled into the following column – there is no option to wrap the data and extend the cell vertically. Tables which are too wide for the frame run downwards to the end of the first set of columns, then move back to the top of the data to generate the next set of columns, and so on. This is the opposite behavious from leaf.table.Spread which walks across the columns.

To print a simple columnar report from a matrix of data:

leaf.table.List matrix

All the normal table settings apply, but at the column level only, except for alignment, shading and ⎕FMT which may be specified by cell. Please use leaf.table.Spread if you need more complex presentation.

Setting ‘one-off’ properties

The optional left argument can set any of emphasis,colour etc. passed as a vector of property-value pairs. The values may only be numeric codes here, and would generally have been computed from the data matrix. For example ...

('emph' emp)('col' clr) leaf.table.List mat

The properties you may include here are:

  • Emphasis – selective bold/italic etc by column
  • Colour – text colour by column as palette index or RGB composite
  • BCol – cell background colour (may be set by cell)
  • Align – column alignment (0,1,2)
  • Clip – clipping rules (0-1)
  • VGrid – vertical grid lines
  • HGrid – horizontal grid lines (below each row)

The property values will normally be a vector matching the number of columns. However the cell background may be set as a matrix, and the horizontal grid lines should be given as a vector matching the number of rows in the data.

See also ...

Colour Table


NewLeaf for Dyalog12: leaf.table.Measure – measure table cells

leaf.table.Measure – measure table cells

To compute the best cell widths for an entire table (allowing for headings):

cw←leaf.table.Measure ⍕¨MAT

If you have applied a ⎕FMT string with leaf.table.Qfmt, you will need to apply the same format specification to your matrix. Note that for numeric data it may be much faster to measure the maximum value only!


NewLeaf for Dyalog12: leaf.table.Query – check table properties

leaf.table.Query – check table properties

To check the current value of any table property:

     leaf.table.Query 'cell' 'grid'
72 72  0.8 1 0  ⍝ cell widths and gridlines

This returns a vector result with one element for each property queried. You must give at least the first two letters of the property name, but the abbreviations are case-insensitive.


NewLeaf for Dyalog12: leaf.table.Reset – reset table properties

leaf.table.Reset – reset table properties

This function will close any open tables and reset all the table properties to their initial values.

leaf.table.Reset

This may be a safer call than just ‘unsetting’ particular properties which were required for a previous table.


NewLeaf for Dyalog12: leaf.table.Rule – rule across table

leaf.table.Rule – rule across table

To rule across the full width of a table:

leaf.table.Rule 2

In this release, rules are always solid and black. Possible future enhancements would be colour and line-style. Also it may be a requirement to specify which column boundaries to rule between on the table.

Note that this does not break the continuity of the table, so you can separate two blocks of data with:

leaf.table.List mat[1;;]
leaf.table.Rule 2
leaf.table.List mat[2;;]

This may often be easier to program than to set a vector of horizontal gridlines, and then pass the entire table in a single call.

A vector of values gives: (line-gap-line-gap .... ) so that:

leaf.table.Rule 1 3 2

is ‘thin-gap-thick’. The odd-numbered elements are equivalent to calling leaf.table.Bump.


NewLeaf for Dyalog12: leaf.table.Set – setting table properties

leaf.table.Set – setting table properties

In NewLeaf you have two equivalent ways of setting any table property. You can call leaf.table.Set with a short (case-independent) code for the property, or you can run a property-setting function directly. In this case you must get the function name exactly correct! See the Properties Reference for details.

leaf.table.Set ('ce' 72 72)('gr' 1 1 0)
leaf.table.CellWidths 72 72 ⋄ leaf.table.GridLines 1 1 0

The two lines above are exactly equivalent; note that at least two characters are required to identify the property. To query the current value, you should use leaf.table.Query with a vector of property names.

The properties are all held in leaf.table.∆proplist, so to see a quick display of the available names, just type this variable to the APL session.

Whichever method you use, you will find that whenever you set a property you will be returned the previous value. This can be used to reverse a setting easily.


NewLeaf for Dyalog12: leaf.table.Spread – spread matrix into a table

leaf.table.Spread – spread matrix into a table

This function allows for very complex formatting of tabular data, with most properties available at cell level. If you have a simple formatting job, where you do not need wrapping of text into cells, and can use column-level formatting, use leaf.table.List instead, as it is much faster. To populate a table with data:

leaf.table.Spread matrix

Each element of the matrix will occupy one cell, and will be aligned as per the pre-set columns alignments. Text will be wrapped into the cells (increasing the cell depth) as required. If the table is too wide for the frame, it will walk across columns, repeating key columns as required. You can constrain the total number of pages used with the fit to page property which will reduce the final table in proportion as necessary. Numbers will have the default formatting applied unless you have already set up a suitable format string for the table.

If a cell’s content is a matrix (with >1 row) then NewLeaf assumes that the application has already wrapped the text and does not change the given line-breaks.

In general, a cell will never be broken across a page boundary. The only exception is when the cell occupies more than 25% of the frame height, and does not fit into the current frame.

Setting ‘one-off’ properties

The optional left argument can set any of emphasis,colour etc. passed as a vector of property-value pairs. The values may only be numeric codes here, and would generally have been computed from the data matrix. For example ...

('emph' emp)('col' clr)('shade' (3 5⍴1 2 3)) leaf.table.Spread mat

The properties you may include here are:

  • Emphasis – selective bold/italic etc by cell
  • Borders – cell borders (left,right,bottom,top)
  • Colour – text colour as palette index or RGB composite
  • BCol – cell background colour
  • Align – alignment (0,1,2)
  • Clip – clipping rules (0-3)
  • VGrid – vertical grid lines
  • HGrid – horizontal grid lines (below each row)
  • Indents – cell indent level (0,1,2 ...)

The property values will normally match the shape of the data matrix, or may be a vector matching the number of columns. However, hgrid and vgrid would generally match the number of rows and number of columns respectively and the indent level is taken to apply down the first column only if it is passed as a vector.

Typically this could be use to make -ve numbers red, for example

clr←9×mat<0 ⍝ colour-9 is bright red

Colours 0..15 are indices into the colour table. For emphasis, use 1=bold, 2=italic, 4=underline, 8=strikethrough, summed as required. Cell borders are numbers in the range 0-9999 representing line-weights 1-9 for edges lrbt so 20 is a 2-pixel line below the cell.

  • Alignment can be 0,1,2 or 3.x for decimal (x is the number after the point).
  • Clip can be 0 1 2 3

This facility only applies to cell-level formatting – you cannot use it to set column widths, titles and so on.


NewLeaf for Dyalog12: leaf.Use – using master pages

leaf.Use – using master pages

Master pages are saved by the designer in standard APL matrices. To set a single page layout as the working definition:

leaf.Use mypage    ⍝ work with layout mypage

As you flow and place text, it will snake around the frames on the page layout until no more remain. The page will then be spooled to file, and a new page will be started using the same master, with any page numbers (marked by &p in fixed text) incremented automatically.

Note that you can pass a null argument to leaf.Use, in which case NewLeaf provides a default layout consisting of a single frame (with 1” margins all round) and a page number centred at the foot of the page.

If you have marked any parameters in the fixed text (using placeholders %1 to %9) you can substitute values for these by passing up to 9 items as the left argument to leaf.Use:

'Sales' 1998 leaf.Use salesrep

This will replace %1 with ‘Sales’ and %2 with ‘1998’ in the report master. You can update these substitutions at any time (see leaf.Subst for details).

Using a set of master pages

A common requirement is to alternate between left and right masters, possibly with a different design for the first page. It may also be necessary to make a ‘follow-on’ page for a form letter which omits the address box. Simply pass a vector of page definitions to leaf.Use:

leaf.Use left right          ⍝ alternates
leaf.Use first left right    ⍝ different 1st page
leaf.Use (⊂addr),2⍴⊂followon ⍝ letter with follow-on pages

Note that NewLeaf uses up the pages until only two remain, then these are alternated. If you know exactly where your section breaks will occur, simply pass a vector of page definitions, reshaped to match your document.


NewLeaf for Dyalog12: leaf.vml.Colour – set line colour

leaf.vml.Colour – set line colour

To set the drawing colour for the next polyline:

leaf.vml.Colour 1

Colour numbers (range 1-15) are required here.


NewLeaf for Dyalog12: leaf.vml.Fill – set fill pattern

leaf.vml.Fill – set fill pattern

To set the next polyline to be filled:

leaf.vml.Fill 4

Argument is a fill pattern from 1 (10% grey) to 15 (solid); use 0 (no fill) to revert to unfilled polylines.


NewLeaf for Dyalog12: leaf.vml.Nib – set line weight

leaf.vml.Nib – set line weight

To set the line-drawing weight (in points) for the next polyline:

leaf.vml.Nib 3

Argument is a positive scalar – non-integer values are allowed.


NewLeaf for Dyalog12: leaf.vml.PolyBar – draw multiple boxes

leaf.vml.PolyBar – draw multiple boxes

This allows you to add arbitrary filled rectangles to the output page. A likely application would be to print barcodes. You can set fill-colour and edge-weight in advance:

⍝ Simple black rectangle
 leaf.vml.Colour 0
 leaf.vml.Nib 0
 leaf.vml.PolyBar 20 20 100 100

You may pass a simple vector (the length should be a multiple of 4) or an (n,4) matrix of (xyxy) co-ordinates here giving the lower left and upper right of each bar. All co-ordinate values are in points, with the origin at the lower left-hand corner of the paper.

See also ...

leaf.vml.GSave – save co-ordinate system | leaf.vml.GRestore – restore co-ordinate system

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.vml.Polyline – line drawing

leaf.vml.Polyline – line drawing

This allows you to add arbitrary line-drawing elements to the page. This might be used in conjunction with leaf.PushFrame to make organisation charts, data-flow diagrams and so on. You can set line-styles, colours and weights in advance:

⍝ Simple coloured box
 leaf.vml.Colour 2
 leaf.vml.Nib 4
 leaf.vml.Polyline 5 2⍴100 700 200 700 200 800 100 800 100 700

You can also choose to fill the closed polyline:

 leaf.vml.Colour 12
 leaf.vml.Fill 15   ⍝ Pattern-15 is solid
 leaf.vml.Polyline 20+5 2⍴100 700 200 700 200 800 100 800 100 700

In this release, you may give colour, pattern and style numbers only here. All co-ordinate values are in points, with the origin at the lower left-hand corner of the paper.

See also ...

leaf.vml.GSave – save co-ordinate system | leaf.vml.GRestore – restore co-ordinate system

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.vml.Style – set line style

leaf.vml.Style – set line style

To set the line style for the next polyline:

leaf.vml.Style n

Styles are as for RainPro: 1=solid, 2=dash, 3=dotted, 4=dot-dash, 5=invisible.


NewLeaf for Dyalog12: leaf.vml.GSave – save co-ordinate system

leaf.vml.GSave – save co-ordinate system

Saves the current page co-ordinates prior to a scaling transformation.

leaf.vml.GSave

Remember to restore the co-ordinates afterwards!

See also ...

leaf.vml.GRestore – restore co-ordinate system | leaf.vml.Translate – translate co-ordinate origin | leaf.vml.Scale – scale co-ordinates

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.vml.GRestore – restore co-ordinate system

leaf.vml.GRestore – restore co-ordinate system

Restores to the last saved set of page co-ordinates.

leaf.vml.GRestore

Normally would be paired with GSave, enclosing a translation or scaling of the co-ordinate system.

See also ...

leaf.vml.GSave – save co-ordinate system | leaf.vml.Translate – translate co-ordinate origin | leaf.vml.Scale – scale co-ordinates

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.vml.Translate – translate co-ordinate origin

leaf.vml.Translate – translate co-ordinate origin

Re-positions the origin of the page co-ordinates to any (x,y) position, measured from the lower left corner of the co-ordinate system currently in use.

leaf.vml.Translate 100 200

Would normally be preceeded with GSave and eventually followed by GRestore to return to the previously saved settings.

See also ...

leaf.vml.GSave – save co-ordinate system | leaf.vml.GRestore – restore co-ordinate system | leaf.vml.Scale – scale co-ordinates

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.vml.Scale – scale co-ordinates

leaf.vml.Scale – scale co-ordinates

Re-scales the page co-ordinates with (x,y) multiplier. If a single number is given, both axes are scaled similarly.

leaf.vml.Scale 2

Would normally be preceeded with GSave and eventually followed by GRestore to return to the previously saved settings.

See also ...

leaf.vml.GSave – save co-ordinate system | leaf.vml.GRestore – restore co-ordinate system

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: Property Reference

Property Reference

All the properties which you can set for reports and tables.

Align | leaf.Align – paragraph alignment
Bullet | leaf.Bullet – bullet and bullet counter
Colour | leaf.Colour – set paragraph colour
Decimal | leaf.Decimal – set decimal separator
Emphasis | Emphasis – add extra font decorations
Font | leaf.Font – set current font (face and pitch)
Indent | leaf.Indent – set paragraph indents
Keep | leaf.Keep – widow/orphan control
MinAfter | leaf.MinAfter – minimum space after
PageBreak | leaf.PageBreak – set page break before
Pitch | leaf.Pitch – set line spacing within paragraph
Size | leaf.Size – set font size for paragraph
SoftHyphen | leaf.SoftHyphen – set soft hyphen character
Spacing | leaf.Spacing – set paragraph spacing
Tabrack | leaf.Tabrack – set up tabstops
Titlebar | leaf.Titlebar – title view PDF and HTML output
TOC | leaf.TOC – set Table-of-Contents level
TrueFont | leaf.TrueFont – using TrueType fonts directly
TAlign | leaf.table.Align – set cell alignment in tables
TBCol | leaf.table.BCol – set cell background colours
TBorders | leaf.table.Borders
TCaption | leaf.table.Caption – set table caption
TCFont | leaf.table.CFont – set the caption font
TCColour | leaf.table.CColour – set caption colour
TCell | leaf.table.CellWidths – set cell widths
TClip | leaf.table.Clip – set cell clipping
TTColour | leaf.table.TColour – set text colour for titles
TTBColour | leaf.table.TBCol – set the background colour for column titles
TEmphasis | leaf.table.Emphasis – set character formatting
TFillchar | leaf.table.Fillchar – set fill character
TFit | leaf.table.Fit – set ‘fit to page’ parameters
TFont | leaf.table.Font – set table fonts
TFootnote | leaf.table.Footnote – set table footer
TFFont | leaf.table.FFont – set footnote font
TFColour | leaf.table.FColour – set footnote colour
TFStyle | leaf.table.FStyle – set footnote style
TGrid | leaf.table.Grid – set gridline weights
TGridcolour | leaf.table.GridColour
TGridStyle | leaf.table.GridStyle
THeading | leaf.table.Heading – set table heading
THFont | leaf.table.HFont – set font for heading
THColour | leaf.table.HColour – set heading colour
THStyle | leaf.table.HStyle – set table header style
TIndent | leaf.table.Indent – set table indents
TKeyStyle | leaf.table.KeyStyle – set column key style
TMaxCell | leaf.table.MaxCell – set maximum limit for measured widths
TMerge | leaf.table.Merge – set title cell merging
TMinCell | leaf.table.MinCell – set minimum cell width
TOffset | leaf.table.Offset – set grid offset
TPitch | leaf.table.Pitch – table text pitch in wrapped cells
TQfmt | leaf.table.Qfmt – set format specifications
TRounding | leaf.table.Rounding
TRowheights | leaf.table.RowHeights – set ‘at least’ heights
TShade | leaf.table.Shade – set cell shading
TSpace | leaf.table.Spacing – set table spacing
TSubhead | leaf.table.Subhead – set second-level heading
TSFont | leaf.table.SFont – set the subhead font
TSColour | leaf.table.SColour – set subhead colour
TTalign | leaf.table.TAlign – set title alignment
TTDepth | leaf.table.TDepth – tree-structured titles
TTFont | leaf.table.TFont – set table title font
TTitles | leaf.table.Titles – set table column titles
TValign | leaf.table.Valign – set vertical cell alignment


NewLeaf for Dyalog12: leaf.Align – paragraph alignment

leaf.Align – paragraph alignment

Placement of paragraph text within the frame.

leaf.Align 'Centre'

May be ‘Left’ ‘Centre’ or ‘Right’. The default is ‘Left’.

Only the first letter of the alignment is required, capitalisation is ignored.


NewLeaf for Dyalog12: leaf.Bullet – bullet and bullet counter

leaf.Bullet – bullet and bullet counter

Current bullet character, and optional counter for automatically numbered bullets. The character may be:

⍕ (the APL format symbol)
#. to get bullets shown as 1. 2. etc.
(@) to get (a), (b) and so on
(^) to get (i), (ii) and so on

Any short text vector is valid. The characters # and @ are substituted with the current bullet counter (starting from 1 by default) as either a decimal number or an element from a-z, A-Z. For Roman numbers use ^ as the placeholder.

leaf.Bullet '⍕'        ⍝ simple bullets
leaf.Bullet '(#)' 12   ⍝ numbers from 12

To start from (A) set the initial bullet counter at 27:

leaf.Bullet '(@)' 27


NewLeaf for Dyalog12: leaf.Colour – set paragraph colour

leaf.Colour – set paragraph colour

Colour of paragraph text using the standard HTML colour names:

‘maroon,green,navy’ etc. ... Dull colours

‘red,lime,blue’, etc. ... Bright colours

leaf.Colour 'teal'
leaf.Set ('font' 'ti,16')('colour' 'blue')

The complete list is given in leaf.∆colours. You can also use the standard HTML colour convention with ‘#FFFFFF’ being bright white and so on. For compatibility with old NewLeaf code, short (case-sensitive) colour abbreviations are also allowed.


NewLeaf for Dyalog12: leaf.Decimal – set decimal separator

leaf.Decimal – set decimal separator

This allows the user to set an explicit decimal separator for column alignment in tables. It defaults to the character specified in the Regional Settings tab of Windows.

leaf.Decimal ','  ⍝ European usage

The separator is reset to the Windows default by leaf.Init, so must always be explicitly over-ridden.


NewLeaf for Dyalog12: Emphasis – add extra font decorations

Emphasis – add extra font decorations

Newleaf supports various ‘extra’ formatting which is applied to the existing font definition. This currently includes bold, italic, underline and strikethrough. To underline an entire paragraph (you might want to include this in a subhead style):

leaf.Emphasis 'underline'
leaf.Place 'Subheading'
leaf.Set 'emph' ''
'Title' leaf.DefineStyle ('fon' 'tii,24')('al' 'ce')

    ('sp' 18 12)('pagebr' 1)
'Subhead' leaf.DefineStyle ('fon' 'heb,14')('space' 6 3)

    ('emph' 'underline')
'subhead' leaf.Place 'Section 4.3'

If you prefer, you can pass the emphasis as a numeric code, being the sum of:

  • 1=bold
  • 2=italic
  • 4=underline
  • 8=strikethrough

The underlined option also works as an HTML tag in the same way as bold and italic:

leaf.Flow 'Here is <u>underlined</u> text'.

Strikethrough is not well supported by HTML, and will not be included in the set of supported tags.


NewLeaf for Dyalog12: leaf.Font – set current font (face and pitch)

leaf.Font – set current font (face and pitch)

Current font definition for paragraph text. Expressed as a short code (which refers to leaf.∆fonttbl), the required size in points, and the interline spacing (defaults to 120% of the font size).

leaf.Font 'tib,14/18'

ti,12/18 ... is 12point Times-Roman at 1.5 line spacing
tii,24 ... is 24point Times-Roman Italic (default spacing)
heb,14 ... is 14point Helvetica bold (mapped to Arial bold)
hebi,18 ... is 18point Helvetica bold italic (mapped to Arial)

These abbreviations are all defined in a text matrix called leaf.∆fonttbl, which you may modify as required to add new fonts, or change the abbreviations of those already defined. Note that any changes you make in this way will be lost next time you install a NewLeaf upgrade. Use leaf.DefineFont to make temporary or permanent changes to this table.

You can also use TrueType fonts directly (see leaf.TrueFont), but note that any fonts so defined will not be available if you use the Direct PostScript capability, and are very likely not to work in reports output to HTML where your favourite fonts are probably not present.


NewLeaf for Dyalog12: leaf.Indent – set paragraph indents

leaf.Indent – set paragraph indents

Current indent settings (3-element vector) for:

left margin (from edge of frame)
right margin (from edge of frame)
first line (may be negative)

All values are in points.

leaf.Indent 36 36  ⍝ 1/2" each side


NewLeaf for Dyalog12: leaf.Keep – widow/orphan control

leaf.Keep – widow/orphan control

Number of lines which must be kept together at the start or end of a paragraph. If there are insufficient free lines in the current frame to start the paragraph, NewLeaf will skip to the next frame. If the split would leave fewer lines than this value at the top of the new frame, NewLeaf moves the breakpoint forward until enough lines come beyond it.

If it is impossible to satisfy both conditions (there may not be enough lines in the paragraph) the split will occur approximately 2/3 of the way down, i.e. the majority of the paragraph will be placed at the foot of the previous page.

leaf.Keep 6  ⍝ At least 6 lines

The default setting is to skip if fewer than 2 lines are free.


NewLeaf for Dyalog12: leaf.MinAfter – minimum space after

leaf.MinAfter – minimum space after

The space (in points) that must be free in the frame after this paragraph has been placed. Use this for subheadings as a simple way of ensuring that the subhead does not get detached from the following paragraph. Ensure that the Keep value of the following paragraph is less than the number of lines requested by MinAfter.

leaf.MinAfter 72  ⍝ At least an inch reqd

If sufficient space is not available the paragraph will begin a new frame. The default value is 0.


NewLeaf for Dyalog12: leaf.PageBreak – set page break before

leaf.PageBreak – set page break before

If this property is set on a paragraph, NewLeaf will always start a new page before writing the text.

leaf.PageBreak 1

This would normally be part of a major heading style, so that:

'heading' leaf.Place 'Chapter Five'

... would always start on a new page.


NewLeaf for Dyalog12: leaf.Pitch – set line spacing within paragraph

leaf.Pitch – set line spacing within paragraph

Over-rides the default pitch in the font setting. Necessary for Arial if this is used in body text, as this really needs at least 1.5×size to look good.

A simple numeric scalar gives the interline spacing in points:

leaf.Pitch 18
leaf.Set 'Pitch' 18


NewLeaf for Dyalog12: leaf.Size – set font size for paragraph

leaf.Size – set font size for paragraph

Over-rides the default face size in the font setting.

A simple numeric scalar gives the size in points:

leaf.Size 13.5

This can be used in a style to change size, regardless of the current face, for example:

'small' leaf.DefineStyle 'size' 11.5

... will retain all other settings, but will reduce the size.

Any number is valid here – NewLeaf is not restricted to half-point increments (as many Microsoft tools are).


NewLeaf for Dyalog12: leaf.SoftHyphen – set soft hyphen character

leaf.SoftHyphen – set soft hyphen character

Text wrap occurs when you call any of the following:

leaf.Flow – to wrap paragraph text
leaf.table.Spread – to place text into table cells

... and also when table headings are fitted into given column widths.

By default, NewLeaf uses the tilde character ‘~’ as an optional word-break point, so that a table heading such as ‘Con~trib~ution’ may appear as:

Con-
tribution

or as

Contrib-
ution

or as

Contribution

... depending on the available column widths. If you require the ‘~’ character as normal text, you could do your own wrapping and use leaf.Place (which ignores it) or you could switch to a different soft hyphen with:

leaf.SoftHyphen '⌹'


NewLeaf for Dyalog12: leaf.Spacing – set paragraph spacing

leaf.Spacing – set paragraph spacing

Space before/after paragraphs in points.

leaf.Spacing 6 6  ⍝ Half a line each side

Default value 0/12. If you give a single number it is used for the space before, and the space after is set to zero.


NewLeaf for Dyalog12: leaf.Tabrack – set up tabstops

leaf.Tabrack – set up tabstops

Tabs default to every 1”, and can be set in points using the tabrack property:

leaf.Tabrack 96 ¯200 220
leaf.Set 'tabrack' 144  ¯600

Negative tabs are right-aligned, centred and decimal tabs are not supported. To skip to the next tab, embed ⎕AV[10] or the string <tab> in the input to leaf.Flow. Note that leaf.Place does not process HTML tags, so does not notice tabs. All tabs are relative to the left edge of the current frame and disregard indents.

If you set tabstops beyond the right edge of the frame, no check is made on the positioning, and your text will appear outside the frame.


NewLeaf for Dyalog12: leaf.Titlebar – title view PDF and HTML output

leaf.Titlebar – title view PDF and HTML output

You can set the ‘title’ of your NewLeaf document with an initial call to this function:

leaf.Titlebar 'Sample Page from NewLeaf'

This should be the first function you call after leaf.Init, as the title will be written into the page by leaf.Use. It will be shown by the in-built viewer and will form the browser titlebar of an output HTML page. It is also used to title the document in reports saved to PDF format, and will caption the window of any EPS files imported into MS Word as pictures.


NewLeaf for Dyalog12: leaf.TOC – set Table-of-Contents level

leaf.TOC – set Table-of-Contents level

This property can be applied to a paragraph to cause it to make an automatic entry in the bookmarks table (using the paragraph text as the bookmark entry). This would most commonly be used in a style definition such as:

 'H1'leaf.DefineStyle('font' 'arb,18')('pa' 1)('toc' 1 1)
 'H2'leaf.DefineStyle('font' 'arb,15')('sp' 12 6)('toc' 2 0)
 'H3'leaf.DefineStyle('font' 'tib,12')('sp' 6 0)('toc' 3 0)

This will create a complete contents tree for the document from the various headings as they occur. This will be used by Acrobat Distiller or the built-in PDF generation to create an outline tree for the document.

See also ...

leaf.Bookmark – mark TOC entry | leaf.Style – set paragraph style

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.TrueFont – using TrueType fonts directly

leaf.TrueFont – using TrueType fonts directly

In general, NewLeaf expects you to work with a table of font short codes and definitions. This allows your reports to be output directly to PostScript devices (or Acrobat Distiller) and will enable reports to be rendered well on HTML browsers.

However if you allow users to pick arbitrary fonts from those available on their Windows installation, you will need to use this function in place of leaf.Font to choose the font definition.

The simple syntax is:

leaf.TrueFont 'Verdana,18/24'  ⍝ 18pt on 24pt spacing

which is just the same as for leaf.Font. In addition, you can choose italic and/or bold variants with the syntax:

leaf.TrueFont 'comic sans,14' 1       ⍝ Italic
leaf.TrueFont 'book antiqua,18' 0 800 ⍝ bold

The names you give are matched against the current list of installed fonts, case-independent omitting blanks. Only the leading part of the name is used, so ‘comic’, ‘comic sans’ and ‘comic sans ms’ all match ‘Comic Sans MS’ which is the actual name of the Windows font.

The codes for font weight are 400 (normal) and any number above 400 (typically 800) for bold. These are the same numbers as are used in the APL ‘Font’ object.


NewLeaf for Dyalog12: leaf.table.Align – set cell alignment in tables

leaf.table.Align – set cell alignment in tables

Table cells may be ‘Left’, ‘Centre’, ‘Right’ or ‘Decimal’ aligned. This gives a vector of alignments, with one value for each column. If required it will be reshaped to match the number of columns. Note that alignment by individual cell is supported by leaf.table.List, but leaf.table.Spread aligns by column only.

leaf.table.Align 'left' 'centre' 'dec2' 'dec1'

Note that you must give the expected number of places after the decimal point with the ‘decimal’ alignment. If any numbers in the column have more places than you give, they will overflow to the right. There is adequate space for a closing parenthesis after the final digit, so ‘decimal2’ is fine for ‘(23.45)’. You can use leaf.Decimal to over-ride the default separator character.

Tip: to get correct alignment on integer data with parenthesised negatives, use ∆decimal0∇ alignment which will leave sufficient space after the last digit to exdent the closing parenthesis.

Only the initial letters of the alignments are required, but be sure to pass these as a vector of vectors, not as a single word:

leaf.table.Align ,¨3 7⍴'crcl'
leaf.table.List 3 7⍴⍳99

This will make a pattern of cell alignments, centre, right, centre, left ... and so on.


NewLeaf for Dyalog12: leaf.table.BCol – set cell background colours

leaf.table.BCol – set cell background colours

Both List and Spread will accept an array of cell background colours. This should either be a vector with the same number of elements as the number of columns in the data, or a matrix which has the same shape as the data array.

leaf.table.BCol'red' 4 '#BB7B27'       ⍝ Orange

You can give the colours as short mnemonics (these are case sensitive), as indices into the standard 16-colour palette (0=black), or as hex strings.


NewLeaf for Dyalog12: leaf.table.Borders

leaf.table.Borders

Define cell borders within table.

leaf.table.Borders 5 4⍴20↑0 0 0 0,0 0 0 0,0 1111 0 0

Argument gives borders LRBT in points as an integer matrix. For example 2040 is l=2 b=4 points (maximum line width 9 pt). This will be reshaped to match the shape of your data. The example will box the second column of rows 3, 8 and so on with a 1-point line all around. The box is drawn entirely inside the cell, so if you box 2 adjacent cells the line on the boundary will appear twice as heavy as the line-weight you give. A likely value is 10 which could be used to underline totals in an otherwise plain grid.

A likely future extension is to treat this as an index to a 9-element vector of line widths (default setting 1-9) so that border weights may be completely customised. Currently the border style is always ‘solid’ and the colour is black.

Note that heavy use of this capability will greatly add to rendering times both in print-preview and on paper. Use gridlines and rules where possible.


NewLeaf for Dyalog12: leaf.table.Caption – set table caption

leaf.table.Caption – set table caption

The table caption is written just above the top left corner of the table, and is repeated on every part-page if the table spans more than one page wide. Typically it would be used as a page-label for any higher dimensions where the report was paging through data such as sales by country by product:

:for ct :in ⍳⍴prodname
  leaf.table.Caption prodname[ct]
  leaf.table.List prodsales[ct;;]
:endfor

If you pass a vector of captions they are stacked vertically above the table. You can change the caption font with CFont and the colour with CColour. Captions are always left-aligned at the head of the table.

See also table heading, subhead and footnote for other ways of adding text elements to tables.


NewLeaf for Dyalog12: leaf.table.CFont – set the caption font

leaf.table.CFont – set the caption font

The table caption is set by default in 13-point TimesBold. To reset this:

leaf.table.CFont 'arb,12'      ⍝ or ...
leaf.table.Set 'cfont' 'arb,12'

This gives Arial Bold, 12-point.


NewLeaf for Dyalog12: leaf.table.CColour – set caption colour

leaf.table.CColour – set caption colour

To set the colour of the table captions (default black):

leaf.table.CColour 'blue'  ⍝ or
leaf.table.Set 'ccolour' 4

You can use the standard colour mnemonics, numeric values (0-15) or internet-style hex strings of the form ‘#rrggbb’ here.


NewLeaf for Dyalog12: leaf.table.CellWidths – set cell widths

leaf.table.CellWidths – set cell widths

Width of each cell in points. May be given as ¯32768 (-2*15) which measures the column at runtime to fit the given data; the width is limited by the MaxCell property. Any unspecified widths (or columns given as -ve 1) will share the remaining space in the frame after all specified columns have been placed.

leaf.table.CellWidths ¯1 72 144

This example sets 2 columns explicitly and leaves the first column to take all the slack.

If you prefer, you can use -ve numbers throughout to allocate the frame width in proportion:

leaf.table.CellWidths ¯3 ¯1 ¯1 ¯2

... which will use the available space in the ratio 3:1:1:2. You can mix the settings as required to give some columns absolute widths and let others share the remaining space. Note that NewLeaf currently sets a minimum cell width of 24pt for columns which it calculates, so it is possible that not all your columns will fit into the frame if you use the automatic allocation. If this happens, you can use leaf.table.MinCell to over-ride this default.


NewLeaf for Dyalog12: leaf.table.Clip – set cell clipping

leaf.table.Clip – set cell clipping

The default for leaf.table.List is to allow overflow at the cell boundary. You can use leaf.table.Spread to allow wrapping within cell, or clip selected columns at the cell boundary:

leaf.table.Clip 0 1 0 0 0  ⍝ Clip 2nd column only

The available options are:

0=default (spill in List, wrap in Spread)
1=clip at cell boundary (implemented in Spread as well as List from release 1.6)
2=spill into next column always (over-ride Spread default)
3=wrap text and extend cell vertically (=Spread default, not used in List)

Clipping adds significant processing time to report production, so only use it when you need to.


NewLeaf for Dyalog12: leaf.table.TColour – set text colour for titles

leaf.table.TColour – set text colour for titles

Sets the text colour for the column titles using the standard HTML colour names or the ‘#FF’ syntax:

leaf.table.TColour 'Green'

All the titles will be given a single colour – you cannot pass a vector of colours here.


NewLeaf for Dyalog12: leaf.table.TBCol – set the background colour for column titles

leaf.table.TBCol – set the background colour for column titles

Sets the background colour for the column titles using the standard HTML colour names or the ‘#FF’ syntax:

leaf.table.TBCol'#064606'  ⍝ Titles orange on green

All the title cells will be given a single background colour – you cannot pass a vector of colours here.


NewLeaf for Dyalog12: leaf.table.Emphasis - set character formatting

leaf.table.Emphasis – set character formatting

Extra character formatting may be set by column (in List) or by cell (in Spread) using this property. Normally you would compute this from the data matrix and so it is easy to pass the required emphasis as a simple numeric matrix, each value being the sum of:

  • 1=bold
  • 2=italic
  • 4=underline
  • 8=strikethrough
bold←mat<0  ⍝ Bolded negatives
leaf.table.Emphasis bold

If you pass a simple vector, it is reshaped across the columns. In this case you might prefer to use character codes to set the emphasis of each column:

leaf.table.Emphasis '' '' '' 'bold'

This example will embolden every 4th column in the table. Note that you can pass the emphasis property in the optional left argument to both List and Spread, in which case it only applies to that particular table.

See also ...

leaf.table.List – simple column-based reports | leaf.table.Spread – spread matrix into a table

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: leaf.table.Fillchar – set fill character

leaf.table.Fillchar – set fill character

It is sometimes helpful to fill a cell from the last character to the cell boundary. This can be used to provide ‘dot leaders’ in tables of contents or to make it easy to follow across the lines in a wide table. You can provide a vector of fill characters which will be used in turn for each column in the table.

leaf.table.Fillchar '*'
leaf.table.Set ('grid' 0)('align' 'le' 'ri')('fillchar' '.')
leaf.table.List TOC
Chapter 1 ........... 2
Next Section ........ 3
Summary ............ 99

This provides a simple way to format a table of contents with dot leaders.


NewLeaf for Dyalog12: leaf.table.Fit – set 'fit to page' parameters

leaf.table.Fit – set ‘fit to page’ parameters

Tables formatted with leaf.table.Spread may be constrained to fit entirely on a single page, or to occupy no more than n pages wide.

Valid combinations are:

  • {any scalar = fitted across,open-ended downwards}
  • 1 1 = all on 1 page (uniform scaling)
leaf.table.Fit 1 1  ⍝ Use only one page
leaf.table.Fit 1    ⍝ No more than one page wide
leaf.table.Fit 6    ⍝ No more than 6 pages wide

The constraints of fixed rows (headings) and fixed arbitrary columns (set with Keystyle 11) make the combination of n×m very hard to compute! Shelved for the moment as the above provide the 90% solution!

No attempt is made to balance the columns of a wide table across pages, so you may arrive at a situation where the final (rightmost) page has only a single column.If you fix too many (wide) columns so that there is no space in the frame for any unfixed columns, NewLeaf will progressively unfix them until there is room for at least one unfixed column.


NewLeaf for Dyalog12: leaf.table.Font – set table fonts

leaf.table.Font – set table fonts

A vector of font specifications for each column or cell of the table.

leaf.table.Font 'ti,12' 'tib,14' 'tii,12'

will be Times-12, TimesBold-14 and Times-Italic 12.

These will be reshaped as required to cover the number of columns in the table (for leaf.table.List) or to match the shape of the data (for leaf.table.Spread).


NewLeaf for Dyalog12: leaf.table.Footnote – set table footer

leaf.table.Footnote – set table footer

You can add a footnote to your table with:

leaf.table.Footnote 'Footer Text'

The footnote only appears at the very end of the table, if it spans several pages either horizontally or vertically. By default, the footnote is left-aligned, but this may be changed using the footnote style. You may also change the font and colour.

You can specify linebreaks in the footer by including the semi-colon character in the text or by passing a nested vector:

leaf.table.Footnote 'This is Line-1;This is the Second line'
leaf.table.Footnote 'Printed on DD/MM/YY' 'by User nnn'

See also table caption, heading and subhead for other ways of adding text elements to tables.


NewLeaf for Dyalog12: leaf.table.FFont – set footnote font

leaf.table.FFont – set footnote font

The table footer is set by default in 8-point Arial (non-bold). To reset this:

leaf.table.FFont 'ti,10'      ⍝ or ...
leaf.table.Set 'ffont' 'ti,10'

See also: setting the heading and subhead fonts.


NewLeaf for Dyalog12: leaf.table.FColour – set footnote colour

leaf.table.FColour – set footnote colour

To set the colour of the table footnote (default black):

leaf.table.FColour 'green'  ⍝ or
leaf.table.Set fcolour' 3

You can use the standard colour mnemonics, numeric values (0-15) or internet-style hex strings of the form ‘#rrggbb’ here.


NewLeaf for Dyalog12: leaf.table.FStyle – set footnote style

leaf.table.FStyle – set footnote style

Table footnotes are left-aligned by default. This may be changed by setting the footnote style:

leaf.table.FStyle 'right'

The keywords ‘left’ ‘centre’ ‘center’ ‘right’ are recognised here.


NewLeaf for Dyalog12: leaf.table.Grid – set gridline weights

leaf.table.Grid – set gridline weights

Weight (in points) of:

  • grid border
  • vertical lines (may be a vector)
  • horizontal separators (may be a vector)

The default is 1 0.8 0.01.

To frame the entire table, with no other gridlines:

leaf.table.Gridlines 1 0 0

To rule vertically after alternate columns with hairline separators between cells (use 0.001 to ensure you get the thinnest line your printer can draw):

leaf.table.Gridlines 1 (0 0.5) .001

To rule horizontally after every 5 rows of data:

leaf.table.Gridlines 1 .5 (0 0 0 0 1)

See also ...

leaf.table.Rounding


NewLeaf for Dyalog12: leaf.table.GridColour

leaf.table.GridColour

This property controls the colours of the table border, the vertical and horizontal gridlines.

leaf.table.GridColour 0 5 0

It takes a 3-element vector of colour numbers – each element is an integer scalar.

See also ...

Colour Table


NewLeaf for Dyalog12: leaf.table.GridStyle

leaf.table.GridStyle

This property controls the linestyles of the table border, the vertical and horizontal gridlines.

leaf.table.GridStyle 1 1 2

It takes a 3-element vector of line styles – each element is an integer scalar. Currently, only the second and third elements are used – the grid border is always drawn with a solid line.

The styles are:

  • 0 = solid (the default)
  • 1 = dashed
  • 2 = dotted

The repeat pattern is scaled with the line weight (for lines above 1pt).


NewLeaf for Dyalog12: leaf.table.Heading – set table heading

leaf.table.Heading – set table heading

You can add a main heading to your table with:

leaf.table.Heading 'Heading Text'  ⍝ or
leaf.table.Set 'head' 'My Heading'

The heading only appears on the first page of the table, if it spans several pages either horizontally or vertically. By default, the heading is centred, but this may be changed using the heading style. You may also change the font and colour of the heading. You can specify linebreaks in the heading by including the semi-colon character in the heading text or by passing a nested vector:

leaf.table.Heading 'This is Line-1;This is the Second line'
leaf.table.Heading 'Here is' 'my Heading'

See also table caption, subhead and footnote for other ways of adding text elements to tables.


NewLeaf for Dyalog12: leaf.table.HFont – set font for heading

leaf.table.HFont – set font for heading

The table heading is set by default in 20-point Times (non-bold). To reset this:

leaf.table.HFont 'arb,14'      ⍝ or ...
leaf.table.Set 'hfont' 'arb,14'

See also: setting the subhead and footnote fonts.


NewLeaf for Dyalog12: leaf.table.HColour – set heading colour

leaf.table.HColour – set heading colour

To set the colour of the table heading (default black):

leaf.table.HColour 'red'  ⍝ or
leaf.table.Set 'hcolour' 'red'

You can use the standard colour mnemonics, numeric values (0-15) or internet-style hex strings of the form ‘#rrggbb’ here.


NewLeaf for Dyalog12: leaf.table.HStyle – set table header style

leaf.table.HStyle – set table header style

Table headers and subheads are centred by default. This may be changed by setting the heading style:

leaf.table.HStyle 'right'

The keywords ‘left’ ‘centre’ ‘center’ ‘right’ are recognised here. Other options may be added in a future release.


NewLeaf for Dyalog12: leaf.table.Indent – set table indents

leaf.table.Indent – set table indents

A common use of tables is to present information like budgets or sales summaries where the leftmost column is a tree-structure of organisational units. You can manage the indenting manually by inserting leading blanks, but if the text is forced to wrap into a narrow column, the indenting structure is obscured. A better strategy is to set the indent level for the table and have NewLeaf wrap the text correctly for each entry.

leaf.table.Indent orglevel
leaf.table.Spread salesmat

Typically this would be a depth-vector (0,1,2 ...) of indent levels for the first column. If you pass a vector it is reshaped to the number of ROWS in the table and taken to apply to column-1 only. If you pass a matrix, it applies on a cell-by-cell basis and should match the shape of your data. The actual degree of indent applied is computed from the indent level and font – you cannot currently control this. More than one column may be indented, but the indent structure should generally match across columns. Note that you can also pass the indenting as an element in the optional left argument to Spread:

('ind' depth) leaf.table.Spread budget

When the table crosses a page boundary, it is likely that the first row on the new page will not be a level-zero item. In this case a note is written above the table in the Caption font to indicate the continuation e.g. “Europe,UK ... continued”. This shows the ancestor levels of the item on the first row back to level-0. If more than one column has indents, the ancestors are taken from the leftmost. Indented columns may be repeated across wide reports in the normal way with KeyStyle 1.

See also ...

leaf.table.Spread – spread matrix into a table


NewLeaf for Dyalog12: leaf.table.KeyStyle – set column key style

leaf.table.KeyStyle – set column key style

Set key column options for use in horizontally folded reports, or to tidy repeated rows in tabular data. This is useful when you have several columns which act as the key to the data values (such as Product Id and Month) with repeated values in the outer column. You can blank out the repeating elements, rule across the table when the value changes (e.g. between Products), as well as ensuring that all the key columns are printed at the left of every page of a multi-page report.

  • 0 is normal behaviour
  • 1 is ‘retain on each page’ when report is folded horizontally
  • 2 is ‘merge repeated rows’ in this column
  • 4 is ‘add more space before change’ in this column
  • 8 is ‘space and rule before change’
  • (16 could be ‘pagebreak before change’ – reserved for future extension)
  • 32 is ‘column break after me’ signal for wrapping across pages
  • (64 is reserved for non-printing columns – future extension)

Simply add the numbers to set any combination of styles:

cbr←0 0 0 0 0 0 0 32 0 0 0 0 0 32
leaf.table.KeyStyle cbr+(⍴cbr)↑11 11

See the sample function Folder (in the NewLeaf workspace) for some examples.

Note that as from release 1.6 the ‘merge cells’ switch is supported in Spread as well as List. It compresses out vertical space in the situation where several adjacent columns have wrapped text in merged cells – the tallest cell group sets the row height.


NewLeaf for Dyalog12: leaf.table.MaxCell – set maximum limit for measured widths

leaf.table.MaxCell – set maximum limit for measured widths

The default maximum cell width in tables is the frame width. If you want to use automatically measured cells with a smaller upper limit, you can reset this with:

leaf.table.MaxCell 360  ⍝ 5" max columns

You may give a single value or a vector of values here. The vector will be reshaped to match the number of columns in your table. Use ¯1 as a marker for default values.


NewLeaf for Dyalog12: leaf.table.Merge – set title cell merging

leaf.table.Merge – set title cell merging

When a table has tree-structured titles, you may want to omit the horizontal rule between vertically adjacent cells if the cells match in width. To have these unwanted rules omitted:

leaf.table.Merge 1

The default is 0, so that rules get drawn unless both the vertically adjacent cells are completely blank, in which case the rule is always omitted.


NewLeaf for Dyalog12: leaf.table.MinCell – set minimum cell width

leaf.table.MinCell – set minimum cell width

The default minimum cell width in tables is 24pt (1/3 of an inch). If you want to use the automatic cell allocation with a different value, you can reset this with:

leaf.table.MinCell 72  ⍝ Min 1"

You may give a single value or a vector of values here. The vector will be reshaped to match the number of columns in your table. Use ¯1 as a marker for default values.


NewLeaf for Dyalog12: leaf.table.Offset – set grid offset

leaf.table.Offset – set grid offset

Normally the entire table is boxed, and gridlines start at the left boundary and enclose the entire grid. To leave the first column outside the box:

leaf.table.Offset 1

Note that it will still have the heading above – insert a null title element if you want the titles to start at column-2 also.

You can also choose to start drawing the horizontal gridlines from a given column – this is set with the second element, for example:

leaf.table.Offset 0 2

This is often useful with merged cells, as you do not want to draw the grid through these.

See also ...

leaf.table.KeyStyle – set column key style


NewLeaf for Dyalog12: leaf.table.Pitch – table text pitch in wrapped cells

leaf.table.Pitch – table text pitch in wrapped cells

Interline spacing for each table cell. This defaults to 120% of the font size.

leaf.table.Pitch 18

Note that this has no effect in leaf.table.List, as this does not wrap the text within a cell. To set the vertical cell spacing, use leaf.table.Spacing here.


NewLeaf for Dyalog12: leaf.table.Qfmt – set format specifications

leaf.table.Qfmt – set format specifications

By default, leaf.table.Spread will simply apply the APL monadic format to any numeric data. You may override this cell by cell with a format specification to be used as the left argument of ⎕FMT. Note that no checking or error trapping is done, so invalid specifications will cause APL errors in Spread or List.

leaf.table.Qfmt 'I2' 'CF8.2'

The vector of format specifications will be reshaped to match the data.

Tip: to get correct alignment on integer data with parenthesised negatives, use ∆decimal0∇ alignment which will leave sufficient space after the last digit to exdent the closing parenthesis.


NewLeaf for Dyalog12: leaf.table.Rounding

leaf.table.Rounding

This property controls the corner-rounding of the outer frame of the table.

  leaf.table.Rounding 4

This will round the corners with a radius of 4pts in both the x and y directions.

See also ...

leaf.table.Grid – set gridline weights


NewLeaf for Dyalog12: leaf.table.RowHeights – set 'at least' heights

leaf.table.RowHeights – set ‘at least’ heights

This sets user-defined heights for each row in the table (implemented in Spread only for now).

leaf.table.RowHeights 0 144 0

Argument gives minimum height in points (like Word ‘At least’ setting). Extra height over and above this is vertically distributed within the cell depending on vertical alignment, default ‘Top’. The example sets the second, fifth etc. rows to at least 2” tall. Other rows retain their calculated height.


NewLeaf for Dyalog12: leaf.table.Shade – set cell shading

leaf.table.Shade – set cell shading

Sets the cell shading as a vector/matrix of pattern indices (0–15):

leaf.table.Shade 0 0 2 0

The shadings are reshaped to match the cells. Values are from 0 (unshaded) to 7 (90% grey). Various other patterns are available using numbers from 9 to 15 (which is solid black). See Patterns in the RainPro workspace for some examples. In general, values above 3 should only be used if you also set the text colour to white.

Cell shading is supported by both Spread and List.


NewLeaf for Dyalog12: leaf.table.Spacing – set table spacing

leaf.table.Spacing – set table spacing

Space before/after cell text in points. This is best set to similar values for before and after – approximately 1/4 the font size each side.

leaf.table.Spacing 5 5  ⍝ Suitable for 18pt text

Default value 3/3.


NewLeaf for Dyalog12: leaf.table.Subhead – set second-level heading

leaf.table.Subhead – set second-level heading

You can add a subsidiary heading to your table with:

leaf.table.Subhead 'Subhead Text'   ⍝ or
leaf.table.Set 'subhead' text

The subhead only appears on the first page of the table, if it spans several pages either horizontally or vertically. It always has the same alignment as the main heading (set with HStyle) but you may independently change the subhead font and colour.

You can specify linebreaks in the subhead by including the semi-colon character in the text or by passing a nested vector:

leaf.table.Subhead 'This is Line-1;This is the Second line'
leaf.table.Subhead 'Printed on 21/3/1953' 'by Adrian'

See also table caption, heading and footnote for other ways of adding text elements to tables.


NewLeaf for Dyalog12: leaf.table.SFont – set the subhead font

leaf.table.SFont – set the subhead font

The table subheading is set by default in 16-point Times Italic (non-bold). To reset this:

leaf.table.SFont 'ari,13'      ⍝ or ...
leaf.table.Set 'sfont' 'ari,13'

See also: setting the heading and footnote fonts.


NewLeaf for Dyalog12: leaf.table.SColour – set subhead colour

leaf.table.SColour – set subhead colour

To set the colour of the table subheading (default black):

leaf.table.SColour 'blue'  ⍝ or
leaf.table.Set 'scolour' '#00F0F0'

You can use the standard colour mnemonics, numeric values (0-15) or internet-style hex strings of the form ‘#rrggbb’ here.


NewLeaf for Dyalog12: leaf.table.TAlign – set title alignment

leaf.table.TAlign – set title alignment

Column titles are centred by default – to allow alignment set the TAlign property to match the number of title cells.

leaf.table.TAlign 'left' 'right'

Note that this will be reshaped to match the number of titles, which may be more than the number of columns if you use tree-structured headings.


NewLeaf for Dyalog12: leaf.table.TDepth – tree-structured titles

leaf.table.TDepth – tree-structured titles

This table property is used to set multi-level headings as a tree structure. For example:

  ┌─────────────────────────────────────────────────┐
  │            Salaries Report 1996                 │
  ├─────────────────────────────┬────────┬──────────┤
  │ Name                        │    Age │   Salary │
  ├─────────────────────────────┼────────┼──────────┤
  │ Adrian Smith                │     42 │    5,678 │
  │ And so on                   │     21 │  123,000 │
  └─────────────────────────────┴────────┴──────────┘

Here you can see a major heading (level 0) with 2 level-1 headings below it, of which the second ‘Details’ in turn has two level-2 children.

To set up this structure in NewLeaf, you must specify all 5 headings, and the appropriate heading depth for each (of course the default case is to have all headings at level 0):

leaf.table.Titles 'Report' 'Emp' 'Details' 'Age' 'Salary'
leaf.table.TDepth  0        1     1         2     2

Note that you should have the same number of ‘leaves’ in the tree as you have columns in the table.


NewLeaf for Dyalog12: leaf.table.TFont – set table title font

leaf.table.TFont – set table title font

NewLeaf has a single font specification for the titles used in a table:

leaf.table.TFont 'heb,14'

All the titles will be set in 14pt Helvetica Bold. The default is 13pt Helvetica Bold.


NewLeaf for Dyalog12: leaf.table.Titles – set table column titles

leaf.table.Titles – set table column titles

Defines the column titles for a table.

leaf.table.Titles 'One' 'Two'

To generate multi-line titles, pass an enclosed vector:

leaf.table.Titles 'First' ('One' 'Two')

You can use leaf.table.TDepth to define these in a tree structure. Also you may pass a multi-row matrix with repeated elements in the upper rows. These will be merged automatically to create a tree structure.


NewLeaf for Dyalog12: leaf.table.Valign – set vertical cell alignment

leaf.table.Valign – set vertical cell alignment

Table cells may be ‘Top’, ‘Centre’ or ‘Bottom’ aligned – the default is always ‘Top’. This property gives a vector of alignments, with one value for each column. If required it will be reshaped to match the number of columns.

leaf.table.Valign 'top' 'centre'

Note that this property is only used by leaf.table.Spread as leaf.table.List never writes more than one line of data in each cell. You can abbreviate the settings to a single letter, but be sure to pass this argument as a vector of vectors:

leaf.table.Valign ,¨'cbctcbc'
leaf.table.Spread 3 7⍴(3 4⍴'fat cat') 'sat'

Vertical alignment can only be set for entire columns.


NewLeaf for Dyalog12: Customising NewLeaf

Customising NewLeaf

Some things you can change in the way NewLeaf handles fonts and other options.

Cust_guide | Customisation Guidelines
Cust_init | Structuring an Initialisation Routine
Cust_paper | Adding Extra Paper Sizes
Cust_fonts | Adding Extra Fonts
Cust_styles | Defining Paragraph Styles
Cust_props | Setting New Defaults
Cust_save | Saving a Reports on File
Cust_tran | Translating the Viewer Text


NewLeaf for Dyalog12: Customisation Guidelines

Customisation Guidelines

NewLeaf comes with default settings that allow you to create documents immediately. These settings, however, are not necessarily ideal for everyone. As NewLeaf is supplied in the form of an APL workspace, it is a relatively easy matter to create, modify and delete objects within it, that is, to customise it to suit your own or your users∇ requirements. This approach is discouraged, as it may result in unforeseen problems when upgrading to a future version of NewLeaf. While Causeway Graphical Systems will make every reasonable effort to ensure that subsequent releases are upwards compatible functionally, it is impossible to offer similar assurances about the implementation. It is reasonable to expect that the enhancement of existing functionality and the addition of new features will, at some point, necessitate changes to functions and to the structure and content of variables.

In the light of these warnings, this chapter provides information and guidelines for customising NewLeaf. The approach can be summarised as follows:

  • Make a backup copy of the NewLeaf workspace and put it somewhere safe.
  • Do not alter any of the NewLeaf source code or the structure of any NewLeaf variables. Use existing customising routines where available, rather than altering variables directly.
  • Keep the code that customises NewLeaf in a single function if possible. Write an initialisation routine that executes leaf.Init , then use leaf.Set or leaf.table.Set to change the property values.
  • Do not assume that properties persist after leaf.Close or leaf.Spool executes to complete a document.
  • Always use leaf.Set and leaf.table.Set to set the values of properties, leaf.Query and leaf.table.Query to find out their current values.

Make a note of any changes and put it somewhere handy for reference.


NewLeaf for Dyalog12: Structuring an Initialisation Routine

Structuring an Initialisation Routine

The aim of writing a custom initialisation routine is to gather together in one place as many of the non-standard text and table property settings as possible, especially where these are the same for several different reports in an application. In most cases, it will also be necessary to fine-tune some of these for individual reports. Assuming that the required objects are in the workspace, one possible framework for a report module could look like this:

  1. General initialisation, including the custom NewLeaf initialisation routine described below.
  2. Report-specific initialisation, including any special NewLeaf property values for this report.
  3. Start the report with leaf.Use and the page layout(s) for this report.
  4. Run the report (leaf.Flow, leaf.Place, leaf.table.List, leaf.table.Spread ...).
  5. Stop the report (leaf.Close or leaf.Spool).
  6. Tidy-up and exit.

The customised NewLeaf initialisation procedure allows you to accommodate “house” styles, such as non-standard paper sizes or a requirement that all reports be printed in 10-point Times or Helvetica. This function also has a simple structure:

  1. Run leaf.Init to set default properties and create working copies of variables.
  2. Add information about custom papers to leaf.∆papers.
  3. Run leaf.DefineFont to add custom font mappings.
  4. Run leaf.DefineStyle to add custom text styles.
  5. Run leaf.Set ... to set the default values for text properties such as font, indents, etc.
  6. Run leaf.table.Set ... to set the default values for table or column header properties such as font, alignment, etc.


NewLeaf for Dyalog12: Adding Extra Paper Sizes

Adding Extra Paper Sizes

NewLeaf stores information for several standard paper sizes in the three-column nested matrix leaf.∆papers:

     leaf.∆papers[1 8 9;]
1 US Letter 612 792
8 A3 842 1191
9 A4 595 842

There is one row for each paper size. The columns contain:

  1. An integer scalar, the unique numeric identifier.
  2. A mixed-case text vector, the unique name of the paper (e.g., ∆A4∇, ∆US Letter∇).
  3. A two-element numeric vector, the width and height, respectively, of the paper in points (72 points = 1 inch).

The optional pg type object in a NewLeaf page layout can contain values for the paper and orientation properties of the document. When the paper property is specified explicitly, NewLeaf looks in the second column of leaf.∆papers to find a matching name. The values in column three of the corresponding row are then used as the paper size. If there is no match, or if no explicit value is given for the paper property, NewLeaf uses the paper size associated with the current printer. To include a new paper size, run leaf.DefinePaper giving a unique name, and the width and height:

leaf.DefinePaper 'Causeway' (72×7 11)

This adds the new data (width and height in points) to the bottom of this matrix. Remember to re-apply any changes whenever you upgrade NewLeaf.


NewLeaf for Dyalog12: Adding Extra Fonts

Adding Extra Fonts

NewLeaf maintains a table, leaf.∆fonts, that maps each NewLeaf font abbreviation to a Windows TrueType font and, when specified, to a PostScript font. This table is referenced each time the font property is changed. If you plan to use a font that does not appear in the table, use leaf.DefineFont to add it. The calling syntax contains two or, optionally, three text vectors:

leaf.DefineFont nlFont winFont (psfont)

The vectors in the right argument are the NewLeaf font abbreviation, the Windows font name and, if present, the PostScript font name. The NewLeaf font abbreviation is converted automatically to an uppercase text string before it is appended to the font table; the other two strings are stored unchanged. The abbreviation must not exceed four characters, it must be unique within the table, and its first two characters must differ from those for any font family (see below). For example, you can add a single font:

leaf.DefineFont 'uncl' 'Uncial'

This appends an entry to the table that maps the NewLeaf font abbreviation ∆UNCL∇ to the ∆Uncial∇ Windows font; there is no associated PostScript font. If you decide subsequently to map this to a particular PostScript font, re-enter the definition to remove any existing entry for that NewLeaf abbreviation and append a new entry:

leaf.DefineFont 'uncl' 'Uncial' 'ZapfChancery-MediumItalic'

Finally, to remove an entry, you need specify only the abbreviation:

leaf.DefineFont 'uncl'

In addition to an individual font, NewLeaf allows you to add a font family to the table. A font family is a group of four variants (plain, italic, bold and bold-italic) of a single font. You add a font family by specifying a unique two-character text string as the abbreviation. So,

leaf.DefineFont 'ga' 'Garamond MT' 'Garamond'

adds four entries to the table with the abbreviations GA, GAI, GAB, GABI. These correspond to the Windows Garamond MT font with appropriate Italic and Bold properties. leaf.DefineFont also adds standard suffixes to the latter three PostScript names (-Italic, -Bold, -BoldItalic). Occasionally, as here, the PostScript suffix for the plain variant is incorrect (it should be Garamond-Regular). You will need to fix this by hand in leaf.∆fonttbl, remembering to re-apply the change when you next upgrade NewLeaf.


NewLeaf for Dyalog12: Defining Paragraph Styles

Defining Paragraph Styles

NewLeaf maintains a table, leaf.∆gallery, that contains a set of defined paragraph styles. This table is referenced each time the style is changed. If you plan to use a style that does not appear in this table, you can add it through leaf.DefineStyle. The function is ambivalent:

{stylename} leaf.DefineStyle props

where props is a two-column nested matrix with text property names in the first column and the corresponding value in the second column. styleName, if supplied, is a simple, mixed-case text vector containing the unique name for this style together with a brief description. The name and description are separated by one of these three characters: =;⍝. If there is no left argument, a default name ('Newx' where x is one greater than the number of rows in the table) and description (;'(untitled)') are provided. For example:

props←2 2⍴'Font' 'HE,36' 'Align' 'Centre'
'Title;Main document title' leaf.DefineStyle props

adds a style called Title that, when specified, will centre 36-point Helvetica text on the page. If the Title style already exists in the table, the original entry is deleted and the new definition appended. So, if you decide that 36 text is too large, change the property value(s) and redefine it:

props←2 2⍴'Font' 'HE,24' 'Align' 'Centre'
'Title;Main document title' leaf.DefineStyle props

Similarly, because a style must have at least one valid text property and value, you can remove an entry in the table by trying to define one with an empty set of properties:

'Title' leaf.DefineStyle ''


NewLeaf for Dyalog12: Setting New Defaults

Setting New Defaults

NewLeaf stores information for the text properties in the six-column nested matrix leaf.∆proplist. There is one row for each property (the first row is reserved for field descriptions). The first two columns contain the two-character abbreviation for the property and a brief description, respectively. Column 3 is the ‘Set’ function, column 4 describes the expected property type, column 5 is the ‘Query’ function, and column 6 is the default value.

To find out the current value of a property, use the query function followed by the property abbreviation. If several abbreviations are supplied, a nested vector with the same number of elements is returned. A simple example is to look at the text alignment:

leaf.Query 'al'
Left

When you run leaf.Init (implicit when you start any report) NewLeaf always begins by running the ‘Set’ method (column 3) with each default value (column 6). If you prefer different default values, write an appropriate ‘Customise’ function which changes them as you require – making sure to respect the property types – and run it every time you re-install or upgrade NewLeaf to modify this table.

Default Table Properties

NewLeaf stores information for the table properties in the six-column nested matrix leaf.table.∆proplist. There is one row for each property (the first row is reserved for field descriptions). The structure is identical to leaf.∆proplist, so you can modify it in exactly the same way.

To find out the current value of a property, run the query function leaf.table.Query followed by the property abbreviation. If several abbreviations are supplied, a nested vector with the same number of elements is returned.


NewLeaf for Dyalog12: Saving a Reports on File

Saving a Reports on File

This topic applies to all NewLeaf documents, tabular or otherwise. The final output of NewLeaf is a series of ASCII page descriptions held in text vector format. While you continue to add text, tables, etc., to a document, NewLeaf saves each page to an APL component file as it is completed. This file is created by default in the TEMP directory (typically c:\temp or c:\windows\temp) and has the name newleaf.spl.

Over-riding the spool path

To choose your own path for the spool file, assign global leaf.∆spoolpath to the directory where the spool files are to be stored:

leaf.∆spoolpath←'E:\reports'

This may be necessary if you only have write access to a particular set of network directories.

Over-riding the spool file name

If you have several copies of APL running NewLeaf at the same time on the same computer (possibly in a server environment) you will need to ensure that each instance uses a different file name for spooling. The application may set the spool file name, which is stored as a global leaf.∆spoolname:

leaf.∆spoolname←'spool23.spl'
leaf.∆spoolname←''  ⍝ name will be generated

If you set this to null (as in the lower example) NewLeaf will make a file name of the form ‘~1234567.spl’ from the system clock at the time you call leaf.Use. This will give every spool file a unique name, but you will need to track and later delete these yourself.

The file tie number is the value of leaf.spool; so if you must untie all component files while producing a report, do so using ⎕FUNTIE ⎕FNUMS~leaf.spool. To this point, you have used leaf.Close to terminate each report. This has the effect of reading the component file and concatenating all of the page descriptions into a single text vector which is returned as the result. The component file is erased, so:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles districts
leaf.table.List sales[1;;]
leaf.NewPage
leaf.table.List sales[2;;]
View doc←leaf.Close

leaves the entire document description in the variable doc. It is frequently useful to leave the document on file. This is done by terminating it with leaf.Spool which unties the file and returns its name. This allows you to rename the file and keep it for later viewing:

leaf.Init ⋄ leaf.Use''
leaf.table.Titles districts
leaf.table.List sales[1;;]
leaf.NewPage
leaf.table.List sales[2;;]
docfile←leaf.Spool 'C:\SALESREPS\96H1.rep'
View 'C:\SALESREPS\96H1.rep'

If you run leaf.Spool with a null right argument, it returns the default file name (e.g. c:\temp\newleaf.spl) and simply unties the file.


NewLeaf for Dyalog12: Translating the Viewer Text

Translating the Viewer Text

All the text elements associated with the NewLeaf viewer may be translated into your local language by maintaining a simple text phrasebook file and reading this into the application at initialisation, or simply before saving the workspace prior to shipping. Phrasebooks in most common European languages are shipped by Causeway, but if you wish to create your own file, the format is very simple, and you may start simply by renaming the uk-en.phb file and modifying the phrases as appropriate.

Using an existing phrasebook

This is managed with two service functions:

∆de←PostScrp.GetPhraseBook 'c:\deutsch.phb'

This reads the phrase table from file, and sets it as the active phrasebook for the viewer. You may ignore the result if you only run in a single language – just save the workspace with the phrase table in place. However if you regularly switch languages, you can keep the result in a variable (or on your own component file) and pass it as argument to:

PostScrp.UsePhraseBook ∆de

Note that this is the internal form of the phrase table, and may be changed in the future. It is always safest to maintain the plain text form as an external .PHB file.

Phrasebook file format

The format of the file is: {TAG=Phrase [# Purpose of phrase]} with one phrase per line. A special phrase is anything beginning ‘~’ which removes a tool button or menu item completely. You can force newlines in a phrase with the ASCII ‘pipe’ character (this only applies to error messages and tooltips). You may use tabs in place of the ‘=’ and ‘#’ delimiter characters if you prefer.

Lines beginning with blank, and comment lines (which begin with the ‘#’ character) are ignored; all trailing space is removed from the phrase. Please note that the short tags used to identify the phrase to the viewer are case-sensitive, and should not be altered.

Here is a small sample from the uk-en phrasebook file:

# Input request dialogues
WMFC=Metafile Copy                       # Copy dialogue title
WMFE=Invalid file name or directory ...  # Copy dialogue error
BMPS=Bitmap Scale                        # Bitmap scale title
GIFS=GIF Scale                           # GIF scale title

Where data is to be inserted into a phrase at run-time, the parameters are marked with the symbols %1 %2 and so on, for example Page %1 of %2.

When new capabilities are added to the viewer, local Causeway distributors, users or other volunteers will be contacted to update the necessary texts before the product is shipped. If a phrase cannot be translated in time, the phrasebook will be shipped with the new phrase in English. Missing phrases show in the viewer with the identifying tag only.


NewLeaf for Dyalog12: Causeway Graphical Systems Ltd

Causeway Graphical Systems Ltd

For more information on any Causeway product, contact us at:

Causeway Graphical Systems Ltd
The Maltings
7 Castlegate
MALTON
North Yorkshire, YO17 7DP UK

Information is also available on the World Wide Web at

HTTP://www.causeway.co.uk

where you will also find the latest updates of any of our products.

Tel: +44 (0) 1653 696760 ... Fax: +44 (0) 1653 697719

Email: support@causeway.co.uk


NewLeaf for Dyalog12: Clipping text at frame edge

Clipping text at frame edge

Text set with leaf.Flow always wraps at the left edge, but may run out of the bottom of the frame if ‘overflow’ is set to 1.

If the frame is set to ‘Clip’ its content, text set with leaf.Place will be trimmed at the right-hand edge, and any text that would run out of the bottom of the frame may be discarded by setting overflow to 2.

See also ...

leaf.Bitmap – placing bitmaps | Allowing text to flow out from a frame

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: Colour Table

Colour Table

Any of the NewLeaf commands which take colours as argument can take either an integer argument, a short code, a colour name or a hex string of the form '#FF00CC' which is the syntax normally used in web pages. The colours corresponding to the numbers 0-15 are:

# | Code | Name
0 | ne | Black
1 | re | Maroon
2 | gr | Green
3 | or | Olive
4 | bl | Navy
5 | ma | Purple
6 | cy | Teal
7 | wh | Gray
8 | NE | Silver
9 | RE | Red
10 | GR | Lime
11 | YE | Yellow
12 | BL | Blue
13 | PU | Fuchsia
14 | CY | Aqua
15 | WH | White

The two-letter (case-sensitive) short-codes are included for compatibility with older NewLeaf applications only. From now on it is better to use the standard internet names for the colours, as the old short-codes will eventually be de-supported. Higher numbers are taken as an RGB composite, so that (for example) 1234567 is a pastel green. Alternatively you can give the HTML-style colour strings such as:

leaf.table.TColour'#BB7B27'
leaf.table.TBCol'#064606'

This will set the table titles to orange text on a dark green background.


NewLeaf for Dyalog12: Frames

Frames

The frame is the basic element of page-layout in NewLeaf. It defines a rectangular region into which text can be placed or flowed.

Frames can be drawn with borders, or background-filled with colour. Frames can have names to allow text to be placed in specific areas on the page.


NewLeaf for Dyalog12: Flagging items for HTML use

Flagging items for HTML use

When you build a page layout, it is likely that some elements will be required on the HTML page (for example a company name at the top) but not all elements are relevant (page numbers are usually meaningless here). The options are:

  • (none) – the default state
  • Top of Report – item appears once only at the very top
  • Top of Page – item appears at the top of every page
  • End of Report – item appears once only, at the very end
  • End of Page – item appears at the end of every page

You can mark elements as ‘Top of Page’ or ‘End of Page’ but note that only hard page-breaks (created with leaf.Newpage) will be mirrored in the HTML (as heavy horizontal rules) so these are unlikely to be useful.

See also ...

How to generate a simple web page


NewLeaf for Dyalog12: Allowing text to flow out from a frame

Allowing text to flow out from a frame

The default for the ‘overflow’ state of a frame is 0=’autoskip’ so that when either text or an image would be drawn beyond the bottom edge of the frame, NewLeaf automatically skips to the next available frame.

If overflow is 1=’spill’ the check at the frame boundary is not made, and the text is simply written on to the paper. This might be appropriate for an address box on a letter, where an unexpectedly long address should all appear on the paper, even if it failed to fit completely in its box.

If overflow is 2=’discard’, NewLeaf does not skip to a new frame here, but instead simply abandons any text that would fall outside the frame boundary. This would be appropriate for a form-filling application where extra text must not interfere with the content of other fields.

See also ...

leaf.Bitmap – placing bitmaps | Clipping text at frame edge

Send comments on this topic
© Dyalog Ltd 2007


NewLeaf for Dyalog12: Points

Points

The point is 1/72 of a inch, approximately 1/28cm. It is the standard unit used by PostScript printing devices, and is used throughout NewLeaf in setting measurements.

In the page design tool, you can choose to work in inches, centimetres or millimetres as well as directly in points.


NewLeaf for Dyalog12: leaf.table.Colour – set table text colour

leaf.table.Colour – set table text colour

Sets the cell text colours as a vector or matrix of colours using the standard HTML colour names or the ‘#FF’ syntax:

leaf.table.Colour 'red' 'blue' 'green'

The colours are reshaped to match the shape of the input data.

See also ...

Colour Table


NewLeaf for Dyalog12: About the Tutorials

About the Tutorials

By working through the table tutorials, you should quickly learn to create complex tabular reports.


NewLeaf for Dyalog12: VML for line-drawing

VML for line-drawing

NewLeaf uses a selection of simple drawing commands based on the ideas in Microsoft’s VML standard. These can be used to add arbitrary lines and boxes anywhere on the page.