Advanced

 

Summary

Events triggered by jqDock Hook functions (options) Events listened for by jqDock Command strings

[ As of v1.5 unless indicated otherwise ]

Events & ‘Sleeping’ Dock1.5

As of v1.5, a number of custom events have been introduced, mainly to support the new concept of the Dock being able to “go to sleep”. This enables the calling script (if it so desires) to do something with the Dock – like slide it out of view – if it has not been used for a while.

Basically, the Dock will (if instructed to – see the idle option) go to sleep after a specified period during which the mouse has not entered the Dock. Technically, it does this by setting a timer on a mouseleave event, cancelling the timer on any mouseenter or mousemove event (within the Dock). The duration of the timer is set via the idle option, and if the timer fires then the Dock goes to sleep.
Note that this is totally different to the inactivity option, which is for the absence of mouse movement while over the Dock.

Also, the calling script has the ability to put the Dock to sleep at any time, by triggering an event or issuing a command to the Dock.
Alternatively, as of v1.61.6, the Dock can be ‘frozen’, which is the same as putting it to sleep but without the collapse to its ‘at rest’ state.

Once the Dock has gone to sleep, the only way to wake it up it is to ‘nudge’ it. While the Dock is alseep it will not respond to any mouse movement events (enter, leave or move) but it will still respond to clicks.

jqDock Will Call …

jqDock has a number of hook functions available as “on___” options (see Options). These are synchronous function calls that precede notification of the related event (see jqDock Will Trigger… below):

  • onReady

    Called after jqDock has completed initialisation and is ready to reveal the Dock. Returning false from the onReady() call will prevent the Dock being revealed, put the Dock to sleep, and prevent notification of the dockshow event.

    As of v1.61.6 the function receives a single parameter : a string, ‘ready’.

    Note that, unlike the other “on___” calls, onReady() and dockshow are separated by another process – that of actually ‘revealing’ the Dock. If the fadeIn option is set, there could be a discernible delay because dockshow is only triggered once the Dock is fully visible.

    Warning : If you return false from an onReady() function, you have effectively absolved jqDock of any responsibility for the initial display of the Dock! It is your script that will have to ensure that the Dock is, or becomes, visible and usable, and then ‘nudge’ the Dock awake.

  • onSleep

    Called immediately prior to putting a non-sleeping Dock to sleep, or freezing1.6 a non-frozen Dock, with the following exceptions:

    • onReady returning false
    • the issue of an ‘active‘ or ‘expand‘ command on an image1.6

    Returning false will prevent the Dock going to sleep. Note that even if onSleep() returns false the idle timer does not get automatically reset! It will require a ‘nudge’ to reset it.

    As of v1.61.6 the function receives a single parameter : a string, with a value of either ‘sleep’ or ‘freeze’. The value of this parameter indicates the method being used to put the Dock to sleep.

  • onWake

    Called immediately prior to waking the Dock from sleep. Returning false will prevent the Dock waking up.

    As of v1.61.6 the function receives a single parameter : a string, with a value of either ‘wake’ or ‘thaw’. The value of this parameter is indicative of the method that was used to put the Dock to sleep : ‘‘thaw’ indicates that the Dock had been ‘frozen’; otherwise, the value will be ‘wake’.

As of v1.91.9 you can simply supply a boolean false instead of a function for any of these “on___” options, which is the equivalent of supplying your own function that always returns false.

jqDock Will Trigger …

There are a number of events triggered that a calling script may listen for, all of which are notified to the original menu element:

  • dockshow

    Triggered once (and once only) when the Dock has initially been made visible after initialisation. Can be prevented by onReady() (see onReady and Options) returning false.

    As of v1.61.6, the listener is passed an additional parameter (besides the Event object) which is a string with the value of ‘ready’.

  • docksleep

    Triggered the instant a non-sleeping Dock goes to sleep (except when onReady() returns false), or a non-frozen Dock becomes frozen1.6, with the following exceptions:

    • onReady returning false

    Can be prevented by onSleep() (see onSleep and Options) – which immediately precedes it – returning false.

    As of v1.61.6, the listener is passed an additional parameter (besides the Event object) which is a string with a value of either ‘sleep’ or ‘freeze’. This parameter indicates how the Dock was put to sleep : if the Dock was ‘frozen’ – as a result of receiving a dockfreeze event, or a ‘freeze’ command – then the parameter will be set to ‘freeze’; otherwise, the parameter will be set to ‘sleep’.

  • dockwake

    Triggered the instant the Dock is woken up (from either a ‘sleep’ or a ‘freeze’1.6). Can be prevented by onWake() (see onWake and Options) – which immediately precedes it – returning false.

    As of v1.61.6, the listener is passed an additional parameter (besides the Event object) which is a string with a value of either ‘wake’ or ‘thaw’. This parameter indicates how the Dock was previously put to sleep : if the Dock was previously ‘frozen’, then the parameter will be set to ‘thaw’; otherwise, the parameter will be set to ‘wake’.

  • dockitem2.0

    Triggered the instant any image either leaves or returns to its ‘at rest’ position.

    The listener is passed 2 extra parameters (besides the Event object) : the DOM element of the image in question, and a Boolean flag indicating whether that image is leaving its ‘at rest’ position (true) or has just returned to it (false).

jqDock Listens For …

There are a number of events that jqDock will listen for, ie. a calling script can trigger them (on the original menu element):

  • dockidle

    On receipt, the Dock will (if not already asleep) attempt to go to sleep by calling onSleep(), and then triggering docksleep if successful. The [extra] parameter1.6 passed into the function and event will be ‘sleep’.

  • docknudge

    On receipt, the Dock will attempt to wake up (if asleep) by calling onWake() and then triggering dockwake if successful. The [extra] parameter1.6 passed into the function and event will be ‘thaw’ if the Dock was frozen, or ‘wake’ otherwise.

    If the Dock is not asleep when it receives a docknudge, it will (if appropriate) reset the idle timer.

  • dockfreeze1.6

    On receipt, the Dock will (if not already asleep) attempt to go to sleep by calling onSleep(), and then triggering docksleep if successful. The [extra] parameter passed into the function and event will be ‘freeze’.

jqDock Command Strings…

An alternative to triggering the above events – dockidle, docknudge or dockfreeze1.6 – is to issue a command string – ‘idle‘, ‘nudge‘ or ‘freeze1.6respectively – directly to jqDock():

There are also some additional command strings:

  • active1.6

    May be called on an image within a Dock in order to instantly (ie. no animation) expand that image to full size. (Also see expand below)

  • expand1.6

    May be called on an image within a Dock in order to animate the expansion of that image to full size.

    Warning : Both active and expand immediately freeze the dock and trigger a docksleep event (if the Dock was not already frozen), but they do not call any onSleep() function! In both cases a ‘nudge’ is required in order to wake the Dock up again.

  • get1.6

    Depending on the selector, this will return the internal object for either the Dock itself, or an image within a Dock.

  • destroy1.6

    Removes jqDock from a menu.

    There are a few things to note:
    • Only elements, events, classes, etc, that jqDock has applied will be removed. If you have bound your own event handlers to the original menu element (for docksleep, dockwake, etc), then their removal and/or replacement is down to you.
    • Any text nodes removed by jqDock are not restored.
    • The original menu element may have residual inline styling (eg. to make it visible if it was initially hidden).

Sleep vs. Freeze1.6

A Freeze really only differs from a Sleep in one respect : the Dock is not automatically collapsed back to its ‘at rest’ state, it is literally ‘frozen’ at whatever state of expansion it was at at the time. In all other respects they are the same, and actually a ‘frozen’ Dock is also ‘asleep’!

The same function – onSleep() – is called for both a Sleep and a Freeze; and the same event – docksleep – is triggered. And when ‘nudged’ awake (or ‘unfrozen’), the same onWake() function is called, and the same dockwake event is triggered. The only subtle difference is that jqDock tries to keep you informed about which state is/will be set – Freeze or Sleep – by changing the string parameter passed into these functions/events…

  As a result of… jqDock… On ‘nudge’, jqDock…
Sleep
  • idle option is set and gets activated, or
  • script triggers dockidle event, or
  • script calls jqDock(‘idle’)

if Dock is not already asleep:

  • calls onSleep(‘sleep’)
  • triggers docksleep, with parameter ‘sleep’
  • calls onWake(‘wake’)
  • triggers dockwake, with parameter ‘wake’
  • script returns false from onReady()
 
Freeze
  • script triggers dockfreeze event, or
  • script calls jqDock(‘freeze’)

if Dock is not already frozen:

  • calls onSleep(‘freeze’)
  • triggers docksleep, with parameter ‘freeze’
  • calls onWake(‘thaw’)
  • triggers dockwake, with parameter ‘thaw’
  • script calls [img].jqDock(‘active’), or
  • script calls [img].jqDock(‘expand’)

if Dock is not already frozen:

  • triggers docksleep, with parameter ‘freeze’

[ Please note that anything to do with ‘freeze’, or extra parameters being passed into functions/events, only applies as of version 1.6. ]

Illustrations of Event/Callback Sequences

Share
 Posted by at 10:45 am

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">

(required)

(required)