@database arexx.guide
@author "Janne Jalkanen"
@(c) "Janne Jalkanen 1996"
@$VER: arexx.guide 1.0 (27-Jan-96)

@wordwrap

@node Main "PPT Arexx interface"

                   @{fg highlight}THE AREXX INTERFACE@{fg text}


    No self-respecting Amiga program comes without Arexx port. So I've
    included one, too. Currently, there are not very many commands
    available, I'm afraid but the list is growing, day by day...

    This list is currently in alphabetical order.  A good idea might
    be to order them by context or something...

        @{" COPYFRAME   " link CopyFrame}
	@{" CROP        " link Crop}

        @{" DELETEFRAME " link DeleteFrame}

        @{" EFFECTINFO  " link EffectInfo}
        @{" FRAMEINFO   " link FrameInfo}

        @{" GETAREA     " link GetArea}
        @{" GETRENDERPREFS " link GetRenderPrefs}

        @{" LISTEFFECTS " link ListEffects}
        @{" LISTLOADERS " link ListLoaders}
        @{" LOADERINFO  " link LoaderInfo}
        @{" LOADFRAME   " link LoadFrame}

        @{" PROCESS     " link Process}
        @{" RENAMEFRAME " link RenameFrame}
        @{" RENDER      " link Render}

        @{" SAVEFRAMEAS " link SaveFrameAs}
        @{" SETAREA     " link SetArea}
        @{" SETRENDERPREFS " link SetRenderPrefs}

        @{" VERSION     " link Version}

        @{" QUIT        " link Quit}

@endnode


@node CopyFrame "AREXX: COPYFRAME"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    COPYFRAME FRAME/A/N

@{b}INPUTS@{ub}
    FRAME = frame to be duplicated.

@{b}OUTPUTS@{ub}
    RC = 0, if succeeded
    RESULT = new frame id.

@{b}DESCRIPTION@{ub}
    Use this command to make a complete duplicate of a frame.  The only
    thing differing from the original frame is the name.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@node Crop "AREXX: CROP"

@{b}MENU@{ub}
    Edit/Crop

@{b}AREXX Command Template@{ub}
    CROP FRAME/A/N

@{b}INPUTS@{ub}
    FRAME = frame

@{b}OUTPUTS@{ub}
    A smaller frame

@{b}DESCRIPTION@{ub}
    Crops away the area outside the selected area.

    Use the SETAREA command to first set the area to be cropped!    

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node LoadFrame "AREXX: LOADFRAME"

@{b}MENU@{ub}
    Project/Load

@{b}AREXX Command Template@{ub}
    LOADFRAME FILE/A

@{b}INPUTS@{ub}
    FILE = the file to be loaded.

@{b}OUTPUTS@{ub}
    rc = 0, if succeeded.
    RESULT = new frame id.

@{b}DESCRIPTION@{ub}
    Loads a new frame to the PPT.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode



@node DeleteFrame "AREXX: DELETEFRAME"

@{b}MENU@{ub}
    Project/Delete

@{b}AREXX Command Template@{ub}
    DELETEFRAME FRAME/A/N,FORCE/S

@{b}INPUTS@{ub}
    FRAME - the frame ID.
    FORCE - If not specified, a confirmation requestor
        is shown.

@{b}OUTPUTS@{ub}
    A lot more free memory.

@{b}DESCRIPTION@{ub}
    Deletes the frame completely. No traces. You will be asked
    for a confirmation first, of course.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@remark ---------------------------------------------------------
@remark         AREXX Commands
@remark ---------------------------------------------------------

@node LISTLOADERS "AREXX: LISTLOADERS"

@{b}MENU@{ub}
    Project/Modules/Loaders

@{b}AREXX Command Template@{ub}
    LISTLOADERS STEM/A,ONLYLOADERS/S,ONLYSAVERS/S

@{b}INPUTS@{ub}
    STEM - a variable to be filled with data.
        STEM.0 - amount of loaders
        STEM.1 - first loader name,
        STEM.2 - second loader name
        ...
    ONLYLOADERS - specify if you do not want to see any savers
    ONLYSAVERS - specify if you do not want to see any loaders

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Returns available loaders in the system. By using the
    switches you may specify which kind of loaders you want
    to see.

@{b}BUGS@{ub}
    The switches are not very clear.

@{b}SEE ALSO@{ub}
    @{ "LISTEFFECTS" link ListEffects }, @{"LOADERINFO" link LoaderInfo}

@endnode

@node LoaderInfo "AREXX: LOADERINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    LOADERINFO LOADER/A,STEM/A

@{b}INPUTS@{ub}
    LOADER - The loader name you wish info on.
    STEM - A stem variable telling where the info should be put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Gets information on a given loader. The stem is filled out as follows:
        STEM.VERSION - Version number
        STEM.REVISION - Revision number
        STEM.AUTHOR - The author of this module
        STEM.INFOTXT - A short blurb describing this module.
        STEM.LOAD - 1, if this loader is capable of loading
        STEM.SAVETC - 1, if this loader saves truecolor images
        STEM.SAVECM - 1, if this loader saves colormapped images
        STEM.REXXTEMPLATE - String containing the AREXX command template
            for this loader.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{ "EFFECTINFO" link EffectInfo}, @{ "LISTLOADERS" link ListLoaders}.

@endnode


@node EffectInfo "AREXX: EFFECTINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    EFFECTINFO EFFECT/A,STEM/A

@{b}INPUTS@{ub}
    EFFECT - The effect name you wish info on.
    STEM - A stem variable telling where the info should be put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    Gets information on a given effect. The stem is filled out as follows:
        STEM.VERSION - Version number
        STEM.REVISION - Revision number
        STEM.AUTHOR - The author of this module
        STEM.INFOTXT - A short blurb describing this module.
        STEM.REXXTEMPLATE - String containing the AREXX command template
            for this effect.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{ "LOADERINFO" link LoaderInfo}, @{ "LISTEFFECTS" link ListEffects}.

@endnode


@node ListEffects "AREXX: LISTEFFECTS"

@{b}MENU@{ub}
    Project/Modules/Filters

@{b}AREXX Command Template@{ub}
    LISTEFFECTS STEM/A

@{b}INPUTS@{ub}
    STEM - specifies a stem variable to be affected. Hereforth
        referenced to as stem.

@{b}OUTPUTS@{ub}
    The stem.0 - compound symbol contains the number of possible
    effects. The names of the effects will be from compound
    symbol stem.1 onward.

@{b}DESCRIPTION@{ub}
    Use this to get a listing of all possible effects at your
    disposal.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"EFFECTINFO" link EffectInfo}, @{"LISTLOADERS" link ListLoaders}.

@endnode


@node FrameInfo "AREXX: FRAMEINFO"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    FRAMEINFO FRAME/A/N,STEM/A

@{b}INPUTS@{ub}
    FRAME - frame ID
    STEM - a stem variable where the information is put.

@{b}OUTPUTS@{ub}
    RC = 0, if no error. Otherwise RC2 will contain a string
    describing the error.

@{b}DESCRIPTION@{ub}
    The stem variable is filled as follows:
        STEM.NAME - The name for this frame
        STEM.FILENAME - The actual path for the file on disk.
        STEM.HEIGHT - Height of the image
        STEM.WIDTH - Width of the image
        STEM.COLORSPACE - A number describing the colorspace. See
            ppt.h for more info.
        STEM.COMPONENTS - # of components / pixel.
        STEM.XASPECT, STEM.YASPECT - X and Y aspect ratios for the image.
        STEM.BYTESPERROW - How many bytes does one row occupy

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node SetArea "AREXX: SETAREA"

@{b}MENU@{ub}
    NA

@{b}AREXX Command Template@{ub}
    SETAREA FRAME/A,X0/N,Y0/N,X1/N,Y1/N,ALL/S

@{b}INPUTS@{ub}
    FRAME  = frame name
    X0, Y0 = Co-ordinates of the upper left-hand corner
    X1, Y1 = Co-ordinates of the lower right-hand corner
    ALL    = Specify if you wish to select the whole picture

    If ALL is specified on the command line, the co-ordinates
    are ignored.

@{b}OUTPUTS@{ub}
    RC = 5, if the co-ordinates were out of bounds or there
    were not enough of them.

@{b}DESCRIPTION@{ub}
    Set the area to be used with processing applications.

@endnode


@node Quit "AREXX: QUIT"

@{b}MENU@{ub}
    @{"Project/Quit" link ppt.guide/quit} (Q)

@{b}AREXX Command Template@{ub}
    QUIT FORCE/S

@{b}INPUTS@{ub}
    Specify FORCE on the command line if you don't wish the selection
    to be confirmed.

@{b}OUTPUTS@{ub}
    RC = 5, if the user cancelled, 0 otherwise.

@{b}DESCRIPTION@{ub}
    You may quit the program by selecting this. You will be asked first for
    confirmation, of course, unless the FORCE - keyword is specified.

@endnode


@node Process "AREXX: PROCESS"

@{b}MENU@{ub}
    @{"Process/Process..." link ppt.guide/process}

@{b}AREXX Command Template@{ub}
    PROCESS FRAME/A/N EFFECT/A ARGS/F

@{b}INPUTS@{ub}
    FRAME  - frame id
    EFFECT - the name of the effect you wish to perform
    ARGS   - all the rest of the command line is understood as
             arguments for the effect. See @{"effects" link effects/Main} for more
             information.

@{b}OUTPUTS@{ub}
    RC != 0 on error.
    RC2 = a textual description of the error.

@{b}DESCRIPTION@{ub}
    Start up a new process.  Note that this command is blocking, ie.
    even though a new process is started this command does not return
    until it has completed.  However, it does not block PPT and you
    may still run other Arexx scripts or use the program manually
    while this command is executing.

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode


@node SetRenderPrefs "AREXX: SETRENDERPREFS"

@{b}MENU@{ub}
    @{"Render/Settings..." link ppt.guide/RenderSettings}

@{b}AREXX Command Template@{ub}
    SETRENDERPREFS FRAME/A/N PREFS/A

@{b}INPUTS@{ub}

@{b}OUTPUTS@{ub}

@{b}DESCRIPTION@{ub}
    N/A

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode

@node GetRenderPrefs "AREXX: GETRENDERPREFS"

@{b}MENU@{ub}
    N/A

@{b}AREXX Command Template@{ub}
    GETRENDERPREFS FRAME/A/N PREFS/A

@{b}INPUTS@{ub}
    PREFS - a stem into which the preferences are put.

@{b}OUTPUTS@{ub}
    RC != 0 on error.

@{b}DESCRIPTION@{ub}
    The PREFS stem consists of following elements after the command
    has returned:

    MODEID  = current mode id
    DEPTH   = display depth
    NCOLORS = number of colors
    DITHER  = string telling the current dithering method
    MODE    = render mode (Normal, EHB, HAM6, HAM8)

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}
    @{"SETRENDERPREFS" link SetRenderPrefs},
    @{"Render/Settings..." link ppt.guide/RenderSettings}

@endnode


@node empty

@{b}MENU@{ub}

@{b}AREXX Command Template@{ub}

@{b}INPUTS@{ub}

@{b}OUTPUTS@{ub}

@{b}DESCRIPTION@{ub}

@{b}BUGS@{ub}

@{b}SEE ALSO@{ub}

@endnode