Armory - plugin for Intellij IDEA

Hello everyone! Here we'll at first discuss theoretical preconditions and existing challenges in the field of user interface development for an IDE as such, and finally we'll invite you to familiarise yourselves with the result of our work as a plug-in for the popular platform "Intellij IDEA".

Why yet another tool for developers?

For a long time our team has elaborated alternative ergonomics of the user interface for the proprietary development environment as well as for third-party ones. The goal has been set to easily handle complex and intricate projects with a large number of classes and files on board. Primarily we as programmers were interested in increasing the level of efficiency and satisfaction while working on assigned tasks. This refers to the common programming tasks, such as: creating new classes, filling them with code, exploring the existing code, finding the right place to study, navigating between different parts of the project, and so forth.

In a nutshell the main objectives this alternative ergonomics has to solve can be outlined as follows:

  • To reduce the number of routine actions, for instance: scrolling to the right place in the code or to an element in the tree, expanding the tree, visual search for an item in a large list, and the like.

  • To minimize cognitive load. Programming tasks considerably load intelligence and memory as it is, therefore it would be wrong to demand from the developer to keep in mind and analyze additional information. This not only reduces the level of job satisfaction, but also can significantly affect productivity.

  • Fewer distractions. Superfluous (irrelevant to the current task) information whenever possible should either be hidden or have less visual weight.

  • Reuse of automatisms. If the user interface involves mastering some new skill, then this skill should be applied as many times as conceivable.

Let us examine each of these points in more detail.

Reducing the number of routine operations

During experiments it became clear that efficiency is influenced considerably by access time to a targeted code area. Moreover, this influence is expressed not by a linear function, as it might seem at first sight, but by some kind of an exponential one.

The explanation of the non-linear dependence apparently lies in the distinctive characteristics of the human short-term memory. If your development environment does not allow access to the appropriate code area in a split second while precious short-term memory is still "alive", most likely, you will be forced to take a step backwards and "to think it over" for a while to restore the task context in your mind. Surely everyone is familiar with the situation when we have finally found that very method in that very class, but have completely forgotten about the very reason why we were actually looking for it at all. The positive side of such interrelation between access time and overall performance is that even a slight reduction in search time may considerably affect productivity in general.

The key rationalization that we propose to address the challenge of reducing access time is the use of multiple project tree. Instead of the habitual single tree, we suggest to use an arbitrary number of trees for a project, each of which can be adjusted to reflect a specific branch of its structure. Such an approach allows you to fine-tune the "project desktop" for a specific need and to arrange the elements so that everything will be close at hand.

Fewer distractions

A user's overall cognitive load is affected a great deal by the search time and the number of purposive movements needed to reach the target, but not only by them. The other weighty factor is when your workspace is overloaded with irrelevant information. Of course it's not so easy to determine which objects are currently key and which aren't of paramount importance and represent only a source of hindrances, especially given the diversity of ways to use the IDE. However, to give the developer the ability to hide redundant items seems an essential requirement to us.

With regard to code editing quite good results were shown by focusing exclusively on the current method of a class while concealing all surrounding code from view. This allows you to concentrate on either completion or studying of the current method and to temporarily forget about the existence of other code in the class.

In the context of navigation across the project tree great effect was obtained via hiding extraneous to the task elements in so-called visual groups. These groups in contrast with packages and classes don't exert any influence on the project structure, but allow an engineer to quickly and painlessly create a suitable visual arrangement and to get your priorities right.

Apart from holding aside inessential parts it is sometimes useful to go exactly in the opposite direction, i.e. to highlight the critical points by using typographical accents (e.g. bold, italic, or underline). Such marks allow you to catch sight of a special entity during a brief look at the tree branches or their cursory inspection and to remember something meaningful, for the sake of what the emphasis was introduced.

Reuse of automatisms

Sometimes even the most obvious at first glance solutions for quick access to frequently used items are doomed to failure because the acquired automatisms of the user gain the upper hand over the estimated simplicity. An example of this type of failure would be the proposal of the developers of the OS Windows itself to place multimedia files in the designated folders: "Pictures", "Music" and "Videos". Why does this not work? The truth is that users will rather exploit their more familiar and universal skills to create their own folders and store photos there, than will remember about the existence of the specially intended directory which has been courteously created by founders of the operating system for this purpose. And such a behavior would be quite rational. Learning a new way of solving the problem always involves an additional expense of time and effort and if this acquired skill were useful only in a fairly narrow range of tasks it is very likely that the cost of its development and up-to-date maintenance would not be justified by the result that is planned to be received in the end.

Thus, when designing the interface it would be naive to expect that all of our proposed ideas on the labour management will immediately find approval among users. Moreover, if we propose either to get into the new habit of work or to master a new skill, it has to be really justified and this experience needs to be as versatile as possible.

For this reason, we do not like the concept of "Favorites" as a separate component or a dialog box. Instead it would be desirable that each of the project trees could be with great ease turned into a set of the necessary classes or packages picked up by the developer for a particular purpose. Thus the universal skill at setting up a custom tree could be reused in the working process. Besides, it would allow us to move away from the uniform global scope towards multiple contextual domains.


The first development environment embodying the principles described above appeared in 1996 under the name of "Visual Programming Armoury". At that time the most actual language for us was C++, and the blooming stage of Java had only just begun. The development environment was a standalone Windows application supporting plug-ins for different programming languages, including object-relational mapping and modelling frameworks and other in-house tools.

A lot of work was done and many of ideas were realized, but unfortunately the project was curtailed in 2001 due to insurmountable difficulties.

Despite this we continued to improve our Armoury for private use. It is difficult to reject the instrument that gives an opportunity to accelerate development more than somewhat and to earn more.

Meanwhile progress didn't stand still. AutoComlete, Find Usages, navigation in the code by Ctrl + Click and all kinds of smart search become a norm among the popular IDEs.

In 2001 there appeared IntelliJ IDEA and slowly but surely started winning hearts of programmers. The intelligent code analyzer helps to find errors even before the compilation, while refactoring tools allow developers to quickly reorganize the source program. Here we must pay tribute to JetBrains, they did a great job of creating a full-fledged structure of the source code elements, having reflected it in the so-called hierarchy of Psi-objects. On the basis of this abstract model one can perform code inspections for compliance, code analysis, micro-refactoring, as well as display and traverse the project tree.

Although we love this remarkable development environment (Intellij IDEA), some points have not entirely suited us especially considering the accumulated experience in organizing an ergonomic workspace.

So the question has arisen, is it possible to unite the ergonomics of the old Armoury with the intelligence of IDEA? Having studied the source code of IntelliJ Platform SDK, we found out that the Open API provides access to all key functions of the development environments and such integration is quite feasible. The prospect to get the convenient tool to work with all the bells and whistles of the most advanced editor inspired us and we thought why not share it with the developer community.

As a result of our work the Armory plug-in for JetBrains products has appeared. The plug-in is absolutely free for IntelliJ IDEA Community Edition and under this platform supports such languages as Java, Scala and Groovy.

How to use the Armory plug-in

Armory may be installed either from the JetBrains official repository of third-party plug-ins or from the Downloads page of the program website. The distribution kits at both places are completely identical, the only difference is that there is sometimes a time lag of several days between our site and the JetBrains repository. This is owing to the fact that after we upload our updated version to the repository it is necessary to pass moderation.

After the plug-in is installed and IDEA is restarted the tab of the Armory window will appear on the right (like the tab of the Project window on the left). Clicking on that tab opens the plug-in main window containing project trees themselves, toolbar and the panel informing about the element selected in the tree. Like all the IDEA's Tool Windows the Armory's one can operate in several modes: Pinned, Floating, Docked. Read more about Tool Window management here. Docked Mode together with Pinned Mode is set by default. Docked Mode implies that the plug-in window will "bite off" its workspace from the other components of the IDE at the opening and won't overlap them on top. Pinned Mode assumes that the Armory window does not automatically hide when it loses the input focus. At this point perhaps you would like to adjust this behavior as you wish by setting the desired combination of the modes.

Now you are ready to configure your workspace. It is possible to create new project trees by dragging a folder, a package or a class to the special Drop-zones as shown in the animation.

There are other ways to add new trees, you may read about them in the program's online help.

Now it is necessary to say a few words about navigation between the project tree and the editor. The fact is that in contrast to the built-in Project View component, the Armory window is much larger horizontally. The reason is obvious — here we deal not with a single tree but with several ones simultaneously. As a result the way of navigation to the editor has been changed. To switch to and fro between the tree and the editor by default Armory uses the hot key Ctrl + Enter. If you for some reason are accustomed to using this shortcut in the editor to insert line breaks without moving the cursor (which is its default behavior in IDEA) you can assign another keystroke in the plug-in settings.

If you paid attention, when opening a class member function from the project tree in the editor, here we see not the whole class but only the current method body. Actually all the code before and after the current method is collapsed by two Folding regions. In order to see the class entirely just double-press Escape while in the editor. You can also change this behavior in the plug-in settings, for example instead of collapsing the surrounding code, you can choose to highlight it by your preferred background color.

Please pay attention that when you are navigating into the editor by Ctrl + Enter the Armory window is being closed. If you have a large enough monitor and you don't want to close the tree views after switching to the editor then you can use IDEA's standard navigation keys:

  • Enter — To open the source code of the current element without setting input focus to the editor.
  • F4 or mouse double-click — To open the source code of the current element and set input focus to the editor.

This basic information is sufficient to get under way using the plug-in and at the same time to start making a certain profit from the application of multiple trees. Further we will consider how to fine-tune each project tree and create groups of elements.

Configuring the root element of the tree

As described above, the Armory tree may contain a root element which points to a specific node of the project structure. Besides, each Armory tree can include several such root elements referring to different parts of the project. This is useful if we want to set up a tree as a collection of favorites by gathering certain classes or packages from various sections of the source code. To add an item as a root to any tree, simply drag this item to a special area in the header of the tree, as shown in the following animation.

To add an item as a root using the keyboard you can press Ctrl + Up and by means of arrow keys specify a tree to which this root element has to be added.

To remove a root element from a tree just drag it to the header region or use a hot key Ctrl + Delete.

It's worth saying that all the Armory commands are available through the Armory context menu. Invoke it by pressing Ctrl + Right mouse button or by a keyboard shortcut Ctrl + Menu.

With this approach both menus (standard IDEA's context menu and plug-in's context menu) are always at hand.


The grouping of tree elements is an indispensable facility to keep order within a class with a large number of constants and variables. In addition, it is helpful to isolate some methods of the class, grouping them by some intrinsic logic. You can group any elements of the tree, including files, folders and packages.

Such grouping has no physical effect on the source code itself and is purely visual. Deleting a group will only ungroup all its constituent elements. To group selected items without the help of the mouse there is a hot key Ctrl + Alt + Page Down. To ungroup press Ctrl + Alt + Page Up.

Sorting of tree items

The order of tree elements is defined by the current sorting scheme. To change the order of items you need either to select a preset option or to create a new sorting scheme in the plug-in settings. The illustration below shows how to change the sorting scheme with the aid of the toolbar button.

How to create new sorting schemes and edit existing ones can be found in the plug-in's online help.

Highlighting tree items

As mentioned above, in addition to hiding secondary items in a group or bringing them out of sight by setting the root element it is also sometimes useful to visually accent important nodes. At the moment Armory supports three styles of typographical emphasis, namely bold, italic and underline. Their combinations are valid as well. To highlight elements there are generally accepted shortcut keys: Ctrl + B, Ctrl + I and Ctrl + U. One can also apply a style by means of the Armory context menu.

The picture shows the Armory context menu and on its left there is an example of how the items formatted with different styles look like.


In summary, it would be desirable to tell that all techniques listed above, after some practice and getting accustomed to them produce amazing results. Having a "composite map" of the source code which remembers its state and keeps hold of user notes "in the margins" written along the way, you can very quickly recollect the context of previous work and get into gear. Your time isn't wasted. Your attention is centred and energy is saved.

This can be compared with a somewhat contrived case when, instead of beating the hoof around the city for hours, we suddenly gain the ability to instantly teleport by simply touching the desired point on the map.

We hope that our plug-in will be of benefit to you and become a reliable assistant in your work.

If you have any thoughts on the subject, if you disagree with something or have a suggestion for improving the program, please give your on-the-spot feedback.

Thank you for your attention!