diff options
Diffstat (limited to 'doc/DwImage.txt')
| -rw-r--r-- | doc/DwImage.txt | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/doc/DwImage.txt b/doc/DwImage.txt new file mode 100644 index 00000000..d79f50bf --- /dev/null +++ b/doc/DwImage.txt @@ -0,0 +1,201 @@ +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 +================= + +(See also Imgbuf.txt, what is named DilloImageBuffer here, has been +implemented under the name Imgbuf.) + +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. |