Custom Screen Type

Custom Screen Functions

All applications require a screen to work in. This can be an existing, public screen or a new, custom screen created by the application itself. To create a new, custom screen to work with, you call OpenScreenTags().

Custom Screen Functions

OpenScreenTags()	Create a new, custom screen from a tag list. Use either one of these to open any screen.
OpenScreenTagList()
CloseScreen()	Close a custom screen and free the memory it used.

Creating a new Custom Screen

There are two functions you can use to open a custom screen: OpenScreenTags() or OpenScreenTagList().

struct Screen *OpenScreenTagList( struct NewScreen * , struct TagItem *);
struct Screen *OpenScreenTags( struct NewScreen *, ULONG, ULONG, ... );

The "Screen Attributes" section below contains a complete list of all the tag options available for setting up an Intuition screen. For a general description of tag items, see Utility Library.

A Custom Screen Example

There are so many tag options available with screens it can be a bit overwhelming. Before discussing more details, it may be helpful to look at a simple example. The code below opens a new, custom screen using the OpenScreenTags() call. The example uses just two tag items (SA_Depth and SA_Pens) which provide the minimum attributes needed to make a screen that uses the 3D look of Intuition. (See the section on "DrawInfo and the 3D Look" below for more information.)

/* newlookscreen.c
** open a screen with the "new look".
*/

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/screens.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

/* Simple routine to demonstrate opening a screen with the new look.
** Simply supply the tag SA_Pens along with a minimal pen specification,
** Intuition will fill in all unspecified values with defaults.
** Since we are not supplying values, all are Intuition defaults.
*/
int main(int argc, char **argv)
{
    uint16 pens[] = { ~0 };

    struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
    struct IntuitionIFace *IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
    if (IIntuition != NULL)
    {
        /* The screen is opened two bitplanes deep so that the
        ** new look will show-up better.
        */
        struct Screen *my_screen = IIntuition->OpenScreenTags(NULL,
            SA_Pens, pens,
            SA_Depth, 2,
            TAG_END);
        if (my_screen != NULL)
        { 
            /* screen successfully opened */
            IDOS->Delay(30);  /* normally the program would be here */

            IIntuition->CloseScreen(my_screen);
        }

        IExec->DropInterface((struct Interface*)IIntuition);
        IExec->CloseLibrary(IntuitionBase);
        return 0;
    }
}

Return Values from OpenScreenTagList()

OpenScreenTagList() and its variants return a pointer to a Screen structure on the successful creation of a new screen and NULL on failure. The call also supports extended error codes on failure. The error returns provide information on the type of failure, giving the application a greater chance of recovery. To get the extended error code, you need to use the SA_ErrorCode tag; the code itself will be placed into the LONG pointed to by the Item.ti_Data field. Here are the codes:

OSERR_NOMONITOR

The monitor needed to display the requested mode is not available. An example of this error would be opening a Productivity mode screen on a system without a VGA or multisync monitor.

OSERR_NOCHIPS

Newer custom chips are required for this screen mode. For instance, the ECS Denise is required for the productivity modes.

OSERR_NOMEM

Could not allocate enough memory.

OSERR_NOCHIPMEM

Could not allocate enough Chip memory.

OSERR_PUBNOTUNIQUE

Could not create public screen'name already used. The system requires that public screen names be unique.

OSERR_UNKNOWNMODE

Display mode requested was not recognized. The system does not understand the value specified with the SA_DisplayID tag.

Closing the Screen

When an application has finished using a screen, the memory that the screen occupied should be returned to the system by calling CloseScreen(). Normally, an application should close only those screens that it created. CloseScreen() returns a boolean value, TRUE for success and FALSE for failure. CloseScreen() can fail if the screen is public and another task is still using the screen.