Make WordPress Core

Changeset 41310


Ignore:
Timestamp:
08/24/2017 05:47:58 PM (4 years ago)
Author:
wonderboymusic
Message:

Docs: improve JS docs for editor-expand.js

Props IreneYoast, terwdan.
Fixes #41068.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/editor-expand.js

    r38893 r41310  
    77        $footer = $( '#wpfooter' );
    88
    9     /* Autoresize editor. */
     9    /**
     10     * @summary Handles the resizing of the editor.
     11     *
     12     * @since 4.0.0
     13     *
     14     * @returns {void}
     15     */
    1016    $( function() {
    1117        var $wrap = $( '#postdivrich' ),
     
    5460            };
    5561
     62        /**
     63         * @summary Resizes textarea based on scroll height and width.
     64         *
     65         * Resizes textarea based on scroll height and width. Doesn't shrink the
     66         * editor size below the 300px auto resize minimum height.
     67         *
     68         * @since 4.6.1
     69         *
     70         * @returns {void}
     71         */
    5672        var shrinkTextarea = window._.throttle( function() {
    5773            var x = window.scrollX || document.documentElement.scrollLeft;
     
    7490        }, 300 );
    7591
     92        /**
     93         * @summary Resizes the text editor depending on the old text length.
     94         *
     95         * If there is an mceEditor and it is hidden, it resizes the editor depending
     96         * on the old text length. If the current length of the text is smaller than
     97         * the old text length, it shrinks the text area. Otherwise it resizes the editor to
     98         * the scroll height.
     99         *
     100         * @since 4.6.1
     101         *
     102         * @returns {void}
     103         */
    76104        function textEditorResize() {
    77105            var length = textEditor.value.length;
     
    95123        }
    96124
     125        /**
     126         * @summary Gets the height and widths of elements.
     127         *
     128         * Gets the heights of the window, the adminbar, the tools, the menu,
     129         * the visualTop, the textTop, the bottom, the statusbar and sideSortables
     130         * and stores these in the heights object. Defaults to 0.
     131         * Gets the width of the window and stores this in the heights object.
     132         *
     133         * @since 4.0.0
     134         *
     135         * @returns {void}
     136         */
    97137        function getHeights() {
    98138            var windowWidth = $window.width();
     
    111151            };
    112152
    113             // Adjust for hidden
     153            // Adjust for hidden menubar.
    114154            if ( heights.menuBarHeight < 3 ) {
    115155                heights.menuBarHeight = 0;
     
    118158
    119159        // We need to wait for TinyMCE to initialize.
     160        /**
     161         * @summary Binds all necessary functions for editor expand to the editor
     162         * when the editor is initialized.
     163         *
     164         * @since 4.0.0
     165         *
     166         * @param {event} event The TinyMCE editor init event.
     167         * @param {object} editor The editor to bind the vents on.
     168         *
     169         * @returns {void}
     170         */
    120171        $document.on( 'tinymce-editor-init.editor-expand', function( event, editor ) {
     172            // VK contains the type of key pressed. VK = virtual keyboard.
    121173            var VK = window.tinymce.util.VK,
     174                /**
     175                 * @summary Hides any float panel with a hover state. Additionally hides tooltips.
     176                 *
     177                 * @returns {void}
     178                 */
    122179                hideFloatPanels = _.debounce( function() {
    123180                    ! $( '.mce-floatpanel:hover' ).length && window.tinymce.ui.FloatPanel.hideAll();
     
    142199            $menuBar = $contentWrap.find( '.mce-menubar' );
    143200
     201            /**
     202             * @summary Gets the offset of the editor.
     203             *
     204             * @returns {Number|Boolean} Returns the offset of the editor
     205             * or false if there is no offset height.
     206             */
    144207            function mceGetCursorOffset() {
    145208                var node = editor.selection.getNode(),
    146209                    range, view, offset;
    147210
     211                /*
     212                 * If editor.wp.getView and the selection node from the editor selection
     213                 * are defined, use this as a view for the offset.
     214                 */
    148215                if ( editor.wp && editor.wp.getView && ( view = editor.wp.getView( node ) ) ) {
    149216                    offset = view.getBoundingClientRect();
     
    151218                    range = editor.selection.getRng();
    152219
     220                    // Try to get the offset from a range.
    153221                    try {
    154222                        offset = range.getClientRects()[0];
    155223                    } catch( er ) {}
    156224
     225                    // Get the offset from the bounding client rectangle of the node.
    157226                    if ( ! offset ) {
    158227                        offset = node.getBoundingClientRect();
     
    163232            }
    164233
    165             // Make sure the cursor is always visible.
    166             // This is not only necessary to keep the cursor between the toolbars,
    167             // but also to scroll the window when the cursor moves out of the viewport to a wpview.
    168             // Setting a buffer > 0 will prevent the browser default.
    169             // Some browsers will scroll to the middle,
    170             // others to the top/bottom of the *window* when moving the cursor out of the viewport.
     234            /**
     235             * @summary Filters the special keys that should not be used for scrolling.
     236             *
     237             * @since 4.0.0
     238             *
     239             * @param {event} event The event to get the key code from.
     240             *
     241             * @returns {void}
     242             */
    171243            function mceKeyup( event ) {
    172244                var key = event.keyCode;
    173245
    174                 // Bail on special keys.
     246                // Bail on special keys. Key code 47 is a /
    175247                if ( key <= 47 && ! ( key === VK.SPACEBAR || key === VK.ENTER || key === VK.DELETE || key === VK.BACKSPACE || key === VK.UP || key === VK.LEFT || key === VK.DOWN || key === VK.UP ) ) {
    176248                    return;
    177                 // OS keys, function keys, num lock, scroll lock
     249                // OS keys, function keys, num lock, scroll lock. Key code 91-93 are OS keys. Key code 112-123 are F1 to F12. Key code 144 is num lock. Key code 145 is scroll lock.
    178250                } else if ( ( key >= 91 && key <= 93 ) || ( key >= 112 && key <= 123 ) || key === 144 || key === 145 ) {
    179251                    return;
     
    183255            }
    184256
     257            /**
     258             * @summary Makes sure the cursor is always visible in the editor.
     259             *
     260             * Makes sure the cursor is kept between the toolbars of the editor and scrolls
     261             * the window when the cursor moves out of the viewport to a wpview.
     262             * Setting a buffer > 0 will prevent the browser default.
     263             * Some browsers will scroll to the middle,
     264             * others to the top/bottom of the *window* when moving the cursor out of the viewport.
     265             *
     266             * @since 4.1.0
     267             *
     268             * @param {string} key The key code of the pressed key.
     269             *
     270             * @returns {void}
     271             */
    185272            function mceScroll( key ) {
    186273                var offset = mceGetCursorOffset(),
     
    188275                    cursorTop, cursorBottom, editorTop, editorBottom;
    189276
     277                // Don't scroll if there is no offset.
    190278                if ( ! offset ) {
    191279                    return;
    192280                }
    193281
     282                // Determine the cursorTop based on the offset and the top of the editor iframe.
    194283                cursorTop = offset.top + editor.iframeElement.getBoundingClientRect().top;
     284
     285                // Determine the cursorBottom based on the cursorTop and offset height.
    195286                cursorBottom = cursorTop + offset.height;
     287
     288                // Subtract the buffer from the cursorTop.
    196289                cursorTop = cursorTop - buffer;
     290
     291                // Add the buffer to the cursorBottom.
    197292                cursorBottom = cursorBottom + buffer;
    198293                editorTop = heights.adminBarHeight + heights.toolsHeight + heights.menuBarHeight + heights.visualTopHeight;
     294
     295                /*
     296                 * Set the editorBottom based on the window Height, and add the bottomHeight and statusBarHeight if the
     297                 * advanced editor is enabled.
     298                 */
    199299                editorBottom = heights.windowHeight - ( advanced ? heights.bottomHeight + heights.statusBarHeight : 0 );
    200300
    201                 // Don't scroll if the node is taller than the visible part of the editor
     301                // Don't scroll if the node is taller than the visible part of the editor.
    202302                if ( editorBottom - editorTop < offset.height ) {
    203303                    return;
    204304                }
    205305
     306                /*
     307                 * If the cursorTop is smaller than the editorTop and the up, left
     308                 * or backspace key is pressed, scroll the editor to the position defined
     309                 * by the cursorTop, pageYOffset and editorTop.
     310                 */
    206311                if ( cursorTop < editorTop && ( key === VK.UP || key === VK.LEFT || key === VK.BACKSPACE ) ) {
    207312                    window.scrollTo( window.pageXOffset, cursorTop + window.pageYOffset - editorTop );
     313
     314                /*
     315                 * If any other key is pressed or the cursorTop is bigger than the editorTop,
     316                 * scroll the editor to the position defined by the cursorBottom,
     317                 * pageYOffset and editorBottom.
     318                 */
    208319                } else if ( cursorBottom > editorBottom ) {
    209320                    window.scrollTo( window.pageXOffset, cursorBottom + window.pageYOffset - editorBottom );
     
    211322            }
    212323
     324            /**
     325             * @summary If the editor is fullscreen, calls adjust.
     326             *
     327             * @since 4.1.0
     328             *
     329             * @param {event} event The FullscreenStateChanged event.
     330             *
     331             * @returns {void}
     332             */
    213333            function mceFullscreenToggled( event ) {
     334                // event.state is true if the editor is fullscreen.
    214335                if ( ! event.state ) {
    215336                    adjust();
     
    217338            }
    218339
    219             // Adjust when switching editor modes.
     340            /**
     341             * @summary Shows the editor when scrolled.
     342             *
     343             * Binds the hideFloatPanels function on the window scroll.mce-float-panels event.
     344             * Executes the wpAutoResize on the active editor.
     345             *
     346             * @since 4.0.0
     347             *
     348             * @returns {void}
     349             */
    220350            function mceShow() {
    221351                $window.on( 'scroll.mce-float-panels', hideFloatPanels );
     
    227357            }
    228358
     359            /**
     360             * @summary Resizes the editor.
     361             *
     362             * Removes all functions from the window scroll.mce-float-panels event.
     363             * Resizes the text editor and scrolls to a position based on the pageXOffset and adminBarHeight.
     364             *
     365             * @since 4.0.0
     366             *
     367             * @returns {void}
     368             */
    229369            function mceHide() {
    230370                $window.off( 'scroll.mce-float-panels' );
     
    244384            }
    245385
     386            /**
     387             * @summary Toggles advanced states.
     388             *
     389             * @since 4.1.0
     390             *
     391             * @returns {void}
     392             */
    246393            function toggleAdvanced() {
    247394                advanced = ! advanced;
    248395            }
    249396
     397            /**
     398             * @summary Binds events of the editor and window.
     399             *
     400             * @since 4.0.0
     401             *
     402             * @returns {void}
     403             */
    250404            mceBind = function() {
    251405                editor.on( 'keyup', mceKeyup );
     
    253407                editor.on( 'hide', mceHide );
    254408                editor.on( 'wp-toolbar-toggle', toggleAdvanced );
     409
    255410                // Adjust when the editor resizes.
    256411                editor.on( 'setcontent wp-autoresize wp-toolbar-toggle', adjust );
     412
    257413                // Don't hide the caret after undo/redo.
    258414                editor.on( 'undo redo', mceScroll );
     415
    259416                // Adjust when exiting TinyMCE's fullscreen mode.
    260417                editor.on( 'FullscreenStateChanged', mceFullscreenToggled );
     
    263420            };
    264421
     422            /**
     423             * @summary Unbinds the events of the editor and window.
     424             *
     425             * @since 4.0.0
     426             *
     427             * @returns {void}
     428             */
    265429            mceUnbind = function() {
    266430                editor.off( 'keyup', mceKeyup );
     
    276440
    277441            if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
    278                 // Adjust "immediately"
     442
     443                // Adjust "immediately".
    279444                mceBind();
    280445                initialResize( adjust );
     
    282447        } );
    283448
    284         // Adjust the toolbars based on the active editor mode.
     449        /**
     450         * @summary Adjusts the toolbars heights and positions.
     451         *
     452         * Adjusts the toolbar heights and positions based on the scroll position on the page,
     453         * the active editor mode and the heights of the editor, admin bar and side bar.
     454         *
     455         * @since 4.0.0
     456         *
     457         * @param {event} event The event that calls this function.
     458         *
     459         * @returns {void}
     460         */
    285461        function adjust( event ) {
    286             // Make sure we're not in fullscreen mode.
     462
     463            // Makes sure we're not in fullscreen mode.
    287464            if ( fullscreen && fullscreen.settings.visible ) {
    288465                return;
     
    300477                topPos, topHeight, editorPos, editorHeight;
    301478
    302             // Refresh the heights
     479            /*
     480             * Refresh the heights if type isn't 'scroll'
     481             * or heights.windowHeight isn't set.
     482             */
    303483            if ( resize || ! heights.windowHeight ) {
    304484                getHeights();
    305485            }
    306486
     487            // Resize on resize event when the editor is in text mode.
    307488            if ( ! visual && type === 'resize' ) {
    308489                textEditorResize();
     
    319500            }
    320501
    321             // TinyMCE still initializing.
     502            // Return if TinyMCE is still intializing.
    322503            if ( ! visual && ! $top.length ) {
    323504                return;
     
    328509            editorHeight = $editor.outerHeight();
    329510
    330             // Should we pin?
     511            /*
     512             * If in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + topHeight.
     513             * If not in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + 20.
     514             */
    331515            canPin = visual ? autoresizeMinHeight + topHeight : autoresizeMinHeight + 20; // 20px from textarea padding
    332516            canPin = editorHeight > ( canPin + 5 );
     
    358542                }
    359543            } else {
    360                 // Maybe pin the top.
     544                // Check if the top is not already in a fixed position.
    361545                if ( ( ! fixedTop || resize ) &&
    362                     // Handle scrolling down.
    363546                    ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight ) &&
    364                     // Handle scrolling up.
    365547                    windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) ) {
    366548                    fixedTop = true;
     
    385567                        width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
    386568                    } );
    387                 // Maybe unpin the top.
     569                    // Check if the top is already in a fixed position.
    388570                } else if ( fixedTop || resize ) {
    389                     // Handle scrolling up.
    390571                    if ( windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight ) ) {
    391572                        fixedTop = false;
     
    410591                            width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
    411592                        } );
    412                     // Handle scrolling down.
    413593                    } else if ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) {
    414594                        fixedTop = false;
     
    436616                }
    437617
    438                 // Maybe adjust the bottom bar.
     618                // Check if the bottom is not already in a fixed position.
    439619                if ( ( ! fixedBottom || ( resize && advanced ) ) &&
    440                         // +[n] for the border around the .wp-editor-container.
     620                        // Add borderWidth for the border around the .wp-editor-container.
    441621                        ( windowPos + heights.windowHeight ) <= ( editorPos + editorHeight + heights.bottomHeight + heights.statusBarHeight + borderWidth ) ) {
    442622
     
    469649            }
    470650
    471             // Sidebar pinning
    472             if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 && // sidebar position is changed with @media from CSS, make sure it is on the side
    473                 $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) && // the sidebar is not the tallest element
    474                 heights.windowHeight < editorHeight ) { // the editor is taller than the viewport
     651            // The postbox container is positioned with @media from CSS. Ensure it is pinned on the side.
     652            if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 &&
     653
     654                // Check if the sidebar is not taller than the document height.
     655                $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) &&
     656
     657                // Check if the editor is taller than the viewport.
     658                heights.windowHeight < editorHeight ) {
    475659
    476660                if ( ( heights.sideSortablesHeight + pinnedToolsTop + sidebarBottom ) > heights.windowHeight || fixedSideTop || fixedSideBottom ) {
    477                     // Reset when scrolling to the top
     661
     662                    // Reset the sideSortables style when scrolling to the top.
    478663                    if ( windowPos + pinnedToolsTop <= postBodyTop ) {
    479664                        $sideSortables.attr( 'style', '' );
    480665                        fixedSideTop = fixedSideBottom = false;
    481666                    } else {
     667
     668                        // When scrolling down.
    482669                        if ( windowPos > lastScrollPosition ) {
    483                             // Scrolling down
    484670                            if ( fixedSideTop ) {
    485                                 // let it scroll
     671
     672                                // Let it scroll.
    486673                                fixedSideTop = false;
    487674                                sidebarTop = $sideSortables.offset().top - heights.adminBarHeight;
    488675                                footerTop = $footer.offset().top;
    489676
    490                                 // don't get over the footer
     677                                // Don't get over the footer.
    491678                                if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
    492679                                    sidebarTop = footerTop - heights.sideSortablesHeight - 12;
     
    499686                                });
    500687                            } else if ( ! fixedSideBottom && heights.sideSortablesHeight + $sideSortables.offset().top + sidebarBottom < windowPos + heights.windowHeight ) {
    501                                 // pin the bottom
     688                                // Pin the bottom.
    502689                                fixedSideBottom = true;
    503690
     
    508695                                });
    509696                            }
     697
     698                        // When scrolling up.
    510699                        } else if ( windowPos < lastScrollPosition ) {
    511                             // Scrolling up
    512700                            if ( fixedSideBottom ) {
    513                                 // let it scroll
     701                                // Let it scroll.
    514702                                fixedSideBottom = false;
    515703                                sidebarTop = $sideSortables.offset().top - sidebarBottom;
    516704                                footerTop = $footer.offset().top;
    517705
    518                                 // don't get over the footer
     706                                // Don't get over the footer.
    519707                                if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
    520708                                    sidebarTop = footerTop - heights.sideSortablesHeight - 12;
     
    527715                                });
    528716                            } else if ( ! fixedSideTop && $sideSortables.offset().top >= windowPos + pinnedToolsTop ) {
    529                                 // pin the top
     717                                // Pin the top.
    530718                                fixedSideTop = true;
    531719
     
    539727                    }
    540728                } else {
    541                     // if the sidebar container is smaller than the viewport, then pin/unpin the top when scrolling
     729                    // If the sidebar container is smaller than the viewport, then pin/unpin the top when scrolling.
    542730                    if ( windowPos >= ( postBodyTop - pinnedToolsTop ) ) {
    543731
     
    576764        }
    577765
     766        /**
     767         * @summary Resizes the editor and adjusts the toolbars.
     768         *
     769         * @since 4.0.0
     770         *
     771         * @returns {void}
     772         */
    578773        function fullscreenHide() {
    579774            textEditorResize();
     
    581776        }
    582777
     778        /**
     779         * @summary Runs the passed function with 500ms intervals.
     780         *
     781         * @since 4.0.0
     782         *
     783         * @param {function} callback The function to run in the timeout.
     784         *
     785         * @returns {void}
     786         */
    583787        function initialResize( callback ) {
    584788            for ( var i = 1; i < 6; i++ ) {
     
    587791        }
    588792
     793        /**
     794         * @summary Runs adjust after 100ms.
     795         *
     796         * @since 4.0.0
     797         *
     798         * @returns {void}
     799         */
    589800        function afterScroll() {
    590801            clearTimeout( scrollTimer );
     
    592803        }
    593804
     805        /**
     806         * @summary Binds editor expand events on elements.
     807         *
     808         * @since 4.0.0
     809         *
     810         * @returns {void}
     811         */
    594812        function on() {
    595             // Scroll to the top when triggering this from JS.
    596             // Ensures toolbars are pinned properly.
     813            /*
     814             * Scroll to the top when triggering this from JS.
     815             * Ensure the toolbars are pinned properly.
     816             */
    597817            if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
    598818                window.scrollTo( window.pageXOffset, 0 );
     
    607827            } );
    608828
    609             // Adjust when collapsing the menu, changing the columns, changing the body class.
     829            /*
     830             * Adjust when collapsing the menu, changing the columns
     831             * or changing the body class.
     832             */
    610833            $document.on( 'wp-collapse-menu.editor-expand postboxes-columnchange.editor-expand editor-classchange.editor-expand', adjust )
    611834                .on( 'postbox-toggled.editor-expand postbox-moved.editor-expand', function() {
     
    629852            mceBind();
    630853
    631             // Adjust when entering/exiting fullscreen mode.
     854            // Adjust when entering or exiting fullscreen mode.
    632855            fullscreen && fullscreen.pubsub.subscribe( 'hidden', fullscreenHide );
    633856
     
    650873        }
    651874
     875        /**
     876         * @summary Unbinds editor expand events.
     877         *
     878         * @since 4.0.0
     879         *
     880         * @returns {void}
     881         */
    652882        function off() {
    653883            var height = parseInt( window.getUserSetting( 'ed_size', 300 ), 10 );
     
    659889            }
    660890
    661             // Scroll to the top when triggering this from JS.
    662             // Ensures toolbars are reset properly.
     891            /*
     892             * Scroll to the top when triggering this from JS.
     893             * Ensure the toolbars are reset properly.
     894             */
    663895            if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
    664896                window.scrollTo( window.pageXOffset, 0 );
     
    672904            mceUnbind();
    673905
    674             // Adjust when entering/exiting fullscreen mode.
     906            // Adjust when entering or exiting fullscreen mode.
    675907            fullscreen && fullscreen.pubsub.unsubscribe( 'hidden', fullscreenHide );
    676908
     
    695927            }
    696928
     929            // If there is a height found in the user setting.
    697930            if ( height ) {
    698931                $textEditor.height( height );
     
    702935        }
    703936
    704         // Start on load
     937        // Start on load.
    705938        if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
    706939            on();
    707940
    708             // Ideally we need to resize just after CSS has fully loaded and QuickTags is ready.
     941            // Resize just after CSS has fully loaded and QuickTags is ready.
    709942            if ( $contentWrap.hasClass( 'html-active' ) ) {
    710943                initialResize( function() {
     
    715948        }
    716949
    717         // Show the on/off checkbox
     950        // Show the on/off checkbox.
    718951        $( '#adv-settings .editor-expand' ).show();
    719952        $( '#editor-expand-toggle' ).on( 'change.editor-expand', function() {
     
    727960        });
    728961
    729         // Expose on() and off()
     962        // Expose on() and off().
    730963        window.editorExpand = {
    731964            on: on,
     
    734967    } );
    735968
    736     /* DFW. */
     969    /**
     970     * @summary Handles the distraction free writing of TinyMCE.
     971     *
     972     * @since 4.1.0
     973     *
     974     * @returns {void}
     975     */
    737976    $( function() {
    738977        var $body = $( document.body ),
     
    7781017        } );
    7791018
     1019        /**
     1020         * @summary Recalculates the bottom and right position of the editor in the DOM.
     1021         *
     1022         * @since 4.1.0
     1023         *
     1024         * @returns {void}
     1025         */
    7801026        function recalcEditorRect() {
    7811027            editorRect = $editor.offset();
     
    7841030        }
    7851031
     1032        /**
     1033         * @summary Activates the distraction free writing mode.
     1034         *
     1035         * @since 4.1.0
     1036         *
     1037         * @returns {void}
     1038         */
    7861039        function activate() {
    7871040            if ( ! _isActive ) {
     
    7931046        }
    7941047
     1048        /**
     1049         * @summary Deactivates the distraction free writing mode.
     1050         *
     1051         * @since 4.1.0
     1052         *
     1053         * @returns {void}
     1054         */
    7951055        function deactivate() {
    7961056            if ( _isActive ) {
     
    8041064        }
    8051065
     1066        /**
     1067         * @summary Returns _isActive.
     1068         *
     1069         * @since 4.1.0
     1070         *
     1071         * @returns {boolean} Returns true is _isActive is true.
     1072         */
    8061073        function isActive() {
    8071074            return _isActive;
    8081075        }
    8091076
     1077        /**
     1078         * @summary Binds events on the editor for distraction free writing.
     1079         *
     1080         * @since 4.1.0
     1081         *
     1082         * @returns {void}
     1083         */
    8101084        function on() {
    8111085            if ( ! _isOn && _isActive ) {
     
    8241098        }
    8251099
     1100        /**
     1101         * @summary Unbinds events on the editor for distraction free writing.
     1102         *
     1103         * @since 4.1.0
     1104         *
     1105         * @returns {void}
     1106         */
    8261107        function off() {
    8271108            if ( _isOn ) {
     
    8401121        }
    8411122
     1123        /**
     1124         * @summary Binds or unbinds the editor expand events.
     1125         *
     1126         * @since 4.1.0
     1127         *
     1128         * @returns {void}
     1129         */
    8421130        function toggle() {
    8431131            if ( _isOn ) {
     
    8481136        }
    8491137
     1138        /**
     1139         * @summary Returns the value of _isOn.
     1140         *
     1141         * @since 4.1.0
     1142         *
     1143         * @returns {boolean} Returns true if _isOn is true.
     1144         */
    8501145        function isOn() {
    8511146            return _isOn;
    8521147        }
    8531148
     1149        /**
     1150         * @summary Fades out all elements except for the editor.
     1151         *
     1152         * The fading is done based on key presses and mouse movements.
     1153         * Also calls the fadeIn on certain key presses
     1154         * or if the mouse leaves the editor.
     1155         *
     1156         * @since 4.1.0
     1157         *
     1158         * @param event The event that triggers this function.
     1159         *
     1160         * @returns {void}
     1161         */
    8541162        function fadeOut( event ) {
    8551163            var isMac,
     
    8601168            }
    8611169
    862             // fadeIn and return on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
     1170            // Fade in and returns on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
    8631171            if ( key === 27 || ( key === 87 && event.altKey && ( ( ! isMac && event.shiftKey ) || ( isMac && event.ctrlKey ) ) ) ) {
    8641172                fadeIn( event );
     
    8661174            }
    8671175
     1176            // Return if any of the following keys or combinations of keys is pressed.
    8681177            if ( event && ( event.metaKey || ( event.ctrlKey && ! event.altKey ) || ( event.altKey && event.shiftKey ) || ( key && (
    8691178                // Special keys ( tab, ctrl, alt, esc, arrow keys... )
     
    8931202
    8941203                $overlay
    895                     // Always recalculate the editor area entering the overlay with the mouse.
     1204                    // Always recalculate the editor area when entering the overlay with the mouse.
    8961205                    .on( 'mouseenter.focus', function() {
    8971206                        recalcEditorRect();
     
    9601269                        y = ny;
    9611270                    } )
    962                     // When the overlay is touched, always fade in and cancel the event.
     1271
     1272                    // When the overlay is touched, fade in and cancel the event.
    9631273                    .on( 'touchstart.focus', function( event ) {
    9641274                        event.preventDefault();
     
    9801290        }
    9811291
     1292        /**
     1293         * @summary Fades all elements back in.
     1294         *
     1295         * @since 4.1.0
     1296         *
     1297         * @param event The event that triggers this function.
     1298         *
     1299         * @returns {void}
     1300         */
    9821301        function fadeIn( event ) {
    9831302            if ( faded ) {
     
    10191338        }
    10201339
     1340        /**
     1341         * @summary Fades in if the focused element based on it position.
     1342         *
     1343         * @since 4.1.0
     1344         *
     1345         * @returns {void}
     1346         */
    10211347        function maybeFadeIn() {
    10221348            setTimeout( function() {
     
    10341360        }
    10351361
     1362        /**
     1363         * @summary Fades out the admin bar based on focus on the admin bar.
     1364         *
     1365         * @since 4.1.0
     1366         *
     1367         * @returns {void}
     1368         */
    10361369        function fadeOutAdminBar() {
    10371370            if ( ! fadedAdminBar && faded ) {
     
    10481381        }
    10491382
     1383        /**
     1384         * @summary Fades in the admin bar.
     1385         *
     1386         * @since 4.1.0
     1387         *
     1388         * @returns {void}
     1389         */
    10501390        function fadeInAdminBar() {
    10511391            if ( fadedAdminBar ) {
     
    10561396        }
    10571397
     1398        /**
     1399         * @summary Fades out the edit slug box.
     1400         *
     1401         * @since 4.1.0
     1402         *
     1403         * @returns {void}
     1404         */
    10581405        function fadeOutSlug() {
    10591406            if ( ! fadedSlug && faded && ! $slug.find( ':focus').length ) {
     
    10661413        }
    10671414
     1415        /**
     1416         * @summary Fades in the edit slug box.
     1417         *
     1418         * @since 4.1.0
     1419         *
     1420         * @returns {void}
     1421         */
    10681422        function fadeInSlug() {
    10691423            if ( fadedSlug ) {
     
    10761430        }
    10771431
     1432        /**
     1433         * @summary Triggers the toggle on Alt + Shift + W.
     1434         *
     1435         * Keycode 87 = w.
     1436         *
     1437         * @since 4.1.0
     1438         *
     1439         * @param {event} event The event to trigger the toggle.
     1440         *
     1441         * @returns {void}
     1442         */
    10781443        function toggleViaKeyboard( event ) {
    10791444            if ( event.altKey && event.shiftKey && 87 === event.keyCode ) {
     
    10861451        }
    10871452
     1453        /**
     1454         * @summary Adds the distraction free writing button when setting up TinyMCE.
     1455         *
     1456         * @since 4.1.0
     1457         *
     1458         * @param {event} event The TinyMCE editor setup event.
     1459         * @param {object} editor The editor to add the button to.
     1460         *
     1461         * @returns {void}
     1462         */
    10881463        $document.on( 'tinymce-editor-setup.focus', function( event, editor ) {
    10891464            editor.addButton( 'dfw', {
     
    11171492        } );
    11181493
     1494        /**
     1495         * @summary Binds and unbinds events on the editor.
     1496         *
     1497         * @since 4.1.0
     1498         *
     1499         * @param {event} event The TinyMCE editor init event.
     1500         * @param {object} editor The editor to bind events on.
     1501         *
     1502         * @returns {void}
     1503         */
    11191504        $document.on( 'tinymce-editor-init.focus', function( event, editor ) {
    11201505            var mceBind, mceUnbind;
     
    11521537                }
    11531538
     1539                // Bind and unbind based on the distraction free writing focus.
    11541540                $document.on( 'dfw-on.focus', mceBind ).on( 'dfw-off.focus', mceUnbind );
    11551541
    1156                 // Make sure the body focuses when clicking outside it.
     1542                // Focuse the editor when it is the target of the click event.
    11571543                editor.on( 'click', function( event ) {
    11581544                    if ( event.target === editor.getDoc().documentElement ) {
     
    11631549        } );
    11641550
     1551        /**
     1552         * @summary  Binds events on quicktags init.
     1553         *
     1554         * @since 4.1.0
     1555         *
     1556         * @param {event} event The quicktags init event.
     1557         * @param {object} editor The editor to bind events on.
     1558         *
     1559         * @returns {void}
     1560         */
    11651561        $document.on( 'quicktags-init', function( event, editor ) {
    11661562            var $button;
    11671563
     1564            // Bind the distraction free writing events if the distraction free writing button is available.
    11681565            if ( editor.settings.buttons && ( ',' + editor.settings.buttons + ',' ).indexOf( ',dfw,' ) !== -1 ) {
    11691566                $button = $( '#' + editor.name + '_dfw' );
Note: See TracChangeset for help on using the changeset viewer.