Author: Harald Oehlmann <[email protected]>
State: Draft
Type: Project
Created: 04-Mar-2025
Tcl-Version: 9.1
Tk-Branch: tip-714-alt
Keywords: photo
Abstract
This TIP proposes to add an information command for image types, which returns an information dict. In case of the photo image handler, the format list is returned.
Background
The original request is this Tk ticket 1441f8. A practical application of the proposed image types photo command is as follows. The list of photo image formats is used to filter supported image file types in a file search box file type choice:
set formatlist [dict get [image types photo] file]
set filetypelist {}
foreach format $formatlist {
lappend filetypelist [list $format .$format]}
}
tk_getOpenFile -filetypes $filetypelist
Another application is performance. The photo handler will test the given data for any format, if no -format option is given. Using this option, a format option may be created on run-time. If no format is available, an error message may be issued.
The 3rd application is to avoid the handling of image data by the default handler. If no other handler takes the data, the default handler is always used. Then, the data is seen as a tcl list, which often leads to strange error messages or corrupt images.
Rationale
The application of this communication possibility is to query the list of supported photo formats in the processing order.
Specification
script level
The command image types is extended by a new optional parameter type:
image types ?type?
It type is given, the information dict for this image type is returned. If type is not given, the current behaviour of returning the registered image types remain.
In a Tk standard installation, the command result is as follows for the photo image type:
% image types photo
format {svg ppm png gif default} file {svg ppm png gif} write {ppm png gif}
photo image handler return value
The photo image handler returns a dict with the following keys:
- format: list of registered photo formats in the search order (if -format is not given to a photo image).
- read: like format, but only formats with file read capability.
- write: like format, but only formats with file write capability.
proposed C interface
If a photo type handler wishes to return an information dict, it should do:
- call Tk_CreateImageType for its registration as image type
- call the new API Tk_SetTypeInfoProc to register a photo info proc.
Example from "generic/tkWindow.c":
Tk_CreateImageType(&tkPhotoImageType);
Tk_SetTypeInfoProc(&tkPhotoImageType, TkPhotoInfoProc);
The new API function has the following signature:
Tk_SetTypeInfoProc(Tk_ImageType *typePtr, Tk_ImageInfoProc *typeInfo)
where the passed typeInfo procedure has the following prototype:
int Tk_ImageInfoProc(Tcl_Interp *interp);
The registered typeInfo function should set the interpreter result of the passed interp and return a standard TCL result. This result is the result of the script level command.
Compatibility
Fully backward compatible.
Discussion
Registered structure extension or new callback?
There are two proposals to pass the function pointer Tk_ImageInfoProc for the format information dict from the image type handler to Tk:
- use a new registration function Tk_SetTypeInfoProc, after the other function pointers were passed by Tk_CreateImageType. This method is described in this TIP and implemented in the solution branch.
- extend the list of the function pointers passed by Tk_CreateImageType passes the function pointer as all the other pointers. This method is implemented in the older branch tip-714-image-driver-info. There is anyway a reserved member which may be used for this.
The advantage of the first method is, that there are no backward compatibilities. The advantage of the second method is that we have the same interface for all function pointers. This makes also the internal structure of Tk easier avoiding a hash table in the thread specific data.
Note: the functionality of the implementation should be as described here (extend image types and don't pass arguments, return a dict) and not as implemented in the branch tip-714-image-driver-info.
Reference Implementation
A reference impementation can be found in Tk branch tip-714-image-driver-info.
Copyright
This document has been placed in the public domain.