Copyright (c) 2012-2016 Hyperion Entertainment and contributors.

ASL Screen Mode Requester

From AmigaOS Documentation Wiki
Jump to: navigation, search

The Screeen Mode requester provides application writers with a convenient way to ask the user for their screen display preferences. You create an ASL screen mode requester the same way you create an ASL file requester or font requester; only the tags and structures used are different.

 struct ScreenModeRequester {
     ULONG sm_DisplayID;            /* Display mode ID                  */
     ULONG sm_DisplayWidth;         /* Width of display in pixels       */
     ULONG sm_DisplayHeight;        /* Height of display in pixels      */
     UWORD sm_DisplayDepth;         /* Number of bit-planes of display  */
     UWORD sm_OverscanType;         /* Type of overscan of display      */
     BOOL  sm_AutoScroll;           /* Display should auto-scroll?      */
     ULONG sm_BitMapWidth;          /* Used to create your own BitMap   */
     ULONG sm_BitMapHeight;
     WORD  sm_LeftEdge;             /* Coordinates of requester on exit */
     WORD  sm_TopEdge;
     WORD  sm_Width;
     WORD  sm_Height;
     BOOL  sm_InfoOpened;           /* Info window opened on exit?      */
     WORD  sm_InfoLeftEdge;         /* Last coordinates of Info window  */
     WORD  sm_InfoTopEdge;
     WORD  sm_InfoWidth;
     WORD  sm_InfoHeight;
     APTR  sm_UserData;             /* You can store your own data here */
 };

The fields in this structure will be filled in with information obtained from the user. This information can then be used in your application to create the type of screen that the user prefers.

Note that for most programs, the user's preferred screen mode can be determined from the Amiga's Preferences subsystem. You do not have to use a screen mode requester. Consider carefully whether it is more appropriate to use an ASL requester or to obtain the information directly from the settings in Overscan and ScreenMode Preferences.

Specifying Screen Mode Requester Options With TagItems

Here's a brief summary of the tag items that apply only to the ASL screen mode requester. For a complete listing of all ASL tag items, refer to the ASL include files and Autodocs.

Screen Mode Requester Tag Name Used For
ASLSM_Window Parent window
ASLSM_Screen Screen to open on if no window
ASLSM_PubScreenName Name of public screen
ASLSM_PrivateIDCMP Allocate private IDCMP?
ASLSM_IntuiMsgFunc Function to handle IntuiMessages
ASLSM_SleepWindow Block input in ASLSM_Window?
ASLSM_UserData What to put in sm_UserData
ASLSM_TextAttr Text font to use for gadget text
ASLSM_Locale Locale ASL should use for text
ASLSM_TitleText Title of requester
ASLSM_PositiveText Positive gadget text
ASLSM_NegativeText Negative gadget text
ASLSM_InitialLeftEdge Initial requester left coordinate
ASLSM_InitialTopEdge Initial requester top coordinate
ASLSM_InitialWidth Initial requester width
ASLSM_InitialHeight Initial requester height
ASLSM_InitialDisplayID Initial display mode id
ASLSM_InitialDisplayWidth Initial display width
ASLSM_InitialDisplayHeight Initial display height
ASLSM_InitialDisplayDepth Initial display depth
ASLSM_InitialOverscanType Initial type of overscan
ASLSM_InitialAutoScroll Initial autoscroll setting
ASLSM_InitialInfoOpened Info window initially opened?
ASLSM_InitialInfoLeftEdge Initial Info window left coordinate
ASLSM_InitialInfoTopEdge Initial Info window top coordinate
ASLSM_DoWidth Display Width gadget?
ASLSM_DoHeight Display Height gadget?
ASLSM_DoDepth Display Depth gadget?
ASLSM_DoOverscanType Display Overscan Type gadget?
ASLSM_DoAutoScroll Display AutoScroll gadget?
ASLSM_PropertyFlags Must have these Property flags
ASLSM_PropertyMask Only these should be looked at
ASLSM_MinWidth Minimum display width to allow
ASLSM_MaxWidth Maximum display width to allow
ASLSM_MinHeight Minimum display height to allow
ASLSM_MaxHeight Maximum display height to allow
ASLSM_MinDepth Minimum display depth
ASLSM_MaxDepth Maximum display depth
ASLSM_FilterFunc Function to filter mode id's
ASLSM_CustomSMList Exec list of struct DisplayMode

Example Screen Mode Requester

Listed below is a simple program that displays the new ASL screen mode requester including depth, width and height gadgets.

/*
** aslsm.c
*/
 
#include <libraries/asl.h>
#include <utility/tagitem.h>
 
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/asl.h>
 
#define SMRTITLE "Simplest ScreenMode Requester"
 
struct AslIFace *IAsl;
 
int main(int argc, char **argv)
{
 
struct ScreenModeRequester *smr;
struct TagItem smrtags[5];
 
struct Library *AslBase = IExec->OpenLibrary("asl.library", 50);
IAsl = (struct AslIFace*)IExec->GetInterface(AslBase, "main", 1, NULL);
 
if( IAsl != NULL)
    {
    smrtags[0].ti_Tag=ASLSM_TitleText;
    smrtags[0].ti_Data=(ULONG)SMRTITLE;
 
    smrtags[1].ti_Tag=ASLSM_DoWidth;
    smrtags[1].ti_Data=TRUE;
 
    smrtags[2].ti_Tag=ASLSM_DoHeight;
    smrtags[2].ti_Data=TRUE;
 
    smrtags[3].ti_Tag=ASLSM_DoDepth;
    smrtags[3].ti_Data=TRUE;
 
    smrtags[4].ti_Tag=TAG_END;
 
    if( smr = (struct ScreenModeRequester *)
          IAsl->AllocAslRequest(ASL_ScreenModeRequest, smrtags) )
        {
        if( IAsl->AslRequest(smr, 0L) )
            {
            IDOS->Printf("Display type: $%lx (see graphics/displayinfo.h)\n",
                    smr->sm_DisplayID);
            IDOS->Printf("Display width: %ld, height: %ld, depth: %ld\n",
                   smr->sm_DisplayWidth, smr->sm_DisplayHeight,
                   smr->sm_DisplayDepth);
            }              
        else
            IDOS->Printf("User cancelled or error...\n");  
 
        IAsl->FreeAslRequest(smr);
        }
    }
 
    IExec->DropInterface((struct Interface*)IAsl);
    IExec->CloseLibrary(AslBase);
 
    return 0;
}

As with other ASL requesters, the attributes of the screen mode requester are established using tag items when AllocAslRequest() is called. These attributes can later be changed by using different tag items in the AslRequest() call.

For instance, in the example above, tag items are used to specify that the screen mode requester should include gadgets for setting the display height (ASLSM_DoHeight), width (ASLSM_DoWidth) and depth (ASLSM_DoDepth).