Programming AmigaOS in C

5. Opening a Screen

AmigaOS supports a concept called screens, which is a display setup of a specific resolution and color depth, limited by the Monitor drivers and the CRT or LCD used used. On the classic Amigas, they can use low or medium resolutions with colour depths from 4 to 256 colours. Amigas with graphic cards can support higher resolutions with 65K or 16M or more colours and use the Picasso96 or CyberGraphics libraries to support these cards. Screens are part of the intuition library.

If you do not wish to open a screen then an application can be opened on the current default Workbench screen. This is known as a public screen which means that multiple applications can run on the same screen rather than different screens.

A screen is useful, if you wish to use a specific resolution and colour depth for your application, games will commonly use their own screens to suit itself.

There are a number of functions available to open a screen:

OpenScreen() - Open a screen using the NewScreen structure
OpenScreenTagList() -
Open a screen using Tag items
LockPubScreen() -
Open and lock the public screen
CloseScreen() - Close a screen

6. Open a Screen using OpenScreen()

This method requires you to define a NewScreen structure and then use the OpenScreen function. This is available in all versions of AmigaOS. The NewScreen structure is defined in the header intuition/screens.h file.

The structure looks like this:

struct NewScreen
   {
   WORD LeftEdge, TopEdge, Width, Height, Depth; /* screen dimensions */
   UBYTE DetailPen, BlockPen;                    /* for bar/border/gadget rendering */
   UWORD ViewModes;                              /* the Modes for the ViewPort (and View) */
   UWORD Type;                                   /* the Screen type (see defines above) */
   struct TextAttr *Font;                        /* this Screen's default text attributes */
   UBYTE *DefaultTitle;                          /* the default title for this Screen */
   struct Gadget *Gadgets;                       /* UNUSED: Leave this NULL */
   struct BitMap *CustomBitMap;
   };

Format of the command is:

struct Screen* = OpenScreen(struct NewScreen *)

or, in AmigaOS 4:

struct Screen* = IIntuition->OpenScreen(struct NewScreen *)

Some parameters just require values and others require a pointer to another structure otherwise use NULL if you are not going to use it. If you are using other structures, then they must be defined before the NewScreen structure, so it can reference it.

#include <proto/intuition.h>
#include <proto/dos.h>
#include <intuition/screens.h>
int main(void) {
    struct NewScreen Screen1 = {
     0,0,640,480,8,             /* Screen of 640 x 480 of depth 8 (2^8 = 256 colours)    */
     DETAILPEN, BLOCKPEN,
     HIRES,                     /* see graphics/view.h for view modes */
     PUBLICSCREEN,              /* Screen types */
     NULL,                      /* Text attributes (use defaults) */
     "My New Screen", 
     NULL,
     NULL
     };
     struct Screen *myScreen;
     myScreen = OpenScreen(&Screen1);  /* & (ampersand) means address of */
     Delay(500);
     if (myScreen) CloseScreen(&Screen1);
	  return(0);
   } 

Code for AmigaOS 4:

#include <proto/intuition.h>
#include <proto/dos.h>
#include <intuition/screens.h>
int main(void) {
    struct NewScreen Screen1 = {
     0,0,640,480,8,             /* Screen of 640 x 480 of depth 8 (2^8 = 256 colours)    */
     DETAILPEN, BLOCKPEN,
     HIRES,                     /* see graphics/view.h for view modes */
     PUBLICSCREEN,              /* Screen types */
     NULL,                      /* Text attributes (use defaults) */
     "My New Screen", 
     NULL,
     NULL
     };
     struct Screen *myScreen;
     myScreen = IIntuition->OpenScreen(&Screen1);  /* & (ampersand) means address of */
     IDOS->Delay(500);
     if (myScreen) IIntuition->CloseScreen(&Screen1);
	  return(0);
   } 

 

7. Opening a Screen using OpenScreenTags() and OpenScreenTagList()


This method allows you to specify the parameters of the Screen in the command itself without having to define a NewScreen structure. This is available from AmigaOS 2 or later. A Tag list is a list of parameter names followed by a value. For example to specify the DefaultTitle of a screen you use the SA_Title followed by the title in quotes. The tags are defined in Intuition/Screens.h header file, under 'Screen attribute tag ID's'.
e.g.
SA_Left = Left position of screen
SA_Top = Top poisition of screen
SA_Width = Width of screen
SA_Height = Height of screen
SA_Depth = Colour depth of screen ( 2^n = Num. of colours)
SA_DetailPen = Detail Pen
SA_BlockPen = Block Pen
SA_Title = Screen title name
SA_Type = Screen type

Screen types:
CUSTOMSCREEN = Custom screen for this application
PUBLICSCREEN = A sharable public screen
WBENCHSCREEN = Workbench screen
SHOWTITLE = Display screen title
BEEPING = Set when screen is beeping
CUSTOMBITMAP = Screen with a custom bitmap
SCREENBEHIND = Screen is displayed behind current screen
SCREENQUIET = Use if you do not want intuition to render onto this screen
SCREENHIRES = Do not use low red gadgets on this screen
NS_EXTENDED = New extended screen type with more attributes
AUTOSCROLL = Screen with autoscroll feature

and there are many other tags that can be used to define a screen.The last tag item should always be TAG_DONE. The format of the command is:

struct Screen* = OpenScreenTags(struct NewScreen *,Tag Tag1Type ...) 
struct Screen* = OpenScreenTagList(struct NewScreen *,struct TagItem TagList) 

or, in AmigaOS 4:

struct Screen* = IIntuition->OpenScreenTags(struct NewScreen *,Tag Tag1Type ...) 

struct Screen* = IIntuition->OpenScreenTagList(struct NewScreen *, struct TagItem TagList) 

So, to re-write the above code using the OpenScreenTags() command you can say:

#include <proto/intuition.h>
#include <proto/dos.h>
#include <intuition/screens.h>
   
int main() {
     struct Screen *myScreen;
     myScreen = OpenScreenTags(NULL, 
     SA_Left, 0, SA_Top, 0, SA_Width, 640, SA_Height, 480,
     SA_Depth, 8, SA_Title, "My New Screen",
     SA_Type, PUBLICSCREEN,
     SA_SysFont, 1,
     TAG_DONE);
   
     Delay(500);
     if (myScreen) CloseScreen(&myScreen);

     return (0);
}

And here is the same code for the OpenScreenTagList() command, which uses an array of TagItems, a Tag name and Tag value, which has the advantage of being to re-use the array for further screens if needed:

#include <proto/intuition.h>
#include <proto/dos.h>
#include <intuition/screens.h>
   
int main() {
     struct Screen *myScreen;

	  struct TagItem screentags[9] = {      
      SA_Left, 0, SA_Top, 0, SA_Width, 640, SA_Height, 480,
      SA_Depth, 8, SA_Title, "My New Screen",
      SA_Type, PUBLICSCREEN,
      SA_SysFont, 1,
      TAG_DONE, NULL
	  };

	  myScreen = OpenScreenTagList(NULL, &screentags[0]);
   
     Delay(500);
     if (myScreen) CloseScreen(&myScreen);

     return (0);
}


8. Closing a Screen

Use the CloseScreen() command to close a screen. The format of the command is:

CloseScreen(struct Screen *)

or, in AmigaOS 4:

IIntuition->CloseScreen(struct Screen *)

You should test if the screen is valid before closing it.

9. Opening or Locking a Public Screen

If you do not wish to use a custom screen, then you can use an existing public screen such as Workbench. Screens can be closed, so to prevent that, the public screen should be locked while the
application is running. You can do this using the LockPubScreen function. Format of the command is:

struct Screen * = LockPubScreen(UBYTE *name)

or, in AmigaOS 4:

struct Screen * = IIntuition->LockPubScreen(UBYTE *name)

where name is the name of the Public Screen to lock.If no name is given then it will use the Workbench public screen. Once done with the Public screen you can then Unlock it:

UnlockPubScreen(UBYTE *name, struct Screen *screen )

or, in AmigaOS 4:

IIntuition->UnlockPubScreen(UBYTE *name, struct Screen *screen )

For example, the following code will lock and unlock the default Workbench screen.

#include <proto/intuition.h>
#include <intuition/screens.h>
#include <proto/dos.h>
#include <stdio.h>
int main(void) {
   
   struct Screen *myScreen;
   if (myScreen = LockPubScreen(NULL)) {
        printf("Public Screen locked.\n");
        Delay(100);
        UnlockPubScreen(NULL, myScreen);
        printf("Public Screen unlocked.\n");
   }
   return 0;
   }

10. Using Screens

There are some additional functions you can use to manipulate screens. The following functions are examples of these functions:

void DisplayBeep(struct Screen *)
This function will flash the specified screen, for example, to indicate an error.
e.g.
DisplayBeep(myScreen);

void MoveScreen(struct Screen *, WORD dx, WORD dy)
This function will move the current screen to the specified pixel co-ordinates. This is similar to dragging the screen bar to a new location.
e.g.
MoveScreen(myScreen, 0, 100); /* Move screen down to y co-ord 100 */

void ScreenToBack(struct Screen *)
void ScreenToFront(struct Screen *)
If you have multiple screens open, then you can switch between screens using these functions. ScreenToFront will make a screen the visible screen.
e.g.
ScreenToFront(myScreen);

void MakeScreen(struct Screen *)
This function will rebuild a Copper (Co-processor) which is used to display special graphics effects such as rainbows.
e.g.
MakeScreen(myScreen);

void ShowTitle(struct Screen *, BOOL)
Specifies whether to show the screen's title bar or not.
e.g.
ShowTitle(myScreen, FALSE);

See Intuition Reference documentation for further commands.

Next Page