local-lib5/man/man3/Template::Plugin::Image.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Plugin::Image 3"
 132 .TH Template::Plugin::Image 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin::Image \- Plugin access to image sizes
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 6
 138 \&    [% USE Image(filename) %]
 139 \&    [% Image.width %]
 140 \&    [% Image.height %]
 141 \&    [% Image.size.join(', ') %]
 142 \&    [% Image.attr %]
 143 \&    [% Image.tag %]
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 This plugin provides an interface to the Image::Info or Image::Size
 148 modules for determining the size of image files.
 149 .PP
 150 You can specify the plugin name as either '\f(CW\*(C`Image\*(C'\fR' or '\f(CW\*(C`image\*(C'\fR'.  The
 151 plugin object created will then have the same name.  The file name of
 152 the image should be specified as a positional or named argument.
 153 .PP
 154 .Vb 6
 155 \&    [% # all these are valid, take your pick %]
 156 \&    [% USE Image('foo.gif') %]
 157 \&    [% USE image('bar.gif') %]
 158 \&    [% USE Image 'ping.gif' %]
 159 \&    [% USE image(name='baz.gif') %]
 160 \&    [% USE Image name='pong.gif' %]
 161 .Ve
 162 .PP
 163 A \f(CW\*(C`root\*(C'\fR parameter can be used to specify the location of the image file:
 164 .PP
 165 .Vb 3
 166 \&    [% USE Image(root='/path/to/root', name='images/home.png') %]
 167 \&    # image path: /path/to/root/images/home.png
 168 \&    # img src: images/home.png
 169 .Ve
 170 .PP
 171 In cases where the image path and image url do not match up, specify the
 172 file name directly:
 173 .PP
 174 .Vb 1
 175 \&    [% USE Image(file='/path/to/home.png', name='/images/home.png') %]
 176 .Ve
 177 .PP
 178 The \f(CW\*(C`alt\*(C'\fR parameter can be used to specify an alternate name for the
 179 image, for use in constructing an \s-1XHTML\s0 element (see the \f(CW\*(C`tag()\*(C'\fR method
 180 below).
 181 .PP
 182 .Vb 1
 183 \&    [% USE Image('home.png', alt="Home") %]
 184 .Ve
 185 .PP
 186 You can also provide an alternate name for an \f(CW\*(C`Image\*(C'\fR plugin object.
 187 .PP
 188 .Vb 2
 189 \&    [% USE img1 = image 'foo.gif' %]
 190 \&    [% USE img2 = image 'bar.gif' %]
 191 .Ve
 192 .PP
 193 The \f(CW\*(C`name\*(C'\fR method returns the image file name.
 194 .PP
 195 .Vb 1
 196 \&    [% img1.name %]     # foo.gif
 197 .Ve
 198 .PP
 199 The \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`height\*(C'\fR methods return the width and height of the
 200 image, respectively.  The \f(CW\*(C`size\*(C'\fR method returns a reference to a 2
 201 element list containing the width and height.
 202 .PP
 203 .Vb 4
 204 \&    [% USE image 'foo.gif' %]
 205 \&    width: [% image.width %]
 206 \&    height: [% image.height %]
 207 \&    size: [% image.size.join(', ') %]
 208 .Ve
 209 .PP
 210 The \f(CW\*(C`modtime\*(C'\fR method returns the modification time of the file in question,
 211 suitable for use with the Date plugin, for example:
 212 .PP
 213 .Vb 3
 214 \&    [% USE image 'foo.gif' %]
 215 \&    [% USE date %]
 216 \&    [% date.format(image.modtime, "%B, %e %Y") %]
 217 .Ve
 218 .PP
 219 The \f(CW\*(C`attr\*(C'\fR method returns the height and width as \s-1HTML/XML\s0 attributes.
 220 .PP
 221 .Vb 2
 222 \&    [% USE image 'foo.gif' %]
 223 \&    [% image.attr %]
 224 .Ve
 225 .PP
 226 Typical output:
 227 .PP
 228 .Vb 1
 229 \&    width="60" height="20"
 230 .Ve
 231 .PP
 232 The \f(CW\*(C`tag\*(C'\fR method returns a complete \s-1XHTML\s0 tag referencing the image.
 233 .PP
 234 .Vb 2
 235 \&    [% USE image 'foo.gif' %]
 236 \&    [% image.tag %]
 237 .Ve
 238 .PP
 239 Typical output:
 240 .PP
 241 .Vb 1
 242 \&    <img src="foo.gif" width="60" height="20" alt="" />
 243 .Ve
 244 .PP
 245 You can provide any additional attributes that should be added to the
 246 \&\s-1XHTML\s0 tag.
 247 .PP
 248 .Vb 2
 249 \&    [% USE image 'foo.gif' %]
 250 \&    [% image.tag(class="logo" alt="Logo") %]
 251 .Ve
 252 .PP
 253 Typical output:
 254 .PP
 255 .Vb 1
 256 \&    <img src="foo.gif" width="60" height="20" alt="Logo" class="logo" />
 257 .Ve
 258 .PP
 259 Note that the \f(CW\*(C`alt\*(C'\fR attribute is mandatory in a strict \s-1XHTML\s0 \f(CW\*(C`img\*(C'\fR
 260 element (even if it's empty) so it is always added even if you don't
 261 explicitly provide a value for it.  You can do so as an argument to
 262 the \f(CW\*(C`tag\*(C'\fR method, as shown in the previous example, or as an argument
 263 .PP
 264 .Vb 1
 265 \&    [% USE image('foo.gif', alt='Logo') %]
 266 .Ve
 267 .SH "CATCHING ERRORS"
 268 .IX Header "CATCHING ERRORS"
 269 If the image file cannot be found then the above methods will throw an
 270 \&\f(CW\*(C`Image\*(C'\fR error.  You can enclose calls to these methods in a
 271 \&\f(CW\*(C`TRY...CATCH\*(C'\fR block to catch any potential errors.
 272 .PP
 273 .Vb 6
 274 \&    [% TRY;
 275 \&         image.width;
 276 \&       CATCH;
 277 \&         error;      # print error
 278 \&       END
 279 \&    %]
 280 .Ve
 281 .SH "USING Image::Info"
 282 .IX Header "USING Image::Info"
 283 At run time, the plugin tries to load Image::Info in preference to
 284 Image::Size. If Image::Info is found, then some additional methods are
 285 available, in addition to \f(CW\*(C`size\*(C'\fR, \f(CW\*(C`width\*(C'\fR, \f(CW\*(C`height\*(C'\fR, \f(CW\*(C`attr\*(C'\fR, and \f(CW\*(C`tag\*(C'\fR.
 286 These additional methods are named after the elements that Image::Info
 287 retrieves from the image itself. The types of methods available depend on the
 288 type of image (see Image::Info for more details). These additional methods
 289 will always include the following:
 290 .Sh "file_media_type"
 291 .IX Subsection "file_media_type"
 292 This is the \s-1MIME\s0 type that is appropriate for the given file format.
 293 The corresponding value is a string like: "\f(CW\*(C`image/png\*(C'\fR\*(L" or \*(R"\f(CW\*(C`image/jpeg\*(C'\fR".
 294 .Sh "file_ext"
 295 .IX Subsection "file_ext"
 296 The is the suggested file name extention for a file of the given
 297 file format.  The value is a 3 letter, lowercase string like
 298 "\f(CW\*(C`png\*(C'\fR\*(L", \*(R"\f(CW\*(C`jpg\*(C'\fR".
 299 .Sh "color_type"
 300 .IX Subsection "color_type"
 301 The value is a short string describing what kind of values the pixels
 302 encode.  The value can be one of the following:
 303 .PP
 304 .Vb 7
 305 \&    Gray
 306 \&    GrayA
 307 \&    RGB
 308 \&    RGBA
 309 \&    CMYK
 310 \&    YCbCr
 311 \&    CIELab
 312 .Ve
 313 .PP
 314 These names can also be prefixed by "\f(CW\*(C`Indexed\-\*(C'\fR\*(L" if the image is
 315 composed of indexes into a palette.  Of these, only \*(R"\f(CW\*(C`Indexed\-RGB\*(C'\fR" is
 316 likely to occur.
 317 .PP
 318 (It is similar to the \s-1TIFF\s0 field PhotometricInterpretation, but this
 319 name was found to be too long, so we used the \s-1PNG\s0 inpired term
 320 instead.)
 321 .Sh "resolution"
 322 .IX Subsection "resolution"
 323 The value of this field normally gives the physical size of the image
 324 on screen or paper. When the unit specifier is missing then this field
 325 denotes the squareness of pixels in the image.
 326 .PP
 327 The syntax of this field is:
 328 .PP
 329 .Vb 3
 330 \&   <res> <unit>
 331 \&   <xres> "/" <yres> <unit>
 332 \&   <xres> "/" <yres>
 333 .Ve
 334 .PP
 335 The \f(CW\*(C`<res>\*(C'\fR, \f(CW\*(C`<xres>\*(C'\fR and \f(CW\*(C`<yres>\*(C'\fR fields are
 336 numbers.  The \f(CW\*(C`<unit>\*(C'\fR is a string like \f(CW\*(C`dpi\*(C'\fR, \f(CW\*(C`dpm\*(C'\fR or
 337 \&\f(CW\*(C`dpcm\*(C'\fR (denoting "dots per inch/cm/meter).
 338 .Sh "SamplesPerPixel"
 339 .IX Subsection "SamplesPerPixel"
 340 This says how many channels there are in the image.  For some image
 341 formats this number might be higher than the number implied from the
 342 \&\f(CW\*(C`color_type\*(C'\fR.
 343 .Sh "BitsPerSample"
 344 .IX Subsection "BitsPerSample"
 345 This says how many bits are used to encode each of samples.  The value
 346 is a reference to an array containing numbers. The number of elements
 347 in the array should be the same as \f(CW\*(C`SamplesPerPixel\*(C'\fR.
 348 .Sh "Comment"
 349 .IX Subsection "Comment"
 350 Textual comments found in the file.  The value is a reference to an
 351 array if there are multiple comments found.
 352 .Sh "Interlace"
 353 .IX Subsection "Interlace"
 354 If the image is interlaced, then this returns the interlace type.
 355 .Sh "Compression"
 356 .IX Subsection "Compression"
 357 This returns the name of the compression algorithm is used.
 358 .Sh "Gamma"
 359 .IX Subsection "Gamma"
 360 A number indicating the gamma curve of the image (e.g. 2.2)
 361 .SH "AUTHOR"
 362 .IX Header "AUTHOR"
 363 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 364 .SH "COPYRIGHT"
 365 .IX Header "COPYRIGHT"
 366 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 367 .PP
 368 This module is free software; you can redistribute it and/or
 369 modify it under the same terms as Perl itself.
 370 .SH "SEE ALSO"
 371 .IX Header "SEE ALSO"
 372 Template::Plugin, Image::Info