Module Tools
============

|Haver| provides three UI tools to deal directly with modules.
Additionally the browsers have been enhanced to select
a current module for various purposes.

Both tools can be opened by using the (enhanced)
:guilabel:`Open` menu -- select
:menuselection:`World → Open`:

.. figure:: Open.jpeg
   :alt: An Image of Haver's Open menu.

   |Havers| Open menu.

   
The Modules Browser
-------------------

.. figure:: ModulesBrowser.jpeg
   :target: http://haver.klix.ch/_static/ModulesBrowser1.mp4
   :alt: Image of the modules browser

   The Module Browser (Video)

The modules browser on can create, rename, remove and browse modules.
All the actions can either be performed with the usual pop-up menu
or with the buttons at the top of the window.

.. note:: If the module name is highlighted with yellow
          the module has no package it can be stored in.
          In this case you can either define a package
          with same name as the module or assign a
          package name with :guilabel:`Package ...` button.
          This `video`_ shows how it's done.

The hierarchical list contains all modules defined in the image
at the first level. The second level shows all the objects
bound to names local to the module.

The :guilabel:`Inspect It ...` and the :guilabel:`Explore it ...`
open an Inspector or an Explorer on the selected item:

When a module is selected the |BrowseIt| button opens
a Browser to change the module's exports and imports.

.. _video: _static/AttachPackageToModule.mp4


The Module Browser
------------------

As mentioned in before the module browser can be opened
by selecting a module in the modules browser and push
the |BrowseIt| button:

.. figure:: OpenModuleBrowser.jpeg
   :target: http://haver.klix.ch/_static/OpenModuleBrowser.mp4
   
   Opening the Module Browser (Video)

The following sketches the various actions the module browser can
perform:

.. figure:: DemoModule.png
   :scale: 150 %

   The Module Browser's Actions

A brief explanation of all the actions the module browser's actions
on interfaces and exported symbols follows suit:


  :guilabel:`Package ...`
    Set the package of the selected item as show in this `video`_.

  :guilabel:`New ...`
    Asks for a interface name and creates an interfaces
    with that name.

  :guilabel:`Remove ...`
    Removes the selected module from the collection
    of modules.

  :guilabel:`Rename ...`
    Asks for a new interface name and renames the interface.

  :guilabel:`Add ...`
    Displays a menu of symbols bound in the module
    and lets you chose one to export.
    The same effect can also be achieved by dragging a
    symbol bound in the module to interface item.

    .. figure:: AddExport.png
       :target: http://haver.klix.ch/_static/AddExport.mp4

       The :guilabel:`Add` action (Video)

  :guilabel:`Remove ...`
    Removes the selected symbols from the interface

  :guilabel:`Edit ...`
    Edits the name of the exported symbol.

The actions possible on import specifications are explained here:

  :guilabel:`Package ...`
    Set the package of the selected item.

  :guilabel:`New ...`
    Displays a menu of modules and the a menu of interfaces
    exported by the selected module. The same effect can be
    achieved by drag and drop.

    .. figure:: AddImport.png
       :target: http://haver.klix.ch/_static/AddImport.mp4

       Importing an interface (Video)

  :guilabel:`Remove ...`
    Removes the selected import from the collection
    of imports.

  Add an exported symbol
    An exported symbol can only be added by drag and drop [#]_.

    .. figure:: ImportSymbol.png
      :target: http://haver.klix.ch/_static/ImportSymbol.mp4

      Adding a specific symbol to an imported interface (Video)

  :guilabel:`Import all`
    This action removes all explicitly imported symbols
    and again imports all symbols the interface exports.

  :guilabel:`Exclude`
    This imports all symbols exported by the interface excluding
    those explicitly mentioned.

  :guilabel:`Edit ...`
    With this action you can rename an imported symbol.
      
  :guilabel:`Remove ...`
    Removes the selected symbol from the collection
    of imported symbols.

This video shows the effect of the aforementioned actions:

.. figure:: AdditionalImportActions.png
   :target: http://haver.klix.ch/_static/AdditionalImportActions.mp4

   Additional actions on imported symbols (Video)

   
The Default Module Browser
--------------------------

To make working with modules easier a browser that lets
one select a default module where classes are defined in
and global symbols are searched before they are looked up in
`Smalltalk`.

This video should explain the semantics of the default module
settings:

.. figure:: GlobalDefaultModuleBrowser.png
   :target: http://haver.klix.ch/_static/GlobalDefaultModuleBrowser.mp4

   A longer video explaining the Default Module Browser

The default module browser is especially helpful, when one wants
to file a non-module-aware package into a module.

.. figure:: Modularize.png
   :target: http://haver.klix.ch/_static/Modularize.mp4

   Convert the Spacewar! package into a Spacewar!-module
   and -package (Video).

Finally we can define `API` and `SPI` for the Spacewar! package:

.. figure:: ModularizeInterfaces.png
   :target: http://haver.klix.ch/_static/ModularizeInterfaces.mp4

   Define interfaces for the Spacewar! module (Video)
            
Modifications to Existing Tools
-------------------------------
The following tools were modified to make Smalltalk development
with modules easier.


System and Hierarchy Browser
............................

The System and the Hierarchy Browser windows were modified to
contain a local default module browser, with the same functionality
as the global default module browser.

If want to define Module named `Scratch` one can perform
the steps shown in the video below:

.. figure:: LocalDefaultModuleBrowser.png
   :target: http://haver.klix.ch/_static/LocalDefaultModuleBrowser.mp4
         
   Define a package, a category, a module
   and two classes in four simple steps.

            
Workspaces
..........

While objects -- especially classes -- bound in modules
can be accessed with the `>>`, the Workspace window
menu gained a modules sub menu.

.. figure:: WorkspaceModulesMenu.png
   :target: http://haver.klix.ch/_static/WorkspaceModulesMenu.mp4

   The Workspace Modules Menu (Video)

         
.. |BrowseIt| replace:: :guilabel:`Browse It ...`

.. [#] I wanted to avoid the three consecutive menus this
       would have needed. It's ugly to implement and unpleasant
       to operate.