Creating a new maTooltip

Easy! Create a new tooltip like so: var t = new maTooltip("#myTarget", {static_message: "Hello World!"}); t.show();. The target can be a HTML element, a JQuery selector string or a JQuery object. The constructor and the factory method maToolip.quickTooltip has been explained and demoed at the How To Use page. We will also explain in detail all the settings you can pass along with the constructor invocation in the next section Settings and Global Configuration.

Settings and Global Configuration

The defaults object

You can get a reference to the defaults object by calling the static method maTooltip.getDefaults. See an example here. You'll find a few options in the defaults object, and changing any one of thoose options affects the default behaviour for all tooltips. It doesn't affect the behaviour of a tooltip if you supplied the very same setting to his constructor. The defaults are only fall back values and some of these settings are not customizable at all via the constructor.

Settings

All of the following settings are located in the defaults object. They who can be set on an individual level per tooltip are marked as "Yes" in the column "Is overridable?" If you do wish to override a default behaviour, you can supply this option in the map object sent as the second argument to the constructor.

Setting

position
fade_in_duration
move_in_duration
move_in_from
full_visibility_duration
fade_out_duration
move_out_duration
easing_in
easing_out
static_message
one_time_only
insert_before
calculated_time_offset
opacity
flash_on_text_change

Current default value

"TOP"
200
100
10
-2
600
0
"swing"
"linear"
null
false
"body"
null
0.8
true

Is overridable?

Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
No

There are two settings not mentioned in the table. These are optionally supplied to the constructor only and are not replicated in the defaults object. One of them is inline_style, whose value is a string that specifies an inline style that will be set as a style attribute of the div container that holds all contents. Also, 'cause the tooltiper is kind enough to store references to his DOM elements, you can manage the style without this setting like so: .DOM.$divContents.css('styleProperty', 'styleValue'). Read more about how the DOM works somewhere else on this page.

The other setting not mentioned are move_in_to. This setting is also, optionally and only, supplied to the constructor and shall specify exactly where the tooltiper is finally located. The value is an object with his .top and .left property set to some nummeric value. It has been described and demoed here.

Next we'll talk some about the settings in the previous table. move_in_from is as mighty as it .. might.. be difficult to understand. In short, this setting specifies where the move-in animation shall begin. A value that is == 0 means the opposite position. As an example, the opposite position for a tooltiper that has a final targeted position set to TOP, is.. BOTTOM. Float values between > 0 and < 1 are a percentage offset from that opposite side. A value of 0.5 will therefor be right in the middle of the target element. A value of 0.99 would be kinda at the final position. Integer values >= 1 is amount of pixels towards the opposite side of the final position. If you didn't get any of this, try another caveat: All numbers can be negative. A negative number will reverse the direction of all the explanations so far. You should really play around with this variable at the demo page to see the magic for yourself. Finally, this setting can actually be an object with properties .top and .left defined. They must be integer values that together describe a specific screen coordinate. This practice has been demonstrated here.

easing_in is the easing variable sent to jQuery and applies to the fade-in and move-in animations. Unfamiliar with this concept? Read all about it over at the jQuery documentation. easing_out is likewise sent to jQuery and applies to the fade-out and move-out animations. No big surprise there.

static_message is the message maTooltip displays. It can be a string with pure text or HTML, doesn't matter. If your needs are overly ambitious, then it can also be a function or even an object. It has been explained here. If you plan to handle the contents yourself, as demonstrated here, then you have no reason to use this setting at all.

Passing the option one_time_only to the constructor and set his value to true, is not that much different from using the factory method maTooltip.quickTooltip. Because this option in the defaults object is set to false, the normal procedure for the constructor is to store a reference to the new tooltip in maTooltip.INSTANCES. You can read more about this object in the next section. With one_time_only set to true, that reference will never be stored. And, when a "one time only" tooltiper sooner or later get a call to his .hide method, he will make a subsequent call to his .dispose method which does a few things, among thoose is to destroy his DOM completely. The rationale is to promote garbage collection effectiveness. But, I can't think of a use case when you would need to manually set this variable. If you only intend to construct a new tooltip and have him display a quick message just once, then use the factory method and forget all about it. Otherwise, if you ever feel that you're done with old tooltipers just laying around and you are a memory-byte-fundamentalist, call the tooltipers .dispose method.

If insert_before is set to null, then the default and temporary placement for a tooltiper during his visibility, is to be inserted right before the target element in the document tree. The internally used jQuery method is actually called .insertBefore. However, due to a seriously buggish behavior in the Opera browser (confirmed in 12.02 build 1578, x86), this setting defaults to the body element. If you should encounter any strange problems, try to set this insertion point at another location globally through the defaults object or individually by passing the new target to the constructor. This jQuery handle or the results of the selection string must only contain one element.

Whenever full_visibility_duration is set to -2, an internal algorithm will compute the time to be displayed for a tooltip before his .hide method is called (we'll get into the details of this setting in the next section). You might not be satisfied with this result, particularly not if you do stuff with your tooltip contents or visual appearance that you feel should reduce or expand this time interval. Here is when calculated_time_offset comes in handy. This setting must be a string that begins with "+=", "-=", "/=", or "*=". The string must thereafter end with a nummeric value. A specified string "*=2" would double the calculated sum. This option has been demoed here.

opacity in the defaults object is the hardcoded default value to fall back to whenever maTooltip failed to parse out the opacity value from the style sheet. You should therefor never have the need to touch this setting. Use the style sheet to set this setting on a global level! Optionally you can supply this value to the constructor if you want to have a particular opacity for one tooltip only.

flash_on_text_change is fully explained and demoed here.

Position, animations and visibility

A given position can be one of the following string values: "LEFT", "TOP", "RIGHT" or "BOTTOM". Not saving you any keystrokes are a static object maTooltip.POSITIONS that has exactly those properties. The position is more accurately defined as target or final position. This shall be one of the target element's four sides after an optional move in animation has finished. As we've already talked about, you can set your own custom coordinates for both the start and final position.

An absolute speed (or call it duration) is always measured in milliseconds. There is a static object maTooltip.SPEED that has property .FAST set to 200 and property .SLOW set to 600. Settings that accept a speed value are fade_in_duration, move_in_duration, fade_out_duration and move_out_duration. Thoose four are all durations of animations. A value of 0 will effectively kill the animation and is the preferred method for such intention.

full_visibility_duration accepts an integer value in the range from -3 to infinity. -3 or maTooltip.VISIBILITY.HOVER will make the constructor setup proper event handler methods so that the tooltip is shown whenever you hover your mouse over the target element, and it will hide whenever mouse leaves target element. If you use this value and let maTooltip setup these handlers, then the tooltiper will always complete his in-animations before hiding again even if the user just hovered the element for a really short while. -2 or maTooltip.VISIBILITY.AUTO will make an internal algorithm compute the time for you, and that timer will not start ticking before all in-animations have fully finished. Afterwards, the tooltip will hide himself and this value/behaviour is the default. A value of -1 or maTooltip.VISIBILITY.FOREVER means live forever – you'll have to make a call to .hide or .toggle yourself. All values from 0 to infinity is parsed as pure milliseconds to live before the tooltiper hides himself.

Tooltiper Variables

Static

Some variables have already been mentioned, namely maTooltip.POSITIONS, maTooltip.SPEED and maTooltip.VISIBILITY. There is one we haven't talked about yet; maTooltip.INSTANCES. If the tooltiper has not had his setting one_time_only explicitly set to true, and he was not concieved by the factory method, then the constructor shall spare a reference to every tooltiper created in the maTooltip.INSTANCES object and thus make the reference globally available. Making a call to .dispose will delete this reference. The property name of the maTooltip.INSTANCES object will first and foremost be the same as the ID attribute of your target element. If ID is missing, we'll have a look for the name attribute. If the name attribute too have gone fishing, the tooltiper will be called "_ANONYMOUS". Thereafter, whenever a new tooltiper is created and there happens to be a naming conflict, a nummeric serial will be appended to the end of the property name prefixed with an underscore character. Example:

var tt = new maTooltip('#someElementID');

console.log( tt.name );                                // Prints "someElementID".
console.log( tt === maTooltip.INSTANCES[tt.name] );    // Prints "TRUE".

var links = $('a');
var first = new maTooltip(links.eq(0));
var second = new maTooltip(links.eq(1));

console.log( first.name );                             // Prints "_ANONYMOUS".
console.log( second.name );                            // Prints "_ANONYMOUS_3".

In the tooltip

IsInFadeInAnimation tells you with a true or false whether or not the queried tooltiper is in a current running fade-in animation. Likewise, you have sister variables .IsInFadeOutAnimation, .IsInMoveInAnimation and .IsInMoveOutAnimation for the very same purposes.

All current settings applied to any one maTooltip is stored as properties of an object located in SETTINGS. See the section above titled "Settings and Global Configuration" for a walk through.

The DOM object has three properties .$divParent, .$divArrow and .$divContents. These are jQuery references to the respective div element in the document tree that maTooltip creates for every new tooltip. These elements are only in the document whenever the tooltiper is visible. But the tooltiper sure doesn't have to be visible for you to grab a hold of the elements and do whatever you like with them. The practice has been more thoroughly explained and demoed here.

name is a string that holds the tooltiper's name used in the maTooltip.INSTANCES object as explained in the previous section.

$ is a jQuery reference to the target element.

Callbacks are not natively supported by maTooltip. But there is an object stored in every tooltip called _animCompleteCallbacks which has four properties, all of which are arrays: fadein, fadeout, movein and moveout. These arrays are sometimes used internally to store functions that executes after each animation has completed. Thereafter, the function is removed from the array so keep that in mind. But if you have the need to then there's nothing stopping you from adding your own functions. Example:

var tooltip = new maTooltip('#someTarget', {static_message: 'whatever'});
tooltip._animCompleteCallbacks.fadein.push(function () { alert('Hello world!'); });

tooltip.show();                       // Will alert "Hello world!" when done.
setTimeout(function () {
    tooltip.show();                   // Will NOT alert! Function has been removed after first run.
    }, 5000);

Public API

Static methods

maTooltip.quickTooltip( what_element, what_message /* , optional_settings */ ) is a factory method and has been explained and demoed over at the How To Use page. The third argument is optional and is a conventient way to further more specify particular settings that the factory method forwards to the constructor. The setting one_time_only cannot be overridden though, it will always be set to true when using the factory method.

maTooltip.getDefaults() accepts no arguments and will return the defaults object, which has been explained previously on this page, in the section Settings and Global Configuration.

Looking for the constructor? You guessed it, has been explained and demoed over at the at the How To Use page. The constructor is also explained in more details on this page in the section Settings and Global Configuration.

maTooltip methods

.dispose() will promote effective garbage collection usage. Doing so primarly by fully removing the tooltipers DOM elements. It accepts no arguments and does not throw exceptions.

.show() will display the tooltip. What message to display is preferably setup when instantiating the tooltip with the option static_message supplied to the settings object, passed to the constructor. Do have a look at the Settings and Global Configuration section for more details. Supplying an argument to the .show() method is only temporary. The static message won't change. If the static message has been set earlier, the tooltip will revert back to it after the current call. If the static message has not been set, and there is no argument supplied to .show(), then there won't be no message displayed in the tooltip. Only an empty frame will show. The argument supplied can be a string, a function or even an object. Review basic example 3 and basic example 4 to see how to setup a function or object. In these examples, the message will be set upon creation of the tooltip. But it isn't any different from passing the same function or object as an argument to the .show() method.

.hide() hides the tooltip. It doesn't destroy the DOM or anything like that, for that purpose you would want to use .dispose() instead. .hide() can optionally accept a boolean argument. If true, then the tooltiper will hide instantly without any regard to move out or fade out animations.

.toggle() toggles current visibility.

.isAnyAnimationAlive() answers the question accordingly. The full implementation goes like this:

return this.IsInFadeInAnimation || this.IsInFadeOutAnimation || this.IsInMoveInAnimation || this.IsInMoveOutAnimation || false;

.getDimensionsAndPositions( /* dimensions */ ) is a conventient way to query the size and position of a tooltip. The return value is an object that has some neet properties set. Property targetElemOffset is another object, the very same object that calling jQuery's .offset() method on the target would return. This object in turn defines .top and .left. Please see jQuery's documentation on the subject. Properties targetElemWidth and targetElemHeight is the target element's height and width in pixels (integer), including padding and border, excluding margin. Properties tooltiperWidth and tooltiperHeight is likewise the width and height of the tooltip, accounting for the tooltiper's stem (arrow). Actually, it is the size of the wrapper DIV you can access through a variable set in the tooltip: .DOM.$divParent. Properties top_final and left_final is the target position after an optional move in animation has finished. Top and left are measured in pixels (integer) from the upper left corner of the document. Likewise, the properties top_start and left_start give away the starting position of a tooltip which will be different from the final position if a move in animation has been set. Properties top_current and left_current says exactly where a tooltiper is when you make the call to .getDimensionsAndPositions(). Instead of parsing the returned object, you could optionally pass in an object as an argument to .getDimensionsAndPositions() and store all properties in that argument instead. Note however, that all other properties in that object will be destroyed.

.isFullyVisible() says whether the tooltiper is currently visible. Algorithmically, if all animations have finished and the current opacity is close to the target opacity, the tooltiper is considered to be visible. The full implementation goes like this:

if (this.isAnyAnimationAlive() === true)
    return false;

return this.DOM.$divParent.css('opacity') >= (this.SETTINGS.opacity * 0.90);

.isFullyHidden() says whether the tooltiper is currently not visible. The full implementation goes like this:

if (this.isAnyAnimationAlive() === true)
    return false;

return this.DOM.$divParent.css('opacity') == 0;

Calling .positionMightBeDirty() will force the tooltiper to recalculate his position and stuff. Event handlers has already been setup to call this method whenever the browser window is resized and once when the document DOM has fully finished loading (including fonts). You should only need to call this method if you have a gut feeling that the tooltip might or should be out of place. For instance, if it is attached to target elements who themselves have had their positions altered.

Need more?

The source is open and available at Github. There you'll find the internal API, algorithms and variables explained with comments in JSDoc. Feel free to ask me if you still haven't found what you are looking for.