Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
extending [2016/03/24 09:32]
christian [Add a new Smalltalk class]
extending [2016/09/28 23:05] (current)
93.204.170.83 ↷ Links adapted because of a move operation
Line 28: Line 28:
 ==== Add a new Smalltalk class ==== ==== Add a new Smalltalk class ====
  
-The new class can be defined with the //''class definition editor''//:+The new class can be defined with the //''ClassCreationDialog''//: 
 {{:pdf:borderstyledefinitiondialog.png?nolink | The ClassCreationDialog for BorderStyle}} {{:pdf:borderstyledefinitiondialog.png?nolink | The ClassCreationDialog for BorderStyle}}
- 
-=== Choose a class name === 
  
 === Choose the package === === Choose the package ===
 +
 +The package is ''[PDF Interactive Features]'', because it is related to /Annot which is defined there.
  
 === Choose the namespace === === Choose the namespace ===
  
-=== Choose the superclass ===+This should be ''Graphics.PDF'', since this is the only namespace for the runtime code of the library.
  
-Firstly, new class need to be defined. For this you need to choose: +=== Choose a class name ===
-  * a name +
-  * a package +
-  * a namespace (which should be ''Graphics.PDF''+
-  * a superclass which may be Dictionary, TypedDictionary if the object has an attribute **/Type**, or someting else (see later).+
  
-As name for this example, I use **/BorderStyle**. Ideally the name should be the same as used in the specification. The package is **[PDF Document]**because it is related to /Annot which is defined there. The superclass is **TypedDictionary**because the specification defines a **/Type** entry in the border style dictionary.+As name for this example, I use ''BorderStyle''. Ideally the name should be the same as used in the PDF specification. If the name does not match the name in the specificationbe it because the name is already defined or for estetic reasons, the class method ''type'' (or ''subtype'', depending on the type inference mechanism) needs to be implemented.
  
-As class comment, the first paragraph of the description in the specificatiopn is copied. Also the reference to the specification should be included as first line:+=== Choose the superclass ===
  
-<code> +Most oftenthis will be ''Dictionary'' or a ''TypedDictionary'' if the object has the common attribute ''/Type''It can also be something exotic as a ''PDFArray''a ''Name'' or someting else (see later).
-PDF border style dictionary as defined in PDF 32000_2008.pdfsection 12.5.4pp. 386.+
  
-An annotation may optionally be surrounded by border when displayed or printed. If present, the border shall be drawn completely inside the annotation rectangle. In PDF 1.1, the characteristics of the border shall be specified by the Border entry in the annotation dictionary (see Table 164). Beginning with PDF 1.2, the border characteristics for some types of annotations may instead be specified in a border style dictionary designated by the annotation’s BS entry. Such dictionaries may also be used to specify the width and dash pattern for the lines drawn by line, square, circle, and ink annotations. Table 166 summarizes the contents of the border style dictionary. If neither the Border nor the BS entry is present, the border shall be drawn as a solid line with a width of 1 point. +=== Add class comment ===
-</code>+
  
-I usually edit this text to add line breaks after sentences and remove any cross references to other parts of the specification:+The first line should give the reference to the PDF specification, followed by the first paragraph of the description in the specification. I usually edit this text to add line breaks after sentences and remove any cross references to other parts of the specification:
  
 <code> <code>
Line 68: Line 63:
 </code> </code>
  
-Two more bits of information should be added as methods on the class side:+=== Add class methods === 
 + 
 +Two more bits of information should be added as methods on the class side
 + 
 +The ''documentationPlace'' defines the section in the PDF specification. This is a more recent addition intented to be able to jump directly to the corresponding place in the specification PDF from the code browser or the PDFExplorer. This has not been done yet and most objects don't have this method, but for new objects, I add it. Eventually, I will add this to all objects. 
 <code smalltalk> <code smalltalk>
 documentationPlace documentationPlace
Line 74: Line 74:
 </code> </code>
  
-This is a recent addition intended to be able to jump directly to the corresponding place in the specification PDF. This has not been done yet and most objects don't have this methodbut for new objects, I want to have it.+If the object type was not part of the original PDF specification 1.0, the version should be added. ''version'' notes the minor part of the PDF version in which this feature first occurredallowing for computing the minimal version for a PDF.
  
 <code smalltalk> <code smalltalk>
Line 81: Line 81:
 </code> </code>
  
-This notes the minor part of the PDF version in which this feature first occurredallowing for computing the minimal version for a PDF.+The version is usually mentioned in the specification of the object. After I add this methodI remove the corresponding text from the class comment.
  
-Since a new type is defined, the object types have to be reset with ''PDF resetObjecttypes'' so that the new type can be found.+=== Reset the object types === 
 + 
 +Since a new type is defined, the object types have to be reset with 
 +<code smalltalk> 
 +PDF resetObjecttypes
 +</code> 
 +This clears the cache for all the object types (Smalltalk classes - 137 at the time of writing). On next access, the cache is filled with all known types, including the newly defined ones, so that the new type can be found. 
 + 
 +This has to be done only when a new class is defined. 
 + 
 +=== Use the new type for the containing attributes ===
  
 The new type can now be used. Therefore, the type of the attribute which contains the object should be set to the new type. In the example, in the method ''BS'' of class ''FreeText'', the ''type:'' pragma should be changed from The new type can now be used. Therefore, the type of the attribute which contains the object should be set to the new type. In the example, in the method ''BS'' of class ''FreeText'', the ''type:'' pragma should be changed from
Line 104: Line 114:
 </code> </code>
  
-The result looks like this in the PDFExplorer (after hitting F5 for refresh): the style is recognized as **BorderStyle** and it shows the right version (PDF-1.2), but the required field ''Type'' is red (error) and the ''W'' field is pink (not known).+The result looks like this in the PDFExplorer (after hitting F5 for refresh):
  
 {{:pdf:pdfexplorerborderstyle.png?nolink |new object type /BorderStyle}} {{:pdf:pdfexplorerborderstyle.png?nolink |new object type /BorderStyle}}
  
 +the style is recognized as **BorderStyle** and it shows the right version (PDF-1.2), but the required field ''Type'' is red (error) and the ''W'' field is pink (not known).
 ==== Add attributes ==== ==== Add attributes ====
  
-add attribute method+Attributes are added as methods in protocol ''accessing entries'' named like the key in the definition, even with a capital letter, although this is not common Smalltalk style.
  
-add pragmas+The first two attributes (of 4) look like this in the PDF specification: 
 + 
 +{{:pdf:pdfspecborderstyle.png?nolink|Part of the BorderStyle attribute definition}} 
 + 
 +The corresponding methods look like this: 
 + 
 +<code smalltalk> 
 +Type 
 + <type: #Name> 
 + <attribute: 1 documentation: 'The type of PDF object that this dictionary describes.'> 
 + ^self objectAt: #Type ifAbsent: [#Border asPDF] 
 +</code> 
 + 
 +<code smalltalk> 
 +
 + <type: #Number> 
 + <attribute: 2 documentation: 'The border width in points. If this value is 0, no border shall drawn.'> 
 + ^self objectAt: #W ifAbsent: [1 asPDF] 
 +</code> 
 + 
 +An attribute method consists of a number of describing pragmas and the code for access. 
 + 
 +=== The type: pragma === 
 + 
 +Mandatory is the ''<type: aSymbol>'' pragma: it takes the name symbol of the Smalltalk class implementing the PDF type. This is derived from the "Type" column of the definition table. For more information about typing and the possible type pragmas, see [[typing]]. 
 + 
 +=== The documentation pragma === 
 + 
 +The documentation is specified in the ''<attribute: anInteger documentation: aString>'' pragma. The first parameter defines the order of the attribute, so that they can be displayed in the same order as they are defined by the PDF specification. The first attribute shall be ''1'' and the next ones are numbered consecutively. 
 + 
 +The documentation is taken directly from the specification and edited, so that all information is removed which is expressed directly in the method. In our example, the "(Optional)" is removed, because this is implied. If the attribute is required, the ''<required>'' pragma is used to express this fact. 
 + 
 +The description of the default value is also removed, because this is evident from the access code. 
 + 
 +Also references to other parts of the specification are removed (which is not the case in the example). 
 + 
 +=== The version: pragma === 
 + 
 +Often, new attributes were added with later PDF versions. The version of an attribute, if it is higher than the version of the type, can be noted with the ''<version: anInteger>'' pragma, where the argument is the minor version of the PDF (i.e. 2 for version PDF-1.2). 
 + 
 +=== The access code === 
 + 
 +The access code can be either 
 +<code smalltalk> 
 + ^self objectAt: #Type ifAbsent: [#Border asPDF] 
 +</code> 
 + 
 +for optional attributes with a default value, or  
 +<code smalltalk> 
 + ^self objectAt: #Type 
 +</code> 
 + 
 +for a required attribute. This will raise an error if the attribute is not present in the object. 
 + 
 +The method will return the object of the value of the attribute. The object is either stored directly in the attribute or a reference to it. In any case, the object is returned. To access the value (object or reference), the following methods can be used: 
 +<code smalltalk> 
 + ^self at: #Type ifAbsent: [#Border asPDF] 
 +</code> 
 +<code smalltalk> 
 + ^self at: #Type 
 +</code>
  
-copy and edit comment 
  
 ===== Customize an object type ===== ===== Customize an object type =====
  
-docs, icon, string, attributes (docstypeorderversion, required)+Nowthe PDF type is sufficiently defined to be usefully displayed in the PDFExplorer. But more can be done by defining some of the following methods. 
 + 
 +==== Optional customization methods ==== 
 + 
 +=== Display name === 
 + 
 +The method ''listText'' returns a short Text used in the treeview of the PDFExplorer. The method ''titleText'' is used for the display of the selected object on the right side. 
 + 
 +=== Icon === 
 + 
 +The method ''toolListIcon'' can be defined on the class side to get an icon for the class in the Smalltalk browser. A PDF type class has the method ''listIcon'' on the instance side whichby defaultis the ''toolListIcon'' of the class. Therefore it is possible to select an icon depending on the object's state. 
 + 
 +=== Excluding attributes === 
 + 
 +Some attributes clutter the treeview on the left side of the PDFExplorer. For exampleevery ''TypedDictionary'' has the attribute ''/Type'' which is usually used as the name of the object itself. 
 + 
 +By defining the method ''displayKeysToOmit''such attributes can be excluded from the children of the object in the treeview. For the class ''TypedDictionary'' the method looks like this: 
 + 
 +<code smalltalk> 
 +displayKeysToOmit 
 + ^super displayKeysToOmit #(#Type) 
 +</code> 
  • extending.1458808358.txt.gz
  • Last modified: 2016/03/24 09:32
  • by christian