BSE Categories
==============

The purpose of BSE Categories is to provide a mapping of functionality
provided by BSE and its plugins to GUI frontends. Categories are used to
provide a hirarchical structure, to group certain services and to aid
the user in finding required functionality.

Object Categories
-----------------

BSE objects and procedures are "categorized" to easily integrate them
into menu or similar operation structures in GUIs.

Objects that are derived from the BseSource class with the main intend
to be used as synthesis modules in a synthesis network are categorized
under the "/Modules/" toplevel category, ordered by operational
categories.

Core Procedures
---------------

Procedures provided by the BSE core are categorized under a
subcategory of the "/Methods/" toplevel category.
The object type a procedure operates on is appended to
the toplevel category to form a category name starting with
"/Methods/<ObjectType>/".
Procedures implementing object methods need to take the
object as first argument and follow a special naming convention
(for the procedure name). To construct the procedure type name,
the object type and method named are concatenated to form
"<ObjectType>+<MethodName>". This ensure proper namespacing
of method names to avoid clashes with equally named methods
of distinct object types.
Some special internal procedures may also be entered under
the "/Proc/" toplevel category.

Utility Procedures
------------------

Procedures implementing utility functionality, usually implemented
as scripts, are entered into one of the below listed categories.
Depending on the category, some procedure arguments are automatically
provided by the GUI, the name and type of automatic arguments are
listed with the category in the following table:

Category		Automatic arguments as (name:type) pairs
------------------------------------------------------------------------------
/Project/		project:BseProject
/SNet/			snet:BseSNet
/Song/			song:BseSong
/Part/			part:BsePart
/CSynth/		csynth:BseCSynth
/WaveRepo/		wave_repo:BseWaveRepo
/Wave/			wave:BseWave

The set of automatic arguments provided upon invocation is not restricted
by te above lists, so caution should be taken when naming multiple arguments
to a procedure auto_*.

Aliasing/Mapping
----------------

A certain BSE type (procedure or object) may be entered under several
categories simultaneously, thus allowing multiple categories to
refer (alias) to the same type (functionality).


Examples
--------

Category			TypeName		Comment
------------------------------------------------------------------------------
/Methods/BseProject/File/Store	BseProject+store-bse	BseProject procedure
/Modules/Spatial/Balance	BseBalance		synthesis module
/SNet Utility/Utils/Grid Align	modules2grid		scheme script
