qooxdoo integrates the support for clipping and combining images in the framework and both features are heavily used within the framework mainly in the different themes like appearance or decoration theme.

To use the two features you have to create a config file which can be used by the generator to clip or combine images. Altough it is possible to integrate the jobs for clipping and combining in your config.json file of your application, the better way is to create an own config file for the image manipuations to separate it from the application configuration.

At the first look the configuration file for the image jobs is basically the same as a normal application configuration file.

{
  // IMAGE CLIPPING AND COMBINING JOBS
  "jobs" :
  {
    "common" :
    {
      "let" :
      {
         "RESPATH" : "./source/resource/APPLICATION_NAME"
      },
 
      "cache" :
      {
         // path to your cache folder
         "compile" : "../../cache"
      }
  }
}

The described common is used to setup the basic settings which are used by the specific jobs image-clipping and image-combine which are described at the following sections.

Clipping images is needed whenever you have a base image, e.g. a complete image for your button with rounded borders, to strip them into several parts.

"image-clipping" :
{
   "extend" : ["common"],
 
   "slice-images" :
   {
      "images" :
      {
         // IMAGES TO CLIP - example
         "${RESPATH}/image/source/groupBox.png" :
         {
            "prefix" : "${RESPATH}/image/clipped/groupBox",
            "border-width" : 4
         }
      } 
   }
}

Each entry in the images block represents one source image to clip.

• value of the key has to be the path to this image
• the prefix entry will set the filename for all of your splitted images. The resulting images will follow the rule prefix+imagepart where imagepart will be e.g. tl or br (for top-left and bottom-right)
• the entry border-width is to define the part of the image which the rounded border occupies. If you look at your baseImage you can determine the “border-width” by select a rectangle (which your graphic tool) which occupies the rounded border completely

For the case border-width: One image says more than thousand words :)

The selection rectangle has the size of 4 x 4 pixels, thus the border-width value of 4.

Opposite to image clipping the image combining takes multiple images as source and generates one combined image out of them.

"image-combine" :
{
   "extend" : ["common"],
 
   "combine-images" :
   {
      "images" :
      {
         // combined images
         "${RESPATH}/image-combined/combined.png":
         {
            "input"  :
            [
               "${RESPATH}/image/clipped/groupBox*.png"
           ],
           "layout" : "vertical"
         }
      }
   }
}

Basically the structure is the same as for the image-clipping jobs. Let’s take a look at the details.

• value of the key has to the path of the combined image to create
• input is an array which takes the several images to combine as arguments - the use of wildcards like * or [tb] are allowed
• the layout key takes the two possible values horizontal or vertical and determines the alignment of the source images inside the combined images

If you are finished with the definition of your images to clip and/or to combine you can use the generator to actually let them created for you.

./generator -c image.json image-clipping

./generator -c image.json image-combine

If you include the following job in your image.json jobs list

"images" :
{
   "run" : [ "image-clipping", "image-combine" ]
},

the execution of

./generator -c image.json images

will run both jobs at once.

There are several benefits for setting the image clipping and combining up

• less HTTP requests meaning better performance when using combined images
• widgets using the grid decorator are easier to use. If you do not use clipping you have to slice the baseImage and name the parts manually
• state changes are faster with combined images as the browser does not have to change the source if the displayed image. Instead he only changes the value of the CSS property background-position to display the desired part of the combined image