#
# $Id: TOUR,v 1.3 2000/01/21 05:07:19 kline Exp kline $
#
# TOUR: an overview of muuz from the coding standpoint
#


  ==Forward==

    This documentation is meant primarily for the X Window System 
    programmer or audio//sound savvy programmer who needs to understand
    the flow of the Muuz suite: how things fit together, and hopefully
    _why_.

    Feedback encouraged.


	December, 1996; January, 2000





  A Tour of Muuz



  Some initialization is done in main() but most in from within do_muuz()
  in main.c.  

  The global values are gleaned first in do__muuz(), the screen_number,
  height and width of the main form, the global display values.  
  This is where the C++ paradigm class structures are used. (Feb99)

  Next, allocate_private_colormap() in do_colors.c allocates the 
  private colormap.

  Widgets and ancillary forms are created and the default flash color
  is set.  The default color is set by XMuuzSetDefaultFlash() and in
  the program initialization function the colormode index, in set.
  Currently YELLOW.

  The global_flash_color variable is set in the color-set button 
  callback routines colorsdown_buttonCB() and colorsup_buttonCB() in
  callbacks.c

  +++Assembly buttons.

  There are many buttons that consist of labelwidgets within labelwidgets,
  up- and down-arrows, and commandwidgets.  These control things like the
  volume, pitch, colors, action (start/pause/stop), mode (audio/video/a+v),
  and hertz.  Hereafter, I will refer to these complex widgets ``assemblies.''

  There are three files that contain assemblies.  The first time that 
  the user sees the 6 assemblies, these are constructed in controlpanel.c.
  These 6 buttons disappear if the user goes to another panel such as 
  the prep-programmed panel.  In prepcallbacks.c there are three (3)
  assemblies that also appear on the first panel, L_MODE, L_ACTION, and
  L_VOLUME.

  If the user decided to return to the "Control Panel" to experiment with
  Muuz, the third file, callbacks.c, is used to construct the 6 assemblies.

  If the user goes to another panel (with the permanently displayed buttons
  on the upper-left) and then decides to return to the main Control Panel,
  we use the code is callbacks.c.

  Within the CreateManagedWidget() calls, those containing the ``L_***''
  XtNlabel <labelstrings> contain the muuz.h #define LABEL_COLORS that
  have the background and foreground colors (white, black).

  The colors of the screen will likely include a color-cycling option
  eventually in which the range of hues will be cycled through at from
  one to 30 times per second.  Because of the difficulties with the
  display versus scan-rate, cycling beyond 10 or 15 hertz may not work.
  This is yet to be determined.

  For the L_HERTZ, L_ACTION, L_PITCH, L_VOLUME, L_MODE, L_COLORS trio
  sections are the muuz.h #defines for the FORMLABEL_COLORS.

  Running horizontally across the top of the muuz rectangle is the
  menu-bar that contains N button that create popdown menus.  The 
  code that creates this menu assembly is in form.c; the menu code is
  largely in muuzmenu.c.

  I hope to have my new Help-Widget implemented and added to the code
  base by 12/31/01; until then the present XawtextScroll (Athena toolkit)
  widgets plus the ancillary documentation plus the HTML files on
  magnesium.net will have to suffice.







  After the Xt/Xaw loop is set in completed within do_muuz()
  XtRealize() brings up the warning screen with a [yes/no], and behind
  it the first screen of the "Control Panel"; this from 

    void
    controlPanel()
    {
    }

  in controlpanel.c.

  The first screen is divided into an omnipresent 4-button assembly in
  the  upper-left, the 6-button "Control Panel" assembly in the upper-right,
  and below these panels is the large formflash.

  By selecting one of the 4 buttons in the upper-left panel, the user can
  go to (1) the Pre-programmed panel (which will appear in the upper-right
  and replace the Control-Panel, (2), the user-created panel (which will
  appear in the upper-right, (3) QUIT (with [confirm/canel] buttons), or
  (4) if the user has selected and has exited the first instantiation of the
  Control-Panel (without quitting!!), he can return to the Control-panel
  display.  The "Control Panel" assembly is the first of the four.  The
  second (and last) re-display of the control-panel is handled in the
  callback


     
  void
  selectpanel_buttonCB(Widget _w, XtPointer _client_data, XtPointer _call_data)
  {  
  }

  in callbacks.c



  The control-panel lets the user experiment with muuz.  He can set the
  Volume, the flash-frequency, the pitch, the color of the formflash 
  window; he can stop, play, pause the flashing, and he can select audio-only,
  video-only, or audio+video.  

  The user should be familiar with the general functioning and purpose of
  muuz after only 5 or 10 minutes.  If he wants to, he can set the program
  to flash and sound at him for as long as he wishes.

  Back in do_muuz() in main.c, after the form manager is called the widgets
  are brought to life with XtRealizeWidget().   Then the essential warning
  screen is popped up by graphicWarning().

  The odds and ends are wrapped up: we initialize the Display, the 
  Drawable, and the FlashGC; then we set up the icon display with
  XSetIconName().

  To conclude do_muuz() we infinite loop with XtAppMainLoop().



  // Broadly, with exactitude.

  The user can then select the Pre-Programmed screen or the Create Your
  Own Mind-Machine Program screen//header (as of 12/1999, not implemented.

  The Pre-Programmed header code, largely in callback.c and prepcallbacks.c,
  lets the user select one of 7 program categories: 

  creativity,
  learning,
  relaxation,
  mediation,
  energize,
  sleep,
  fun.

  Each category has between 5 and 7 programs; I'll add more once I've
  completed the research required to insure some degree of effectiveness.
  It is this--knowledge behind the programs--that is essential to muuz.
  Decades of research have proven the efficacy of this mind-machine 
  program; I need to be sure that I get my programs right!

  Only some (3,4) of the control buttons available on the first screen,
  the main control-panel screen, are available on the pre-programmed screen.
  This is because the hard-coded programmed are meant to be enjoyed as
  written.  

  The user can adjust the volume, change the pitch, alter  the mode
  (audio, visual, or audio and video). [[Add.]]


  The user can select a given program, engage it for as long as desired,
  end it any any time, choose another program and try it.  

  The state changes are controlled by a number of variables involving
  flag_t, action_t, audio_t, audiovideo_t, pitch_t, volume_t, boolean, and
  toggle variables.  Theses are typedef'd in muuztypes.h.


  The TIMEOUT problem.

  The most significant problem I ran into in the Xt/Xaw3d version of muuz
  was in getting the delays necessary for flashes to not interfere with the
  response that the user can click the mouse to change state.  After 
  several months of trying, unsuccessfully, I gave up on using XtTimeOut()
  for the audio part of muuz.  I'm hoping that some sound wizard can join
  in finding a unified solution here.  

  The flashed for the Control-panel flashing is handled in flashes.c.
  The screen flashing for the pre-programmed programs is within 
  prepengine.c.

  The free-formed flashing (for the control-panel) is handled in

  void    
  timeout_proc(XtPointer _client_data, XtIntervalId *_id)
  {
  }

  where XtAppTimeOut() and usleep() calls working with XChangeCG() and
  XFillRectangle() create the flashing correctly.  When there is a 
  mouse-click to change state, a boolean variable skips the usleep()
  calls thus making the clicks work reasonably well.

  Since state-switching is less complicated in the pre-programmed
  timeout routing, preptimeout_proc(), the need for skipping around 
  the usleep() calls was not necessary.  

  Self-contained Documentation:

  In January, 2000 I began looking around to create new windet types
  1) for a Help class widget and 2) for an interface to allow the user
  to create his own programs.  I found the code from the Free Widget
  Foundation and modified it to create pop-up widgets with scrollbars
  and more that will eventually be used for the on-line Help files.

  Currently, tho, the help docs are maintained in file header files:
  helpUserPrep.h, helpPrep.h, helpOverview.h, acknowledgement.h, and
  aboutMuuz.h.

  These files contain # comments and $Id$ tracking information that
  is stripped with grep -v "^#" and rewwritten to "*.text" files that
  are stored in a consistant directory location to be read by the
  menuing routines in muuzmenu.c.  

    Future-plans-note:

    Eventually there will be more than one time of on-off screen
    flashing; both in the control-panel and pre-programmed areas.
    When this is implemented, there will be matching timeout
    procedures.  In my earlier Xlib version I created two other
    like of display interruptions.  

    However, for all practical functionality, the simple on-off
    transitioning is fully effective.  


    Sound-wise, I'm expecting to let the MIDI functionality produce
    various and interesting beats; if MIDI can be wrapped into the
    single binary--efficiently--the simple sine wave generation code
    may well disappear.  

    Screen-flashes initially are in simple yellow, orange, lightpink,
    lightskyblue, lightyellow, and white.  One idea (thanks duly 
    noted to Chuck Roby!) is to include any number of graphic patterns
    that flash rhythmically on the screen.  The possibilities here,
    as with the MIDI sounds, are limitless.

    The different flashing and sounds would very probably not make 
    any difference in the effectiveness of the program, but it 
    would certainly make the program more interesting to the user.




    The initial Xt/XAW version was coded in straight C; in early
    1999 I decided to move to the C++ model mostly hoping to improve
    the modularity of muuz as it passed the 10K-line point.  Moves 
    toward the Object Oriented Programming model--adding various
    Class structures--are discussed in the file ``Classification.Plans.''


    As the Project grows, this ``Tour'' will be expanded; at least
    twice a year.
  



