@Database

@node MAIN

@{b}  MesaOutput - Output handler selector for AmigaMesaRTL
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@{ub}

 @{" 1.Basic functions " LINK "Basic"}

 @{" 2.Advanced CLI launching (AMRTL authors) " LINK "CLI"}

 @{" 3.ParameterQuery (AMRTL developers) " LINK "Query"}

 @{" 4.Readargsgroup.mcc extensions (AMRTL/MUI developers) " LINK "readargs"}



 (C)1998 Szymon Ulatowski  szulat@friko6.onet.pl

@endnode
@node Basic
@{b}Basic Functions
~~~~~~~~~~~~~~~
@{ub}Currently selected handler is marked with an arrow '>' on the left. To select
another one, click on the list and press 'Mark as default' button.
Some handlers (supporting @{"parameter query" LINK "Query"}) can show their own preferences on
the right panel.
There are usual prefs buttons on the bottom (Save, Use, Cancel). When launched
from Shell (or @{"another application" LINK "CLI"}) the additional 'Use local' button appears.
It means the settings will be used by the current process only. (You can open
many shell windows, set the different preferences for each one, and launch
AMRTL applications - they will use different settings).

@endnode
@node CLI
@{b}Advanced CLI Launching
~~~~~~~~~~~~~~~~~~~~~~
@{ub}You can start MesaOutput from within your AMRTL program with usual system()
call. You could eg. add the menu option 'Output preferences'.
Plain "MesaOutput" call gives you the usual preferences window, the user can
change all the setting and apply changes systemwide (Save/Use) or for your
application use only (Use local).
You can call "MesaOutput GLOBAL" to exclude "Use local" button or
"MesaOutput LOCAL" to make the user set the preferences for your process only.
Additional keywords are: LIST (pick the handler from the list, no parameters), 
PARAMS (only the parameters for the given handler are shown,
eg. "MesaOutput grey PARAMS LOCAL").

@endnode
@node Query
@{b}ParameterQuery
~~~~~~~~~~~~~~
@{ub}MesaOutput (and Mesa.mcc page in MUI prefs) can display handler specific
preferences and get/set its values from environment variables.
If you want to make your own handler take advantage of this, you should
do 2 things:

 1.Return parameters template in GetOutputHandlerAttr() for
   AMRTL_ParameterQuery attribute.
   The template is the standard ReadArgs()-compatible template.
   You can use some @{"extensions" LINK "readargs"} to make the interface look better.

 2.During the startup, read the parameter values from OH_Parameters
   attribute and from ENV:AmigaMesaRTL/YOURNAME.prefs (if the OH_Parameters
   is not present).

Example sources are available in AMRTL package.
@endnode

@node readargs
@{b}Readargsgroup.mcc extensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@{ub}Readargsgroup is a simple GUI element for parsing and creating ReadArgs-style
parameter strings. It is used by MesaOutput and Mesa.mcc prefs page.

@{i} refer to Readargsgroup.mcc archive in dev/mui for detailed specification
@{ui}
The extensions:

    - underscores '_' in the argument's names are converted to spaces in
      GUI labels

    - special codes can be put in argument's names to create additional GUI
      elements:

      _LA_any_text - creates a label
      _LA1_any_text - a label with horizontal bar
         labels should be specified as keywords (/K) so they will not cause
         arguement strings to be longer

      _FN_argument - string gadget with filename popup 
      _FO_argument - ... with font popup (format: fontname/size) 
      _SM_argument - ... with screenmode popup (format: 0xHEXNUMBER)

      _MX_switch/S,_MX_secondswitch/S,...
        MX turns a set of checkboxes into mutual exclude radiobutton
        switches beginning with _MX1_ form the second radiobutton group
        _MX2_ - third and so on


example - quickcolor handler uses the following template:

NoDither/S,_LA1_Own_Window_Parameters/K,NAMED=_MX_Public_Screen/S,
DEFAULT=_MX_Default_Screen/S,CUSTOM=_MX_Full_Screen/S,NAME=Screen_Name,
_LA1_Full_Screen_Parameters/K,_SM_Mode,Width/N,Height/N

@endnode