====== Registry ======

The registry graph is used by GroIMP as registry for platform elements. Each project get its own registry that is a children of the Main registry. For the project, the registry stores how different resources are linked to the way GroIMP loads them — including which Java classes are used and with which parameters. 

===== Structure =====

The registry use the [[:01_user_documentation:06_graph:01_edge:01_successor|successor]] and [[:01_user_documentation:06_graph:01_edge:02_branch|branch]] edges for the structural informations between the nodes. Nodes of the registry are [[https://javadoc.grogra.de/platform.core/de/grogra/pf/registry/Item.html|items]]. In order to loop over all children of an Item, the edge loop over the first branch and then the successors:

<code java>
for (Item n = (Item) getBranch (); n != null; n = (Item) n.getSuccessor ()){
}
</code>

===== Plugin registry (TODO: refactor this section) =====


The platform is structured by the registry, which has a tree structure. All elements loaded by the platform have to be defined in the platform registry. Upon startup GroIMP load the platform registry based on all the ''plugin.xml'' files defined in the project repositories.

Hence, new items to the platform must be added in the ''plugin.xml'' files, in the ''<registry>'' section.
The platform registry consists of a tree of items. Each item has a name and can be referenced in a file system. The path for selecting an item is similar to a unix path (//i.e.// ''/ui/commands'').

==== Platform registry structure ====

The main directories in the registry are:

<code>
/
│    application/
│    attributes/  
│
└─── objects/  
│   │    graph/
│   │    R'files/
│   └─── R'datasets/  
│
│    cmdline/
│
└─── ui/
│   │    options
│   │    commands/
│   │    editors/
│   │    panels/
│   │    layouts/
│   └─── iconthemes/
│
│    export/
│    help/
│
└─── io/
│   │    filetypes/
│   │    mimetypes
│   └─── streamhandlers
│           
└─── hooks/
│   │    postboot/
│   │    startup/
│   │    shutdown/
│   └─── configure/
│       │    main/
│       │    │    workbench/
│       │    └─── classes/
│       │    
│       └─── project
│            │    objects/
│            └─── layouts/
│   │    
│   └─── complete/
│       └─── project/
│            └─── workbench/
│   │    
│   │    projectloaded
│   │    close
│   └─── rgg
│       │    finished/
│       └─── saving/
</code>

==== Main repositories ====

=== Application ===

On start GroIMP launch the method in the application repository. Currently ''de.grogra.imp.IMP.run''.

=== Attributes ===
The attributes repository contains the Attributes (classes derived from ''de.grogra.imp.objects.Attributes''), which are linked with the ui attributes items and persistence mechanism. 
GroIMP objects need to describe their attribute for them to be accessible in the GUI. (see [[:05_developer_tutorials:02_extending_groimp:creating-node-class|how to create nodes in groimp]]).

=== Objects ===

All objects are inserted in this repository.
The objects added to a project are usually added to one of its resources sub directories (files, images, objects, datasets, ...). Resource directories where associated object factories have been registered (FileFactory, FixedImageAdapter, ...).

It also where math, 2d and 3d objects are registered with their factories, so they can be created in a GroIMP project.

=== UI ===

This is where the ui components are registered, including Panels, ui commands, layouts. 

All panels should be registered in the ''/ui/panels'' directory before being added to the hooks (where they become accessible from menu entries) even if they are not accessible through the ''menu/src/panels'' entry. (see also [[:05_developer_tutorials:02_extending_groimp:create-windows|how to create windows and make them available in GroIMP]]).

=== IO ===

This is where the readable file types, mimetypes and streamholders are registered. 
New data, file or mime types, should be added to this repository. (see [[:01_user_documentation:03_interacting_with_groimp:14_io|how to add new mime, or file types]]).

=== Hooks ===

This is where the executables are registered. The startup , postboot, shutdown, and close hooks are run at the designated GroIMP event. 
Once elements have been defined in other repositories, they can be inserted in the hooks, so they are loaded at the designated GroIMP event (_e.g._ upon opening a new window).
For instance, the menu entries of the main window (the ones available from the default GroIMP window) are inserted in ''/hooks/configure/main/workbench/menu/src/''.

==== Registry tags ====

Each tag is see a node in the registry tree, and children nodes inherit their parents added tags. 

The complete list of predefined registry elements is found in _Platform-Core_ in the class ''de.grogra.pf.registry.Root'' (see [[:GroIMP-Platform:Complete-registry-tags-list|complete list of defined tags]]). 

=== Most used tags ===

The most used tags (defined in _Root_ and added in _Platform_) are:

  - ''<directory>''
  - ''<ref>''
  - ''<panel>''
  - ''<command>''
  - ''<mimetype>''
  - ''<ext>''
  - ''<object>''
  - ''<var>'' and ''<vars>''
  - ''<hook>''
  - ''<insert>''

=== Add a tag ===


By default the registry can only read tags predefined in //Root//, but it is possible to add some to a specific node in the registry tree. A node can uses all of its parents predefined tags. For instance, the registry node ''<registry>'' adds the tags ''<command>'', ''<group>'', ''<choicegroup>'', ''<checkboxitem>'', ''<separator>'', ''<dependency>'', and ''<selectable>'' when it is first called (in ''Platform/plugin.xml''). Then, within the ''<registry>'' tag (//i.e.// within the whole definition of the registry in ''plugin.xml'') it is possible to call on of these non predefined tags.

Tags are added as a key, value elements in a given node. Where the key is the tag name, and the value the associated java method which defined the effects of the tag. They are added in their parent node tag with the variable ''elements''. They are usually added in ''<directory>'', or ''<group>''. 

Example: 

<code xml>
<directory name="objects" elements="{{resdir,de.grogra.pf.ui.registry.ResourceDirectory},{factory,de.grogra.pf.ui.registry.ObjectItemFactory},...}">
</code>


=== Display or hide an object in GUI ===

Registry object added (prefered linked) under /hooks/configure/ ... are loaded and displayed when the main workbench (the main window) is created. i.e. when GroIMP is started. Most item in GroIMP are only displayed if they validate the condition //is available//. You can add a condition in the registry to an object to make it //available// if that condition is true. 

Currently there are two conditions used: <exists /> and <booleanvalueoption />. 

  - <exists name=".available" ref="aref"/> has two arguments: //name// and //ref//. //Name// should be //.available// in this case. //Ref// is the absolute path of an object in the registry. If that object exists, then the condition is true.
  - <booleanvalueoption name=".available" value="true" optPath="/path/to/option"/> has three arguments: //name//, //value//, and //optPath//. //Name// should be //.available//. //Value// is the default value returned by the condition (used if the option item is either not set or not found). //optPath// is the path in the registry to an Option object. This Option should be a boolean. If the Option is found, the condition returns the boolean value of the option.