|
| 1 | +""" |
| 2 | +Usage information for QtConsole |
| 3 | +""" |
| 4 | + |
| 5 | +# Copyright (c) Jupyter Development Team. |
| 6 | +# Distributed under the terms of the Modified BSD License. |
| 7 | + |
| 8 | + |
| 9 | +gui_reference = """\ |
| 10 | +===================== |
| 11 | +The Jupyter QtConsole |
| 12 | +===================== |
| 13 | +
|
| 14 | +This console is designed to emulate the look, feel and workflow of a terminal |
| 15 | +environment. Beyond this basic design, the console also implements |
| 16 | +functionality not currently found in most terminal emulators. Some examples of |
| 17 | +these console enhancements are inline syntax highlighting, multiline editing, |
| 18 | +inline graphics, and others. |
| 19 | +
|
| 20 | +This quick reference document contains the basic information you'll need to |
| 21 | +know to make the most efficient use of it. For the various command line |
| 22 | +options available at startup, type ``jupyter qtconsole --help`` at the command |
| 23 | +line. |
| 24 | +
|
| 25 | +
|
| 26 | +Multiline editing |
| 27 | +================= |
| 28 | +
|
| 29 | +The graphical console is capable of true multiline editing, but it also tries |
| 30 | +to behave intuitively like a terminal when possible. If you are used to |
| 31 | +IPython's old terminal behavior, you should find the transition painless. If |
| 32 | +you learn to use a few basic keybindings, the console provides even greater |
| 33 | +efficiency. |
| 34 | +
|
| 35 | +For single expressions or indented blocks, the console behaves almost like the |
| 36 | +IPython terminal: single expressions are immediately evaluated, and indented |
| 37 | +blocks are evaluated once a single blank line is entered:: |
| 38 | +
|
| 39 | + In [1]: print ("Hello Jupyter!") # Enter was pressed at the end of the line |
| 40 | + Hello Jupyter! |
| 41 | +
|
| 42 | + In [2]: for num in range(10): |
| 43 | + ...: print(num) |
| 44 | + ...: |
| 45 | + 0 1 2 3 4 5 6 7 8 9 |
| 46 | +
|
| 47 | +If you want to enter more than one expression in a single input block |
| 48 | +(something not possible in the terminal), you can use ``Control-Enter`` at the |
| 49 | +end of your first line instead of ``Enter``. At that point the console goes |
| 50 | +into 'cell mode' and even if your inputs are not indented, it will continue |
| 51 | +accepting lines until either you enter an extra blank line or |
| 52 | +you hit ``Shift-Enter`` (the key binding that forces execution). When a |
| 53 | +multiline cell is entered, the console analyzes it and executes its code producing |
| 54 | +an ``Out[n]`` prompt only for the last expression in it, while the rest of the |
| 55 | +cell is executed as if it was a script. An example should clarify this:: |
| 56 | +
|
| 57 | + In [3]: x=1 # Hit Ctrl-Enter here |
| 58 | + ...: y=2 # from now on, regular Enter is sufficient |
| 59 | + ...: z=3 |
| 60 | + ...: x**2 # This does *not* produce an Out[] value |
| 61 | + ...: x+y+z # Only the last expression does |
| 62 | + ...: |
| 63 | + Out[3]: 6 |
| 64 | +
|
| 65 | +The behavior where an extra blank line forces execution is only active if you |
| 66 | +are actually typing at the keyboard each line, and is meant to make it mimic |
| 67 | +the IPython terminal behavior. If you paste a long chunk of input (for example |
| 68 | +a long script copied form an editor or web browser), it can contain arbitrarily |
| 69 | +many intermediate blank lines and they won't cause any problems. As always, |
| 70 | +you can then make it execute by appending a blank line *at the end* or hitting |
| 71 | +``Shift-Enter`` anywhere within the cell. |
| 72 | +
|
| 73 | +With the up arrow key, you can retrieve previous blocks of input that contain |
| 74 | +multiple lines. You can move inside of a multiline cell like you would in any |
| 75 | +text editor. When you want it executed, the simplest thing to do is to hit the |
| 76 | +force execution key, ``Shift-Enter`` (though you can also navigate to the end |
| 77 | +and append a blank line by using ``Enter`` twice). |
| 78 | +
|
| 79 | +If you are editing a multiline cell and accidentally navigate out of it using the |
| 80 | +up or down arrow keys, the console clears the cell and replaces it with the |
| 81 | +contents of the cell which the up or down arrow key stopped on. If you wish to |
| 82 | +to undo this action, perhaps because of an accidental keypress, use the Undo |
| 83 | +keybinding, ``Control-z``, to restore the original cell. |
| 84 | +
|
| 85 | +
|
| 86 | +Key bindings |
| 87 | +============ |
| 88 | +
|
| 89 | +The Jupyter QtConsole supports most of the basic Emacs line-oriented keybindings, |
| 90 | +in addition to some of its own. |
| 91 | +
|
| 92 | +The keybindings themselves are: |
| 93 | +
|
| 94 | +- ``Enter``: insert new line (may cause execution, see above). |
| 95 | +- ``Ctrl-Enter``: *force* new line, *never* causes execution. |
| 96 | +- ``Shift-Enter``: *force* execution regardless of where cursor is, no newline added. |
| 97 | +- ``Up``: step backwards through the history. |
| 98 | +- ``Down``: step forwards through the history. |
| 99 | +- ``Shift-Up``: search backwards through the history (like ``Control-r`` in bash). |
| 100 | +- ``Shift-Down``: search forwards through the history. |
| 101 | +- ``Control-c``: copy highlighted text to clipboard (prompts are automatically stripped). |
| 102 | +- ``Control-Shift-c``: copy highlighted text to clipboard (prompts are not stripped). |
| 103 | +- ``Control-v``: paste text from clipboard. |
| 104 | +- ``Control-z``: undo (retrieves lost text if you move out of a cell with the arrows). |
| 105 | +- ``Control-Shift-z``: redo. |
| 106 | +- ``Control-o``: move to 'other' area, between pager and terminal. |
| 107 | +- ``Control-l``: clear terminal. |
| 108 | +- ``Control-a``: go to beginning of line. |
| 109 | +- ``Control-e``: go to end of line. |
| 110 | +- ``Control-u``: kill from cursor to the begining of the line. |
| 111 | +- ``Control-k``: kill from cursor to the end of the line. |
| 112 | +- ``Control-y``: yank (paste) |
| 113 | +- ``Control-p``: previous line (like up arrow) |
| 114 | +- ``Control-n``: next line (like down arrow) |
| 115 | +- ``Control-f``: forward (like right arrow) |
| 116 | +- ``Control-b``: back (like left arrow) |
| 117 | +- ``Control-d``: delete next character, or exits if input is empty |
| 118 | +- ``Alt-<``: move to the beginning of the input region. |
| 119 | +- ``alt->``: move to the end of the input region. |
| 120 | +- ``Alt-d``: delete next word. |
| 121 | +- ``Alt-Backspace``: delete previous word. |
| 122 | +- ``Control-.``: force a kernel restart (a confirmation dialog appears). |
| 123 | +- ``Control-+``: increase font size. |
| 124 | +- ``Control--``: decrease font size. |
| 125 | +- ``Control-Alt-Space``: toggle full screen. (Command-Control-Space on Mac OS X) |
| 126 | +
|
| 127 | +The pager |
| 128 | +========= |
| 129 | +
|
| 130 | +The Jupyter QtConsole will show long blocks of text from many sources using a |
| 131 | +built-in pager. You can control where this pager appears with the ``--paging`` |
| 132 | +command-line flag: |
| 133 | +
|
| 134 | +- ``inside`` [default]: the pager is overlaid on top of the main terminal. You |
| 135 | + must quit the pager to get back to the terminal (similar to how a pager such |
| 136 | + as ``less`` or ``more`` pagers behave). |
| 137 | +
|
| 138 | +- ``vsplit``: the console is made double height, and the pager appears on the |
| 139 | + bottom area when needed. You can view its contents while using the terminal. |
| 140 | +
|
| 141 | +- ``hsplit``: the console is made double width, and the pager appears on the |
| 142 | + right area when needed. You can view its contents while using the terminal. |
| 143 | +
|
| 144 | +- ``none``: the console displays output without paging. |
| 145 | +
|
| 146 | +If you use the vertical or horizontal paging modes, you can navigate between |
| 147 | +terminal and pager as follows: |
| 148 | +
|
| 149 | +- Tab key: goes from pager to terminal (but not the other way around). |
| 150 | +- Control-o: goes from one to another always. |
| 151 | +- Mouse: click on either. |
| 152 | +
|
| 153 | +In all cases, the ``q`` or ``Escape`` keys quit the pager (when used with the |
| 154 | +focus on the pager area). |
| 155 | +
|
| 156 | +Running subprocesses |
| 157 | +==================== |
| 158 | +
|
| 159 | +When running a subprocess from the kernel, you can not interact with it as if |
| 160 | +it was running in a terminal. So anything that invokes a pager or expects |
| 161 | +you to type input into it will block and hang (you can kill it with ``Control-C``). |
| 162 | +
|
| 163 | +The console can use magics provided by the IPython kernel. These magics include |
| 164 | +``%less`` to page files (aliased to ``%more``), |
| 165 | +``%clear`` to clear the terminal, and ``%man`` on Linux/OSX. These cover the |
| 166 | +most common commands you'd want to call in your subshell and that would cause |
| 167 | +problems if invoked via ``!cmd``, but you need to be aware of this limitation. |
| 168 | +
|
| 169 | +Display |
| 170 | +======= |
| 171 | +
|
| 172 | +For example, if using the IPython kernel, there are functions available for |
| 173 | +object display: |
| 174 | +
|
| 175 | +
|
| 176 | + In [4]: from IPython.display import display |
| 177 | +
|
| 178 | + In [5]: from IPython.display import display_png, display_svg |
| 179 | +
|
| 180 | +Python objects can simply be passed to these functions and the appropriate |
| 181 | +representations will be displayed in the console as long as the objects know |
| 182 | +how to compute those representations. The easiest way of teaching objects how |
| 183 | +to format themselves in various representations is to define special methods |
| 184 | +such as: ``_repr_svg_`` and ``_repr_png_``. IPython's display formatters |
| 185 | +can also be given custom formatter functions for various types:: |
| 186 | +
|
| 187 | + In [6]: ip = get_ipython() |
| 188 | +
|
| 189 | + In [7]: png_formatter = ip.display_formatter.formatters['image/png'] |
| 190 | +
|
| 191 | + In [8]: png_formatter.for_type(Foo, foo_to_png) |
| 192 | +
|
| 193 | +For further details, see ``IPython.core.formatters``. |
| 194 | +""" |
0 commit comments