About OmniBrowser code :)
cputney at wiresong.ca
Wed Dec 8 01:27:06 UTC 2004
I'm very glad that you're digging around in the code,
> I have a few questions:
> - What is the difference between OB-Standard and OmniBrowser:
> I guess that one is the framework and the other is the standard code
That's right. There's also OB-Filesystem, which is the file browser
that was part of the early alphas. It's been languishing while I worked
on the code browsers, so I haven't included it in the later releases.
When I get some spare time, I'll dust it off and release it separately.
> - so if I try to understand:
> A browser is described by a metaGraph. This metaGraph is described
> by node and edges.
> A node can be manipulated by actions
> which represent what can be done on a specific node. A node will
> wrap the code entity.
Yes. The important thing to understand is that there are actually two
The "domain graph" represents the objects in the domain we are
browsing. The "domain nodes" wrap objects in the domain the user is
working with - Smalltalk code in this case. There are many kinds of
domain nodes; all the subclasses of OBNode are domain nodes. The edges
of this graph aren't reified.
The "metagraph" represents the paths through the domain graph that the
browser makes available to the user. When the user clicks on a domain
node, we look at its metanode to see what should happen in response.
The edges incident on that metanode represent navigation messages that
we can send to the selected domain node. The domain node will respond
with a collection of more domain nodes, which are then associated with
the metanode the edge leads to.
That sounds more confusing than it really is, so I'll give a more
concrete example. Imagine that we've just clicked on the class Date in
an OBSystemBrowser. The currently selected domain node is an
OBClassNode that wraps Date. Its metanode is touched by a single edge,
labelled #categories. So we send #categories to the domain node that
wraps Date, and get back a collection of OBMethodCategoryNodes. The
edge points to another metanode, which we assign to all the nodes in
our collection. Then we display the list of nodes in the column to the
right of the one containing Date. If the user then clicks on a method
category, we repeat the process to get a list of OBMethodNodes to
display in the next column.
> It is not clear yet to me, how we represent state transition (for
> example, how to pass
> from "we are editing a method, to the method is compiled so the
> browser does not have to
> tell us that we will lose your code if we click on a method category
> for example".
Hmm, Alexander asked me that question as well. I think it might be best
to think about it in terms of two levels of state, corresponding to the
metagraph and the domain graph.
The metagraph is very like a state machine. Metanodes represent states,
and edges represent transitions between them. But you might say that
these are "abstract states." There could be any number of nodes in the
domain graph that correspond to a given metanode. The currently
selected domain node is the concrete state of the browser. When the
user does something that triggers a state change, the browser sends
#okToChange to all of its panels. The panels all maintain secondary
state that they can use to tell whether a state transition is ok. Then
after the change has been done, the browser sends #nodeChanged to all
the panels, and they update their secondary state (and the display) to
reflect the change.
> - why OBCodeNode, OBClassVariableNode are totally empty?
This is the result of refactorings. They originally had more definite
purpose, but gradually lost all their methods. I left OBCodeNode in
because I wasn't sure that I wouldn't need to put behavior there again.
I had removed it and then put it back once already, and it was enough
of a hassle that I left it in. OBClassVariableNode is still there for
structural reasons. It makes more sense to me to have an OBVariableNode
class that both class and instance variable nodes inherit from, even if
it results in an empty class. The alternative - having
OBInstanceVariableNode inherit from OBClassVariableNode - would be
confusing, I think.
> - is OB using the systemNotifier mechanism?
Yes. OBCodeBrowser registers for SCN events and refreshes its display
when it receives them.
> - why the OBMetaGraphBuilder does not have any instance methods? I
> understand that this is a metagraph Repository
> but without methods or state I do not understand.
This is more refactoring. As far as OB-Standard is concerned, this
class can go away, but OB-Filesystem still has extension methods on it,
and so I left it in until I get around to reviving OB-Filesystem.
> - what is an OBDefinition? Answer should also go in comments :)
An OBDefinition is a way to define domain nodes. It presents the domain
node as text, and knows how to translate changes in the text into
changes in the domain. So an OBMethodDefinitionNode knows how to
compile methods, OBClassDefinitionNode knows how to create or alter
classes. Definitions also do all the associated error checking - for
example, OBClassDefinition is responsible for checking that a new class
definition doesn't overwrite some other class in the system.
As for comments, yes. The comments in beta 1 haven't been updated in a
while. I'm working on this, but it's a lot of work, and I wanted to at
least get the code out there. The next release should have updated
> - how can I open an OBHierarchyBrowser?
Ok, you caught me. This isn't implemented yet. I hardly ever use
hierarchy browsers, so this one fell through the cracks. I'll put one
in the next release.
> - I imagine that we really need the notion of environment to be able
> to scope the search
> senders... in the image, and for example SystemNavigation could use
> such search environment
> and also for the rbengine. Do you think that OBEnvironmentNode could
> be one candidate,
> may be the namespace implementation we are doing could serve also
> that purpose.
I agree that we need this, but I don't think OBEnvironmentNode is a
candidate. Its purpose is to *wrap* an environment. Right now it wraps
Smalltalk. I think we'd actually be in good shape if SystemNavigation
were more analogous to SystemOrganization. Then you could send
#navigation to a SystemDictionary to get a SystemNavigation that was
limited to the classes it contains. That would be a big step towards
being able to have multiple SystemDictionaries.
More information about the Squeak-dev