ASL Screen Mode Requester

Creating a Screen Mode Requester

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.

There are three main functions to call:

AllocAslRequest()	Sets up the ScreenModeRequester structure you need.
AslRequest()	Displays the requester you have set up with AllocAslRequest().
FreeAslRequest()	Frees the ScreenModeRequester structure and other resources.

The first step is to set up a ScreenModeRequester structure with the AllocAslRequest() function. The ScreenModeRequester structure is defined in <libraries/asl.h> as follows:

 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.

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

/*
** aslsm.c
*/
 
#include <exec/types.h>
#include <libraries/asl.h>
#include <utility/tagitem.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).

Screen Mode Requester Tags

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 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