docs: add doc for menu basics, how to customize

docs/index.rst

@@ -12,6 +12,7 @@ WuttaPOS is a `Python`_ point of sale app based on `Rattail`_.
    :caption: Contents:
 
    quickstart
+   menus
 
 
 Indices and tables

docs/menus.rst

@@ -0,0 +1,102 @@
+
+=====
+Menus
+=====
+
+The default POS screen uses a "master menu" control to draw all button
+menus on the right half of the screen.
+
+This area is further broken down into 4 quadrants, each of which is
+managed by a "menu" control.  These quadrants are:
+
+* ``tenkey`` (top left)
+* ``meta`` (top right)
+* ``context`` (bottom left)
+* ``suspend`` (bottom right)
+
+.. warning::
+
+   These names will likely change, as well as (possibly) the overall
+   structure.  Things are being documented as-is for now.
+
+
+Custom Menus
+------------
+
+You may override any of the above quadrant menu controls by specifying
+your preferred control in your config file.
+
+Most typically you would override the ``context`` menu:
+
+.. code-block:: ini
+
+   [wuttapos.menus]
+   context.spec = poser.menus.context:PoserContextMenu
+
+Of course that is after you have defined ``PoserContextMenu`` which
+should be a subclass of :class:`wuttapos.controls.menus.WuttaMenu`.
+
+
+Dynamic Context Menu
+--------------------
+
+The default ``context`` menu is actually empty; all the more reason
+you would want to override it as described in the previous section.
+
+But this quadrant is special in that the POS expects that menu to be
+"swapped out" dynamically based on user action.
+
+The way this works is to invoke the POS command named ``context_menu``
+and specify the "key" of the menu you wish to show.  This is generally
+wired up to a button, so clicking the button would show a certain
+menu::
+
+   from wuttapos.controls.menus import WuttaMenu
+
+   class PoserContextMenu(WuttaMenu):
+
+       def build_controls(self):
+           return [
+
+               self.make_button_row([
+
+                   self.make_button("SHOW STUFF",
+                                    bgcolor='yellow',
+                                    pos_cmd='context_menu',
+                                    pos_cmd_entry='stuff'),
+               ]),
+           ]
+
+The above would show a menu whose key was ``stuff`` - so your config
+must define the spec for this menu as well:
+
+.. code-block:: ini
+
+   [wuttapos.menus]
+   stuff.spec = poser.menus.stuff:PoserStuffMenu
+
+And that menu is conceptually no different than the ``context``
+example above.  It can show whichever buttons it needs, and it is
+usually a good idea for some button(s) to load other menus.  For
+example this (``stuff`` menu) includes a "BACK" button to load the
+original ``context`` menu::
+
+   from wuttapos.controls.menus import WuttaMenu
+
+   class PoserStuffMenu(WuttaMenu):
+
+       def build_controls(self):
+           return [
+
+               self.make_button_row([
+
+                   self.make_button("VOID",
+                                    bgcolor='red',
+                                    pos_cmd='void_dwim'),
+
+                   self.make_button("BACK",
+                                    bgcolor='yellow',
+                                    pos_cmd='context_menu',
+                                    pos_cmd_entry='context'),
+               ]),
+           ]