Shell ===== Overview ^^^^^^^^ Let's start with some terminology and basic plumbing. * A **shell** is a running process that accepts multiple user commands until explicitly exited. * A shell is made up of one or more **screens**. * Each screen has its own **menu**. * The menu is used to let the user make the shell do something. * A user inputs a menu item's **trigger** to invoke the code tied to that item. * The shell framework provides hooks to navigate from screen to screen and render the menu. Getting Started ^^^^^^^^^^^^^^^ The first step is to create the ``Shell`` instance itself. It won't do much until we populate it, but it has a number of framework methods we'll want access to for the menu items. The defaults should be sufficient in many cases, however the ability to pass in a specific ``Prompt`` instance is available as well. The bulk of the shell is in the screens. Each screen can be thought of as similar to a web page. The screen's menu is used to do things, such as functionality or transitioning to another screen. The common usage is to subclass the ``Screen`` class for each particular screen, but that's not a hard requirement. The main goal in creating a screen is to add the appropriate menu items for that screen using the ``add_menu_item`` method. Menu items are instances of the ``MenuItem`` class and effectively pair the following pieces: * The trigger used to invoke the item (e.g. 'q' for quit). Multiple triggers may be passed as a list and there are no restrictions on the length of a trigger. * The item description to show to the user when rendering the menu. * The function to invoke when the item is selected by the user. There are some other things to tweak in a menu item, but those are the basics and good enough for now. Keep in mind the ``Shell`` instance has a number of navigational methods that a screen's menu may want to use. For instance, if a screen should provide the ability to move to another screen, the shell's ``transition`` method would be passed to the menu item as its function. Once the screens are created, they are added to the shell instance. One screen must be designated as the *home* screen. The home screen is the first screen displayed to the user. Additionally, the shell has built in menu functions for navigating directly back to the home screen. The first screen added to the shell will be designated as the home screen, however this can later be changed by specifying ``is_home=True`` when adding a different screen. Once the shell instance is configured, it begins the input loop through the ``start`` method. The loop will continue to run and accept user input until the ``stop`` method on the shell instance is called. Alternatively, the ``safe_start`` method can be used to begin the shell. The difference between the two is that the latter will restart the input loop in the event an exception occurs (the one caveat is that a SystemExit exception will still cause the loop to be interrupted. A sample shell can be found in the samples section of the source code or at: ``_