GPL_bin_fullset/NaturalDocs/Modules/NaturalDocs/Project/ImageFile.pm

   1 ###############################################################################
   2 #
   3 #   Class: NaturalDocs::Project::ImageFile
   4 #
   5 ###############################################################################
   6 #
   7 #   A simple information class about project image files.
   8 #
   9 ###############################################################################
  10
  11 # This file is part of Natural Docs, which is Copyright © 2003-2010 Greg Valure
  12 # Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
  13 # Refer to License.txt for the complete details
  14
  15 use strict;
  16 use integer;
  17
  18 package NaturalDocs::Project::ImageFile;
  19
  20
  21
  22 ###############################################################################
  23 # Group: Implementation
  24
  25 #
  26 #   Constants: Members
  27 #
  28 #   The class is implemented as a blessed arrayref.  The following constants are used as indexes.
  29 #
  30 #       LAST_MODIFIED - The integer timestamp of when the file was last modified.
  31 #       STATUS - <FileStatus> since the last build.
  32 #       REFERENCE_COUNT - The number of references to the image from the source files.
  33 #       WAS_USED - Whether the image was used the last time Natural Docs was run.
  34 #       WIDTH - The image width.  Undef if can't be determined, -1 if haven't attempted to determine yet.
  35 #       HEIGHT - The image height.  Undef if can't be determined, -1 if haven't attempted to determine yet.
  36 #
  37
  38 use NaturalDocs::DefineMembers 'LAST_MODIFIED', 'LastModified()', 'SetLastModified()',
  39                                                  'STATUS', 'Status()', 'SetStatus()',
  40                                                  'REFERENCE_COUNT', 'ReferenceCount()',
  41                                                  'WAS_USED', 'WasUsed()', 'SetWasUsed()',
  42                                                  'WIDTH', 'Width()',
  43                                                  'HEIGHT', 'Height()';
  44
  45
  46 #
  47 #   Topic: WasUsed versus References
  48 #
  49 #   <WasUsed()> is a simple true/false that notes whether this image file was used the last time Natural Docs was run.
  50 #   <ReferenceCount()> is a counter for the number of times it's used *this* run.  As such, it starts at zero regardless of whether
  51 #   <WasUsed()> is set or not.
  52 #
  53
  54
  55 ###############################################################################
  56 # Group: Functions
  57
  58 #
  59 #   Function: New
  60 #
  61 #   Creates and returns a new file object.
  62 #
  63 #   Parameters:
  64 #
  65 #       lastModified - The image file's last modification timestamp
  66 #       status - The <FileStatus>.
  67 #       wasUsed - Whether this image file was used the *last* time Natural Docs was run.
  68 #
  69 sub New #(timestamp lastModified, FileStatus status, bool wasUsed)
  70     {
  71     my ($package, $lastModified, $status, $width, $height, $wasUsed) = @_;
  72
  73     my $object = [ ];
  74     $object->[LAST_MODIFIED] = $lastModified;
  75     $object->[STATUS] = $status;
  76     $object->[REFERENCE_COUNT] = 0;
  77     $object->[WAS_USED] = $wasUsed;
  78     $object->[WIDTH] = -1;
  79     $object->[HEIGHT] = -1;
  80
  81     bless $object, $package;
  82
  83     return $object;
  84     };
  85
  86
  87 #
  88 #   Functions: Member Functions
  89 #
  90 #   LastModified - Returns the integer timestamp of when the file was last modified.
  91 #   SetLastModified - Sets the file's last modification timestamp.
  92 #   Status - Returns the <FileStatus> since the last build.
  93 #   SetStatus - Sets the <FileStatus> since the last build.
  94 #
  95
  96 #
  97 #   Function: ReferenceCount
  98 #   Returns the current number of references to this image file during *this* Natural Docs execution.
  99 #
 100
 101 #
 102 #   Function: AddReference
 103 #   Increases the number of references to this image file by one.  Returns the new reference count.
 104 #
 105 sub AddReference
 106     {
 107     my $self = shift;
 108
 109     $self->[REFERENCE_COUNT]++;
 110     return $self->[REFERENCE_COUNT];
 111     };
 112
 113 #
 114 #   Function: DeleteReference
 115 #   Decreases the number of references to this image file by one.  Returns the new reference count.
 116 #
 117 sub DeleteReference
 118     {
 119     my $self = shift;
 120     $self->[REFERENCE_COUNT]--;
 121
 122     if ($self->[REFERENCE_COUNT] < 0)
 123         {  die "Deleted more references to an image file than existed.";  };
 124
 125     return $self->[REFERENCE_COUNT];
 126     };
 127
 128
 129 #
 130 #   Functions: Member Functions
 131 #
 132 #   WasUsed - Returns whether this image file was used during the *last* Natural Docs execution.
 133 #   SetWasUsed - Sets whether this image file was used during the *last* Natural Docs execution.
 134 #   Width - Returns the width in pixels, undef if it can't be determined, and -1 if determination hasn't been attempted yet.
 135 #   Height - Returns the width in pixels, undef if it can't be determined, and -1 if determination hasn't been attempted yet.
 136 #
 137
 138
 139 #
 140 #   Function: SetDimensions
 141 #   Sets the width and height of the image.  Set to undef if they can't be determined.
 142 #
 143 sub SetDimensions #(int width, int height)
 144     {
 145     my ($self, $width, $height) = @_;
 146
 147     # If either are undef, both should be undef.  This will also convert zeroes to undef.
 148     if (!$width || !$height)
 149         {
 150         $self->[WIDTH] = undef;
 151         $self->[HEIGHT] = undef;
 152         }
 153     else
 154         {
 155         $self->[WIDTH] = $width;
 156         $self->[HEIGHT] = $height;
 157         };
 158     };
 159
 160
 161 1;