This document serves as the current "Record of Understanding" for the requirements of the class browser for the Eclipse CDT.
| CDT Class Browser Feature Spec This document serves as the current "Record of Understanding" for the requirements of the class browser for the Eclipse CDT. |
|
| Author | : Chris Wiebe |
| Revision Date | : 01/29/2004 - Version: 0.1.0 |
| Change History | : 0.2 - Draft |
This document serves as a starting point for understanding the requirements and design for a class browser within the CDT.
A class browser is a convenient feature found in many development environments. It assists the developer in visualizing and navigating a project's class hierarchy by presenting it in a purely logical layout (as opposed to a file-system layout). Classes can typically be filtered and sorted by project, namespace, base class, etc.
The "Java Browsing" perspective in the Eclipse JDT provides a good illustration of how we might envision a class browser for the CDT. It allows easy navigation of the Java model using separate views for projects, packages, types and members.
For the CDT, we would likewise want a "C/C++ Browsing" perspective to navigate the C model. For C++ projects, we would show namespaces and classes rather than Java packages and types. For C projects, we might simply show all structures under a default global namespace.
This section outlines some of the architectural and functional requirements for the CDT class browser.
The CDT class browser should be functionally equivalent to the JDT java browser. This means we need a "C/C++ Browsing" perspective which mirrors the layout of the "Java Browsing" perspective in the JDT. The following views are required:
The "C/C++ Browsing" perspective should work for both C and C++ projects, but the contents of the views should reflect the project type:
The "Namespaces" and "Classes" views should be able to display their contents as either a hierarchy or a flat list.
Nested type declarations should be flattened and prefixed with the parent scope, so that each unique type is visible as a separate item. Empty nested declarations could be hidden.
For example, given the following code in C++:
namespace NSA
{
class A1
{
public:
void foo();
class A2
{
public:
void bar();
};
};
namespace NSB
{
class B1
{
public:
void foo();
};
};
namespace NSC
{
};
};
Selecting A2 in the "C/C++ Browsing" perspective would look like this (with the "Namespaces" view flattened):
In C, structures can also be nested:
struct Bob
{
int x;
struct Alice
{
int y;
};
};
Selecting Bob in the "C/C++ Browsing" perspective would look like this (with the "Classes" view flattened):
Note: In the "Java Browsing" perspective, nested java classes are not flattened in the "Types" view, but are shown only in the "Members" view. In the case of C and C++, however, it is quite common for nested classes to be publicly accessible outside the surrounding class (e.g. Map::iterator i = map.begin()), so it's more useful to show these classes individually in the "Classes" view. This makes navigating through deep hierarchies much less cumbersome.
The "C/C++ Browsing" perspective should search incrementally, updating each of the views as the selection changes:
Each of the perspective views should have filtering options:
Whenever a resource modification is made, the "C/C++ Browsing" perspective should be updated to reflect the change.
Although the C model differs substantially from the java model, the gui presentation of the browsing perspectives are very similar. We should strive to reuse the existing JDT browsing code (dialogs, views, actions, etc.) where possible.
For a developer to be productive, the "C/C++ Browsing" perspective needs to remain quick and responsive, even when navigating thousands of classes. The UI responsiveness will depend largely on the speed of the search engine (which internally relies on the indexer), as well as any potential caching strategies in the perspective views.