1ico(n)                       Windows ICO handling                       ico(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       ico - Reading and writing windows icons
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require ico  ?1.0?
14
15       ::ico::icons file ?option value...?
16
17       ::ico::iconMembers file name ?option value...?
18
19       ::ico::getIcon file name ?option value...?
20
21       ::ico::getIconByName file name ?option value...?
22
23       ::ico::getFileIcon file ?option value...?
24
25       ::ico::writeIcon file name depth data ?option value...?
26
27       ::ico::copyIcon file index file2 index2 ?option value...?
28
29       ::ico::EXEtoICO file ?dir?
30
31       ::ico::clearCache ?file?
32
33       ::ico::transparentColor image color
34
35       ::ico::Show file ?option value...?
36
37_________________________________________________________________
38

DESCRIPTION

40       This  package  provides functions for reading and writing Windows icons
41       from ICO, EXE, DLL, ICL, and BMP files.  As used in this module an icon
42       is  a  visual  representation of an object.  An icon consists of one or
43       more images usually with varying resolution and color depth. Each  icon
44       and  image  has  a  resource identifier which may be a text string or a
45       positive integer value. Most commands use this  identifier  to  specify
46       which icon or image to operate on.
47

API

49       ::ico::icons file ?option value...?
50              Returns  a list of icons found in file where each element is the
51              name or numeric ID. Recognizes the following options:
52
53              -type fileFormat
54
55
56       ::ico::iconMembers file name ?option value...?
57              Returns a list of images that make up the  icon  with  ID  name.
58              Each  element  is  itself  a  sublist  in the format {name width
59              height bpp}. Recognizes the following options:
60
61              -type fileFormat
62
63
64       ::ico::getIcon file name ?option value...?
65              Extracts the icon with ID name from file.  The  default  -format
66              is image which will return the name of a Tk image containing the
67              icon. The resolution and  color  depth  are  selected  with  the
68              ?-res?,  ?-bpp?,  and  ?-exact? options.  If -exact is specified
69              and there is no exact match, an  error  is  thrown.   Optionally
70              -image  may  be used to specify the name of the Tk image that is
71              created. If -format is colors then a list of color names in  the
72              #RRGGBB  format  is  returned. Each list element is a horizontal
73              row. Each horizontal row contains a list of colors for  all  the
74              pixels  in  that row from left to right. If -format is name then
75              the resource name of the image chosen is returned.  This is use‐
76              ful for calling writeIcon or getIconByName.  Recognizes the fol‐
77              lowing options.
78
79              -type fileFormat
80
81              -format value
82
83              -image value
84
85              -res value
86
87              -bpp value
88
89              -exact value
90
91
92       ::ico::getIconByName file name ?option value...?
93              Extracts the image with ID name from file. This name  should  be
94              the  name of a specific image as returned by ::ico::iconMembers,
95              not an icon name returned from  ::ico::icons.  If  there  is  no
96              matching  resource ID in file an error is thrown. Recognizes the
97              following options:
98
99              -type fileFormat
100
101              -format value
102
103
104       ::ico::getFileIcon file ?option value...?
105              This command is only functional when running under  Windows.  It
106              reads  the  Windows  registry  to determine the display icon for
107              file as it would appear in Explorer or similar.  file  does  not
108              need to exist and may also be specified as a file extension with
109              a leading dot. If file is a directory or you specify the special
110              name  Folder  then  the  icon representing a folder is returned.
111              This command takes the same arguments and usage as getIcon:
112
113              -format value
114
115              -image value
116
117              -res value
118
119              -bpp value
120
121              -exact value
122
123
124       ::ico::writeIcon file name depth data ?option value...?
125              Writes an image to file. name is the resource identifier of  the
126              image  in  file  to  write.  When writing to an EXE, DLL, or ICL
127              file you may only overwrite existing icons with an icon  of  the
128              same  dimensions and color depth. No icons may be added to these
129              file types.
130
131              When writing to BMP the name is ignored as this type can contain
132              only  one  image.  This  means if the file already existed it is
133              completely overwritten.
134
135              When writing to an ICO or ICODATA file  if  the  name  specified
136              does  not  exist then an image is appended and will be named the
137              next in sequence (the specified name is ignored). Images in  ICO
138              and  ICODATA  files may be overwritten with differing dimensions
139              or color depths.  Note that you will get  strange  results  when
140              displaying  icons  if you fail to change every image which makes
141              up a given icon.
142
143              integer depth (in)
144                     This argument must have a value of 1, 4, 8, 24, or 32. If
145                     data has more colors than the color depth allows an error
146                     will be generated.
147
148              options data (in)
149                     This argument is either a list of colors  in  the  format
150                     returned  by ::ico::getIcon -format colors or the name of
151                     a Tk image.
152
153       Recognizes the following options.
154
155              -type fileFormat
156
157
158       ::ico::copyIcon file index file2 index2 ?option value...?
159              Copies the icon at index in file to index2 in file2.
160
161              -fromtype fileFormat
162
163              -totype fileFormat
164
165
166       ::ico::EXEtoICO file ?dir?
167              Extracts all icons from the executable file to ICO files  placed
168              in dir. ?dir? defaults to the directory file is located in. Icon
169              files will be named in the form file-ID.ico where ID is the icon
170              resource identifier.
171
172              -type fileFormat
173
174
175       ::ico::clearCache ?file?
176              The  ::ico::getIconList  command caches icon offsets inside EXE,
177              DLL, ICL, and ICO files in order to speed up  extraction.   This
178              command clears that cache for the specific ?file? or all files.
179
180       ::ico::transparentColor image color
181              If  image  is a single word it is assumed to be the name of a Tk
182              image.  All pixels matching color  in  the  image  will  be  set
183              transparent.   Alternatively, image may be a color list in which
184              case a modified list is returned.
185
186       ::ico::Show file ?option value...?
187              Application level command which displays a  window  showing  all
188              the icons in file and their name.
189
190              -type fileFormat
191
192              -parent pathName
193

EXAMPLE

195           button .explore -image [::ico::getIcon explorer.exe 0 -name explore -res 16 -bpp 8]
196
197           set i [lsearch -inline [::ico::iconMembers tclkit.exe 0] {* 32 32 8}]
198           set colorlist [::ico::getIconByName tclkit.exe [lindex $i 0] -format colors]
199
200

LIMITATIONS

202       Icons may not be added or removed from file types other than ICO. Icons
203       in these files may only be replaced with icons of the  same  dimensions
204       and color depth.
205
206       Icons of 8bpp or lower must include black in the pallete, this means if
207       your icon does not have black in it, you will need  to  leave  a  color
208       free so that it may be included by writeIcon.
209
210       There  is currently no way to read alpha channel information from 32bpp
211       icons.
212
213       Tk images do not have an alpha channel so the only way to write a  true
214       32bpp icon is from a color list. writing a 32bpp icon from a Tkimage is
215       identical to writing a 24bpp icon.
216

KEYWORDS

218       dll, entry, exe, ico, icon
219
220
221
222ico                                   1.0                               ico(n)
Impressum