home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / tools / workbench / madhouse / developer / autodocs / madblankersupport.doc
Encoding:
Text File  |  1998-02-04  |  20.6 KB  |  783 lines
  1. TABLE OF CONTENTS
  2.  
  3. madblankersupport.library/--overview--
  4. madblankersupport.library/MBS_AllocPalette
  5. madblankersupport.library/MBS_BeginAutoCycling
  6. madblankersupport.library/MBS_ClearMousePointer
  7. madblankersupport.library/MBS_ColorCycleStep
  8. madblankersupport.library/MBS_ContinueBlanking
  9. madblankersupport.library/MBS_DebugMode
  10. madblankersupport.library/MBS_EndAutoCycling
  11. madblankersupport.library/MBS_ErrorReport
  12. madblankersupport.library/MBS_FreePalette
  13. madblankersupport.library/MBS_GetBlankjob
  14. madblankersupport.library/MBS_GetColorPrefs
  15. madblankersupport.library/MBS_GetFontPrefs
  16. madblankersupport.library/MBS_GetPaletteColor
  17. madblankersupport.library/MBS_GetPrefs
  18. madblankersupport.library/MBS_GetScreenmodePrefs
  19. madblankersupport.library/MBS_GetScreenmodePrefs
  20. madblankersupport.library/MBS_GetScreenPalette
  21. madblankersupport.library/MBS_GetStringPrefs
  22. madblankersupport.library/MBS_PaletteSpread
  23. madblankersupport.library/MBS_PutPaletteColor
  24. madblankersupport.library/MBS_Quit
  25. madblankersupport.library/MBS_RefreshPalette
  26. madblankersupport.library/MBS_SetPaletteScreen
  27. madblankersupport.library/--overview-- madblankersupport.library/--overview--
  28.  
  29.    NAME
  30.     --overview-- -- overview
  31.  
  32.    SYNOPSIS
  33.     --overview--();
  34.  
  35.  
  36.     void --overview-- (void);
  37.  
  38.    NOTE
  39.     madblankersupport.library is used for all blanker communication with
  40.     Madhouse.  Please note that some functions have to be called in a
  41.     special order:
  42.  
  43.     - Open the library.  Please use the latest version.
  44.  
  45.     - Call MBS_DebugMode() if you want to run the blanker yourself,
  46.       delete this call when compiling a blanker for Madhouse.
  47.  
  48.     - Call MBS_GetBlankjob().
  49.  
  50.     - Call any other function.  Maybe you first want to get the blanker's
  51.       settings using MBS_GetPrefs() and others.
  52.  
  53.     - Open your screen.  You could do that before, but hopefully the
  54.       screen mode is configurable, so you have to
  55.       MBS_GetScreenmodePrefs() first.
  56.  
  57.     - Main loop.  Draw graphics and so on...  ask MBS_ContinueBlanking()
  58.       for a result !=0, which means that you have to exit the main loop.
  59.  
  60.     - Close your screen.
  61.  
  62.     - Call MBS_Quit() after closing the screen.
  63.  
  64.     - Close the library and all other stuff.
  65.  
  66.    SEE ALSO
  67.     MBS_DebugMode(), MBS_GetBlankjob(), MBS_GetPrefs(),
  68.     MBS_ContinueBlanking(), MBS_Quit()
  69.  
  70. madblankersupport.library/MBS_AllocPalette
  71.  
  72.    NAME
  73.     MBS_AllocPalette -- Allocate an internal palette structure.  (V26)
  74.  
  75.    SYNOPSIS
  76.     palette = MBS_AllocPalette();
  77.     d0
  78.  
  79.     APTR MBS_AllocPalette (void);
  80.  
  81.    FUNCTION
  82.     You can manipulate this palette using the supplied functions.  They
  83.     all feature the OS 2.x 4bit per gun definition and the OS 3.x 32bit
  84.     per gun definition transparently, taking a lot of problems off your
  85.     shoulders.
  86.  
  87.    RESULT
  88.     palette (d0) - black box pointer to the internal palette.  May be
  89.         NULL if there is not enough memory available.
  90.  
  91.    SEE ALSO
  92.     MBS_FreePalette(), MBS_SetPaletteScreen()
  93.  
  94. madblankersupport.library/MBS_BeginAutoCycling
  95.  
  96.    NAME
  97.     MBS_BeginAutoCycling -- Starts automatic color cycling, using a
  98.     detached Process.  (V26)
  99.  
  100.    SYNOPSIS
  101.     MBS_BeginAutoCycling( palette, start, end, direction, steps, delay );
  102.                   a2       a1     a0   d2          d1     d0
  103.  
  104.     void MBS_BeginAutoCycling( APTR palette, LONG start, LONG end, LONG
  105.         direction, LONG steps, LONG delay );
  106.  
  107.    FUNCTION
  108.     Color cycling goes without further triggering from the blanker task
  109.     and can be stopped using MBS_EndAutoCycling().    The blanker process
  110.     and a color cycling process will run simultaneously.
  111.  
  112.    INPUTS
  113.     palette - pointer to the internal palette.
  114.  
  115.     start - the first palette entry to be cycled (inclusive).
  116.  
  117.     end - the last palette entry to be cycled (inclusive).    Note that
  118.         start < end is required.
  119.  
  120.     direction - for incremental color cycling, use 1.  Any other input
  121.         will result in decremental cycling (backwards).
  122.  
  123.     steps - when using a higher number that 1, more steps than one will
  124.         be done with one function call of MBS_ColorCycleStep().  This
  125.         function is called from the detached Process.
  126.  
  127.     delay - delay in 1/50s between two cycling events.  (Delay() will be
  128.         called.)
  129.  
  130.    WARNING
  131.     Stop this effect before closing the screen!
  132.  
  133.     Do not use other color manipulating/cycling functions before doing an
  134.     MBS_EndAutoCycling()!
  135.  
  136.    SEE ALSO
  137.     MBS_EndAutoCycling()
  138.  
  139. madblankersupport.library/MBS_ClearMousePointer
  140.  
  141.    NAME
  142.     MBS_ClearMousePointer -- Lets the mouse cursor vanish.
  143.  
  144.    SYNOPSIS
  145.     MBS_ClearMousePointer( screen );
  146.                    d0
  147.  
  148.     void MBS_ClearMousePointer( struct Screen *screen );
  149.  
  150.    FUNCTION
  151.     Set an empty mouse pointer image on all windows currently opened on
  152.     the screen.
  153.  
  154.    INPUTS
  155.     screen - pointer to struct Screen of the screen which should get its
  156.         mouse pointer erased.
  157.  
  158. madblankersupport.library/MBS_ColorCycleStep
  159.  
  160.    NAME
  161.     MBS_ColorCycleStep -- cycles your palette one step and displays it.
  162.     (V26)
  163.  
  164.    SYNOPSIS
  165.     MBS_ColorCycleStep( palette, start, end, direction, steps );
  166.                 a1         a0     d2     d1        d0
  167.  
  168.     void MBS_ColorCycleStep( APTR palette, LONG start, LONG end, LONG
  169.         direction, LONG steps );
  170.  
  171.    FUNCTION
  172.     This will color-cycle your palette.  A LoadRBG4/32 call will be done,
  173.     so you'll see the results directly after the call of this function.
  174.  
  175.    INPUTS
  176.     palette - pointer to the internal palette
  177.  
  178.     start - the first palette entry to be cycled (inclusive)
  179.  
  180.     end - the last palette entry to be cycled (inclusive).    Note that
  181.         start < end is required.
  182.  
  183.     direction - for incremental color cycling, use 1.  Any other input
  184.         will result in decremental cycling (backwards).
  185.  
  186.     steps - when using a higher number that 1, more steps than one will
  187.         be done with one function call of MBS_ColorCycleStep().
  188.  
  189.    SEE ALSO
  190.     MBS_BeginAutoCycling()
  191.  
  192. madblankersupport.library/MBS_ContinueBlanking
  193.  
  194.    NAME
  195.     MBS_ContinueBlanking -- Get server blanking state.
  196.  
  197.    SYNOPSIS
  198.     continue = MBS_ContinueBlanking();
  199.     D0
  200.  
  201.     LONG MBS_ContinueBlanking (void);
  202.  
  203.    FUNCTION
  204.     You should ask MBS_ContinueBlanking() very often, maybe even in a
  205.     tight loop.  Experiment with exit speeds.  Return values:
  206.  
  207.     - MBSCB_CONTINUE (0) -- Just continue.
  208.  
  209.     - MBSCB_TIMEOUT (1) -- The user has set a `duration' for your
  210.       Blanker, this time is now expired.  The blanker may continue for
  211.       some seconds, maybe to finish an effect.  As an example, the Soccer
  212.       blanker moves all players out of view.
  213.  
  214.     - MBSCB_USERABORT (2) -- Abort as fast as possible, a user defined
  215.       event (e.g.  a mouse click) has happened.
  216.  
  217.    RESULT
  218.     continue (D0) - Continue state, to be asked in a blanker's main loop.
  219.         At the moment, three results are possible, a result of 0 will
  220.         always mean that the blanker can continue.
  221.  
  222.    NOTE
  223.     When running in Debug Mode, only mouse clicks are considered an
  224.     event, and timeout is after 120 seconds.
  225.  
  226.     (v27.7) CTRL_C signal is checked, also.  MSCB_USERABORT will be
  227.     returned in case the signal is set.  This is useful for debugging
  228.     (Madhouse)...
  229.  
  230.    SEE ALSO
  231.     MBS_DebugMode()
  232.  
  233. madblankersupport.library/MBS_DebugMode
  234.  
  235.    NAME
  236.     MBS_DebugMode -- run blanker in Debug Mode
  237.  
  238.    SYNOPSIS
  239.     MBS_DebugMode();
  240.  
  241.  
  242.     void MBS_DebugMode (void);
  243.  
  244.    FUNCTION
  245.     Without using that function, you cannot simply run your blanker
  246.     executable out of a shell.  Preferences file and Madhouse server
  247.     aren't granted in that situation.  To test your blanker in a
  248.     programming environment, call MBS_DebugMode() before
  249.     MBS_GetBlankjob().  This will have the following effects:
  250.  
  251.     - Default values are passed in MBS_GetPrefs().
  252.  
  253.     - Locale language is "english".
  254.  
  255.     - Duration time is 120 seconds.
  256.  
  257.    NOTE
  258.     Madhouse cannot run your blanker with a MBS_DebugMode() call in it!
  259.     Don't forget to remove it before you put your blanker executable in
  260.     its Madhouse blanker subdirectory.
  261.  
  262.    BUGS
  263.     This function throws Enforcer hits.
  264.  
  265.    SEE ALSO
  266.     MBS_GetBlankjob(), MBS_GetPrefs()
  267.  
  268. madblankersupport.library/MBS_EndAutoCycling
  269.  
  270.    NAME
  271.     MBS_EndAutoCycling -- stops the automatic color cycling.  (V26)
  272.  
  273.    SYNOPSIS
  274.     MBS_EndAutoCycling();
  275.  
  276.  
  277.     void MBS_EndAutoCycling (void);
  278.  
  279.    WARNING
  280.     Call this function before closing your screen!
  281.  
  282. madblankersupport.library/MBS_ErrorReport
  283.  
  284.    NAME
  285.     MBS_ErrorReport -- Inform Madhouse about an error situation.  Give
  286.     feedback to the user.
  287.  
  288.    SYNOPSIS
  289.     MBS_ErrorReport( text );
  290.              d0
  291.  
  292.     void MBS_ErrorReport( char *text );
  293.  
  294.    FUNCTION
  295.     Madhouse will display your text in an EasyRequester after the user
  296.     aborted your blanker or another one (if your blanker exited because
  297.     of the error situation).  The name of your blanker will be displayed
  298.     in that requester, too.
  299.  
  300.    INPUTS
  301.     text - Pointer to an error text string, max.  500 bytes long.  A copy
  302.         of your string will be kept internally.  Use '\n' to insert
  303.         line feeds.
  304.  
  305.    NOTE
  306.     Calling this function twice will cause the second text to remain.
  307.     This works global for all started blankers: if a second blanker
  308.     throws an error report, too, you'll see the report of the second
  309.     blanker.
  310.  
  311. madblankersupport.library/MBS_FreePalette
  312.  
  313.    NAME
  314.     MBS_FreePalette -- free an internal palette.  (V26)
  315.  
  316.    INPUTS
  317.     palette - black box pointer you got in MBS_AllocPalette().
  318.  
  319. madblankersupport.library/MBS_GetBlankjob
  320.  
  321.    NAME
  322.     MBS_GetBlankjob -- Signal Blanker task activity and get some basic
  323.     information.
  324.  
  325.    SYNOPSIS
  326.     blankjob = MBS_GetBlankjob();
  327.     D0
  328.  
  329.     mbs_blankjob *MBS_GetBlankjob (void);
  330.  
  331.    FUNCTION
  332.     Madhouse gets signaled that your blanker task is happy, up and
  333.     running.  It runs the stopwatch for your blanker and fills the
  334.     mbs_blankjob structure.  It arranges Message Ports for communication
  335.     with Madhouse, and so on.
  336.  
  337.     (v27.7) SigAlloc() is called to receive SIGBREAKF_CTRL_C.
  338.  
  339.    RESULT
  340.     blankjob (D0) - Pointer to read-only data.  Maybe you don't want to
  341.         store this result at all, no library function needs it.  You
  342.         don't have to expect a NULL result.  You can use it to obtain
  343.         the locale language (for error messages) or the
  344.         user-predefined blanking time (if you want your effect to
  345.         `fade out' just before Madhouse tells the blanker to stop
  346.         because of timeout).
  347.  
  348.    WARNING
  349.     You have to call this function, before calling any other support
  350.     function.  You should call it directly after opening this library.
  351.     EXCEPTION: If you want to run your blanker yourself (this is called
  352.     Debug Mode), you have to call MBS_DebugMode() BEFORE MBS_BlankJob().
  353.  
  354.    SEE ALSO
  355.     MBS_DebugMode(), MBS_Quit()
  356.  
  357. madblankersupport.library/MBS_GetColorPrefs
  358.  
  359.    NAME
  360.     MBS_GetColorPrefs -- Get a color preference item, as defined in
  361.     gadget file.
  362.  
  363.    SYNOPSIS
  364.     MBS_GetColorPrefs( ID, storage );
  365.                a0  d0
  366.  
  367.     void MBS_GetColorPrefs( char *ID, mbs_color *storage );
  368.  
  369.    FUNCTION
  370.     Obtain preferences information from Madhouse.  You can call this
  371.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  372.     how often.
  373.  
  374.    INPUTS
  375.     ID - Identifier string, should equal one of the gadget identifiers
  376.         used in the blanker's gadget file.  String comparison is not
  377.         case sensitive.
  378.  
  379.     storage - Pass on a pointer to an initialized mbs_color struct here.
  380.         Data will be overwritten, except when running in Debug Mode
  381.         or no `pref' is file found.
  382.  
  383.    EXAMPLE
  384.     in source code:
  385.     struct mbs_color col;
  386.     col.r = 255;
  387.     col.g = 200;
  388.     col.b = 0;
  389.     MBS_GetColorPrefs( "background", &col );
  390.  
  391.     in gadget file:
  392.     background = Color,
  393.  
  394.    SEE ALSO
  395.     MBS_GetBlankjob(), MBS_Quit()
  396.  
  397. madblankersupport.library/MBS_GetFontPrefs
  398.  
  399.    NAME
  400.     MBS_GetFontPrefs -- Get a font preference item, as defined in gadget
  401.     file.
  402.  
  403.    SYNOPSIS
  404.     MBS_GetFontPrefs( ID, textat, buffer );
  405.               a0  d1      d0
  406.  
  407.     void MBS_GetFontPrefs( char *ID, struct TextAttr *textat, char
  408.         *buffer );
  409.  
  410.    FUNCTION
  411.     Obtain preferences information from Madhouse.  You can call this
  412.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  413.     how often.
  414.  
  415.    INPUTS
  416.     ID - Identifier string, should equal one of the gadget identifiers
  417.         used in the blanker's gadget file.  String comparison is not
  418.         case sensitive.
  419.  
  420.     textat - Pass on a pointer to an initialized struct TextAttr here.
  421.         ta_Name and ta_YSize will be filled in, except when running
  422.         in Debug Mode or no `pref' is file found.  ta_Name will point
  423.         to the given `buffer'.
  424.  
  425.     buffer - Pass on a pointer to your (at least 100 bytes long) buffer
  426.         array.    The font name will be filled in here, ".font" will be
  427.         added.    textat.ta_Name will point to this buffer.  Therefore,
  428.         you should have the buffer in a global variable (or use
  429.         "static").
  430.  
  431.    EXAMPLE
  432.     in source code:
  433.     char buf[100];
  434.     strcpy( buf, "topaz.font" );
  435.     struct TextAttr ta;
  436.     ta.ta_Name = buf;
  437.     ta.ta_YSize = 8;
  438.     ta.ta_Style = 0;
  439.     ta.ta_Flags = 0;
  440.     MBS_GetFontPrefs( "font", &ta, buf );
  441.  
  442.     in gadget file:
  443.     font = Font( "f" ),
  444.  
  445.    SEE ALSO
  446.     MBS_GetBlankjob(), MBS_Quit()
  447.  
  448. madblankersupport.library/MBS_GetPaletteColor
  449.  
  450.    NAME
  451.     MBS_GetPaletteColor -- Get a single color register of the internal
  452.     palette.  (V26)
  453.  
  454.    INPUTS
  455.     palette - pointer to the internal palette
  456.  
  457.     position - register number to get the color from, counted from 0.
  458.  
  459.     color - pointer to a struct color which r,g,b elements will be
  460.         overwritten.
  461.  
  462. madblankersupport.library/MBS_GetPrefs madblankersupport.library/MBS_GetPrefs
  463.  
  464.    NAME
  465.     MBS_GetPrefs -- Get a numeric preference item, as defined in gadget
  466.     file.
  467.  
  468.    SYNOPSIS
  469.     prefvalue = MBS_GetPrefs( ID, default );
  470.     d0              a0  d0
  471.  
  472.     LONG MBS_GetPrefs( char *ID, LONG default );
  473.  
  474.    FUNCTION
  475.     Obtain preferences information from Madhouse.  You can call this
  476.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  477.     how often.
  478.  
  479.    INPUTS
  480.     ID - Identifier string, should equal one of the gadget identifiers
  481.         used in the blanker's gadget file.  String comparison is not
  482.         case sensitive.
  483.  
  484.     default - Default value.  Used if no `pref' file found or running in
  485.         Debug Mode.
  486.  
  487.    RESULT
  488.     prefvalue (d0) - numeric pref value, e.g.  the state of a cycle
  489.         gadget (counted beginning with 0) or a slider or a checkmark
  490.         gadget.  The default is maybe passed on (s.a.).
  491.  
  492.    EXAMPLE
  493.     in source code:
  494.     LONG speed = MBS_GetPrefs( "speed", 3 );
  495.  
  496.     in gadget file:
  497.     speed = Slider( "s", 1, 5 ),
  498.  
  499.    SEE ALSO
  500.     MBS_GetBlankjob(), MBS_Quit()
  501.  
  502. madblankersupport.library/MBS_GetScreenmodePrefs
  503.  
  504.    NAME
  505.     MBS_GetScreenmodePrefs -- Get the screen depth of the user selected
  506.     screen mode.
  507.  
  508.    SYNOPSIS
  509.     depth = MBS_GetScreenmodePrefs( default );
  510.     d0                d0
  511.  
  512.     ULONG MBS_GetScreenmodePrefs( ULONG default );
  513.  
  514.    FUNCTION
  515.     Obtain preferences information from Madhouse.  You can call this
  516.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  517.     how often.
  518.  
  519.    INPUTS
  520.     default - default screen depth.  Used if no `pref' file found or
  521.         running in Debug Mode.    May range from 1 to 8.
  522.  
  523.    RESULT
  524.     depth (d0) - selected screen depth.  `default' may be passed on.  May
  525.         range from 0 to 8.  (0 means that you didn't want a user
  526.         selectable screen depth in your blanker's `gadget' file.)
  527.  
  528.    NOTE
  529.     The screen depth preferences has no identifier.  Only one value can
  530.     be set in MadhouseConfigEd and stored in the `pref' file.
  531.  
  532.    EXAMPLE
  533.     in source code:
  534.     ULONG depth = MBS_GetScreendepthPrefs( 3 );
  535.  
  536.     in gadget file:
  537.     DisplayMode( 3 ),
  538.     3 is default amount of bitplanes. If you don't want a
  539.     user selectable screen depth, use:
  540.     DisplayMode( 0 ),
  541.  
  542.    SEE ALSO
  543.     MBS_GetScreenmodePrefs(), MBS_GetBlankjob(), MBS_Quit()
  544.  
  545. madblankersupport.library/MBS_GetScreenmodePrefs
  546.  
  547.    NAME
  548.     MBS_GetScreenmodePrefs -- Get the Screen Mode ID of the user selected
  549.     display mode.
  550.  
  551.    SYNOPSIS
  552.     ModeID = MBS_GetScreenmodePrefs( default );
  553.     d0                 d0
  554.  
  555.     ULONG MBS_GetScreenmodePrefs( ULONG default );
  556.  
  557.    FUNCTION
  558.     Obtain preferences information from Madhouse.  You can call this
  559.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  560.     how often.
  561.  
  562.    INPUTS
  563.     default - Default Mode ID.  Used if no `pref' file found or running
  564.         in Debug Mode.
  565.  
  566.    RESULT
  567.     ModeID (d0) - selected display mode.  `default' may be passed on.
  568.  
  569.    NOTE
  570.     The Screen Mode preferences has no identifier.    Only one mode can be
  571.     set in MadhouseConfigEd and stored in the `pref' file.
  572.  
  573.    EXAMPLE
  574.     in source code:
  575.     ULONG modeID = MBS_GetScreenmodePrefs( HIRESLACE_KEY );
  576.  
  577.     in gadget file:
  578.     DisplayMode( 3 ),
  579.     3 is default amount of bitplanes. If you don't want a
  580.     user selectable screen depth, use:
  581.     DisplayMode( 0 ),
  582.  
  583.    SEE ALSO
  584.     MBS_GetBlankjob(), MBS_Quit()
  585.  
  586. madblankersupport.library/MBS_GetScreenPalette
  587.  
  588.    NAME
  589.     MBS_GetScreenPalette -- copy the screen's palette to the internal
  590.     palette.  (V26)
  591.  
  592.    SYNOPSIS
  593.     MBS_GetScreenPalette( palette, screen );
  594.                   a0       d0
  595.  
  596.     void MBS_GetScreenPalette( APTR palette, struct Screen *screen );
  597.  
  598.    FUNCTION
  599.     The internal palette will be filled with the color data of the given
  600.     screen.  Useful for blankers which copy a screen to make effects on
  601.     the Workbench.
  602.  
  603.    INPUTS
  604.     palette - pointer to the internal palette
  605.  
  606.     screen - screen to get the palette information from
  607.  
  608.    NOTE
  609.     This function will perform an MBS_SetPaletteScreen() call with the
  610.     given screen as an argument.  If you pass a screen that is not yours,
  611.     call MBS_SetPaletteScreen() will your own screen afterwards.
  612.  
  613. madblankersupport.library/MBS_GetStringPrefs
  614.  
  615.    NAME
  616.     MBS_GetStringPrefs -- Get a text string preference item, as defined
  617.     in gadget file.
  618.  
  619.    SYNOPSIS
  620.     MBS_GetStringPrefs( ID, storage );
  621.                 a0    d0
  622.  
  623.     void MBS_GetStringPrefs( char *ID, char *storage );
  624.  
  625.    FUNCTION
  626.     Obtain preferences information from Madhouse.  You can call this
  627.     function any time between MBS_GetBlankjob() and MBS_Quit(), no matter
  628.     how often.
  629.  
  630.    INPUTS
  631.     ID - Identifier string, should equal one of the gadget identifiers
  632.         used in the blanker's gadget file.  String comparison is not
  633.         case sensitive.
  634.  
  635.     storage - Pass on a pointer to an initialized array of char here.
  636.         Data will be overwritten, except when running in Debug Mode
  637.         or no `pref' is file found.  Make the array big enough so
  638.         that the string fits (maximum string length is defined in
  639.         `gadget' file).
  640.  
  641.    EXAMPLE
  642.     in source code:
  643.     char text[150];
  644.     strcpy( text, "Oh, what a night!" );
  645.     MBS_GetStringPrefs( "message", text );
  646.  
  647.     in gadget file:
  648.     message = String( "m", 150 ),
  649.  
  650.    SEE ALSO
  651.     MBS_GetBlankjob(), MBS_Quit()
  652.  
  653. madblankersupport.library/MBS_PaletteSpread
  654.  
  655.    NAME
  656.     MBS_PaletteSpread -- Make a spread between two palette registers.
  657.     (V26)
  658.  
  659.    SYNOPSIS
  660.     MBS_PaletteSpread( palette, start, stop );
  661.                a0        d1       d0
  662.  
  663.     void MBS_PaletteSpread( APTR palette, LONG start, LONG stop );
  664.  
  665.    FUNCTION
  666.     An RGB color spread will be generated in between the given register
  667.     numbers.
  668.  
  669.    INPUTS
  670.     palette - pointer to the internal palette.
  671.  
  672.     start - first color of the spread.
  673.  
  674.     stop - second color of the spread.
  675.  
  676.    NOTE
  677.     Take care: start <= stop.
  678.  
  679.     This won't change anything onscreen, since the palette isn't updated
  680.     automatically.
  681.  
  682.    SEE ALSO
  683.     MBS_RefreshPalette()
  684.  
  685. madblankersupport.library/MBS_PutPaletteColor
  686.  
  687.    NAME
  688.     MBS_PutPaletteColor -- Set a single color register of the internal
  689.     palette.  (V26)
  690.  
  691.    SYNOPSIS
  692.     MBS_PutPaletteColor( palette, position, color );
  693.                  a0       d1    d0
  694.  
  695.     void MBS_PutPaletteColor( APTR palette, LONG position, struct
  696.         mbs_color *color );
  697.  
  698.    INPUTS
  699.     palette - pointer to the internal palette
  700.  
  701.     position - register number to set the color in, counted from 0.
  702.  
  703.     color - pointer to a struct color which defines the color to set.
  704.  
  705.    NOTE
  706.     This won't change anything onscreen, since the palette isn't updated
  707.     automatically.
  708.  
  709.    SEE ALSO
  710.     MBS_RefreshPalette()
  711.  
  712. madblankersupport.library/MBS_Quit       madblankersupport.library/MBS_Quit
  713.  
  714.    NAME
  715.     MBS_Quit -- Signal that blanker task is about to exit.    All screens
  716.     are closed.
  717.  
  718.    SYNOPSIS
  719.     MBS_Quit();
  720.  
  721.  
  722.     void MBS_Quit (void);
  723.  
  724.    FUNCTION
  725.     All allocated memory is flushed.  Madhouse is told to start the next
  726.     blanker (if necessary).
  727.  
  728.    NOTE
  729.     All screens and windows have to be closed at this time, blank mouse
  730.     pointer images and stuff like that are freed now, too.
  731.  
  732.    WARNING
  733.     Don't call any other library function after MBS_Quit()!
  734.  
  735. madblankersupport.library/MBS_RefreshPalette
  736.  
  737.    NAME
  738.     MBS_RefreshPalette -- Updates a screen's palette according to the
  739.     internal palette.  (V26)
  740.  
  741.    SYNOPSIS
  742.     MBS_RefreshPalette( palette, screen );
  743.                 a0         d0
  744.  
  745.     void MBS_RefreshPalette( APTR palette, struct Screen *screen );
  746.  
  747.    FUNCTION
  748.     The given screen will get the palette information from the given
  749.     internal palette.  You must call this function if you want to see the
  750.     changes on screen, which you have made with functions which don't
  751.     update the palette automatically (e.g.    MBS_PutPaletteColor() or
  752.     MBS_PaletteSpread).
  753.  
  754.     This is also useful if you have two screens with the same palette, as
  755.     the screen has to be defined here, again.
  756.  
  757.    INPUTS
  758.     palette - pointer to the internal palette
  759.  
  760.     screen - screen to set the palette on
  761.  
  762. madblankersupport.library/MBS_SetPaletteScreen
  763.  
  764.    NAME
  765.     MBS_SetPaletteScreen -- connect the palette to your screen.  (V26)
  766.  
  767.    SYNOPSIS
  768.     MBS_SetPaletteScreen( palette, screen );
  769.                   a0       d0
  770.  
  771.     void MBS_SetPaletteScreen( APTR palette, struct Screen *screen );
  772.  
  773.    INPUTS
  774.     palette - pointer to the internal palette.
  775.  
  776.     screen - the screen that should be used together with your palette.
  777.         This function will store its Viewport and the amount of
  778.         colors used.
  779.  
  780.    NOTE
  781.     HAM screens will fail.
  782.  
  783.