+---------+--------------------------------------------------------------------
|notes.txt| Mike's ramblings on the Window Manager library.
+---------+

These notes are just thoughts on how the Window Manager library should work.
They will not necessarily mean anything to you.

Architecture:

    The idea of libwm is it fits into the architecture as such:

                        MAIN LOOP
                       /         \
                      KUI      TGDB
                       |
                      WM
                       | 
                      Widgets

    Widgets are the source buffer, the GDB buffer, data displays, etc.

    This architecture means that widgets do their I/O vicariously through
    the window manager (libwm).  Output will be handled by giving the widget
    a curses window, which is basically a sandbox environment.  The widget
    can write freely to this window without risk of damaging another window's
    territory.

    Input ideally should be handled as it is in X, where the server (libwm) 
    gets input from the keyboard (perhaps at a very low level) and feeds it to 
    the focused window in a meaningful way.  I'm assuming at this point the
    main loop notices input on stdin (select), and notifies the KUI.  The KUI
    does something, which is not completely determined yet, and then the
    result is given to the Window Manager.  The WM can then feed this to the
    appropriate window (either the current focused window or the command
    window if the user is typing a :command).

    This leads me to believe that there needs to be an event mechanism.  Not
    only is keyboard input an event to be sent to the widget, but also window
    resize operations.  The widget will most likely want to reformat its
    contents in the event of a window resize.  See current assumptions for how
    I think this will be handled.

Design Notes:
-------------

03-01-2004:

  Current assumptions:

    Windows are always bound to one widget (widget can be anything)
    Windows are opened and closed via libwm
    No widget allocation/deallocation occurs here, app must handle this
    Many windows can view into a single widget
    
    The widget type contains the following:
        - win:     Curses window for the widget to draw in
        - input:   Function pointer to the widget's input event handler
        - resize:  Function pointer to the widget's resize event handler
            (Maybe both events could be collapsed into a more general event
            handler function, since it's conceivable that the number of events
            could grow down the road.)
        - options: Options for the given widget
        - data:    Pointer to the widget's private data structure
            (This would be "struct scroller" or whatever in the old CGDB.)

  Open problems:

    Window needs access to specific widget members:
        - Cursor position and window 'viewport'
          (Think about multiple windows viewing different parts of the same
           buffer... in this case the widget can't store the positional
           information because it is window-specific.)
    How does the window have such information without breaking encapsulation?

    Special windows:  GDB, TTY, Command Window (:commands)
        These windows will need some kind of unique identifier so they can be
        opened or closed by the user?  For example, the user could close the 
        TTY window with :q, and re-open it with :sp __tty__ or something?
        Or is it a special command, like :sptty, :vstty (vertical)?
    
    Options: 
        Some options are windowing related, like winheight and winwidth.
        These obviously belong to the window manager.  Other options are
        window-specific, but really apply to the underlying widget, for
        example, wrap.  How do we set these options on a per-window basis but
        have them apply to the underlying widget?

        Vim gets away with this because every window maps to a buffer.  Buffers
        are the only type of widget.  For us, I don't believe this will always
        be true.  For now, GDB and source displays are definitely just text
        buffers.  However, it's conceivable that future widgets, like data
        displays, may have their own unique options, and buffer options like
        'wrap' won't necessarily apply.

