forked from briancherne/jquery-hoverIntent
-
Notifications
You must be signed in to change notification settings - Fork 0
/
jquery.hoverIntent.html
186 lines (146 loc) · 12 KB
/
jquery.hoverIntent.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="imagetoolbar" content="no" />
<title>hoverIntent jQuery Plug-in</title>
<link rel="stylesheet" type="text/css" href="/cherne.css" />
<link rel="stylesheet" type="text/css" href="/cherne_print.css" media="print" />
<script type="text/javascript" src="http://code.jquery.com/jquery.js"></script>
<script type="text/javascript" src="./jquery.hoverIntent.js"></script>
<!-- DEMO CSS -->
<style type="text/css" media="screen">
/* styles for the demo examples -- NOT REQUIRED for hoverIntent to work, just for demo purposes */
#RESOURCES #main .demo li { padding-bottom: 0; }
ul.demo {display:block; width:100%; height:75px; padding:0; margin:0; background:#9cc; list-style-type:none;}
ul.demo li {background:#fcc; display:block; width:25%; height:50px; padding:0; margin:0; float: left; position:relative; overflow:hidden; cursor:default; font-size:0.9em; line-height:1.1em;}
ul.demo li.p2 {background:#ffc;}
ul.demo li.p3 {background:#cfc;}
ul.demo li.p4 {background:#ccf;}
ul.demo li span { display:block; margin:4px; background:#eef; cursor:default;}
</style>
<!-- DEMO JS -->
<script type="text/javascript" charset="utf-8">
$(document).ready(function(){
$("#demo1 li").hover(makeTall,makeShort);
$("#demo2 li").hoverIntent(makeTall,makeShort);
$("#demo3 li").hoverIntent({
over: makeTall,
timeout: 500,
out: makeShort
});
}); // close document.ready
function makeTall(){ $(this).animate({"height":75},200);}
function makeShort(){ $(this).animate({"height":50},200);}
</script>
</head>
<body id="RESOURCES">
<div id="pageHeader">
<ul id="nav1">
<li><a href="/">cherne.net</a></li>
<li><a href="/brian/pictures/">Pictures</a></li>
<li><a href="/brian/resume/">Resume</a></li>
<li><a href="/brian/portfolio/">Portfolio</a></li>
<li><a href="/brian/resources/" class="current">Resources</a></li>
</ul>
<h1>hoverIntent jQuery Plug-in</h1>
</div>
<div id="pageContent">
<div id="main">
<noscript><p><em>If you can see this message <strong>JavaScript is disabled</strong>. This plug-in requires JavaScript to be enabled in order for the examples to work. (This is really a note to myself so the next time I look at my web site with JavaScript accidentally turned off I don't freak out and wonder why it's not working)</em></p></noscript>
<h2>What is hoverIntent?</h2>
<p>hoverIntent is a plug-in that attempts to determine the user's intent... like a crystal ball, only with mouse movement! It works like (and was derived from) <a href="http://jquery.com/">jQuery</a>'s built-in <a href="http://api.jquery.com/hover/">hover</a>. However, instead of immediately calling the onMouseOver function, it waits until the user's mouse slows down enough before making the call.</p>
<p>Why? To delay or prevent the accidental firing of animations or ajax calls. Simple timeouts work for small areas, but if your target area is large it may execute regardless of intent.</p>
<p class="download"><a href="jquery.hoverIntent.js">Download hoverIntent r6 (fully-commented, uncompressed)</a></p>
<p class="download"><a href="jquery.hoverIntent.minified.js">Download hoverIntent r6 (minified)</a></p>
<p>hoverIntent r6 (2011) has all the same functionality of r5 (2007) except that the Google Chrome defect (<a href="#defects">known defects</a>) is fixed once you upgrade to jQuery 1.5.1.</p>
<h2>Translations</h2>
<p><a href="http://www.designcontest.com/show/jquery.hoverIntent-be" hreflang="be-BY">Беларуская</a> courtesy Martha Ruszkowski</p>
<h2>Examples</h2>
<h3>jQuery's hover (for reference)</h3>
<pre>$("#demo1 li").hover( makeTall, makeShort )</pre>
<ul class="demo" id="demo1">
<li class="p1"> </li>
<li class="p2"> </li>
<li class="p3"> </li>
<li class="p4"><span>hover ignores over/out events from children</span></li>
</ul>
<p>jQuery's built-in hover calls onMouseOver/onMouseOut functions immediately.</p>
<h3>hoverIntent as hover replacement</h3>
<pre>$("#demo2 li").hoverIntent( makeTall, makeShort )</pre>
<ul class="demo" id="demo2">
<li class="p1"> </li>
<li class="p2"> </li>
<li class="p3"> </li>
<li class="p4"><span>hoverIntent also ignores over/out events from children</span></li>
</ul>
<p>hoverIntent is interchangeable with jQuery's hover. It can use the same exact onMouseOver and onMouseOut functions and it passes the same <strong>this</strong> and <strong>event</strong> objects to those functions.</p>
<h3>hoverIntent with configuration object</h3>
<pre>
var config = {
over: makeTall, <span>// function = onMouseOver callback (REQUIRED)</span>
timeout: 500, <span>// number = milliseconds delay before onMouseOut</span>
out: makeShort <span>// function = onMouseOut callback (REQUIRED)</span>
};
$("#demo3 li").hoverIntent( config )
</pre>
<ul class="demo" id="demo3">
<li class="p1"> </li>
<li class="p2"> </li>
<li class="p3"> </li>
<li class="p4"> </li>
</ul>
<p>To override the default configuration of hoverIntent, pass it an object as the first (and only) parameter. The object must contain "over" and "out" functions, in addition to any other options you'd like to override.</p>
<h2>Basic Configuration Options</h2>
<p>The "timeout" delay (by default set to 0) will mostly likely be the one you'll want to override. The "over" and "out" functions are required but nothing prevents you from sending an empty function(){} to either.</p>
<h3>over:</h3>
<p>Required. The function you'd like to call onMouseOver. Your function receives the same "this" and "event" objects as it would from jQuery's hover method.</p>
<h3>timeout:</h3>
<p>A simple delay, in milliseconds, before the "out" function is called. If the user mouses back over the element before the timeout has expired the "out" function will not be called (nor will the "over" function be called). This is primarily to protect against sloppy/human mousing trajectories that temporarily (and unintentionally) take the user off of the target element... giving them time to return. <em>Default timeout: 0</em></p>
<h3>out:</h3>
<p>Required. The function you'd like to call onMouseOut. Your function receives the same "this" and "event" objects as it would from jQuery's hover method. Note, hoverIntent will only call the "out" function if the "over" function has been called on that same run.</p>
<h2>Advanced Configuration Options</h2>
<p>When choosing the default settings for hoverIntent I tried to find the best possible balance between responsiveness and frequency of false positives. Modify these if you are brave, test tirelessly, and completely understand what you are doing.</p>
<h3>sensitivity:</h3>
<p>If the mouse travels fewer than this number of pixels between polling intervals, then the "over" function will be called. With the minimum sensitivity threshold of 1, the mouse must not move between polling intervals. With higher sensitivity thresholds you are more likely to receive a false positive. <em>Default sensitivity: 7</em></p>
<h3>interval:</h3>
<p>The number of milliseconds hoverIntent waits between reading/comparing mouse coordinates. When the user's mouse first enters the element its coordinates are recorded. The soonest the "over" function can be called is after a single polling interval. Setting the polling interval higher will increase the delay before the first possible "over" call, but also increases the time to the next point of comparison. <em>Default interval: 100</em></p>
<h2>Notice of DOM Manipulation</h2>
<p>hoverIntent adds two custom attributes to every DOM element it's assigned to. For example: <li hoverIntent_t="" hoverIntent_s=""> </p>
<ul>
<li>hoverIntent_t is the polling interval timer, or the mouseOut timer.</li>
<li>hoverIntent_s stores the state to prevent unmatched function calls.</li>
</ul>
<p>Timers are stored as integers, so there should not be any <a href="http://msdn.microsoft.com/library/en-us/IETechCol/dnwebgen/ie_leak_patterns.asp">trouble with memory leaks</a>. hoverIntent state is also stored as an integer.</p>
<h2 id="defects">Known Defects</h2>
<p>hoverIntent r5 suffers from <a href="http://code.google.com/p/chromium/issues/detail?id=68629">a defect in Google Chrome that improperly triggers mouseout when entering a child input[type="text"] element</a>. hoverIntent r6 uses the same mouseenter/mouseleave special events as jQuery's built-in hover, and jQuery 1.5.1 patched this issue. Thanks to Colin Stuart for tipping me off about this and for providing isolated code to demonstrate/test.</p>
<p id="chrome9defect" style="background:#eee;margin-bottom:1em;">This page uses jQuery 1.5.1+ and hoverIntent r6, so when your cursor goes over the text input nothing should change (it should continue to read "enter parent" because you are still over this paragraph). <br/><input type="text" value=""/><br/> However, if you were using Google Chrome and if this page were using an older version of jQuery or hoverIntent, moving the cursor over the text input would improperly trigger the mouseout event, and the value would change to "leave parent".</p>
<script type="text/javascript">
function enter(e){$("input", e.target).val("enter parent");}
function leave(e){$("input", e.target).val("leave parent");}
$("#chrome9defect").hoverIntent(enter,leave);
</script>
<p>If you place an element with onMouseOut event listeners flush against the edge of the browser chrome, sometimes Internet Explorer does not trigger an onMouseOut event immediately if your mouse leaves the document. hoverIntent does not correct for this.</p>
<p>jQuery's hover can take <a href="http://api.jquery.com/hover/#hover1">both a handlerIn and a handlerOut</a> <strong>or</strong> <a href="http://api.jquery.com/hover/#hover2">just a handlerIn</a>. The current version of hoverIntent requires both handlerIn and handlerOut <strong>or</strong> a single configuration object. It was not designed to take just a handlerIn like hover. This will be addressed in a future release.</p>
<p>Please email me ( <a href="mailto:%62%72%69%61%6E%40%63%68%65%72%6E%65%2E%6E%65%74">brian@cherne.net</a> ) if you have questions or would like to notify me of any defects. I will tweet about any updates from <a href="http://twitter.com/#!/briancherne">@briancherne</a> using the tags #hoverIntent #jQuery.</p>
<h2>The Future of hoverIntent</h2>
<p>hoverIntent r7 (in development) will be backwards compatible with all current implementations and include hoverIntent custom events.</p>
<h2>Release History</h2>
<ul>
<li>r7 = In development. Adding custom events.</li>
<li>r6 = Current stable release. Updated to correct for Google Chrome defect.</li>
<li>r5 = Added state to prevent unmatched function calls. This release (and previous releases) suffers from <a href="http://code.google.com/p/chromium/issues/detail?id=68629">a defect in Google Chrome that improperly triggers mouseout when entering a child input[type=text] element</a>.</li>
<li>r4 = Fixed polling interval timing issue (now uses a self-calling timeout to avoid interval irregularities).</li>
<li>r3 = Developer-only release for debugging.</li>
<li>r2 = Added timeout and interval references to DOM object -- keeps timers separate from each other. Added configurable options. Added timeout option to delay onMouseOut function call. Fixed two-interval mouseOver bug (now setting pX and pY onMouseOver instead of hardcoded value).</li>
<li>r1 = Initial release to jQuery discussion forum for feedback.</li>
</ul>
</div><!-- close #main -->
</div><!-- close #pageContent -->
<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3082227-1");
pageTracker._trackPageview();
</script>
</body>
</html>