User Tools

Site Tools


pdf:extending

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pdf:extending [2016/03/24 10:02] – [Add a new Smalltalk class] christianpdf:extending [2016/03/30 09:00] (current) – [Add a new Smalltalk class] christian
Line 42: Line 42:
 === Choose a class name === === Choose a class name ===
  
-As name for this example, I use ''BorderStyle''. Ideally the name should be the same as used in the PDF specification.+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 specification, be 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.
  
 === Choose the superclass === === Choose the superclass ===
Line 85: Line 85:
 === Reset the object types === === Reset the object types ===
  
-Since a new type is defined, the object types have to be reset with ''PDF resetObjecttypes'' so that the new type can be found.+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 === === Use the new type for the containing attributes ===
Line 115: Line 121:
 ==== 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> 
/var/www/virtual/code4hl/html/dokuwiki/data/attic/pdf/extending.1458810155.txt.gz · Last modified: 2016/03/24 10:02 by christian