Documentation moving slowly; let's redesign/update some parts.

[Iban Hatchondo]

Erik Enge wrote:
> The documentation is moving, but very slowly.  I've been thinking lately
> that some of my efforts will be wasted rather quickly as we redesign
> parts of Eclipse and this has been discouraging.  What I'm about to
> suggest is that we redo some parts that we know could be done better
> before documenting them.
> 
> For example, our theming concept needs some work.  Most notably, we need
> to be able to change icons when a mouse moves over buttons but we also
> should make the process of creating a theme slighly more elegant.
> 
> I'm not entirely sure what is required to make the buttons happen, but
> making the process of creating a theme more elegant should be fairly
> straighforward.  We should eliminate the excessively large macro
> define-theme and replace it with smaller functions/macros that make more
> sense and are easier to type without errors.  I'm hoping to create a
> situation where you could build a theme in an incremental way, instead
> of as now, where it's an all or nothing approach.
> 
> We need to clarify the draw-on-in* methods too so that they make more
> sense to a person creating themes.  Perhaps we could use macros here so
> that the syntax is more basic.  I don't have anything solid here, I just
> would like to be more straightforward than it currently is.
> 
> In making the process more elegant I hope we will be able to keep it
> around, even if we decide at a later stage that we need to do some
> redesigning of how themes work.  This would eliminate the need for
> themes for various versions of Eclipse (perhaps; I don't know how
> realistic this is, but I do believe it is worth a shot).
> 
> While overhauling the theming-code, we should also take the time to
> document all functions, macros, variables and slots to make it easier to
> read the code without trying to defer from the name of a
> function/macro/variable/slot what it does or what it represents.
> 
> Thoughts?

Hi all,

I agree with you except for the define-theme macro, but it could maybe 
be discuss later (after this thread I mean).

As you propose the first point to be discuss should be the clarification 
on the draw-on* methods. As you might have seen, I ask for some comments 
on that point on c.l.l few weeks ago. I was thinking to a set of 
macro's, that would play with the mop to ensure that all user's 
definitions would be reversable when switching from one theme to 
another. But as Daniel Bralow and Kent M Pitman answered, it could be a 
better idea to specialize all the methods that deals with theme on the 
theme name (eg: (name (eql 'my-theme-name))) and having a package that 
enclose all the private definitions in their own namespeace.

In this direction I though to something like this:

(-- exit the draw-on-* methods --)

  - repaint widget name focused-p [generic function]:

This method is dedicated to widget repaint. It is specialized on widget 
type (base-widget, button, push-button, title-bar, icon ...), theme name 
(via an eql specializer) and a boolean that indicate if the 
corresponding toplevel (type decoration) is or not focused.

Except for standard expose events, the dispatch on focus change will be 
perform accroding to parts-to-redraw-on-focus list given in define-theme.

The core of eclipse provide some basic implementation for the repaint 
method:

---- predefined methods ----
(defmethod repaint ((widget base-widget) theme-name (focused-p t))
   (values))

(defmethod repaint ((widget button) theme-name (focused-p t))
   ;; draw a pixmap if the button provide a pixmap to display when
   ;; toplevel is focused.
   ;; in case of title bar draw a centered text corresponding to the app
   ;; name.
   )

(defmethod repaint ((widget button) theme-name (focused-p null))
   ;; clear the button.
   )

(defmethod repaint ((widget box-button) theme-name focused-p)
   ;; draw the message that is displayed by this box.
   )

(defmethod redraw ((widget icon) theme-name focused-p)
   ;; draw the icon name if aaplication does not provide a pixmap for it.
   )

---- end predefined methods ----

Adding to this: a package definition for each theme. Theme then should 
import and export needed symbols (repaint should be enough to export).

Thoughts ?

Iban.