« back to all changes in this revision
Viewing changes to doc/html.man
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Package Import Robot
- Author(s): Ole Streicher
- Date: 2012-03-02 18:45:00 UTC
- Revision ID: package-import@ubuntu.com-20120302184500-np17d7d6gd1jedj0
Tags: upstream-3.0~fossil20110109
Import upstream version 3.0~fossil20110109
- files added:
- doc
- hv
- src
- tclconfig
- tests
- tests/page1
- tests/page2
- tests/page3
- tests/page4
- tools
- tools/rules
- webpage
added
removed
doc/html.man
1
2
[TH tkhtml n]
3
4
[Section Name]
5
tkhtml - Widget to render html documents.
6
7
[Section Synopsis]
8
html pathName ?options?
9
10
[Section Standard Options]
11
[Code {
12
-height
13
-width
14
-xscrollcommand
15
-xscrollincrement
16
-yscrollcommand
17
-yscrollincrement
18
}]
19
20
See the options(n) manual entry for details on the standard options.
21
22
[Section Widget-Specific Options]
23
[Option defaultstyle {
24
This option is used to set the default style-sheet for the
25
widget. The option value should be the entire text of the
26
default style-sheet.
27
28
The default stylesheet defines things that are "built-in" to
29
the document - for example the behaviour of <p> or <img> tags
30
in html. The idea behind making it flexible is to allow
31
Tkhtml to display anything that looks roughly like an XML
32
document. But this will not work at the moment because of
33
other assumptions the implementation makes about the set
34
of valid tags. Currently, only valid HTML tags are recognized.
35
36
The Tkhtml package adds the [SQ ::tkhtml::htmlstyle] command to
37
the interpreter it is loaded into. Invoking this command
38
returns a CSS document suitable for use with Tkhml as a default
39
stylesheet for HTML documents. If the "-quirks" option is
40
passed to [SQ ::tkhtml::htmlstyle] then the returned document
41
includes some extra rules used when rendering legacy documents.
42
43
If the value of the -defaultstyle option is changed, the new
44
value does not take effect until after the next call to the
45
widget [SQ reset] method.
46
47
The default value of this option is the same as the string
48
returned by the [SQ ::tkhtml::htmlstyle] command.
49
}]
50
[Option fontscale {
51
This option is set to a floating point number, default 1.0.
52
After CSS algorithms are used to determine a font size,
53
it is multiplied by the value of this option. Setting this
54
to a value other than 1.0 breaks standards compliance.
55
}]
56
[Option fonttable {
57
This option must be set to a list of 7 integers. The first
58
integer must be greater than 0 and each subsequent integer
59
must be greater than or equal to its predecessor.
60
61
The seven integers define the sizes of the Tk fonts (in points)
62
used when a CSS formatted document requests font-size
63
'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large' or
64
'xx-large', respectively.
65
66
The default value is {8 9 10 11 13 15 17}.
67
}]
68
[Option forcefontmetrics {
69
This is a boolean option. If true, the font-metrics returned
70
by Tk are overridden with calculated values based on the
71
font requested. This improves CSS compatibility, but on some
72
systems may cause problems. The default is true.
73
}]
74
[Option forcewidth {
75
When determining the layout of a document, Tkhtml3 (and all
76
other HTML/CSS engines) require as an input the width of
77
the containing block for the whole document. For web-browsers,
78
this is usually the width of the viewport in which the document
79
will be displayed.
80
81
If this option is true or the widget window is not mapped,
82
Tkhtml3 uses the value of the -width option as the initial
83
containing block width. Otherwise, the width of the widget
84
window is used.
85
86
The default value is false.
87
}]
88
[Option imagecache {
89
This boolean option (default true) determines whether or not
90
Tkhtml3 caches the images returned to it by the -imagecmd
91
callback script. If true, all images are cached until the
92
next time the [SQ reset] sub-command is invoked. If false,
93
images are discarded as soon as they are not in use.
94
95
For simple applications, or applications that retrieve
96
images from local sources, false is usually a better value
97
for this option (since it may save memory). However for
98
web-browser applications where the background images of
99
elements may be modified by mouseover events and so on,
100
true is a better choice.
101
}]
102
[Option imagecmd {
103
As well as for replacing entire document nodes (i.e. <img>),
104
images are used in several other contexts in CSS formatted
105
documents, for example as list markers or backgrounds. If the
106
-imagecmd option is not set to an empty string (the default),
107
then each time an image URI is encountered in the document, it
108
is appended to the -imagecmd script and the resulting list
109
evaluated.
110
111
The command should return either an empty string, the name of a
112
Tk image, or a list of exactly two elements, the name of a Tk
113
image and a script. If the result is an empty string, then no
114
image can be displayed. If the result is a Tk image name, then
115
the image is displayed in the widget. When the image is no
116
longer required, it is deleted. If the result of the command is
117
a list containing a Tk image name and a script, then instead of
118
deleting the image when it is no longer required, the script is
119
evaluated.
120
121
If the size or content of the image are modified while it is in
122
use the widget display is updated automatically.
123
}]
124
[Option mode {
125
This option may be set to "quirks", "standards" or
126
"almost standards", to set the rendering engine mode. The
127
default value is "standards".
128
129
TODO: List the differences between the three modes in Tkhtml.
130
}]
131
[Option parsemode {
132
This option may be set to "html", "xhtml" or "xml", to set
133
the parser mode. The default value is "html".
134
135
In "html" mode, the parser attempts to mimic the tag-soup
136
approach inherited by modern web-browsers from the bad old
137
days. Explicit XML style self-closing tags (i.e. closing
138
a markup tag with "/>" instead of ">") are not handled
139
specially. Unknown tags are ignored.
140
141
"xhtml" mode is the same as "html" mode except that explicit
142
self-closing tags are recognized.
143
144
"xml" mode is the same as "xhtml" mode except that unknown
145
tag names and XML CDATA sections are recognized.
146
}]
147
[Option shrink {
148
This boolean option governs the way the widgets requested width
149
and height are calculated. If it is set to false (the default),
150
then the requested width and height are set by the -width
151
and -height options as per usual.
152
153
If this option is set to true, then the widgets requested width
154
and height are determined by the current document. Each time
155
the document layout is calculated, the widgets requested height
156
and width are set to the size of the document layout. If the
157
widget is unmapped when the layout is calculated, then the
158
value of the -width option is used to determine the width
159
of the initial containing block for the layout. Otherwise, the
160
current window width is used.
161
}]
162
[Option zoom {
163
This option may be set to any floating point number. Before
164
the document layout is calculated, all lengths and sizes
165
specified in the HTML document or CSS style configuration,
166
implicit or explicit, are multiplied by this value.
167
168
The default value is 1.0.
169
}]
170
[Option logcmd {
171
This option is used for debugging the widget. It is not
172
part of the official interface and may be modified or
173
removed at any time. Don't worry about it.
174
}]
175
[Option timercmd {
176
This option is used for debugging the widget. It is not
177
part of the official interface and may be modified or
178
removed at any time. Don't worry about it.
179
}]
180
[Option layoutcache {
181
This option is used for debugging the widget. It is not
182
part of the official interface and may be modified or
183
removed at any time. Don't worry about it.
184
185
If this boolean option is set to true, then Tkhtml caches
186
layout information to improve performance when the layout of a
187
document must be recomputed. This can happen in a variety of
188
situations, for example when extra text is appended to the
189
document, a new style is applied to the document, a dynamic CSS
190
selector (i.e. :hover) is activated, the widget window is
191
resized, or when the size of an embedded image or Tk window
192
changes.
193
194
Layout caching consumes no extra memory or significant
195
processing cycles, so in an ideal world there is no real reason
196
to turn it off. But it can be a source of layout bugs, hence
197
this option.
198
199
The default value is true.
200
}]
201
202
[Section Description]
203
204
The [SQ html] command creates a new window (given by the pathName
205
argument) and makes it into an html widget. The html command
206
returns its pathName argument. At the time this command is invoked,
207
there must not exist a window named pathName, but pathName's parent
208
must exist.
209
210
[Section Widget Command]
211
The [SQ html] command creates a new Tcl command whose name is
212
pathName. This command may be used to invoke various operations on
213
the widget as follows:
214
215
[Subcommand {
216
pathName bbox _nodeHandle_
217
If node nodeHandle generates content, this command returns a
218
list of four integers that define the bounding-box of the
219
generated content, relative to the top-left hand corner of the
220
rendered document. The first two integers are the x and y
221
coordinates of the top-left corner of the bounding-box, the
222
later two are the x and y coordinates of the bottom-right
223
corner of the same box. If the node does not generate content,
224
then an empty string is returned.
225
}]
226
227
[Subcommand {
228
pathName cget _option_
229
Returns the current value of the configuration option given
230
by option. Option may have any of the values accepted by
231
the [SQ html] command.
232
}]
233
234
[Subcommand {
235
pathName configure ?_option_? ?_value_?
236
Query or modify the configuration options of the widget. If
237
no option is specified, returns a list describing all of
238
the available options for pathName (see Tk_ConfigureInfo
239
for information on the format of this list). If option is
240
specified with no value, then the command returns a list
241
describing the one named option (this list will be
242
identical to the corresponding sublist of the value
243
returned if no option is specified). If one or more
244
option-value pairs are specified, then the command modifies
245
the given widget option(s) to have the given value(s); in
246
this case the command returns an empty string. Option may
247
have any of the values accepted by the [SQ html] command.
248
}]
249
250
[Subcommand {
251
pathName fragment _html-text_
252
TODO: Document this command.
253
}]
254
255
[Subcommand -4 {
256
pathName handler node _tag_ _script_
257
pathName handler attribute _tag_ _script_
258
pathName handler script _tag_ _script_
259
pathName handler parse _tag_ _script_
260
This command is used to define "handler" scripts - Tcl
261
callback scripts that are invoked by the widget when
262
document elements of specified types are encountered. The
263
widget supports two types of handler scripts: "node" and
264
"script".
265
266
For a "node" handler script, whenever a document element
267
having the specified tag type (e.g. "p" or "link") is
268
encountered during parsing, then the node handle for the
269
node is appended to script and the resulting list
270
evaluated as a Tcl command. See the section "NODE COMMAND"
271
for details of how a node handle may be used to query and
272
manipulate a document node. A node handler is called only
273
after the subtree rooted at the node has been completely
274
parsed.
275
276
If the handler script is a "script" handler, whenever a
277
document node of type tag is parsed, two arguments are
278
appended to the specified _script_ before it is evaluated.
279
The first argument is a key-value list (suitable for passing
280
to the [SQ array set] command containing the HTML attributes
281
that were part of the element declaration. The second
282
argument is the literal text that appears between the
283
start and end tags of the element.
284
285
Elements for which a "script" handler is evaluated are not
286
included in the parsed form of the HTML document. Instead,
287
the result of the script handler evaluation is substituted
288
into the document and parsed. For example, to handle the
289
following embedded javascript:
290
291
[Code {
292
<SCRIPT>
293
document.write("<p>A paragraph</p>")
294
</SCRIPT>
295
}]
296
297
a script handler that returns the string "<p>A paragraph</p>"
298
must be configured for nodes of type "SCRIPT".
299
300
Unlike node or script handlers, a "parse" handler may be
301
associated with a specific opening tag, a closing tag or
302
with text tags (by specifying an empty string as the tag
303
type). Whenever such a tag is encountered the parse handler
304
script is invoked with two arguments, the node handle for
305
the created node and the character offset of the in the parsed
306
document. For a closing tag (i.e. "/form") an empty string
307
is passed instead of a node handle.
308
309
TODO: Describe "attribute" handlers.
310
311
TODO: The offset values passed to parse handler scripts
312
currently have problems. See http://tkhtml.tcl.tk/cvstrac/tktview?tn=126
313
314
Handler callbacks are always made from within
315
[SQ pathName parse] commands. The callback for a given node
316
is made as soon as the node is completely parsed. This can
317
happen because an implicit or explicit closing tag is
318
parsed, or because there is no more document data and the
319
-final switch was passed to the [SQ pathName parse]
320
command.
321
322
TODO: Return values of handler scripts? If an exception
323
occurs in a handler script?
324
}]
325
326
[Subcommand {
327
pathName image
328
This command returns the name of a new Tk image containing
329
the rendered document. Where Tk widgets would be mapped in a
330
live display, the image contains blank space.
331
332
The returned image should be deleted when the script has
333
finished with it, for example:
334
[Code {
335
set img \[.html image]
336
# ... Use $img ...
337
image delete $img
338
}]
339
340
This command is included mainly for automated testing and
341
should be used with care, as large documents can result in very
342
large images that take a long time to create and use vast
343
amounts of memory.
344
345
Currently this command is not available on windows. On that
346
platform an empty string is always returned.
347
}]
348
349
[Subcommand {
350
pathName node ? ?-index? _x_ _y_?
351
This command is used to retrieve one or more document node
352
handles from the current document. If the x and y parameters
353
are omitted, then the handle returned is the root-node of the
354
document, or an empty string if the document has no root-node
355
(i.e. an empty document).
356
357
If the x and y arguments are present, then a list of node
358
handles is returned. The list contains one handle for each
359
node that generates content currently located at viewport
360
coordinates (x, y). Usually this is only a single node, but
361
floating boxes and other overlapped content can cause
362
this command to return more than one node. If no content is
363
located at the specified coordinates or the widget window is
364
not mapped, then an empty string is returned.
365
366
If the -index option is specified along with the x and y
367
coordinates, then instead of a list of node handles, a list of
368
two elements is returned. The first element of the list is the
369
node-handle associated with the generated text closest to
370
the specified (x, y) coordinates. The second list value is a
371
byte (not character) offset into the text obtainable by
372
[SQ nodeHandle text] for the character closest to coordinates
373
(x, y). The index may be used with the [SQ pathName tag] commands.
374
375
The document node can be queried and manipulated using the
376
interface described in the "NODE COMMAND" section.
377
}]
378
379
[Subcommand {
380
pathName parse ?-final? _html-text_
381
Append extra text to the end of the (possibly empty)
382
document currently stored by the widget.
383
384
If the -final option is present, this indicates that the
385
supplied text is the last of the document. Any subsequent
386
call to [SQ pathName parse] before a call to
387
[SQ pathName reset] will raise an error.
388
389
If the -final option is not passed to [SQ pathName parse] along
390
with the final part of the document text, node handler scripts
391
for any elements closed implicitly by the end of the document
392
will not be executed. It is not an error to specify an empty
393
string for the _html-text_ argument.
394
}]
395
396
[Subcommand {
397
pathName preload _uri_
398
This command is only useful if the -imagecache option is
399
set to true and an -imagecmd script is defined. It causes
400
the widget to invoke the -imagecmd script to retrieve
401
the image at URI _uri_. Assuming -imagecache is true, the
402
returned image is then stored in the image-cache.
403
404
This command may be useful when implementing scripting
405
environments that support "preloading" of images.
406
}]
407
408
[Subcommand {
409
pathName reset
410
This is used to clear the internal contents of the widget
411
prior to parsing a new document. The widget is reset such
412
that the document tree is empty (as if no calls to
413
[SQ pathName parse] had ever been made) and no stylesheets
414
except the default stylesheet are loaded (as if no
415
invocations of [SQ pathName style] had occured).
416
}]
417
418
[Subcommand {
419
pathName search _selector_
420
The _selector_ argument passed to this command must be a valid
421
CSS selector, for example "h1" or "a[SQ href]". This command
422
returns a list of node-handles corresponding to the set of
423
document nodes that match the supplied selector.
424
}]
425
426
[Subcommand {
427
pathName style ?_options_? _stylesheet-text_
428
Add a stylesheet to the widgets internal configuration. The
429
stylesheet-text argument should contain the text of a
430
complete stylesheet. Incremental parsing of stylesheets is
431
not supported, although of course multiple stylesheets may
432
be added to a single widget.
433
434
The following options are supported:
435
[Code {
436
Option Default Value
437
--------------------------------------
438
-id <stylesheet-id> "author"
439
-importcmd <script> ""
440
-urlcmd <script> ""
441
}]
442
443
The value of the -id option determines the priority taken
444
by the style-sheet when assigning property values to
445
document nodes (see chapter 6 of the CSS specification for
446
more detail on this process). The first part of the
447
style-sheet id must be one of the strings "agent", "user"
448
or "author". Following this, a style-sheet id may contain
449
any text.
450
451
When comparing two style-ids to determine which stylesheet
452
takes priority, the widget uses the following approach: If
453
the initial strings of the two style-id values are not
454
identical, then "user" takes precedence over "author", and
455
"author" takes precedence over "agent". Otherwise, the
456
lexographically largest style-id value takes precedence.
457
For more detail on why this seemingly odd approach is
458
taken, please refer to the "STYLESHEET LOADING" below.
459
460
The -importcmd option is used to provide a handler script
461
for @import directives encountered within the stylesheet
462
text. Each time an @import directive is encountered, if the
463
-importcmd option is set to other than an empty string, the
464
URI to be imported is appended to the option value and the
465
resulting list evaluated as a Tcl script. The return value
466
of the script is ignored. If the script raises an error,
467
then it is propagated up the call-chain to the
468
[SQ pathName style] caller.
469
470
The -urlcmd option is used to supply a script to translate
471
"url(...)" CSS attribute values. If this option is not set to
472
"", each time a url() value is encountered the URI is appended
473
to the value of -urlcmd and the resulting script evaluated. The
474
return value is stored as the URL in the parsed stylesheet.
475
}]
476
477
[Subcommand -4 {
478
pathName tag add _tag-name_ _node1_ _index1_ _node2_ _index2_
479
pathName tag remove _tag-name_ _node1_ _index1_ _node2_ _index2_
480
pathName tag configure _tag-name_ _option_ _value_ ?_option_ _value_...?
481
pathName tag delete _tag-name_
482
The [SQ pathName tag] command is used to highlight regions
483
of text displayed by the widget. For example, a region
484
of text selected using the pointer.
485
486
Each displayed document character is identified by a
487
text node-handle (see below) and an index into the text
488
returned by the [SQ node text] command. The index is a byte
489
(not character) offset. See also the documentation for the
490
[SQ pathName node -index] command. Both the [SQ pathName tag add]
491
and [SQ pathName tag remove] use this convention.
492
493
Evaluating the [SQ pathName tag add] command adds the specified
494
tag to all displayed characters between the point in the
495
document described by (_node1_, _index1_) and the point
496
described by (_node2_, _index2_). If the specified tag does
497
not exist, it is created with default option values. The
498
order in which the two specified points occur in the
499
document is not important.
500
501
The [SQ pathName tag remove] command removes the specified tag
502
from all displayed characters between the point in the document
503
described by (_node1_, _index1_) and the point described by
504
(_node2_, _index2_).
505
506
The [SQ pathName tag configure] command is used to configure
507
a tags options, which determine how tagged characters are
508
displayed. If the specified tag does not exist, it is
509
created. The following options are supported:
510
[Code {
511
Option Default Value
512
--------------------------------------
513
-background black
514
-foreground white
515
}]
516
517
A tag can be completely deleted (removed from all characters
518
and have it's option values set to the defaults) using the
519
[SQ pathName tag delete] command.
520
521
The [SQ pathName tag] command replaces the
522
[SQ pathName select] command that was present in early
523
alpha versions of Tkhtml3. Users should note that the
524
options supported by [SQ pathName tag configure] are likely
525
to change before beta release. See
526
http://tkhtml.tcl.tk/cvstrac/tktview?tn=73 (ticket #73).
527
}]
528
529
[Subcommand -4 {
530
pathName text bbox _node1_ _index1_ _node2_ _index2_
531
pathName text index _offset_ ?_offset_...?
532
pathName text offset _node_ _index_
533
pathName text text
534
The [SQ pathName text] commands allow an application to
535
query and interact with the text of the displayed document.
536
This can be used, for example, to search for a string
537
within an Html document, or to copy a region of text
538
to the system clipboard.
539
540
The [SQ pathName text text] command returns a string
541
containing the raw, unformatted text of the displayed document.
542
Each block box is seperated from the next by a newline
543
character. Each block of whitespace is collapsed to a
544
single space, except within blocks with the CSS 'white-space'
545
property set to "pre".
546
547
The [SQ pathName text index] command is used to transform
548
from a character offset in the string returned by
549
[SQ pathName text text] to a node/index pair that can be
550
used with the [SQ pathName tag] commands. The return value
551
is a list of two elements, the node-handle followed by the
552
index.
553
554
Command [SQ pathName text offset] is the reverse of
555
[SQ pathName text index]. Given a node-handle and index of the
556
type similar to that used by the [SQ pathName tag] commands,
557
this command returns the corresponding character offset in the
558
string returned by [SQ pathName text text] command.
559
}]
560
561
[Subcommand -3 {
562
pathName write continue
563
pathName write text _html-text_
564
pathName write wait
565
TODO
566
}]
567
568
[Subcommand -3 {
569
pathName xview
570
pathName xview moveto _fraction_
571
pathName xview scroll _number_ _what_
572
This command is used to query or adjust the horizontal
573
position of the viewport relative to the document layout.
574
It is identical to the [SQ pathName xview] command
575
implemented by the canvas and text widgets.
576
}]
577
578
[Subcommand -4 {
579
pathName yview
580
pathName yview moveto _fraction_
581
pathName yview scroll _number_ _what_
582
pathName yview _nodeHandle_
583
This command is used to query or adjust the vertical
584
position of the viewport relative to the document layout.
585
It supports a superset of the [SQ pathName yview] interface
586
implemented by the canvas and text widgets.
587
588
As well as the standard interface copied from the canvas
589
and text widgets, Tkhtml supports passing a single node-handle
590
as the only argument to [SQ pathName yview]. In this case
591
the viewport is scrolled so that the content generated by
592
the node _nodeHandle_ is visible. This can be useful for
593
implementing support for URI fragments.
594
}]
595
596
[Section Node Command]
597
There are several interfaces by which a script can obtain a "node
598
handle". Each node handle is a Tcl command that may be used to
599
access the document node that it represents. A node handle is valid
600
from the time it is obtained until the next call to
601
[SQ pathName reset]. The node handle may be used to query and
602
manipulate the document node via the following subcommands:
603
604
[Subcommand {
605
nodeHandle attribute ??-default _default-value_? ?attribute? ?new-value??
606
If the _attribute_ argument is present, then return the value
607
of the named html attribute. If the attribute is not defined
608
for the node, then a copy of the _default-value_ argument is
609
returned instead. If no -default option was specified (and
610
hence there is no _default-value_ argument) and the named
611
attribute does not exist, an error is raised.
612
613
If the _new-value_ argument is present, then set the named
614
attribute to the specified _new-value_.
615
616
If no _attribute_ argument is present, return a key-value list
617
of the defined attributes of the form that can be passed to
618
[SQ array set].
619
620
[Code {
621
# Html code for node
622
<p class="normal" id="second" style="color : red">
623
624
# Value returned by [nodeHandle attr]
625
{class normal id second style {color : red}}
626
627
# Value returned by [nodeHandle attr class]
628
normal
629
}]
630
}]
631
[Subcommand {
632
nodeHandle children
633
Return a list of node handles for all children of nodeHandle.
634
The leftmost child node becomes element 0 of the list, the
635
second leftmost element 1, and so on.
636
}]
637
[Subcommand {
638
nodeHandle destroy
639
TODO. Experimental.
640
}]
641
[Subcommand -2 {
642
nodeHandle dynamic set ?_flag_?
643
nodeHandle dynamic clear ?_flag_?
644
Set or clear a dynamic flag on a node.
645
646
The supported values for the _flag_ argument are "active",
647
"hover", "focus", "link" and "visited". The status of each
648
dynamic flag determines whether or not the corresponding CSS
649
dynamic pseudo-classes are considered to match the node. For
650
example, when the mouse moves over node $N, a script could
651
invoke:
652
[Code {
653
$N dynamic set hover
654
}]
655
Or possibly, if $PN were the node the mouse hovered over
656
previously:
657
[Code {
658
for {set n $PN} {$n ne ""} {set n [$n parent]} {
659
$n dynamic clear hover
660
}
661
for {set n $N} {$n ne ""} {set n [$n parent]} {
662
$n dynamic set hover
663
}
664
}]
665
}]
666
[Subcommand {
667
nodeHandle insert ?-before _node_? _node-list_
668
TODO. Experimental.
669
}]
670
[Subcommand {
671
nodeHandle override ?_value_?
672
TODO. Experimental.
673
}]
674
[Subcommand {
675
nodeHandle parent
676
Return the node handle for the node's parent. If the node
677
does not have a parent (i.e. it is the document root), then
678
return an empty string.
679
}]
680
[Subcommand {
681
nodeHandle property ?-before|-after? ?property-name?
682
TODO.
683
}]
684
[Subcommand {
685
nodeHandle remove ?_node-list_?
686
TODO.
687
}]
688
[Subcommand {
689
nodeHandle replace ? ?options? newValue?
690
This command is used to set and get the name of the
691
replacement object for the node, if any. If the newValue
692
argument is present, then this command sets the nodes
693
replacement object name and returns the new value. If
694
newValue is not present, then the current value is
695
returned.
696
697
A nodes replacement object may be set to the name of a Tk
698
window or an empty string. If it is an empty string (the
699
default and usual case), then the node is rendered normally.
700
If the node replacement object is set to the name of a Tk
701
window, then the Tk window is mapped into the widget in place
702
of any other content (for example to implement form elements or
703
plugins).
704
705
The following options are supported:
706
707
[Code {
708
Option Default Value
709
--------------------------------------
710
-deletecmd <script> ""
711
-configurecmd <script> ""
712
-stylecmd <script> ""
713
}]
714
715
When a replacement object is no longer being used by the
716
widget (e.g. because the node has been deleted or
717
[SQ pathName reset] is invoked), the value of the
718
-deletecmd option is evaluated as Tcl script.
719
720
If it is not set to an empty string (the default) each time
721
the nodes CSS properties are recalculated, a serialized
722
array is appended to the value of the -configurecmd option
723
and the result evaluated as a Tcl command. The script
724
should update the replacement objects appearance where
725
appropriate to reflect the property values. The format of
726
the appended argument is {p1 v1 p2 v2 ... pN vN} where the
727
pX values are property names (i.e. "background-color") and
728
the vX values are property values (i.e. "#CCCCCC"). The
729
CSS properties that currently may be present in the array
730
are listed below. More may be added in the future.
731
732
[Code {
733
background-color color
734
font selected
735
}]
736
737
The value of the "font" property, if present in the
738
serialized array is not set to the value of the
739
corresponding CSS property. Instead it is set to the name
740
of a Tk font determined by combining the various
741
font-related CSS properties. Unless they are set to
742
"transparent", the two color values are guaranteed to parse
743
as Tk colors. The "selected" property is either true or
744
false, depending on whether or not the replaced object is
745
part of the selection or not. Whether or not an object is
746
part of the selection is governed by previous calls to the
747
[SQ pathName select] command.
748
749
The -configurecmd callback is always executed at least once
750
between the [SQ nodeHandle replace] command and when the
751
replaced object is mapped into the widget display.
752
}]
753
[Subcommand {
754
nodeHandle tag
755
Return the name of the Html tag that generated this
756
document node (i.e. "p" or "link"), or an empty string if
757
the node is a text node.
758
}]
759
[Subcommand {
760
nodeHandle text ?-tokens|-pre?
761
If the node is a "text" node, return the string contained
762
by the node. If the node is not a "text" node, return an
763
empty string.
764
765
TODO: Document -tokens and -pre.
766
}]
767
768
[Section Stylesheet Loading]
769
Apart from the default stylesheet that is always loaded (see the
770
description of the -defaultstyle option above), a script may
771
configure the widget with extra style information in the form of
772
CSS stylesheet documents. Complete stylesheet documents (it is not
773
possible to incrementally parse stylesheets as it is HTML document
774
files) are passed to the widget using the [SQ pathName style]
775
command.
776
777
As well as any stylesheets specified by the application,
778
stylesheets may be included in HTML documents by document authors
779
in several ways:
780
781
[Bulletlist {
782
Embedded in the document itself, using a <style> tag. To
783
handle this case an application script must register a
784
"script" type handler for <style> tags using the
785
[pathName handler] command. The handler command should
786
call [pathName style] to configure the widget with the
787
stylesheet text.
788
} {
789
Linked from the document, using a <link> tag. To handle
790
this case the application script should register a "node"
791
type handler for <link> tags.
792
} {
793
Linked from another stylesheet, using the @import
794
directive. To handle this, an application needs to
795
configure the widget -importcommand option.
796
}]
797
798
[Code {
799
# Implementations of application callbacks to load
800
# stylesheets from the various sources enumerated above.
801
# ".html" is the name of the applications tkhtml widget.
802
# The variable $document contains an entire HTML document.
803
# The pseudo-code <LOAD URI CONTENTS> is used to indicate
804
# code to load and return the content located at $URI.
805
806
proc script_handler {tagcontents} {
807
incr ::stylecount
808
set id "author.[format %.4d $::stylecount]"
809
set handler "import_handler $id"
810
.html style -id $id.9999 -importcmd $handler $tagcontents
811
}
812
813
proc link_handler {node} {
814
if {[node attr rel] == "stylesheet"} {
815
set URI [node attr href]
816
set stylesheet [<LOAD URI CONTENTS>]
817
818
incr ::stylecount
819
set id "author.[format %.4d $::stylecount]"
820
set handler "import_handler $id"
821
.html style -id $id.9999 -importcmd $handler $stylesheet
822
}
823
}
824
825
proc import_handler {parentid URI} {
826
set stylesheet [<LOAD URI CONTENTS>]
827
828
incr ::stylecount
829
set id "$parentid.[format %.4d $::stylecount]"
830
set handler "import_handler $id"
831
.html style -id $id.9999 -importcmd $handler $stylesheet
832
}
833
834
.html handler script style script_handler
835
.html handler node link link_handler
836
837
set ::stylecount 0
838
839
.html parse -final $document
840
}]
841
842
The complicated part of the example code above is the generation of
843
stylesheet-ids, the values passed to the -id option of the
844
[SQ .html style] command. Stylesheet-ids are used to determine the
845
precedence of each stylesheet passed to the widget, and the role it
846
plays in the CSS cascade algorithm used to assign properties to
847
document nodes. The first part of each stylesheet-id, which must be
848
either "user", "author" or "agent", determines the role the
849
stylesheet plays in the cascade algorithm. In general, author
850
stylesheets take precedence over user stylesheets which take
851
precedence over agent stylesheets. An author stylesheet is one
852
supplied or linked by the author of the document. A user stylesheet
853
is supplied by the user of the viewing application, possibly by
854
configuring a preferences dialog or similar. An agent stylesheet is
855
supplied by the viewing application, for example the default
856
stylesheet configured using the -defaultstyle option.
857
858
The stylesheet id mechanism is designed so that the cascade can be
859
correctly implemented even when the various stylesheets are passed
860
to the widget asynchronously and out of order (as may be the case
861
if they are being downloaded from a network server or servers).
862
863
[Code {
864
#
865
# Contents of HTML document
866
#
867
868
<html><head>
869
<link rel="stylesheet" href="A.css">
870
<style>
871
@import uri("B.css")
872
@import uri("C.css")
873
... rules ...
874
</style>
875
<link rel="stylesheet" href="D.css">
876
... remainder of document ...
877
878
#
879
# Contents of B.css
880
#
881
882
@import "E.css"
883
... rules ...
884
}]
885
886
In the example above, the stylesheet documents A.css, B.css, C.css,
887
D.css, E.css and the stylesheet embedded in the <style> tag are all
888
author stylesheets. CSS states that the relative precedences of the
889
stylesheets in this case is governed by the following rules:
890
891
[Bulletlist {
892
Linked, embedded or imported stylesheets take precedence
893
over stylesheets linked, embedded or imported earlier in
894
the same document or stylesheet.
895
} {
896
Rules specified in a stylesheet take precedence over rules
897
specified in imported stylesheets.
898
}]
899
900
Applying the above two rules to the example documents indicates
901
that the order of the stylesheets from least to most important is:
902
A.css, E.css, B.css, C.css, embedded <stylesheet>, D.css. For the
903
widget to implement the cascade correctly, the stylesheet-ids
904
passed to the six [SQ pathName style] commands must sort
905
lexigraphically in the same order as the stylesheet precedence
906
determined by the above two rules. The example code above shows one
907
approach to this. Using the example code, stylesheets would
908
be associated with stylesheet-ids as follows:
909
910
[Code {
911
Stylesheet Stylesheet-id
912
-------------------------------
913
A.css author.0001.9999
914
<embedded style> author.0002.9999
915
B.css author.0002.0003.9999
916
E.css author.0002.0003.0004.9999
917
C.css author.0002.0005.9999
918
D.css author.0006.9999
919
}]
920
921
Entries are specified in the above table in the order in which the
922
calls to [SQ html style] would be made. Of course, the example code
923
fails if 10000 or more individual stylesheet documents are loaded.
924
More inventive solutions that avoid this kind of limitation are
925
possible.
926
927
Other factors, namely rule specificity and the !IMPORTANT directive
928
are involved in determining the precedence of individual stylesheet
929
rules. These are completely encapsulated by the widget, so are not
930
described here. For complete details of the CSS cascade algorithm,
931
refer to the CSS and CSS 2 specifications (www.w3.org).
932
933
[Section Orphan Nodes]
934
Loggerhead is a web-based interface for Breezy
Version: 2.0.1