You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2752 lines
156 KiB
2752 lines
156 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en-US-x-Hixie" ><head><title>7.7 Drag and drop — HTML5 </title><style type="text/css">
|
|
pre { margin-left: 2em; white-space: pre-wrap; }
|
|
h2 { margin: 3em 0 1em 0; }
|
|
h3 { margin: 2.5em 0 1em 0; }
|
|
h4 { margin: 2.5em 0 0.75em 0; }
|
|
h5, h6 { margin: 2.5em 0 1em; }
|
|
h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
|
|
h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
|
|
p { margin: 1em 0; }
|
|
hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
|
|
dl, dd { margin-top: 0; margin-bottom: 0; }
|
|
dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
|
|
dt + dt { margin-top: 0; }
|
|
dd dt { margin-top: 0.25em; margin-bottom: 0; }
|
|
dd p { margin-top: 0; }
|
|
dd dl + p { margin-top: 1em; }
|
|
dd table + p { margin-top: 1em; }
|
|
p + * > li, dd li { margin: 1em 0; }
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
dt dfn { font-style: italic; }
|
|
pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
|
|
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
|
|
pre em { font-weight: bolder; font-style: normal; }
|
|
@media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead, table tbody { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table tbody th { text-align: left; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
|
|
|
|
.bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
|
|
.matrix, .matrix td { border: none; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
img.extra { float: right; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
|
|
pre.css:first-line { color: #AAAA50; }
|
|
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
|
|
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
|
|
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
|
|
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
|
|
dl.domintro dd p { margin: 0.5em 0; }
|
|
dl.switch { padding-left: 2em; }
|
|
dl.switch > dt { text-indent: -1.5em; }
|
|
dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
|
|
dl.triple { padding: 0 0 0 1em; }
|
|
dl.triple dt, dl.triple dd { margin: 0; display: inline }
|
|
dl.triple dt:after { content: ':'; }
|
|
dl.triple dd:after { content: '\A'; white-space: pre; }
|
|
.diff-old { text-decoration: line-through; color: silver; background: transparent; }
|
|
.diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
|
|
a .diff-new { border-bottom: 1px blue solid; }
|
|
|
|
h2 { page-break-before: always; }
|
|
h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
|
|
h1 + h2, hr + h2.no-toc { page-break-before: auto; }
|
|
|
|
p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
|
|
li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
|
|
|
|
div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
|
|
div.head p { margin: 0; }
|
|
div.head h1 { margin: 0; }
|
|
div.head .logo { float: right; margin: 0 1em; }
|
|
div.head .logo img { border: none } /* remove border from top image */
|
|
div.head dl { margin: 1em 0; }
|
|
div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
|
|
|
|
body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
|
|
body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
|
|
body > .toc > li > * { margin-bottom: 0.5em; }
|
|
body > .toc > li > * > li > * { margin-bottom: 0.25em; }
|
|
.toc, .toc li { list-style: none; }
|
|
|
|
.brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
|
|
.brief li { margin: 0; padding: 0; }
|
|
.brief li p { margin: 0; padding: 0; }
|
|
|
|
.category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
|
|
.category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
|
|
.category-list li { display: inline; }
|
|
.category-list li:not(:last-child)::after { content: ', '; }
|
|
.category-list li > span, .category-list li > a { text-transform: lowercase; }
|
|
.category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
|
|
|
|
.XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.XXX > :first-child { margin-top: 0; }
|
|
p .XXX { line-height: 3em; }
|
|
.annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
|
|
.annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
|
|
.annotation :link, .annotation :visited { color: inherit; }
|
|
.annotation :link:hover, .annotation :visited:hover { background: transparent; }
|
|
.annotation span { border: none ! important; }
|
|
.note { color: green; background: transparent; font-family: sans-serif; }
|
|
.warning { color: red; background: transparent; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; }
|
|
p.note, div.note { padding: 0.5em 2em; }
|
|
span.note { padding: 0 2em; }
|
|
.note p:first-child, .warning p:first-child { margin-top: 0; }
|
|
.note p:last-child, .warning p:last-child { margin-bottom: 0; }
|
|
.warning:before { font-style: normal; }
|
|
p.note:before { content: 'Note: '; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
|
|
.bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
|
|
.bookkeeping { font-size: 0.8em; margin: 2em 0; }
|
|
.bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
|
|
.bookkeeping dt { margin: 0.5em 2em 0; }
|
|
.bookkeeping dd { margin: 0 3em 0.5em; }
|
|
|
|
h4 { position: relative; z-index: 3; }
|
|
h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
|
|
.element {
|
|
background: #EEEEFF;
|
|
color: black;
|
|
margin: 0 0 1em 0.15em;
|
|
padding: 0 1em 0.25em 0.75em;
|
|
border-left: solid #9999FF 0.25em;
|
|
position: relative;
|
|
z-index: 1;
|
|
}
|
|
.element:before {
|
|
position: absolute;
|
|
z-index: 2;
|
|
top: 0;
|
|
left: -1.15em;
|
|
height: 2em;
|
|
width: 0.9em;
|
|
background: #EEEEFF;
|
|
content: ' ';
|
|
border-style: none none solid solid;
|
|
border-color: #9999FF;
|
|
border-width: 0.25em;
|
|
}
|
|
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
|
|
td > .example:only-child { margin: 0 0 0 0.1em; }
|
|
|
|
ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
|
|
ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
|
|
ul.domTree li li { list-style: none; }
|
|
ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
|
|
ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
|
|
ul.domTree span { font-style: italic; font-family: serif; }
|
|
ul.domTree .t1 code { color: purple; font-weight: bold; }
|
|
ul.domTree .t2 { font-style: normal; font-family: monospace; }
|
|
ul.domTree .t2 .name { color: black; font-weight: bold; }
|
|
ul.domTree .t2 .value { color: blue; font-weight: normal; }
|
|
ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
|
|
ul.domTree .t7 code, .domTree .t8 code { color: green; }
|
|
ul.domTree .t10 code { color: teal; }
|
|
|
|
body.dfnEnabled dfn { cursor: pointer; }
|
|
.dfnPanel {
|
|
display: inline;
|
|
position: absolute;
|
|
z-index: 10;
|
|
height: auto;
|
|
width: auto;
|
|
padding: 0.5em 0.75em;
|
|
font: small sans-serif, Droid Sans Fallback;
|
|
background: #DDDDDD;
|
|
color: black;
|
|
border: outset 0.2em;
|
|
}
|
|
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
|
|
.dfnPanel :link, .dfnPanel :visited { color: black; }
|
|
.dfnPanel p { font-weight: bolder; }
|
|
.dfnPanel * + p { margin-top: 0.25em; }
|
|
.dfnPanel li { list-style-position: inside; }
|
|
|
|
#configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
|
|
#configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
|
|
#configUI p label { display: block; }
|
|
#configUI #updateUI, #configUI .loginUI { text-align: center; }
|
|
#configUI input[type=button] { display: block; margin: auto; }
|
|
|
|
fieldset { margin: 1em; padding: 0.5em 1em; }
|
|
fieldset > legend + * { margin-top: 0; }
|
|
fieldset > :last-child { margin-bottom: 0; }
|
|
fieldset p { margin: 0.5em 0; }
|
|
|
|
.stability {
|
|
position: fixed;
|
|
bottom: 0;
|
|
left: 0; right: 0;
|
|
margin: 0 auto 0 auto !important;
|
|
z-index: 1000;
|
|
width: 50%;
|
|
background: maroon; color: yellow;
|
|
-webkit-border-radius: 1em 1em 0 0;
|
|
-moz-border-radius: 1em 1em 0 0;
|
|
border-radius: 1em 1em 0 0;
|
|
-moz-box-shadow: 0 0 1em #500;
|
|
-webkit-box-shadow: 0 0 1em #500;
|
|
box-shadow: 0 0 1em red;
|
|
padding: 0.5em 1em;
|
|
text-align: center;
|
|
}
|
|
.stability strong {
|
|
display: block;
|
|
}
|
|
.stability input {
|
|
appearance: none; margin: 0; border: 0; padding: 0.25em 0.5em; background: transparent; color: black;
|
|
position: absolute; top: -0.5em; right: 0; font: 1.25em sans-serif; text-align: center;
|
|
}
|
|
.stability input:hover {
|
|
color: white;
|
|
text-shadow: 0 0 2px black;
|
|
}
|
|
.stability input:active {
|
|
padding: 0.3em 0.45em 0.2em 0.55em;
|
|
}
|
|
.stability :link, .stability :visited,
|
|
.stability :link:hover, .stability :visited:hover {
|
|
background: transparent;
|
|
color: white;
|
|
}
|
|
|
|
</style><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation
|
|
requirements"><link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet" type="text/css"><style type="text/css">
|
|
|
|
.applies thead th > * { display: block; }
|
|
.applies thead code { display: block; }
|
|
.applies tbody th { whitespace: nowrap; }
|
|
.applies td { text-align: center; }
|
|
.applies .yes { background: yellow; }
|
|
|
|
.matrix, .matrix td { border: hidden; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
td.eg { border-width: thin; text-align: center; }
|
|
|
|
#table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
|
|
#table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
|
|
#table-example-1 caption { padding-bottom: 0.5em; }
|
|
#table-example-1 thead, #table-example-1 tbody { border: none; }
|
|
#table-example-1 th, #table-example-1 td { border: solid thin; }
|
|
#table-example-1 th { font-weight: normal; }
|
|
#table-example-1 td { border-style: none solid; vertical-align: top; }
|
|
#table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
|
|
#table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
|
|
#table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
|
|
#table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
|
|
#table-example-1 tbody td:first-child::after { content: leader(". "); }
|
|
#table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
|
|
#table-example-1 tbody td:first-child + td { width: 10em; }
|
|
#table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
|
|
#table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
|
|
|
|
.apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
|
|
.apple-table-examples * { font-family: "Times", serif; }
|
|
.apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
|
|
.apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
|
|
.apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
|
|
.apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
|
|
.apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
|
|
.apple-table-examples td { text-align: right; vertical-align: top; }
|
|
.apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
|
|
.apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
|
|
.apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
|
|
.apple-table-examples sup { line-height: 0; }
|
|
|
|
.details-example img { vertical-align: top; }
|
|
|
|
#base64-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 6em;
|
|
column-count: 5;
|
|
column-gap: 1em;
|
|
-moz-column-width: 6em;
|
|
-moz-column-count: 5;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 6em;
|
|
-webkit-column-count: 5;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#base64-table thead { display: none; }
|
|
#base64-table * { border: none; }
|
|
#base64-table tbody td:first-child:after { content: ':'; }
|
|
#base64-table tbody td:last-child { text-align: right; }
|
|
|
|
#named-character-references-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 30em;
|
|
column-gap: 1em;
|
|
-moz-column-width: 30em;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 30em;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#named-character-references-table > table > tbody > tr > td:first-child + td,
|
|
#named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
|
|
#named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
|
|
#named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
|
|
|
|
.glyph.control { color: red; }
|
|
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
|
|
}
|
|
|
|
</style><style type="text/css">
|
|
.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
|
|
</style><script type="text/javascript">
|
|
function getCookie(name) {
|
|
var params = location.search.substr(1).split("&");
|
|
for (var index = 0; index < params.length; index++) {
|
|
if (params[index] == name)
|
|
return "1";
|
|
var data = params[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
var cookies = document.cookie.split("; ");
|
|
for (var index = 0; index < cookies.length; index++) {
|
|
var data = cookies[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
return null;
|
|
}
|
|
</script>
|
|
<script src="link-fixup.js" type="text/javascript"></script>
|
|
<link href="style.css" rel="stylesheet"><link href="editing.html" title="7 User interaction" rel="prev">
|
|
<link href="spec.html#contents" title="Table of contents" rel="index">
|
|
<link href="syntax.html" title="8 The HTML syntax" rel="next">
|
|
</head><body><div class="head" id="head">
|
|
<div id="multipage-common">
|
|
<p class="stability" id="wip"><strong>This is a work in
|
|
progress!</strong> For the latest updates from the HTML WG, possibly
|
|
including important bug fixes, please look at the <a href="http://dev.w3.org/html5/spec/Overview.html">editor's draft</a> instead.
|
|
There may also be a more
|
|
<a href="http://www.w3.org/TR/html5">up-to-date Working Draft</a>
|
|
with changes based on resolution of Last Call issues.
|
|
<input onclick="closeWarning(this.parentNode)" type="button" value="╳⃝"></p>
|
|
<script type="text/javascript">
|
|
function closeWarning(element) {
|
|
element.parentNode.removeChild(element);
|
|
var date = new Date();
|
|
date.setDate(date.getDate()+4);
|
|
document.cookie = 'hide-obsolescence-warning=1; expires=' + date.toGMTString();
|
|
}
|
|
if (getCookie('hide-obsolescence-warning') == '1')
|
|
setTimeout(function () { document.getElementById('wip').parentNode.removeChild(document.getElementById('wip')); }, 2000);
|
|
</script></div>
|
|
|
|
<p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
|
|
|
|
<h1>HTML5</h1>
|
|
</div><div>
|
|
<a href="editing.html" class="prev">7 User interaction</a> –
|
|
<a href="spec.html#contents">Table of contents</a> –
|
|
<a href="syntax.html" class="next">8 The HTML syntax</a>
|
|
<ol class="toc"><li><ol><li><a href="dnd.html#dnd"><span class="secno">7.7 </span>Drag and drop</a>
|
|
<ol><li><a href="dnd.html#introduction-7"><span class="secno">7.7.1 </span>Introduction</a></li><li><a href="dnd.html#the-drag-data-store"><span class="secno">7.7.2 </span>The drag data store</a></li><li><a href="dnd.html#the-datatransfer-interface"><span class="secno">7.7.3 </span>The <code>DataTransfer</code> interface</a>
|
|
<ol><li><a href="dnd.html#the-datatransferitems-interface"><span class="secno">7.7.3.1 </span>The <code>DataTransferItems</code> interface</a></li><li><a href="dnd.html#the-datatransferitem-interface"><span class="secno">7.7.3.2 </span>The <code>DataTransferItem</code> interface</a></li></ol></li><li><a href="dnd.html#the-dragevent-interface"><span class="secno">7.7.4 </span>The <code>DragEvent</code> interface</a></li><li><a href="dnd.html#drag-and-drop-processing-model"><span class="secno">7.7.5 </span>Drag-and-drop processing model</a></li><li><a href="dnd.html#dndevents"><span class="secno">7.7.6 </span>Events summary</a></li><li><a href="dnd.html#the-draggable-attribute"><span class="secno">7.7.7 </span>The <code>draggable</code> attribute</a></li><li><a href="dnd.html#the-dropzone-attribute"><span class="secno">7.7.8 </span>The <code>dropzone</code> attribute</a></li><li><a href="dnd.html#security-risks-in-the-drag-and-drop-model"><span class="secno">7.7.9 </span>Security risks in the drag-and-drop model</a></li></ol></li><li><a href="dnd.html#editing-apis"><span class="secno">7.8 </span>Editing APIs</a></li></ol></li></ol></div>
|
|
|
|
<h3 id="dnd"><span class="secno">7.7 </span><dfn>Drag and drop</dfn></h3><p>This section defines an event-based drag-and-drop mechanism.</p><p>This specification does not define exactly what a
|
|
<em>drag-and-drop operation</em> actually is.</p><p>On a visual medium with a pointing device, a drag operation could
|
|
be the default action of a <code title="event-mousedown">mousedown</code> event that is followed by a
|
|
series of <code title="event-mousemove">mousemove</code> events, and
|
|
the drop could be triggered by the mouse being released.</p><p>On media without a pointing device, the user would probably have
|
|
to explicitly indicate his intention to perform a drag-and-drop
|
|
operation, stating what he wishes to drag and where he wishes to
|
|
drop it, respectively.</p><div class="impl">
|
|
|
|
<p>However it is implemented, drag-and-drop operations must have a
|
|
starting point (e.g. where the mouse was clicked, or the start of
|
|
the selection or element that was selected for the drag), may have
|
|
any number of intermediate steps (elements that the mouse moves over
|
|
during a drag, or elements that the user picks as possible drop
|
|
points as he cycles through possibilities), and must either have an
|
|
end point (the element above which the mouse button was released, or
|
|
the element that was finally selected), or be canceled. The end
|
|
point must be the last element selected as a possible drop point
|
|
before the drop occurs (so if the operation is not canceled, there
|
|
must be at least one element in the middle step).</p>
|
|
|
|
</div><h4 id="introduction-7"><span class="secno">7.7.1 </span>Introduction</h4><p><i>This section is non-normative.</i></p><p>To make an element draggable is simple: give the element a <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> attribute, and set an event
|
|
listener for <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> that
|
|
stores the data being dragged.</p><p>The event handler typically needs to check that it's not a text
|
|
selection that is being dragged, and then needs to store data into
|
|
the <code><a href="#datatransfer">DataTransfer</a></code> object and set the allowed effects
|
|
(copy, move, link, or some combination).</p><p>For example:</p><pre><p>What fruits do you like?</p>
|
|
<ol ondragstart="dragStartHandler(event)">
|
|
<li draggable="true" data-value="fruit-apple">Apples</li>
|
|
<li draggable="true" data-value="fruit-orange">Oranges</li>
|
|
<li draggable="true" data-value="fruit-pear">Pears</li>
|
|
</ol>
|
|
<script>
|
|
var internalDNDType = 'text/x-example'; // set this to something specific to your site
|
|
function dragStartHandler(event) {
|
|
if (event.target instanceof HTMLLIElement) {
|
|
// use the element's data-value="" attribute as the value to be moving:
|
|
event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
|
|
event.dataTransfer.effectAllowed = 'move'; // only allow moves
|
|
} else {
|
|
event.preventDefault(); // don't allow selection to be dragged
|
|
}
|
|
}
|
|
</script></pre><hr><p>To accept a drop, the drop target has to have a <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute and listen to the
|
|
<code title="drop-event">drop</code> event.</p><p>The value of the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code>
|
|
attribute specifies what kind of data to accept (e.g. "<code title="">s:text/plain</code>" to accept any text strings, or
|
|
"<code>f:image/png</code>" to accept a PNG image file) and what kind
|
|
of feedback to give (e.g. "<code>move</code>" to indicate that the
|
|
data will be moved).</p><p class="note">Instead of using the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute, a drop target can
|
|
handle the <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code> event (to
|
|
report whether or not the drop target is to accept the drop) and the
|
|
<code title="event-dragover"><a href="#event-dragover">dragover</a></code> event (to specify what
|
|
feedback is to be shown to the user).</p><p>The <code title="event-drop"><a href="#event-drop">drop</a></code> event allows the actual
|
|
drop to be performed. This event needs to be canceled, so that the
|
|
<code title="dom-DataTransfer-DropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code>
|
|
attribute's value can be used by the source (otherwise it's
|
|
reset).</p><p>For example:</p><pre><p>Drop your favorite fruits below:</p>
|
|
<ol dropzone="move s:text/x-example" ondrop="dropHandler(event)">
|
|
<-- don't forget to change the "text/x-example" type to something
|
|
specific to your site -->
|
|
</ol>
|
|
<script>
|
|
var internalDNDType = 'text/x-example'; // set this to something specific to your site
|
|
function dropHandler(event) {
|
|
var li = document.createElement('li');
|
|
var data = event.dataTransfer.getData(internalDNDType);
|
|
if (data == 'fruit-apple') {
|
|
li.textContent = 'Apples';
|
|
} else if (data == 'fruit-orange') {
|
|
li.textContent = 'Oranges';
|
|
} else if (data == 'fruit-pear') {
|
|
li.textContent = 'Pears';
|
|
} else {
|
|
li.textContent = 'Unknown Fruit';
|
|
}
|
|
event.target.appendChild(li);
|
|
}
|
|
</script></pre><hr><p>To remove the original element (the one that was dragged) from
|
|
the display, the <code title="event-dragend"><a href="#event-dragend">dragend</a></code> event
|
|
can be used.</p><p>For our example here, that means updating the original markup to
|
|
handle that event:</p><pre><p>What fruits do you like?</p>
|
|
<ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)">
|
|
<em>...as before...</em>
|
|
</ol>
|
|
<script>
|
|
function dragStartHandler(event) {
|
|
// <em>...as before...</em>
|
|
}
|
|
function dragEndHandler(event) {
|
|
// remove the dragged element
|
|
event.target.parentNode.removeChild(event.target);
|
|
}
|
|
</script></pre><h4 id="the-drag-data-store"><span class="secno">7.7.2 </span>The drag data store</h4><p>The data that underlies a drag-and-drop operation, known as the
|
|
<dfn id="drag-data-store">drag data store</dfn>, consists of the following information:</p><ul><li><p>A <dfn id="drag-data-store-item-list">drag data store item list</dfn>, which is a list of
|
|
items representing the dragged data, each consisting of the
|
|
following information:</p>
|
|
|
|
<dl><dt><dfn id="the-drag-data-item-kind">The drag data item kind</dfn></dt>
|
|
|
|
<dd>
|
|
|
|
<p>The kind of data:</p>
|
|
|
|
<dl><dt><i>Plain Unicode string</i></dt>
|
|
<dd>
|
|
<p>Text.</p>
|
|
</dd>
|
|
|
|
|
|
<dt><i><a href="infrastructure.html#file">File</a></i></dt>
|
|
<dd>
|
|
<p>Binary data with a file name.</p>
|
|
</dd>
|
|
|
|
|
|
</dl></dd>
|
|
|
|
<dt><dfn id="the-drag-data-item-type-string">The drag data item type string</dfn></dt>
|
|
|
|
<dd>
|
|
|
|
<p>A Unicode string giving the type or format of the data,
|
|
generally given by a <a href="infrastructure.html#mime-type">MIME type</a>. Some values that
|
|
are not <a href="infrastructure.html#mime-type" title="MIME type">MIME types</a> are
|
|
special-cased for legacy reasons. The API does not enforce the
|
|
use of <a href="infrastructure.html#mime-type" title="MIME type">MIME types</a>; other values
|
|
can be used as well. In all cases, however, the values are all
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a> by the API.</p>
|
|
|
|
<p class="note">Strings that contain <a href="common-microsyntaxes.html#space-character" title="space
|
|
character">space characters</a> cannot be used with the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute, so authors are
|
|
encouraged to use only <a href="infrastructure.html#mime-type" title="MIME type">MIME types</a>
|
|
or custom strings (without spaces).</p>
|
|
|
|
<p>There is a limit of one <i>Plain Unicode string</i> item per
|
|
<a href="#the-drag-data-item-type-string" title="The drag data item type string">item type
|
|
string</a>.</p>
|
|
</dd>
|
|
|
|
<dt>The actual data</dt>
|
|
|
|
<dd><p>A Unicode or binary string, in some cases with a file name
|
|
(itself a Unicode string), as
|
|
per <a href="#the-drag-data-item-kind">the drag data item kind</a>.</p></dd>
|
|
|
|
</dl><p>The <a href="#drag-data-store-item-list">drag data store item list</a> is ordered in the
|
|
order that the items were added to the list; most recently added
|
|
last.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>The following information, used to generate the UI feedback
|
|
during the drag:</p>
|
|
|
|
<ul><li>User-agent-defined default feedback information, known as the
|
|
<dfn id="drag-data-store-default-feedback">drag data store default feedback</dfn>.</li>
|
|
|
|
<li>A list of zero or more elements known as the <dfn id="drag-data-store-elements-list">drag data
|
|
store elements list</dfn>.</li>
|
|
|
|
<li>Optionally, a bitmap image and the coordinate of a point
|
|
within that image, known as the <dfn id="drag-data-store-bitmap">drag data store bitmap</dfn>
|
|
and <dfn id="drag-data-store-hot-spot-coordinate">drag data store hot spot coordinate</dfn>.</li>
|
|
|
|
</ul></li>
|
|
|
|
<li>
|
|
|
|
<p>A <dfn id="drag-data-store-mode">drag data store mode</dfn>, which is one of the
|
|
following:</p>
|
|
|
|
<dl><dt><dfn id="concept-dnd-rw" title="concept-dnd-rw">Read/write mode</dfn></dt>
|
|
<dd>
|
|
|
|
<p>For the <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> event.
|
|
New data can be added to the <a href="#drag-data-store">drag data store</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="concept-dnd-ro" title="concept-dnd-ro">Read-only mode</dfn></dt>
|
|
<dd>
|
|
|
|
<p>For the <code title="event-drop"><a href="#event-drop">drop</a></code> event. The list of
|
|
items representing dragged data can be read, including the data.
|
|
No new data can be added.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="concept-dnd-p" title="concept-dnd-p">Protected mode</dfn></dt>
|
|
<dd>
|
|
|
|
<p>For all other events. The formats and kinds in the <a href="#drag-data-store">drag
|
|
data store</a> list of items representing dragged data can be
|
|
enumerated, but the data itself is unavailable and no new data can
|
|
be added.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></li>
|
|
|
|
<li>
|
|
|
|
<p>A <dfn id="drag-data-store-allowed-effects-state">drag data store allowed effects state</dfn>, which is a
|
|
string.</p>
|
|
|
|
</li>
|
|
|
|
</ul><p>When a <a href="#drag-data-store">drag data store</a> is <dfn id="create-a-drag-data-store" title="create a drag
|
|
data store">created</dfn>, it must be initialized such that its
|
|
<a href="#drag-data-store-item-list">drag data store item list</a> is empty, it has no
|
|
<a href="#drag-data-store-default-feedback">drag data store default feedback</a>, its <a href="#drag-data-store-elements-list">drag data
|
|
store elements list</a> is empty, it has no <a href="#drag-data-store-bitmap">drag data store
|
|
bitmap</a> / <a href="#drag-data-store-hot-spot-coordinate">drag data store hot spot coordinate</a>,
|
|
its <a href="#drag-data-store-mode">drag data store mode</a> is <a href="#concept-dnd-p" title="concept-dnd-p">protected mode</a>, and its <a href="#drag-data-store-allowed-effects-state">drag data
|
|
store allowed effects state</a> is the string "<code title="">uninitialized</code>".</p><h4 id="the-datatransfer-interface"><span class="secno">7.7.3 </span>The <code><a href="#datatransfer">DataTransfer</a></code> interface</h4><p><code><a href="#datatransfer">DataTransfer</a></code> objects are used to expose the
|
|
<a href="#drag-data-store">drag data store</a> that underlies a drag-and-drop
|
|
operation.</p><pre class="idl">interface <dfn id="datatransfer">DataTransfer</dfn> {
|
|
attribute DOMString <a href="#dom-datatransfer-dropeffect" title="dom-DataTransfer-dropEffect">dropEffect</a>;
|
|
attribute DOMString <a href="#dom-datatransfer-effectallowed" title="dom-DataTransfer-effectAllowed">effectAllowed</a>;
|
|
|
|
readonly attribute <a href="#datatransferitems">DataTransferItems</a> <a href="#dom-datatransfer-items" title="dom-DataTransfer-items">items</a>;
|
|
|
|
void <a href="#dom-datatransfer-setdragimage" title="dom-DataTransfer-setDragImage">setDragImage</a>(in Element image, in long x, in long y);
|
|
void <a href="#dom-datatransfer-addelement" title="dom-DataTransfer-addElement">addElement</a>(in Element element);
|
|
|
|
/* old interface */
|
|
readonly attribute DOMStringList <a href="#dom-datatransfer-types" title="dom-DataTransfer-types">types</a>;
|
|
DOMString <a href="#dom-datatransfer-getdata" title="dom-DataTransfer-getData">getData</a>(in DOMString format);
|
|
void <a href="#dom-datatransfer-setdata" title="dom-DataTransfer-setData">setData</a>(in DOMString format, in DOMString data);
|
|
void <a href="#dom-datatransfer-cleardata" title="dom-DataTransfer-clearData">clearData</a>(in optional DOMString format);
|
|
readonly attribute <a href="infrastructure.html#filelist">FileList</a> <a href="#dom-datatransfer-files" title="dom-DataTransfer-files">files</a>;
|
|
};</pre><dl class="domintro"><dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the kind of operation that is currently selected. If
|
|
the kind of operation isn't one of those that is allowed by the
|
|
<code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute, then the operation will fail.</p>
|
|
|
|
<p>Can be set, to change the selected operation.</p>
|
|
|
|
<p>The possible values are "<code title="">none</code>", "<code title="">copy</code>", "<code title="">link</code>", and "<code title="">move</code>".</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the kinds of operations that are to be allowed.</p>
|
|
|
|
<p>Can be set, to change the allowed operations.</p>
|
|
|
|
<p>The possible values are "<code title="">none</code>", "<code title="">copy</code>", "<code title="">copyLink</code>", "<code title="">copyMove</code>", "<code title="">link</code>", "<code title="">linkMove</code>", "<code title="">move</code>", "<code title="">all</code>", and "<code title="">uninitialized</code>",</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-items"><a href="#dom-datatransfer-items">items</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#datatransferitems">DataTransferItems</a></code> object, with the drag data.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-setDragImage"><a href="#dom-datatransfer-setdragimage">setDragImage</a></code>(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Uses the given element to update the drag feedback, replacing any previously specified feedback.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-addElement"><a href="#dom-datatransfer-addelement">addElement</a></code>(<var title="">element</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Adds the given element to the list of elements used to render the drag feedback.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-types"><a href="#dom-datatransfer-types">types</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code>DOMStringList</code> listing the formats that
|
|
were set in the <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code>
|
|
event. In addition, if any files are being dragged, then one of
|
|
the types will be the string "<code title="">Files</code>".</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">data</var> = <var title="">dataTransfer</var> . <code title="dom-DataTransfer-getData"><a href="#dom-datatransfer-getdata">getData</a></code>(<var title="">format</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the specified data. If there is no such data, returns the empty string.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-setData"><a href="#dom-datatransfer-setdata">setData</a></code>(<var title="">format</var>, <var title="">data</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Adds the specified data.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-clearData"><a href="#dom-datatransfer-cleardata">clearData</a></code>( [ <var title="">format</var> ] )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Removes the data of the specified formats. Removes all data if
|
|
the argument is omitted.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">dataTransfer</var> . <code title="dom-DataTransfer-files"><a href="#dom-datatransfer-files">files</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="infrastructure.html#filelist">FileList</a></code> of the files being dragged, if any.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p><code><a href="#datatransfer">DataTransfer</a></code> objects are used during the <a href="#dndevents">drag-and-drop events</a>, and are only valid while
|
|
those events are being dispatched.</p><div class="impl">
|
|
|
|
<p>A <code><a href="#datatransfer">DataTransfer</a></code> object is associated with a
|
|
<a href="#drag-data-store">drag data store</a> while it is valid.</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-dropeffect" title="dom-DataTransfer-dropEffect"><code>dropEffect</code></dfn>
|
|
attribute controls the drag-and-drop feedback that the user is given
|
|
during a drag-and-drop operation. When the <code><a href="#datatransfer">DataTransfer</a></code>
|
|
object is created, the <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> attribute is
|
|
set to a string value. On getting, it must return its current value.
|
|
On setting, if the new value is one of "<code title="">none</code>",
|
|
"<code title="">copy</code>", "<code title="">link</code>", or
|
|
"<code title="">move</code>", then the attribute's current value
|
|
must be set to the new value. Other values must be ignored.</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-effectallowed" title="dom-DataTransfer-effectAllowed"><code>effectAllowed</code></dfn>
|
|
attribute is used in the drag-and-drop processing model to
|
|
initialize the <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> attribute
|
|
during the <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code> and <code title="event-dragover"><a href="#event-dragover">dragover</a></code> events. When the
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object is created, the <code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute is set to a string value. On getting, it must return its
|
|
current value. On setting, if the new value is one of "<code title="">none</code>", "<code title="">copy</code>", "<code title="">copyLink</code>", "<code title="">copyMove</code>", "<code title="">link</code>", "<code title="">linkMove</code>", "<code title="">move</code>", "<code title="">all</code>", or "<code title="">uninitialized</code>", then the attribute's current value
|
|
must be set to the new value. Other values must be ignored.</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-items" title="dom-DataTransfer-items"><code>items</code></dfn>
|
|
attribute must return a <code><a href="#datatransferitems">DataTransferItems</a></code> object
|
|
associated with the <code><a href="#datatransfer">DataTransfer</a></code> object. The same
|
|
object must be returned each time.</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-setdragimage" title="dom-DataTransfer-setDragImage"><code>setDragImage(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>)</code></dfn> method must run the following
|
|
steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is not in the <a href="#concept-dnd-rw" title="concept-dnd-rw">read/write mode</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the <var title="">element</var> argument is an
|
|
<code><a href="embedded-content-1.html#the-img-element">img</a></code> element, then set the <a href="#drag-data-store-bitmap">drag data store
|
|
bitmap</a> to the element's image (at its intrinsic size);
|
|
otherwise, set the <a href="#drag-data-store-bitmap">drag data store bitmap</a> to an image
|
|
generated from the given element (the exact mechanism for doing so
|
|
is not currently specified).</p></li>
|
|
|
|
<li><p>Set the <a href="#drag-data-store-hot-spot-coordinate">drag data store hot spot coordinate</a> to
|
|
the given <var title="">x</var>, <var title="">y</var>
|
|
coordinate.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransfer-addelement" title="dom-DataTransfer-addElement"><code>addElement(<var title="">element</var>)</code></dfn> method is an alternative way of
|
|
specifying how the user agent is to <a href="#base-dnd-feedback">render the drag feedback</a>. The method
|
|
must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is not in the <a href="#concept-dnd-rw" title="concept-dnd-rw">read/write mode</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>Add the given <var title="">element</var> to the element's
|
|
<a href="#drag-data-store-elements-list">drag data store elements list</a>.</p></li>
|
|
|
|
</ol><p class="note">The difference between <code title="dom-DataTransfer-setDragImage"><a href="#dom-datatransfer-setdragimage">setDragImage()</a></code> and
|
|
<code title="dom-DataTransfer-addElement"><a href="#dom-datatransfer-addelement">addElement()</a></code> is
|
|
that the latter automatically generates the image based on the
|
|
current rendering of the elements added (potentially keeping it
|
|
updated as the drag continues, e.g. if the elements include an
|
|
actively playing video), whereas the former uses the exact specified
|
|
image at the time the method is invoked.</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-types" title="dom-DataTransfer-types"><code>types</code></dfn>
|
|
attribute must return a <a href="infrastructure.html#live">live</a> <code>DOMStringList</code>
|
|
giving the strings that the following steps would produce. The same
|
|
object must be returned each time.</p>
|
|
|
|
<ol><li><p>Start with an empty list <var title="">L</var>.</p></li>
|
|
|
|
<li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, the
|
|
<code>DOMStringList</code> is empty. Abort these steps; return the
|
|
empty list <var title="">L</var>.</p></li>
|
|
|
|
<li><p>For each item in the <a href="#drag-data-store-item-list">drag data store item list</a>
|
|
whose <a href="#the-drag-data-item-kind" title="the drag data item
|
|
kind">kind</a> is <i>Plain Unicode string</i>, add an entry to
|
|
the list <var title="">L</var> consisting of the item's <a href="#the-drag-data-item-type-string" title="the drag data item type string">type string</a>.</p></li>
|
|
|
|
<li><p>If there are any items in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a>
|
|
is <i><a href="infrastructure.html#file">File</a></i>, then add an entry to the list <var title="">L</var>
|
|
consisting of the string "<code title="">Files</code>". (This value
|
|
can be distinguished from the other values because it is not
|
|
lowercase.)</p></li>
|
|
|
|
|
|
|
|
<li><p>The strings produced by these steps are those in the list
|
|
<var title="">L</var>.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransfer-getdata" title="dom-DataTransfer-getData"><code>getData(<var title="">format</var>)</code></dfn> method
|
|
must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, return the empty
|
|
string and abort these steps.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is in the <a href="#concept-dnd-p" title="concept-dnd-p">protected mode</a>, return the empty
|
|
string and abort these steps.</p></li>
|
|
|
|
<li><p>Let <var title="">format</var> be the first argument,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
|
|
|
|
<li><p>Let <var title="">convert-to-URL</var> be false.</p></li>
|
|
|
|
<li><p>If <var title="">format</var> equals "<code title="">text</code>", change it to "<code title="">text/plain</code>".</p></li>
|
|
|
|
<li><p>If <var title="">format</var> equals "<code title="">url</code>", change it to "<code title="">text/uri-list</code>" and set <var title="">convert-to-URL</var> to true.</p></li>
|
|
|
|
<li><p>If there is no item in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a>
|
|
is <i>Plain Unicode string</i> and whose <a href="#the-drag-data-item-type-string" title="the drag data
|
|
item type string">type string</a> is equal to <var title="">format</var>, return the empty string and abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>Let <var title="">result</var> be the data of the item
|
|
in the <a href="#drag-data-store-item-list">drag data store item list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a> is <i>Plain Unicode
|
|
string</i> and whose <a href="#the-drag-data-item-type-string" title="the drag data item type
|
|
string">type string</a> is equal to <var title="">format</var>.</p></li>
|
|
|
|
<li><p>If <var title="">convert-to-URL</var> is true, then parse
|
|
<var title="">result</var> as appropriate for <code title="">text/uri-list</code> data, and then set <var title="">result</var> to the first URL from the list, if any, or
|
|
the empty string otherwise. <a href="references.html#refsRFC2483">[RFC2483]</a></p></li>
|
|
|
|
<li><p>Return <var title="">result</var>.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransfer-setdata" title="dom-DataTransfer-setData"><code>setData(<var title="">format</var>, <var title="">data</var>)</code></dfn> method
|
|
must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is not the <a href="#concept-dnd-rw" title="concept-dnd-rw">read/write mode</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>Let <var title="">format</var> be the first argument,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">format</var> equals "<code title="">text</code>", change it to "<code title="">text/plain</code>".</p>
|
|
|
|
<p>If <var title="">format</var> equals "<code title="">url</code>", change it to "<code title="">text/uri-list</code>".</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Remove the item in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a>
|
|
is <i>Plain Unicode string</i> and whose <a href="#the-drag-data-item-type-string" title="the drag data
|
|
item type string">type string</a> is equal to <var title="">format</var>, if there is one.</p></li>
|
|
|
|
<li><p>Add an item to the <a href="#drag-data-store-item-list">drag data store item list</a>
|
|
whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a> is <i>Plain
|
|
Unicode string</i>, whose <a href="#the-drag-data-item-type-string" title="the drag data item type
|
|
string">type string</a> is equal to <var title="">format</var>,
|
|
and whose data is the string given by the method's second
|
|
argument.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransfer-cleardata" title="dom-DataTransfer-clearData"><code>clearData()</code></dfn>
|
|
method must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is not the <a href="#concept-dnd-rw" title="concept-dnd-rw">read/write mode</a>, abort these steps.
|
|
Nothing happens.</p></li>
|
|
|
|
<li><p>If the method was called with no arguments, remove each item
|
|
in the <a href="#drag-data-store-item-list">drag data store item list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a> is <i>Plain Unicode
|
|
string</i>, and abort these steps.</p></li>
|
|
|
|
<li><p>Let <var title="">format</var> be the first argument,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">format</var> equals "<code title="">text</code>", change it to "<code title="">text/plain</code>".</p>
|
|
|
|
<p>If <var title="">format</var> equals "<code title="">url</code>", change it to "<code title="">text/uri-list</code>".</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Remove the item in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a>
|
|
is <i>Plain Unicode string</i> and whose <a href="#the-drag-data-item-type-string" title="the drag data
|
|
item type string">type string</a> is equal to <var title="">format</var>, if there is one.</p></li>
|
|
|
|
</ol><p class="note">The <code title="dom-DataTransfer-clearData"><a href="#dom-datatransfer-cleardata">clearData()</a></code> method does
|
|
not affect whether any files were included in the drag, so the <code title="dom-DataTransfer-types"><a href="#dom-datatransfer-types">types</a></code> attribute's list might
|
|
still not be empty after calling <code title="dom-DataTransfer-clearData"><a href="#dom-datatransfer-cleardata">clearData()</a></code> (it would
|
|
still contain the "<code title="">Files</code>" string if any files
|
|
were included in the drag).</p>
|
|
|
|
<p>The <dfn id="dom-datatransfer-files" title="dom-DataTransfer-files"><code>files</code></dfn>
|
|
attribute must return a <a href="infrastructure.html#live">live</a> <code><a href="infrastructure.html#filelist">FileList</a></code>
|
|
sequence consisting of <code><a href="infrastructure.html#file">File</a></code> objects representing the
|
|
files found by the following steps. The same object must be returned
|
|
each time. Furthermore, for a given <code><a href="infrastructure.html#filelist">FileList</a></code> object and
|
|
a given underlying file, the same <code><a href="infrastructure.html#file">File</a></code> object must be
|
|
used each time.</p>
|
|
|
|
<ol><li><p>Start with an empty list <var title="">L</var>.</p></li>
|
|
|
|
<li><p>If the <code><a href="#datatransfer">DataTransfer</a></code> object is no longer
|
|
associated with a <a href="#drag-data-store">drag data store</a>, the
|
|
<code><a href="infrastructure.html#filelist">FileList</a></code> is empty. Abort these steps; return the
|
|
empty list <var title="">L</var>.</p></li>
|
|
|
|
<li><p>If the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-mode" title="drag data
|
|
store mode">mode</a> is in the <a href="#concept-dnd-p" title="concept-dnd-p">protected mode</a>, abort these steps;
|
|
return the empty list <var title="">L</var>.</p></li>
|
|
|
|
<li><p>For each item in the <a href="#drag-data-store-item-list">drag data store item list</a>
|
|
whose <a href="#the-drag-data-item-kind" title="the drag data item
|
|
kind">kind</a> is <i><a href="infrastructure.html#file">File</a></i> ,
|
|
add the item's data (the file, in particular its name and contents,
|
|
as well as its <a href="#the-drag-data-item-type-string" title="the drag data item type
|
|
string">type</a>) to the list <var title="">L</var>.</p></li>
|
|
|
|
|
|
|
|
<li><p>The files found by these steps are those in the list <var title="">L</var>.</p></li>
|
|
|
|
</ol><p class="note">This version of the API does not expose the types of
|
|
the files during the drag.</p>
|
|
|
|
</div><h5 id="the-datatransferitems-interface"><span class="secno">7.7.3.1 </span>The <code><a href="#datatransferitems">DataTransferItems</a></code> interface</h5><p>Each <code><a href="#datatransfer">DataTransfer</a></code> object is associated with a
|
|
<code><a href="#datatransferitems">DataTransferItems</a></code> object.</p><pre class="idl">interface <dfn id="datatransferitems">DataTransferItems</dfn> {
|
|
readonly attribute unsigned long <a href="#dom-datatransferitems-length" title="dom-DataTransferItems-length">length</a>;
|
|
<a href="#dom-datatransferitems-item" title="dom-DataTransferItems-item">getter</a> <a href="#datatransferitem">DataTransferItem</a> (in unsigned long index);
|
|
<a href="#dom-datatransferitems-removeitem" title="dom-DataTransferItems-removeItem">deleter</a> void (in unsigned long index);
|
|
void <a href="#dom-datatransferitems-clear" title="dom-DataTransferItems-clear">clear</a>();
|
|
|
|
<a href="#datatransferitem">DataTransferItem</a> <a href="#dom-datatransferitems-add" title="dom-DataTransferItems-add">add</a>(in DOMString data, in DOMString type); <a href="#datatransferitem">DataTransferItem</a> <a href="#dom-datatransferitems-add" title="dom-DataTransferItems-add">add</a>(in <a href="infrastructure.html#file">File</a> data);};</pre><dl class="domintro"><dt><var title="">items</var> . <code title="dom-DataTransferItems-length"><a href="#dom-datatransferitems-length">length</a></code></dt>
|
|
|
|
<dd><p>Returns the number of items in the <a href="#drag-data-store">drag data store</a>.</p></dd>
|
|
|
|
|
|
<dt><var title="">items</var>[<var title="">index</var>]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <code><a href="#datatransferitem">DataTransferItem</a></code> object representing the <var title="">index</var>th entry in the <a href="#drag-data-store">drag data store</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><code title="">delete</code> <var title="">items</var>[<var title="">index</var>]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Removes the <var title="">index</var>th entry in the <a href="#drag-data-store">drag data store</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">items</var> . <code title="dom-DataTransferItems-clear"><a href="#dom-datatransferitems-clear">clear</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Removes all the entries in the <a href="#drag-data-store">drag data store</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">items</var> . <code title="dom-DataTransferItems-add"><a href="#dom-datatransferitems-add">add</a></code>(<var title="">data</var>)</dt>
|
|
<dt><var title="">items</var> . <code title="dom-DataTransferItems-add"><a href="#dom-datatransferitems-add">add</a></code>(<var title="">data</var>, <var title="">type</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Adds a new entry for the given data to the <a href="#drag-data-store">drag data
|
|
store</a>. If the data is plain text
|
|
then a <var title="">type</var> string has to be provided
|
|
also.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>While the <code><a href="#datatransferitems">DataTransferItems</a></code> object's
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object is associated with a <a href="#drag-data-store">drag
|
|
data store</a>, the <code><a href="#datatransferitems">DataTransferItems</a></code> object's
|
|
<i>mode</i> is the same as the <a href="#drag-data-store-mode">drag data store mode</a>.
|
|
When the <code><a href="#datatransferitems">DataTransferItems</a></code> object's
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object is <em>not</em> associated with a
|
|
<a href="#drag-data-store">drag data store</a>, the <code><a href="#datatransferitems">DataTransferItems</a></code>
|
|
object's <i>mode</i> is the <i>disabled mode</i>. The <a href="#drag-data-store">drag
|
|
data store</a> referenced in this section (which is used only
|
|
when the <code><a href="#datatransferitems">DataTransferItems</a></code> object is not in the
|
|
<i>disabled mode</i>) is the <a href="#drag-data-store">drag data store</a> with which
|
|
the <code><a href="#datatransferitems">DataTransferItems</a></code> object's
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object is associated.</p>
|
|
|
|
<p>The <dfn id="dom-datatransferitems-length" title="dom-DataTransferItems-length"><code>length</code></dfn>
|
|
attribute must return zero if the object is in the <i>disabled
|
|
mode</i>; otherwise it must return the number of items in the
|
|
<a href="#drag-data-store-item-list">drag data store item list</a>.</p>
|
|
|
|
<p>When a <code><a href="#datatransferitems">DataTransferItems</a></code> object is not in the
|
|
<i>disabled mode</i>, its <a href="infrastructure.html#supported-property-indices">supported property indices</a>
|
|
are the numbers in the range
|
|
|
|
<span title="">0 .. <var title="">n</var>-1</span>,
|
|
|
|
where <var title="">n</var> is the number of items in the <a href="#drag-data-store-item-list">drag
|
|
data store item list</a>.</p>
|
|
|
|
<p>To <dfn id="dom-datatransferitems-item" title="dom-DataTransferItems-item">determine the value of
|
|
an indexed property</dfn> <var title="">i</var> of a
|
|
<code><a href="#datatransferitems">DataTransferItems</a></code> object, the user agent must return a
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object representing the <var title="">i</var>th item in the <a href="#drag-data-store">drag data store</a>. The
|
|
same object must be returned each time a particular item is obtained
|
|
from this <code><a href="#datatransferitems">DataTransferItems</a></code> object. The
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object must be associated with the
|
|
same <code><a href="#datatransfer">DataTransfer</a></code> object as the
|
|
<code><a href="#datatransferitems">DataTransferItems</a></code> object when it is first created.</p>
|
|
|
|
<p>To <dfn id="dom-datatransferitems-removeitem" title="dom-DataTransferItems-removeItem">delete an
|
|
existing indexed property</dfn> <var title="">i</var> of a
|
|
<code><a href="#datatransferitems">DataTransferItems</a></code> object, the user agent must run these
|
|
steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransferitems">DataTransferItems</a></code> object is not in the
|
|
<i title="concept-dnd-rw"><a href="#concept-dnd-rw">read/write mode</a></i>, throw an
|
|
<code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>Remove the <var title="">i</var>th item from the <a href="#drag-data-store">drag
|
|
data store</a>.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransferitems-clear" title="dom-DataTransferItems-clear"><code>clear</code></dfn> method,
|
|
if the <code><a href="#datatransferitems">DataTransferItems</a></code> object is in the <i title="concept-dnd-rw"><a href="#concept-dnd-rw">read/write mode</a></i>, must remove all the
|
|
items from the <a href="#drag-data-store">drag data store</a>. Otherwise, it must do
|
|
nothing.</p>
|
|
|
|
<p>The <dfn id="dom-datatransferitems-add" title="dom-DataTransferItems-add"><code>add()</code></dfn> method
|
|
must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransferitems">DataTransferItems</a></code> object is not in the
|
|
<i title="concept-dnd-rw"><a href="#concept-dnd-rw">read/write mode</a></i>, return null and
|
|
abort these steps.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Jump to the appropriate set of steps from the following list:</p>
|
|
|
|
<dl class="switch"><dt>If the first argument to the method is a string</dt>
|
|
|
|
<dd>
|
|
|
|
<p>If there is already an item in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item
|
|
kind">kind</a> is <i>Plain Unicode string</i> and whose <a href="#the-drag-data-item-type-string" title="the drag data item type string">type string</a> is
|
|
equal to the value of the method's second argument,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>, then throw a
|
|
<code><a href="common-dom-interfaces.html#not_supported_err">NOT_SUPPORTED_ERR</a></code> exception and abort these
|
|
steps.</p>
|
|
|
|
<p>Otherwise, add an item to the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item
|
|
kind">kind</a> is <i>Plain Unicode string</i>, whose <a href="#the-drag-data-item-type-string" title="the drag data item type string">type string</a> is
|
|
equal to the value of the method's second argument,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>, and whose data is the
|
|
string given by the method's first argument.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the first argument to the method is a <code><a href="infrastructure.html#file">File</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Add an item to the <a href="#drag-data-store-item-list">drag data store item list</a>
|
|
whose <a href="#the-drag-data-item-kind" title="the drag data item kind">kind</a> is
|
|
<i><a href="infrastructure.html#file">File</a></i>, whose <a href="#the-drag-data-item-type-string" title="the drag data item type
|
|
string">type string</a> is the <code title="dom-Blob-type">type</code> of the <code><a href="infrastructure.html#file">File</a></code>,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>, and whose data is the
|
|
same as the <code><a href="infrastructure.html#file">File</a></code>'s data.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
</dl></li>
|
|
|
|
<li><p><a href="#dom-datatransferitems-item" title="dom-DataTransferItems-item">Determine the value
|
|
of the indexed property</a> corresponding to the newly added
|
|
item, and return that value (a newly created
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object).</p></li>
|
|
|
|
</ol></div><h5 id="the-datatransferitem-interface"><span class="secno">7.7.3.2 </span>The <code><a href="#datatransferitem">DataTransferItem</a></code> interface</h5><p>Each <code><a href="#datatransferitem">DataTransferItem</a></code> object is associated with a
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object.</p><pre class="idl">interface <dfn id="datatransferitem">DataTransferItem</dfn> {
|
|
readonly attribute DOMString <a href="#dom-datatransferitem-kind" title="dom-DataTransferItem-kind">kind</a>;
|
|
readonly attribute DOMString <a href="#dom-datatransferitem-type" title="dom-DataTransferItem-type">type</a>;
|
|
void <a href="#dom-datatransferitem-getasstring" title="dom-DataTransferItem-getAsString">getAsString</a>(in <a href="#functionstringcallback">FunctionStringCallback</a> callback); <a href="infrastructure.html#file">File</a> <a href="#dom-datatransferitem-getasfile" title="dom-DataTransferItem-getAsFile">getAsFile</a>();};
|
|
|
|
[Callback=FunctionOnly, NoInterfaceObject]
|
|
interface <dfn id="functionstringcallback">FunctionStringCallback</dfn> {
|
|
void <span title="dom-FunctionStringCallback-handleEvent">handleEvent</span>(in DOMString data);
|
|
};</pre><dl class="domintro"><dt><var title="">item</var> . <code title="dom-DataTransferItem-kind"><a href="#dom-datatransferitem-kind">kind</a></code></dt>
|
|
<dd>
|
|
|
|
<p>Returns <a href="#the-drag-data-item-kind">the drag data item kind</a>, one of: "string",
|
|
"file".</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">item</var> . <code title="dom-DataTransferItem-type"><a href="#dom-datatransferitem-type">type</a></code></dt>
|
|
<dd>
|
|
|
|
<p>Returns <a href="#the-drag-data-item-type-string">the drag data item type string</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">item</var> . <code title="dom-DataTransferItem-getAsString"><a href="#dom-datatransferitem-getasstring">getAsString</a></code>(<var title="">callback</var>)</dt>
|
|
<dd>
|
|
|
|
<p>Invokes the callback with the string data as the argument, if <a href="#the-drag-data-item-kind">the drag data item kind</a> is <i>Plain Unicode string</i>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">file</var> = <var title="">item</var> . <code title="dom-DataTransferItem-getAsFile"><a href="#dom-datatransferitem-getasfile">getAsFile</a></code>()</dt>
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="infrastructure.html#file">File</a></code> object, if <a href="#the-drag-data-item-kind">the drag data item kind</a> is <i><a href="infrastructure.html#file">File</a></i>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>While the <code><a href="#datatransferitem">DataTransferItem</a></code> object's
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object is associated with a <a href="#drag-data-store">drag
|
|
data store</a> and that <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-item-list">drag
|
|
data store item list</a> still contains the item that the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object represents, the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object's <i>mode</i> is the same as
|
|
the <a href="#drag-data-store-mode">drag data store mode</a>. When the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object's <code><a href="#datatransfer">DataTransfer</a></code>
|
|
object is <em>not</em> associated with a <a href="#drag-data-store">drag data
|
|
store</a>, or if the item that the <code><a href="#datatransferitem">DataTransferItem</a></code>
|
|
object represents has been removed from the relevant <a href="#drag-data-store-item-list">drag data
|
|
store item list</a>, the <code><a href="#datatransferitem">DataTransferItem</a></code> object's
|
|
<i>mode</i> is the <i>disabled mode</i>. The <a href="#drag-data-store">drag data
|
|
store</a> referenced in this section (which is used only when the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object is not in the <i>disabled
|
|
mode</i>) is the <a href="#drag-data-store">drag data store</a> with which the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object's <code><a href="#datatransfer">DataTransfer</a></code>
|
|
object is associated.</p>
|
|
|
|
<p>The <dfn id="dom-datatransferitem-kind" title="dom-DataTransferItem-kind"><code>kind</code></dfn> attribute
|
|
must return the empty string if the <code><a href="#datatransferitem">DataTransferItem</a></code>
|
|
object is in the <i>disabled mode</i>; otherwise it must return the
|
|
string given in the cell from the second column of the following
|
|
table from the row whose cell in the first column contains <a href="#the-drag-data-item-kind">the
|
|
drag data item kind</a> of the item represented by the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object:</p>
|
|
|
|
<table><thead><tr><th> Kind </th><th> String
|
|
</th></tr></thead><tbody><tr><td> <i>Plain Unicode string</i> </td><td> "<code title="">string</code>"
|
|
</td></tr><tr><td> <i><a href="infrastructure.html#file">File</a></i> </td><td> "<code title="">file</code>"
|
|
</td></tr></tbody></table><p>The <dfn id="dom-datatransferitem-type" title="dom-DataTransferItem-type"><code>type</code></dfn> attribute
|
|
must return the empty string if the <code><a href="#datatransferitem">DataTransferItem</a></code>
|
|
object is in the <i>disabled mode</i>; otherwise it must return
|
|
<a href="#the-drag-data-item-type-string">the drag data item type string</a> of the item represented
|
|
by the <code><a href="#datatransferitem">DataTransferItem</a></code> object.</p>
|
|
|
|
<p>The <dfn id="dom-datatransferitem-getasstring" title="dom-DataTransferItem-getAsString"><code>getAsString(<var title="">callback</var>)</code></dfn> method must run the following
|
|
steps:</p>
|
|
|
|
<ol><li><p>If the <var title="">callback</var> is null, abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>If the <code><a href="#datatransferitem">DataTransferItem</a></code> object is not in the <i title="concept-dnd-rw"><a href="#concept-dnd-rw">read/write mode</a></i> or the <i title="concept-dnd-ro"><a href="#concept-dnd-ro">read-only mode</a></i>, abort these steps. The
|
|
callback is never invoked.</p></li>
|
|
|
|
<li><p>If <a href="#the-drag-data-item-kind">the drag data item kind</a> is not <i>Plain
|
|
Unicode string</i>, abort these steps. The callback is never
|
|
invoked.</p></li>
|
|
|
|
<li><p>Otherwise, <a href="webappapis.html#queue-a-task">queue a task</a> to invoke <var title="">callback</var>, passing the actual data of the item
|
|
represented by the <code><a href="#datatransferitem">DataTransferItem</a></code> object as the
|
|
argument.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-datatransferitem-getasfile" title="dom-DataTransferItem-getAsFile"><code>getAsFile()</code></dfn>
|
|
method must run the following steps:</p>
|
|
|
|
<ol><li><p>If the <code><a href="#datatransferitem">DataTransferItem</a></code> object is not in the <i title="concept-dnd-rw"><a href="#concept-dnd-rw">read/write mode</a></i> or the <i title="concept-dnd-ro"><a href="#concept-dnd-ro">read-only mode</a></i>, return null and abort
|
|
these steps.</p></li>
|
|
|
|
<li><p>If <a href="#the-drag-data-item-kind">the drag data item kind</a> is not <i><a href="infrastructure.html#file">File</a></i>,
|
|
then return null and abort these steps.</p></li>
|
|
|
|
<li><p>Return a new <code><a href="infrastructure.html#file">File</a></code> object representing the
|
|
actual data of the item represented by the
|
|
<code><a href="#datatransferitem">DataTransferItem</a></code> object.</p>
|
|
|
|
</li></ol></div><h4 id="the-dragevent-interface"><span class="secno">7.7.4 </span>The <code><a href="#dragevent">DragEvent</a></code> interface</h4><p>The drag-and-drop processing model involves several events. They
|
|
all use the <code><a href="#dragevent">DragEvent</a></code> interface.</p><pre class="idl">interface <dfn id="dragevent">DragEvent</dfn> : <a href="infrastructure.html#mouseevent">MouseEvent</a> {
|
|
readonly attribute <a href="#datatransfer">DataTransfer</a> <a href="#dom-dragevent-datatransfer" title="dom-DragEvent-dataTransfer">dataTransfer</a>;
|
|
|
|
void <a href="#dom-dragevent-initdragevent" title="dom-DragEvent-initDragEvent">initDragEvent</a>(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in any dummyArg, in long detailArg, in long screenXArg, in long screenYArg, in long clientXArg, in long clientYArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in unsigned short buttonArg, in EventTarget relatedTargetArg, in <a href="#datatransfer">DataTransfer</a> dataTransferArg);
|
|
};</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-DragEvent-dataTransfer"><a href="#dom-dragevent-datatransfer">dataTransfer</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <code><a href="#datatransfer">DataTransfer</a></code> object for the event.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-dragevent-initdragevent" title="dom-DragEvent-initDragEvent"><code>initDragEvent()</code></dfn>
|
|
method must initialize the event in a manner analogous to the
|
|
similarly-named method in the DOM Events interfaces, except that the
|
|
<var title="">dummyArg</var> argument must be ignored. <a href="references.html#refsDOMEVENTS">[DOMEVENTS]</a></p>
|
|
|
|
<p>The <dfn id="dom-dragevent-datatransfer" title="dom-DragEvent-dataTransfer"><code>dataTransfer</code></dfn>
|
|
attribute of the <code><a href="#dragevent">DragEvent</a></code> interface represents the
|
|
context information for the event.</p>
|
|
|
|
</div><div class="impl">
|
|
|
|
<p>When a user agent is required to <dfn id="fire-a-dnd-event">fire a DND event</dfn>
|
|
named <var title="">e</var> at an element, using a particular
|
|
<a href="#drag-data-store">drag data store</a>, the user agent must run the following
|
|
steps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If <var title="">e</var> is <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code>, set the <a href="#drag-data-store-mode">drag data
|
|
store mode</a> to the <a href="#concept-dnd-rw" title="concept-dnd-rw">read/write
|
|
mode</a>.</p>
|
|
|
|
<p>If <var title="">e</var> is <code title="event-drop"><a href="#event-drop">drop</a></code>, set the <a href="#drag-data-store-mode">drag data store
|
|
mode</a> to the <a href="#concept-dnd-ro" title="concept-dnd-ro">read-only
|
|
mode</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Let <var title="">dataTransfer</var> be a newly created
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object associated with the given
|
|
<a href="#drag-data-store">drag data store</a>.</p></li>
|
|
|
|
<li><p id="effectAllowed-initialization">Set the <code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute to the <a href="#drag-data-store">drag data store</a>'s <a href="#drag-data-store-allowed-effects-state">drag data
|
|
store allowed effects state</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p id="dropEffect-initialization">Set the <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> attribute to
|
|
"<code title="">none</code>" if <var title="">e</var> is <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code>, <code title="event-drag"><a href="#event-drag">drag</a></code>, or <code title="event-dragleave"><a href="#event-dragleave">dragleave</a></code>; to the value
|
|
corresponding to the <a href="#current-drag-operation">current drag operation</a> if <var title="">e</var> is <code title="event-drop"><a href="#event-drop">drop</a></code> or <code title="event-dragend"><a href="#event-dragend">dragend</a></code>; and to a value based on the
|
|
<code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute's value and to the drag-and-drop source, as given by the
|
|
following table, otherwise (i.e. if <var title="">e</var> is <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code> or <code title="event-dragover"><a href="#event-dragover">dragover</a></code>):</p>
|
|
|
|
<table><thead><tr><th><code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code></th>
|
|
<th><code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code></th>
|
|
</tr></thead><tr><td>"<code title="">none</code>"</td>
|
|
<td>"<code title="">none</code>"</td>
|
|
</tr><tr><td>"<code title="">copy</code>", "<code title="">copyLink</code>", "<code title="">copyMove</code>", "<code title="">all</code>"</td>
|
|
<td>"<code title="">copy</code>"</td>
|
|
</tr><tr><td>"<code title="">link</code>", "<code title="">linkMove</code>"</td>
|
|
<td>"<code title="">link</code>"</td>
|
|
</tr><tr><td>"<code title="">move</code>"</td>
|
|
<td>"<code title="">move</code>"</td>
|
|
</tr><tr><td>"<code title="">uninitialized</code>" when what is being dragged is a selection from a text field</td>
|
|
<td>"<code title="">move</code>"</td>
|
|
</tr><tr><td>"<code title="">uninitialized</code>" when what is being dragged is a selection</td>
|
|
<td>"<code title="">copy</code>"</td>
|
|
</tr><tr><td>"<code title="">uninitialized</code>" when what is being dragged is an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element with an <code>href</code> attribute</td>
|
|
<td>"<code title="">link</code>"</td>
|
|
</tr><tr><td>Any other case</td>
|
|
<td>"<code title="">copy</code>"</td>
|
|
</tr></table></li>
|
|
|
|
<li>
|
|
|
|
<p>Create a <code><a href="#dragevent">DragEvent</a></code> object and initialize it to
|
|
have the given name <var title="">e</var>, to bubble, to be
|
|
cancelable unless <var title="">e</var> is <code title="event-dragleave"><a href="#event-dragleave">dragleave</a></code> or <code title="event-dragend"><a href="#event-dragend">dragend</a></code>, and to have the <code title="dom-UIEvent-detail">detail</code> attribute set to zero,
|
|
the mouse and key attributes set according to the state of the
|
|
input devices as they would be for user interaction events, the
|
|
<code title="">relatedTarget</code> attribute set to null, and the
|
|
<code title="dom-DragEvent-dataTransfer"><a href="#dom-dragevent-datatransfer">dataTransfer</a></code>
|
|
attribute set to <var title="">dataTransfer</var>, the
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object created above.</p>
|
|
|
|
|
|
|
|
<p>If there is no relevant pointing device, the object must have
|
|
its <code title="">screenX</code>, <code title="">screenY</code>,
|
|
<code title="">clientX</code>, <code title="">clientY</code>, and
|
|
<code title="">button</code> attributes set to 0.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Dispatch the newly created <code><a href="#dragevent">DragEvent</a></code> object at
|
|
the specified target element.</p></li>
|
|
|
|
<li><p>Set the <a href="#drag-data-store-allowed-effects-state">drag data store allowed effects state</a>
|
|
to the current value of <var title="">dataTransfer</var>'s <code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute.</p></li>
|
|
|
|
<li><p>Set the <a href="#drag-data-store-mode">drag data store mode</a> back to the <a href="#concept-dnd-p" title="concept-dnd-p">protected mode</a> if it was changed in
|
|
the first step.</p></li>
|
|
|
|
<li><p>Break the association between <var title="">dataTransfer</var> and the <a href="#drag-data-store">drag data
|
|
store</a>.</p></li>
|
|
|
|
</ol></div><div class="impl">
|
|
|
|
<h4 id="drag-and-drop-processing-model"><span class="secno">7.7.5 </span>Drag-and-drop processing model</h4>
|
|
|
|
<p>When the user attempts to begin a drag operation, the user agent
|
|
must run the following steps. User agents must act as if these steps
|
|
were run even if the drag actually started in another document or
|
|
application and the user agent was not aware that the drag was
|
|
occuring until it intersected with a document under the user agent's
|
|
purview.</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>Determine what is being dragged, as follows:</p>
|
|
|
|
<p>If the drag operation was invoked on a selection, then it is
|
|
the selection that is being dragged.</p>
|
|
|
|
<p>Otherwise, if the drag operation was invoked on a
|
|
<code><a href="infrastructure.html#document">Document</a></code>, it is the first element, going up the
|
|
ancestor chain, starting at the node that the user tried to drag,
|
|
that has the IDL attribute <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> set to true. If there is no
|
|
such element, then nothing is being dragged; abort these steps,
|
|
the drag-and-drop operation is never started.</p>
|
|
|
|
<p>Otherwise, the drag operation was invoked outside the user
|
|
agent's purview. What is being dragged is defined by the document
|
|
or application where the drag was started.</p>
|
|
|
|
<p class="note"><code><a href="embedded-content-1.html#the-img-element">img</a></code> elements and <code><a href="text-level-semantics.html#the-a-element">a</a></code>
|
|
elements with an <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code>
|
|
attribute have their <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code>
|
|
attribute set to true by default.</p>
|
|
|
|
</li>
|
|
|
|
<li><p><a href="#create-a-drag-data-store">Create a drag data store</a>. All the DND events
|
|
fired subsequently by the steps in this section must use this
|
|
<a href="#drag-data-store">drag data store</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Establish which DOM node is the <dfn id="source-node">source node</dfn>, as
|
|
follows:</p>
|
|
|
|
<p>If it is a selection that is being dragged, then the
|
|
<a href="#source-node">source node</a> is the text node that the user started
|
|
the drag on (typically the text node that the user originally
|
|
clicked). If the user did not specify a particular node, for
|
|
example if the user just told the user agent to begin a drag of
|
|
"the selection", then the <a href="#source-node">source node</a> is the first
|
|
text node containing a part of the selection.</p>
|
|
|
|
<p>Otherwise, if it is an element that is being dragged, then the
|
|
<a href="#source-node">source node</a> is the element that is being dragged.</p>
|
|
|
|
<p>Otherwise, the <a href="#source-node">source node</a> is part of another
|
|
document or application. When this specification requires that an
|
|
event be dispatched at the <a href="#source-node">source node</a> in this case,
|
|
the user agent must instead follow the platform-specific
|
|
conventions relevant to that situation.</p>
|
|
|
|
<p class="note">Multiple events are fired on the <a href="#source-node">source
|
|
node</a> during the course of the drag-and-drop operation.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Determine the <dfn id="list-of-dragged-nodes">list of dragged nodes</dfn>, as follows:</p>
|
|
|
|
<p>If it is a selection that is being dragged, then the <a href="#list-of-dragged-nodes">list
|
|
of dragged nodes</a> contains, in <a href="infrastructure.html#tree-order">tree order</a>,
|
|
every node that is partially or completely included in the
|
|
selection (including all their ancestors).</p>
|
|
|
|
<p>Otherwise, the <a href="#list-of-dragged-nodes">list of dragged nodes</a> contains only
|
|
the <a href="#source-node">source node</a>, if any.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If it is a selection that is being dragged, then add an item to
|
|
the <a href="#drag-data-store-item-list">drag data store item list</a>, with its properties
|
|
set as follows:</p>
|
|
|
|
<dl><dt><a href="#the-drag-data-item-type-string">The drag data item type string</a>
|
|
</dt><dd>"<code>text/plain</code>"</dd>
|
|
|
|
<dt><a href="#the-drag-data-item-kind">The drag data item kind</a>
|
|
</dt><dd><i>Plain Unicode string</i></dd>
|
|
|
|
<dt>The actual data</dt>
|
|
<dd>The text of the selection</dd>
|
|
|
|
</dl><p>Otherwise, if any files are being dragged, then add one item
|
|
per file to the <a href="#drag-data-store-item-list">drag data store item list</a>, with their
|
|
properties set as follows:</p>
|
|
|
|
<dl><dt><a href="#the-drag-data-item-type-string">The drag data item type string</a>
|
|
</dt><dd>The MIME type of the file, if known, or "<code>application/octet-stream</code>" otherwise.</dd>
|
|
|
|
<dt><a href="#the-drag-data-item-kind">The drag data item kind</a>
|
|
</dt><dd><i><a href="infrastructure.html#file">File</a></i></dd>
|
|
|
|
<dt>The actual data</dt>
|
|
<dd>The file's contents and name.</dd>
|
|
|
|
</dl><p class="note">Dragging files can currently only happen from
|
|
outside a <a href="browsers.html#browsing-context">browsing context</a>, for example from a file
|
|
system manager application.</p>
|
|
|
|
<p>If the drag initiated outside of the application, the user
|
|
agent must add items to the <a href="#drag-data-store-item-list">drag data store item list</a>
|
|
as appropriate for the data being dragged, honoring platform
|
|
conventions where appropriate; however, if the platform
|
|
conventions do not use <a href="infrastructure.html#mime-type" title="MIME type">MIME types</a>
|
|
to label dragged data, the user agent must make a best-effort
|
|
attempt to map the types to MIME types, and, in any case, all the
|
|
<a href="#the-drag-data-item-type-string" title="the drag data item type string">drag data item type
|
|
strings</a> must be <a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII
|
|
lowercase</a>.</p>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li>Perform <dfn id="drag-and-drop-initialization-steps">drag-and-drop initialization steps</dfn> defined
|
|
in any <a href="infrastructure.html#other-applicable-specifications">other applicable specifications</a>.</li>
|
|
|
|
|
|
<li>
|
|
|
|
<p>Run the following substeps:</p>
|
|
|
|
<ol><li><p>Let <var title="">urls</var> be an empty list of <a href="urls.html#absolute-url" title="absolute URL">absolute URLs</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>For each <var title="">node</var> in the <a href="#list-of-dragged-nodes">list of
|
|
dragged nodes</a>:</p>
|
|
|
|
<dl><dt>If the node is an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element with an <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code> attribute</dt>
|
|
|
|
<dd>Add to <var title="">urls</var> the result of <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> the element's <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code> content attribute
|
|
relative to the element.</dd>
|
|
|
|
<dt>If the node is an <code><a href="embedded-content-1.html#the-img-element">img</a></code> element with an <code title="attr-img-src"><a href="embedded-content-1.html#attr-img-src">src</a></code> attribute</dt>
|
|
|
|
<dd>Add to <var title="">urls</var> the result of <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> the element's <code title="attr-img-src"><a href="embedded-content-1.html#attr-img-src">src</a></code> content attribute relative to
|
|
the element.</dd>
|
|
|
|
|
|
|
|
</dl></li>
|
|
|
|
<li><p>If <var title="">urls</var> is still empty, abort these
|
|
substeps.</p></li>
|
|
|
|
<li><p>Let <var title="">url string</var> be the result of
|
|
concatenating the strings in <var title="">urls</var>, in the
|
|
order they were added, separated by a U+000D CARRIAGE RETURN
|
|
U+000A LINE FEED character pair (CRLF).</p></li>
|
|
|
|
<li><p>Add one item to the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a>, with its properties set as follows:</p>
|
|
|
|
<dl><dt><a href="#the-drag-data-item-type-string">The drag data item type string</a>
|
|
</dt><dd><code>text/uri-list</code></dd>
|
|
|
|
<dt><a href="#the-drag-data-item-kind">The drag data item kind</a>
|
|
</dt><dd><i>Plain Unicode string</i></dd>
|
|
|
|
<dt>The actual data</dt>
|
|
<dd><var title="">url string</var></dd>
|
|
|
|
</dl></li>
|
|
|
|
</ol></li>
|
|
|
|
<li>
|
|
|
|
<p>If it is an element that is being dragged, then set the
|
|
<a href="#drag-data-store-elements-list">drag data store elements list</a> to contain just the
|
|
<a href="#source-node">source node</a>.</p>
|
|
|
|
<p>Otherwise, update the <a href="#drag-data-store-default-feedback">drag data store default
|
|
feedback</a> as appropriate for the user agent (if the user is
|
|
dragging the selection, then the selection would likely be the
|
|
basis for this feedback; if the drag began outside the user agent,
|
|
then the platform conventions for determining the drag feedback
|
|
should be used).</p>
|
|
|
|
<p class="note">Script can use the <code title="dom-DataTransfer-addElement"><a href="#dom-datatransfer-addelement">addElement()</a></code> method to
|
|
add further elements to the list of what is being dragged. (This
|
|
list is only used for rendering the drag feedback.)</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p><a href="#fire-a-dnd-event">Fire a DND event</a> named <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> at the <a href="#source-node">source
|
|
node</a>.</p>
|
|
|
|
<p>If the event is canceled, then the drag-and-drop operation
|
|
should not occur; abort these steps.</p>
|
|
<p class="note">Since events with no event listeners registered
|
|
are, almost by definition, never canceled, drag-and-drop is always
|
|
available to the user if the author does not specifically prevent
|
|
it.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p><a href="#initiate-the-drag-and-drop-operation">Initiate the drag-and-drop operation</a> in a manner
|
|
consistent with platform conventions, and as described below.</p>
|
|
|
|
<p id="base-dnd-feedback">The drag-and-drop feedback must be
|
|
generated from the first of the following sources that is
|
|
available:</p>
|
|
|
|
<ol><li>The <a href="#drag-data-store-bitmap">drag data store bitmap</a>, if any. In this
|
|
case, the <a href="#drag-data-store-hot-spot-coordinate">drag data store hot spot coordinate</a> should
|
|
be used as hints for where to put the cursor relative to the
|
|
resulting image. The values are expressed as distances in CSS
|
|
pixels from the left side and from the top side of the image
|
|
respectively. <a href="references.html#refsCSS">[CSS]</a></li>
|
|
|
|
<li>The elements in the <a href="#drag-data-store-elements-list">drag data store elements
|
|
list</a>, if any.</li>
|
|
|
|
<li>The <a href="#drag-data-store-default-feedback">drag data store default feedback</a>.</li>
|
|
|
|
</ol></li>
|
|
|
|
</ol><p>From the moment that the user agent is to <dfn id="initiate-the-drag-and-drop-operation">initiate the
|
|
drag-and-drop operation</dfn>, until the end of the drag-and-drop
|
|
operation, device input events (e.g. mouse and keyboard events) must
|
|
be suppressed. In addition, the user agent must track all DOM
|
|
changes made during the drag-and-drop operation, and add them to its
|
|
<span>undo transaction history</span> as one atomic operation once
|
|
the drag-and-drop operation has ended.</p>
|
|
|
|
<p>During the drag operation, the element directly indicated by the
|
|
user as the drop target is called the <dfn id="immediate-user-selection">immediate user
|
|
selection</dfn>. (Only elements can be selected by the user; other
|
|
nodes must not be made available as drop targets.) However, the
|
|
<a href="#immediate-user-selection">immediate user selection</a> is not necessarily the
|
|
<dfn id="current-target-element">current target element</dfn>, which is the element currently
|
|
selected for the drop part of the drag-and-drop operation.</p>
|
|
|
|
<p>The <a href="#immediate-user-selection">immediate user selection</a> changes as the user
|
|
selects different elements (either by pointing at them with a
|
|
pointing device, or by selecting them in some other way). The
|
|
<a href="#current-target-element">current target element</a> changes when the <a href="#immediate-user-selection">immediate
|
|
user selection</a> changes, based on the results of event
|
|
listeners in the document, as described below.</p>
|
|
|
|
<p>Both the <a href="#current-target-element">current target element</a> and the
|
|
<a href="#immediate-user-selection">immediate user selection</a> can be null, which means no
|
|
target element is selected. They can also both be elements in other
|
|
(DOM-based) documents, or other (non-Web) programs altogether. (For
|
|
example, a user could drag text to a word-processor.) The
|
|
<a href="#current-target-element">current target element</a> is initially null.</p>
|
|
|
|
<p>In addition, there is also a <dfn id="current-drag-operation">current drag operation</dfn>,
|
|
which can take on the values "<code title="">none</code>", "<code title="">copy</code>", "<code title="">link</code>", and "<code title="">move</code>". Initially, it has the value "<code title="">none</code>". It is updated by the user agent as described
|
|
in the steps below.</p>
|
|
|
|
<p>User agents must, as soon as the drag operation is <a href="#initiate-the-drag-and-drop-operation" title="initiate the drag-and-drop operation">initiated</a> and
|
|
every 350ms (±200ms) thereafter for as long as the drag
|
|
operation is ongoing, <a href="webappapis.html#queue-a-task">queue a task</a> to perform the
|
|
following steps in sequence:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If the user agent is still performing the previous iteration of
|
|
the sequence (if any) when the next iteration becomes due, abort
|
|
these steps for this iteration (effectively "skipping missed
|
|
frames" of the drag-and-drop operation).</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p><a href="#fire-a-dnd-event">Fire a DND event</a> named <code title="event-drag"><a href="#event-drag">drag</a></code> event at the <a href="#source-node">source
|
|
node</a>. If this event is canceled, the user agent must set
|
|
the <a href="#current-drag-operation">current drag operation</a> to "<code title="">none</code>" (no drag operation).</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the <code title="event-drag"><a href="#event-drag">drag</a></code> event was not
|
|
canceled and the user has not ended the drag-and-drop operation,
|
|
check the state of the drag-and-drop operation, as follows:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If the user is indicating a different <a href="#immediate-user-selection">immediate user
|
|
selection</a> than during the last iteration (or if this is
|
|
the first iteration), and if this <a href="#immediate-user-selection">immediate user
|
|
selection</a> is not the same as the <a href="#current-target-element">current target
|
|
element</a>, then update the <a href="#current-target-element">current target
|
|
element</a> as follows:</p>
|
|
|
|
<dl class="switch"><dt>If the new <a href="#immediate-user-selection">immediate user selection</a> is null</dt>
|
|
|
|
<dd><p>Set the <a href="#current-target-element">current target element</a> to null
|
|
also.</p></dd>
|
|
|
|
<dt>If the new <a href="#immediate-user-selection">immediate user selection</a> is in a
|
|
non-DOM document or application</dt>
|
|
|
|
<dd><p>Set the <a href="#current-target-element">current target element</a> to the
|
|
<a href="#immediate-user-selection">immediate user selection</a>.</p></dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<p><a href="#fire-a-dnd-event">Fire a DND event</a> named <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code> at the
|
|
<a href="#immediate-user-selection">immediate user selection</a>.</p>
|
|
|
|
<p>If the event is canceled, then set the <a href="#current-target-element">current target
|
|
element</a> to the <a href="#immediate-user-selection">immediate user
|
|
selection</a>.</p>
|
|
|
|
<p>Otherwise, run the appropriate step from the following
|
|
list:</p>
|
|
|
|
<dl class="switch"><dt>If the <a href="#current-target-element">current target element</a> is a text
|
|
field (e.g. <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>, or an <code><a href="the-input-element.html#the-input-element">input</a></code>
|
|
element whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code>
|
|
attribute is in the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state) or an
|
|
<a href="editing.html#editable">editable</a> element, and the <a href="#drag-data-store-item-list">drag data store
|
|
item list</a> has an item with <a href="#the-drag-data-item-type-string">the drag data item
|
|
type string</a> "<code>text/plain</code>" and <a href="#the-drag-data-item-kind">the
|
|
drag data item kind</a> <i>Plain Unicode string</i></dt>
|
|
|
|
<dd><p>Set the <a href="#current-target-element">current target element</a> to the
|
|
<a href="#immediate-user-selection">immediate user selection</a> anyway.</p></dd>
|
|
|
|
|
|
<dt>If the <a href="#current-target-element">current target element</a> is an element
|
|
with a <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute
|
|
that <a href="#concept-dropzone-match" title="concept-dropzone-match">matches</a> the
|
|
<a href="#drag-data-store">drag data store</a></dt>
|
|
|
|
<dd><p>Set the <a href="#current-target-element">current target element</a> to the
|
|
<a href="#immediate-user-selection">immediate user selection</a> anyway.</p></dd>
|
|
|
|
|
|
<dt>If the <a href="#current-target-element">current target element</a> is
|
|
<a href="dom.html#the-body-element-0">the body element</a></dt>
|
|
|
|
<dd><p>Leave the <a href="#current-target-element">current target element</a>
|
|
unchanged.</p></dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<p><a href="#fire-a-dnd-event">Fire a DND event</a> named <code title="event-dragenter"><a href="#event-dragenter">dragenter</a></code> at <a href="dom.html#the-body-element-0">the body
|
|
element</a>, and set the <a href="#current-target-element">current target
|
|
element</a> to <a href="dom.html#the-body-element-0">the body element</a>, regardless
|
|
of whether that event was canceled or not.</p>
|
|
|
|
<p class="note">If <a href="dom.html#the-body-element-0">the body element</a> is null,
|
|
then the event will be fired at the <code><a href="infrastructure.html#document">Document</a></code>
|
|
object (as required by the definition of <a href="dom.html#the-body-element-0">the body
|
|
element</a>), but the <a href="#current-target-element">current target element</a>
|
|
would be set to null, not the <code><a href="infrastructure.html#document">Document</a></code>
|
|
object.</p></dd>
|
|
|
|
</dl></dd>
|
|
|
|
</dl></li>
|
|
|
|
<li>
|
|
|
|
<p>If the previous step caused the <a href="#current-target-element">current target
|
|
element</a> to change, and if the previous target element was
|
|
not null or a part of a non-DOM document, then <a href="#fire-a-dnd-event">fire a DND
|
|
event</a> named <code title="event-dragleave"><a href="#event-dragleave">dragleave</a></code> at the previous target
|
|
element.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the <a href="#current-target-element">current target element</a> is a DOM element,
|
|
then <a href="#fire-a-dnd-event">fire a DND event</a> named <code title="event-dragover"><a href="#event-dragover">dragover</a></code> at this <a href="#current-target-element">current
|
|
target element</a>.</p>
|
|
|
|
<p>If the <code title="event-dragover"><a href="#event-dragover">dragover</a></code> event is
|
|
not canceled, run the appropriate step from the following
|
|
list:</p>
|
|
|
|
<dl class="switch"><dt>If the <a href="#current-target-element">current target element</a> is a text field
|
|
(e.g. <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>, or an <code><a href="the-input-element.html#the-input-element">input</a></code> element
|
|
whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code> attribute is in
|
|
the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state) or an
|
|
<a href="editing.html#editable">editable</a> element, and the <a href="#drag-data-store-item-list">drag data store
|
|
item list</a> has an item with <a href="#the-drag-data-item-type-string">the drag data item type
|
|
string</a> "<code>text/plain</code>" and <a href="#the-drag-data-item-kind">the drag data
|
|
item kind</a> <i>Plain Unicode string</i></dt>
|
|
|
|
<dd><p>Set the <a href="#current-drag-operation">current drag operation</a> to either
|
|
"<code title="">copy</code>" or "<code title="">move</code>",
|
|
as appropriate given the platform conventions.</p></dd>
|
|
|
|
|
|
<dt>If the <a href="#current-target-element">current target element</a> is an element
|
|
with a <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute
|
|
that <a href="#concept-dropzone-match" title="concept-dropzone-match">matches</a> the
|
|
<a href="#drag-data-store">drag data store</a> and <a href="#concept-dropzone-operation" title="concept-dropzone-operation">specifies an
|
|
operation</a></dt>
|
|
|
|
<dd><p>Set the <a href="#current-drag-operation">current drag operation</a> to the
|
|
operation <a href="#concept-dropzone-operation" title="concept-dropzone-operation">specified</a> by the
|
|
<code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute of the
|
|
<a href="#current-target-element">current target element</a>.</p>
|
|
|
|
|
|
</dd><dt>If the <a href="#current-target-element">current target element</a> is an element
|
|
with a <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute
|
|
that <a href="#concept-dropzone-match" title="concept-dropzone-match">matches</a> the
|
|
<a href="#drag-data-store">drag data store</a> and does not <a href="#concept-dropzone-operation" title="concept-dropzone-operation">specify an
|
|
operation</a></dt>
|
|
|
|
<dd><p>Set the <a href="#current-drag-operation">current drag operation</a> to "<code title="">copy</code>".</p>
|
|
|
|
|
|
</dd><dt>Otherwise</dt>
|
|
|
|
<dd><p>Reset the <a href="#current-drag-operation">current drag operation</a> to "<code title="">none</code>".</p></dd>
|
|
|
|
</dl><p>Otherwise (if the <code title="event-dragover"><a href="#event-dragover">dragover</a></code> event <em>is</em>
|
|
canceled), set the <a href="#current-drag-operation">current drag operation</a> based on
|
|
the values of the <code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code> and
|
|
<code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code>
|
|
attributes of the <code><a href="#dragevent">DragEvent</a></code> object's <code title="dom-DragEvent-dataTransfer"><a href="#dom-dragevent-datatransfer">dataTransfer</a></code> object as
|
|
they stood after the event dispatch finished, as per the
|
|
following table:</p>
|
|
|
|
<table><thead><tr><th><code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code></th>
|
|
<th><code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code></th>
|
|
<th>Drag operation</th>
|
|
</tr></thead><tr><td>"<code title="">uninitialized</code>", "<code title="">copy</code>", "<code title="">copyLink</code>", "<code title="">copyMove</code>", or "<code title="">all</code>"</td>
|
|
<td>"<code title="">copy</code>"</td>
|
|
<td>"<code title="">copy</code>"</td>
|
|
</tr><tr><td>"<code title="">uninitialized</code>", "<code title="">link</code>", "<code title="">copyLink</code>", "<code title="">linkMove</code>", or "<code title="">all</code>"</td>
|
|
<td>"<code title="">link</code>"</td>
|
|
<td>"<code title="">link</code>"</td>
|
|
</tr><tr><td>"<code title="">uninitialized</code>", "<code title="">move</code>", "<code title="">copyMove</code>", "<code title="">linkMove</code>", or "<code title="">all</code>"</td>
|
|
<td>"<code title="">move</code>"</td>
|
|
<td>"<code title="">move</code>"</td>
|
|
</tr><tr><td colspan="2">Any other case</td>
|
|
<td>"<code title="">none</code>"</td>
|
|
</tr></table></li>
|
|
|
|
<li>
|
|
|
|
<p>Otherwise, if the <a href="#current-target-element">current target element</a> is not
|
|
a DOM element, use platform-specific mechanisms to determine
|
|
what drag operation is being performed (none, copy, link, or
|
|
move), and set the <i><a href="#current-drag-operation">current drag operation</a></i>
|
|
accordingly.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Update the drag feedback (e.g. the mouse cursor) to match the
|
|
<a href="#current-drag-operation">current drag operation</a>, as follows:</p>
|
|
|
|
<table><thead><tr><th>Drag operation</th>
|
|
<th>Feedback</th>
|
|
</tr></thead><tr><td>"<code title="">copy</code>"</td>
|
|
<td>Data will be copied if dropped here.</td>
|
|
</tr><tr><td>"<code title="">link</code>"</td>
|
|
<td>Data will be linked if dropped here.</td>
|
|
</tr><tr><td>"<code title="">move</code>"</td>
|
|
<td>Data will be moved if dropped here.</td>
|
|
</tr><tr><td>"<code title="">none</code>"</td>
|
|
<td>No operation allowed, dropping here will cancel the drag-and-drop operation.</td>
|
|
</tr></table></li>
|
|
|
|
</ol></li>
|
|
|
|
<li>
|
|
|
|
<p>Otherwise, if the user ended the drag-and-drop operation (e.g.
|
|
by releasing the mouse button in a mouse-driven drag-and-drop
|
|
interface), or if the <code title="event-drag"><a href="#event-drag">drag</a></code> event
|
|
was canceled, then this will be the last iteration. Run the
|
|
following steps, then stop the drag-and-drop operation:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If the <a href="#current-drag-operation">current drag operation</a> is "<code title="">none</code>" (no drag operation), or, if the user ended
|
|
the drag-and-drop operation by canceling it (e.g. by hitting the
|
|
<kbd>Escape</kbd> key), or if the <a href="#current-target-element">current target
|
|
element</a> is null, then the drag operation failed. Run
|
|
these substeps:</p>
|
|
|
|
<ol><li><p>Let <var title="">dropped</var> be false.</p></li>
|
|
|
|
<li><p>If the <a href="#current-target-element">current target element</a> is a DOM
|
|
element, <a href="#fire-a-dnd-event">fire a DND event</a> named <code title="event-dragleave"><a href="#event-dragleave">dragleave</a></code> at it; otherwise, if
|
|
it is not null, use platform-specific conventions for drag
|
|
cancellation.</p>
|
|
|
|
</li></ol><p>Otherwise, the drag operation was as success; run these substeps:</p>
|
|
|
|
<ol><li><p>Let <var title="">dropped</var> be true.</p></li>
|
|
|
|
<li><p>If the <a href="#current-target-element">current target element</a> is a DOM
|
|
element, <a href="#fire-a-dnd-event">fire a DND event</a> named <code title="event-drop"><a href="#event-drop">drop</a></code> at it; otherwise, use
|
|
platform-specific conventions for indicating a drop.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the event is canceled, set the <a href="#current-drag-operation">current drag
|
|
operation</a> to the value of the <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> attribute
|
|
of the <code><a href="#dragevent">DragEvent</a></code> object's <code title="dom-DragEvent-dataTransfer"><a href="#dom-dragevent-datatransfer">dataTransfer</a></code> object
|
|
as it stood after the event dispatch finished.</p>
|
|
|
|
<p>Otherwise, the event is not canceled; perform the event's
|
|
default action, which depends on the exact target as
|
|
follows:</p>
|
|
|
|
<dl class="switch"><dt>If the <a href="#current-target-element">current target element</a> is a text
|
|
field (e.g. <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>, or an <code><a href="the-input-element.html#the-input-element">input</a></code>
|
|
element whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code>
|
|
attribute is in the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state) or an
|
|
<a href="editing.html#editable">editable</a> element, and the <a href="#drag-data-store-item-list">drag data store
|
|
item list</a> has an item with <a href="#the-drag-data-item-type-string">the drag data item
|
|
type string</a> "<code>text/plain</code>" and <a href="#the-drag-data-item-kind">the
|
|
drag data item kind</a> <i>Plain Unicode string</i></dt>
|
|
|
|
<dd><p>Insert the actual data of the first item in the
|
|
<a href="#drag-data-store-item-list">drag data store item list</a> to have <a href="#the-drag-data-item-type-string" title="the drag data item type string">a drag data item type
|
|
string</a> of "<code>text/plain</code>" and <a href="#the-drag-data-item-kind" title="the drag data item kind">a drag data item kind</a>
|
|
that is <i>Plain Unicode string</i> into the text field or
|
|
<a href="editing.html#editable">editable</a> element in a manner consistent with
|
|
platform-specific conventions (e.g. inserting it at the
|
|
current mouse cursor position, or inserting it at the end of
|
|
the field).</p></dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd><p>Reset the <a href="#current-drag-operation">current drag operation</a> to
|
|
"<code title="">none</code>".</p></dd>
|
|
|
|
</dl></li>
|
|
|
|
</ol></li>
|
|
|
|
<li>
|
|
|
|
<p><a href="#fire-a-dnd-event">Fire a DND event</a> named <code title="event-dragend"><a href="#event-dragend">dragend</a></code> at the <a href="#source-node">source
|
|
node</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Run the appropriate steps from the following list as the
|
|
default action of the <code title="event-dragend"><a href="#event-dragend">dragend</a></code>
|
|
event:</p>
|
|
|
|
<dl class="switch"><dt>If the <a href="#current-target-element">current target element</a> is a text field
|
|
(e.g. <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>, or an <code><a href="the-input-element.html#the-input-element">input</a></code> element
|
|
whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code> attribute is in
|
|
the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state), and
|
|
<var title="">dropped</var> is true, and the <a href="#current-drag-operation">current drag
|
|
operation</a> is "<code title="">move</code>", and the
|
|
source of the drag-and-drop operation is a selection in the
|
|
DOM</dt>
|
|
|
|
<dd>The user agent should delete the range representing the
|
|
dragged selection from the DOM.</dd>
|
|
|
|
<dt>If the <a href="#current-target-element">current target element</a> is a text field
|
|
(e.g. <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>, or an <code><a href="the-input-element.html#the-input-element">input</a></code> element
|
|
whose <code title="attr-input-type"><a href="the-input-element.html#attr-input-type">type</a></code> attribute is in
|
|
the <a href="states-of-the-type-attribute.html#text-state-and-search-state" title="attr-input-type-text">Text</a> state), and
|
|
<var title="">dropped</var> is true, and the <a href="#current-drag-operation">current drag
|
|
operation</a> is "<code title="">move</code>", and the
|
|
source of the drag-and-drop operation is a selection in a text
|
|
field</dt>
|
|
|
|
<dd>The user agent should delete the dragged selection from the
|
|
relevant text field.</dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>The event has no default action.</dd>
|
|
|
|
</dl></li>
|
|
|
|
</ol></li>
|
|
|
|
</ol><p class="note">User agents are encouraged to consider how to react
|
|
to drags near the edge of scrollable regions. For example, if a user
|
|
drags a link to the bottom of the viewport on a long page, it might
|
|
make sense to scroll the page so that the user can drop the link
|
|
lower on the page.</p>
|
|
|
|
<p class="note">This model is independent of which
|
|
<code><a href="infrastructure.html#document">Document</a></code> object the nodes involved are from; the events
|
|
are fired as described above and the rest of the processing model
|
|
runs as described above, irrespective of how many documents are
|
|
involved in the operation.</p>
|
|
|
|
</div><h4 id="dndevents"><span class="secno">7.7.6 </span>Events summary</h4><p><i>This section is non-normative.</i></p><p>The following events are involved in the drag-and-drop
|
|
model.</p><table><thead><tr><th> Event Name </th>
|
|
<th> Target </th>
|
|
|
|
<th> Cancelable? </th>
|
|
<th> <a href="#drag-data-store-mode">Drag data store mode</a> </th>
|
|
|
|
<th> <code title="dom-DataTransfer-dropEffect"><a href="#dom-datatransfer-dropeffect">dropEffect</a></code> </th>
|
|
<th> Default Action </th>
|
|
</tr></thead><tbody><tr><td><dfn id="event-dragstart" title="event-dragstart"><code>dragstart</code></dfn></td>
|
|
<td><a href="#source-node">Source node</a></td>
|
|
|
|
<td>✓ Cancelable</td>
|
|
<td><a href="#concept-dnd-rw" title="concept-dnd-rw">Read/write mode</a>
|
|
|
|
</td><td>"<code title="">none</code>"</td>
|
|
<td>Initiate the drag-and-drop operation</td>
|
|
</tr><tr><td><dfn id="event-drag" title="event-drag"><code>drag</code></dfn></td>
|
|
<td><a href="#source-node">Source node</a></td>
|
|
|
|
<td>✓ Cancelable</td>
|
|
<td><a href="#concept-dnd-p" title="concept-dnd-p">Protected mode</a>
|
|
|
|
</td><td>"<code title="">none</code>"</td>
|
|
<td>Continue the drag-and-drop operation</td>
|
|
</tr><tr><td><dfn id="event-dragenter" title="event-dragenter"><code>dragenter</code></dfn></td>
|
|
<td><a href="#immediate-user-selection">Immediate user selection</a> or <a href="dom.html#the-body-element-0">the body element</a></td>
|
|
|
|
<td>✓ Cancelable</td>
|
|
<td><a href="#concept-dnd-p" title="concept-dnd-p">Protected mode</a>
|
|
|
|
</td><td><a href="#dropEffect-initialization">Based on <code>effectAllowed</code> value</a></td>
|
|
<td>Reject <a href="#immediate-user-selection">immediate user selection</a> as potential <a href="#current-target-element" title="current target element">target element</a></td>
|
|
</tr><tr><td><dfn id="event-dragleave" title="event-dragleave"><code>dragleave</code></dfn></td>
|
|
<td><a href="#current-target-element" title="current target element">Previous target element</a></td>
|
|
|
|
<td>—</td>
|
|
<td><a href="#concept-dnd-p" title="concept-dnd-p">Protected mode</a>
|
|
|
|
</td><td>"<code title="">none</code>"</td>
|
|
<td>None</td>
|
|
</tr><tr><td><dfn id="event-dragover" title="event-dragover"><code>dragover</code></dfn></td>
|
|
<td><a href="#current-target-element">Current target element</a></td>
|
|
|
|
<td>✓ Cancelable</td>
|
|
<td><a href="#concept-dnd-p" title="concept-dnd-p">Protected mode</a>
|
|
|
|
</td><td><a href="#dropEffect-initialization">Based on <code>effectAllowed</code> value</a></td>
|
|
<td>Reset the <a href="#current-drag-operation">current drag operation</a> to "none"</td>
|
|
</tr><tr><td><dfn id="event-drop" title="event-drop"><code>drop</code></dfn></td>
|
|
<td><a href="#current-target-element">Current target element</a></td>
|
|
|
|
<td>✓ Cancelable</td>
|
|
<td><a href="#concept-dnd-ro" title="concept-dnd-ro">Read-only mode</a>
|
|
|
|
</td><td><a href="#current-drag-operation">Current drag operation</a></td>
|
|
<td>Varies</td>
|
|
</tr><tr><td><dfn id="event-dragend" title="event-dragend"><code>dragend</code></dfn></td>
|
|
<td><a href="#source-node">Source node</a></td>
|
|
|
|
<td>—</td>
|
|
<td><a href="#concept-dnd-p" title="concept-dnd-p">Protected mode</a>
|
|
|
|
</td><td><a href="#current-drag-operation">Current drag operation</a></td>
|
|
<td>Varies</td>
|
|
</tr></tbody></table><p>Not shown in the above table: all these events bubble, and the
|
|
<code title="dom-DataTransfer-effectAllowed"><a href="#dom-datatransfer-effectallowed">effectAllowed</a></code>
|
|
attribute always has the value it had after the previous event was
|
|
fired, defaulting to "<code title="">uninitialized</code>" in the
|
|
<code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> event.</p><h4 id="the-draggable-attribute"><span class="secno">7.7.7 </span>The <dfn title="attr-draggable"><code>draggable</code></dfn> attribute</h4><p>All <a href="infrastructure.html#html-elements">HTML elements</a> may have the <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> content attribute set. The
|
|
<code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> attribute is an
|
|
<a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. It has three states. The first
|
|
state is <i>true</i> and it has the keyword <code title="">true</code>. The second state is <i>false</i> and it has
|
|
the keyword <code title="">false</code>. The third state is
|
|
<i>auto</i>; it has no keywords but it is the <i>missing value
|
|
default</i>.</p><p>The <i>true</i> state means the element is draggable; the
|
|
<i>false</i> state means that it is not. The <i>auto</i> state
|
|
uses the default behavior of the user agent.</p><dl class="domintro"><dt><var title="">element</var> . <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if the element is draggable; otherwise, returns
|
|
false.</p>
|
|
|
|
<p>Can be set, to override the default and set the <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> content attribute.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-draggable" title="dom-draggable"><code>draggable</code></dfn> IDL
|
|
attribute, whose value depends on the content attribute's in the way
|
|
described below, controls whether or not the element is
|
|
draggable. Generally, only text selections are draggable, but
|
|
elements whose <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL
|
|
attribute is true become draggable as well.</p>
|
|
|
|
<p>If an element's <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code>
|
|
content attribute has the state <i>true</i>, the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL attribute must return
|
|
true.</p>
|
|
|
|
<p>Otherwise, if the element's <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> content attribute has the
|
|
state <i>false</i>, the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL attribute must return
|
|
false.</p>
|
|
|
|
<p>Otherwise, the element's <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> content attribute has the
|
|
state <i>auto</i>. If the element is an <code><a href="embedded-content-1.html#the-img-element">img</a></code> element,
|
|
or, if the element is an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element with an <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code> content attribute, the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL attribute must return
|
|
true.</p>
|
|
|
|
<p>Otherwise, the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> DOM
|
|
must return false.</p>
|
|
|
|
<p>If the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL attribute
|
|
is set to the value false, the <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code> content attribute must be
|
|
set to the literal value <code title="">false</code>. If the <code title="dom-draggable"><a href="#dom-draggable">draggable</a></code> IDL attribute is set to the
|
|
value true, the <code title="attr-draggable"><a href="#the-draggable-attribute">draggable</a></code>
|
|
content attribute must be set to the literal value <code title="">true</code>.</p>
|
|
|
|
</div><h4 id="the-dropzone-attribute"><span class="secno">7.7.8 </span>The <dfn title="attr-dropzone"><code>dropzone</code></dfn> attribute</h4><p>All <a href="infrastructure.html#html-elements">HTML elements</a> may have the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> content attribute set. When
|
|
specified, its value must be an <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique
|
|
space-separated tokens</a> that are <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a>. The allowed values are the following:</p><dl><dt><dfn id="attr-dropzone-copy" title="attr-dropzone-copy"><code>copy</code></dfn></dt>
|
|
|
|
<dd><p>Indicates that dropping an accepted item on the element will
|
|
result in a copy of the dragged data.</p>
|
|
|
|
|
|
</dd><dt><dfn id="attr-dropzone-move" title="attr-dropzone-move"><code>move</code></dfn></dt>
|
|
|
|
<dd><p>Indicates that dropping an accepted item on the element will
|
|
result in the dragged data being moved to the new location.</p>
|
|
|
|
|
|
</dd><dt><dfn id="attr-dropzone-link" title="attr-dropzone-link"><code>link</code></dfn></dt>
|
|
|
|
<dd><p>Indicates that dropping an accepted item on the element will
|
|
result in a link to the original data.</p>
|
|
|
|
|
|
</dd><dt>Any keyword with three characters or more, beginning with the
|
|
two characters U+0073 LATIN SMALL LETTER S and U+003A COLON or
|
|
U+0053 LATIN CAPITAL LETTER S and U+003A COLON (i.e. an <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a> match for the string "<code title="">s:</code>")<dt>
|
|
|
|
</dt></dt><dd><p>Indicates that items with <a href="#the-drag-data-item-kind">the drag data item
|
|
kind</a> <i>Plain Unicode string</i> and <a href="#the-drag-data-item-type-string">the drag data
|
|
item type string</a> set to a value that matches the remainder
|
|
of the keyword are accepted.</p></dd>
|
|
|
|
|
|
<dt>Any keyword with three characters or more, beginning with the
|
|
two characters U+0066 LATIN SMALL LETTER F and U+003A COLON or
|
|
U+0046 LATIN CAPITAL LETTER F and U+003A COLON (i.e. an <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a> match for the string "<code title="">f:</code>")<dt>
|
|
|
|
</dt></dt><dd><p>Indicates that items with <a href="#the-drag-data-item-kind">the drag data item
|
|
kind</a> <i><a href="infrastructure.html#file">File</a></i> and <a href="#the-drag-data-item-type-string">the drag data item type
|
|
string</a> set to a value that matches the remainder of the
|
|
keyword are accepted.</p></dd>
|
|
|
|
|
|
</dl><p>The <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> content
|
|
attribute's values must not have more than one of the three feedback
|
|
values (<code title="attr-dropzone-copy"><a href="#attr-dropzone-copy">copy</a></code>, <code title="attr-dropzone-move"><a href="#attr-dropzone-move">move</a></code>, and <code title="attr-dropzone-link"><a href="#attr-dropzone-link">link</a></code>) specified. If none are
|
|
specified, the <code title="attr-dropzone-copy"><a href="#attr-dropzone-copy">copy</a></code> value is
|
|
implied.</p><div class="impl">
|
|
|
|
<p>A <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute <dfn id="concept-dropzone-match" title="concept-dropzone-match">matches a drag data store</dfn> if
|
|
the <a href="#dropzone-processing-steps"><code title="attr-dropzone">dropzone</code> processing
|
|
steps</a> result in a match.</p>
|
|
|
|
<p>A <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute <dfn id="concept-dropzone-operation" title="concept-dropzone-operation">specifies an operation</dfn> if
|
|
the <a href="#dropzone-processing-steps"><code title="attr-dropzone">dropzone</code> processing
|
|
steps</a> result in a specified operation. The specified
|
|
operation is as given by those steps.</p>
|
|
|
|
<p>The <dfn id="dropzone-processing-steps"><code title="attr-dropzone">dropzone</code> processing
|
|
steps</dfn> are as follows. They either result in a match or not,
|
|
and separate from this result either in a specified operation or
|
|
not, as defined below.</p>
|
|
|
|
<ol><li><p>Let <var title="">value</var> be the value of the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute.</p></li>
|
|
|
|
<li><p>Let <var title="">keywords</var> be the result of <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">splitting <var title="">value</var> on spaces</a>.</p></li>
|
|
|
|
<li><p>Let <var title="">matched</var> be false.</p></li>
|
|
|
|
<li><p>Let <var title="">operation</var> be unspecified.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>For each value in <var title="">keywords</var>, if any, in the
|
|
order that they were found in <var title="">value</var>, run the
|
|
following steps.</p>
|
|
|
|
<ol><li><p>Let <var title="">keyword</var> be the keyword.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">keyword</var> is one of "<code title="attr-dropzone-copy"><a href="#attr-dropzone-copy">copy</a></code>", "<code title="attr-dropzone-move"><a href="#attr-dropzone-move">move</a></code>", or "<code title="attr-dropzone-link"><a href="#attr-dropzone-link">link</a></code>", then: run the following
|
|
substeps:</p>
|
|
|
|
<ol><li><p>If <var title="">operation</var> is still unspecified,
|
|
then let <var title="">operation</var> be the string given by
|
|
<var title="">keyword</var>.</p></li>
|
|
|
|
<li><p>Skip to the step labeled <i>end of keyword</i>
|
|
below.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>If <var title="">keyword</var> is shorter than three
|
|
characters in length, then skip to the step labeled <i>end of
|
|
keyword</i> below.</p></li>
|
|
|
|
<li><p>If the second character in <var title="">keyword</var> is
|
|
not a U+003A COLON character (:), then skip to the step labeled
|
|
<i>end of keyword</i> below.</p></li>
|
|
|
|
<li><p>Let <var title="">kind code</var> be the first character
|
|
in <var title="">keyword</var>, <a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII
|
|
lowercase</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Jump to the appropriate step from the list below, based on
|
|
the value of <var title="">kind code</var>:</p>
|
|
|
|
<dl class="switch"><dt>If <var title="">kind code</var> is a U+0073 LATIN SMALL LETTER S character</dt>
|
|
<dd>
|
|
|
|
<p>Let <var title="">kind</var> be
|
|
<i>Plain Unicode string</i>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If <var title="">kind code</var> is a U+0066 LATIN SMALL LETTER F character</dt>
|
|
<dd>
|
|
|
|
<p>Let <var title="">kind</var> be
|
|
<i><a href="infrastructure.html#file">File</a></i>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
<dd>
|
|
|
|
<p>Skip to the step labeled <i>end of keyword</i> below.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></li>
|
|
|
|
<li><p>Let <var title="">type</var> be the string consisting of
|
|
all but the first two characters of <var title="">keyword</var>,
|
|
<a href="infrastructure.html#converted-to-ascii-lowercase">converted to ASCII lowercase</a>.</p></li>
|
|
|
|
<li><p>If there exist any items in the <a href="#drag-data-store-item-list">drag data store item
|
|
list</a> whose <a href="#the-drag-data-item-kind" title="the drag data item kind">drag data
|
|
item kind</a> is the
|
|
kind given in <var title="">kind</var> and whose <span title="the drag data item type">drag data item type</span> is
|
|
<var title="">type</var>, then let <var title="">matched</var> be
|
|
true.</p></li>
|
|
|
|
<li><p><i>End of keyword</i>: Go on to the next keyword, if any,
|
|
or the next step in the overall algorithm, if there are no
|
|
more.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li>
|
|
|
|
<p>The algorithm results in a match if <var title="">matched</var>
|
|
is true, and does not otherwise.</p>
|
|
|
|
<p>The algorithm results in a specified operation if <var title="">operation</var> is not unspecified. The specified
|
|
operation, if one is specified, is the one given by <var title="">operation</var>.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p>The <dfn id="dom-dropzone" title="dom-dropzone"><code>dropzone</code></dfn> IDL
|
|
attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>In this example, a <code><a href="grouping-content.html#the-div-element">div</a></code> element is made into a drop
|
|
target for image files using the <code title="attr-dropzone"><a href="#the-dropzone-attribute">dropzone</a></code> attribute. Images dropped
|
|
into the target are then displayed.</p>
|
|
|
|
<pre><div dropzone="copy f:image/png f:image/gif f:image/jpeg" ondrop="receive(event, this)">
|
|
<p>Drop an image here to have it displayed.</p>
|
|
</div>
|
|
<script>
|
|
function receive(event, element) {
|
|
var data = event.dataTransfer.items;
|
|
for (var i = 0; i < data.length; i += 1) {
|
|
if ((data[i].kind == 'file') && (data[i].type.match('^image/'))) {
|
|
var img = new Image();
|
|
img.src = window.createObjectURL(data[i].getAsFile());
|
|
element.appendChild(img);
|
|
}
|
|
}
|
|
}
|
|
</script></pre>
|
|
|
|
</div><div class="impl">
|
|
|
|
<h4 id="security-risks-in-the-drag-and-drop-model"><span class="secno">7.7.9 </span>Security risks in the drag-and-drop model</h4>
|
|
|
|
<p>User agents must not make the data added to the
|
|
<code><a href="#datatransfer">DataTransfer</a></code> object during the <code title="event-dragstart"><a href="#event-dragstart">dragstart</a></code> event available to scripts
|
|
until the <code title="event-drop"><a href="#event-drop">drop</a></code> event, because
|
|
otherwise, if a user were to drag sensitive information from one
|
|
document to a second document, crossing a hostile third document in
|
|
the process, the hostile document could intercept the data.</p>
|
|
|
|
<p>For the same reason, user agents must consider a drop to be
|
|
successful only if the user specifically ended the drag operation
|
|
— if any scripts end the drag operation, it must be considered
|
|
unsuccessful (canceled) and the <code title="event-drop"><a href="#event-drop">drop</a></code>
|
|
event must not be fired.</p>
|
|
|
|
<p>User agents should take care to not start drag-and-drop
|
|
operations in response to script actions. For example, in a
|
|
mouse-and-window environment, if a script moves a window while the
|
|
user has his mouse button depressed, the UA would not consider that
|
|
to start a drag. This is important because otherwise UAs could cause
|
|
data to be dragged from sensitive sources and dropped into hostile
|
|
documents without the user's consent.</p>
|
|
|
|
</div><h3 id="editing-apis"><span class="secno">7.8 </span>Editing APIs</h3><dl class="domintro"><dt><var title="">document</var> . <code title="dom-document-execCommand"><a href="#execCommand">execCommand</a></code>(<var title="">commandId</var> [, <var title="">showUI</var> [, <var title="">value</var> ] ] )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Runs the action specified by the first argument, as described
|
|
in the list below. The second and third arguments sometimes affect
|
|
the action. (If they don't they are ignored.)</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">document</var> . <code title="dom-document-queryCommandEnabled"><a href="#dom-document-querycommandenabled">queryCommandEnabled</a></code>(<var title="">commandId</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns whether the given command is enabled, as described in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">document</var> . <code title="dom-document-queryCommandIndeterm"><a href="#dom-document-querycommandindeterm">queryCommandIndeterm</a></code>(<var title="">commandId</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns whether the given command is indeterminate, as described in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">document</var> . <code title="dom-document-queryCommandState"><a href="#dom-document-querycommandstate">queryCommandState</a></code>(<var title="">commandId</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the state of the command, as described in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">document</var> . <code title="dom-document-queryCommandSupported"><a href="#dom-document-querycommandsupported">queryCommandSupported</a></code>(<var title="">commandId</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if the command is supported; otherwise, returns false.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">document</var> . <code title="dom-document-queryCommandValue"><a href="#dom-document-querycommandvalue">queryCommandValue</a></code>(<var title="">commandId</var>)</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the value of the command, as described in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="execCommand" title="dom-document-execCommand"><code>execCommand(<var title="">commandId</var>, <var title="">showUI</var>, <var title="">value</var>)</code></dfn> method on the
|
|
<code><a href="dom.html#htmldocument">HTMLDocument</a></code> interface allows scripts to perform
|
|
actions on the current selection or at the current caret position.
|
|
Generally, these commands would be used to implement editor UI, for
|
|
example having a "delete" button on a toolbar.</p>
|
|
|
|
<p>There are three variants to this method, with one, two, and three
|
|
arguments respectively. The <var title="">showUI</var> and <var title="">value</var> parameters, even if specified, are ignored
|
|
except where otherwise stated.</p>
|
|
|
|
<p>When <code title="dom-document-execCommand"><a href="#execCommand">execCommand()</a></code>
|
|
is invoked, the user agent must run the following steps:</p>
|
|
|
|
<ol><li>If the given <var title="">commandId</var> maps to an entry in
|
|
the list below whose "Enabled When" entry has a condition that is
|
|
currently false, do nothing; abort these steps.</li>
|
|
|
|
<li>Otherwise, execute the "Action" listed below for the given <var title="">commandId</var>.</li>
|
|
|
|
</ol></div><p>A document is <dfn id="ready-for-editing-host-commands">ready for editing host commands</dfn> if it
|
|
has a selection that is entirely within an <a href="editing.html#editing-host">editing
|
|
host</a>, or if it has no selection but its caret is inside an
|
|
<a href="editing.html#editing-host">editing host</a>.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-document-querycommandenabled" title="dom-document-queryCommandEnabled"><code>queryCommandEnabled(<var title="">commandId</var>)</code></dfn> method, when invoked, must
|
|
return true if the condition listed below under "Enabled When" for
|
|
the given <var title="">commandId</var> is true, and false
|
|
otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-document-querycommandindeterm" title="dom-document-queryCommandIndeterm"><code>queryCommandIndeterm(<var title="">commandId</var>)</code></dfn> method, when invoked, must
|
|
return true if the condition listed below under "Indeterminate When"
|
|
for the given <var title="">commandId</var> is true, and false
|
|
otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-document-querycommandstate" title="dom-document-queryCommandState"><code>queryCommandState(<var title="">commandId</var>)</code></dfn> method, when invoked, must
|
|
return the value expressed below under "State" for the given <var title="">commandId</var>.</p>
|
|
|
|
<p>The <dfn id="dom-document-querycommandsupported" title="dom-document-queryCommandSupported"><code>queryCommandSupported(<var title="">commandId</var>)</code></dfn> method, when invoked, must
|
|
return true if the given <var title="">commandId</var> is in the
|
|
list below, and false otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-document-querycommandvalue" title="dom-document-queryCommandValue"><code>queryCommandValue(<var title="">commandId</var>)</code></dfn> method, when invoked, must
|
|
return the value expressed below under "Value" for the given <var title="">commandId</var>.</p>
|
|
|
|
</div><p>The possible values for <var title="">commandId</var>, and their
|
|
corresponding meanings, are as follows. <span class="impl">These
|
|
values must be compared to the argument in an <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a> manner.</span></p><dl><dt><dfn id="command-bold" title="command-bold"><code>bold</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is bold.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <em><code><a href="text-level-semantics.html#the-b-element">b</a></code></em> element (or, again,
|
|
unwrapped, or have that semantic inserted or removed, as defined by
|
|
the UA).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: True if the selection, or the caret, if
|
|
there is no selection, is, or is contained within, a
|
|
<code><a href="text-level-semantics.html#the-b-element">b</a></code> element. False otherwise.</dd>
|
|
<dd><strong>Value</strong>: The string "<code title="">true</code>"
|
|
if the expression given for the "State" above is true, the string
|
|
"<code title="">false</code>" otherwise.</dd>
|
|
|
|
<dt><dfn id="command-createlink" title="command-createLink"><code>createLink</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is a
|
|
link or not. If the second argument is true, and a link is to be
|
|
added, the user agent will ask the user for the address. Otherwise,
|
|
the third argument will be used as the address.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <em><code><a href="text-level-semantics.html#the-a-element">a</a></code></em> element (or, again,
|
|
unwrapped, or have that semantic inserted or removed, as defined by
|
|
the UA). If the user agent creates an <code><a href="text-level-semantics.html#the-a-element">a</a></code> element or
|
|
modifies an existing <code><a href="text-level-semantics.html#the-a-element">a</a></code> element, then if the <var title="">showUI</var> argument is present and has the value false,
|
|
then the value of the <var title="">value</var> argument must be
|
|
used as the <a href="urls.html#url">URL</a> of the link. Otherwise, the user agent
|
|
should prompt the user for the URL of the link.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-delete" title="command-delete"><code>delete</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Deletes the selection or the
|
|
character before the cursor.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had performed <a href="editing.html#contenteditable-delete">a backspace
|
|
operation</a>.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-formatblock" title="command-formatBlock"><code>formatBlock</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Wraps the selection in the element
|
|
given by the third argument. If the third argument doesn't
|
|
specify an element that is a <dfn id="formatblock-candidate"><code title="">formatBlock</code>
|
|
candidate</dfn>, does nothing.</dd>
|
|
<dd class="impl">
|
|
<p><strong>Action</strong>: The user agent must run the following
|
|
steps:</p>
|
|
<ol><li><p>If the <var title="">value</var> argument wasn't
|
|
specified, abort these steps without doing anything.</p></li>
|
|
<li><p>If the <var title="">value</var> argument has a leading
|
|
U+003C LESS-THAN SIGN character (<) and a trailing U+003E
|
|
GREATER-THAN SIGN character (>), then remove the first and last
|
|
characters from <var title="">value</var>.</p></li>
|
|
<li>
|
|
<p>If <var title="">value</var> is (now) an <a href="infrastructure.html#ascii-case-insensitive">ASCII
|
|
case-insensitive</a> match for the tag name of an element
|
|
defined by this specification that is defined to be a
|
|
<a href="#formatblock-candidate"><code title="">formatBlock</code> candidate</a>, then,
|
|
for every position in the selection, take the nearest
|
|
<a href="#formatblock-candidate"><code title="">formatBlock</code> candidate</a>
|
|
ancestor element of that position that contains only
|
|
<a href="content-models.html#phrasing-content">phrasing content</a>, and, if that element is
|
|
<a href="editing.html#editable">editable</a>, is not an <a href="editing.html#editing-host">editing host</a>, and
|
|
has a parent element whose content model allows that parent to
|
|
contain any <a href="content-models.html#flow-content">flow content</a>, replace it with an
|
|
element in the HTML namespace whose name is <var title="">value</var>, and move all the children that were in it
|
|
to the new element, and copy all the attributes that were on it
|
|
to the new element.</p>
|
|
<p>If there is no selection, then, where in the description
|
|
above refers to the selection, the user agent must act as if the
|
|
selection was an empty range (with just one position) at the
|
|
caret position.</p>
|
|
</li>
|
|
</ol></dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-forwarddelete" title="command-forwardDelete"><code>forwardDelete</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Deletes the selection or the
|
|
character after the cursor.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had performed <a href="editing.html#contenteditable-delete">a forward delete
|
|
operation</a>.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-insertimage" title="command-insertImage"><code>insertImage</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is an
|
|
image or not. If the second argument is true, and an image is to be
|
|
added, the user agent will ask the user for the address. Otherwise,
|
|
the third argument will be used as the address.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act
|
|
as if the user had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <em><code><a href="embedded-content-1.html#the-img-element">img</a></code></em> element (or, again,
|
|
unwrapped, or have that semantic inserted or removed, as defined by
|
|
the UA). If the user agent creates an <code><a href="embedded-content-1.html#the-img-element">img</a></code> element or
|
|
modifies an existing <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, then if the <var title="">showUI</var> argument is present and has the value false,
|
|
then the value of the <var title="">value</var> argument must be
|
|
used as the <a href="urls.html#url">URL</a> of the image. Otherwise, the user
|
|
agent should prompt the user for the URL of the image.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-inserthtml" title="command-insertHTML"><code>insertHTML</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Replaces the selection with the value
|
|
of the third argument parsed as HTML.</dd>
|
|
<dd class="impl">
|
|
<p><strong>Action</strong>: The user agent must run the following
|
|
steps:</p>
|
|
<ol><li><p>If the document is an <a href="dom.html#xml-documents" title="XML documents">XML
|
|
document</a>, then throw an <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code>
|
|
exception and abort these steps.</p></li>
|
|
<li><p>If the <var title="">value</var> argument wasn't
|
|
specified, abort these steps without doing anything.</p></li>
|
|
<li><p>If there is a selection, act as if the user had requested
|
|
that <a href="editing.html#contenteditable-delete">the selection be
|
|
deleted</a>.</p></li>
|
|
<li><p>Invoke the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment parsing algorithm</a>
|
|
with an arbitrary orphan <code><a href="sections.html#the-body-element">body</a></code> element owned by the
|
|
same <code><a href="infrastructure.html#document">Document</a></code> as the <i title="">context</i> element
|
|
and with the <var title="">value</var> argument as <i title="">input</i>.</p></li>
|
|
<li><p>Insert the nodes returned by the previous step into the
|
|
document at the location of the caret, firing any mutation events
|
|
as appropriate.</p></li>
|
|
</ol></dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-insertlinebreak" title="command-insertLineBreak"><code>insertLineBreak</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Inserts a line break.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had <a href="editing.html#contenteditable-br">requested a line
|
|
separator</a>.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-insertorderedlist" title="command-insertOrderedList"><code>insertOrderedList</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is an ordered list.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <code><a href="grouping-content.html#the-ol-element">ol</a></code> element (or unwrapped, or, if
|
|
there is no selection, have that semantic inserted or removed
|
|
— the exact behavior is UA-defined).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-insertunorderedlist" title="command-insertUnorderedList"><code>insertUnorderedList</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is an unordered list.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <code><a href="grouping-content.html#the-ul-element">ul</a></code> element (or unwrapped, or, if
|
|
there is no selection, have that semantic inserted or removed
|
|
— the exact behavior is UA-defined).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-insertparagraph" title="command-insertParagraph"><code>insertParagraph</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Inserts a paragraph break.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had performed a <a href="editing.html#contenteditable-breakBlock">break
|
|
block</a> editing action.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-inserttext" title="command-insertText"><code>insertText</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Inserts the text given in the third parameter.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had <a href="editing.html#contenteditable-insertText">inserted text</a>
|
|
corresponding to the <var title="">value</var> parameter.</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-italic" title="command-italic"><code>italic</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is italic.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <em><code><a href="text-level-semantics.html#the-i-element">i</a></code></em> element (or, again,
|
|
unwrapped, or have that semantic inserted or removed, as defined by
|
|
the UA).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: True if the selection, or the caret, if
|
|
there is no selection, is, or is contained within, a
|
|
<code><a href="text-level-semantics.html#the-i-element">i</a></code> element. False otherwise.</dd>
|
|
<dd><strong>Value</strong>: The string "<code title="">true</code>"
|
|
if the expression given for the "State" above is true, the string
|
|
"<code title="">false</code>" otherwise.</dd>
|
|
|
|
<dt><dfn id="command-redo" title="command-redo"><code>redo</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Acts as if the user had requested a redo.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must <span title="do-redo">move forward one step</span> in its <span>undo
|
|
transaction history</span>, restoring the associated state. If the
|
|
<span>undo position</span> is at the end of the <span>undo
|
|
transaction history</span>, the user agent must do nothing.
|
|
</dd>
|
|
<dd><strong>Enabled When</strong>: The <span>undo position</span>
|
|
is not at the end of the <span>undo transaction
|
|
history</span>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-selectall" title="command-selectAll"><code>selectAll</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Selects all the editable content.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must change the
|
|
selection so that all the content in the currently focused
|
|
<a href="editing.html#editing-host">editing host</a> is selected. If no <a href="editing.html#editing-host">editing
|
|
host</a> is focused, then the content of the entire document
|
|
must be selected.</dd>
|
|
<dd><strong>Enabled When</strong>: Always.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-subscript" title="command-subscript"><code>subscript</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is subscripted.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <em><code><a href="text-level-semantics.html#the-sub-and-sup-elements">sub</a></code></em> element (or, again,
|
|
unwrapped, or have that semantic inserted or removed, as defined by
|
|
the UA).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: True if the selection, or the caret, if
|
|
there is no selection, is, or is contained within, a
|
|
<code><a href="text-level-semantics.html#the-sub-and-sup-elements">sub</a></code> element. False otherwise.</dd>
|
|
<dd><strong>Value</strong>: The string "<code title="">true</code>"
|
|
if the expression given for the "State" above is true, the string
|
|
"<code title="">false</code>" otherwise.</dd>
|
|
|
|
<dt><dfn id="command-superscript" title="command-superscript"><code>superscript</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Toggles whether the selection is superscripted.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must act as if the user
|
|
had requested that the selection <a href="editing.html#contenteditable-wrapSemantic">be wrapped in the
|
|
semantics</a> of the <code><a href="text-level-semantics.html#the-sub-and-sup-elements">sup</a></code> element (or unwrapped, or, if
|
|
there is no selection, have that semantic inserted or removed
|
|
— the exact behavior is UA-defined).</dd>
|
|
<dd><strong>Enabled When</strong>: The document is <a href="#ready-for-editing-host-commands">ready for
|
|
editing host commands</a>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: True if the selection, or the caret, if
|
|
there is no selection, is, or is contained within, a
|
|
<code><a href="text-level-semantics.html#the-sub-and-sup-elements">sup</a></code> element. False otherwise.</dd>
|
|
<dd><strong>Value</strong>: The string "<code title="">true</code>"
|
|
if the expression given for the "State" above is true, the string
|
|
"<code title="">false</code>" otherwise.</dd>
|
|
|
|
<dt><dfn id="command-undo" title="command-undo"><code>undo</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Acts as if the user had requested an undo.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must <span title="do-undo">move back one step</span> in its <span>undo
|
|
transaction history</span>, restoring the associated state. If the
|
|
<span>undo position</span> is at the start of the <span>undo
|
|
transaction history</span>, the user agent must do nothing.
|
|
</dd>
|
|
<dd><strong>Enabled When</strong>: The <span>undo position</span>
|
|
is not at the start of the <span>undo transaction
|
|
history</span>.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-unlink" title="command-unlink"><code>unlink</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Removes all links from the selection.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must remove all
|
|
<code><a href="text-level-semantics.html#the-a-element">a</a></code> elements that have <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code> attributes and that are partially
|
|
or completely included in the current selection.</dd>
|
|
<dd><strong>Enabled When</strong>: The document has a selection
|
|
that is entirely within an <a href="editing.html#editing-host">editing host</a> and that
|
|
contains (either partially or completely) at least one
|
|
<code><a href="text-level-semantics.html#the-a-element">a</a></code> element that has an <code title="attr-hyperlink-href"><a href="links.html#attr-hyperlink-href">href</a></code> attribute.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt><dfn id="command-unselect" title="command-unselect"><code>unselect</code></dfn></dt>
|
|
<dd><strong>Summary</strong>: Unselects everything.</dd>
|
|
<dd class="impl"><strong>Action</strong>: The user agent must change the
|
|
selection so that nothing is selected.</dd>
|
|
<dd><strong>Enabled When</strong>: Always.</dd>
|
|
<dd><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd><strong>State</strong>: Always false.</dd>
|
|
<dd><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
<dt class="impl"><code><var title="">vendorID</var>-<var title="">customCommandID</var></code></dt>
|
|
<dd class="impl"><strong>Action</strong>: User agents may implement
|
|
vendor-specific extensions to this API. Vendor-specific extensions
|
|
to the list of commands should use the syntax <code><var title="">vendorID</var>-<var title="">customCommandID</var></code>
|
|
so as to prevent clashes between extensions from different vendors
|
|
and future additions to this specification.</dd>
|
|
<dd class="impl"><strong>Enabled When</strong>: UA-defined.</dd>
|
|
<dd class="impl"><strong>Indeterminate When</strong>: UA-defined.</dd>
|
|
<dd class="impl"><strong>State</strong>: UA-defined.</dd>
|
|
<dd class="impl"><strong>Value</strong>: UA-defined.</dd>
|
|
|
|
<dt class="impl">Anything else</dt>
|
|
<dd class="impl"><strong>Action</strong>: User agents must do nothing.</dd>
|
|
<dd class="impl"><strong>Enabled When</strong>: Never.</dd>
|
|
<dd class="impl"><strong>Indeterminate When</strong>: Never.</dd>
|
|
<dd class="impl"><strong>State</strong>: Always false.</dd>
|
|
<dd class="impl"><strong>Value</strong>: Always the string "<code title="">false</code>".</dd>
|
|
|
|
</dl></body></html>
|