Visibility Reference Manual 

1.0 Installation

This product has been packaged as a configuration map. To import it into your library select 'Browse Configuration Maps' from the 'Tools' menu of the 'System Transcript'. In the 'Configuration Maps Browser' select 'Import...' from the 'Names' menu and select the file tobvis5-5_1-0-3a.dat You should then select the seven configuration maps contained within this file:

 

To load the configuration maps into your image select each of them in the 'Configuration Maps Browser' select 'Load With Required Maps' from the 'Editions' menu.

2.     Note re. OS/2

WindowsNT was used to develop this software. We have checked it out against OS/2 Warp 3.0 and note the following differences:

·         There is no direct support in IBM OS/2 Smalltalk for direct printer commands for facilities such as setting orientation, as there is in Windows. Thus, we have created our own methods. These work with our version of OS/2 and with our printers. If you have any problems with setting orientation, can you please e-mail the debug stack to beta@lamplight.co.uk.

·         OS/2 fonts are different from Windows fonts. The test page as shown on our web site is set for Windows font sizing. OS/2 Times Roman creates to a larger size - point size for point size and thus the test page prints a little differently under this OS than under Windows. The differences are minor and are only a problem in the test page. Your own programming will automatically take into account OS/2 fonts as you define your pages. This is a cross platform issue only. There is a known problem in moving cross platform, as far as fonts are concerned, generally between Windows and OS/2. If you are writing cross platform code, you will already have seen this in the windows that you create.


3.     Overview

3.1     Introduction

Visibility comprises of IBM Smalltalk code to enable developers to print to any printer attached to the system with ease and flair.

3.1.1     Compatibility

Visibility is written, 100%, in IBM Smalltalk. This means that it is compatible both with IBM Smalltalk and IBM VisualAge Smalltalk. Lamplight supply import files for both Standard and Professional versions of these two systems. As no code other than that supplied by IBM is used, Visibility should be compatible with all Smalltalk/VisualAge supported operating systems. As all printer attributes are derived from the standard Smalltalk facilities and all output is scaled, the printed result should be compatible with most printers whose drivers conform to the operating system requirements.

3.1.1.1     Note:

Due to the impossibility of testing Visibility under all operating systems and all possible printers, it cannot be guaranteed that it will produce acceptable output on every available combination. However, if any incompatibilities are discovered and reported to Lamplight Software, we will do our best to resolve them or provide a full refund, provided that we are informed within 30 days of providing the software to you.

3.1.2     Capabilities

Visibility provides the following capabilities:

·         to build a series of pages from an array of strings and output them to the chosen printer with full pagination, headers, footers and page numbers;

·         to build a series of pages made up from standard and user extendible building blocks

·         to build a page comprising of specifically xy located objects of the following forms:

·         text strings

·         font changes

·         lines of user-defined width

·         open boxes with borders of user-defined width

·         filled boxes

·         open circles with borders of user-defined width

·         filled circles

·         other objects built by yourself using Visibility tools

·         support for such items as drawing boxes around text

·         text justification of left, right and centred

·         choice of portrait, landscape or fax output

·         user defined process names - these appear in the print spooler window

·         automatic page numbering

The rest is really up to your imagination.

3.1.3     What it cannot do

There is currently no support for the following:

·         rotated text

·         text lines longer than a single line - no line wrap

·         bit maps

3.1.4     What is to come

The current development plans include various facilities that will be included within future releases of Visibility. These releases will be available to existing users at a suitably reduced upgrade fee. The plans include:

·         line wrapping - a specialised text object that can handle text longer than a single page width;

·         complex line height changes;

·         bit map printing;

·         a full ‘turtle graphics’ module which will enable the use of simple commands such as move, moveTo:, turn, turnTo:, penUp, penDown, etc. to create complex graphics on the page;

·         page preview

·         support for nominated printers rather than just portrait, landscape, etc.

4.     Supplied classes

Visibility comes with a range of classes that provide the means to print. Each of these has a specialised task.

4.1     VisibilityBasicObject

Visibility works by building a single page at a time. It takes individual composition objects and places them on the page in the required xy location. VisibilityBasicPrintObject provides the abstract class on which the class methods needed to create these objects are built.

The subsidiary classes represent each type of object that can be added to a page. These comprise of:

·         VisibilityTextObject - place a line of text in a defined or default font on the page;

·         VisibilityFontObject - record a global change of font;

·         VisibilityLineObject - place a line of a defined or default width on the page;

·         VisibilityBoxObject - place a box of a defined size with a default or define outer border, or place a filled box of a defined size - on the page;

·         VisibilityCircleObject - place a circle of a defined diameter with a default or define outer border, or place a filled circle of a defined diameter - on the page;

The individual objects are all discussed later in the Methods Dictionary along with full descriptions of all of the instance variables. Source is provided for each of the public methods of these objects. However, a simple overview would be appropriate here.

All objects have two things in common:

1.       They each have a class creation method called newFor: followed by the specific paramters for their object type;

2.       They each respond to the drawOn:shell using:gc method where shell is the current Printer Shell and gc is the current Graphics Context held within the current VisibilityPrint instance as printerShell and gc. This drawOn method does the actual drawing for the object. Obviously, complex drawings may be implemented in these methods as well as the printing of core objects.

4.1.1     Text object

Placing an item of text onto the page requires certain information. We need to know:

·         what the text is

·         where it is to go

·         what justification is needed

·         which font to use

The class method

newFor:aLine where:where justification:justification font:font

provides these facilities. As an example:

VisibilitytextObject newFor:’This is a test’ where:1000@1000 justification:##centre font:’Standard’

will result in the text ‘This is a test’ being centred on a point 1000 points across and 1000 points down from the top left hand corner and displayed using the font in the FontDictionary residing at ‘Standard’, which in the demo system is TimesNewRoman 12 point.

4.1.2     Other objects

The other objects require further information such as a diameter for the circle object and an end point for a line.

4.1.3     Creating your own

As the process is relatively simple, we have provided instructions later in this document that describe how to construct your own print objects. There is no real requirement for an object to do a single task. The print object could be as complex as you wish it to be - it could draw a complex logo for instance. It is up to you!

4.2     VisibilityPagePrinter

This is the super class of any class that you would build to create pages for your use. As you will see, VisibilityDemo is a sub-class of this. It provides all of the lower level routines that you can use to create the page. These include:

·         obtaining resolution adjusted points, line heights and point locations

·         setting headers, footers and page numbers

·         setting fonts

·         obtaining printer information

·         processing the print objects

Each of the public methods are described in details later. However, the main process of creating a page needs to described.

4.2.1     Printing a simple array or text file

The following method description is provided in the Method Dictionary:

printArray:array header:header footer:footer

array: OrderedCollection (or other compatible structure) of String header:, footer: String

Builds and prints all of the pages required to show the strings within array with header and footer on each page.

This is the basic method for printing an array. The array must comprise of an indexable array - Array or OrderedCollection (OC) will do. The individual components must be either strings or objects that return a string as a result of being sent the printString method. Each string must be less than a single page width in length. This length is font dependent. (A future release will give you facilities to handle strings that are longer than this.)

The method calculates the number of pages required to display all of the strings, one to a line. It then builds a special type of OC that holds OCs for each of the pages required. It then places these strings into these OCs as text print objects. It adds the required header and footer to each page and then sends the whole construct to VisibilityPrint to print.

VisibilityDemo provides a wrapper to this to show how it works. This is printFile:fName.

This takes the contents of fName - which must be a standard text ASCII text file with either lf or lf/cr line separators; sends these to a special routine that converts the lines into individual strings in an array, and then sends this array to the above mentioned method.

4.2.2     Printing a complex page

There is a VisibilityDemo class method that prints out the standard test page. This makes use of instance methods of that class to construct the elements on the page and then send them to VisibilityPagePrinter for printing. The source code for all of these operations is supplied so you should look to that for guidance. As we have done with VisibilityDemo, you should sub-class VisibilityPagePrinter to use its capabilities.

4.3     VisibilityPrint

This class does the actual interpretation of the print objects into points on the page. Most of the class is private and solely concerned with the general housekeeping of running the output and managing the graphics context. However, you do need access to some of it so that you can extend the facilities yourself. Thus, the source is provided for most of the public methods in this class.

VisibilityPrint also manages the FontDictionary. This is covered in another section of this guide.

4.4     VisibilityPrinterInfo

This class provides a wrapper for the basic page information about the printer. This information is obtained from the operating system and is thus controlled by the way that you have configured the printer using the control panel (and maybe the VA set up). If you have set the printer to 300 dpi in the control panel, you should not expect 600 dpi output from Visibility.

All of the answers provided by these methods are in absolute printer points, not scaled points.

5.     Hints, tips and explanations

5.1     Which methods should you use

We have not made the usual distinction between public and private methods - in that normally the developer is suggesting that you do not use private methods as they might change. Many of our private methods are just this. However, we make some methods private as they are at a low level and should not be used to construct your pages. More than that, changing them might break something. To ensure that you cannot break anything, we only provide the source to the public methods that you can add to make your own objects or to use as templates to construct your own pages.

The misuse of a graphics context can be very difficult to track down and the whole point of this utility is that we make it easy (well easier) for you to print.

To make it very clear, those methods that are available for your use are all within the VisibilityAPI category. Anything  else is held within the plain vanilla Visibility category.

5.2     Printer point issues

We use a range of names for printer points in this document. This is because a point is not always a point!

5.2.1     Basic dpi

All printers can manage a set number of dots across the page and down. This is regarded as the resolution and noted in dots per inch (dpi). Thus a 600 dpi printer can manage 600 dots by 600 dots in each square inch = 36,000 dots. A 300 dpi printer can only manage 300 by 300 = 9,000. Notice the acceleration in dots as we get higher. In addition, some printers - most usually ink jets - have unequal resolution - 600 by 360 or something.

We wanted to make  the printing process simple in terms of getting the same page out of all printers, no matter what their resolution. Constructing a page for 300 by 300 results in a quarter sized image in the top left hand corner on a 600 by 600 printer.

5.2.2     Scaling factor

Visibility is constructed for a basic 600 dpi printer. Everything else is scaled from that. Thus, if you want to start printing a piece of text at a point 1000@1000, on a 600 dpi, it will send 1000@1000, on a 300 dpi printer it will send 500@500. This results in a text line at the same place on the page (well actually, there is sometimes some roundings going on as we have to work in integers). In other words, when the printing process starts, we inquire of the resolution and divide that into 600@600. Thus a 600 dpi printer returns a scaling of 1@1 whilst a 300 dpi printer results in a scaling of 2@2.

5.2.3     Raw points

When we refer to raw points, we are talking about the points that the printer itself understands; i.e. the unscaled points. Thus the 1000@1000 mentioned earlier will go to a 600 dpi printer at 1000@1000 (its raw points) whilst the 300 dpi printer will get 500@500 - its raw points. Some elements of the printing process are better handled in raw points as there is no reason to make them scaled only to scale them back. Line heights are a good example. You should never use a line height directly yourself. You should always let the utility handle them and thus they are kept in raw points as that is how we get them from the font sizing methods of Smalltalk.

5.2.4     Printer points

These are the ones that you should use, both conceptually and actually. If you always think in 600 dpi mode, you won’t go wrong. Thus, the example above would result in you using 1000@1000 for both the 600 dpi and 300 dpi printers. You don’t even want to think about conceptualising in 600@360 points!

5.3     Page size

Don’t forget that the printable area of various printers differs. A printer may not even have the same left margin as it has right margin. Fax machines often don’t even have a left margin at all! The top and bottom margins are almost certain to differ. We always return the size of the largest writeable area on the page. This does mean that the aspect ratio of boxes, etc. might differ when printed on different printers - text will be ok. We have decided that it is better to get everything on the page rather than have some lost. We would be interested in the users reactions to this and we may decide to add a facility to a future release that allows you the choice to keep the aspect ratio or the page contents consistent.

5.4     Fax machines

We use Windows NT 4.0 and have recently installed Microsoft’s own fax software. On printing the test page to through that, we get all of the text left justified, irrespective of where we actually place the text, and we get no graphics. You should send a test page through your target fax to check the output before you rely on it. We are looking at this problem.

5.5     Constructing a new print object

The standard ‘print an object routine’ takes VisibilityBasicPrintObject (and its subclasses) objects and converts them to actual printer output.

5.5.1     Example - printing a box

A box can have two forms - filled or open and has a range of parameters that must be set. The creation routine for a box is a class method in VisibilityLIneObject:

newFor:width where:where whereEnd:whereEnd

width: Integer. the width of the line - 0 (zero) will add no border - difficult to see the use of a line with zero width. This is defined as the width of the line that you want to see - remember all operations look as though they are being done on a 600 dpi printer. Thus a 4  will result in a 4 point line at 600dpi but only a 2 point line at 300 dpi (but it looks like the 4 that was asked for due to its lack of resolution).

Where: Point. The top leftmost corner of the box.
WhereEnd: Point. The bottom rightmost corner of the box.

All of these are instance variables of VisibilityLineObject or inherited from VisibilityBasicObject. The actual object is created as follows:

 

newFor:width where:where whereEnd:whereEnd

|o|

o:=self new.

o  width:width;

    where:where;

    whereEnd:whereEnd.

^o

5.5.2     Making your own

1.       Subclass an appropriate existing object.

2.       Decide on how the object must be described - an arc needs two angles, for instance, in IBM Smalltalk.

3.       Add any new instance variables to the instance methods of the new class - angle1 and angle2 for example.

4.       Build a newXXX method and add it as a class method. This method must accept all of the parameters required and answer a single instance of the object,  similar to the above example.

5.       Add an instance method to the class called drawOn:aPrinterShell using:aGraphicsContext that draws the new object. The form used is described in the IBM Smalltalk Programmers Reference but an open box looks like this.

drawBoxAs:aLine on:shell using:gc
self changeWidth:self width.                     “always change the width as the requirement might have changed”
shell window drawRectangle:gc        “printerShell is the passed printer shell. gc is the passed printer graphics context”
                   x:self where x
                   y: self where y
                   width:( self whereEnd x - self where x)
                   height:( self whereEnd y - self where y)

“the shell and gc are passed from VisibilityPrint. This class has the instance variables printerShell and gc which provide these objects.

6.       Construct your new page using the new object class method constructor - and bingo!

5.6     Fonts

Fonts are tricky things to handle. If you have read the IBM Smalltalk Programmer’s Reference, you will see that the whole area of fonts is complex. We have tried to make it as simple as possible. Please remember, however, that Visibility is a programmer’s tool and not an end user tool. We do not provide an end user printer selection window, neither do we provide a font selection window. You must allocate fonts yourself. However, we have made the use of fonts as easy as we can. VisibilityPrint contains a class dictionary called FontArray (? Sometimes our naming is not as good as it could be!) This provides simple access to the range of fonts required for the page.

At the start of the print process, VisibilityPrint builds the dictionary from a list held within initFontArray. The source is provided for this method. Each line of this method builds an individual copy of a font at a specific size and weight. Thus:

self defineFont:’*Times New Roman-medium-r*’  called:’Standard’ size:10

builds a ‘TimesNewRoman’ font that is medium weight (not bold or italic) at 10 points and saves it into FontArray at ‘Standard’.

Note: You must always have one font called ‘Standard’ for the printArray facility to work.

Another line in that method is:

self defineFont:’*Times New Roman-bold-r*’  called:’BigBold’ size:16.

This builds a bold version of the font at 16 point size.

defineFont: called: size does all of the actual creation by asking the operating system for a copy of a font that matches the name string. The construction of that string; i.e. why is says: *Times New Roman-bold-r*’ is described in the Programmer’s Reference. Fundamentally, this returns the first font that matches the specification.

You can add to the list in the initFontArray method and provide any fonts that are available on the current computer. Please note that your customers must also have the same font installed. If they do not, then the operating system will return the nearest match, which might actually be no match at all!

You can call the fonts by any name you wish (but keep ‘Standard’ clear as mentioned).

You do have to build medium, bold, italic and bold italic fonts separately and name them differently - this is an operating system requirement - not ours.

5.6.1     Changing fonts

If you do not define a font, the printer will use its default font - normally some sort of Courier -ugh!  There are two ways to manage the font situation.

5.6.1.1     Global change

If you are constructing your page in a coherent manner and are confident that a global font change is what you want, you can call the VisibilityPagePrinter instance method

resetFont:aName  addToCommon:which

which will answer a font, which you can ignore. This will set the system wide font to the required one. It will appear in the instance variable font, which is inherited from VisibilityPagePrinter. You can add this to a text line at will.

The addToCommon part accepts a boolean and if true will also add a font printer object to the commonItems list. This will ensure that the printer receives the font and sets itself to it. You can then send a nil to each text line and the printer will use this global font for every line.

5.6.1.1.1     Warning

Setting a font just once in a text line will reset the printer to that font and thus cause that new font to be the default.

5.6.2     Individual assignment

It is better, if you are building a complex page, to define the font with each line. Then you can never get confused as to which font the printer is going to use. Call

resetFont:aName  addToCommon:which

with which set to false. This will load the chosen font into the class instance variable font. When you construct a line now, you can send this instance variable to the constructor and be sure that this font will be used with this text line.

This is demonstrated within VisibilityDemo.

6.     Visibility Methods dictionary

6.1     VisibilityDemo class methods

Please note that all source is provided for the VisibilityDemo class. File in visdemo.st.

printFile:fName

fName: String - must be a valid path to a file; e.g. ‘readme.txt’ will look in the current default directory. ‘c:\prindemo\readme.txt’ will look in ‘C:\prindemo’ directory for the file. fName must be a text file with either lf or lf/cr line delimiters. We supply the standard IBM readme.txt for VA - renamed ‘ibm.txt’. Place the file ‘ibm.txt’ in the directory or folder containing your image and then invoke this method by executing the following from any workspace.

VisibilityDemo printFile:‘ibm.txt’- On an HP 5L this results in 14 pages of text!

The method just wrappers up the inherited printArray instance method so that we can take the input from a file. The buildTextFile:fName is just a convenience for this demo. You can build any array and send it to printArray: header: footer:. Don’t forget - if you don’t want a header or footer, you should send null strings to this method.

printTestPage:orientation

orientation: Atom ##portrait = portrait, ##landscape = landscape, ##fax = Fax. There must be a printer with ‘Fax’ in the title for 3 to work. If it doesn’t exist, the default printer will be used. If your fax doesn’t emulate a printer then you cannot fax from Visibility. Please note that Fax output is more restrictive than most laser printers. You should check the results of using Visibility to send faxes before you start to send them in earnest.

PrintTestPage invokes an instance method printPage:orientation (see below). This initialises the printer and then creates some boxes, strings, etc., send them to the printer and prints the whole lot.

Invoke this method, the first time, by executing the following from any workspace.

VisibilityDemo printTestPage:##portrait (Replace :##portrait with ##landscape for a landscape version or ##fax to test your fax capability.)

6.2     VisibilityDemo instance methods

printPage:orientation

orientation: Atom ##portrait = portrait, ##landscape = landscape, ##fax = Fax.

This method is called by the class method testPrint:orientation.

init: processName: is used to initalise the print process. orientation sets the page orientation. processName is the name that appears in the Print spooler to denote the job that is being printed. showSomeBoxes;showSomeLines;showSomeText;showSomeCircles. These let us build some bits for the page - we put them in commonItems for convenience as there is no other need for that on this page. printList add:commonItems. Add the print items to the instance variable printList. printer printDoc:printList;startPrint. printDoc loads the printer with printList. startJob kicks off the print process.

Use this method as a template to build your own print methods.

showSomeBoxes Creates some VisibilityPrintLine objects with two boxes - one empty, one filled.

showSomeCircles Creates some VisibilityPrintLine objects with two circles - one empty, one filled.

showSomeLines Creates some VisibilityPrintLine objects with lines. These are at a variety of angles from a common origin.

showSomeText Creates some VisibilityPrintLine objects with text strings. These demonstrate how to change fonts, justification and point size. The fonts available are defined in VisibilityPrint and are placed in a dictionary within the instance of that class used for each print job. You can add fonts to that Dictionary using the techniques described in that section.

6.3     VisibilityPagePrinter methods

adjustX:x

x:Integer Answers a resolution adjusted x.

adjustY:y

y: Integer Answers a resolution adjusted y.

atLine:lineNumber x:x

lineNumber, x: Integer Answers a point (x@y) of x@lineNumber in absolute printer points. Visibility knows the current line height and calculates the new y in printer points representing that number of lines down the page.

atLine:lineNumber plus:delta x:x

lineNumber, delta, x: Integer Answers a point (x@y) of x@lineNumber with an extra delta amount of resolution adjusted points added to the lineNumber value. Visibility knows the current line height and calculates the new y in printer points representing that number of lines down the page. The delta enables you to adjust (+/-) a number of points from that calculation. This is useful when drawing boxes to go around text. If the standard atLine: x: was used, this would obscure some of the text.

atYRaw:y less:lineNum x:x

y, lineNum,x: Integer Answers a point (x@y) of x@y with an extra negative delta amount of lineNum. Visibility knows the standard line height and calculates the new y in printer points representing y absolute printer points with lineNum number of lines calculated as points and subtracted from y. This is a useful procedure for placing multiple line footers at the bottom of the page if y was the largest point number down the page.

buildFooter:footer

footer: String Creates a VisibilityPrintLine that represents footer. The justification is set to ##centre. The where is set to the bottom line@ page centre. This is added to commonItems which is automatically added to each page and thus will place a footer on each page. You can construct the string to contain any character.

buildHeader:header

header: String Creates a VisibilityPrintLine that represents footer. The justification is set to ##centre. The where is set to the top line@ page centre. The font is set to bold. The justification is set to ##centre. The where is set to the bottom line@ page centre. This is added to commonItems which is automatically added to each page and thus will place a header on each page. You can construct the string to contain any character. This is done for you when printing a list using the Demo printFile: method.

buildListFrom:lineList

lineList: OrderedCollection Assigns to the instance variable - pages, an OrderedCollection that contains an OrderedCollection for each page of the final print with the required number of elements from lineList.

buildTextFile:fName

fName: String fName must be a valid path to a file; e.g. ‘readme.txt’ will look in the current default directory. ‘c:\prindemo\readme.txt’ will look in ‘C:\prindemo’ directory for the file. Answers a list of strings extracted from the file fName. buildPageLines

Converts the pages of strings built using buildTextFile: into the actual print objects required. It also adds the commonItems to each page.

commonItems

Answers the commonItems instance variable. This normally contains an OrderedCollection of VisibilityPrintLine elements. These are the elements that you wish to appear on each page. At the appropriate time, you should addAll:commonItems to the built list of VisibilityPrintLine items for each page to achieve this.

commonItems:aList

aList:Normally an OrderedCollection new. Sets the commonItems instance variable.

defaultTextLine:oneLine at:lineCount oneLine:

String lineCount: Integer

Answers a VisibilityPrintLine set to print oneLine left justified at the left border at the required lineCount down in the current font.

font:aFont

aFont: Font from the VisibilityPrint font list Sets the current font to:aFont. This font is applied to all new text VisibilityPrintLine objects created until the font is changed.

init:orientation processName:aProcessName

orientation:Atom ##portrait = portrait, ##landscape = landscape, ##fax = Fax. aProcessName: String Carries out a general initialisation of the printing process. It sets the following: current printer orientation current printer processName font to the current ‘Standard’ font commonItems to an emptyOrderedCollection pages to an emptyOrderedCollection lineNumber to 1. printer to the current printer printerInfo to the current VisibilityPrintInfo istance which contains the information needed about the current printer in terms of height, width, etc.

isFirstPage:each

each: One element of the instance variable pages. Answers true if each is the first element of pages and therefore the first page; answers false if it is not.

isLastPage:each

each: One element of the instance variable pages. Answers true if each is the last element of pages and therefore the last page; answers false if it is not.

leading:numPoints

numPoints:Integer Sets the leading instance variable to a point number of your choice. The number sent should be an absolute number, not resolution adjusted. Leading is the extra distance placed between one line on the page and the next. Without leading the lowest point of the first line would be adjacent to the highest point of the lext line.

leading

Answers a resolution adjusted number for the extra to be placed between lines. If there is none set, it defaults to a resolution adjusted 5 points.

lineheight:aHeight

aHeight:Integer Sets the current line height.

lineheight

Answers the number of absolute points required between lines to accommodate the current font. Leading is added to this value. If there is no lineheight set, the lineheight of the current font is returned.

lineHeightCount

Answers the number of lines possible on the current printer page, using the page height and the current lineheight size (including the leading). The number answered is reduced by 2 to allow for the header and footer.

lineHeightCountAbsolute

Answers the number of lines possible on the current printer page, using the page height and the current lineheight size (including the leading).

printArray:array header:header footer:footer

array: OrderedCollection (or other compatible structure) of String header:, footer: String Builds and prints all of the pages required to show the strings within array with header and footer on each page.

printerInfo

Answers the currently set printerInfo

resetFont:aName addToCommon:which

aName: String representing a font in the currently defined font dictionary which:Boolean Answers the font represented by aName. It also sets the instance variable font to hold this font. In addition, if which is set to true, it will add a VisibilityPrintLine to the commonItems list setting the font change. This is only required if you do not assign a font to each text VisibilityPrintLine but assign a nil to the font in this.

showPageNumber:bool

bool: Boolean Sending true results in the printer routine automatically adding page numbers to the bottom right hand corner of the page.  The number is printed using the last define font. Sending false results in no line numbers.

standardLineWidth:aWidth

aWidth: Integer Sets the standard line width to aWidth. This number should be an absolute printer point value. All line operations use a line width. This is a useful way to record the line width that you wish to use if carry out many operations.

standardLineWidth

Answers the standard line width. If one is not set, it will answer a resolution adjusted line width representing the equivalent of 4 points at 600dpi.

6.4     VisibilityPrint methods

initFontArray

Builds a dictionary of fonts. You can add to this list if you wish. Refer to page 116 of the IBM Smalltalk Programmers Reference for details as to how to define the font name. This reference refers to Version 3, release 0 of that manual.

printOne:aLine

aLine: A subclass object of VisibilityBasicPrintObject that defines a single element on the page. This method sends the drawOn:using message to each object which results in a printed object or a font change.

StartPrint

Starts the print process. This is the final step before you relinquish control to the printer for the rest of the job - thus everything has to be completed at this point.

6.5     VisibilityBasicPrintObject methods

VisibilityBasicPrintObject is the abstract class and thus should never be used to instantiate an object. It does however provide the basic instance variables and their methods. All of the usable print objects are derived from this class. As the instance variables mentioned below are common across some classes, they are described in the table at the end of this section.

6.5.1     VisibilityBasicPrintObject subclasses

The supplied subclasses are as follows:

6.5.1.1     VisibilityCircleObject

newFor:width where:where diameter:aDiameter fill:bool

Creates an open circle of aDiameter diameter from a nominal point which is the top left hand corner of a bounding square. The border of the circle will be width wide. If bool is set to true, the box will be filled, if false then it will not.

6.5.1.2     VisibilityBoxObject

newFor:width where:where whereEnd:whereEnd fill:bool

Creates an open box in a rectangle from a point - where to a second point - whereEnd. The border of the box will be width wide. If bool is set to true, the box will be filled, if false then it will not.

6.5.1.3     VisibilityTextObject

newFore:aLine where:where justification:justification font:font

Creates a line of text that must be equal to or narrower than the printable width of the page.. aLine should be a string. If it is not, however, Visibility will send printString to it before use. Thus, any object that responds to printString where that method answers a string may be used. justification can currently be ##l (left), ##r (right) or ##c (centered). where is used as the starting point for the print operation and is decided by the justification symbol. Thus, ##l and 200@200 will use 200@200 as the leftmost bottom point, ##r and 200@200 will use 200@200 as the rightmost bottom point whilst ##c and 200@200 will use 200@200 as the mid, bottom point. font is the font to be used. If this is nil, the printer will use the last defined font sent to it using newFont:font above (or its default!).

6.5.1.4     VisibilityFontObject

newFor:aFont

Sets the current printer font to aFont. If this is not sent, the printer will print all output in its default font - normally Courier.

6.5.1.5     VisibilityLineObject

newFor:width where:where whereEnd:whereEnd

Creates a line from a point - where to a second point - whereEnd. The width of the line will be width wide.

6.5.2     Using Print Objects

Each subclassed object must have a method called drawOn:aPrinterShell using:gc. This was described in the section titled ‘Making your own’ above.

6.6     VisibilityBasicPrintObject (and subclass) instance variables

width

Integer - The width of the line or border. It is sent in absolute numbers and converted to resolution adjusted numbers. Thus, as 600dpi is the yardstick, if you want a 4 printer point wide line, and the printer is set to 600dpi, you will get a 4 point line; if the printer is set to 300dpi, you will get a 2 point line(which looks like a 4 point line, if you see what we mean!).

where

Point - The printer resolution adjusted start point for an object. Thus, 100@100 sent to a 600dpi printer is a point closer to the top left hand corner than 100@100 sent to a 300dpi printer, which will be the same point as the 600dpi printers 200@200. Thus, you should scale the point using adjustX: and adjustY: before sending.

whereEnd

Point - The same as where except it defines the end point of any object.

diameter

Integer - The resolution adjusted width of the required circle. It actually describes the width of a square that bounds the required circle.

aFont

FontStruct - The current font to be used to display the text included with the object. A FontStruct is the result of asking the font dictionary for a font. Once the dictionary has been built at initialisation time, the fonts are all available in this form. If this is set to nil, the last defined font will be used by the printer. If no font has every been sent to the printer for this print job, then the printer’s default font will be used - usually, Courier.

justification

Atom - Defines the justification for the current text object. ##l = left ##r = right ##c = centre.

6.7     VisibilityPrinterInfo instance methods

bottomBorder

Answersan integer representing  the number of raw printer points from the top of the page - represents the lowest writeable line on the page.

bottomCorner

Answers a point representing the number of raw printer points defining the raw printer point distance of the bottom right hand corner - represents the furthest writeable extent from the top left hand corner

centrePage

Answers an integer representing the nearest integer to the number of raw printer points from the leftmost writeable edge to the centre of the page.

extent

Answers a point representing the writeable extent of the page in raw printer points.

fontHeight:aFontName

aFontName: String - the name of a font in the font dictionary.

Answers the height of a font in raw printer points. This distance represents the number of points between the lowest descender character and the highest ascender character.

height

Answers an integer representing the height of the writeable area of the page in raw printer points.

leftBorder

Answers an integer representing the left hand edge of the writeable area. This is always 0 (zero).

numLines:lineHeight

lineHeight: Integer - the height of a line in raw printer points.

Answers an integer representing the number of lines possible on the page for a supplied lineHeight

origin

Answers a point representing the top left hand corner of the writeable area of the page. This is always 0@0.

rightBorder

Answers an integer representing the rightmost writeable point on the page.

showPageNum: anObject

anObject:Boolean Sending true results in the printer routine automatically adding page numbers to the bottom right hand corner of the page.  The number is printed using the last define font. Sending false results in no line numbers.

topBorder

Answers an integer representing the topmost printer point of the writeable area. This is always 0 (zero).

topCorner

Answers a point representing the number of raw printer points defining the raw printer point top left hand corner - represents the writeable extent of the top left hand corner. This is always 0@0.

width

Answers an integer representing the width of the writeable area of the page in raw printer points.