[prev] Using the Menu Editor [up] Programming Tools [next] Using the Help Tool
 

Using the Image Editor

Index


Introduction

The ST/X Image Editor allows you to define bitmap images - especially (but not limited to) for use with the following widgets: and also (indirectly, via a LabelAndIcon instance), for: and finally, for: The Image Editor can store the image either outside of the Smalltalk world in a file (gif, tiff, png, and many other formats) or inside Smalltalk as a resource method (typically in the "image specs" protocol as a class method). When invoked, this resource method will answer with a bitmap image, which is an instance of a subclass of the "Image" class. The use of resource methods is recommended, because it makes the deployment/installation process easier, because all required images will be already contained in the executable.

Commonly used and sharable images are found in the GenericToolbarIconLibrary-class and its view-style specific subclasses. Notice that the global variable ToolbarIconLibrary is dynamically rebound to one of the concrete libraries, depending on the view style.

Image resource methods are usually invoked during the setup of an application instance, if an image has been specified for one of the above listed widgets. (for example, for a Label-widget, if the labelIsImage flag must be turned on).

For enhanced performance, the generated resource methods remember their generated bitmap image objects in a cache (a dictionary inside the Icon class). When first invoked, the image is created from bitmap information and cached for further calls. Be sure to flush this cache, if an image-resource method is modified by hand and recompiled (the imageEditor does this automatically for you, when an image is saved).
To avoid large ST/X snapshot images (not to confuse with bitmap-images), all cached bitmap images are deleted from this cache, whenever an ST/X-snapshot image file is saved.

A typical resource method looks like:

newImageIcon
    "Generated by the Image Editor"

    "ImageEditor openOnClass:self andSelector: #newImageIcon"

    <resource: #image>

    ^Icon
        constantNamed:#'ImageEditor newImageEditor'
        ifAbsentPut:[(Depth4Image new) width: 22 height: 22; etc.]
Here, #'ImageEditor newImageEditor' is the identifier (key) for the cache dictionary, and the value in brackets represents the bitmapImage.

Warning:
If you manually copy-paste such a resource method's code, do not forget to modify this key in the source code. Otherwise, the cache slot will be overwritten by the other image. Alternatively, open an image editor on the method's image, and save the image back into the resource method.


Starting the Image Editor

There are multiple ways to start the Image Editor:
  1. by pressing the   Start Image Editor Button -button in the toolbar or selecting the Tools/Image Editor menu item in the launcher
  2. by pressing the Image Editor-button in the Image section of the Menu Editor
  3. by double-clicking on an image resource method in a System Browser (those are marked with an  An icon representing an image resource method icon)
  4. by evaluating one of
 After startup, an Image Editor appears as shown in the next figure:

A View of a Image Editor


Image editors also appear as embedded editor in the new system browser, when the "Use Embedded Editors" option flag is enabled AND an image resource method has been selected.

Drawing in the Image Editor

Drawing is done by pressing a mouse button in the right draw area and moving the mouse while keeping the button pressed. All area functions show a frame rectangle and actually performed the operaion when you release the mouse button. Pressing the ESCAPE-key while still holding down the mouse button aborts a current draw operation. Also, the last few drawing operations can be undone by the toolbars "undo" function. The kind of draw function is selected by the "drawing mode". This can be changed either via the main menu, or one of the mode buttons in the vertical mode toolbar.

Notice that both the first and the second mouse button can be used for drawing. Each has its own assigned drawing color, which is specified by selecting one of the colors in the colormap (select the button which is to be affected using one of the mouse-button icons above the color list).

Edit Modes

The behavior of the editor when clicking in the drawing area is determined by the current edit mode, which is selected via the vertical bar (to the left of the drawing area) or the main menu. View of a Pixel Edit Functions Panel (outdated)

Menu & Toolbar Functions

Functions are grouped as usual into submenus. The most often used functions are also available as toolbar buttons.

Basic Load and Save Functions

Menu Button Description
New Image Editor Opens another Image Editor (useful to merge multiple images into one). 
New... Opens a dialog with choices of size and color depth to create a new image. 
New From Clipboard Loads the image contained in the clipBoard (see "Copy to ClipBoard" below). 
Load... Opens a dialog for selecting and loading an image from a resource method of a class.
Load from File... Opens a dialog for selecting and loading an image from a file.
Grab from Screen Lets you pick a rectangular area on the screen.
Save Saves the image as resource method in the current class and selector. 
Save As... Asks for class and selector and saves the image as resource method. 
Save to File... Asks for fileName and saves the image into it (*). 
Save Mask to File... Asks for fileName and saves the image's mask only into it. 
Copy to ClipBoard Saves the image in the clipBoard (see "New from ClipBoard" above). 
 
(*)
The file's extension determins its format. Currently supported are tiff, png, gif, bmp, xbm and xpm.

Edit Functions

Edit Menu Description
Undo Undo the last action.
Resize... Opens a dialog to resize the image.
If its made larger, the new area will be empty,
If its made smaller, the area will be chopped off.
Magnify... Opens a dialog to magnify/shrink the image to a desired size.
Magnify By... Opens a dialog to magnify/shrink the image by a factor.
Rotate... Opens a dialog to rotate the image in degrees.
Flip Flips the image vertically or horizontally.
Invert Inverts the image (black/white).
Brighten Brightenes the image.
Darken Darkenes the image.
Crop... Cut off margins of the image.
You may either manually specify the number of pixels
which are to be chopped off,
or use the autocrop function, which detects margins
consisting of constant color.
The autocrop function is useful to remove frames around
images.
Uncrop... Add a margin to the image.
Shift... Opens a dialog to shift/rotate pixels horizontally or vertically.
Edit Mask Opens another Image Editor on the mask-plane alone.
Text Render a text-string into the image.
Next in Sequence Edit the next image in an animated gif's image sequence.
Previous in Sequence Edit the previous image in an animated gif's image sequence.
Edit each in Sequence For each individual image in the image sequence, an extra editor is opened.

Drawing-Mode SelectionMenu

See "Edit Modes" paragraph above.

Colormap and Image Manipulating Functions

Colormap functions only work for images which have a colormap (up to 8bit palette images). These do not change any pixel value, but instead manipulate the colormap. The image manipulation functions also work for images which have no colormap (24bit rgb images).
Colors-Depth Menu Description
Depth - n-Plane Converts the image to an n-plane colormap image.
You will get a warnBox, if the number of colors
exceeds the available number of colorMap slots.
Depth - n-Plane + Mask Converts the image to an n-plane colormap image
with an additional mask plane (transparent pixels).
You will get a warnBox, if the number of colors
exceeds the available number of colorMap slots.
Colors-Colormap Menu Description
Compress ColorMap Removes unneeded colors from the colorMap.
Sort ColorMap Sorts the colorMap by red-green-blue.
Reduce number of colors by rounding Reduces color resolution.
You will be asked for nearest r/g/b component
values, to which colors will be rounded.
This is useful when 24bit images are to be converted to
n-plane palette images.
Reduce number of colors by masking Reduces color resolution.
You will be asked for the number bits which are
to be stripped off.
This is useful when 24bit images are to be converted to
n-plane palette images.
Dither to Depth Using a standard color cube, generate a dithered
version of the image with reduced depth.
Brighten Change the colormap to make the image brighter.
Darken Change the colormap to make the image darker.
Invert Change the colormap to invert the image
(this usually only makes sense for b&w or greyscale) images.
Colors-Edit Menu Description
Convert to Greyscale Converts the image to a greyscale image.
Brighten Change the pixel values to make the image brighter.
Darken Change the pixel values to make the image darker.
Invert Change the pixel values to invert the image
(this usually only makes sense for b&w or greyscale) images.
Change Hue/Light/Saturation Change the pixel values to shift the images h/l/s
within the color wheel. Can be used to change
the images overall color appearance.
(for example: make a green lamp from a red one.)
Colors-Mask Menu Description
Copy Mask Copy the mask to the clipboard.
Paste Mask Paste the mask from the clipboard.
Clear Masked Pixels Clear all masked pixels to a pixelvalue of 0.
Clear Colormap Entry for Masked Pixels Clear all masked pixels to a pixelvalue of 0
and make sure that a black color is located at the
colormap entry for 0. This is required for the
win32 operating system's window icons.
 

Mouse Button Functions

The View of a Mouse Button Functions Panel

The mouse buttons are used for image modification (default: pixel drawing). For both left and right mouse buttons, a separate color can be defined. By switching the toggle menu items ColorMap-Left/Right-Mouse-Button, the drawing color of the button can be seen and defined.

You can also pick a color in the edited image, by clicking into the magnified image view while holding down the SHIFT-key.
 

The Color Map

A View of a Color Map Table

The set of colors which are used by a bitmap image are held in the images color map. Depending on the size of the colormap, different classes are used to represent the image Only bitmaps with a depth up to 8 do actually have a colormap, Wide bitmaps (i.e. with 16, 24 or 32 bits per pixel) can also be shown and edited; however, these do not have a colormap. Instead, the pixels of the image directly define the r/g/b values of a pixel's color.
 
 Color Depth (bits per pixel)   Number of Colors   Real Class
  1  1 -   2  Depth1Image 
 2  1 -   4  Depth2Image 
 4  1 -  16  Depth4Image 
 8  1 - 256  Depth8Image 
The colormap provides its own popupMenu with functions to add/remove or edit colormap entries.

The Image class is an abstract class. Depending on the size of the colormap, instances of one of the Depth*Image classes are used to represent the real image.

Adding a Color

After loading an image, the color map table only shows its used colors. In order to use a color which is not available in the color map, you have to increase the images depth by selecting one of the items from the Color Map menu.
You may also reduce the colormap size, by selecting a smaller depth from the menu - however, if the number of colors exceeds the colormaps size, colors will be lost and the image may not look as expected afterwards.

Defining your own initial colormap

The colormap of a new image is defined by the Image Editor's listOfColorMaps class method. This method can be redefined if you prefer some other default colormap.
 

The Image Mask

The mask of an image defines which pixels are painted as opposed to being transparent.
Technically, the mask is another (depth1 / monochrome) image, where each black pixel makes the corresponding pixel of the actual image invisible (i.e. transparent).

All pixel edit functions treat the mask color like any other ordinary color. In the color map, the mask color is always the first entry (if defined).
 

Picking a color for drawing

Press the SHIFT-Key while clicking on a pixel in the drawing area, in order to pick a color for drawing.

Limitations and Bugs

Notice - after all, this was written as an icon-editor - not as a general image manipulation program. For real image processing, we recommend tools like gimp, photoshop or a bitmap editor like ms-paint.

Special Notes for Icons under Windows

Under win32, images which are to be used as a window-icon must have a black color as their first palette color Otherwise, masked pixels will not be transparent, and the window decoration and taskbar icons might look wrong.

So, to prevent this, make sure that:

  1. the palette contains a black color
    (if required, add a color to the palette)

  2. the palette is sorted, so that the black color is the first in the palette
    (if required, sort the colors using the corresonding menu function)

  3. masked pixels have a 0 (zero) pixel value
    (if required, clear masked pixels using the corresonding menu function)
All of the above is now performed by a single menu function: "Set Masked Pixels to 0->0/0/0" in the "Colors"-"Mask" menu.


[stx-logo]
Copyright © 1998-2009 eXept Software AG, all rights reserved


Doc $Revision: 1.33 $ $Date: 2016/09/14 09:41:13 $