Jan 2001, S.Geerken@ping.de
Last update: Dec 2004
=======
DwImage
=======
A widget for displaying images and handling image maps.
Image Maps
==========
Client Side Image Maps
----------------------
You must first create a list of image maps: Allocate a DwImageMapList,
and initialize it by calling a_Dw_image_map_list_init. Adding a map is
done by a_Dw_image_map_list_add_map. a_Dw_image_map_list_add_shape
adds a shape to the last map. For the meaning of the link argument,
see Section "Signals".
Image maps are referred by a URL (not only by a name). But currently,
the image map list is stored in DilloHtmlLB and there is no
possibility to parse documents without rendering, so images can only
use maps defined in the same document.
To use a map in an image, call a_Dw_image_set_usemap with the image,
the map list, and the URL of the map. Passing the whole list makes it
possible to use maps parsed after the image is created.
Server Side Image Maps
----------------------
To use images for server side image maps, you must call
a_Dw_image_set_ismap and the style must contain a valid link
element. See section "Signals" for more details.
Signals
=======
There are five signals, which can be connected to process actions with
links. All have at least three arguments:
- link is the link element of the DwStyle (server side image maps)
or DwImageMapShape (client side image maps). The value is an
integer, which is currently only used for hypertext links. But
generally, it depends on the signal callback how this value is
used.
- x and y are, when server side image maps are used, the relative
coordinates of the mouse pointer, otherwise always -1.
Note that, unlike by DwPage before, no cursors are set. Instead, the
signal callback function has to do this.
The signals:
- void link_entered (DwImage *image,
gint link, gint x, gint y)
Emitted when the link the mouse pointer is over has
changed. "Changed" includes link, x and y, so this signal is also
emitted each time the pointer is moved within a server side image
map. If the pointer is outside of a link, all arguments have the
value -1.
- void link_pressed (DwImage *image,
gint link, gint x, gint y,
GdkEventButton *event)
Emitted when the user presses a mouse button _inside_ a link,
this signal is never emitted with link = -1. You can use the
event to get information about the button, shift keys, etc.
- void link_released (DwImage *image,
gint link, gint x, gint y,
GdkEventButton *event)
- void link_clicked (DwImage *image,
gint link, gint x, gint y,
GdkEventButton *event)
Analogue to link_pressed.
- void void (*image_pressed) (DwImage *page,
GdkEventButton *event)
Emitted when the user presses the mouse button on an image which
has no related map. In some cases, it may be neccessary to
suppress event processing by a_Dw_widget_set_button_sensitive().
Future Extentions
=================
These are some ideas for a different design, which will solve several
problems (image transparency, memory usage when implementing a global
size factor):
1. Instead of a guchar array, a new data type, DilloImageBuffer,
should be used (DICacheEntry::ImageBuffer and DwImage::buffer). Any
access is done by function calls. Copying the lines (in
a_Image_write) is done by a_Image_buffer_copy_line, etc. The call to
Image_line becomes obsolete, since DilloImageBuffer will deal with
different types: indexed, RGB, gray, RGBA, gray-alpha(?). This may
be useful for a more efficient implementation of DilloImageBuffer.
2. The modules Png, Jpeg, Gif, Image and DICache deal with the
original image size (read by the decoders), while DwImage gets the
"viewed" size (original size, multiplied by the global image
scaling factor) from DilloImageBuffer.
3. For DwImage, there are further methods which replace the current
direct access. Note to worth:
- Scaled buffers are shared, reference counters are used. Copying
rows will automatically also affect the related scaled buffers.
- There are two methods for drawing, one called after expose events
(Dw_image_draw) and another called by a_Dw_image_draw_row. The
exact rules, how the buffer is scaled (this can, e.g., differ by a
pixel or so), is hidden by DilloImageBuffer.
- As noted above, all DwImage code is based on the viewed size.
4. The global image scaling factor is used in two places. The HTML
parser must apply it on the WIDTH and HEIGHT attributes of the
<IMG> tag and DilloImageBuffer must use it to scale the inherent
size of an image. There are two modes, which the user can switch
by a dillorc option:
(i) The original image data is preserved, and an additional scaled
buffer is created:
+-------+ +------------------+ additional
| Image | -- copy --> | DilloImageBuffer | --> scaled
+-------+ rows | (original size) | buffers
+------------------+
| ^
| |
scale requests
each row for scaled
| buffers
| |
v |
+------------------+
| DilloImageBuffer |
| (viewed size) |
+------------------+
^
|
+---------+
| DwImage |
+---------+
(ii) The original data gets lost just after scaling:
+-------+ +------------------+
| Image | -- copy --> | DilloImageBuffer | --> scaled
+-------+ rows | (viewed size) | buffers
+------------------+
^
|
+---------+
| DwImage |
+---------+
(ii) uses generally less memory, while in some cases leads to a
lower rendering quality, as in this example:
"foo.png" has a size of 100x100 pixels, the image scaling factor is
50%, and the following HTML sniplet is rendered:
<img src="foo.png">
<img src="foo.png" width=200 height=200>
The first image is displayed at a size of 50x50, the second at
100x100. (i) will, for the second, use the original buffer, but
(ii) will enlarge the buffer, which was scaled down before, so
resulting in a "pixelized" image.
5. Any implementation of DilloImageBuffer will handle transparency
independent of the background, i.e., the background colour will not
be used anymore. The first implementation may be based on GdkRGB
and (when needed) dithered clipping bitmaps. Better implementations
may then be developed in the future.
6. Background images: The modules Image and DICache do no longer
access the DwImage directly, all calls are replaced by an
Interface, which is then implemented by DwImage and an appropriate
structure for background images (part of DwStyle). The interface is
in C realized by a struct of function pointers, and a generic
pointer on DwImage, etc.
7. If someone really needs it, animated GIF's may be considered.