@database "rxaslenglish"
@index "Functions"

@Node "Main" "RxASL - Version 6.0 @ 1999, 2000 Alfonso Ranieri"

    @{u}RxAsl - Version 6.0 © 1999, 2000 Alfonso Ranieri@{uu}

    1. @{"Introduction       " LINK "Introduction"}
    2. @{"Author             " LINK "Author"}
    3. @{"WRID               " LINK "WRID"}
    4. @{"Terms              " LINK "Terms"}
    5. @{"Bugs               " LINK "Bugs"}
    6. @{"Functions          " LINK "Functions"}
@EndNode

@Node "Introduction"

  @{u}1. Introduction@{uu}


    The library is a set of function to manipulate asl.library
    requesters. The library offers supports for AmigaOS3.5
    (asl.library V44).
@EndNode

@Node "Author"

  @{u}2. Author@{uu}


    I am Alfonso Ranieri

    My e-mail address is alforan@tin.it

    You can find me on irc at:
        - #amigaita ircnet
        - #amyita   ircnet

    You can find last version of this library at my home page:
    http://web.tiscalinet.it/amiga/
@EndNode

@Node "WRID" "Warning, Requirements, Installation and Distribution"

  @{u}3. Warning, Requirements, Installation and Distribution@{uu}


    Warning
        THIS SOFTWARE AND INFORMATION ARE PROVIDED @{i}AS IS@{ui}.
        ALL USE IS AT YOUR OWN RISK, AND NO LIABILITY OR
        RESPONSIBILITY IS ASSUMED. NO WARRANTIES ARE MADE.

    Requirements
        The library needs AmigaOS, version 3 or higher.

    Installation
        Use the installation script.

    Distribution
        RxAsl is FreeWare.

        You are free to distribute it as long as the original archive
        is kept intact. Commercial use or its inclusion in other
        software package is prohibited without prior written consents
        from the Author.
@EndNode

@Node "Terms"

  @{u}4. Terms@{uu}


    The main terms used are:

        o stem or stemName: a valid ARexx variable name e.g. var,
          var.0, var.name

        o types of arguments: the types used are:
            D   any data            --
            N   numeric             /N
            S   symbol              /S ARexx valid symbol
            V   stemName            /V ARexx valid symbol as S but
                                       with length<20
@EndNode

@Node "Bugs"

  @{u}5. Bugs@{uu}


    None knows.
@EndNode

@Node "Functions"

  @{u}6. Functions@{uu}


    The functions have also the "RXASL_"FunctionName form to avoid
    conflicts with functions from other libraries.


    @{"GetRxAslString" LINK "GetRxAslString"}
    @{"Help          " LINK "Help"}
    @{"ReqFile       " LINK "ReqFile"}
    @{"ReqFont       " LINK "ReqFont"}
    @{"ReScreen      " LINK "ReqScreen"}
@EndNode

@Node "GetRxAslString"

  @{b}GetRxAslString@{ub} - returns a localized RxAsl string


  @{b}Synopsis@{ub}
    string = GetRxAslString(id)
    <id/N>


  @{b}Function@{ub}
    Returns a localized RxAsl string.

    @{i}id@{ui} id one of
        o 51  [NO_MEM]        too few memory
        o 52  [ARG_MISS]      required argument missing
        o 53  [BAD_NUMBER]    bad number
        o 54  [BAD_VALUE]     bad value
        o 55  [BAD_PATTERN]   bad pattern
        o 56  [NO_WINDOW]     window not found
        o 57  [NO_SCREEN]     public screen not found


  @{b}Inputs@{ub}
    id - an integer


  @{b}Result@{ub}
    string - a RxAsl localized string
@EndNode

@Node "Help"

  @{b}help@{ub} - returns a RxAsl function help strings.


  @{b}Synopsis@{ub}
    string = Help(funName)
    <funName/S>


  @{b}Function@{ub}
    Returns the arguments types mask of the function @{i}funName@{ui}.


  @{b}Inputs@{ub}
    funName - a RxAsl function name


  @{b}Result@{ub}
    string - a help string
@EndNode

@Node "ReqFile"

  @{b}ReqFile@{ub} - shows a file requester


  @{b}Synopsis@{ub}
    res = ReqFile(stem)
    <stem/V>


  @{b}Function@{ub}
    Shows a file requester.

    In @{i}stem@{ui} you may set the fields:

        o Window

            . WINDOW S This is a name of a RxMUI Window object
                       or a RxWiz SURFACE/WINDOW pair.
                       If the window is found, it is put to sleep.

            . PUBSCREEN S This is the name of a public screen. If
                          it is found, the requester is opened on
                          it, otherwise, the reeuster is opened on
                          the default public screen if and only if
                          FALLBACK is 1.

            . FALLBACK B See PUBSCREEN, default 0 .

            . SLEEPWINDOW B

            . NTSCREENTOFRONT B The screen, the requester opens on,
                                is put to front by default. Setting
                                it to 0 causes the screen to not be
                                put to front.

        o Text

            . TITLE S

            . POSITIVETEXT S

            . NEGATIVETEXT S

        o Initial settings

            . LEFTEDGE N Default 0.

            . TOPEDGE N Default 0.

            . WIDTH N Default 50% of screen width .

            . HEIGHT N Default 50% of screen height .

            . FILE S

            . DRAWER S

            . PATTERN S

            . SHOWVOLUMES B Only asl.library V44 (AmigaOS 3.5)

        o Options

            . DOSAVEMODE B

            . DOMULTISELECT B

            . DOPATTERNS B

            . NOEMPTY B if set and the user enters an empty file
                        name the result of ReqFile() will be -1,
                        like the user pressed "Cancel" button
                        if not set and the user enters an empty
                        file name, an empty file name is returned;
                        it is only valid for file requester not
                        for drawer requester, because epmty drawer
                        name means CurrentDir.

        o Filtering

            . DRAWERSONLY B

            . FILTERFUNC S This is an ARexx macro, for each entry in
                           the requester, before the entry is shown.
                           The macro is called as a function with
                           argument:
                            - entry name
                            - drawer name
                            - AnchorPat pointer
                            If and only if the function returns 0, the
                            entry is not shown (e.g. if the function
                            fails, the entry is shown).

            . FILTERSTRING B FILTERFUNC is a string-inline function.

            . REJECTICONS B

            . REJECTPATTERN S

            . ACCEPTPATTERN S

            . FILTERDRAWERS B

        o Sorting - Only asl.library V44 (AmigaOS 3.5)

            . SORTBY N or "NAME" "DATE" "SIZE"

            . SORTDRAWERS N or "FIRST" "MIX" "LAST"

            . SORTORDER N or "ASCEND" "DESCENT"


    The function writes in @{i}stem@{ui}:

        o LEFTEDGE N

        o TOPEDGE N

        o WIDTH N

        o HEIGHT N

        o FILE S

        o DRAWER S

        o PATTERN S

        o SORTBY N      Only asl.library V44 (AmigaOS 3.5)

        o SORTDRAWERS N Only asl.library V44 (AmigaOS 3.5)

        o SORTORDER N   Only asl.library V44 (AmigaOS 3.5)


  @{b}Inputs@{ub}
    stem - an ARexx stem name


  @{b}Result@{ub}
    res - an integer:
            o -1 the user exit from the requester
            o  0 OK
            o >0 error code - use @{"GetRxAslString" LINK "GetRxAslString"} to get the string
                 RXASLERROR is also set to the field name that caused the error.
@EndNode

@Node "ReqFont"

  @{b}ReqFont@{ub} - shows a file requester


  @{b}Synopsis@{ub}
    res = ReqFont(stem)
    <stem/V>


  @{b}Function@{ub}
    Shows a font requester.

    In @{i}stem@{ui} you may set the fields:

        o Window

            . WINDOW S This is a name of a RxMUI Window object
                       or a RxWiz SURFACE/WINDOW pair.
                       If the window is found, it is put to sleep.

            . PUBSCREEN S This is the name of a public screen. If
                          it is found, the requester is opened on
                          it, otherwise, the reeuster is opened on
                          the default public screen if and only if
                          FALLBACK is 1.

            . FALLBACK B See PUBSCREEN, default 0 .

            . SLEEPWINDOW B

            . NTSCREENTOFRONT B The screen, the requester opens on,
                                is put to front by default. Setting
                                it to 0 causes the screen to not be
                                put to front.

        o Text

            . TITLE S

            . POSITIVETEXT S

            . NEGATIVETEXT S

        o Initial settings

            . LEFTEDGE N

            . TOPEDGE N

            . WIDTH N

            . HEIGHT N

            . NAME S

            . SIZE N

            . STYLE N or one or more of "NORMAL" "UNDERLINE" "BOLD"
                                        "ITALIC" "COLORFONT"

            . FLAGS N

            . FRONTPEN N

            . BACKPEN N

            . DRAWMODE N or "JAM1" "JAM2" "COMPLEMENT" "INVERSVID"

        o Options

            . DOFLAGS B

            . DOFRONTPEN B

            . DOBACKPEN B

            . DOSTYLE B

            . DODRAWMODE B

        o Filtering

            . FIXEDWIDTHONLY B

            . MINHEIGHT N

            . MAXHEIGHT N

            . FILTERFUNC S This is an ARexx macro, for each entry in
                           the requester, before the entry is shown.
                           The macro is called as a function with
                           argument:
                            - entry name
                            - YSize
                            - struct TextAttr pointer
                            If and only if the function returns 0,
                            the entry is not shown (e.g. if the
                            function fails, the entry is shown).

            . FILTERSTRING B FILTERFUNC is a string-inline function.

            . MAXFRONTPEN N

            . MAXBACKPEN N

    The function writes in @{i}stem@{ui}:

        o LEFTEDGE N

        o TOPEDGE N

        o WIDTH N

        o HEIGHT N

        o NAME N

        o SIZE N

        o STYLE N

        o FLAGS N

        o DRAWMODE N

        o FRONTPEN N

        o BACKPEN N


  @{b}Inputs@{ub}
    stem - an ARexx stem name


  @{b}Result@{ub}
    res - an integer:
            o -1 the user exit from the requester
            o  0 OK
            o >0 error code - use @{"GetRxAslString" LINK "GetRxAslString"} to get the string
                 RXASLERROR is also set to the field name that caused the error.
@EndNode

@Node "ReqScreen"

  @{b}ReqScreen@{ub} - shows a screen requester


  @{b}Synopsis@{ub}
    res = ReqScreen(stem)
    <stem/V>


  @{b}Function@{ub}
    Shows a screen requester.

    In @{i}stem@{ui} you may set the fields:

        o Window

            . WINDOW S This is a name of a RxMUI Window object
                       or a RxWiz SURFACE/WINDOW pair.
                       If the window is found, it is put to sleep.

            . PUBSCREEN S This is the name of a public screen. If
                          it is found, the requester is opened on
                          it, otherwise, the reeuster is opened on
                          the default public screen if and only if
                          FALLBACK is 1.

            . FALLBACK B See PUBSCREEN, default 0 .

            . SLEEPWINDOW B

            . NTSCREENTOFRONT B The screen, the requester opens on,
                                is put to front by default. Setting
                                it to 0 causes the screen to not be
                                put to front.

        o Text

            . TITLE S

            . POSITIVETEXT S

            . NEGATIVETEXT S

        o Initial settings

            . LEFTEDGE N

            . TOPEDGE N

            . WIDTH N

            . HEIGHT N

            . DISPLAYID N

            . DISPLAYWIDTH N

            . DISPLAYHEIGHT N

            . DISPLAYDEPTH N

            . OVERSCAN N or "TEXT" "STANDARD" "MAX" "VIDEO"

            . AUTOSCROLL B

            . INFOOPENED B

            . INFOLEFTEDGE N

            . INFOTOPEDGE N

        o Options

            . DOWIDTH B

            . DOHEIGHT B

            . DODEPTH B

            . DOOVERSCAN B

            . DOAUTOSCROLL B

        o Filtering

            . PROPERTYFLAGS N

            . PROPERTYMASK N

            . MINWIDTH N

            . MAXWIDTH N

            . MINHEIGHT N

            . MAXHEIGHT N

            . MINDEPTH N

            . MAXDEPTH N

            . FILTERFUNC S This is an ARexx macro, for each entry
                           in the requester, before the entry is
                           shown. The macro is called as a function
                           with argument:
                            - screen mode
                            - struct ScreenModeRequester pointer
                           If and only if the function returns 0,
                           the entry is not shown (e.g. if the
                           function fails, the entry is shown).

            . FILTERSTRING B FILTERFUNC is a string-inline function.


    The function writes in @{i}stem@{ui}:

        o LEFTEDGE N

        o TOPEDGE N

        o WIDTH N

        o HEIGHT N

        o DISPLAYID N

        o DISPLAYWIDTH N

        o DISPLAYHEIGHT N

        o DISPLAYDEPTH N

        o OVERSCAN N

        o AUTOSCROLL B

        o INFOOPENED B

        o INFOLEFTEDGE B

        o INFOTOPEDGE B

        o BITMAPWIDTH B

        o BITMAPHEIGHT B


  @{b}Inputs@{ub}
    stem - an ARexx stem name


  @{b}Result@{ub}
    res - an integer:
            o -1 the user exit from the requester
            o  0 OK
            o >0 error code - use @{"GetRxAslString" LINK "GetRxAslString"} to get the string
                 RXASLERROR is also set to the field name that caused the error.
@EndNode