← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/spriteutils.py

  • Committer: Edwin Grubbs
  • Date: 2010-02-08 22:26:54 UTC
  • mto: This revision was merged to the branch mainline in revision 10304.
  • Revision ID: edwin.grubbs@canonical.com-20100208222654-tmj5ivq33mozsmnn
Added docstrings and moved more code into SpriteUtil.__init__().

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/spriteutils.py
28
28
        /* It is autogenerated by spriteutils. */
29
29
        """)
30
30
 
31
 
    def __init__(self, margin=150):
32
 
        self.sprites = None
 
31
    def __init__(self, css_template_file, group_name,
 
32
                 url_prefix_substitutions=None, margin=150):
 
33
        """Initialize with the specified css template file.
 
34
 
 
35
        :param css_template_file: (str) Name of the file containing
 
36
 
 
37
            css rules with a background-image style that needs to be
 
38
            combined into the sprite file, a comment allowing sprites to
 
39
            be grouped into different image files, and a
 
40
            background-repeat style if necessary. Currently, "repeat-y"
 
41
            is not supported since the file is combined vertically, so
 
42
            repeat-y would show the entire combined image file.
 
43
 
 
44
            Example css template:
 
45
                edit-icon {
 
46
                    background-image: url(../edit.png)
 
47
                    /* sprite-ref: group1 */
 
48
                }
 
49
                blue-bar {
 
50
                    background-image: url(../blue-bar.png)
 
51
                    /* sprite-ref: group1 */
 
52
                    background-repeat: repeat-x
 
53
                }
 
54
 
 
55
        :param group_name: (str) Only add sprites to the
 
56
            combined image file whose sprite-ref comment in the
 
57
            css template match this group-name.
 
58
 
 
59
        :param url_prefix_substitutions: (dict) The css template
 
60
            will contain references to image files by their url
 
61
            path, but the filesystem path relative to the css
 
62
            template is needed.
 
63
 
 
64
        :param margin: (int) The number of pixels between each sprite.
 
65
            Be aware that Firefox will ignore extremely large images,
 
66
            for example 64x34000 pixels.
 
67
 
 
68
        If the css_template_file has been modified, a new
 
69
        css file using an existing combined image and positioning
 
70
        file can be generated using:
 
71
            sprite_util = SpriteUtil(...)
 
72
            sprite_util.loadPositioning(...)
 
73
            sprite_util.saveConvertedCSS(...)
 
74
 
 
75
        If a new image file needs to be added to the combined image
 
76
        and the positioning file, they can be regenerated with:
 
77
            sprite_util = SpriteUtil(...)
 
78
            sprite_util.combineImages(...)
 
79
            sprite_util.savePNG(...)
 
80
            sprite_util.savePositioning(...)
 
81
 
 
82
        If the image file is regenerated any time the css file is
 
83
        regenerated, then the step for saving and loading the positioning
 
84
        information could be removed. For example:
 
85
            sprite_util = SpriteUtil(...)
 
86
            sprite_util.combineImages(...)
 
87
            sprite_util.savePNG(...)
 
88
            sprite_util.saveConvertedCSS(...)
 
89
        """
33
90
        self.combined_image = None
34
91
        self.positions = None
35
 
        self.css_object = None
36
 
        self.margin=margin
 
92
        self.group_name = group_name
 
93
        self.margin = margin
 
94
        self._loadCSSTemplate(
 
95
            css_template_file, group_name, url_prefix_substitutions)
37
96
 
38
 
    def loadCSSTemplate(self, css_file, group_name,
 
97
    def _loadCSSTemplate(self, css_template_file, group_name,
39
98
                        url_prefix_substitutions=None):
 
99
        """See `__init__`."""
40
100
        smartsprites_exp = re.compile(
41
101
            r'/\*+([^*]*sprite-ref: [^*]*)\*/')
42
 
        self.css_object = cssutils.parseFile(css_file)
43
 
        sprites = []
 
102
        self.css_object = cssutils.parseFile(css_template_file)
 
103
        self.sprites = []
44
104
        for rule in self.css_object:
45
105
            if rule.cssText is None:
46
106
                continue
51
111
                if parameters['sprite-ref'] == group_name:
52
112
                    filename = self._getSpriteImagePath(
53
113
                        rule, url_prefix_substitutions)
54
 
                    sprites.append(dict(filename=filename, rule=rule))
55
 
        self.sprites = sprites
56
 
        self.group_name = group_name
 
114
                    self.sprites.append(dict(filename=filename, rule=rule))
57
115
 
58
116
    def _getSpriteImagePath(self, rule, url_prefix_substitutions=None):
 
117
        """Convert the url path to a filesystem path."""
59
118
        # Remove url() from string.
60
119
        filename = rule.style.backgroundImage[4:-1]
61
120
        # Convert urls to paths relative to the css
67
126
        return filename
68
127
 
69
128
    def _parseCommentParameters(self, parameter_string):
 
129
        """Parse parameters out of javascript comments.
 
130
 
 
131
        Currently only used for the group name specified
 
132
        by "sprite-ref".
 
133
        """
70
134
        results = {}
71
135
        for parameter in parameter_string.split(';'):
72
136
            if parameter.strip() != '':
77
141
        return results
78
142
 
79
143
    def combineImages(self, css_dir):
 
144
        """Copy all the sprites into a single PIL image."""
80
145
        for sprite in self.sprites:
81
146
            filename = os.path.join(css_dir, sprite['filename'])
82
147
            sprite['image'] = Image.open(filename)
128
193
        self.combined_image = combined_image
129
194
 
130
195
    def savePNG(self, filename):
 
196
        """Save the PIL image object to disk."""
131
197
        self.combined_image.save(filename, format='png', optimize=True)
132
198
 
133
199
    def savePositioning(self, filename):
 
200
        """Save the positions of sprites in the combined image.
 
201
 
 
202
        This allows the final css to be generated after making
 
203
        changes to the css template without recreating the combined
 
204
        image file.
 
205
        """
134
206
        fp = open(filename, 'w')
135
207
        fp.write(self.EDIT_WARNING)
136
208
        simplejson.dump(self.positions, fp=fp, indent=4)
137
209
 
138
210
    def loadPositioning(self, filename):
 
211
        """Load file with the positions of sprites in the combined image."""
139
212
        json = open(filename).read()
140
213
        # Remove comments from the beginning of the file.
141
214
        start = json.index('{')
142
215
        json = json[start:]
143
216
        self.positions = simplejson.loads(json)
144
217
 
145
 
    def saveConvertedCSS(self, css_file, combined_image_file):
 
218
    def saveConvertedCSS(self, css_file, combined_image_url_path):
 
219
        """Generate new css from the template and the positioning info.
 
220
 
 
221
        Example css template:
 
222
            background-image: url(../edit.png); /* sprite-ref: group1 */
 
223
        Example css output:
 
224
            background-image: url(combined_image_url_path)
 
225
            background-position: 0px 2344px
 
226
        """
146
227
        for sprite in self.sprites:
147
228
            rule = sprite['rule']
148
 
            rule.style.backgroundImage = 'url(%s)' % combined_image_file
 
229
            rule.style.backgroundImage = 'url(%s)' % combined_image_url_path
149
230
            position = self.positions[sprite['filename']]
150
231
            rule.style.backgroundPosition = '%dpx %dpx' % tuple(position)
151
232