Skip to Content
Amiga Assembly Library v41.21 — Motorola 68020 shared library for Commodore Amiga
DocumentationIntuition & GadToolsAllocAsmRequestA

AllocAsmRequestA

Synopsis

areq = AllocAsmRequestA(TagList)
 D0                       A0

C Prototype

struct AsmRequest *AllocAsmRequestA(struct TagItem *);
 
/* Varargs stub */
struct AsmRequest *AllocAsmRequest(Tag, ...);

Description

Allocates an AsmRequest structure and initializes it according to the TagItem array passed in the inputs. The returned AsmRequest structure is READ-ONLY and must be freed from memory when no longer needed using FreeAsmRequest().

Once initialized, an AsmRequest can be modified, allowing the use of different types of AsmRequests combined together. In practice, there are two approaches to using multiple AsmRequests: initialize as many as needed, or create a single one and modify it via ChangeAsmReqAttrsA() when necessary.

An AsmRequest has all the features of intuition.library/EasyRequest(), with the addition of special functions. The default layout of an AsmRequest is as follows:

+-----------------------------------------+
| . |  TITLE (screen font)             |LL|
+-----------------------------------------+
||                                       ||
|| BODYTEXT (system font)                ||
||                                       ||
+-----------------------------------------+
|                                         |
|          Gadget (screen font)           |
+-----------------------------------------+

An optional Object (image or animation loaded via datatypes.library) can be placed either beside or above the body text. When the AREQ_TextUnderObject tag is set to TRUE, the object is centered above the text.

Buttons are ordered the same way as intuition.library/EasyRequest(): the leftmost button returns the highest value and the rightmost button returns 0.

Keyboard Control — The ESC key exits the requester with a return code of NULL by default. Buttons can be selected via keyboard if the underscore character _ (0x5f) was included in their label string. The RETURN key selects the leftmost button (equivalent to AmigaLeft+V). The RETURN key behavior can be disabled via the AREQ_ReturnKey tag.

Tags

  • AREQ_Left (UWORD) — LeftEdge of the request relative to the output screen.
  • AREQ_Top (UWORD) — TopEdge of the request relative to the output screen.
  • AREQ_REI (struct REI *) — Determines the output screen via a REI structure.
  • AREQ_Window (struct Window *) — Reference window that determines the output screen.
  • AREQ_Screen (struct Screen *) — Address of the output screen. Can be NULL to use the default public screen.
  • AREQ_Title (STRPTR) — Title of the AsmRequest. If NULL, the reference window title is used, or "System Request" as fallback.
  • AREQ_IDCMP (ULONG) — IDCMP flags to handle directly. For each set bit, if that message is received, the AsmRequest lets you exit or handle it yourself. Works with AREQ_IDCMPHook. (Default: NULL)
  • AREQ_IDCMPHook (struct Hook *) — Hook invoked when an IDCMP flag set in AREQ_IDCMP is received. Called with object == (struct REI *) and message == (struct REIMessage *). If the Hook returns ~0, it causes immediate exit. (Default: NULL)
  • AREQ_LockREI (struct REI *) — Address of the REI to put in wait state while the request is displayed. Usually the parent REI.
  • AREQ_Justification (UWORD) — Text justification: ASJ_LEFT, ASJ_RIGHT, ASJ_CENTER.
  • AREQ_Object (Object *) — Pointer to a boopsi object obtained via datatypes.library. Can be any image or animation.
  • AREQ_Sound (Object *) — Pointer to a sound opened via DataTypes. Played when the request opens.
  • AREQ_CenterHScreen (BOOL) — If TRUE, centers the window horizontally on the output screen. (Default: FALSE)
  • AREQ_CenterVScreen (BOOL) — If TRUE, centers the window vertically on the output screen. (Default: FALSE)
  • AREQ_CenterMouse (BOOL) — If TRUE, opens the window so the mouse pointer is at its center. (Default: FALSE)
  • AREQ_TextUnderObject (BOOL) — If TRUE, the text is displayed below the Object (if present). Otherwise the text is placed beside the Object. (Default: FALSE)
  • AREQ_APenPattern (UWORD) — Foreground pen for the default pattern, or for a simple backfill in NewLook mode. (Default: 2)
  • AREQ_BPenPattern (UWORD) — Background pen for the default pattern, or for a simple backfill in NewLook mode. (Default: 0)
  • AREQ_PubScreenName (STRPTR) — Name of the output public screen.
  • AREQ_NewLookBackFill (BOOL) — Removes the standard system requester crosshatch pattern, giving the request a new graphic look. (Default: FALSE)
  • AREQ_ReturnKey (BOOL) — If FALSE, disables RETURN key recognition. (Default: TRUE)
  • AREQ_FrameOnly (BOOL) — If TRUE, removes the title bar, drag bar, and gadgets from the request window. (Default: FALSE)
  • AREQ_WindowFlags (ULONG) — Additional window flags for personal use. USE WITH CAUTION. (Default: NULL)
  • AREQ_ButtomHook (struct Hook *) — Hook invoked when a request button is released. Called with object == (struct REI *) and message == (struct REIMessage *). The rim_REICode field contains the button number. If the Hook returns ~0, it causes immediate exit. (Default: NULL)

Result

  • areq — If NULL, an error occurred. Otherwise returns the address of the allocated AsmRequest structure.

See Also

AsmRequestArgs, ChangeAsmReqAttrsA, FreeAsmRequest

assembly/asmintuition.h

Implementation

The original 68020 assembly implementation:

; (13-May-1995) --- AllocAsmRequestA(taglist) (a0)
STDICM  EQU     IDCMP_REFRESHWINDOW|IDCMP_CLOSEWINDOW|BUTTONIDCMP|IDCMP_ACTIVEWINDOW|IDCMP_IDCMPUPDATE
SIDCMP  EQU     STDICM|IDCMP_VANILLAKEY|IDCMP_NEWSIZE|LISTVIEWIDCMP
 
STADFL  EQU     WFLG_CLOSEGADGET|WFLG_ACTIVATE|WFLG_RMBTRAP|WFLG_DRAGBAR|WFLG_DEPTHGADGET
SFLAGS  EQU     STADFL
 
REIFLAGS EQU    REIF_REQUEST|REIF_NOFONTSENSITIVE
 
AsmRequestTable
        dc.l    AR_EXT,ARQLeft,ARQTop,ARQREI,ARQWindow,ARQScreen,ARQTitle,ARQIDCMP
        dc.l    ARQIDCMPHook,ARQLockREI,ARQJust,ARQObject,ARQSound
        dc.l    AR_TAGG,AR_TAGG
        dc.l    ARQCenterH,ARQCenterV,ARQCenterM,ARQUnderObject
        dc.l    ARQAPenPattern,ARQBPenPattern,ARQPubScreenName,ARQNewLookBackFill
        dc.l    ARQReturnKey,ARQFrameOnly,ARQWindowFlags,ARQButtomHook
;--------------------------------------------------------------------------------------
_LVOAllocAsmRequestA
        movem.l d2-d3/a2-a6,-(sp)
        move.l  a6,a5                   * Save AssemblyBase...
        suba.l  a4,a4                   * AllocMem()...
        move.l  a0,a2                   * Save TagList...
        move.l  #4+areq_SIZEOF,d2       * memory for the AsmRequest structure
        move.l  d2,d0
        moveq   #1,d1
        swap    d1                      * MEMF_CLEAR
        move.l  ab_ExecBase(a5),a6
        jsr     _LVOAllocMem(a6)
        move.l  d0,a4                   * all ok??
        tst.l   d0
        bne.s   AR_Cont                 * Ok, continue...
AR_EXT  move.l  a4,d0
        movem.l (sp)+,d2-d3/a2-a6
        rts
;--------------------------------------------------------------------------------------
; Before jumping to the Tags, we perform standard initializations; if modified via Tags
; they will be changed, otherwise these defaults will remain if no Tags are provided...
;--------------------------------------------------------------------------------------
AR_Cont move.l  d2,(a4)+                * D2 = true SizeOF - AllocVec() ;)
        move.l  a5,a6
        bsr     _LVOAllocRastPort       * Allocate for calculations...
        move.l  d0,areq_SysRP(a4)       * System RastPort
        move.l  #SIDCMP,rei_NewWindow+nw_IDCMPFlags(a4) * Set IDCMP
        move.l  #SFLAGS,rei_NewWindow+nw_Flags(a4) * Set Flags
        moveq   #-1,d0
        move.l  d0,rei_NewWindow+nw_MaxHeight(a4)
        move.l  d0,rei_NewWindow+nw_MaxWidth(a4)
        move.l  #REIFLAGS,rei_Flags(a4) * Mode Requester... for REI
        lea     areq_Hook(a4),a0        * Default LayoutCallBack Hook
        lea     LayFill(pc),a1          * routine...
        movem.l a1/a4/a5,h_Entry(a0)    * Init...
        move.l  a0,rei_LayoutCallBack(a4) * Use Default standard Hook...
        move.l  #$00020000,areq_FgPatternPen(a4) * Default Pattern Color
        move.w  #ARQF_RETURNKEY,areq_Flags(a4) * Set ON Return Key... default
        lea     areq_STDWindowTAG(a4),a0
        move.l  #WA_InnerWidth,(a0)     * Build the Standard Window TAG
        move.l  #WA_InnerHeight,8(a0)
        move.l  #WA_AutoAdjust,16(a0)
        move.l  #1,20(a0)
        move.l  #TAG_MORE,24(a0)
        moveq   #0,d0                   * Clear these Tags for safety...
        move.l  d0,28(a0)
        move.l  d0,32(a0)
        move.l  a0,rei_STDWindowTAG(a4)
;--------------------------------------------------------------------------------------
        move.l  ab_IntuiBase(a5),a6     * Get by default, the address
        suba.l  a0,a0                   * of the public screen... passing
        jsr     _LVOLockPubScreen(a6)   * NAME = NULL.
        move.l  d0,rei_Screen(a4)       * Then get the RastPort of
        move.l  d0,a1                   * this screen, and save it...
        lea     sc_RastPort(a1),a0
        move.l  a0,areq_ScreenRP(a4)
        suba.l  a0,a0
        jsr     _LVOUnlockPubScreen(a6) * Unlock the screen...
;--------------------------------------------------------------------------------------
        move.l  a2,a0                   * Address of the TagList...
;--------------------------------------------------------------------------------------
AR_PTAG USETAGLIST.s AsmRequestTable(pc),AR_TAGG,AR_EXT2
AR_EXT2 move.l  a4,d0
        movem.l (sp)+,d2-d3/a2-a6
        rts
;--------------------------------------------------------------------------------------
ARQLeft move.l  (a0)+,d0
        move.w  d0,areq_LeftEdge(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQTop  move.l  (a0)+,d0
        move.w  d0,areq_TopEdge(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQREI  move.l  (a0)+,d0               * Get the REI structure
        beq     AR_TAGG
        move.l  (rei_Screen.w,d0.l),a2  * (struct Screen *)
        move.l  a2,rei_Screen(a4)       * Same screen, thanks...
        lea     sc_RastPort(a2),a2      * (struct RastPort *)
        move.l  a2,areq_ScreenRP(a4)    * Save it...
        tst.l   rei_NewWindow+nw_Title(a4)
        bne     AR_TAGG
        move.l  (rei_Window.w,d0.l),a2
        move.l  wd_Title(a2),d1         * Title of the reference Window...
        beq     AR_TAGG
        move.l  d1,rei_NewWindow+nw_Title(a4) * Set Req Title...
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQWindow
        move.l  (a0)+,d0               * Window/Screen output...
        beq     AR_TAGG                 * Ok, use the default pubscreen...
        move.l  (wd_WScreen.w,d0.l),a2  * Window's Screen...
        move.l  a2,rei_Screen(a4)       * In AsmRequest.. which starts with the REI
        lea     sc_RastPort(a2),a2      * Get the RastPort of the output screen
        move.l  a2,areq_ScreenRP(a4)    * of output
        bra     AR_TAGG                 * Start again...
;--------------------------------------------------------------------------------------
ARQScreen
        move.l  (a0)+,a2               * (struct Screen *)
        move.l  a2,rei_Screen(a4)       * Set ScreenPtr Output
        lea     sc_RastPort(a2),a2      * (struct RastPort *)
        move.l  a2,areq_ScreenRP(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQTitle
        move.l  (a0)+,d0               * Check for NULL Title...
        move.l  d0,a2
        bne.s   okSet
        lea     defStr(pc),a2           * Get the Default Title for safety
        move.l  rei_Window(a4),d0       * Is there a reference Window??
        beq.s   okSet                   * No, use the default...
        move.l  (wd_Title.w,d0.l),d1    * Title of the reference Window...
        beq.s   okSet
        move.l  d1,a2
okSet   move.l  a2,rei_NewWindow+nw_Title(a4) * Set Req Title...
        bra     AR_TAGG
defStr  STRING  <"System Request">
;--------------------------------------------------------------------------------------
ARQIDCMP
        move.l  #SIDCMP,rei_NewWindow+nw_IDCMPFlags(a4) * Set IDCMP
        move.l  (a0)+,d0
        or.l    d0,rei_NewWindow+nw_IDCMPFlags(a4) * Add IDCMPFlags...
        move.l  d0,areq_IDCMPFlags(a4)  * Save them for checking...
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQIDCMPHook
        move.l  (a0)+,areq_IDCMPHook(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQLockREI
        move.l  (a0)+,areq_LockREI(a4)  * REI to lock...
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQJust move.l  (a0)+,d0
        move.w  d0,areq_TextFlags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQObject                               * Insert the Object into our
        move.l  (a0)+,d0
        move.l  d0,areq_Object(a4)      * set it anyway
        beq     AR_TAGG                 * If NULL exit...
        move.l  a0,d2
        move.l  d0,a0                   * Object *
        move.l  sp,d3                   * save the stack
        subq.w  #8,sp
        move.l  sp,a3                   * request information about the
        pea     TAG_DONE                * dimensions of this object
        move.l  a3,-(sp)               * and store them in a ULONG
        pea     DTA_NominalVert         * for later use...
        addq.w  #4,a3
        move.l  a3,-(sp)
        pea     DTA_NominalHoriz
        move.l  sp,a2                   * Attrs
        move.l  ab_DataTypesBase(a5),a6
        jsr     _LVOGetDTAttrsA(a6)     * get info...
        move.l  (a3),areq_ObjectWidth(a4) * save dimensions in the AsmRequest
        subq.w  #4,a3
        move.l  (a3),areq_ObjectHeight(a4)
        move.l  d3,sp                   * Restore StackPointer....
        move.l  d2,a0
        bra     AR_PTAG
;--------------------------------------------------------------------------------------
ARQSound
        move.l  (a0)+,areq_Sound(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQCenterH
        move.l  (a0)+,d0
        bne.s   ACHFSET
        BCLRL   REIB_CENTERHSCREEN,rei_Flags(a4)
        bra     AR_TAGG
ACHFSET BSETL   REIB_CENTERHSCREEN,rei_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQCenterV
        move.l  (a0)+,d0
        bne.s   ACVFSET
        BCLRL   REIB_CENTERVSCREEN,rei_Flags(a4)
        bra     AR_TAGG
ACVFSET BSETL   REIB_CENTERVSCREEN,rei_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQCenterM
        move.l  (a0)+,d0
        bne.s   ACMFSET
        BCLRL   REIB_CENTERMOUSE,rei_Flags(a4)
        bra     AR_TAGG
ACMFSET BSETL   REIB_CENTERMOUSE,rei_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQUnderObject
        BCLRW   ARQB_TEXTUNDEROBJECT,areq_Flags(a4)
        move.l  (a0)+,d0
        beq     AR_TAGG
        BSETW   ARQB_TEXTUNDEROBJECT,areq_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQAPenPattern
        move.l  (a0)+,d0
        move.w  d0,areq_FgPatternPen(a4) * Default Pattern Color
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQBPenPattern
        move.l  (a0)+,d0
        move.w  d0,areq_BgPatternPen(a4) * Default Pattern Color
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQPubScreenName
        move.l  (a0)+,d2               * public screen name
        exg.l   a0,d2
        move.l  ab_IntuiBase(a5),a6
        jsr     _LVOLockPubScreen(a6)
        move.l  d0,rei_Screen(a4)       * Then get the RastPort of
        move.l  d0,a1
        lea     sc_RastPort(a1),a0
        move.l  a0,areq_ScreenRP(a4)
        suba.l  a0,a0
        jsr     _LVOUnlockPubScreen(a6) * Unlock the screen...
        move.l  d2,a0
        bra     AR_PTAG
;--------------------------------------------------------------------------------------
ARQNewLookBackFill
        lea     LayFill(pc),a2
        move.l  (a0)+,d0
        beq.s   StaDefH
        lea     NewLookLayFill(pc),a2
StaDefH lea     areq_Hook(a4),a1
        move.l  a2,h_Entry(a1)
        bra     AR_PTAG
;--------------------------------------------------------------------------------------
ARQReturnKey
        BCLRW   ARQB_RETURNKEY,areq_Flags(a4)
        move.l  (a0)+,d0
        beq     AR_TAGG
        BSETW   ARQB_RETURNKEY,areq_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
FONLY   SET     WFLG_CLOSEGADGET|WFLG_DRAGBAR|WFLG_DEPTHGADGET
ARQFrameOnly
        move.l  (a0)+,d0
        beq.s   FONLOFF
        andi.l  #~FONLY,rei_NewWindow+nw_Flags(a4)
        move.l  #0,rei_NewWindow+nw_Title(a4)
        bra     AR_TAGG
FONLOFF ori.l   #FONLY,rei_NewWindow+nw_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQWindowFlags
        move.l  (a0)+,d0
        or.l    d0,rei_NewWindow+nw_Flags(a4)
        bra     AR_TAGG
;--------------------------------------------------------------------------------------
ARQButtomHook
        move.l  (a0)+,areq_ButtomHook(a4)
        bra     AR_TAGG
Last updated on
OverviewFreeAsmRequest

The Amiga Assembly Library is a shared library for Commodore Amiga written in Motorola 68020 assembly language. Version 41.21, Public Domain Software. Compatible with KickStart 3.0+.

DOCUMENTATION
Getting Started
Exec Module
DOS Module
Graphics Module
C Interface
RESOURCES
AmigaOS Wiki
English Amiga Board
68000 Editor
Aminet
MODULES
Exec (Memory)
DOS (Files)
Graphics
Libraries (Strings)
Math (Conversions)
Intuition & GadTools
REI Interface
Examples

Amiga Assembly Library v41.21 — Public Domain Software

Made with care by Undolog

Hosted on Vercel

Built with Mantine + Nextra

Source on GitHub