Help file for gui.mac macros for MacAnova
(C) 2005 by Gary W. Oehlert
!!!! Starting marker for message of the day
!!!! Ending marker for message of the day

???? Starting marker for list of up to 32 comma/newline separated keys
dialogs
xml
???? Ending marker for keys

Note: There are no topics with names longer than 15 characters so as to
allow 5 column output from 'help()' with width >= 80.

Each topic starts with '====topicName' in column 1, followed by an
unlimited number of lines of information.  It is helpful, but not
required, that topics be in alphabetical order.  Topic names should, if
possible, be no longer than 12 characters, since otherwise they must be
quoted in a help() command.  The convention is used that when referring
to functions, but not macros, by name, '()' is appended.

Each topic name that refers to a function or a pre-defined macro has
'()' appended to it.  This does not affect output but is intended to
useful in semi-automatic generation of the reference manual from the
help file.

Names of topics that are not to be included in the Reference Manual are
followed by '*'.  This does not affect help() output.

Names of topics whose usages are not to be included in the Reference
Manual are followed by '%'.  This does not affect help() output.

Keys separated by commas can follow the topic name (and trailing '()',
'*' or '%') if separated from it by '#'.  These should be selected from
up to 32 keys listed between lines starting with '????' somewhere before
the first help topic.  Case is ignored.

If the next line after '====topicName' starts with '%%%%', all following
lines up to a matching '%%%%' are skipped by help() and printed by
usage().  usage() skips the lines following the second '%%%%'.  This
feature implemented 951212.

The file should be terminated by a line starting '_E_O_F_'

====alert()#dialogs
%%%%
alert(mess) displays a message box containing mess
%%%%
alter(mess) opens a dialog box displaying the message in the
character scalar mess.

====doguihelp()#
%%%%
doguihelp(filename) display html file filename in a simple html viewer
%%%%
doguihelp(filename) displays the html file named in the CHARACTER
scalar filename in a simple browser.  filename should be a complete
path to the html file (see findfile()).  See also 'guihelp()' and
'help()'.

====getdirname()#
%%%%
getdirname() finds a directory
%%%%
getdirname() brings up a dialog box to allow the user to select
a directory.  The full path to the directory is returned as a
CHARACTER scalar.

====getmenubar()#xml
%%%%
getmenubar() returns a character scalar containing the menu resource
%%%%
getmenubar() returns a character scalar containing the current
menu resource.

====guiabout()#
%%%%
guiabout() displays the About Macanova dialog
%%%%
guiabout() displays the About Macanova dialog.

====guianova()#
%%%%
guianova() does basic anova via dialogs
%%%%
guianova() does basic anova via dialogs

====guiboxplot()#
%%%%
guiboxplot() does boxplots via dialogs
%%%%
guiboxplot brings up a dialog box to collect information that
will be used to construct a boxplot command.  The dialog is a
"tabbed" dialog, meaning that the information is collected on
multiple panels that the user accesses via tabs.

The "Basic" tab collects the standard information for a basic
boxplot without any bells and whistles.  At the bottom of the
panel, you choose the variable or variables to appear in the 
boxplot.  If you choose multiple vector variables, each variable 
will determine one box.  If you choose a matix variable, each 
column will determine one box.  At the top of the panel, you can
choose a "split-by" variable.  If you have chosen a single vector
variable at the bottom of the panel, you can choose a "split-by"
variable to divide the single variable into groups.  This split-by
variable must have the same number of elements as the plotted
variable, and a separate box will be constructed for each unique
value of the split-by variable, with elements of the response
variable divided according to their corresonding split value.  
See split(). You must type the name of the split variable (or an
expression that computes an appropriate split variable) into the
dialog element.

The remainder of the elements on the Basic tab control how the
boxplots look.  You can choose vertical (default) or horizontal
boxes.  You can choose to show outliers (default) or to simply
have the whiskers extend to the extremes.  If you show the outliers,
you can control the symbols used to display them.  You may also
enter variables or expressions to control the location and width
of the boxes.  The location expression should evaluate to a real
vector with length equal to the number of boxes.  The width
expression can be a real scalar or a vector with length equal to
the number of boxes.  

The "Appearance" tab collects information that affects the overall
appearance of the plot.  First, you can choose that the plot appear
in a new window (default), or you can choose the number of the
graph window where you would like it to appear. A window number of
0 indicates the most recently used graph window. Next, you can set
the width and height of the plot.  On the screen, these are in
units of pixels.  When printing using PostScript, these are in
units of points (approximately 1/72 of an inch).  

The second major set of choices are for labels.  You can add a title
and/or labels for the vertical and horizontal axes.

Finally, you can set where the border box and axis ticks will be
drawn.  By default, ticks and borders are drawn on all four sides.

The "Axes" tab allows you to control the appearance of the axes.
First, you can choose to have a logarithmic scale by clicking the
check box.  Next, you may specify your own minimum and maximum values
in each direction. Third, you may decide whether the x=0 or y=0 lines
are drawn on the plot.  Finally, you may set the appearance of the
ticks and labels.  Tick locations should be either a variable name
or an expression that evaluates to a vector of real values.  If
this is NULL, no ticks will be drawn.  Tick labels should be character
vectors with the same number of elements as the tick locations.
Finally, tick lengths should be real scalars >= -1.  Values less than
0 are outside the frame; values greater than zero are inside the
frame.  Values greater than 2 draw a grid all the way across the
plot.  The default value is -.5.

If you know the MacAnova commands, you may type in your options
directly on the "Direct Options" tab.


====guifilepath()#
%%%%
guifilepath(type:charscalar) where charscalar is one of
"setdatafile", "addmacrofile", "addhelpfile", "addpath"
%%%%
guifilepath() is used to set various files, file lists,
and path lists.  It brings up dialogs to solicit file
information, which it then forms into a MacAnova command.
Options are
  type:"setdatafile"   does DATAFILE <- "..."
  type:"addmacrofile"  does addmacrofile("...")
  type:"addhelpfile"   does addhelpfile("...")
  type:"adddatapath"   does adddatapath("...")
where the ... is extracted from the dialogs


====guihelp()#
%%%%
guihelp(topic) displays html help on topic 
%%%%
guihelp(topic) displays the MacAnova html help associated with topic.
Standard MacAnova help topics have html versions in files in the
SharedSupport/docs/html directory.  They have names of the form
prefix_topic.htm; for example, the html help on run is in base_run.htm,
and the html help on reml is in design_reml.htm .  guihelp() runs
through the various prefixes in an attempt to match an html help file,
and then calls doguihelp() when a match is found.  See also
'doguihelp()' and 'help()'.

====guihist()#
%%%%
guihist()
%%%%
guihist brings up a dialog box to collect information that
will be used to construct a histogram command.  The dialog is a
"tabbed" dialog, meaning that the information is collected on
multiple panels that the user accesses via tabs.

The "Basic" tab collects the standard information for a basic
histogram without any bells and whistles.  At the bottom of the
panel, you choose the variable to appear in the histogram.  

The elements at the top of the Basic tab control how the
histogram looks.  On the left, you can choose between density
(default) or frequency or relative frequency histograms.  On
the right, you set the bins.  You may let MacAnova choose the
bins, or you can choose the number of bins and let MacAnova
choose their locations.  The two remaining options allow you
to specify the bin locations.  The anchor/width specification
will produce adjacent bins with your chosen width, with one
bin edge placed at the anchor point.  Both the anchor and the
width must be numeric values.  The final choice is to enter
an expression that will evaluate to a vector of bin edges.
It is usually an error to have data outside the bins, but you
may choose to let that happen by checking the "Data outside bins"
box.  Finally, you choose the endpoint convention.  By default,
the right hand endpoint is in the interval, but you may choose
to have the left hand endpoint in the interval by choosing that
option.

The "Appearance" tab collects information that affects the overall
appearance of the plot.  First, you can choose that the plot appear
in a new window (default), or you can choose the number of the
graph window where you would like it to appear. A window number of
0 indicates the most recently used graph window. Next, you can set
the width and height of the plot.  On the screen, these are in
units of pixels.  When printing using PostScript, these are in
units of points (approximately 1/72 of an inch).  

The second major set of choices are for labels.  You can add a title
and/or labels for the vertical and horizontal axes.

Finally, you can set where the border box and axis ticks will be
drawn.  By default, ticks and borders are drawn on all four sides.

The "Axes" tab allows you to control the appearance of the axes.
First, you can choose to have a logarithmic scale by clicking the
check box.  Next, you may specify your own minimum and maximum values
in each direction. Third, you may decide whether the x=0 or y=0 lines
are drawn on the plot.  Finally, you may set the appearance of the
ticks and labels.  Tick locations should be either a variable name
or an expression that evaluates to a vector of real values.  If
this is NULL, no ticks will be drawn.  Tick labels should be character
vectors with the same number of elements as the tick locations.
Finally, tick lengths should be real scalars >= -1.  Values less than
0 are outside the frame; values greater than zero are inside the
frame.  Values greater than 2 draw a grid all the way across the
plot.  The default value is -.5.

If know the MacAnova commands, you may type in your options
directly on the "Direct Options" tab.


====guilistxml()#
%%%%
guilistxml()
%%%%
This is a utility routine, not called by users

====guilistctrl()#
%%%%
guilistctrl()
%%%%
This is a utility routine, not called by users.  It produces
the xml for a choose variable control that can be embedded into
a dialog.  See guilistdlg() for a description of the arguments.

====guilistdlg()#
%%%%
guilistdlg(many, many keyword arguments)
%%%%
This routine brings up a dialog box allowing you to choose variables,
and returns a CHARACTER vector of the chosen names.  It takes 
keyword arguments of several types: usexxxx:T, reqxxxx:T, and
attrxxxx:T|F (for example, attrlogic:T or reqreal:T).  Without any
arguments, all variables are included in the dialog.  If an reqxxx:T
argument is present, any variable must match the xxxx to be listed in
the dialog.  If one or more usexxxx:T arguments is present, then a
variable must match at least one of the xxxx descriptors to be 
included in the dialog.  If an attrxxx: keyword is used, then a
checkbox will be added to the dialog to optionally allow variables
that match the xxx to be show.  The T or F of the attrxxx keyword
determines whether the checkbox in initially checked or unchecked. 
Note: if any attrxxx:T arguments are present, then a variable must
match at least one of them to be listed.

There are two additional reqxxx keywords.  reqnrows:k means that a
variable must have leading dimension k; reqndims:k means that a
variable must have k dimensions.

Keyword maxselected:k sets that at most k variables can be selected.
0 is the default, and it indicates no limit.

usonly:vec says to use only the names in the character vector vec.
omit:vec says to omit any names in the character vector vec.

matchrows:T means that once a variable has been selected, only
variables that match the number of rows will be show.  This differs
from reqnrows:k in that matchrows:T allows different numbers of
rows to be shown before the first variable is selected.

Possible xxxx attributes are:
char         CHARACTER variable
graph        GRAPH variable
logic        LOGIC variable
macro        MACRO variable
real         REAL variable

scalr        Scalar variable
vect         Vector variable (a la isvector)
matrx        Matrix variable (a la ismatrix)
1d           Exactly one dimensional
2d           Exactly two dimensional
array        Array variable
struc        Structure variable

lockd        Locked variable
ulock        Unlocked variable

factr        Factor variable
vart         Variate (1 dimensional, real, not factor) variable
binary       0/1 variable
system       Name is all capitals, and either longer than
                         1 letter or not "E"

nonsys       A non-system variable
nsvart       A non-system variate
nsfact       A non-system factor
ns1d         A non-system 1d variable
ns2d         A non-system 2d variable
nsstrc       A non-system structure



====guintrctplt()#
%%%%
guintrctplt() does interaction plots via dialogs
%%%%
guintrctplt brings up a dialog box to collect information that
will be used to construct an interaction plot command.  The
dialog is a "tabbed" dialog, meaning that the information is
collected on multiple panels that the user accesses via tabs.

Interaction plots graphically display a vector/matrix/array of
real numbers.  The coordinates of the first dimension are
indicated by the horizontal plotting position.  The levels of
any other dimensions are indicated by the plotting symbol; for
example, 2.4 indicates level 2 of the second factor and level 4
of the third factor.  Points with the same plotting symbol are
joined by lines.

The "Basic" tab determines the vector/matrix/array to be plotted.
First, you may directly select a matrix or array of plotting
positions by selecting a matrix of array in the variable selection
control at the bottom of the tab.  In this form, you only select
a single matrix or array.  Second, if there is an active model,
you may choose to plot least squares means from the active model.
To do this, you check the "use LS means" box in the "Control"
subdialog and select the desired factors from the model in the
variable selection control.  (Note: this form makes use of glmtable()
internally and thus will not work for balanced designs.  Use unbal:T
in the anova() command to enable the use of LS means in interaction
plots for balanced data.)  Finally, you may indicate the vector/
matrix/array to be plotted as the tabular means of a response 
variable split according to one or more factor variables.  In this
form, you first select the response variable, and then select one
or more splitting variables.

You may optionally choose to plot error bars around each mean, 
simply by checking the show error bars button in the "Control"
subdialog.  By default, the bars are plus or minus two SE, but you
may adjust that in the Control subdialog.  For LS means, standard
errors are taken directly from the model.  For the matrix/array
form, you must enter the name of a matrix of standard errors in
the "Options" subdialog.  The tabular data form will compute SEs
for the within-cell variances.  Note: an SE of 0 will be used
for cells with a single observation.  Optionally, checking the
"Pooled estimate of error" box in the Options subdialog will pool
variance information from all cells into a single common estimate
of variance, which will then be used to compute cell standard errors.
Finally, you may simply specify a common error variance directly
in the Options subdialog.

The "Appearance" tab collects information that affects the overall
appearance of the plot.  First, you can choose that the plot appear
in a new window (default), or you can choose the number of the
graph window where you would like it to appear. A window number of
0 indicates the most recently used graph window. Next, you can set
the width and height of the plot.  On the screen, these are in
units of pixels.  When printing using PostScript, these are in
units of points (approximately 1/72 of an inch).  

The second major set of choices are for labels.  You can add a title
and/or labels for the vertical and horizontal axes.

Finally, you can set where the border box and axis ticks will be
drawn.  By default, ticks and borders are drawn on all four sides.

The "Axes" tab allows you to control the appearance of the axes.
First, you can choose to have a logarithmic scale by clicking the
check box.  Next, you may specify your own minimum and maximum values
in each direction. Third, you may decide whether the x=0 or y=0 lines
are drawn on the plot.  Finally, you may set the appearance of the
ticks and labels.  Tick locations should be either a variable name
or an expression that evaluates to a vector of real values.  If
this is NULL, no ticks will be drawn.  Tick labels should be character
vectors with the same number of elements as the tick locations.
Finally, tick lengths should be real scalars >= -1.  Values less than
0 are outside the frame; values greater than zero are inside the
frame.  Values greater than 2 draw a grid all the way across the
plot.  The default value is -.5.

If you know the MacAnova commands, you may type in your options
directly on the "Direct Options" tab.


====guipatterned()#
%%%%
guipatterned()
%%%%
guipatterned() will solicit information for building factors,
maximum level, the number of times each should be repeated
consecutively, and the number of times the whole pattern is then
repeated. You may optionally save as factor or nonfactor.

====guiplotresid()#
%%%%
guiplotresid() does residual plots via dialogs
%%%%
guiplotresid brings up a dialog box to collect information that
will be used to construct a plotresids command for plotting
residuals.  The dialog is a "tabbed" dialog, meaning that the
information is collected on multiple panels that the user accesses
via tabs.

The "Basic" tab allows you to determine which plots you want,
which kind of residuals to use, and what plotting character to use.
On the left, you may select one or more of the plot types: residuals
versus fitted values, or residuals versus normal scores, or
residuals versus case numbers.  On the right, you may choose which
type of residuals: raw residuals, scaled residuals, standardized
residuals, or studentized residuals.  You may also choose the size
and style of the plotting character.

Scaled residuals are raw residuals divided by the root MSE.
Standardized residuals are residuals divided by an estimate of their
standard error (ie, this takes the HII values into account). 
Studentized residuals are outlier-t residuals.  In all cases,
scaling involves the final error term of the model.  

The "Appearance" tab collects information that affects the overall
appearance of the plot.  First, you can choose that the plot appear
in a new window (default), or you can choose the number of the
graph window where you would like it to appear. A window number of
0 indicates the most recently used graph window. Next, you can set
the width and height of the plot.  On the screen, these are in
units of pixels.  When printing using PostScript, these are in
units of points (approximately 1/72 of an inch).  

The second major set of choices are for labels.  You can add a title
and/or labels for the vertical and horizontal axes.

Finally, you can set where the border box and axis ticks will be
drawn.  By default, ticks and borders are drawn on all four sides.

The "Axes" tab allows you to control the appearance of the axes.
First, you can choose to have a logarithmic scale by clicking the
check box.  Next, you may specify your own minimum and maximum values
in each direction. Third, you may decide whether the x=0 or y=0 lines
are drawn on the plot.  Finally, you may set the appearance of the
ticks and labels.  Tick locations should be either a variable name
or an expression that evaluates to a vector of real values.  If
this is NULL, no ticks will be drawn.  Tick labels should be character
vectors with the same number of elements as the tick locations.
Finally, tick lengths should be real scalars >= -1.  Values less than
0 are outside the frame; values greater than zero are inside the
frame.  Values greater than 2 draw a grid all the way across the
plot.  The default value is -.5.

If you know the MacAnova commands, you may type in your options
directly on the "Direct Options" tab.


====guirandom()#
%%%%
guirandom(dist:disttype)
%%%%
guirandom() is a dialog based interface to the most common
ways to generate random data into MacAnova.  The possible disttypes
(as character scalars) are:
    "uniform","normal","binomial","poisson","F","beta",
    "gamma","chisq","student"   

====guireadfile()#
%%%%
guireadfile(type:readtype,useclip:TF)
%%%%
guireadfile() is a dialog based interface to the most common
ways to read data into MacAnova.  If useclip is T, then guireadfile()
will read from the clipboard; otherwise it will read from a file.
The possible readtypes (as character scalars) are:
    "matread"	            read in matread format
    "matread/datafile"      read from DATAFILE in matread format
    "vecread"               read data as a vector
    "vecread/matrix"        read data but store as matrix
    "readdata/labelled"     read labelled columns
    "readdata/unlabelled"   read unlabelled columns

====guirsample()#
%%%%
guirsample() to subsample a variable through a dialog
%%%%
guitypein() brings up a dialog into which you can enter information
to subsample from a variable.


====guitypein()#
%%%%
guitypein() to type in data through a dialog
%%%%
guitypein() brings up a dialog into which you can type data,
and then have it read in.


====setmenubar()#xml
%%%%
setmenubar(res,menuName) replaces the current menubar with that
described in the xml resource res with name menuName; both res and
menuName are CHARACTER scalars
%%%%
All menus in Carapace versions of MacAnova, including the default
menus, are set using XML resources.  These resources are based on the
XRC system in wxWidgets, with some MacAnova-specific extensions.
The resource variable is a CHARACTER scalar in XML format:
<?xml version="1.0"?>
  <resource>
    ...
  </resource>

Of course, all the action is in the ... where the menus are actually
specified.  The resource is a collection of objects.  Each object
has a type given by its class, and an identifier given by its name.
Within the object, you can have parameters that describe or modify
the object, and other objects that are called children of the containing
object.  

To set up a menu bar, the resource contains one object of class
wxMenuBar.  The name for that menubar is the menuName used in the
setmenubar() call.  For example, setmenubar(resource,"sampleMenu")
based on this excerpted resource:
<?xml version="1.0"?>
  <resource>
    <object class="wxMenuBar" name="sampleMenu">
      ...
    </object>
  </resource>

The children of a menu bar are objects of class cpcMenu; these are the
menus seen on the menu bar.  The children of a menu are items (objects
of class cpcMenuItem), separators (objects of class separator), and/or
submenus (more objects of class cpcMenu).  Here is an example, with
comments and explanations interspersed in the XML.

      <object class="cpcMenu" name="File_menu">
        <label>File</label>
Start a menu. The name (File_menu) should be unique, but is otherwise
not used.  The label determines how the menu will be shown on the
menu bar; here we have the File menu.
          <object class="cpcMenuItem" name="CPC_FILE_OPEN">
            <label>Open\tCtrl+O</label>
            <accel>Ctrl+O</accel>
            <help>Open a text file</help>
          </object>
Here we have a menu item with name CPC_FILE_OPEN.  Many names that
begin CPC_ correspond to predetermined actions; here, CPC_FILE_OPEN 
opens a text file in a new output window.  A list of these known
names is given below.  The label parameter determines how the item
will appear on the menu.  The accel parameter determines a keyboard
combination that is equivalent to selecting the menu item, here,
control plus O.  Finally, the help parameter is a message displayed
in the status bar at the bottom of the frame.
          <object class="separator"/>
This is a separator to produce a gap in the menu.
          <object class="cpcMenuItem" name="SaveWorkspace">
            <label>Save workspace\tCtrl+K</label>
            <accel>Ctrl+K</accel>
            <help>Save the workspace in a file</help>
            <action>save()</action>
          </object>
Here is a menu item with an action.  When a menu item with
an action is selected, the action value is sent to MacAnova as a
command, just as if you had typed it at the command line.  Please
note, if you add an action to one of the standard CPC_... named
items, the action will be ignored.
          <object class="cpcMenu" name="CPC_WINDOWS_TEXTWINDOW">
            <label>Output windows</label>
            <help>Select output window</help>
            <object class="cpcMenuItem" name="fake window">
              <label>fake</label>
            </object>
          </object>
Here is object that is another menu.  In this case, the menu named
CPC_WINDOWS_TEXTWINDOW has only a single fake item in the resource.
The menu with this name is updated automatically by Carapace to
reflect the command windows present.
          <object class="cpcMenuItem" name="CPC_HELP_HELP">\
            <label>$Help\tCtrl+L</label>\
            <accel>Ctrl+L</accel>\
            <selectionlabel>$Help on selection</selectionlabel>\
            <help>Help on MacAnova</help>\
            <action>guihelp()</action>\
            <hidecommand>1</hidecommand>\
            <selectionaction>guihelp(%s)</selectionaction>\
          </object>\
        </object>
You can make menus change slightly depending on whether or not anything
in the window is selected.  If there is a selectionlabel parameter,
that label will be used whenever something in the window is selected.
Similarly, the selectionaction will be used instead of the action
whenever something is selected.  In this case, the selected text will
replace the %s in the selectionaction parameter.  One additional
twist here is hidecommand.  Ordinarily, any action or selectionaction
command is printed in the output pane.  If hidecommand is 1, the
command will not be printed.  It is not shown here, but there is also
a hideoutput parameter. If hideoutput is 1, then any printing that
the command would do is suppressed.

Here are the standard names and their corresponding actions:
 CPC_FILE_OPEN            Open a file in an output window
 CPC_FILE_SAVEWINDOW      Save the contents of the output pane
 CPC_FILE_SAVEWINDOWAS    Save the contents, but change the name
 CPC_FILE_PAGESETUP       Set up for printing
 CPC_FILE_PRINTSELECTION  Print
 CPC_FILE_INTERRUPT       Interrupt execution
 CPC_FILE_QUIT            Quit
 CPC_FILE_FASTQUIT        No fooling around, just quit now

 CPC_EDIT_UNDO            Undo last edit/typing
 CPC_EDIT_CUT             Cut selection
 CPC_EDIT_COPY            Copy selection
 CPC_EDIT_PASTE           Paste selection
 CPC_EDIT_COPYTOEND       Copy selection to command line
 CPC_EDIT_EXECUTE         Execute the command line
 CPC_EDIT_UPHISTORY       Go back in command history
 CPC_EDIT_DOWNHISTORY     Go forward in command history

 CPC_WINDOWS_HIDE         Hide this window
 CPC_WINDOWS_CLOSE        Close this window
 CPC_WINDOWS_FASTCLOSE    Close this window, no chance to save
 CPC_WINDOWS_NEWWINDOW    Open a new command window
 CPC_WINDOWS_GRAPH        Nothing happens, this is a submenu
 CPC_WINDOWS_TEXTWFONT    Select command window font
 CPC_WINDOWS_GOTOTOP      Scroll to top of output pane
 CPC_WINDOWS_GOTOEND      Scroll to bottom of output frame
 CPC_WINDOWS_GOTOCOMMANDPOINT  Move focus to end of command pane


_E_O_F_#This should be the last line, an internal End Of File marker
