Metadata-Version: 1.0
Name: django-keyboard-shortcuts
Version: 0.0.7
Summary: Helps to use the keyboard inside your web project.
Home-page: https://bitbucket.org/DNX/django-keyboard-shorcuts/
Author: Denis Darii
Author-email: denis.darii@gmail.com
License: BSD License
Description: 
        =========================
        Django-keyboard-shortcuts
        =========================
        
        **Helps to use the keyboard inside your web project**
        
        The project code and bugtracker is hosted on
        `Bitbucket <https://bitbucket.org/DNX/django-keyboard-shorcuts/>`_ and `Github <https://github.com/DNX/django-keyboard-shorcuts/>`_.
        
        Don't uses any javascript framework!
        ------------------------------------
        
        On the client side you will have only pure javascript code that receives all pre-elaborated and optimized data directly from django.
        
        The only dependency is Django itself
        ------------------------------------
        Just **install**, **configure**, and you are ready to **dominate the world** with your website keyboard shortcuts.
        
        ============
        Installation
        ============
        
        There are a few different ways to install keyboard_shortcus:
        
        Using pip
        ---------
        If you have pip install available on your system, just type::
        
            pip install django-keyboard-shortcuts
        
        If you've already got an old version of keyboard_shortcus, and want to upgrade, use::
        
            pip install -U django-keyboard-shortcuts
        
        Installing from a directory
        ---------------------------
        If you've obtained a copy of keyboard_shortcus using either Mercurial or a downloadable
        archive, you'll need to install the copy you have system-wide. Try running::
        
            python setup.py develop
        
        If that fails, you don't have ``setuptools`` or an equivalent installed;
        either install them, or run::
        
            python setup.py install
        
        
        ==============================
        How to use keyboard_shortcuts?
        ==============================
        
        If you have already installed keyboard_shortcus, you must proceed with the
        configuration of your project.
        
        Configuration
        -------------
        very simple, in three steps:
        
        #. Add **keyboard_shortcuts** To INSTALLED_APPS
        
        #. Modify Your settings.py, declare your **HOTKEYS** settings.
        
        #. Add **{% load hotkeys %}{% setup_hotkeys %}** in your template.
        
        Below the long explanation of each step...
        
        Add keyboard_shortcuts To INSTALLED_APPS
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        As with most Django applications, you should add **keyboard_shortcuts** to the INSTALLED_APPS within your settings file (usually *settings.py*).
        
        Example::
        
            INSTALLED_APPS = [
                'django.contrib.admin',
                'django.contrib.auth',
                'django.contrib.contenttypes',
                'django.contrib.sessions',
                'django.contrib.sites',
        
                # Added.
                'keyboard_shortcuts',
            ]
        
        Modify Your settings.py
        ^^^^^^^^^^^^^^^^^^^^^^^
        
        Within your *settings.py*, you’ll need to add some settings in order to assign to desired keyboard shortcuts some actions and to personalize the **django-keyboard-shortcuts** behaviour for your project.
        
        You can define:
        
        - **HOTKEYS** - a list containing the desired keyboard combinations and some settings for each (*default:* **list()**)
        - **SPECIAL_DISABLED** - a bool, to disable shortcuts in some "**special cases**", when an input, a textarea or a select is active (*default:* **True**)
        
        Example::
        
            # START keyboard_shortcuts settings #
            HOTKEYS = [
                        {'keys': 'g + h',  # go home
                        'link': '/'},
                    ]
            SPECIAL_DISABLED = True
            # END keyboard_shortcuts settings #
        
        More about HOTKEYS setting?
        """""""""""""""""""""""""""
        
        HOTKEYS is a list of dictioanaries. Each dictionary contains the attributes for a particular keyboard combination. HOTKEYS dist must have a key called "**keys**" and one of "**link**" or "**js**".
        
        Examples of "**keys**" value:
        
        - "CTRL + R"
        
        - "Z + R + P"
        
        - "3 (NUMPAD)"
        
        - "CTRL + \*"
        
        - "="
        
        Examples of "**link**" value:
        
        - "/about/"
        
        - "http://google.com"
        
        Examples of "**js**" value:
        
        - "alert('HELLO!');"
        
        if for a keyboard combination we have both "**link**" and "**js**" declared, only "**link**" will be condidered.
        
        Another advanced examples for **HOTKEYS** list::
        
            HOTKEYS = [
                        {'keys': 'ctrl+h',  # home
                        'link': '/',
                        },
                        {'keys': 'alt+w',
                        'link': '/workspace/',
                        },
                        {'keys': 'shift+j',
                        'js': 'js_function();', # javascript code here
                        },
                        {'keys': 'a+j',
                        'js': 'alert(\'A+J Pressed!\');', # javascript code here
                        },
                        {'keys': '1+2+3',
                        'link': '/secret-url/',
                        },
                    ]
        
        Available keys for your combinations:
        
        - BACKSPACE
        - TAB
        - ENTER
        - SHIFT
        - CTRL
        - ALT
        - PAUSE
        - CAPSLOCK
        - ESC
        - PAGE UP
        - PAGE DOWN
        - END
        - HOME
        - LEFT ARROW
        - UP ARROW
        - RIGHT ARROW
        - DOWN ARROW
        - INSERT
        - DELETE
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - A
        - B
        - C
        - D
        - E
        - F
        - G
        - H
        - I
        - J
        - K
        - L
        - M
        - N
        - O
        - P
        - Q
        - R
        - S
        - T
        - U
        - V
        - W
        - X
        - Y
        - Z
        - 0 (NUMPAD)
        - 1 (NUMPAD)
        - 2 (NUMPAD)
        - 3 (NUMPAD)
        - 4 (NUMPAD)
        - 5 (NUMPAD)
        - 6 (NUMPAD)
        - 7 (NUMPAD)
        - 8 (NUMPAD)
        - 9 (NUMPAD)
        - \*
        - \+
        - \-
        - .
        - /
        - F1
        - F2
        - F3
        - F4
        - F5
        - F6
        - F7
        - F8
        - F9
        - F10
        - F11
        - F12
        - NUMLOCK
        - SCROLL
        - =
        - COMMA
        - SLASH /
        - BACKSLASH \\
        - META
        
        Setup Hotkeys In Your Template
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Now all you need to do is to add **{% load hotkeys %}** and **{% setup_hotkeys %}** in yout template, and *django-keyboard-shortcuts* will do the rest for you... add event listeners and attend for any keypress.
        
        The easiest way to do this is to load hotkeys **{% load hotkeys %}** at the **top** of your "base" template and to setup **{% setup_hotkeys %}** the in your **<head>** section.
        
        Example of "base.html" template::
        
            {% load hotkeys %}
            <html>
                <head>
                    <title>My title</title>
                    {% setup_hotkeys %}
                </head>
                <body>
                    my content...
                </body>
            </html>
        
        ==============================
        How to test keyboard_shortcus?
        ==============================
        
        Very simple::
        
            $ ./manage.py test keyboard_shortcus
        
        
        ==========================
        Do you need some examples?
        ==========================
        
        Further a list of the most useful keyboard shortcuts of our favorite web services.
        So, if you need a suggestion about which key combination use on your site,
        this is where you find it:
        
        Gmail
        -----
        
            **c** – compose a new mail
        
            **/** – puts your cursor in the search box
        
            **k** – move to newer conversation
        
            **j** – Move to older conversation
        
            **n** – next message
        
            **p** – previous message
        
            **o or Enter** – open a conversation
        
            **u** – return to conversation list
        
            **y** – archive a conversation
        
            **m** – mute (archive and make all future messages from this conversation
            skip the inbox)
            **x** – select conversation
        
            **s** – star a message or conversation
        
            **!** – report spam
        
            **r** – reply to a mail
        
            **a** – reply to all recepients
        
            **f** – forward message
        
            **Esc** – escape from input field
        
            **ctrl+s** – save draft
        
        
        key combos
        ^^^^^^^^^^
        
            **tab then Enter** – send message
        
            **y then o** – archive your conversation and move to the next one.
        
            **g then a** – go to all mail
        
            **g then s** – go to starred conversations
        
            **g then c** – go to contacts list.
        
            **g then d** – go to drafts
        
            **g then i** – go to inbox
        
        Google Reader
        -------------
        
            **j/k** – selects the next/previous item in the list
        
            **space/shift-space** – moves the page down/up
        
            **n/p** – in list view, selects the next item without opening it
        
            **o** – in list view, expands or collapses the selected item
        
            **enter** – in list view, expands or collapses the selected item
        
            **s** – stars the selected item
        
            **shift-s** – shares the selected item
        
            **m** – switches the read state of the selected item
        
            **t** – opens the tagging field for the selected item
        
            **v** – opens the original source for this article in a new window
        
            **shift-a** – marks all items in the current view as read
        
            **1** – displays the subscription as expanded items
        
            **2** – displays the subscription as a list of headlines
        
            **r** – refreshes the unread counts in the navigation
        
            **shift-n/p** – selects the next/previous subscription or folder in the
            navigation
        
            **shift-x** – expand or collapse a folder selected in the navigation
        
            **shift-o** – opens the item currently selected in the navigation
        
            **gh** – goes to the Google Reader homepage
        
            **ga** – goes to the “All items” view
        
            **gs** – goes to the “Starred items” view
        
            **gt** – allows you to navigate to a tag by entering the tag name
        
            **gu** – allows you to navigate to a subscription by entering the
            subscription name
        
            **u** – hides and shows the list of subscriptions
        
            **?** – displays a quick guide to all of Reader’s shortcuts
        
        Wikipedia
        ---------
        
            **+** – add a new section (talk pages only)
        
            **.** – opens your user page if logged in
        
            **=** – protect/unprotect the current page (sysops only)
        
            **c** – shows the content page associated with the current article
        
            **d** – delete/undelete the current page (sysops only)
        
            **e** – edit this page/show source of current page
        
            **f** – search Wikipedia
        
            **h** – current page’s history
        
            **j** – shows all of the pages that link to the current one
        
            **k** – shows recent changes in pages linked to the current one
        
            **l** – opens your watchlist (logged – in users only)
        
            **m** – move the current page and its talk page (non – move – protected pages only)
        
            **n** – opens your user’s or IP’s talk page
        
            **p** – shows a preview of your changes (on edit pages)
        
            **q** – shows a list of all special pages
        
            **r** – shows a list of recent changes to the Wikipedia
        
            **s** – saves the changes that you have made (on edit pages)
        
            **t** – opens the current article’s talk page
        
            **u** – allows you to upload images or media files
        
            **v** – shows what changes you made to the text (on edit pages)
        
            **w** – adds the current page to your watchlist (logged – in users only)
        
            **x** – loads a random article
        
            **y** – opens a list of your user’s or IP’s contributions
        
            **z** – goes to the Main Page
        
        
        Yahoo! Mail
        -----------
        
            **m** – check mail
        
            **Shift+m** – check all mail
        
            **Ctrl+** – close current tab
        
            **n** – new message
        
            **Shift+n** – new message in its own window
        
            **r** – reply
        
            **Shift+r** – reply in a new window
        
            **a** – reply all
        
            **Shift+a** – reply all in a new window
        
            **f** – forward message
        
            **Shift+f** – forward in a new window
        
            **k** – mark as read
        
            **Shift+k** – mark as unread
        
            **l** – flag
        
            **Shift+l** – clear flag
        
            **del** – delete item
        
            **p/Ctrl+p** – print
        
            **Ctrl+s** – save draft
        
            **Ctrl+Enter** – send message
        
            **v** – turn reading pane on/off
        
            **Ctrl+[** – navigate through tabs
        
            **Ctrl+]** – navigate through tabs
        
            **Enter** – open message in its own tab (when message is selected)
        
            **Enter** – edit contact info (when contact is selected)
        
            **Ctrl+f** – find a word or phrase in message
        
            **F11** – expand window to max height
        
            **Ctrl+.** – next message (in message tab)
        
            **Ctrl+,** – previous message (in message tab)
        
            **Ctrl+Alt+Shift+up arrow/down arrow** – next/previous message
        
            **Ctrl+Shift+End** – skip to oldest unread message
        
            **d** – move message to folder
        
            **Esc** – close read** – message tab
        
            **Ctrl+Shift+End** – start a new chat
        
        
        =======
        Credits
        =======
        
        Special thanks to the authors of this resources:
        
        http://www.w3.org/2002/09/tests/keys.html
        
        http://www.quirksmode.org/js/keys.html#t00
        
        http://unixpapa.com/js/key.html
        
        http://www.openjs.com/scripts/events/keyboard_shortcuts/
        
        https://github.com/jeresig/jquery.hotkeys/
        
        http://mashable.com/2007/06/29/keyboard-shortcuts/
        
        
        =========
        Changelog
        =========
        
        0.0.7
        -----
        
        * added support for "js" action for your shortcuts
        * covered with tests the new functionality
        * improved documentation
        
        0.0.6
        -----
        
        * you can now configure in your settings.py the behaviour in "special cases"
        * updated the documentation
        * improved tests
        
        0.0.5
        -----
        
        * disabled hotkeys in selet and text type inputs
        
        0.0.4
        -----
        
        * now you can add multiple key combinations
        * improved tests
        * updated the documentation
        
        0.0.3
        -----
        
        * included "keyboard_shortcuts/templates \*" in MANIFEST.in
        * documentation updated
        * templatetags and utils are now tested
        
        0.0.2
        -----
        
        * added hotkeys templatetag
        * added an example project for testing purposes
        
        0.0.1
        -----
        
        * initial structure
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
